felhom.eu/documentation/REORG-NOTES-2026-06-13.md

Documentation reorg + refresh — 2026-06-13

Rationale, inventory of changes, what was verified, and the doc-gaps left for review. Part of the audit-fix + docs-centralize session (controller v0.59.0; agent v0.29.1; hub v0.11.0).

Goal

Give the controller a documentation home under felhom.eu/documentation/ as thorough as the agent/platform/hub already have, and ground everything in current code (not memory or stale repo-local docs — the controller's own controller/README.md banner referenced v0.45 while live was v0.58). Centralize so there is one published-docs home; keep per-repo operational working files in their repos.

Structure chosen (and why)

documentation/
  README.md                      # NEW — top-level index across controller/agent/platform/hub/audits/tests
  controller/                    # NEW subtree — the controller, mirroring the agent's depth
    README.md                    #   controller docs index + overview
    module-map.md                #   current per-package map (supersedes architecture/02 planning map)
    deploy-and-stack-lifecycle.md
    backup-architecture.md
    storage-monitoring-metrics.md
    auth-hub-sync-integrations.md
  audits/                        # NEW — authoritative remediation record
    deep-sweep-2026-06-13.md     #   (from controller audit/2026-06-13-deep-sweep, + status header)
    bughunt-reconcile-2026-06-13.md
  architecture/ 01..05, _reviews # unchanged (agent/platform/hub design docs)
  proxmox-platform.md            # unchanged
  tests/                         # unchanged (spike findings)

Why this shape: the agent/platform/hub already live under architecture/ as numbered design docs; the controller had no central home (its prose lived in the repo README, stale). Rather than renumber the existing set, I added a sibling controller/ subtree (feature-doc style, like the agent's areas) and a top-level README.md index that ties all four components together. The four controller feature docs are split by area (deploy, backup, storage/monitoring, auth/hub-glue) so each maps to a coherent set of packages and can be maintained independently.

What was created / changed

• Created documentation/README.md (top index), documentation/controller/ (5 files), documentation/audits/ (2 records). All additive.
• Superseded, not deleted: architecture/02-controller-module-map.md (v0.33 planning map) is kept for history; controller/module-map.md is the live map and links back to it. Used additive cross-links rather than git mv because the old doc is a planning artifact with distinct value (the KEEP/PORT/DELETE rationale), not a stale copy of the new one.
• controller/README.md (controller repo): an authoritative banner was prepended — version bumped to v0.59.0, a "documentation has moved" pointer to documentation/controller/, the bootstrap-managed deploy note, and a marker that the body is retained legacy reference. The 1987-line body was NOT rewritten this session (safety over completeness — a full unattended rewrite risked garbling operational/build detail). Fully slimming the body to a pure quickstart is a deferred follow-up; until then the banner makes the central docs authoritative and warns the body may lag.
• BUGHUNT.md (controller repo): added a reconciliation banner (H10 fixed, pointer to the reconcile record); original content preserved.
• CONTEXT.md (controller repo): banner-and-below refreshed to v0.59.0 state.
• Removed the accidental committed artifact controller/mnt/user-data/outputs/felhom-controller/ (a stale duplicate of the README under a Claude-sandbox output path; see "Tidy" below).

What each major controller claim was verified against

Each of the four feature docs was drafted by reading the actual current source and carries an inline content grounded in these packages (the drafting captured a per-doc verification ledger; representative anchors):

• deploy-and-stack-lifecycle: internal/stacks/deploy.go (AppConfig:98, H1 check-and-set:122-139, CTRL-T2-1 transitional deployed:false:~295-336 + success flip in runComposeDeploy, H10 fail-closed in SaveAppConfig), manager.go (Stack/ContainerState, up-d-not-restart), delete.go (H2 guards, protected enforcement), infra.go (EnsureBaseStack TryLock + filebrowser-preserve), healthprobe.go.
• backup-architecture: internal/appbackup/dbdump.go (docker-ps discovery, H8 Sync+Close-before- rename), paths.go/backup.go (GetAppDrivePath systemDataPath fallback — C3 moot), recovery_unit.go (secret-free unit), restore_unit.go (fail-closed data-key gate), tier2.go (off-drive rsync + rootfs-headroom guard), quiesce/quiesce.go, agentapi/client.go (whole-guest backup is the agent's).
• storage-monitoring-metrics: internal/agentapi/client.go (DiskInfo, leaf-pin), web/agent_disk_handlers.go
  • storage_handlers.go (thin proxies, 409 on agent refusal), system/dockervol.go (reserve floor max(5GB,10%), HTTP 507 deploy gate), metrics/store.go (WAL verified), metrics/collector.go (cancellable ctx), monitor/healthcheck.go (watchdog/pinger gone).
• auth-hub-sync-integrations: web/auth.go+csrf.go (bcrypt, cookie flags, demo open-mode, XFF rate-limit), setup/+bootstrap/ (NeedsSetup, bootstrap.json v2), report/+notify/ (zero-knowledge hub push), sync/sync.go (never overwrites app.yaml), integrations/, cloudflare/waf.go ([felhom-geo]), selfupdate/updater.go (pinned tags, never :latest), assets/syncer.go.

Doc-gaps / uncertainties left for review (per the cardinal rule — flagged, not guessed)

1. Daily volume-dump consistency: DumpAppVolumesSafe (stop→dump→restart) exists, but whether the daily scheduled path calls it or the unsafe DumpAppVolumes, and the exact volume-tar trigger on the daily cadence, was not fully traced from main.go. Backup doc describes volume tars without asserting live-dump consistency. (Trace cmd/controller/main.go schedule wiring next.)
2. metricsDBPath hardcoded to /opt/docker/felhom-controller/data/metrics.db in main.go even on the bootstrap-managed guest (no compose). Documented as-is; whether that path is correct under the golden/bootstrap data volume was not assessed.
3. onlyoffice:nextcloud integration internals not opened (only confirmed registered + occ-based); documented at one-line depth.
4. selfUpdateAuthMiddleware (API auth wrapper for the hub-callback /api/selfupdate|config|geo routes) referenced but its implementation not read in depth.
5. Agent/platform/hub design docs (architecture/01,03,04,05, proxmox-platform.md) are explicit design drafts. I did NOT rewrite them — a half-verified refresh risks regressing decision content. Known drift to fix in a dedicated pass: 05-hub-architecture.md prose still says "felhom-hub v0.6.3" (live is v0.11.0); 02/03 reference v0.33 controller precedent. The top index records the current versions; full grounding of these against agent v0.29.1 / hub v0.11.0 is the recommended next docs slice.
6. Front-end (templates) deploy progress markup lives in web/templates, documented only via the in-memory state it polls, not the template/endpoint markup.

Tidy

• controller/mnt/user-data/outputs/felhom-controller/{README.md,assets/README.md} was a tracked accidental commit (a stale 283-line duplicate README under a Claude sandbox output path, from the initial added controller commit). Removed via git rm — clearly safe (stale duplicate, obviously accidental path). Noted here for the record.