@terreno/mcp 57.19.2 → 57.21.0

package/dist/docs/versioned/57.20.0/implementationPlans/unified-mutation-executors.md

@@ -0,0 +1,129 @@
+# Unified mutation executors (MCP → executors)
+
+**Status:** Complete — 2026-08-25  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [model-router-actions.md](../explanation/model-router-actions.md), [model-router-mcp.md](model-router-mcp.md), [pluggable-database-sqlite.md](pluggable-database-sqlite.md)  
+**Task list:** [unified-mutation-executors.md](../tasks/unified-mutation-executors.md)  
+**Depends on:** none  
+**Unlocks:** [can-as-permission-seam.md](can-as-permission-seam.md), [collection-registry.md](collection-registry.md)
+
+## Goal
+
+One write pipeline for create, update, and delete. REST and Sync already call `executeCreate` / `executeUpdate` / `executeDelete` in `api/src/sync/executors.ts`. MCP `handleCreate` / `handleUpdate` / `handleDelete` in `api/src/mcp/handlers.ts` still run permissions, transformers, hooks, and `model.create` / `doc.save` themselves.
+
+When this ships, MCP write tools call those executors. A permission, hook, field-view, or soft-delete fix lands once.
+
+## Non-Goals
+
+- List/read unification (MCP list/read stay handlers; they are not duplicated against executors).
+- Replacing executors with a new `WriteService` class.
+- Implementing the SQLite `DatabaseAdapter` (executors will later call the adapter; this IP does not introduce it). See [pluggable-database-sqlite.md](pluggable-database-sqlite.md).
+- Changing MCP tool names, JSON-RPC transport, or `excludeFields` config shape.
+- Compiling RBAC `access` away from `PermissionMethod[]` (that is [can-as-permission-seam.md](can-as-permission-seam.md)).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — MCP adapters call existing executors.** Not B (a new `WriteService` wrapping both). Smallest interface: three functions already used by REST and Sync. |
+| Error contract | Executors keep throwing `APIError`. MCP maps `APIError` (and hook failures) onto the existing MCP error `textResult` / `errorResult` envelope. No new error type. |
+| Request object | Pass a real Express `req` when HTTP; otherwise the existing executor `{user}` stub via `createMCPRequest` fields (`user`, `body`). Do not invent a second hook request type. |
+| MCP-only behavior | Keep MCP `excludeFields`, `mcpResponseHandler`, and tool-result JSON wrapping in the handler **after** the executor returns `{doc}`. Executors stay transport-agnostic. |
+| `skipPostHooks` | MCP uses the REST path (`skipPostHooks` unset). Sync keeps the ledger-safe skip. |
+| Compatibility | No app-facing API break. MCP tool argument schemas and success JSON `{data}` stay the same. Error **strings** may align to `APIError.title` where they currently diverge; tests that pin MCP wording update in this slice. |
+| Sequencing | Land before collection-registry and can-as-permission-seam so those IPs do not have to touch two write implementations. |
+
+## Interface shapes considered
+
+**A (chosen).** `handleCreate(entry, args, user)` → `executeCreate({model, options: entry.options, user, body, req: mcpStubReq})` → map `{doc}` / `APIError` to `MCPToolResult`.
+
+**B (rejected).** `class MutationService { create; update; delete }` that REST, Sync, and MCP all call. Deletes the executor module only by renaming it; REST already has the deep module.
+
+## Architecture
+
+```
+Before:
+  MCP handlers ──duplicate──► Mongoose + permissions + hooks
+  REST / Sync ──────────────► executors ──► Mongoose
+
+After:
+  MCP ──map args/errors──► executors ◄── REST / Sync
+                              │
+                              ▼
+                           Mongoose (later: DatabaseAdapter)
+```
+
+`executeCreate` already: `checkPermissions` → `transform` → `preCreate` → `model.create` → populate → `postCreate` (unless skipped). MCP `handleCreate` repeats that and calls `model.create` directly (`api/src/mcp/handlers.ts`).
+
+Handler leftover after this IP:
+
+1. Auth / anonymous gate that is MCP-transport specific.
+2. `omitDeniedWriteFields` / MCP `excludeFields` (if not already covered by executor field views — prove with tests; if executor already strips write-denied fields, delete the MCP copy).
+3. Call executor.
+4. `mcpResponseHandler` / `serializeResponse`.
+5. `APIError` → MCP error result.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/explanation/model-router-actions.md` | Writes (CRUD, not named actions) go through executors for REST, Sync, and MCP. |
+| `docs/reference/api.md` (MCP tools) | MCP create/update/delete share REST permission and hook semantics; errors are `APIError` titles. |
+| `docs/implementationPlans/model-router-mcp.md` | Note: write path now executors (status note, not a rewrite of that shipped IP). |
+
+Skip operator how-to: no new env, CLI, or app setup.
+
+## Testing
+
+Public seam: `executeCreate` / `executeUpdate` / `executeDelete` (existing `executors.test.ts`) plus MCP integration tests that assert **behavior** (denied create, preCreate null, hook throw, field omit) against the same fixtures as REST.
+
+Add one MCP test that fails if `handleCreate` uses `model.create` instead of `executeCreate` (spy or shared side-effect: `preCreate` called once with the stub request).
+
+Do not weaken executor tests. MCP tests that duplicate permission matrices can shrink after the adapter is thin.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| MCP error strings differ from `APIError.title` | Golden-file or explicit map in handler; update MCP tests in-slice. |
+| `createMCPRequest` missing Express fields hooks read | Inventory hook usage in `api` tests and example-backend; extend stub only for fields executors already pass on HTTP. |
+| Double field-stripping | Single test: write-denied field absent from DB for both REST and MCP. |
+
+## Phases
+
+1. Map MCP create to `executeCreate`; MCP create tests green and share preCreate/permission behavior with REST.
+2. Map update and delete the same way.
+3. Delete duplicated MCP write bodies; keep transport mapping. Docs + changelog fragment.
+
+## Feature Flags & Migrations
+
+None. Internal call-graph change.
+
+## Not Included / Future Work
+
+- Executor calls `DatabaseAdapter` ([pluggable-database-sqlite.md](pluggable-database-sqlite.md)).
+- MCP list/read through a shared query executor.
+- `access.can()` as the permission engine ([can-as-permission-seam.md](can-as-permission-seam.md)).
+
+## Files to Create / Modify
+
+- `api/src/mcp/handlers.ts` — write handlers become adapters
+- `api/src/mcp/handlers.ts` tests / `api/src/mcp/integration.test.ts`
+- `api/src/sync/executors.ts` — only if a missing hook/request field is required for MCP parity; prefer not
+- Docs listed above
+- Changelog fragment for `@terreno/api`
+
+## Acceptance Criteria
+
+- [ ] MCP create/update/delete call `executeCreate` / `executeUpdate` / `executeDelete`.
+- [ ] MCP write handlers contain no `model.create` / `doc.save` / delete persistence.
+- [ ] A `preCreate` / `preUpdate` / `preDelete` hook runs for MCP the same as REST (existing hook tests or new shared cases).
+- [ ] Permission denial for MCP writes matches executor denial (status/title mapped into MCP error result).
+- [ ] `bun test` in `api` covering `mcp/` and `sync/executors` passes.
+- [ ] Docs in this slice match the shipped call graph.
+
+## Task List
+
+[docs/tasks/unified-mutation-executors.md](../tasks/unified-mutation-executors.md)

package/dist/docs/versioned/57.20.0/implementationPlans/upgrade-guides-and-skill.md

@@ -0,0 +1,167 @@
+# Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1013
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`oss-governance-baseline`](oss-governance-baseline.md) (changelog)
+**RTK deprecation flag:** **Blocked** — the largest upgrade Terreno will ever ask consumers to perform is RTK → syncdb. The skill and the notes must be built around it.
+
+## Goal
+
+Make upgrading Terreno a solved problem before we ask the public to depend on it. The machinery is half-built: `terreno_get_upgrade_guide` exists and concatenates per-release notes, and a `terreno_upgrade` prompt exists — but only two upgrade notes have ever been written (`0.20.0.md`, `0.21.0.md`) against a current version of 0.26.0. Five releases have no notes, so the tool returns nothing useful for any recent range. There is no `upgrading-terreno` skill; the only upgrade skill in the repo is `upgrading-expo`, which handles the Expo SDK portion and nothing Terreno-specific.
+
+An open-source framework that ships breaking changes in lockstep across eleven packages and cannot tell you what changed is not adoptable.
+
+## Non-Goals
+
+- Upgrading the Expo SDK (delegate to the existing `upgrading-expo` skill — do not duplicate its content).
+- Automated codemods (see [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) question M6 — agent-assisted, not codemod).
+- Changing the lockstep versioning scheme.
+- Retroactively rewriting git history or release notes.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| U1 | One consolidated **0.21 → 0.26** upgrade note; per-release notes from next version onward |
+| U2 | Upgrade note required when changelog has **Deprecated / Removed / Changed** (CI-enforced) |
+| U3 | Skill **performs** upgrade with confirmation gate + clean git tree |
+| U4 | **Direct multi-version jump** with sequential fallback on failure |
+| U5 | **Wrap `upgrading-expo`** at the correct point in the sequence |
+| U6 | Publish **deprecation window policy** (≥3 minors until 1.0; align RTK sunset with program P6) |
+
+## Architecture
+
+### Three artifacts
+
+1. **Upgrade notes** (`mcp-server/src/docs/upgrades/<version>.md`) — the data. Consumed by `terreno_get_upgrade_guide`, readable directly, and referenced from the changelog.
+2. **The `upgrading-terreno` skill** — the executor. Wraps note application, dependency bumps, Expo delegation, codegen, and verification.
+3. **A versioning and deprecation policy** (`docs/explanation/versioning-policy.md`) — the promise. What lockstep means, what a minor can break before 1.0, how long deprecations last.
+
+### Upgrade note format
+
+Standardize on the shape the existing notes already use, with required sections so the concatenated output from `terreno_get_upgrade_guide` reads coherently across several versions:
+
+```markdown
+# Upgrading to <version>
+
+**Action required:** Yes | No
+**Affected packages:** @terreno/api, @terreno/ui, ...
+
+## Summary
+## Breaking changes
+### <change title>
+**What changed** / **Why** / **Migration** (before/after code)
+## Deprecations
+## New capabilities
+## Verification
+```
+
+The `Verification` section matters most for automation: it gives the skill a concrete way to confirm each version's upgrade succeeded before moving to the next.
+
+### The upgrade ordering problem
+
+Order is the thing consumers get wrong, and it is not obvious:
+
+```mermaid
+flowchart TD
+  A["1. Clean git tree + branch"]
+  B["2. application_info:<br/>current @terreno/* versions"]
+  C["3. terreno_get_upgrade_guide<br/>current → target"]
+  D["4. Backend packages<br/>api, ai, admin-backend, feature-flags, api-health"]
+  E["5. Backend tests + compile"]
+  F["6. Expo SDK<br/>delegate to upgrading-expo"]
+  G["7. Frontend packages<br/>ui, syncdb, admin-frontend, admin-spa"]
+  H["8. Regenerate typed client"]
+  I["9. Compile + lint + tests"]
+  J["10. Run the app, verify UI"]
+  A --> B --> C --> D --> E --> F --> G --> H --> I --> J
+```
+
+Backend first because the OpenAPI spec is the contract the frontend generates from; regenerating the client against an un-upgraded backend produces a client for the wrong API. Expo before the Terreno frontend packages because `@terreno/ui` pins peer dependencies against Expo's versions.
+
+### Release-process enforcement
+
+The `release` skill currently does not require an upgrade note. Add:
+
+1. A required step: if the release's changelog section contains `Breaking`, `Deprecated`, `Removed`, or `Changed`, write `mcp-server/src/docs/upgrades/<version>.md` before tagging.
+2. A CI check in `repo-policies.yml` that fails a release tag when the note is missing.
+
+Without mechanical enforcement this decays again — that is exactly what happened between 0.21.0 and 0.26.0.
+
+## Models / APIs
+
+No new models. `terreno_get_upgrade_guide`'s behavior with a range containing no notes needs improving: it should say "no notes recorded for 0.22–0.24" rather than returning empty, so an agent does not conclude nothing changed.
+
+## Notifications
+
+An Announcements discussion post per breaking release, per [`public-roadmap-github`](public-roadmap-github.md) Task 5.3.
+
+## UI
+
+None.
+
+## Phases
+
+1. **Backfill** — the consolidated 0.21 → 0.26 note plus the note format and template.
+2. **Policy** — `docs/explanation/versioning-policy.md`.
+3. **Skill** — `upgrading-terreno` with the correct ordering and Expo delegation.
+4. **Enforcement** — release skill step and CI check; improve the tool's empty-range response.
+5. **Validation** — perform a real upgrade of a consumer app using only the skill.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- Codemods.
+- Automatic dependency-bump PRs (Dependabot covers third-party deps, not intra-Terreno lockstep bumps).
+- A compatibility matrix across Expo SDK versions (worth doing once there is more than one supported SDK).
+- Downgrade guidance.
+
+## Files to Create / Modify
+
+**Create**
+
+- `mcp-server/src/docs/upgrades/README.md` (format + template)
+- `mcp-server/src/docs/upgrades/0.26.0.md` (consolidated 0.21 → 0.26)
+- `mcp-server/src/docs/upgrades/<syncdb-version>.md` (owned by the migration IP; referenced here)
+- `docs/explanation/versioning-policy.md`
+- `docs/how-to/upgrade-terreno.md`
+- `.rulesync/skills/upgrading-terreno/SKILL.md`
+- `.rulesync/skills/upgrading-terreno/references/ordering.md`
+
+**Modify**
+
+- `mcp-server/src/tools.ts` (`terreno_get_upgrade_guide` empty-range response)
+- `mcp-server/src/prompts.ts` (`terreno_upgrade` prompt points at the skill)
+- `.rulesync/skills/release/SKILL.md`
+- `.github/workflows/repo-policies.yml`
+- `CHANGELOG.md` (link notes per version)
+- `docs/how-to/README.md`, `docs/explanation/README.md`
+
+## Task List
+
+See [`docs/tasks/upgrade-guides-and-skill.md`](../tasks/upgrade-guides-and-skill.md).
+
+## Acceptance Criteria
+
+- [ ] `mcp-server/src/docs/upgrades/README.md` defines the required note format with a template.
+- [ ] A consolidated note covers everything a consumer must know to move from 0.21.0 to 0.26.0, derived from real release notes and diffs.
+- [ ] `terreno_get_upgrade_guide` for the range 0.21.0 → current returns useful content, and for a range with no recorded notes returns an explicit "no notes recorded" message rather than empty output.
+- [ ] `docs/explanation/versioning-policy.md` states what lockstep versioning means, the pre-1.0 breaking-change policy, and the minimum deprecation window.
+- [ ] The `upgrading-terreno` skill exists with all mirrors committed and enforces a clean git tree before starting.
+- [ ] The skill follows the documented ordering, delegates the Expo SDK portion to `upgrading-expo`, and regenerates the typed client only after the backend is upgraded.
+- [ ] The skill runs compile, lint, and tests between phases and stops on first failure with the failing step named.
+- [ ] On a multi-version jump failure, the skill retries version by version to isolate the breaking version.
+- [ ] The release skill requires an upgrade note when the changelog section contains a breaking, deprecated, removed, or changed entry.
+- [ ] A CI check fails a release tag whose upgrade note is missing when required.
+- [ ] An upgrade of a real consumer app across at least two minor versions succeeds using only the skill, and the transcript is captured.
+- [ ] `bun run mcp:build`, `bun run lint`, and `bun run rules:check` pass.

package/dist/docs/versioned/57.20.0/implementationPlans/web-ssr-and-admin-spa.md

@@ -0,0 +1,154 @@
+# Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
+
+**Status:** Approved
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1017
+**Priority:** Medium
+**Effort:** Epic
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md) (Wave 2)
+**Depends on:** Expo SDK ≥ 55 (PR [#779](https://github.com/TerrenoLabs/terreno/pull/779) upgrades to SDK 56), [`deployment-foundation`](deployment-foundation.md)
+**RTK deprecation flag:** **Partial** — SSR interacts directly with the data layer. Server-rendered HTML needs data at render time, which is a fundamentally different question for a local-first client than for a request/response client. The data-loading design tasks are `[RTK]` marked and blocked on #869.
+
+## Goal
+
+Give Terreno's web target real server rendering, so a Terreno app can be indexed, shared with usable link previews, and load meaningful first paint without waiting for a JavaScript bundle. Then evaluate moving `@terreno/admin-spa` onto the same mechanism, since it is already served from Express and is the lowest-risk consumer.
+
+The Django/Rails positioning makes this gap conspicuous: both frameworks server-render by default. Today Terreno's web output is `single` — a client-only SPA with one `index.html`, no per-route HTML, and no server rendering. For a framework claiming Django/Rails parity plus universal apps, "your web app is not indexable" is a real objection.
+
+## Non-Goals
+
+- Server-rendering native. SSR is web-only by definition.
+- Replacing `@terreno/api` with Expo Router API routes. The backend stays the backend.
+- React Server Components.
+- Making SSR mandatory. It must be opt-in per app.
+- Upgrading the Expo SDK (PR #779 owns that; this IP depends on it).
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| S1 | **`static` first, `server` later** (SSR alpha in Expo SDK 55+) |
+| S2 | **`expo-server/adapter/express`** in `@terreno/api` as Terreno-native path; document per-provider adapters |
+| S3 | **Shell-only SSR v1** — hydrate on client |
+| S4 | **`admin-spa` moves to `static` output only** |
+| S5 | **`static` becomes default eventually** (after component audit); `server` opt-in |
+| S6 | **Expo Router API routes narrowly** for OG images / webhooks only |
+
+## Architecture
+
+### Where SSR fits
+
+```mermaid
+flowchart TD
+  U["Browser request"]
+  E["Express app (@terreno/api)"]
+  SSR["expo-server/adapter/express<br/>renders dist/server"]
+  C["dist/client<br/>static assets"]
+  API["modelRouter + auth routes"]
+  ADM["AdminSpaServeApp"]
+  U --> E
+  E -->|"/api/*, /auth/*"| API
+  E -->|"/admin/*"| ADM
+  E -->|"static assets"| C
+  E -->|"everything else"| SSR
+  SSR -->|"HTML"| U
+```
+
+One Express process serves the API, the static client bundle, and server-rendered HTML. Route precedence matters: API and auth routes must match before the SSR catch-all, and the admin mount must not be shadowed.
+
+### Risks specific to React Native Web SSR
+
+This is where the work actually is, and where the estimate could be badly wrong:
+
+| Risk | Detail | Mitigation |
+|------|--------|------------|
+| Components that touch browser APIs at module scope | `@terreno/ui` has ~100 components; any that read `window`, `localStorage`, or `Dimensions` during render or module init will throw during server rendering | Audit and fix; the repo already has SSR-safety precedent (`typeof window` checks in the client storage layer) |
+| Fonts and styles | Nunito/Titillium Web loading and `react-native-web` style injection must produce correct first paint without a flash of unstyled content | Verify style extraction; may need explicit critical-CSS handling |
+| Theme and provider hydration | `TerrenoProvider` computes a theme; server and client must agree or React logs hydration mismatches | Ensure deterministic theme resolution; no `Date.now()` or random values in the render path |
+| Auth-dependent rendering | The server does not know who the user is without reading a session; rendering a logged-in shell then hydrating to logged-out causes visible flicker | v1: always render the unauthenticated shell (S3 option A) |
+| Native-only dependencies | Packages that import native modules at the top level break the server bundle | Audit; use platform-specific extensions |
+| Local-first client on the server | The syncdb client assumes IndexedDB and Web Crypto, neither of which exists on the server | The client must not initialize during server render; needs an explicit guard verified after #869 |
+
+The last row is the one that could invalidate the plan, and it cannot be assessed until #869 merges. **Phase 0 exists to answer it before committing to the rest.**
+
+### `admin-spa` as the proving ground
+
+`@terreno/admin-spa` is an Expo Router web app already served from Express via `AdminSpaServeApp`. Moving it to `static` output is a contained experiment: no SEO requirement, one known consumer (`example-backend`), an existing integration test workflow (`admin-spa-integration.yml`), and an authenticated surface where the auth-flicker problem is bounded. If `static` output works there, the pattern generalizes.
+
+## Models / APIs
+
+No new models. `AdminSpaServeApp` gains options for the output mode and the server bundle path. Route precedence in `TerrenoApp`/`setupServer` may need an explicit ordering guarantee so the SSR catch-all cannot shadow API routes.
+
+## Notifications
+
+None.
+
+## UI
+
+No new components. Existing `@terreno/ui` components may need SSR-safety fixes — those are bug fixes, not features, and each needs a test that renders the component in a server-like environment without `window`.
+
+## Phases
+
+0. **Feasibility spike** — after SDK ≥ 55 and #869, attempt `static` output on `example-frontend` and record every failure. Decide go/no-go and correct this plan. **Do not proceed without this.**
+1. **SSR-safety audit and fixes** — make `@terreno/ui` render without browser globals; add a server-render test harness.
+2. **`static` output for `admin-spa`** — prove the pattern on the contained consumer.
+3. **`static` output for `example-frontend`** — the reference implementation plus documentation.
+4. **`server` output with the Express adapter** — SSR through `@terreno/api`, route precedence, deployment implications.
+5. **Data loading design** — a separate design pass on `useLoaderData` versus local-first reconciliation. May become its own IP.
+6. **Documentation and defaults** — how-to, explainer, and the decision on whether `static` becomes the default.
+
+## Feature Flags & Migrations
+
+- Output mode is per-app configuration in the Expo app config, not a runtime flag.
+- `AdminSpaServeApp` must keep serving existing `single`-output builds so consumers upgrading Terreno without changing their admin build are unaffected.
+- Changing the recommended default (S5) is a breaking change for consumers who copied the bootstrap config; it needs an upgrade note.
+
+## Not Included / Future Work
+
+- React Server Components.
+- Streaming SSR.
+- Incremental static regeneration.
+- Server-rendering authenticated, personalized content (depends on Phase 5).
+- Edge-runtime adapters (`workerd`, Netlify Edge) — the adapters exist upstream; document them once the Express path is proven.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/how-to/enable-web-ssr.md`
+- `docs/explanation/web-rendering-modes.md`
+- `ui/src/__tests__/serverRender.test.tsx` (server-render harness)
+- `admin-spa/app.config.ts` changes plus a server entry if `server` output is adopted
+
+**Modify**
+
+- `example-frontend/app.json` (output mode)
+- `admin-spa/app.json` / `app.config.ts`
+- `admin-spa/src/**` (SSR-unsafe code)
+- `ui/src/**` (SSR-safety fixes)
+- `api/src/adminSpaServeApp.ts` (or wherever `AdminSpaServeApp` lives — confirm the path) for output-mode support
+- `api/src/expressServer.ts` / `terrenoApp.ts` (route precedence)
+- `docs/explanation/deployment-baseline.md` (update the output-mode table)
+- `.github/workflows/admin-spa-integration.yml`
+
+## Task List
+
+See [`docs/tasks/web-ssr-and-admin-spa.md`](../tasks/web-ssr-and-admin-spa.md).
+
+## Acceptance Criteria
+
+- [ ] The Phase 0 spike produced a written feasibility report listing every failure encountered with `static` output, and an explicit go/no-go with this plan corrected accordingly.
+- [ ] Every `@terreno/ui` component renders in a server-like environment without `window`, `document`, or `localStorage`, verified by an automated test.
+- [ ] `admin-spa` builds and serves correctly with `static` output through `AdminSpaServeApp`, and `admin-spa-integration.yml` passes.
+- [ ] `AdminSpaServeApp` still serves an existing `single`-output build unchanged.
+- [ ] `example-frontend` builds with `static` output, produces per-route HTML, and every route returns HTML containing meaningful content (verified by fetching a route with JavaScript disabled).
+- [ ] No React hydration mismatch warnings in the console on any `example-frontend` route.
+- [ ] If Phase 4 proceeds: `server` output renders through the Express adapter inside `@terreno/api`, API and auth routes take precedence over the SSR catch-all (verified by tests), and the admin mount is not shadowed.
+- [ ] The syncdb client does not attempt to initialize during server render, verified by a test.
+- [ ] `docs/explanation/web-rendering-modes.md` explains all modes with honest tradeoffs and states which Terreno supports.
+- [ ] `docs/how-to/enable-web-ssr.md` takes a reader from `single` to their chosen mode, including the deployment change required.
+- [ ] Deployment guides for both Vercel and GCP are updated for whichever modes ship.
+- [ ] `bun run lint`, `bun run compile`, `bun run ui:test`, and `bun run admin-spa:test` all pass.