Add multi-repo discovery scan orchestration

docs/repo-reality-scanner.md

@@ -210,6 +210,54 @@ Failures do not corrupt the scan. Missing catalogs become
 `connector_failed` artifacts, and future remote connectors should use
 `connector_rate_limited` when backoff is required.
 
+## Multi-Repo Orchestration
+
+Known local repos can be scanned from the same onboarding manifest used by
+`registry sync-manifest`:
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --dry-run \
+  --output-dir .fabric-discovery
+```
+
+The command isolates each repo. A missing path, invalid previous snapshot, or
+registry write failure is reported for that repo without aborting the rest of
+the run. The summary includes repo counts for scanned, changed, retired,
+conflicted, LLM skipped, LLM failed, ingested, accepted, and errors so it can be
+copied into State Hub progress notes or future automation output.
+
+Useful controls:
+
+- `--repo-slug <slug>` can be repeated to scan an allowlist.
+- `--profile <name>` tags the scan profile and output filename.
+- `--previous-dir <dir>` reconciles each repo against
+  `<slug>-<profile>.discovery.json` from an earlier run.
+- `--llm` enables LLM-assisted extraction; `--deterministic-only` forces the
+  offline rule path.
+- `--llm-max-runs <n>` caps how many repos may attempt LLM extraction in one
+  orchestration run, while `--llm-max-tokens` remains the per-repo request cap.
+- `--connector local-fabric-registry` attaches manifest-derived registry facts
+  to every repo scan.
+- `--ingest` stores discovery snapshots in the registry; `--accept` then
+  projects accepted candidates into graph snapshots. `--dry-run` suppresses
+  registry writes even when those flags are present.
+
+Example review cycle:
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --repo-slug railiance-fabric \
+  --previous-dir .fabric-discovery \
+  --output-dir .fabric-discovery \
+  --connector local-fabric-registry \
+  --dry-run
+```
+
+After review, rerun with `--ingest` to store the snapshots. Add `--accept` only
+when candidates marked `review_state: accepted` should be projected into the
+registry graph.
+
 ## Identity
 
 Identity is the main safety boundary. The scanner must not append guesses on