Files

T

mrcharles 4f2bfe18a5 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

3.2 KiB

Raw Blame History

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

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/ 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 or dns-cluster-setup/remote-dns.sh.

Git Policy

Autonomous commit + push. Do not wait to be asked. After each logical unit: stage, commit (conventional format), push to origin/main.
Atomic commits. Each commit coherent on its own.
Conventional format: feat(scope): desc, fix(scope): desc, docs: desc, refactor(scope): desc, test(scope): desc.

Automatic Gardening Protocol

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

Update STATUS.md — reflect completed work, new issues, changed infrastructure state. This file is human read-only; agents own it.
Update docs/docmap.md — if a doc was added, removed, or substantively changed, update the table and "Last Reviewed" date.
Grep for stale paths — grep -rn 'old/path' --include='*.md' after any rename or restructure. Fix all references in the same commit.
Verify new docs are linked — every new .md file must appear in docs/docmap.md and be linked from at least one other doc.

Key Scripts

Script	Purpose
`provisioning/SetupNewSystem.sh`	Full server provisioning
`tests/vm-validation.sh`	Deploy + validate on sandbox VM
`tests/run-tests.sh`	Test suite
`dns-cluster-setup/setup.sh`	DNS cluster replication
`perf/deploy-tuning.sh`	Deploy perf tunings

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 docs/PROJECT.md for the fleet report.

3.2 KiB Raw Blame History