@terreno/mcp 57.2.0 → 57.3.0

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

@@ -1,174 +0,0 @@
-# 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/src/docs/versioned/0.28.0/implementationPlans/apierror-standard-error-redesign.md

@@ -1,332 +0,0 @@
-# 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/src/docs/versioned/0.28.0/implementationPlans/build-terreno-app-validation.md

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