@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/next/explanation/admin-interface.md

@@ -56,7 +56,11 @@ legacy `AdminAuditLog`, `audit-log`, and `audit-events` names. Jobs is a custom
 screen (`name: "jobs"`); the shell lifts it the same way.
 
 Below 768px the rail becomes a hamburger drawer. The main column is a body-style
-canvas (`neutral-050`). Nested `Page` screens use `color="transparent"` and
+canvas (`neutral-050`, or `neutral-900` in dark mode so `surface.base` cards stand out).
+The colorful teal rail has no dark palette, so dark mode always uses the clinical rail.
+Host apps must give React Navigation a theme that follows the Terreno color scheme
+(the example app uses `buildNavigationTheme` with a transparent background inside the
+admin `Stack`); otherwise its default light screen containers cover the canvas. Nested `Page` screens use `color="transparent"` and
 `padding={0}` so cards sit on that canvas. Custom screens wrap content in
 `AdminScreenPage`; the back arrow uses `router.push(routeBase)` rather than
 `router.back()` because sidebar clicks do not always leave history on web.

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

@@ -297,3 +297,4 @@ plain text, so an ask cannot show a chart or table above its control yet. Both l
   payment card numbers, API keys, or other secrets.
 - **HTML is display-only and opt-in.** An `html` block can be used for XSS, phishing, exfiltration, or clickjacking if it runs as part of the host page. The server allows it only when `uiBlocks.html` is on, strips scripts, event handlers, forms, frames, `meta`/`base`/`link`, anchor `href`s, and every URL except `data:image`, then stores that cleaned document. The client draws it in a sandboxed frame with no JavaScript and no navigation, labeled as an agent-generated preview, and only after the reply has finished.
 - **Image hosts are an allowlist.** An `image` block can leak conversation data by requesting a URL the model chooses. `data:image` URLs and `file:` refs are always allowed. An `https` URL loads only when its hostname is in `uiBlocks.imageHosts`. The default list is empty, so a hostile prompt cannot point the image at a server the app did not name.
+- **The image allowlist does not cover Markdown.** `imageHosts` applies to `image` blocks, `gallery` tiles, and `list` item images only. A Markdown image (`![alt](https://…)`) inside a `text` block, or in a plain assistant reply when `uiBlocks` is off, renders through `MarkdownView` and loads from any URL the model writes (decision D27 kept the existing Markdown behavior). So a prompt-injected reply can still make the client request an attacker's URL through Markdown, and that request can carry conversation data in its path or query. Apps that need the allowlist guarantee for every image should also restrict Markdown images. One approach, not built today, is an `imageHosts`-aware image handler on `MarkdownView` that drops or placeholders images whose host is not on the list, wired to the same hosts the server passes to `uiBlocks.imageHosts`.

package/dist/docs/versioned/next/explanation/authentication.md

@@ -12,7 +12,7 @@ Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On t
 
 Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
 
-**MCP service tokens** are a third, opt-in credential. They authenticate the consumer app's `POST /mcp` only. They are not Better Auth sessions, not JWTs, and not a REST personal-access-token. Enable them with `mcpServiceTokens` on `TerrenoApp`. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
+**MCP service tokens** are a third, opt-in credential. They authenticate the consumer app's `POST /mcp` only. They are not Better Auth sessions, not JWTs, and not a REST personal-access-token. Enable them with `mcpServiceTokens` on `TerrenoApp`. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md). **MCP OAuth access tokens** are the fourth, for remote clients that need an OAuth flow; enable them with `mcpOAuth` ([Enable MCP OAuth](../how-to/enable-mcp-oauth.md)).
 
 ## When to choose which
 
@@ -36,14 +36,15 @@ Modern session-based authentication with built-in social OAuth support.
 2. User chooses social provider (Google, GitHub, Apple) or email/password
 3. Backend redirects to OAuth provider or validates credentials
 4. Better Auth creates session in MongoDB
-5. Frontend receives session cookie (web) or bearer session token (native)
-6. On the first authenticated request, session middleware looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`)
-7. `req.user` is that app document for subsequent `modelRouter` permissions
+5. Frontend receives a session cookie (web, default), a bearer session token (native), or, on web with `webAuth: "bearer"`, a bearer token from the `set-auth-token` header. Bearer on web is the option when the web app and the API are on different sites, where browsers block the third-party session cookie. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
+6. On the first authenticated request or socket handshake, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`). An email alone does not prove someone owns an existing account, so an existing app `User` with the same email is linked only after Better Auth verifies that email, and never when the row already belongs to another Better Auth account. Linking removes a legacy password the row never proved with a verified email. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
+7. `req.user` is that app document for subsequent `modelRouter` permissions. A session whose app `User` has `disabled: true` no longer authenticates: `req.user` stays unset, so protected routes answer 401 and disabling an account ends its live sessions. Better Auth's own routes, such as sign-out, still work
 
 Email/password create omits `oauthProvider`. Apps that never use social login can keep `strict: "throw"` without declaring that field. OAuth create sets `oauthProvider` and the User schema must declare it.
 
 **Key properties:**
 - Session-based (cookies / bearer session) vs. stateless JWT
+- A session cookie is sent with requests other sites start, so a cookie-authenticated write counts only when it comes from a trusted origin. Bearer tokens are never sent automatically, so they need no such check
 - Built-in OAuth providers with PKCE
 - `betterAuthAdapter` for syncdb socket auth
 - `sync:auth-expired` socket event when the session is no longer valid
@@ -85,10 +86,16 @@ OAuth 2.0 authentication with GitHub.
 5. GitHub redirects back to `GET /auth/github/callback`
 6. Backend verifies authorization code with GitHub
 7. Backend finds/creates user, issues JWT tokens
-8. Backend redirects to `returnTo` URL with tokens as query params
+8. Backend redirects to `returnTo` with tokens in the URL fragment, only when `returnTo` matches
+   `githubAuth.allowedReturnTo`; otherwise it returns the tokens as JSON
+
+Every flow carries an OAuth `state` value bound to the starting browser by a signed, HttpOnly,
+short-lived cookie. The callback rejects a response without matching state.
 
 **Account Linking:**
-- Authenticated users can link their GitHub account via `GET /auth/github/link`
+- Authenticated users can link their GitHub account via `GET /auth/github/link`. The bearer
+  user's ID is recorded in the signed state, and the callback links only to that user, never to
+  a session or token present on the callback request
 - Multiple authentication methods can be attached to one user account
 - Users must have a password set before unlinking GitHub
 
@@ -98,12 +105,26 @@ OAuth 2.0 authentication with GitHub.
 
 Personal `mcp_` keys for remote MCP clients (Perplexity, Cursor JSON config) that cannot hold a session cookie. `TerrenoApp` must set `mcpServiceTokens`. Users mint keys from `POST /mcp/service-tokens` or **Profile → MCP connections**. The plaintext secret is returned **once**; the database stores SHA-256 `tokenHash`.
 
-`extractUserFromHeaders` on `/mcp` tries a `mcp_` Bearer first, then Better Auth, then JWT. A match loads the owning `User` and updates `lastUsedAt`. Revoked, expired, or disabled-user keys resolve to no user. The same Bearer is ignored on REST, sync, admin, and on the mint/list/revoke routes (a key cannot mint another key).
+`extractUserFromHeaders` on `/mcp` tries a `mcp_` Bearer first, then Better Auth, then JWT. A match loads the owning `User` and updates `lastUsedAt`. Revoked, expired, or disabled-user keys resolve to no user, and so does a key minted before the user's last password reset or session revocation (`tokenEpoch` changed since it was issued). MCP OAuth grants end the same way. The same Bearer is ignored on REST, sync, admin, and on the mint/list/revoke routes (a key cannot mint another key).
 
-This is not OAuth 2.1. Interactive MCP clients that cannot send a static key wait for the app MCP OAuth work ([app MCP server](../implementationPlans/app-mcp-server.md)). It is also not the hosted `@terreno/mcp` codegen server ([MCP server reference](../reference/mcp-server.md)).
+This is not OAuth 2.1; interactive clients use MCP OAuth below. It is also not the hosted `@terreno/mcp` codegen server ([MCP server reference](../reference/mcp-server.md)).
 
 **Learn more:** [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md)
 
+### MCP OAuth (opt-in, `/mcp` only)
+
+Claude.ai connectors and ChatGPT apps cannot paste a static key; they run OAuth 2.1 discovery, get a client id (pre-created by the app, or through dynamic client registration), and run the authorization-code flow with PKCE. With `mcpOAuth` on `TerrenoApp`, Terreno is that authorization server for a JWT app. Terreno is backend-only, so the app hosts the consent screen and approves or denies with the signed-in user's JWT. The client then gets opaque, short-lived `mcpat_` access tokens and rotating `mcprt_` refresh tokens, stored as hashes. On `/mcp`, `extractAuthFromHeaders` resolves `mcpat_` alongside the other credentials, and a request with none gets a `401` RFC 9728 challenge that starts discovery. OAuth access tokens are ignored on REST, like service tokens.
+
+Every part of it is opt-in. Without `mcpOAuth.enabled` there are no OAuth routes, discovery documents, or challenge. Dynamic client registration is a second flag (`dynamicClientRegistration`) because an open registration endpoint lets anyone create a client, which leaves the consent screen as the only defense against a phishing client. With it off, the app creates its clients as `McpOAuthClient` documents.
+
+Revocation works on token families: every pair rotated from one approval shares a `familyId`. Revoking a family writes a tombstone before revoking its pairs, and issuing into a tombstoned family fails, checked again after the new pair is written. That closes the races where a refresh or code exchange that already passed its single-use check would otherwise issue a live pair after a concurrent reuse revoked the family.
+
+**Learn more:** [Enable MCP OAuth for a JWT app](../how-to/enable-mcp-oauth.md)
+
+### Which credential authenticated the request
+
+`getCurrentRequestContext()?.credential` is `"jwt"`, `"better-auth-session"`, `"mcp-service-token"`, or `"oauth"`. Service tokens and OAuth tokens are delegated: an agent holds them on the user's behalf. Permission code that grants broad access (an admin bypass, cross-tenant reads) should check the credential and keep that access to the user's own session. See [Request credential](../reference/api.md#request-credential).
+
 ### Anonymous Strategy (JWT — legacy)
 
 Allows limited access without authentication.
@@ -131,8 +152,11 @@ modelRouter(Model, {
 **Access Token (short-lived)**
 - Default expiration: 15 minutes (`TOKEN_EXPIRES_IN`)
 - Used for API requests
-- Included in `Authorization: Bearer <token>` header
+- Included in `Authorization: Bearer <token>` header (or the `jwt` cookie). Other
+  `Authorization` schemes are never read as a JWT
 - Contains user ID and permissions in payload
+- Rejected with 401 once the user is `disabled`. Login, refresh, password reset, and GitHub
+  sign-in also stop issuing tokens to a disabled user, so disabling an account ends its access
 
 **Refresh Token (long-lived)**
 - Default expiration: 30 days (`REFRESH_TOKEN_EXPIRES_IN`)
@@ -248,6 +272,15 @@ permissions: {
 }
 ``````
 
+### Owner scope on writes
+
+Object permissions such as `IsOwner` first run against the document as it was loaded. On
+create and update, modelRouter also checks the document as it will be written. A user cannot
+create a record that names another user as `ownerId`, or move their own record to another
+user, even when the router has no `preUpdate` that strips `ownerId`. RBAC routers get the same
+check from their role scopes and `access.scope`. Admins can still reassign owners. See
+[modelRouter write scope](../reference/api.md#modelrouter-write-scope).
+
 ### Custom Permissions
 
 Create custom permission functions:
@@ -264,6 +297,23 @@ modelRouter(Model, {
 });
 ``````
 
+### Why changing the email needs the current password
+
+The account email is where password-reset links go. If a session alone could change it, anyone
+holding a stolen or borrowed session could move the recovery address to a mailbox they control,
+request a reset, and keep the account after the session ends. So `PATCH /auth/me` asks for the
+current password before it changes the mailbox, and then tells the old address that the change
+happened. The notice holds no link or token, so forwarding it or leaving it in an inbox exposes
+nothing that acts on the account.
+
+The check uses whichever password the user has: the passport-local-mongoose hash, or, for a
+Better Auth user with no passport hash, the Better Auth credential. A user who signed up only
+through a social provider has no password to confirm, so they must set one through the reset
+flow first. Wrong attempts share the passport lockout with login rather than a separate counter.
+The new email is not held as pending and existing sessions are not ended; the notice to the old
+address is the signal that lets the owner react. Status codes and messages are in the
+[API reference](../reference/api.md#changing-the-email-on-patch-authme).
+
 ## Security Best Practices
 
 ### Backend
@@ -294,7 +344,7 @@ modelRouter(Model, {
 - Validate tokens before making authenticated requests
 
 ❌ **Don't:**
-- Store tokens in localStorage on web (use httpOnly cookies in production)
+- Store tokens in localStorage on web when frontend and API share a site (use httpOnly cookies). When they are on different sites, Better Auth's `webAuth: "bearer"` mode is the supported way to keep a web token: it accepts the XSS and shared-device risk of web storage, and `bearerStorage: window.sessionStorage` narrows the second. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
 - Log tokens to console
 - Send tokens in URL query parameters (MCP service tokens included)
 - Ignore token refresh failures

package/dist/docs/versioned/next/explanation/deployment-baseline.md

@@ -1,6 +1,6 @@
 # Deployment baseline
 
-Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), future Vercel guide) map these to specific platforms; this page names them once.
+Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), [Deploy to Vercel](../how-to/deploy-to-vercel.md)) map these to specific platforms; this page names them once.
 
 See also the [environment variables reference](../reference/environment-variables.md).
 
@@ -44,9 +44,9 @@ Expo Router supports three web output modes. The choice determines hosting optio
 
 | Mode | Output | API routes | SSR | Hosting | Terreno status |
 |------|--------|-----------|-----|---------|----------------|
-| `single` | One `index.html` SPA | No | No | Any static host | **Current default** |
-| `static` | Per-route HTML files | No | No | Any static host | Available; better SEO |
-| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Not yet — repo catalog is Expo `~54.0.29`; see [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md) |
+| `single` | One `index.html` SPA | No | No | Any static host | Expo's default |
+| `static` | Per-route HTML files | No | No | Any static host | Used by `example-frontend` and `demo`; better SEO |
+| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Available (repo catalog is Expo `~57.0.14`) but unused; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#advanced-server-output) and [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md) |
 
 ## Multi-environment checklist
 

package/dist/docs/versioned/next/explanation/example-coverage.md

@@ -22,7 +22,8 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
 | Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
 | Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/documents.tsx` (Consents section), admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
-| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
+| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Seeded examples are drafts, so fresh databases do not interrupt sign-in. Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
+| What's new banner | n/a — generated from `CHANGELOG.md` by `bun run whats-new:generate` | yes — `WhatsNewBanner` in `example-frontend/components/SyncTodosScreen.tsx`, data in `example-frontend/constants/whatsNew.generated.json` | `bun run check:whats-new` keeps the data in sync with each release. |
 | File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/documents.tsx` (Files section, every signed-in user, 1 upload / IP / min), `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. Deployed bucket is terraform-managed (`google_storage_bucket.example_documents`). |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |

package/dist/docs/versioned/next/explanation/model-router-actions.md

@@ -2,7 +2,7 @@
 
 `modelRouter` can register **actions** — named operations at collection or instance scope — alongside standard CRUD. Actions reuse the same permission model, error envelope, and OpenAPI pipeline as CRUD routes, without hand-wiring `endpoints`, `asyncHandler`, and doc loading.
 
-CRUD **create, update, and delete** (not named actions) share one write pipeline: REST, Sync, and MCP all call `executeCreate` / `executeUpdate` / `executeDelete` in `api/src/sync/executors.ts`. MCP tools map arguments and `APIError` titles onto the MCP result envelope after the executor returns. RBAC User-role stripping runs in those executors **after** `transform` / `preCreate` / `preUpdate`. MCP passes the registry `modelName` so stripping still applies when the compiled mongoose `modelName` is not `"User"`. Invalid document `_id` values (`CastError` on path `_id`, BSON invalid ObjectId) load as 404 `Document not found`; `CastError` on populate paths is a GET error, not a missing document.
+CRUD **create, update, and delete** (not named actions) share one write pipeline: REST, Sync, and MCP all call `executeCreate` / `executeUpdate` / `executeDelete` in `api/src/sync/executors.ts`. MCP tools map arguments and `APIError` titles onto the MCP result envelope after the executor returns. RBAC User-role stripping runs in those executors **after** `transform` / `preCreate` / `preUpdate`. Stripping applies to the user model: a model compiled as `"User"`, or the `userModel` passed to `createAccess` under whatever name it was compiled. Pass `userModel` to `createAccess` when your user model has another name. Invalid document `_id` values (`CastError` on path `_id`, BSON invalid ObjectId) load as 404 `Document not found`; `CastError` on populate paths is a GET error, not a missing document.
 
 ## When to use actions
 
@@ -86,6 +86,8 @@ Handlers receive a single context object:
 
 Return a plain value from the handler; the framework responds with `{data: <value>}` and status `200` (or `action.status` if set). If the handler writes the response itself (`res.json`, streaming), return without relying on auto-wrap — the framework skips wrapping when `res.headersSent` is true.
 
+Set `unwrapResponse: true` to send the return value itself as the body, with `action.status`, instead of `{data: <value>}`. An `undefined` return sends an empty body (useful with `status: 204`). Use it when converting an existing `router.post` route whose clients expect the bare shape. OpenAPI documents the `response` schema without the `data` wrapper for these actions. `unwrapResponse` affects REST only; MCP always returns the value as the tool's JSON text.
+
 ## Permissions
 
 Each action requires a non-empty `permissions` array (same `PermissionMethod` types as CRUD). An empty array disables the action and returns **405**, matching CRUD.
@@ -101,6 +103,8 @@ HTTP method and scope map to a CRUD permission check:
 **403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
 **401** — unauthenticated when a permission requires auth (from existing auth middleware).
 
+With RBAC `access` on the router, an action without its own `access` inherits the router's resource and the mapped CRUD action. When the action's resource (inherited or set with `access`) matches the router's resource, the router's `access.scope` check and `access.also[method]` permissions also run, before and after the document loads, exactly as they do for the mapped CRUD method. A user whose role grants `todo:update` but who fails the router scope for a document gets **403** on that document's instance actions, the same as on `PATCH`. An action whose `access` names another resource skips the router's `scope` and `also`.
+
 `authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD. An action may set `allowAnonymous: true` to accept unauthenticated requests without making the router's CRUD routes or other actions anonymous. Keep a non-empty permission such as `Permissions.IsAny` and authenticate any service token in the handler.
 
 ## Validation
@@ -128,6 +132,33 @@ When `openApi` is configured on the router (automatic with `TerrenoApp` and `set
 
 Request/response schemas are derived from Zod when `body`, `query`, or `response` are set. Successful responses are documented as `{data: ...}` to match the wire format.
 
+## MCP tools
+
+Set `mcp: {name, description?}` on an action to also expose it as an MCP tool on `/mcp`, so a frontend calling the action over REST and an agent calling it over MCP share one implementation:
+
+```typescript
+instanceActions: {
+  promote: {
+    body: z.object({note: z.string().optional()}).strict(),
+    handler: async ({body, doc}) => promoteDraft(doc, body.note),
+    mcp: {description: "Promote a draft to published", name: "drafts_promote"},
+    method: "POST",
+    permissions: [Permissions.IsOwner],
+  },
+},
+```
+
+The tool behaves like the REST route:
+
+- **Input.** An instance action takes `{id, ...body}` (POST) or `{id, ...query}` (GET). A collection action takes the body or query alone. `body` / `query` must be a `z.object()`, and an instance action's schema cannot define `id` (a collection action's can, and gets it). With no schema, the tool accepts any arguments, as REST forwards the raw body.
+- **Validation.** The MCP server validates arguments against that schema before the handler runs, so the handler gets the same parsed `ctx.body` / `ctx.query` as REST.
+- **Permissions.** The same `runActionPermissions` chain runs before and after the document loads, including RBAC `access`. It never falls back to the router's CRUD permissions. A refused call returns an `isError` result with the error title (`Access denied`), where REST returns 403 or 405.
+- **Authentication.** A call without a user is refused unless the action or router sets `allowAnonymous`.
+- **Handler.** `req` comes from `createMCPRequest` (`req.isMCPRequest === true`, `req.params.id` set for instance actions). `res` throws `Action used res during an MCP call` when touched, so an action that writes to `res` directly cannot opt in.
+- **Result.** The return value becomes the tool's JSON text. A thrown `APIError` becomes an `isError` result with its title; validation errors add their field messages.
+
+Action tools are collected from every registered router when `/mcp` mounts, alongside CRUD and `registerMCPTool` tools. A disabled action (`permissions: []`) is not exposed. Tool names must be unique across all tools; a collision fails at boot.
+
 ## Collision detection
 
 At router build time, Terreno rejects:

package/dist/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -191,7 +191,7 @@ example-backend Dockerfile with CI validation.
 **Title:** `Deploy to Vercel`
 
 **Labels:** `area:deploy`, `type:docs`  
-**Project fields:** Area=`deploy`, Target=`Next`, Impact=`Improvement`, IP=`deploy-to-vercel`, Status=`Planned`
+**Project fields:** Area=`deploy`, Target=`Released`, Impact=`Improvement`, IP=`deploy-to-vercel`, Status=`Shipped`
 
 Documents Expo web export on Vercel, preview-deployment CORS and Better Auth origin handling,
 Vercel Functions WebSockets (Public Beta) operator docs, and a deploy-vercel skill with

package/dist/docs/versioned/next/how-to/README.md

@@ -9,6 +9,8 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Deploy to Google Cloud Platform](deploy-to-gcp.md) — index for GCP guides
 - [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) — container + Secret Manager + Cloud Run
 - [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) — static hosting with SPA routing
+- [Deploy to Vercel](deploy-to-vercel.md) — web on Vercel, backend on Cloud Run or Vercel Functions; previews, CORS, CI
+- [Run WebSockets on Vercel Functions](vercel-function-websockets.md) — Socket.IO and syncdb on Vercel's WebSocket beta: transports, reconnects, state
 
 ## Contents
 
@@ -33,6 +35,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Set up Terreno MCP](set-up-terreno-mcp.md) — Configure hosted docs/codegen and local runtime tools
 - [Debug with MCP](debug-with-mcp.md) — Diagnose backend, browser, Metro, app, and client-state failures
 - [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
+- [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md) — Let Claude.ai and ChatGPT connect to `/mcp` through OAuth 2.1 with your own consent screen
 - [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
 - [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
 - [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate

package/dist/docs/versioned/next/how-to/add-github-oauth.md

@@ -68,7 +68,8 @@ setupServer({
     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
     callbackURL: process.env.GITHUB_CALLBACK_URL || "http://localhost:4000/auth/github/callback",
     scope: ["user:email"], // Optional, defaults to ["user:email"]
-    allowAccountLinking: true, // Optional, defaults to true
+    allowAccountLinking: true, // Optional
+    allowedReturnTo: ["https://app.yourapp.com", "yourapp://auth"], // Optional, needed for returnTo
   },
 });
 ``````
@@ -81,7 +82,8 @@ setupServer({
 | `clientSecret` | string | Yes | GitHub OAuth Client Secret |
 | `callbackURL` | string | Yes | OAuth callback URL (must match GitHub app settings) |
 | `scope` | string[] | No | OAuth scopes (default: `["user:email"]`) |
-| `allowAccountLinking` | boolean | No | Allow linking GitHub to existing accounts (default: `true`) |
+| `allowAccountLinking` | boolean | No | `true` lets `GET /auth/github/link` attach GitHub to the signed-in user. When omitted, the link route is mounted but linking returns 400, and a GitHub login whose email matches an existing account links to it. `false` turns off both. |
+| `allowedReturnTo` | string[] | No | Exact http(s) origins (`https://app.yourapp.com`) or custom-scheme authorities (`yourapp://auth`) that `returnTo` may point to. Unset means `returnTo` is ignored. |
 | `findOrCreateUser` | function | No | Custom user creation/lookup handler |
 
 ## Step 4: Set Environment Variables
@@ -106,8 +108,20 @@ The following routes are automatically added when `githubAuth` is configured:
 GET /auth/github
 ``````
 
-Redirects users to GitHub for authentication. Optional query parameter:
-- `returnTo` — URL to redirect after successful authentication (tokens will be appended as query params)
+Redirects users to GitHub for authentication. The redirect carries an OAuth `state` value, and
+the response sets a short-lived (10 minute), signed, HttpOnly, `SameSite=Lax` cookie named
+`terreno_github_oauth_state` that holds the same value. The callback accepts the GitHub response
+only from the browser that holds that cookie, and each cookie works once. The cookie is signed
+with `SESSION_SECRET` (or `TOKEN_SECRET` when `SESSION_SECRET` is unset).
+
+Optional query parameter:
+- `returnTo` — URL to redirect to after successful authentication. Its origin (or custom-scheme
+  authority) must be listed in `allowedReturnTo`; any other value returns 400. When
+  `allowedReturnTo` is unset, `returnTo` is ignored and the callback returns JSON. Tokens are
+  delivered in the URL fragment (`#token=...&refreshToken=...&userId=...`), never the query
+  string. `returnTo` is kept in `req.session` between the two requests, so it needs a
+  persistent session middleware (for example `express-session`) mounted through
+  `beforeJsonSetup` or `addMiddleware`; TerrenoApp ships none.
 
 ### OAuth Callback
 
@@ -115,7 +129,7 @@ Redirects users to GitHub for authentication. Optional query parameter:
 GET /auth/github/callback
 ``````
 
-Handles the GitHub OAuth callback. Returns JSON with tokens:
+Handles the GitHub OAuth callback. Without an allowlisted `returnTo`, returns JSON with tokens:
 
 ``````json
 {
@@ -134,7 +148,12 @@ GET /auth/github/link
 Authorization: Bearer <jwt-token>
 ``````
 
-Links GitHub to the authenticated user's existing account. Redirects to GitHub, then back to callback.
+Links GitHub to the authenticated user's existing account. Redirects to GitHub, then back to
+the callback. The user ID from the bearer token is recorded in the signed state cookie, and the
+callback links GitHub only to that user. A session cookie or token that happens to be on the
+callback request is never used as the link target. Open this route in the same browser that will
+return to the callback, so the state cookie is present there. Requires
+`allowAccountLinking: true`.
 
 ### Unlink GitHub Account (Requires Auth)
 
@@ -164,7 +183,7 @@ Removes GitHub authentication from the user's account. Returns:
 3. User authorizes on GitHub
 4. Backend receives callback, creates new user with GitHub profile data
 5. Backend generates JWT tokens
-6. Backend redirects to `returnTo` URL with tokens in query params
+6. Backend checks `returnTo` against `allowedReturnTo` again and redirects there with tokens in the URL fragment
 7. Frontend stores tokens and logs user in
 
 ### Existing User Login
@@ -195,7 +214,8 @@ setupServer({
       // - profile: GitHub profile data
       // - accessToken: GitHub access token
       // - refreshToken: GitHub refresh token (if available)
-      // - existingUser: If user is authenticated, their user document
+      // - existingUser: The user who started GET /auth/github/link (from the verified
+      //   OAuth state), otherwise undefined
       
       if (existingUser) {
         // Link GitHub to existing user
@@ -243,6 +263,7 @@ const handleGitHubLogin = async () => {
   });
   
   if (result.type === "success") {
+    // Tokens arrive in the fragment; expo-auth-session merges fragment values into params
     const {token, refreshToken, userId} = result.params;
     // Store tokens and log in user
   }
@@ -258,12 +279,13 @@ const handleGitHubLogin = () => {
   window.location.href = `https://api.yourapp.com/auth/github?returnTo=${window.location.origin}/auth/callback`;
 };
 
-// On callback page (/auth/callback)
-const urlParams = new URLSearchParams(window.location.search);
-const token = urlParams.get("token");
-const refreshToken = urlParams.get("refreshToken");
-const userId = urlParams.get("userId");
-// Store tokens and redirect to app
+// On callback page (/auth/callback). Tokens are in the fragment, not the query string.
+const fragment = new URLSearchParams(window.location.hash.slice(1));
+const token = fragment.get("token");
+const refreshToken = fragment.get("refreshToken");
+const userId = fragment.get("userId");
+// Clear the fragment, store tokens, and redirect to app
+window.history.replaceState(null, "", window.location.pathname);
 ``````
 
 ## Creating a GitHub OAuth App
@@ -284,8 +306,9 @@ const userId = urlParams.get("userId");
 ## Security Considerations
 
 - **Never expose client secrets** — They should only exist on the backend
+- **State is enforced** — The callback rejects a response without a valid, unexpired state cookie from the same browser (redirect to `/auth/github/failure`), which blocks login CSRF and cross-site account linking
 - **Use HTTPS in production** — GitHub OAuth requires HTTPS for production callbacks
-- **Validate redirect URLs** — Only allow trusted domains in `returnTo` parameters
+- **Redirect allowlist** — List only your own app origins in `allowedReturnTo`. Matching is exact on origin (or custom-scheme authority); subdomains and other ports are not included
 - **Scope minimization** — Only request GitHub scopes your app actually needs
 - **Token storage** — Store tokens securely on the frontend (SecureStore on mobile, httpOnly cookies on web)
 
@@ -301,13 +324,23 @@ const userId = urlParams.get("userId");
 
 A different user has already linked this GitHub account. Users must unlink it first or use a different GitHub account.
 
+### Callback redirects to `/auth/github/failure` right away
+
+The OAuth state did not verify. The flow must start (`/auth/github` or `/auth/github/link`) and
+finish (`/auth/github/callback`) in the same browser within 10 minutes, and the API host that
+serves `callbackURL` must be the host that set the cookie. Check that `SESSION_SECRET` is the
+same on every instance.
+
 ### "Account linking is disabled"
 
 Set `allowAccountLinking: true` in `githubAuth` configuration.
 
 ### Tokens not included in callback
 
-If using `returnTo`, tokens are appended as query parameters. Check that your frontend is reading them correctly.
+Tokens are in the URL fragment (`window.location.hash`), not the query string. If the callback
+returns JSON instead of redirecting, check that `allowedReturnTo` lists the `returnTo` origin and
+that a session middleware keeps `req.session` between `/auth/github` and the callback. A 400
+"returnTo is not an allowed redirect target" means the origin is not listed.
 
 ## Learn More
 

package/dist/docs/versioned/next/how-to/admin-add-model.md

@@ -49,4 +49,7 @@ Common fields:
   sentinel is consumed before Mongo receives the query.
 - `fieldsets`: grouped form sections.
 - `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
-- `adminPermissions`: optional admin-specific permission methods.
+- `adminPermissions`: optional per-action (`list`, `read`, `create`, `update`, `delete`)
+  permission methods. They run in addition to the admin check (`admin:access` plus the model's
+  RBAC action, or `IsAdmin`), so they can only restrict access. An empty array disables that
+  action, including `list` and `read`.

package/dist/docs/versioned/next/how-to/ai-feature-development.md

@@ -108,6 +108,11 @@ await aiService.generateText({
 
 Missing `production` fails the request (400). Do not fall back to a hardcoded string.
 
+3. Bound cost before users reach the AI routes. `@terreno/ai` has no per-user token or spend
+   limit, and a chat reply keeps running after the client disconnects. Enable `TerrenoApp`
+   `rateLimit` and set a provider budget or quota alert; see
+   [Cost and abuse limits](../reference/ai.md#cost-and-abuse-limits).
+
 ## 7. Production tracing and feedback
 
 Do this in parallel with steps 1–6 once the feature is reachable.

package/dist/docs/versioned/next/how-to/background-jobs.md

@@ -46,7 +46,10 @@ entrypoint.
 When `JobsApp` is registered **before** `AdminApp`, `POST {adminBase}/scripts/:name/run`
 enqueues job `admin/script` (`maxAttempts: 1`) and still returns `{taskId}` for the existing
 Scripts poll UI (`BackgroundTask`). Progress, logs, dry/wet, and cancel stay on that row.
-Cancel also cancels the job so `ctx.signal` aborts.
+Cancel also cancels the job so `ctx.signal` aborts. The job handler starts the script only
+when it moves the task from `pending` to `running`; a delivery for a task that already
+started fails with 409 and the script is not run again. Start a new run instead of retrying
+a dead `admin/script` job.
 
 Apps without `JobsApp` keep the previous in-process `void` runner. The CLI
 (`runScriptCli` / `bun run script`) stays process-local.
@@ -114,8 +117,17 @@ On shutdown, call `jobsApp.stopWorker()` so in-flight handlers receive `ctx.sign
 
 ## Mongo runner: restart, retry, idempotency, schedules
 
-**Restart:** Jobs are Mongo documents. A crashed worker leaves `running` rows; after
-`lockTtlMs` (default 15 minutes) another worker reclaims them via `lockedAt` expiry.
+**Lease:** A claimed job holds a lease on its row (`lockedAt` / `lockedBy`). While the
+handler runs, the worker renews `lockedAt` every `lockTtlMs / 3`, so a long handler keeps its
+claim and no other worker or execute dispatch runs it at the same time. If a renewal finds
+that another consumer owns the row, the worker aborts `ctx.signal` and discards its own
+result. A finalize failure on one job is logged and does not stop the poll loop.
+
+**Restart:** Jobs are Mongo documents. A crashed worker leaves `running` rows; once their
+lease is older than `lockTtlMs` (default 15 minutes) another worker reclaims them. A reclaim
+counts as an attempt (`attemptCount++`, `attempts[]` entry with `errorClass: "LeaseExpired"`).
+When that exhausts `maxAttempts`, the job goes to `status: "dead"` instead of running again,
+so a `maxAttempts: 1` job never runs twice.
 
 **Retry:** Handler throws → `attemptCount++`, `attempts[]` entry, exponential backoff with
 equal jitter, `status: "pending"` and future `runAt`. At `maxAttempts` (default 5) →
@@ -130,8 +142,9 @@ tick when a child for that schedule is still `pending` / `running` / `scheduled`
 
 ## At-least-once handlers
 
-Delivery is **at-least-once**: lock expiry, Cloud Task retries, or Vercel queue redelivery
-can run a handler more than once.
+Delivery is **at-least-once**: a reclaim after a worker crash (within `maxAttempts`),
+Cloud Task retries, or Vercel queue redelivery can run a handler more than once. A live
+handler is never run concurrently by a second consumer while its lease renews.
 
 - Make handlers idempotent (stable keys, upserts, “already processed” checks).
 - Use `idempotencyKey` on enqueue to prevent duplicate **rows**, not duplicate execution after admin retry/requeue.

package/dist/docs/versioned/next/how-to/circleci.md

@@ -239,7 +239,8 @@ restrict `terreno-release` and `terreno-npm` to tag/manual release pipelines.
 | `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` | `e2e`, `admin-spa-integration`, `maestro-e2e` |
 | `terreno-release` | `REPO_ADMIN_TOKEN`, `ZOOM_WEBHOOK_URL`, `ZOOM_WEBHOOK_TOKEN` | stable version bump + release notification |
 | `terreno-agentic` | `CURSOR_API_KEY`, optional `CURSOR_MODEL` | `architectural-pr-review` |
-| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, `architectural-pr-review` |
+| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, `architectural-pr-review`, `approve` |
+| `terreno-approve` | `TERRENO_APP_ID`, `TERRENO_APP_PRIVATE_KEY` (the terreno-approval-agent GitHub App), `ANTHROPIC_API_KEY` | `approve` |
 | `terreno-github-deployments` | `GITHUB_DEPLOYMENTS_TOKEN`: fine-grained PAT on `TerrenoLabs/terreno` with **Deployments: read/write** and **Pull requests: read** only | GitHub Deployment records + preview PR lookup in every Netlify/GCP deploy job |
 
 Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
@@ -247,8 +248,9 @@ Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets on
 GitHub PAT) in project env vars — those are injected into every job, including
 `bun` scripts from the PR. `terreno-github-api` must hold the PAT as
 `GITHUB_TOKEN`; restrict it to this project and leave fork-PR secret passing off.
-The `always` workflow attaches it **only** to `dco` and `architectural-pr-review`
-(the latter also gets `terreno-agentic`). DCO skips if `GITHUB_TOKEN` is unset.
+The `always` workflow attaches it **only** to `dco`, `architectural-pr-review`
+(which also gets `terreno-agentic`), and `approve` (which also gets `terreno-approve`).
+DCO skips if `GITHUB_TOKEN` is unset.
 `architectural-pr-review` also skips if `GITHUB_TOKEN` or `CURSOR_API_KEY` is
 unset, and it skips fork PRs. The job checks out `origin/master` before running
 the review script so a PR cannot rewrite the reviewer.
@@ -293,6 +295,7 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Repository policies (barrels, source rules, explicit any, licenses, changelog, parity, lifecycle, static analysis) | `repo-policies` |
 | Verify rules are in sync | `rulesync-check` |
 | `dco` | `dco` |
+| (none) | `approve` |
 | Run all tests (API CI) | `api-ci` |
 | Admin backend lint, compile, coverage | `packages-ci` (`admin-backend`) |
 | Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
@@ -339,6 +342,39 @@ CD replacement map:
 | Publish on tag (`publish-on-tag.yml`) | `publish-release` |
 | Appium Android / iOS | Not ported (Maestro web is `maestro-e2e`) |
 
+## Approval agent
+
+`approve` runs `brewery approve` from
+[joshgachnang/brewery](https://github.com/joshgachnang/brewery) on every same-repo PR
+pipeline and posts one review as the **terreno-approval-agent** GitHub App plus a
+`terreno/approve` check run. Policy lives in `.brewery.json` (`approve` block: levels
+the App may approve, path rules that floor, cap, or forbid approval; when a file matches
+both a floor and a lower ceiling, the floor wins) and
+`docs/approval-rubric.md` (what the model scores). Both are read from `origin/master`,
+so a PR cannot change the rules it is judged by, and a PR that edits either file is
+never approved. The job resets its working tree to `origin/master` right after
+checkout, so the PR-number script, `bunfig.toml`, and the agent's working directory all
+come from master and nothing from the PR tree runs while the App key is in the
+environment; brewery reads the head through `git show <sha>:`. Brewery itself is
+pinned to a commit (`BREWERY_REF`) and cloned into `$HOME`; the model runs read-only
+with an allowlisted environment that holds no GitHub or App credential. The job waits
+(`--wait-checks`, up to 45 minutes) for every other check on the head before judging,
+ignoring its own `ci/circleci: approve` check (`selfChecks` in `.brewery.json`), and
+skips a red or still-pending head without spending a model, so it runs once per push,
+last.
+
+To teach the agent from what reviewers actually say, run
+`brewery calibrate TerrenoLabs/terreno` (optionally `--reviewer <login>` or `--notes
+<file>` of pasted comments): it opens one PR editing `docs/approval-rubric.md` and the
+path rules from the review comments since the last pass.
+
+Rollout: `approveLevels` is `[]`, so every PR gets a `COMMENT` review that says the
+risk level and why, and nothing approves. After a dozen PRs, compare the levels with
+how humans reviewed them, tune the path rules and rubric, then set
+`"approveLevels": ["low"]` in a one-line PR. The prompts and answers behind each
+verdict are stored as the `brewery-approve` job artifact. Full reference:
+[brewery `docs/approve.md`](https://github.com/joshgachnang/brewery/blob/master/docs/approve.md).
+
 ## Manual pipelines
 
 Trigger a pipeline from the CircleCI UI/API on the ref containing the code to