fix(context7): use local stdio MCP and clarify operator key path

.cursor/mcp.json

@@ -4,8 +4,9 @@
       "url": "https://mcp.supabase.com/mcp?project_ref=sjrfecxgysukkwxsowpy&read_only=true"
     },
     "context7": {
-      "url": "https://mcp.context7.com/mcp",
-      "headers": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@3.2.5"],
+      "env": {
         "CONTEXT7_API_KEY": "${env:CONTEXT7_API_KEY}"
       }
     },

.env.example

@@ -289,12 +289,14 @@ TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe
 # --- Agent tooling only (not read by Next.js / env.ts) ---
 # Context7 MCP — versioned library docs for agents (Tailwind 4, Zod 4, Playwright,
 # Vitest, React 19, @supabase/supabase-js, …). Wired in `.cursor/mcp.json` as
-# https://mcp.context7.com/mcp (unversioned remote) with header
-# CONTEXT7_API_KEY: ${env:CONTEXT7_API_KEY}. Works without a key at lower rate
-# limits; get a free key (prefix ctx7sk) at https://context7.com/dashboard.
-# Set it as a Windows/user env var or Cursor Settings → MCP so Cursor can expand
-# ${env:CONTEXT7_API_KEY}. Does NOT feed project MCP: .env.local alone, or Cursor
-# Cloud Agent Secrets (those inject into the Next app env only). Host-injected
-# Cloud Context7 is a separate connector path — see docs/agents-guide.md.
+# local stdio: npx -y @upstash/context7-mcp@3.2.5 with
+# env CONTEXT7_API_KEY=${env:CONTEXT7_API_KEY}. When unset, Cursor expands that
+# placeholder to empty and the server runs anonymously at lower rate limits; get
+# a free key (prefix ctx7sk) at https://context7.com/dashboard for higher limits.
+# Set as Windows/user env, Cursor Settings → MCP, or Cloud Agent Secret (shell
+# process.env). Local MCP / `npx ctx7` use that env; host-injected Context7 may
+# still ignore it — fall back to `npx ctx7`. Reload MCP (or restart Cursor) after
+# key changes — stdio captures env at spawn. .env.local alone does not expand
+# project MCP ${env:}. See docs/agents-guide.md.
 # Never commit the real value. Next.js 16 docs stay local: node_modules/next/dist/docs/
 #CONTEXT7_API_KEY=

AGENTS.md

@@ -966,7 +966,7 @@ Use `docs/codex-cloud.md` as the environment contract:
 
 Durable notes for Cloud Agents. Standard commands live in `README.md` and `package.json`; only non-obvious caveats are captured here.
 
-- Context7 peer-library docs habit (and the Next 16 local-docs carve-out) lives in `docs/agents-guide.md`; Cloud Agent Secrets feed the Next app env, not `.cursor/mcp.json` `${env:}` headers.
+- Context7 peer-library docs habit (and the Next 16 local-docs carve-out) lives in `docs/agents-guide.md`. Project MCP is local `@upstash/context7-mcp@3.2.5` with `CONTEXT7_API_KEY` from env/Secrets. If the host-injected Context7 MCP returns quota exceeded, use `npx ctx7 library|docs …` with the same secret — do not invent peer APIs from training data.
 - Runtime: the app hard-requires Node 24.x / npm 11.x (`engine-strict`, and `scripts/dev-free-port.mjs` exits on any other major). Node 24 is installed via nvm and symlinked into `/usr/local/cargo/bin` (first entry in `PATH`) so `node`/`npm` resolve to v24 in every shell. If a shell ever resolves `/exec-daemon/node` (v22) instead, prepend the installed nvm Node 24 bin to `PATH` (for example `"$HOME/.nvm/versions/node/v24.18.1/bin"`; run `ls "$HOME/.nvm/versions/node"` to confirm the exact patch version).
 - Live vs demo mode: the app auto-detects. When the Supabase + OpenAI env vars below are present (set them as Cloud Agent **Secrets** so they inject into `.env.local`/`process.env`), `isDemoMode()` (`src/lib/env.ts`) is false and the app runs against the live `Clinical KB Database` project (~2000 indexed docs) with OpenAI answer generation. When they are absent, dev auto-falls back to demo mode using the synthetic corpus in `src/lib/demo-data.ts` / `public/demo-documents/`. Required for live mode: `NEXT_PUBLIC_SUPABASE_URL`, `SUPABASE_PROJECT_REF`, `SUPABASE_PROJECT_NAME`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (`sb_publishable_…`), `SUPABASE_SERVICE_ROLE_KEY` (accepts the `sb_secret_…` secret key), `OPENAI_API_KEY`. Keep `RAG_PROVIDER_MODE=auto` so OpenAI is used with graceful source-only fallback. `E2E_USER_EMAIL`/`E2E_USER_PASSWORD` power CI env-check and Playwright.
 - Live-mode caveat: `RAG_PROVIDER_MODE=auto` attempts OpenAI (fast → strong route); if generation fails the built-in quality gates it silently degrades to a deterministic "Source-only" answer that still cites real documents — this is expected, not a failure. The header sign-in UI exposes magic-link + OAuth only (no password field), but the `/api/answer` + retrieval flow works server-side without a browser session.

README.md

@@ -187,19 +187,24 @@ hosted Supabase MCP server uses OAuth, not repo secrets.
 
 ### Context7
 
-Workspace config in `.cursor/mcp.json` points at `https://mcp.context7.com/mcp`
-(unversioned remote URL); `.cursor/settings.json` enables the `context7-plugin`.
-Use Context7 for versioned library docs — **Tailwind 4, Zod 4, Playwright, Vitest,
-React 19, `@supabase/supabase-js`** (peers; not exhaustive) — not for Next.js 16:
-read `node_modules/next/dist/docs/` locally and do not invent App Router APIs from
+Workspace config in `.cursor/mcp.json` runs pinned local
+`npx -y @upstash/context7-mcp@3.2.5` with `CONTEXT7_API_KEY` from `${env:…}`;
+`.cursor/settings.json` enables the `context7-plugin`. Use Context7 for
+versioned library docs — **Tailwind 4, Zod 4, Playwright, Vitest, React 19,
+`@supabase/supabase-js`** (peers; not exhaustive) — not for Next.js 16: read
+`node_modules/next/dist/docs/` locally and do not invent App Router APIs from
 Context7 or training data.
 
 Optional `CONTEXT7_API_KEY` (`ctx7sk…`) from [context7.com/dashboard](https://context7.com/dashboard)
-raises rate limits. Set it as a user/OS env var or in Cursor **Settings → MCP** so
-`${env:CONTEXT7_API_KEY}` in `.cursor/mcp.json` expands. `.env.local` alone and
-Cursor Cloud Agent Secrets do **not** feed that project MCP header (Secrets feed
-the Next app env only). Context7 works without a key at lower limits. Full setup
-notes: `docs/agents-guide.md`. Never commit the API key.
+raises rate limits. Set it as a user/OS env var, Cursor **Settings → MCP**, or a
+Cursor Cloud Agent Secret (shell `process.env`). Local stdio MCP and `npx ctx7`
+use that env; a separate host-injected Context7 connector may still ignore it —
+fall back to `npx ctx7 library|docs …` if host MCP returns quota exceeded.
+Without a key, Cursor expands `${env:CONTEXT7_API_KEY}` to empty and the server
+runs anonymously at lower rate limits. **Reload MCP servers** (or restart Cursor)
+after setting or rotating the key — the stdio child captures env at spawn.
+`.env.local` alone does not expand project MCP `${env:}`. Full setup notes:
+`docs/agents-guide.md`. Never commit the API key.
 
 ## Documentation
 

docs/agents-guide.md

@@ -58,33 +58,38 @@ 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**                 | 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                                                                                 |
+| 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` → `npx -y @upstash/context7-mcp@3.2.5` (+ Cursor `context7-plugin`)                                                                                        | Versioned docs for **Tailwind 4, Zod 4, Playwright, Vitest, React 19, `@supabase/supabase-js`** (peers; not exhaustive). Local stdio reads `CONTEXT7_API_KEY` from env (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)
 
 1. Create a free key at [context7.com/dashboard](https://context7.com/dashboard) (`ctx7sk…`).
-2. Set `CONTEXT7_API_KEY` as a **user/OS env var** or in Cursor **Settings → MCP → context7**
-   env so `${env:CONTEXT7_API_KEY}` in `.cursor/mcp.json` resolves. That expansion is what
-   raises rate limits for the **project** MCP entry (header form
-   `CONTEXT7_API_KEY: ${env:CONTEXT7_API_KEY}` — leave it; do not switch the committed file to
-   empty `Authorization: Bearer`).
-3. **Does not feed project MCP `${env:}`:** `.env.local` alone, or Cursor Cloud Agent
-   **Secrets** (Secrets inject into the Next app’s `.env.local` / `process.env`, not into
-   `.cursor/mcp.json` header interpolation).
-4. **Project MCP vs host connector:** the checked-in `.cursor/mcp.json` entry is the desktop
-   project path. Cursor Cloud may also expose a **host-injected** Context7 connector — same
-   product, different injection. Cloud quota is not fixed by putting the key only in app
-   Secrets.
-5. The remote URL is **unversioned** (cannot pin like `chrome-devtools-mcp@1.6.0`). Reload MCP
-   servers after key changes. Without a key, Context7 still works at lower rate limits.
-6. Prefer the Cursor `context7-plugin` / `resolve-library-id` + `query-docs` tools over raw
-   `curl` to `https://context7.com/api/v2/...` unless you are debugging the HTTP API.
+2. **Project MCP (checked-in):** `.cursor/mcp.json` runs pinned local
+   `@upstash/context7-mcp@3.2.5` with `env.CONTEXT7_API_KEY: ${env:CONTEXT7_API_KEY}` so the
+   stdio child receives the key when Cursor expands it (Cursor filters inherited env for MCP
+   children — the explicit `env` pass-through is required). Set the key as a **user/OS env var**
+   or in Cursor **Settings → MCP → context7**.
+3. **Cursor Cloud Agent Secrets:** inject `CONTEXT7_API_KEY` into the agent shell
+   `process.env`. That authenticates **local** Context7 (`npx @upstash/context7-mcp` /
+   `npx ctx7`) and project stdio MCP after reload. It does **not** authenticate a separate
+   **host-injected** Context7 connector — measured 2026-08-05: host `resolve-library-id`
+   still returned monthly quota exceeded while the same key worked for `npx ctx7 library …`.
+   If host MCP is quota-blocked, use `npx ctx7 library|docs …` (or the project local MCP
+   after reload) — do not invent APIs from training data.
+4. **Does not expand project MCP `${env:}`:** `.env.local` alone (Next app / env.ts path).
+5. **Reload MCP servers after key changes.** The stdio child captures env at spawn time — setting
+   or rotating `CONTEXT7_API_KEY` has no effect until you reload MCP (or restart Cursor).
+6. **Keyless / lower rate limits:** when `CONTEXT7_API_KEY` is unset, Cursor expands
+   `${env:CONTEXT7_API_KEY}` to an empty string and the server runs anonymously. If MCP logs
+   ever show the literal placeholder `${env:CONTEXT7_API_KEY}` as the key value, remove the
+   `env` object from the `context7` entry (anonymous) or set a real key, then reload MCP.
+7. Prefer `resolve-library-id` → `query-docs` when the authenticated MCP path is available;
+   otherwise `npx ctx7`. Avoid raw `curl` with keys in chat logs unless debugging.
 
 Never paste credential values into chat, issues, or commits. Prefer presence/length checks
 (`check:local-presence`) over dumping env contents.

docs/branch-review-ledger.md

@@ -655,3 +655,4 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie
 | 2026-08-05 | claude/privacy-notch-safe-area | 0fbb5686ace5368f6a21b07089db886e639c095a | PR #1621 babysit standalone-shell review fixes | supersede: prior row HEAD ef92d628 was unresolvable; tip after main sync is this SHA; product fixes unchanged | ledger:append correction; merge-tree clean vs main |
 | 2026-08-05 | claude/privacy-notch-safe-area | a3967f8f0ee05b9a3ab922cd4a9feeebdf7efbbc | PR #1621 babysit standalone-shell review fixes | supersede: prior row HEAD ef92d628 was unresolvable; tip after main sync is this SHA; product fixes unchanged | ledger:append correction; merge-tree clean vs main |
 | 2026-08-05 | claude/privacy-notch-safe-area | fe352adb18d3260f0646f64ef992376e1449b0de | Run PR sweep | merged main (stale DIRTY); superseded unresolvable ledger HEAD per Devin; no product threads open | merge-tree clean |
+| 2026-08-05 | cursor/context7-refresh-22b5 | 9479401744191292002f689a07a2cb5308cedc97 | Run PR sweep | no unresolved threads; merged origin/main | merge-tree clean |

docs/codex-cloud.md

@@ -312,9 +312,10 @@ the session, then run `codex mcp login railway`. Setup does not copy any MCP ser
 `$CODEX_HOME`. Hosted ChatGPT and Codex Cloud require the separately installed/authenticated
 workspace app. Start a fresh task after consent and verify the actual callable inventory.
 The root `.mcp.json` is a cross-client Desktop/CLI template and static allowlist only. It does not
-prove hosted Cloud availability. Context7 / library-docs
-MCP is Cursor-side (`.cursor/mcp.json` or a host-injected connector), not part of this Codex Cloud
-Railway + Supabase allowlist.
+prove hosted Cloud availability. Context7 / library-docs MCP is Cursor-side
+(`.cursor/mcp.json` local `@upstash/context7-mcp@3.2.5` with `CONTEXT7_API_KEY` from `${env:…}`,
+or a host-injected connector), not part of this Codex Cloud Railway + Supabase allowlist. When the
+host connector is quota-blocked, use `npx ctx7` with the agent Secret in `process.env`.
 
 ### Personal Pro split control plane