@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/57.18.0/how-to/deploy-web-to-gcs-cdn.md

@@ -0,0 +1,183 @@
+# Deploy web to GCS + CDN
+
+Host a static Terreno web export on Google Cloud Storage with Cloud CDN.
+
+Replace placeholders: `$PROJECT_ID`, `$REGION`, `$WEB_BUCKET`, `$SITE_NAME`, `$DOMAIN`.
+
+## Prerequisites
+
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
+- Backend deployed and CORS configured — see [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md)
+- [Build for web](build-for-web.md) completed with the correct `EXPO_PUBLIC_API_URL`
+
+## 1. Build the web bundle
+
+Set the API URL **before** export — it is inlined into the bundle:
+
+```bash
+cd example-frontend
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+The export script is `bun expo export --platform web` (see `example-frontend/package.json`).
+
+Output is in `dist/`.
+
+## 2. Enable the Compute Engine API
+
+Cloud CDN and its global load-balancing resources require the Compute Engine API:
+
+```bash
+gcloud services enable compute.googleapis.com --project="$PROJECT_ID"
+```
+
+## 3. Create the GCS bucket
+
+```bash
+gsutil mb -p "$PROJECT_ID" -l "$REGION" "gs://$WEB_BUCKET/"
+```
+
+## 4. Allow public object reads
+
+Cloud CDN must be able to serve the bucket's objects to unauthenticated visitors:
+
+```bash
+gsutil iam ch allUsers:objectViewer "gs://$WEB_BUCKET"
+```
+
+Do not grant `allUsers` a write role such as `objectAdmin`.
+
+## 5. Configure SPA routing
+
+Client-side routes require `index.html` for unknown paths:
+
+```bash
+gsutil web set -e index.html "gs://$WEB_BUCKET"
+```
+
+Do not set `MainPageSuffix` — GCS 301 redirects break client-side routing.
+
+## 6. Upload the build
+
+```bash
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' \
+  dist/ "gs://$WEB_BUCKET/"
+
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html "gs://$WEB_BUCKET/index.html"
+```
+
+## 7. Create HTTPS CDN resources
+
+The load balancer serves the bucket over HTTPS only. A Google-managed certificate secures
+the domain:
+
+```bash
+# Backend bucket (CDN-enabled)
+gcloud compute backend-buckets create "${SITE_NAME}-backend" \
+  --gcs-bucket-name="$WEB_BUCKET" \
+  --enable-cdn \
+  --no-negative-caching \
+  --project="$PROJECT_ID"
+
+# URL map
+gcloud compute url-maps create "${SITE_NAME}-url-map" \
+  --default-backend-bucket="${SITE_NAME}-backend" \
+  --project="$PROJECT_ID"
+
+# Static IP
+gcloud compute addresses create "${SITE_NAME}-ip" --global --project="$PROJECT_ID"
+
+# Managed TLS certificate
+gcloud compute ssl-certificates create "${SITE_NAME}-cert" \
+  --domains="$DOMAIN" \
+  --global \
+  --project="$PROJECT_ID"
+
+# HTTPS proxy
+gcloud compute target-https-proxies create "${SITE_NAME}-https-proxy" \
+  --url-map="${SITE_NAME}-url-map" \
+  --ssl-certificates="${SITE_NAME}-cert" \
+  --project="$PROJECT_ID"
+
+# HTTPS forwarding rule
+gcloud compute forwarding-rules create "${SITE_NAME}-https-forwarding-rule" \
+  --address="${SITE_NAME}-ip" \
+  --target-https-proxy="${SITE_NAME}-https-proxy" \
+  --global \
+  --ports=443 \
+  --project="$PROJECT_ID"
+```
+
+## 8. Redirect HTTP to HTTPS
+
+Port 80 should redirect rather than serve the bundle. Without a listener there at all, `http://$DOMAIN` fails to connect instead of sending visitors to the secure URL.
+
+`gcloud` exposes redirect behavior only through an imported spec, not through `url-maps create` flags:
+
+```bash
+gcloud compute url-maps import "${SITE_NAME}-http-redirect-url-map" \
+  --global --project="$PROJECT_ID" --source=/dev/stdin <<SPEC
+name: ${SITE_NAME}-http-redirect-url-map
+defaultUrlRedirect:
+  httpsRedirect: true
+  redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
+SPEC
+
+gcloud compute target-http-proxies create "${SITE_NAME}-http-proxy" \
+  --url-map="${SITE_NAME}-http-redirect-url-map" \
+  --project="$PROJECT_ID"
+
+gcloud compute forwarding-rules create "${SITE_NAME}-forwarding-rule" \
+  --address="${SITE_NAME}-ip" \
+  --target-http-proxy="${SITE_NAME}-http-proxy" \
+  --global \
+  --ports=80 \
+  --project="$PROJECT_ID"
+```
+
+Port 80 now only ever returns a 301; the bundle itself is served exclusively over TLS.
+
+Or run the parameterized script, which provisions steps 7 and 8 in one pass:
+
+```bash
+./scripts/setup-gcs-hosting.sh \
+  --project "$PROJECT_ID" \
+  --site-name "$SITE_NAME" \
+  --bucket "$WEB_BUCKET" \
+  --domain "$DOMAIN"
+```
+
+## 9. Point DNS and wait for the certificate
+
+```bash
+gcloud compute addresses describe "${SITE_NAME}-ip" --global \
+  --project="$PROJECT_ID" --format='value(address)'
+```
+
+Create an A record for `$DOMAIN` pointing at that IP. Managed certificates only begin provisioning once DNS resolves to the load balancer, and can take up to about an hour to become active:
+
+```bash
+gcloud compute ssl-certificates describe "${SITE_NAME}-cert" --global \
+  --project="$PROJECT_ID" --format='value(managed.status)'
+```
+
+Wait for `ACTIVE` before sending traffic. Still `PROVISIONING` after an hour usually means the A record does not resolve to the reserved IP.
+
+## 10. Invalidate cache after deploy
+
+```bash
+gcloud compute url-maps invalidate-cdn-cache "${SITE_NAME}-url-map" \
+  --path "/*" --async --project="$PROJECT_ID"
+```
+
+## Static-only path
+
+This guide hosts the `expo export -p web` output as static files. Server-rendered web (SSR, API routes) requires Expo SDK ≥ 55 — see [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).
+
+## Related
+
+- [Build for web](build-for-web.md)
+- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md)
+- [GCP architecture](../explanation/deployment-architecture-gcp.md)

package/src/docs/versioned/57.18.0/how-to/enable-mcp-oauth.md

@@ -0,0 +1,134 @@
+# Enable MCP OAuth for a JWT app
+
+Let Claude.ai custom connectors, ChatGPT apps, and other remote MCP clients connect to your app's `POST /mcp` through OAuth 2.1, when your app signs users in with Terreno JWTs. Terreno runs the authorization server; your app hosts one consent screen.
+
+Use [a service token](connect-mcp-service-token.md) instead for clients that take a static Bearer key (Perplexity, Cursor, Claude Code).
+
+## Prerequisites
+
+- A `TerrenoApp` backend with at least one MCP tool ([Expose MCP tools](expose-mcp-tools.md))
+- A public https origin for the API, for example `https://api.example.com`
+- A signed-in page in your app that can call the API with the user's JWT
+
+## 1. Turn on `mcpOAuth`
+
+MCP OAuth is off until you set `enabled: true`. Without it the app has no `/oauth/*` routes, no `.well-known/oauth-*` documents, and no OAuth challenge on `/mcp`.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpOAuth: {
+    consentUrl: "https://app.example.com/oauth/consent",
+    enabled: true,
+    issuer: "https://api.example.com",
+  },
+});
+```
+
+- `issuer` is the API's public origin, with no path. Every discovery URL and endpoint is built from it, so it must be the origin clients reach.
+- `consentUrl` is the page from step 2.
+
+### Choose how clients get a `client_id`
+
+Dynamic client registration (`POST /oauth/register`) is a separate opt-in and stays off by default. The endpoint is unauthenticated: anyone who can reach your API can create a client with any name and a redirect on an allowed host. The consent screen is then the only thing between that client and a user's grant, so a convincing name is enough to phish an approval.
+
+- **Registration off (default).** Create each client yourself and give its `client_id` to the client (Claude.ai custom connectors accept one under advanced settings). `/oauth/register` returns 404 and the metadata has no `registration_endpoint`.
+
+  ```typescript
+  import {McpOAuthClient} from "@terreno/api";
+
+  await McpOAuthClient.create({
+    clientId: "claude-connector",
+    clientName: "Claude",
+    grantTypes: ["authorization_code", "refresh_token"],
+    redirectUris: ["https://claude.ai/api/mcp/auth_callback"],
+    responseTypes: ["code"],
+  });
+  ```
+
+- **Registration on.** Turn it on only when clients you cannot pre-register must connect. Set `dynamicClientRegistration: true` and list `allowedRedirectHosts`, which limits where a registered client may send codes. Claude.ai redirects to `claude.ai`, ChatGPT to `chatgpt.com`. Use `*.example.com` for subdomains, and add `localhost` only if you want local clients with loopback `http://` redirects. Keep rate limiting on.
+
+  ```typescript
+  mcpOAuth: {
+    allowedRedirectHosts: ["claude.ai", "chatgpt.com"],
+    consentUrl: "https://app.example.com/oauth/consent",
+    dynamicClientRegistration: true,
+    enabled: true,
+    issuer: "https://api.example.com",
+  },
+  ```
+
+Booting with an issuer that has a path, a consent URL that is not a URL, or registration on with no redirect hosts throws. Full option list: [API reference → MCP OAuth](../reference/api.md#mcp-oauth).
+
+## 2. Host the consent screen
+
+The client sends the user's browser to `/oauth/authorize`. Terreno checks the client, redirect URI, and PKCE, stores a pending request, and redirects to `consentUrl?request=<id>`. Your page:
+
+1. Makes sure the user is signed in (send them through login and back if not, keeping `request`).
+2. Loads the request to show who is asking:
+
+   ```http
+   GET /oauth/authorize/<request>
+   Authorization: Bearer <user JWT>
+   ```
+
+   Response: `{data: {clientName, redirectHost, scope, expiresAt, …}}`. Show the client name and redirect host so the user can spot a client they did not start.
+
+3. Posts the decision with the same JWT, then sends the browser to the returned URL:
+
+   ```http
+   POST /oauth/authorize/<request>/approve   # or /deny
+   Authorization: Bearer <user JWT>
+   ```
+
+   ```typescript
+   const {data} = await approve(requestId);
+   window.location.assign(data.redirectUrl);
+   ```
+
+The three endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequest`, `denyMcpOAuthRequest`), so `bun run sdk` generates hooks for them. A request expires after 10 minutes (400 `Authorization request expired`), and a decided request cannot be decided again (409). The endpoints refuse `mcp_` and OAuth bearers, so an agent cannot approve itself.
+
+## 3. Connect a client
+
+Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the rest:
+
+1. `POST /mcp` without credentials returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"`.
+2. The client reads that document, then `/.well-known/oauth-authorization-server`.
+3. It uses the `client_id` you gave it, or registers itself at `/oauth/register` when `dynamicClientRegistration` is on, then runs the browser flow through your consent screen, and exchanges the code at `/oauth/token` for an access token (`mcpat_…`, one hour) and a refresh token (`mcprt_…`, 30 days).
+
+For Claude.ai: **Settings → Connectors → Add custom connector**, paste the MCP URL, and connect. For ChatGPT: create a connector with the MCP URL and choose OAuth.
+
+## 4. Check it
+
+```bash
+curl -i -X POST https://api.example.com/mcp \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+# HTTP/1.1 401 … WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"
+
+curl https://api.example.com/.well-known/oauth-authorization-server
+```
+
+## What changes on `/mcp`
+
+- Every request that cannot be authenticated, including `initialize` and `tools/list`, gets the 401 challenge. A rejected credential adds `error="invalid_token"` so clients refresh.
+- JWTs, Better Auth sessions, and `mcp_` service tokens keep working.
+- Tools see the approving user. `getCurrentRequestContext()?.credential` is `"oauth"`, so permission code can treat an agent's token differently from the user's own session (for example, no admin bypass). See [Request credential](../reference/api.md#request-credential).
+- Scopes are not enforced for you. A token can call every tool its user can, whatever scope it was granted. If `scopesSupported` lists scopes with different meanings (for example `["read", "write"]`), add `requireOAuthScope("write")` to the permissions of the methods and actions that need it. The granted scopes are in `getCurrentRequestContext()?.oauthScopes`.
+
+## Revoking access
+
+- The client revokes with `POST /oauth/revoke`. Revoking a refresh token ends the whole chain.
+- Disabling the user stops their tokens at the next call.
+- A password reset, Better Auth password change, or session revocation (anything that bumps `tokenEpoch`) ends every grant approved before it: the next `/mcp` call, refresh, or code exchange fails and the chain is revoked. The user reconnects the client.
+- Server-side, revoke everything a user granted with `McpOAuthToken.updateMany({userId, revokedAt: {$exists: false}}, {$set: {revokedAt: DateTime.now().toJSDate()}})`.
+
+Refresh tokens rotate on every use. If an old refresh token comes back, Terreno assumes it leaked and revokes every token issued from that approval; the user reconnects the client. The revoke is final: Terreno records the revoked approval, so a refresh or code exchange that was already in flight cannot issue a new token for it.
+
+## Security notes
+
+- Only public clients with PKCE `S256` are supported. `plain` PKCE and client secrets are rejected.
+- Tokens, codes, and refresh tokens are stored as SHA-256 hashes.
+- Registration, authorize, token, and revoke count against the `auth` [rate-limit](rate-limiting.md) bucket. Turn rate limiting on in production, since registration is unauthenticated.
+- If a browser-based client (such as the MCP Inspector) runs discovery from another origin, allow that origin in `corsOrigin`.

package/src/docs/versioned/57.18.0/how-to/expose-mcp-tools.md

@@ -0,0 +1,241 @@
+# Expose Model Context Protocol Tools
+
+Turn a `modelRouter` model into Model Context Protocol (MCP) tools that an LLM can call, reusing the permissions, query filters, population, and lifecycle hooks you already declared for REST.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- At least one model registered with `modelRouter`
+
+## Steps
+
+### 1. Add an `mcp` config to a model router
+
+```typescript
+import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  mcp: {
+    excludeFields: ["internalNote"],
+    maxLimit: 25,
+    methods: ["list", "read", "create", "update", "delete"],
+  },
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsOwner],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+  },
+  queryFields: ["completed", "title"],
+  queryFilter: OwnerQueryFilter,
+});
+```
+
+`methods` defaults to `["list", "read"]`, and `maxLimit` defaults to 50. A method whose `permissions` array is empty is never exposed as a tool, so REST and MCP cannot drift apart.
+
+### 2. Start the server
+
+`TerrenoApp` mounts `POST /mcp` automatically as soon as any model has an `mcp` config. Every other verb on `/mcp` returns a JSON-RPC 405. No extra registration is needed.
+
+Tools are named `{prefix}_{method}` — `todos_list`, `todos_read`, and so on.
+
+The endpoint speaks the `2026-07-28` MCP revision through the TypeScript SDK v2
+`createMcpHandler`. It is stateless: every request carries its protocol version,
+client identity, and capabilities, so requests can land on any backend instance.
+The SDK's stateless legacy fallback remains enabled, so 2025-era clients continue
+to work while clients migrate.
+
+### 3. Call the tools
+
+Point any MCP client at `POST /mcp`. Auth order on the Bearer header is:
+
+1. `mcp_…` service token, when `mcpServiceTokens` is enabled
+2. `mcpat_…` OAuth access token, when `mcpOAuth` is enabled
+3. Better Auth session
+4. JWT
+
+The credential type that won is recorded as `getCurrentRequestContext()?.credential` (`"mcp-service-token"`, `"oauth"`, `"better-auth-session"`, or `"jwt"`), so a permission function can refuse delegated agent tokens where it would trust the user's own session. Remote clients that need OAuth (Claude.ai connectors, ChatGPT apps) are covered in [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md).
+
+The resolved user is what permission checks run against, so an LLM never sees more than that user could see over REST. Mint and paste a static key with [Connect an MCP client with a service token](connect-mcp-service-token.md).
+
+`initialize` and `tools/list` are the unauthenticated catalog (unless `mcpOAuth` is enabled, which makes every unauthenticated `/mcp` request a 401 challenge). Identity is enforced on `tools/call`. GET `/mcp` is Streamable HTTP **405** (`Method not allowed.`) — there is no GET SSE stream; Perplexity still uses that 405 as a successful probe.
+
+Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP. Service tokens are MCP-only: they are rejected on `/mcp/service-tokens` and are not accepted on REST, sync, or admin.
+
+To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
+
+```typescript
+import {getMCPTools} from "@terreno/ai";
+
+const tools = getMCPTools(req.user);
+```
+
+`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
+version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
+hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
+`Mcp-Method` / `Mcp-Name` routing headers.
+
+## Naming tools
+
+The default prefix is the lowercase model name run through a simple pluralizer: `Todo` → `todos`, `Category` → `categories`, `Status` → `statuses`. Irregular nouns need an explicit prefix:
+
+```typescript
+mcp: {toolPrefix: "people"} // person_list -> people_list
+```
+
+## Filtering list results
+
+Only fields listed in `queryFields` can be filtered, exactly as in REST. A filter value may be an exact value or an operator object:
+
+```json
+{"completed": false, "title": {"$in": ["Buy milk", "Walk dog"]}}
+```
+
+Allowed operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$all`, `$size`, `$exists`, and `$regex` (with `$options`). Operators that can execute code or ignore indexes — `$where`, `$expr`, `$function`, `$accumulator`, `$jsonSchema`, `$text` — are rejected with an error rather than silently dropped, so the model can correct itself.
+
+Filters can be combined with top-level `$and` / `$or`, whose branches are validated against `queryFields` too:
+
+```json
+{"$or": [{"completed": true}, {"title": {"$regex": "^Urgent"}}]}
+```
+
+`queryFilter` still runs after the filter is built, so an `OwnerQueryFilter` keeps scoping results to the calling user no matter what the LLM sends.
+
+## Populating references
+
+Population comes from the model router's `populatePaths`, exactly as it does over REST. A tool may pass `populate` to request a **subset** of those declared paths — it can never introduce a new one, so the `fields` allowlist on each declared path always applies and a caller cannot pull back a whole referenced document:
+
+```typescript
+populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
+```
+
+`{"populate": "ownerId"}` is accepted; anything undeclared is refused with an error listing the allowed paths. Models with no `populatePaths` don't get a `populate` parameter at all.
+
+## Hiding fields
+
+`excludeFields` removes fields from both the generated tool schemas and the responses:
+
+- A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
+- A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
+
+The list tool's `sort` argument accepts only the router's sortable fields (`queryFields`, fields in the router's `sort`, and `sortFields`) minus `excludeFields`. Sorting on any other field returns an error that lists the allowed fields, because result order would reveal the hidden values.
+
+## Customizing responses
+
+`mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
+
+```typescript
+mcp: {
+  mcpResponseHandler: async (value, method) => {
+    if (Array.isArray(value)) {
+      return value.map((todo) => ({id: String(todo._id), title: todo.title}));
+    }
+    return {id: String(value._id), title: value.title};
+  },
+}
+```
+
+`excludeFields` is applied after your handler runs.
+
+## Lifecycle hooks
+
+`preCreate`, `postCreate`, `preUpdate`, `postUpdate`, `preDelete`, and `postDelete` all run for MCP calls. An MCP tool call is JSON-RPC rather than HTTP, so `createMCPRequest` builds a stub Express-shaped `request` (`MCPRequest`):
+
+- `user` — the authenticated MCP user
+- `body` — the hook-stage payload after write denylist + transform, not the raw tool args (on delete, `id` is in `body`, not `params`)
+- `headers` / `query` / `params` — always `{}` (MCP does not forward HTTP headers)
+- `isMCPRequest` — `true`
+
+REST `responseHandler` gets the same stub with an empty `body`.
+
+```typescript
+import type {MCPRequest} from "@terreno/api";
+
+preCreate: (body, req) => {
+  if ((req as unknown as MCPRequest).isMCPRequest) {
+    // e.g. tag records created by an assistant
+    return {...body, source: "assistant"};
+  }
+  return body;
+},
+```
+
+A hook that reads `req.headers` or `req.query` gets an empty object instead of a crash, but anything genuinely HTTP-specific (cookies, IP address) is unavailable — branch on `isMCPRequest` when that matters.
+
+## Logging and error reporting
+
+Every generated tool call emits a structured backend audit log with stable
+`mcpTool`, `mcpMethod`, and `mcpModel` labels plus the active Terreno request
+context (`requestId`, `userId`, and trace fields when present):
+
+- successful calls log at `info` with `durationMs`
+- expected refusals (permissions, not found, invalid filters) log at `warn`
+- caught database, transform, and lifecycle-hook failures log at `error`
+
+When `USE_SENTRY_LOGGING=true`, expected failures are mirrored as Sentry logs.
+Unexpected exceptions and caught internal causes are also captured with
+`Sentry.captureException`, preserving their original stack. The client still
+receives the stable MCP error text — internal exceptions and stack traces stay
+server-side. Tool arguments are not logged.
+
+## Actions as tools
+
+A verb that is not CRUD belongs in a [modelRouter action](../explanation/model-router-actions.md). Add `mcp` to the action to expose the same implementation as a tool, instead of writing it twice:
+
+```typescript
+export const todoRouter = modelRouter("/todos", Todo, {
+  collectionActions: {
+    bulkComplete: {
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      handler: async ({body, user}) => completeTodos(body.ids, user),
+      mcp: {description: "Mark several todos complete", name: "todos_bulk_complete"},
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      handler: async ({doc}) => markComplete(doc),
+      mcp: {name: "todos_mark_complete"},
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+    },
+  },
+  permissions: { /* CRUD */ },
+});
+```
+
+- `todos_mark_complete` takes `{id}`; an instance action's tool input is `{id, ...body}` (or `{id, ...query}` for GET). `todos_bulk_complete` takes `{ids}`.
+- The tool runs the action's own `permissions` and RBAC `access`, before and after loading the document, exactly as REST does. It does not need `mcp` on the router, and the router's CRUD permissions do not apply.
+- The handler sees `req.isMCPRequest === true`. Its return value is the tool's JSON text. Touching `res` fails the call, so return values instead of writing to `res`.
+- `body` / `query` must be a `z.object()`, and instance actions cannot define `id` in it. Tool names must be unique; a duplicate fails at boot.
+
+Audit log lines for action tools carry `mcpTool`, `mcpModel`, and `mcpAction` labels.
+
+## Custom tools
+
+CRUD tools cover one model at a time, and actions cover one model's verbs. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
+
+```typescript
+import {registerMCPTool} from "@terreno/api";
+import {z} from "zod";
+
+registerMCPTool({
+  name: "users_todo_statuses",
+  description: "List every user with each of their todos and completed status. Admin only.",
+  zodSchema: z.object({}).strict(),
+  handler: async (_args, user) => {
+    if (!user?.admin) {
+      return {
+        content: [{type: "text", text: JSON.stringify({error: "Permission denied: admin required"})}],
+        isError: true,
+      };
+    }
+    // load users + todos and return JSON text
+    return {content: [{type: "text", text: JSON.stringify({users: []})}]};
+  },
+});
+```
+
+The example backend registers this as `users_todo_statuses` from `example-backend/src/api/usersTodoStatus.ts`.

package/src/docs/versioned/57.18.0/how-to/generate-a-rest-cli.md

@@ -0,0 +1,34 @@
+# Generate a REST CLI from OpenAPI
+
+Run this from an app repo that already serves `/openapi.json` (Terreno `setupServer` does).
+
+1. Install the CLI: `bun add -g @terreno/cli` (or `bunx @terreno/cli`).
+2. Generate the wrapper:
+
+```bash
+terreno generate rest-cli \
+  --schema http://localhost:4000/openapi.json \
+  --out ./tools/app-cli \
+  --name myapp \
+  --base-url http://localhost:4000
+```
+
+3. Call the API:
+
+```bash
+cd tools/app-cli
+bun ./src/cli.ts list
+bun ./src/cli.ts call todo_list --param limit=10 --token "$TERRENO_TOKEN"
+bun ./src/cli.ts request GET /todos/{id} --param id=abc --json
+```
+
+Auth uses `--token` or `TERRENO_TOKEN`. Base URL uses `--base-url` or `TERRENO_API_URL`, then `servers[0].url` from the spec.
+
+To list or call without generating a package:
+
+```bash
+terreno api list --schema http://localhost:4000/openapi.json
+terreno api call todo_list --schema ./openapi.json --param limit=10
+```
+
+`generate rest-cli` writes `src/cli.ts` that imports `runAppRestCli` from `@terreno/cli`. Point that dependency at the published `@terreno/cli` version in apps outside this monorepo.

package/src/docs/versioned/57.18.0/how-to/github-actions-ci.md

@@ -0,0 +1,41 @@
+# GitHub Actions CI (Terreno)
+
+CircleCI is the CI/CD of record; see [CircleCI](circleci.md). The GitHub
+Actions CI and deploy workflows below are disabled
+(`push.branches-ignore: ["**"]`) and kept only for rollback. This page
+describes how they behaved if one is ever re-enabled.
+
+## Docs site (`docs-deploy.yml`)
+
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
+
+PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
+`master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
+
+| Behavior | PR preview | `master` production |
+| --- | --- | --- |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
+| JS minify | Off | On |
+| Local search index | Skipped | Built |
+| Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
+| TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
+| Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
+
+Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
+
+## Other high-cost jobs
+
+| Workflow | What we skip or reuse |
+| --- | --- |
+| `e2e-ci`, `admin-spa-ci`, `admin-spa-integration` | Playwright Chromium under `~/.cache/ms-playwright`, keyed on `bun.lock`. E2E shards share one compile job (`workspace-dist` artifact) so required check names stay `E2E · <spec>`. |
+| `fingerprint-gate` | Master iOS/Android hashes cached per `pull_request.base.sha` (skips a second `bun run compile`) |
+| `maestro-e2e` | Demo export + static server only when `demo/`, `ui/`, or `.maestro/flows/demo/` change |
+| `example-backend-docker` | Buildx runs only when the image recipe changes (`Dockerfile`, lockfile, `package.json`). Source-only PRs skip; CD preview deploy still builds the image. `load: true` stays off. |
+| `cd` Cloud Run deploys | Runs a local wrapper around `google-github-actions/deploy-cloudrun` that retries only the transient GitHub WIF subject-token timeout, up to three attempts; IAM, image, and configuration failures fail immediately. The backend preview runs for every example-frontend PR preview, including frontend-only changes, so the Netlify build targets an isolated `pr-<number>` backend instead of production. The frontend deploy waits for that backend's healthy `/health` response before publishing to Netlify, and per-PR concurrency cancels duplicate deploys to the same alias. CD runs the built container against the configured Secret Manager values, including the Cloud Tasks `JOBS_*` env, and requires a healthy `/health` response before pushing or deploying. Preview Cloud Run uses `--memory=1Gi` and `--cpu-boost`, overwrites revision secrets, and binds `PORT` before MongoDB connect. Before deploy it rebuilds traffic with `--set-tags` / `--clear-tags` so a not-Ready tagged revision is omitted (`--remove-tags` leaves that revision in the spec and Cloud Run rejects the update). It then deploys `--no-traffic` without `--tag`, sets `--revision-suffix=pr<n>-<run_id>-<run_attempt>`, and tags the new Ready revision afterward. |
+| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.0` and runs `bun install --frozen-lockfile` with no `~/.bun/install/cache`. CircleCI measurements: cache restore (~15–73s) exceeded the install savings (~9s). See [circleci.md](circleci.md#bun-install-is-uncached). |
+
+Playwright e2e on CircleCI groups specs into five shards (`e2e-auth`,
+`e2e-app`, `e2e-admin-core`, `e2e-admin-table`, `e2e-syncdb`). The retained GHA
+twin still lists one spec per matrix entry for rollback.