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; the scripts history lives in 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).