@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/57.17.0/tasks/dashboard-chart-parity.md

@@ -0,0 +1,145 @@
+# Tasks: Dashboard chart parity
+
+IP: [dashboard-chart-parity.md](../implementationPlans/dashboard-chart-parity.md)  
+**Follows:** https://github.com/TerrenoLabs/terreno/issues/1175  
+**Roadmap issue:** set after IP approval
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (scorecard)
+
+- [x] **Task 1.1**: `SparklineChart` + dotted `comparisonData`
+  - Delivers: public plot-only sparkline; solid current series; dotted comparison aligned on `label`; no axes/grid/legend/tooltip row; empty input does not throw
+  - Files: `ui/src/SparklineChart.tsx`, `ui/src/SparklineChart.test.tsx`, `ui/src/charts/paths.ts` (reuse line path), `ui/src/Common.ts` (TypeDoc props), `ui/src/index.tsx` / `heavyOptionalExports.tsx`
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: stub `SparklineChart` on `docs/reference/ui.md` Display list
+  - Acceptance: bun tests — N points → path present; comparison path present when `comparisonData` set; empty data shows nothing / emptyText if provided; `ui` compile green
+
+- [x] **Task 1.2**: `Scorecard` + `ChartCard`
+  - Delivers: KPI tile with title, formatted value, optional sparkline; `ChartCard` with title, period badge, optional `onPeriodPress`, optional `filterSummary`
+  - Files: `ui/src/Scorecard.tsx`, `ui/src/Scorecard.test.tsx`, `ui/src/ChartCard.tsx`, `ui/src/ChartCard.test.tsx`, lazy exports
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: stub both on `docs/reference/ui.md`
+  - Acceptance: bun tests — value + title render; sparkline mounts when `sparklineData` set; badge press fires; period badge has no press handler when `onPeriodPress` omitted
+
+- [x] **Task 1.3**: Scorecard demo + first golden
+  - Delivers: demo story; gallery fixture `scorecard-sparkline-comparison` (five KPI tiles, static data); PNG golden
+  - Files: `demo/stories/Scorecard.stories.tsx`, `demo/stories/ChartCard.stories.tsx`, `demo/demoConfig.tsx`, `demo/chartVisual/fixtureCatalog.ts`, `demo/chartVisual/fixtures.tsx`, `demo/rendered-snapshots/scorecard-sparkline-comparison.png`
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `review-chart-visuals`, `verify-ui-changes`
+  - Docs: `docs/how-to/compare-chart-rendered-snapshots.md` lists the new id
+  - Acceptance: fixture catalog test includes the id; `bun run ui:charts:compare` green for it; story registered
+
+## Phase 2 — Cartesian additive facades
+
+- [x] **Task 2.1**: `series` + `comparisonData` on `LineChart` / `AreaChart`
+  - Delivers: multi-series lines from `series`; single `data` still works; dotted comparison overlay; per-series legend; markers stay
+  - Files: `ui/src/LineChart.tsx`, `ui/src/AreaChart.tsx`, matching tests, `ui/src/charts/scales.ts` (shared x domain across series)
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` Line/Area props
+  - Acceptance: bun tests — three `series` → three paths + three legend labels; `{label,value}[]` only still draws one series; comparison path exists when set
+
+- [x] **Task 2.2**: `xTickPolicy` + bar comparison + header shortcuts
+  - Delivers: `"auto"` rotates when labels would truncate, stays horizontal for ≤7 categories; `BarChart` accepts `series` (grouped later if >1 — this slice: first series only unless a second is comparison) and `comparisonData`; `title` / `periodLabel` / `onPeriodPress` on cartesian facades
+  - Files: `ui/src/BarChart.tsx`, `ui/src/LineChart.tsx`, `ui/src/charts/layout.ts`, `ui/src/BarChart.test.tsx`, `ui/src/LineChart.test.tsx`
+  - Blocked by: 2.1
+  - Skills: `terreno-ui`
+  - Docs: tick policy in `docs/explanation/charts.md`
+  - Acceptance: bun tests — 14 long date labels with `auto` → rotated tick style; 7 weekday labels stay horizontal; facade title renders when set and `ChartCard` is not wrapping (documented exclusive use)
+
+- [x] **Task 2.3**: Cartesian goldens
+  - Delivers: fixtures `bar-time-rotated-ticks`, `line-three-series`, `bar-day-of-week`
+  - Files: `demo/chartVisual/**`, `demo/rendered-snapshots/*.png`
+  - Blocked by: 2.2
+  - Skills: `review-chart-visuals`, `verify-ui-changes`
+  - Docs: compare-how-to fixture table
+  - Acceptance: `bun run ui:charts:compare` green for the three ids
+
+## Phase 3 — Donut center and share legend
+
+- [x] **Task 3.1**: Donut hole + percent legend
+  - Delivers: `centerTitle`, `centerValue`; legend `swatch + label + formatShare` (default percent of total); 100% single-slice still draws a ring + center
+  - Files: `ui/src/DonutChart.tsx`, `ui/src/DonutChart.test.tsx`
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` Donut props
+  - Acceptance: bun tests — center copy present; legend includes `%`; one-slice data still has one path; existing slice color override still works
+
+- [x] **Task 3.2**: Donut goldens
+  - Delivers: `donut-center-and-share`, `donut-single-slice`
+  - Files: `demo/chartVisual/**`, goldens
+  - Blocked by: 3.1
+  - Skills: `review-chart-visuals`
+  - Docs: compare-how-to
+  - Acceptance: compare green for both ids
+
+## Phase 4 — Spanning grid
+
+- [x] **Task 4.1**: `DashboardGridItem` spans
+  - Delivers: eager `DashboardGridItem` with `span` per breakpoint; default span 1; children without a wrapper keep current equal-column behavior
+  - Files: `ui/src/DashboardGrid.tsx` and/or `ui/src/DashboardGridItem.tsx`, `ui/src/DashboardGrid.test.tsx`, `ui/src/index.tsx` (eager)
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` Layout
+  - Acceptance: bun tests — span 2 in a 4-column row yields ~2× cell width minus gap; unwrapped children still fill 1 column
+
+- [ ] **Task 4.2**: `hows-it-going-dashboard` chart composition
+  - Delivers: hard fixture matching the reference layout (5 scorecards, cost/conv bar, 3-line imp share, DOW bar, two donuts). Table slot may be a `ChartCard` placeholder until 5.2
+  - Files: `demo/chartVisual/fixtures.tsx`, `fixtureCatalog.ts`, golden
+  - Blocked by: 2.3, 3.2, 4.1
+  - Skills: `review-chart-visuals`, `verify-ui-changes`
+  - Docs: how-to example rewritten to this composition
+  - Acceptance: compare green; fixture uses `Scorecard` / `ChartCard` / `DashboardGridItem`, not ad-hoc `Box` widths only
+
+## Phase 5 — Table chrome
+
+- [ ] **Task 5.1**: Header groups, footer rows, range status, wrapLines
+  - Delivers: `headerGroups` second header row; `footerRows` sticky totals; range copy `start–end of total` with existing pagination; `wrapLines={2}` wraps cell text inside `rowHeight` (virtualization unchanged)
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`, `ui/src/Pagination.tsx` (if range lives there), `ui/src/Common.ts`
+  - Blocked by: 4.1
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` DataTable; pointer from charts how-to
+  - Acceptance: bun tests — grouped header text visible; footer row present; range text `1–50 of 452` with page 1 size 50 total 452; pinned column scroll still syncs with groups/footer; wrapLines 2 does not change `rowHeight`
+
+- [ ] **Task 5.2**: Table card in the hard fixture
+  - Delivers: one `ChartCard` + `DataTable` in `hows-it-going-dashboard` (Search Terms or Ad Group Check-in static rows, totals, period headers)
+  - Files: `demo/chartVisual/fixtures.tsx`, update golden
+  - Blocked by: 5.1, 4.2
+  - Skills: `review-chart-visuals`, `verify-ui-changes`
+  - Docs: how-to shows table in the same grid
+  - Acceptance: compare green after intentional golden update; wrapped first-column names visible in the PNG
+
+## Phase 6 — Packaging and docs
+
+- [ ] **Task 6.1**: Lazy root + import regression
+  - Delivers: `Scorecard`, `SparklineChart`, `ChartCard`, chart facades stay on `heavyOptionalExports`; `DashboardGrid` / `DashboardGridItem` eager; root import does not evaluate chart files
+  - Files: `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, `ui/src/RootImportRegression.test.tsx`, `docs/reference/ui-performance.md`
+  - Blocked by: 4.1, 5.1, 2.1, 3.1
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: performance page lists new lazy exports
+  - Acceptance: `RootImportRegression` fails if new chart files load with the root import; subpath imports work
+
+- [ ] **Task 6.2**: Diátaxis + changelog + rules
+  - Delivers: how-to rewritten for easy-build composition; explanation covers scorecard, comparison stroke, additive facades vs grammar; reference complete; changelog fragment; ui rule export list; TypeDoc
+  - Files: `docs/how-to/charts-and-dashboards.md`, `docs/explanation/charts.md`, `docs/reference/ui.md`, `docs/how-to/README.md`, `.rulesync/rules/ui/00-ui.mdc`, `changelog/unreleased/dashboard-chart-parity.md`; `bun run website:generate` if needed
+  - Blocked by: 6.1, 5.2
+  - Skills: `update-docs`, `docs-audit`, `terreno-ui`
+  - Docs: the files listed above
+  - Acceptance: a stranger can copy the how-to into a screen that resembles the reference; explanation states grammar is not required; changelog `category: Added`; existing single-series how-to steps still valid as a subset
+
+## Verification mapping
+
+| Criterion | Method |
+|-----------|--------|
+| Scorecard + sparkline + comparison | bun tests + `scorecard-sparkline-comparison` PNG |
+| Multi-series line | bun tests + `line-three-series` PNG |
+| Rotated vs horizontal ticks | bun tests + `bar-time-rotated-ticks` / `bar-day-of-week` |
+| Donut center + share | bun tests + donut goldens |
+| Grid spans + reference layout | `hows-it-going-dashboard` PNG + grid unit tests |
+| Table chrome | bun tests + table region of hard golden |
+| Facade compatibility | existing `*Chart.test.tsx` stay green |
+| Lazy charts | `RootImportRegression` |
+| Frontend proof | `verify-ui-changes` on demo gallery; artifacts on the implementation PR |

package/dist/docs/versioned/57.17.0/tasks/datatable-server-side-filtering.md

@@ -0,0 +1,87 @@
+# Tasks: DataTable server-side filtering and search
+
+Plan: [`docs/implementationPlans/datatable-server-side-filtering.md`](../implementationPlans/datatable-server-side-filtering.md)  
+**Status:** Pick complete — tasks 1.1–4.1 implemented
+**Closes:** https://github.com/TerrenoLabs/terreno/issues/1177
+
+**Feature profile:** false (full IP)
+
+## Instructions for the implementing agent
+
+- Load `terreno-ui`, `update-docs`, `verify-ui-changes`. Admin tasks also load `building-admin-interfaces`.
+- TDD: failing test first per task.
+- Run `bun test` in touched packages (`ui`, `admin-frontend`, `admin-backend`).
+- Do not import RTK, axios, or admin packages from `@terreno/ui`.
+- Do not change modelRouter list behavior or admin `q` ObjectId search.
+- Frontend slices: `verify-ui-changes` (demo on 8085; admin list when AdminModelTable changes).
+
+---
+
+### Phase 1 — Tracer (query object, no chrome)
+
+- [x] **Task 1.1**: `buildDataTableListQuery` + regex escape
+  - Delivers: Pure helper from filter/search state → modelRouter-shaped object per the IP contract table; empty values omitted; user text escaped; choice always `$in` (including one value)
+  - Files: `ui/src/dataTableListQuery.ts`, `ui/src/dataTableListQuery.test.ts`, export from `ui/src/index.tsx` only if other UI modules need it (prefer importing the file, no new barrel)
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: stub the query table in `docs/reference/ui.md` so the helper is named when it lands
+  - Acceptance: `bun test ui/src/dataTableListQuery.test.ts` — search `$or` regex; `.*` in input is literal; boolean omit/true; date `_gte`/`_lte`; number nested `$gte`; choice `$in`; no `page`/`sort` keys
+
+---
+
+### Phase 2 — DataTable chrome
+
+- [x] **Task 2.1**: Types + controlled props
+  - Delivers: `DataTableColumn.filter` and search/filter/`onQueryChange` props; omitted props preserve today’s UI
+  - Files: `ui/src/Common.ts`, `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`
+  - Docs: none beyond types (generated props in 4.1)
+  - Acceptance: tests — no filter prop → no filter controls; `onQueryChange` not required; existing sort cycle and pagination tests still pass
+
+- [x] **Task 2.2**: Web per-column `Filter` + search box
+  - Delivers: Toolbar search (debounced) and header `Filter` popovers; text / boolean / numberRange / dateRange / choice (`MultiselectField`); `renderFilter` slot; Apply/Clear call `onFilterValuesChange` and `onQueryChange`
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`, `demo/stories/DataTable.stories.tsx`
+  - Blocked by: 2.1
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: demo story is the tutorial surface; reference example in `docs/reference/ui.md`
+  - Acceptance: tests fire `onQueryChange` for each kind; demo story renders search + four kinds; `verify-ui-changes` on demo DataTable story
+
+- [x] **Task 2.3**: Native Filters sheet
+  - Delivers: On non-web, one Filters control + `Modal` sheet containing the same fields and search; same query object as web
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`
+  - Blocked by: 2.2
+  - Skills: `terreno-ui`
+  - Docs: one row in the platform table in `docs/reference/ui.md`
+  - Acceptance: test with `Platform.OS` mock (or testIDs) — sheet apply emits the same params as web Apply; no `Filter` portal on native
+
+---
+
+### Phase 3 — Admin
+
+- [x] **Task 3.1**: `parseAdminListFilters` choice `$in` and text `$regex`
+  - Delivers: Declared `choice` accepts `{ $in: string[] }` (subset of `choices`); `text` accepts `{ $regex, $options: "i" }`; scalar choice/text still work; top-level `$or` still errors; values outside `choices` error
+  - Files: `admin-backend/src/filterParser.ts`, `admin-backend/src/filterParser.test.ts`
+  - Blocked by: none (can parallel 2.x)
+  - Skills: `building-admin-interfaces`
+  - Docs: note in `docs/how-to/admin-add-model.md` that choice filters may be multi-value `$in`
+  - Acceptance: `bun test admin-backend/src/filterParser.test.ts` covers happy `$in`, invalid choice, text regex, rejected `$or`
+
+- [x] **Task 3.2**: AdminModelTable adopts DataTable filters
+  - Delivers: Map `filters` → column `filter` / `renderFilter` for `ref`; search → `q`; drop `AdminFilterDrawer` from the table; `buildAdminListQueryParams` forwards `$in` and omits `$or`
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, `admin-frontend/src/adminModelListQueryParams.ts`, `admin-frontend/src/adminModelListQueryParams.test.ts`, `admin-frontend/src/AdminModelTable.test.tsx`, `admin-frontend/src/AdminFilterDrawer.tsx` / `index.tsx` if unused
+  - Blocked by: 2.2, 3.1
+  - Skills: `building-admin-interfaces`, `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: `docs/reference/admin-frontend.md`, `docs/explanation/admin-interface.md`, `docs/how-to/admin-add-model.md` (filters on columns, not a drawer)
+  - Acceptance: tests — search param is `q` not `$or`; choice multi → `$in`; drawer not in table output; admin list verification in admin-spa or example admin
+
+---
+
+### Phase 4 — Docs and seed
+
+- [x] **Task 4.1**: Diátaxis + generated props + changelog
+  - Delivers: Query contract and platform table in `docs/reference/ui.md`; admin how-to/reference/explanation; regenerate UI component reference; CHANGELOG Added; seed IP/task links already in Grow stay accurate
+  - Files: `docs/reference/ui.md`, `docs/how-to/admin-add-model.md`, `docs/reference/admin-frontend.md`, `docs/explanation/admin-interface.md`, `docs/explanation/roadmap-seed-issues.md`, `CHANGELOG.md`; `ui` types + `bun run website:generate` as required by `update-docs`
+  - Blocked by: 2.3, 3.2
+  - Skills: `update-docs`
+  - Acceptance: a stranger can wire `onQueryChange` to a modelRouter list from docs; admin text contains + choice `$in` are explicit; `bun run website:build` if the site is in the slice

package/dist/docs/versioned/57.17.0/tasks/demo-workshop.md

@@ -0,0 +1,150 @@
+# Task List: Demo workshop
+
+See: [`docs/implementationPlans/demo-workshop.md`](../implementationPlans/demo-workshop.md)
+
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Work the frontier: any task whose blockers are complete. The tracer is Task 1.1 (Button).
+- Do not start iOS work, a translation catalog, or an addon API.
+- Docs named on a task ship in that task. Use the `update-docs` skill.
+- UI tasks also use `verify-ui-changes` and `terreno-ui`.
+- Visual tasks use `review-chart-visuals` for the PNG diff workflow, then the new demo how-to.
+- Run the task's verification command before handoff. `bun run lint` and `bun run demo:compile` on every demo task.
+
+## Phase 1: Catalog, snippets, and preview bar
+
+- [x] **Task 1.1**: Button catalog contract
+  - Delivers: Button has a copyable usage snippet, resolvable related links, stable stories, one declarative interaction list, and typed control defaults.
+  - Files: `demo/demoConfig.tsx`, `demo/story-config/Button.config.tsx`, `demo/stories/Button.stories.tsx`, `demo/collectRegisteredStoryRenders.ts`, `demo/app/demo/[component].tsx`, `demo/README.md`
+  - Blocked by: none
+  - Acceptance: a unit test fails when a related name does not resolve, when an excluded story has an empty reason, or when a boolean control defaults to `""`. Button's snippet renders and copies. `showInDemo: false` hides a Button story in demo mode and leaves it on the dev route.
+  - Verification: `bun test demo/collectRegisteredStoryRenders.ts demo/demoConfig` (or the new colocated test), `bun run demo:compile`, and a web demo pass that opens Button, copies the snippet, and follows one related link.
+  - Docs: `demo/README.md` catalog-contract section
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.2**: Search, categories, and related links
+  - Delivers: the home grid and dev index filter by text and category, and every component's related row is links.
+  - Files: `demo/components/DemoHomePage.tsx`, `demo/components/DevHomePage.tsx`, `demo/app/demo/[component].tsx`, story configs whose `related` strings do not resolve, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: searching "button" shows Button; choosing a category hides other categories; a broken related name fails the catalog test; the home grid still does not nest pressables (`demo/components/DemoCard.test.tsx`).
+  - Verification: catalog unit test, `demo/components/DemoCard.test.tsx`, and a web demo pass of search, category filter, and a related link.
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.3**: Usage snippet on every component
+  - Delivers: every registered story config has `usageExample`, and the component page can copy it.
+  - Files: `demo/story-config/*.config.tsx`, `demo/app/demo/[component].tsx`, `scripts/check-demo-coverage.ts` or a sibling check, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run check:demo-coverage` (or the new snippet check it calls) fails when any registered config lacks a non-empty `usageExample`. The Button page copy control still works.
+  - Verification: the check command, plus one web copy action on a second component (TextField).
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [x] **Task 1.4**: Preview toolbar and URL state
+  - Delivers: demo and dev component routes change theme, viewport, background, locale, right-to-left, and reduced motion from the URL. Embeds apply that state and hide the bar.
+  - Files: `demo/components/DemoChrome.tsx`, `demo/app/_layout.tsx`, `demo/app/demo/_layout.tsx`, `demo/app/dev/_layout.tsx`, `demo/contexts/EmbedModeContext.tsx`, `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: Button at a documented query uses the dark remap and the 375 viewport. Consent or date stories that already read locale receive the toolbar locale. Embed hides the bar. Reloading keeps the query.
+  - Verification: a focused demo unit test for query parse/serialize, `bun run demo:compile`, and a web demo pass of the Button query plus one embed URL.
+  - Docs: `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+## Phase 2: Web proof and health
+
+- [ ] **Task 2.1**: Web interaction and axe for Button
+  - Delivers: Playwright runs Button's step list and axe against the Button stories.
+  - Files: `scripts/demo/runWebStoryChecks.ts`, `demo/story-config/Button.config.tsx`, root `package.json` (axe dependency if needed), `.circleci/config.yml`, `.circleci/continue-config.yml`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Blocked by: Task 1.1
+  - Acceptance: the Button interaction steps pass in Chromium. A serious axe violation fails the command. An excluded story with a reason is skipped. The job is required for `ui/**` and `demo/**` pull requests.
+  - Verification: `bun run demo:web-checks --only=Button` (the script this task adds) locally against demo web, then the CircleCI path-filter test if one exists beside `.circleci/`.
+  - Docs: `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 2.2**: Web visual harness for Button
+  - Delivers: one cropped web PNG baseline for each stable Button story, compared with the chart pixel matcher.
+  - Files: `scripts/demo/compareDemoSnapshots.ts`, `demo/rendered-snapshots/web/`, `scripts/charts/compareChartImages.ts` (reuse only), `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run demo:snapshots:compare --only=Button` passes against the new goldens and fails when a golden is missing. Chart compare still passes for the existing chart fixtures.
+  - Verification: the new compare command and `bun run ui:charts:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`, `docs/how-to/compare-chart-rendered-snapshots.md` (pointer only)
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.3**: Web proof for every stable story
+  - Delivers: every stable story has interaction steps or an exclusion reason, an axe run, and a web PNG baseline.
+  - Files: `demo/story-config/*.config.tsx`, `demo/stories/*.stories.tsx`, `demo/rendered-snapshots/web/`, the web check and snapshot scripts
+  - Blocked by: Task 2.1, Task 2.2
+  - Acceptance: the web check and snapshot commands, with no `--only`, exit 0. Removing one stable story's golden or steps fails the matching command. Excluded stories name a reason.
+  - Verification: `bun run demo:web-checks` and `bun run demo:snapshots:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.4**: Story health and CI summary
+  - Delivers: the component page shows render, interaction, accessibility, and visual status from `demo/story-health.json`. CI stores that file and writes a check summary.
+  - Files: `demo/app/demo/[component].tsx`, `scripts/demo/writeStoryHealth.ts`, `.circleci/continue-config.yml`, `docs/reference/test.md`
+  - Blocked by: Task 2.3
+  - Acceptance: Button shows a pass row after the web commands. A forced failing story shows fail. A missing health file shows not-run. The CircleCI job summary lists failed story ids. The job does not call `gh pr comment`.
+  - Verification: unit test for health rendering, the web commands, and a CI config test or review that the job uploads artifacts and writes the summary.
+  - Docs: `docs/reference/test.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+## Phase 3: Android
+
+- [ ] **Task 3.1**: Android proof for Button
+  - Delivers: a CircleCI Android emulator job runs Button's steps, accessibility-tree assertions, and a cropped Android PNG.
+  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`, `scripts/demo/generateMaestroFlows.ts`, `.maestro/flows/demo/generated/`, `demo/rendered-snapshots/android/`, `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`
+  - Blocked by: Task 2.1
+  - Acceptance: Pixel 6 API 34 runs the generated Button flow. The job is required when `ui/**` or `demo/**` changes. A missing Android golden fails the job. Web axe is unchanged.
+  - Verification: the local Maestro command documented in the how-to, against an emulator, for the Button flow. Record the CircleCI job name.
+  - Docs: `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 3.2**: Android proof for every stable story
+  - Delivers: every stable story has an Android flow, accessibility-tree check, and PNG, or an exclusion reason.
+  - Files: generated Maestro flows, `demo/rendered-snapshots/android/`, `demo/story-health.json` writer
+  - Blocked by: Task 3.1, Task 2.3
+  - Acceptance: the Android job without `--only` exits 0. Health on Button includes the Android columns. An excluded story is absent from the Android failure list and its reason is in the summary.
+  - Verification: the Android compare and Maestro commands across the stable catalog.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+## Phase 4: Major versions
+
+- [ ] **Task 4.1**: Version manifest and dropdown
+  - Delivers: production stays on the current major, `versions.json` lists released majors and a `preview/<major>` branch, and the top bar dropdown navigates there. The default is the highest released major.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `scripts/ci/netlify-deploy.sh`, `demo/components/DemoChrome.tsx`, `docs/how-to/demo-versions.md`, `.circleci/continue-config.yml`
+  - Blocked by: Task 1.4
+  - Acceptance: a unit test of the manifest builder marks `preview/58` as preview and not current, marks 57 as current, and omits `pr-*` aliases. The dropdown on the home page shows those labels. `versions.json` on the production origin sends CORS headers the aliases can read.
+  - Verification: the manifest unit test, a deploy dry-run, and a web demo pass of the dropdown.
+  - Docs: `docs/how-to/demo-versions.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 4.2**: Freeze the previous major and backfill 56
+  - Delivers: moving master from 57 to a later major freezes 57 on alias `v57`. Alias `v56` serves the last master commit whose package major is 56.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `.circleci/continue-config.yml`, `docs/how-to/demo-versions.md`
+  - Blocked by: Task 4.1
+  - Acceptance: a test with a fake deploy history freezes the previous production deploy when the major increases, and leaves 57 updating on ordinary master commits. The backfill command documents the git revision it deployed for 56.
+  - Verification: unit test of the freeze decision, plus the one-time 56 alias deploy recorded in the how-to.
+  - Docs: `docs/how-to/demo-versions.md`
+  - Skills: `update-docs`
+
+- [ ] **Task 4.3**: Docs embeds follow the demo major
+  - Delivers: a 57 docs page embeds the 57 demo. The next docs version embeds the 58 preview when the manifest lists it.
+  - Files: `website/docusaurus.config.ts`, `website/src/components/ComponentDemo/index.tsx`, `docs/how-to/demo-versions.md`, the docs reference page that describes component embeds
+  - Blocked by: Task 4.1
+  - Acceptance: `ComponentDemo` for the 57 docs build requests the 57 demo URL with `?embed=1`. When the manifest has an unreleased preview, the next docs build uses that preview URL. A missing preview falls back to production.
+  - Verification: a website unit test or build-arg test for the URL choice, and `bun run website:build`.
+  - Docs: `docs/how-to/demo-versions.md` and the existing component-embed reference section
+  - Skills: `update-docs`
+
+## Phase 5: MCP catalog
+
+- [ ] **Task 5.1**: Public demo catalog tools
+  - Delivers: `terreno_list_demo_stories` and `terreno_get_demo_story` return Button's snippet, route, story ids, and the version manifest URL.
+  - Files: `demo/demo-catalog.json`, `demo/package.json`, `mcp-server/src/tools.ts`, MCP tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 1.3, Task 4.1
+  - Acceptance: `terreno_get_demo_story` for Button includes `usageExample` and a `/demo/Button` route. The list tool filters by category. The response points at production `versions.json`. A catalog drift test fails when a registered component is missing from the JSON.
+  - Verification: `cd mcp-server && bun test` for the new tool tests, and `bun run demo:catalog` followed by the drift check.
+  - Docs: `docs/reference/mcp-server.md`, `demo/README.md`
+  - Skills: `update-docs`

package/dist/docs/versioned/57.17.0/tasks/deploy-to-gcp.md

@@ -0,0 +1,100 @@
+# Task List: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy-to-gcp.md)
+
+**RTK deprecation flag:** None. The only client-side surface is `EXPO_PUBLIC_API_URL`, which is unchanged by PR #869. Safe to implement before #869 merges.
+
+## Instructions for the implementing agent
+
+- Use placeholder variables in all documentation: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$WEB_BUCKET`, `$UPLOADS_BUCKET`. Never hardcode a real project ID, bucket, or URL.
+- Grep for `flourish` in every file you write or edit before committing: `rg -i flourish <file>`. The only permitted matches are inside `infra/flourish/`.
+- Do **not** run `gcloud` commands that create or modify resources unless the user has explicitly named a target project in the request.
+- Verify every `gcloud` flag you document against `gcloud run deploy --help` before writing it. Do not guess flag names.
+- Run `bun run lint` before each commit; run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Generalize the how-to guides
+
+- [x] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Description: New guide covering: prerequisites (gcloud installed and authenticated, billing enabled, required APIs — `run`, `artifactregistry`, `secretmanager`, `compute`); creating an Artifact Registry repo; building and pushing the backend image; creating Secret Manager secrets for `MONGO_URI`, `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, and `BETTER_AUTH_SECRET`; creating the runtime service account with least-privilege roles; the `gcloud run deploy` invocation with `--session-affinity`, `--timeout`, `--min-instances`, `--set-secrets`, and `--set-env-vars`; and verification via `curl $SERVICE_URL/health`. Use placeholder variables throughout. Read `example-backend/src/server.ts` and `docs/reference/environment-variables.md` to get the env var list right — do not copy it from this task description without checking.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md` (new)
+  - Depends on: none
+  - Acceptance: `rg -i flourish docs/how-to/deploy-backend-to-cloud-run.md` returns nothing; every env var named exists in `docs/reference/environment-variables.md` or the backend source; every `gcloud` flag used appears in `gcloud run deploy --help`.
+
+- [x] **Task 1.2**: Add the production constraints section
+  - Description: Add a "Production constraints" section to the backend guide as a symptom → cause → fix table covering at minimum: (a) websockets disconnect every few requests → no session affinity → add `--session-affinity`; (b) long-lived socket connections drop at 5 minutes → default request timeout → raise `--timeout`; (c) realtime and live feature flags stop working → MongoDB is not a replica set → use Atlas or a replica set, because change streams require one; (d) first request after idle is slow and sockets churn → scaled to zero → `--min-instances=1`; (e) browser requests fail CORS → `corsOrigin` in `setupServer` and Better Auth `trustedOrigins` do not include the web origin. Verify claim (c) against `feature-flags` live-update code before writing it.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Depends on: Task 1.1
+  - Acceptance: all five rows present with a concrete symptom; the change-streams claim is verified against the source and the source path is cited in the guide.
+
+- [x] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Description: New guide covering: building the web bundle (`bunx expo export -p web` — confirm the exact command against `example-frontend/package.json` scripts), the requirement to set `EXPO_PUBLIC_API_URL` at build time because it is inlined into the bundle, creating and configuring the GCS bucket with public read and `notFoundPage=index.html` for client-side routing, the five CDN resources (backend bucket, URL map, static IP, HTTP(S) proxy, forwarding rule), pointing DNS at the IP, and cache invalidation after each deploy. Include a note that this is a static-only path and link [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md) for the SSR future.
+  - Files: `docs/how-to/deploy-web-to-gcs-cdn.md` (new)
+  - Depends on: none
+  - Acceptance: no Flourish strings; the export command matches an actual script in `example-frontend/package.json`; the guide explains why `EXPO_PUBLIC_API_URL` must be set before building, not after.
+
+- [x] **Task 1.4**: Write the architecture explainer
+  - Description: Create `docs/explanation/deployment-architecture-gcp.md` explaining the reference topology (reuse the mermaid diagram from the IP), what each component is responsible for, why Cloud Run rather than App Engine or GKE, why Atlas rather than self-hosted Mongo, and the tradeoffs of static web hosting versus a server-rendered deployment. Keep it conceptual — no commands.
+  - Files: `docs/explanation/deployment-architecture-gcp.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: contains the topology diagram; contains no shell commands; explains at least three explicit tradeoffs.
+
+- [x] **Task 1.5**: Rewire the existing GCP how-to and index
+  - Description: Replace `docs/how-to/deploy-to-gcp.md` with a short index page linking the two new guides and the explainer, preserving the old anchor names where practical so existing links do not break. Update `docs/how-to/README.md` to list the new guides. Check `website/` for any hardcoded reference to the old page path and update it.
+  - Files: `docs/how-to/deploy-to-gcp.md`, `docs/how-to/README.md`, `website/` (as needed)
+  - Depends on: Task 1.1, Task 1.3, Task 1.4
+  - Acceptance: `bun run website:build` succeeds with no new broken-link warnings introduced by this change.
+
+## Phase 2: Terraform module and Flourish separation
+
+- [x] **Task 2.1**: Extract the generic backend module
+  - Description: Create `terraform/modules/terreno-backend/` with `main.tf`, `variables.tf`, `outputs.tf`, and `README.md`. Resources: Artifact Registry repository, Cloud Run v2 service (session affinity, timeout, min/max instances, secret env refs), Secret Manager secrets (created empty, values supplied out-of-band), runtime service account with `secretmanager.secretAccessor` and object admin on a supplied uploads bucket, and optional Workload Identity Federation pool for CI. Every value that could differ between users must be a variable with a description and no Flourish default. Outputs: service URL, service account email, registry path.
+  - Files: `terraform/modules/terreno-backend/main.tf`, `variables.tf`, `outputs.tf`, `README.md` (all new)
+  - Depends on: Task 1.1
+  - Acceptance: `terraform init && terraform validate` passes in the module directory; `rg -i flourish terraform/modules/` returns nothing; every variable has a `description`.
+  - Implementation note: secrets start empty, and Cloud Run rejects a revision that references a versionless secret, so the module does not mount secret env refs at creation. The `set_secrets_flag` output supplies the `--set-secrets` flag for the first real `gcloud run deploy`, consistent with the existing "Terraform owns structure, deploy owns payload" split (`lifecycle.ignore_changes` on env).
+
+- [x] **Task 2.2**: Relocate Flourish-specific terraform
+  - Description: Move Flourish's environment configuration from `terraform/` to `infra/flourish/`, leaving only `terraform/modules/` behind. Update every path reference: `.github/workflows/cd.yml`, `terraform/README.md` (split into a generic module README and `infra/flourish/README.md`), `AGENTS.md` / `CLAUDE.md` if they reference `terraform/README.md`, and any script under `scripts/`. Use `git mv` so history is preserved.
+  - Files: `infra/flourish/**` (moved), `terraform/README.md`, `.github/workflows/cd.yml`, `AGENTS.md`, `CLAUDE.md`, `scripts/**`
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "terraform/" --glob '!infra/**' --glob '!terraform/**'` shows no stale paths pointing at moved files; the `cd.yml` workflow references the new location; `bun run rules:check` exits 0 after regenerating rules.
+
+- [x] **Task 2.3**: Parameterize the GCS hosting script
+  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, `--bucket`, and `--domain` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact, with HTTPS as the only public serving path. Add a `--dry-run` flag that prints commands without executing them.
+  - Files: `scripts/setup-gcs-hosting.sh`
+  - Depends on: Task 1.3
+  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces HTTPS commands containing the supplied values, no port 80 forwarding rule, and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
+
+## Phase 3: The `deploy-gcp` skill
+
+- [x] **Task 3.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-gcp/SKILL.md` with frontmatter (`name: deploy-gcp`, a `description` that names the trigger phrases "deploy to GCP", "deploy to Cloud Run", "ship the backend", and `targets: ['*']`). Body sections in this order: When to use / When not to use; Preflight checks (project layout detection, `gcloud config get-value project`, required APIs, replica-set verification of `MONGO_URI`); **Plan and confirm** — print target project, region, service name, and every resource to be created or updated, then stop and require explicit user confirmation before any mutating command; Backend deploy steps; Frontend deploy steps; Verification (`curl $SERVICE_URL/health` expecting `"healthy":true`, fetch web root); Troubleshooting (link the reference file). Include an explicit prohibition: never deploy to a project the user did not name in the request, and never create or modify secrets without echoing which secret names will change.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: frontmatter has `name`, `description`, and `targets`; the confirmation gate appears before the first mutating command; every command in the skill also appears in the how-to guides (no skill-only knowledge).
+
+- [x] **Task 3.2**: Add the troubleshooting reference
+  - Description: Create `.rulesync/skills/deploy-gcp/references/troubleshooting.md` containing the symptom → cause → fix table from Task 1.2 plus deploy-time failures: image push permission denied, secret access denied at cold start, Cloud Run revision failing health checks because `PORT` is not read from the environment, and CDN serving a stale bundle after deploy. For each, give the exact log line or error message the user will see.
+  - Files: `.rulesync/skills/deploy-gcp/references/troubleshooting.md` (new)
+  - Depends on: Task 3.1
+  - Acceptance: at least nine rows; each row quotes an actual error string rather than paraphrasing.
+
+- [x] **Task 3.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit every generated file under `.cursor/skills/`, `.claude/skills/`, `.devin/skills/`, `.github/skills/`, and `.agents/skills/`. Do not hand-edit generated files.
+  - Files: generated skill mirrors
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-gcp` appears under each configured target directory.
+
+## Phase 4: Validation
+
+- [ ] **Task 4.1**: Dry-run the guide end to end
+  - Description: Following **only** `docs/how-to/deploy-backend-to-cloud-run.md` and `docs/how-to/deploy-web-to-gcs-cdn.md` (no internal knowledge, no `infra/flourish/`), deploy `example-backend` and `example-frontend` to a scratch GCP project. Record every point where the guide was wrong, incomplete, or required outside knowledge. Fix the guides. Capture the successful `curl $SERVICE_URL/health` output and the loaded web app as artifacts under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`, `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Depends on: Task 1.1, Task 1.3, Task 2.3
+  - Acceptance: the deploy succeeds; `/health` returns `"healthy":true`; the web app loads and can log in against the deployed backend; every guide correction is committed.
+
+- [ ] **Task 4.2**: Exercise the skill against the validated guide
+  - Description: Run the `deploy-gcp` skill in a fresh agent session against the same scratch project and confirm it reaches the same result, including the confirmation gate firing before any mutation. Note any step where the skill needed information the guide did not provide and fix the skill.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` plus mirrors
+  - Depends on: Task 3.3, Task 4.1
+  - Acceptance: the skill run produces a working deploy; the confirmation gate is observed in the transcript; `bun run rules:check` exits 0 after any skill edits.

package/dist/docs/versioned/57.17.0/tasks/deploy-to-vercel.md

@@ -0,0 +1,116 @@
+# Task List: Deploy to Vercel + `deploy-vercel` Skill
+
+See: [`docs/implementationPlans/deploy-to-vercel.md`](../implementationPlans/deploy-to-vercel.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` cover client configuration, auth origins, and websocket verification, all of which change shape with PR #869 (syncdb uses a websocket delta transport, so the websocket verification step becomes more load-bearing, not less). Re-verify marked tasks after #869.
+
+## Instructions for the implementing agent
+
+- Verify every Vercel configuration key against the current Expo documentation at `https://docs.expo.dev/guides/publishing-websites` and `https://docs.expo.dev/router/web/api-routes` before writing it. Vercel's config schema has changed across versions (`routes`/`builds` versus `rewrites`/`functions`) — document the current one and note the legacy form only if the repo's Expo version requires it.
+- Confirm the repo's Expo SDK version from the root `package.json` catalog before writing anything about server output or SSR. If it is below 55, the server-output section must be clearly marked as unavailable-until-upgrade and link PR #779.
+- Never write `corsOrigin: true` as a recommendation.
+- Run `bun run lint` before each commit; `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 0: Vercel topology spike (blocks Phase 1)
+
+Close every **Open TODO** in the IP before writing the how-to guide.
+
+- [ ] **Task 0.1**: Spike `@terreno/api` on Vercel
+  - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Treat [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the vendor contract. Record Fluid compute, max-duration disconnects, instance pinning (not affinity across reconnects), Redis for cross-instance fan-out, Function billing while sockets are open, cold starts, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
+  - Files: spike notes in PR / IP update; optional scratch `example-backend/vercel.json`
+  - Depends on: none
+  - Acceptance: IP questions **V1**, **V2**, and **V3** updated with a recorded decision; all IP Open TODO checkboxes checked or explicitly deferred with owner.
+
+- [ ] **Task 0.2**: Write Vercel Functions WebSocket operator docs
+  - Description: Create `docs/how-to/vercel-function-websockets.md` from the IP section **Vercel Functions WebSockets (Public Beta)**. Cite `https://vercel.com/docs/functions/websockets`; do not copy Vercel examples. Cover Fluid compute, HTTP Upgrade + Firewall/rate limits, websocket-only Socket.IO, `export default` HTTP server vs `TerrenoApp.start()`, instance pinning, max-duration reconnects, Redis (`RealtimeApp` adapter), Function billing while connected, and verification (`WEBSOCKETS_DEBUG`, DevTools WS, no polling fallback). Mark **beta**. Do not recommend all-in-one topology until V1 is decided. Link from `docs/how-to/README.md` and later from `docs/how-to/deploy-web-to-vercel.md` and `docs/how-to/websocket-integration.md`.
+  - Files: `docs/how-to/vercel-function-websockets.md` (new), `docs/how-to/README.md`, `docs/how-to/websocket-integration.md`
+  - Depends on: none (may ship before Task 0.1 closes; must re-verify against the Vercel page at ship time)
+  - Acceptance: every required operator section from the IP is present; the Vercel URL is cited; Next.js `experimental_upgradeWebSocket`, Bun, and Python examples are out of scope; `corsOrigin: true` is not recommended; listed in the how-to index.
+
+## Phase 1: Core how-to guide
+
+- [ ] **Task 1.1**: Write the Vercel deployment guide for `single` output
+  - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements. Link `docs/how-to/vercel-function-websockets.md` wherever sockets on Functions are mentioned.
+  - Files: `docs/how-to/deploy-web-to-vercel.md` (new), `docs/how-to/README.md`
+  - Depends on: `deployment-foundation` Phase 4, Task 0.2
+  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index; websocket Functions page is linked, not duplicated.
+
+- [ ] **Task 1.2**: `[RTK]` Add the verification section
+  - Description: Add a "Verify the deployment" section with four checks, each with the expected result and what failure means: (1) the root URL loads the app; (2) a deep link loads directly on refresh (proves the SPA rewrite works); (3) login succeeds, proving the API call reaches the backend and CORS is configured; (4) the websocket connects, proving realtime and live feature flags work. For check 4, give a concrete way to verify — browser devtools Network tab filtered to WS, or the client's debug logging flag (find the actual flag name in the client package, `WEBSOCKETS_DEBUG` at time of writing) — and explain that the app looks fine when this is broken, which is why it must be checked explicitly.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.1
+  - Acceptance: all four checks present with expected results; the websocket check names a real debug flag verified in the client source; the "looks fine while broken" warning is present.
+
+- [ ] **Task 1.3**: Add the reference `vercel.json`
+  - Description: Per IP question V3 (after Phase 0), add `vercel.json` to `example-frontend` and optionally `example-backend` if all-in-one wins. Wire to a real deployment only if V3 decision is **A**.
+  - Files: `example-frontend/vercel.json` (new), `example-frontend/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: the file is valid JSON and matches the guide's configuration exactly; the README explains its status; no new deploy workflow was added.
+
+## Phase 2: Preview deployments and origins
+
+- [ ] **Task 2.1**: `[RTK]` Document the preview-origin problem
+  - Description: Add a "Preview deployments" section covering: how Vercel assigns a unique origin per deployment; why that breaks CORS and Better Auth; a concrete `corsOrigin` pattern accepting production plus preview origins (write it as a function or regex matching the project's preview hostname shape — read `api/src/expressServer.ts` to confirm what shapes `corsOrigin` actually accepts before writing the example); the equivalent `trustedOrigins` configuration for Better Auth including native deep-link schemes; and OAuth redirect-URI registration per provider, noting that most providers do not support wildcards so preview OAuth needs either a fixed proxy origin or provider-specific handling. State that `corsOrigin: true` must not be used in production and explain the risk.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.2
+  - Acceptance: the `corsOrigin` example is a shape actually supported by `setupServer`, cited to source; `trustedOrigins` guidance matches `api/src/betterAuth.ts`; the OAuth wildcard limitation is stated; the `corsOrigin: true` warning explains the risk rather than just prohibiting it.
+
+- [ ] **Task 2.2**: `[RTK]` Document per-environment client configuration
+  - Description: Add a short section on Vercel's three environment scopes (production, preview, development) and how `EXPO_PUBLIC_API_URL` should differ across them — typically a production backend and a staging backend. Explain the consequence that follows from build-time inlining: each environment produces a different bundle, so a promoted preview build points at the preview backend unless rebuilt. Cross-reference the multi-environment checklist in `docs/explanation/deployment-baseline.md`. Add a note to `docs/reference/environment-variables.md` about Vercel's per-environment scoping.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 2.1
+  - Acceptance: the promotion pitfall is stated explicitly; the reference page notes Vercel scoping; both link the baseline checklist.
+
+## Phase 3: Advanced — server output
+
+- [ ] **Task 3.1**: Determine and record server-output availability
+  - Description: Read the `expo` version in the root `package.json` catalog and the state of PR #779 (Expo SDK 56 upgrade). Record in the guide whether `server` output is available today. If the SDK is below 55, the section must open with a clear "not available on the current Terreno Expo version" note plus a link to PR #779 and [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md).
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.1
+  - Acceptance: the stated Expo version matches the catalog exactly; availability is stated unambiguously; PR #779 is linked if applicable.
+
+- [ ] **Task 3.2**: Write the server-output section
+  - Description: Document the server-output path as advanced: setting `web.output` to `server` in the app config, the server entry file using `expo-server/adapter/vercel`, the `vercel.json` with `outputDirectory` pointing at the client output and a function including `dist/server/**`, and the `vercel-build` script. Verify the exact adapter import path, function config keys, and required file locations against the current Expo API-routes documentation. Add a clearly-marked caveat: responses through the Vercel adapter may be buffered rather than streamed, which breaks the SSE streaming used by `@terreno/ai`'s `/gpt/prompt` endpoint — link the upstream issue and state the workaround (keep AI streaming on the `@terreno/api` backend rather than routing it through Expo API routes on Vercel).
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 3.1
+  - Acceptance: every config key and import path verified against current Expo docs with the doc URL cited; the streaming caveat names the affected Terreno endpoint and gives a workaround; the section is labeled advanced.
+
+- [ ] **Task 3.3**: Disambiguate "Vercel AI SDK" across the repo
+  - Description: Grep for `Vercel` across `docs/`, package READMEs, and `.rulesync/rules/` (`rg -n "Vercel"`). For every occurrence referring to the AI library, ensure it reads "the Vercel AI SDK" and never bare "Vercel". Add a one-line note to `docs/reference/ai.md` clarifying that `@terreno/ai` is provider-agnostic via the Vercel AI SDK and that this is unrelated to Vercel hosting. Add the same clarification to the new deployment guide.
+  - Files: `docs/reference/ai.md`, `docs/how-to/deploy-web-to-vercel.md`, `.rulesync/rules/ai/00-ai.md`, `ai/README.md`, generated mirrors
+  - Depends on: Task 1.1
+  - Acceptance: `rg -n "Vercel" docs/ */README.md .rulesync/` shows every hit is either "the Vercel AI SDK" or a hosting context; `bun run rules:check` exits 0.
+
+## Phase 4: The `deploy-vercel` skill
+
+- [ ] **Task 4.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-vercel/SKILL.md` with frontmatter (`name`, a `description` naming trigger phrases "deploy to Vercel", "deploy the web app", "put this online", and `targets: ['*']`). Body: When to use / when not to use (explicitly: not for the backend); Detect (Expo Router app, `web.output` value, existing `vercel.json`, backend URL); Configure (`vercel.json` per output mode, `vercel-build` script for server output); Wire the backend (set `EXPO_PUBLIC_API_URL` per Vercel environment; print the exact `corsOrigin` and `trustedOrigins` changes the user must apply on the backend and stop until they confirm, since the agent cannot safely edit a deployed backend's config); Deploy (`vercel`, then `vercel --prod` behind a confirmation gate); Verify (the four checks from Task 1.2); Troubleshoot (link the reference). Include a prohibition on deploying to production without explicit confirmation and on setting `corsOrigin: true`.
+  - Files: `.rulesync/skills/deploy-vercel/SKILL.md` (new)
+  - Depends on: Task 2.1, Task 3.2
+  - Acceptance: frontmatter complete; the production-deploy confirmation gate is present; the verification step includes the websocket check; no command appears in the skill that is absent from the how-to guide.
+
+- [ ] **Task 4.2**: Add the troubleshooting reference
+  - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works (Fluid off, long-polling fallback, or max-duration close — link `docs/how-to/vercel-function-websockets.md`); and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
+  - Files: `.rulesync/skills/deploy-vercel/references/troubleshooting.md` (new)
+  - Depends on: Task 4.1
+  - Acceptance: at least six entries; each quotes a real error string or describes a precisely observable symptom; each names the file or setting to change.
+
+- [ ] **Task 4.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit all generated files. Do not hand-edit generated output.
+  - Files: generated skill mirrors
+  - Depends on: Task 4.1, Task 4.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-vercel` appears under every configured target directory.
+
+## Phase 5: Validation
+
+- [ ] **Task 5.1**: Deploy the example frontend to a scratch Vercel project
+  - Description: Following only `docs/how-to/deploy-web-to-vercel.md`, deploy `example-frontend` to a scratch Vercel project pointed at a real deployed backend. Run all four verification checks. Record and fix every gap in the guide. Capture screenshots of the deployed app (logged in, with a deep link loaded directly) and the devtools websocket connection, saved under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.3, Task 2.2
+  - Acceptance: all four verification checks pass on the deployed app; every guide gap found is fixed; screenshots captured including the websocket evidence.
+
+- [ ] **Task 5.2**: Exercise the skill in a fresh session
+  - Description: Run the `deploy-vercel` skill in a fresh agent session against a second scratch project and confirm it reaches a working deployment, that the production confirmation gate fires, and that it correctly stops to ask the user to apply backend CORS changes. Fix any step where the skill needed information it did not have.
+  - Files: `.rulesync/skills/deploy-vercel/SKILL.md` plus mirrors
+  - Depends on: Task 4.3, Task 5.1
+  - Acceptance: the skill run produces a working deployment; both stop-and-confirm points are observed in the transcript; `bun run rules:check` exits 0 after any edits.