# 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

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

## 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.