@terreno/mcp 57.2.0 → 57.4.0

package/src/docs/versioned/next/tasks/app-mcp-server.md

@@ -0,0 +1,199 @@
+# Tasks: App MCP server
+
+See: [`docs/implementationPlans/app-mcp-server.md`](../implementationPlans/app-mcp-server.md)
+
+**Status:** Draft (Grow). Do not Pick until the IP header is **Approved**.
+
+## Instructions for the implementing agent
+
+- Load `update-docs`, `terreno-backend-api`, `backend-test-env`. For `MCPService` / RTK also `terreno-data-fetching`.
+- TDD: failing test for the primitive, then implementation.
+- After API export changes, update `docs/reference/api.md` and `docs/how-to/expose-mcp-tools.md` in the same task.
+- Run focused `bun test` in `api/` (and `ai/` / `mcp-server/` for those phases). `bun run lint` on touched packages.
+- Do not implement MCP Apps or streaming handlers.
+
+---
+
+### Phase 1: Prompts, resources, richer tools
+
+- [ ] **Task 1.1**: MCP result helper + richer custom tool types
+  - Delivers: `mcpResult.text` / `.json` / `.error`; optional `annotations`, `outputSchema`, `shouldRegister` on `registerMCPTool` without breaking existing callers
+  - Files: `api/src/mcp/result.ts`, `api/src/mcp/result.test.ts`, `api/src/mcp/types.ts`, `api/src/mcp/registry.ts`, `api/src/mcp/registry.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Docs: `docs/reference/api.md` (custom tool options table)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: existing `registerMCPTool` tests pass; new test covers `shouldRegister` returning false omits the tool from `getAllMCPTools` for that user; `mcpResult.json` returns text JSON plus `structuredContent` when the SDK result type allows it
+
+- [ ] **Task 1.2**: Register and serve prompts
+  - Delivers: `registerMCPPrompt` / list / get on the default `/mcp` server
+  - Files: `api/src/mcp/prompts.ts`, `api/src/mcp/prompts.test.ts`, `api/src/mcp/server.ts`, `api/src/mcp/registry.ts`
+  - Blocked by: Task 1.1
+  - Docs: `docs/how-to/add-mcp-prompts-and-resources.md` (create; prompts section)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: HTTP or in-process MCP client `prompts/list` includes the prompt; `prompts/get` returns messages; `shouldRegister: false` hides it; tools still list
+
+- [ ] **Task 1.3**: Register and serve resources
+  - Delivers: `registerMCPResource` / list / read on `/mcp`
+  - Files: `api/src/mcp/resources.ts`, `api/src/mcp/resources.test.ts`, `api/src/mcp/server.ts`, `api/src/mcp/registry.ts`
+  - Blocked by: Task 1.1
+  - Docs: same how-to, resources section
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: `resources/list` + `resources/read` for a `terreno://` or `app://` URI; missing URI is an MCP error; hidden resource omitted
+
+- [ ] **Task 1.4**: CRUD tool annotations
+  - Delivers: generated list/read `readOnlyHint`; delete `destructiveHint`; create/update not read-only
+  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
+  - Blocked by: Task 1.1
+  - Docs: `docs/how-to/expose-mcp-tools.md` one-line note
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: tests assert annotation flags on generated tool defs passed to `registerTool`
+
+- [ ] **Task 1.5**: Example-backend tracer primitives
+  - Delivers: one prompt + one resource next to existing custom tool; README how to list them
+  - Files: `example-backend/src/` (MCP module or next to `usersTodoStatus`), `example-backend/README.md`
+  - Blocked by: Task 1.2, Task 1.3
+  - Docs: example README only
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: booting example-backend, authenticated `prompts/list` and `resources/list` return the new names (API integration test)
+
+---
+
+### Phase 2: Named servers
+
+- [ ] **Task 2.1**: `mountMCPServer` path + include lists
+  - Delivers: second mount that only exposes named tools/prompts/resources; default `/mcp` still union
+  - Files: `api/src/mcp/server.ts`, `api/src/mcp/server.test.ts`, `api/src/terrenoApp.ts` (optional `mcpServers` or `configureApp` example)
+  - Blocked by: Task 1.2, Task 1.3
+  - Docs: `docs/how-to/expose-mcp-tools.md` named-server section; `docs/reference/api.md`
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: test app mounts `/mcp` and `/mcp/weather`; weather path lists only included names; `/mcp` still has CRUD + weather tool if globally registered
+
+- [ ] **Task 2.2**: TerrenoApp helper for extra servers
+  - Delivers: documented `configureApp` or `app.addMCPServer` so consumers do not call `mountMCPServer` internals
+  - Files: `api/src/terrenoApp.ts`, `api/src/terrenoApp.test.ts` (or server tests), `api/src/index.ts`
+  - Blocked by: Task 2.1
+  - Docs: reference + how-to
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: public method/options covered by a test that boots `TerrenoApp` and hits both paths
+
+---
+
+### Phase 3: Factories + hosted generators
+
+- [ ] **Task 3.1**: `defineMCPTool` / `defineMCPPrompt` / `defineMCPResource`
+  - Delivers: exported factories that call register functions; example-backend migrated to factories
+  - Files: `api/src/mcp/define.ts`, `api/src/mcp/define.test.ts`, `api/src/index.ts`, example-backend MCP module
+  - Blocked by: Task 1.5
+  - Docs: how-to examples switch to `defineMCP*`
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: factories are the documented API; `registerMCPTool` still exported
+
+- [ ] **Task 3.2**: Hosted `terreno_generate_mcp_tool`
+  - Delivers: `@terreno/mcp` tool that returns a `defineMCPTool` snippet from name/description/fields
+  - Files: `mcp-server/src/tools.ts`, `mcp-server` tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 3.1
+  - Docs: `docs/reference/mcp-server.md` tool table
+  - Skills: `update-docs`
+  - Acceptance: returned TypeScript typechecks against public factory types (snapshot or compile test); tool description tells agents to call this before inventing tool shapes
+
+- [ ] **Task 3.3**: Hosted `terreno_generate_mcp_prompt` and `terreno_generate_mcp_resource`
+  - Delivers: sibling generators for prompts and resources
+  - Files: `mcp-server/src/tools.ts`, tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 3.2
+  - Docs: same reference page
+  - Skills: `update-docs`
+  - Acceptance: each tool returns a snippet that matches `defineMCPPrompt` / `defineMCPResource`; tests cover required vs optional arguments / URI + mimeType
+
+---
+
+### Phase 4: Test helpers + Inspector how-to
+
+- [ ] **Task 4.1**: `invokeMCPTool` / `invokeMCPPrompt` / `readMCPResource`
+  - Delivers: helpers used by api tests; assert `isError`, text, structured JSON
+  - Files: `api/src/mcp/testHelpers.ts`, `api/src/mcp/testHelpers.test.ts`, re-export from a test-only path if consumers need it
+  - Blocked by: Task 1.2, Task 1.3
+  - Docs: how-to testing section
+  - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
+  - Acceptance: helper test authenticates a user, calls the tracer tool, asserts JSON; unauthenticated call matches production auth rules
+
+- [ ] **Task 4.2**: MCP Inspector operator docs
+  - Delivers: copy-paste Inspector command against example-backend `/mcp` with bearer header
+  - Files: `docs/how-to/add-mcp-prompts-and-resources.md` or `docs/how-to/expose-mcp-tools.md`
+  - Blocked by: Task 1.5
+  - Docs: that how-to only
+  - Skills: `update-docs`
+  - Acceptance: command uses current example-backend URL/port; auth header documented; no vendored Inspector binary
+
+---
+
+### Phase 5: First-party client
+
+- [ ] **Task 5.1**: `MCPService` Streamable HTTP default
+  - Delivers: tools listed over HTTP against `mountMCPServer`; SSE still selectable
+  - Files: `ai/src/service/mcpService.ts`, `ai/src/service/mcpService.test.ts`, types
+  - Blocked by: Task 2.1 (server stable)
+  - Docs: `docs/reference/ai.md` if MCPService is documented there; else api/ai README
+  - Skills: `terreno-data-fetching`, `update-docs`
+  - Acceptance: test does not mock away the transport type; SSE path still unit-tested
+
+- [ ] **Task 5.2**: Client prompt + resource methods
+  - Delivers: `listPrompts` / `getPrompt` / `listResources` / `readResource` on `MCPService`
+  - Files: `ai/src/service/mcpService.ts` + tests
+  - Blocked by: Task 5.1, Task 1.2, Task 1.3
+  - Docs: same reference
+  - Skills: `terreno-data-fetching`, `update-docs`
+  - Acceptance: methods return the tracer prompt/resource from Phase 1 example or a test server
+
+---
+
+### Phase 6: OAuth 2.1 via Better Auth
+
+- [ ] **Task 6.1**: Catalog deps + Better Auth MCP plugin wiring
+  - Delivers: `@better-auth/mcp` and `@better-auth/oauth-provider` on the Better Auth instance `BetterAuthApp` already builds; JWT-only apps do not load the plugin
+  - Files: root catalog / `api/package.json`, Better Auth setup module, tests that plugin registers only when Better Auth is on
+  - Blocked by: none (can start in parallel with Phase 1; do not merge OAuth onto `/mcp` until 6.2)
+  - Docs: `docs/how-to/configure-better-auth.md` pointer that MCP OAuth is enabled with Better Auth
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: versions match [infra-mcp.md](../implementationPlans/infra-mcp.md) pins; JWT-only boot does not import the MCP OAuth plugin
+
+- [ ] **Task 6.2**: Protected-resource metadata + 401 challenge
+  - Delivers: RFC 9728 well-known document; unauthenticated `/mcp` returns 401 with `WWW-Authenticate` pointing at it
+  - Files: `api/src/mcp/server.ts`, `api/src/mcp/oauth.ts` (or Better Auth route hook), tests
+  - Blocked by: Task 6.1
+  - Docs: `docs/how-to/secure-app-mcp.md` (create); `docs/reference/api.md` well-known paths
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: Better Auth test app: no Authorization header → 401 + challenge; JWT-only app: no well-known required, bearer JWT still works
+
+- [ ] **Task 6.3**: Access token → app User in `extractUserFromHeaders`
+  - Delivers: OAuth access tokens on `Authorization: Bearer` resolve to the same `User` as REST; tool calls honor permissions
+  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`, server integration test
+  - Blocked by: Task 6.2
+  - Docs: `docs/how-to/secure-app-mcp.md` client connect steps (Claude/ChatGPT-style OAuth vs Inspector bearer)
+  - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
+  - Acceptance: issued access token lists tools as that user; expired/wrong audience token is 401; JWT bearer still succeeds on the same app
+
+---
+
+### Phase 7: Explanation page
+
+- [ ] **Task 7.1**: Two-layer MCP explanation
+  - Delivers: `docs/explanation/app-mcp.md` + index link
+  - Files: `docs/explanation/app-mcp.md`, `docs/explanation/README.md`
+  - Blocked by: Task 2.2, Task 3.1, Task 6.3 (API and auth names stable)
+  - Docs: that explanation + README
+  - Skills: `update-docs`
+  - Acceptance: page tables Boost vs app MCP, generated vs registered primitives, JWT bearer vs Better Auth OAuth; links how-tos; does not document MCP Apps as shipped
+
+---
+
+## Frontier after Approve
+
+Unblocked: **Task 1.1** and **Task 6.1** (OAuth plugin wiring is independent until 6.2).
+Blocked until 1.1: 1.2–1.4.
+1.5 after 1.2+1.3.
+2.x after prompts+resources.
+3.2–3.3 after 3.1 (required generators).
+4.1 can start after 1.2+1.3 in parallel with 2.x.
+5.x after server HTTP surface is stable (2.1).
+6.2 after 6.1; 6.3 after 6.2.
+7.1 last for name-stable docs.

package/src/docs/versioned/next/tasks/better-auth-strict-oauth-provider.md

@@ -0,0 +1,41 @@
+# Task List: Better Auth sync omits unset `oauthProvider`
+
+**Feature profile:** true  
+**IP:** [better-auth-strict-oauth-provider.md](../implementationPlans/better-auth-strict-oauth-provider.md)  
+**Issue:** https://github.com/FlourishHealth/terreno/issues/1218
+
+## Durable contract
+
+- **Destination:** email/password Better Auth sync creates the app `User` on a `strict: "throw"` schema that has no `oauthProvider` field, so the first authenticated `modelRouter` request gets `req.user` instead of 401.
+- **Scope:** omit `oauthProvider` on `syncBetterAuthUser` create unless a non-empty provider string is passed; regression tests; docs and agent rules; changelog fragment.
+- **Non-goals:** bootstrap User schema; inventing `betterAuthUserPlugin`; session-middleware 401-on-sync-failure behavior; JWT.
+- **Decisions:** Q1 = option 1 (omit unset field). OAuth apps must still declare `oauthProvider`. Do not add the field to bootstrap.
+- **Tracer:** `syncBetterAuthUser` create path in `api/src/betterAuthSetup.ts`.
+- **Verification seam:** focused `bun test api/src/betterAuthSetup.test.ts` (red without the payload change), then `bun run api:test` and `bun run lint`.
+
+## Instructions for the implementing agent
+
+- TDD: add the `strict: "throw"` regression first and confirm it fails, then change the create payload.
+- Do not set `oauthProvider: null`. Omit the key.
+- When updating `docs/how-to/configure-better-auth.md` § User Model, replace the `betterAuthUserPlugin` example (that export does not exist) with explicit `betterAuthId` plus optional `oauthProvider`.
+- Use `backend-test-env` for any `process.env` mutations. Follow existing `betterAuthSetup.test.ts` helpers (separate MongoMemoryServer connection).
+- Supporting skills: `update-docs`, `backend-test-env`, `mongoose-schema-safety`, `terreno-backend-api`.
+
+### Phase 1: Fix lazy User create
+
+- [x] **Task 1.1**: Omit unset `oauthProvider` on Better Auth User create
+  - Delivers: email/password sign-up then first authenticated API call works on a bootstrap-like User schema (`strict: "throw"`, `betterAuthId`, no `oauthProvider`).
+  - Files: `api/src/betterAuthSetup.ts`, `api/src/betterAuthSetup.test.ts`, `docs/how-to/configure-better-auth.md`, `docs/explanation/authentication.md`, `.rulesync/rules/api/00-api.md` (regenerate agent copies with `bun run rules` and `bun run skills:sync`), `changelog/unreleased/better-auth-strict-oauth-provider.md`
+  - Blocked by: none
+  - Docs: how-to User model fields; explanation lazy sync; agent rule field list. Do not hand-edit generated TypeDoc.
+  - Skills: `update-docs`, `backend-test-env`, `mongoose-schema-safety`, `terreno-backend-api`
+  - Acceptance:
+    - New test: schema `{strict: "throw"}` without `oauthProvider`; `syncBetterAuthUser(model, baUser)` resolves; saved doc has `betterAuthId` and no `oauthProvider` path.
+    - New test: schema that declares `oauthProvider`; third argument `"google"` persists `"google"`.
+    - That first test fails on current `oauthProvider: oauthProvider || null` (StrictModeError).
+    - `bun test api/src/betterAuthSetup.test.ts` and `bun run api:test` pass after the fix.
+    - Docs state `betterAuthId` is required for sync; `oauthProvider` is required only when using OAuth.
+
+## Plan vs Actual
+
+- Task 1.1: `syncBetterAuthUser` create spreads `oauthProvider` only when truthy. Strict-throw schema without the field is green; create with `"google"` still persists. Docs dropped the non-existent `betterAuthUserPlugin` example.

package/src/docs/versioned/next/tasks/can-as-permission-seam.md

@@ -0,0 +1,32 @@
+# Tasks: `can()` as the permission seam
+
+IP: [can-as-permission-seam.md](../implementationPlans/can-as-permission-seam.md)
+
+## Phase 1 — `assertAllowed`
+
+- [ ] **Task 1.1**: Helper + unit tests
+  - Delivers: `assertAllowed` implements legacy `checkPermissions` and `accessControl.can()`; double-gate test (access allow + permissions deny → allow)
+  - Files: `api/src/rbac/assertAllowed.ts`, `api/src/rbac/assertAllowed.test.ts`
+  - Blocked by: none (can land before MCP adapters; executors wiring waits on unified writes if MCP still duplicates checks)
+  - Acceptance: bun tests cover 405 empty array, 403 can() deny, legacy AND, access-wins-over-permissions
+
+## Phase 2 — Hot path
+
+- [ ] **Task 2.1**: Middleware + executors
+  - Delivers: `permissionMiddleware` and `executeCreate/Update/Delete` call `assertAllowed`; `buildAccessPermissions` not used on requests
+  - Files: `api/src/permissions.ts`, `api/src/sync/executors.ts`, `api/src/api.ts`, `api/src/rbac/modelRouterAccess.ts`, tests
+  - Blocked by: 1.1; unified-mutation-executors Phase 2 so MCP is included automatically
+  - Acceptance: modelRouter + executor + MCP permission tests pass; grep shows no request-path `buildAccessPermissions`
+
+## Phase 3 — Consumers and docs
+
+- [ ] **Task 3.1**: example-backend dual config
+  - Delivers: routers with `access` drop redundant AND `permissions` where RBAC is the intent
+  - Files: `example-backend/src/**` model routers
+  - Blocked by: 2.1
+  - Acceptance: example-backend tests pass
+- [ ] **Task 3.2**: Docs + breaking changelog
+  - Files: `docs/reference/api.md`, `docs/how-to/create-a-model.md`, `docs/implementationPlans/rbac-permissions.md` pointer, changelog
+  - Blocked by: 2.1
+  - Skills: `update-docs`
+  - Acceptance: evaluation order is documented; 403 vs 405 table exists

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

@@ -0,0 +1,120 @@
+# Tasks: Charts and dashboard primitives
+
+IP: [charts-and-dashboards.md](../implementationPlans/charts-and-dashboards.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1175
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (`LineChart`)
+
+- [x] **Task 1.1**: Private scale/path/theme helpers
+  - Delivers: linear and band scales plus line/area/arc path strings from `{label, value}[]`; theme paint map from `useTheme`; no public d3 types
+  - Files: `ui/src/charts/types.ts`, `ui/src/charts/scales.ts`, `ui/src/charts/paths.ts`, `ui/src/charts/theme.ts`, `ui/src/charts/scales.test.ts`, `ui/src/charts/paths.test.ts`, `ui/package.json` (`d3-scale`, `d3-shape`, types)
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: none yet (helpers are private); record the dependency choice in the IP (already decided)
+  - Acceptance: bun tests — known fixtures produce expected domain/range and path `d` containing the fixture points; empty input does not throw
+
+- [x] **Task 1.2**: `LineChart` + frame (tooltip, legend, empty, loading)
+  - Delivers: public `LineChart` on owned SVG; overlay `Text` ticks; legend when `legendLabel` set; tooltip `{label}: {value}` on press (and hover on web); empty `Text`; `loading` `Spinner`; per-point `testID` / a11y labels
+  - Files: `ui/src/charts/ChartFrame.tsx`, `ui/src/LineChart.tsx`, `ui/src/LineChart.test.tsx`, `ui/src/index.tsx` (lazy export; may be a temporary direct export until 4.1), `ui/src/Common.ts` (TypeDoc props if that is the audit source)
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`, `verify-ui-changes`
+  - Docs: stub `LineChart` in `docs/reference/ui.md` Display list so the tracer is documented when it lands
+  - Acceptance: bun tests — 3 points → 3 mark testIDs; empty data shows `emptyText`; `loading` shows spinner; press on a mark shows tooltip copy; `legendLabel` renders. `ui` compile green.
+
+- [x] **Task 1.3**: `LineChart` demo story
+  - Delivers: demo story with default, empty, loading, and tooltip-able data; registered in `demoConfig.tsx`
+  - Files: `demo/stories/LineChart.stories.tsx`, `demo/demoConfig.tsx` (and story-config if that package requires a config module)
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `verify-ui-changes`
+  - Docs: none beyond the story
+  - Acceptance: `bun run demo:compile` (or package equivalent) passes; story is reachable in `demoConfig`
+
+## Phase 2 — Sibling charts
+
+- [x] **Task 2.1**: `BarChart`
+  - Delivers: public `BarChart` on `ChartFrame`; one bar per point; same empty/loading/tooltip/legend/a11y contract as `LineChart`
+  - Files: `ui/src/BarChart.tsx`, `ui/src/BarChart.test.tsx`, `ui/src/index.tsx`, `demo/stories/BarChart.stories.tsx`, `demo/demoConfig.tsx`
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: add `BarChart` to `docs/reference/ui.md`
+  - Acceptance: bun tests for mark count, empty, tooltip copy; demo story registered; compile green
+
+- [x] **Task 2.2**: `AreaChart`
+  - Delivers: public `AreaChart` (filled path + line) on `ChartFrame`; same contract
+  - Files: `ui/src/AreaChart.tsx`, `ui/src/AreaChart.test.tsx`, `ui/src/index.tsx`, `demo/stories/AreaChart.stories.tsx`, `demo/demoConfig.tsx`
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: add `AreaChart` to `docs/reference/ui.md`
+  - Acceptance: bun tests for area path presence / mark count, empty, tooltip; demo story registered
+
+- [x] **Task 2.3**: `DonutChart`
+  - Delivers: public `DonutChart`; one slice per point; per-slice `color` override; legend is one row per slice (ignore `legendLabel`); tooltip on slice press/hover
+  - Files: `ui/src/DonutChart.tsx`, `ui/src/DonutChart.test.tsx`, `ui/src/index.tsx`, `demo/stories/DonutChart.stories.tsx`, `demo/demoConfig.tsx`
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: add `DonutChart` to `docs/reference/ui.md`
+  - Acceptance: bun tests — N slices, color override on one slice, empty, tooltip copy; demo story registered
+
+## Phase 3 — Dashboard grid
+
+- [x] **Task 3.1**: `DashboardGrid`
+  - Delivers: eager public `DashboardGrid`; default columns `{sm: 1, md: 2, lg: 3}`; wraps children with gap; children remain `Card`s supplied by the caller
+  - Files: `ui/src/DashboardGrid.tsx`, `ui/src/DashboardGrid.test.tsx`, `ui/src/index.tsx` (eager export), `demo/stories/DashboardGrid.stories.tsx`, `demo/demoConfig.tsx`
+  - Blocked by: 1.2 (demo composition uses `LineChart`; grid component itself does not)
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: add `DashboardGrid` to `docs/reference/ui.md` Layout list
+  - Acceptance: bun tests — default column map, custom `columns`, `gap`, child `testID`s still present; demo story shows a grid of `Card`+chart; compile green
+
+## Phase 4 — Packaging and docs
+
+- [x] **Task 4.1**: Lazy root boundary + import regression
+  - Delivers: `LineChart`, `BarChart`, `AreaChart`, `DonutChart` on `heavyOptionalExports`; `DashboardGrid` stays eager; root import does not evaluate chart implementation modules; subpath imports still work
+  - Files: `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, `ui/src/RootImportRegression.test.tsx`, `docs/reference/ui-performance.md` (list charts with other heavy widgets)
+  - Blocked by: 2.1, 2.2, 2.3, 3.1
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` performance section names the chart lazy exports
+  - Acceptance: `RootImportRegression` (or equivalent) fails if chart files load with the root import; `bun run performance:imports` does not regress beyond documented noise; subpath `import {LineChart} from "@terreno/ui/LineChart"` works
+
+- [x] **Task 4.2**: Diátaxis + changelog + rules + seed
+  - Delivers: how-to (compose charts in a `DashboardGrid` of `Card`s), explanation (why owned SVG vs victory-native), reference complete, how-to/explanation README links, TypeDoc props, changelog fragment, ui rule export list, roadmap seed IP/task GitHub links, comms/b2b pointers if they still say “not yet written”
+  - Files: `docs/how-to/charts-and-dashboards.md`, `docs/how-to/README.md`, `docs/explanation/charts.md`, `docs/explanation/README.md`, `docs/reference/ui.md`, `docs/explanation/roadmap-seed-issues.md`, `docs/implementationPlans/comms-admin-dashboard.md` (link only), `.rulesync/rules/ui/00-ui.mdc`, `changelog/unreleased/charts-and-dashboards.md`; `bun run rules` / `skills:sync` if rulesync requires it; `bun run website:generate` if TypeDoc pages are generated
+  - Blocked by: 3.1, 4.1
+  - Skills: `update-docs`, `docs-audit`, `terreno-ui`
+  - Docs: the files listed above
+  - Acceptance: a stranger can copy the how-to example into a screen; explanation states the victory-native rejection; seed `Implementation plan` / `Tasks` are not `*(not yet written)*`; `bun run website:build` if the docs site is in the slice; changelog fragment `category: Added`
+
+## Phase 5 — Rendered visual regression
+
+- [x] **Task 5.1**: Chart visual gallery + compare command + review skill
+  - Delivers: easy-through-hard fixtures actually rendered in the demo; PNG goldens under `demo/rendered-snapshots/`; `bun run ui:charts:compare` / `ui:charts:update-snapshots`; `review-chart-visuals` skill
+  - Files: `demo/chartVisual/**`, `demo/app/demo/chart-visual-gallery.tsx`, `scripts/charts/compareChartImages.ts`, `scripts/charts/compareRenderedSnapshots.ts`, `demo/rendered-snapshots/*.png`, `.rulesync/skills/review-chart-visuals/SKILL.md`, `docs/how-to/compare-chart-rendered-snapshots.md`, `docs/explanation/charts.md`, `docs/reference/ui.md`
+  - Blocked by: 4.2
+  - Skills: `verify-ui-changes`, `review-chart-visuals`, `update-docs`, `update-agent-docs`
+  - Docs: how-to compare page; explanation + reference pointers; skill + `verify-ui-changes` hook
+  - Acceptance: catalog tests; fixture render tests; pixelmatch unit tests; compare against goldens is green; skill is in `skills.sh.json` groupings
+
+## Phase 6 — Composition grammar (not this slice)
+
+- [ ] **Task 6.1**: Declarative `Chart` children grammar (follow-up Pick)
+  - Delivers: `Chart`, `ChartTitle`, `ChartSubtitle`, `ChartCartesian`, `ChartPolar`, `ChartXAxis`, `ChartYAxis`, `ChartGrid`, `ChartLegend`, `ChartTooltip`, `ChartLine`, `ChartArea`, `ChartBar`, `ChartDonut`, `ChartDataLabels`, `ChartReferenceLine`, `ChartReferenceBand`; keyed rows + `dataKey`; facades additive `{label,value}`; tooltip overlay+footer; tokens+hex; grouped bars unless `stackId`
+  - Files: `ui/src/Chart*.tsx` (flat named exports, no barrel)
+  - Blocked by: 5.1
+  - Skills: `terreno-ui`, `review-chart-visuals`, `update-docs`
+  - Docs: how-to + reference rewritten for composition; visual goldens updated
+  - Acceptance: a complex titled/labeled/colored chart is composed only from Terreno chart children; `ui:charts:compare` stays green
+
+## Verification mapping
+
+| Criterion | Method |
+|-----------|--------|
+| Four chart types + grid export | compile + import tests |
+| No victory-native | `ui/package.json` / grep |
+| Single-series contract | bun tests + TypeDoc props |
+| Tooltip + legend + empty/loading | bun tests + demo web exercise |
+| Theme + overlay `Text` | unit theme map + render tests |
+| Lazy charts | `RootImportRegression` / import benchmark |
+| Demo + docs | registered stories; how-to/explanation/reference exist |
+| Frontend proof | `verify-ui-changes` on demo stories; artifacts on the implementation PR |
+| Rendered paint | `bun run ui:charts:compare` vs `demo/rendered-snapshots/` |

package/src/docs/versioned/next/tasks/collection-registry.md

@@ -0,0 +1,42 @@
+# Tasks: One collection registry
+
+IP: [collection-registry.md](../implementationPlans/collection-registry.md)
+
+## Phase 1 — Dual-write catalog
+
+- [ ] **Task 1.1**: `CollectionRegistry` module
+  - Delivers: `registerCollection`, `replaceCollectionOptions`, `getCollection`, `listCollections`, `clearCollectionRegistry` with unit tests (unknown path no-op, options replace)
+  - Files: `api/src/collectionRegistry.ts`, `api/src/collectionRegistry.test.ts`
+  - Blocked by: none
+  - Acceptance: bun tests for the module pass without wiring modelRouter
+- [ ] **Task 1.2**: Dual-write from `modelRouter`
+  - Delivers: `modelRouter` / `_buildModelRouter` write the catalog in addition to existing `register*` / `update*`
+  - Files: `api/src/api.ts`
+  - Blocked by: 1.1
+  - Acceptance: existing api tests still pass
+
+## Phase 2 — Surfaces read the catalog
+
+- [ ] **Task 2.1**: MCP and realtime views
+  - Delivers: `getMCPRegistry` / realtime finders read `CollectionRegistry`; arrays in those files removed
+  - Files: `api/src/mcp/registry.ts`, `api/src/realtime/registry.ts`, related tests
+  - Blocked by: 1.2
+  - Acceptance: MCP and realtime tests pass; `updateMCPRegistryOptions` updates the shared record
+- [ ] **Task 2.2**: Sync view + keep validation
+  - Delivers: sync lookup uses catalog; `registerSync` validation + index promises still run
+  - Files: `api/src/sync/registry.ts`, `api/src/sync/*.test.ts`
+  - Blocked by: 1.2
+  - Acceptance: missing `deleted` / `_syncSeq` still throws; sync tests pass
+
+## Phase 3 — Contract
+
+- [ ] **Task 3.1**: Single writer + clear-all
+  - Delivers: `modelRouter` only writes `CollectionRegistry`; wrapper register/update/clear functions; tests that used independent clears updated
+  - Files: `api/src/api.ts`, registry wrappers, tests
+  - Blocked by: 2.1, 2.2
+  - Acceptance: one `replaceCollectionOptions` is enough for MCP+sync options identity
+- [ ] **Task 3.2**: Docs + changelog
+  - Files: `docs/explanation/modular-api-design.md`, `docs/reference/api.md`, changelog
+  - Blocked by: 3.1
+  - Skills: `update-docs`
+  - Acceptance: docs name the catalog as the runtime seam

package/src/docs/versioned/next/tasks/comms-adapter-expo-push.md

@@ -2,27 +2,27 @@
 
 IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
 
-- [ ] **Task 1**: `ExpoPushProvider` implementation
+- [x] **Task 1**: `ExpoPushProvider` implementation
   - Description: token validation, chunked send, ticket collection per IP
   - Files: `comms/src/adapters/expoPush.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests pass, one `SendResult` per token
-- [ ] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
+- [x] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
   - Description: poll receipts after configurable delay; map `DeviceNotRegistered` to permanent failure
   - Files: `comms/src/adapters/expoPush.ts`
   - Depends on: Task 1
   - Acceptance: dead token deactivated in test
-- [ ] **Task 3**: Dependency moves
+- [x] **Task 3**: Dependency moves
   - Description: optional peer `expo-server-sdk` on comms; remove from `@terreno/api`
   - Files: `comms/package.json`, `api/package.json`, root catalog if needed
   - Depends on: Task 1
   - Acceptance: `bun install` + full compile pass; api tests unaffected
-- [ ] **Task 4**: example-frontend token registration + dev test-send
+- [x] **Task 4**: example-frontend token registration + dev test-send
   - Description: register token on login via `POST /comms/pushTokens`; profile dev row triggers `sendPushToUser`
   - Files: `example-frontend/app/_layout.tsx` or profile screen, `example-backend` dev route
   - Depends on: Task 1, comms-abstraction Phase 2
   - Acceptance: UI verification per verify-ui-changes with screenshots
-- [ ] **Task 5**: Docs
+- [x] **Task 5**: Docs
   - Description: adapter section in `docs/reference/comms.md` with env/config table
   - Files: `docs/reference/comms.md`
   - Depends on: Task 1

package/src/docs/versioned/next/tasks/comms-adapter-sendgrid.md

@@ -25,15 +25,19 @@ IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
   - Depends on: 1.1
   - Acceptance: boot without key skips registration; compile passes without the SDK installed
 
-## Phase 2 — Delivery events + opt-outs (gated on inbound-webhooks)
+## Phase 2 — Delivery events + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Task 3.3. The tables in the SendGrid IP remain the contract. Do not Pick these on this
+adapter branch.
 
 - [ ] **Task 2.1**: Event Webhook route
   - Description: ECDSA signature verification via inbound-webhooks; event mapping per the IP table → `DeliveryEvent`; `x-message-id` prefix correlation
   - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
+  - Depends on: inbound-webhooks Task 3.3
   - Acceptance: signed fixtures per event type update `CommsMessage.status` (+ `errorCode` for bounce/dropped); unsigned rejected 401
 - [ ] **Task 2.2**: Opt-out events
   - Description: `spamreport`/`unsubscribe`/`group_unsubscribe` → `OptOutEvent` → consumer `onOptOut`
   - Files: `comms/src/adapters/sendgrid.ts` + tests
-  - Depends on: 2.1
+  - Depends on: inbound-webhooks Task 3.3
   - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-sms.md

@@ -4,36 +4,40 @@ IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.m
 
 ## Phase 1 — Send path
 
-- [ ] **Task 1.1**: `TwilioSmsProvider` with config resolution
+- [x] **Task 1.1**: `TwilioSmsProvider` with config resolution
   - Description: constructor/env config, messaging-service-first sender selection
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests cover both sender configs
-- [ ] **Task 1.2**: E.164 validation + error classification
+- [x] **Task 1.2**: E.164 validation + error classification
   - Description: `libphonenumber-js` normalization; Twilio error-code → `errorCode`/`errorClass` map per the IP table (unknown codes → `transient`); full error payload into `CommsMessage.metadata`; Twilio SDK calls wrapped with `withApiErrorHandling`
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: 1.1
-  - Acceptance: invalid number → 400 before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
-- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Acceptance: invalid number → permanent `SendResult` before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
+- [x] **Task 1.3**: Dashboard metadata + hooks coverage
   - Description: `metadata.consoleUrl` deep link per message SID; `onError` fires with the classified `SendResult`
   - Files: `comms/src/adapters/twilioSms.ts` + tests
   - Depends on: 1.2
   - Acceptance: failed-send test asserts consoleUrl and onError invocation
-- [ ] **Task 1.4**: Peer dep + example-backend registration + docs
+- [x] **Task 1.4**: Peer dep + example-backend registration + docs
   - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
   - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: 1.1
   - Acceptance: compile + boot without twilio installed when unconfigured
 
-## Phase 2 — Delivery callbacks + opt-outs (gated on inbound-webhooks)
+## Phase 2 — Delivery callbacks + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Tasks 3.2–3.3. The tables in the Twilio SMS IP remain the contract. Do not Pick these on
+this adapter branch.
 
 - [ ] **Task 2.1**: Status callback route
   - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework; status mapping per IP table incl. `ErrorCode` propagation
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
+  - Depends on: inbound-webhooks Task 3.2
   - Acceptance: signed payload updates `CommsMessage.status` (+ `errorCode` on failure); unsigned rejected 401
 - [ ] **Task 2.2**: STOP/START opt-out handling
   - Description: inbound keyword webhook → `OptOutEvent` → consumer `onOptOut`; opt-in (START) emitted symmetrically
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration + tests
-  - Depends on: 2.1
+  - Depends on: inbound-webhooks Task 3.2
   - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-verify.md

@@ -2,17 +2,17 @@
 
 IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-verify.md)
 
-- [ ] **Task 1**: `TwilioVerifyProvider` start/check
+- [x] **Task 1**: `TwilioVerifyProvider` start/check
   - Description: provider per IP with config resolution and status mapping
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
-- [ ] **Task 2**: Redacted logging + error classification
+- [x] **Task 2**: Redacted logging + error classification
   - Description: `CommsMessage` rows with channel `verification`, fully redacted destination, no codes, and verification channel metadata on start; `errorCode`/`errorClass` mapping (rate-limit transient, expired/max-attempts permanent, bad SID config); rows flagged non-retryable; `onError` fires on failures
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: Task 1
   - Acceptance: log assertion tests prove no code/full destination in any row; failure fixtures assert class + onError
-- [ ] **Task 3**: Registration + docs
+- [x] **Task 3**: Registration + docs
   - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
   - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: Task 1

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

@@ -4,17 +4,17 @@ IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
 
 ## Phase 1 — Backend routes
 
-- [ ] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
+- [x] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
   - Description: rich filters (channel/provider/status/errorClass/errorCode/userId/to/templateId/dates/`q`), pagination, `GET /comms/messages/:id` with attempts + metadata + retained payload
   - Files: `comms/src/routes/commsDashboard.ts` + supertest
   - Depends on: comms-abstraction Phase 2 (incl. hooks/error-taxonomy additions)
   - Acceptance: every filter covered by a supertest case; non-admin 403
-- [ ] **Task 1.2**: `retryMessage` facade + retry route
+- [x] **Task 1.2**: `retryMessage` facade + retry route
   - Description: retryability validation (status, errorClass, payload retention, channel configured, not verification), linked rows via `retriedFromId`/`retriedById`, hooks fire with `isRetry: true`, acting admin recorded
   - Files: `comms/src/commsService.ts`, `comms/src/routes/commsDashboard.ts` + tests
   - Depends on: 1.1
   - Acceptance: each non-retryable reason returns 400 with its stable `code`; successful retry creates a linked row
-- [ ] **Task 1.3**: `retryMany` + `/comms/stats`
+- [x] **Task 1.3**: `retryMany` + `/comms/stats`
   - Description: bulk retry with cap + skipped reasons; aggregation by channel × provider × status with day buckets and failure rate
   - Files: `comms/src/routes/commsDashboard.ts` + tests
   - Depends on: 1.2
@@ -22,17 +22,17 @@ IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
 
 ## Phase 2 — Admin screens
 
-- [ ] **Task 2.1**: `CommsDashboardScreen`
+- [x] **Task 2.1**: `CommsDashboardScreen`
   - Description: stats cards, filter bar (URL-persisted), DataTable with status badges + inline retry
   - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx`, `CommsStatusBadge.tsx`, `useCommsDashboardApi.tsx` + tests
   - Depends on: 1.1, 1.3
   - Acceptance: loading/error/empty states; filters round-trip through the URL
-- [ ] **Task 2.2**: `CommsMessageDetail`
+- [x] **Task 2.2**: `CommsMessageDetail`
   - Description: attempt timeline, provider console links, JSON viewer for payload/metadata, confirmed retry button with disabled-reason tooltips
   - Files: `admin-frontend/src/comms/CommsMessageDetail.tsx` + tests
   - Depends on: 1.2, 2.1
   - Acceptance: non-retryable rows show the specific reason; retry navigates to the new row
-- [ ] **Task 2.3**: Example app + admin-spa wiring
+- [x] **Task 2.3**: Example app + admin-spa wiring
   - Description: expo-router screens under `app/admin/comms/`, admin-spa nav entry, `bun run sdk`
   - Files: `example-frontend/app/admin/comms/*`, `example-frontend/store/openApiSdk.ts`, admin-spa nav
   - Depends on: 2.1, 2.2
@@ -40,12 +40,12 @@ IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
 
 ## Phase 3 — Bulk retry UI + docs
 
-- [ ] **Task 3.1**: "Retry all failed" flow
+- [x] **Task 3.1**: "Retry all failed" flow
   - Description: filtered bulk retry with count confirmation modal; skipped-reason summary toast
   - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx` + tests
   - Depends on: 1.3, 2.1
   - Acceptance: confirmation shows the exact count; result summarizes retried/skipped
-- [ ] **Task 3.2**: Docs + rules
+- [x] **Task 3.2**: Docs + rules
   - Description: dashboard section in comms reference, admin reference update, rulesync
   - Files: `docs/reference/comms.md`, `docs/reference/admin.md`, `.rulesync/**`
   - Depends on: 2.x