@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/tasks/agent-ui-blocks.md

@@ -0,0 +1,114 @@
+# Task List: Agent UI Blocks
+
+**Status:** Approved 2026-09-15 — ready for Pick (`docs/implementationPlans/agent-ui-blocks.md`). Wire format is whole-reply YAML (D2 = b): no fences anywhere in this list.
+**Supporting skills:** `terreno-ui`, `ai-prompt-governance`, `update-docs`, `verify-ui-changes`, `backend-test-env`, `terreno-backend-api`.
+
+Every task is a vertical slice: contract + renderer or producer + docs + Bun tests. Work
+the frontier (blockers complete). Phase 2 chart/table work is additionally blocked on
+[PR #1302](https://github.com/TerrenoLabs/terreno/pull/1302) merging to `master`.
+
+### Phase 1: Contract — `@terreno/blocks`
+
+- [ ] **Task 1.1**: Package scaffold, Zod schema, parser, structural validation
+  - Delivers: `parseBlocks(text)` (strips an optional surrounding ` ```yaml ` fence, YAML or JSON, `NOT_A_DOCUMENT` when not a mapping with `v`), `wrapAsTextDocument(text)`, and `validateBlocks(doc)` reject unknown keys, wrong enums, and wrong top-level key order (`v` → `datasets` → `blocks`, `KEY_ORDER`) with `{path, code, message, fix}`; `v: 1` required; heading/text/metric/badge/divider/context/columns/card blocks and their enums exist.
+  - Files: `blocks/package.json`, `blocks/tsconfig.json`, `blocks/biome.jsonc`, `blocks/src/index.ts`, `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/errors.ts`, `blocks/src/parse.ts`, `blocks/src/validate.ts`, `blocks/src/fixtures/valid/*.yaml`, `blocks/src/fixtures/invalid/*.yaml`, `blocks/src/*.test.ts`; root `package.json` (workspace + catalog `yaml`), `knip.jsonc`, `.github/workflows/blocks-ci.yml` (mirror `comms-ci.yml`) or a `blocks` job in `packages-ci.yml`, plus `.circleci` parity if `check:circleci-parity` requires it.
+  - Blocked by: none
+  - Docs: `docs/reference/blocks.md` (new: grammar tables, limits, error codes), `docs/explanation/agent-ui-blocks.md` (new: why a closed catalog, why whole-reply YAML, approaches considered, ownership diagram), `docs/reference/README.md`, `docs/explanation/README.md`.
+  - Acceptance: AC1 (golden fixtures for the leaf + layout blocks, including a prose-only `text` document), AC2 for structural codes (`UNKNOWN_KEY`, `INVALID_ENUM`, `MISSING_REQUIRED`, `UNSUPPORTED_VERSION`, `DEPTH_EXCEEDED`, `TOO_MANY_BLOCKS`, `KEY_ORDER`, `NOT_A_DOCUMENT`); YAML anchors/tags rejected (`YAML_FEATURE_DISALLOWED`); `bun test blocks/` green; `bun run check:knip` green.
+
+- [ ] **Task 1.2**: Datasets, chart and table schema, semantic lint
+  - Delivers: `datasets` map with two sources — `inline` (typed columns + rows) and `ref` (`{source: ref, id, grain?, limit?}`, D4/Q6); `chart` (`kind`, `data`/`x`/`y` or `points`) and `table` blocks; lint pass for dataset refs, column existence/type (inline; `ref` columns checked when a `knownDatasets` map is passed, deferred otherwise), row arity, id uniqueness, D7 limits including `ref` `limit` caps, chart heuristics as warnings.
+  - Files: `blocks/src/schema.ts`, `blocks/src/lint.ts`, `blocks/src/validate.ts`, `blocks/src/fixtures/**`, `blocks/src/lint.test.ts`, `blocks/src/validate.perf.test.ts`.
+  - Blocked by: 1.1
+  - Docs: `docs/reference/blocks.md` (dataset sources + chart + table sections, warning codes).
+  - Acceptance: AC2 for semantic codes (`DATASET_NOT_FOUND`, `COLUMN_NOT_FOUND`, `COLUMN_TYPE_MISMATCH`, `ROW_ARITY_MISMATCH`, `DUPLICATE_ID`, `DATASET_TOO_LARGE`, `TABLE_TOO_WIDE`, `TOO_MANY_POINTS`) and warnings (`BAR_TOO_MANY_CATEGORIES`, `DONUT_TOO_MANY_SLICES`, `LINE_SINGLE_POINT`); AC18 (`ref` half); AC3 perf test; doc-code parity test reads `docs/reference/blocks.md` and asserts every code in `BLOCK_ERROR_CODES` appears.
+
+- [ ] **Task 1.3**: Actions schema, partial parser, JSON Schema, prompt section, CLI
+  - Delivers: `actions` block with `button`/`segmented` elements and closed `action.kind` set (`reply`, `open`, `select`, `callback`); `validateBlocks(doc, {hostActions?, knownDatasets?})` emits `UNKNOWN_HOST_ACTION` when an allowlist is supplied; `parseBlocksPartial(text)` → `{datasets, blocks, pending}` from a truncated document (completed top-level `blocks` items only, each validated individually, never throws); `blocksJsonSchema`; `blocksPromptSection({hostActions})` that embeds the grammar, key-order rule, limits, the reply rule ("your entire reply is one document; no prose outside it; no text before tool calls"), the `ref` dataset rule ("use the `datasetId` a tool returned; never paste more than 500 rows"), and two examples (data + prose-only); `terreno-blocks validate` CLI bin.
+  - Files: `blocks/src/schema.ts`, `blocks/src/parsePartial.ts`, `blocks/src/jsonSchema.ts`, `blocks/src/prompt.ts`, `blocks/src/cli.ts`, `blocks/package.json` (`bin`), `blocks/src/fixtures/partial/*.yaml`, tests.
+  - Blocked by: 1.2
+  - Docs: `docs/reference/blocks.md` (actions, partial parsing, CLI), `docs/how-to/agent-ui-blocks.md` (new: "validate a document locally" section only).
+  - Acceptance: AC4 (ajv round-trip on fixtures); AC20 (`parsePartial` half: truncated fixtures cut mid-block, mid-dataset, and mid-scalar); `select` with a non-chart/table target → `SELECT_TARGET_INVALID`; CLI exit codes 0/1 asserted via `Bun.spawn`; prompt section snapshot test asserts limits text equals `BLOCK_LIMITS` values (single source of truth).
+
+### Phase 2: Renderer — `@terreno/ui`
+
+- [ ] **Task 2.1**: `BlocksView` for leaf and layout blocks, error and placeholder states
+  - Delivers: `BlocksView` (lazy via `heavyOptionalExports`) renders heading/text/metric/badge/divider/context/columns/card with `@terreno/ui` components; string input is validated; invalid → `Banner` + collapsed raw YAML; non-document string → `wrapAsTextDocument` fallback; `columns` stacks on `sm`.
+  - Files: `ui/package.json` (`@terreno/blocks` dep), `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksError.tsx`, `ui/src/Common.ts` (`BlocksViewProps`), `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `demo/story-config/BlocksView.config.tsx`, `demo/demoConfig.tsx`.
+  - Blocked by: 1.1
+  - Docs: `docs/reference/ui.md` (`BlocksView` section), `docs/explanation/agent-ui-blocks.md` (renderer ownership).
+  - Acceptance: AC5 for the covered blocks (plus an `rg` guard test that `ui/src/blocks/` imports no `react-native` `View`/`Text`); AC6 (both halves); `bun run check:demo-coverage` green; screenshot of the story saved under `/opt/cursor/artifacts/`.
+
+- [ ] **Task 2.2**: Chart and table blocks bound to datasets
+  - Delivers: `chart` renders `BarChart`/`LineChart`/`AreaChart`/`DonutChart` inside a `Card` with title, legend, `emptyText`, `height` map (`sm`/`md`/`lg` → px); `table` renders `DataTable` with typed columns (paginated via `more` for `ref` sources); `ref` datasets resolve through the `resolveDataset` prop (`useResolvedDatasets` hook: `loading` state on the chart, error `Banner` on failure, request de-duplicated per `{id, grain, limit, page}`); per-point `color` is not exposed to the agent.
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/datasetToPoints.ts`, `ui/src/blocks/useResolvedDatasets.ts`, tests, `demo/stories/BlocksView.stories.tsx` (chart presets incl. a mocked `ref` preset).
+  - Blocked by: 1.2, 2.1, PR #1302 merged
+  - Docs: `docs/reference/ui.md`, `docs/how-to/charts-and-dashboards.md` (one paragraph: "charts from agent replies").
+  - Acceptance: AC5 for chart/table; `datasetToPoints` unit tests (date columns formatted with Luxon, numeric parse, empty dataset → `emptyText`); `useResolvedDatasets` tests (loading → data, rejection → banner, no duplicate fetch); screenshot of bar + donut from one dataset.
+
+- [ ] **Task 2.3**: Actions, `onAction`, segmented dataset switch
+  - Delivers: `actions` renders `Button` / `SegmentedControl`; every press calls `onAction({blockId, elementId, messageId, action})`; `select` updates local dataset binding of the target block and still reports; `hostActions` allowlist marks unknown `callback` names as disabled with tooltip; `callback` buttons show `loading` while their id is in `pendingElementIds`; `BlocksView` accepts `overrides: Record<blockId, BlocksDocument>` so a host can replace one block in place (D6 `replace: block`).
+  - Files: `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/useBlockSelections.ts`, `ui/src/Common.ts`, tests, story additions.
+  - Blocked by: 1.3, 2.2
+  - Docs: `docs/reference/ui.md` (`onAction` payload table, `pendingElementIds`, `overrides`), `docs/explanation/agent-ui-blocks.md` (interaction flow incl. server callbacks).
+  - Acceptance: AC8; `onAction` payload snapshot per kind; disabled unknown callback asserted; AC19 (`BlocksView` half: loading + block override).
+
+- [ ] **Task 2.4**: `GPTChat` `uiBlocks` mode, progressive render, Blocks Playground
+  - Delivers: `GPTChat` prop `uiBlocks?: boolean`; when on, assistant messages render through `BlocksView` instead of `MarkdownView` — streaming messages use `parseBlocksPartial` and show completed top-level blocks plus a `Spinner` tail row, completed messages use `parseBlocks` with `wrapAsTextDocument` fallback; forwards `reply` to `onSubmit`, `open`/`select` to `onBlockAction`, and `callback` to `onBlockCallback?: (action) => Promise<{text?, blocks?, replace?}>` — tracking pending element ids, applying `replace: block` via `overrides`, `replace: message` by swapping the message body, and `text` by appending an assistant message; passes `resolveDataset` through; user messages and tool-call cards unchanged; demo Blocks Playground (YAML `TextArea` → live render + error list, fixture presets, "simulate streaming" toggle that feeds the document in 40-char steps).
+  - Files: `ui/src/GPTChat.tsx`, `ui/src/GPTChat.test.tsx`, `ui/src/Common.ts`, `demo/stories/BlocksPlayground.stories.tsx`, `demo/story-config/BlocksPlayground.config.tsx`, `demo/demoConfig.tsx`.
+  - Blocked by: 2.3
+  - Docs: `docs/reference/ui.md` (`GPTChat.uiBlocks`, `onBlockAction`, `onBlockCallback`, `resolveDataset`), `docs/how-to/agent-ui-blocks.md` (playground section).
+  - Acceptance: AC7; AC19 (`GPTChat` half); AC20 (`GPTChat` half: a streaming message cut mid-block renders the preceding blocks and a `Spinner`, never raw YAML); `uiBlocks` off → existing `MarkdownView` path untouched (regression test); playground recording saved under `/opt/cursor/artifacts/`.
+
+### Phase 3: Producer — `@terreno/ai`
+
+- [ ] **Task 3.1**: `uiBlocks` route option, prompt constant, post-stream validation SSE, repair pass
+  - Delivers: `addGptRoutes(router, {uiBlocks: true | UiBlocksOptions})` appends `TERRENO_UI_BLOCKS_SYSTEM_PROMPT` (built from `blocksPromptSection` + host callback names) and pins the blocks temperature preset; the **final step's** `text-delta`s form the document (earlier-step text is logged, not stored as the message); after the stream ends the document is validated with `{hostActions: Object.keys(...), knownDatasets}` and SSE `{blocks: {ok, errors, warnings}}` is emitted before `{done}`; with `repair: true` and `ok: false`, one non-streamed repair call (errors appended) replaces the stored assistant `content` and streams a `{replace: text}` SSE event before `{done}`; validation errors are appended to the stored assistant turn as a system note so the next user turn's context includes them; `AIRequest.metadata.uiBlocks` summary logged.
+  - Files: `ai/package.json` (`@terreno/blocks` dep), `ai/src/service/prompts.ts`, `ai/src/routes/gpt.ts`, `ai/src/types/index.ts` (`HostAction`, `UiBlocksOptions`), `ai/src/routes/gpt.test.ts`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/ai.md` (option + SSE event rows), `docs/how-to/agent-ui-blocks.md` (backend enable section, repair trade-off).
+  - Acceptance: AC9 with a mock model that streams a valid document, an invalid document, and a prose-only non-document; AC18 (`UNKNOWN_HOST_ACTION` half); prompt constant lives at the top of `prompts.ts` (ai-prompt-governance); no SSE `blocks` event and no prompt change when `uiBlocks` is off (regression test).
+
+- [ ] **Task 3.4**: `AIDataset` model, `registerAiDataset`, `GET /gpt/datasets/:id`
+  - Delivers: `AIDataset` Mongoose model (D18: `expiresAt?` with `{expiresAt: 1}, {expireAfterSeconds: 0}` index, `isDeletedPlugin`, descriptions on every field); `configureAiDatasets({datasetTtlDays = 0, datasetMaxRows = 50_000})` called by `addGptRoutes`; `registerAiDataset({userId, historyId, columns, rows})` sets `expiresAt` only when `datasetTtlDays > 0`, rejects over-cap rows with `APIError 413`, and returns `{datasetId, columns, rowCount, preview, stats}` for tool results; `GET /gpt/datasets/:id?grain=&limit=&page=` (`IsOwner`) buckets `date` columns by `grain`, downsamples line/area with LTTB when rows exceed `limit`, paginates tables with `more`; mounted by `addGptRoutes` when `uiBlocks` is on.
+  - Files: `ai/src/models/aiDataset.ts`, `ai/src/service/aiDatasets.ts` (`configureAiDatasets`, `registerAiDataset`, `bucketByGrain`, `lttb`), `ai/src/routes/gptDatasets.ts`, `ai/src/routes/gpt.ts` (mount), `ai/src/types/index.ts`, `ai/src/index.ts`, `ai/src/service/aiDatasets.test.ts`, `ai/src/routes/gptDatasets.test.ts`.
+  - Blocked by: 1.2
+  - Docs: `docs/reference/ai.md` (model + route + helper + options rows), `docs/explanation/agent-ui-blocks.md` ("why rows never pass through the model"; retention defaults to unlimited), `docs/how-to/agent-ui-blocks.md` ("return a dataset from a tool", "set a retention window").
+  - Acceptance: AC16 (including the `datasetTtlDays` 0 vs 7 assertion); `lttb` property test (output length ≤ `limit`, first/last points preserved); mongoose-schema-safety checklist applied (new model, additive only).
+
+- [ ] **Task 3.5**: `POST /gpt/actions` host callback route
+  - Delivers: `POST /gpt/actions` (D19) validates `{historyId, messageId, blockId, elementId, name, payload}`, looks up `hostActions[name]`, validates `payload` against its Zod schema, checks history ownership, runs `handler({payload, user, history, blockId, elementId})` with a 10 s timeout, validates any returned `blocks` with `validateBlocks`, returns `{text?, blocks?, replace?}`, logs `AIRequest` `requestType: "ui_action"`; shares the `/gpt` rate-limit bucket.
+  - Files: `ai/src/routes/gptActions.ts`, `ai/src/routes/gpt.ts` (mount), `ai/src/types/index.ts`, `ai/src/routes/gptActions.test.ts`, `ai/src/models/aiRequest.ts` (`requestType` enum additions).
+  - Blocked by: 3.1
+  - Docs: `docs/reference/ai.md` (route row + `HostAction` type), `docs/how-to/agent-ui-blocks.md` ("register a server callback"), `docs/explanation/agent-ui-blocks.md` (Block Kit `block_actions` comparison table).
+  - Acceptance: AC17; handler timeout returns 504 and is logged; returned invalid `blocks` → 500 with error list (host bug, not agent bug).
+
+- [ ] **Task 3.2**: `AIService.generateBlocks` with bounded repair
+  - Delivers: `generateBlocks({prompt, systemPrompt?, userId?, repair?})` → `Output.object(blocksJsonSchema)` → `validateBlocks`; one repair retry on failure with errors appended to the prompt; `requestType: "ui_blocks"`; throws `APIError 422` with the error list after the retry fails.
+  - Files: `ai/src/service/aiService.ts`, `ai/src/types/index.ts`, `ai/src/service/aiService.test.ts`.
+  - Blocked by: 3.1
+  - Docs: `docs/reference/ai.md` (method table row + temperature preset note).
+  - Acceptance: AC10; deterministic temperature asserted; logged `metadata.errorCodes` on failure.
+
+- [ ] **Task 3.3**: MCP validator tool
+  - Delivers: `terreno_validate_ui_blocks({document})` returns the CLI report text; listed in `ListTools`.
+  - Files: `mcp-server/package.json` (`@terreno/blocks` dep), `mcp-server/src/tools.ts`, `mcp-server/src/tools.test.ts`.
+  - Blocked by: 1.3
+  - Docs: `docs/reference/mcp-server.md` (tool row), `.cursor/rules/mcp-server/00-mcp-server.mdc` via rulesync source `.rulesync/rules/mcp-server/00-mcp-server.md`.
+  - Acceptance: AC11; tool schema snapshot.
+
+### Phase 4: Examples, e2e, docs
+
+- [ ] **Task 4.1**: example-frontend AI tab renders blocks and handles actions
+  - Delivers: `ai.tsx` handles SSE `blocks` event (attaches validation summary to the message for a subtle "n components" caption), passes `onBlockAction` (`open` → `router.push` for `/…` routes or `Linking.openURL` for https), `onBlockCallback` → generated `usePostGptActionsMutation`, `resolveDataset` → generated `useLazyGetGptDatasetsByIdQuery` (SDK regenerated via `bun run sdk`), `reply` flows through existing `onSubmit`; `GPTChat uiBlocks` on; e2e mock streams a whole-reply document (in chunks, to exercise progressive render) with one inline and one `ref` dataset and serves the dataset + action routes.
+  - Files: `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/store/openApiSdk.ts` (generated), `example-frontend/e2e/helpers/mockGpt.ts`, `example-frontend/e2e/ai-chat.spec.ts`.
+  - Blocked by: 2.4, 3.1, 3.4, 3.5
+  - Docs: `docs/how-to/agent-ui-blocks.md` (frontend wiring section), `docs/explanation/example-coverage.md` (capability row).
+  - Acceptance: AC13; recording of prompt → bar chart (from `ref`) → callback button loading → block replaced → follow-up `reply` button → new user message, saved under `/opt/cursor/artifacts/`.
+
+- [ ] **Task 4.2**: example-backend enable, changelog, docs sweep
+  - Delivers: `example-backend` passes `uiBlocks: {hostActions: {exportDataset: {payload, handler}}, repair: true}` (TTL left at the unlimited default) with a handler that returns `{replace: "block", blocks}`; a `todoStats` tool calls `registerAiDataset` so a real prompt produces a `ref` chart; changelog entry; all reference/how-to/explanation pages cross-linked; rules regenerated.
+  - Files: `example-backend/src/server.ts`, `example-backend/src/ai/hostActions.ts`, `example-backend/src/ai/tools.ts`, `changelog/unreleased/agent-ui-blocks.md`, `docs/how-to/README.md`, `docs/reference/README.md`, `docs/explanation/README.md`, `.rulesync/rules/ui/00-ui.md` (BlocksView bullet) → `bun run rules`.
+  - Blocked by: 4.1, 3.2, 3.3
+  - Docs: as listed.
+  - Acceptance: AC14, AC15; `bun run website:build` green; `bun run rules:check` green.

package/src/docs/versioned/next/tasks/announcements-surfaces.md

@@ -0,0 +1,101 @@
+# Task List: Announcement Surfaces, Targeting, and Click Tracking
+
+**Status:** Complete — Phase 4 verified; Taste in progress
+**IP:** `docs/implementationPlans/announcements-surfaces.md`  
+**Parent IP:** `docs/implementationPlans/announcements.md`  
+**Created:** 2026-09-15  
+**Feature profile:** false
+
+Supporting skills for every task: `mongoose-schema-safety` (schema/model work), `terreno-backend-api`, `terreno-ui`, `terreno-data-fetching`, `update-docs`, `verify-ui-changes` (tasks that touch `@terreno/ui` / example-frontend).
+
+## Phase 1: Backend contracts
+
+- [x] **Task 1.1**: Acknowledgement policy + plugin default
+  - Delivers: Per-announcement `acknowledgementPolicy` with consumer `defaultAcknowledgementPolicy`; `acknowledgementMode` and `requiresAcknowledgement` removed from schema/options; public DTO still exposes resolved `requiresAcknowledgement`
+  - Files: `announcements/src/models/announcement.ts`, `announcements/src/types.ts`, `announcements/src/pending.ts`, `announcements/src/announcementsApp.ts`, `announcements/src/tests/*.test.ts`, `example-backend/src/server.ts`
+  - Docs: `docs/reference/announcements.md` (plugin options + policy table)
+  - Blocked by: none
+  - Acceptance: Unit tests cover required / dismiss-only / omitted-field+default / leftover boolean `true` → required. Plugin option `acknowledgementMode` no longer compiles. `GET /pending` `current.requiresAcknowledgement` matches resolution. `bun test announcements/src/tests`
+
+- [x] **Task 1.2**: Display mode, audience type, min build filters
+  - Delivers: `displayMode`, `audienceType`, `minBuildNumber` on `Announcement`; pending is interrupt-only; feed/help honor min build + audience callback; exported `matchAudienceByType`
+  - Files: `announcements/src/models/announcement.ts`, `announcements/src/types.ts`, `announcements/src/pending.ts`, `announcements/src/help.ts`, `announcements/src/announcementsApp.ts`, `announcements/src/index.ts`, `announcements/src/tests/pending.test.ts`, `announcements/src/tests/announcementsApp.test.ts`, `announcements/src/tests/help.test.ts`
+  - Docs: `docs/reference/announcements.md` (fields + query `version`)
+  - Blocked by: 1.1
+  - Acceptance: Pending omits `displayMode: "feed"`. Feed includes feed-only. `minBuildNumber: 10` hidden when `?version=9`, visible when `?version=10` or when `version` omitted. `matchAudienceByType` matrix: all/staff/patient. Schema field `description`s present. Missing new fields on old docs default modal + all.
+
+- [x] **Task 1.3**: CTA click events
+  - Delivers: `AnnouncementClickEvent` model, `POST /announcements/:id/click`, admin list/read
+  - Files: `announcements/src/models/announcementClickEvent.ts`, `announcements/src/types.ts`, `announcements/src/announcementsApp.ts`, `announcements/src/tests/announcementsApp.test.ts`
+  - Docs: `docs/reference/announcements.md` (click route + model)
+  - Blocked by: 1.2
+  - Acceptance: Authenticated POST `{action:"primaryAction"}` inserts a row with version + optional platform. Repeat clicks insert another row. 400 on missing primaryAction or unknown action. 404 when announcement not visible. Admin GET lists events. Unique index not required.
+
+- [x] **Task 1.4**: Admin config endpoint
+  - Delivers: `GET /announcements/config` returns the plugin `defaultAcknowledgementPolicy`
+  - Files: `announcements/src/announcementsApp.ts`, `announcements/src/tests/announcementsApp.test.ts`
+  - Docs: `docs/reference/announcements.md`
+  - Blocked by: 1.1
+  - Acceptance: Admin 200 `{ data: { defaultAcknowledgementPolicy } }`. Non-admin 403. Default in response is `"dismiss-only"` when the constructor omits the option.
+
+## Phase 2: Consumer UI
+
+- [x] **Task 2.1**: Banner surface + version query
+  - Delivers: `AnnouncementBanner`; navigator blocks only for `modal`; banner overlays children; pending/feed requests send build `version`
+  - Files: `ui/src/AnnouncementBanner.tsx`, `ui/src/AnnouncementBanner.test.tsx`, `ui/src/AnnouncementNavigator.tsx`, `ui/src/AnnouncementNavigator.test.tsx`, `ui/src/useAnnouncements.ts`, `ui/src/useAnnouncements.test.ts` (if present), `ui/src/index.tsx`
+  - Docs: `docs/how-to/product-announcements.md` (modal vs banner)
+  - Blocked by: 1.2
+  - Acceptance: Tests: empty queue renders children; modal hides children; banner keeps children and shows `AnnouncementBanner`. Query string includes `platform` and `version` when build number is a finite integer. Public type includes `displayMode`. Feed-only items never appear as `pending.current` (server contract; navigator still ignores unexpected `feed`).
+
+- [x] **Task 2.2**: Client frequency caps
+  - Delivers: Session max, cooldown, skip-first-launch applied to interrupts before show
+  - Files: `ui/src/announcementFrequency.ts`, `ui/src/announcementFrequency.test.ts`, `ui/src/AnnouncementNavigator.tsx`, `ui/src/AnnouncementNavigator.test.tsx`
+  - Docs: `docs/how-to/product-announcements.md` (frequency props)
+  - Blocked by: 2.1
+  - Acceptance: With `maxInterruptionsPerSession: 1`, second pending item this session is not shown until remount of a new session helper. `skipFirstLaunch: true` skips on first launch then stores launched flag. `cooldownHours` skips when last interrupt is inside the window. Defaults: max 1 / session, cooldown off, skipFirstLaunch false. Caps do not filter `useAnnouncements` feed.
+
+- [x] **Task 2.3**: Primary-action click tracking
+  - Delivers: Modal and banner primary buttons call `POST /announcements/:id/click` then open the URL
+  - Files: `ui/src/useAcknowledgeAnnouncement.ts`, `ui/src/AnnouncementScreen.tsx`, `ui/src/AnnouncementScreen.test.tsx`, `ui/src/AnnouncementBanner.tsx`, `ui/src/AnnouncementBanner.test.tsx`
+  - Docs: `docs/reference/announcements.md` (consumer hook)
+  - Blocked by: 1.3, 2.1
+  - Acceptance: Click mutation fires once per press. URL still opens if click POST fails (warn log, do not block navigation). No click POST when `primaryAction` is absent.
+
+## Phase 3: Admin, example, docs
+
+- [x] **Task 3.1**: Admin editor structured targeting
+  - Delivers: Selects for displayMode, audienceType, acknowledgementPolicy (from config), number field for minBuildNumber; list columns; audience JSON remains advanced
+  - Files: `admin-frontend/src/AnnouncementEditor.tsx`, `admin-frontend/src/AnnouncementEditor.test.tsx`, `admin-frontend/src/AnnouncementList.tsx`
+  - Docs: `docs/how-to/product-announcements.md` (admin fields)
+  - Blocked by: 1.2, 1.4
+  - Acceptance: Create form pre-fills policy from config. Save persists new fields (no `requiresAcknowledgement`). Tests cover create payload shape and edit omitting status (existing editor rule).
+
+- [x] **Task 3.2**: Example app + architecture docs
+  - Delivers: Example backend `defaultAcknowledgementPolicy` + `matchAudienceByType` using `user.admin`; seeds one staff modal (required) and one patient banner (dismiss-only); example-frontend navigator frequency documented; parent IP pointer accurate
+  - Files: `example-backend/src/server.ts`, `example-backend/src/scripts/seed-announcements.ts` (and any seed caller), `example-frontend` layout using `AnnouncementNavigator`, `docs/reference/announcements.md`, `docs/how-to/product-announcements.md`, `docs/implementationPlans/announcements.md`, `announcements/README.md`
+  - Docs: listed files — Diátaxis in place, one minimal wiring example
+  - Blocked by: 2.2, 2.3, 3.1
+  - Acceptance: Seed idempotent. Docs tables match shipped options (no `acknowledgementMode`). How-to shows Flourish-style staff vs patient. `bun run website:build` if docs pages changed. Frontend verification: log in to example app, confirm modal vs banner per seed, capture artifacts under `/opt/cursor/artifacts/`.
+
+## Phase 4: Admin launch overview
+
+- [x] **Task 4.1**: Overview API
+  - Delivers: Admin-only `GET /announcements/overview?page=&limit=` with aggregate per-row metrics (impressions, acknowledgements, clicks across all event versions), status/total summaries, deterministic pagination, OpenAPI response schema, integration tests (metrics, totals, pagination, empty state, 401/403)
+  - Files: `announcements/src/overview.ts`, `announcements/src/types.ts`, `announcements/src/announcementsApp.ts`, `announcements/src/index.ts`, `announcements/src/tests/overview.test.ts`
+  - Docs: `docs/reference/announcements.md` (overview route + response shape)
+  - Blocked by: Phase 3
+  - Acceptance: Admin 200 with exact row metrics and totals; non-admin 403; unauth 401; deleted docs excluded; default limit 20 cap 100; `bun test announcements/src/tests/overview.test.ts`
+
+- [x] **Task 4.2**: Admin overview UI
+  - Delivers: `@terreno/admin-frontend` overview screen with summary cards and metrics table backed by generated SDK hook for `/announcements/overview`
+  - Files: `admin-frontend/src/AnnouncementOverview.tsx`, tests, `admin-frontend/src/index.tsx`
+  - Docs: `docs/how-to/product-announcements.md` (admin overview)
+  - Blocked by: 4.1
+  - Acceptance: Admin can open overview, see totals cards and paginated rows with metrics; frontend verification artifacts captured
+
+- [x] **Task 4.3**: Nav and media wiring
+  - Delivers: Grouped Announcements nav with overview + audit models; example-frontend admin route; launch seed with markdown, YouTube, screenshots, and tracked CTA
+  - Files: `announcements/src/announcementsApp.ts` (`adminContribution`), `admin-frontend/src/AdminShell.tsx`, `example-frontend/app/admin/announcements/`, `example-backend/src/scripts/seed-announcements.ts`, `website/static/img/announcements/`
+  - Docs: `docs/how-to/product-announcements.md`
+  - Blocked by: 4.2
+  - Acceptance: Overview reachable from the Announcements sidebar group in the example app; related audit pages share that group; seeded staff modal renders markdown with YouTube and screenshot media

package/src/docs/versioned/next/tasks/announcements.md

@@ -0,0 +1,173 @@
+# Task List: Product Update Announcements
+
+**Status:** In progress — tracer bullet implemented  
+**IP:** `docs/implementationPlans/announcements.md`  
+**Created:** 2026-09-08
+
+**Follow-up tasks (same PR):** [`docs/tasks/announcements-surfaces.md`](announcements-surfaces.md)
+
+Structured task breakdown for automated implementation. Each task should be independently implementable and testable.
+
+## Phase 1: `@terreno/announcements` package + API
+
+- [x] **Task 1.1**: Scaffold `announcements/` workspace package
+  - Description: Add `announcements/package.json` (`@terreno/announcements`), `tsconfig.json`, `biome.jsonc`, `src/index.ts`. Register in root `package.json` workspaces and add `announcements:compile` / `announcements:test` scripts.
+  - Files: `announcements/package.json`, `announcements/tsconfig.json`, `announcements/src/index.ts`, root `package.json`
+  - Depends on: none
+  - Acceptance: `bun run announcements:compile` succeeds; package importable from workspace
+
+- [x] **Task 1.2**: `Announcement` Mongoose model
+  - Description: Schema with all fields from IP (`title`, `body`, `status`, `version`, `priority`, `requiresAcknowledgement`, `audience`, `publishAt`, `expiresAt`, `platforms`, `primaryAction`, `publishedAt`, `archivedAt`). Indexes, plugins (`createdUpdated`, `isDeleted`, `findExactlyOne`), TypeScript document interface. Pre-save hook: when `status === "published"` and `title` or `body` modified, increment `version`.
+  - Files: `announcements/src/models/announcement.ts`, `announcements/src/types.ts`
+  - Depends on: 1.1
+  - Acceptance: Model validates enums, version bump hook covered by unit test
+
+- [x] **Task 1.3**: `AnnouncementAcknowledgement` and `AnnouncementImpression` models
+  - Description: Schemas per IP. Compound unique index on ack `(userId, announcementId, version)`. Impression index on `(announcementId, viewedAt)`.
+  - Files: `announcements/src/models/announcementAcknowledgement.ts`, `announcements/src/models/announcementImpression.ts`
+  - Depends on: 1.1
+  - Acceptance: Models importable; indexes defined
+
+- [x] **Task 1.4**: `AnnouncementsApp` plugin skeleton
+  - Description: Class implementing `TerrenoPlugin`. Constructor accepts `AnnouncementsOptions` (`basePath`, `matchAudience`, `acknowledgementMode`, `permissions`). `register()` mounts router; `adminContribution()` registers admin models and custom editor routes.
+  - Files: `announcements/src/announcementsApp.ts`
+  - Depends on: 1.2, 1.3
+  - Acceptance: Plugin registers with `TerrenoApp` in a smoke test
+
+- [x] **Task 1.5**: Announcement admin CRUD via modelRouter
+  - Description: `modelRouter(Announcement)` at `/announcements` with IsAdmin permissions, queryFields (`status`, `priority`, `title`), default sort `-priority,-publishedAt`. OpenAPI via `createOpenApiBuilder`.
+  - Files: `announcements/src/announcementsApp.ts`
+  - Depends on: 1.4
+  - Acceptance: CRUD endpoints work; admin-only enforced
+
+- [x] **Task 1.6**: `POST /announcements/:id/publish` and `POST /announcements/:id/archive`
+  - Description: Custom admin routes. Publish: only from `draft` (or re-publish rules documented), set `publishedAt`, honor `publishAt` scheduling. Archive: only from `published`, set `archivedAt`.
+  - Files: `announcements/src/announcementsApp.ts`
+  - Depends on: 1.5
+  - Acceptance: Status transitions validated; 400 on invalid transitions
+
+- [x] **Task 1.7**: `GET /announcements/pending`
+  - Description: Filter published, in schedule window, platform match (from `User-Agent` or `?platform=` query), `matchAudience` callback, acknowledgement rules per `acknowledgementMode`. Sort by priority desc, publishedAt desc. Return `{ data: { current, remainingCount } }`.
+  - Files: `announcements/src/announcementsApp.ts`, `announcements/src/pending.ts` (pure filter helper for tests)
+  - Depends on: 1.4
+  - Acceptance: Unit tests for filter matrix; integration test with supertest
+
+- [x] **Task 1.8**: `GET /announcements/feed`
+  - Description: Paginated list of published announcements (same visibility filters as pending except acknowledgement). Support `limit` + `page` or cursor.
+  - Files: `announcements/src/announcementsApp.ts`
+  - Depends on: 1.7
+  - Acceptance: Returns only visible announcements; pagination works
+
+- [x] **Task 1.9**: `POST /announcements/:id/acknowledge` and `POST /announcements/:id/impression`
+  - Description: Ack: create acknowledgement for current announcement version (idempotent). Impression: create impression row with optional platform in body.
+  - Files: `announcements/src/announcementsApp.ts`
+  - Depends on: 1.4
+  - Acceptance: Duplicate ack same version returns 200 without duplicate row; impression creates row
+
+- [x] **Task 1.10**: Acknowledgement + impression admin read routes
+  - Description: modelRouter read-only list/read for admin on both models with populatePaths for `announcementId` and `userId`.
+  - Files: `announcements/src/announcementsApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Admin can list acks and impressions
+
+- [x] **Task 1.11**: Package tests
+  - Description: `announcements/src/tests/` — pending logic, version bump, publish/archive, acknowledge idempotency, matchAudience callback, acknowledgementMode matrix.
+  - Files: `announcements/src/tests/*.test.ts`, `announcements/src/tests/bunSetup.ts`
+  - Depends on: 1.7, 1.9
+  - Acceptance: `bun run announcements:test` passes
+
+## Phase 2: Markdown embeds (`@terreno/ui`)
+
+- [x] **Task 2.1**: YouTube + Loom embed detection utilities
+  - Description: Pure functions: `isYouTubeUrl`, `isLoomUrl`, `toYouTubeEmbedUrl`, `toLoomEmbedUrl`. Handle youtu.be, youtube.com/watch, /embed/, Loom share URLs.
+  - Files: `ui/src/markdownEmbeds.ts`, `ui/src/markdownEmbeds.test.ts`
+  - Depends on: none
+  - Acceptance: Unit tests cover common URL shapes
+
+- [x] **Task 2.2**: Integrate embeds into `MarkdownView`
+  - Description: Custom `rules` / link renderer in `react-native-markdown-display`: matching URLs render embed component (web: iframe in Box; native: WebView with sensible aspect ratio). Non-matching links unchanged.
+  - Files: `ui/src/MarkdownView.tsx`, optional `ui/src/MarkdownEmbed.tsx`
+  - Depends on: 2.1
+  - Acceptance: Render test or snapshot for YouTube + Loom markdown strings on web
+
+## Phase 3: Consumer UI (`@terreno/ui` + `@terreno/rtk`)
+
+- [x] **Task 3.1**: `useAnnouncements` hook
+  - Description: RTK endpoint injection for `GET /announcements/pending` and `GET /announcements/feed`. Returns `{ pending, feed, isLoading, error, refetch }`. Pattern from `useConsentForms`.
+  - Files: `ui/src/useAnnouncements.ts`
+  - Depends on: Phase 1
+  - Acceptance: Hook fetches and caches; tags for invalidation
+
+- [x] **Task 3.2**: `useAcknowledgeAnnouncement` hook
+  - Description: Mutations for acknowledge + impression. Invalidates pending on success.
+  - Files: `ui/src/useAcknowledgeAnnouncement.ts`
+  - Depends on: Phase 1
+  - Acceptance: Mutation works; cache invalidated
+
+- [x] **Task 3.3**: `AnnouncementScreen` component
+  - Description: Renders single announcement: title, MarkdownView body, primaryAction Button (opens URL), acknowledge vs dismiss per ack requirement. Calls impression on mount. Props: `announcement`, `onAcknowledge`, `onDismiss`, `isSubmitting`, `requiresAcknowledgement`.
+  - Files: `ui/src/AnnouncementScreen.tsx`, `ui/src/AnnouncementScreen.test.tsx`
+  - Depends on: 2.2, 3.2
+  - Acceptance: Ack button gated correctly; primary action navigates
+
+- [x] **Task 3.4**: `AnnouncementNavigator` component
+  - Description: Mirror `ConsentNavigator`: loading spinner, error retry, auth pass-through on 401/403, single modal from pending.current, refetch after ack/dismiss until queue empty, then render children.
+  - Files: `ui/src/AnnouncementNavigator.tsx`, `ui/src/AnnouncementNavigator.test.tsx`
+  - Depends on: 3.1, 3.3
+  - Acceptance: Tests cover empty queue, single item, multi-item sequence
+
+- [x] **Task 3.5**: Export from `@terreno/ui`
+  - Description: Export navigator, screen, hooks from `ui/src/index.tsx` and lazy boundary if needed.
+  - Files: `ui/src/index.tsx`
+  - Depends on: 3.4
+  - Acceptance: `import {AnnouncementNavigator} from "@terreno/ui"` works
+
+## Phase 4: Admin UI (`@terreno/admin-frontend`)
+
+- [x] **Task 4.1**: `AnnouncementList` component
+  - Description: DataTable with title, status, priority, version, publishedAt, expiresAt. Create button → editor. Uses admin API hooks.
+  - Files: `admin-frontend/src/AnnouncementList.tsx`
+  - Depends on: Phase 1
+  - Acceptance: Lists announcements; navigation works
+
+- [x] **Task 4.2**: `AnnouncementEditor` component
+  - Description: Full editor per IP: MarkdownEditor for body, preview pane, scheduling fields, platforms multi-select, audience JSON field, primaryAction, requiresAcknowledgement, priority. Header actions: Save, Publish, Archive. Uses `useAdminApi`.
+  - Files: `admin-frontend/src/AnnouncementEditor.tsx`, `admin-frontend/src/AnnouncementEditor.test.tsx`
+  - Depends on: 4.1
+  - Acceptance: Create/edit/publish/archive flows work in isolation tests
+
+- [x] **Task 4.3**: Wire adminContribution custom routes
+  - Description: In `AnnouncementsApp.adminContribution()`, point list/create/edit to `AnnouncementList` / `AnnouncementEditor` (same pattern as consent custom admin screens).
+  - Files: `announcements/src/announcementsApp.ts`, `admin-frontend/src/index.tsx`
+  - Depends on: 4.2
+  - Acceptance: Admin SPA shows custom screens for announcements model
+
+## Phase 5: Example app + documentation
+
+- [x] **Task 5.1**: Integrate into `example-backend`
+  - Description: Register `AnnouncementsApp` with sample `matchAudience` (e.g. pass all or filter on `audience.tier`). Seed one published announcement.
+  - Files: `example-backend/src/server.ts`, `example-backend/src/seed.ts` (or dedicated seed helper)
+  - Depends on: Phase 1
+  - Acceptance: OpenAPI includes announcement routes; seed idempotent
+
+- [x] **Task 5.2**: Integrate into `example-frontend`
+  - Description: Wrap authenticated layout with `AnnouncementNavigator`. Add optional “What’s new” screen using feed hook. Regenerate SDK (`bun run sdk`).
+  - Files: `example-frontend/app/_layout.tsx`, optional `example-frontend/app/whats-new.tsx`
+  - Depends on: Phase 3, 5.1
+  - Acceptance: Modal appears for seeded announcement; ack clears queue
+
+- [x] **Task 5.3**: Admin routes in example-frontend
+  - Description: Expo Router admin paths for announcement list/editor if not covered by admin-spa default model routing.
+  - Files: `example-frontend/app/admin/announcements/` or admin-spa equivalent
+  - Depends on: Phase 4, 5.1
+  - Acceptance: Admin can create and publish from example app
+
+- [x] **Task 5.4**: Documentation
+  - Description: `docs/reference/announcements.md` (API + models), `docs/how-to/product-announcements.md` (consumer wiring, matchAudience, acknowledgementMode). Update package README.
+  - Files: `docs/reference/announcements.md`, `docs/how-to/product-announcements.md`, `announcements/README.md`
+  - Depends on: Phases 1–4
+  - Acceptance: Docs match shipped behavior; linked from relevant explanation pages if applicable
+
+## Tracer bullet (minimum shippable slice)
+
+For first Pick iteration, complete **Tasks 1.1–1.7, 1.9, 1.11, 3.1–3.4, 5.1–5.2** before Phase 4 admin polish if time-boxed — proves `pending → navigator → acknowledge` end-to-end.

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

@@ -2,7 +2,7 @@
 
 **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
+**Issue:** https://github.com/TerrenoLabs/terreno/issues/1218
 
 ## Durable contract
 

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/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/src/docs/versioned/next/tasks/compile-pipeline-dedup.md

@@ -0,0 +1,61 @@
+# Tasks: Compile pipeline dedup
+
+IP: [compile-pipeline-dedup.md](../implementationPlans/compile-pipeline-dedup.md)
+Slice: pipeline-ordering-dedup · Scan goal: reduce-cold-compile-time (305s → 214s)
+
+Tracer-bullet order. Each task names files, acceptance, and verification.
+
+## T0 — Capture baseline artifacts (blocking, no code change)
+
+- **Files:** none (read-only).
+- **Do:** `rm -rf */dist && bun run compile 2>&1 | tee /tmp/baseline-build.log`; copy every
+  package's `dist/` into a baseline snapshot dir for later `diff -r`.
+- **Acceptance:** baseline build log + dist snapshot captured; note the cold time (best of
+  3 already recorded = 305s).
+- **Verify:** snapshot dir exists with per-package `dist/`.
+
+## T1 — Apply the three compile-script edits
+
+- **Files:** `package.json`, `api/package.json`, `admin-backend/package.json`.
+- **Do:**
+  - root `compile` → `bun run --filter '*' compile`
+  - `api` `compile` → `bun tsc`
+  - `admin-backend` `compile` → `bun tsc`
+- **Acceptance:** the three scripts match the IP; `.github/scripts/compile-workspace-deps.js`
+  is untouched (`git diff --stat` excludes it).
+- **Blockers:** none. **Docs:** none yet.
+
+## T2 — Prove correctness: single-build, clean, dist-identical
+
+- **Files:** none (verification).
+- **Do:** `rm -rf */dist && bun run compile 2>&1 | tee /tmp/new-build.log`; then
+  `diff -r` each package's new `dist/` against the T0 snapshot.
+- **Acceptance (IP criteria 1–3):**
+  - exit 0 from clean tree
+  - each buildable `@terreno/*` package appears once; **zero** `Compiling @terreno/... with
+    bun tsc` lines (that string only comes from `compile-workspace-deps.js`, which must not
+    run during the dev build)
+  - `diff -r` reports no differences in any `dist/`
+- **Verify:** grep `/tmp/new-build.log` for per-package compile count and for
+  `compile-workspace-deps` output (expect none).
+
+## T3 — Prove publish/CI unaffected
+
+- **Files:** none (verification).
+- **Do:** confirm `compile-workspace-deps.js` unchanged; re-read each caller
+  (`publish-on-tag.yml`, `.circleci/continue-config.yml`, `new-file-coverage.yml`,
+  `rtk-ci.yml`, `example-*-ci.yml`, `scripts/ci/*.sh`) and confirm each still calls the
+  script directly before its compile step.
+- **Acceptance (IP criterion 5):** every publish/CI compile is preceded by a direct
+  `compile-workspace-deps.js` call; script content unchanged.
+
+## T4 — Measure + docs
+
+- **Files:** build/compile explanation doc (if the root `compile` contract is documented).
+- **Do:** run the metric command best-of-3
+  (`find . -maxdepth 2 -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete; rm -rf */dist; time bun run compile`);
+  record min. Update the build doc to note reliance on Bun topological ordering (via
+  `update-docs` skill).
+- **Acceptance (IP criteria 4, 6):** cold time recorded with delta vs 305s; `bun run lint`,
+  `bun run api:test`, `bun run ui:test` green.
+- **Verify:** three timings recorded; lint/test exit 0.