# REPORT — docs: REUSE.md introduced (cross-repo reuse map)

**Date:** 2026-07-03 · **Class:** docs-only (no code change, no version bump, no deploy)
**Baseline:** `main` @ `d0c70a7da6f4060422a545cea2396f9df5f7d61f` (v0.98.3)

## What was done

- **`REUSE.md`** created at the repo root (210 lines): the curated reuse map — canonical helpers
  (62 rows across 9 domains), canonical patterns (10), dangerous lookalikes (8), test seams +
  cross-repo edges, extension points, and observed duplication (12 clusters, recorded NOT fixed).
- Sourced from a full code sweep (1174 non-test `func` declarations scanned; call-site counts +
  body reads per candidate; mandatory trap sweep over `--delete`/`os.RemoveAll`/`mkfs`/etc.).
  Every entry cites file + symbol, verified in code — not copied from README/docs.
- **`CLAUDE.md`**: two hook lines added — "See `REUSE.md` before writing new code" (read-first
  pointers) and end-of-session checklist item 7 (update REUSE.md in the same commit as a shared
  helper change). No other CLAUDE.md edits.
- `CHANGELOG.md` entry (no version number) + `CONTEXT.md` note.

## Verification

`python felhom.eu/scripts/reuse_refs_check.py e:/git/felhom-controller` →
`OK [felhom-controller]: 65 cited paths, all exist` (the check caught and fixed one wrong citation:
the template/emoji gate scripts live at `controller/scripts/`, not `scripts/`).

## Notable traps recorded (§3 highlights)

`rsyncMirror` (`--delete`, tier-2 only) vs `rsyncCopy`; raw `os.RemoveAll` vs the
`ProtectedHDDPaths`-gated delete path; fresh `agentapi.New` per request (the v0.74.0 conn-leak
incident); `timeAgo` on string timestamps; `DumpAppVolumes` on a running DB app;
no-timeout `composeExec` for new long-running calls.

## Observations (NOT acted on)

- Atomic-write helper exists ×4 (+1 inline) with differing semantics; two of them have a deliberate
  NON-atomic bind-mount fallback — a convergence candidate needs care.
- `util.TruncateStr` (rune-safe) has 1 caller while the byte-based `stacks.truncateStr` twin is the
  widely used one.
- 5 JSON writers / 3 envelope shapes; 6 dir-size implementations; 2 CSRF implementations
  (intentional but unlabeled). Full list in REUSE.md §6.
- CLAUDE.md "Workspace layout" lists ~7 internal packages; code has ~30. Its bare-metal
  `/opt/docker` deploy steps are superseded by the 9201 bootstrap mechanism (already flagged
  in-file). A CLAUDE.md refresh is a separate task.

Cross-repo summary + full sweep counts: `felhom.eu/REPORT.md`.