mrcharles
4f2bfe18a5
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>
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# 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
|
|
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.
|
|
- **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. **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`.
|
|
|
|
## 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.
|
|
|
|
## 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 |
|
|
| [`perf/deploy-tuning.sh`](perf/deploy-tuning.sh) | Deploy perf tunings |
|
|
|
|
## 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
|
|
[`docs/PROJECT.md`](docs/PROJECT.md) for the fleet report.
|