Prepare State Hub retirement baseline

docs/cluster-operating-model.md

@@ -159,6 +159,19 @@ Runbook: [`docs/consistency-sweep-runbook.md`](consistency-sweep-runbook.md).
 cutover while the bridge target chain was rewired. Manual sweeps succeed.
 Re-enablement is tracked outside this workplan (service-inventory gap).
 
+## Activity-core ops run visibility
+
+Ops-run claims, leases, completion, and failure remain on activity-core in
+Railiance. State Hub only exposes the cached read projection described in
+[`ops-run-read-projection.md`](ops-run-read-projection.md). Configure the
+coulombcore State Hub deployment with a private `ACTIVITY_CORE_URL` and an
+OpenBao/ESO-injected `ACTIVITY_CORE_WORKER_TOKEN`.
+
+If the Railiance edge or tunnel is unavailable, State Hub serves the last
+successful projection with `stale: true`; before any successful pull it returns
+`available: false`. Alert on those flags. Do not add claim or completion writes
+to State Hub as a failover mechanism.
+
 ## Pragmatic Limitations (Single-Node)
 
 This deployment is intentionally **not** highly available:
@@ -197,4 +210,4 @@ After image or chart changes, see `deploy/railiance/README.md` and
 - `workplans/CUST-WP-0011-state-hub-threephoenix-migration.md` — migration plan
 - `workplans/CUST-WP-0038-state-hub-threephoenix-ha.md` — future HA target
 - `deploy/railiance/README.md` — Helm/CNPG handoff
-- `the-custodian/ops/service-inventory.yml` — live endpoint inventory
+- `the-custodian/ops/service-inventory.yml` — live endpoint inventory

docs/onboarding.md

@@ -19,6 +19,28 @@ cd ~/state-hub
 make bootstrap-env
 ```
 
+The bootstrap enables `sandbox_workspace_write.network_access` in the
+operator's Codex `config.toml`, removes any default `dev-hub` Codex MCP
+registration, then checks whether a Codex sandbox can reach
+`http://127.0.0.1:8000/state/health`. Use `--skip-codex` to omit this step, or
+run it independently:
+
+```bash
+make configure-codex
+```
+
+If verification still reports isolated networking, a managed Codex permission
+profile is overriding user configuration. Retry State Hub REST/CLI commands with
+escalated execution or change that managed profile; do not infer that the API is
+down until the same health check has been run outside the sandbox.
+
+The slim six-tool Codex MCP server remains available for explicit testing, but
+is not recommended while the Codex MCP bridge adds substantial call latency:
+
+```bash
+make configure-codex WITH_MCP=1
+```
+
 On a clean Ubuntu 24.04 machine, allow package installation explicitly:
 
 ```bash

docs/ops-run-read-projection.md

@@ -0,0 +1,56 @@
+# Ops run read projection
+
+State Hub projects activity-core `ops_run` queue health for fleet visibility.
+Activity-core remains the authority for run creation, claims, leases,
+completion, failure, and expiry under ACT-ADR-005 and ACTIVITY-WP-0026.
+
+## V1 contract
+
+V1 is a cached **pull** projection. State Hub reads activity-core:
+
+```text
+GET {ACTIVITY_CORE_URL}/ops-runs?limit=200
+X-Worker-Token: ${ACTIVITY_CORE_WORKER_TOKEN}
+```
+
+The credential is owned by the OpenBao/railiance-platform path and must be
+injected at runtime. State Hub never persists or returns it.
+
+The upstream fields consumed are:
+
+| Upstream field | Projection field |
+| --- | --- |
+| `id` | `id` |
+| `activity_definition_id` | `definition` |
+| `target_repo` | `target_repo` |
+| `state` | `state` |
+| `claim_owner`, `lease_until`, `attempt` | `lease` |
+| `updated_at` | `updated_at` |
+| `result.error` or `last_error` | `last_error` |
+
+State Hub exposes:
+
+- `GET /ops-runs/summary`
+- `/state/summary` field `ops_runs`
+
+Both provide `open`, `claimed`, `failed_24h`, `stuck_open_or_claimed`, and a
+bounded list of open/claimed/failed rows. There are deliberately no claim,
+heartbeat, complete, fail, or expiry endpoints in State Hub.
+
+## Cache and failure behavior
+
+`OPS_RUN_PROJECTION_TTL_SECONDS` defaults to 15 seconds. A refresh failure
+serves the last successful projection with `stale: true` and an `error` field.
+Before the first successful read, the projection returns `available: false`;
+State Hub summary and work-record APIs remain healthy.
+
+`OPS_RUN_SLA_HOURS` defaults to 1 hour and classifies open or claimed runs older
+than the threshold as stuck. This is an operator signal, not a state transition.
+
+## Railiance and coulombcore boundary
+
+Claims happen against activity-core on Railiance. State Hub on coulombcore only
+pulls visibility through the configured private activity-core endpoint. If the
+edge/tunnel path is unavailable, visibility may lag and the projection is marked
+stale; operators should alert on stale/unavailable projection state rather than
+moving claim authority into State Hub.