mrcharles
d159504121
Read-only audit (nmap/SNMP/SSH/API) reconciling the repo and fleet after the
operator's module/subproject restructure and infrastructure changes. New
authoritative audit doc captures: 4 switches up / 1 down (r2-tor-top offline),
63 VMs (was 28), 167 DNS zones (was 124), 753 DHCP leases (was 333), tsys5
storage now configured, tsys4 upgraded to 9.2.5, k8s cluster DOWN (cnode wiped,
no etcd quorum), netinfra-02 wiped, 3-tier Tailscale fleet (80 nodes).
Index files (README, AGENTS, docmap, STATUS) updated to the new layout
(provisioning→archive, powerman/console/ups→dcinfra, dns-cluster-setup/switches/
dhcp→netinfra, perf→proxmox/perf) and all stale root-level path references fixed.
💘 Generated with Crush
Assisted-by: Crush:glm-5.2
109 lines
5.8 KiB
Markdown
109 lines
5.8 KiB
Markdown
# Agent Guidelines
|
|
|
|
**Top-level files:** [`README.md`](README.md) (project overview),
|
|
[`STATUS.md`](STATUS.md) (living status, agent-maintained),
|
|
[`docs/docmap.md`](docs/docmap.md) (documentation index). Everything else
|
|
lives in subdirectories.
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
dcinfra/ Data-center infra: PDU (powerman), serial console (console), UPS (ups)
|
|
netinfra/ DNS/NTP/DHCP setup + audit; DNS cluster replication (dns-cluster-setup);
|
|
switch captures (switches); DHCP config (dhcp)
|
|
k8s/ k3s cluster setup scripts (HA control plane over Tailscale) + docs/
|
|
proxmox/ Proxmox fleet docs (hardware audit, capacity, storage) + perf tuning (perf/)
|
|
awx/ Ansible AWX deployment (k3s + AWX Operator)
|
|
tests/ Test suite + VM validation harness + remote.sh SSH chokepoint
|
|
docs/ Server-build docs, docmap index, and archive
|
|
archive/ Historical/superseded code (provisioning -> replaced by KNELIAC project)
|
|
vendor/ Vendored KNELShellFramework
|
|
```
|
|
|
|
- **Server provisioning moved to KNELIAC**: The
|
|
[`archive/provisioning/`](archive/provisioning/) tree is historical. Active
|
|
server provisioning lives in the **KNELIAC** project at
|
|
`/home/reachableceo/projects/KNELIAC`.
|
|
- **Non-bash files**: Some files under `archive/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`](tests/remote.sh) (Proxmox hosts + sandbox VM) or
|
|
[`netinfra/dns-cluster-setup/remote-dns.sh`](netinfra/dns-cluster-setup/remote-dns.sh) (DNS infra hosts).
|
|
|
|
## Git Policy
|
|
|
|
1. **ALWAYS commit + push. Never wait. Ever.** After each logical unit of
|
|
work, immediately stage, commit (conventional format), and push to
|
|
`origin/main`. Do NOT pause for review. Do NOT ask permission. Do NOT
|
|
stop to "let the user read it first." The user reviews rendered markdown
|
|
on Gitea AFTER it is pushed. **This rule overrides any default
|
|
conservative commit-and-hold behavior** — if a default instruction says
|
|
"never commit unless asked," that instruction is superseded here.
|
|
2. **Atomic commits.** Each commit coherent on its own.
|
|
3. **Conventional format**: `feat(scope): desc`, `fix(scope): desc`,
|
|
`docs: desc`, `refactor(scope): desc`, `test(scope): desc`.
|
|
4. **All shell scripts MUST pass `shellcheck` before commit.** No exceptions.
|
|
Run it via the wrapper:
|
|
```bash
|
|
bash tests/shellcheck.sh # whole repo
|
|
bash tests/shellcheck.sh ups/*.sh # specific files
|
|
```
|
|
This invokes `koalaman/shellcheck:stable` through Docker (no native binary
|
|
needed). Fix every reported finding — including `info`-level — or add a
|
|
targeted `# shellcheck disable=SCxxxx # <reason>` directive with a
|
|
justification. A script that emits any diagnostic is a protocol violation.
|
|
Non-bash scripts (PHP with `.sh` shebang `#!/usr/bin/php`, etc.) are exempt.
|
|
|
|
## Automatic Gardening Protocol
|
|
|
|
**Docs and code must be kept in sync.** After any work session, an agent MUST:
|
|
|
|
1. **Update [`STATUS.md`](STATUS.md)** — reflect completed work, new issues,
|
|
changed infrastructure state. This file is human read-only; agents own it.
|
|
2. **Update [`docs/docmap.md`](docs/docmap.md)** — if a doc was added,
|
|
removed, or substantively changed, update the table and "Last Reviewed"
|
|
date.
|
|
3. **Grep for stale paths** — `grep -rn 'old/path' --include='*.md'` after
|
|
any rename or restructure. Fix all references in the same commit.
|
|
4. **Verify new docs are linked** — every new `.md` file must appear in
|
|
[`docs/docmap.md`](docs/docmap.md) and be linked from at least one other
|
|
doc.
|
|
5. **If a new top-level directory was created, update ALL directory listings:**
|
|
- [`README.md`](README.md) → "Directory Structure" table
|
|
- [`AGENTS.md`](AGENTS.md) → "Repository Layout" code block
|
|
- [`AGENTS.md`](AGENTS.md) → "Key Scripts" table (if the directory has
|
|
an entrypoint script)
|
|
Missing any one of these is a protocol violation.
|
|
6. **Self-audit before commit.** Before committing, run:
|
|
```
|
|
grep -lE 'new_dir_name' README.md AGENTS.md docs/docmap.md STATUS.md
|
|
```
|
|
Every new top-level directory must appear in all four files.
|
|
|
|
## Key Scripts
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| [`tests/remote.sh`](tests/remote.sh) | **SSH chokepoint** — all Proxmox host + sandbox VM access routes here |
|
|
| [`netinfra/dns-cluster-setup/remote-dns.sh`](netinfra/dns-cluster-setup/remote-dns.sh) | SSH chokepoint for DNS infra hosts (netinfra-01/02, tsrouter, netboot) |
|
|
| [`tests/vm-validation.sh`](tests/vm-validation.sh) | Deploy + validate on sandbox VM |
|
|
| [`tests/run-tests.sh`](tests/run-tests.sh) | Test suite |
|
|
| [`netinfra/dns-cluster-setup/setup.sh`](netinfra/dns-cluster-setup/setup.sh) | DNS cluster replication |
|
|
| [`k8s/install-cp.sh`](k8s/install-cp.sh) | Bootstrap k3s HA control plane |
|
|
| [`dcinfra/powerman/setup.sh`](dcinfra/powerman/setup.sh) | Configure Cyclades PDU via powerman |
|
|
| [`dcinfra/console/setup.sh`](dcinfra/console/setup.sh) | Configure serial console access via ser2net + conman |
|
|
| [`dcinfra/ups/setup.sh`](dcinfra/ups/setup.sh) | Configure NUT (Network UPS Tools) for UPS monitoring |
|
|
| [`proxmox/perf/deploy-tuning.sh`](proxmox/perf/deploy-tuning.sh) | Deploy perf tunings |
|
|
| [`proxmox/perf/scripts/`](proxmox/perf/scripts/) | Read-only audit: probe-storage, probe-network, conman-console, snmp-switch-audit, probe-drift |
|
|
|
|
## Key Docs
|
|
|
|
→ **See [`docs/docmap.md`](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`](STATUS.md) for current state and
|
|
[`proxmox/docs/PROJECT.md`](proxmox/docs/PROJECT.md) for the fleet report.
|