@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/implementationPlans/charts-and-dashboards.md

@@ -0,0 +1,246 @@
+# Implementation Plan: Charts and dashboard primitives
+
+**Status:** In progress  
+**Branch:** `cursor/charts-and-dashboards-2bc3`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1175 (this feature **closes** that issue; implementation PRs use `Fixes #1175`)  
+**Task list:** [charts-and-dashboards.md](../tasks/charts-and-dashboards.md)  
+**Depends on:** —  
+**RTK deprecation flag:** None  
+**Program:** [B2B platform](b2b-platform-program.md) track E  
+
+## Goal
+
+Ship themed, universal chart and dashboard layout primitives in `@terreno/ui` so B2B
+admin and product screens can compose line, bar, area, and donut charts without a
+third-party chart API leaking into app code.
+
+Rendering is **owned SVG** on `react-native-svg` (already used for icons). Public
+components are `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and `DashboardGrid`.
+Proof is demo stories plus docs. No example-frontend screen and no comms-dashboard
+wiring in this slice.
+
+## Non-Goals
+
+- `victory-native`, Skia canvas charts, `react-native-gifted-charts`, `react-native-chart-kit`, WebView/ECharts.
+- Example-frontend dashboard screen.
+- Comms admin stats charts (comms IP already defers to this item; a later comms task consumes these primitives).
+- Zoom, pan, brush, stacked/grouped multi-series cartesian, combo charts, maps, heatmaps.
+- A new `DashboardCard` (reuse `Card`).
+- Dark-mode palette work (`dark-mode-theme`); charts read `useTheme()` so they follow when that ships.
+- Implementing the approved composition grammar in the visual-regression slice (Phase 6).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Public exports | Named `LineChart`, `BarChart`, `AreaChart`, `DonutChart`. No `Chart` dispatcher. Remove the commented `export * from "./Chart"` stub. |
+| First consumer | Demo stories only. |
+| Interactivity | Legend plus press (native) / hover (web) tooltip. No zoom/pan. |
+| Dashboard layout | `DashboardGrid` with responsive column counts; children are existing `Card`s. |
+| Engine | Owned `react-native-svg` primitives in `@terreno/ui`. Not victory-native, not a wrap. |
+| Series model | Single series this slice: `data: {label: string; value: number}[]`. Donut uses the same points as slices (`color?` optional per slice). Multi-series cartesian is future work. |
+| Math | Private `d3-scale` + `d3-shape` in `ui/` only (single-package; raw versions, not catalog unless a second package needs them). Do not export d3 types. |
+| Axis labels | Overlay `@terreno/ui` `Text` (theme fonts). Do not draw axis copy with SVG `<Text>` as the primary path. |
+| Tooltip chrome | Terreno `Tooltip` when a mark can be the child; otherwise an internal overlay `Box`+`Text` at the hit point with the same copy (`label: value`). |
+| Empty / loading | Empty `data` → `Text` (`emptyText`, default `"No data"`). `loading` → `Spinner`. |
+| Colors | Theme tokens: series/slice fills from `primary` / `secondary` / `accent` / `error` (and tints). Grid/axis from `border` / `text.secondaryDark`. Optional `color` on a donut slice overrides. |
+| Packaging | Chart components join the existing lazy root boundary (`heavyOptionalExports`). `DashboardGrid` stays eager (layout only). Subpaths `@terreno/ui/LineChart` etc. remain direct. |
+| Dates | `label` is a display string. Callers format with Luxon before passing. No `Date` objects in props. |
+| Visual proof | Rendered PNG goldens via `bun run ui:charts:compare`, not React JSON snapshots. |
+
+## Architecture
+
+```
+@terreno/ui
+  LineChart / BarChart / AreaChart / DonutChart
+    ChartFrame (Box + sized Svg + overlay Text axes + legend + tooltip)
+      charts/scales.ts   d3-scale linear / band (private)
+      charts/paths.ts    d3-shape line / area / arc (private)
+      charts/theme.ts    useTheme → stroke / fill / grid / axis
+  DashboardGrid
+    Box wrap + width percent from breakpoint column count
+```
+
+### Public props (minimal)
+
+```typescript
+interface ChartPoint {
+  label: string;
+  value: number;
+  color?: string; // donut slice override
+}
+
+interface CartesianChartProps {
+  data: ChartPoint[];
+  height?: number; // default 200
+  legendLabel?: string;
+  emptyText?: string;
+  loading?: boolean;
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+interface DashboardGridProps {
+  columns?: {sm?: number; md?: number; lg?: number}; // default 1 / 2 / 3
+  gap?: SignedUpTo12;
+  children: React.ReactNode;
+  testID?: string;
+}
+```
+
+Cartesian charts share `CartesianChartProps`. `DonutChart` uses the same `data` as slices
+(ignore `legendLabel`; legend is one row per slice).
+
+Layout: `Box` around an `Svg` with a stable `viewBox`. Plot geometry is SVG. Tick labels
+sit in `Box` rows/columns around the plot so Nunito/Titillium apply. Legend is a wrapping
+`Box` of color swatch + `Text` below the plot.
+
+Hit testing: map press/hover location to the nearest point (cartesian) or slice (donut).
+Web uses hover in; native uses press. Tooltip copy is `{label}: {value}` (no extra
+formatting unless `value` is shown with a caller-supplied `formatValue?: (n) => string`,
+default `String(n)`).
+
+### File layout
+
+| Path | Role |
+|------|------|
+| `ui/src/charts/types.ts` | `ChartPoint` and shared props (not a public barrel) |
+| `ui/src/charts/scales.ts` | Private scale helpers + unit tests |
+| `ui/src/charts/paths.ts` | Private path helpers + unit tests |
+| `ui/src/charts/theme.ts` | Theme → paint |
+| `ui/src/charts/ChartFrame.tsx` | Shared frame (not exported from package root) |
+| `ui/src/LineChart.tsx` | Public line |
+| `ui/src/BarChart.tsx` | Public bar |
+| `ui/src/AreaChart.tsx` | Public area |
+| `ui/src/DonutChart.tsx` | Public donut |
+| `ui/src/DashboardGrid.tsx` | Public grid |
+| `ui/src/index.tsx` | Eager `DashboardGrid`; lazy chart named exports |
+| `ui/src/lazyBoundaries/heavyOptionalExports.tsx` | Chart lazy factories |
+| `ui/package.json` | `d3-scale`, `d3-shape` (+ types) |
+
+No `ui/src/charts/index.ts` barrel (Biome `noBarrelFile`).
+
+### Dependencies
+
+`react-native-svg` is already a `ui` dependency. Add `d3-scale` and `d3-shape` to `ui/`
+only. Do not add `victory-native`. Import-benchmark and `RootImportRegression` must show
+chart implementation modules off the cold `@terreno/ui` root graph (same pattern as
+`GPTChat`).
+
+### Chart visual regression
+
+JSON snapshots of the React tree do not prove paint. The demo hosts
+`/demo/chart-visual-gallery` (easy → hard fixtures in
+`demo/chartVisual/fixtureCatalog.ts`). `bun run ui:charts:compare` launches Chromium,
+screenshots each `[data-testid=chart-visual-<id>]`, and pixel-diffs against
+`demo/rendered-snapshots/<id>.png`. Failures write
+`demo/chart-visual-output/{actual,diff,report.json}`. Agents follow
+`review-chart-visuals`. `bun run ui:charts:update-snapshots` rewrites goldens after an
+intentional visual change.
+
+### Testing
+
+Bun + `@testing-library/react-native` + `renderWithTheme`. Assert:
+
+- Empty and loading states by text / `testID`.
+- One mark per `data` item (`testID` suffix by index or label).
+- Tooltip copy after press (native) or hover where the test renderer allows.
+- Legend label / slice labels.
+- Scale/path helpers with numeric fixtures (no renderer).
+- `DashboardGrid`: child count and `testID`; width math via style when observable.
+
+Do not mock `react-native-svg` unless a helper is untestable; prefer querying `testID`s
+on wrapper `Box`es if SVG nodes are opaque in happy-dom.
+
+### Demo
+
+Stories: `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `DashboardGrid` (grid of
+`Card`s each holding a chart). Register in `demoConfig.tsx` so the demo coverage
+allowlist passes. Static fixture data only.
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+Universal React Native + web. No admin-v2 `home.slots` work. Comms dashboard is a future
+consumer, not this IP.
+
+## Phases
+
+1. **Tracer:** private scales/paths/theme + `LineChart` (tooltip, legend, empty/loading) +
+   tests + demo story + reference stub.
+2. **Sibling charts:** `BarChart`, `AreaChart`, `DonutChart` on the same frame.
+3. **DashboardGrid** + composing demo story.
+4. **Packaging + docs:** lazy root exports, import regression, Diátaxis pages, TypeDoc,
+   changelog fragment, seed links, rules/skill mentions.
+5. **Rendered visual regression:** gallery + compare command + `review-chart-visuals` skill.
+6. **Composition grammar (approved, not this slice):** declarative children (`Chart`,
+   `ChartTitle`, cartesian/polar, series, axes, grid, legend, tooltip, data labels,
+   reference line/band). Keyed rows + `dataKey`. Facades stay additive `{label,value}`.
+   Tooltip overlay + footer (facades keep footer). Colors: theme tokens + hex.
+   `data`/`xKey` on `Chart`/`ChartCartesian`/`ChartPolar`. Grouped bars unless `stackId`.
+
+## Feature Flags & Migrations
+
+None. Additive public components. Not a major.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Composition grammar (Phase 6) — recorded Grow decisions; implement on a follow-up Pick.
+- Multi-series cartesian beyond `dataKey` / `stackId` once the grammar ships.
+- Wiring `CommsDashboardScreen` charts to the stats endpoint.
+- Example-frontend dashboard.
+- Zoom/pan.
+- Victory/Skia renderer if a later product needs GPU-scale series (thousands of points).
+
+## Files to Create / Modify
+
+See the task list. Docs created or updated in-slice:
+
+- `docs/how-to/charts-and-dashboards.md` (create)
+- `docs/how-to/README.md` (link)
+- `docs/explanation/charts.md` (create — why owned SVG, not victory-native)
+- `docs/explanation/README.md` (link)
+- `docs/reference/ui.md` (Display exports + example)
+- `docs/explanation/roadmap-seed-issues.md` (`charts-and-dashboards` IP/task links)
+- `docs/implementationPlans/b2b-platform-program.md` / `comms-admin-dashboard.md` (pointer only if they still say “charts later” without a path)
+- `.rulesync/rules/ui/00-ui.mdc` (export list)
+- `changelog/unreleased/charts-and-dashboards.md`
+- TypeDoc props so `docs-audit` is clean after `bun run website:generate`
+
+## Task List
+
+[docs/tasks/charts-and-dashboards.md](../tasks/charts-and-dashboards.md)
+
+## Acceptance Criteria
+
+- [ ] `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and `DashboardGrid` are
+      importable from `@terreno/ui` and from component subpaths.
+- [ ] Charts render with `react-native-svg`; `victory-native` is not a dependency.
+- [ ] Single-series `{label, value}[]` is the only cartesian data contract.
+- [ ] Empty and loading states are visible; tooltip + legend work (press native, hover web).
+- [ ] Theme tokens drive default paints; overlay axis labels use `Text`.
+- [ ] Chart implementations are lazy on the package root; `DashboardGrid` is eager.
+- [ ] Focused bun tests cover scales, empty/loading, mark counts, tooltip copy, grid columns.
+- [ ] Demo stories exist for all five exports and are registered.
+- [ ] How-to, explanation, and `docs/reference/ui.md` describe the API; TypeDoc props exist.
+- [ ] `bun test` (ui affected files), `bun run compile` in `ui`, and demo compile succeed.
+- [ ] Frontend verification: demo stories exercised on web; artifacts on the implementation PR.
+- [x] `bun run ui:charts:compare` matches `demo/rendered-snapshots/` for the gallery.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| happy-dom SVG nodes hard to query | `testID` on `Box` wrappers around marks; helper unit tests for path strings |
+| Hover vs press tooltip | Shared hit-test helper; platform-specific event wiring; tests cover press at minimum |
+| Root import size | Lazy boundary + `performance:imports` / `RootImportRegression` |
+| d3 + RN types | Confine d3 to `charts/scales.ts` and `charts/paths.ts` |

package/src/docs/versioned/next/implementationPlans/comms-admin-dashboard.md

@@ -25,8 +25,9 @@ uses (`addAiRequestsExplorerRoutes`) but with mutation (retry) and much richer f
 
 - Building the messages themselves (comms-abstraction) or provider integrations (adapter
   IPs).
-- Charts beyond simple count cards — themed chart components arrive with
-  `charts-and-dashboards`; the stats endpoint is designed so charts can be added then.
+- Charts beyond simple count cards — themed chart components are in
+  [`charts-and-dashboards.md`](charts-and-dashboards.md); the stats endpoint is designed so
+  those primitives can be added later.
 - Broadcast/bulk *composition* from admin (sending new messages, campaign tooling).
 - User-facing notification history (`notification-center` item).
 - Cross-service log aggregation (Sentry/Cloud Logging stay the deep-debug tools; the
@@ -145,7 +146,7 @@ Every retry is itself a `CommsMessage` row (with `retriedFromId` and the acting
 
 - Failure-rate alerting (Slack/Google Chat notifier when a provider's failure rate spikes)
   — small follow-up once `/comms/stats` exists.
-- Charts on the stats endpoint (`charts-and-dashboards`).
+- Charts on the stats endpoint — consume [`charts-and-dashboards`](charts-and-dashboards.md) primitives.
 - Editing a message before retry ("retry with edits").
 - Automatic scheduled retries with backoff — arrives with `job-queues`; this IP is
   explicitly *manual, admin-driven* retry.

package/src/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/src/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).