feat: establish sbom nexus extraction slice

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a028f0-a42f-7582-89a8-ebaad7343834

docs/operator-guide.md

@@ -0,0 +1,65 @@
+# Operator guide
+
+## Run locally
+
+```bash
+make install
+make run
+```
+
+The API defaults to `127.0.0.1:8010` and `./sbom-nexus.db`. Set
+`SBOM_NEXUS_DATABASE_PATH` to an explicit durable location for non-development
+use.
+
+## Register and ingest a repository
+
+```bash
+curl -X PUT http://127.0.0.1:8010/repositories/example \
+  -H 'Content-Type: application/json' \
+  -d '{"checkout_path":"/srv/repos/example","active":true}'
+
+curl -X POST http://127.0.0.1:8010/sbom/example/ingest
+```
+
+The ingest response is terminal: `ingested`, or `skipped` with one of
+`no-checkout`, `no-manifest`, or `ingest-error`. A skip advances queue fairness
+but does not advance `last_success_at`.
+
+## Inspect catch-up
+
+```bash
+curl -s 'http://127.0.0.1:8010/sbom/catch-up?limit=3' | python3 -m json.tool
+```
+
+The default stale threshold is 30 days. Override it globally with
+`SBOM_NEXUS_STALE_DAYS` or per query with `stale_days` during controlled
+operation.
+
+## Import State Hub history
+
+Run a read-only preview first:
+
+```bash
+uv run python scripts/import_state_hub.py --dry-run
+```
+
+Then run against a backed-up Nexus database:
+
+```bash
+uv run python scripts/import_state_hub.py \
+  --source-url http://127.0.0.1:8000 \
+  --target-url http://127.0.0.1:8010
+```
+
+Imports are idempotent on the State Hub snapshot UUID. Before cutover, compare
+the source/target repository, snapshot, and entry counts described in the
+extraction review. The current script reports counts but is not yet the complete
+production reconciliation gate.
+
+## Current production limitations
+
+- The extraction store is SQLite and intended for local/single-node operation.
+- Authentication and authorization are not yet integrated.
+- Structured operational metrics, PostgreSQL migrations, backup/restore proof,
+  and retention policy are required before authority cutover.
+- State Hub and Repo Manager callers have not yet been retargeted.