docs(release): update contracts and docs for functional-completion changes

Add the new endpoints to contracts/openapi.yaml and docs/05-api-contract.md
(return-preview, the four rule-specific data-quality resolution endpoints,
search, integration status, scheduled-scan), document the role matrix and
the audit before/after exposure in docs/12-security-and-audit.md, document
each rule type's actual resolution flow in docs/07-data-quality.md
(including the deliberate evidence-fingerprint simplification and the
reopened_from/previous_decision recurrence link), document the preview/
commit relationship in docs/08-return-workflow.md, and update README.md's
scope/integration-status/quality-gate sections to match what's actually
implemented and verified now. Also drops docs/05-api-contract.md's mention
of GET /api/v1/system/status, which was never implemented.

docs/05-api-contract.md

@@ -11,9 +11,10 @@ The demo may use signed server-issued sessions or short-lived JWTs. Demo-role bu
 ### System and demo
 
 - `GET /health`
-- `GET /api/v1/system/status`
 - `POST /api/v1/demo/login`
-- `POST /api/v1/demo/reset` — Operations Manager only
+- `GET /api/v1/demo/session` — confirms the current session; `Cache-Control: no-store`
+- `POST /api/v1/demo/logout` — safe to call without a session
+- `POST /api/v1/demo/reset` — Operations Manager only; invalidates the caller's own session
 
 ### Dashboard
 
@@ -28,17 +29,37 @@ The demo may use signed server-issued sessions or short-lived JWTs. Demo-role bu
 
 - `GET /api/v1/bookings`
 - `GET /api/v1/bookings/{public_ref}`
+- `POST /api/v1/bookings/{public_ref}/return-preview` — non-mutating; shares its domain
+  evaluation with the commit endpoint below so the two cannot drift apart
 - `POST /api/v1/bookings/{public_ref}/return`
 
-Return commands require an `Idempotency-Key` header and optimistic version where relevant.
+Return commands require an `Idempotency-Key` header. Concurrency safety is row-lock based
+(`SELECT ... FOR UPDATE` on the booking and vehicle); no optimistic-version field is
+accepted or needed on top of that.
 
 ### Data quality
 
+All Operations Manager only.
+
 - `GET /api/v1/data-quality/issues`
 - `GET /api/v1/data-quality/issues/{public_ref}`
+- `POST /api/v1/data-quality/scan` — manual trigger for the deterministic five-rule scan
 - `POST /api/v1/data-quality/issues/{public_ref}/defer`
 - `POST /api/v1/data-quality/issues/{public_ref}/reject`
-- `POST /api/v1/data-quality/issues/{public_ref}/merge-customers`
+- `POST /api/v1/data-quality/issues/{public_ref}/merge-customers` — possible_duplicate_customer
+- `POST /api/v1/data-quality/issues/{public_ref}/provide-fields` — missing_required_field
+- `POST /api/v1/data-quality/issues/{public_ref}/resolve-odometer-regression` — odometer_regression
+- `POST /api/v1/data-quality/issues/{public_ref}/resolve-overlap` — booking_overlap
+- `POST /api/v1/data-quality/issues/{public_ref}/apply-recommended-status` — vehicle_status_conflict
+
+Each of the five rule types has exactly one bounded resolution path above (plus
+defer/reject, which apply to any open issue).
+
+### Search
+
+- `GET /api/v1/search?q=...` — bounded typed results (vehicle, booking,
+  data_quality_issue, section); role-filtered server-side; customers are never returned
+  (no customer detail route exists in this PoC)
 
 ### Knowledge
 
@@ -47,9 +68,21 @@ Return commands require an `Idempotency-Key` header and optimistic version where
 
 ### Automation and audit
 
-- `GET /api/v1/workflows`
-- `POST /api/v1/workflows/{event_id}/retry`
-- `GET /api/v1/audit`
+- `GET /api/v1/workflows` — Operations Manager only
+- `POST /api/v1/workflows/{event_id}/retry` — Operations Manager only
+- `GET /api/v1/audit` — Operations Manager only; each event includes `before`/`after`
+  plus a resolved `entity_ref`/`entity_link` where the entity type supports one
+- `GET /api/v1/integrations/status` — Operations Manager only; truthful aggregate n8n
+  state from outbox delivery counts (not just the most recent event), and the actual
+  MCP Hub `registration_enabled` setting
+
+### n8n-service endpoints
+
+Service-token protected (`X-Service-Token`, same shared secret as the return callback):
+
+- `POST /api/v1/integrations/n8n/return-callback`
+- `POST /api/v1/integrations/n8n/scheduled-scan` — triggered by the scheduled
+  quality-scan workflow; runs the same domain scan the manual UI action uses
 
 ### MCP-provider endpoints