Files

T

mrcharles 6b6a8ff021 docs: organize docs into project subdirectories

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 <crush@charm.land>

2026-07-28 11:34:23 -05:00

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

3.3 KiB Raw Blame History