@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -335,8 +335,9 @@ export const syncDb = createSyncDb({authProvider, baseUrl, collections: ["todos"
 
 Better Auth session tokens live in the Better Auth client (`@terreno/rtk` `createBetterAuthClient`):
 
-- **Native:** `expo-secure-store`
-- **Web:** `@react-native-async-storage/async-storage`
+- **Native:** the Expo plugin's cookie jar in `expo-secure-store`
+- **Web (default):** Better Auth's HttpOnly session cookie, managed by the browser. No token is in app storage
+- **Web with `webAuth: "bearer"`:** the `set-auth-token` bearer in `localStorage` (or the `bearerStorage` you pass), readable with `getBetterAuthBearerToken()`. See [Frontend and API on different sites](configure-better-auth.md#frontend-and-api-on-different-sites)
 
 Syncdb does not store tokens itself — it calls `authProvider` on every transport/HTTP request.
 
@@ -346,12 +347,14 @@ On connect, the socket transport sends the bearer token from `getToken()`. When
 
 ### Backend
 
+Register `BetterAuthApp` and `RealtimeApp` on the same `TerrenoApp`. `RealtimeApp` picks up the
+Better Auth instance by itself, so no extra option is needed. Legacy JWT sockets keep working
+alongside it. Only a `RealtimeApp` mounted without `TerrenoApp` needs the instance passed in:
+
 ```typescript
 new RealtimeApp({betterAuth: {auth, userModel: User}})
 ```
 
-Required for Better Auth socket sessions. Legacy JWT sockets continue to work without it.
-
 ## 8. Codegen
 
 Synced collections use `bun run sync-sdk`, which runs `terreno-syncdb-codegen` from

package/dist/docs/versioned/next/how-to/password-reset.md

@@ -29,6 +29,8 @@ authOptions: {
 }
 ```
 
+Pass the `message` through unchanged. Recovery mail carries `sensitive: true`, and `@terreno/comms` stores no payload for a sensitive message, so the reset or verify link never reaches the `CommsMessage` log or the admin Comms Dashboard. If you send through another transport, do not log or store the content of a message with `sensitive: true`.
+
 | Action | Path | Body |
 | --- | --- | --- |
 | Forgot | `POST /auth/forgotPassword` | `{email}` → 202 |
@@ -71,6 +73,10 @@ On `BetterAuthConfig` set the same `publicAppUrl`, `sendMail`, and `renderAuthMa
 4. Show a profile banner when `emailVerified` is false, with Resend calling `POST /auth/sendVerification`.
 5. Add `/verifyEmail` that reads `token` from the query string. JWT apps call `POST /auth/verifyEmail`. Better Auth apps try `GET /verify-email?token=...` first, then the JWT route so either token type can complete.
 
-A new `issueFor` for the same user and type invalidates earlier unused tokens of that type. Changing the mailbox through `PATCH /auth/me` invalidates unused `passwordReset` tokens even when the User schema has no `emailVerified` field. When `emailVerificationPlugin` is applied, mailbox change also sets `emailVerified` to false and invalidates unused `emailVerification` tokens. Letter casing alone does not count as a mailbox change. `emailVerified` and `tokenEpoch` are privileged user fields: signup and `PATCH /auth/me` drop them.
+A new `issueFor` for the same user and type invalidates earlier unused tokens of that type. Changing the mailbox through `PATCH /auth/me` invalidates unused `passwordReset` tokens even when the User schema has no `emailVerified` field. When `emailVerificationPlugin` is applied, mailbox change also sets `emailVerified` to false and invalidates unused `emailVerification` tokens. Letter casing alone does not count as a mailbox change. `emailVerified` and `tokenEpoch` are privileged user fields: signup and `PATCH /auth/me` drop them, along with the password fields `hash` and `salt`.
+
+To set a password from your own server code (for example an admin action), call `changeUserPassword(user, password, {adminId, app: req.app})` from `@terreno/api` so the change revokes sessions the same way a reset does. The example backend's `POST /users/:id/password` uses it.
+
+Either reset path also ends the user's MCP credentials: `mcp_` service tokens and MCP OAuth grants issued before the reset stop working, because they are bound to `tokenEpoch`. With `CommsApp` registered, push also stops going to devices the user registered before the reset until each device registers again.
 
-Better Auth password reset revokes that user's Better Auth sessions (`revokeSessionsOnPasswordReset`) and, when an app User exists, updates the JWT password and `tokenEpoch` so `POST /auth/login` cannot keep the old passport hash. JWT `POST /auth/resetPassword` does the reverse for Better Auth when `BetterAuthApp` is registered: it updates the Better Auth password and deletes Better Auth sessions. Console mail in development prints length only; check `CommsMessage` / console adapter logs for delivery, not the raw token in logger output. Request logs redact `password`, `newPassword`, `oldPassword`, `token`, and `refreshToken` in bodies and in URL query strings.
+Better Auth password reset revokes that user's Better Auth sessions (`revokeSessionsOnPasswordReset`) and, when an app User exists, updates the JWT password and `tokenEpoch` so `POST /auth/login` cannot keep the old passport hash. JWT `POST /auth/resetPassword` does the reverse for Better Auth when `BetterAuthApp` is registered: it updates the Better Auth password and deletes Better Auth sessions. Console mail in development prints length only; check `CommsMessage` / console adapter logs for delivery, not the raw token in logger output. Request logs redact password, token, secret, and code fields (any key name, any depth) in bodies and in URL query strings.

package/dist/docs/versioned/next/how-to/product-announcements.md

@@ -131,7 +131,7 @@ Interrupt frequency is enforced **client-side** in `AnnouncementNavigator` befor
 </AnnouncementNavigator>
 ```
 
-`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so seeded interrupts still appear on first launch.
+`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so an announcement an admin publishes appears on the next launch.
 
 | Prop | Default | Behavior |
 |------|---------|----------|
@@ -150,9 +150,11 @@ Paste YouTube or Loom URLs in the announcement `body` using markdown links or im
 
 ## Example app
 
-`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds:
+`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds two **drafts**:
 
 - **Staff modal (required)** — `audienceType: "staff"`, `displayMode: "modal"`, `acknowledgementPolicy: "required"` (`Example staff operations bulletin`)
 - **Patient banner (dismiss-only)** — `audienceType: "patient"`, `displayMode: "banner"`, `acknowledgementPolicy: "dismiss-only"` (`Example patient care tip`)
 
-The staff launch example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. Re-running the seed updates that example in place. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently so it no longer blocks the patient banner. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile); non-staff users therefore see only the patient banner interrupt under the default session cap of `1`.
+The seed keeps them as drafts so a fresh database (local dev or a PR preview) does not interrupt sign-in. Publish one from **Admin → Announcements** to see it. Re-running the seed updates both examples in place and sets them back to draft. The staff example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile).
+
+Release notes in the example app use [`WhatsNewBanner`](./whats-new-banner.md) instead of announcements.

package/dist/docs/versioned/next/how-to/rate-limiting.md

@@ -77,13 +77,13 @@ const uploadLimit = createRouteRateLimitMiddleware({
 | `POST /auth/forgotPassword`, `/auth/resetPassword`, `/resetPassword` | auth |
 | `POST /auth/sendVerification`, `/auth/verifyEmail` | auth |
 | `GET /auth/github`, `/auth/github/callback` | auth |
-| `{betterAuthBasePath}/sign-in/*`, `sign-up/*`, `forget-password`, `request-password-reset`, `reset-password`, `send-verification-email`, `verify-email`, `callback/*` | auth |
+| `{betterAuthBasePath}/sign-in/*`, `sign-up/*`, `forget-password`, `request-password-reset`, `reset-password`, `send-verification-email`, `verify-email`, `callback/*`, `oauth-handoff/*`, `one-time-token/*` | auth |
 | Trailing slash on those paths (`/auth/login/`) | same bucket as the unsuffixed path |
 | `GET`/`PATCH /auth/me` | api (600 / 15 min) |
 | modelRouter, admin, AI HTTP, `POST /mcp`, `POST /sync/mutate` | api |
 | `GET /health`, `/healthz`, `/openapi.json`, `/swagger` | skip |
 
-`rateLimit.skip` adds extra skips. Health/openapi/swagger always skip. Paths use Express `req.path` (not the raw request-target), without a trailing slash.
+`rateLimit.skip` adds extra skips. Health/openapi/swagger always skip. Paths use Express `req.path` (not the raw request-target), without a trailing slash. Classification also resolves `.` and `..` segments, including `%2e` forms, the way Better Auth's router does: a request is charged to the auth bucket when either the path as sent or its resolved form is a credential route (so `/api/auth/%2e/sign-in/email` counts as sign-in), and a path that contains dot segments never gets the health/openapi/swagger skip.
 
 JWT login/signup/refresh and password-reset paths skip access-token verification so a stale `Authorization` header cannot block credential exchange. Other routes still 401 on an expired JWT. Path matching uses Express `req.path` and ignores trailing slashes and letter case.
 

package/dist/docs/versioned/next/how-to/run-tests-locally.md

@@ -89,6 +89,56 @@ Full local suite: `bun run frontend:e2e`. Nightly load (`e2e-load` / `syncdb-loa
 not PR-blocking; run `bunx playwright test e2e/syncdb-loadlab.spec.ts` only when that job
 failed.
 
+`e2e/crossSiteBearer.spec.ts` and `e2e/crossSiteOAuth.spec.ts` have no CircleCI job: they need
+a web server built with `EXPO_PUBLIC_API_URL=http://127.0.0.1:4000`,
+`EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true` and `EXPO_PUBLIC_MOCK_OIDC_SIGN_IN=true`, a backend
+with `BETTER_AUTH_URL=http://127.0.0.1:4000`, `BETTER_AUTH_OAUTH_HANDOFF=true` and
+`MOCK_OIDC_ISSUER`, and the mock OIDC provider on `127.0.0.1:4555`. Naming either spec file (or
+setting `E2E_CROSS_SITE_BEARER=true`) makes `playwright.config.ts` start all three and run only
+the cross-site specs, so stop any other backend on 4000 and web server on 8082 first:
+`cd example-frontend && bunx playwright test e2e/crossSiteBearer.spec.ts e2e/crossSiteOAuth.spec.ts`.
+
+### Deployed bearer smoke (`deploy-frontend-preview`)
+
+`netlify-deploy.sh frontend` builds the web app with `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true`
+for production and previews. After the preview deploy, the `deploy-frontend-preview` job's
+"Smoke the deployed preview in web bearer mode" step runs `bun run smoke:deployed`
+(`playwright.smoke.config.ts`, `e2e/deployedBearer.smoke.ts`) against
+`https://pr-<n>--terreno-frontend.netlify.app`. It signs up a new `smoke-*@example.com` user on
+the PR's own backend, agrees to the consent forms, reloads, opens the profile, and fails if the
+API's origin holds a Better Auth session cookie. It also checks that the Google button's OAuth
+handoff start link redirects (to the provider, or back to `/login?error=provider_not_found`)
+instead of returning 404; `gcp-deploy.sh` sets `BETTER_AUTH_OAUTH_HANDOFF=true` on both backends.
+Production deploys never run it. To re-run it:
+
+1. Against the PR preview, which takes about 1 minute:
+
+   ```bash
+   cd example-frontend
+   SMOKE_BASE_URL=https://pr-<n>--terreno-frontend.netlify.app \
+     SMOKE_API_URL=https://pr-<n>---terreno-backend-example-7knxlrnpqq-uc.a.run.app \
+     bun run smoke:deployed
+   ```
+
+2. Against a local cross-site stack, which takes about 5 minutes because of the web export.
+   Start the backend with Better Auth on `127.0.0.1:4000`, then build and serve the web app
+   with the flag on `localhost:8082` (a different site):
+
+   ```bash
+   # Terminal 1, from example-backend/ (the replica-set mongod from step 2 above)
+   AUTH_PROVIDER=better-auth BETTER_AUTH_URL=http://127.0.0.1:4000 PORT=4000 \
+     BETTER_AUTH_OAUTH_HANDOFF=true \
+     MONGO_URI="mongodb://127.0.0.1:27017/terreno-smoke?replicaSet=rs0" \
+     TOKEN_SECRET=dev TOKEN_ISSUER=dev REFRESH_TOKEN_SECRET=dev SESSION_SECRET=dev \
+     bun run src/index.ts
+   # Terminal 2, from example-frontend/. --clear: Metro's cache can keep an earlier
+   # build's EXPO_PUBLIC_* values.
+   EXPO_PUBLIC_API_URL=http://127.0.0.1:4000 EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true \
+     bun run export --clear && bunx serve dist -s -l 8082
+   # Terminal 3, from example-frontend/
+   SMOKE_BASE_URL=http://localhost:8082 bun run smoke:deployed
+   ```
+
 CircleCI skips a shard no changed file can reach. Ask for the same verdict before
 pushing with `bun run check:e2e-affected` (see
 [the affected gate](circleci.md#e2e-affected-gate)).

package/dist/docs/versioned/next/how-to/use-syncdb-correctly.md

@@ -96,7 +96,7 @@ In tests, clean up with `Model.collection.deleteMany(...)`, which bypasses Mongo
 
 ### Deltas don't apply `queryFilter`
 
-Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` (or RBAC) per recipient. A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
+Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` per recipient (on an RBAC router: the role, `access.scope`, and `access.also.read`, the same checks REST read applies; subscriptions also apply `access.also.list`). A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
 
 ### Membership grants arrive late
 

package/dist/docs/versioned/next/how-to/vercel-function-websockets.md

@@ -0,0 +1,131 @@
+# Run Terreno WebSockets on Vercel Functions
+
+Operator notes for serving `@terreno/api` realtime (`RealtimeApp`, Socket.IO) and `@terreno/syncdb` deltas from a Vercel Function.
+
+> **Beta.** Vercel documents WebSockets on Functions as a public beta: [Vercel Functions WebSockets](https://vercel.com/docs/functions/websockets). That page is the vendor contract. This page only covers what it means for a Terreno backend. Re-read the Vercel page before you rely on it in production; the limits and behavior below were checked against it on 2026-10-11 (page last updated 2026-08-10).
+
+For the full deploy (projects, `vercel.json`, CI, CORS), see [Deploy to Vercel](deploy-to-vercel.md).
+
+## When to use this
+
+Use this page when `@terreno/api` itself runs on Vercel Functions, the all-in-one topology in [Deploy to Vercel](deploy-to-vercel.md#what-goes-where). Terreno's `example-backend` runs this way at `https://terrenolabs-backend.vercel.app`, alongside its Cloud Run deploy, while the topology is evaluated.
+
+You do not need this page when:
+
+- The web app is static on Vercel and the backend runs on a long-lived host such as Cloud Run (the split topology). Sockets go to that host; follow [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) and [Add WebSocket integration](websocket-integration.md).
+- You ship native apps through EAS. Native clients connect to whichever backend URL they were built with.
+- You mean the Vercel AI SDK. `@terreno/ai` uses the Vercel AI SDK for model calls; that library has nothing to do with Vercel hosting or this feature.
+
+## Prerequisites
+
+- **Fluid compute on.** Vercel requires it for WebSockets. It is the default for projects created on or after April 23, 2025. Confirm in **Project → Settings → Functions → Fluid Compute**, or set `"fluid": true` in `vercel.json` ([Fluid compute](https://vercel.com/docs/fluid-compute)). Without Fluid compute, do not host Terreno sockets on Functions.
+- **A max duration that fits your product.** Every socket closes when its Function hits max duration. With Fluid compute the default is 300 seconds on all plans; Pro and Enterprise can raise it to 800 seconds ([limits](https://vercel.com/docs/functions/limitations#max-duration)). Set the project default in **Settings → Functions → Function Max Duration**.
+- **A MongoDB replica set** reachable from Vercel. Change streams still drive sync deltas and live feature flags, same as any other host ([deployment baseline](../explanation/deployment-baseline.md)). Vercel has no static egress IPs unless you buy Secure Compute or Static IPs, so Atlas must accept connections from Vercel's dynamic ranges.
+- **Redis**, if you rely on direct socket-to-socket emits or rooms across instances (see [State](#state)).
+
+## Socket.IO on a Function
+
+Vercel serves an exported Node `http.Server` as-is, WebSocket upgrades included. Vercel's own Socket.IO snippet is the vendor shape: create an `http.Server`, attach Socket.IO, `export default server`. See [Set up a WebSocket endpoint](https://vercel.com/docs/functions/websockets#set-up-a-websocket-endpoint).
+
+For Terreno, the shape is the same, but `TerrenoApp` attaches the Express app and Socket.IO for you. Pass it a server it does not listen on, through `httpServer`. `example-backend` does this in two files:
+
+- `example-backend/src/vercelServer.ts`: `createVercelServer()` calls `createServer()` and then `start(false, server)`.
+- `example-backend/src/app.ts`: the Vercel entry. It awaits `createVercelServer()` and does `export default server`.
+
+`start(skipListen, existingServer)` in `example-backend/src/server.ts` treats a host-owned server differently from a server it binds itself:
+
+| Behavior | Cloud Run (`src/index.ts`, owns the listener) | Vercel (`src/app.ts`, host-owned server) |
+|---|---|---|
+| Binds `PORT` | Yes, before Mongo connects | No |
+| Waits for sync indexes and startup migrations before serving | No, binds first | Yes, awaits `terraApp.whenReady()` before returning |
+| In-process jobs worker | Unless `JOBS_START_WORKER=false` | Never |
+| Harness runner | Yes | Never |
+
+`RealtimeApp` and `SyncApp` stay registered exactly as on any other host. Socket auth (Better Auth session or JWT) runs on the upgrade request, the same as today.
+
+Export the `http.Server`, not the Express app. Vercel would wrap a bare Express app in its own server, and `/socket.io/` would never be mounted.
+
+### Client transport
+
+Socket.IO clients default to HTTP long-polling first. Vercel's page says the client must use the WebSocket transport (`transports: ['websocket']`). On Functions, each polling request is an ordinary invocation that can land on any instance, so a polling handshake can fail with `Session ID unknown`. Do not use long-polling against a Function.
+
+Both Terreno clients default to `["polling", "websocket"]` (polling helps local dev survive server restarts). Override it for Vercel:
+
+```typescript
+import {useSocketConnection} from "@terreno/rtk";
+import {createSyncDb} from "@terreno/syncdb";
+
+const {socket} = useSocketConnection({
+  baseUrl,
+  getAuthToken,
+  shouldConnect: Boolean(userId),
+  transports: ["websocket"],
+});
+
+export const syncDb = createSyncDb({
+  // ...name, collections, authProvider, baseUrl
+  socketTransports: ["websocket"],
+});
+```
+
+`example-frontend` reads the list from `expoConfig.extra.SOCKET_TRANSPORTS` (`example-frontend/store/socketTransports.ts`), and its Vercel build writes `SOCKET_TRANSPORTS=websocket` into `app.json`. The Socket.IO `path` stays the default `/socket.io/`; the backend owns every path on its Vercel project.
+
+## Reconnects
+
+A connection closes when the Function reaches max duration: 300 seconds by default. Clients must reconnect, resubscribe, and reload state.
+
+- `@terreno/rtk` `useSocketConnection` reconnects with backoff (5 attempts, 1 to 5 seconds) and reconnects on token refresh.
+- `@terreno/syncdb` resubscribes its streams after the socket reconnects and catches up through its reconcile path.
+
+A reconnect may land on a different instance, or on a newer deployment. Nothing in the client may assume the server remembers it.
+
+The app looks fine while this is broken. REST calls, login, and navigation all work with no socket at all. What breaks is quieter: other users' edits stop appearing, live feature flags stop flipping, and syncdb falls back to its periodic reconcile. Check the socket explicitly (see [Verify](#verify)).
+
+## State
+
+Vercel pins one connection to one Function instance for its lifetime, and Fluid compute lets one instance hold many connections. New connections, including reconnects, are not guaranteed to reach the same instance. After a deploy, new connections can reach the new deployment while old ones stay on the previous deployment until they close.
+
+What that means for Terreno:
+
+- **Sync deltas work across instances.** Each instance runs its own MongoDB change-stream watchers, so a write on any instance reaches the sockets on every instance through the database. You pay for one set of watchers per instance.
+- **In-memory rooms and direct emits do not.** `socket.join` and `io.to(room).emit` reach only sockets on the same instance. Use a cross-instance Socket.IO adapter for those. `RealtimeApp` accepts `adapter: "redis"` with `redisUrl` (or `VALKEY_URL` / `REDIS_URL`), but it only logs the URL; it does not install an adapter. Install `@socket.io/redis-adapter` yourself and call `io.adapter(...)` on `realtimeApp.getIo()` (see `api/src/realtime/realtimeApp.ts`).
+- **Presence, counters, and pub/sub** belong in Redis or MongoDB, not process memory.
+- **Old and new deployments overlap.** For up to one max duration after a deploy, old instances still serve sockets. Keep socket event shapes backward compatible across one deploy.
+
+## Limits and pricing
+
+WebSocket connections follow normal Function [limits](https://vercel.com/docs/functions/limitations) and [pricing](https://vercel.com/docs/functions/usage-and-pricing). You pay Function usage for as long as each socket stays open, plus Fast Data Transfer and Fast Origin Transfer for the bytes sent. Every logged-in Terreno client holds a socket for as long as the app is open, so a busy app can cost much more on Functions than the same app on a long-lived host. Check usage in the Vercel dashboard during evaluation.
+
+Other limits that matter for a Terreno backend: 4.5 MB request and response bodies, and 1,024 file descriptors shared across concurrent work on one instance. Sockets, MongoDB connections, and outbound HTTP all use descriptors.
+
+## Verify
+
+1. Open the deployed web app, sign in, and open DevTools → **Network** → filter **WS**.
+2. Expect one request to `/socket.io/?EIO=4&transport=websocket` with status **101**, and frames flowing in its **Messages** tab.
+3. Filter by `transport=polling`. There should be no polling requests. Any hit means a client still uses the default transports and will fail intermittently.
+4. Leave the tab open past the Function max duration. The socket closes and a new 101 appears within a few seconds.
+5. For more detail, set `WEBSOCKETS_DEBUG` to the string `"true"` in `app.json` `extra` (read by `rtk/src/constants.ts`) and rebuild, then watch the console for connect and disconnect logs. On the backend, set the `WEBSOCKETS_DEBUG=true` environment variable (`example-backend/src/conf.ts`) and watch the Vercel runtime logs.
+
+From a shell, the upgrade can be checked without a browser:
+
+```bash
+curl -i -N --http1.1 \
+  -H "Connection: Upgrade" -H "Upgrade: websocket" \
+  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
+  "https://terrenolabs-backend.vercel.app/socket.io/?EIO=4&transport=websocket"
+```
+
+Expect `HTTP/1.1 101 Switching Protocols`.
+
+## Out of scope
+
+- Next.js `experimental_upgradeWebSocket` from `@vercel/functions`. Terreno's server is Express, not Next.js.
+- `Bun.serve()` and Python (FastAPI, Django Channels, Flask-Sock) examples. They are on the Vercel page. The Terreno function runs on Node (`nodejs24.x`), not Bun.
+- Replacing MongoDB change streams with Vercel Queues or a KV pub/sub as the sync protocol.
+
+## Related
+
+- [Deploy to Vercel](deploy-to-vercel.md)
+- [Add WebSocket integration](websocket-integration.md)
+- [Use syncdb correctly](use-syncdb-correctly.md)
+- [Deployment baseline](../explanation/deployment-baseline.md)

package/dist/docs/versioned/next/how-to/websocket-integration.md

@@ -137,24 +137,56 @@ Add to your `app.json` or environment:
 }
 ``````
 
-### 2. Set Up Connection Hook
+### 2. Register the token source
 
-Create a custom hook to manage the connection:
+The hook reads its handshake token from the token source the app registers once at startup
+with `setTokenSource`. A JWT app registers nothing: the default source reads the JWT in
+storage. A Better Auth app registers the adapter it builds for syncdb:
+
+``````typescript
+// store/tokenSource.ts: import once from the app entry, before the store is created
+import {setTokenSource} from "@terreno/rtk";
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
+import {authClient} from "@/lib/betterAuth";
+
+setTokenSource(betterAuthAdapter(bridgeBetterAuthReactClient(authClient)));
+``````
+
+With `webAuth: "bearer"`, also pass the adapter `getBearerToken`
+([syncdb adapter](../reference/syncdb.md#createsyncdb-configuration)).
+
+With a token source, the hook:
+
+- reads `getToken()` on every connect and reconnect;
+- calls `refresh()` once when the server rejects the token, then reconnects, and stops after a
+  second rejection (`onConnectError` fires). With no `refresh`, or a failed one, it stops at
+  once;
+- reconnects with the new token when `onAuthChange` fires, and disconnects when there is no
+  token.
+
+To use a different source for one socket, pass it as `tokenSource`. Passing the legacy
+`getAuthToken` getter instead turns the token source off for that hook. See
+[Token source](../reference/legacy/rtk.md#token-source).
+
+### 3. Set Up Connection Hook
+
+Create a custom hook to manage the connection. A Better Auth app gates `shouldConnect` on
+`selectBetterAuthUserId` instead of the JWT user id:
 
 ``````typescript
 // hooks/useWebSocket.ts
-import {useSocketConnection, getAuthToken, baseWebsocketsUrl} from "@terreno/rtk";
-import {useSelectCurrentUserId} from "@/store";
+import {useSocketConnection, baseWebsocketsUrl} from "@terreno/rtk";
+import {selectBetterAuthUserId} from "@terreno/rtk";
+import {useSelector} from "react-redux";
 import {useCallback} from "react";
 import * as Sentry from "@sentry/react-native";
 
 export const useWebSocket = () => {
-  const userId = useSelectCurrentUserId();
+  const userId = useSelector(selectBetterAuthUserId); // JWT apps: useSelectCurrentUserId()
   
   const {socket, isSocketConnected} = useSocketConnection({
     baseUrl: baseWebsocketsUrl,
     shouldConnect: !!userId,
-    getAuthToken,
     onConnect: () => {
       console.info("[WebSocket] Connected");
     },
@@ -176,7 +208,23 @@ export const useWebSocket = () => {
 };
 ``````
 
-### 3. Subscribe to Events in Components
+#### Transports
+
+`useSocketConnection` starts with HTTP long-polling and upgrades to WebSocket (`transports: ["polling", "websocket"]`), so a restarting dev server does not fail the first handshake. Polling needs every request of a session to reach the same server process. Hosts without session affinity, such as Vercel Functions, need WebSocket only:
+
+``````typescript
+useSocketConnection({
+  baseUrl,
+  shouldConnect: !!userId,
+  transports: ["websocket"],
+});
+``````
+
+`@terreno/syncdb` takes the same list as `createSyncDb({socketTransports: ["websocket"]})`. Cloud Run with `--session-affinity` works with the default. See [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md).
+
+`baseWebsocketsUrl` replaces `api.` with `ws.` in the API host (`https://api.example.com` becomes `ws.example.com`), for deployments that run sockets on a separate host. If sockets are served by the API host itself, as on Vercel, pass `baseUrl` instead.
+
+### 4. Subscribe to Events in Components
 
 ``````typescript
 // screens/TodoList.tsx
@@ -226,7 +274,7 @@ export const TodoListScreen = () => {
 };
 ``````
 
-### 4. Show Connection Status (Optional)
+### 5. Show Connection Status (Optional)
 
 ``````typescript
 import {useWebSocket} from "@/hooks/useWebSocket";
@@ -361,7 +409,8 @@ This logs:
 **Cause:** Token not provided or invalid.
 
 **Solution:**
-1. Ensure `getAuthToken()` returns a valid JWT
+1. Ensure the token source returns a valid token: `await getTokenSource()?.getToken()` (or
+   `getAuthToken()` on a JWT app with no source registered)
 2. Check backend token verification logic
 3. Enable `WEBSOCKETS_DEBUG` to see token status
 
@@ -373,6 +422,13 @@ This logs:
 - `useSocketConnection` automatically reconnects (5 attempts)
 - Tokens are refreshed if expiring within 60 seconds
 - Toast notifications inform users after 9+ seconds
+- On Vercel Functions, every socket closes at the Function max duration (300s by default); see [reconnects](vercel-function-websockets.md#reconnects)
+
+### "Session ID unknown" or a 400 on `transport=polling`
+
+**Cause:** Polling requests for one session reached different server instances (no session affinity).
+
+**Solution:** Pass `transports: ["websocket"]` to `useSocketConnection` and `socketTransports: ["websocket"]` to `createSyncDb`, or enable session affinity on the host.
 
 ### Events not received
 
@@ -414,4 +470,5 @@ This logs:
 - [@terreno/syncdb Reference](../reference/syncdb.md) — Local-first data layer (replaces RTK for synced collections)
 - [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md) — RTK Query utilities during the support window
 - [Authentication Architecture](../explanation/authentication.md) — JWT system deep-dive
+- [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md) — Vercel's WebSocket beta: transports, reconnects, cross-instance state
 - [Socket.io Documentation](https://socket.io/docs/v4/) — Official Socket.io docs

package/dist/docs/versioned/next/how-to/whats-new-banner.md

@@ -0,0 +1,55 @@
+# Show release notes with WhatsNewBanner
+
+Use `WhatsNewBanner` from `@terreno/ui` to tell people about a new release without blocking
+them. The banner reads "What's new in 57.16.2" until the viewer opens or dismisses it, then
+stays hidden until a newer release is listed. Use it instead of a required announcement modal
+for routine release notes.
+
+## Add the banner
+
+1. Build a list of releases, newest first. Each entry has a `version`, Markdown `body`, and
+   an optional `date`:
+
+   ```typescript
+   import type {WhatsNewRelease} from "@terreno/ui";
+
+   export const RELEASES: WhatsNewRelease[] = [
+     {body: "### Fixed\n\n- Exports finish on slow networks.", date: "2026-10-13", version: "2.4.1"},
+     {body: "### Added\n\n- Bulk-complete todos.", date: "2026-10-01", version: "2.4.0"},
+   ];
+   ```
+
+2. Render it near the top of a screen people see after signing in:
+
+   ```tsx
+   import {WhatsNewBanner} from "@terreno/ui";
+
+   <WhatsNewBanner releases={RELEASES} testID="home-whats-new-banner" />
+   ```
+
+3. Open the app. The banner shows the latest version and how many earlier releases the viewer
+   has not seen. **See what's new** opens a modal with the notes for every unseen release.
+
+The last seen version is stored on the device under `@TerrenoUI:whatsNew:lastSeenVersion`.
+Pass `storageKey` to keep separate histories, for example one per product.
+
+## Generate releases from CHANGELOG.md
+
+The example app builds its list from the repository changelog, so every release appears in the
+banner without hand edits:
+
+- `bun run whats-new:generate` writes the 10 most recent `CHANGELOG.md` releases to
+  `example-frontend/constants/whatsNew.generated.json`. Repo-relative links and `(#123)` pull
+  request numbers become GitHub URLs.
+- `bun run changelog:assemble <version>` regenerates that file when it cuts a release.
+- `bun run check:whats-new` fails when the file does not match `CHANGELOG.md`. CircleCI runs it
+  in the lint job, next to `check:changelog`.
+
+`example-frontend/constants/whatsNew.ts` types the JSON as `WhatsNewRelease[]`, and
+`SyncTodosScreen` renders the banner above the todo list.
+
+## When to use announcements instead
+
+`WhatsNewBanner` is static and per device. Use [product announcements](./product-announcements.md)
+when you need audience targeting, required acknowledgement, scheduling, or analytics. Props are
+listed in the [UI reference](../reference/ui.md#whatsnewbanner).

package/dist/docs/versioned/next/implementationPlans/agent-ui-asks.md

@@ -115,6 +115,8 @@ How asks and blocks divide the work:
 | D25 | Compact surface mode | `surface: "compact"` on `/gpt/prompt` or `turn` offers only `ask_confirm` and a narrowed `ask_choice` (`select: one`, 2–3 options, labels ≤ 20), and appends one prompt line: keep replies to two short sentences and ask only yes/no or up to three short options. | assumed |
 | D26 | Button order and safety | Primary answer first, Cancel last. A `destructive` confirm marks its approve button `destructive`, so Apple Watch Double Tap, which triggers the first non-destructive action, can never approve it. | assumed |
 
+D27 note: Markdown images in `text` blocks and plain replies bypass `imageHosts`; this is documented as a known gap in `docs/explanation/agent-ui-asks.md`.
+
 ## Architecture
 
 ```

package/dist/docs/versioned/next/implementationPlans/ai-agents-and-failover.md

@@ -60,7 +60,7 @@ App
         → AIRequest.logRequest (served model id + failover metadata)
 ```
 
-`AIService` stays the only path that talks to the Vercel SDK for logged calls. Agent does not call `generateText` / `streamText` from `ai` directly.
+`AIService` stays the only path that talks to the Vercel AI SDK for logged calls. Agent does not call `generateText` / `streamText` from `ai` directly.
 
 Failover is a `LanguageModel` Proxy (same idea as `withStrippedJsonFencesModel` in `aiService.ts`): intercept `doGenerate` and `doStream`, preserve other properties from the **primary** model (`specificationVersion`, `provider`, `supportedUrls`).
 

package/dist/docs/versioned/next/implementationPlans/app-mcp-server.md

@@ -65,7 +65,7 @@ When this is done, an operator can:
 | Q2 | Primitive shape | **Factories:** `defineMCPTool` / `defineMCPPrompt` / `defineMCPResource` wrapping `registerMCP*`. |
 | Q3 | Default endpoint | **Keep `/mcp`.** Additive capabilities. No rename. |
 | Q4 | Multiple servers | **Yes, v1.** Named mounts with explicit include lists. Default `/mcp` remains the union of CRUD + globally registered primitives. Extra servers are opt-in and do not auto-include every model tool. |
-| Q5 | Auth | **Bearer (JWT + Better Auth session) plus OAuth 2.1 for MCP** via Better Auth (`@better-auth/mcp` + `@better-auth/oauth-provider`). Same User as REST after token exchange. JWT-only apps keep bearer-only; OAuth metadata mounts only when Better Auth is enabled. |
+| Q5 | Auth | **Bearer (JWT + Better Auth session) plus OAuth 2.1 for MCP** via Better Auth (`@better-auth/mcp` + `@better-auth/oauth-provider`). Same User as REST after token exchange. JWT-only apps get the Terreno-native `mcpOAuth` authorization server instead (#1573); with `mcpOAuth` off they keep bearer-only and mount no OAuth metadata. |
 | Q6 | Tool metadata | **MCP spec hints:** `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, plus optional `outputSchema` + `structuredContent`. |
 | Q7 | Conditional register | **`shouldRegister(user)`** (and optional `shouldRegister: false`). Filter list methods and reject call/get/read if hidden. |
 | Q8 | Response helper | **`mcpResult.text` / `.json` / `.error`.** Images/audio out. |
@@ -161,7 +161,7 @@ Remote MCP clients (Claude connectors, ChatGPT, Cursor HTTP) expect **OAuth 2.1*
 5. Extend `extractUserFromHeaders` to accept an OAuth access token on `Authorization: Bearer`, resolve it through Better Auth, then load the app `User` by `betterAuthId` — same mapping as session cookies today.
 6. Keep JWT verification as a fallback so Inspector, tests, and `useMCPTools` keep working with session/JWT bearer.
 
-**When Better Auth is off (JWT-only):** do not mount OAuth metadata. Bearer JWT behavior is unchanged. Docs state that ChatGPT-class connectors need Better Auth.
+**When Better Auth is off (JWT-only):** set `mcpOAuth: {enabled: true, …}` to mount the Terreno-native OAuth 2.1 authorization server ([Enable MCP OAuth](../how-to/enable-mcp-oauth.md)). It serves the RFC 9728 and RFC 8414 documents, authorize/consent, token, and revoke, and `/mcp` answers unauthenticated requests with the 401 challenge. Dynamic client registration is a second opt-in (`dynamicClientRegistration: true`), off by default because the endpoint is unauthenticated and lets anyone create a client; without it the app creates `McpOAuthClient` documents itself. Revoking a token family writes a tombstone that `McpOAuthToken.issue` honors, so in-flight exchanges cannot revive it. The app hosts the consent screen. Bearer JWT keeps working. With `mcpOAuth` off, no OAuth metadata mounts and bearer behavior is unchanged.
 
 **Not in this IP:** social login providers (already documented); infra-mcp’s RBAC/elicitation; replacing Passport JWT for REST.
 
@@ -250,7 +250,7 @@ Tracer: example-backend custom tool already exists (`users_todo_statuses`). Add
 - Wire plugin in Better Auth setup used by `BetterAuthApp`.
 - RFC 9728 + 401 `WWW-Authenticate` on `/mcp`.
 - `extractUserFromHeaders` accepts OAuth access tokens.
-- JWT-only apps unchanged.
+- JWT-only apps unchanged by this phase: they use the Terreno-native `mcpOAuth` server (#1573, [Enable MCP OAuth](../how-to/enable-mcp-oauth.md)). Reuse its well-known builders (`buildProtectedResourceMetadata`, `buildAuthorizationServerMetadata`) and `/mcp` challenge (`sendMcpOAuthChallenge`) from `api/src/mcp/oauthMetadata.ts`, which does not depend on the JWT authorization-server routes, so both stacks share one code path.
 - How-to `docs/how-to/secure-app-mcp.md`; reference well-known paths.
 - Tests with Better Auth test instance: no token → 401 challenge; valid access token → `tools/list` as that user.
 
@@ -311,7 +311,10 @@ None. Additive APIs. `registerMCPTool` signature may gain optional fields only.
 - [ ] `invokeMCPTool` can assert a successful custom tool in Bun tests
 - [ ] `MCPService` can list tools over Streamable HTTP against `mountMCPServer`
 - [ ] Better Auth on: unauthenticated `/mcp` returns 401 with resource metadata; a valid OAuth access token runs tools as that user
-- [ ] JWT-only: existing bearer behavior unchanged; no OAuth well-known required
+- [ ] JWT-only with `mcpOAuth` off: existing bearer behavior unchanged; no OAuth well-known mounted
+- [ ] JWT-only with `mcpOAuth` on: RFC 9728/8414 documents mount, unauthenticated `/mcp` returns the 401 challenge, and bearer JWT still works
+- [ ] `mcpOAuth` on without `dynamicClientRegistration`: `/oauth/register` is 404, metadata has no `registration_endpoint`, and an app-created client completes the flow
+- [ ] A revoked token family stays revoked when a concurrent refresh or code exchange issues after the revoke
 - [ ] Hosted `terreno_generate_mcp_tool|prompt|resource` return TypeScript matching the factories
 - [ ] Docs: two MCP layers; prompts/resources; Inspector; OAuth vs bearer; generator tools
 - [ ] `registerMCPTool` without new fields still typechecks and runs

package/dist/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/dist/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). |