Add discovery registry review flow

docs/registry-api.md

@@ -29,6 +29,38 @@ GET  /repositories/{repo_slug}/snapshots/diff
 Snapshot ingestion accepts a `FabricGraphExport` under `graph` plus `commit`
 and optional `generated_at`.
 
+## Discovery Snapshots
+
+```text
+POST /repositories/{repo_slug}/discovery-snapshots
+GET  /repositories/{repo_slug}/discovery-snapshots
+GET  /repositories/{repo_slug}/discovery-snapshots/latest
+GET  /repositories/{repo_slug}/discovery-snapshots/diff
+GET  /repositories/{repo_slug}/discovery-snapshots/{snapshot_id}
+POST /repositories/{repo_slug}/discovery-snapshots/{snapshot_id}/accept
+```
+
+Discovery ingestion accepts a `FabricDiscoverySnapshot`. Snapshots are stored by
+repo, commit, and scan profile for dry-run review. Discovery diffs include
+candidate additions, removals, changes, confidence changes, reconciliation
+conflicts, and scoped retirements.
+
+Acceptance projects only explicitly accepted discovery candidates into a normal
+`FabricGraphExport` snapshot. Existing graph nodes are preserved, so repo-owned
+declarations are not overwritten by discovery output. Projected nodes carry
+discovery provenance, review state, confidence, and source anchors in their
+attributes; graph explorer exports surface that metadata.
+
+CLI helpers:
+
+```bash
+railiance-fabric registry ingest-discovery discovery.json \
+  --repo-slug railiance-fabric
+
+railiance-fabric registry accept-discovery railiance-fabric 12 \
+  --accepted-key discovery:railiance-fabric:service-declaration:example
+```
+
 ## Graph Queries
 
 ```text

docs/repo-reality-scanner.md

@@ -131,6 +131,39 @@ is present in the current scan and has `mode: replacement`. Missing candidates
 from additive scopes, such as broad LLM evidence bundles, are left alone.
 Existing tombstones are preserved so repeated scans can explain graph drift.
 
+## Registry Review And Acceptance
+
+Discovery snapshots can be stored in the Fabric registry for review:
+
+```bash
+railiance-fabric scan . \
+  --repo-slug railiance-fabric \
+  --previous-snapshot previous-discovery.json \
+  --output discovery.json
+
+railiance-fabric registry ingest-discovery discovery.json \
+  --repo-slug railiance-fabric
+```
+
+The registry keeps discovery snapshots separately from accepted graph snapshots
+by repo, commit, and scan profile. It exposes latest/list/diff API routes so a
+dry run can be reviewed without changing the accepted graph.
+
+Accepted discovery can be projected into a normal graph snapshot:
+
+```bash
+railiance-fabric registry accept-discovery railiance-fabric 12 \
+  --accepted-key discovery:railiance-fabric:service-declaration:example
+```
+
+By default, the accept path only projects candidates already marked
+`review_state: accepted`. Passing `--accepted-key` explicitly includes selected
+candidate stable keys. Existing accepted graph nodes win over discovery nodes
+with the same graph id, so repo-owned declarations are preserved. Projected
+nodes carry discovery stable key, origin, review state, confidence, provenance,
+and source anchors in graph attributes; the graph explorer payload exposes
+those fields for review.
+
 ## Connector Follow-Up
 
 Connector follow-up is explicit and separated from repo-local extraction: