@terreno/mcp 57.0.0 → 57.2.0

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

@@ -0,0 +1,175 @@
+# Implementation Plan: The AI Development Loop (Boost)
+
+**Status:** Draft — key decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/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/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/57.1.0/implementationPlans/apierror-standard-error-redesign.md

@@ -0,0 +1,333 @@
+# APIError redesign — standards-first extension of Error
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1080
+**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/57.1.0/implementationPlans/b2b-platform-program.md

@@ -0,0 +1,116 @@
+# Program: B2B platform
+
+**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first ten IPs open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1095
+**Owner:** unassigned
+**Created:** 2026-08-09
+
+Umbrella plan coordinating the IPs that take Terreno from a single-tenant, per-user
+full-stack kit to a framework you can spin up a B2B SaaS app with in hours. Pairs with the
+roadmap items in
+[roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md) (B2B platform program
+section).
+
+## Goal
+
+A freshly scaffolded, deployed Terreno app supports the B2B critical path out of the box:
+**sign up → create an organization → invite a teammate → pick a plan → get an email.**
+Today zero of those five steps are possible without custom code.
+
+## Background
+
+A capability audit (2026-08-08) found Terreno strong as a single-tenant CRUD + auth +
+realtime + admin + AI kit, with three structural gaps for B2B SaaS: **tenancy** (no
+orgs/teams/memberships), **money** (no billing), and **communication** (no email, SMS, or
+push delivery — `expo-server-sdk` is an unused dependency and the RTK client's
+`resetPassword` endpoint has no backend implementation). Supporting gaps: no invitations,
+no durable jobs, no inbound-webhook framework, no rate limiting, no framework-level audit
+log, no enterprise SSO/MFA, and missing B2B UI surfaces (server-filtered data grid, charts,
+org switcher, dark mode).
+
+## Tracks
+
+| Track | Theme | IPs / roadmap items |
+|---|---|---|
+| A | Tenancy & access | `orgs-and-teams`, `rbac-permissions` (Complete), `invitations-and-seats`, `org-management-ui` |
+| C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); operations: `comms-admin-dashboard`; consumers: `password-reset-and-email-verification`, `notification-center` |
+| B | Billing | `inbound-webhooks`, `billing-stripe` (web-first, per D1), `mobile-iap-revenuecat` (Future) |
+| D | Zero-to-deployed DX | `create-terreno-app`, `mongo-migrations` (deploy items already exist in the OSS launch program) |
+| E | B2B UI surfaces | `data-grid-server-filters`, `charts-and-dashboards`, `dark-mode-theme`, `command-palette`, `wizard-stepper`, `wysiwyg-editor` (markdown stays for now, per D3), `global-search` |
+| F | Enterprise & scale | `framework-audit-log` (Next), `rate-limiting` (Next), `job-queues` (Next), `enterprise-sso`, `mfa-step-up-auth` |
+| — | Native baseline | `native-module-baseline` — all new native modules land in one major release |
+
+## Sequencing
+
+1. **Foundations first:** `comms-abstraction` and `orgs-and-teams` are independent and both
+   unblock most of the program. `inbound-webhooks` lands before billing and before comms
+   delivery callbacks.
+2. **Close the auth hole early:** `password-reset-and-email-verification` ships as soon as
+   the abstraction plus one mail adapter exist — the client already calls `POST
+   /resetPassword`.
+3. **Billing after orgs + webhooks.**
+4. **Native baseline rides the next major release** so every later feature ships as
+   JS/OTA against the same binary.
+5. Track E/F items are independent and can be scheduled opportunistically.
+
+## Native module baseline (next major release)
+
+Adding a native module to `@terreno/ui` or the example apps forces consumers to cut a new
+dev-client/store build, so all additions land together in the next major:
+
+| Package | Enables | Notes |
+|---|---|---|
+| `@stripe/stripe-react-native` | Billing (payment sheet, Apple/Google Pay) | Config plugin; Kotlin 2.x + compileSdk 36 via `expo-build-properties` |
+| `react-native-purchases` (+ `-ui`) | Mobile IAP (RevenueCat) | Feature ships later (D1: Stripe web-first) — SDK included now so IAP lands without another major |
+| `expo-device` | Push registration guards | trivial |
+| `expo-crypto` | PKCE for SSO, invite tokens | trivial |
+| `expo-local-authentication` | Biometric step-up (MFA) | `NSFaceIDUsageDescription` |
+| `expo-system-ui` | Dark mode root/system chrome | trivial |
+| `react-native-otp-verify` | Android SMS OTP autofill | Included (D7) for the Twilio Verify flows |
+
+Excluded by decision: `@10play/tentap-editor` (D3 — markdown stays; revisit in a later
+major if WYSIWYG is adopted).
+
+Already linked, no action: skia, reanimated, gesture-handler, svg, webview,
+expo-notifications, expo-secure-store, expo-document-picker/image-picker, blur,
+permissions, expo-network. Charts (`victory-native`) is JS-only on existing peers.
+
+## Decision log
+
+All decisions resolved by the maintainer on 2026-08-09:
+
+| # | Decision | Resolution |
+|---|---|---|
+| D1 | Billing vendor strategy | **Stripe web-first.** RevenueCat mobile IAP stays `Future`; `react-native-purchases` still ships in the native baseline |
+| D2 | First mail adapter | **SendGrid (Twilio SendGrid)** — pairs with the Twilio SMS/Verify credentials story; other providers get items when demand appears |
+| D3 | WYSIWYG editor | **Markdown-only for now.** TenTap excluded from the native baseline; revisit in a later major |
+| D4 | First push adapter | **Expo push.** |
+| D5 | Targets | **Twilio push adapter dropped entirely** (item removed). Promoted to `Next`: `notification-center`, `framework-audit-log`, `rate-limiting`, `job-queues`. Everything else stays as drafted |
+| D6 | Orgs data model | **Native Terreno Mongoose models** (works for JWT + Better Auth), optional Better Auth sync later |
+| D7 | Final native manifest | **Confirmed:** six core packages + `react-native-purchases` + `react-native-otp-verify`; no TenTap |
+
+## IPs in this program
+
+| IP | Status | Tasks |
+|---|---|---|
+| [comms-abstraction](comms-abstraction.md) | Approved — Phase 1 gap-fill implemented | [tasks](../tasks/comms-abstraction.md) |
+| [comms-adapter-expo-push](comms-adapter-expo-push.md) | Draft | [tasks](../tasks/comms-adapter-expo-push.md) |
+| [comms-adapter-twilio-sms](comms-adapter-twilio-sms.md) | Draft | [tasks](../tasks/comms-adapter-twilio-sms.md) |
+| [comms-adapter-twilio-verify](comms-adapter-twilio-verify.md) | Draft | [tasks](../tasks/comms-adapter-twilio-verify.md) |
+| [comms-adapter-sendgrid](comms-adapter-sendgrid.md) | In progress (Phase 1) | [tasks](../tasks/comms-adapter-sendgrid.md) |
+| [comms-admin-dashboard](comms-admin-dashboard.md) | Draft | [tasks](../tasks/comms-admin-dashboard.md) |
+| [password-reset-and-email-verification](password-reset-and-email-verification.md) | Draft | [tasks](../tasks/password-reset-and-email-verification.md) |
+| [orgs-and-teams](orgs-and-teams.md) | Draft | [tasks](../tasks/orgs-and-teams.md) |
+| [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |
+| [native-module-baseline](native-module-baseline.md) | Draft | [tasks](../tasks/native-module-baseline.md) |
+| [rbac-permissions](rbac-permissions.md) | Complete (PR #932) | — |
+
+Remaining items (`inbound-webhooks`, `invitations-and-seats`, `org-management-ui`,
+`notification-center`, `framework-audit-log`, `rate-limiting`, `job-queues`, …) get IPs as
+they approach the top of the queue.
+
+## Not Included
+
+- Deploy guides and deployment foundation (OSS launch program).
+- `@terreno/syncdb` migration work (PR #869 track).
+- Marketing/positioning for the B2B pitch.