@terreno/mcp 57.19.2 → 57.21.0

package/dist/docs/versioned/next/how-to/enable-mcp-oauth.md

@@ -1,8 +1,8 @@
 # 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.
+Let Claude.ai custom connectors, ChatGPT apps, and other remote MCP clients connect to your app's `POST /mcp` through OAuth 2.1. Terreno runs the authorization server; your app hosts one consent screen. A Terreno JWT is the usual way to approve that screen. An app with its own session sets `req.user` first. See [Apps without a Terreno JWT](#apps-without-a-terreno-jwt).
 
-Use [a service token](connect-mcp-service-token.md) instead for clients that take a static Bearer key (Perplexity, Cursor, Claude Code).
+Use [a service token](connect-mcp-service-token.md) when the client can only hold a static Bearer key (Perplexity, Cursor, Claude Code). For a headless client that can perform a token request, use [client credentials](#headless-clients-client-credentials) instead.
 
 ## Prerequisites
 
@@ -46,6 +46,8 @@ Dynamic client registration (`POST /oauth/register`) is a separate opt-in and st
   });
   ```
 
+  A loopback redirect (`localhost`, `127.0.0.1`, or `[::1]`) matches any port. Register one URI, for example `http://127.0.0.1:33418/callback`, and a native client can send `http://127.0.0.1:<ephemeral>/callback` with the same scheme, host, path, and query. The authorization code is sent to the port the client used. `localhost` and `127.0.0.1` do not match each other. Every other redirect URI must match exactly. There is no per-client opt-out. Another process on that host can listen on a different port and receive the code. PKCE `S256` is what stops that process from exchanging it.
+
 - **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
@@ -62,6 +64,10 @@ Booting with an issuer that has a path, a consent URL that is not a URL, or regi
 
 ## 2. Host the consent screen
 
+If the backend serves `@terreno/admin-spa` (`AdminSpaServeApp`), it already has one: set `consentUrl` to `${issuer}/console/oauth/consent` (use your `basePath` if it is not `/console`) and skip to step 3. Any signed-in user can approve there, and the page uses the Better Auth session cookie. See [admin-spa reference](../reference/admin-spa.md#mcp-oauth-consent-route).
+
+To build your own page instead:
+
 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`).
@@ -88,6 +94,29 @@ The client sends the user's browser to `/oauth/authorize`. Terreno checks the cl
 
 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.
 
+### Apps without a Terreno JWT
+
+`authenticateMiddleware()` calls `next()` when `req.user` is already set, so the consent routes do not require a JWT or a Better Auth session. Set the approving user in `addMiddleware`, which runs before these routes. Limit that to the consent paths. `GET /oauth/authorize` stays the unauthenticated redirect that starts the flow.
+
+The user object needs `_id`. Approve issues the grant to that id and records that user's `tokenEpoch`. `userForThisRequest` must resolve a session the app has already verified, such as a signed session cookie. Do not set `req.user` from an unverified header or query parameter. That user becomes the subject of the grant.
+
+```typescript
+new TerrenoApp({userModel: User, mcpOAuth: {consentUrl, enabled: true, issuer}})
+  .addMiddleware(async (req, _res, next) => {
+    if (!req.path.startsWith("/oauth/authorize/")) {
+      next();
+      return;
+    }
+    const user = await userForThisRequest(req);
+    if (user) {
+      req.user = user;
+    }
+    next();
+  });
+```
+
+Call `GET /oauth/authorize/<request>` and `POST .../approve` or `.../deny` with no `Authorization` header. `mcp_` and `mcpat_` bearers are still rejected on those routes.
+
 ## 3. Connect a client
 
 Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the rest:
@@ -98,6 +127,32 @@ Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the res
 
 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.
 
+## Headless clients (client credentials)
+
+A sandbox or another server has no browser, so it cannot run the authorization-code flow. Create a confidential client bound to a service-account user. The helper returns the secret once. Store it, then exchange it at `POST /oauth/token`. Dynamic registration stays public-only and still rejects client secrets.
+
+```typescript
+import {McpOAuthClient} from "@terreno/api";
+
+const {client, clientSecret} = await McpOAuthClient.issueConfidential({
+  clientName: "Sandbox agent",
+  tokenEndpointAuthMethod: "client_secret_basic", // or "client_secret_post"
+  userId: serviceAccount._id,
+});
+```
+
+`client_secret_basic` sends `Authorization: Basic` with the form-encoded `client_id:client_secret`. `client_secret_post` sends `client_id` and `client_secret` in the form body. The client must use the method it was created with.
+
+```bash
+# Form-encode the id and secret before base64. A raw colon join breaks when either value contains '%' or ':'.
+AUTH=$(node -e 'const [id, secret] = process.argv.slice(1); process.stdout.write(Buffer.from(`${encodeURIComponent(id)}:${encodeURIComponent(secret)}`).toString("base64"))' "$CLIENT_ID" "$CLIENT_SECRET")
+curl -X POST https://api.example.com/oauth/token \
+  -H "Authorization: Basic $AUTH" \
+  -d grant_type=client_credentials
+```
+
+The response is an `mcpat_…` access token and no refresh token. It acts as `userId`, with `credential: "oauth"`. Disabling that user, or bumping `tokenEpoch`, ends the token the same way it ends an authorization-code token. `McpOAuthClient.revoke(clientId)` ends every token that client holds, and a revoked client cannot start a new authorization or token grant. `deleteOne`, `findOneAndDelete`, and `deleteMany` do the same. `bulkWrite` skips those hooks, so use `revoke` when a bulk write removes clients.
+
 ## 4. Check it
 
 ```bash
@@ -128,7 +183,9 @@ Refresh tokens rotate on every use. If an old refresh token comes back, Terreno
 
 ## Security notes
 
-- Only public clients with PKCE `S256` are supported. `plain` PKCE and client secrets are rejected.
+- Public clients use PKCE `S256` only. `plain` PKCE is rejected. Confidential clients use `client_credentials` with `client_secret_basic` or `client_secret_post`. `private_key_jwt` is not supported. Dynamic registration cannot create a confidential client.
 - 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`.
+
+To put `/mcp` on the public internet behind a Cloudflare Tunnel, see [Expose an MCP server safely](expose-mcp-server-safely.md).

package/dist/docs/versioned/next/how-to/expose-mcp-server-safely.md

@@ -0,0 +1,140 @@
+# Expose an MCP server safely
+
+Put a Terreno backend's `POST /mcp` on the public internet with OAuth 2.1 for interactive clients, service tokens for static-key clients, and a Cloudflare Tunnel in front, so no inbound port is open on the host. The admin console stays behind Cloudflare Access.
+
+This guide fits any Terreno backend with MCP tools. It is written for the single-binary MCP server from the `bootstrap-mcp-server` skill, which serves `/mcp` and the admin console (including its OAuth consent screen at `/console/oauth/consent`) from one origin.
+
+## Prerequisites
+
+- A Terreno backend with at least one MCP tool ([Expose MCP tools](expose-mcp-tools.md))
+- A domain on Cloudflare, for example `example.com`, and `cloudflared` on the host that runs the backend
+- A hostname for the server, for example `mcp.example.com`
+
+## What is public and what is not
+
+| Path | Who calls it | Exposure |
+| --- | --- | --- |
+| `POST /mcp` | MCP clients | Public. Every request needs a Bearer credential. |
+| `/.well-known/oauth-protected-resource/mcp`, `/.well-known/oauth-authorization-server` | MCP clients during discovery | Public |
+| `/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/revoke` | MCP clients and the user's browser | Public, rate limited |
+| `/console` (including `/console/oauth/consent`), `/api/auth` | Operators, and any user approving an OAuth connection (they sign in and approve in the console) | Behind Cloudflare Access when every OAuth approver is in the Access policy; otherwise public, guarded by Better Auth and the `admin` check |
+| `/admin` | The console's admin API | Behind Cloudflare Access when `/console` is |
+| `/health` | Uptime checks | Public |
+
+MCP clients cannot complete a Cloudflare Access login, so the first three rows must bypass Access. Everything else does not need to.
+
+## 1. Pick the credential for each client
+
+| Client | Credential | Guide |
+| --- | --- | --- |
+| Claude.ai custom connectors, ChatGPT connectors | OAuth 2.1 access token (`mcpat_…`) | [Enable MCP OAuth](enable-mcp-oauth.md) |
+| Perplexity, Cursor, Claude Code, MCP Inspector | Service token (`mcp_…`) | [Connect an MCP client with a service token](connect-mcp-service-token.md) |
+| A headless service you run | OAuth client credentials | [Enable MCP OAuth](enable-mcp-oauth.md#headless-clients-client-credentials) |
+
+Every credential acts as one user and gets that user's MCP permissions. Mint service tokens for the person who uses them, not for an admin account.
+
+## 2. Configure the backend for a public origin
+
+```typescript
+const publicUrl = "https://mcp.example.com";
+
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {enabled: true, publicMcpUrl: publicUrl},
+  mcpOAuth: {
+    allowedRedirectHosts: ["claude.ai", "chatgpt.com"],
+    consentUrl: `${publicUrl}/console/oauth/consent`,
+    dynamicClientRegistration: true,
+    enabled: true,
+    issuer: publicUrl,
+  },
+  rateLimit: {store: "memory", trustProxy: "loopback"}, // cloudflared on the same host
+});
+```
+
+- `issuer` must be the exact origin clients reach. Discovery documents, the `WWW-Authenticate` challenge, and token audiences are built from it. If it says `http://localhost:4000`, every remote client fails discovery.
+- Keep `allowedRedirectHosts` to the clients you support. With dynamic client registration on, anyone can register a client, and this list is what stops a registered client from sending authorization codes to a host you did not choose.
+- Turn rate limiting on. Registration and token requests are unauthenticated.
+- Set `trustProxy` for the proxy in front of the app. With `cloudflared` on the same host, every request arrives from `127.0.0.1`; `"loopback"` tells Express to read the client address from `X-Forwarded-For` instead. Confirm with one request that `req.ip` is your public address. Without it, every visitor shares one rate-limit bucket.
+- Set `BETTER_AUTH_URL` to the same public origin so console sign-in cookies are issued for it.
+
+## 3. Create a named tunnel
+
+Use a named tunnel. A quick tunnel (`cloudflared tunnel --url …`) gets a new `trycloudflare.com` hostname on every run, so the `issuer`, the discovery documents, and every client registered against the old hostname break. Cloudflare documents quick tunnels as a testing tool.
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create mcp
+cloudflared tunnel route dns mcp mcp.example.com
+```
+
+Write `~/.cloudflared/config.yml`:
+
+```yaml
+tunnel: mcp
+credentials-file: /home/<user>/.cloudflared/<tunnel-id>.json
+ingress:
+  - hostname: mcp.example.com
+    service: http://127.0.0.1:4000
+  - service: http_status:404
+```
+
+Run it as a service (`sudo cloudflared service install`), and check:
+
+```bash
+curl -s https://mcp.example.com/health
+curl -si -X POST https://mcp.example.com/mcp | grep -i www-authenticate
+```
+
+The second command prints `WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"`. If the URL in it is not your public hostname, fix `issuer`.
+
+## 4. Close the direct path
+
+The tunnel makes an outbound connection, so the backend needs no inbound port. Block the backend port (4000 above) at the host firewall so the only way in is through Cloudflare, where Access and Cloudflare's own protections apply. Do not port-forward it from a router.
+
+## 5. Put the console behind Cloudflare Access
+
+In Cloudflare Zero Trust, add a **self-hosted** Access application for `mcp.example.com` with these paths, and an Allow policy for your operators' emails or identity-provider group:
+
+- `/console`
+- `/admin`
+- `/api/auth`
+
+That works only when every user who approves an OAuth connection is in the policy, because approving needs the console's consent screen, its sign-in page, and Better Auth. When people outside the policy connect clients too, leave `/console` and `/api/auth` out of the Access application and rely on Better Auth sign-in and the `admin` check. You can still keep `/admin` behind Access, since only operators (who are in the policy) call it.
+
+Do not add `/mcp`, `/.well-known`, or the other `/oauth/*` paths. An Access application on the bare hostname covers them too, so scope it to paths.
+
+Access is a second layer, not a replacement: the admin routes still require `admin: true`, and the console still requires a Better Auth session.
+
+## 6. Connect a client and check it
+
+1. Claude.ai: **Settings → Connectors → Add custom connector**, paste `https://mcp.example.com/mcp`, connect, approve on the consent page.
+2. If you registered `mcpAdminModels()` ([Manage MCP from the admin panel](manage-mcp-in-admin.md)), open **MCP OAuth clients** and **MCP OAuth connections** in the console and confirm the new client and connection.
+3. Static-key client: mint a token with `POST /mcp/service-tokens` (signed in as that user), then run `tools/list` with `Authorization: Bearer mcp_…`.
+
+## Revoking access
+
+- One service token: delete it on **MCP service tokens**, or the owner calls `DELETE /mcp/service-tokens/<id>`.
+- Every MCP credential one user holds: run the `mcp-sign-out-everywhere` admin script.
+- One OAuth connection: delete it on **MCP OAuth connections**, or have the client call `/oauth/revoke`.
+- Everything a user holds: disable the user, or reset their password or revoke their sessions (both bump `tokenEpoch`). Their OAuth grants and service tokens stop working on the next request. See [Enable MCP OAuth](enable-mcp-oauth.md#revoking-access).
+- Cut all traffic at once: stop the tunnel (`sudo systemctl stop cloudflared`).
+
+## Security checklist
+
+- [ ] `issuer` and `BETTER_AUTH_URL` equal the tunnel hostname
+- [ ] Named tunnel, not a quick tunnel
+- [ ] Backend port closed to inbound traffic
+- [ ] `rateLimit` on, with `trustProxy` set so `req.ip` is the visitor, not the proxy
+- [ ] `allowedRedirectHosts` lists only supported clients
+- [ ] Access covers `/console` and `/api/auth` only when every OAuth approver is in the policy (`/admin` can always be covered), and never `/mcp`, `/.well-known`, or `/oauth/*`
+- [ ] MCP tools expose only the methods each model needs (`mcp: {methods: ["list", "read"]}` unless writes are intended)
+- [ ] Credentials are minted per person, never shared from an admin account
+
+## Related
+
+- [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md)
+- [Connect an MCP client with a service token](connect-mcp-service-token.md)
+- [Expose MCP tools](expose-mcp-tools.md)
+- [Manage MCP from the admin panel](manage-mcp-in-admin.md)
+- [Rate limiting](rate-limiting.md)

package/dist/docs/versioned/next/how-to/install-agent-skills.md

@@ -19,12 +19,12 @@ takes a plugin skill's command from the frontmatter `name`.
 
 | Host | Plugin | Invoke Grow | Scan plugin | Invoke Aim |
 | --- | --- | --- | --- | --- |
-| Cursor | `terreno-planning` | `/terreno-1-grow` | `terreno-scan` | `/terreno-scan-1-aim` |
-| Codex | `terreno-planning` | `$terreno-1-grow` | `terreno-scan` | `$terreno-scan-1-aim` |
-| Claude Code | `terreno` | `/terreno:1-grow` | `terreno-scan` | `/terreno-scan:1-aim` |
+| Cursor | `terreno-planning` | `/terreno-1-grow` | `terreno-loop` | `/terreno-loop-1-aim` |
+| Codex | `terreno-planning` | `$terreno-1-grow` | `terreno-loop` | `$terreno-loop-1-aim` |
+| Claude Code | `terreno` | `/terreno:1-grow` | `terreno-loop` | `/terreno-loop:1-aim` |
 
-`terreno-scan` depends on the lifecycle plugin: Plot hands each slice to Grow. Its
-resident loop (`/terreno-scan:loop`, `/terreno-scan-loop`, `$terreno-scan-loop`) keeps a
+`terreno-loop` depends on the lifecycle plugin: Plot hands each slice to Grow. Its
+resident loop (`/terreno-loop:run`, `/terreno-loop-run`, `$terreno-loop-run`) keeps a
 goal running and heartbeats over the PRs it opens. See the
 [scan plugin reference](../reference/scan-plugin.md).
 
@@ -37,7 +37,7 @@ Install `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://gith
 ```text
 codex plugin marketplace add TerrenoLabs/terreno
 codex plugin install terreno-planning --source terreno-plugins
-codex plugin install terreno-scan --source terreno-plugins
+codex plugin install terreno-loop --source terreno-plugins
 $terreno-1-grow
 ```
 
@@ -51,7 +51,7 @@ Codex installs the canonical plugin at
 ```text
 /plugin marketplace add TerrenoLabs/terreno
 /plugin install terreno@terreno-plugins
-/plugin install terreno-scan@terreno-plugins
+/plugin install terreno-loop@terreno-plugins
 /terreno:1-grow
 ```
 
@@ -59,7 +59,29 @@ Marketplace: [`.claude-plugin/marketplace.json`](https://github.com/TerrenoLabs/
 Claude Code stages, app skills, and agents come from the generated copy at
 [`plugins/terreno-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-claude);
 scan stages come from
-[`plugins/terreno-scan-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-scan-claude).
+[`plugins/terreno-loop-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-loop-claude).
+
+#### Pick a channel
+
+Register one channel. Each one provides plugins named `terreno` and `terreno-loop`, so
+two channels give duplicate `/terreno:*` skills.
+
+| Channel | Tracks | Add the marketplace | Install |
+| --- | --- | --- | --- |
+| Master | Every merge to `master` | `/plugin marketplace add TerrenoLabs/terreno` | `/plugin install terreno@terreno-plugins` |
+| Pinned release | One release tag, frozen | `/plugin marketplace add TerrenoLabs/terreno#<version>` | `/plugin install terreno@terreno-plugins` |
+| Latest release | The newest stable release, from npm | `/plugin marketplace add https://raw.githubusercontent.com/TerrenoLabs/terreno/master/plugins/claude-release/.claude-plugin/marketplace.json` | `/plugin install terreno@terreno-releases` |
+
+The release channel installs `@terreno/agent-plugin` and `@terreno/agent-plugin-loop`
+from npm. Both are published in lockstep with every other `@terreno/*` package, and
+their plugin version is the Terreno release. To move a pinned install to another release, remove
+the marketplace and add it again at the new tag. Only tags from 57.21.0 on carry
+distinct plugin versions. Older tags all report `2.12.0`, so switching between two of
+them can be skipped as already up to date.
+
+Claude Code does not auto-update third-party marketplaces by default. Run
+`/plugin update terreno@<marketplace>`, or turn on auto-update for the marketplace in
+`/plugin` → **Marketplaces**.
 
 ## What you get
 
@@ -67,10 +89,10 @@ scan stages come from
 | --- | --- |
 | Lifecycle | `terreno-1-grow` … `terreno-5-taste`, `terreno-pick-roast-loop`, `terreno-planning-loop`, `terreno-taste-sweep` |
 | Terreno apps | backend, UI, admin interfaces, data, schema, SDK, prompts, upgrades, deployment |
-| Testing | `terreno-test-setup` (bootstrap backend, frontend, mobile), `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests`, `backend-test-env` |
-| Docs | `update-docs`, `update-agent-docs`, architecture skills |
+| Testing | `terreno-test-setup` (bootstrap backend, frontend, mobile), `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests`, `backend-test-env`, `backfill-regression` (propose manual regression cases for approval) |
+| Docs | `update-docs`, `backfill-user-guide` (draft end-user guide pages for approval), `update-agent-docs`, architecture skills |
 | GitHub | issues, review, UI verification, PR screenshots (`attach-pr-media`), release, dependency updates |
-| Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |
+| Code scans | `terreno-loop-1-aim` … `terreno-loop-5-track`, `terreno-loop-campaign`, `terreno-loop-run` |
 | Expo and native | `track-upstream-expo`, `upgrading-expo`, `store-assets`, deployment / EAS skills |
 | Plugin agents | `pre-commit`, `ui-verifier` |
 
@@ -84,12 +106,12 @@ Canonical sources:
 
 1. `plugins/terreno-planning/skills/` — lifecycle and reusable Terreno app workflows
 2. `plugins/terreno-planning/agents/` — reusable verification agents
-3. `plugins/terreno-scan/skills/` — scan stages and the campaign loop
+3. `plugins/terreno-loop/skills/` — scan stages and the campaign loop
 4. `.rulesync/skills/` — repository-only and optional Expo skills (`bun run rules` generates agent copies)
 5. `<package>/.ai/skills/` — package/MCP-specific copies; not installable overlays
 
 `plugins/terreno-claude/` is generated from sources 1 and 2, and
-`plugins/terreno-scan-claude/` from source 3, both with shortened skill names.
+`plugins/terreno-loop-claude/` from source 3, both with shortened skill names.
 Codex uses the canonical plugin plus committed `.codex-plugin/plugin.json` and
 `.agents/plugins/marketplace.json` — do not generate a third plugin tree.
 

package/dist/docs/versioned/next/how-to/manage-mcp-in-admin.md

@@ -0,0 +1,79 @@
+# Manage MCP from the admin panel
+
+Add admin screens for an app's MCP server: service tokens, OAuth clients, OAuth connections, a request log, and a tool registry with on/off switches. Add a one-click "sign out of MCP everywhere" script for a user.
+
+## Prerequisites
+
+- A `TerrenoApp` backend with at least one MCP tool ([Expose MCP tools](expose-mcp-tools.md))
+- `AdminApp` from `@terreno/admin-backend` and an admin UI (`@terreno/admin-spa` or `@terreno/admin-frontend`)
+- Service tokens or MCP OAuth turned on if you want those screens to show data ([service tokens](connect-mcp-service-token.md), [MCP OAuth](enable-mcp-oauth.md))
+
+## 1. Turn on the request log and tool registry
+
+Both are off by default.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpRequestLog: {enabled: true, retentionDays: 30},
+  mcpToolSettings: true,
+  // mcpServiceTokens, mcpOAuth, ...
+});
+```
+
+- The request log stores one row per `tools/call`: tool, user, credential type, service token or OAuth client, duration, outcome, and the error class when the tool threw. It never stores tool arguments, results, or error messages, so it is safe for apps that handle personal data. Rows are deleted after `retentionDays`.
+- The tool registry records every tool at startup. An admin can switch a tool off; it then disappears from `tools/list` and `tools/call` rejects it, for every user and client. The process that saved the switch applies it on the next request; other server instances apply it within 5 seconds. If the settings read fails, the server keeps the last switches it read, and refuses MCP requests when it has none.
+
+## 2. Register the screens and script
+
+```typescript
+import {AdminApp, mcpAdminModels, mcpAdminScripts} from "@terreno/admin-backend";
+
+new AdminApp({
+  models: [...appAdminModels, ...mcpAdminModels({requestLog: true, toolSettings: true})],
+  scripts: [...appScripts, ...mcpAdminScripts()],
+});
+```
+
+Set `requestLog` and `toolSettings` to match the `TerrenoApp` options from step 1. Both default to `false`, like the server options: a request log screen with logging off stays empty, and tool switches with `mcpToolSettings` off do nothing.
+
+With RBAC (`AdminApp({accessControl})`), add the statements and grant them to the roles that run MCP:
+
+```typescript
+import {mcpAdminStatements} from "@terreno/admin-backend";
+
+export const appStatements = {...terrenoStatements, ...mcpAdminStatements, /* ... */};
+```
+
+## 3. Use the screens
+
+The admin sidebar shows an **MCP** group:
+
+| Screen | Use it to |
+| --- | --- |
+| MCP service tokens | See each user's `mcp_` keys and when they were last used. Delete revokes a key. |
+| MCP OAuth clients | See registered connectors (Claude.ai, ChatGPT, headless clients) and their redirect URLs. Delete removes the client and revokes everything issued to it. |
+| MCP OAuth connections | See who approved which client and when. Each row is one token pair; rows with the same `familyId` are one connection. Delete revokes that connection. |
+| MCP request log | See recent tool calls by tool, user, client, outcome, and duration. Filter by user or client to see which clients a user has connected recently. |
+| MCP tools | Switch a tool off or on. Only `enabled` can be changed. `registered: false` means the running server no longer has that tool. |
+
+MCP over HTTP is stateless, so there is no list of open connections. "Who is connected" means recent activity in the request log plus active rows in the token and connection screens.
+
+## 4. Sign a user out of MCP everywhere
+
+Run the `mcp-sign-out-everywhere` script from **Scripts** with `user` set to the user's id or email. Run it as a dry run first: it reports how many OAuth connections and service tokens it would revoke. The wet run revokes them all; the user's clients must reconnect.
+
+To end every MCP credential and every app session at once, reset the user's password or revoke their sessions instead. That bumps `tokenEpoch`, which ends OAuth grants and service tokens on their next use.
+
+## Check it
+
+1. Call a tool with a service token, then open **MCP request log**: a row shows the tool, `outcome: ok`, and the token.
+2. Switch that tool off in **MCP tools** and run `tools/list` again: the tool is gone.
+3. Delete the token's row in **MCP service tokens** and call the tool again: the token no longer authenticates (401 with MCP OAuth on, otherwise the tool refuses an anonymous caller).
+
+## Related
+
+- [Expose an MCP server safely](expose-mcp-server-safely.md)
+- [Enable MCP OAuth](enable-mcp-oauth.md)
+- [admin-backend reference: MCP screens](../reference/admin-backend.md#mcp-screens)
+- [api reference: MCP request log and tool settings](../reference/api.md#mcp-request-log-and-tool-settings)

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

@@ -6,6 +6,15 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 
 `modelRouter` `realtime`, `realtimeList`, `realtimeDocument`, and `setRealtimeSocket` are **deprecated** and **will be removed in Terreno 58**. `RealtimeApp` stays as the socket host for syncdb. Removal checklist: [`docs/tasks/remove-legacy-realtime.md`](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/remove-legacy-realtime.md).
 
+`installTerrenoDevConsoleLogger` moved to `@terreno/syncdb`. The `@terreno/rtk` export is a **deprecated** re-export kept for the deprecation window. Change the import and pass the base URL:
+
+```typescript
+import {baseUrl} from "@terreno/rtk";
+import {installTerrenoDevConsoleLogger} from "@terreno/syncdb";
+
+installTerrenoDevConsoleLogger({baseUrl});
+```
+
 ## 1. Before you start
 
 | Decision | Requirement | Why |

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

@@ -79,4 +79,4 @@ To set a password from your own server code (for example an admin action), call
 
 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, token, secret, and code fields (any key name, any depth) 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. With `BetterAuthApp` registered, the JWT routes only replace an existing JWT password, because `POST /auth/login` has no second factor: `POST /auth/forgotPassword` mails no link to an app User without one (the response is still 202), and `POST /auth/resetPassword` refuses that User's token with 400 `legacy-password-reset-unavailable`, setting no password. That account (for example a social-only one) resets through Better Auth. Without Better Auth, the JWT routes still let any user set a password. 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/recover-locked-out-user.md

@@ -0,0 +1,112 @@
+# Recover a locked-out user
+
+Help a user who lost their authenticator, passkey, or social account get back in. Platform
+staff use `/users/:id/security`; org-admins use `/orgs/:orgId/members/:userId/security`. Both
+run the same handlers, and every change writes a security `AuditEvent`.
+
+## Before you start
+
+1. Register `AuditApp` and `AccountSecurityApp` on the `TerrenoApp`:
+
+   ```typescript
+   import {AccountSecurityApp, AuditApp, BetterAuthApp, TerrenoApp} from "@terreno/api";
+
+   new TerrenoApp({accessControl: access, organizations: true, userModel: User})
+     .register(new BetterAuthApp({config: betterAuthConfig}))
+     .register(new AuditApp())
+     .register(new AccountSecurityApp())
+     .start();
+   ```
+
+2. For `disable` and `enable`, apply `isDisabledPlugin` to the User schema.
+3. For `send-password-reset`, set `sendMail` and `publicAppUrl` in `BetterAuthConfig`.
+4. For the org path, turn organizations on (`organizations: true`). `TerrenoApp` hands the
+   registered `AccountSecurityApp` to `OrgsApp`, which mounts the org routes.
+
+## Who can do what
+
+| Action | Route suffix | Platform staff (`user:manageSecurity`) | Org-admin of the user's org |
+| --- | --- | --- | --- |
+| Read the summary | `GET /security` | Yes | Yes |
+| Reset two-factor | `POST /security/reset-two-factor` | Yes | Yes |
+| Remove a passkey | `DELETE /security/passkeys/:passkeyId` | Yes | Yes |
+| Unlink a provider | `DELETE /security/accounts/:providerId` | Yes | Yes |
+| Sign out everywhere | `POST /security/revoke-sessions` | Yes | Yes |
+| Send a password reset | `POST /security/send-password-reset` | Yes | Yes |
+| Disable or enable the account | `POST /security/disable`, `/enable` | Yes | No |
+| Suspend the membership | `POST /security/suspend-membership` | Through the org path | Yes |
+| Issue a sign-in link | `POST /security/issue-sign-in-link` | `superadmin` only (`user:issueSignInLink`) | No |
+
+`superadmin` and `operator` hold `user:manageSecurity`. An org-admin is a user whose active
+`Membership` in that org has `roleName: "org-admin"`.
+
+Nobody can act on themselves, or on someone who holds a permission they lack. An org-admin can't
+reach platform staff or `admin: true` users, members of other orgs, or suspended members. Platform
+staff on the org path are judged the same way as on the platform path, so an org-only permission
+does not block them.
+
+## Platform path
+
+Prefix every route with `/users/<userId>`.
+
+1. Read the summary to see the user's sign-in methods and the actions that apply:
+
+   ```bash
+   curl -H "Authorization: Bearer $TOKEN" https://api.example.com/users/<userId>/security
+   ```
+
+   `data.actions` lists only the actions that apply to this user and that you may run.
+2. Run the action that fixes the problem:
+   - Lost authenticator: `POST .../reset-two-factor`. The user signs in with their password and
+     can enroll again.
+   - Lost device with a passkey: `DELETE .../passkeys/<passkeyId>` (ids are in the summary).
+   - Lost social account: `DELETE .../accounts/<providerId>`.
+   - Stolen device: `POST .../revoke-sessions`.
+   - Forgotten password: `POST .../send-password-reset`.
+   - Compromised account: `POST .../disable`. Later, `POST .../enable`.
+   - Legacy user with no password and no inbox: `POST .../issue-sign-in-link`, then give the
+     user the returned link yourself. Only a superadmin can do this.
+3. Removing the user's last sign-in method answers `409` unless their email is verified. With a
+   verified email, the route also mails a password reset.
+
+## Org path
+
+Prefix every route with `/orgs/<orgId>/members/<userId>`. The user must be an active member of
+`<orgId>`. They may belong to other orgs too.
+
+1. Read the summary: `GET /orgs/<orgId>/members/<userId>/security`.
+2. Run the same recovery actions as the platform path (2FA, passkey, provider, sessions, reset).
+3. To cut the user off from your org, run `POST .../suspend-membership`. It suspends only their
+   membership in `<orgId>`. They still sign in and keep their other orgs.
+4. To bring a suspended member back, use the membership route:
+   `PATCH /orgs/<orgId>/members/<memberId>` with `{"status": "active"}`. A suspended member is out
+   of reach of the security routes until then.
+
+To stop an org-admin from attaching an existing user by email and acting on them right away, set
+a minimum membership age:
+
+```typescript
+new TerrenoApp({
+  accessControl: access,
+  organizations: {orgRecovery: {minMembershipDays: 7}},
+  userModel: User,
+});
+```
+
+## Check the audit trail
+
+Every change is one `AuditEvent` with `source: "security"`. Org actions carry the org's id in
+`organizationId`. When `sendMail` is configured, each change also emails the user (except
+`send-password-reset`, whose reset email is the notice). For `issue-sign-in-link` the email says a
+link was created, never the link itself. The email says "an administrator" and never names you;
+see
+[Notifications](../reference/account-security.md#notifications).
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://api.example.com/audit-events?source=security&recordId=<userId>"
+```
+
+Related: [Account security reference](../reference/account-security.md),
+[How organization tenancy works](../explanation/organizations.md#member-recovery),
+[Enable the framework audit log](audit-log.md).