REUSE-WP-0019-T06: hub freshness monitoring, docs, close workplan

reuse_surface/stats.py: _hub_summary() now reports composed_at, stale,
age_days, freshness_threshold_days (REUSE_SURFACE_FRESHNESS_DAYS env,
default 7), and a computed stale_warning. New hub_client.hub_federated()
backs it. format_stats_markdown surfaces a STALE marker when triggered.

.forgejo/workflows/ci.yml: new informational (non-failing) hub freshness
check against the live production hub on every push -- prints a
:⚠️: annotation when stale, never fails the build.

docs/RegistryFederation.md: new section tying together the webhook (T02),
scheduled fallback (T03), and freshness visibility (T06) into one
explanation. docs/deploy/reuse-kubernetes.md: updated for the T03 Forgejo
migration and the now-automated image.yaml build; image promotion
checklist updated for the known /health ingress bug (verify via
/v1/repos or /v1/federated instead).

14 new pytest cases, 173 total pass. Live-verified against production:
reuse-surface stats correctly showed composed_at/age_days for the real
federated index. Separately discovered and confirmed (via a live signed
webhook test) that reuse-surface-env moving to ExternalSecret/OpenBao
custody (railiance-apps commit 706f6c7, found while updating these docs)
did not break the T02/T03 webhook -- the synced value still matches what
the hub actually uses.

REUSE-WP-0019 is now fully complete (T01-T06). SCOPE.md and
docs/IntentScopeGapAnalysis.md updated to reflect closure.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/RegistryFederation.md

@@ -262,6 +262,32 @@ curl -fsS "$REUSE_SURFACE_URL/v1/federated" | jq '.capabilities | length'
 Read endpoints are public; writes require `REUSE_SURFACE_TOKEN` (Bearer). API
 spec: `specs/FederationHubAPI.md`.
 
+### Automatic recompose and freshness (REUSE-WP-0019-T02/T03/T06)
+
+The hub recomposes automatically rather than waiting for a manual
+`reuse-surface federation compose --refresh`:
+
+- **Forgejo org webhook** (primary): a single org-level webhook on `coulomb`
+  fires on every push, HMAC-signed. `POST /v1/webhooks/forgejo` verifies the
+  signature, checks whether the push touched `registry/indexes/`, and — only
+  if so — recomposes. It never parses pushed file content, only paths.
+- **Scheduled fallback**: `.forgejo/workflows/recompose-fallback.yaml` in
+  this repo calls `POST /v1/federated/compose` (token-auth) every 6 hours,
+  in case a webhook delivery is ever missed.
+- **Freshness visibility**: `GET /v1/federated` carries `composed_at`
+  (timestamp of the last *forced* recompose) and `stale` (set by the
+  webhook, cleared on the next successful recompose). `reuse-surface stats`
+  surfaces both plus an `age_days`/`stale_warning` computed against a
+  threshold (`REUSE_SURFACE_FRESHNESS_DAYS`, default 7 days) — this repo's
+  own CI runs an informational (non-failing) freshness check on every push.
+
+Setting up the org webhook or rotating its secret is an operator action on
+the Forgejo instance and the cluster Secret, not something `reuse-surface`
+itself automates — see `railiance-apps/docs/reuse-surface-on-railiance01.md`
+(the authoritative operator runbook) and `docs/deploy/reuse-kubernetes.md`
+for the current secret custody chain (OpenBao → `ExternalSecret` →
+`reuse-surface-env`).
+
 ### Hub vs local `sources.yaml`
 
 | Workflow | When to use |