From 6b6a8ff021fa3cddece2b57b1c6bcb0ca1628dd4 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Tue, 28 Jul 2026 11:34:23 -0500 Subject: [PATCH] docs: organize docs into project subdirectories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split docs/ into project-based subdirectories: - docs/proxmox/ fleet ops, hardware, k8s (PROJECT.md, TODO.md, K8S.md) - docs/server-build/ provisioning, security, DNS (SECURITY.md, tailscale.md, DEPLOYMENT.md, TSYS-2FA-GUIDE.md, DEVELOPMENT-GUIDELINES.md) - docs/archive/ historical AI reviews, completed todos, pre-refactor docs docmap.md rewritten with new paths. All cross-references in AGENTS.md, README.md, STATUS.md, and dns-cluster-setup/README.md updated. Code directories unchanged — scripts stay where BASH_SOURCE expects them. 🤖 Generated with [Crush](https://github.com/charmassociates/crush) Assisted-by: GLM-5 via Crush --- AGENTS.md | 2 +- dns-cluster-setup/README.md | 2 +- docs/{ => archive}/AIReview-QWEN.md | 0 docs/{ => archive}/AiOverview-Gemini.md | 0 docs/{ => archive}/AiOverview-OpenCode.md | 0 docs/{ => archive}/AiSecurityAudit-Gemini.md | 0 docs/{ => archive}/CODE-REVIEW-FINDINGS.md | 0 docs/{ => archive}/Claude-Review.md | 0 docs/{ => archive}/REFACTORING-EXAMPLES.md | 0 docs/{ => archive}/charles-todo.md | 0 docs/{ => archive}/claude-todo.md | 0 docs/docmap.md | 55 +++++++++++-------- docs/{ => proxmox}/K8S.md | 0 docs/{ => proxmox}/PROJECT.md | 0 docs/{ => proxmox}/TODO.md | 0 docs/{ => server-build}/DEPLOYMENT.md | 0 .../DEVELOPMENT-GUIDELINES.md | 0 docs/{ => server-build}/SECURITY.md | 0 docs/{ => server-build}/TSYS-2FA-GUIDE.md | 0 docs/{ => server-build}/tailscale.md | 0 20 files changed, 33 insertions(+), 26 deletions(-) rename docs/{ => archive}/AIReview-QWEN.md (100%) rename docs/{ => archive}/AiOverview-Gemini.md (100%) rename docs/{ => archive}/AiOverview-OpenCode.md (100%) rename docs/{ => archive}/AiSecurityAudit-Gemini.md (100%) rename docs/{ => archive}/CODE-REVIEW-FINDINGS.md (100%) rename docs/{ => archive}/Claude-Review.md (100%) rename docs/{ => archive}/REFACTORING-EXAMPLES.md (100%) rename docs/{ => archive}/charles-todo.md (100%) rename docs/{ => archive}/claude-todo.md (100%) rename docs/{ => proxmox}/K8S.md (100%) rename docs/{ => proxmox}/PROJECT.md (100%) rename docs/{ => proxmox}/TODO.md (100%) rename docs/{ => server-build}/DEPLOYMENT.md (100%) rename docs/{ => server-build}/DEVELOPMENT-GUIDELINES.md (100%) rename docs/{ => server-build}/SECURITY.md (100%) rename docs/{ => server-build}/TSYS-2FA-GUIDE.md (100%) rename docs/{ => server-build}/tailscale.md (100%) diff --git a/AGENTS.md b/AGENTS.md index dffa0cd..ab48c5a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,4 +72,4 @@ vendor/ Vendored KNELShellFramework 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. +[`docs/proxmox/PROJECT.md`](docs/proxmox/PROJECT.md) for the fleet report. diff --git a/dns-cluster-setup/README.md b/dns-cluster-setup/README.md index db33c10..244bf11 100644 --- a/dns-cluster-setup/README.md +++ b/dns-cluster-setup/README.md @@ -179,5 +179,5 @@ dig @192.168.3.253 pfv-netinfra-01.knel.net The KNELServerBuild provisioning code (`provisioning/ConfigFiles/NTP/ntp.conf` and `provisioning/ConfigFiles/Resolv/resolv.conf`) points clients at both -servers for DNS and NTP redundancy. See `docs/tailscale.md` for the +servers for DNS and NTP redundancy. See `docs/server-build/tailscale.md` for the full DNS architecture analysis. diff --git a/docs/AIReview-QWEN.md b/docs/archive/AIReview-QWEN.md similarity index 100% rename from docs/AIReview-QWEN.md rename to docs/archive/AIReview-QWEN.md diff --git a/docs/AiOverview-Gemini.md b/docs/archive/AiOverview-Gemini.md similarity index 100% rename from docs/AiOverview-Gemini.md rename to docs/archive/AiOverview-Gemini.md diff --git a/docs/AiOverview-OpenCode.md b/docs/archive/AiOverview-OpenCode.md similarity index 100% rename from docs/AiOverview-OpenCode.md rename to docs/archive/AiOverview-OpenCode.md diff --git a/docs/AiSecurityAudit-Gemini.md b/docs/archive/AiSecurityAudit-Gemini.md similarity index 100% rename from docs/AiSecurityAudit-Gemini.md rename to docs/archive/AiSecurityAudit-Gemini.md diff --git a/docs/CODE-REVIEW-FINDINGS.md b/docs/archive/CODE-REVIEW-FINDINGS.md similarity index 100% rename from docs/CODE-REVIEW-FINDINGS.md rename to docs/archive/CODE-REVIEW-FINDINGS.md diff --git a/docs/Claude-Review.md b/docs/archive/Claude-Review.md similarity index 100% rename from docs/Claude-Review.md rename to docs/archive/Claude-Review.md diff --git a/docs/REFACTORING-EXAMPLES.md b/docs/archive/REFACTORING-EXAMPLES.md similarity index 100% rename from docs/REFACTORING-EXAMPLES.md rename to docs/archive/REFACTORING-EXAMPLES.md diff --git a/docs/charles-todo.md b/docs/archive/charles-todo.md similarity index 100% rename from docs/charles-todo.md rename to docs/archive/charles-todo.md diff --git a/docs/claude-todo.md b/docs/archive/claude-todo.md similarity index 100% rename from docs/claude-todo.md rename to docs/archive/claude-todo.md diff --git a/docs/docmap.md b/docs/docmap.md index d0bd2f4..2c6f55a 100644 --- a/docs/docmap.md +++ b/docs/docmap.md @@ -5,20 +5,27 @@ > **Last updated:** 2026-07-28 -## Active Documentation +## Proxmox Cluster ([`proxmox/`](proxmox/)) -These docs reflect current reality and should be kept up to date. +Fleet operations, hardware, performance tuning, storage architecture. | 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 | +| [`proxmox/PROJECT.md`](proxmox/PROJECT.md) | Comprehensive fleet report: 7 hosts, VM inventory, storage, recommendations | 2026-07-27 | +| [`proxmox/TODO.md`](proxmox/TODO.md) | Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 | +| [`proxmox/K8S.md`](proxmox/K8S.md) | Kubernetes architecture deep-dive (for future k8s session) | 2026-07-27 | + +## Server Build ([`server-build/`](server-build/)) + +Server provisioning, security hardening, DNS/NTP configuration. + +| Document | Description | Last Reviewed | +|----------|-------------|---------------| +| [`server-build/SECURITY.md`](server-build/SECURITY.md) | Security architecture: SSH hardening, 2FA, SCAP-STIG, Wazuh, auditd | 2026-07-25 | +| [`server-build/tailscale.md`](server-build/tailscale.md) | Tailscale vs managed DNS analysis (RESOLVED — netinfra pair serves knel.net) | 2026-07-28 | +| [`server-build/DEPLOYMENT.md`](server-build/DEPLOYMENT.md) | Server deployment procedures, package lists, config flow | 2026-07-25 | +| [`server-build/TSYS-2FA-GUIDE.md`](server-build/TSYS-2FA-GUIDE.md) | End-user guide for 2FA setup (SSH, Cockpit, Webmin) | 2026-07-25 | +| [`server-build/DEVELOPMENT-GUIDELINES.md`](server-build/DEVELOPMENT-GUIDELINES.md) | Coding standards, commit conventions, script patterns | 2026-07-25 | ## Operational Guides (outside docs/) @@ -29,28 +36,28 @@ These docs reflect current reality and should be kept up to date. | [`../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) +## Archive ([`archive/`](archive/)) -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. +Historical AI reviews, completed task lists, and pre-refactor examples. Read-only +context — do not update; 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) | +| [`archive/CODE-REVIEW-FINDINGS.md`](archive/CODE-REVIEW-FINDINGS.md) | Early code review findings (most issues now fixed) | +| [`archive/REFACTORING-EXAMPLES.md`](archive/REFACTORING-EXAMPLES.md) | Pre-refactor code patterns (historical "before" examples) | +| [`archive/Claude-Review.md`](archive/Claude-Review.md) | Claude's initial code review | +| [`archive/AIReview-QWEN.md`](archive/AIReview-QWEN.md) | Qwen AI review | +| [`archive/AiOverview-Gemini.md`](archive/AiOverview-Gemini.md) | Gemini project overview | +| [`archive/AiOverview-OpenCode.md`](archive/AiOverview-OpenCode.md) | OpenCode project overview | +| [`archive/AiSecurityAudit-Gemini.md`](archive/AiSecurityAudit-Gemini.md) | Gemini security audit | +| [`archive/charles-todo.md`](archive/charles-todo.md) | Charles's early task list (completed) | +| [`archive/claude-todo.md`](archive/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) | +| [`../AGENTS.md`](../AGENTS.md) | Agent operating instructions (repo layout, git policy, gardening protocol) | | [`../STATUS.md`](../STATUS.md) | Living project status (agent-maintained, human read-only) | | [`../README.md`](../README.md) | Project overview and quick start | | [`../LICENSE`](../LICENSE) | License | @@ -68,7 +75,7 @@ When making changes to this repo, agents MUST: 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. + `grep -rn 'old/path' --include='*.md'` and fix all references. 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. diff --git a/docs/K8S.md b/docs/proxmox/K8S.md similarity index 100% rename from docs/K8S.md rename to docs/proxmox/K8S.md diff --git a/docs/PROJECT.md b/docs/proxmox/PROJECT.md similarity index 100% rename from docs/PROJECT.md rename to docs/proxmox/PROJECT.md diff --git a/docs/TODO.md b/docs/proxmox/TODO.md similarity index 100% rename from docs/TODO.md rename to docs/proxmox/TODO.md diff --git a/docs/DEPLOYMENT.md b/docs/server-build/DEPLOYMENT.md similarity index 100% rename from docs/DEPLOYMENT.md rename to docs/server-build/DEPLOYMENT.md diff --git a/docs/DEVELOPMENT-GUIDELINES.md b/docs/server-build/DEVELOPMENT-GUIDELINES.md similarity index 100% rename from docs/DEVELOPMENT-GUIDELINES.md rename to docs/server-build/DEVELOPMENT-GUIDELINES.md diff --git a/docs/SECURITY.md b/docs/server-build/SECURITY.md similarity index 100% rename from docs/SECURITY.md rename to docs/server-build/SECURITY.md diff --git a/docs/TSYS-2FA-GUIDE.md b/docs/server-build/TSYS-2FA-GUIDE.md similarity index 100% rename from docs/TSYS-2FA-GUIDE.md rename to docs/server-build/TSYS-2FA-GUIDE.md diff --git a/docs/tailscale.md b/docs/server-build/tailscale.md similarity index 100% rename from docs/tailscale.md rename to docs/server-build/tailscale.md