@terreno/mcp 58.0.0-beta.1 → 58.0.0-beta.3

package/src/docs/versioned/57.15.0/how-to/debug-with-mcp.md

@@ -1,160 +0,0 @@
-# Debug a Terreno app with MCP
-
-Start the backend and frontend, reproduce the failure once, then inspect the merged runtime evidence
-instead of copying logs into the agent chat.
-
-## 1. Read the latest error
-
-Call the local MCP tool:
-
-```json
-{"name":"last_error","arguments":{"sources":["backend","browser","metro","app"]}}
-```
-
-It returns the newest error-level JSONL/CDP entry. Use `read_logs` when the failure needs surrounding
-events:
-
-```json
-{
-  "name": "read_logs",
-  "arguments": {
-    "entries": 100,
-    "level": "error",
-    "sources": ["backend", "browser", "metro", "app"]
-  }
-}
-```
-
-`backend` and `browser` read durable JSONL; `metro` and `app` read in-memory rings populated from
-Metro `/events` and CDP. Connection status in the response explains when either live source is
-unavailable.
-
-CLI equivalents:
-
-```bash
-terreno logs last-error --sources backend,browser,metro,app
-terreno logs --entries 100 --level error --sources backend,browser,metro,app
-```
-
-## 2. Inspect client state
-
-Check authentication and non-synced RTK Query cache state:
-
-```json
-{"name":"get_rtk_state","arguments":{"slice":"rtk","query":"todos"}}
-```
-
-The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
-cannot access the app heap directly. `slice: "auth"` prefers the Better Auth slice and falls back to
-legacy JWT auth; pass `betterAuth` to request that exact slice. The CLI equivalent is:
-
-Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
-returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
-
-```bash
-terreno state --slice rtk --query todos
-```
-
-## 3. Inspect and change SyncDB state
-
-Create the app client with `debug: true`, then inspect the same state that powers
-the SyncDB debugger:
-
-```json
-{"name":"get_syncdb_state","arguments":{"collection":"todos"}}
-```
-
-The result includes entities (including tombstones, seq/stream, and pending ids),
-decoded outbox rows, conflicts, cursors, known streams, repair markers, aggregate
-status, and debugger events. Sensitive fields are returned as `[REDACTED]`.
-
-Capture state before and after reproduction, then compare it:
-
-```json
-{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
-{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
-{"name":"syncdb_snapshot","arguments":{"action":"compare","snapshotId":"syncdb-...-1","otherSnapshotId":"syncdb-...-2"}}
-```
-
-Snapshots live in the local MCP process. Each capture privately retains the
-TinyBase mergeable content so `mergeSnapshot` can CRDT-merge it back later
-without wiping newer local rows (later HLCs win, including deletes). `get` and
-`compare` never return that merge payload. To restore a specific captured row,
-use `setLocalEntity` from `syncdb_snapshot` `get`.
-
-State changes require an explicit local opt-in:
-
-```bash
-TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
-```
-
-Then use `syncdb_action`. Normal writes should use `mutate`; `flush` drains the
-outbox, and `reconcile` catches up from server snapshots:
-
-```json
-{"name":"syncdb_action","arguments":{"action":"mutate","collection":"todos","operation":"update","id":"todo-1","data":{"completed":true}}}
-{"name":"syncdb_action","arguments":{"action":"flush"}}
-{"name":"syncdb_action","arguments":{"action":"reconcile"}}
-```
-
-Other actions are `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`,
-`goOnline`, `clearDebug`, `setLocalEntity`, `deleteLocalEntity`, and
-`mergeSnapshot`. Direct local edits bypass server validation and outbox
-semantics. `mergeSnapshot` CRDT-merges the captured TinyBase content into the
-live store (later HLCs win) instead of replacing it. Capture a baseline first
-and use these only for fault injection or repair.
-
-## 4. Prove the web fix
-
-Use Bun 1.4's built-in WebView through the local `browser` tool:
-
-```json
-{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082"}}
-{"name":"browser","arguments":{"action":"wait","timeout":1000}}
-{"name":"browser","arguments":{"action":"click","selector":"[data-testid=save]"}}
-{"name":"browser","arguments":{"action":"snapshot"}}
-{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/save-result.png"}}
-{"name":"browser","arguments":{"action":"close"}}
-```
-
-The session persists between MCP calls. `snapshot` returns visible text and up to 200 interactive
-elements so the agent can choose selectors and verify state without image guessing. `screenshot`
-saves the viewport for the PR or walkthrough.
-WebView console output is not added to `browser.log`; call `read_logs` alongside this flow when the
-running app posts browser logs to the backend collector. The collector accepts local-loopback
-traffic before login; devices or remote browsers must send the app's normal authentication.
-
-The equivalent one-process CLI sequence is:
-
-```bash
-terreno web http://localhost:8082 \
-  --action '{"action":"click","selector":"[data-testid=save]"}' \
-  --snapshot \
-  --screenshot /opt/cursor/artifacts/save-result.png
-```
-
-## 5. Verify the native fix in the running app
-
-Navigation and arbitrary evaluation are disabled by default. Opt in only for local debugging:
-
-```bash
-TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
-```
-
-Then call `navigate` with `{"path":"/profile"}` or run:
-
-```bash
-TERRENO_MCP_EVAL=1 terreno navigate /profile
-```
-
-Confirm the target screen renders, then call `last_error` again. A successful fix has no new
-error-level entry after the navigation timestamp.
-
-## Connection problems
-
-- Upgrade to Bun 1.4 or newer when `Bun.WebView requires Bun 1.4 or newer` appears.
-- Set `BUN_CHROME_PATH` if WebView cannot discover Chrome, Chromium, or Edge on Linux or Windows.
-- Set `TERRENO_PROJECT_ROOT` if logs or package versions come from the wrong directory.
-- Set `TERRENO_METRO_URL` if Metro is not on the frontend script's `--port`.
-- Close React Native DevTools when Hermes reports another debugger connection.
-- Use only `backend,browser` sources when Metro is intentionally stopped.

package/src/docs/versioned/57.15.0/how-to/deploy-backend-to-cloud-run.md

@@ -1,119 +0,0 @@
-# Deploy backend to Cloud Run
-
-Deploy a Terreno `@terreno/api` backend (for example `example-backend`) to Google Cloud Run with Secret Manager.
-
-Replace placeholders: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$REPOSITORY`.
-
-## Prerequisites
-
-- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
-- GCP project with billing enabled
-- MongoDB Atlas cluster (or other replica set) — [deployment baseline](../explanation/deployment-baseline.md)
-- Docker (local build) or Cloud Build
-
-Enable APIs:
-
-```bash
-gcloud services enable run.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com --project="$PROJECT_ID"
-```
-
-## 1. Create Artifact Registry
-
-```bash
-gcloud artifacts repositories create "$REPOSITORY" \
-  --repository-format=docker \
-  --location="$REGION" \
-  --project="$PROJECT_ID"
-```
-
-## 2. Build and push the image
-
-From the **repository root** (the Dockerfile expects the monorepo context):
-
-```bash
-docker build -f example-backend/Dockerfile -t "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" .
-docker push "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest"
-```
-
-## 3. Create secrets
-
-Create Secret Manager secrets (values added out of band):
-
-```bash
-for name in mongodb-uri token-secret token-issuer refresh-token-secret session-secret; do
-  gcloud secrets create "$SERVICE_NAME-$name" --project="$PROJECT_ID" --replication-policy=automatic
-done
-```
-
-Add secret values (example for MongoDB URI):
-
-```bash
-echo -n 'mongodb+srv://user:pass@cluster.example/terreno?retryWrites=true&w=majority' | \
-  gcloud secrets versions add "$SERVICE_NAME-mongodb-uri" --data-file=- --project="$PROJECT_ID"
-```
-
-Repeat for `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, and `SESSION_SECRET`.
-
-For Better Auth, also create `better-auth-secret` and set `AUTH_PROVIDER=better-auth` plus `BETTER_AUTH_URL` at deploy time. See [Configure Better Auth](configure-better-auth.md).
-
-## 4. Runtime service account
-
-```bash
-gcloud iam service-accounts create "$SERVICE_NAME-runtime" --project="$PROJECT_ID"
-
-gcloud projects add-iam-policy-binding "$PROJECT_ID" \
-  --member="serviceAccount:$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
-  --role="roles/secretmanager.secretAccessor"
-```
-
-Grant object access on your uploads bucket separately if using GCS file storage.
-
-## 5. Deploy to Cloud Run
-
-```bash
-gcloud run deploy "$SERVICE_NAME" \
-  --image="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" \
-  --region="$REGION" \
-  --project="$PROJECT_ID" \
-  --platform=managed \
-  --port=3000 \
-  --session-affinity \
-  --timeout=3600 \
-  --min-instances=1 \
-  --allow-unauthenticated \
-  --service-account="$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
-  --set-secrets="MONGO_URI=$SERVICE_NAME-mongodb-uri:latest,TOKEN_SECRET=$SERVICE_NAME-token-secret:latest,TOKEN_ISSUER=$SERVICE_NAME-token-issuer:latest,REFRESH_TOKEN_SECRET=$SERVICE_NAME-refresh-token-secret:latest,SESSION_SECRET=$SERVICE_NAME-session-secret:latest" \
-  --set-env-vars="NODE_ENV=production"
-```
-
-Adjust `min-instances` to `0` for dev sandboxes (websockets will churn on cold start).
-
-## 6. Verify
-
-```bash
-SERVICE_URL=$(gcloud run services describe "$SERVICE_NAME" --region="$REGION" --project="$PROJECT_ID" --format='value(status.url)')
-curl -s "$SERVICE_URL/health" | jq .
-```
-
-Expect `"healthy": true`.
-
-## Production constraints
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` |
-| Socket connections drop after ~5 minutes | Default request timeout (300s) | Raise `--timeout` (for example `3600`) |
-| Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
-| Bun-compiled container never opens its port while creating indexes | OpenTelemetry Mongoose instrumentation patched an already-loaded Mongoose module | Do not explicitly patch Mongoose in the compiled binary; retain HTTP/Express tracing |
-| Container hangs before listening when cloud logging initializes | A network logging transport blocks startup | Log to stdout/stderr during boot; Cloud Run ingests both streams |
-| `gcloud run deploy --tag` fails citing an old revision that never became Ready | That tag still points at the failed revision; `--remove-tags` keeps it in the traffic spec | Rebuild traffic with `--to-revisions=<live>=100` plus `--set-tags` of Ready tags only, deploy `--no-traffic` without `--tag`, then `--update-tags` the new revision |
-| A zero-traffic preview tag returns `503` with `{"status":"starting"}` indefinitely | The early TCP listener satisfies Cloud Run's startup probe before Mongo and seed work finish; request-only CPU then starves idle boot work | Deploy preview revisions with `--no-cpu-throttling`, then poll the tagged `/health` URL for `"healthy":true` before reporting deployment success |
-| First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
-| Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
-
-## Related
-
-- [Deployment baseline](../explanation/deployment-baseline.md)
-- [Environment variables](../reference/environment-variables.md)
-- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md)
-- [GCP architecture](../explanation/deployment-architecture-gcp.md)

package/src/docs/versioned/57.15.0/how-to/deploy-to-gcp.md

@@ -1,36 +0,0 @@
-# Deploy to Google Cloud Platform
-
-Deploy a Terreno full-stack app to GCP: Cloud Run for the backend, GCS + Cloud CDN for the static web export.
-
-## Before you start
-
-Read the [deployment baseline](../explanation/deployment-baseline.md) — seven requirements (replica-set MongoDB, auth secrets, build-time `EXPO_PUBLIC_API_URL`, and more) apply to every provider.
-
-## Guides
-
-| Guide | What it covers |
-|-------|----------------|
-| [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) | Container image, Secret Manager, Cloud Run with session affinity |
-| [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) | Static web export, bucket + CDN setup, cache invalidation |
-| [Build for web](build-for-web.md) | Export command, `EXPO_PUBLIC_API_URL`, local verification |
-
-## Architecture
-
-[GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
-
-## Scripts
-
-- [`scripts/setup-gcs-hosting.sh`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
-
-## Environment variables
-
-[Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
-
-## Operator-specific deployment
-
-Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
-
-## Related
-
-- [Environment variables](../reference/environment-variables.md)
-- [Deployment baseline](../explanation/deployment-baseline.md)

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

@@ -1,202 +0,0 @@
-# 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. Better Auth session
-3. JWT
-
-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. 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.
-
-## 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.
-
-## Custom tools
-
-CRUD tools cover one model at a time. 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.15.0/how-to/github-actions-ci.md

@@ -1,41 +0,0 @@
-# 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.