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>
4.0 KiB
4.0 KiB
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 |
Comprehensive fleet report: 7 Proxmox hosts, VM inventory, storage architecture, recommendations | 2026-07-27 |
SECURITY.md |
Security architecture: SSH hardening, 2FA, SCAP-STIG, Wazuh, auditd | 2026-07-25 |
tailscale.md |
Tailscale vs managed DNS analysis (RESOLVED — netinfra pair serves knel.net) | 2026-07-28 |
DEPLOYMENT.md |
Server deployment procedures, package lists, config flow | 2026-07-25 |
TODO.md |
Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 |
K8S.md |
Kubernetes architecture deep-dive (for future k8s session) | 2026-07-27 |
TSYS-2FA-GUIDE.md |
End-user guide for 2FA setup (SSH, Cockpit, Webmin) | 2026-07-25 |
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 |
Technitium DNS cluster setup: export, deploy, cluster, verify | 2026-07-28 |
../tests/README.md |
Test suite documentation: unit, security, validation tests | 2026-07-28 |
../netinfra/pfv-netinfra-setup.md |
pfv-netinfra-01/02 initial setup guide | 2026-07-27 |
../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 |
Early code review findings (most issues now fixed) |
REFACTORING-EXAMPLES.md |
Pre-refactor code patterns (historical "before" examples) |
Claude-Review.md |
Claude's initial code review |
AIReview-QWEN.md |
Qwen AI review |
AiOverview-Gemini.md |
Gemini project overview |
AiOverview-OpenCode.md |
OpenCode project overview |
AiSecurityAudit-Gemini.md |
Gemini security audit |
charles-todo.md |
Charles's early task list (completed) |
claude-todo.md |
Claude's early task list (completed) |
Top-Level Files
| File | Description |
|---|---|
../AGENTS.md |
Agent operating instructions (repo layout, git policy, key scripts) |
../STATUS.md |
Living project status (agent-maintained, human read-only) |
../README.md |
Project overview and quick start |
../LICENSE |
License |
Agent Gardening Protocol
When making changes to this repo, agents MUST:
- Update
../STATUS.mdif the work changes infrastructure state, completes/starts a task, or discovers a new issue. - Update this file (
docmap.md) if a doc is added, removed, or has a substantive content change. Update the "Last Reviewed" date. - Verify cross-references — any new
.mdfile must be linked from at least one existing doc or this map. - Check for stale paths — after any directory rename or file move,
grep all
.mdfiles for old paths and fix them. - 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.