docs: add STATUS.md, docmap.md, encode gardening protocol

Restructure top-level to exactly three .md files: - AGENTS.md (agent operating instructions) - README.md (project overview, links to status + docmap) - STATUS.md (living project status, agent-maintained, human read-only) Add docs/docmap.md as the single documentation index/map. All docs are categorized (active, operational guides, historical) with last-reviewed dates. Includes the agent gardening protocol requiring agents to update STATUS.md and docmap.md after every work session. Rewrite AGENTS.md to be lean: points to docmap.md for doc discovery, encodes the automatic gardening protocol (keep docs/code in sync, grep for stale paths after renames, update STATUS.md after infrastructure changes). All references are Gitea-renderable relative links. Simplify README.md: header links to STATUS.md + docmap.md + AGENTS.md, doc table replaced with pointer to docmap.md. 🤖 Generated with [Crush](https://github.com/charmassociates/crush) Assisted-by: GLM-5 via Crush <crush@charm.land>
2026-07-28 11:32:03 -05:00
parent a7fbad60ab
commit 4f2bfe18a5
4 changed files with 208 additions and 100 deletions
@@ -1,87 +1,75 @@
 # Agent Guidelines

-This repo combines two formerly-separate projects:
- **Server provisioning** (formerly KNELServerBuild): [`provisioning/`](provisioning/),
-  [`tests/`](tests/), [`vendor/`](vendor/), [`dns-cluster-setup/`](dns-cluster-setup/)
- **Proxmox cluster ops** (formerly PFVCluster/perfopt): [`perf/`](perf/),
-  [`netinfra/`](netinfra/), [`switches/`](switches/)
+**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

- **Vendored framework**: `KNELShellFramework` lives at
-  `vendor/git@git.knownelement.com/29418/KNEL/KNELShellFramework/`. Its includes
-  are under `Framework-Includes/` there. Never assume `./Framework-Includes`
-  exists relative to the repo root.
- **Self-locating scripts**: All provisioning scripts derive their own location
-  via `BASH_SOURCE` and compute `PROJECT_ROOT_PATH` from it. They must never
-  depend on the current working directory. Run from anywhere.
- **Local config files are the source of truth**: Configs in
+```
+provisioning/        Server provisioning (SetupNewSystem.sh, security, 2FA)
+tests/               Test suite + VM validation harness
+dns-cluster-setup/   Technitium DNS cluster replication
+perf/                Proxmox perf tuning, fleet audit, iperf
+netinfra/            pfv-netinfra-01/02 DNS/NTP setup
+switches/            Switch configuration captures
+docs/                All documentation (see docs/docmap.md)
+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 — that CDN
-  is deprecated.
- **Non-bash agents**: Some files under `provisioning/Agents/` carry a `.sh`
-  extension but are PHP (e.g. `mysql.sh`, shebang `#!/usr/bin/php`). Syntax
-  checkers must skip these.
- **Proxmox hosts** are standalone installs managed via **PDM** (Proxmox
-  Datacenter Manager). SSH keys deployed to `localuser` with passwordless sudo
-  on all hosts.
- **SSH in Crush**: Direct ssh/scp is blocked in the Crush bash environment.
-  Use the wrapper scripts: [`tests/remote.sh`](tests/remote.sh),
-  [`dns-cluster-setup/remote-dns.sh`](dns-cluster-setup/remote-dns.sh),
-  or the `perf/deploy-check.sh` / `perf/deploy-tuning.sh` patterns.
+  `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 Commit Requirements
+## Git Policy

-1. **Commit atomically**: each logical change its own commit.
-2. **Conventional commit format**: `feat(scope): desc`, `fix(scope): desc`,
-   `docs: desc`, `refactor(scope): desc`, `test(scope): desc`, `chore: desc`.
-3. **Verbose messages**: title (50 chars max), blank line, body explaining
-   WHAT and WHY, footer with attribution.
+1. **Autonomous commit + push.** Do not wait to be asked. After each logical
+   unit: stage, commit (conventional format), push to `origin/main`.
+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`.

-## Autonomous Git Workflow
+## Automatic Gardening Protocol

-**Agents are authorized to commit AND push autonomously — do not wait to be
-asked.** After each logical unit of work:
+**Docs and code must be kept in sync.** After any work session, an agent MUST:

-1. Stage only the files belonging to that logical change.
-2. Commit with a conventional, well-formed message.
-3. Push to `origin` (`git push`). The branch tracks `origin/main`.
-4. Repeat per logical unit.
+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.

-Group changes so each commit is coherent on its own (a reader should
-understand the commit without seeing the others). Never batch unrelated
-changes into one commit.
-
-## Key scripts
+## Key Scripts

 | Script | Purpose |
 |--------|---------|
-| [`provisioning/SetupNewSystem.sh`](provisioning/SetupNewSystem.sh) | Full server provisioning (packages, hardening, 2FA) |
-| [`tests/vm-validation.sh`](tests/vm-validation.sh) | End-to-end deploy + validate on sandbox VM |
-| [`tests/run-tests.sh`](tests/run-tests.sh) | Project test suite (unit/security/validation) |
-| [`dns-cluster-setup/setup.sh`](dns-cluster-setup/setup.sh) | Technitium DNS cluster replication |
-| [`perf/deploy-check.sh`](perf/deploy-check.sh) | Deploy read-only data collector to hosts |
-| [`perf/deploy-tuning.sh`](perf/deploy-tuning.sh) | Deploy perf tunings to hosts |
-| [`perf/validate-fixes.sh`](perf/validate-fixes.sh) | Validate applied tuning changes |
-| [`perf/iperf-full-matrix.sh`](perf/iperf-full-matrix.sh) | Full iperf throughput suite |
+| [`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 |
+| [`perf/deploy-tuning.sh`](perf/deploy-tuning.sh) | Deploy perf tunings |

-## Key documentation
+## Key Docs

-| Doc | Contents |
-|-----|----------|
-| [`docs/PROJECT.md`](docs/PROJECT.md) | Comprehensive fleet report (7 hosts, VM inventory, storage) |
-| [`docs/SECURITY.md`](docs/SECURITY.md) | Security architecture and hardening details |
-| [`docs/tailscale.md`](docs/tailscale.md) | Tailscale vs managed DNS analysis (resolved) |
-| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Deployment procedures |
-| [`docs/TODO.md`](docs/TODO.md) | Pending hardware work (tsys2/4/5) |
-| [`docs/K8S.md`](docs/K8S.md) | Kubernetes architecture deep-dive |
-| [`dns-cluster-setup/README.md`](dns-cluster-setup/README.md) | DNS cluster setup guide |
-| [`tests/README.md`](tests/README.md) | Test suite documentation |
+→ **See [`docs/docmap.md`](docs/docmap.md) for the full documentation index.**

-## Project context
+## Project Context

-This is a solo-founder R&D Proxmox cluster in a private residence. Shoestring
-budget. Redundancy is not a concern for the R&D cluster. Backups DO matter
-(PBS in use). Production lives on a VPS in Reston VA (Cloudron). See
-[`docs/PROJECT.md`](docs/PROJECT.md) for the comprehensive fleet report and
-[`docs/TODO.md`](docs/TODO.md) for pending hardware work.
+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/PROJECT.md`](docs/PROJECT.md) for the fleet report.