Close repo reality scanner rollout

docs/repo-reality-scanner.md

@@ -258,6 +258,75 @@ 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.
 
+## Scan Profiles And Review Workflow
+
+The initial profile is `deterministic`, which means repo-local extraction plus
+any explicitly enabled offline connectors. Additional profiles should be named
+for the evidence policy they represent, for example `deterministic-llm-draft`
+or `catalog-followup`. Keep profile names stable because per-repo previous
+snapshots use `<slug>-<profile>.discovery.json`.
+
+Recommended workflow:
+
+1. Run `scan` or `registry scan-manifest` with `--dry-run`.
+2. Reconcile with `--previous-snapshot` or `--previous-dir` when a prior
+   snapshot exists.
+3. Review candidates with `review_state: needs_review`, `status: conflicted`,
+   tombstones, and review artifacts before accepting anything.
+4. Store reviewed output with `registry ingest-discovery`.
+5. Use `registry accept-discovery` or `registry scan-manifest --ingest --accept`
+   only for candidates whose review state is acceptable for projection.
+
+## Failure Modes
+
+Failures are captured close to the evidence source:
+
+- Missing repo paths, invalid manifest entries, unreadable previous snapshots,
+  and registry request failures mark that repo as `status: error` in
+  `scan-manifest` without stopping other repos.
+- Connector failures become review artifacts such as `connector_unavailable` or
+  `connector_failed`.
+- LLM provider failures and malformed model output become `llm_execution_error`
+  or `llm_output_invalid` review artifacts.
+- Low-confidence LLM candidates become `llm_low_confidence` artifacts instead
+  of graph candidates.
+- Possible duplicates are marked as conflicts and left for review instead of
+  being silently merged.
+
+## Rollout Dry Run
+
+The first small local rollout ran on 2026-05-19:
+
+```bash
+railiance-fabric registry scan-manifest registry/local-repos.yaml \
+  --repo-slug repo-scoping \
+  --repo-slug llm-connect \
+  --repo-slug railiance-fabric \
+  --dry-run \
+  --connector local-fabric-registry
+```
+
+Result:
+
+- `repo-scoping`: 18 nodes, 17 edges, 13 attributes
+- `llm-connect`: 5 nodes, 4 edges, 13 attributes
+- `railiance-fabric`: 55 nodes, 63 edges, 13 attributes
+- summary: 3 scanned, 0 changed, 0 retired, 0 conflicted, 3 LLM skipped,
+  0 LLM failed, 0 accepted, 0 errors
+
+Follow-up backlog from this first pass:
+
+- Add a standard discovery snapshot directory, likely `.fabric-discovery/`, so
+  repeated dry-runs can reconcile by default.
+- Add a previous-from-registry option so manifest scans can diff against the
+  latest stored discovery snapshot without exporting JSON first.
+- Expand runtime/deployment extraction beyond local manifests to cover live
+  server and deployment inventory connectors.
+- Add review UI affordances for conflicts, tombstones, and bulk acceptance once
+  enough repos have baseline snapshots.
+- Define privacy and budget defaults before enabling non-mock LLM providers in
+  multi-repo scans.
+
 ## Identity
 
 Identity is the main safety boundary. The scanner must not append guesses on