@terreno/mcp 0.29.0 → 0.31.0

package/dist/docs/versioned/0.29.0/implementationPlans/ai-dev-loop-boost.md

@@ -0,0 +1,174 @@
+# Implementation Plan: The AI Development Loop (Boost)
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**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/flourishhealth/terreno/pull/802) merging (assumed)
+**RTK deprecation flag:** **Partial** — `get_rtk_state` and `installTerrenoDevConsoleLogger` are RTK-named surfaces delivered by #802 that must be renamed or relocated after #869. Marked tasks are blocked on both PRs.
+
+## Goal
+
+Turn Terreno's AI-native pillar from a claim into a documented, demonstrable loop. The machinery mostly exists after PR #802 lands: 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.
+- 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/>generate_model / route / screen<br/>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 + 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 after #802
+
+| Tool | Server | Purpose |
+|------|--------|---------|
+| `terreno_search_docs` | hosted | BM25 search over the docs corpus, multi-query |
+| `terreno_get_component_docs` | hosted | Full props table for a `@terreno/ui` component |
+| `terreno_get_upgrade_guide` | hosted | Concatenated upgrade notes for a version range |
+| `terreno_bootstrap_app` / `terreno_bootstrap_ai_rules` | hosted | Scaffold an app / agent rules |
+| `terreno_generate_*`, `terreno_validate_model_schema`, `terreno_install_admin` | hosted | Codegen |
+| `application_info` | local | `@terreno/*` and toolchain versions |
+| `database_schema` / `database_query` | local | Mongo introspection, read-only allowlist |
+| `read_logs` | local | Merged backend + app (CDP) + Metro + browser logs |
+| `last_error` | local | Most recent error with stack across sources |
+| `get_rtk_state` → `get_client_state` | local | Store and cache inspection |
+| `evaluate` / `navigate` | local | CDP runtime, `TERRENO_MCP_EVAL=1` gated |
+
+### Gaps that surface once the story is written
+
+1. **Naming**: `get_rtk_state` is named after a package being deprecated (AI1).
+2. **Discovery**: nothing tells a developer to install `terreno-mcp-local`. `docs/reference/mcp-server.md` documents it, but no getting-started path mentions it.
+3. **Hermes single-connection contention**: opening React Native DevTools steals the CDP connection the log tools need. #802 mitigates with lazy connect/release and status reporting; users need to know the symptom.
+4. **No end-to-end setup guide**: MCP configuration is scattered across the README and the reference page, per-editor, with no single how-to.
+5. **Hosted server has no rate limiting** (AI5) — a launch risk.
+6. **Composition is undocumented**: `expo-mcp` and Playwright MCP wiring exists in bootstrap output but is not explained (AI4).
+
+### 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 |
+| `docs/how-to/debug-with-mcp.md` | Using `read_logs`, `last_error`, `get_client_state`, `navigate` on a real failure |
+| `docs/reference/mcp-server.md` | Updated with the complete post-#802 tool surface 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, from #802) needs documenting including its production-disabled behavior and the `TERRENO_BROWSER_LOGS` override.
+
+## Notifications
+
+None.
+
+## UI
+
+None. `installTerrenoDevConsoleLogger` is invisible instrumentation.
+
+## Phases
+
+1. **Reconcile with merged #802** — 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 (post-#869), logger relocation, hosted rate limiting, discovery paths.
+6. **Agent guidelines explainer** — how guidelines reach agents and how consumers extend them.
+
+## Feature Flags & Migrations
+
+- `TERRENO_MCP_EVAL=1` gates `evaluate` and `navigate`; never enabled by bootstrap defaults.
+- `TERRENO_BROWSER_LOGS` and `NODE_ENV` gate the browser-log route.
+- 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/how-to/set-up-terreno-mcp.md`
+- `docs/how-to/debug-with-mcp.md`
+- `docs/explanation/agent-guidelines.md`
+
+**Modify**
+
+- `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.

package/dist/docs/versioned/0.29.0/implementationPlans/apierror-standard-error-redesign.md

@@ -0,0 +1,332 @@
+# APIError redesign — standards-first extension of Error
+
+**Status:** Complete
+**Branch:** cursor/apierror-standard-error-redesign-e24a
+**Owner:** TBD
+**Created:** 2026-07-28
+
+## Goal
+
+Redesign `APIError` (`api/src/errors.ts`) so the **standard `Error` fields carry the standard
+meaning** — `name` is the error type, `message` is the stable human-readable summary, `stack` is
+the capture site, and `cause` is the wrapped original error — and the JSONAPI extension fields
+(`status`, `code`, `detail`, `source`, `meta`, `links`, `id`) only carry the *extra* API context.
+
+The motivating symptom: tools like Sentry derive the issue headline from `error.name` and the
+subtitle from `error.message`, and walk `error.cause` for linked exceptions. Because every
+`APIError` has `name === "APIError"` and a `message` polluted with an embedded stack trace,
+unrelated errors all show up as **"APIError"** and group together, while the actual wrapped error
+is invisible to Sentry.
+
+## Non-Goals
+
+- Changing the client-facing wire format beyond clarifying `disableExternalErrorTracking` (see
+  Decisions). Frontends (`ui/src/Utilities.tsx` `isAPIError`/`printAPIError`, RTK error
+  middleware, `example-frontend/store/errors.ts`) keep reading `data.title`, `data.detail`,
+  `data.status`, `data.meta.fields`, and `data.disableExternalErrorTracking` when present.
+- Replacing the JSONAPI error model. The extension fields stay; only their relationship to the
+  standard `Error` fields changes.
+- A general error-taxonomy overhaul for consuming apps (Flourish, etc.). They get better behavior
+  for free; adopting `code`/subclasses is opt-in.
+
+## Evaluation of the current design
+
+What `APIError` does today (`api/src/errors.ts`):
+
+| Standard field | Current use | Problem |
+|---|---|---|
+| `name` | Hardcoded `"APIError"` | Every Sentry issue headline is "APIError". A 403 admin check and a 500 integration failure are indistinguishable at a glance, and type-based grouping collapses. |
+| `message` | `` `${title}: ${detail}\n${wrappedError.stack}` `` | Embedding a per-occurrence stack makes `message` unstable (defeats message-based grouping) and unreadable as a Sentry subtitle. It duplicates data Sentry would render natively from a `cause` chain. |
+| `stack` | Default (capture site) | Fine — but for framework-wrapped errors (e.g. the `preCreate hook error:` re-wraps in `api.ts`), the top frames are framework code, so unrelated app errors share a stack and group together. |
+| `cause` | Not used; a non-standard `error: unknown` field instead | Sentry's default `linkedErrors` integration walks `error.cause` and shows the chain as linked exceptions. The `error` field is invisible to it. |
+
+Additional design issues:
+
+1. **Constructor side effects.** Every construction calls `logger.error`/`logger.warn`, even when
+   the error is caught and handled, converted, or expected. Reporting belongs at the handling
+   boundary (`apiErrorMiddleware`), not at construction.
+2. **Internal config on the wire.** `getAPIErrorBody` serializes
+   `disableExternalErrorTracking` into the HTTP response body when true (needed for client-side
+   Sentry suppression). It is omitted when false/undefined.
+3. **Brittle type guard.** `isAPIError` checks `error.name === "APIError"`, which forbids ever
+   making `name` meaningful (the fix for the Sentry headline) and only exists to survive duplicate
+   `@terreno/api` instances across packages.
+4. **No `toJSON`.** `getAPIErrorBody` manually iterates a key list; the class should own its wire
+   serialization.
+5. **`title` is documented as stable per problem type (JSONAPI) but the framework violates it** —
+   e.g. `title: errorMessage(error)` and `` title: `preCreate hook error: ${errorMessage(error)}` ``
+   in `api.ts` interpolate per-occurrence text into `title`.
+6. **Sentry capture has no grouping hints.** `apiErrorMiddleware` calls
+   `Sentry.captureException(err)` bare — no fingerprint, no tags, no context from the JSONAPI
+   fields.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| What does `message` hold? | Exactly `title` — a stable, human-readable summary of the problem type. `detail`, `fields`, and the cause stack are **never** concatenated into `message`. `title` becomes a getter aliasing `message` so the extension field and the standard field cannot drift. |
+| What does `name` hold? | The error *type*, by precedence: subclass name (via `new.target.name`) → PascalCased `code` (`"update-admin-error"` → `UpdateAdminError`) → status-derived name (`BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `InternalServerError`, …) → `APIError`. |
+| How is the wrapped error attached? | Standard ES2022 `cause`: `super(title, {cause})`. The old `error` option is kept as a deprecated alias that feeds `cause`. Sentry then renders the chain as linked exceptions with the original stack. |
+| Where does logging happen? | In `apiErrorMiddleware`, not the constructor: `warn` for 4xx, `error` for 5xx (5xx are bugs/ops issues; 4xx are mostly client mistakes). Non-HTTP boundaries (websockets, scripts) already log via `logger.catch`/`captureException`. |
+| Is `disableExternalErrorTracking` still sent to clients? | Only when `true`. It lets the frontend suppress duplicate Sentry reporting (`example-frontend/store/errors.ts`). Omitted from the wire body when false/undefined. Still suppresses server-side Sentry capture in `apiErrorMiddleware` when set. |
+| How does `isAPIError` work? | Brand property `isTerrenoAPIError = true` set in the constructor (survives duplicate package instances), with a transition fallback for `name === "APIError"`. |
+| Does Sentry still capture 4xx APIErrors? | Unchanged for now: capture everything unless `disableExternalErrorTracking`. But capture gains a fingerprint and context (below) so 4xx noise at least groups correctly. A follow-up may default 4xx to log-only. |
+| Wire body shape? | `{status, title, detail?, code?, id?, links?, source?, meta?, disableExternalErrorTracking?}`. The last field is present only when `true`. `meta.fields` unchanged. |
+
+## Architecture
+
+### New class shape (`api/src/errors.ts`)
+
+```typescript
+export interface APIErrorOptions {
+  /** Stable, human-readable summary of the problem TYPE (JSONAPI title). Becomes Error.message. */
+  title: string;
+  /** HTTP status, 400–599. Defaults to 500; out-of-range values are coerced to 500 with a warn. */
+  status?: number;
+  /** Application-specific stable error code (kebab-case). Also drives Error.name when set. */
+  code?: string;
+  /** Human-readable, per-occurrence explanation. NOT folded into message. */
+  detail?: string;
+  /** Field-level messages for forms; folded into meta.fields on the wire (unchanged). */
+  fields?: {[id: string]: string};
+  /** The original error being wrapped. Standard ES2022 Error cause. */
+  cause?: unknown;
+  /** @deprecated Use `cause`. */
+  error?: unknown;
+  id?: string;
+  links?: {about?: string; type?: string};
+  source?: {pointer?: string; parameter?: string; header?: string};
+  meta?: {[id: string]: unknown};
+  /** When true, skip Sentry capture in apiErrorMiddleware. Never serialized to clients. */
+  disableExternalErrorTracking?: boolean;
+}
+
+export class APIError extends Error {
+  /** Brand for cross-package instanceof-free detection. */
+  readonly isTerrenoAPIError = true as const;
+
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly detail: string | undefined;
+  readonly id: string | undefined;
+  readonly links: {about?: string; type?: string} | undefined;
+  readonly source: {pointer?: string; parameter?: string; header?: string} | undefined;
+  readonly meta: {[id: string]: unknown};
+  readonly disableExternalErrorTracking: boolean | undefined;
+
+  constructor(options: APIErrorOptions) {
+    // message = title, nothing else. cause = the wrapped error, natively understood by Sentry.
+    super(options.title, {cause: options.cause ?? options.error});
+    this.status = normalizeStatus(options.status); // 500 default, 400–599 enforced
+    this.code = options.code;
+    // name precedence: subclass > code > status. `new.target` keeps subclass names automatically.
+    this.name =
+      new.target !== APIError
+        ? new.target.name
+        : (options.code ? pascalCase(options.code) : nameForStatus(this.status));
+    this.detail = options.detail;
+    this.id = options.id;
+    this.links = options.links;
+    this.source = options.source;
+    this.meta = {...options.meta, ...(options.fields ? {fields: options.fields} : {})};
+    this.disableExternalErrorTracking = options.disableExternalErrorTracking;
+    // No logging here. Reporting happens where the error is handled.
+  }
+
+  /** JSONAPI title === Error.message; a getter so the two can never drift. */
+  get title(): string {
+    return this.message;
+  }
+
+  /** Client-facing JSONAPI body. Excludes name/stack/cause; includes disableExternalErrorTracking when true. */
+  toJSON(): APIErrorBody {
+    ...
+  }
+}
+```
+
+`nameForStatus` maps common statuses (`400 BadRequestError`, `401 UnauthorizedError`,
+`403 ForbiddenError`, `404 NotFoundError`, `409 ConflictError`, `422 ValidationError`,
+`429 TooManyRequestsError`, `500 InternalServerError`, `502/503/504` gateway names) and falls back
+to `APIError` for anything unmapped.
+
+### What Sentry sees, before vs. after
+
+```text
+Before:  APIError
+         Only an admin can update that!: You must be an admin...\nError: inner\n  at ...
+
+After:   ForbiddenError            (or UpdateAdminError when code is set)
+         Only an admin can update that!
+         └─ caused by TypeError: Cannot read properties of undefined   (linked exception, own stack)
+```
+
+### Middleware changes (`apiErrorMiddleware`)
+
+```typescript
+if (isAPIError(err)) {
+  const logMessage = `${err.name}(${err.status}): ${err.message}${err.detail ? ` — ${err.detail}` : ""}`;
+  if (err.status >= 500) {
+    logger.error(logMessage);   // moved here from the constructor
+  } else {
+    logger.warn(logMessage);
+  }
+  if (!err.disableExternalErrorTracking) {
+    Sentry.withScope((scope) => {
+      // Group by logical error type, not by whichever framework frame constructed it.
+      scope.setFingerprint([err.name, err.code ?? err.message, String(err.status)]);
+      scope.setTag("http.status_code", String(err.status));
+      if (err.code) {
+        scope.setTag("api_error.code", err.code);
+      }
+      scope.setContext("apiError", err.toJSON()); // detail, source, meta.fields, etc.
+      Sentry.captureException(err);
+    });
+  }
+  res.status(err.status).json(err.toJSON());
+  return;
+}
+```
+
+The explicit fingerprint fixes the second half of the reported problem: today all framework-thrown
+`APIError`s share near-identical construction stacks inside `api.ts`, so Sentry's default
+stack-trace grouping lumps unrelated errors together. Fingerprinting on
+`name + (code ?? title) + status` groups by problem type instead, while the `cause` chain
+preserves each occurrence's real origin stack for debugging.
+
+### Optional convenience subclasses (phase 2)
+
+For the most common statuses, thin subclasses give static `name`s, less boilerplate, and free
+`instanceof` narrowing. They are sugar only — everything works with plain `APIError`:
+
+```typescript
+export class NotFoundError extends APIError {
+  constructor(options: Omit<APIErrorOptions, "status"> | string) {
+    super(typeof options === "string" ? {status: 404, title: options} : {...options, status: 404});
+  }
+}
+// BadRequestError, UnauthorizedError, ForbiddenError, ConflictError, ValidationError, InternalError
+```
+
+`mongooseErrorToAPIError` would return `ValidationError` instances (name "ValidationError",
+status 400) instead of generic `APIError({title: "Validation failed"})`.
+
+### Framework call-site cleanup (`api/src/api.ts`)
+
+The re-wrap sites currently interpolate the inner message into `title`. With `cause`, `title`
+becomes stable and per-occurrence text moves to `detail`:
+
+```typescript
+// Before
+throw new APIError({title: `preCreate hook error: ${errorMessage(error)}`, error, status: 400, ...});
+
+// After
+throw new APIError({
+  cause: error,
+  code: "pre-create-hook-error",       // -> name PreCreateHookError
+  detail: errorMessage(error),
+  disableExternalErrorTracking: getDisableExternalErrorTracking(error),
+  status: 400,
+  title: "preCreate hook failed",
+});
+```
+
+Same pattern for `preUpdate`/`preDelete`/`postCreate`/`postUpdate`, `Populate error`,
+`responseHandler error`, and `Query filter error` sites.
+
+## Models
+
+No model changes. `errorsPlugin` (the `apiErrors` subdocument schema) already stores only the
+JSONAPI extension fields and is unaffected.
+
+## APIs
+
+- **Wire format:** `disableExternalErrorTracking` is included in the body only when `true`.
+- **Public exports:** `APIError`, `APIErrorOptions` (new; `APIErrorConstructor` kept as a
+  deprecated alias), `isAPIError`, `errorMessage`, `errorStack`,
+  `getDisableExternalErrorTracking`, `mongooseErrorToAPIError`, middlewares — all keep their
+  names. `getAPIErrorBody` becomes a deprecated wrapper around `error.toJSON()`.
+- **`isAPIError`:** checks the `isTerrenoAPIError` brand (plus a transition-period fallback for
+  `name === "APIError"` to accept instances from older `@terreno/api` versions in mixed
+  node_modules).
+
+## Notifications
+
+None.
+
+## UI
+
+No UI changes required. `ui/src/Utilities.tsx` `isAPIError` (checks `data.title`) and
+`printAPIError` (reads `data.title`/`data.detail`) continue to work; `title` remains the stable
+summary and `detail` the occurrence-specific text.
+
+## Phases
+
+1. **Core class** — rewrite `APIError` (message=title, name derivation, `cause`, brand, `toJSON`,
+   no constructor logging); update `isAPIError`, deprecate `getAPIErrorBody`; move logging +
+   Sentry scope/fingerprint into    `apiErrorMiddleware`; update `errors.test.ts`, `api.hooks.test.ts` (assert
+   `res.body.disableExternalErrorTracking` when the flag is set),
+   `api.errors.test.ts`, `permissions.middleware.test.ts`, `docLoader.test.ts`.
+2. **Framework call sites** — stabilize `title` + move per-occurrence text to `detail`/`cause` in
+   `api.ts`, `openApiValidator.ts`, `permissions.ts`, `auth.ts`, `plugins.ts`, and add `code`
+   where a stable identity helps grouping. Introduce the convenience subclasses and use
+   `ValidationError` in `mongooseErrorToAPIError`.
+3. **Downstream packages** — `admin-backend`, `feature-flags`, `ai`, `example-backend`: swap
+   `error:` for `cause:` and adopt `code`/subclasses opportunistically. Regenerate website
+   reference docs (`update-docs` skill).
+
+## Feature Flags & Migrations
+
+None. No stored data changes. The behavior changes (Sentry titles/grouping, log level for 4xx,
+dropped response flag) ship with a minor version bump and a changelog entry; consuming apps need
+no code changes unless they asserted on the removed response field or the exact `name` string.
+
+## Activity Log & User Updates
+
+N/A.
+
+## Not Included / Future Work
+
+- Defaulting 4xx APIErrors to log-only (no Sentry capture) unless opted in.
+- An RFC 9457 (`application/problem+json`) response mode. The JSONAPI error object is close
+  (`title`/`detail`/`status` align); `links.about` ≈ `type`. Not worth a wire break now.
+- Client-side (RTK) typed error codes generated from the OpenAPI spec.
+
+## Files to Create / Modify
+
+As implemented:
+
+- `api/src/errors.ts` — core redesign (class, name/status maps, subclasses, `toJSON`, middleware).
+- `api/tsconfig.json` — add `es2022.error` to `lib` for the standard `ErrorOptions`/`cause` types.
+- `api/src/api.ts`, `api/src/transformers.ts`, `api/src/httpClient.ts`, `api/src/config.ts`,
+  `api/src/docLoader.ts` — stable titles, `cause`, `code` at every wrap site (phase 2).
+  `permissions.ts`, `auth.ts`, `plugins.ts`, and `openApiValidator.ts` needed no changes — they
+  already used stable titles without wrapped errors.
+- Tests: `api/src/errors.test.ts`, `api/src/api.errors.test.ts`, `api/src/api.hooks.test.ts`,
+  `api/src/api.test.ts`, `api/src/api.errorPaths.test.ts`, `api/src/notifiers/*.test.ts`,
+  `ai/src/langfuseRoutesMiddleware.test.ts` — updated expectations plus new coverage for name
+  derivation, `cause`, subclasses, `toJSON`, and the Sentry fingerprint.
+- Downstream packages had no `error:` usages, so phase 3 required no code changes.
+- Docs: `.rulesync/rules/api/00-api.md` error-handling section (mirrors regenerated with
+  `bun run rules`).
+
+## Task List
+
+Implemented directly on this branch (all three phases); no separate tasks file.
+
+## Acceptance Criteria
+
+- [x] `new APIError({status: 404, title: "Todo not found"})` has `name === "NotFoundError"`,
+      `message === "Todo not found"`, `title === "Todo not found"`, and a clean single-line message.
+- [x] `new APIError({title: "X", cause: inner})` exposes `error.cause === inner` and Sentry shows
+      the inner error as a linked exception with its own stack.
+- [x] Sentry issue headline shows the derived/subclass name (never a bare "APIError" for errors
+      with a mapped status or code), and two errors with different `name`/`code` never share an
+      issue (fingerprint on `name + code + status`, falling back to `name` when `code` is absent).
+- [x] Constructing an APIError produces no log output; handling one through `apiErrorMiddleware`
+      logs `warn` (4xx) or `error` (5xx) exactly once.
+- [x] Response bodies keep `{status, title, detail, code, meta.fields, ...}`; include
+      `disableExternalErrorTracking` only when `true`; never include `name`, `stack`, or `cause`.
+- [x] `isAPIError` returns true across duplicate `@terreno/api` copies and for subclasses.
+- [x] `bun run api:test` passes; `bun run lint` passes for all touched packages (the pre-existing
+      `@terreno/ui` `ConsentNavigator.tsx` floating-promise failures are unrelated).

package/dist/docs/versioned/0.29.0/implementationPlans/build-terreno-app-validation.md

@@ -0,0 +1,153 @@
+# Implementation Plan: Dogfooding Run and Launch Blog Post
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**Priority:** High (this is the program's acceptance test)
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), [`ai-dev-loop-boost`](ai-dev-loop-boost.md), [`deploy-to-vercel`](deploy-to-vercel.md), [`docs-reference-coverage`](docs-reference-coverage.md)
+**RTK deprecation flag:** **Blocked** — the build must be performed against the supported stack (syncdb + Better Auth). A dogfooding run on the deprecated data layer would produce a friction log and a blog post that are both obsolete on publication.
+
+## Goal
+
+Prove the launch claim by testing it, then publish the result. The [`build-terreno-app`](../../.rulesync/skills/build-terreno-app/SKILL.md) skill is the harness; this IP is the run, the fixes that come out of it, and the blog post.
+
+The program's launch gate is: **if an agent following only public documentation and published skills cannot build and deploy a real universal app, the launch is not ready.** This IP executes that test. Its most likely outcome is a list of documentation gaps, which is exactly what it is for.
+
+## Non-Goals
+
+- Writing the skill (already done — this IP runs it).
+- Shipping the demo app as a maintained Terreno example. It is a blog-post artifact, not a fourth example app to keep updated.
+- Marketing beyond the blog post.
+- Building every app concept. One run, one app.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Question | Decision |
+|---|----------|----------|
+| B1 | App concept | **Pantry** — leads on syncdb conflict resolution |
+| B2 | Public demo repo? | **A** — `flourishhealth/terreno-pantry` |
+| B3 | Who performs the run? | **C** if capacity; else **A** |
+| B4 | Runs before publish | **B** — two runs with fix cycle between |
+| B5 | Publication venue | **A** — docs site blog only |
+| B6 | Name the model? | **A** — yes, with version |
+
+## Architecture
+
+### Run structure
+
+```mermaid
+flowchart TD
+  R1["Run 1<br/>fresh session, public sources only"]
+  L1["Friction log 1<br/>gaps by severity"]
+  F["Fix cycle<br/>docs, skills, MCP"]
+  R2["Run 2<br/>fresh session, fresh environment"]
+  L2["Friction log 2<br/>+ repeat-gap analysis"]
+  G{"Blocking or<br/>major gaps left?"}
+  B["Blog post"]
+  LAUNCH["Launch gate: passed"]
+  R1 --> L1 --> F --> R2 --> L2 --> G
+  G -->|"yes"| F
+  G -->|"no"| B --> LAUNCH
+```
+
+The loop between the gap check and the fix cycle is the point. Exiting after one pass would mean publishing a launch claim that was never re-tested.
+
+### What counts as passing
+
+| Gate | Threshold |
+|------|-----------|
+| Blocking gaps | zero |
+| Major gaps | zero at launch; any found in run 1 must be fixed and confirmed in run 2 |
+| Minor gaps | acceptable, all filed as issues |
+| App completeness | every slice in the chosen concept working on web and one native target |
+| Differentiators | all six demonstrated with artifacts (AI, offline, realtime, admin, universal, feature flags) |
+| Deployment | public URL, all four verification checks passing |
+| Debug loop | the deliberate bug found via `last_error` / `read_logs` without reading framework source |
+
+The debug-loop gate is the one that most directly tests the AI-native pillar. If the agent has to read `@terreno/api` source to diagnose a bug in its own app, the pillar is not real yet.
+
+### Fix routing
+
+Gaps found in a run do not get fixed inside this IP. They route to the IP that owns the surface:
+
+| Gap type | Routes to |
+|----------|-----------|
+| Tutorial wrong or incomplete | [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md) |
+| Reference page missing or wrong | [`docs-reference-coverage`](docs-reference-coverage.md) |
+| MCP tool or agent-loop gap | [`ai-dev-loop-boost`](ai-dev-loop-boost.md) |
+| Deployment guide or skill gap | [`deploy-to-vercel`](deploy-to-vercel.md) / [`deploy-to-gcp`](deploy-to-gcp.md) |
+| Bootstrap output wrong | [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) (agent surfaces) or the MCP server |
+| Positioning inconsistency | [`positioning-django-rails-universal`](positioning-django-rails-universal.md) |
+| Genuine framework bug | a new issue, triaged normally |
+
+This keeps ownership clear and prevents this IP from absorbing the whole program.
+
+## Models / APIs
+
+None in Terreno. The demo app's models come from the chosen concept and live in its own repository.
+
+## Notifications
+
+None.
+
+## UI
+
+The demo app's screens live in its own repository. No changes to `@terreno/ui` unless the run finds a bug, which routes out per the table above.
+
+## Phases
+
+1. **Run 1** — fresh session, public sources only, friction log produced.
+2. **Triage** — classify every gap, route to owning IPs, file issues.
+3. **Fix cycle** — owning IPs land their fixes (tracked, not performed here).
+4. **Run 2** — fresh session and fresh environment, second friction log, repeat-gap analysis.
+5. **Gate** — confirm zero blocking and zero major gaps, or loop back to phase 3.
+6. **Blog post** — draft, artifact review, fact check, publish.
+7. **Retrospective** — record what the harness itself got wrong so the skill improves.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- A recurring dogfooding cadence (worth doing quarterly; propose separately once the first run has calibrated the effort).
+- Building the other four app concepts.
+- Maintaining the demo app past the post.
+- Comparative benchmarks against other frameworks.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/explanation/dogfooding-results.md` (the public summary of both runs)
+- The demo app repository (outside this repo, per B2)
+
+**Modify**
+
+- `.rulesync/skills/build-terreno-app/SKILL.md` and its references (retrospective improvements)
+- `website/blog/` (the post, if the docs site gains a blog)
+- Whichever documents the fix cycle touches — owned by their IPs
+
+## Task List
+
+See [`docs/tasks/build-terreno-app-validation.md`](../tasks/build-terreno-app-validation.md).
+
+## Acceptance Criteria
+
+- [ ] Run 1 completed with a friction log classifying every gap by severity, phase, and suggested fix.
+- [ ] Every blocking and major gap from run 1 is filed as an issue and routed to an owning IP.
+- [ ] Run 2 completed in a fresh environment after fixes, with its own friction log.
+- [ ] Run 2 reports zero blocking gaps and zero major gaps.
+- [ ] Any gap appearing in both runs is called out explicitly with an explanation of why the fix did not work.
+- [ ] The demo app implements every slice of the chosen concept and runs on web and one native target.
+- [ ] All six differentiators are demonstrated with artifacts in `/opt/cursor/artifacts/`.
+- [ ] The deliberate bug was found using only `last_error` and `read_logs`, without reading framework source, and the elapsed time is recorded.
+- [ ] The app is deployed to a public URL with all four verification checks passing.
+- [ ] `BLOG_DRAFT.md` follows the outline, includes a "what did not work" section with three real gaps, and names the model and version used.
+- [ ] Every claim in the post is verified against an artifact by someone who did not perform the run.
+- [ ] `docs/explanation/dogfooding-results.md` publishes both runs' gap counts and what changed between them.
+- [ ] The `build-terreno-app` skill is updated with retrospective improvements, and mirrors are regenerated.