feat: prepare postgres sbom cutover

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

docs/operator-guide.md

@@ -7,9 +7,19 @@ 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.
+The API defaults to `127.0.0.1:8010` and `./sbom-nexus.db`. SQLite schema is
+created automatically for local development.
+
+For PostgreSQL, migrate before starting the API:
+
+```bash
+export SBOM_NEXUS_DATABASE_URL='postgresql+psycopg://user:password@host/sbom_nexus'
+make migrate
+make run
+```
+
+PostgreSQL never auto-creates tables unless `SBOM_NEXUS_AUTO_CREATE=1` is set
+explicitly. Normal production operation must use Alembic.
 
 ## Register and ingest a repository
 
@@ -53,13 +63,13 @@ uv run python scripts/import_state_hub.py \
 
 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.
+extraction review. The command fails unless every legacy snapshot id, repository,
+timestamp, entry count, licence group, and direct-production copyleft count
+reconciles.
 
 ## 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.
+- Structured operational metrics, backup/restore proof, and retention policy are
+  required before authority cutover.
 - State Hub and Repo Manager callers have not yet been retargeted.