Complete REUSE-WP-0005: registry federation and relation graphs

Add federation manifest and schema, federation compose and graph CLI commands,
relation cycle/reference checks, federated index and Mermaid graph artifacts,
RegistryFederation guide, and CI validation updates.

docs/IntentScopeGapAnalysis.md

@@ -270,13 +270,14 @@ own evidence (e.g. feature-control at R3).
 | 9 | Catalog site | `reuse-surface catalog` → MD + HTML | Closed (WP-0004) |
 | 10 | Overlap detection | `reuse-surface overlaps` | Closed (WP-0004) |
 | 11 | CI validation | `.gitea/workflows/ci.yml` | Closed (WP-0004) |
-| 12 | Registry federation | Cross-repo capability index composition | Open |
+| 12 | Registry federation | `federation compose` + federated index | Closed (WP-0005) |
+| 14 | Graph visualization | `reuse-surface graph` Mermaid output | Closed (WP-0005) |
 
 | Priority | Gap | Suggested outcome |
 |---|---|---|
 | 13 | Interactive catalog | Searchable catalog UI beyond static HTML |
-| 14 | Graph visualization | Capability relation graphs |
-| 15 | Federation | Compose indexes across repositories |
+| 15 | Network federation | Remote index fetch and cross-org sync |
+| 16 | Graph UI | Interactive relation graph explorer |
 
 ---
 
@@ -296,4 +297,5 @@ own evidence (e.g. feature-control at R3).
 |---|---|
 | 2026-06-15 | Initial analysis after REUSE-WP-0002 completion |
 | 2026-06-15 | REUSE-WP-0003 closed priority gaps 1–8; vector updated to D5/A3/C4/R2 |
-| 2026-06-15 | REUSE-WP-0004 closed priorities 9–11 (catalog, overlaps, CI) |
+| 2026-06-15 | REUSE-WP-0004 closed priorities 9–11 (catalog, overlaps, CI) |
+| 2026-06-15 | REUSE-WP-0005 closed priorities 12 and 14 (federation, relation graphs) |

docs/RegistryFederation.md

@@ -0,0 +1,90 @@
+# Registry Federation
+
+**Repository:** `reuse-surface`  
+**Audience:** Architects and agents composing multi-repo capability indexes
+
+---
+
+## Purpose
+
+helix_forge capabilities may be registered in multiple repositories. Federation
+composes capability indexes from configured sources into a single discovery
+surface without silently merging duplicate IDs.
+
+## Manifest
+
+`registry/federation/sources.yaml` lists index sources:
+
+```yaml
+version: 1
+domain: helix_forge
+collision_policy: warn
+sources:
+  - repo: reuse-surface
+    index: registry/indexes/capabilities.yaml
+    enabled: true
+    required: true
+```
+
+Schema: `schemas/federation.schema.yaml`
+
+### Source fields
+
+| Field | Meaning |
+|---|---|
+| `repo` | Source repository slug |
+| `index` | Path to `capabilities.yaml` (repo-relative or `~/...`) |
+| `enabled` | Include this source in compose |
+| `required` | Fail compose if index missing when enabled |
+| `domain` | Optional domain label |
+
+Sibling repos (`state-hub`, `feature-control`, `identity-canon`) are listed as
+disabled placeholders until they publish registry indexes.
+
+## Compose workflow
+
+```bash
+reuse-surface federation compose
+```
+
+Writes `registry/indexes/federated.yaml` with:
+
+- Merged `capabilities` from all enabled sources
+- `source_repo` and `source_index` on every row
+- `collision_policy` and per-source counts
+
+### Collision policy
+
+`warn` (default): duplicate IDs across sources are kept but reported as
+warnings. Consumers must inspect `source_repo` before choosing an entry.
+
+## Agent query pattern
+
+1. Run `reuse-surface federation compose` after manifest or sibling index changes.
+2. Read `registry/indexes/federated.yaml` for cross-repo discovery.
+3. Open `path` in the source repo for full entry detail when local.
+4. Run `reuse-surface graph --check` before relying on relation navigation.
+
+## Relation graphs
+
+```bash
+reuse-surface graph
+reuse-surface graph --check
+reuse-surface graph --stdout
+```
+
+Generates `docs/graph/capability-graph.mmd` from local entry `relations`.
+`--check` reports `depends_on` cycles and broken relation targets against the
+federated ID set.
+
+## CI integration
+
+Gitea CI runs:
+
+```bash
+reuse-surface validate --relations
+reuse-surface federation compose
+```
+
+Warnings on broken relations or missing optional sibling indexes do not fail CI;
+schema validation errors do.

docs/graph/capability-graph.mmd

@@ -0,0 +1,24 @@
+graph LR
+  capability_feature_control_evaluate["capability.feature-control.evaluate<br/>D5 / A4 / C3 / R3"]
+  capability_feature_control_rollout["capability.feature-control.rollout<br/>D4 / A2 / C2 / R1"]
+  capability_identity_subject_resolution["capability.identity.subject-resolution<br/>D3 / A0 / C1 / R0"]
+  capability_identity_vocabulary_canonicalize["capability.identity.vocabulary-canonicalize<br/>D4 / A0 / C2 / R0"]
+  capability_registry_register["capability.registry.register<br/>D3 / A3 / C2 / R2"]
+  capability_statehub_workstream_coordinate["capability.statehub.workstream-coordinate<br/>D4 / A4 / C3 / R2"]
+  capability_registry_register -->|supports| capability_feature_control_evaluate
+  capability_registry_register -->|supports| capability_identity_vocabulary_canonicalize
+  capability_registry_register -->|related_to| capability_registry_validate
+  capability_feature_control_evaluate -->|depends_on| capability_identity_vocabulary_canonicalize
+  capability_feature_control_evaluate -->|supports| capability_registry_register
+  capability_feature_control_evaluate -->|related_to| capability_feature_control_rollout
+  capability_feature_control_evaluate -->|related_to| capability_feature_control_visibility
+  capability_feature_control_rollout -->|depends_on| capability_feature_control_evaluate
+  capability_feature_control_rollout -->|related_to| capability_feature_control_visibility
+  capability_identity_vocabulary_canonicalize -->|supports| capability_feature_control_evaluate
+  capability_identity_vocabulary_canonicalize -->|supports| capability_registry_register
+  capability_identity_vocabulary_canonicalize -->|related_to| capability_identity_subject_resolution
+  capability_identity_subject_resolution -->|depends_on| capability_identity_vocabulary_canonicalize
+  capability_identity_subject_resolution -->|supports| capability_feature_control_evaluate
+  capability_identity_subject_resolution -->|supports| capability_statehub_workstream_coordinate
+  capability_statehub_workstream_coordinate -->|supports| capability_registry_register
+  capability_statehub_workstream_coordinate -->|related_to| capability_statehub_progress_log