@terreno/mcp 57.17.0 → 57.18.0

package/src/docs/versioned/next/implementationPlans/deploy-to-vercel.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
 
-**Status:** Approved — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Status:** Implemented — V1/V2/V3 decided 2026-10-11; Vercel runs in parallel with Cloud Run + Netlify for an evaluation period
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1012
 **Priority:** High
 **Effort:** Big batch
@@ -28,23 +28,32 @@ Give Terreno the fastest possible "my app is on the internet" path, and a skill
 
 | # | Question | Decision |
 |---|----------|----------|
-| V1 | Backend host | **Open — spike required.** Candidate: all-in-one on Vercel (web + backend + Blob storage). Fallback: Railway/Render/Fly + Vercel static web (see [`deployment-foundation`](deployment-foundation.md)). **Do not publish a final answer until TODOs below are closed.** |
-| V2 | Document `server` output? | **Open — depends on V1 spike.** Default if documented: advanced section, Expo SDK ≥ 55, SSE buffering caveat |
-| V3 | Commit `vercel.json`? | **Open — depends on V1 spike.** Candidate: wired to real deployment in `example-frontend` and `example-backend` |
+| V1 | Backend host | **Decided 2026-10-11 (human): run all-in-one on Vercel in parallel with the existing split deploy.** `terreno-backend` (Vercel Functions, Fluid compute) serves `@terreno/api` with Socket.IO; `terreno-frontend` and `terreno-demo` are static exports. Both topologies are documented; split stays the conservative default for apps that need background workers or GCS uploads. Uploads (GCS) and the jobs worker are disabled on Vercel during the evaluation. |
+| V2 | Document `server` output? | **Decided: A** — advanced section only (repo is on Expo SDK 57); both apps keep `static` output; SSE buffering caveat documented. |
+| V3 | Commit `vercel.json`? | **Decided: A** — committed in `example-backend`, `example-frontend`, and `demo`, wired to real projects in the `terrenolabs` Vercel team (owner: Josh) and deployed by CircleCI (`vercel-deploy` job, `terreno-vercel` context). |
 | V4 | Preview deployments | **A** — include CORS + Better Auth `trustedOrigins` for preview URLs |
 | V5 | Disambiguate Vercel AI SDK vs hosting | **A** — consistent phrasing: "the Vercel AI SDK" vs "Vercel (hosting)" |
 
+## Spike outcome (2026-10-11)
+
+Answered by deploying the examples, not a scratch spike. See `docs/how-to/deploy-to-vercel.md` and `docs/how-to/vercel-function-websockets.md`.
+
+- `@terreno/api` runs on Vercel Functions (Node 24, Fluid compute) by exporting an `http.Server` that `TerrenoApp` attaches to (`example-backend/src/app.ts`, `start(false, server)`). WebSocket upgrades work; change-stream watchers run per instance.
+- The backend must be fully bundled with Bun (`build:vercel`): Vercel's launcher refuses `require()` of ESM, Bun inlines `NODE_ENV`, and the Express preset needs an `import "express"` marker.
+- Clients must use WebSocket-only Socket.IO on Vercel; `@terreno/rtk` `useSocketConnection({transports})` and `@terreno/syncdb` `createSyncDb({socketTransports})` were added.
+- Preview origins are matched with `CORS_ORIGINS` wildcards (`toCorsOrigin`), and Better Auth gets the raw patterns.
+
 ## Open TODOs (pre-implementation spike)
 
 Complete these before Phase 1 of the how-to guide ships:
 
-- [ ] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Use [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the source of truth. Document runtime limits, Fluid compute, cold starts, max-duration disconnects, and that a connection is pinned to one function instance (not session affinity across reconnects).
-- [ ] **V1-todo:** Write operator docs for websocket usage on Vercel Functions (see **Vercel Functions WebSockets** below). Link the beta page; do not copy it. Re-verify every config key and limitation against that page before the how-to ships.
-- [ ] **V1-todo:** Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
-- [ ] **V1-todo:** Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
-- [ ] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
-- [ ] **V2-todo:** If `server` output is documented, confirm Expo SDK ≥ 55+ requirements and list which Terreno features break under static/server export.
-- [ ] **V3-todo:** If committing `vercel.json`, confirm CI/deploy wiring for `example-frontend` and `example-backend` and who owns the Vercel project.
+- [x] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Use [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the source of truth. Document runtime limits, Fluid compute, cold starts, max-duration disconnects, and that a connection is pinned to one function instance (not session affinity across reconnects).
+- [x] **V1-todo:** Write operator docs for websocket usage on Vercel Functions (see **Vercel Functions WebSockets** below). Link the beta page; do not copy it. Re-verify every config key and limitation against that page before the how-to ships.
+- [x] **V1-todo:** (Deferred — Terreno does not route AI through Expo server output; the guide tells operators to keep `/gpt/prompt` on the `@terreno/api` backend.) Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
+- [x] **V1-todo:** (Deferred, owner Josh — GCS uploads are off on Vercel during the evaluation; Blob vs external GCS is future work.) Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
+- [x] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
+- [x] **V2-todo:** If `server` output is documented, confirm Expo SDK ≥ 55+ requirements and list which Terreno features break under static/server export.
+- [x] **V3-todo:** If committing `vercel.json`, confirm CI/deploy wiring for `example-frontend` and `example-backend` and who owns the Vercel project.
 
 ## Architecture
 
@@ -185,7 +194,7 @@ None.
 
 **Create**
 
-- `docs/how-to/deploy-to-vercel.md` (blocked on Phase 0 spike)
+- `docs/how-to/deploy-to-vercel.md` (named for both web and backend; the task list's `deploy-web-to-vercel.md`)
 - `docs/how-to/vercel-function-websockets.md` (Vercel Functions WebSockets beta; may ship during Phase 0)
 - `.rulesync/skills/deploy-vercel/SKILL.md`
 

package/src/docs/versioned/next/implementationPlans/durable-agent-harness.md

@@ -36,7 +36,7 @@ job is one opaque handler with no checkpoints. The harness fills that gap.
 
 | Question | Decision |
 |----------|----------|
-| Build our own harness or adopt pi-durable? | Own harness on Mongo + Vercel `ai` SDK, copying Pi's concepts (tasks, checkpoints, replay-safe tools, hooks, memos, documents, compaction, forks). |
+| Build our own harness or adopt pi-durable? | Own harness on Mongo + the Vercel AI SDK (`ai`), copying Pi's concepts (tasks, checkpoints, replay-safe tools, hooks, memos, documents, compaction, forks). |
 | Where should the harness live? | Inside `@terreno/ai`, as subpath `@terreno/ai/harness`. |
 | How should the `@terreno/jobs` dependency be wired? | Optional peer. Jobs integration is optional; a single process can own execution. |
 | Who executes a run? | Pluggable `Runner`: `InProcessRunner` (single owner, default) and `JobsRunner` (leased, multi-instance). |

package/src/docs/versioned/next/implementationPlans/job-queues.md

@@ -144,7 +144,7 @@ picks it up. Cloud runners persist then create a platform task whose HTTP body
 is `{jobId}` (not the payload). Execute loads the Mongo row, claims if needed,
 runs the handler.
 
-GCP and Vercel SDKs are **optional peers** on subpath exports
+GCP and Vercel Queues SDKs are **optional peers** on subpath exports
 (`@terreno/jobs/runners/gcpCloudTasks`, `@terreno/jobs/runners/vercelQueues`).
 Core `@terreno/jobs` has zero cloud SDKs. Tests inject fakes.
 

package/src/docs/versioned/next/implementationPlans/model-router-mcp.md

@@ -20,7 +20,7 @@ This makes every Terreno app instantly AI-native: any model becomes callable by
 - Auth-agnostic: works with both JWT and Better Auth
 - Tool naming: `{prefix}_list`, `{prefix}_read`, `{prefix}_create`, `{prefix}_update`, `{prefix}_delete`
 - Populate is an option on the read tool, not a separate tool
-- Also exports `getMCPTools()` from `@terreno/ai` returning Vercel `ai` SDK `CoreTool` objects for direct in-process use
+- Also exports `getMCPTools()` from `@terreno/ai` returning Vercel AI SDK (`ai`) `CoreTool` objects for direct in-process use
 - Custom tools via `registerMCPTool` (example: `users_todo_statuses`)
 
 **Related work:** The `ai-multimodal-tools-mcp` branch has `MCPService` (MCP client) and `AIService` in `@terreno/ai` — that's the consumer of what this plan builds.
@@ -116,7 +116,7 @@ Generated from model name, field names/types, and `queryFields`. Example:
 
 ### CoreTool Export
 
-`getMCPTools()` exported from `@terreno/ai` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel `ai` SDK's `streamText()` / `generateText()`.
+`getMCPTools()` exported from `@terreno/ai` returns all registered MCP tools as `Record<string, CoreTool>` for direct use with the Vercel AI SDK's (`ai`) `streamText()` / `generateText()`.
 
 ## Notifications
 

package/src/docs/versioned/next/reference/ai.md

@@ -2,6 +2,8 @@
 
 AI service layer for Terreno backends: provider-agnostic chat via the Vercel AI SDK, request logging, GPT history, projects, file uploads, MCP tools, and optional Langfuse integration.
 
+> `@terreno/ai` is provider-agnostic via the Vercel AI SDK (the `ai` package and its `@ai-sdk/*` providers). That is a model library, unrelated to Vercel hosting; on this page "Vercel" means the AI SDK unless it says hosting. To host on Vercel, see [Deploy to Vercel](../how-to/deploy-to-vercel.md).
+
 ## Table of Contents
 
 - [Install](#install)
@@ -165,7 +167,7 @@ All generation methods log to `AIRequest` via private `logRequest()`. Logging fa
 
 - Default to `TemperaturePresets.DETERMINISTIC` when `temperature` is omitted.
 - Use `JSON_VALUE_SYSTEM_PROMPT` when `systemPrompt` is omitted.
-- Run model text through `normalizeLlmJsonTextForStructuredOutput` before Vercel `Output.*` parsing (strips fences, preamble, balanced JSON slice, trailing commas, smart-quote repair).
+- Run model text through `normalizeLlmJsonTextForStructuredOutput` before the Vercel AI SDK's `Output.*` parsing (strips fences, preamble, balanced JSON slice, trailing commas, smart-quote repair).
 - On failure: `logger.error` records prompt, system prompt, raw model text, and error details; `AIRequest` stores `response` (raw text or sentinel), `error`, and `metadata` (`system`, `finishReason`, `errorStack`, `rawModelTextCaptured`).
 
 Standalone helpers:
@@ -735,7 +737,7 @@ Subpath imports for tree-shaking: `@terreno/ai/langfuseClient`, `@terreno/ai/lan
 ## Subpath exports
 
 Import these instead of `dist/` paths. Deep `dist/` imports break when a bundler (such as
-Vercel's) inlines them and their bare `@terreno/api` imports no longer resolve. Each
+Vercel hosting's build) inlines them and their bare `@terreno/api` imports no longer resolve. Each
 subpath shares module instances with `@terreno/ai/harness`.
 
 | Subpath | Exports |

package/src/docs/versioned/next/reference/environment-variables.md

@@ -68,12 +68,16 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `APP_ENV` | example-backend | ❌ | `development` | No | server |
 | `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
 | `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
+| `CORS_ORIGINS` | example-backend (`utils/betterAuthConfig.ts`) | ✅ for deployed web origins | localhost:8082 origins only | No | server |
+| `CROSS_DOMAIN_AUTH_COOKIES` | example-backend Better Auth config | ❌ | `false` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
 | `TERRENO_BROWSER_LOGS` | `@terreno/api` dev log ingestion | ❌ | enabled only in development; loopback or authenticated requests only | No | server |
 | `ALLOW_MIGRATIONS` | `@terreno/api` `terreno-migrate` | ❌ | unset | No | server |
 | `MIGRATIONS_DIR` | example-backend Dockerfile / `resolveMigrationDir` | ❌ | `<cwd>/migrations` when `dir` is `$bunfs` | No | server |
 
+`CORS_ORIGINS` is comma-separated. An entry may contain `*` (for example `https://*.preview.example.com`); use it only on a domain you control, never on a shared namespace like `vercel.app`. For `corsOrigin`, `*` becomes a `RegExp` that matches letters, digits, and hyphens but never a dot. Better Auth `trustedOrigins` receives the raw pattern and applies its own, broader wildcard matching. Never use `corsOrigin: true` in production; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#cors). Set `CROSS_DOMAIN_AUTH_COOKIES=true` when the web app and API are on different sites.
+
 ## Client / build-time
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -93,6 +97,7 @@ Configured in `expo.extra` and read via `expo-constants`:
 | `DEV_API_PORT` | `@terreno/rtk` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
 | `AUTH_DEBUG` | `@terreno/rtk` | `"true"` enables auth debug logs |
 | `WEBSOCKETS_DEBUG` | `@terreno/rtk` | `"true"` enables socket debug logs |
+| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `useSocketConnection({transports})` and `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
 | `APP_ENV` | `@terreno/rtk` | Logged at startup |
 
 Resolution order for API base URL (`rtk/src/constants.ts`):
@@ -101,6 +106,12 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 2. `extra.BASE_URL` (production only, when env unset)
 3. Dev fallbacks: `hostUri`, experience URL, `localhost`
 
+`EXPO_PUBLIC_API_URL` is inlined only into app source. Code under `node_modules`, including `@terreno/rtk`, does not see the inlined value in a production export and falls back to `extra.BASE_URL`, so set both for production web builds. `example-frontend/scripts/vercelBuild.ts` writes `extra.BASE_URL` from `EXPO_PUBLIC_API_URL` before `expo export`.
+
+### Per-environment values on hosting platforms
+
+Hosting platforms scope variables per environment. Vercel has **Production**, **Preview**, and **Development** scopes; set `EXPO_PUBLIC_API_URL` in each so each build points at its own backend. Because the value is inlined at build time, promoting a preview build to production keeps the preview backend URL. Rebuild for production instead. See [Deploy to Vercel](../how-to/deploy-to-vercel.md#configure-each-environment) and the [multi-environment checklist](../explanation/deployment-baseline.md#multi-environment-checklist).
+
 ## Development tooling
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -329,6 +340,7 @@ skips it, so no deployed revision, PR previews included, holds those accounts.
 
 - [Deployment baseline](../explanation/deployment-baseline.md)
 - [Build for web](../how-to/build-for-web.md)
+- [Deploy to Vercel](../how-to/deploy-to-vercel.md)
 - [Configure Better Auth](../how-to/configure-better-auth.md)
 - [Rate limiting](../how-to/rate-limiting.md)
 - [Durable background jobs](../how-to/background-jobs.md)

package/src/docs/versioned/next/reference/legacy/rtk.md

@@ -284,6 +284,7 @@ useEffect(() => {
 - `onConnectError` (function) — Callback on connection error
 - `onReconnectFailed` (function) — Callback after all reconnection attempts fail
 - `captureEvent` (function) — Analytics event tracking (optional)
+- `transports` (string[]) — Socket.IO transports in order. Default `["polling", "websocket"]`. Pass `["websocket"]` for hosts without session affinity, such as Vercel Functions ([details](../../how-to/vercel-function-websockets.md))
 
 **Returns:**
 - `socket` (Socket | null) — Socket.io client instance

package/src/docs/versioned/next/reference/syncdb.md

@@ -227,6 +227,7 @@ before anything else has confirmed one.
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
 | `transport` | `SyncTransport` | socket transport from `baseUrl` | Override for tests or custom wiring |
+| `socketTransports` | `string[]` | `["polling", "websocket"]` | Socket.IO transports for the default socket transport. Use `["websocket"]` on hosts without session affinity, such as Vercel Functions ([details](../how-to/vercel-function-websockets.md)) |
 | `httpChannel` | `HttpChannel` | built from `baseUrl` | HTTP fallback channel override |
 | `persisterFactory` | `PersisterFactory` | platform default (IndexedDB web, expo-sqlite native) | Storage backend override |
 | `keyProvider` | `KeyProvider` | server-derived via `GET /sync/key` | Web encryption key provider |

package/src/docs/versioned/next/tasks/deploy-to-vercel.md

@@ -15,13 +15,13 @@ See: [`docs/implementationPlans/deploy-to-vercel.md`](../implementationPlans/dep
 
 Close every **Open TODO** in the IP before writing the how-to guide.
 
-- [ ] **Task 0.1**: Spike `@terreno/api` on Vercel
+- [x] **Task 0.1**: Spike `@terreno/api` on Vercel
   - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Treat [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the vendor contract. Record Fluid compute, max-duration disconnects, instance pinning (not affinity across reconnects), Redis for cross-instance fan-out, Function billing while sockets are open, cold starts, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
   - Files: spike notes in PR / IP update; optional scratch `example-backend/vercel.json`
   - Depends on: none
   - Acceptance: IP questions **V1**, **V2**, and **V3** updated with a recorded decision; all IP Open TODO checkboxes checked or explicitly deferred with owner.
 
-- [ ] **Task 0.2**: Write Vercel Functions WebSocket operator docs
+- [x] **Task 0.2**: Write Vercel Functions WebSocket operator docs
   - Description: Create `docs/how-to/vercel-function-websockets.md` from the IP section **Vercel Functions WebSockets (Public Beta)**. Cite `https://vercel.com/docs/functions/websockets`; do not copy Vercel examples. Cover Fluid compute, HTTP Upgrade + Firewall/rate limits, websocket-only Socket.IO, `export default` HTTP server vs `TerrenoApp.start()`, instance pinning, max-duration reconnects, Redis (`RealtimeApp` adapter), Function billing while connected, and verification (`WEBSOCKETS_DEBUG`, DevTools WS, no polling fallback). Mark **beta**. Do not recommend all-in-one topology until V1 is decided. Link from `docs/how-to/README.md` and later from `docs/how-to/deploy-web-to-vercel.md` and `docs/how-to/websocket-integration.md`.
   - Files: `docs/how-to/vercel-function-websockets.md` (new), `docs/how-to/README.md`, `docs/how-to/websocket-integration.md`
   - Depends on: none (may ship before Task 0.1 closes; must re-verify against the Vercel page at ship time)
@@ -29,19 +29,19 @@ Close every **Open TODO** in the IP before writing the how-to guide.
 
 ## Phase 1: Core how-to guide
 
-- [ ] **Task 1.1**: Write the Vercel deployment guide for `single` output
+- [x] **Task 1.1**: Write the Vercel deployment guide for `single` output
   - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements. Link `docs/how-to/vercel-function-websockets.md` wherever sockets on Functions are mentioned.
   - Files: `docs/how-to/deploy-web-to-vercel.md` (new), `docs/how-to/README.md`
   - Depends on: `deployment-foundation` Phase 4, Task 0.2
   - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index; websocket Functions page is linked, not duplicated.
 
-- [ ] **Task 1.2**: `[RTK]` Add the verification section
+- [x] **Task 1.2**: `[RTK]` Add the verification section
   - Description: Add a "Verify the deployment" section with four checks, each with the expected result and what failure means: (1) the root URL loads the app; (2) a deep link loads directly on refresh (proves the SPA rewrite works); (3) login succeeds, proving the API call reaches the backend and CORS is configured; (4) the websocket connects, proving realtime and live feature flags work. For check 4, give a concrete way to verify — browser devtools Network tab filtered to WS, or the client's debug logging flag (find the actual flag name in the client package, `WEBSOCKETS_DEBUG` at time of writing) — and explain that the app looks fine when this is broken, which is why it must be checked explicitly.
   - Files: `docs/how-to/deploy-web-to-vercel.md`
   - Depends on: Task 1.1
   - Acceptance: all four checks present with expected results; the websocket check names a real debug flag verified in the client source; the "looks fine while broken" warning is present.
 
-- [ ] **Task 1.3**: Add the reference `vercel.json`
+- [x] **Task 1.3**: Add the reference `vercel.json`
   - Description: Per IP question V3 (after Phase 0), add `vercel.json` to `example-frontend` and optionally `example-backend` if all-in-one wins. Wire to a real deployment only if V3 decision is **A**.
   - Files: `example-frontend/vercel.json` (new), `example-frontend/README.md`
   - Depends on: Task 1.1
@@ -49,13 +49,13 @@ Close every **Open TODO** in the IP before writing the how-to guide.
 
 ## Phase 2: Preview deployments and origins
 
-- [ ] **Task 2.1**: `[RTK]` Document the preview-origin problem
+- [x] **Task 2.1**: `[RTK]` Document the preview-origin problem
   - Description: Add a "Preview deployments" section covering: how Vercel assigns a unique origin per deployment; why that breaks CORS and Better Auth; a concrete `corsOrigin` pattern accepting production plus preview origins (write it as a function or regex matching the project's preview hostname shape — read `api/src/expressServer.ts` to confirm what shapes `corsOrigin` actually accepts before writing the example); the equivalent `trustedOrigins` configuration for Better Auth including native deep-link schemes; and OAuth redirect-URI registration per provider, noting that most providers do not support wildcards so preview OAuth needs either a fixed proxy origin or provider-specific handling. State that `corsOrigin: true` must not be used in production and explain the risk.
   - Files: `docs/how-to/deploy-web-to-vercel.md`
   - Depends on: Task 1.2
   - Acceptance: the `corsOrigin` example is a shape actually supported by `setupServer`, cited to source; `trustedOrigins` guidance matches `api/src/betterAuth.ts`; the OAuth wildcard limitation is stated; the `corsOrigin: true` warning explains the risk rather than just prohibiting it.
 
-- [ ] **Task 2.2**: `[RTK]` Document per-environment client configuration
+- [x] **Task 2.2**: `[RTK]` Document per-environment client configuration
   - Description: Add a short section on Vercel's three environment scopes (production, preview, development) and how `EXPO_PUBLIC_API_URL` should differ across them — typically a production backend and a staging backend. Explain the consequence that follows from build-time inlining: each environment produces a different bundle, so a promoted preview build points at the preview backend unless rebuilt. Cross-reference the multi-environment checklist in `docs/explanation/deployment-baseline.md`. Add a note to `docs/reference/environment-variables.md` about Vercel's per-environment scoping.
   - Files: `docs/how-to/deploy-web-to-vercel.md`, `docs/reference/environment-variables.md`
   - Depends on: Task 2.1
@@ -63,19 +63,19 @@ Close every **Open TODO** in the IP before writing the how-to guide.
 
 ## Phase 3: Advanced — server output
 
-- [ ] **Task 3.1**: Determine and record server-output availability
+- [x] **Task 3.1**: Determine and record server-output availability
   - Description: Read the `expo` version in the root `package.json` catalog and the state of PR #779 (Expo SDK 56 upgrade). Record in the guide whether `server` output is available today. If the SDK is below 55, the section must open with a clear "not available on the current Terreno Expo version" note plus a link to PR #779 and [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md).
   - Files: `docs/how-to/deploy-web-to-vercel.md`
   - Depends on: Task 1.1
   - Acceptance: the stated Expo version matches the catalog exactly; availability is stated unambiguously; PR #779 is linked if applicable.
 
-- [ ] **Task 3.2**: Write the server-output section
+- [x] **Task 3.2**: Write the server-output section
   - Description: Document the server-output path as advanced: setting `web.output` to `server` in the app config, the server entry file using `expo-server/adapter/vercel`, the `vercel.json` with `outputDirectory` pointing at the client output and a function including `dist/server/**`, and the `vercel-build` script. Verify the exact adapter import path, function config keys, and required file locations against the current Expo API-routes documentation. Add a clearly-marked caveat: responses through the Vercel adapter may be buffered rather than streamed, which breaks the SSE streaming used by `@terreno/ai`'s `/gpt/prompt` endpoint — link the upstream issue and state the workaround (keep AI streaming on the `@terreno/api` backend rather than routing it through Expo API routes on Vercel).
   - Files: `docs/how-to/deploy-web-to-vercel.md`
   - Depends on: Task 3.1
   - Acceptance: every config key and import path verified against current Expo docs with the doc URL cited; the streaming caveat names the affected Terreno endpoint and gives a workaround; the section is labeled advanced.
 
-- [ ] **Task 3.3**: Disambiguate "Vercel AI SDK" across the repo
+- [x] **Task 3.3**: Disambiguate "Vercel AI SDK" across the repo
   - Description: Grep for `Vercel` across `docs/`, package READMEs, and `.rulesync/rules/` (`rg -n "Vercel"`). For every occurrence referring to the AI library, ensure it reads "the Vercel AI SDK" and never bare "Vercel". Add a one-line note to `docs/reference/ai.md` clarifying that `@terreno/ai` is provider-agnostic via the Vercel AI SDK and that this is unrelated to Vercel hosting. Add the same clarification to the new deployment guide.
   - Files: `docs/reference/ai.md`, `docs/how-to/deploy-web-to-vercel.md`, `.rulesync/rules/ai/00-ai.md`, `ai/README.md`, generated mirrors
   - Depends on: Task 1.1
@@ -83,19 +83,19 @@ Close every **Open TODO** in the IP before writing the how-to guide.
 
 ## Phase 4: The `deploy-vercel` skill
 
-- [ ] **Task 4.1**: Author the skill
+- [x] **Task 4.1**: Author the skill
   - Description: Create `.rulesync/skills/deploy-vercel/SKILL.md` with frontmatter (`name`, a `description` naming trigger phrases "deploy to Vercel", "deploy the web app", "put this online", and `targets: ['*']`). Body: When to use / when not to use (explicitly: not for the backend); Detect (Expo Router app, `web.output` value, existing `vercel.json`, backend URL); Configure (`vercel.json` per output mode, `vercel-build` script for server output); Wire the backend (set `EXPO_PUBLIC_API_URL` per Vercel environment; print the exact `corsOrigin` and `trustedOrigins` changes the user must apply on the backend and stop until they confirm, since the agent cannot safely edit a deployed backend's config); Deploy (`vercel`, then `vercel --prod` behind a confirmation gate); Verify (the four checks from Task 1.2); Troubleshoot (link the reference). Include a prohibition on deploying to production without explicit confirmation and on setting `corsOrigin: true`.
   - Files: `.rulesync/skills/deploy-vercel/SKILL.md` (new)
   - Depends on: Task 2.1, Task 3.2
   - Acceptance: frontmatter complete; the production-deploy confirmation gate is present; the verification step includes the websocket check; no command appears in the skill that is absent from the how-to guide.
 
-- [ ] **Task 4.2**: Add the troubleshooting reference
+- [x] **Task 4.2**: Add the troubleshooting reference
   - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works (Fluid off, long-polling fallback, or max-duration close — link `docs/how-to/vercel-function-websockets.md`); and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
   - Files: `.rulesync/skills/deploy-vercel/references/troubleshooting.md` (new)
   - Depends on: Task 4.1
   - Acceptance: at least six entries; each quotes a real error string or describes a precisely observable symptom; each names the file or setting to change.
 
-- [ ] **Task 4.3**: Generate skill mirrors
+- [x] **Task 4.3**: Generate skill mirrors
   - Description: Run `bun run rules` and commit all generated files. Do not hand-edit generated output.
   - Files: generated skill mirrors
   - Depends on: Task 4.1, Task 4.2
@@ -103,7 +103,7 @@ Close every **Open TODO** in the IP before writing the how-to guide.
 
 ## Phase 5: Validation
 
-- [ ] **Task 5.1**: Deploy the example frontend to a scratch Vercel project
+- [x] **Task 5.1**: Deploy the example frontend to a scratch Vercel project
   - Description: Following only `docs/how-to/deploy-web-to-vercel.md`, deploy `example-frontend` to a scratch Vercel project pointed at a real deployed backend. Run all four verification checks. Record and fix every gap in the guide. Capture screenshots of the deployed app (logged in, with a deep link loaded directly) and the devtools websocket connection, saved under `/opt/cursor/artifacts/`.
   - Files: `docs/how-to/deploy-web-to-vercel.md`
   - Depends on: Task 1.3, Task 2.2

package/src/docs/versioned/next/tasks/model-router-mcp.md

@@ -25,7 +25,7 @@
   - Acceptance: Given a Mongoose model, produces valid Zod schemas for each CRUD method. Tests cover all common field types. `excludeFields` removes specified fields from schemas.
 
 - [x] **Task 1.4**: Generate MCP tool definitions from registry entries
-  - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel `ai` SDK `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
+  - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel AI SDK (`ai`) `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
   - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
   - Depends on: Task 1.2, Task 1.3
   - Acceptance: Registry entry with `methods: ['list', 'read']` produces exactly `todos_list` and `todos_read` tools with correct schemas and descriptions.
@@ -55,7 +55,7 @@
   - Acceptance: Full CRUD lifecycle works over MCP. Permission denials return appropriate errors. Owner filtering restricts results. Population returns nested data.
 
 - [x] **Task 1.9**: Export public API
-  - Description: Export `MCPConfig` and MCP registry/server helpers from `@terreno/api`. Export `getMCPTools()` from `@terreno/ai` so the Vercel `ai` SDK stays out of `@terreno/api`.
+  - Description: Export `MCPConfig` and MCP registry/server helpers from `@terreno/api`. Export `getMCPTools()` from `@terreno/ai` so the Vercel AI SDK (`ai`) stays out of `@terreno/api`.
   - Files: `api/src/index.ts`, `ai/src/index.ts`, `ai/src/service/getMCPTools.ts`
   - Depends on: Task 1.7
   - Acceptance: Consumers can `import { MCPConfig } from "@terreno/api"` and `import { getMCPTools } from "@terreno/ai"`.

package/dist/docs/versioned/0.30.0/README.md

@@ -1,29 +0,0 @@
-# Terreno Documentation
-
-Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
-
-## Structure
-
-- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
-- **[How-to guides](how-to/)** — Problem-oriented, practical steps
-- **[Reference](reference/)** — Technical reference for APIs and packages
-- **[Explanation](explanation/)** — Concepts and context
-- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
-
-## Packages
-
-| Package | Description |
-|---------|-------------|
-| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
-| [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
-| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
-| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
-| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
-| [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
-
-## Quick links
-
-- [Getting started](tutorials/getting-started.md)
-- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
-- [.cursorrules](../.cursorrules) — Project and code style rules

package/dist/docs/versioned/0.30.0/explanation/README.md

@@ -1,14 +0,0 @@
-# Explanation
-
-Understanding-oriented documentation: concepts, architecture, and context.
-
-## Contents
-
-- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
-- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
-- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
-- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
-- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
-- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
-- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
-- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels