@terreno/mcp 0.28.0 → 0.30.0

package/dist/docs/versioned/0.28.0/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -0,0 +1,169 @@
+# Implementation Plan: RTK Deprecation and SyncDB Migration Docs
+
+**Status:** Draft — blocked on PR #869
+**Priority:** Critical (gates most of Wave 1)
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** PR [#869](https://github.com/flourishhealth/terreno/pull/869) merging
+**RTK deprecation flag:** **Blocked** — this IP *is* the RTK deprecation. Nothing here can be written until #869 lands, because the public surface of `@terreno/syncdb` is not final until then.
+
+## Goal
+
+Make **Better Auth + `@terreno/syncdb`** the documented, blessed frontend platform, and give every existing `@terreno/rtk` consumer a correct, tested migration path. This is the gating IP for the launch documentation: publishing tutorials, reference docs, or a positioning rewrite against RTK Query would guarantee an immediate rewrite.
+
+Scope is documentation, deprecation signalling, and migration tooling — not syncdb feature work (that is PR #869's own scope).
+
+## Non-Goals
+
+- Implementing or changing `@terreno/syncdb` behavior.
+- Migrating internal Flourish applications (tracked separately).
+- Removing `@terreno/rtk` from the repo or unpublishing it.
+- Rewriting the tutorials themselves — that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), which depends on this IP.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (see program [P6–P7](oss-launch-program.md#blocking-questions-program-level)).
+
+| # | Question | Decision |
+|---|----------|----------|
+| M1 | RTK support window (→ P6) | **Keep publishing with deprecation notice through the current major line; stop publishing `@terreno/rtk` in the next major** |
+| M2 | `npm deprecate` marker | **B** — mark at end of support window |
+| M3 | Auth vs data migration | **C** — Better Auth first, then syncdb |
+| M4 | `docs/reference/rtk.md` (→ P7 **A**) | **Remove from the public reference index** — no legacy reference page. Existing RTK consumers use **`docs/how-to/migrate-rtk-to-syncdb.md`** only; do not maintain a parallel RTK reference path in launch docs |
+| M5 | SDK codegen command | **A** — `bun run sdk` keeps working |
+| M6 | Codemod | **B** — agent-assisted via `upgrading-terreno` skill |
+| M7 | Local-first default | **A** if #869 ships local-first only (verify against merged code) |
+
+## Architecture
+
+### Documentation surface map
+
+Every document below currently describes an RTK-shaped world and must be reconciled.
+
+| Document | Current state | Target state |
+|----------|---------------|--------------|
+| `docs/reference/rtk.md` | Primary frontend reference | **Removed from launch reference** (P7 A). Redirect to migration guide; archive pre-launch content if needed for inbound links |
+| `docs/reference/syncdb.md` | does not exist | New primary frontend data reference |
+| `docs/how-to/migrate-rtk-to-syncdb.md` | does not exist | New step-by-step migration guide |
+| `docs/explanation/local-first-data.md` | does not exist | New conceptual explainer: why local-first, what changes for the developer |
+| `docs/explanation/authentication.md` | JWT-primary | Better Auth primary, JWT documented as legacy |
+| `docs/how-to/configure-better-auth.md` | Exists, positioned as optional | Repositioned as the default auth path |
+| `docs/README.md` | Package table omits `ai`, `syncdb` | Complete package table with syncdb as the frontend data package |
+| `.rulesync/skills/generate-sdk/SKILL.md` | RTK Query codegen | syncdb descriptor codegen; RTK path kept as a legacy branch during the support window |
+| `.rulesync/rules/rtk/*` | RTK conventions for agents | New `syncdb` rules; RTK rules marked legacy |
+| `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md` | "Always use generated SDK hooks" (RTK) | syncdb hooks; RTK guidance moved to a legacy note |
+| `README.md` architecture diagram | `@terreno/rtk` box | `@terreno/syncdb` box |
+| `mcp-server` resources + bootstrap templates | RTK store wiring | syncdb client wiring |
+
+### The migration guide's shape
+
+The migration guide is the highest-value artifact. It must be organized by *what the developer has to change*, not by package internals:
+
+1. **Before you start** — decision table: adopt Better Auth first (M3), confirm backend version, confirm Mongo is a replica set.
+2. **Install and configure** — add `@terreno/syncdb`, create the client, wrap the app, remove the Redux store or keep it side-by-side.
+3. **Reads** — `useGetTodosQuery` → syncdb query hook. Show the same screen before and after, side by side.
+4. **Writes** — `usePostTodosMutation` → syncdb mutation. This is where behavior genuinely changes: writes land locally first, so loading states, error handling, and optimistic-update code all get simpler or get deleted. Show what to delete.
+5. **Conflicts** — new concept with no RTK equivalent. What a conflict is, when it happens, the two v1 strategies, and the minimum UI a consumer must add.
+6. **Sync status** — replacing spinner-driven UX with sync-state UX.
+7. **Auth** — JWT auth slice → Better Auth session, including token storage differences and the socket auth handshake.
+8. **Codegen** — regenerating typed operations, and what changes in the generated file.
+9. **Feature flags** — the OpenFeature provider's new data source.
+10. **Rollback** — how to go back if it goes wrong, per-screen via the `USE_SYNCDB` flag.
+11. **Checklist** — a copy-pasteable checklist for a real migration.
+
+Each step needs a working before/after code pair taken from the actual `example-frontend` migration in #869, not invented.
+
+### Deprecation signalling
+
+| Channel | Action |
+|---------|--------|
+| `docs/reference/legacy/rtk.md` | Legacy banner with the support window and end date/version |
+| `rtk/README.md` | Deprecation notice at the top linking the migration guide |
+| Root `CHANGELOG.md` | `Deprecated` entry in the release that lands #869 |
+| GitHub Discussions | Announcement post (see [`public-roadmap-github`](public-roadmap-github.md)) |
+| `mcp-server/src/docs/upgrades/<version>.md` | Upgrade note so `terreno_get_upgrade_guide` returns it |
+| `ROADMAP.md` | An item with `Impact = Breaking` and the removal target |
+| Agent rules | `.rulesync/rules/rtk/` marked legacy so agents stop generating RTK code |
+
+Agent rules matter most in practice: if the MCP server and bootstrap templates keep emitting RTK code, every AI-generated Terreno app starts on the deprecated path.
+
+## Models
+
+None.
+
+## APIs
+
+None new. This IP documents the surface #869 introduces; it must not add to it.
+
+## Notifications
+
+One Announcements discussion post at the start of the deprecation window. No in-app notifications.
+
+## UI
+
+None directly. The migration guide specifies the minimum conflict-resolution and sync-status UI a consumer must build; if `example-frontend` lacks a good reference implementation after #869, file a follow-up rather than inventing one here.
+
+## Phases
+
+1. **Reconcile with merged #869** — read the merged code, produce a verified inventory of the actual public API, and correct the surface map above. Nothing else starts until this is done.
+2. **Reference docs** — `docs/reference/syncdb.md`, move and banner `rtk.md`, update `docs/README.md`.
+3. **Migration guide** — the eleven-step guide with verified before/after pairs.
+4. **Explainers and auth repositioning** — `local-first-data.md`, rewrite `authentication.md`, reposition Better Auth.
+5. **Agent surfaces** — rules, skills, `AGENTS.md`/`CLAUDE*.md`, MCP resources and bootstrap templates.
+6. **Deprecation signalling** — READMEs, changelog, upgrade note, announcement draft, roadmap item.
+
+## Feature Flags & Migrations
+
+- `USE_SYNCDB` (introduced by #869) is the consumer-side rollout flag; the migration guide is organized around enabling it per screen.
+- No repo-side flag needed for documentation.
+- Docusaurus redirects required for every moved page (`docs/reference/rtk.md` → `docs/reference/legacy/rtk.md`).
+
+## Not Included / Future Work
+
+- Removing `@terreno/rtk` from the monorepo (end of support window, separate IP).
+- Native (iOS/Android) local storage encryption, which #869 explicitly defers.
+- Migrating Flourish's internal apps.
+- A `syncdb` performance/tuning guide.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/reference/syncdb.md`
+- `docs/reference/legacy/rtk.md` (moved)
+- `docs/how-to/migrate-rtk-to-syncdb.md`
+- `docs/explanation/local-first-data.md`
+- `mcp-server/src/docs/upgrades/<syncdb-release-version>.md`
+- `.rulesync/rules/syncdb/00-syncdb.md`
+
+**Modify**
+
+- `docs/reference/README.md`, `docs/README.md`, `docs/how-to/README.md`
+- `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
+- `README.md` (architecture diagram and package list)
+- `rtk/README.md`, `syncdb/README.md`
+- `.rulesync/rules/rtk/00-rtk.md` (legacy banner), `.rulesync/skills/generate-sdk/SKILL.md`
+- `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`
+- `mcp-server/src/docs/resources/*.md`, `mcp-server/src/docs/templates/bootstrap/**`
+- `CHANGELOG.md`
+- `website/docusaurus.config.ts` (redirects)
+
+## Task List
+
+See [`docs/tasks/rtk-to-syncdb-migration-docs.md`](../tasks/rtk-to-syncdb-migration-docs.md).
+
+## Acceptance Criteria
+
+- [ ] A verified inventory of `@terreno/syncdb`'s public exports exists and every documented API appears in the merged package's `src/index.ts`.
+- [ ] `docs/reference/syncdb.md` documents every exported hook, client method, and config option, with a runnable example for each.
+- [ ] `docs/how-to/migrate-rtk-to-syncdb.md` covers all eleven steps, and every before/after pair compiles against the merged code.
+- [ ] Following the guide, a fresh clone of `example-frontend` can be moved from the RTK path to the syncdb path with no undocumented steps.
+- [ ] `docs/reference/rtk.md` no longer exists at its old path; the Legacy page states the support window; a Docusaurus redirect resolves the old URL.
+- [ ] `docs/explanation/authentication.md` presents Better Auth first and JWT as legacy.
+- [ ] No agent-facing surface (`AGENTS.md`, `CLAUDE*.md`, `.rulesync/rules/`, MCP resources, bootstrap templates) instructs an agent to write RTK Query code for a new app.
+- [ ] `terreno_bootstrap_app` output uses syncdb, and a bootstrapped app runs.
+- [ ] `terreno_get_upgrade_guide` returns the syncdb upgrade note for the release range that includes #869.
+- [ ] `CHANGELOG.md` has a `Deprecated` entry naming `@terreno/rtk`, the support window, and the migration guide link.
+- [ ] `bun run lint`, `bun run compile`, `bun run rules:check`, and `bun run website:build` all pass.

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

@@ -0,0 +1,166 @@
+# Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
+
+**Status:** Draft — blocked on PR #869
+**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/0.28.0/implementationPlans/web-ssr-and-admin-spa.md

@@ -0,0 +1,153 @@
+# Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
+
+**Status:** Draft — blocking questions open
+**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/flourishhealth/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.

package/dist/docs/versioned/0.28.0/reference/components/custom-select-field.mdx

@@ -0,0 +1,37 @@
+---
+title: "Custom Select Field"
+description: "Displays a list of options using the browser’s native select and includes a custom option that renders a text field when selected and allows user to input value not included in predefined options."
+sidebar_label: "Custom Select Field"
+slug: /reference/components/custom-select-field
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# Custom Select Field
+
+Displays a list of options using the browser’s native select and includes a custom option that renders a text field when selected and allows user to input value not included in predefined options.
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `CustomSelectFieldProps`  
+**Story source:** [`demo/stories/CustomSelectField.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/CustomSelectField.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="Custom Select Field" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `onChange` | `reflection` | Yes | The function to call when the custom select field value changes. |
+| `options` | `array` | Yes | The options available for selection in the select field. Each option should have a label and a value. |
+| `value` | `union` | Yes | The current value of the custom select field. |
+| `disabled` | `boolean` |  | If true, the select field will be disabled. |
+| `disableSearch` | `boolean` |  | When true, hides the type-to-filter search UI. Search is enabled by default. |
+| `errorText` | `string` |  | The error text to display if there is an error. |
+| `helperText` | `string` |  | The helper text to display below the select field. |
+| `placeholder` | `string` |  | The placeholder text to display when no option is selected. |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `testIDs` | `FieldTestIDs` |  |  |
+| `title` | `string` |  | The title of the custom select field. |

package/dist/docs/versioned/0.28.0/reference/components/iconbutton.mdx

@@ -0,0 +1,44 @@
+---
+title: "IconButton"
+description: "Icon buttons allow users to take actions and make choices with a single tap."
+sidebar_label: "IconButton"
+slug: /reference/components/iconbutton
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# IconButton
+
+Icon buttons allow users to take actions and make choices with a single tap.
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `IconButtonProps`  
+**Story source:** [`demo/stories/IconButton.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/IconButton.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="IconButton" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `accessibilityLabel` | `string` | Yes | The accessibility label attribute identifies the user interface element. It should be a very brief description of the element, such as "Add", "Play", "Deleted", etc. |
+| `iconName` | `IconName` | Yes | The name of the icon to display in the button. |
+| `onClick` | `reflection` | Yes | The function to call when the button is clicked. |
+| `accessibilityHint` | `string` |  | The accessibility hint describes the results of performing an action on a control or view. It should be a very brief description of the result of interacting with the button. |
+| `confirmationHeading` | `string` |  | The heading of the confirmation modal. |
+| `confirmationText` | `string` |  | The text content of the confirmation modal. |
+| `disabled` | `boolean` |  | If true, the button will be disabled. |
+| `indicator` | `union` |  | Show a small indicator icon in the lower right corner of the button. |
+| `indicatorText` | `union` |  | The text or number to display in the indicator. If not provided, the indicator will be a solid circle. |
+| `loading` | `boolean` |  | If true, a loading spinner will be shown in the button. |
+| `size` | `union` |  | The size of the button. |
+| `state` | `union` |  | Controls the button's interaction state. Use Default for standard button appearance and Active to indicate a selected or currently engaged state. |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `tooltipIdealPosition` | `TooltipPosition` |  | The ideal position of the tooltip. |
+| `tooltipIncludeArrow` | `boolean` |  | Include an arrow in the tooltip. Pointing to the button. |
+| `tooltipText` | `string` |  | The text content of the tooltip. |
+| `variant` | `union` |  | The variant of the button, which determines its style. |
+| `withConfirmation` | `boolean` |  | If true, a confirmation modal will be shown before the onClick action. |