@terreno/mcp 0.27.0 → 0.28.0

package/src/docs/versioned/next/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/src/docs/versioned/next/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.

package/src/docs/versioned/next/implementationPlans/deploy-to-gcp.md

@@ -0,0 +1,166 @@
+# Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+**Status:** Approved — 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:** [`deployment-foundation`](deployment-foundation.md) for the shared Dockerfile and env reference (soft dependency — Phase 1 can start in parallel)
+**RTK deprecation flag:** None for the backend and infrastructure. The frontend build step is data-layer agnostic (`expo export -p web` output is static either way). The only RTK-adjacent content is the `EXPO_PUBLIC_API_URL` env var, which survives the syncdb migration.
+
+## Goal
+
+Turn Terreno's GCP deployment story from "how Flourish deploys Terreno" into "how anyone deploys a Terreno app to GCP", and give agents a skill that can execute it. Today `docs/how-to/deploy-to-gcp.md` hardcodes the `flourish-terreno` project, `flourish-terreno-terreno-demo` bucket names, and Flourish's service-account layout; `terraform/README.md` is Flourish-specific; and `scripts/setup-gcs-hosting.sh` provisions Flourish's two static sites. None of it is reusable by an outside user, and no skill wraps any of it.
+
+## Non-Goals
+
+- Multi-region or multi-environment (staging/prod) topologies beyond a documented single extra environment.
+- Kubernetes/GKE. Cloud Run only.
+- Managing MongoDB inside GCP. Mongo Atlas is the documented path; self-hosted Mongo is explicitly out of scope.
+- Replacing Flourish's existing terraform — that is relocated, not rewritten (see program question P5).
+
+## Blocking questions
+
+**Recorded 2026-07-29.**
+
+| # | Question | Decision |
+|---|----------|----------|
+| GC1 | Frontend web hosting | **GCS + Cloud CDN as GCP default**, plus **Netlify** (document the existing Flourish/Terreno Netlify pattern as a first-class alternative for static web export) |
+| GC2 | Database guidance | **MongoDB Atlas only** for launch; add a **future-work note** toward Postgres when the data layer supports it |
+| GC3 | terraform or gcloud | **C** — `gcloud` quickstart + terraform for production |
+| GC4 | Reusable terraform module | **B** — `terraform/modules/terreno-backend/` |
+| GC5 | Flourish infra location (→ P5) | **C** — `infra/flourish/` now; **migrate to B** (private repo) post-launch |
+| GC6 | `deploy-gcp` skill deploys? | **C** — full deploy behind explicit confirmation gate |
+| GC7 | Secret management | **A** — Secret Manager for secrets; plain env for non-secrets |
+
+## Architecture
+
+### Reference topology (documented default)
+
+**GCP path:** GCS + Cloud CDN for static web export (see diagram below).
+
+**Netlify path:** Document the existing Terreno/Flourish Netlify static hosting pattern as a first-class alternative for `expo export -p web` — same backend topology, different static host.
+
+```mermaid
+flowchart TD
+  U["User<br/>iOS / Android / Web"]
+  CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
+  CR["Cloud Run<br/>@terreno/api backend"]
+  SM["Secret Manager<br/>auth secrets, MONGO_URI"]
+  AT["MongoDB Atlas<br/>replica set (change streams)"]
+  GCS["GCS bucket<br/>user file uploads"]
+  AR["Artifact Registry<br/>backend image"]
+  U -->|"web"| CDN
+  U -->|"native app"| CR
+  CDN -->|"API calls"| CR
+  CR --> SM
+  CR --> AT
+  CR --> GCS
+  AR --> CR
+```
+
+### Required GCP resources
+
+| Resource | Purpose | Notes |
+|----------|---------|-------|
+| Artifact Registry repo | backend container images | Regional, Docker format |
+| Cloud Run service | backend | Min instances 0 for dev, ≥1 for prod (cold starts break websockets); `--session-affinity` required for Socket.io |
+| Secret Manager secrets | auth secrets + `MONGO_URI` | Mounted as env vars via `--set-secrets` |
+| GCS bucket (web) | static web export | `notFoundPage=index.html` for client-side routing |
+| Backend bucket + URL map + IP + proxy + forwarding rule | Cloud CDN in front of the web bucket | The five resources the current script creates |
+| GCS bucket (uploads) | user file storage | Separate from the web bucket; not public |
+| Service account (runtime) | Cloud Run identity | `roles/secretmanager.secretAccessor`, `roles/storage.objectAdmin` on the uploads bucket only |
+| Service account (deploy) | CI identity | Prefer Workload Identity Federation over JSON keys |
+
+### Websocket and change-stream constraints to document
+
+These are the non-obvious failure modes and must be called out explicitly:
+
+- Socket.io on Cloud Run requires `--session-affinity` and a request timeout raised from the 300s default.
+- Change streams (realtime + feature-flag live updates) require a replica set. A standalone `mongod` silently fails at startup — the guide must say so.
+- Scaling to zero drops websocket connections; the client reconnects, but feature-flag live updates lag. Recommend `--min-instances=1` for anything user-facing.
+- `corsOrigin` in `setupServer` must include the CDN domain, and Better Auth needs the web origin in `trustedOrigins`.
+
+### `deploy-gcp` skill shape
+
+New skill at `.rulesync/skills/deploy-gcp/SKILL.md`, generated into all agent targets. Structure:
+
+1. **Preflight** — detect project layout (bootstrap `backend/`+`frontend/` vs monorepo), read `gcloud config`, verify required APIs enabled, verify `MONGO_URI` points at a replica set.
+2. **Plan** — print the exact resources to be created/updated and the target project, region, and service names. Require explicit user confirmation before mutating anything (GC6).
+3. **Backend** — build image, push to Artifact Registry, create/update secrets, deploy Cloud Run with session affinity and the correct env/secret wiring.
+4. **Frontend** — `expo export -p web`, sync to the web bucket, invalidate CDN cache.
+5. **Verify** — `curl <backend>/health` expecting `"healthy":true`, fetch the web root, confirm the SPA loads, print URLs.
+6. **Troubleshoot** — a table of symptom → cause → fix covering the four constraints above.
+
+## Models
+
+None.
+
+## APIs
+
+None new. The guide relies on the existing `/health` endpoint from `@terreno/api-health` for verification.
+
+## Notifications
+
+None.
+
+## UI
+
+None.
+
+## Phases
+
+1. **Generalize the how-to** — rewrite `docs/how-to/deploy-to-gcp.md` as a project-agnostic guide covering backend + frontend, with placeholder variables and the constraints section.
+2. **Terraform module** — extract a reusable `terraform/modules/terreno-backend/` module; relocate Flourish-specific config to `infra/flourish/`.
+3. **Scripts** — parameterize `scripts/setup-gcs-hosting.sh` to take project/bucket/site names as arguments instead of hardcoding Flourish's.
+4. **Skill** — author `deploy-gcp` in `.rulesync/skills/` and generate mirrors.
+5. **Validate** — deploy the example stack to a scratch GCP project using only the public guide, then fix what the guide got wrong.
+
+## Feature Flags & Migrations
+
+No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenced by `.github/workflows/cd.yml` and `terraform/README.md`; both must be updated in the same commit.
+
+## Not Included / Future Work
+
+- Multi-environment terraform workspaces beyond one documented staging example.
+- Cost estimation guidance.
+- Cloud Armor / WAF configuration.
+- Deploying the hosted MCP server (that is Flourish's own infra, documented in `infra/flourish/`).
+- SSR-capable web hosting — depends on [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md).
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/how-to/deploy-backend-to-cloud-run.md`
+- `docs/how-to/deploy-web-to-gcs-cdn.md`
+- `docs/explanation/deployment-architecture-gcp.md`
+- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,README.md}`
+- `.rulesync/skills/deploy-gcp/SKILL.md`
+- `.rulesync/skills/deploy-gcp/references/troubleshooting.md`
+
+**Modify**
+
+- `docs/how-to/deploy-to-gcp.md` (becomes an index pointing at the two new guides, or is deleted with redirects)
+- `docs/how-to/README.md`
+- `scripts/setup-gcs-hosting.sh` (parameterize)
+- `terraform/README.md` (split generic vs Flourish)
+- `.github/workflows/cd.yml`, `.github/workflows/demo-deploy.yml`, `.github/workflows/frontend-example-deploy.yml` (path updates if terraform moves)
+- `example-backend/Dockerfile` (created by [`deployment-foundation`](deployment-foundation.md); referenced here)
+
+## Task List
+
+See [`docs/tasks/deploy-to-gcp.md`](../tasks/deploy-to-gcp.md).
+
+## Acceptance Criteria
+
+- [ ] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
+- [ ] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
+- [ ] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
+- [ ] `terraform/modules/terreno-backend/` applies cleanly against a scratch project with only variables supplied, creating Cloud Run + Artifact Registry + secrets + service accounts.
+- [ ] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
+- [ ] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
+- [ ] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
+- [ ] A full deploy of `example-backend` + `example-frontend` to a scratch GCP project succeeds following only the public docs, and `curl <backend>/health` returns `"healthy":true`.
+- [ ] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.