felhom.eu/REPORT.md

# felhom.eu — task reports

> **Overwrite** this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in [hub/CHANGELOG.md](hub/CHANGELOG.md); the scripts history lives in [scripts/CHANGELOG.md](scripts/CHANGELOG.md).

---

# REPORT — docs: REUSE.md introduced across all four felhom repos (consolidated)

**Date:** 2026-07-03 · **Class:** docs-only (no code change, no version bumps, no builds, no deploys)
**Deliverable:** a per-repo `REUSE.md` reuse map (canonical helpers / patterns / traps / seams /
extension points / known duplication), code-verified at file+symbol, plus `scripts/reuse_refs_check.py`
as the staleness gate, plus CLAUDE.md maintenance hooks.

## 1. Baselines used (all matched the task's expected hashes; trees clean, pulled fresh)

| Repo | `main` @ baseline | State |
|---|---|---|
| felhom-controller | `d0c70a7da6f4060422a545cea2396f9df5f7d61f` | v0.98.3 |
| felhom-agent | `0db09bf34fe2eff4b80ac77ed19afa18aef7675f` | v0.61.0 |
| felhom.eu | `b0de6b34f61fef2e14807fba2c6176b888dc3327` | hub v0.30.1 |
| app-catalog-felhom.eu | `bb81cd414afcb89e28ac60f405133f40195e6c43` | n/a |

## 2. Files created/modified per repo

- **felhom-controller:** `REUSE.md` (new, 210 lines); `CLAUDE.md` (+2 hook lines); `CHANGELOG.md`
  (docs entry); `CONTEXT.md` (note); `REPORT.md` (overwritten).
- **felhom-agent:** `REUSE.md` (new, 160 lines); `CLAUDE.md` (+2 hook lines); `CHANGELOG.md`;
  `CONTEXT.md`; `REPORT.md`.
- **felhom.eu:** `REUSE.md` (new, 151 lines — hub + website + scripts + manifests);
  `scripts/reuse_refs_check.py` (new gate); `CLAUDE.md` (+2 hook lines); `hub/CHANGELOG.md` +
  `scripts/CHANGELOG.md` (docs entries); `CONTEXT.md` (new, minimal — repo had none); `REPORT.md`
  (this file).
- **app-catalog-felhom.eu:** `REUSE.md` (new, 58 lines, light §2/§5 variant per spec); `CLAUDE.md`
  (new, minimal — repo had none; full CLAUDE.md is a separate task); `CHANGELOG.md`; `CONTEXT.md`
  (new, minimal); `REPORT.md`.

## 3. Commits pushed to `main` (one per repo)

| Repo | Commit |
|---|---|
| felhom-controller | `eda33400da0fd6a3b80271c44df24a177f7a444a` |
| felhom-agent | `2a024b603973e79a0c84d6847a7cde0898091c61` |
| app-catalog-felhom.eu | `c5a3d1b15b71103a3d1da217f1ff5a834857375c` |
| felhom.eu | the commit carrying this REPORT (HEAD of `main` after this push) |

## 4. Per-repo sweep counts (evidence of depth)

| Repo | funcs scanned (non-test) | §1 rows | §3 traps | §6 duplications |
|---|---|---|---|---|
| felhom-controller | 1174 | 62 | 8 | 12 |
| felhom-agent | 702 | 48 | 10 | 7 |
| felhom.eu (hub Go) | 297 | 34 | 8 | 5 |
| app-catalog | 53 apps scanned | 0 (by design) | 3 | 6 |

Trap sweeps ran mechanically per §Method (`--delete`, `wipefs`, `mkfs`, `os.RemoveAll`, `rm -rf`,
`sfdisk`, `dd `, `Format`, `Wipe`) in every repo; each hit classified as guarded-canonical (§1, guard
named) or §3 trap. Known traps (rsyncMirror `--delete`, gokapi entrypoint, AGENT-001 TOCTOU shape,
allowedEventTypes 400) were independently rediscovered from code.

## 5. reuse_refs_check.py output (final, all four repos)

```
OK   [felhom-controller]: 65 cited paths, all exist
OK   [felhom-agent]: 57 cited paths, all exist
OK   [felhom.eu]: 30 cited paths, all exist
OK   [app-catalog-felhom.eu]: 10 cited paths, all exist
```

(The gate earned its keep during authoring: it caught the controller map citing
`scripts/{template_id_gate,emoji_gate}.py` — the real location is `controller/scripts/` — fixed
before commit.)

## 6. Observations — doc↔code drift & findings (recorded, NOT acted on)

**Worth operator attention:**
- **hub severity-coercion gotcha (NEW finding):** the remembered "dispatcher drops critical" issue is
  FIXED in code (`severityNotifies` routes warning/error/critical since v0.24.0), **but**
  `handleEvent` (hub/internal/api/handler.go) coerces any severity outside {info,warning,error} —
  including `"critical"` — to `"info"` at ingest, so a controller-POSTed critical event never
  notifies. Hub-internal events bypass this. Recorded in felhom.eu REUSE.md §3.
- **Committed secrets:** `manifests/felhom.secret.yaml` still carries inline `stringData`
  credentials (healthchecks superuser pw + Django secret — not deployed; umami APP_SECRET +
  POSTGRES_PASSWORD — deployed), unlike the de-gitted Resend key. Recorded as a §3 trap; rotation/
  de-git is an operator follow-up.

**Stale docs (each a separate refresh task):**
- `felhom-agent/CLAUDE.md` says "Current: v0.31.0" and omits ~8 live packages (localapi, signedjobs,
  escrow, capability, guesthook, lanresolver, desired, provision).
- `felhom.eu/CLAUDE.md` "Hub — current state (v0.7.x)" is ~23 minor versions stale (live 0.30.1).
- `felhom-controller/CLAUDE.md` layout lists ~7 of ~30 internal packages; bare-metal deploy steps
  superseded (already flagged in-file).
- app-catalog `README.md`: phantom `filebrowser/` template, missing `recipe-importer/`, field-type
  table omits `subdomain`/`secret_input`, smtp_mapping list undercounts (2 listed, 6 real).

**Duplication highlights (full lists in each REUSE.md §6):** controller atomic-write ×4 (+1 inline,
two with deliberate non-atomic bind-mount fallback), dir-size ×6, JSON writers ×5/3 envelopes;
agent lsblk parsers ×2, atomic JSON store ×3, run() helper ×4, plus the acknowledged
antiRetarget↔WipeExecutor mirror; hub Resend sender ×2 + Hungarian formatter ×2 (frozen legacy
path) and semver-compare ×2 with different failure semantics; agent dead config knobs
`Binaries.MkfsExt4/MkfsXfs` (never executed — wrapper paths are hardcoded).

## 7. Maintenance hooks now active

Every repo's CLAUDE.md: "See `REUSE.md` before writing new code" + "update REUSE.md in the SAME
commit that adds/changes/deprecates a shared helper or pattern". Staleness gate:
`python scripts/reuse_refs_check.py <repo-root> [...]` (run from felhom.eu). Reviewer-side: symbols
spot-verified at file:line (line numbers in the maps are landmarks only).