@terreno/mcp 57.3.0 → 57.6.0

package/dist/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/TerrenoLabs/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/dist/docs/versioned/next/implementationPlans/comms-abstraction-research.md

@@ -45,4 +45,4 @@ Non-breaking choices for a published package:
 - `comms/src/types.ts`, `commsService.ts`, `models/commsMessage.ts`
 - [comms-admin-dashboard.md](comms-admin-dashboard.md)
 - [comms-adapter-sendgrid.md](comms-adapter-sendgrid.md)
-- Roadmap: https://github.com/FlourishHealth/terreno/issues/1018
+- Roadmap: https://github.com/TerrenoLabs/terreno/issues/1018

package/dist/docs/versioned/next/implementationPlans/comms-abstraction.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Pluggable communications layer (@terreno/comms)
 
 **Status:** Complete — `@terreno/comms` shipped; adapters track as their own IPs
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1018
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1018
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/comms-adapter-expo-push.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Comms adapter — Expo push notifications
 
 **Status:** In progress
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1019
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1019
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/comms-adapter-sendgrid.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Comms adapter — transactional email (SendGrid)
 
 **Status:** In progress — Phase 1 send path implemented; Phase 2 gated on inbound-webhooks
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1022
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1022
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/comms-adapter-twilio-sms.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Comms adapter — Twilio SMS
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1020
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1020
 **Priority:** Medium
 **Effort:** Small batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/comms-adapter-twilio-verify.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Comms adapter — Twilio Verify (OTP)
 
 **Status:** Complete
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1021
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1021
 **Priority:** Medium
 **Effort:** Small batch
 **Owner:** unassigned

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

@@ -1,7 +1,7 @@
 # Implementation Plan: Comms admin dashboard (errors, retries, log digging)
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1091
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1091
 **Priority:** High
 **Effort:** Medium batch
 **Owner:** unassigned
@@ -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/dist/docs/versioned/next/implementationPlans/compile-pipeline-dedup.md

@@ -0,0 +1,133 @@
+# Implementation Plan: Compile pipeline dedup (remove redundant recompiles)
+
+**Status:** Approved (2026-09-22)
+**Scan goal:** reduce-cold-compile-time ([charter](../scans/reduce-cold-compile-time/charter.md)) — cold `bun run compile` 305s → 214s
+**Slice:** pipeline-ordering-dedup (round 1, top slice)
+**Findings:** redundant-explicit-prefix (high, S), compile-workspace-deps-overlap (high, M)
+**Effort:** S–M
+**Owner / Reviewer:** @joshgachnang
+**Created:** 2026-09-21
+
+## Goal
+
+Make each `@terreno/*` package compile **exactly once** per cold `bun run compile` by
+relying on Bun's built-in workspace dependency ordering, instead of the current pipeline
+that recompiles shared packages many times. Target contribution to the scan goal: ~60–90s.
+
+## Background — measured redundancy
+
+Baseline cold `bun run compile` = 305s. The root script is:
+
+```
+"compile": "bun run --filter '@terreno/test' compile && bun run --filter '@terreno/api' compile && bun run --filter '*' compile"
+```
+
+From the baseline build log, per full run:
+
+| Package | Times compiled | Should be | Isolated cost |
+| --- | --- | --- | --- |
+| @terreno/test | ~5× | 1× | 10s |
+| @terreno/syncdb | ~4× | 1× | ~9s |
+| @terreno/api | ~3× | 1× | 31s (tsc), 50s (with deps) |
+| @terreno/jobs | ~2× | 1× | ~8s |
+
+Two causes:
+1. **redundant-explicit-prefix** (`package.json:223`): the explicit `@terreno/test` and
+   `@terreno/api` prefixes duplicate the `--filter '*'` pass, which already builds all 19
+   workspaces.
+2. **compile-workspace-deps-overlap** (`api/package.json:117`, `admin-backend/package.json:47`):
+   both packages prefix their `compile` with `node ../.github/scripts/compile-workspace-deps.js`,
+   which re-`tsc`s their `@terreno/*` deps in every process (its dedupe `Set` does not
+   persist across `bun run` processes), while `--filter '*'` also builds those same deps.
+
+## Key research finding — Bun orders builds topologically
+
+Bun 1.4.2 `bun run --filter '*' <script>` executes scripts in **workspace dependency
+order** (a dependent waits for its dependencies' script to finish). Evidence from the
+baseline log: `@terreno/rtk` (→ `ui`, plain `tsc`, `ui` is **not** prebuilt by the
+explicit prefixes) finishes after `ui`; `jobs`/`ai`/`comms` (→ `api`) finish after `api`;
+`example-backend` (→ 9 packages) finishes last. Because these plain-`tsc` packages resolve
+their `@terreno/*` deps from `dist/` (no `paths` → src) and the build succeeds, Bun must be
+ordering deps first.
+
+Dependency graph (acyclic): test, syncdb, ui → (leaves); api → test,syncdb; jobs/ai/comms/
+feature-flags → api,test; rtk → ui; admin-frontend → ui; admin-backend → api,jobs,test;
+example-backend → (many).
+
+## The change (4 files)
+
+The redundancy exists because the pipeline recompiles shared deps to guarantee ordering.
+Bun's `--filter '*'` already builds in dependency order, so in the **root** build the
+per-package `compile-workspace-deps.js` work is pure duplication. But **isolated** compiles
+(`cd <pkg> && bun run compile` in CircleCI per-package jobs and tag publish) have no
+`--filter '*'` ordering and genuinely need it. So we gate it by context rather than remove
+it:
+
+1. `package.json` root `compile` → `TERRENO_SKIP_WORKSPACE_DEPS=1 bun run --filter '*' compile`
+   (drop the two explicit `@terreno/test` + `@terreno/api` prefixes; set the skip flag).
+2. `.github/scripts/compile-workspace-deps.js` → early-return when
+   `TERRENO_SKIP_WORKSPACE_DEPS` is set. The flag is inherited by every `--filter '*'`
+   subprocess, so `api`/`admin-backend` skip the redundant dep rebuild while Bun's ordering
+   supplies the dists. Isolated compiles (no flag) build deps exactly as before.
+3. `api/package.json` `compile` — **unchanged** (`compile-workspace-deps.js && bun tsc`).
+4. `admin-backend/package.json` `compile` — **unchanged**.
+
+(Net: files 3–4 are unchanged vs master; the working change is files 1–2.)
+
+## Non-goals
+
+- No TS project references / `tsc -b` (that is the deferred `no-project-references`
+  finding — an alternative road to the same ordering goal; a separate slice/round).
+- No mcp-server doc-sync change (Slice A, already merged as #1358).
+- No `tsconfig` changes, no `skipLibCheck` changes, no strictness changes.
+
+## Why publish/CI stay green
+
+Isolated per-package compiles do **not** set `TERRENO_SKIP_WORKSPACE_DEPS`, so
+`compile-workspace-deps.js` runs normally and builds sibling dists from source — exactly
+as on master. This covers CircleCI per-package jobs (`api-ci`, `compile_packages`, …), the
+`publish-on-tag.yml` steps, and `scripts/ci/publish-package.sh`. Verified: `cd api &&
+bun run compile` with a clean tree builds `@terreno/test` + `@terreno/syncdb` then `api`
+(exit 0). Only the root ordered build skips the redundant recompile.
+
+## Acceptance criteria (observable + verification)
+
+| # | Criterion | Verification |
+| --- | --- | --- |
+| 1 | Cold `bun run compile` exits 0 from a clean tree | `rm -rf */dist && bun run compile; echo $?` → 0 |
+| 2 | Each `@terreno/*` package is `tsc`-built exactly once per run | Capture build log; assert one "compile: Exited" per buildable package and zero `Compiling @terreno/... with bun tsc` lines from `compile-workspace-deps` during the dev build |
+| 3 | Published `dist/` is byte-identical to baseline | Build baseline dist → tmpA; build new dist → tmpB; `diff -r` every package's `dist/` → no differences |
+| 4 | Cold compile time drops materially | Metric command best-of-3; record min vs 305s baseline (expect ~60–90s reduction) |
+| 5 | Publish path unaffected | `git diff --stat` shows `compile-workspace-deps.js` unchanged; confirm each CI/publish job still calls it directly before its compile |
+| 6 | Lint + tests green | `bun run lint`, `bun run api:test`, `bun run ui:test` pass |
+
+Criterion #4 is the metric tie-back.
+
+## Unacceptable trade-offs (charter, verbatim)
+
+- **Published dist output must stay intact** — `declaration` (.d.ts) emit and the published
+  `dist/` layout for every `@terreno/*` package are preserved.
+- **No type-safety loss** — no loosening `strict`/`strictNullChecks`, no removing existing
+  `skipLibCheck`.
+- Publish-time behavior of `compile-workspace-deps.js` must be preserved.
+
+## Risks
+
+- **Bun ordering not guaranteed for some edge package.** Mitigated by criterion #1 (clean
+  full build) and #3 (dist parity). If a specific package fails ordering, fall back to an
+  explicit dependency-ordered filter for that package only — not a return to full-pass
+  duplication.
+- **A hidden consumer relies on `bun run --filter '@terreno/api' compile` self-building
+  deps.** Checked: all CI/publish callers invoke the script directly first (criterion #5).
+
+## Docs to update
+
+- Build/compile explanation doc (if the root `compile` contract is documented) via the
+  `update-docs` skill.
+- One-line comment in root `package.json`? (json → not possible) — instead note the
+  ordering reliance in the build doc.
+
+## Rollout
+
+Single PR, reviewer @joshgachnang, human merge on green CI. No feature flag; revertable by
+restoring the three script strings.

package/dist/docs/versioned/next/implementationPlans/consent-forms.md

@@ -2,7 +2,7 @@
 
 **Status:** Complete
 **Closed:** 2026-08-20 — Shipped via `ConsentApp`, `ConsentForm`/`ConsentResponse` models, and `@terreno/ui` consent screens (`ConsentNavigator`, `ConsentFormScreen`, `useConsentForms`).
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1078
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1078
 
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 

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/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