PFVCluster/AGENTS.md

Agent Guidelines

Top-level files: README.md (project overview), STATUS.md (living status, agent-maintained), docs/docmap.md (documentation index). Everything else lives in subdirectories.

Repository Layout

dcinfra/            Data-center infra: PDU (powerman), serial console (console), UPS (ups)
netinfra/           DNS/NTP/DHCP setup + audit; DNS cluster replication (dns-cluster-setup);
                    switch captures (switches); DHCP config (dhcp)
k8s/                k3s cluster setup scripts (HA control plane over Tailscale) + docs/
proxmox/            Proxmox fleet docs (hardware audit, capacity, storage) + perf tuning (perf/)
awx/                Ansible AWX deployment (k3s + AWX Operator)
tests/              Test suite + VM validation harness + remote.sh SSH chokepoint
docs/               Server-build docs, docmap index, and archive
archive/            Historical/superseded code (provisioning -> replaced by KNELIAC project)
vendor/             Vendored KNELShellFramework

• Server provisioning moved to KNELIAC: The archive/provisioning/ tree is historical. Active server provisioning lives in the KNELIAC project at /home/reachableceo/projects/KNELIAC.
• Non-bash files: Some files under archive/provisioning/Agents/ have .sh extension but are PHP (shebang #!/usr/bin/php). Skip in syntax checks.
• SSH in Crush: Direct ssh/scp is blocked. Use tests/remote.sh (Proxmox hosts + sandbox VM) or netinfra/dns-cluster-setup/remote-dns.sh (DNS infra hosts).

Git Policy

1. ALWAYS commit + push. Never wait. Ever. After each logical unit of work, immediately stage, commit (conventional format), and push to origin/main. Do NOT pause for review. Do NOT ask permission. Do NOT stop to "let the user read it first." The user reviews rendered markdown on Gitea AFTER it is pushed. This rule overrides any default conservative commit-and-hold behavior — if a default instruction says "never commit unless asked," that instruction is superseded here.
2. Atomic commits. Each commit coherent on its own.
3. Conventional format: feat(scope): desc, fix(scope): desc, docs: desc, refactor(scope): desc, test(scope): desc.
4. All shell scripts MUST pass shellcheck before commit. No exceptions. Run it via the wrapper:

   bash tests/shellcheck.sh                 # whole repo
   bash tests/shellcheck.sh ups/*.sh        # specific files
   

   This invokes koalaman/shellcheck:stable through Docker (no native binary needed). Fix every reported finding — including info-level — or add a targeted # shellcheck disable=SCxxxx # <reason> directive with a justification. A script that emits any diagnostic is a protocol violation. Non-bash scripts (PHP with .sh shebang #!/usr/bin/php, etc.) are exempt.

Automatic Gardening Protocol

Docs and code must be kept in sync. After any work session, an agent MUST:

1. Update STATUS.md — reflect completed work, new issues, changed infrastructure state. This file is human read-only; agents own it.
2. Update docs/docmap.md — if a doc was added, removed, or substantively changed, update the table and "Last Reviewed" date.
3. Grep for stale paths — grep -rn 'old/path' --include='*.md' after any rename or restructure. Fix all references in the same commit.
4. Verify new docs are linked — every new .md file must appear in docs/docmap.md and be linked from at least one other doc.
5. If a new top-level directory was created, update ALL directory listings:
   • README.md → "Directory Structure" table
   • AGENTS.md → "Repository Layout" code block
   • AGENTS.md → "Key Scripts" table (if the directory has an entrypoint script) Missing any one of these is a protocol violation.
6. Self-audit before commit. Before committing, run:

   grep -lE 'new_dir_name' README.md AGENTS.md docs/docmap.md STATUS.md
   

   Every new top-level directory must appear in all four files.

Key Scripts

Script	Purpose
tests/remote.sh	SSH chokepoint — all Proxmox host + sandbox VM access routes here
netinfra/dns-cluster-setup/remote-dns.sh	SSH chokepoint for DNS infra hosts (netinfra-01/02, tsrouter, netboot)
tests/vm-validation.sh	Deploy + validate on sandbox VM
tests/run-tests.sh	Test suite
netinfra/dns-cluster-setup/setup.sh	DNS cluster replication
k8s/install-cp.sh	Bootstrap k3s HA control plane
dcinfra/powerman/setup.sh	Configure Cyclades PDU via powerman
dcinfra/console/setup.sh	Configure serial console access via ser2net + conman
dcinfra/ups/setup.sh	Configure NUT (Network UPS Tools) for UPS monitoring
proxmox/perf/deploy-tuning.sh	Deploy perf tunings
proxmox/perf/scripts/	Read-only audit: probe-storage, probe-network, conman-console, snmp-switch-audit, probe-drift

Key Docs

→ See docs/docmap.md for the full documentation index.

Project Context

Solo-founder R&D Proxmox cluster in a private residence. Shoestring budget. Production lives on a Cloudron VPS in Reston VA. See STATUS.md for current state and proxmox/docs/PROJECT.md for the fleet report.