@terreno/mcp 57.14.0 → 57.16.1

package/dist/docs/versioned/57.15.0/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/dist/docs/versioned/57.15.0/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/TerrenoLabs/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/dist/docs/versioned/57.15.0/tasks/billing-stripe.md

@@ -0,0 +1,75 @@
+# Tasks: Stripe billing and subscriptions
+
+IP: [billing-stripe](../implementationPlans/billing-stripe.md)
+
+## Phase 1 — Package + models
+
+- [ ] **Task 1.1**: Scaffold `@terreno/billing` package
+  - Description: workspace package mirroring `feature-flags/`; root scripts
+  - Files: `billing/package.json`, `billing/tsconfig.json`, root `package.json`
+  - Depends on: none
+  - Acceptance: compile + lint pass
+- [ ] **Task 1.2**: Models (BillingCustomer, BillingSubscription, BillingEvent)
+  - Description: per IP with unique indexes and descriptions
+  - Files: `billing/src/models/*`
+  - Depends on: 1.1
+  - Acceptance: unit tests incl. unique-index violations
+- [ ] **Task 1.3**: Plan config validation
+  - Description: `plans` option schema (Zod), duplicate/missing price detection at startup
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 1.1
+  - Acceptance: bad config fails fast with clear error
+
+## Phase 2 — Checkout + portal + entitlements
+
+- [ ] **Task 2.1**: Customer creation + checkout/portal session routes
+  - Description: `POST /billing/checkoutSession` (IsOrgAdmin), `POST /billing/portalSession`, `GET /billing/plans`
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 1.2, org-management-ui Phase 3
+  - Acceptance: mocked-Stripe supertest incl. permission denials
+- [ ] **Task 2.2**: `getEntitlements` + `planSegment` + `RequiresPlan`
+  - Description: cache-backed entitlement service; feature-flag segment factory; permission
+  - Files: `billing/src/billingService.ts`
+  - Depends on: 1.2
+  - Acceptance: zero inline Stripe calls asserted; flag targeting test with FeatureFlagsApp
+- [ ] **Task 2.3**: `GET /billing/subscription`
+  - Description: org subscription + entitlements for members
+  - Files: `billing/src/billingApp.ts`
+  - Depends on: 2.2
+  - Acceptance: supertest member/non-member
+
+## Phase 3 — Webhook sync (gated on inbound-webhooks)
+
+- [ ] **Task 3.1**: Stripe webhook route with signature verification
+  - Description: raw-body route via inbound-webhooks; reject unsigned
+  - Files: `billing/src/stripeSync.ts`
+  - Depends on: inbound-webhooks IP
+  - Acceptance: signed/unsigned fixture tests
+- [ ] **Task 3.2**: Idempotent event handlers
+  - Description: checkout.session.completed, subscription created/updated/deleted, invoice paid/payment_failed → model sync via `BillingEvent`
+  - Files: `billing/src/stripeSync.ts`
+  - Depends on: 3.1
+  - Acceptance: replay of same event id is a no-op; cancellation downgrades after webhook
+- [ ] **Task 3.3**: Dunning email
+  - Description: `paymentFailed` template through comms when configured
+  - Files: `billing/src/stripeSync.ts`, `comms/src/templates.ts`
+  - Depends on: 3.2, comms-abstraction
+  - Acceptance: template send asserted on payment_failed fixture
+
+## Phase 4 — UI + example + docs
+
+- [ ] **Task 4.1**: Plan picker + billing settings screens
+  - Description: example-frontend screens per IP; SDK regen
+  - Files: `example-frontend/app/**`, `store/openApiSdk.ts`
+  - Depends on: Phase 2
+  - Acceptance: UI verification evidence per verify-ui-changes (Stripe test mode)
+- [ ] **Task 4.2**: example-backend registration + seeds + docs
+  - Description: env-gated BillingApp; test-mode setup guide; how-to + reference docs
+  - Files: `example-backend/src/server.ts`, `docs/how-to/add-billing.md`, `docs/reference/billing.md`
+  - Depends on: Phase 2
+  - Acceptance: docs build + `bun run rules:check` pass
+- [ ] **Task 4.3**: CI + publish wiring
+  - Description: billing-ci workflow; publish-on-tag entry
+  - Files: `.github/workflows/*`
+  - Depends on: 1.1
+  - Acceptance: CI green

package/dist/docs/versioned/57.15.0/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`
+
+- [x] **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
+
+- [x] **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
+
+- [x] **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
+- [x] **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/dist/docs/versioned/57.15.0/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/TerrenoLabs/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/dist/docs/versioned/57.15.0/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
+
+- [x] **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
+- [x] **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
+
+- [x] **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
+- [x] **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
+
+- [x] **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
+- [x] **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/dist/docs/versioned/57.15.0/tasks/comms-abstraction.md

@@ -0,0 +1,96 @@
+# Tasks: Pluggable communications layer (@terreno/comms)
+
+IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
+
+## Phase 1 — Package + contracts
+
+- [x] **Task 1.1**: Scaffold `@terreno/comms` workspace package
+  - Description: `comms/` package with tsconfig/biome/bun test setup mirroring `feature-flags/`; root workspace entry + `comms:*` scripts
+  - Files: `comms/package.json`, `comms/tsconfig.json`, `comms/biome.jsonc`, root `package.json`
+  - Depends on: none
+  - Acceptance: `bun run comms:compile` and `bun run comms:lint` pass
+- [x] **Task 1.2**: Finish provider types for remaining contracts
+  - Description: Add `cancelled` to `CommsMessageStatus`; expand `CommsHookContext` (`message`, `userId`, `isRetry`, `attempt`, `messageId`); add `OptOutEvent`; add `errorCode`/`errorClass` on `DeliveryEvent`; keep shipped `onRetry(context, result)` and `isPermanentFailure` alias
+  - Status: base provider/message/`errorCode`/`errorClass` shipped; listed fields remain
+  - Files: `comms/src/types.ts`, `comms/src/index.ts`
+  - Depends on: 1.1
+  - Acceptance: types compile and are exported; existing SendGrid tests still typecheck against `onRetry(context, result)`
+- [x] **Task 1.3**: Console adapters
+  - Description: dev adapters for all four channels logging via `logger.info`
+  - Files: `comms/src/adapters/console.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: each adapter returns `accepted: true` and logs
+- [x] **Task 1.4**: `CommsMessage` attempt history + dashboard fields
+  - Description: add `status: cancelled`, `attempts[]`, `attemptCount`, `lastAttemptAt`, `retriedFromId`/`retriedById`, `templateId`, `payload`, `payloadExpiresAt`; `logSend` creates the first row; `appendAttempt` never throws; `clearExpiredPayloads` unsets expired `payload` only (limit 50)
+  - Files: `comms/src/models/commsMessage.ts`, `comms/src/modelTypes.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: send logging survives a forced model error (logged, not thrown); a second attempt appends without a second row; Mongo TTL index is not used
+  - Status: model, `errorCode`/`errorClass`, and non-throwing `logSend` shipped; listed fields remain
+- [x] **Task 1.5**: Channel-wide transient retry + no rethrow
+  - Description: wrap provider throws as `{accepted: false, errorClass: "transient", errorCode: "provider-throw"}`; retry once on transient for `sendMail`, `sendSms`, `startVerification`; for `sendPushToUser`, retry only tokens whose first result is transient; do not retry `checkVerification`; prune tokens when `errorClass === "permanent"` or `isPermanentFailure === true`
+  - Status: mail retry shipped; SMS/push/verification still rethrow; prune is `isPermanentFailure` only
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 1.2, 1.3, 1.4
+  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes; permanent/config failures do not retry; SMS throw returns a `SendResult` instead of rejecting
+- [x] **Task 1.6**: Lifecycle hooks + event intake
+  - Description: `beforeSend` (mutate/cancel, once before first attempt; throwing beforeSend = no cancel); `onSend`/`onError`/`onRetry` (keep `(context, result)`, set `context.attempt`); `recordDeliveryEvent` / `recordOptOut` invoke `onDeliveryEvent` / `onOptOut` and update the log row by `providerMessageId` when present; wrap every hook
+  - Files: `comms/src/commsService.ts`, `comms/src/types.ts` + tests
+  - Depends on: 1.5
+  - Acceptance: one test per hook (fires with correct context) plus one throwing-hook test per hook; cancelled send has `status: "cancelled"` and zero provider calls
+- [x] **Task 1.7**: Payload retention + redaction
+  - Description: `retainPayloadDays` (default 30) stores the channel payload after `redactPayload`; `retainPayloadDays: 0` stores nothing; push payload omits tokens; verification start stores `{channel}` only; `clearExpiredPayloads` runs best-effort from `logSend`/`appendAttempt`
+  - Files: `comms/src/commsService.ts`, `comms/src/models/commsMessage.ts` + tests
+  - Depends on: 1.4, 1.5, 1.6
+  - Acceptance: payload stored redacted; expired payload cleared without deleting the row; `retainPayloadDays: 0` stores nothing
+
+## Phase 2 — CommsApp + routes
+
+- [x] **Task 2.1**: `PushToken` model
+  - Description: model per IP with unique token upsert semantics
+  - Files: `comms/src/models/pushToken.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: duplicate token registration updates the existing row
+- [x] **Task 2.2**: `CommsApp` TerrenoPlugin
+  - Description: options wiring, `getCommsService()` accessor, route mounting on `register()`
+  - Files: `comms/src/commsApp.ts` + tests
+  - Depends on: 1.5, 2.1
+  - Acceptance: plugin registers on `TerrenoApp` and service accessor returns configured providers
+- [x] **Task 2.3**: Push token routes
+  - Description: custom idempotent registration/list/deactivation endpoints plus modelRouter owner read; persisted `userId` scoping
+  - Files: `comms/src/routes/pushTokens.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: acceptance criteria bullets 2 pass under supertest
+- [x] **Task 2.4**: Admin delivery explorer
+  - Description: `GET /comms/messages` admin-only, paginated, filtered; OpenAPI builder
+  - Files: `comms/src/routes/commsExplorer.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: non-admin gets 403; filters work
+- [x] **Task 2.5**: `sendPushToUser` token resolution + pruning
+  - Description: resolve active tokens per user; deactivate tokens whose `SendResult` reports permanent failure
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 2.1, 1.5
+  - Acceptance: dead token is `active: false` after a failed send
+  - Note: remaining prune-by-`errorClass` work is in Task 1.5
+
+## Phase 3 — Integration + docs
+
+- [x] **Task 3.1**: example-backend registration
+  - Description: register `CommsApp` with console adapters; env-gated
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 2.2
+  - Acceptance: backend boots; `/comms/pushTokens` in `/openapi.json`
+- [x] **Task 3.2**: Reference docs + rules
+  - Description: `docs/reference/comms.md`, rulesync source rule, `bun run rules`
+  - Files: `docs/reference/comms.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes
+- [x] **Task 3.3**: CI + publish wiring
+  - Description: `comms-ci` workflow; add `@terreno/comms` to `publish-on-tag.yml`
+  - Files: `.github/workflows/comms-ci.yml`, `.github/workflows/publish-on-tag.yml`
+  - Depends on: 1.x
+  - Acceptance: CI green on the PR
+- [x] **Task 3.4**: Docs refresh for gap-fill APIs
+  - Description: document `beforeSend`, `recordDeliveryEvent`/`recordOptOut`, attempt history, payload retention, channel-wide retry, and the `onRetry`/`isPermanentFailure` aliases in reference docs + comms rule
+  - Files: `docs/reference/comms.md`, `.rulesync/rules/comms/00-comms.md`
+  - Depends on: 1.6, 1.7
+  - Acceptance: `bun run rules:check` passes; docs match the Approved IP

package/dist/docs/versioned/57.15.0/tasks/comms-adapter-expo-push.md

@@ -0,0 +1,29 @@
+# Tasks: Comms adapter — Expo push notifications
+
+IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
+
+- [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
+- [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
+- [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
+- [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
+- [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
+  - Acceptance: docs build passes