@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/versioned/next/reference/mcp-server.md

@@ -1,1354 +1,642 @@
 # @terreno/mcp
 
-Published npm package for the Terreno Model Context Protocol (MCP) servers. The monorepo directory
-is `mcp-server/`. The package ships two servers with separate tool sets:
+Published npm package for the Terreno Model Context Protocol (MCP) server. The monorepo directory is still `mcp-server/`. The package exposes:
 
-| Server | npm bin | Entry | Transport | Registers |
-|--------|---------|-------|-----------|-----------|
-| Hosted `terreno-mcp` | `terreno-mcp` → `dist/index.js` | `src/index.ts`, `src/httpApp.ts` | Streamable HTTP, stateless | 14 tools, 9 prompts, documentation resources |
-| Local `terreno-mcp-local` | `terreno-mcp-local` → `dist/local/index.js` | `src/local/index.ts`, `src/local/localServer.ts` | stdio | 13 tools (no prompts, no resources) |
+- **`terreno-mcp`** — HTTP server used in Cloud Run and local debugging (`src/index.ts`)
+- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): app/database/log/browser diagnostics and SyncDB state/action/snapshot tools (the Redux `get_rtk_state` tool was removed in Terreno 58). `evaluate`, `navigate`, and SyncDB state changes are gated by `TERRENO_MCP_EVAL`. Metro URL defaults from `frontend/package.json` `--port` or `TERRENO_METRO_URL`. `application_info` reads bootstrap `backend/` + `frontend/`, or this monorepo's `example-backend/` + `example-frontend/` (bootstrap names win when both exist).
 
-The hosted server gives an agent documentation search, upgrade notes, and code generators. It never
-sees your project. The local server runs inside your project and reads its packages, database, logs,
-Metro, and running app.
+It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
+For editor configuration and runtime prerequisites, see
+[Set up Terreno MCP](../how-to/set-up-terreno-mcp.md). For the end-to-end diagnostic workflow, see
+[Debug a Terreno app with MCP](../how-to/debug-with-mcp.md).
 
-For editor configuration, see [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md). For the
-end-to-end diagnostic workflow, see [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md).
-
-Both HTTP MCP surfaces (`@terreno/mcp` and the `modelRouter` endpoint in `@terreno/api`) use the MCP
-TypeScript SDK v2 and speak the stateless `2026-07-28` protocol revision. The HTTP handlers retain
-the SDK's stateless legacy fallback for 2025-era clients. `terreno-mcp-local` uses v2 `serveStdio`
-with `legacy: "serve"`, which negotiates the connection era and pins one server instance for that
+Both HTTP MCP surfaces (`@terreno/mcp` and the `modelRouter` endpoint in
+`@terreno/api`) use the MCP TypeScript SDK v2 and speak the stateless
+`2026-07-28` protocol revision. The HTTP handlers retain the SDK's stateless
+legacy fallback for 2025-era clients. `terreno-mcp-local` uses v2 `serveStdio`,
+which negotiates the connection era and pins one server instance for that
 connection.
 
 ## Table of Contents
 
-- [Hosted server (`terreno-mcp`)](#hosted-server-terreno-mcp)
-  - [Endpoint](#endpoint)
-  - [Hosted tools](#hosted-tools)
-  - [Prompts](#prompts)
-  - [Resources](#resources)
-  - [Rate limiting](#rate-limiting)
-- [Local server (`terreno-mcp-local`)](#local-server-terreno-mcp-local)
-  - [Running the local server](#running-the-local-server)
-  - [Local tools](#local-tools)
-  - [`TERRENO_MCP_EVAL` gate](#terreno_mcp_eval-gate)
-  - [Metro and CDP connection](#metro-and-cdp-connection)
-  - [React Native DevTools and the `app` source](#react-native-devtools-and-the-app-source)
-- [What the local server can and cannot see](#what-the-local-server-can-and-cannot-see)
-- [Environment variables](#environment-variables)
+- [Overview](#overview)
+- [Installation](#installation)
+- [Resources](#resources)
+- [Tools](#tools)
+- [Prompts](#prompts)
+- [Environment Variables](#environment-variables)
 - [Development](#development)
-- [Architecture](#architecture)
-- [Deployment](#deployment)
 
-## Hosted server (`terreno-mcp`)
+## Overview
+
+The MCP server exposes Terreno's documentation and code generation capabilities through the Model Context Protocol, enabling AI assistants (like Claude in Cursor or Claude Desktop) to:
+
+- Access up-to-date documentation for all Terreno packages
+- Generate boilerplate code following Terreno conventions
+- Provide multi-step workflows for common development tasks
+
+**Key concepts:**
 
-### Endpoint
+- **Resources**: Read-only documentation from `docs/` directory
+- **Tools**: Code generators that return text (AI writes files), documentation search (`terreno_search_docs`, `terreno_get_component_docs`), upgrade notes (`terreno_get_upgrade_guide`), plus local-only tools when using `terreno-mcp-local`
+- **Prompts**: Pre-built multi-step instructions for complex workflows
 
-| Item | Value |
-|------|-------|
-| URL | `https://mcp.terreno.app/mcp` |
-| JSON-RPC routes | `ALL /mcp` and `POST /` (same handler, same rate-limit bucket) |
-| Health check | `GET /` → `{"mcpEndpoint":"/mcp","service":"terreno-mcp","status":"ok"}` (never rate limited) |
-| Sessions | None. Each request is independent; no `initialize` round trip is required. |
-| Request headers | `Accept: application/json, text/event-stream` is required; without both types the server returns JSON-RPC error `-32000` `Not Acceptable: Client must accept both application/json and text/event-stream` |
-| Response | An SSE stream of `event: message` frames (`responseMode: "auto"`) |
-| Logging | Every `tools/call` and `prompts/get` is logged with its name and arguments (`logger.info`), and the server is wrapped with `Sentry.wrapMcpServerWithSentry`. Do not put secrets or PHI in tool arguments. |
+## Installation
 
-`mcp.terreno.flourish.health` is the legacy hostname for the same service. Use
-`https://mcp.terreno.flourish.health/mcp` while `mcp.terreno.app` does not resolve
-(`getaddrinfo ENOTFOUND mcp.terreno.app`).
+### With Claude Desktop
 
-Editor entry (the Terreno servers `create-terreno-app` writes to `.cursor/mcp.json` and
-`.mcp.json`; the full files are in [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md)):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ``````json
 {
   "mcpServers": {
-    "terreno": {"type": "http", "url": "https://mcp.terreno.app/mcp"},
-    "terreno-local": {"command": "bunx", "args": ["-p", "@terreno/mcp", "terreno-mcp-local"]}
+    "terreno": {
+      "command": "bun",
+      "args": ["/absolute/path/to/terreno/mcp-server/dist/index.js"]
+    }
   }
 }
 ``````
 
-Raw HTTP call against a local build (`PORT=8799 bun dist/index.js`):
-
-``````bash
-curl -s -X POST http://127.0.0.1:8799/mcp \
-  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"terreno_get_upgrade_guide","arguments":{"fromVersion":"57.14.0","toVersion":"57.14.0"}}}'
-``````
-
-``````text
-event: message
-data: {"result":{"content":[{"type":"text","text":"Recorded notes in 57.14.0 → 57.14.0: 57.14.0\n\n---\n\n# Upgrade to 57.14.0…"}]},"jsonrpc":"2.0","id":1}
-``````
-
-JSON-RPC methods: `tools/list`, `tools/call`, `prompts/list`, `prompts/get`, `resources/list`,
-`resources/read`.
-
-### Hosted tools
-
-Code generators return text. They do not write files: the agent receives the code and a target path
-and writes it. Scaffold a new app with [`create-terreno-app`](create-terreno-app.md)
-(`bunx create-terreno-app`), not an MCP tool. Every tool returns one text content block.
-
-| Tool | Purpose |
-|------|---------|
-| [`terreno_bootstrap_ai_rules`](#terreno_bootstrap_ai_rules) | Generate AI assistant rule files for an app |
-| [`terreno_search_docs`](#terreno_search_docs) | Keyword search over bundled Terreno docs |
-| [`terreno_get_component_docs`](#terreno_get_component_docs) | Props table for one `@terreno/ui` component |
-| [`terreno_get_upgrade_guide`](#terreno_get_upgrade_guide) | Bundled upgrade notes between two versions |
-| [`terreno_search_update_notes`](#terreno_search_update_notes) | Search upgrade notes and help-API announcements |
-| [`terreno_get_update_note`](#terreno_get_update_note) | Full text of one update note |
-| [`terreno_ask_update_help`](#terreno_ask_update_help) | Ranked update-note excerpts for a question |
-| [`terreno_generate_model`](#terreno_generate_model) | Mongoose model source |
-| [`terreno_generate_route`](#terreno_generate_route) | `modelRouter` route source |
-| [`terreno_generate_screen`](#terreno_generate_screen) | React Native screen source |
-| [`terreno_generate_form_fields`](#terreno_generate_form_fields) | `@terreno/ui` form field source |
-| [`terreno_validate_model_schema`](#terreno_validate_model_schema) | Check schema source against Terreno conventions |
-| [`terreno_validate_ui_blocks`](#terreno_validate_ui_blocks) | Validate a whole-reply UI block document |
-| [`terreno_install_admin`](#terreno_install_admin) | Admin panel files and setup steps |
-
-Example outputs below are real tool output, shortened with `…`.
-
-#### terreno_bootstrap_ai_rules
-
-Generate AI coding assistant rules (`AGENTS.md`, `CLAUDE.md`, `.rulesync/` sources, and
-`rulesync.jsonc`). Guideline bodies come from each package's `.ai/guidelines/core.md`, copied into
-this package at build time (`bun run sync-package-guidelines`). Defined in `src/bootstrap.ts`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `appName` | string | yes | App name in kebab-case |
-| `appDisplayName` | string | yes | Human-readable name |
-| `description` | string | no | One-line app description |
-| `packages` | string[] | no | Guideline packages to merge: `api`, `ui`, `rtk`, `syncdb`, `admin-backend`, `admin-frontend`, or the `@terreno/*` name. Omitted or no valid id means all six. |
-
-``````json
-{"name":"terreno_bootstrap_ai_rules","arguments":{"appName":"my-app","appDisplayName":"My App","packages":["api"]}}
-``````
-
-``````markdown
-# Bootstrap AI Rules for My App
-
-## Files to Create
-
-The following AI coding assistant configuration files need to be created:
-
-- `.rulesync/rules/00-root.md`
-- `backend/AGENTS.md`
-- `backend/CLAUDE.md`
-- `frontend/AGENTS.md`
-- `frontend/CLAUDE.md`
-- `rulesync.jsonc`
-
-## Instructions
-
-1. **Create all the files listed above.** Each file's content is provided below.
-…
-3. **Before generating, move hand-written rules into `.rulesync/rules/`.** `rulesync generate` overwrites the root `CLAUDE.md`, `AGENTS.md`, and `.github/copilot-instructions.md` and deletes every file under `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, and `.agents/memories/` that it did not generate. …
-
-4. **Delete the stale `.cursorrules`** that `create-terreno-app` wrote. …
-
-5. **Generate the editor files with rulesync:**
-   ```bash
-   bunx rulesync@9 generate
-   ```
-…
-``````
-
-`rulesync.jsonc` targets `cursor`, `claudecode`, `copilot`, and `agentsmd`. The one
-`root: true` rule in `00-root.md` covers all four. See
-[Agent guidelines](../explanation/agent-guidelines.md#terreno_bootstrap_ai_rules) for the
-generated editor files and how to add project rules.
-
-#### terreno_search_docs
-
-BM25-style keyword search over markdown bundled with the server: `docs/resources/*.md`, the Diátaxis
-docs synced into `docs/versioned/`, and per-component excerpts from `ui-types-documentation.json`.
-Call it before guessing a Terreno API.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `queries` | string[] | yes | One or more search phrases |
-| `packages` | string[] | no | Filter by package id or scope, e.g. `["api", "@terreno/ui"]` |
-| `tokenLimit` | number | no | Approximate markdown budget. Default 3000, clamped to 8000. |
-| `version` | string | no | `@terreno/*` lockstep version (e.g. `57.2.0`). Omit for current `next` docs. |
+### With Claude Code CLI
 
-An unmatched `version` falls back to the nearest retained snapshot (`website/versioned_docs/`,
-copied into `docs/versioned/` at build), and the response says so. Range prefixes such as
-`^57.2.0` are stripped. A non-array `queries` returns a usage message instead of results.
+Add to your project's `.claude/settings.json`:
 
 ``````json
-{"name":"terreno_search_docs","arguments":{"queries":["instanceActions"],"packages":["api"],"tokenLimit":300}}
+{
+  "mcpServers": {
+    "terreno": {
+      "command": "bun",
+      "args": ["./mcp-server/dist/index.js"]
+    }
+  }
+}
 ``````
 
-``````markdown
-# Terreno documentation search results
+### Building from Source
 
-Queries: "instanceActions"
-Docs version: next
-Package filter: api
+``````bash
+# From monorepo root
+bun install
+bun run mcp:build
 
-## modelRouter actions
-_Source: `versioned/next/reference/api.md` · Packages: api_
-…
-_…Truncated to approximate token budget (~300 tokens)._
+# Or from mcp-server directory
+cd mcp-server
+bun run build
 ``````
 
-#### terreno_get_component_docs
+## Resources
 
-Return the props table for one `@terreno/ui` component from `ui-types-documentation.json`, plus
-related markdown excerpts.
+Documentation resources accessible via `terreno://` protocol:
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `component` | string | yes | Exported component name, e.g. `Button` |
-| `version` | string | no | Lockstep version. A retained snapshot returns that version's generated component page (MDX chrome stripped); otherwise current props are used and the fallback is noted. |
+| URI | Description |
+|-----|-------------|
+| `terreno://docs/overview` | Monorepo overview and architecture |
+| `terreno://docs/api` | @terreno/api reference documentation |
+| `terreno://docs/ui` | @terreno/ui reference documentation |
+| `terreno://docs/syncdb` | @terreno/syncdb: synced collections, request client + generated API hooks, auth session, config, flags |
+| `terreno://docs/patterns` | Common patterns and best practices |
 
-``````json
-{"name":"terreno_get_component_docs","arguments":{"component":"Badge"}}
-``````
+**How it works:**
 
-``````markdown
-# Badge
+- Resources are loaded from markdown files in `docs/` directory
+- Content is transformed and served via MCP protocol
+- AI assistants cache resources for fast lookup
+- Updates require MCP server restart
 
-**Interface:** `BadgeProps`
+**Custom docs directory:**
 
-## Props
+Set `TERRENO_MCP_DOCS_DIR` environment variable to override default path.
 
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `color` | `"bold" | "subtle"` | No | For the "status" variant, whether the dot uses the bold (saturated) or …
-…
-``````
+## Tools
 
-A build without `ui-types-documentation.json` returns:
-`Component documentation is unavailable (ui-types-documentation.json not found). Run `bun run sync-ui-docs` in mcp-server before build.`
+Code generation tools return TypeScript/JavaScript code as text. **Code generation tools do not
+write files** — the AI assistant receives the code and writes it to appropriate locations. Scaffold
+a new app with [`create-terreno-app`](create-terreno-app.md) (`bunx create-terreno-app`), not an MCP
+tool.
 
-#### terreno_get_upgrade_guide
+The local `browser` tool is different: its `screenshot` action writes the requested image path so an
+agent can attach the rendered result as verification evidence. It keeps one headless session alive
+for the MCP connection. Call `open` first, perform interactions, call `snapshot` and `screenshot` to
+prove the final state, then call `close`.
 
-Return bundled lockstep upgrade notes between two versions. The response always lists which versions
-in the range have notes and names the gaps, because an empty concatenation would read as "nothing
-changed". Note format: `mcp-server/src/docs/upgrades/README.md`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `fromVersion` | string | yes | Installed `@terreno/*` semver. Must be ≤ `toVersion`. |
-| `toVersion` | string | yes | Target semver |
+`open` accepts only `http:` and `https:` URLs. Snapshots redact password input values; use them for
+page structure and visible state, not credential inspection.
 
 ``````json
-{"name":"terreno_get_upgrade_guide","arguments":{"fromVersion":"57.13.0","toVersion":"57.14.0"}}
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082","width":1280,"height":720}}
+{"name":"browser","arguments":{"action":"wait","timeout":1000}}
+{"name":"browser","arguments":{"action":"click","selector":"button[type=submit]"}}
+{"name":"browser","arguments":{"action":"snapshot"}}
+{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/app.png"}}
+{"name":"browser","arguments":{"action":"close"}}
 ``````
 
-``````markdown
-Recorded notes in 57.13.0 → 57.14.0: 57.14.0
+`browser` requires Bun 1.4 or newer. macOS uses system WebKit; Linux and Windows use an installed
+Chrome, Chromium, or Edge through the Chrome DevTools Protocol. Browser storage is ephemeral unless
+`open` receives `dataDir`. Set `TERRENO_MCP_EVAL=1` to enable its arbitrary-JavaScript `evaluate`
+action. Screenshot paths must stay under the project root or `/opt/cursor/artifacts`; persistent
+browser data must stay under the project root. Calls are serialized around the one session owned by
+the local MCP process.
 
----
+### SyncDB runtime tools
 
-# Upgrade to 57.14.0
+Create the app client with `debug: true` so it registers by its configured
+`name`. The local MCP uses the in-process registry when available and Hermes CDP
+for a separately running app.
 
-# Upgrading to 57.14.0
+| Tool | Purpose |
+| --- | --- |
+| `get_syncdb_state` | Read status, entities/tombstones, outbox, conflicts, cursors, streams, repair markers, values, and debugger events |
+| `syncdb_snapshot` | Capture, list, get, compare, or delete snapshots held by this MCP process |
+| `syncdb_action` | Mutate or directly edit local state, flush, reconcile/resync, resolve/retry, toggle offline, clear debug events, or merge a snapshot |
 
-**Action required:** No
-**Affected packages:** @terreno/syncdb
-…
-``````
+State and snapshot responses redact fields containing `password`, `token`,
+`secret`, `authorization`, or `cookie`. Snapshot merge payloads are retained
+privately and are not returned. Start the local MCP with
+`TERRENO_MCP_EVAL=1` before calling `syncdb_action`.
 
-#### terreno_search_update_notes
+See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md) for examples and
+safety guidance.
 
-Search bundled upgrade notes and, when `TERRENO_HELP_API_URL` is set, product announcements from a
-Terreno backend help API. Returns JSON.
+### terreno_search_docs
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `queries` | string[] | no | Keyword phrases |
-| `question` | string | no | Natural-language question, used as an extra phrase |
-| `source` | `auto` \| `bundled` \| `announcement` | no | Default `auto` |
-| `limit` | number | no | Default 10 |
-| `includeArchived` | boolean | no | Include archived announcements |
+BM25-style keyword search over markdown bundled with the MCP server: `docs/resources/*.md`, synced Diátaxis docs under `docs/versioned/`, and per-component excerpts derived from `ui-types-documentation.json`. **Prefer this tool before guessing** Terreno APIs (same posture as Laravel Boost `search-docs`).
 
-``````json
-{"name":"terreno_search_update_notes","arguments":{"queries":["rate limit"],"limit":2}}
-``````
+**Parameters:**
 
-``````json
+``````typescript
 {
-  "hits": [
-    {
-      "excerpt": "# Upgrading to 57.3.0 **Action required:** Yes **Affected packages:** @terreno/api, …",
-      "id": "upgrade:57.3.0",
-      "kind": "upgrade",
-      "title": "Terreno 57.3.0 upgrade notes",
-      "version": "57.3.0"
-    },
-    …
-  ],
-  "sources": [
-    "bundled-upgrades"
-  ]
+  queries: string[];       // Required — one or more search phrases
+  packages?: string[];     // Optional — filter by package id or scope, e.g. ["api", "@terreno/ui"]
+  tokenLimit?: number;      // Approximate max tokens of markdown (default 3000)
+  version?: string;         // Optional @terreno/* lockstep version (e.g. 57.2.0). Omit for current `next` docs.
 }
 ``````
 
-#### terreno_get_update_note
+Unmatched versions fall back to the nearest retained snapshot (`website/versioned_docs/`, copied into `docs/versioned/` at MCP build). The response names the resolved version and includes a note when a fallback happened. Pass the consumer app's `@terreno/*` version from `application_info` or `package.json`. Range prefixes such as `^57.2.0` are stripped before matching.
 
-Return the full text of one update note as JSON (`body`, `id`, `kind`, `title`, `version`).
+### terreno_get_component_docs
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `id` | string | yes | `upgrade:<semver>`, `announcement:<mongoId>`, or a bare upgrade semver |
-| `includeArchived` | boolean | no | Allow archived announcements from the help API |
+Returns the full props table for a single `@terreno/ui` component from `ui-types-documentation.json`, plus short related markdown excerpts when the search index finds matches.
 
-``````json
-{"name":"terreno_get_update_note","arguments":{"id":"upgrade:57.14.0"}}
-``````
+**Parameters:**
 
-``````json
+``````typescript
 {
-  "body": "Recorded notes in 57.14.0 → 57.14.0: 57.14.0\n\n---\n\n# Upgrade to 57.14.0\n…",
-  "id": "upgrade:57.14.0",
-  "kind": "upgrade",
-  "title": "Terreno 57.14.0 upgrade notes",
-  "version": "57.14.0"
+  component: string;        // e.g. "Button", "TextField"
+  version?: string;         // Optional @terreno/* lockstep version. Omit for current TypeDoc props.
 }
 ``````
 
-#### terreno_ask_update_help
-
-Answer a question with ranked update-note excerpts and the ids to fetch with
-`terreno_get_update_note`. Returns text.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `question` | string | yes | Question about what changed |
-| `limit` | number | no | Default 5 |
-| `includeArchived` | boolean | no | Include archived announcements |
-
-``````json
-{"name":"terreno_ask_update_help","arguments":{"question":"How do I enable rate limiting?","limit":2}}
-``````
-
-``````text
-Question: How do I enable rate limiting?
-Sources: bundled-upgrades
+When `version` matches a retained docs snapshot, the tool returns that version's generated component page (MDX chrome stripped). Snapshot filenames may be hyphenated (`text-field.mdx`) or concatenated (`userinactivity.mdx`); lookup tries both. Otherwise it uses current `ui-types-documentation.json` and notes the fallback.
 
-Top matches (call terreno_get_update_note with `id` for the full note):
-- [upgrade] Terreno 57.3.0 upgrade notes (upgrade:57.3.0)
-  # Upgrading to 57.3.0 **Action required:** Yes …
-- [upgrade] Terreno 58.0.0 upgrade notes (upgrade:58.0.0)
-  …
-``````
-
-#### terreno_generate_model
+### terreno_get_upgrade_guide
 
-Generate a Mongoose model with `strict: "throw"`, virtuals in `toJSON`/`toObject`, and
-`addDefaultPlugins`. Target path: `backend/src/models/<name>.ts`.
+Return bundled Terreno lockstep upgrade notes between two semver versions (markdown). Use before major bumps to `@terreno/*` packages. The response always lists which versions in the range **have** notes. If some or all versions have none, it names those gaps — an empty concatenation would look like “nothing changed,” which is usually false. `fromVersion` must be less than or equal to `toVersion`. Note format: `mcp-server/src/docs/upgrades/README.md`.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | string | yes | Model name, PascalCase |
-| `fields` | object[] | yes | Each `{name*, type*, required?, unique?, ref?, default?}`. `type`: `String`, `Number`, `Boolean`, `Date`, `ObjectId`, `Array`, `Mixed`. `default` is a string. |
-| `hasOwner` | boolean | no | Add a required `ownerId` referencing `User` |
-| `softDelete` | boolean | no | Enable soft delete |
+**Parameters:**
 
-``````json
-{"name":"terreno_generate_model","arguments":{"name":"Product","fields":[{"name":"title","type":"String","required":true}],"hasOwner":true}}
+``````typescript
+{
+  fromVersion: string;      // Installed @terreno/* semver (e.g. 0.19.0)
+  toVersion: string;        // Target semver to upgrade to (e.g. 0.20.0)
+}
 ``````
 
-``````text
-**IMPORTANT: Write this code to a file**
-
-File path: `backend/src/models/product.ts`
+### terreno_generate_model
 
-After writing the file:
-1. Export from `backend/src/models/index.ts`: `export * from "./product";`
+Generate a Mongoose model with Terreno conventions (timestamps, soft delete, owner tracking, type definitions).
 
----
+**Parameters:**
 
-import mongoose from "mongoose";
-import { addDefaultPlugins } from "@terreno/api";
-…
-const productSchema = new mongoose.Schema<ProductDocument, ProductModel>(
-  {
-    title: { type: String, required: true, trim: true },
-    ownerId: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
-  },
-…
+``````typescript
+{
+  name: string;              // Model name (PascalCase)
+  fields: Array<{
+    name: string;            // Field name (camelCase)
+    type: string;            // "String" | "Number" | "Boolean" | "Date" | "ObjectId"
+    required?: boolean;
+    default?: string;        // Default value as string
+    ref?: string;            // Referenced model name (for ObjectId)
+    description?: string;    // Field description (recommended)
+  }>;
+  hasOwner?: boolean;        // Add ownerId field (default: false)
+  softDelete?: boolean;      // Add deleted field (default: false)
+  timestamps?: boolean;      // Add created/updated fields (default: true)
+}
 ``````
 
-#### terreno_generate_route
-
-Generate a `modelRouter` route. Target path: `backend/src/api/<model>.ts`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `modelName` | string | yes | Model name, PascalCase |
-| `routePath` | string | yes | API path, e.g. `/products` |
-| `permissions` | object | no | `{create, list, read, update, delete}`, each `admin`, `any`, `authenticated`, `authOrReadOnly`, or `owner`. A missing or unknown value becomes `Permissions.IsAuthenticated`. |
-| `queryFields` | string[] | no | Allowed query fields |
-| `sort` | string | no | Default sort, e.g. `-created` |
-| `ownerFiltered` | boolean | no | Add `OwnerQueryFilter` and an `ownerId`-setting `preCreate` |
+**Example:**
 
 ``````json
-{"name":"terreno_generate_route","arguments":{"modelName":"Product","routePath":"/products","permissions":{"list":"authenticated"}}}
-``````
-
-``````text
-**IMPORTANT: Write this code to a file**
-
-File path: `backend/src/api/product.ts`
-
-After writing the file:
-1. Export from `backend/src/api/index.ts`: `export * from "./product";`
-2. Register in server setup: `addProductRoutes(router, options);`
-3. Regenerate frontend SDK: `bun run sdk` in the frontend directory
-…
+{
+  "name": "Product",
+  "fields": [
+    {"name": "title", "type": "String", "required": true, "description": "Product title"},
+    {"name": "price", "type": "Number", "required": true, "description": "Price in cents"},
+    {"name": "active", "type": "Boolean", "default": "true", "description": "Is product active"}
+  ],
+  "hasOwner": true,
+  "softDelete": true
+}
 ``````
 
-#### terreno_generate_screen
+**Returns:**
 
-Generate a React Native screen with `@terreno/ui` components and generated RTK Query hooks. Target
-path: `frontend/src/screens/<name>Screen.tsx`.
+- Model schema code with proper type definitions
+- Methods and statics structure
+- Plugin configuration
+- Export statements
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | string | yes | Screen name, PascalCase |
-| `type` | `list` \| `detail` \| `form` \| `empty` | yes | Screen kind |
-| `modelName` | string | no | Model for data fetching |
-| `fields` | string[] | no | Fields to display or edit |
+### terreno_generate_route
 
-``````json
-{"name":"terreno_generate_screen","arguments":{"name":"ProductList","type":"list","modelName":"Product","fields":["title"]}}
-``````
+Generate modelRouter configuration with permissions and query options.
 
-``````text
-**IMPORTANT: Write this code to a file**
+**Parameters:**
 
-File path: `frontend/src/screens/ProductListScreen.tsx`
-…
-import { useGetProductsQuery } from "@/store/openApiSdk";
-
-const ProductListScreen: React.FC = () => {
-  const { data: products, isLoading, error, refetch } = useGetProductsQuery({});
-…
+``````typescript
+{
+  modelName: string;         // Model name (PascalCase)
+  routePath: string;         // API path (e.g., "/products")
+  permissions?: {
+    create?: "any" | "authenticated" | "admin" | "owner";
+    list?: "any" | "authenticated" | "admin" | "owner";
+    read?: "any" | "authenticated" | "admin" | "owner";
+    update?: "any" | "authenticated" | "admin" | "owner";
+    delete?: "any" | "authenticated" | "admin" | "owner";
+  };
+  queryFields?: string[];    // Allowed query parameters
+  ownerFiltered?: boolean;   // Apply OwnerQueryFilter (default: false)
+  sort?: string;             // Default sort order (e.g., "-created")
+  populate?: Array<{path: string; fields?: string[]}>;
+}
 ``````
 
-#### terreno_generate_form_fields
-
-Generate `@terreno/ui` form fields and their state declarations. Fields use the real
-`@terreno/ui` props (`title`, `value`, `onChange`, `errorText`); `password` renders
-`TextField type="password"`, and `number` and date values are strings. A required field adds an
-`errors` state and `errorText={errors.<name>}`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `fields` | object[] | yes | Each `{name*, type*, label?, required?, options?}`. `type`: `text`, `email`, `password`, `number`, `textarea`, `select`, `boolean`, `date`, `datetime`. `options` is `[{label, value}]` for `select`. |
+**Example:**
 
 ``````json
-{"name":"terreno_generate_form_fields","arguments":{"fields":[{"name":"title","type":"text","required":true}]}}
-``````
-
-``````text
-**IMPORTANT: Write this code to a file**
-
-File path: `your form component file`
-…
-// State declarations (add to your component):
-  const [title, setTitle] = useState("");
-  …
-  const [errors, setErrors] = useState<Record<string, string | undefined>>({});
-
-// Form fields (add inside your component's return):
-…
+{
+  "modelName": "Product",
+  "routePath": "/products",
+  "permissions": {
+    "create": "authenticated",
+    "list": "any",
+    "read": "any",
+    "update": "owner",
+    "delete": "admin"
+  },
+  "queryFields": ["active", "category"],
+  "ownerFiltered": true,
+  "sort": "-created"
+}
 ``````
 
-#### terreno_validate_model_schema
-
-Check schema source text against Terreno conventions and list issues and suggestions. The
-model's `<Name>Document` type may be declared in the file or imported from the app's type files
-(`src/modelInterfaces.ts`, `src/types/models/`); "Missing TypeScript interfaces" means neither.
+**Returns:**
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `schema` | string | yes | Schema source code |
+- Router setup code with modelRouter configuration
+- Permission mapping
+- Lifecycle hooks structure
+- Instructions for registering route
 
-``````json
-{"name":"terreno_validate_model_schema","arguments":{"schema":"const s = new mongoose.Schema({title: {type: String}});"}}
-``````
+### terreno_generate_screen
 
-``````text
-Schema Validation Results:
+Generate React Native screen component with Terreno UI components.
 
-Issues Found:
-- Missing strict: 'throw' in schema options
-- Missing toJSON virtuals configuration
-- Missing default plugins
-- Missing TypeScript interfaces
+**Parameters:**
 
-Suggestions:
-…
+``````typescript
+{
+  name: string;              // Screen name (PascalCase)
+  type: "list" | "detail" | "form" | "empty";
+  modelName?: string;        // Model name for CRUD screens
+  fields?: string[];         // Fields to display/edit
+  collection?: string;       // Synced collection (default: kebab-case plural of modelName)
+}
 ``````
 
-#### terreno_validate_ui_blocks
-
-Validate one whole-reply YAML or JSON block document. The text is the report
-`terreno-blocks validate` prints: one line per problem, `path  CODE  message — fix`. A valid document
-with no warnings returns an empty string.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `document` | string | yes | The YAML or JSON document |
+**Example:**
 
 ``````json
-{"name":"terreno_validate_ui_blocks","arguments":{"document":"v: 1\nblocks:\n  - type: bogus\n"}}
-``````
-
-``````text
-blocks[0].type.type  INVALID_ENUM  blocks[0].type is not a supported block. — Set type to heading, text, metric, …, list, or html.
-``````
-
-#### terreno_install_admin
-
-Generate admin panel screen files and backend/frontend setup steps for `@terreno/admin-backend` and
-`@terreno/admin-frontend`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `models` | object[] | yes | Each `{modelName*, routePath*, displayName*, listFields*}`; `listFields` is string[] |
-
-``````json
-{"name":"terreno_install_admin","arguments":{"models":[{"modelName":"Todo","routePath":"/todos","displayName":"Todos","listFields":["title"]}]}}
+{
+  "name": "ProductList",
+  "type": "list",
+  "modelName": "Product",
+  "fields": ["title", "price", "active"]
+}
 ``````
 
-``````markdown
-# Install Admin Panel
+**Returns:**
 
-## Files to Create
+- React Native functional component
+- `@terreno/syncdb/react` hooks against the synced collection: `useQuery` + `useSyncStatus` (list), `useEntity` (detail), `useMutate().create` (form). For a model that is not synced, swap them for the generated `@/store/apiSdk` hooks
+- @terreno/ui components (Box, Text, Button, Page, etc.)
+- Empty and not-found states
 
-- `frontend/app/(tabs)/admin/index.tsx`
-- `frontend/app/(tabs)/admin/[model].tsx`
-- `frontend/app/(tabs)/admin/[model]/create.tsx`
-- `frontend/app/(tabs)/admin/[model]/[id].tsx`
+### terreno_generate_form_fields
 
-## Setup Instructions
+Generate form field components for a model.
 
-### Step 1: Add `@terreno/admin-backend` to backend
-…
-``````
+**Parameters:**
 
-### Prompts
-
-Multi-step workflow prompts, served by `prompts/list` and `prompts/get`. `terreno_bootstrap` is
-defined in `src/bootstrap.ts`; the rest in `src/prompts.ts`. `*` marks a required argument. All
-arguments are strings.
-
-| Prompt | Arguments | Purpose |
-|--------|-----------|---------|
-| `terreno_bootstrap` | `appName*`, `appDisplayName*` | Run `bunx create-terreno-app`, then `terreno_bootstrap_ai_rules` |
-| `terreno_create_crud_feature` | `name*`, `fields*` (`title:string,price:number`), `hasOwner` (`yes`/`no`) | Model, routes, and frontend screens |
-| `terreno_create_api_endpoint` | `path*`, `method*`, `description*` | Custom endpoint with OpenAPI docs |
-| `terreno_create_ui_component` | `name*`, `type*` (`display`, `interactive`, `form`, `layout`) | Reusable `@terreno/ui`-style component |
-| `terreno_create_form_screen` | `name*`, `fields*` (`name:text,email:email`), `endpoint*` | Form screen with validation |
-| `terreno_add_authentication` | `features` (`email,social,passwordReset`) | Login/signup screens and auth state |
-| `terreno_style_guide` | none | Terreno code style guide |
-| `terreno_migrate_to_terreno_app` | `serverFile` | Move from `setupServer` to `TerrenoApp` |
-| `terreno_upgrade` | `targetVersion` (omit for latest stable) | Lockstep upgrade: read notes, bump `@terreno/*`, test, delegate Expo SDK steps to the upgrading-expo skill |
-
-### Resources
-
-Read-only markdown, loaded once at startup from `<docs root>/resources/` (see
-`TERRENO_MCP_DOCS_DIR`). Restart the server to pick up changes.
-
-| URI | Name | Source |
-|-----|------|--------|
-| `terreno://docs/overview` | Terreno Overview | `overview.md` |
-| `terreno://docs/api` | @terreno/api Documentation | `api.md` |
-| `terreno://docs/ui` | @terreno/ui Documentation | `ui.md` |
-| `terreno://docs/syncdb` | @terreno/syncdb Documentation | `syncdb.md` |
-| `terreno://docs/rtk` | @terreno/rtk Documentation (legacy) | `rtk.md` |
-| `terreno://docs/patterns` | Terreno Patterns & Best Practices | `patterns.md` |
-| `terreno://docs/ui/components` | @terreno/ui Component Reference | Generated from `ui-types-documentation.json` |
-| `terreno://docs/ui/components/<slug>` | `<Component> Component` | One per component |
-
-The two component rows exist only when `ui-types-documentation.json` is bundled.
-
-### Rate limiting
-
-The hosted server limits its JSON-RPC routes per client IP: `/mcp` (all methods) and `POST /` share
-one bucket. The `GET /` health check is never limited. The local stdio server has no limit.
-
-- **Default:** 120 requests per 60 seconds per client IP, a fixed window. Search, codegen, and docs
-  calls are cheap per call (the search index is built once at startup), and an agent session makes
-  a few dozen calls a minute, so the default leaves room for several agents behind one NAT while
-  capping one abusive client at about 2 requests per second.
-- **Configure:** `TERRENO_MCP_RATE_LIMIT_MAX` (`0` turns the limit off, for example in local
-  development) and `TERRENO_MCP_RATE_LIMIT_WINDOW_MS`. An invalid value stops the server at startup
-  rather than running unlimited.
-- **Per instance:** counters live in memory on each Cloud Run instance. With `N` instances, one
-  client can make up to `N` times the limit in a window if its requests land on different
-  instances.
-- **Client IP:** on Cloud Run the server trusts one proxy hop, so the client IP is the address the
-  Google Front End appended to `X-Forwarded-For`. Entries a client writes into that header itself
-  are ignored, so a forged header cannot switch buckets. Off Cloud Run no proxy is trusted and the
-  socket address is used. Set `TERRENO_MCP_TRUST_PROXY_HOPS` when you add a proxy layer (for
-  example `2` behind an external HTTPS load balancer).
-
-A request over the limit gets HTTP `429` with `Retry-After`, `RateLimit`, and `RateLimit-Policy`
-headers and a JSON-RPC error body. `id` echoes the request id when the body is a single request
-with a string or number id; otherwise it is `null`.
-
-``````json
+``````typescript
 {
-  "jsonrpc": "2.0",
-  "error": {
-    "code": -32029,
-    "message": "Rate limit exceeded: 120 requests per 60 seconds per client IP. Retry after 42s.",
-    "data": {"limit": 120, "windowMs": 60000, "retryAfterSeconds": 42}
-  },
-  "id": 7
+  modelName: string;         // Model name (PascalCase)
+  fields: Array<{
+    name: string;
+    type: "text" | "number" | "boolean" | "date" | "select";
+    required?: boolean;
+    options?: string[];      // For select fields
+  }>;
 }
 ``````
 
-`-32029` is in the JSON-RPC range reserved for implementation-defined server errors. Clients
-should wait `retryAfterSeconds` (or `Retry-After`) before retrying.
-
-## Local server (`terreno-mcp-local`)
-
-### Running the local server
-
-Run it from the app repository root with `bunx -p @terreno/mcp terreno-mcp-local`. The bin and the
-package have different names, so `bunx` needs `-p` unless `@terreno/mcp` is already installed in
-the project (as in this monorepo). The bin is
-`#!/usr/bin/env bun`, so it needs Bun; the `browser` tool needs Bun 1.4 or newer. It registers tools
-only.
-
-Project root discovery (`src/local/projectRoot.ts`): `TERRENO_PROJECT_ROOT` when set. Otherwise it
-walks up to 20 directories from the working directory to the first directory with a `package.json`
-and both a backend workspace (`backend/` or `example-backend/`) and a frontend workspace
-(`frontend/` or `example-frontend/`), or one of them plus a non-empty `workspaces` array. With no
-match it uses the working directory. Bootstrap names win when both exist.
-
-Errors: a refused or invalid call usually returns explanatory text. A thrown error (for example from
-`browser`, or a database exception) becomes a JSON-RPC error with code `-32603` and the error
-message. An unknown tool name returns the text `Unknown tool: <name>`.
-
-### Local tools
-
-All schemas set `additionalProperties: false`. Every tool returns one text block, JSON for most
-tools. The server does not validate arguments against the schema: an unknown argument, such as
-`projection` on `database_query`, is ignored, not rejected. Check a result against the parameter
-table when it looks unfiltered.
-
-| Tool | Purpose | Gated by `TERRENO_MCP_EVAL` |
-|------|---------|------|
-| [`application_info`](#application_info) | Workspace packages and key dependency versions | no |
-| [`database_schema`](#database_schema) | Mongo collections, indexes, counts, model excerpts | no |
-| [`database_query`](#database_query) | Read-only Mongo queries | no |
-| [`read_logs`](#read_logs) | Merged backend, browser, Metro, and app log tail | no |
-| [`last_error`](#last_error) | Newest error-level log entry | no |
-| [`get_client_state`](#get_client_state) | RTK Query and SyncDB state of the running app | no |
-| [`get_rtk_state`](#get_rtk_state) | Deprecated alias of `get_client_state` | no |
-| [`get_syncdb_state`](#get_syncdb_state) | SyncDB client state | no |
-| [`syncdb_snapshot`](#syncdb_snapshot) | Capture and compare SyncDB snapshots | no |
-| [`syncdb_action`](#syncdb_action) | Change SyncDB client state | yes, every action |
-| [`evaluate`](#evaluate) | Run JavaScript in the app runtime | yes |
-| [`navigate`](#navigate) | Navigate the app with expo-router | yes |
-| [`browser`](#browser) | Drive a headless WebView | only the `evaluate` action |
-
-Example outputs below are real tool output, shortened with `…`. Where an output needs a running
-Hermes app, which the capture environment did not have, the section says so and shows only the
-call or the failure output.
-
-#### application_info
-
-Read the root `package.json` and the first backend (`backend/`, then `example-backend/`) and frontend
-(`frontend/`, then `example-frontend/`) `package.json`. It reports `@terreno/*` dependencies and
-`expo`, `react`, `react-native`, `mongoose`, `bun`, and `@types/bun` as declared (ranges such as
-`^57.2.0`, `catalog:`, or `workspace:*`, not resolved versions). It checks that `bun.lock` exists but
-does not parse it. Call it at the start of a session. No parameters.
+**Example:**
 
 ``````json
-{"name":"application_info","arguments":{}}
+{
+  "modelName": "Product",
+  "fields": [
+    {"name": "title", "type": "text", "required": true},
+    {"name": "price", "type": "number", "required": true},
+    {"name": "category", "type": "select", "options": ["electronics", "books", "clothing"]}
+  ]
+}
 ``````
 
-``````markdown
-# Application info
-
-- **projectRoot**: `…`
-- **root package**: @terreno/root @ 1.0.0
-- **bun.lock present**: yes
+**Returns:**
 
-## Backend workspace (example-backend/)
-- **name**: @terreno/example-backend
-- **version**: 1.0.0
-- @terreno/admin-backend: workspace:*
-…
-- **mongoose**: catalog:
-
-## Frontend workspace (example-frontend/)
-…
-- **react-native**: catalog:
-
-## Lockfile
-Workspace package versions are recorded under `workspaces` in `bun.lock`. Prefer installed semver over `latest` in generated code.
-``````
+- TextField, NumberField, SelectField components
+- Validation logic structure
+- Form state management pattern
 
-#### database_schema
+### terreno_validate_model_schema
 
-List live Mongo collections with `estimatedDocumentCount` and indexes, plus the first 80 lines of
-each `backend/src/models/*.ts` file (except `index.ts`), read as text. Only `backend/` is scanned,
-not `example-backend/`. Each call connects with Mongoose and disconnects at the end.
+Validate a Mongoose schema against Terreno conventions.
 
-Mongo URI: `MONGO_URI` from the environment, else `MONGO_URI`, else `MONGODB_URI` parsed from
-`<project root>/backend/.env`. `example-backend/.env` is not read.
+**Parameters:**
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `collectionFilter` | string | no | Case-insensitive substring filter on collection names |
-| `summary` | boolean | no | Count model files instead of printing excerpts |
-
-``````json
-{"name":"database_schema","arguments":{"summary":true}}
+``````typescript
+{
+  schemaCode: string;        // Full schema code to validate
+}
 ``````
 
-Output with no URI configured:
+**Returns:**
 
-``````markdown
-# Database schema
+- List of convention violations
+- Recommendations for fixes
+- Severity levels (error, warning, info)
 
-## Declared models (static scan of `backend/src/models/*.ts`)
+### terreno_validate_ui_blocks
 
-_(No model files found.)_
+Check one whole-reply YAML or JSON document. The text is the same report `terreno-blocks validate` prints: each problem is `path  CODE  message — fix`. A valid document with no warnings returns an empty string.
 
-## Live MongoDB
+**Parameters:**
 
-_Unavailable: set `MONGO_URI` in `backend/.env` or export `MONGO_URI` to include live collections._
+``````typescript
+{
+  document: string; // Required — the YAML or JSON document
+}
 ``````
 
-#### database_query
+**Returns:**
 
-Run one read-only query. Each call opens its own connection and closes it afterwards; queries time
-out after 10 seconds (`maxTimeMS`), and `aggregate` runs with `allowDiskUse: false`. Same URI
-resolution as `database_schema`. Results are returned unredacted, so avoid collections that hold
-credentials (Better Auth keeps password hashes in `account`).
+- The CLI report, including a trailing newline when there is at least one line
+- An empty string when the document is valid and has no warnings
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `collection` | string | yes | Collection name |
-| `operation` | `find` \| `aggregate` \| `countDocuments` \| `distinct` | yes | Operation |
-| `filter` | object | no | Query for `find`, `countDocuments`, `distinct`. Rejected anywhere it contains `$where`, `$function`, or `$accumulator`. |
-| `pipeline` | object[] | no | Stages for `aggregate`. Rejected anywhere it contains `$out`, `$merge`, or `$function`. |
-| `field` | string | for `distinct` | Field to collect |
-| `limit` | number | no | Rows or distinct values returned. Default 50, clamped 1–200. |
+### terreno_bootstrap_ai_rules
 
-Results: `find` and `aggregate` return `{collection, count, rows}`; `countDocuments` returns
-`{collection, count}`; `distinct` returns `{collection, field, truncated, values}`.
+Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).
 
-``````json
-{"name":"database_query","arguments":{"collection":"todos","operation":"aggregate","pipeline":[{"$group":{"_id":"$completed","count":{"$sum":1}}},{"$sort":{"_id":1}}]}}
-``````
+**Parameters:**
 
-``````json
+``````typescript
 {
-  "collection": "todos",
-  "count": 1,
-  "rows": [
-    {
-      "_id": false,
-      "count": 2
-    }
-  ]
+  appName: string;
+  appDisplayName: string;
+  description?: string;
+  /** Optional — which @terreno/* packages to merge into rules. Use ids like `api`, `ui`, `syncdb`, `admin-backend`, `admin-frontend`, or `@terreno/api`. Omit or pass only what the app uses so admin guidelines stay out of projects without the admin panel. */
+  packages?: string[];
 }
 ``````
 
-``````json
-{"name":"database_query","arguments":{"collection":"todos","operation":"aggregate","pipeline":[{"$out":"x"}]}}
-``````
+Guideline bodies are composed from per-package `.ai/guidelines/core.md` files, copied into this package at build time (`bun run sync-package-guidelines` in `mcp-server/`).
 
-``````text
-Pipeline rejected: `$out`, `$merge`, and `$function` are not allowed.
-``````
+**Returns:** Rules files and instructions for installing/syncing with rulesync.
 
-``````json
-{"name":"database_query","arguments":{"collection":"todos","operation":"find","filter":{"$where":"true"}}}
-``````
+### terreno_install_admin
 
-``````text
-Filter rejected: `$where`, `$function`, and `$accumulator` are not allowed.
-``````
+Generate admin panel integration for `@terreno/admin-backend` and `@terreno/admin-frontend`.
 
-#### read_logs
+**Parameters:** Model configurations with `modelName`, `routePath`, `displayName`, `listFields`, etc.
 
-Merge log entries from up to four sources, sort them by timestamp, and return the newest.
+**Returns:** Frontend screen files and backend/frontend setup snippets. The generated
+`admin/_layout.tsx` wraps the routes in `AdminProvider` with `apiOrigin={baseUrl}` (from
+`@terreno/syncdb/config`) and `getAuthHeaders` reading `authProvider.getToken()` from the
+scaffold's `frontend/store/syncdb.ts`. No `@terreno/rtk` import.
 
-| Source | Reads | Written by | Notes |
-|--------|-------|-----------|-------|
-| `backend` | `app.log` in each existing `<root>/backend/.terreno/logs`, `<root>/example-backend/.terreno/logs`, `<root>/.terreno/logs` | `@terreno/api` logger JSONL transport (see `TERRENO_LOG_FILE`) at `<backend cwd>/.terreno/logs/app.log` | No `stack` field: `logger.error` stacks are inside `message` |
-| `browser` | `browser.log` in the same directories | [`POST /__terreno/browser-logs`](api.md#development-browser-log-ingestion), fed by `installTerrenoDevConsoleLogger` from `@terreno/syncdb` | `console.error` entries carry no stack; uncaught errors carry `stack`. A render error caught by an error boundary is a `console.error` entry: no `stack`, unformatted `%o`/`%s` placeholders, and the component name in `message` |
-| `metro` | In-memory ring (2000) from Metro's `ws://<metro>/events` | Metro dev server | Always empty with Expo CLI 57 (see [Metro and CDP connection](#metro-and-cdp-connection)) |
-| `app` | In-memory ring (2000) of Hermes `Runtime.consoleAPICalled` over CDP | The running Hermes app | Needs a Hermes target; `stack` is a JSON string of the first 8 call frames; timestamps are receipt time |
+## Prompts
 
-The `metro` and `app` rings start filling on the first call that requests those sources and are
-held for the life of the MCP process. Earlier output is not captured.
+Multi-step workflow prompts that guide AI assistants through complex tasks.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `sources` | string[] | no | Any of `backend`, `browser`, `metro`, `app`. Default all four. |
-| `entries` | number | no | Default 200, clamped 1–2000. Limits lines read per file and the merged result. |
-| `level` | string | no | Exact, case-insensitive level match, e.g. `error` |
-| `since` | string | no | ISO-8601 instant. Drops entries before it; entries without a parseable timestamp are kept. |
+### terreno_bootstrap
 
-| Response field | Content |
-|----------------|---------|
-| `connection` | Always the CDP and Metro events status (see [Metro and CDP connection](#metro-and-cdp-connection)), even when `metro` and `app` were not requested |
-| `entries` | Each `{level, message, raw, source, timestamp}`; `raw` is the line as written |
-| `metroHint` | Connection details for the `metro` and `app` sources requested; absent when neither was requested |
-| `projectRoot` | Resolved project root |
-
-``````json
-{"name":"read_logs","arguments":{"level":"error","entries":3}}
-``````
-
-``````json
-{
-  "connection": "CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: connected",
-  "entries": [
-    …,
-    {
-      "level": "error",
-      "message": "Uncaught TypeError: Cannot read properties of undefined (reading 'profile')",
-      "raw": "{\"level\":\"error\",\"message\":\"Uncaught TypeError: Cannot read properties of undefined (reading 'profile')\",\"source\":\"browser\",\"stack\":\"TypeError: Cannot read properties of undefined (reading 'profile')\\n    at brokenHandler (eval at evaluate (:303:30), <anonymous>:4:19)\\n    at eval (eval at evaluate (:303:30), <anonymous>:6:22)\",\"timestamp\":\"2026-10-12T00:24:58.867+00:00\"}",
-      "source": "browser",
-      "timestamp": "2026-10-12T00:24:58.867+00:00"
-    },
-    {
-      "level": "error",
-      "message": "Fallthrough error: SyntaxError: JSON Parse error: Unexpected identifier \"broken\"\nSyntaxError: JSON Parse error: Unexpected identifier \"broken\"\n    at <parse> (:0)\n…",
-      "raw": "{\"level\":\"error\",\"message\":\"Fallthrough error: SyntaxError: …\",\"requestId\":\"2edcea24-66a8-40b6-821c-a62f57af91fc\",\"terrenoRequestLog\":{\"requestId\":\"2edcea24-66a8-40b6-821c-a62f57af91fc\",\"userId\":null},\"timestamp\":\"2026-10-12T00:25:13.380Z\"}",
-      "source": "backend",
-      "timestamp": "2026-10-12T00:25:13.380Z"
-    }
-  ],
-  "metroHint": "connected | Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)",
-  "projectRoot": "/workspace"
-}
-``````
+Workflow prompt for scaffolding a new Terreno app. Instructs the assistant to run `bunx create-terreno-app`, then `terreno_bootstrap_ai_rules`.
 
-`app` source output, captured against a test device that speaks Metro's device protocol (not a real
-Hermes runtime):
+**Arguments:**
 
-``````json
-{
-  "connection": "CDP: connected; Metro events: not connected",
-  "entries": [
-    …,
-    {"level": "info", "message": "fake app tick #94", "source": "app", "timestamp": "2026-10-12T00:47:43.238Z", "raw": "…"},
-    {"level": "error", "message": "fake app error #95", "source": "app", "timestamp": "2026-10-12T00:47:44.239Z", "raw": "{\"level\":\"error\",\"message\":\"fake app error #95\",\"source\":\"app\",\"stack\":\"[{\\\"columnNumber\\\":10,\\\"functionName\\\":\\\"tick\\\",\\\"lineNumber\\\":42,\\\"scriptId\\\":\\\"1\\\",\\\"url\\\":\\\"http://localhost:8082/index.bundle\\\"}]\",\"timestamp\":\"2026-10-12T00:47:44.239Z\"}"},
-    …
-  ],
-  "metroHint": "connected",
-  "projectRoot": "/workspace"
-}
-``````
+- `appName` (string) — Application name in kebab-case
+- `appDisplayName` (string) — Human-readable display name
 
-#### last_error
+### terreno_upgrade
 
-Return the newest `error`-level entry across the selected sources. It reads the last 500 lines of
-each file plus the `metro` and `app` rings. On a hit it returns the entry's `raw` line only: backend
-lines have no `source` field, and no connection status is appended.
+Lockstep Terreno upgrade workflow: read bundled upgrade notes, bump `@terreno/*` packages, run tests, and delegate Expo SDK steps to the official upgrading-expo skill.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `sources` | string[] | no | Any of `backend`, `browser`, `metro`, `app`. Default all four. |
+**Arguments:** `targetVersion` (optional) — target `@terreno/*` semver; omit to mean latest stable.
 
-``````json
-{"name":"last_error","arguments":{"sources":["browser"]}}
-``````
+### terreno_create_crud_feature
 
-``````text
-{"level":"error","message":"Uncaught TypeError: Cannot read properties of undefined (reading 'profile')","source":"browser","stack":"TypeError: Cannot read properties of undefined (reading 'profile')\n    at brokenHandler (eval at evaluate (:303:30), <anonymous>:4:19)\n    at eval (eval at evaluate (:303:30), <anonymous>:6:22)","timestamp":"2026-10-12T00:24:58.867+00:00"}
-``````
+Generate complete CRUD feature: backend model + routes + frontend screens.
 
-With no error-level entry:
+**Arguments:**
 
-``````text
-No recent error-level entries in selected sources (app). CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: connected
-``````
+- `name` (string) — Feature name (e.g., "Product")
+- `fields` (string) — Comma-separated fields: `title:string,price:number,active:boolean`
+- `hasOwner` (string) — "yes" or "no" (default: "no")
 
-#### get_client_state
+**Workflow:**
 
-Detect and read the running app's client data layer:
+1. Generate Mongoose model with type definitions
+2. Generate API routes with permissions
+3. Generate list screen with DataTable
+4. Generate detail screen
+5. Generate form screen with validation
+6. Provide instructions for:
+   - Registering routes in `server.ts`
+   - Regenerating SDK: `bun run sdk`
+   - Adding navigation
 
-- RTK Query: the Redux store registered by `registerTerrenoDevStore(store)` from `@terreno/rtk`
-  (`__DEV__` only) as `globalThis.__TERRENO_STORE__`.
-- SyncDB: clients created with `createSyncDb({debug: true})`, registered on
-  `globalThis.__TERRENO_SYNCDB__`.
+### terreno_create_api_endpoint
 
-It reads the in-process registries when the MCP process shares the app's heap; otherwise it runs a
-fixed read-only expression in the app through CDP `Runtime.evaluate` (not gated, because the caller
-cannot change the code). Keys matching `password`, `token`, `secret`, `authorization`, or `cookie`
-(case-insensitive) are returned as `[REDACTED]`.
+Generate custom (non-CRUD) API endpoint with OpenAPI documentation.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `slice` | string | no | RTK: `auth` (Better Auth slice, else legacy `auth`), `betterAuth`, `rtk` or `terreno-rtk`, or any top-level state key. Omit for auth plus the RTK Query cache summary. |
-| `query` | string | no | RTK: keep cache rows whose endpoint name or serialized args contain this substring (case-insensitive) |
-| `name` | string | no | SyncDB client name. Default the first registered client. |
-| `collection` | string | no | SyncDB collection filter |
-| `entityId` | string | no | SyncDB entity id filter |
-| `includeDebugEvents` | boolean | no | SyncDB: `false` returns debug stats without event bodies |
-| `limit` | number | no | SyncDB entities per collection. Default 500, max 2000. |
+**Arguments:**
 
-Response: `{layer, rtk?, syncdb?}`. `layer` is `rtk`, `syncdb`, `syncdb+rtk` (both payloads
-returned), or `none`. `rtk` holds `{auth, terrenoRtk: {queries, mutations}}` (rows are
-`{args, endpoint, status}`) or the requested slice. `syncdb` holds the SyncDB inspect output. With
-`layer: "none"` the response has `connection`, `hint`, and per-layer `reasons` instead.
+- `path` (string) — Endpoint path (e.g., "/stats/summary")
+- `method` (string) — HTTP method ("get", "post", "patch", "delete")
+- `description` (string) — What the endpoint does
 
-``````json
-{"name":"get_client_state","arguments":{}}
-``````
+**Workflow:**
 
-Output with Metro running and no Hermes app attached (a populated response needs a running Hermes
-app and is not shown):
+1. Generate route handler with asyncHandler
+2. Generate OpenAPI builder configuration
+3. Generate response types
+4. Provide authentication setup instructions
+5. Provide SDK regeneration instructions
 
-``````json
-{
-  "connection": "CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: not connected",
-  "hint": "No client data layer found. For RTK Query, call `registerTerrenoDevStore(store)` from @terreno/rtk in __DEV__. For SyncDB, create the client with `createSyncDb({debug: true})`. Keep the app running; when the MCP process cannot see the app heap, start Metro so CDP can reach Hermes (see `connection`).",
-  "layer": "none",
-  "reasons": {
-    "rtk": "Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)",
-    "syncdb": "Error: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)\nCDP: …"
-  }
-}
-``````
+### terreno_create_ui_component
 
-#### get_rtk_state
+Generate reusable UI component following @terreno/ui patterns.
 
-Deprecated alias of `get_client_state`, kept for one release. Same schema, same handler, same
-`{layer, rtk?, syncdb?}` response.
+**Arguments:**
 
-#### get_syncdb_state
+- `name` (string) — Component name (PascalCase)
+- `type` (string) — "display" | "interactive" | "form" | "layout"
+- `description` (string) — Component purpose
 
-Read a SyncDB client registered by `createSyncDb({debug: true})`: status, entities (including
-tombstones and pending metadata), decoded outbox, conflicts, cursors, streams, repair markers,
-values, and debugger events. Same access path and redaction as `get_client_state`. Not gated.
+**Workflow:**
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | string | no | Client name. Default the first registered client. |
-| `collection` | string | no | Collection filter |
-| `entityId` | string | no | Entity id filter |
-| `includeDebugEvents` | boolean | no | `false` returns debug stats without event bodies |
-| `limit` | number | no | Entities per collection. Default 500, max 2000. |
+1. Generate component structure with TypeScript types
+2. Include @terreno/ui imports (Box, Text, Button, etc.)
+3. Add prop definitions with JSDoc
+4. Include usage example
+5. Provide testing setup
 
-``````json
-{"name":"get_syncdb_state","arguments":{"collection":"todos"}}
-``````
+### terreno_create_form_screen
 
-On success the text is the redacted inspect output as JSON. With no reachable client it is the
-reason (shown without a Hermes app; a populated response is not shown):
+Generate form screen with validation and error handling.
 
-``````text
-Error: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)
-CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: not connected
-``````
+**Arguments:**
 
-#### syncdb_snapshot
+- `name` (string) — Screen name (e.g., "CreateProduct")
+- `modelName` (string) — Model being created/edited
+- `fields` (string) — Comma-separated: `title:text,price:number,active:boolean`
 
-Capture, list, read, compare, or delete SyncDB snapshots. Snapshots live in the MCP process memory
-and are lost when it exits. A capture keeps the full mergeable TinyBase content privately for a later
-`syncdb_action` `mergeSnapshot`; returned state is redacted. Not gated.
+**Workflow:**
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `action` | `capture` \| `list` \| `get` \| `compare` \| `delete` | yes | Operation |
-| `name`, `collection`, `entityId` | string | no | Capture filters, as in `get_syncdb_state` |
-| `includeDebugEvents` | boolean | no | Capture option |
-| `limit` | number | no | Capture option |
-| `snapshotId` | string | for `get`, `compare`, `delete` | Snapshot id from `capture` or `list` |
-| `otherSnapshotId` | string | for `compare` | Second snapshot. `compare` returns up to 200 path diffs. |
+1. Generate screen component with Page layout
+2. Add form fields from @terreno/ui
+3. Include validation logic
+4. Add generated `store/apiSdk.ts` mutation hooks (or syncdb `useMutate` for synced collections)
+5. Add loading/error/success states
+6. Provide navigation setup
 
-``````json
-{"name":"syncdb_snapshot","arguments":{"action":"list"}}
-``````
+### terreno_add_authentication
 
-``````json
-[]
-``````
+Generate authentication setup for new projects.
 
-#### syncdb_action
-
-Change a live SyncDB client, then return `{action, client, result, state}` with the redacted state
-after the change. Every action requires `TERRENO_MCP_EVAL`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `action` | enum | yes | `mutate`, `setLocalEntity`, `deleteLocalEntity`, `flush`, `reconcile`, `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`, `goOnline`, `clearDebug`, `mergeSnapshot` |
-| `name` | string | no | Client name |
-| `collection`, `id` | string | no | Target row for `mutate`, `setLocalEntity`, `deleteLocalEntity` |
-| `operation` | `create` \| `update` \| `delete` | no | For `mutate` |
-| `data` | object | no | Row data for `mutate`, `setLocalEntity` |
-| `maxAttempts` | number | no | For `mutate` |
-| `deleted` | boolean | no | For `setLocalEntity` |
-| `seq` | number | no | For `setLocalEntity` |
-| `stream` | string | no | For `setLocalEntity` |
-| `mutationId` | string | no | For `resolveConflict` |
-| `strategy` | `useServer` \| `keepMine` | no | For `resolveConflict` |
-| `entityId` | string | no | For `retryFailed` |
-| `snapshotId` | string | no | For `mergeSnapshot`; must belong to the same client |
+**Arguments:**
 
-``````json
-{"name":"syncdb_action","arguments":{"action":"flush"}}
-``````
+- `strategies` (string) — Comma-separated: "email", "github", "google"
+- `includeRefreshToken` (string) — "yes" or "no" (default: "yes")
 
-Without the opt-in:
+**Workflow:**
 
-``````text
-Refused: set `TERRENO_MCP_EVAL=1` to opt in to SyncDB state changes.
-``````
+1. Configure User model with passport-local-mongoose
+2. Set up auth routes in backend
+3. Wire `SessionProvider` / `useSession` from `@terreno/syncdb/auth` in the frontend
+4. Generate login screen
+5. Generate signup screen
+6. Set up token storage
+7. Provide environment variable list
 
-#### evaluate
+### terreno_migrate_to_terreno_app
 
-Run a JavaScript expression in the app's Hermes runtime with CDP `Runtime.evaluate`
-(`awaitPromise`, `returnByValue`). Returns `{result, status}` or `{error, status}`, where `status` is
-the connection status. Requires `TERRENO_MCP_EVAL`.
+Guide for migrating from `setupServer` to the `TerrenoApp` fluent API pattern.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `code` | string | yes | Expression to evaluate |
+**Arguments:**
 
-``````json
-{"name":"evaluate","arguments":{"code":"1 + 1"}}
-``````
+- `serverFile` (string, optional) — Path to server file to migrate (e.g., `src/server.ts`)
 
-Without the opt-in (a successful call needs a Hermes app and is not shown):
+### terreno_style_guide
 
-``````text
-Refused: set `TERRENO_MCP_EVAL=1` to opt in to `Runtime.evaluate` (arbitrary JS in the app runtime).
-``````
+Returns comprehensive code style guide from project documentation.
 
-#### navigate
+**No arguments required.**
 
-Run a fixed snippet in the app that calls `require("expo-router").router.navigate(path)`, or
-`push(path)` when `navigate` is missing. Returns `{result, status}` with `result` like
-`{ok, method}`, or `{error, status}`. Requires `TERRENO_MCP_EVAL`.
+**Returns:**
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | yes | expo-router path |
+- TypeScript conventions
+- React/React Native patterns
+- Backend API conventions
+- Testing practices
+- Logging guidelines
 
-``````json
-{"name":"navigate","arguments":{"path":"/settings"}}
-``````
+## Environment Variables
 
-Without the opt-in (a successful call needs a Hermes app and is not shown):
+### Server Configuration
 
-``````text
-Refused: set `TERRENO_MCP_EVAL=1` to opt in to CDP-driven navigation (runs a fixed expo-router snippet in the app).
-``````
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8080` | HTTP server port |
+| `MCP_HOST` or `HOST` | `0.0.0.0` | Server host address |
+| `TERRENO_MCP_DOCS_DIR` | `../docs` | Path to documentation directory (relative to dist/) |
+| `TERRENO_PROJECT_ROOT` | nearest Terreno project root | Override local package, database, and log discovery |
+| `TERRENO_METRO_URL` | Frontend script port or `http://localhost:8082` | Metro origin used for `/events` and CDP discovery |
+| `TERRENO_MCP_EVAL` | Disabled | Set to `1` to enable local MCP `evaluate`, `navigate`, and SyncDB state-changing actions |
+| `TERRENO_BROWSER_LOGS` | Enabled only when `NODE_ENV=development` | Set to `true` to opt in in another non-production environment or `false` to disable; production rejects the route, and non-loopback clients must authenticate |
 
-#### browser
-
-Drive a headless page with Bun's built-in `Bun.WebView`: system WebKit on macOS; on Linux and
-Windows, Chrome, Chromium, or Edge over the Chrome DevTools Protocol (set `BUN_CHROME_PATH` when Bun
-cannot find one). One session per MCP process; calls are serialized. Use it to exercise a changed web
-flow, then `snapshot` and `screenshot` as proof, then `close`.
-
-| Action | Uses | Notes |
-|--------|------|-------|
-| `open` | `url` (required), `width` (1280), `height` (720), `dataDir` | `http:`/`https:` only. Closes any open session. Storage is ephemeral unless `dataDir`, which must be under the project root. |
-| `click` | `selector` (required), `timeout` | `timeout` is the selector wait in ms |
-| `type` | `text`, `selector`, `timeout` | Clicks `selector` first when given |
-| `press` | `key` (required), `modifiers` | `modifiers`: `Shift`, `Control`, `Alt`, `Meta` |
-| `scroll` | `selector` or `x`/`y` | Scrolls to `selector`, else by the pixel delta |
-| `evaluate` | `code` (required) | Gated by `TERRENO_MCP_EVAL`; without it the call fails with JSON-RPC error `-32603` ``Refused: set `TERRENO_MCP_EVAL=1` to enable arbitrary JavaScript in the WebView.`` |
-| `snapshot` | none | Up to 200 visible interactive elements with a usable `selector`, plus page text (20 000 chars). Password input values are `[REDACTED]`. |
-| `screenshot` | `output` (required), `quality` | `.png`, `.jpg`/`.jpeg`, or `.webp` (other extensions write PNG). Path must be under the project root or `/opt/cursor/artifacts`. |
-| `back`, `forward`, `reload` | none | History navigation |
-| `wait` | `timeout` | Sleeps `timeout` ms (default 1000) |
-| `close` | none | Ends the session |
-
-Results are JSON with `action`, `ok`, and the page `title` and `url`, plus action-specific fields.
-Calling any page action before `open` fails with `No browser session. Run the open action first.`
+**Example:**
 
-``````json
-{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082","width":1280,"height":720}}
-{"name":"browser","arguments":{"action":"snapshot"}}
-{"name":"browser","arguments":{"action":"screenshot","output":"artifacts/app.png"}}
-{"name":"browser","arguments":{"action":"close"}}
+``````bash
+PORT=3001 HOST=localhost bun run start
 ``````
 
-``````json
-{
-  "action": "open",
-  "ok": true,
-  "title": "",
-  "url": "http://localhost:8082/"
-}
-``````
+## Development
 
-``````json
-{
-  "action": "snapshot",
-  "ok": true,
-  "snapshot": {
-    "elements": [
-      …,
-      {
-        "ariaLabel": "Text input field",
-        "disabled": false,
-        "name": null,
-        "placeholder": "Password",
-        "role": "input",
-        "selector": "#login-screen-password-input",
-        "text": "[REDACTED]",
-        "type": "password"
-      },
-      …,
-      {
-        "ariaLabel": "Log In",
-        "disabled": true,
-        "name": null,
-        "placeholder": null,
-        "role": "button",
-        "selector": "[data-testid=\"login-screen-submit-button\"]",
-        "text": "Log In",
-        "type": "button"
-      },
-      …
-    ],
-    "text": "Welcome Back\nEmail\nPassword\n\nLog In\nForgot password?\n…",
-    "title": "",
-    "url": "http://localhost:8082/login"
-  }
-}
-``````
+``````bash
+# Install dependencies
+bun install
 
-``````json
-{
-  "action": "screenshot",
-  "ok": true,
-  "output": "…/artifacts/app.png",
-  "title": "",
-  "url": "http://localhost:8082/"
-}
-``````
+# Build
+bun run build
 
-### `TERRENO_MCP_EVAL` gate
-
-`evaluate`, `navigate`, `syncdb_action`, and the `browser` `evaluate` action run only when the local
-server's environment has `TERRENO_MCP_EVAL=1` or `TERRENO_MCP_EVAL=true`. The variable is read on
-every call; set it in the editor's server entry (`"env": {"TERRENO_MCP_EVAL": "1"}`).
-
-| Gated | What it allows |
-|-------|----------------|
-| `evaluate` | Any JavaScript in the app's Hermes runtime |
-| `navigate` | A fixed expo-router snippet in the app runtime |
-| `syncdb_action` (all actions) | Writes to the app's local SyncDB store, outbox, and sync state |
-| `browser` `evaluate` | Any JavaScript in the WebView page |
-
-The gate exists because these calls run code with the app's full privileges: its session tokens and
-secure storage, its network access as the signed-in user, and its local data. An agent can be steered
-by text it reads, including log lines and database rows, so code execution in the app is a per-process
-opt-in rather than a default.
-
-Not gated: `get_client_state`, `get_rtk_state`, `get_syncdb_state`, and `syncdb_snapshot` also use
-`Runtime.evaluate` when the app is in another process, but only with fixed read expressions built by
-the server (caller values are JSON-encoded), and their output is redacted. `database_query` is
-read-only by operation allowlist and operator checks. The other `browser` actions only interact with
-the page as a user would.
-
-### Metro and CDP connection
-
-`read_logs` (`metro`, `app`), `last_error`, `get_client_state`, `get_syncdb_state`,
-`syncdb_snapshot`, `syncdb_action`, `evaluate`, and `navigate` share one module-level session
-(`src/local/metro/metroDevSession.ts`):
-
-- **Metro URL:** `TERRENO_METRO_URL`, else `--port N` from the frontend workspace's `scripts.start`
-  (or `scripts.web`), else `http://localhost:8082`.
-- **Target:** `GET <metro>/json/list` (4 s timeout); the first target whose title contains `hermes`,
-  else whose description contains `react native`, else the first with a `webSocketDebuggerUrl`. A
-  web browser tab is not a target, so the `app` source and the CDP paths need a Hermes app (dev build
-  or Expo Go) attached to Metro.
-- **Origin:** the debugger socket sends `Origin: <scheme>//127.0.0.1:<Metro port>`.
-  `@react-native/dev-middleware` rejects a socket without an Origin, and Expo CLI closes one whose
-  host is not `127.0.0.1:<Metro port>`. A base URL that reaches Metro through a port-remapping tunnel,
-  or a Metro whose server URL is overridden by `REACT_NATIVE_PACKAGER_HOSTNAME` or
-  `EXPO_PACKAGER_PROXY_URL`, still fails Expo's check.
-- **Lifetime:** connect lazily on first use, send `Runtime.enable`, then keep the socket for the life
-  of the MCP process. Each CDP call times out after 8 s. After a close, the next call that needs the
-  app reconnects, with no backoff.
-
-The status appears as `CDP: <cdp status>; Metro events: <events status>` in `read_logs`
-`connection`, in `last_error` misses, and in `get_client_state` `layer: "none"` responses.
-
-| CDP status | Meaning |
-|------------|---------|
-| `not connected` | No call has needed the app yet |
-| `connected to <title>` | This call opened a new socket |
-| `connected` | This call reused the open socket |
-| `Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)` | Metro answered, but no Hermes app is attached |
-| `TypeError: Unable to connect. Is the computer able to access the url?` | Metro is not reachable (Bun's fetch error; the Metro URL is not included) |
-| `Error: CDP websocket error: …` | The debugger socket upgrade failed |
-| `CDP disconnected (code <code>: <reason>)` | Metro closed the socket; a `[NEW_DEBUGGER_OPENED]` reason adds a hint (see below) |
-| `CDP socket not open after connect` | The socket closed during connect |
-
-| Metro events status | Meaning |
-|---------------------|---------|
-| `not connected` | No call has requested the `metro` source |
-| `connected ws://<host>/events` / `connected` | New / reused socket |
-| `Error: Metro /events unreachable at ws://<host>/events` | Metro is not reachable |
-
-The events status is not updated when the socket later closes, so a call that skips `metro` can
-print a stale `connected`.
-
-**`metro` source under Expo CLI 57:** the `/events` socket opens and reports `connected`, but
-receives nothing. Expo CLI 57.0.24 (`createEventsSocket`) registers its connection handler on one
-WebSocket server and serves `/events` from a second one with no handler, so no client is ever counted
-and no event is broadcast. The `metro` source works only with a Metro whose `/events` broadcasts,
-such as the React Native community CLI. Read bundler errors from the Metro terminal instead.
-
-### React Native DevTools and the `app` source
-
-React Native 0.86 (Terreno 57) reports `supportsMultipleDebuggers` for each app page. On a normal
-`expo start`, React Native DevTools and `terreno-mcp-local` attach to the app at the same time, and
-opening DevTools does not affect the `app` source.
-
-When Metro allows one debugger per app (older React Native, or Expo running headless with
-`EXPO_UNSTABLE_HEADLESS=1` or in a webcontainer), opening DevTools (`j` in Metro) disconnects the
-MCP. A call that does not read the app then shows, verbatim:
-
-``````text
-CDP: CDP disconnected (code 1000: [NEW_DEBUGGER_OPENED] New debugger opened for the same app instance); another debugger (such as React Native DevTools) took the session, and the next call that reads the app reconnects and disconnects it
-``````
+# (Build runs sync-ui-docs, sync-versioned-docs, and sync-package-guidelines before tsc.)
+# To refresh only bundled package AI guidelines from the monorepo:
+# bun run sync-package-guidelines
 
-The next call that reads the app (`read_logs` or `last_error` with `app`, or any CDP tool)
-reconnects automatically without an error, reports `CDP: connected to <app> (<device>)`, and
-disconnects DevTools, which shows `[NEW_DEBUGGER_OPENED] New debugger opened for the same app
-instance`. App console output logged while DevTools held the connection is not in `read_logs`; the
-first call after recovery may return only entries from before the gap.
-
-Workaround: use one or the other. Close DevTools, then call `read_logs` with `sources: ["app"]`
-twice: the first call reconnects, the second shows new entries. To keep DevTools open, stop calling
-tools that read the app, or each call takes the connection back.
-
-## What the local server can and cannot see
-
-The local server inspects the project from the outside. It never imports or runs consumer code in its
-own process: model files are read as text, and the app's runtime is reached only over Metro and CDP.
-
-**Can see:**
-
-| Surface | How |
-|---------|-----|
-| Package manifests | Root and backend/frontend workspace `package.json` files (declared ranges); `bun.lock` presence only |
-| MongoDB | `MONGO_URI` from the environment or `backend/.env`; collections, indexes, counts, and read-only queries |
-| Model source | First 80 lines of each `backend/src/models/*.ts`, as text |
-| Backend and browser logs | `app.log` and `browser.log` JSONL under `.terreno/logs/` in `backend/`, `example-backend/`, or the root |
-| Metro | `/json/list` targets and the `/events` socket |
-| Running Hermes app | Console output, client state, SyncDB state over CDP; code execution and navigation with `TERRENO_MCP_EVAL` |
-| Web app | Rendered page through the `browser` tool's own headless WebView |
-
-**Cannot see:**
-
-- Production or deployed environments: no remote logs, databases, or apps. Production backends do
-  not write the JSONL log or accept browser logs.
-- The web app's JavaScript heap or console through CDP. A browser tab is not a Metro debug target; use
-  `browser`, `browser.log`, and the backend log instead.
-- Native crash reports, device logs, or a device that is not attached to the dev server's Metro.
-- App console output from before the first `app` read, or while another debugger held a
-  single-debugger session.
-- Metro bundler events under Expo CLI 57 (the `metro` source is empty).
-- The resolved dependency tree: `application_info` reports declared ranges, not installed versions.
-- `example-backend/.env` and `example-backend/src/models/` (database discovery reads `backend/` only).
-
-## Environment variables
-
-### Hosted server variables
-
-| Variable | Default | Effect |
-|----------|---------|--------|
-| `PORT` | `8080` | HTTP listen port. Parsed with `parseInt`, so leading digits win (`80abc` is port 80); a value with no leading digits stops startup with `Invalid PORT value`. |
-| `MCP_HOST`, then `HOST` | `0.0.0.0` | Listen host |
-| `NODE_ENV` | unset | `production` disables console colors and warns at startup when `SENTRY_DSN` is unset |
-| `SENTRY_DSN` | unset (Sentry disabled) | Sentry DSN |
-| `APP_ENV` | `development` | Sentry `environment` |
-| `SENTRY_TRACES_SAMPLE_RATE` | `0.1` | Sentry trace sample rate (float) |
-| `TERRENO_MCP_DOCS_DIR` | `<module dir>/docs` (`dist/docs`), else `docs/` next to the executable | Root for bundled resources, prompts' markdown, the search index, and upgrade notes |
-| `TERRENO_HELP_API_URL` | unset | Terreno backend help API for announcements in the three update-note tools. Unset means bundled upgrade notes only. |
-| `TERRENO_HELP_API_TOKEN` | unset | Bearer token for `TERRENO_HELP_API_URL` |
-| `TERRENO_MCP_RATE_LIMIT_MAX` | `120` | JSON-RPC requests per client IP per window; `0` disables. Invalid values stop startup. See [Rate limiting](#rate-limiting). |
-| `TERRENO_MCP_RATE_LIMIT_WINDOW_MS` | `60000` | Rate-limit window in milliseconds (minimum 1) |
-| `TERRENO_MCP_TRUST_PROXY_HOPS` | `1` when `K_SERVICE` is set, else `0` | Reverse-proxy hops trusted for the client IP in `X-Forwarded-For` |
-| `K_SERVICE` | set by Cloud Run | Read only to choose the `TERRENO_MCP_TRUST_PROXY_HOPS` default |
-
-### Local server variables
-
-| Variable | Default | Effect |
-|----------|---------|--------|
-| `TERRENO_PROJECT_ROOT` | Discovered root (see [Running the local server](#running-the-local-server)) | Root for packages, database, logs, Metro URL, and browser paths |
-| `TERRENO_METRO_URL` | `--port` from the frontend `start`/`web` script, else `http://localhost:8082` | Metro HTTP origin for `/json/list`, `/events`, and the debugger Origin's port |
-| `TERRENO_MCP_EVAL` | disabled | `1` or `true` enables `evaluate`, `navigate`, `syncdb_action`, and `browser` `evaluate`. See [`TERRENO_MCP_EVAL` gate](#terreno_mcp_eval-gate). |
-| `MONGO_URI` | `MONGO_URI`, then `MONGODB_URI`, from `<root>/backend/.env` | MongoDB for `database_schema` and `database_query` |
-| `BUN_CHROME_PATH` | Bun auto-discovery | Chrome, Chromium, or Edge binary for `browser` on Linux and Windows (read by Bun, not Terreno) |
-
-### App-side variables that feed the local server
-
-| Variable | Read by | Default | Effect |
-|----------|---------|---------|--------|
-| `TERRENO_LOG_FILE` | `@terreno/api` logger | on when `NODE_ENV !== "production"` | Backend JSONL transport to `<cwd>/.terreno/logs/app.log` (5 MB × 3 files, level `debug`). `false`/`0` forces off, `true`/`1` forces on. A toggle, not a path. |
-| `TERRENO_BROWSER_LOGS` | `@terreno/api` `TerrenoApp` | on only when `NODE_ENV === "development"` | Registers `POST /__terreno/browser-logs`, which appends to `<cwd>/.terreno/logs/browser.log`. `true`/`1` opts in outside development, `false`/`0` disables; production never registers it. See [Development browser-log ingestion](api.md#development-browser-log-ingestion). |
-| `NODE_ENV` | `@terreno/api` | unset | Drives both defaults above |
-| `TERRENO_DEV_CONSOLE_LOGGER_TEST` | `@terreno/syncdb` `installTerrenoDevConsoleLogger` | unset | Test-only: `true` lets the console logger install outside `__DEV__` |
-
-The full cross-package list is in [Environment variables](environment-variables.md).
+# Watch mode (rebuilds on changes)
+bun run dev
 
-## Development
+# Start server
+bun run start
 
-``````bash
-# From the monorepo root
-bun install
-bun run mcp:build          # sync docs + tsc + copy docs into dist/
-
-# From mcp-server/
-bun run compile            # type-check only
-bun run build              # full artifact (sync-ui-docs, sync-versioned-docs, sync-package-guidelines, tsc, copy docs)
-bun run dev                # hosted server with watch
-bun run start              # hosted server from dist/ (run build first)
-bun run test               # bun test src/
+# Lint
 bun run lint
-``````
 
-`bun run sync-package-guidelines` refreshes only the bundled package AI guidelines.
+# Fix lint issues
+bun run lint:fix
+``````
 
 ### Docker
 
-Build from the repository root, as `scripts/ci/gcp-deploy.sh mcp-prod` does. The image needs the
-monorepo (`api/`, `blocks/`, `ui/`, `docs/`, `website/versioned_docs/`):
-
 ``````bash
-docker build --file mcp-server/Dockerfile -t terreno-mcp-server .
+# Build image
+docker build -t terreno-mcp-server ./mcp-server
+
+# Run container
 docker run --rm -p 8080:8080 terreno-mcp-server
 ``````
 
-`mcp-server/src/docs/ui-types-documentation.json` and `mcp-server/src/docs/versioned/` are
-git-ignored, so the builder stage generates them. `bun run --filter "@terreno/ui" types` writes the
-TypeDoc JSON that `terreno_get_component_docs` reads. `sync-versioned-docs` and
-`sync-package-guidelines` fill the `terreno_search_docs` corpus. Without that step the image served
-the one-component test fixture (`No component named "Badge". Examples: Button`) and searched only
-`resources/*.md`.
-
 ### Testing with MCP Inspector
 
 ``````bash
-# Local server over stdio
-bunx @modelcontextprotocol/inspector bun ./mcp-server/dist/local/index.js
+# Start server
+bun run start
 
-# Hosted server: start it, then connect the Inspector with Streamable HTTP to http://localhost:8080/mcp
-TERRENO_MCP_RATE_LIMIT_MAX=0 bun ./mcp-server/dist/index.js
-bunx @modelcontextprotocol/inspector
+# In another terminal, use MCP inspector
+npx @modelcontextprotocol/inspector bun run ./mcp-server/dist/index.js
 ``````
 
 ## Architecture
@@ -1356,34 +644,29 @@ bunx @modelcontextprotocol/inspector
 ``````
 mcp-server/
 ├── src/
-│   ├── index.ts            # Hosted entry: reads env, starts the HTTP server
-│   ├── httpApp.ts          # Express app: JSON-RPC handlers, routes, health check
-│   ├── rateLimit.ts        # Per-IP JSON-RPC rate limit and trust-proxy config
-│   ├── instrument.ts       # Sentry init
-│   ├── tools.ts            # Hosted tools and dispatch
-│   ├── bootstrap.ts        # terreno_bootstrap_ai_rules tool and terreno_bootstrap prompt
-│   ├── prompts.ts          # Workflow prompts
-│   ├── resources.ts        # Documentation resources
-│   ├── docsRoot.ts         # Bundled docs root (TERRENO_MCP_DOCS_DIR)
-│   ├── search/             # Docs search index
-│   ├── help/               # Update-note search and help API client
-│   ├── docs/               # Bundled markdown (resources, upgrades, guidelines)
-│   └── local/
-│       ├── index.ts        # Local entry (stdio)
-│       ├── localServer.ts  # Server and tools/list, tools/call handlers
-│       ├── localTools.ts   # Local tool schemas and dispatch
-│       ├── projectRoot.ts  # Project root discovery
-│       ├── logPaths.ts     # .terreno/logs discovery
-│       ├── metro/          # Metro /events and CDP session
-│       └── tools/          # Tool implementations
-├── dist/                   # Compiled output
-└── Dockerfile              # Hosted server image
+│   ├── index.ts          # Express server + JSON-RPC handlers
+│   ├── resources.ts      # Documentation resource loader
+│   ├── tools.ts          # Code generation tools
+│   ├── prompts.ts        # Workflow prompts
+│   └── docs/             # Inline documentation content
+├── dist/                 # Compiled output
+└── Dockerfile            # Container image
 ``````
 
+**JSON-RPC 2.0 handlers:**
+
+- `resources/list` — List available documentation
+- `resources/read` — Read documentation content
+- `tools/list` — List available tools
+- `tools/call` — Execute a tool
+- `prompts/list` — List available prompts
+- `prompts/get` — Get prompt details
+
 ## Deployment
 
-The hosted server runs as the `terreno-mcp` Cloud Run service. CircleCI's continuous-delivery
-pipeline (`.circleci/config.yml`, triggered by changes under `mcp-server/`) builds and rolls the
-image; Terraform owns the service's structure, and its hostname cutover is in
-[infra/flourish/README.md](../../infra/flourish/README.md#hosted-mcp-hostname).
+See [mcp-server/README.md](../../mcp-server/README.md#cicd) for:
+
+- GitHub Actions workflows
+- Google Cloud Run deployment
+- Required secrets configuration
 - Workload Identity Federation setup