docs: add STATUS.md, docmap.md, encode gardening protocol

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>
This commit is contained in:
2026-07-28 11:32:03 -05:00
parent a7fbad60ab
commit 4f2bfe18a5
4 changed files with 208 additions and 100 deletions
+9 -32
View File
@@ -1,7 +1,8 @@
# PFVCluster
Unified infrastructure repo for the Known Element Enterprises Proxmox R&D cluster.
Combines server provisioning, Proxmox cluster operations, and DNS infrastructure.
**[→ Current Status](STATUS.md)** · **[→ Documentation Index](docs/docmap.md)** · **[→ Agent Guidelines](AGENTS.md)**
## Directory Structure
@@ -13,7 +14,7 @@ Combines server provisioning, Proxmox cluster operations, and DNS infrastructure
| [`perf/`](perf/) | Proxmox performance tuning, fleet audit, iperf, switch diagnostics |
| [`netinfra/`](netinfra/) | pfv-netinfra-01/02 DNS/NTP setup + audit scripts |
| [`switches/`](switches/) | Switch configuration captures |
| [`docs/`](docs/) | All documentation |
| [`docs/`](docs/) | All documentation ([see docmap](docs/docmap.md)) |
| [`vendor/`](vendor/) | Vendored KNELShellFramework |
## Quick Start
@@ -22,50 +23,26 @@ Combines server provisioning, Proxmox cluster operations, and DNS infrastructure
```bash
sudo bash provisioning/SetupNewSystem.sh
```
Installs packages, applies security hardening (SSH, SCAP-STIG, 2FA, Wazuh),
configures NTP/DNS/SNMP/syslog/postfix.
### Validate provisioning on the sandbox VM
### Validate on the sandbox VM
```bash
VM_ID=6000 ./tests/vm-validation.sh all
```
Snapshots, deploys, runs the test suite, auto-rolls back on failure.
### Run the test suite
### Deploy DNS cluster
```bash
./tests/run-tests.sh all
cd dns-cluster-setup/ && ./setup.sh all
```
### Deploy DNS cluster setup
### Deploy perf tunings
```bash
cd dns-cluster-setup/
./setup.sh all
cd perf/ && ./deploy-tuning.sh
```
### Deploy perf tunings to hosts
```bash
cd perf/
./deploy-check.sh # read-only data collection
./deploy-tuning.sh # apply sysctl/tuned/NFS tunings
```
## Key Documentation
| Doc | Contents |
|-----|----------|
| [`docs/PROJECT.md`](docs/PROJECT.md) | Comprehensive fleet report (7 hosts, VM inventory, storage) |
| [`docs/SECURITY.md`](docs/SECURITY.md) | Security architecture and hardening details |
| [`docs/tailscale.md`](docs/tailscale.md) | Tailscale vs managed DNS analysis (resolved) |
| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Deployment procedures |
| [`docs/TODO.md`](docs/TODO.md) | Pending hardware work (tsys2/4/5) |
| [`docs/K8S.md`](docs/K8S.md) | Kubernetes architecture deep-dive |
| [`dns-cluster-setup/README.md`](dns-cluster-setup/README.md) | DNS cluster setup guide |
| [`tests/README.md`](tests/README.md) | Test suite documentation |
## Architecture
- **Proxmox hosts**: 7 standalone PVE installs managed via PDM
- **DNS**: Technitium (authoritative) + Pi-hole (recursive) on pfv-netinfra-01/02
- **NTP**: pfv-netinfra-01/02 (redundant, LAN IPs)
- **NTP**: pfv-netinfra-01/02 (redundant, LAN IPs, stratum 2/3)
- **Production**: Cloudron VPS in Reston VA (this cluster is R&D only)
- **Backups**: Proxmox Backup Server (PBS)