# Agent Guidelines

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

## Repository Layout

```
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) + docs/
powerman/            Cyclades PM10i PDU management via powerman
console/             Serial console management (ser2net + conman) for switches
ups/                 UPS management (NUT) for APC Smart-UPS C 1500 on pfv-tsys1
perf/                Proxmox perf tuning, fleet audit, iperf
proxmox/             Proxmox fleet docs (hardware audit, capacity, k8s host planning)
netinfra/            pfv-netinfra-01/02 DNS/NTP/DHCP setup
switches/            Switch configuration captures
awx/                 Ansible AWX deployment (k3s + AWX Operator)
docs/                Server-build docs, docmap index, and archive
vendor/              Vendored KNELShellFramework
```

- **Self-locating scripts**: All provisioning scripts derive their own
  location via `BASH_SOURCE` and compute `PROJECT_ROOT_PATH` from it. Run
  from anywhere.
- **Local configs are the source of truth**: Files in
  [`provisioning/ConfigFiles/`](provisioning/ConfigFiles/) are read with
  `cat`/`cp`. Do NOT re-introduce `curl ${DL_ROOT}/...` downloads.
- **Non-bash files**: Some files under `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`](tests/remote.sh) or
  [`dns-cluster-setup/remote-dns.sh`](dns-cluster-setup/remote-dns.sh).

## 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
   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`](STATUS.md)** — reflect completed work, new issues,
   changed infrastructure state. This file is human read-only; agents own it.
2. **Update [`docs/docmap.md`](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`](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`](README.md) → "Directory Structure" table
   - [`AGENTS.md`](AGENTS.md) → "Repository Layout" code block
   - [`AGENTS.md`](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 |
|--------|---------|
| [`provisioning/SetupNewSystem.sh`](provisioning/SetupNewSystem.sh) | Full server provisioning |
| [`tests/vm-validation.sh`](tests/vm-validation.sh) | Deploy + validate on sandbox VM |
| [`tests/run-tests.sh`](tests/run-tests.sh) | Test suite |
| [`dns-cluster-setup/setup.sh`](dns-cluster-setup/setup.sh) | DNS cluster replication |
| [`k8s/install-cp.sh`](k8s/install-cp.sh) | Bootstrap k3s HA control plane |
| [`powerman/setup.sh`](powerman/setup.sh) | Configure Cyclades PDU via powerman |
| [`console/setup.sh`](console/setup.sh) | Configure serial console access via ser2net + conman |
| [`ups/setup.sh`](ups/setup.sh) | Configure NUT (Network UPS Tools) for UPS monitoring |
| [`perf/deploy-tuning.sh`](perf/deploy-tuning.sh) | Deploy perf tunings |
| [`perf/scripts/probe-storage.sh`](perf/scripts/probe-storage.sh) | Read-only disk/mount/export/SMART audit |
| [`perf/scripts/probe-network.sh`](perf/scripts/probe-network.sh) | Read-only NIC/bond/LLDP/NFS audit |
| [`perf/scripts/conman-console.py`](perf/scripts/conman-console.py) | Drive switch consoles via conman (PTY-based) |
| [`perf/scripts/snmp-switch-audit.py`](perf/scripts/snmp-switch-audit.py) | SNMP-based switch inventory (interfaces, LLDP, LAG, VLANs) |
| [`perf/scripts/probe-drift.sh`](perf/scripts/probe-drift.sh) | Read-only fleet drift probe (packages, services, tuning, SSH, security) |

## Key Docs

→ **See [`docs/docmap.md`](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`](STATUS.md) for current state and
[`proxmox/docs/PROJECT.md`](proxmox/docs/PROJECT.md) for the fleet report.
