refactor(docs): co-locate k8s/proxmox docs with their code + fix broken perf paths

Docs moved from docs/k8s -> k8s/docs and docs/proxmox -> proxmox/docs to sit
beside their code. Updated all cross-references (docmap, STATUS, README, AGENTS,
k8s README). Fixed SCRIPT_DIR path resolution in 3 perf scripts broken by the
reorg (deploy-check/and-fix/finish-host pointed at root/scripts instead of
perf/scripts). Registered the new top-level proxmox/ dir in all listings.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2

AGENTS.md

@@ -11,13 +11,14 @@ lives in subdirectories.
 provisioning/        Server provisioning (SetupNewSystem.sh, security, 2FA)
 tests/               Test suite + VM validation harness
 dns-cluster-setup/   Technitium DNS cluster replication
-k8s/                 k3s cluster setup scripts (3-node HA over Tailscale)
+k8s/                 k3s cluster setup scripts (3-node HA over Tailscale) + docs/
 powerman/            Cyclades PM10i PDU management via powerman
 console/             Serial console management (ser2net + conman) for switches
 perf/                Proxmox perf tuning, fleet audit, iperf
+proxmox/             Proxmox fleet docs (hardware audit, capacity, k8s host planning)
 netinfra/            pfv-netinfra-01/02 DNS/NTP setup
 switches/            Switch configuration captures
-docs/                All documentation (see docs/docmap.md)
+docs/                Server-build docs, docmap index, and archive
 vendor/              Vendored KNELShellFramework
 ```
 
@@ -94,4 +95,4 @@ vendor/              Vendored KNELShellFramework
 Solo-founder R&D Proxmox cluster in a private residence. Shoestring budget.
 Production lives on a Cloudron VPS in Reston VA. See
 [`STATUS.md`](STATUS.md) for current state and
-[`docs/proxmox/PROJECT.md`](docs/proxmox/PROJECT.md) for the fleet report.
+[`proxmox/docs/PROJECT.md`](proxmox/docs/PROJECT.md) for the fleet report.

README.md

@@ -11,13 +11,14 @@ Unified infrastructure repo for the Known Element Enterprises Proxmox R&D cluste
 | [`provisioning/`](provisioning/) | Server provisioning (SetupNewSystem.sh, security hardening, 2FA, NTP/DNS config, SNMP, Dell OMSA) |
 | [`tests/`](tests/) | Test suite + VM validation harness |
 | [`dns-cluster-setup/`](dns-cluster-setup/) | Technitium DNS cluster replication scripts |
-| [`k8s/`](k8s/) | k3s cluster setup scripts (3-node HA control plane over Tailscale) |
+| [`k8s/`](k8s/) | k3s cluster setup scripts (3-node HA control plane over Tailscale) + co-located docs |
 | [`powerman/`](powerman/) | Cyclades PM10i PDU management via powerman on pfv-tsys1 |
 | [`console/`](console/) | Serial console management (ser2net + conman) for network switches on pfv-tsys4 |
 | [`perf/`](perf/) | Proxmox performance tuning, fleet audit, iperf, switch diagnostics |
+| [`proxmox/`](proxmox/) | Proxmox fleet docs: hardware audit, capacity analysis, k8s host planning |
 | [`netinfra/`](netinfra/) | pfv-netinfra-01/02 DNS/NTP setup + audit scripts |
 | [`switches/`](switches/) | Switch configuration captures |
-| [`docs/`](docs/) | All documentation ([see docmap](docs/docmap.md)) |
+| [`docs/`](docs/) | Server-build docs, documentation index ([docmap](docs/docmap.md)), and archive |
 | [`vendor/`](vendor/) | Vendored KNELShellFramework |
 
 ## Quick Start

STATUS.md

@@ -45,7 +45,7 @@ infrastructure, Proxmox cluster ops, and k8s control plane.
 - [x] Kubeconfig saved to `~/.kube/config.pfv-k8s` (gitignored, embedded certs)
 - [ ] Workers (wnodes) not yet joined to this cluster
 - [ ] Distro decision: **k3s chosen for regular R&D cluster**. Talos docs
-  preserved in `docs/k8s/` for future ITAR/classified cluster.
+  preserved in `k8s/docs/` for future ITAR/classified cluster.
 
 ### PDU Management (powerman on pfv-tsys1 — LIVE)
 - [x] Cyclades AlterPath PM10i (10 outlets) managed via powerman over serial
@@ -90,13 +90,13 @@ infrastructure, Proxmox cluster ops, and k8s control plane.
    - wnode-tsys7 (701): D5 → S1 (tsys4 → tsys5)
    - Gives every wnode its own physical disk, balances 3/3 across servers
 2. **Friday maintenance:** physical hardware + VM migrations (see
-   [`docs/proxmox/AUDIT-2026-07-28.md`](docs/proxmox/AUDIT-2026-07-28.md) §5)
+   [`proxmox/docs/AUDIT-2026-07-28.md`](proxmox/docs/AUDIT-2026-07-28.md) §5)
 3. **k8s workers:** Join wnodes to the k3s cluster (after rebalancing)
 4. **PDU:** Rename outlets in powerman.conf to match physical devices (Friday)
 5. **k8s deferred topics:** ETL tooling, HPC scheduler, vcluster policy,
    solar-aware scale-out
 
-> **See [`docs/proxmox/AUDIT-2026-07-28.md`](docs/proxmox/AUDIT-2026-07-28.md)
+> **See [`proxmox/docs/AUDIT-2026-07-28.md`](proxmox/docs/AUDIT-2026-07-28.md)
 > for the full fresh audit with VM inventory, capacity analysis, and
 > Friday migration plan.**
 

docs/docmap.md

@@ -12,9 +12,9 @@ procedures for the pfv-k8s cluster (Talos + vcluster + Keycloak OIDC).
 
 | Document | Description | Last Reviewed |
 |----------|-------------|---------------|
-| [`k8s/README.md`](k8s/README.md) | Index + TL;DR of all k8s decisions | 2026-07-28 |
+| [`k8s/docs/README.md`](k8s/docs/README.md) | Index + TL;DR of all k8s decisions | 2026-07-28 |
-| [`k8s/DISTRO-DECISION.md`](k8s/DISTRO-DECISION.md) | Talos vs k3s analysis. Recommendation: Talos, driven by ITAR/classified requirement | 2026-07-28 |
+| [`k8s/docs/DISTRO-DECISION.md`](k8s/docs/DISTRO-DECISION.md) | Talos vs k3s analysis. Decision: k3s for regular R&D cluster; Talos preserved for future ITAR/classified | 2026-07-28 |
-| [`k8s/ARCHITECTURE.md`](k8s/ARCHITECTURE.md) | Target architecture: control plane, network, identity, storage, tenant isolation, bootstrap, DR. Mermaid diagrams | 2026-07-28 |
+| [`k8s/docs/ARCHITECTURE.md`](k8s/docs/ARCHITECTURE.md) | Target architecture: control plane, network, identity, storage, tenant isolation, bootstrap, DR. Mermaid diagrams | 2026-07-28 |
 
 ## Proxmox Cluster ([`proxmox/`](proxmox/))
 
@@ -22,10 +22,10 @@ Fleet operations, hardware, performance tuning, storage architecture.
 
 | Document | Description | Last Reviewed |
 |----------|-------------|---------------|
-| [`proxmox/PROJECT.md`](proxmox/PROJECT.md) | Comprehensive fleet report: 7 hosts, VM inventory, storage, recommendations | 2026-07-27 |
+| [`proxmox/docs/PROJECT.md`](proxmox/docs/PROJECT.md) | Comprehensive fleet report: 7 hosts, VM inventory, storage, recommendations | 2026-07-27 |
-| [`proxmox/AUDIT-2026-07-28.md`](proxmox/AUDIT-2026-07-28.md) | Fresh fleet audit with current VM placements, storage redundancy analysis, pre-k8s action items | 2026-07-28 |
+| [`proxmox/docs/AUDIT-2026-07-28.md`](proxmox/docs/AUDIT-2026-07-28.md) | Fresh fleet audit with current VM placements, storage redundancy analysis, pre-k8s action items | 2026-07-28 |
-| [`proxmox/TODO.md`](proxmox/TODO.md) | Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 |
+| [`proxmox/docs/TODO.md`](proxmox/docs/TODO.md) | Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 |
-| [`proxmox/K8S.md`](proxmox/K8S.md) | Kubernetes storage/host analysis (predecessor to [`k8s/`](k8s/)) | 2026-07-27 |
+| [`proxmox/docs/K8S.md`](proxmox/docs/K8S.md) | Kubernetes storage/host analysis (predecessor to [`k8s/`](k8s/)) | 2026-07-27 |
 
 ## Server Build ([`server-build/`](server-build/))
 

k8s/README.md

@@ -42,7 +42,7 @@ kubectl get nodes
 ## Design Decisions
 
 - **k3s (not Talos):** This is a regular R&D cluster, not ITAR/classified.
-  Talos architecture is documented in [`docs/k8s/`](../docs/k8s/) for when
+  Talos architecture is documented in [`docs/`](docs/) for when
   that requirement comes online. k3s on stock Debian is simpler to operate.
 - **Tailscale-only transport:** `--node-ip`, `--advertise-address`, and
   `--tls-san` are all set to Tailscale IPs. No LAN IP appears in any node

perf/deploy-and-fix.sh

@@ -3,7 +3,7 @@
 set -uo pipefail
 HOST="$1"
 SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=8 -o ServerAliveInterval=10 -o StrictHostKeyChecking=accept-new)
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts"
 
 echo "=== Uploading fix script to $HOST ==="
 scp "${SSH_OPTS[@]}" "$SCRIPT_DIR/fix-bond-nfs.sh" "root@$HOST:/root/fix-bond-nfs.sh" >/dev/null 2>&1

perf/deploy-check.sh

@@ -18,9 +18,10 @@
 ###############################################################################
 set -uo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CHECK_SH="$SCRIPT_DIR/scripts/check.sh"
+ROOT_DIR="$(cd "$SELF_DIR/.." && pwd)"
-LOG_DIR="$SCRIPT_DIR/returned-logs"
+CHECK_SH="$SELF_DIR/scripts/check.sh"
+LOG_DIR="$ROOT_DIR/returned-logs"
 mkdir -p "$LOG_DIR"
 
 # ONLY the hosts the user told us are alive.
@@ -43,7 +44,7 @@ fi
 # Sanity-check shellcheck clean before shipping (best-effort, non-blocking)
 if command -v docker >/dev/null 2>&1; then
     log "pre-flight: shellcheck on check.sh"
-    if ! docker run --rm -v "$SCRIPT_DIR:/mnt" -w /mnt \
+    if ! docker run --rm -v "$SELF_DIR:/mnt" -w /mnt \
          koalaman/shellcheck:stable --severity=style --format=gcc scripts/check.sh \
          >"$LOG_DIR/_shellcheck.preflight.txt" 2>&1; then
         log "WARNING: shellcheck reported issues — see _shellcheck.preflight.txt"

perf/finish-host.sh

@@ -22,7 +22,7 @@ if [ -z "$HOST" ]; then
 fi
 
 SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=8 -o ServerAliveInterval=10 -o StrictHostKeyChecking=accept-new)
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/scripts"
 
 echo "==================================================================="
 echo " finish-host.sh — $HOST  (mode: $MODE)"