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>
75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# Documentation Map
|
|
|
|
> **Index of all documentation in this repo.** Agents must update this file
|
|
> whenever a doc is added, removed, or substantively changed.
|
|
|
|
> **Last updated:** 2026-07-28
|
|
|
|
## Active Documentation
|
|
|
|
These docs reflect current reality and should be kept up to date.
|
|
|
|
| Document | Description | Last Reviewed |
|
|
|----------|-------------|---------------|
|
|
| [`PROJECT.md`](PROJECT.md) | Comprehensive fleet report: 7 Proxmox hosts, VM inventory, storage architecture, recommendations | 2026-07-27 |
|
|
| [`SECURITY.md`](SECURITY.md) | Security architecture: SSH hardening, 2FA, SCAP-STIG, Wazuh, auditd | 2026-07-25 |
|
|
| [`tailscale.md`](tailscale.md) | Tailscale vs managed DNS analysis (RESOLVED — netinfra pair serves knel.net) | 2026-07-28 |
|
|
| [`DEPLOYMENT.md`](DEPLOYMENT.md) | Server deployment procedures, package lists, config flow | 2026-07-25 |
|
|
| [`TODO.md`](TODO.md) | Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 |
|
|
| [`K8S.md`](K8S.md) | Kubernetes architecture deep-dive (for future k8s session) | 2026-07-27 |
|
|
| [`TSYS-2FA-GUIDE.md`](TSYS-2FA-GUIDE.md) | End-user guide for 2FA setup (SSH, Cockpit, Webmin) | 2026-07-25 |
|
|
| [`DEVELOPMENT-GUIDELINES.md`](DEVELOPMENT-GUIDELINES.md) | Coding standards, commit conventions, script patterns | 2026-07-25 |
|
|
|
|
## Operational Guides (outside docs/)
|
|
|
|
| Document | Description | Last Reviewed |
|
|
|----------|-------------|---------------|
|
|
| [`../dns-cluster-setup/README.md`](../dns-cluster-setup/README.md) | Technitium DNS cluster setup: export, deploy, cluster, verify | 2026-07-28 |
|
|
| [`../tests/README.md`](../tests/README.md) | Test suite documentation: unit, security, validation tests | 2026-07-28 |
|
|
| [`../netinfra/pfv-netinfra-setup.md`](../netinfra/pfv-netinfra-setup.md) | pfv-netinfra-01/02 initial setup guide | 2026-07-27 |
|
|
| [`../netinfra/pfv-netboot-setup.md`](../netinfra/pfv-netboot-setup.md) | pfv-netboot reference node setup | 2026-07-27 |
|
|
|
|
## Historical / Reference (read-only context)
|
|
|
|
These docs are preserved for historical context. They may reference pre-merge
|
|
paths or outdated architecture. Do not update them; link to active docs instead.
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [`CODE-REVIEW-FINDINGS.md`](CODE-REVIEW-FINDINGS.md) | Early code review findings (most issues now fixed) |
|
|
| [`REFACTORING-EXAMPLES.md`](REFACTORING-EXAMPLES.md) | Pre-refactor code patterns (historical "before" examples) |
|
|
| [`Claude-Review.md`](Claude-Review.md) | Claude's initial code review |
|
|
| [`AIReview-QWEN.md`](AIReview-QWEN.md) | Qwen AI review |
|
|
| [`AiOverview-Gemini.md`](AiOverview-Gemini.md) | Gemini project overview |
|
|
| [`AiOverview-OpenCode.md`](AiOverview-OpenCode.md) | OpenCode project overview |
|
|
| [`AiSecurityAudit-Gemini.md`](AiSecurityAudit-Gemini.md) | Gemini security audit |
|
|
| [`charles-todo.md`](charles-todo.md) | Charles's early task list (completed) |
|
|
| [`claude-todo.md`](claude-todo.md) | Claude's early task list (completed) |
|
|
|
|
## Top-Level Files
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| [`../AGENTS.md`](../AGENTS.md) | Agent operating instructions (repo layout, git policy, key scripts) |
|
|
| [`../STATUS.md`](../STATUS.md) | Living project status (agent-maintained, human read-only) |
|
|
| [`../README.md`](../README.md) | Project overview and quick start |
|
|
| [`../LICENSE`](../LICENSE) | License |
|
|
|
|
---
|
|
|
|
## Agent Gardening Protocol
|
|
|
|
When making changes to this repo, agents MUST:
|
|
|
|
1. **Update [`../STATUS.md`](../STATUS.md)** if the work changes infrastructure
|
|
state, completes/starts a task, or discovers a new issue.
|
|
2. **Update this file (`docmap.md`)** if a doc is added, removed, or has a
|
|
substantive content change. Update the "Last Reviewed" date.
|
|
3. **Verify cross-references** — any new `.md` file must be linked from at
|
|
least one existing doc or this map.
|
|
4. **Check for stale paths** — after any directory rename or file move,
|
|
grep all `.md` files for old paths and fix them.
|
|
5. **Keep code and docs in sync** — if you change a script's interface,
|
|
behavior, or location, update every doc that references it in the same
|
|
commit.
|