Documentation validation — 2026-06-19¶

Point-in-time audit: repo documentation vs live homelab reality after Phase 7 (DNS cutover, Tailscale, ACL GitOps). Use with documentation-validation.md to re-run checks later.

Auditor: Cursor agent session (owner-requested full-doc sweep) Repo ref: main @ post f6650d0 (Tailscale ACL sync green) Published site: hldocs-c0acdec9.pages.dev

Executive summary¶

Area	Verdict	Notes
Phase 7 core (ZBF, DSM/Tailscale, AdGuard cutover, ACL GitOps)	Documented + aligned	Progress tables and Owner TODO updated in this pass
PiHole LXC 104 decom	Open — documented	Intentionally pending owner soak
Phase 7R (HomePod, Aqara, TP-Link WiFi)	Open — documented	ZBF printer rule done; AirPlay still broken
Phase 6 backup-client deploy	Open — documented	`backup.sops.yaml` commit still on Owner TODO
Per-host doc stubs (18 hosts)	Known gap	Inventory metadata only; index table is nav
Per-service mkdocs pages	Partial	AdGuard only; others via `services/*/README.md`

Live validation (2026-06-19)¶

Commands run from operator workstation via SSH unless noted.

DNS — AdGuard on infra-services¶

Check	Command / method	Result
Container running	`docker ps` on `192.168.6.17`	`adguard` container up
Public recursion	`dig @192.168.6.17 google.com +short`	`192.178.164.101` (A record)
Inventory rewrite	`dig @192.168.6.17 infra-services.lab.local +short`	`192.168.6.17`
Owner cutover	UDM WAN + DHCP → `.17` (owner confirmed 2026-06-18 session)	Pass — saltierpoop + stub resolver verified in session

Tailscale — Phase 7 managed hosts¶

Host	Tailscale name	IP	Tag	Join method
infra-services	infra-services	100.117.203.76	tag:server	Ansible + subnet router `192.168.6.0/24`
prox	proxbox-cube	100.97.134.65	tag:server	Ansible from WSL (root SSH; no ansible-pull bootstrap)
saltierpoop	saltierpoop	100.86.38.77	tag:server	Ansible
whrrr	whrrr	100.71.93.130	tag:nas	DSM package (manual)

Not joined (Phase 7 optional): haos, recordurbate, ubuncap.

Off-LAN access (owner phone test, cellular)¶

Test	Target	Result
A — DSM direct tailnet	`https://100.71.93.130:5001`	Pass
B — Subnet routing	`https://192.168.6.17` (cert warn → 404)	Pass (Traefik reached)
C — DNS via hostname	`*.lab.local` in Safari	Expected fail (no Tailscale DNS config)

ACL GitOps¶

Check	Result
GitHub secrets `TS_API_KEY`, `TS_TAILNET`	Owner added 2026-06-19
Workflow	Run 27811413868 — success
Fixes applied	`action: apply` on gitops-pusher; removed `"comment"` keys from `acl.json`
Manual trigger	`workflow_dispatch` added to `.github/workflows/tailscale-acl.yml`

Repo / CI validation¶

Check	Command	Result (2026-06-19)
mkdocs strict build	`uv run mkdocs build --strict`	See § Build log below
mkdocs nav vs files	Manual cross-check + this audit	All nav paths resolve; see § Nav gaps
Stale Phase 7 language	Grep + manual read	Fixed in files listed in § Updates applied
Owner TODO table	`README.md`	Updated statuses for completed Phase 7 items

Build log¶

$ uv run mkdocs build --strict
INFO    -  Building documentation to directory: .../site
INFO    -  Documentation built in 0.85 seconds
Exit code: 0

Strict build passed (2026-06-19). INFO lines list host pages not in nav (by design — see § Nav gaps). Pre-existing anchor warnings on older journal links; new links use verified permalinks.

Documentation inventory¶

mkdocs site (`docs/` + `mkdocs.yml`)¶

Section	Files on disk	In nav	Coverage
Architecture	11	8 (+ diagram via index link)	Live network/firewall + design docs
Hosts	21 + index	2 (+ full index table)	Stubs: 18 hosts — metadata only
Services	2 + index	AdGuard	Other stacks: `services/*/README.md`
Appliances	12 + index	11 (haos added this pass)	whrrr partial; most stubs
Runbooks	17 + index	All listed	Includes new doc-validation runbook
Journal	3 entries + index	All	2026-06-17 + 2026-06-19 check-in + this file
Security	security-register.md	Yes	SEC-007 ACL sync closed this pass

Operator READMEs (not all in mkdocs)¶

Path	Matches live?
`services/adguard/README.md`	Yes — cutover notes aligned
`services/traefik/README.md`	Yes
`services/monitoring/README.md`	Yes
`services/komodo/README.md`	Yes
`infra/tailscale/README.md`	Yes — gitops-pusher caveats documented
`secrets/tailscale/README.md`	Yes

Historical / baseline docs (do not rewrite — label only)¶

Doc	Role
`docs/runbooks/network-observations-2026-06-03.md`	Pre-cutover scan
`docs/architecture/network-live.md` §3a	2026-06-03 DNS baseline
`docs/architecture/lab-audit.md`	Phase 0.5 snapshot
`docs/runbooks/phase-7r-audit-questionnaire.md` §4	Q4 answers superseded 2026-06-18 observations

Nav gaps (acceptable)¶

File	In nav?	Rationale
`architecture/network-diagram.md`	Linked from architecture index	Generated; optional nav entry
`architecture/proxmox-consolidation.md`	Linked from README TODO	Future phase
19 host pages	Index table only	Avoid 21-item nav; expand on demand
Traefik, Grafana, …	Repo README only	Komodo-managed; AdGuard is special (DNS)

Known documentation debt (tracked)¶

ID	Item	Owner action
DOC-001	Host pages with bare `TODO: Document this host`	Closed 2026-06-19 — all 21 hosts have inventory-backed pages
DOC-002	11 appliance stubs	Same
DOC-003	PiHole decom — update network-live §4 when LXC 104 gone	After soak
DOC-004	`phase-7r-audit-questionnaire.md` §4 historical answers	Superseded banner added
DOC-005	Phase 6 backup-client + committed `backup.sops.yaml`	README Owner TODO
DOC-006	prox ansible-pull bootstrap (`someone` user, `/var/lib/ansible-pull`)	Optional hardening

Updates applied (this audit)¶

File	Change
`README.md`	Owner TODO Phase 7 statuses
`docs/journal/2026-06-19-checkin.md`	New milestone check-in
`docs/journal/index.md`	Index row
`docs/runbooks/phase-7-owner-actions.md`	Progress + Tailscale checklist
`docs/services/adguard.md`	Cutover complete; PiHole soak pending
`docs/architecture/network.md`	DNS section current state
`docs/architecture/network-live.md`	Tip banner + §3 status table
`docs/security-register.md`	SEC-007 closed; SEC-008 wording; closed findings
`docs/architecture/index.md`	No longer "will be populated"
`docs/index.md`	Doc maturity note
`docs/hosts/prox.md`	Operator doc (was stub)
`docs/runbooks/documentation-validation.md`	Repeatable procedure
`docs/runbooks/index.md`	Link new runbook
`docs/runbooks/phase-7r-audit-questionnaire.md`	§4 superseded notice
`docs/runbooks/phase-7r-zbf-remediation.md`	Next cohort updated
`mkdocs.yml`	haos, network diagram, validation runbook, journal entries

Sign-off checklist¶

Use before closing a doc audit:

[ ] Owner TODO matches reality (no stale ✅/⬛ on Phase 7 done items)
[ ] phase-7-owner-actions.md progress table dated
[ ] AdGuard / network docs say cutover done, PiHole decom pending if true
[ ] SEC register reflects closed items with date
[ ] Journal index has entry for the audit date
[ ] uv run mkdocs build --strict passes
[ ] Deploy Docs workflow green on main

Next scheduled validation: after PiHole LXC 104 decom, or quarterly — whichever comes first.