vh
fde7834635
fv-ml1-cutover.md covers what to change; this covers the on-site hour, where the binding constraints are limited time and not locking ourselves out of a site an hour away. The load-bearing correction is that fv-ml1 running tailscale is NOT a second independent path. Its default route is the OPNsense LAN address, so its node needs egress through OPNsense to reach the control plane; OPNsense down means fv-ml1 is unreachable by construction. An earlier version of this plan claimed otherwise and proposed proving it by rebooting the firewall, which would have failed on site with the operator standing at the rack. He caught it. What the fv-ml1 node does buy is narrower and still worth one command: it covers control-plane lockout -- a bad admin rule, a WebGUI on the wrong interface, a lost password -- where the box still routes but cannot be managed. It does not cover data-plane failure. Those are different failure classes and conflating them produced the wrong test. The gate is now a deny-admin-from-mesh test run while the console is in arm's reach, which exercises the bypass that actually exists. Deliberate deviation from the cutover runbook: flat /24 with the BMC at 10.251.50.50 rather than a mgmt VLAN at 10.251.250.50. The VLAN needs OPNsense config plus switch tagging during the scarcest hour, for something addable remotely in ten minutes. Also records the DNS chicken-and-egg (the mesh needs public resolvers because the fleet AdGuard is unreachable until the mesh is up) and the interface auto-assignment trap measured on the lab VM the same night.
docs/
Navigation map for the documentation tree. New session? Read
orientation.md first — it's the narrative overview
of the fleet, backup architecture, governing principles, and gotchas,
and it points at everything else.
Tree
docs/
├── orientation.md # start here — fleet overview + where-to-look guide
├── runbooks/ # ops runbooks (recovery, deployment phases)
│ ├── disaster-recovery.md
│ ├── nh3-prune-ritual.md
│ └── pbs-deployment.md
└── pfi/ # PFI-specific reference (services, models, VMs)
├── docker-stack.md
├── model-list.md
├── proxmox-vms.md
├── recommended-model-settings.md
├── vm-102-matrix-appservice.md
└── vm-102-matrix-synapse.md
What goes where
runbooks/— step-by-step ops procedures. Anything you'd reach for during an incident or while standing up new infrastructure. Examples: disaster recovery (blast-radius tiers + restoration steps), PBS deployment (9-phase rollout). New runbook → new file here.pfi/— PFI-specific reference material that's too narrow for the top-level CLAUDE.md but doesn't change incident response. AI model inventory, recommended inference settings, Matrix bridge config, Proxmox VM map. New stable reference → new file here.- Top-level (
docs/orientation.md,docs/README.md) — narrative guides about the workspace itself, not about specific infra.
Cross-references
- Fleet topology + servers table: top-level
CLAUDE.md. - Open work + recent milestones: top-level
STATUS.md. - Durable cross-session facts:
~/.claude/projects/-home-lkraven-development-eshpfi-management/memory/.
Conventions
- Markdown, GitHub-flavored. CommonMark renders fine in most viewers.
- File names are lowercase-kebab-case, descriptive. No dates in filenames — git history covers that.
- One topic per file. If a file grows past ~500 lines, look for a natural split before adding more.
- No checked-in binaries or checksums. Build/release artifacts belong
in a build pipeline or
tools/, notdocs/.