@terreno/mcp 57.1.0 → 57.2.0

package/src/docs/versioned/57.1.0/implementationPlans/upgrade-banner.md

@@ -0,0 +1,279 @@
+# Implementation Plan: Upgrade Banner
+
+**Status:** Complete
+**Closed:** 2026-08-20 — Shipped via `VersionConfig` model, `VersionCheckPlugin` (`GET /version-check`), `AdminVersionConfig`, `useUpgradeCheck` (`@terreno/rtk`), and `UpgradeRequiredScreen` (`@terreno/ui`).
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1079
+
+*When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
+
+## Models
+
+### VersionConfig (new, singleton)
+
+```typescript
+// api/src/models/versionConfig.ts
+
+import {createdUpdatedPlugin} from "../plugins";
+import mongoose from "mongoose";
+
+const versionConfigSchema = new mongoose.Schema<VersionConfigDocument>(
+  {
+    webWarningVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which web users see a warning toast",
+    },
+    webRequiredVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which web users are blocked from using the app",
+    },
+    mobileWarningVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which mobile users see a warning toast",
+    },
+    mobileRequiredVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which mobile users are blocked from using the app",
+    },
+    warningMessage: {
+      type: String,
+      default: "A new version is available. Please update for the best experience.",
+      description: "Message shown in the warning toast",
+    },
+    requiredMessage: {
+      type: String,
+      default: "This version is no longer supported. Please update to continue.",
+      description: "Message shown on the blocking screen",
+    },
+    updateUrl: {
+      type: String,
+      description: "App store or download URL for mobile updates (optional, falls back to expo-updates)",
+    },
+  },
+  { strict: "throw", toJSON: { virtuals: true }, toObject: { virtuals: true } }
+);
+
+versionConfigSchema.plugin(createdUpdatedPlugin);
+```
+
+**Key design points:**
+- Singleton — only one document in the collection
+- All version fields default to `0` (meaning "no constraint"), so the check returns "ok" until an admin configures thresholds
+- Per-platform version thresholds (web vs mobile), shared messages
+- `updateUrl` is optional — mobile falls back to expo-updates OTA
+
+## APIs
+
+### 1. Version Check (public, built-in)
+
+| | |
+|---|---|
+| Method | `GET /version-check` |
+| Auth | None (public) |
+| Query Params | `version` (integer build number), `platform` ("web" \| "mobile") |
+| Response | `{status: "ok" \| "warning" \| "required", message?: string, updateUrl?: string}` |
+| Notes | Requires explicit registration via `VersionCheckPlugin` (e.g., `app.register(new VersionCheckPlugin())`). Returns `{status: "ok"}` if no VersionConfig document exists. |
+
+**Logic:**
+```
+if platform version < requiredVersion → status: "required", message: requiredMessage, updateUrl
+else if platform version < warningVersion → status: "warning", message: warningMessage, updateUrl
+else → status: "ok"
+```
+
+### 2. Admin: Get Version Config
+
+| | |
+|---|---|
+| Method | `GET /admin/version-config` |
+| Auth | `Permissions.IsAdmin` |
+| Response | The singleton VersionConfig document (or defaults if none exists) |
+
+### 3. Admin: Update Version Config
+
+| | |
+|---|---|
+| Method | `PUT /admin/version-config` |
+| Auth | `Permissions.IsAdmin` |
+| Body | All VersionConfig fields |
+| Response | Updated VersionConfig document |
+| Notes | Upsert — creates if doesn't exist, updates if it does. |
+
+Custom routes (not modelRouter) since it's a singleton — no list, no delete, no `:id` params.
+
+## Notifications
+
+No notifications required for this feature. The upgrade system is passive — it checks on app mount and shows in-app UI only.
+
+## UI
+
+### Component 1: `UpgradeRequiredScreen` (new, `@terreno/ui`)
+
+- Full-screen page with centered content
+- Warning icon, the `requiredMessage` text, and an "Update" button
+- Update button behavior controlled by `onUpdate` callback prop:
+  - **Web:** calls `window.location.reload()`
+  - **Mobile:** attempts `expo-updates` OTA → falls back to opening `updateUrl` via `Linking`
+- No back button, no navigation, no dismiss — user is stuck here
+- Props: `message: string`, `onUpdate: () => void`
+
+### Component 2: `useUpgradeCheck` hook (new, `@terreno/rtk`)
+
+- Called in consuming app's root layout
+- On mount: `GET /version-check?version={buildNumber}&platform={web|mobile}`
+- If `"warning"`: shows persistent toast with message + "Update" action button
+- If `"required"`: returns a flag for the consuming app to render `UpgradeRequiredScreen`
+- Returns: `{isRequired: boolean, requiredMessage?: string, onUpdate: () => void}`
+- Skips check if build number is missing/unknown (dev environment)
+- `onUpdate` handles platform logic: web refresh, mobile expo-updates or Linking to updateUrl
+
+### Component 3: Admin Version Config Screen (new, `@terreno/admin-frontend`)
+
+- Form with fields: webWarningVersion, webRequiredVersion, mobileWarningVersion, mobileRequiredVersion, warningMessage, requiredMessage, updateUrl
+- Single "Save" button that PUTs the singleton
+- Accessible from the admin model list as a special entry
+
+### Navigation Flow
+
+```
+App mounts → useUpgradeCheck() fires
+  → "ok"       → normal app
+  → "warning"  → normal app + persistent toast with "Update" button + dismiss X
+  → "required" → UpgradeRequiredScreen (blocks everything)
+```
+
+## Phases
+
+### Phase 1: Backend + Admin
+
+- VersionConfig Mongoose model in `@terreno/api`
+- `GET /version-check` public endpoint via `VersionCheckPlugin`
+- `GET/PUT /admin/version-config` admin routes
+- Admin frontend screen for version config
+- Unit tests for the version check logic
+- Example backend wired up
+
+**Deliverable:** Admin can configure version thresholds and the public endpoint responds correctly.
+
+### Phase 2: Client + CI
+
+- `UpgradeRequiredScreen` component in `@terreno/ui`
+- `useUpgradeCheck` hook in `@terreno/rtk`
+- `app.config.ts` helper for build number injection via `expo.extra.buildNumber`
+- Example frontend wired up with the hook
+- GitHub Actions snippet for `git rev-list --count HEAD`
+
+**Deliverable:** Client apps can check version on mount and show warning toast or blocking screen.
+
+## Feature Flags & Migrations
+
+- **No feature flag needed.** The system is inert by default — the endpoint returns `"ok"` until an admin creates a VersionConfig document with non-zero thresholds.
+- **No data migration needed.** New model, new collection, starts empty.
+- **Rollout:** Ship it. Apps that don't call `useUpgradeCheck()` are unaffected.
+
+## Activity Log & User Updates
+
+No activity logging needed for this feature. Version config changes are admin-only and low-frequency.
+
+## Not Included / Future Work
+
+- Per-user or per-role version targeting
+- Gradual rollout / percentage-based enforcement
+- Push notifications for version updates
+- Automatic semver bumping (stays manual via git tags)
+- Periodic polling (only checks on mount for now)
+- Per-app configs for multi-frontend backends
+- Version check middleware on every API response
+- Analytics on how many users are on which versions
+
+
+# Research: Terreno Upgrade Banner System
+
+## Summary
+
+The Terreno codebase already sends `App-Version` and `App-Platform` headers with every API request via RTK's base query. Building an upgrade banner system requires: (1) a backend model + built-in endpoint for version config, (2) admin screens to manage it, (3) a client hook + prebuilt UI, and (4) CI automation for commit-count-based versioning. The existing `AdminApp` plugin pattern, `Banner` component, toast system, and `Page` component provide strong foundations to build on.
+
+## Context
+
+- **Problem:** No mechanism to notify users their app is outdated. Stale clients can hit deprecated APIs or miss critical fixes.
+- **Current state:** RTK already sends `App-Version` (from `Constants.expoConfig?.version`) and `App-Platform` ("web"/"mobile") on every request (`rtk/src/emptyApi.ts:164-177`). But nothing consumes these headers or enforces version constraints.
+- **Goal:** Two-tier system — soft warning (dismissible toast/banner) and hard block (full-screen, no dismiss). Admin-configurable. Auto-versioned via CI.
+
+## Decisions
+
+- **Per-platform config:** Yes — separate thresholds for web vs mobile since web can force-refresh but mobile needs app store update.
+- **Update mechanism:** Platform-specific — web forces page refresh, mobile triggers expo-updates OTA if available, falls back to app store link.
+- **Endpoint location:** `VersionCheckPlugin` registered with `TerrenoApp` — opt-in per app.
+- **Config storage:** Mongoose model (database-backed) so admins can change without redeploy.
+
+## Findings
+
+### Finding 1: Existing Version Infrastructure in RTK
+
+`rtk/src/emptyApi.ts:164-177` — Every API request already includes:
+```typescript
+const version = Constants.expoConfig?.version ?? "Unknown";
+headers.set("App-Version", version);
+headers.set("App-Platform", IsWeb ? "web" : "mobile");
+```
+
+The version comes from `expo-constants` → `app.json`'s `version` field. Currently `example-frontend/app.json` has `"version": "1.0.0"`.
+
+### Finding 2: Admin Backend Plugin Pattern
+
+`admin-backend/src/adminApp.ts` — The `AdminApp` class provides the pattern:
+- Constructor takes config, `register(app)` adds routes to Express
+- Uses `modelRouter` with `Permissions.IsAdmin` for all CRUD
+- Exposes a `/admin/config` metadata endpoint
+
+### Finding 3: Admin Frontend Patterns
+
+`admin-frontend/` uses a data-driven approach:
+- `useAdminConfig(api, baseUrl)` fetches model metadata
+- `useAdminApi(api, routePath, modelName)` generates CRUD hooks dynamically
+- All screens accept `baseUrl` and `api` props
+- For upgrade config, we need a custom admin screen (singleton config, not a collection)
+
+### Finding 4: UI Components Available
+
+**Banner** (`ui/src/Banner.tsx`) — status variants, persistent dismiss, action button
+**Toast** (`ui/src/Toast.tsx`) — `useToast()` with warn/info/error variants, persistent mode
+**Page** (`ui/src/Page.tsx`) — Full-screen layout for the blocking screen
+**Modal** (`ui/src/Modal.tsx`) — Dialog, but Page is better for hard block (zero escape)
+
+### Finding 5: GitHub Actions & Versioning
+
+Current flow: manual git tag → `publish-on-tag.yml` → selective npm publish.
+No existing build number system. `app.json` version is static.
+`git rev-list --count HEAD` provides simple, monotonically increasing build numbers.
+
+### Finding 6: RTK Store Integration
+
+`example-frontend/store/index.ts` — store combines auth, appState, API reducers.
+`_layout.tsx` checks auth state and routes conditionally — upgrade check follows same pattern.
+
+## Recommendation
+
+**Add to core packages** — spread across:
+- `@terreno/api` — VersionConfig model + public `GET /version-check` endpoint (via `VersionCheckPlugin`)
+- `@terreno/admin-frontend` — Custom admin screen for version config
+- `@terreno/rtk` — `useUpgradeCheck` hook
+- `@terreno/ui` — `UpgradeRequiredScreen` blocking component
+
+**Versioning:** `git rev-list --count HEAD` as integer build number. Helper in CI to set `expo.version` at build time.
+
+**API:** `GET /version-check?version=123&platform=web` — public, no auth. Returns `{status: "ok" | "warning" | "required", message?, updateUrl?}`.
+
+## References
+
+- `rtk/src/emptyApi.ts:164-177` — Existing App-Version header
+- `admin-backend/src/adminApp.ts` — Plugin registration pattern
+- `admin-frontend/src/useAdminApi.tsx` — Dynamic RTK hook generation
+- `ui/src/Banner.tsx` — Banner component
+- `ui/src/Toast.tsx` — Toast notification system
+- `ui/src/Page.tsx` — Full-screen page layout
+- `example-frontend/app/_layout.tsx` — Root layout with auth routing
+- `.github/workflows/publish-on-tag.yml` — Current CI/CD versioning

package/src/docs/versioned/57.1.0/implementationPlans/upgrade-guides-and-skill.md

@@ -0,0 +1,167 @@
+# Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
+
+**Status:** Draft — blocked on PR #869
+**Roadmap issue:** https://github.com/FlourishHealth/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/src/docs/versioned/57.1.0/implementationPlans/web-ssr-and-admin-spa.md

@@ -0,0 +1,154 @@
+# Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
+
+**Status:** Draft — blocking questions open
+**Roadmap issue:** https://github.com/FlourishHealth/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/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/src/docs/versioned/57.1.0/reference/README.md

@@ -0,0 +1,33 @@
+# Reference
+
+Technical reference for Terreno packages and APIs. Information-oriented, precise descriptions.
+
+## Packages
+
+- [@terreno/api](api.md) — modelRouter, auth, permissions, setupServer
+- [@terreno/ui](ui.md) — Components, theming, layout
+- [@terreno/syncdb](syncdb.md) — Local-first data layer (reads, writes, offline sync)
+- [@terreno/ai](ai.md) — AI service, GPT routes, Langfuse integration
+- [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
+- [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
+- [@terreno/admin-spa](admin-spa.md) — Standalone admin SPA + Express serve plugin
+- [@terreno/api-health](api-health.md) — Health check TerrenoPlugin
+- [@terreno/comms](comms.md) — Pluggable mail, SMS, push, and verification providers
+- [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
+- [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
+- [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
+
+## Migrating from RTK
+
+`@terreno/rtk` is deprecated for **data synchronization**. New apps should use [`@terreno/syncdb`](syncdb.md). Existing RTK consumers: follow [Migrate from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md). Archived RTK reference: [legacy/rtk.md](legacy/rtk.md).
+
+## Configuration
+
+- [Environment Variables](environment-variables.md) — Complete environment variable reference for all packages
+
+## Other references
+
+- [Lifecycle plugin](lifecycle-plugin.md) — Grow/Pick/Roast/Brew/Taste contracts, results, and transitions
+- [Install agent skills](../how-to/install-agent-skills.md) — Published `skills/` tree for `npx skills`
+- Root [package.json](https://github.com/flourishhealth/terreno/blob/master/package.json) — Workspace scripts and catalog
+- Per-package `package.json` in each package directory — Commands and dependencies