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

package/src/docs/versioned/57.21.0/implementationPlans/ai-agents-and-failover.md

@@ -0,0 +1,238 @@
+# Implementation plan: AI agents and provider failover
+
+**Status:** Draft  
+**Roadmap:** Area=`ai`, Target=`Future`, Impact=`Feature`  
+**Branch:** `cursor/ai-agents-and-failover-ip-97fd`  
+**Owner:** unassigned  
+**Created:** 2026-08-24  
+**Package:** `@terreno/ai`  
+**Related:** Laravel AI SDK comparison (items 1 and 3): named Agent reuse + LanguageModel failover on 429/503  
+
+## Goal
+
+Add two additive library seams to `@terreno/ai` so app code can:
+
+1. Define a reusable **Agent** (`name`, `instructions`, `tools`, optional `schema`, optional `middleware`) that runs through existing `AIService` logging.
+2. Wrap one or more Vercel AI SDK `LanguageModel`s in **`createFailoverModel`** so 429/502/503/overloaded failures try the next model. Every `AIService` method inherits failover without per-method changes.
+
+Destination: a consuming app can write a typed agent, pass a failover chain as `model`, and prove with mocks that the second model serves after the first throws a failoverable error.
+
+## Non-Goals
+
+- Embeddings, pgvector/Atlas Vector, RAG, `SimilaritySearch` (comparison item 2).
+- Image generation, TTS, STT, reranking, provider file/vector stores.
+- New HTTP routes, `AiApp` options, or GPT chat rewrite.
+- Human-in-the-loop tool approval / resume.
+- First-class sub-agents (keep existing `parentRequestId` / `subRequestIds` only).
+- Queued generation, Echo-style broadcast, `Agent.fake()` Laravel helpers.
+- Changing `AIService` constructor (`model` stays a single `LanguageModel`).
+- Mid-stream failover after the client has received text deltas.
+
+## Decisions
+
+Grow recorded these as executable defaults from the comparison plus current `@terreno/ai` shape (`AIService` + injected `LanguageModel` in `ai/src/service/aiService.ts`). Change a row before Approve if Pick should do something else.
+
+| ID | Question | Decision |
+| --- | --- | --- |
+| D1 | Scope | Agent API + failover wrapper only. No embeddings, no multimodal generation, no new routes. |
+| D2 | Agent shape | Class `Agent` wrapping an `AIService` instance. Not a replacement for `AIService`. Laravel-style PHP agent classes are the DX target, not the type system. |
+| D3 | HTTP | No new routes in v1. Chat stays `addGptRoutes`. Apps call `agent.run()` from their own services/routes. |
+| D4 | Failover seam | `createFailoverModel({models, isFailoverable?})` returns a `LanguageModel`. Pass it as `AIService` `model`. Do not add `models[]` to the constructor. |
+| D5 | Failover triggers | Default: HTTP 429, 502, 503, 529; SDK/provider errors whose `statusCode` matches; messages matching rate-limit / overloaded / capacity. Not 400/401/403/404. Not structured-output parse failures (`NoObjectGeneratedError`). |
+| D6 | Same-model retry | Each listed model is tried once per call. No extra retries on the same model. |
+| D7 | Streaming | Fail over only if `doStream` **rejects before returning a stream**. After the stream exists, errors propagate. No replay of partial output. |
+| D8 | Logging | Successful `AIRequest.aiModel` is the model that served. `metadata.failover` records `{attempts: [{modelId, error?}], servedModelId}`. Failures still never throw from logging. |
+| D9 | Instructions | Agent `instructions` are prompts. Named constants (app `prompts.ts` or `ai/src/service/prompts.ts`). `ai-prompt-governance` applies. |
+| D10 | Schema + tools | v1 allows tools on text/chat runs. `schema` uses `generateJsonObject` and **does not** combine with tools in the same `run`. Streaming `runStream` is text-only (no schema). |
+| D11 | Middleware | Array of `(input, next) => Promise<output>` around `run` / `runStream` only. Not Express middleware. |
+| D12 | Example app | Optional tracer in `example-backend` if two providers are already configured; otherwise tests-only tracer is enough. |
+| D13 | Compatibility | Additive exports only. Existing `new AIService({model})` and `AiApp` stay valid. |
+
+## Architecture
+
+```
+App
+  Agent({instructions, tools?, schema?, middleware?}, aiService)
+    → AIService.generateText | generateChatStream | generateJsonObject
+        → LanguageModel (optionally createFailoverModel)
+            → primary.doGenerate / doStream
+            → on failoverable error → next model
+        → AIRequest.logRequest (served model id + failover metadata)
+```
+
+`AIService` stays the only path that talks to the Vercel AI SDK for logged calls. Agent does not call `generateText` / `streamText` from `ai` directly.
+
+Failover is a `LanguageModel` Proxy (same idea as `withStrippedJsonFencesModel` in `aiService.ts`): intercept `doGenerate` and `doStream`, preserve other properties from the **primary** model (`specificationVersion`, `provider`, `supportedUrls`).
+
+`modelId` on the wrapper: `failover(<primaryId>)` for identification. `AIService` logging must read **served** id via a small well-known slot on the wrapper (for example `lastServedModelId`) so explorer rows are not all `failover(...)`.
+
+### Agent API (proposed)
+
+```typescript
+interface AgentContext {
+  userId?: mongoose.Types.ObjectId;
+}
+
+interface AgentRunOptions extends AgentContext {
+  prompt: string;
+  messages?: Array<{content: string; role: "user" | "assistant" | "system"}>;
+  temperature?: number;
+}
+
+interface AgentMiddleware<OUTPUT = string> {
+  (
+    input: AgentRunOptions,
+    next: (input: AgentRunOptions) => Promise<OUTPUT>
+  ): Promise<OUTPUT>;
+}
+
+interface AgentConfig<OUTPUT = string> {
+  name: string;
+  instructions: string | ((ctx: AgentContext) => string | Promise<string>);
+  tools?: ToolSet | ((ctx: AgentContext) => ToolSet | Promise<ToolSet>);
+  schema?: import("ai").FlexibleSchema<OUTPUT>;
+  middleware?: Array<AgentMiddleware<OUTPUT>>;
+  temperature?: number;
+  maxSteps?: number;
+  requestType?: string;
+}
+
+class Agent<OUTPUT = string> {
+  constructor(config: AgentConfig<OUTPUT>, service: AIService);
+  run(options: AgentRunOptions): Promise<OUTPUT | string>;
+  runStream(options: AgentRunOptions): AsyncGenerator<string>;
+}
+```
+
+Dispatch:
+
+| Config | Implementation |
+| --- | --- |
+| `schema` set | `AIService.generateJsonObject` with `systemPrompt` = resolved instructions. Ignore tools. |
+| `tools` set, no schema | Collect `generateChatStream` with `stopWhen: stepCountIs(maxSteps ?? 5)` (same default as `AiApp.maxSteps`). |
+| neither | `AIService.generateText` with `systemPrompt` = instructions. |
+
+`requestType` defaults to `"agent"` (extend `AIRequestType` union / explorer filters). Store `metadata.agentName`.
+
+Factory export `defineAgent(config)` that returns `(service) => new Agent(config, service)` is optional sugar; Pick may ship class-only if that is smaller.
+
+### Failover API (proposed)
+
+```typescript
+interface CreateFailoverModelOptions {
+  models: LanguageModel[];
+  isFailoverable?: (error: unknown) => boolean;
+}
+
+createFailoverModel(options: CreateFailoverModelOptions): LanguageModel;
+isFailoverableError(error: unknown): boolean;
+```
+
+- `models.length < 1` throws at construction (early return / guard).
+- `isFailoverable` defaults to `isFailoverableError`.
+- On failover: `logger.warn` with `fromModelId`, `toModelId`, `error` (no secrets).
+- If every model fails: throw the **last** error (do not wrap in a generic message that hides the provider error).
+- Structured-json path: `withStrippedJsonFencesModel(createFailoverModel(...))` still works because failover is a LanguageModel. Order: app wraps failover first, then `AIService` applies fence stripping on that wrapper for JSON methods.
+
+### `getModelId` / logging
+
+Update `getModelId` (or logging helpers) so if `model` has `lastServedModelId: string`, log that. Wrapper sets it on success. Tests assert `AIRequest.aiModel` equals the backup id after a primary 429.
+
+## Models
+
+No new Mongoose models. No schema migration.
+
+`AIRequest.metadata` (already Mixed) gains optional:
+
+```typescript
+interface FailoverLogMetadata {
+  attempts: Array<{modelId: string; error?: string}>;
+  servedModelId: string;
+}
+
+interface AgentLogMetadata {
+  agentName: string;
+}
+```
+
+`requestType` may be `"agent"` in addition to current defaults. Update admin explorer filters in `ai/src/routes/aiRequestsExplorer.ts`.
+
+## APIs
+
+No REST/OpenAPI changes.
+
+Public package exports from `ai/src/index.ts`:
+
+- `Agent`, type `AgentConfig`, type `AgentMiddleware`, type `AgentRunOptions`
+- `createFailoverModel`, `isFailoverableError`, type `CreateFailoverModelOptions`
+
+## Notifications
+
+None.
+
+## UI
+
+None. Admin explorer already shows `requestType` / `aiModel` / `metadata`; document the new metadata shape in reference docs only.
+
+## Phases
+
+1. **Failover LanguageModel** — `createFailoverModel` + tests (tracer).
+2. **Logging served model** — `lastServedModelId` into `AIRequest`.
+3. **Agent** — class + dispatch + middleware + tests.
+4. **Docs + agent rules** — reference, how-to, `.cursor/rules/ai`, prompt-governance mention.
+5. **Optional example-backend** — one agent if dual providers exist without new env requirements.
+
+## Feature Flags & Migrations
+
+None. Additive API. No feature flag.
+
+## Activity Log & User Updates
+
+`AIRequest` remains the audit log. No user-facing activity feed.
+
+## Not Included / Future Work
+
+- RAG / embeddings (comparison item 2).
+- Agent-as-tool / sub-agents.
+- Human tool approval.
+- `AiApp` `agent` option mounting a dedicated route.
+- Failover on mid-stream errors.
+- Combining structured schema with tool loops in one `run`.
+
+## Files to Create / Modify
+
+| File | Change |
+| --- | --- |
+| `ai/src/service/failoverModel.ts` | `createFailoverModel`, `isFailoverableError` |
+| `ai/src/service/failoverModel.test.ts` | Mock `doGenerate` / `doStream`; 429 then success; non-failoverable does not switch; empty list throws; stream reject-before-return vs after-return |
+| `ai/src/agent/agent.ts` | `Agent` class |
+| `ai/src/agent/agent.test.ts` | Instructions sent as system; schema path; tools path; middleware order |
+| `ai/src/service/aiService.ts` | Read `lastServedModelId` when logging; optional `requestType` passthrough only if needed (prefer Agent calling existing methods + metadata) |
+| `ai/src/types/index.ts` | Types; `"agent"` request type |
+| `ai/src/routes/aiRequestsExplorer.ts` | Filter includes `agent` |
+| `ai/src/index.ts` | Exports |
+| `docs/reference/ai.md` | Agent + failover sections |
+| `docs/how-to/define-an-ai-agent.md` | New how-to |
+| `docs/how-to/configure-ai-failover.md` | New how-to |
+| `docs/how-to/README.md` | Links |
+| `.cursor/rules/ai/00-ai.mdc` (source of truth for rules sync) | Public API notes |
+| `skills/ai-prompt-governance/SKILL.md` | Agent instructions = named constants |
+| `ai/README.md` | Short mention + link to reference |
+| `docs/tasks/ai-agents-and-failover.md` | This plan's task list |
+| `example-backend/src/api/ai.ts` | Optional Phase 5 only |
+
+## Task List
+
+[`docs/tasks/ai-agents-and-failover.md`](../tasks/ai-agents-and-failover.md)
+
+## Acceptance Criteria
+
+- [ ] `createFailoverModel` with two mocks: first `doGenerate` throws failoverable 429, second returns text; `AIService.generateText` returns the second text; `AIRequest.aiModel` is the second `modelId`; `metadata.failover.attempts` has length 2.
+- [ ] First mock throws 400; second is never called; error propagates.
+- [ ] `doStream` that **returns** a stream then errors does not call the next model.
+- [ ] `Agent` with named instruction constant: mock receives that string as `system` (or equivalent SDK field); `AIRequest` has `requestType: "agent"` and `metadata.agentName`.
+- [ ] `Agent` with `schema` returns a typed object via `generateJsonObject` (existing JSON normalization still applies).
+- [ ] Middleware runs in order; a middleware that returns without `next` short-circuits (no model call).
+- [ ] `docs/reference/ai.md` documents both APIs with one minimal example each.
+- [ ] `bun test` in `ai/` passes; `bun run compile` for `ai` succeeds.
+- [ ] No new Express routes; existing GPT tests still pass.

package/src/docs/versioned/57.21.0/implementationPlans/ai-dev-loop-boost.md

@@ -0,0 +1,190 @@
+# Implementation Plan: The AI Development Loop (Boost)
+
+**Status:** Approved — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1014
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) merging (assumed). **Reconciled 2026-10-12:** #802 and #869 were both closed unmerged, but their substance is on `master` through later PRs (CDP log tools, Metro sessions, the browser-log route, `@terreno/syncdb`, and `get_syncdb_state`; mainly #1128). Read "merged #802" in this plan as "current `master`".
+**RTK deprecation flag:** **Partial** — `get_rtk_state` and `installTerrenoDevConsoleLogger` are RTK-named surfaces that must be renamed or relocated now that `@terreno/syncdb` exists (the #869 substance). Both are on `master`, so the marked tasks are no longer blocked on unmerged PRs.
+
+## Goal
+
+Turn Terreno's AI-native pillar from a claim into a documented, demonstrable loop. The machinery exists on `master`: an agent can search current docs, generate conventional code, run the app, read merged logs from four sources, see the last error with a stack, inspect client state, and drive navigation. What does not exist is any document that explains this as a single workflow, so nobody outside the team knows it is there.
+
+This IP writes the story and closes the gaps that become obvious once the story is written down.
+
+## Non-Goals
+
+- Building new MCP tools beyond renames and small gap-fillers.
+- Re-implementing UI automation — #802 deliberately composes `expo-mcp`, Playwright MCP, and Maestro rather than building tap/screenshot tooling. (Fact check 2026-10-12: `master` has since added a web-only `browser` tool to `terreno-mcp-local`, built on Bun's WebView, with `snapshot` and `screenshot` actions. Native simulator interaction still comes from `expo-mcp`.)
+- The tutorial itself (that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), which depends on this IP's reference content).
+- Langfuse/observability for AI features inside consumer apps (that is `terreno-langfuse-integration.md`).
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| AI1 | Replace `get_rtk_state` | **A** — `get_client_state` with a `layer` field |
+| AI2 | `installTerrenoDevConsoleLogger` location | **B** — move to `@terreno/syncdb`, re-export from rtk during support window |
+| AI3 | Document `evaluate` publicly? | **A** — yes, with `TERRENO_MCP_EVAL=1` gate |
+| AI4 | Compose `expo-mcp` + Playwright MCP? | **A** — yes, with configuration |
+| AI5 | Hosted MCP auth / rate limiting | **B** — rate limiting by IP before public launch |
+| AI6 | MCP URL (→ P4) | **`https://mcp.terreno.app`** |
+
+## Architecture
+
+### The loop, named
+
+```mermaid
+flowchart LR
+  ASK["1. Ask<br/>terreno_search_docs<br/>terreno_get_component_docs"]
+  GEN["2. Generate<br/>terreno_generate_model / _route / _screen<br/>terreno_validate_model_schema"]
+  RUN["3. Run<br/>bun run backend:dev<br/>expo start"]
+  OBS["4. Observe<br/>read_logs (backend/app/metro/browser)<br/>last_error<br/>get_client_state"]
+  FIX["5. Fix<br/>navigate + browser screenshot<br/>regenerate typed client"]
+  ASK --> GEN --> RUN --> OBS --> FIX
+  FIX -->|"iterate"| ASK
+```
+
+The claim worth making is narrow and true: **the agent sees what the app actually did, not a description of it.** Everything else in the *tool* story is table stakes that other frameworks can match.
+
+### Tool layer versus process layer
+
+This loop is only half the AI story, and documenting it alone undersells it. The other half is the `/terreno-*` SDLC pipeline shipped in `plugins/terreno-planning/` — plan, implement test-first, verify in a fresh context, submit with evidence, own the review loop. [`agentic-sdlc-plugin`](agentic-sdlc-plugin.md) owns publishing and documenting it.
+
+| Layer | Answers | Delivered by |
+|-------|---------|--------------|
+| **Tool** | What can the agent see and do? | MCP servers: docs search, codegen, merged logs, client state, navigation |
+| **Process** | In what order should the agent work, and who checks it? | `/terreno-*`: question-first planning, TDD, fresh-context independent review, evidence gates, reactive review loop |
+
+Every document produced by this IP must name both and explain that they compose: the pipeline's implement stage uses the loop's tools, and the loop's tools are most useful when driven by the pipeline's sequencing. `docs/explanation/ai-development-loop.md` and `docs/explanation/agentic-sdlc.md` are companion pages and must cross-link.
+
+### Tool surface (reconciled with master, 2026-10-12)
+
+Every name below is registered in source. The hosted server (`terreno-mcp`, `mcp-server/src/index.ts`) registers tools from `mcp-server/src/tools.ts` and `mcp-server/src/bootstrap.ts`. The local stdio server (`terreno-mcp-local`, `mcp-server/src/local/`) registers tools only, from `mcp-server/src/local/localTools.ts`. Full input schemas and every environment variable, with the file that reads it, are in the Task 1.1 evidence (`.terreno/pipeline/ai-dev-loop-boost-evidence/inventory.md`).
+
+| Tool | Server | Purpose |
+|------|--------|---------|
+| `terreno_search_docs` | hosted | BM25 search over the docs corpus, multi-query, optional `packages` and lockstep `version` |
+| `terreno_get_component_docs` | hosted | Full props table for a `@terreno/ui` component, optional `version` |
+| `terreno_get_upgrade_guide` | hosted | Concatenated upgrade notes for a version range |
+| `terreno_search_update_notes` / `terreno_get_update_note` / `terreno_ask_update_help` | hosted | Search, fetch, and question bundled upgrade notes, plus help-API announcements when `TERRENO_HELP_API_URL` is set |
+| `terreno_bootstrap_ai_rules` | hosted | Agent rule files for Cursor, Windsurf, Claude Code, and Copilot. App scaffolding moved to `bunx create-terreno-app`, and `terreno_bootstrap_app` no longer exists. |
+| `terreno_generate_model` / `terreno_generate_route` / `terreno_generate_screen` / `terreno_generate_form_fields` | hosted | Codegen |
+| `terreno_validate_model_schema` / `terreno_validate_ui_blocks` | hosted | Convention and block-document validation |
+| `terreno_install_admin` | hosted | Admin panel integration snippets |
+| `application_info` | local | `@terreno/*` and toolchain versions |
+| `database_schema` / `database_query` | local | Mongo introspection with a read-only allowlist, using `MONGO_URI` or `backend/.env` |
+| `read_logs` | local | Merged logs from `backend` (JSONL), `browser` (JSONL), `metro` (`/events`), and `app` (Hermes console over CDP) |
+| `last_error` | local | Raw JSONL line of the newest error-level entry across the same four sources. A stack is included only when the entry carries one. |
+| `get_rtk_state` | local | Redux auth and RTK Query cache inspection (in-process or CDP). It is not gated. This is the tool that AI1 renames to `get_client_state`; `get_client_state` does not exist yet. |
+| `get_syncdb_state` / `syncdb_snapshot` / `syncdb_action` | local | SyncDB inspection, snapshots, and actions. `syncdb_action` is gated by `TERRENO_MCP_EVAL=1`. |
+| `evaluate` / `navigate` | local | CDP `Runtime.evaluate` and expo-router navigation, both gated by `TERRENO_MCP_EVAL=1` |
+| `browser` | local | Headless web driving through Bun 1.4 WebView: open, click, type, snapshot, and screenshot. Only its `evaluate` action is gated by `TERRENO_MCP_EVAL=1`. |
+
+Prompts (hosted only): `terreno_bootstrap`, `terreno_create_crud_feature`, `terreno_create_api_endpoint`, `terreno_create_ui_component`, `terreno_create_form_screen`, `terreno_add_authentication`, `terreno_style_guide`, `terreno_migrate_to_terreno_app`, `terreno_upgrade`. Resources (hosted only): `terreno://docs/{overview,api,ui,syncdb,rtk,patterns}`, plus `terreno://docs/ui/components` and one `terreno://docs/ui/components/<slug>` per component.
+
+### Gaps that surface once the story is written
+
+1. **Naming**: `get_rtk_state` is named after a package being deprecated (AI1). It reads Redux only. SyncDB state has its own tool (`get_syncdb_state`), so `get_client_state` must decide whether to reuse that bridge or report the SyncDB layer itself.
+2. **Discovery**: `docs/how-to/set-up-terreno-mcp.md` now exists. It is linked from `docs/README.md`, `docs/how-to/README.md`, `docs/reference/mcp-server.md`, and the `terreno://docs/overview` resource, but not from the root `README.md` or `docs/tutorials/README.md`. `create-terreno-app` writes `terreno-local` into `.cursor/mcp.json` but does not point at the guide.
+3. **Hermes single-connection contention**: opening React Native DevTools steals the CDP connection the log tools need. `master` connects lazily and holds the socket for the life of the MCP process; there is no release. On close it reports `CDP disconnected` and reconnects on the next call. Status reaches the agent in `read_logs`' `connection` field (`CDP: …; Metro events: …`). Users need to know the symptom.
+4. **Setup guide is incomplete and inconsistent**: `docs/how-to/set-up-terreno-mcp.md` covers Cursor and Claude Code for both servers. It uses `https://mcp.terreno.flourish.health/mcp`, while `create-terreno-app` and the root README use `https://mcp.terreno.app` (AI6). It also omits `expo-mcp` and Playwright MCP.
+5. **Hosted server has no rate limiting** (AI5), which is a launch risk. Neither `mcp-server/src/index.ts` nor the `mcp_service` Cloud Run module in `terraform/main.tf` limits requests, and the service allows unauthenticated access. `@terreno/api`'s opt-in `rateLimit` does not apply, because the hosted server uses `createMcpExpressApp`, not `TerrenoApp`.
+6. **Composition is undocumented**: `create-terreno-app` writes `expo` (`https://mcp.expo.dev/mcp`) and `playwright` (`@playwright/mcp`) entries into `.cursor/mcp.json` (`create-terreno-app/src/generate.ts`), but no doc explains them (AI4).
+7. **Reference drift**: `docs/reference/mcp-server.md` has no sections for `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate`, `navigate`, or the three update-note tools. Its env table omits `TERRENO_HELP_API_URL`, `TERRENO_HELP_API_TOKEN`, `MONGO_URI`, `TERRENO_LOG_FILE`, and the Sentry variables. `mcp-server/README.md` omits `terreno_validate_ui_blocks` and lists only the SyncDB local tools.
+
+### Documentation to produce
+
+| Document | Purpose |
+|----------|---------|
+| `docs/explanation/ai-development-loop.md` | The five-stage loop, why it is different, what the agent can and cannot see |
+| `docs/how-to/set-up-terreno-mcp.md` | Per-editor configuration for both Terreno servers plus composed servers. This page already exists on `master`, so update it rather than create it. |
+| `docs/how-to/debug-with-mcp.md` | Using `read_logs`, `last_error`, `get_client_state`, `navigate` on a real failure. This page already exists on `master` and covers `get_rtk_state` and the SyncDB tools; update it. |
+| `docs/reference/mcp-server.md` | Updated with the complete tool surface on `master` and every environment variable |
+| `docs/explanation/agent-guidelines.md` | How per-package `.ai/` guidelines and `.rulesync/` rules reach an agent, and how consumers extend them |
+
+Companion page owned elsewhere: `docs/explanation/agentic-sdlc.md` (the process layer) from [`agentic-sdlc-plugin`](agentic-sdlc-plugin.md). Neither page should duplicate the other; each links the other as the missing half.
+
+## Models / APIs
+
+No new models. `POST /__terreno/browser-logs` (dev-only, `api/src/browserLogsRoute.ts`) needs documenting, including its production-disabled behavior and the `TERRENO_BROWSER_LOGS` override. Facts on `master`:
+
+- Only `TerrenoApp` registers the route, not legacy `setupServer`.
+- By default it is on only when `NODE_ENV === "development"`. An unset `NODE_ENV` leaves it off unless `TERRENO_BROWSER_LOGS=true`.
+- It is never registered in `production`, so requests there get a 404.
+- It returns 403 to clients that are neither loopback nor authenticated.
+
+## Notifications
+
+None.
+
+## UI
+
+None. `installTerrenoDevConsoleLogger` is invisible instrumentation.
+
+## Phases
+
+1. **Reconcile with `master`** (#802 and #869 closed unmerged; their substance landed through later PRs): verify the actual tool names, parameters, and environment variables.
+2. **Reference completeness** — update `docs/reference/mcp-server.md` to the real surface.
+3. **The loop explainer** — `ai-development-loop.md`.
+4. **Setup and debug how-tos** — including composed servers.
+5. **Gap fixes** — the `get_client_state` rename (`@terreno/syncdb` is on `master`), logger relocation, hosted rate limiting, discovery paths, and the CDP `Origin` header fix that Task 1.3 found (Task 5.5).
+6. **Agent guidelines explainer** — how guidelines reach agents and how consumers extend them.
+
+## Feature Flags & Migrations
+
+- `TERRENO_MCP_EVAL=1` (or `true`) gates `evaluate`, `navigate`, `syncdb_action`, and the `browser` tool's `evaluate` action. It does not gate `get_rtk_state`, `get_syncdb_state`, or `syncdb_snapshot`, which read app state over CDP with fixed expressions. The `.cursor/mcp.json` that `create-terreno-app` generates never sets it.
+- `TERRENO_BROWSER_LOGS` and `NODE_ENV` gate the browser-log route (`api/src/browserLogsRoute.ts`). By default it is on only when `NODE_ENV=development`.
+- `TERRENO_LOG_FILE` and `NODE_ENV` gate the backend JSONL file that `read_logs` reads (`api/src/logger.ts`). By default it is on whenever `NODE_ENV !== "production"`.
+- Renaming `get_rtk_state` to `get_client_state` is a breaking MCP tool change: keep the old name as an alias for one release with a deprecation note in its description.
+
+## Not Included / Future Work
+
+- Semantic/vector docs search (BM25 is the v1 answer).
+- CDP multiplexing proxy for the Hermes single-connection limit (the fallback plan in #802 if contention proves painful).
+- Terreno-authored simulator automation.
+- MCP tools generated for consumer app APIs (`model-router-mcp.md`).
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/explanation/ai-development-loop.md`
+- `docs/explanation/agent-guidelines.md`
+
+**Modify**
+
+- `docs/how-to/set-up-terreno-mcp.md`, `docs/how-to/debug-with-mcp.md` (both already on `master`)
+- `docs/reference/mcp-server.md`, `mcp-server/README.md`
+- `mcp-server/src/local/tools/runtime.ts` (tool rename + alias)
+- `mcp-server/src/local/localTools.ts` (tool registration)
+- `mcp-server/src/index.ts` (rate limiting)
+- `rtk/src/devConsoleLogger.ts` → `syncdb/src/devConsoleLogger.ts` (with re-export)
+- `docs/reference/environment-variables.md`
+- `README.md` (MCP section links the new how-to)
+
+## Task List
+
+See [`docs/tasks/ai-dev-loop-boost.md`](../tasks/ai-dev-loop-boost.md).
+
+## Acceptance Criteria
+
+- [ ] `docs/reference/mcp-server.md` lists every tool, prompt, and resource on both servers, matching the merged code, and every environment variable that affects them.
+- [ ] `docs/explanation/ai-development-loop.md` explains the five stages and states precisely what an agent can and cannot observe.
+- [ ] `docs/explanation/ai-development-loop.md` distinguishes the tool layer from the process layer, and cross-links `docs/explanation/agentic-sdlc.md` as the other half of the AI story.
+- [ ] `docs/how-to/set-up-terreno-mcp.md` gives working configuration for at least Cursor and Claude Code, covering both Terreno servers, and explains when to add `expo-mcp` and Playwright MCP.
+- [ ] `docs/how-to/debug-with-mcp.md` walks a real failure from symptom to fix using `last_error` and `read_logs`, with real tool output.
+- [ ] The Hermes single-CDP-connection limitation is documented with its symptom and the workaround.
+- [ ] `evaluate` and `navigate` are documented with the `TERRENO_MCP_EVAL` gate and the security reasoning for it.
+- [ ] `get_client_state` exists, works against both store types, reports which layer it found, and `get_rtk_state` remains as a deprecated alias for one release.
+- [ ] `installTerrenoDevConsoleLogger` is exported from the supported client package with a re-export from `@terreno/rtk` for the support window.
+- [ ] The hosted MCP server enforces rate limiting, with the limit documented and a clear error response when exceeded.
+- [ ] `POST /__terreno/browser-logs` is documented including that it 404s in production.
+- [ ] A bootstrapped app's generated `mcp.json` matches the setup how-to exactly.
+- [ ] `bun run mcp:build`, `bun run lint`, `bun run compile`, and `bun run rules:check` all pass.