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/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.