@terreno/mcp 57.2.0 → 57.4.0

package/dist/docs/versioned/next/implementationPlans/create-terreno-app.md

@@ -0,0 +1,177 @@
+# Implementation Plan: create-terreno-app scaffolding CLI
+
+**Status:** In progress — all tasks Roast PASS; next: Brew  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1174  
+**Branch:** `cursor/create-terreno-app-ip-54bd`  
+**Owner:** unassigned  
+**Created:** 2026-09-10  
+**Program:** [B2B platform](b2b-platform-program.md) track D; [OSS launch](oss-launch-program.md) (zero-to-running DX)  
+**Depends on:** [`deployment-foundation`](deployment-foundation.md) (Complete)  
+**RTK deprecation flag:** **Partial** — scaffold output is Better Auth + `@terreno/syncdb`. Do not emit RTK Query collection CRUD.
+
+## Goal
+
+Ship a published **`create-terreno-app`** CLI that writes a running, deployable Terreno app to disk in one non-interactive command. `terreno_bootstrap_app` uses the **same generator**: local MCP writes when `targetDir` is set; hosted MCP never writes and returns a short CLI instruction plus the file dump.
+
+When this is done, an operator or agent can:
+
+1. Run `bunx create-terreno-app my-app --display-name "My App"` (or `npm create terreno-app`).
+2. Get `my-app/backend` + `my-app/frontend` (syncdb, Better Auth, admin, seed script, `.env` / `.env.example`, consumer `Dockerfile`, CI workflows, MCP config).
+3. Follow the printed README: replica-set MongoDB, `bun install`, `bun run seed`, `bun run sdk`, `bun run web`.
+4. Sign in as `test@example.com` / `testpassword123`.
+5. Deploy using existing how-tos; the scaffold Dockerfile and env examples match [deployment baseline](../explanation/deployment-baseline.md).
+
+## Non-Goals
+
+| Out | Why |
+| --- | --- |
+| GitHub template repo | Q1 — one generator; a template would drift |
+| Snapshot / clone of `example-*` | Q2 — examples include consent and monorepo-only Docker |
+| Interactive prompts | Q5 — agents need flags |
+| `bun install`, Mongo, or seed inside the CLI | Q5 — write files only |
+| Terraform / GCP / Vercel copy-paste into the tree | Q4 — README links to how-tos |
+| `--no-admin` | parked; v1 matches current bootstrap (admin included) |
+| Hosted MCP writing the server disk | Q3 — dump + CLI instruction only |
+| Copying `example-backend/Dockerfile` | that image builds this monorepo, not a consumer app |
+
+## Decisions
+
+| ID | Question | Decision |
+| --- | --- | --- |
+| Q1 | Delivery vehicle | Unscoped npm CLI `create-terreno-app` in this monorepo (not a template repo) |
+| Q2 | Generator source of truth | Extract `generateAllFiles` from `mcp-server/src/bootstrap.ts` into the CLI package; MCP imports it |
+| Q3 | Hosted vs local MCP | Write when local + writable `targetDir`; otherwise CLI instructions + file dump |
+| Q4 | Deployable in v1 | Consumer `Dockerfile` + `.env.example` + README links to deploy how-tos |
+| Q5 | CLI UX | `bunx create-terreno-app my-app --display-name "My App"`; refuse non-empty dir; `--yes` derives display name; no prompts; no install/seed |
+| Q6 | Package name | Unscoped `create-terreno-app` (`npm create terreno-app` / `bunx create-terreno-app`) |
+| Q7 | MCP write path | Optional `targetDir`; write only if set and allowed; else dump |
+| Q8 | Generated `@terreno/*` versions | Pin `^<create-terreno-app version>` (lockstep with published `@terreno/*`) |
+
+### Recorded assumptions (implementation detail)
+
+- Workspace directory: `create-terreno-app/` at the repo root (same pattern as `mcp-server/`).
+- One package: bin + exported `generateAllFiles` / `writeScaffold`. MCP depends on `create-terreno-app` via `workspace:*`.
+- Version pin: read `create-terreno-app/package.json` `version` (lockstep with other packages at release). Generated deps use `^${version}`, not `"latest"`.
+- Target layout: `<dir>/{backend,frontend,.github,README.md,Dockerfile,…}` matching today’s bootstrap file list, plus deploy files from Q4.
+- Env files: write gitignored `backend/.env` and `frontend/.env` with local-dev defaults **and** committed `.env.example` siblings (issue asked for env files; Q4 asked for examples).
+- Dockerfile: **consumer** backend image (`oven/bun:1-slim` or `oven/bun:1`, bind `0.0.0.0`, `PORT` from env, health on `/health`). Not the monorepo `example-backend/Dockerfile`.
+- Non-empty: refuse if the target exists and contains anything other than `.git` / `.gitignore`.
+- Hosted write guard: `terreno-mcp-local` sets `TERRENO_MCP_WRITE_SCAFFOLD=1`. HTTP hosted MCP never sets it and **ignores** `targetDir` even if passed.
+- `targetDir` must be an absolute path; local MCP resolves and writes `join(targetDir, appName)` only if that path is empty as above. Do not write `/` or home without an explicit `appName` subdirectory.
+- Publish: add `create-terreno-app` to tag publish (GitHub workflow + CircleCI `publish-package`) as an unscoped package. Changelog lockstep sentence gains this package.
+- npm name `create-terreno-app` must be available under the publishing npm user; if publish fails on name claim, that is an **access** blocker, not a redesign.
+
+## Architecture
+
+```
+bunx create-terreno-app my-app --display-name "My App"
+        │
+        ▼
+create-terreno-app (bin)
+  parse flags → writeScaffold({appName, appDisplayName, targetDir})
+        │
+        ▼
+generateAllFiles(args)  ◄──── terreno_bootstrap_app (MCP)
+        │                         │
+        │                         ├─ TERRENO_MCP_WRITE_SCAFFOLD=1 + targetDir
+        │                         │     → writeScaffold (local)
+        │                         └─ else → markdown: CLI command + file dump
+        ▼
+<dir>/backend + frontend + Dockerfile + .env(.example) + seed + CI + MCP config
+```
+
+Public seams Pick must test:
+
+| Seam | Behavior |
+| --- | --- |
+| `create-terreno-app` bin | Writes files; exits non-zero on missing `appName`, missing display name without `--yes`, or non-empty target |
+| `generateAllFiles` | Returns the file list; `@terreno/*` versions are `^` + package version; includes Dockerfile and `.env.example` |
+| `writeScaffold` | Creates files on disk; does not run `bun install` |
+| `handleBootstrapToolCall` | Dump path unchanged in shape (instructions mention CLI); write path creates files only when the env guard is set |
+
+## Models / APIs / Notifications / UI
+
+None. Scaffolded consumer apps keep the current bootstrap Todo + User + admin + Better Auth + syncdb shape.
+
+## CLI contract
+
+```bash
+bunx create-terreno-app <appName> --display-name <string> [--description <string>] [--mcp-server-url <url>] [--yes]
+npm create terreno-app <appName> -- --display-name <string>
+```
+
+| Flag | Required | Default |
+| --- | --- | --- |
+| `appName` (positional) | yes | — (kebab-case; used as directory and package names) |
+| `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
+| `--description` | no | empty |
+| `--mcp-server-url` | no | current bootstrap default |
+| `--yes` | no | off |
+
+Print next commands (install, Mongo replica set, seed, sdk, web) after a successful write. Do not execute them.
+
+## MCP contract
+
+`terreno_bootstrap_app` keeps `appName`, `appDisplayName`, `description`, `mcpServerUrl`, and adds:
+
+| Param | Required | Role |
+| --- | --- | --- |
+| `targetDir` | no | Absolute directory that will contain `<appName>/` |
+
+Write iff `targetDir` is set **and** `TERRENO_MCP_WRITE_SCAFFOLD=1`. Otherwise return the CLI one-liner plus the existing file dump (dump stays so hosted agents without shell can still materialize files).
+
+`terreno_bootstrap_ai_rules` stays in `@terreno/mcp` (not this CLI).
+
+## Phases
+
+1. **Extract generator** — move file generation + existing bootstrap app tests into `create-terreno-app`; MCP imports the package; versions become `^<cli version>`.
+2. **CLI writer** — bin, flags, `writeScaffold`, refuse non-empty, print next steps.
+3. **Deploy files** — consumer Dockerfile, `.env.example`, README deploy section linking baseline + GCP/web how-tos.
+4. **MCP delegate** — `targetDir` + write guard; dump mentions CLI; local write tests.
+5. **Docs, publish, skills** — tutorial/how-to/reference, `build-terreno-app` Phase 2, workspace + publish jobs, changelog fragment.
+
+## Feature Flags & Migrations
+
+None. Additive package + MCP params. Existing dump-only MCP clients keep working.
+
+## Not Included / Future Work
+
+- GitHub template generated from the same `generateAllFiles`
+- `--no-admin`, extra example slices, Windows-specific path docs
+- Running install/seed from the CLI
+- Provider-specific deploy folders
+
+## Files to Create / Modify
+
+| Path | Change |
+| --- | --- |
+| `create-terreno-app/` | New workspace package (src, tests, `package.json` bin, README) |
+| `mcp-server/src/bootstrap.ts` | Thin: args + MCP write/dump; import generator |
+| `mcp-server/src/__tests__/bootstrap.test.ts` | Dump + write-guard tests; generation assertions live in the CLI package |
+| `mcp-server/package.json` | `create-terreno-app` workspace dependency |
+| `package.json` | Workspace entry; optional root script |
+| `.github/workflows/publish-on-tag.yml` + CircleCI publish | Publish unscoped `create-terreno-app` |
+| `docs/tutorials/getting-started.md` | First path is the CLI; clone-examples remains secondary |
+| `docs/how-to/create-a-terreno-app.md` | Flags, layout, run, deploy pointers |
+| `docs/reference/mcp-server.md` | Delegate + `targetDir` |
+| `docs/README.md`, `docs/how-to/README.md` | Index the how-to and package |
+| `.rulesync/skills/build-terreno-app/SKILL.md` | Phase 2 uses the CLI (MCP dump is fallback) |
+| `changelog/unreleased/create-terreno-app.md` | Added |
+| `mcp-server/src/docs/upgrades/<next>.md` | If the release notes file for the next version exists, mention the CLI |
+
+## Task List
+
+[`docs/tasks/create-terreno-app.md`](../tasks/create-terreno-app.md)
+
+## Acceptance Criteria
+
+- [ ] `bunx create-terreno-app <tmp>/my-app --display-name "My App"` writes backend + frontend and exits 0
+- [ ] Non-empty target exits non-zero and writes nothing
+- [ ] Generated `@terreno/*` dependencies are `^` + the CLI package version, not `latest`
+- [ ] Scaffold includes consumer `Dockerfile`, `.env.example`, seed script, and README deploy links
+- [ ] `terreno_bootstrap_app` without write guard still returns markdown dump that names the CLI
+- [ ] `terreno_bootstrap_app` with write guard + `targetDir` writes the same files as the CLI
+- [ ] Hosted path cannot write even if `targetDir` is passed
+- [ ] Docs: getting-started, create how-to, MCP reference, build-terreno-app skill
+- [ ] Package is in the workspace and on the publish list
+- [ ] Focused bun tests cover CLI, generator versions, MCP dump vs write

package/dist/docs/versioned/next/implementationPlans/datatable-server-side-filtering.md

@@ -0,0 +1,219 @@
+# Implementation Plan: DataTable server-side filtering and search
+
+**Status:** Approved  
+**Branch:** `cursor/datatable-server-side-filtering-191d`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1177 (this feature **closes** that issue; implementation PRs use `Fixes #1177`)  
+**Task list:** [datatable-server-side-filtering.md](../tasks/datatable-server-side-filtering.md)  
+**Depends on:** —  
+**RTK deprecation flag:** Partial — `@terreno/ui` stays data-layer agnostic; AdminModelTable keeps RTK `useListQuery`; syncdb is out of scope  
+
+## Goal
+
+`DataTable` grows optional, controlled filter and search chrome that emits a JavaScript object of [modelRouter](../how-to/create-a-model.md) list params (`queryFields` equality, nested `$in` / `$regex` / `$gte`/`$lte`, date `field_gte`/`field_lte`, search `$or`). Parents pass that object to RTK, `fetch`, or any client. `AdminModelTable` uses the same UI and drops `AdminFilterDrawer`.
+
+## Non-Goals
+
+- Changing modelRouter list semantics or adding a new list query language.
+- Changing admin `q` / `buildAdminPartialSearchFilter` (ObjectId match stays on the backend).
+- Client-side filtering of the `data` prop.
+- Nested `$and`/`$or` query-builder UI.
+- Multi-select `$in` on admin `ref` (single ObjectId only).
+- Syncdb `useQuery` list wiring.
+- Making `Filter` itself universal (native uses a `Modal` sheet).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Emission | Presentational `onQueryChange(params)` JS object. Page/sort stay the existing callbacks. Parent merges. |
+| Operators | Text contains (`$regex` + `$options: "i"`, escaped); boolean equality; date `field_gte`/`field_lte`; number `{field: {$gte,$lte}}`; choice multi-select `{field: {$in: values}}`. |
+| Search | Generic: `$or` of escaped `$regex` on caller `searchFields`. Admin: toolbar string → `q` only (do not send `$or`; parser rejects top-level operators). |
+| Admin chrome | One surface: DataTable search + column filters. Remove `AdminFilterDrawer`. `ref` uses column `renderFilter`. |
+| Native | One “Filters” `Modal`/`ActionSheet` with every column filter + search. Web: per-column `Filter` popovers. |
+| Control | Filter/search state is controlled like `page` / `sortColumn`. Search debounce matches admin (existing delay). |
+| Admin parser | Extend `parseAdminListFilters` for choice `$in` (allowed values only) and text `{ $regex, $options: "i" }`. Keep rejecting undeclared `$or`. |
+
+## Architecture
+
+```
+DataTable (optional filter/search props)
+  web: header Filter popover per filterable column
+  native: one Filters sheet
+  → buildDataTableListQuery(state) → onQueryChange(params)
+
+Parent
+  generic modelRouter: pass params to list GET (qs.stringify nested ops)
+  AdminModelTable: strip $or; set q from search; keep $in / ranges / equality; RTK useListQuery
+```
+
+`@terreno/ui` must not import RTK, admin, or axios. Export `buildDataTableListQuery` and filter types next to DataTable.
+
+### Public types (sketch)
+
+```typescript
+interface DataTableColumnFilterChoiceOption {
+  label: string;
+  value: string;
+}
+
+interface DataTableColumnFilter {
+  field: string;
+  kind: "text" | "boolean" | "numberRange" | "dateRange" | "choice";
+  options?: DataTableColumnFilterChoiceOption[]; // choice
+  renderFilter?: (args: {
+    field: string;
+    value: unknown;
+    onChange: (value: unknown) => void;
+  }) => React.ReactNode;
+}
+
+interface DataTableQueryParams {
+  [field: string]: unknown;
+  $or?: Array<Record<string, unknown>>;
+}
+
+interface DataTableProps {
+  // existing page / sort / data ...
+  search?: string;
+  searchFields?: string[];
+  onSearchChange?: (search: string) => void;
+  filterValues?: Record<string, unknown>;
+  onFilterValuesChange?: (next: Record<string, unknown>) => void;
+  onQueryChange?: (params: DataTableQueryParams) => void;
+}
+```
+
+`DataTableColumn` gains optional `filter?: DataTableColumnFilter`. Omit `filter` → no column control (today’s table). Omit search props → no search box.
+
+`onQueryChange` fires when search (debounced) or filters change. It does **not** include `page`, `limit`, or `sort`.
+
+### Query object contract
+
+| UI | Wire |
+|----|------|
+| Search (generic) | `$or: [{field: {$regex: escaped, $options: "i"}}, ...]` for `searchFields` |
+| Text column | `{field: {$regex: escaped, $options: "i"}}` |
+| Boolean | `{field: true \| false}`; unset omits the key |
+| Date range | `field_gte` / `field_lte` ISO strings (modelRouter Date merge) |
+| Number range | `{field: {$gte?: number, $lte?: number}}` |
+| Choice (one or many) | `{field: {$in: string[]}}` even for a single value |
+| Empty filter | key omitted |
+
+Escape every user regex with the same rules as `escapeRegexLiteral` in `admin-backend/src/adminTextSearch.ts` (copy into ui; do not import admin-backend).
+
+### Native vs web
+
+| Platform | Chrome |
+|----------|--------|
+| Web | Toolbar `TextField` search; per-column header icon opens existing `Filter` (Apply/Clear). Choice uses `MultiselectField`. |
+| Native | Toolbar search + one “Filters” control opening `Modal` (or existing mobile sheet pattern from admin: `ADMIN_FILTER_MOBILE_BREAKPOINT`). Same `filterValues` / `onQueryChange`. |
+
+### Admin adoption
+
+`AdminModelTable` maps `modelConfig.filters` onto `DataTableColumn.filter`:
+
+| Admin kind | DataTable kind |
+|------------|----------------|
+| `text` | `text` (contains; documented behavior change from exact match) |
+| `boolean` | `boolean` |
+| `dateRange` | `dateRange` |
+| `choice` | `choice` + `options` from `choices` |
+| `ref` | `choice`-shaped slot with `renderFilter` wrapping `AdminRefField` (single id) |
+
+`buildAdminListQueryParams` consumes DataTable state:
+
+1. Copy filter params except `$or`.
+2. If `searchFields.length && search.trim()`, set `q`.
+3. Keep `limit`, `page`, `sort`.
+
+Delete `AdminFilterDrawer` usage from the table. Keep the module only if another screen still imports it; otherwise remove export after table tests prove the new path.
+
+`parseAdminListFilters` today rejects objects on choice/text and any top-level `$` key. This slice:
+
+- Parses `role: { $in: ["staff", "admin"] }` when every value is in `choices`.
+- Parses text `{ $regex: string, $options: "i" }` (regex already escaped by the client).
+- Still errors on top-level `$or` / `$and`.
+
+### Compatibility
+
+Existing `DataTable` callers with no filter/search props are unchanged (no chrome, no callbacks).
+
+## Models
+
+None.
+
+## APIs
+
+No new HTTP routes. Consumers keep `GET` list with existing `queryFields`. Admin list still uses `q` for search.
+
+## Notifications
+
+None.
+
+## UI
+
+Demo story: filterable columns + search, mock `onQueryChange` log / JSON. Admin SPA / example admin: Todos or Users list — search, boolean, choice `$in`, date range, ref via custom renderer.
+
+## Phases
+
+1. **Tracer:** query helper + DataTable tests (no fetch).
+2. **Chrome:** web popovers + native sheet + demo story.
+3. **Admin parser + table:** `$in` / text regex; drop drawer.
+4. **Docs:** reference, how-to, seed links, generated component props.
+
+## Feature Flags & Migrations
+
+No flag. Admin text filters become contains. Call out in CHANGELOG and admin how-to.
+
+## Activity Log & User Updates
+
+- 2026-09-10: Grow approved; next Pick Task 1.1.
+
+## Not Included / Future Work
+
+- Multi-select `$in` on `ref`.
+- Client-side filter of `data`.
+- Nested boolean query builder.
+- Universal `Filter` popover on native.
+- Syncdb collection queries.
+
+## Files to Create / Modify
+
+| Path | Change |
+|------|--------|
+| `ui/src/Common.ts` | Filter types on `DataTableColumn` / `DataTableProps` |
+| `ui/src/dataTableListQuery.ts` (new) | `buildDataTableListQuery`, regex escape |
+| `ui/src/DataTable.tsx` | Search + column filters + native sheet |
+| `ui/src/DataTable.test.tsx` | Query emission tests |
+| `demo/stories/DataTable.stories.tsx` | Filter/search demo |
+| `admin-backend/src/filterParser.ts` | Choice `$in`, text `$regex` |
+| `admin-backend/src/filterParser.test.ts` | New cases |
+| `admin-frontend/src/AdminModelTable.tsx` | Wire DataTable; remove drawer |
+| `admin-frontend/src/adminModelListQueryParams.ts` | Map search → `q`; pass `$in` |
+| `admin-frontend/src/AdminFilterDrawer.tsx` | Remove if unused |
+| `docs/reference/ui.md` | DataTable filter contract |
+| `docs/how-to/admin-add-model.md` | Filters live on the table; text is contains |
+| `docs/reference/admin-frontend.md` | AdminModelTable |
+| `docs/explanation/admin-interface.md` | Drop drawer as the list filter UI |
+| `docs/explanation/roadmap-seed-issues.md` | IP/task links |
+| `CHANGELOG.md` | Added |
+
+Generated `docs/reference/components/` DataTable props via `ui` `bun run types` / `website:generate` in the docs task.
+
+## Task List
+
+[datatable-server-side-filtering.md](../tasks/datatable-server-side-filtering.md)
+
+## Acceptance Criteria
+
+- [ ] DataTable with no filter/search props matches current sort/page-only UI (unit test).
+- [ ] `buildDataTableListQuery` emits escaped `$regex` `$or` for search and `{field: {$in}}` for multi choice (`bun test ui/src/dataTableListQuery.test.ts` or colocated).
+- [ ] Interacting with web column Filter Apply calls `onQueryChange` with the contract table (`DataTable.test.tsx`).
+- [ ] Native “Filters” sheet applies the same object (`DataTable.test.tsx` with platform mock or sheet testIDs).
+- [ ] Admin list: search still hits `q`; choice multi-select reaches Mongo `$in`; `parseAdminListFilters` rejects top-level `$or` (`filterParser.test.ts` + `AdminModelTable.test.tsx`).
+- [ ] `AdminFilterDrawer` is not rendered on `AdminModelTable`.
+- [ ] Demo story shows search + at least text, boolean, date, and choice filters.
+- [ ] Docs: `docs/reference/ui.md`, admin how-to/reference, generated component props, CHANGELOG.
+- [ ] `bun run analyze:full` clean; frontend verification per `verify-ui-changes` (demo + admin list).

package/dist/docs/versioned/next/implementationPlans/deploy-to-vercel.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
 
-**Status:** Draft — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Status:** Approved — open Vercel spike TODOs; other decisions recorded (2026-07-29)
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1012
 **Priority:** High
 **Effort:** Big batch
@@ -38,7 +38,8 @@ Give Terreno the fastest possible "my app is on the internet" path, and a skill
 
 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? Document runtime limits, cold starts, and whether session affinity is available.
+- [ ] **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.
@@ -121,14 +122,51 @@ New skill at `.rulesync/skills/deploy-vercel/SKILL.md`:
 
 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.
-1. **How-to guide** — `single` output, clone → public URL (topology per V1 outcome).
+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.
@@ -148,6 +186,7 @@ None.
 **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)**
@@ -155,6 +194,11 @@ None.
 - `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).
@@ -163,6 +207,7 @@ See [`docs/tasks/deploy-to-vercel.md`](../tasks/deploy-to-vercel.md).
 
 - [ ] 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.

package/dist/docs/versioned/next/implementationPlans/deployment-foundation.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Deployment Foundation
 
-**Status:** Draft — blocking questions open
+**Status:** Complete — blocking questions resolved 2026-07-29; all tasks executed
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1011
 **Priority:** High
 **Effort:** Big batch

package/dist/docs/versioned/next/implementationPlans/describe-model-schema.md

@@ -0,0 +1,124 @@
+# `describeModel()` schema metadata
+
+**Status:** Approved — 2026-08-24  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [api.md](../reference/api.md) OpenAPI / model conventions, [create-a-model.md](../how-to/create-a-model.md), [pluggable-database-sqlite.md](pluggable-database-sqlite.md) (adapters need shared path metadata; this is that core, not a second DSL)  
+**Task list:** [describe-model-schema.md](../tasks/describe-model-schema.md)  
+**Depends on:** none (can parallel unified-mutation-executors)  
+**Consumed by:** OpenAPI (`getOpenApiSpecForModel`), admin `extractFieldMeta`, MCP `schemaGenerator`
+
+## Goal
+
+Walk each Mongoose schema **once**. OpenAPI, admin field widgets, and MCP Zod tools consume a `ModelDescription` instead of each re-interpreting `schema.paths` / mongoose-to-swagger / OpenAPI `$ref` hacks.
+
+Evidence: `api/src/populate.ts` `getOpenApiSpecForModel` uses mongoose-to-swagger; `admin-backend/src/adminApp.ts` `extractFieldMeta` (~469) walks OpenAPI properties; `api/src/mcp/schemaGenerator.ts` walks `schema.paths` into Zod. `AdminFieldMeta` (backend) and `AdminFieldConfig` (frontend) duplicate shapes.
+
+## Non-Goals
+
+- Replacing Mongoose as the authoring format (SQLite IP D1).
+- Generating TypeScript document types (five-type pattern stays hand-written).
+- Unifying admin frontend/backend **component** trees; only the **field descriptor** they share.
+- MCP operator-hint copy and OpenAPI prose beyond field facts.
+- Widget registry / admin screen router ([admin-improvements.md](admin-improvements.md) owns AdminApp carve-up).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — `describeModel(model, {populatePaths?, extraProperties?}) → ModelDescription`.** Surfaces format that graph. Not B (OpenAPI JSON as the canonical model) — OpenAPI drops refs/widget hints MCP and admin need; it is a **view**. |
+| Field graph | Paths with `kind`, `required`, `description`, `enum`, `ref`, `isArray`, `item` (nested description or primitive kind), `system` (created/updated/deleted/_id/__v). |
+| Write exclusions | `writableOnCreate` / `writableOnUpdate` derived from the same rules MCP `SYSTEM_FIELDS` + router `validation` / field views **when those options are passed in**. `describeModel` on the model alone does not know field views; `describeModelForRouter(model, options)` adds write masks. Two functions, one module. |
+| OpenAPI | `getOpenApiSpecForModel` builds swagger **from** `ModelDescription` (or merges m2s output with description for populate — Phase 2 may keep m2s for compatibility then replace). Compatibility: existing OpenAPI snapshots in `example-backend` / api tests must stay equal or have an explicit, reviewed diff. |
+| Admin | `extractFieldMeta` maps `ModelDescription` (+ OpenAPI only if still required for nested quirks). Prefer description → `AdminFieldMeta` directly. |
+| MCP | `mongooseTypeToZod` maps `FieldDescription`, not raw SchemaType. |
+| Compatibility | Public OpenAPI HTTP body stable. Admin `/admin/config` field types stable unless a bugfix is documented. |
+
+## Interface shapes considered
+
+**A (chosen).** Canonical graph in `@terreno/api`, adapters in OpenAPI/admin/MCP.
+
+**B (rejected).** Canonical OpenAPI document. Admin already loses `ref` (see `format === "objectid"` comment in `extractFieldMeta`). MCP would parse OpenAPI into Zod — another shallow wrapper.
+
+## Architecture
+
+```
+Mongoose schema.paths
+        │
+        ▼
+describeModel / describeModelForRouter
+        │
+        ├──► getOpenApiSpecForModel (components, populate)
+        ├──► Admin extractFieldMeta /config
+        └──► MCP Zod tool schemas
+```
+
+Deletion test: deleting `extractFieldMeta`’s OpenAPI walk and MCP’s SchemaType switch **into** `describeModel` concentrates “what is this field?”. Splitting `adminApp.ts` without this only moves the walk.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/explanation/` new short page `schema-metadata.md` | Why one descriptor; OpenAPI/admin/MCP are views. |
+| `docs/reference/api.md` | `describeModel` export, field kinds table. |
+| `docs/how-to/create-a-model.md` | Field `description` still required; it feeds the descriptor. |
+| Admin reference | Config fields come from `describeModel`, not a second OpenAPI parse. |
+
+## Testing
+
+Seam: `describeModel` snapshots for a fixture model (string, enum, bool, date, ObjectId ref, array of primitives, subdocument array, Mixed).
+
+Surface tests:
+
+- OpenAPI: existing `openApi.test.ts` / example-backend snapshot — update only with reviewed diffs.
+- MCP: tool schema tests compare Zod shape to descriptor, not SchemaType.
+- Admin: `extractFieldMeta` tests (or new) for ref + enum + required.
+
+No mongoose-schema-safety schema **changes**; this reads schemas.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| OpenAPI snapshot churn | Phase 1: descriptor + tests; Phase 2: OpenAPI switches with snapshot review as its own task. |
+| Mixed / virtuals / populate | Populate stays a `getOpenApiSpecForModel` concern using `populatePaths`; descriptor records `ref` on the local path only. |
+| Admin widget heuristics | Keep widget choice in admin; descriptor supplies type/enum/ref only. |
+
+## Phases
+
+1. `describeModel` + snapshots; MCP Zod uses it (highest drift vs SchemaType).
+2. Admin `extractFieldMeta` uses it.
+3. OpenAPI uses it; delete duplicate walks; docs.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- SQLite adapter reading `ModelDescription` for DDL ([pluggable-database-sqlite.md](pluggable-database-sqlite.md) follow-on).
+- Generating admin `AdminFieldConfig` types from the same module published to the frontend (shared type package later).
+
+## Files to Create / Modify
+
+- `api/src/schemaMetadata.ts` (new)
+- `api/src/schemaMetadata.test.ts`
+- `api/src/mcp/schemaGenerator.ts`
+- `api/src/populate.ts` (`getOpenApiSpecForModel`)
+- `admin-backend/src/adminApp.ts` (`extractFieldMeta`)
+- `api/src/index.ts` export
+- Docs listed above
+
+## Acceptance Criteria
+
+- [ ] One module describes paths; MCP, admin, and OpenAPI do not walk `schema.paths` independently.
+- [ ] Fixture snapshot covers enum, ref, array, subdocument, system fields.
+- [ ] OpenAPI compatibility tests pass (or reviewed snapshot update).
+- [ ] Admin config still exposes type, required, enum, ref, description.
+- [ ] MCP create tool schemas still hide system fields.
+- [ ] Docs explain the descriptor; `update-docs` pages listed above.
+
+## Task List
+
+[docs/tasks/describe-model-schema.md](../tasks/describe-model-schema.md)

package/dist/docs/versioned/next/implementationPlans/design-blend-skill.md

@@ -1,6 +1,8 @@
 # Implementation Plan: design-blend Skill
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1083
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1083  
+**Status:** Complete
+
 ## Goal
 
 Create a new `design-blend` skill that converts a Claude design file into a Terreno implementation blueprint and execution steps, with these hard constraints:

package/dist/docs/versioned/next/implementationPlans/docs-reference-coverage.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Reference Documentation Coverage
 
-**Status:** Draft — blocked on PR #869
+**Status:** In progress — remaining README, sanitization, and docs-audit work
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1009
 **Priority:** High
 **Effort:** Big batch