Implement REUSE-WP-0012 federation scale and intent alignment

Add hub sync and report cohorts CLI commands with pytest coverage, document
sibling index publish contract and hub hardening path, align INTENT layout,
raise external evidence on three registry entries, and close gap priorities
19-23 (priority 18 deferred on sibling index blocks).

docs/RegistryFederation.md

@@ -60,6 +60,56 @@ Sibling repos (`state-hub`, `feature-control`, `identity-canon`) are listed as
 disabled local placeholders until they publish registry indexes. A disabled
 `example-remote` URL source illustrates HTTP federation.
 
+## Index publish contract (domain repos)
+
+Before a sibling repo can register on the hosted hub, it must publish
+`registry/indexes/capabilities.yaml` at a **stable raw HTTP(S) URL** that
+returns **200** with valid YAML (not a redirect to login or HTML).
+
+### Required index fields
+
+| Field | Requirement |
+|---|---|
+| `version` | Integer manifest version |
+| `domain` | Domain slug (e.g. `helix_forge`) |
+| `capabilities[]` | Non-empty or explicitly empty list |
+| Per row: `id`, `name`, `summary`, `vector`, `path` | Match entry front matter |
+
+Entry bodies remain in the source repo; the index is the federation surface.
+
+### Gitea raw URL shape
+
+```text
+https://gitea.coulomb.social/coulomb/<repo>/raw/<branch>/registry/indexes/capabilities.yaml
+```
+
+Use `main` (or the repo's default branch). Verify before registration:
+
+```bash
+curl -fsSI "<raw-url>" | head -n1   # expect HTTP/2 200 or HTTP/1.1 200
+curl -fsS "<raw-url>" | head
+```
+
+### Auth expectations
+
+- **Public indexes:** no auth; hub fetches without credentials.
+- **Private indexes:** set `auth_env` on the hub registration (or local `url`
+  source) to an environment variable holding a Bearer token or full header value.
+  The hub stores `auth_env` / `auth_header` names only — never secret values.
+
+### Registration checklist
+
+1. Merge capability index to the default branch.
+2. Confirm raw URL returns 200 YAML.
+3. `reuse-surface hub register --repo <slug> --url <raw-url> --domain helix_forge`
+4. `curl -fsS "$REUSE_SURFACE_URL/v1/federated" | jq '.capabilities | length'`
+5. Optionally `reuse-surface hub sync --merge` to refresh local `sources.yaml`.
+
+**Current blocks (2026-06-16):** `state-hub`, `feature-control`,
+`identity-canon`, and `shard-wiki` raw URLs return **303** (not published).
+See `history/2026-06-16-hub-registration-blocks.md` for probe evidence and owner
+follow-ups.
+
 ## Compose workflow
 
 ```bash
@@ -122,8 +172,26 @@ spec: `specs/FederationHubAPI.md`.
 | **Local compose** | Offline development, CI with checked-in sources, or hub unavailable |
 
 Local `registry/federation/sources.yaml` remains valid for `reuse-surface
-federation compose`. Optional future: `reuse-surface hub sync` to materialize
-`sources.yaml` from hub state.
+federation compose`. Use `reuse-surface hub sync` to materialize `sources.yaml`
+from hub `GET /v1/repos` state.
+
+### hub sync
+
+```bash
+export REUSE_SURFACE_URL=https://reuse.coulomb.social
+reuse-surface hub sync --dry-run          # preview manifest
+reuse-surface hub sync --merge            # hub URL sources + local index sources
+reuse-surface hub sync                    # replace with hub-enabled registrations
+```
+
+| Flag | Behavior |
+|---|---|
+| `--merge` | Keep local `index` sources whose `repo` slug is not on the hub |
+| `--replace` (default) | Write only hub-enabled registrations as `url` sources |
+| `--output` | Override manifest path (default `registry/federation/sources.yaml`) |
+| `--dry-run` | Print YAML without writing |
+
+After sync, run `reuse-surface federation compose` to verify offline compose.
 
 ## Agent query pattern