Skip to content

Documentation Refactor Report - June 9, 2026

Summary

The site was reorganized into an operational reference centered on current infrastructure, physical hardware, active services, and runbooks. Runtime facts were refreshed from read-only Proxmox and Docker queries on June 9, 2026.

Metric Result
Documentation pages after refactor 56
Pages created 35
Existing pages modified 20
Obsolete or audit-only pages removed 31
Internal link references after refactor 377
Local image references 17
Repository assets 53

Pages Modified

Core pages were rewritten or expanded for:

  • Home, purpose, audience, scope, and maintenance expectations
  • Infrastructure overview, index, network, Proxmox, Docker, and pfSense
  • Hardware inventory and all existing physical-device records
  • Backup, runbook, and publishing cross-references

Pages Created

  • Infrastructure dependency map, VM inventory, LXC inventory, cloud-service register, and retired-system register
  • Dedicated pages for active platform, database, application, DNS, and website services
  • Dedicated Starlink Gen 3 and unidentified Wi-Fi 6 router inventory pages
  • Configuration redaction and documentation maintenance procedures
  • Repository-local documentation QA script

The navigation now links systems by category. The resulting site contains 377 internal link references. First references in newly written operational pages link to dedicated pages, and Related Systems sections provide backlinks between infrastructure, hardware, services, storage, and operations.

Images Added or Reused

Existing local assets were reused for:

  • Network topology
  • Dell OptiPlex 7040
  • Synology RS816
  • HP 290 G1 MT
  • Huawei HG8245H
  • Proxmox, pfSense, Docker, Traefik, Forgejo, Drone, Nginx, Portainer, MariaDB, MongoDB, and Vaultwarden

Images include alt text and captions where they document physical equipment or architecture. The malformed hg8245h-01.webp filename was normalized to hg8245h-01.webp.

Audit Content Removed

The audit index, discovery log, task tracker, audit inventories, and audit-specific redaction pages were removed. Durable operational facts were migrated into permanent inventory, service, and operations pages. Redaction procedures now live under Operations.

Current Runtime Reconciliation

  • 25 running Docker containers were documented.
  • kestra, n8n, and wordpress were removed from the active inventory because they were absent on June 9, 2026.
  • appsmith, meshcentral, dashboard, and noticeboard remain active but have missing Compose source.
  • kh3-dev-site has ambiguous deployment ownership between its own project label and the Forgejo runner.

Outstanding Documentation Gaps

  • Confirm physical location, rack/shelf position, warranty, purchase date, UPS feed, and asset tag for most devices.
  • Verify the Synology chassis model, serial number, DSM version, RAID health alerts, and snapshot policy.
  • Identify the active Wi-Fi 6 router and map both WAN providers to pfSense WAN1/WAN2.
  • Record switch management, port/VLAN map, and current deployment status.
  • Recover missing Compose files and assign service owners for Appsmith, MeshCentral, Dashboard, Noticeboard, Receipt App, and website workloads.
  • Verify the DNS LXC installation method and exact Pi-hole/Cloudflared configuration paths.
  • Define backup schedules, retention, owners, and recurring restore tests.
  • Confirm the purpose and disposition of stopped Proxmox guests.

Quality Assurance

The repository is checked with:

python3 scripts/docs_qa.py
mkdocs build --strict
git diff --check

The QA script validates non-empty pages, H1 titles, local links, local images, duplicate titles, and malformed asset filenames.

Final validation completed successfully:

  • python3 scripts/docs_qa.py: 56 pages and 53 assets passed
  • mkdocs build --strict: completed successfully
  • git diff --check: no whitespace errors