@terreno/mcp 57.14.0 → 57.16.1

package/src/docs/versioned/57.15.0/implementationPlans/demo-workshop.md

@@ -0,0 +1,219 @@
+# Implementation Plan: Demo workshop
+
+**Status:** Approved
+**Branch:** `cursor/demo-workshop-cc39`
+**Owner:** —
+**Created:** 2026-09-26
+**Task list:** [demo-workshop.md](../tasks/demo-workshop.md)
+**Depends on:** —
+**RTK deprecation flag:** None
+**Supersedes:** the visual-regression non-goal in [examples-demo-coverage.md](examples-demo-coverage.md). Story coverage from that plan stays as it is.
+
+## Goal
+
+Turn the Expo demo into the workshop for `@terreno/ui`: a person can find a component, copy a usage snippet, change theme and viewport from the URL, and see whether every stable story passes interaction, accessibility, and visual checks on web and Android.
+
+Released demo majors stay online. The site opens on the newest released major (57 today). A dropdown lists older majors, such as 56, and the next major when `preview/<major>` exists, such as 58 preview.
+
+## Non-Goals
+
+- An addon or plugin system.
+- iOS simulator runs, iOS screenshot baselines, and iOS accessibility checks.
+- A translation catalog for `@terreno/ui`.
+- The commented combinatorial prop matrix in `demo/app/demo/[component].tsx`.
+- A pull-request comment bot.
+- Rebuilding frozen majors on later master commits.
+- Android baselines for historical majors. Android CI proves the branch under test.
+- Feature-branch Netlify aliases (`pr-*`) appearing in the version dropdown.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Platforms | Web and Android in this plan. iOS is a later plan. |
+| Visual coverage | Every stable named story. A story may opt out only with `stability: "exclude"` and a non-empty reason. |
+| Usage snippets | One curated `usageExample` string on each story config, shown with a copy button. |
+| Preview controls | Theme, viewport, background, locale, right-to-left, and reduced motion on demo and dev routes. State lives in the URL. Embeds apply the query and hide the bar. |
+| Theme values | Light, plus the existing canonical dark role remap (`demo/components/palette/darkTheme.ts`). Custom palettes stay on `/palette`. |
+| Viewports | The Box breakpoints already documented for web: 320, 375, 1024, and 1280. |
+| Locale | The toolbar passes the selected locale only to components that already read one (consent content, date and calendar formatting). Right-to-left is a separate control. |
+| Collaboration | CI artifacts and a check summary. No pull-request comment. |
+| Agent access | Public `@terreno/mcp` tools read a generated demo catalog and the version manifest URL. |
+| Visual comparison | Separate cropped web and Android PNG baselines. Reuse the chart pixel matcher. An Android-specific tolerance requires a note in the how-to. |
+| Android CI | The full Android suite blocks pull requests that change `ui/` or `demo/`. |
+| Preview branch | `preview/<major>` (for example `preview/58`) is the only branch labeled as the next-major preview. |
+| Frozen majors | When master moves to a new major, keep the previous major at its last master commit. The current major redeploys on every master merge. Backfill 56 from its last master commit. |
+| Version dropdown | Persistent top bar on the home, demo, and dev pages. Default is the highest released major, which is the production deploy. |
+| Docs embeds | A docs version embeds the demo major it documents. The next docs version embeds `preview/<major>` when that deploy exists. |
+| Accessibility | Web uses axe and fails a story on serious or critical violations. Android asserts the accessibility tree from the same step list. Moderate axe findings are warnings in the health report. |
+| Interaction source | One declarative step list per story. Playwright runs it on web. A generated Maestro flow runs it on Android. |
+
+## Architecture
+
+```text
+demo/demoConfig.tsx
+  usageExample, related routes, story stability, interaction steps
+        │
+        ├─ home/dev search + category filters + linked related components
+        ├─ preview bar (URL state) and version bar (versions.json)
+        ├─ web Playwright: interactions, axe, cropped PNG
+        ├─ Android Maestro: same steps, accessibility tree, cropped PNG
+        └─ demo-catalog.json ── @terreno/mcp list/get tools
+
+master deploy ── production site = current major (57)
+last 56 master commit ── Netlify alias v56 (frozen)
+preview/58 ── Netlify alias v58 (preview: true)
+production /versions.json ── dropdown on every major
+```
+
+### Catalog contract
+
+`DemoConfiguration` gains:
+
+- `usageExample: string` — copyable usage, including the import when it is a normal `@terreno/ui` import.
+- `related` entries resolve through `findDemoConfig`. Unknown names fail the catalog test.
+- `stories[name].stability`: `"stable"` by default, or `"exclude"` with `excludeReason`.
+- `stories[name].showInDemo` is honored. `false` hides that story from demo mode and keeps it on the dev route.
+- `stories[name].interactions`: ordered steps `{action: "press" | "type" | "expectText" | "expectRole", targetTestID?, value?, role?, name?}`.
+- Control defaults come from the control type: `false` for boolean, `0` for number, `""` for string. The `""` fallback for every type goes away.
+
+`demo/collectRegisteredStoryRenders.ts` remains the inventory. Story ids stay `<Component> / <story>`.
+
+### Preview and version chrome
+
+`DemoChrome` wraps home, demo, and dev. The version dropdown is on every non-embed page. Preview controls are on demo and dev component routes. `?embed=1` hides both and still applies preview query params.
+
+Preview query keys: `theme`, `viewport`, `background`, `locale`, `rtl`, `reducedMotion`.
+
+The version dropdown does not switch code inside one bundle. It navigates to that major's deploy. Every bundle loads `versions.json` from the production demo origin so a frozen major learns about a new preview without a rebuild. That file is served with CORS for the demo aliases.
+
+```typescript
+interface DemoVersionManifest {
+  currentMajor: number;
+  versions: {
+    major: number;
+    label: string;
+    url: string;
+    preview: boolean;
+    released: boolean;
+  }[];
+}
+```
+
+`currentMajor` is the highest `released && !preview` entry. Production is that major. `preview/58` adds `{major: 58, label: "58 preview", preview: true, released: false}` while the branch exists. Merging 58 to master freezes 57 onto alias `v57`, points production at 58, and removes the preview flag.
+
+Feature-branch aliases stay out of the manifest.
+
+### Proof
+
+| Check | Web | Android |
+| --- | --- | --- |
+| Render | Existing `demo/storiesSmoke.test.tsx` | Maestro opens the story |
+| Interaction | Playwright runs `interactions` | Generated Maestro flow |
+| Accessibility | axe, serious and critical fail | Accessibility-tree assertions from `expectRole` / labels |
+| Visual | Cropped PNG in `demo/rendered-snapshots/web/` | Cropped PNG in `demo/rendered-snapshots/android/` |
+
+Chart goldens stay in `demo/rendered-snapshots/` until the chart task moves them. The chart compare script keeps working for chart fixtures.
+
+A stable story without a web golden, an Android golden, or an exclusion fails CI. The same rule applies to interaction steps.
+
+`demo/story-health.json` is produced by those jobs and copied into the demo build. The component page shows pass, fail, or not-run for render, interaction, accessibility, and visual, per platform. Missing file means not-run.
+
+CI uploads the JSON, PNGs, and diffs as job artifacts and writes a check summary. It does not comment on the pull request.
+
+Android runs on a CircleCI Android image with one pinned emulator: Pixel 6, API 34. The job is path-filtered like today's Maestro demo job (`ui/**`, `demo/**`) and is required on those pull requests.
+
+### MCP
+
+`bun run demo:catalog` writes `demo/demo-catalog.json` with component name, category, route, snippet, story ids, stability, and the production `versions.json` URL. `@terreno/mcp` exposes:
+
+- `terreno_list_demo_stories`
+- `terreno_get_demo_story`
+
+Tools return catalog data. They do not drive a browser and they do not run Android.
+
+### Docs embeds
+
+`website` `DEMO_URL` becomes per docs version. Version 57.x points at the 57 demo alias (production while 57 is current). The next docs version points at the `preview/<major>` URL when the manifest lists that preview, and otherwise at production. `ComponentDemo` keeps `?embed=1`.
+
+## Models
+
+None.
+
+## APIs
+
+`GET /versions.json` on the production demo host, shape above.
+
+MCP tools `terreno_list_demo_stories` and `terreno_get_demo_story`. No new HTTP API on `@terreno/api`.
+
+## Notifications
+
+None.
+
+## UI
+
+- Home and dev: search box and category filters over `DemoConfig`.
+- Component page: copyable snippet, linked related components, preview controls, per-story health.
+- Persistent version dropdown on home, demo, and dev.
+- Embed mode unchanged except that preview query params apply.
+
+Frontend verification uses the running web demo. Android verification uses the emulator flow for Button, then the full stable catalog.
+
+## Phases
+
+1. Catalog contract, search, snippets, and the preview bar. Button is the tracer.
+2. Web interaction, axe, and visual baselines, then the health report.
+3. Android emulator CI for Button, then every stable story.
+4. Version manifest, frozen majors, preview branch, docs embeds.
+5. MCP catalog tools.
+
+## Feature Flags & Migrations
+
+None. New demo query params are optional. Existing `/demo/<component>` URLs keep working. Production keeps serving the current major at the existing demo host.
+
+## Not Included / Future Work
+
+- iOS simulator coverage and iOS goldens.
+- Library-wide translations.
+- Demo addon API.
+- Pixel baselines for every historical major.
+
+## Files to Create / Modify
+
+Create
+
+- `docs/how-to/preview-demo.md`
+- `docs/how-to/demo-versions.md`
+- `docs/how-to/compare-demo-snapshots.md`
+- `demo/components/DemoChrome.tsx`
+- `scripts/demo/` runners and manifest publisher
+- `demo/demo-catalog.json` (generated)
+
+Modify
+
+- `demo/demoConfig.tsx`, `demo/story-config/*.config.tsx`, `demo/app/demo/[component].tsx`
+- `demo/components/DemoHomePage.tsx`, `demo/components/DevHomePage.tsx`
+- `demo/README.md`
+- `docs/reference/test.md`, `docs/reference/ui.md`, `docs/reference/mcp-server.md`
+- `docs/how-to/run-tests-locally.md`, `docs/how-to/circleci.md`
+- `.circleci/config.yml`, `.circleci/continue-config.yml`
+- `scripts/ci/netlify-deploy.sh`
+- `website/src/components/ComponentDemo/index.tsx`, `website/docusaurus.config.ts`
+- `mcp-server/src/tools.ts`
+
+## Task List
+
+[docs/tasks/demo-workshop.md](../tasks/demo-workshop.md)
+
+## Acceptance Criteria
+
+- [ ] Search on the home grid finds Button by name and by category, and Button's related components are links.
+- [ ] Every registered component has a `usageExample`, and the Button page copies it.
+- [ ] A URL on the Button demo sets theme, viewport, background, locale, right-to-left, and reduced motion. Embed hides the bar and keeps the query.
+- [ ] Every stable story has web interaction steps or an exclusion reason, an axe result, and a web PNG baseline.
+- [ ] The same stable stories have Android interaction, accessibility-tree, and PNG results. The Android job fails the pull request when `ui/` or `demo/` changes.
+- [ ] The Button page shows health from `story-health.json`. CI publishes a check summary and artifacts and does not comment.
+- [ ] Production opens on major 57. Alias `v56` serves the last major-56 master commit. `preview/58` appears as "58 preview" and is not the default.
+- [ ] A 57 docs page embeds the 57 demo. The next docs version embeds the 58 preview when that alias exists.
+- [ ] `terreno_get_demo_story` returns Button's snippet, route, and the version manifest URL.
+- [ ] `demo/README.md`, the how-to pages named above, and the reference pages named above match this behavior.

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

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

package/src/docs/versioned/57.15.0/implementationPlans/deploy-to-vercel.md

@@ -0,0 +1,213 @@
+# Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
+
+**Status:** Approved — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1012
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`deployment-foundation`](deployment-foundation.md)
+**RTK deprecation flag:** **Partial** — the web build and client configuration sections depend on the frontend data layer; the syncdb websocket transport also has implications for which parts of the app can be served from serverless functions. Marked tasks must be re-verified after PR #869.
+
+## Goal
+
+Give Terreno the fastest possible "my app is on the internet" path, and a skill that executes it. Vercel is where most JavaScript developers expect to deploy, and Expo Router has first-class Vercel support (`vercel.json` with `expo export -p web`, plus `expo-server/adapter/vercel` for server output). Terreno currently has zero Vercel documentation — the only occurrences of "Vercel" in the repo refer to the Vercel **AI SDK** inside `@terreno/ai`, which is a completely different thing and is itself a source of confusion worth addressing.
+
+**Topology is not finalized.** A pre-implementation spike must answer whether a single-platform Vercel deploy (web + `@terreno/api` + file storage) is viable, or whether the documented path remains split (static web on Vercel, long-lived backend elsewhere). Until the spike completes, this IP documents the **interim split topology** and tracks open questions as TODOs.
+
+## Non-Goals
+
+- Committing to a Vercel backend topology before the spike (see **Open TODOs** below).
+- Vercel-hosted MongoDB (does not exist; Atlas is the answer).
+- Native app distribution (that is EAS; see the `expo-deployment` skill).
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted where not marked open).
+
+| # | Question | Decision |
+|---|----------|----------|
+| V1 | Backend host | **Open — spike required.** Candidate: all-in-one on Vercel (web + backend + Blob storage). Fallback: Railway/Render/Fly + Vercel static web (see [`deployment-foundation`](deployment-foundation.md)). **Do not publish a final answer until TODOs below are closed.** |
+| V2 | Document `server` output? | **Open — depends on V1 spike.** Default if documented: advanced section, Expo SDK ≥ 55, SSE buffering caveat |
+| V3 | Commit `vercel.json`? | **Open — depends on V1 spike.** Candidate: wired to real deployment in `example-frontend` and `example-backend` |
+| V4 | Preview deployments | **A** — include CORS + Better Auth `trustedOrigins` for preview URLs |
+| V5 | Disambiguate Vercel AI SDK vs hosting | **A** — consistent phrasing: "the Vercel AI SDK" vs "Vercel (hosting)" |
+
+## Open TODOs (pre-implementation spike)
+
+Complete these before Phase 1 of the how-to guide ships:
+
+- [ ] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Use [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the source of truth. Document runtime limits, Fluid compute, cold starts, max-duration disconnects, and that a connection is pinned to one function instance (not session affinity across reconnects).
+- [ ] **V1-todo:** Write operator docs for websocket usage on Vercel Functions (see **Vercel Functions WebSockets** below). Link the beta page; do not copy it. Re-verify every config key and limitation against that page before the how-to ships.
+- [ ] **V1-todo:** Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
+- [ ] **V1-todo:** Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
+- [ ] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
+- [ ] **V2-todo:** If `server` output is documented, confirm Expo SDK ≥ 55+ requirements and list which Terreno features break under static/server export.
+- [ ] **V3-todo:** If committing `vercel.json`, confirm CI/deploy wiring for `example-frontend` and `example-backend` and who owns the Vercel project.
+
+## Architecture
+
+### Interim topology (document until spike closes)
+
+Until V1 is decided, document this split layout — it is known to work:
+
+```mermaid
+flowchart LR
+  U["Users<br/>web + native"]
+  V["Vercel<br/>Expo web export<br/>(single output)"]
+  B["Long-running host<br/>@terreno/api + Socket.io"]
+  A["MongoDB Atlas<br/>replica set"]
+  S["Object storage<br/>uploads"]
+  U -->|"web"| V
+  U -->|"native"| B
+  V -->|"XHR + websocket"| B
+  B --> A
+  B --> S
+```
+
+The web deployment is static; dynamic operations go to the backend. Vercel needs SPA rewrites and build-time `EXPO_PUBLIC_API_URL`.
+
+### Candidate topology (if spike succeeds)
+
+```mermaid
+flowchart LR
+  U["Users<br/>web + native"]
+  VC["Vercel<br/>web + @terreno/api + storage"]
+  A["MongoDB Atlas<br/>replica set"]
+  U --> VC
+  VC --> A
+```
+
+**Do not document this as the recommended path until all V1 TODOs are checked.**
+
+### `vercel.json` for `single` output
+
+Per Expo's published configuration, the SPA case needs rewrites so client-side routes resolve:
+
+```json
+{
+  "buildCommand": "expo export -p web",
+  "outputDirectory": "dist",
+  "devCommand": "expo",
+  "cleanUrls": true,
+  "framework": null,
+  "rewrites": [{ "source": "/:path*", "destination": "/" }]
+}
+```
+
+### `vercel.json` for `server` output (advanced)
+
+Server output changes the shape: `dist/client` is served statically and a function handles everything else via `expo-server/adapter/vercel`, with `includeFiles` pulling in `dist/server/**`. Document only after V2 TODOs close. Flag the streaming caveat for `@terreno/ai` chat.
+
+### The preview-deployment problem
+
+Vercel gives every PR a unique origin. That breaks two things:
+
+1. **CORS** — `corsOrigin` in `setupServer` must accept the preview origin. Document a pattern (a function or regex matching `https://<project>-*.vercel.app`) rather than `corsOrigin: true`, and say plainly that `true` is not acceptable in production.
+2. **Better Auth `trustedOrigins`** — same problem, separate config, and OAuth redirect URIs must be registered per provider.
+
+This section ships regardless of V1 outcome.
+
+### `deploy-vercel` skill
+
+New skill at `.rulesync/skills/deploy-vercel/SKILL.md`:
+
+1. **Detect** — is this an Expo Router web app; what is `web.output` in the app config; is there an existing `vercel.json`.
+2. **Configure** — write or update `vercel.json` for the detected output mode; add the `vercel-build` script when using server output.
+3. **Wire the backend** — determine the backend URL (per finalized V1 decision), set `EXPO_PUBLIC_API_URL` as a Vercel environment variable per environment (production/preview/development), and print the CORS and `trustedOrigins` changes the user must make on the backend.
+4. **Deploy** — `vercel` / `vercel --prod`, with a confirmation gate before the first production deploy.
+5. **Verify** — load the deployed URL, confirm the app boots, confirm an authenticated request reaches the backend, and confirm the websocket connects.
+6. **Troubleshoot** — blank page (missing rewrites), 404 on refresh (same), API calls to localhost (`EXPO_PUBLIC_API_URL` not set at build time), CORS failure, websocket failure, buffered SSE on server output.
+
+The verification step must include the websocket check. A Terreno web app can look completely fine while realtime and live feature flags are silently broken.
+
+### Vercel Functions WebSockets (Public Beta) — required how-to
+
+Vercel now documents WebSockets on Vercel Functions as **Public Beta**: [WebSockets](https://vercel.com/docs/functions/websockets). Phase 0 and the how-to must treat that page as the vendor contract. The Terreno page is operator docs for `@terreno/api` (`RealtimeApp` / Socket.io) and `@terreno/syncdb` on that runtime — not a reprint of Vercel’s examples.
+
+**Ship** `docs/how-to/vercel-function-websockets.md`. Link it from `docs/how-to/deploy-web-to-vercel.md` and from `docs/how-to/websocket-integration.md`. Mark the feature **beta**; tell operators to re-read the Vercel page before production. Do **not** present all-in-one Vercel hosting as the recommended Terreno topology until the V1 TODOs close.
+
+The published page must cover the following (cite the Vercel URL; keep examples Terreno-shaped).
+
+#### What Vercel guarantees (as of the beta page)
+
+| Fact | Terreno implication |
+|------|---------------------|
+| A WebSocket starts as HTTP `GET` with `Upgrade`. Routing Middleware, rewrites, Firewall, and rate limits apply **before** the upgrade. | Document Firewall rules and rate limits on the Socket.io path. Better Auth / JWT handshake auth still runs on the upgrade, same as today. |
+| After upgrade, messages stay on the **same function instance** for the life of that connection. Fluid compute can multiplex many connections on one instance. | In-memory `socket.join` rooms work for one connection’s instance only. Cross-instance fan-out still needs the Redis adapter (`RealtimeApp` `adapter: "redis"` + `VALKEY_URL` / `REDIS_URL`). |
+| New connections are **not** guaranteed to hit the same instance. After a deploy, **new** connections may land on the new deployment while **existing** connections stay on the old one until they close. | Presence, rooms, counters, and pub/sub must live in Redis (or equivalent), not process memory. Change-stream watchers are per instance — spike must record cost and fan-out via Redis. |
+| The connection closes when the function hits **max duration**. Clients must reconnect, resubscribe, and reload state. | Document exponential backoff. `@terreno/rtk` `useSocketConnection` already reconnects; `@terreno/syncdb` must resubscribe after reconnect. Name the debug flag (`WEBSOCKETS_DEBUG` at time of writing). |
+| Socket.IO is supported if the **client uses the WebSocket transport only** (`transports: ['websocket']`). Long-polling is not the Vercel path. | Terreno already documents `transports: ["websocket"]` in `docs/how-to/websocket-integration.md`. The Vercel page must restate that long-polling is forbidden on Functions. |
+| Express (and Hono, etc.) can serve sockets by attaching `ws` / Socket.IO to a Node HTTP server and **`export default server`**. | Spike must map this to `TerrenoApp.build()` (or equivalent) vs `start()`. Today the process listens; a Function entry exports the HTTP server. Record the exact adapter file (`api/server.ts` or Expo `expo-server/adapter/vercel` is a **different** path — do not conflate web SSR with the API process). |
+| Fluid compute is required. It is the default for new Vercel projects created on or after 2025-04-23. | Document how to confirm Fluid is on. Without it, do not host Terreno sockets on Functions. |
+| Usage is billed as Function time while the socket is open, plus Fast Data Transfer / Fast Origin Transfer. | Include a cost warning in the all-in-one vs split comparison (V1 cost TODO). Long-lived sync sockets are not “free HTTP”. |
+
+#### Required operator sections
+
+1. **When to use this** — hosting `@terreno/api` (or a dedicated socket process) on Vercel Functions. When **not** to: static Expo `single` output on Vercel talking to a long-running backend (interim topology); native EAS; treating the Vercel **AI SDK** as this feature.
+2. **Prerequisites** — Fluid compute; Function max duration set high enough for the product; Redis if more than one instance or rolling deploys; MongoDB Atlas replica set still required for change streams (unchanged).
+3. **Socket.IO on a Function** — export an HTTP server with Socket.IO attached; client `path` and `transports: ['websocket']`; Terreno `RealtimeApp` + `SyncApp` still registered. Link Vercel’s Socket.IO snippet as the vendor shape, then show the Terreno registration, not a second copy of `ws` echo servers.
+4. **Reconnects** — max-duration close; backoff; resubscribe; “looks fine while sync/flags are dead”.
+5. **State** — no in-memory rooms across instances; Redis; deploy split-brain (old + new deployments both alive).
+6. **Limits and pricing** — pointer to Vercel’s limits/pricing on that page; Function duration while connected.
+7. **Verify** — DevTools Network → WS; `WEBSOCKETS_DEBUG`; confirm the client did **not** fall back to polling.
+
+#### Explicitly out of scope for this page
+
+- Next.js `experimental_upgradeWebSocket` from `@vercel/functions` (not Terreno’s server).
+- Bun `Bun.serve()` / Python FastAPI examples (link the Vercel page; do not re-home them).
+- Replacing MongoDB change streams with Vercel Queues or Vercel KV pub/sub as the Terreno protocol.
+
+## Models / APIs / Notifications / UI
+
+None.
+
+## Phases
+
+0. **Spike** — close all **Open TODOs** above; record decision on V1/V2/V3 in this file; write `docs/how-to/vercel-function-websockets.md` from the beta contract (may ship before V1 is decided, as constraints — not as a topology recommendation).
+1. **How-to guide** — `single` output, clone → public URL (topology per V1 outcome); link the websocket Functions page.
+2. **Preview deployments and origins** — CORS, `trustedOrigins`, OAuth redirects.
+3. **Advanced: server output** — only if V2 is approved.
+4. **Skill** — author and generate mirrors.
+5. **Validate** — deploy examples per V3 outcome.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- EAS native distribution (separate skill).
+- Multi-region Vercel edge configuration.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/how-to/deploy-to-vercel.md` (blocked on Phase 0 spike)
+- `docs/how-to/vercel-function-websockets.md` (Vercel Functions WebSockets beta; may ship during Phase 0)
+- `.rulesync/skills/deploy-vercel/SKILL.md`
+
+**Modify (after V3 decision)**
+
+- `example-frontend/vercel.json` (candidate)
+- `example-backend/vercel.json` (candidate — only if all-in-one path wins)
+
+**Modify (with Task 0.2)**
+
+- `docs/how-to/README.md`
+- `docs/how-to/websocket-integration.md`
+
+## Task List
+
+See [`docs/tasks/deploy-to-vercel.md`](../tasks/deploy-to-vercel.md).
+
+## Acceptance Criteria
+
+- [ ] All **Open TODOs** are closed with a written decision on V1, V2, and V3.
+- [ ] `docs/how-to/deploy-to-vercel.md` matches the decided topology (not the interim split doc if all-in-one wins, and vice versa).
+- [ ] `docs/how-to/vercel-function-websockets.md` exists, cites [Vercel Functions WebSockets](https://vercel.com/docs/functions/websockets), covers Fluid compute, websocket-only Socket.IO, instance pinning, max-duration reconnects, Redis for cross-instance state, Function billing while connected, and Terreno `RealtimeApp` / syncdb — without recommending all-in-one until V1 is decided.
+- [ ] Preview-deployment CORS and `trustedOrigins` guidance is present.
+- [ ] `deploy-vercel` skill includes websocket verification in its checklist.
+- [ ] Vercel AI SDK vs Vercel hosting disambiguation appears in both `@terreno/ai` and deployment docs.