Fix hosted versus local MCP access boundaries

.codex/config.toml

@@ -1,13 +1,15 @@
-# Secret-free, project-scoped MCP registrations for trusted Codex hosts.
+# Secret-freeMCP registrations for trusted Codex Desktop/CLI hosts.
 # OAuth credentials remain in each host credential store — never commit them here.
 #
 # checked-in policy:
 # - enabled = false so ordinary/offline Codex sessions do not initialize providers
+# (check:codex-cloud fails if any tracked entry is enabled; opt in via
+# $CODEX_HOME/config.toml or a never-committed local edit)
 # - production Supabase uses "prompt" so every metadata/read operation requires
 # explicit approval; write-capable Figma/Railway/Sentry tools use "writes"
 # - Paid API canaries (eval:rag, eval:retrieval:quality, eval:quality, verify:release,
 # test:live, check:supabase-project) still need explicit confirmation per AGENTS.md
-# Hosted Cloud tools come from installed OAuth plugins/connectors; `.mcp.json` is a cross-client template, not runtime proof.
+# Hosted ChatGPT/Codex tools come only from installed, authenticated apps; this file is not runtime proof.
 
 [mcp_servers.figma_cloud]
 url = "https://mcp.figma.com/mcp"
@@ -21,7 +23,9 @@ url = "https://mcp.supabase.com/mcp?project_ref=sjrfecxgysukkwxsowpy&read_only=t
 enabled = false
 default_tools_approval_mode = "prompt"
 
-[mcp_servers.railway_cloud]
+# Named `railway` (not `railway_cloud`) so `codex mcp login railway` matches the
+# entry name. Other providers keep the `_cloud` suffix; this asymmetry is intentional.
+[mcp_servers.railway]
 url = "https://mcp.railway.com"
 enabled = false
 default_tools_approval_mode = "writes"

AGENTS.md

@@ -366,7 +366,7 @@ surface, read `docs/rag-behaviour/` (README → behaviour-map → refuted-approa
 - Production services `Database` (Next.js app tier, serves `https://psychiatry.tools`) and `worker` (ingestion) auto-deploy from `BigSimmo/Database` pushes to `main`; the `staging` environment runs the `app` service.
 - The older Railway project `clinical-kb` (`4361c04f-dd3c-4ee9-9e97-49e4e5707b70`) is superseded with zero active deployments; treat it as stale — never `railway link` to it or deploy there.
 - The similarly named Supabase project `Clinical KB Database` is the database/auth tier, not a Railway project; see "Supabase project safety" above.
-- Railway CLI/MCP auth uses `RAILWAY_API_TOKEN` (personal account token; see `.env.example`). The project-scoped `RAILWAY_TOKEN` is for CI deploys only and cannot list or link projects. The project-scoped Railway MCP server is registered in `.mcp.json`.
+- Railway CLI token auth uses `RAILWAY_API_TOKEN` (personal account token; see `.env.example`). The project-scoped `RAILWAY_TOKEN` is for CI deploys only and cannot list or link projects; Cloud runtime acceptance no longer installs or probes the CLI, so that substitution rule is documentation-enforced until an operator workflow reintroduces CLI checks. Desktop/CLI MCP uses the secret-free `railway` entry (enable in `$CODEX_HOME/config.toml` or via a never-committed local edit — never commit `enabled = true`) plus `codex mcp login railway`; neither repository MCP file activates a hosted ChatGPT/Codex app.
 - Railway deploys and mutations fall under the "API and provider confirmation boundary" below; verify target project/environment IDs before any mutation.
 
 <!-- END:railway-project-safety -->
@@ -876,11 +876,13 @@ Use `docs/codex-cloud.md` as the environment contract:
  Write-capable Figma, Railway, and Sentry tools still require explicit confirmation. Paid API
  canaries (`eval:rag`, `eval:retrieval:quality`, `eval:quality`, `verify:release`,
  `test:live`, `check:supabase-project`) still need explicit confirmation. Project
- `.codex/config.toml` keeps MCP entries `enabled = false` so ordinary/offline hosts do not
- initialize them. Connected setup writes enabled Railway and constrained Supabase entries to the
- host `$CODEX_HOME/config.toml`; actual availability still requires the installed host
- plugin/connector to complete OAuth and a fresh task to prove the callable inventory with
- read-only identity calls. Root `.mcp.json` is a static cross-client template, not runtime proof.
+ `.codex/config.toml` keeps Desktop/CLI MCP entries `enabled = false` in git (`check:codex-cloud`
+ fails if any tracked entry is enabled). Opt in locally via `$CODEX_HOME/config.toml` (preferred)
+ or a never-committed project-file edit, then `codex mcp login railway`. Cloud setup never writes
+ Railway or Supabase MCP registrations to `$CODEX_HOME`. Hosted ChatGPT/Codex requires an
+ installed, workspace-authorized, OAuth-authenticated app, and a fresh task must prove the callable
+ inventory with read-only identity calls. Root `.mcp.json` is a static cross-client template, not
+ hosted runtime proof.
 - Cloud has no Windows task-start script. Report that exact fact, then perform equivalent
  read-only identity, branch, status, worktree, and Git-operation checks. Proceed only in a
  clean disposable checkout on a task-specific non-protected branch.
@@ -893,16 +895,22 @@ Use `docs/codex-cloud.md` as the environment contract:
  separately without printing secret values.
 - In a fresh Cloud task, run `bash scripts/check-codex-cloud-raw-env.sh` before sourcing a
  profile or entering a login shell. It must report only provider variable names and presence,
- never values. Then run `npm run check:codex-cloud` directly; it must report the
- static-and-environment PASS line. Run `npm run check:codex-cloud -- --runtime` with
- `CODEX_CLOUD_EXPECTED_BASE_SHA` set to the intended merge/base commit when the checkout has
- only a task HEAD. Setup and maintenance may report freshness as unverified so provisioning
- remains repairable, but explicit acceptance must not pass an arbitrary HEAD. The command shims
- load the generated profile for normal `node`, `npm`, and `npx` work. Also run
- `npm run check:runtime` and `npm run check:installed-lock-parity` before trusting a new or
- reset environment. A skipped browser install is not full browser readiness. Output is limited
- to approved mode values, presence booleans, full Git commit identities, and MCP
- server/command/environment-variable names; never print credential values.
+ never values. Treat exit `1` / `FAIL`+`STOP` as a hard stop for any unexpected inherited name.
+ Only exit `2` / `FAIL-KNOWN` for `OPENAI_BASE_URL` alone may use the restricted
+ profile-and-shim continue path; do not generalize that allowance. Exit `2` is still a failed raw
+ boundary — future automation must not treat non-1 as success or as a blind retry. That name can
+ redirect OpenAI-bound traffic, so never invoke OpenAI clients from the raw parent or any binary
+ that bypasses the profile/`node`/`npm`/`npx` scrub. Then run
+ `npm run check:codex-cloud` directly; it must report the static-and-environment PASS line. Run
+ `npm run check:codex-cloud -- --runtime` with `CODEX_CLOUD_EXPECTED_BASE_SHA` set to the
+ intended merge/base commit when the checkout has only a task HEAD. Setup and maintenance may
+ report freshness as unverified so provisioning remains repairable, but explicit acceptance must
+ not pass an arbitrary HEAD. The command shims load the generated profile for normal `node`,
+ `npm`, and `npx` work. Also run `npm run check:runtime` and
+ `npm run check:installed-lock-parity` before trusting a new or reset environment. A skipped
+ browser install is not full browser readiness. Output is limited to approved mode values,
+ presence booleans, full Git commit identities, and MCP server/command/environment-variable
+ names; never print credential values.
 - Do not add OpenAI, Supabase, Railway, GitHub, database, or user credentials as ordinary
  Cloud environment variables. Codex Cloud secrets are setup-only and unavailable to the
  agent phase unless the platform explicitly exposes a secret to the named task phase; do not
@@ -915,9 +923,17 @@ Use `docs/codex-cloud.md` as the environment contract:
  `.github/workflows/authenticated-live-tests.yml` GitHub Actions workflow, its explicit
  dispatch confirmation, and the `Database / production` environment, never by exposing
  credentials to the Codex Cloud agent shell.
-- Connected Cloud Railway access uses the hosted Railway MCP connector and browser OAuth; prove it
- with the callable tool inventory and a read-only identity/project-list call. CLI token auth is a
- separate operator capability: it requires both the pinned CLI and a dedicated
+- The active hosted workspace is **Personal Pro**. Use Railway's installed official ChatGPT app
+ with browser OAuth and **Allow read actions**; Personal Pro does not provide the dedicated-group
+ RBAC or per-tool action disabling assumed by Enterprise/Edu instructions. Prove Railway with the
+ callable tool inventory and a read-only identity/project-list call. Repository setup and local
+ MCP config cannot activate it, and the Codex Cloud connector page currently offers no Railway
+ connector. Use the documented split control plane: Codex Cloud for code and its native GitHub
+ connector, ChatGPT web for Railway and project-scoped read-only Supabase. Every provider change
+ still requires explicit approval. Enterprise/Edu custom-app controls are a future governance
+ option, not the current workspace classification.
+ CLI token auth is a separate operator capability: it requires a separately installed Railway CLI
+ and a dedicated
  `RAILWAY_API_TOKEN`, and must never substitute `RAILWAY_TOKEN` or expose either token to an
  ordinary agent shell. GitHub connector access, GitHub CLI authentication, the credential-free
  `origin` URL, and shell Git authentication are separate capabilities.

docs/README.md

@@ -125,6 +125,7 @@ as it was on that date; supersede with a new dated document rather than editing.
 - [audit/audit-handover-2026-07-14.md](audit/audit-handover-2026-07-14.md) — multi-skill repository audit findings inventory
 - [audit/audit-remediation-plan-2026-07-14.md](audit/audit-remediation-plan-2026-07-14.md) — sequenced remediation plan for the 2026-07-14 audit, with the 2026-07-17 reconciliation
 - [audit/design-audit-2026-07-17.md](audit/design-audit-2026-07-17.md) — repository-wide design, accessibility, and interaction audit
+- [audit/cloud-connection-acceptance-2026-08-05.md](audit/cloud-connection-acceptance-2026-08-05.md) — hosted versus local MCP boundary acceptance, Personal Pro split control plane, and remaining Cloud launcher blockers
 - [current-clinical-work-brief.md](current-clinical-work-brief.md) — ledger #063 product/privacy/persistence brief (decision only, no implementation)
 - [factsheets-reading-model-brief.md](factsheets-reading-model-brief.md) — ledger #041 reading-model decision (no second Factsheets mode)
 - [source-governance-refresh-worklist-2026-07-22.md](source-governance-refresh-worklist-2026-07-22.md) — ledger #022 worklist and BMJ attestation policy status

docs/agents-guide.md

@@ -44,7 +44,7 @@ below defers to it, so rules live in one place and cannot drift.
 | **Codex** (OpenAI) | Primary PR code-review + automatic resolve | AGENTS.md "Codex review" sections, `docs/codex-review-protocol.md`, `docs/codex-prompt-playbook.md`, `.github/workflows/codex-autofix-review-comments.yml` |
 | **Claude Code** | Interactive dev; scoped review subagents + workflow skills | `.claude/` (agents, skills, hooks), `.github/workflows/claude.yml` |
 | **Cursor** | Editor skills + project MCP (Supabase, Context7, …) | `.cursor/` (skills, `mcp.json`) |
-| **Railway MCP** | Deploy/logs/env **names** (project-scoped)  | Root `.mcp.json` (`@railway/cli` mcp); needs `RAILWAY_API_TOKEN` — not `RAILWAY_TOKEN`  |
+| **Railway MCP** | Desktop/CLI template; hosted app is separate| Root `.mcp.json` / `.codex/config.toml` use `https://mcp.railway.com` with OAuth; hosted ChatGPT/Codex requires a workspace-installed app |
 | **CodeRabbit** | Advisory PR review (never blocking) | `.coderabbit.yaml` (`commit_status: false`) |
 | **`.agents/`** | Home-grown single-word skill catalogue | `.agents/skills/catalog.json`; list with `npm run skills` |
 
@@ -58,13 +58,13 @@ servers** per session (tool-schema token bloat degrades agents).
 Use registered MCPs before opening dashboards when the task is read-only inspection.
 Writes, secret rotations, and hosted mutations stay confirmation-gated per `AGENTS.md`.
 
-| Server | Config | Use for | Do not |
-| --------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Supabase** (read-only) | `.cursor/mcp.json` — pinned `project_ref=sjrfecxgysukkwxsowpy`, `read_only=true` | `search_docs`, advisors, read SQL, schema inspection | Print secret values; raw-edit retrieval RPCs via `execute_sql`; Auth DB connection-cap (`#011`) — **dashboard only** |
-| **Railway** | Root `.mcp.json` | Deploy status, service logs, env **names**/presence  | Confuse `RAILWAY_API_TOKEN` (personal) with CI `RAILWAY_TOKEN`; mutate without approval |
-| **Context7** | `.cursor/mcp.json` → `https://mcp.context7.com/mcp` (+ Cursor `context7-plugin`) | Versioned docs for **Tailwind 4, Zod 4, Playwright, Vitest, React 19, `@supabase/supabase-js`** (peers; not exhaustive). Optional higher limits: set `CONTEXT7_API_KEY` (see below) | Next.js 16 — always use `node_modules/next/dist/docs/` (AGENTS.md). Do not invent App Router APIs from training data; never commit the API key |
-| **Chrome DevTools** | `.cursor/mcp.json` → `npx -y chrome-devtools-mcp@1.6.0` | CLS/LCP/console/network while implementing redesigns (`#147`, `#162`–`#164`, Therapy Compass) | Don't leave it always-on with Browse + Playwright MCP (token bloat). Use for perf/debug passes |
-| **GitHub Checks / Actions** | Operator approval pending | PR check visibility when `gh pr checks` returns empty totals | Bot `update-branch`; broaden scopes beyond Checks/Actions read |
+| Server | Config | Use for | Do not |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Supabase** (read-only) | `.cursor/mcp.json` — pinned `project_ref=sjrfecxgysukkwxsowpy`, `read_only=true` | `search_docs`, advisors, read SQL, schema inspection | Print secret values; raw-edit retrieval RPCs via `execute_sql`; Auth DB connection-cap (`#011`) — **dashboard only** |
+| **Railway** | Desktop/CLI: root `.mcp.json` / `.codex/config.toml` (`railway` + OAuth). Hosted ChatGPT/Codex: workspace-installed app only — repository MCP files are not a read path there | Deploy status, service logs, env **names**/presence (Desktop/CLI MCP or hosted app tools)| Treat root `.mcp.json` as hosted proof; confuse `RAILWAY_API_TOKEN` (personal) with CI `RAILWAY_TOKEN`; mutate without approval |
+| **Context7** | `.cursor/mcp.json` → `https://mcp.context7.com/mcp` (+ Cursor `context7-plugin`) | Versioned docs for **Tailwind 4, Zod 4, Playwright, Vitest, React 19, `@supabase/supabase-js`** (peers; not exhaustive). Optional higher limits: set `CONTEXT7_API_KEY` (see below) | Next.js 16 — always use `node_modules/next/dist/docs/` (AGENTS.md). Do not invent App Router APIs from training data; never commit the API key |
+| **Chrome DevTools** | `.cursor/mcp.json` → `npx -y chrome-devtools-mcp@1.6.0` | CLS/LCP/console/network while implementing redesigns (`#147`, `#162`–`#164`, Therapy Compass) | Don't leave it always-on with Browse + Playwright MCP (token bloat). Use for perf/debug passes |
+| **GitHub Checks / Actions** | Operator approval pending | PR check visibility when `gh pr checks` returns empty totals | Bot `update-branch`; broaden scopes beyond Checks/Actions read |
 
 ### Context7 API key (optional)