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.