@terreno/mcp 57.18.0 → 57.20.0

package/dist/docs/versioned/57.18.0/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/TerrenoLabs/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/57.18.0/implementationPlans/dashboard-chart-parity.md

@@ -0,0 +1,275 @@
+# Implementation Plan: Dashboard chart parity
+
+**Status:** Approved — 2026-09-25  
+**Branch:** `cursor/dashboard-chart-parity-8a50`  
+**Owner:** —  
+**Created:** 2026-09-24  
+**Roadmap issue:** — (create via `roadmap-item` after this IP is Approved; follow-up to [#1175](https://github.com/TerrenoLabs/terreno/issues/1175))  
+**Task list:** [dashboard-chart-parity.md](../tasks/dashboard-chart-parity.md)  
+**Depends on:** [charts-and-dashboards.md](charts-and-dashboards.md) (shipped Phases 1–5)  
+**RTK deprecation flag:** None  
+**Program:** [B2B platform](b2b-platform-program.md) track E  
+
+## Goal
+
+Make `@terreno/ui` able to compose an ops dashboard like the “How’s it going?”
+reference: KPI scorecards with comparison sparklines, titled chart cards with period
+badges, multi-series lines, donut hole labels, spanning grids, and Looker-like table
+chrome — without copying Looker paint, and without requiring the Chart children grammar.
+
+App authors rebuild that page from first-class primitives (`Scorecard`, `SparklineChart`,
+`ChartCard`, spanning `DashboardGrid`, additive chart facades, `DataTable` extras). Proof
+is a demo gallery fixture of the reference layout plus rendered PNG goldens.
+
+## Non-Goals
+
+- Pixel-identical Looker colors, fonts, or screenshot matching of the PDF JPEG.
+- Shipping a date-range picker. Period badges may call `onPeriodPress`.
+- Variable `DataTable` row height (would break virtualization).
+- Dual-period numbers inside one table cell (current + previous stacked in the same cell).
+- Replacing `{label, value}[]` facades with composition-only `Chart*` children.
+- Implementing the Phase 6 composition grammar in this slice (still future work on
+  `charts-and-dashboards`).
+- Example-frontend screen, comms dashboard wiring, zoom/pan, combo charts, maps, heatmaps.
+- Cross-chart filtering / drill-down.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Scope | All chart surfaces, headers, period badges, KPI cards, spanning grid, and the table chrome named below. Not the whole PDF pixel-for-pixel. |
+| Easy-build surface | `ChartCard` (title + period badge + child) + `Scorecard` + spanning `DashboardGrid`. |
+| Scorecards | Dedicated `Scorecard` facade plus reusable `SparklineChart`. |
+| Comparison | First-class `comparisonData` with dotted stroke on sparkline and optional cartesian overlay. |
+| Facades vs grammar | Keep `LineChart` / `BarChart` / `AreaChart` / `DonutChart`. Add additive props. This dashboard must not require a composition tree. |
+| Visual language | Capabilities are theme-configurable. Default paint stays Terreno tokens, not a Looker preset. |
+| Responsive grid | Configurable `span` on items. Reference fixture: KPI row 5→2→1; lower chart row 3→1. |
+| Tables | Same IP. After the chart tracer: period header groups, sticky totals row, `1–50 of N` range status. Reuse existing pin/sort/pagination. |
+| Wrapped names | Wrap up to two lines inside the existing `rowHeight`. Keep virtualization. |
+| Period badge | Label plus optional `onPress`. No picker in this slice. |
+
+## Architecture
+
+```
+DashboardGrid
+  DashboardGridItem span={{sm,md,lg}}
+    ChartCard title periodLabel onPeriodPress?
+      Scorecard | LineChart | BarChart | DonutChart | DataTable
+    Scorecard
+      SparklineChart (plot only; solid + dotted comparison)
+```
+
+Existing facades stay the simple path. `ChartCard` is chrome around any child (chart or
+table). Facade `title` / `periodLabel` / `onPeriodPress` are shortcuts that render the
+same header inside the chart; callers use **either** `ChartCard` **or** those props, not
+both.
+
+### Public props (additive)
+
+```typescript
+interface ChartSeries {
+  color?: string;
+  data: Array<{color?: string; label: string; value: number}>;
+  id: string;
+  label: string;
+  stroke?: "solid" | "dotted";
+}
+
+interface CartesianChartProps {
+  comparisonData?: Array<{label: string; value: number}>;
+  data: Array<{color?: string; label: string; value: number}>;
+  formatValue?: (value: number) => string;
+  onPeriodPress?: () => void;
+  periodLabel?: string;
+  series?: ChartSeries[];
+  title?: string;
+  xTickPolicy?: "auto" | "truncate" | "rotate";
+  // existing: height, legendLabel, emptyText, loading, accessibilityLabel, testID
+}
+
+interface DonutChartProps extends CartesianChartProps {
+  centerTitle?: string;
+  centerValue?: string;
+  formatShare?: (value: number, total: number) => string;
+}
+
+interface SparklineChartProps {
+  comparisonData?: Array<{label: string; value: number}>;
+  data: Array<{label: string; value: number}>;
+  height?: number;
+  testID?: string;
+}
+
+interface ScorecardProps {
+  comparisonData?: Array<{label: string; value: number}>;
+  formatValue?: (value: number) => string;
+  onPeriodPress?: () => void;
+  periodLabel?: string;
+  sparklineData?: Array<{label: string; value: number}>;
+  title: string;
+  value: number | string;
+  testID?: string;
+}
+
+interface ChartCardProps {
+  children: React.ReactNode;
+  filterSummary?: string;
+  onPeriodPress?: () => void;
+  periodLabel?: string;
+  title: string;
+  testID?: string;
+}
+
+interface DashboardGridItemProps {
+  children: React.ReactNode;
+  span?: {lg?: number; md?: number; sm?: number};
+  testID?: string;
+}
+
+interface DataTableProps {
+  footerRows?: DataTableCellData[][];
+  headerGroups?: Array<{columnCount: number; subtitle?: string; title: string}>;
+  rangeStart?: number;
+  rangeTotal?: number;
+  wrapLines?: 1 | 2; // default 1; 2 = wrap inside rowHeight
+  // existing page / setPage / totalPages remain; range copy uses page size math
+}
+```
+
+`series` when present is the cartesian data source (`data` is ignored except as a
+single-series fallback). `comparisonData` aligns on `label` and paints a dotted stroke
+(sparkline/line) or a lighter overlay (bar — if labels match). Default `xTickPolicy` is
+`"auto"`: rotate ~45° when labels would truncate; keep horizontal for ≤7 categorical
+labels.
+
+Donut legend rows become `swatch + label + formatShare` (default percent of total).
+`centerTitle` / `centerValue` sit in the hole via overlay `Text`.
+
+`DashboardGridItem` span is in column units of the current breakpoint count (span 5 in a
+5-column KPI row is full width on `sm` when `columns.sm === 1`).
+
+`SparklineChart` draws no axes, grid, legend, or reserved tooltip row. Hit targets stay
+≥24px when press/hover is wired; default is non-interactive (KPI sparkline).
+
+`headerGroups` paint a second header row above `columns` (period title + optional
+subtitle such as `(Previous period)`). `footerRows` stick to the bottom of the scroll
+body. Range status is `rangeStart–rangeEnd of rangeTotal` next to existing pagination.
+
+### File layout
+
+| Path | Role |
+|------|------|
+| `ui/src/SparklineChart.tsx` | Public sparkline |
+| `ui/src/Scorecard.tsx` | Public KPI tile |
+| `ui/src/ChartCard.tsx` | Public title + period badge chrome |
+| `ui/src/DashboardGridItem.tsx` | Public span wrapper (or named export from `DashboardGrid.tsx` — no barrel) |
+| `ui/src/LineChart.tsx` etc. | Additive `series`, `comparisonData`, ticks, header shortcuts |
+| `ui/src/DonutChart.tsx` | Center stack + share legend |
+| `ui/src/DataTable.tsx` | Header groups, footer rows, range status, wrapLines |
+| `ui/src/Pagination.tsx` | Range copy when totals provided |
+| `demo/chartVisual/fixtureCatalog.ts` | New hard fixtures including `hows-it-going-dashboard` |
+| `docs/how-to/charts-and-dashboards.md` | Rewrite around Scorecard + ChartCard + spans |
+
+`DashboardGrid` stays eager. New chart widgets join `heavyOptionalExports`. `ChartCard`
+and `Scorecard` are layout+text heavy enough to sit with charts (lazy). `DashboardGridItem`
+stays eager with the grid.
+
+### Chart visual regression
+
+Add fixtures that exercise the reference patterns (not the JPEG pixels):
+
+| id | Pattern |
+|----|---------|
+| `scorecard-sparkline-comparison` | Five KPI tiles, solid + dotted sparkline |
+| `bar-time-rotated-ticks` | Vertical bars, rotated dates, y `formatValue` |
+| `line-three-series` | Three lines, markers, per-series legend |
+| `bar-day-of-week` | Seven categorical bars, horizontal ticks |
+| `donut-center-and-share` | Hole label + percent legend |
+| `donut-single-slice` | One 100% slice + center total |
+| `hows-it-going-dashboard` | Spanning grid: 5 KPIs, time bar, 3-line, DOW bar, two donuts, one table card |
+
+`bun run ui:charts:compare` must cover these. Agents use `review-chart-visuals`.
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+Universal React Native + web. Demo stories + visual gallery only. Tables stay `DataTable`
+inside `ChartCard`.
+
+## Phases
+
+1. **Tracer:** `SparklineChart` + `Scorecard` + `ChartCard` + `comparisonData` on the
+   sparkline; demo story; docs stub; golden for `scorecard-sparkline-comparison`.
+2. **Cartesian additive:** `series`, `comparisonData`, `xTickPolicy`, header shortcuts on
+   line/bar/area; goldens for time bar and 3-line.
+3. **Donut:** center stack + share legend; goldens for two-slice and 100% slice.
+4. **Grid spans:** `DashboardGridItem`; reference KPI wrap; compose `hows-it-going-dashboard`
+   charts (table slot placeholder ok until Phase 5).
+5. **Table chrome:** header groups, footer rows, range status, `wrapLines={2}`; table card
+   in the hard fixture.
+6. **Packaging + docs:** lazy exports, import regression, how-to rewrite, explanation,
+   reference, TypeDoc, changelog, ui rule export list.
+
+## Feature Flags & Migrations
+
+None. Additive public props. Existing `{label, value}[]` callers stay valid. Not a major.
+
+`legendLabel` remains for single-series cartesian. Multi-series uses `series[].label`.
+Donut still ignores `legendLabel`.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Chart children grammar (`Chart`, `ChartXAxis`, …) — still `charts-and-dashboards` Phase 6.
+- Date-range picker control.
+- Dual-period table cells.
+- Variable row height.
+- Example-frontend / comms wiring.
+- Zoom/pan, combo charts.
+
+## Files to Create / Modify
+
+See the task list. Docs in-slice:
+
+- `docs/how-to/charts-and-dashboards.md` (rewrite)
+- `docs/explanation/charts.md` (multi-series, scorecard, why not grammar-first)
+- `docs/reference/ui.md` (new exports)
+- `docs/how-to/compare-chart-rendered-snapshots.md` (new fixture ids)
+- `.rulesync/rules/ui/00-ui.mdc`
+- `changelog/unreleased/dashboard-chart-parity.md`
+- TypeDoc props (`bun run website:generate` in the docs task)
+
+## Task List
+
+[docs/tasks/dashboard-chart-parity.md](../tasks/dashboard-chart-parity.md)
+
+## Acceptance Criteria
+
+- [ ] `Scorecard`, `SparklineChart`, and `ChartCard` are importable from `@terreno/ui` and subpaths.
+- [ ] A scorecard shows title, formatted value, and a sparkline with dotted `comparisonData`.
+- [ ] `LineChart` renders three series from `series` with a legend item each.
+- [ ] Time-series x ticks can rotate; day-of-week ticks stay horizontal under `auto`.
+- [ ] `DonutChart` draws `centerTitle` / `centerValue` and percent legend rows.
+- [ ] `DashboardGridItem` spans reproduce 5→2→1 KPI and 3→1 chart wrapping in the reference fixture.
+- [ ] `DataTable` shows period header groups, a sticky totals row, `1–50 of N`, and two-line wrap inside `rowHeight`.
+- [ ] Existing single-series `{label, value}[]` charts and tests stay green.
+- [ ] `bun run ui:charts:compare` matches goldens including `hows-it-going-dashboard`.
+- [ ] How-to shows the easy-build composition (Scorecard + ChartCard + spans), not only raw `Card` + `LineChart`.
+- [ ] Chart implementations stay lazy on the root; grid item stays eager.
+- [ ] Frontend verification: demo gallery exercised on web; artifacts on the implementation PR.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Dual header APIs (`ChartCard` vs facade title) | Document exclusive use; tests assert no double header when only one is set |
+| `DataTable` wrap vs virtualization | Cap at two lines; keep `rowHeight`; screenshot a wrapped first column |
+| Additive `series` vs later grammar | Facades remain the supported easy path; grammar stays a follow-up |
+| Golden flake on dense dashboards | One hard fixture at a fixed gallery width; review-chart-visuals on mismatch |
+| Header groups vs pinned columns | Totals and groups must align with `pinnedColumns` scroll sync; regression tests |

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

@@ -0,0 +1,219 @@
+# Implementation Plan: DataTable server-side filtering and search
+
+**Status:** Complete — shipped in #1303  
+**Branch:** `cursor/datatable-server-side-filtering-191d`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/TerrenoLabs/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).