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 — CLOSED (2026-06-13). Verified on the live bootstrap-managed guest 9201: the felhom-controller-data volume mounts at /opt/docker/felhom-controller, data_dir = /opt/docker/felhom-controller/data, and metrics.db lives there — so the hardcoded metricsDBPath (main.go:189) coincides with the volume-backed data_dir and metrics persist correctly. Residual (low-priority backlog, not a live bug): the path is hardcoded rather than derived from cfg.Paths.DataDir, so it would diverge if data_dir were ever reconfigured. Documented in the storage doc.
3. onlyoffice:nextcloud internals — CLOSED (2026-06-13). Read internal/integrations/onlyoffice_nextcloud.go; documented the full occ command sequence (install/enable + DocumentServerUrl/InternalUrl/jwt_secret/ StorageUrl + trusted_domains; Revoke = app:disable) in auth-hub-sync-integrations.md.
4. selfUpdateAuthMiddleware (API auth wrapper for the hub-callback /api/selfupdate|config|geo routes) referenced but its implementation not read in depth. (Still open.)
5. Agent/platform/hub design docs (architecture/01,03,04,05, proxmox-platform.md) are explicit design drafts. PARTIALLY CLOSED: 05-hub-architecture.md's stale "felhom-hub v0.6.3" corrected to v0.11.0 (with a design-draft note). 01,03,04 + proxmox-platform.md still reference older precedent and remain design-drafts — full grounding against agent v0.30.0 / hub v0.11.0 is the recommended next docs slice (the top index already records current versions).
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.