@terreno/mcp 57.7.0 → 57.9.0

package/dist/docs/versioned/next/tasks/demo-workshop.md

@@ -0,0 +1,150 @@
+# Task List: Demo workshop
+
+See: [`docs/implementationPlans/demo-workshop.md`](../implementationPlans/demo-workshop.md)
+
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Work the frontier: any task whose blockers are complete. The tracer is Task 1.1 (Button).
+- Do not start iOS work, a translation catalog, or an addon API.
+- Docs named on a task ship in that task. Use the `update-docs` skill.
+- UI tasks also use `verify-ui-changes` and `terreno-ui`.
+- Visual tasks use `review-chart-visuals` for the PNG diff workflow, then the new demo how-to.
+- Run the task's verification command before handoff. `bun run lint` and `bun run demo:compile` on every demo task.
+
+## Phase 1: Catalog, snippets, and preview bar
+
+- [x] **Task 1.1**: Button catalog contract
+  - Delivers: Button has a copyable usage snippet, resolvable related links, stable stories, one declarative interaction list, and typed control defaults.
+  - Files: `demo/demoConfig.tsx`, `demo/story-config/Button.config.tsx`, `demo/stories/Button.stories.tsx`, `demo/collectRegisteredStoryRenders.ts`, `demo/app/demo/[component].tsx`, `demo/README.md`
+  - Blocked by: none
+  - Acceptance: a unit test fails when a related name does not resolve, when an excluded story has an empty reason, or when a boolean control defaults to `""`. Button's snippet renders and copies. `showInDemo: false` hides a Button story in demo mode and leaves it on the dev route.
+  - Verification: `bun test demo/collectRegisteredStoryRenders.ts demo/demoConfig` (or the new colocated test), `bun run demo:compile`, and a web demo pass that opens Button, copies the snippet, and follows one related link.
+  - Docs: `demo/README.md` catalog-contract section
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.2**: Search, categories, and related links
+  - Delivers: the home grid and dev index filter by text and category, and every component's related row is links.
+  - Files: `demo/components/DemoHomePage.tsx`, `demo/components/DevHomePage.tsx`, `demo/app/demo/[component].tsx`, story configs whose `related` strings do not resolve, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: searching "button" shows Button; choosing a category hides other categories; a broken related name fails the catalog test; the home grid still does not nest pressables (`demo/components/DemoCard.test.tsx`).
+  - Verification: catalog unit test, `demo/components/DemoCard.test.tsx`, and a web demo pass of search, category filter, and a related link.
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.3**: Usage snippet on every component
+  - Delivers: every registered story config has `usageExample`, and the component page can copy it.
+  - Files: `demo/story-config/*.config.tsx`, `demo/app/demo/[component].tsx`, `scripts/check-demo-coverage.ts` or a sibling check, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run check:demo-coverage` (or the new snippet check it calls) fails when any registered config lacks a non-empty `usageExample`. The Button page copy control still works.
+  - Verification: the check command, plus one web copy action on a second component (TextField).
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [x] **Task 1.4**: Preview toolbar and URL state
+  - Delivers: demo and dev component routes change theme, viewport, background, locale, right-to-left, and reduced motion from the URL. Embeds apply that state and hide the bar.
+  - Files: `demo/components/DemoChrome.tsx`, `demo/app/_layout.tsx`, `demo/app/demo/_layout.tsx`, `demo/app/dev/_layout.tsx`, `demo/contexts/EmbedModeContext.tsx`, `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: Button at a documented query uses the dark remap and the 375 viewport. Consent or date stories that already read locale receive the toolbar locale. Embed hides the bar. Reloading keeps the query.
+  - Verification: a focused demo unit test for query parse/serialize, `bun run demo:compile`, and a web demo pass of the Button query plus one embed URL.
+  - Docs: `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+## Phase 2: Web proof and health
+
+- [ ] **Task 2.1**: Web interaction and axe for Button
+  - Delivers: Playwright runs Button's step list and axe against the Button stories.
+  - Files: `scripts/demo/runWebStoryChecks.ts`, `demo/story-config/Button.config.tsx`, root `package.json` (axe dependency if needed), `.circleci/config.yml`, `.circleci/continue-config.yml`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Blocked by: Task 1.1
+  - Acceptance: the Button interaction steps pass in Chromium. A serious axe violation fails the command. An excluded story with a reason is skipped. The job is required for `ui/**` and `demo/**` pull requests.
+  - Verification: `bun run demo:web-checks --only=Button` (the script this task adds) locally against demo web, then the CircleCI path-filter test if one exists beside `.circleci/`.
+  - Docs: `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 2.2**: Web visual harness for Button
+  - Delivers: one cropped web PNG baseline for each stable Button story, compared with the chart pixel matcher.
+  - Files: `scripts/demo/compareDemoSnapshots.ts`, `demo/rendered-snapshots/web/`, `scripts/charts/compareChartImages.ts` (reuse only), `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run demo:snapshots:compare --only=Button` passes against the new goldens and fails when a golden is missing. Chart compare still passes for the existing chart fixtures.
+  - Verification: the new compare command and `bun run ui:charts:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`, `docs/how-to/compare-chart-rendered-snapshots.md` (pointer only)
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.3**: Web proof for every stable story
+  - Delivers: every stable story has interaction steps or an exclusion reason, an axe run, and a web PNG baseline.
+  - Files: `demo/story-config/*.config.tsx`, `demo/stories/*.stories.tsx`, `demo/rendered-snapshots/web/`, the web check and snapshot scripts
+  - Blocked by: Task 2.1, Task 2.2
+  - Acceptance: the web check and snapshot commands, with no `--only`, exit 0. Removing one stable story's golden or steps fails the matching command. Excluded stories name a reason.
+  - Verification: `bun run demo:web-checks` and `bun run demo:snapshots:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.4**: Story health and CI summary
+  - Delivers: the component page shows render, interaction, accessibility, and visual status from `demo/story-health.json`. CI stores that file and writes a check summary.
+  - Files: `demo/app/demo/[component].tsx`, `scripts/demo/writeStoryHealth.ts`, `.circleci/continue-config.yml`, `docs/reference/test.md`
+  - Blocked by: Task 2.3
+  - Acceptance: Button shows a pass row after the web commands. A forced failing story shows fail. A missing health file shows not-run. The CircleCI job summary lists failed story ids. The job does not call `gh pr comment`.
+  - Verification: unit test for health rendering, the web commands, and a CI config test or review that the job uploads artifacts and writes the summary.
+  - Docs: `docs/reference/test.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+## Phase 3: Android
+
+- [ ] **Task 3.1**: Android proof for Button
+  - Delivers: a CircleCI Android emulator job runs Button's steps, accessibility-tree assertions, and a cropped Android PNG.
+  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`, `scripts/demo/generateMaestroFlows.ts`, `.maestro/flows/demo/generated/`, `demo/rendered-snapshots/android/`, `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`
+  - Blocked by: Task 2.1
+  - Acceptance: Pixel 6 API 34 runs the generated Button flow. The job is required when `ui/**` or `demo/**` changes. A missing Android golden fails the job. Web axe is unchanged.
+  - Verification: the local Maestro command documented in the how-to, against an emulator, for the Button flow. Record the CircleCI job name.
+  - Docs: `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 3.2**: Android proof for every stable story
+  - Delivers: every stable story has an Android flow, accessibility-tree check, and PNG, or an exclusion reason.
+  - Files: generated Maestro flows, `demo/rendered-snapshots/android/`, `demo/story-health.json` writer
+  - Blocked by: Task 3.1, Task 2.3
+  - Acceptance: the Android job without `--only` exits 0. Health on Button includes the Android columns. An excluded story is absent from the Android failure list and its reason is in the summary.
+  - Verification: the Android compare and Maestro commands across the stable catalog.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+## Phase 4: Major versions
+
+- [ ] **Task 4.1**: Version manifest and dropdown
+  - Delivers: production stays on the current major, `versions.json` lists released majors and a `preview/<major>` branch, and the top bar dropdown navigates there. The default is the highest released major.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `scripts/ci/netlify-deploy.sh`, `demo/components/DemoChrome.tsx`, `docs/how-to/demo-versions.md`, `.circleci/continue-config.yml`
+  - Blocked by: Task 1.4
+  - Acceptance: a unit test of the manifest builder marks `preview/58` as preview and not current, marks 57 as current, and omits `pr-*` aliases. The dropdown on the home page shows those labels. `versions.json` on the production origin sends CORS headers the aliases can read.
+  - Verification: the manifest unit test, a deploy dry-run, and a web demo pass of the dropdown.
+  - Docs: `docs/how-to/demo-versions.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 4.2**: Freeze the previous major and backfill 56
+  - Delivers: moving master from 57 to a later major freezes 57 on alias `v57`. Alias `v56` serves the last master commit whose package major is 56.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `.circleci/continue-config.yml`, `docs/how-to/demo-versions.md`
+  - Blocked by: Task 4.1
+  - Acceptance: a test with a fake deploy history freezes the previous production deploy when the major increases, and leaves 57 updating on ordinary master commits. The backfill command documents the git revision it deployed for 56.
+  - Verification: unit test of the freeze decision, plus the one-time 56 alias deploy recorded in the how-to.
+  - Docs: `docs/how-to/demo-versions.md`
+  - Skills: `update-docs`
+
+- [ ] **Task 4.3**: Docs embeds follow the demo major
+  - Delivers: a 57 docs page embeds the 57 demo. The next docs version embeds the 58 preview when the manifest lists it.
+  - Files: `website/docusaurus.config.ts`, `website/src/components/ComponentDemo/index.tsx`, `docs/how-to/demo-versions.md`, the docs reference page that describes component embeds
+  - Blocked by: Task 4.1
+  - Acceptance: `ComponentDemo` for the 57 docs build requests the 57 demo URL with `?embed=1`. When the manifest has an unreleased preview, the next docs build uses that preview URL. A missing preview falls back to production.
+  - Verification: a website unit test or build-arg test for the URL choice, and `bun run website:build`.
+  - Docs: `docs/how-to/demo-versions.md` and the existing component-embed reference section
+  - Skills: `update-docs`
+
+## Phase 5: MCP catalog
+
+- [ ] **Task 5.1**: Public demo catalog tools
+  - Delivers: `terreno_list_demo_stories` and `terreno_get_demo_story` return Button's snippet, route, story ids, and the version manifest URL.
+  - Files: `demo/demo-catalog.json`, `demo/package.json`, `mcp-server/src/tools.ts`, MCP tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 1.3, Task 4.1
+  - Acceptance: `terreno_get_demo_story` for Button includes `usageExample` and a `/demo/Button` route. The list tool filters by category. The response points at production `versions.json`. A catalog drift test fails when a registered component is missing from the JSON.
+  - Verification: `cd mcp-server && bun test` for the new tool tests, and `bun run demo:catalog` followed by the drift check.
+  - Docs: `docs/reference/mcp-server.md`, `demo/README.md`
+  - Skills: `update-docs`

package/package.json

@@ -11,7 +11,7 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.7.0",
+    "@terreno/api": "57.9.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -104,5 +104,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.7.0"
+  "version": "57.9.0"
 }

package/src/docs/resources/ui.md

@@ -253,7 +253,7 @@ radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radius3xl
 ## Utilities
 
 ```typescript
-import { useStoredState, MediaQuery, isMobileDevice } from "@terreno/ui";
+import { useStoredState, MediaQuery, isNarrowViewport } from "@terreno/ui";
 
 // Persist state to storage
 const [value, setValue] = useStoredState("key", defaultValue);
@@ -263,9 +263,10 @@ const [value, setValue] = useStoredState("key", defaultValue);
   <DesktopLayout />
 </MediaQuery>
 
-// Device detection
-if (isMobileDevice()) {
-  // Mobile-specific code
+// Current window is below the desktop breakpoint.
+// isMobileDevice() is deprecated in favor of isNarrowViewport().
+if (isNarrowViewport()) {
+  // Narrow-viewport code
 }
 ```
 

package/src/docs/upgrades/57.8.0.md

@@ -0,0 +1,61 @@
+# Upgrading to 57.8.0
+
+**Action required:** No
+**Affected packages:** @terreno/ui, @terreno/announcements
+
+## Summary
+
+Bump every lockstep `@terreno/*` package together to `57.8.0`. `@terreno/ui` adds opt-in `SplitPage` web layouts and `IconButton` `backgroundOpacity`, and deprecates `isMobileDevice` in favor of `isNarrowViewport` (the old function still returns the same result). `@terreno/announcements` can import a Markdown release pack through `POST /announcements/import-release`. `DropdownPanel` anchors to its trigger, and `/gpt/prompt` emits each generated image once. No Expo upgrade is required if you are already on `57.x`.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+### `isMobileDevice`
+
+**What changed**
+
+`isMobileDevice` is deprecated. `isNarrowViewport` is the supported name. Both stay exported and return the same boolean: true when the window is below the supported desktop floor (web width under 1024, native width under 1024).
+
+**Why**
+
+`isMobileDevice` described a window-width check. The new name matches that behavior.
+
+**Migration**
+
+```typescript
+// Before
+import {isMobileDevice} from "@terreno/ui";
+
+if (isMobileDevice()) {
+  // narrow layout
+}
+
+// After
+import {isNarrowViewport} from "@terreno/ui";
+
+if (isNarrowViewport()) {
+  // narrow layout
+}
+```
+
+## New capabilities
+
+`SplitPage` web props are opt-in. Existing callers keep the previous layout.
+
+- `desktopChildrenMinWidth` keeps one or two desktop children at least that many pixels wide and scrolls the row when it is tighter. More than two children keeps the segmented control.
+- `narrowViewportChildLabels`, `narrowViewportSelectionActive`, `narrowViewportSelectionKey`, and `narrowViewportListButtonLabel` replace the dotted narrow swiper with a labeled pager.
+- `narrowBelowWidth` uses the narrow layout when the window width is less than or equal to that pixel value. Omit it to follow `isNarrowViewport()`.
+- Native `SplitPage` ignores these props.
+- `IconButton` `backgroundOpacity` tints only that button's background.
+
+`@terreno/announcements` accepts a `terreno.announcement-pack/v1` directory (`pack.yaml` plus one Markdown file per announcement) at `POST /announcements/import-release`. Imports are idempotent by product, release version, channel, and slug, default to drafts, and publish immediately when `publish: true`. Admin auth or bearer `ANNOUNCEMENTS_UPLOAD_TOKEN` can call the route. The token is optional.
+
+## Verification
+
+- `bun add` every lockstep `@terreno/*` dependency to `57.8.0`, then `bun run compile` at the app root
+- Replace `isMobileDevice` imports with `isNarrowViewport` before a future major removes the alias
+- Open a `DropdownPanel` whose trigger is not at the start of its row and confirm the panel opens on the trigger
+- Import a draft announcement pack with `POST /announcements/import-release` and confirm a second import updates the same slug instead of inserting a duplicate

package/src/docs/upgrades/57.9.0.md

@@ -0,0 +1,28 @@
+# Upgrading to 57.9.0
+
+**Action required:** No
+**Affected packages:** @terreno/ai, @terreno/ui
+
+## Summary
+
+This release adds durable and resumable GPT chat streams, safer attachment handling, operations-dashboard components, and improved web toast and file-picker behavior. Existing applications continue to work without migration.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+None
+
+## New capabilities
+
+- Configure `fileStorageService` to persist chat attachments and resume in-flight replies through `GET /gpt/histories/:id/stream`.
+- Compose operations dashboards with scorecards, comparison series, spanning items, and richer chart presentation.
+- Set `maxHeight` on growing `TextField` and `TextArea` components.
+
+## Verification
+
+- Run `bun run compile` and `bun run lint` at the app root.
+- Exercise GPT chat attachment upload, reload during a response, and stream resumption when adopting the new AI capabilities.
+- Check web toasts above an open modal and file selection through `FilePickerButton`.

package/src/docs/versioned/next/explanation/charts.md

@@ -20,6 +20,14 @@ Height works the same way: `height` is the whole chart, and the tick row, toolti
 row come out of that budget. A chart therefore fits a fixed-height slot, and reserving the tooltip
 row even when no tooltip is showing keeps hovering from reflowing the page.
 
+Cartesian facades use `xTickPolicy="auto"` by default: up to seven categorical labels
+stay horizontal, while denser sets rotate 45 degrees and reserve a taller axis row.
+That taller row comes out of `height`; the plot shrinks so the chart still fits the
+requested slot. `SparklineChart` scales to the data range so a small period-over-period
+change stays visible.
+Callers may force `"truncate"` or `"rotate"`. `title` and `periodLabel` are convenience
+props backed by the same `ChartCard` used for explicit chart/table composition.
+
 `DashboardGrid` is layout only, so it stays on the eager root export. Chart implementations sit behind the same lazy root boundary as `GPTChat`. Cell width subtracts flex `gap` so `md`/`lg` column counts actually fit.
 
 Chart paint is proven with **rendered PNG goldens**, not React test-renderer JSON.
@@ -27,3 +35,7 @@ Chart paint is proven with **rendered PNG goldens**, not React test-renderer JSO
 (`/demo/chart-visual-gallery`), screenshots each fixture from easy to hard, and
 pixel-diffs against `demo/rendered-snapshots/`. Agents use the `review-chart-visuals`
 skill to read golden / actual / diff images when a compare fails.
+
+The example app admin home (`/admin`) mounts `AdminCharts` so scorecards, a multi-series line,
+bars, an area, and a donut with a center label render together. See
+[Compose charts in a dashboard grid](../how-to/charts-and-dashboards.md).

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -20,7 +20,8 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
 | Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
 | Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/consents.tsx`, admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
-| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/gcs-settings.tsx` | |
+| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
+| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |
 | SyncDB diagnostics | n/a | yes — `debug` registration in `example-frontend/store/syncdb.ts`, debugger UI at `example-frontend/app/syncdb-debug.tsx` | `terreno-mcp-local` can inspect, snapshot/compare/merge, mutate, flush, reconcile/resync, and exercise offline/conflict paths against the running development client. |

package/src/docs/versioned/next/explanation/model-router-actions.md

@@ -101,7 +101,7 @@ HTTP method and scope map to a CRUD permission check:
 **403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
 **401** — unauthenticated when a permission requires auth (from existing auth middleware).
 
-`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD.
+`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD. An action may set `allowAnonymous: true` to accept unauthenticated requests without making the router's CRUD routes or other actions anonymous. Keep a non-empty permission such as `Permissions.IsAny` and authenticate any service token in the handler.
 
 ## Validation
 

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -639,6 +639,26 @@ docs are the proof; comms admin stats consume these primitives later.
 
 ---
 
+## dashboard-chart-parity
+
+**Title:** `Ops dashboard chart parity`
+
+**Labels:** `area:ui`, `type:feature`
+**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=`dashboard-chart-parity`, Status=`Planned`
+
+Follow-up to charts-and-dashboards: scorecards with comparison sparklines, `ChartCard`
+period badges, additive multi-series facades, donut hole labels, spanning `DashboardGrid`
+items, and DataTable period headers / totals / range status so apps can compose a
+“How’s it going?”-class ops dashboard. Terreno theme defaults; no Looker preset. Grammar
+not required.
+
+- **Implementation plan:** [dashboard-chart-parity.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/dashboard-chart-parity.md)
+- **Tasks:** [dashboard-chart-parity.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/dashboard-chart-parity.md)
+- **RTK flag:** None
+- **Depends on:** charts-and-dashboards
+
+---
+
 ## dark-mode-theme
 
 **Title:** `First-class dark mode`
@@ -1257,6 +1277,20 @@ IP and tracking issue; this entry is the release checklist, not a plan.
 
 ---
 
+## demo-workshop
+
+**Title:** `Demo workshop`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`demo-workshop`, Status=`Planned`
+
+Turn the Expo demo into the workshop for `@terreno/ui`: a person can find a component, copy a usage snippet, change theme and viewport from the URL, and see whether every stable story passes interaction, accessibility, and visual checks on web and Android.
+
+- **Implementation plan:** [demo-workshop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/demo-workshop.md)
+- **Tasks:** [demo-workshop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/demo-workshop.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

package/src/docs/versioned/next/how-to/README.md

@@ -39,7 +39,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
 - [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
 - [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
-- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid`
+- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
 - [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
 - [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API

package/src/docs/versioned/next/how-to/admin-import-prebuilt.md

@@ -18,7 +18,7 @@ const app = new TerrenoApp({userModel: User})
 
 - `FeatureFlagsApp`: FeatureFlag model and `feature-flags-overrides` home widget.
 - `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
-- `DocumentStorageApp`: `documents` custom screen.
+- `DocumentStorageApp`: `documents` custom screen. Pass `fileUploadsEnabled: false` (or a function that returns `false`) to reject uploads while listing and download stay available. The example app wires this to the `file-uploads` feature flag.
 - `AIAdminApp`: `ai-requests` custom screen and explorer API.
 - `JobsApp`: `jobs` custom screen and home widget (`dead` / `running` counts). With
   `accessControl`, requires **both** `admin:access` and `admin:jobs`; without it, legacy

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

@@ -35,3 +35,8 @@ export const OpsDashboard: FC = () => {
 Charts have no width prop: each one fills the container you put it in and redraws when that width changes, so size the `Card` or `Box` around it. `height` is the chart's whole height, tick row and tooltip row included, so `height={140}` fits a 140px slot; the tooltip row is always reserved so hovering never reflows the page. Long x labels truncate inside their band rather than widening the chart.
 
 Prove paint with `bun run ui:charts:compare` against `demo/rendered-snapshots/`, not with JSON snapshots. See [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md).
+
+The example app admin home (`example-frontend/components/AdminCharts.tsx`, mounted
+below the admin dashboard at `/admin`) shows the same pieces together: scorecards with comparison
+sparklines, a multi-series line, a donut with a center label, a bar chart, and an
+area chart inside a spanning `DashboardGrid`.

package/src/docs/versioned/next/how-to/circleci.md

@@ -242,9 +242,10 @@ restrict `terreno-release` and `terreno-npm` to tag/manual release pipelines.
 Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
 (or the in-job `ci-e2e-*-secret` fallbacks). **Do not** put `GITHUB_TOKEN` (or any
 GitHub PAT) in project env vars — those are injected into every job, including
-`bun` scripts from the PR. Create `terreno-github-api`, restrict it to this
-project, leave fork-PR secret passing off, and attach that context **only** to
-`dco` and `architectural-pr-review`. DCO skips if `GITHUB_TOKEN` is unset.
+`bun` scripts from the PR. `terreno-github-api` must hold the PAT as
+`GITHUB_TOKEN`; restrict it to this project and leave fork-PR secret passing off.
+The `always` workflow attaches it **only** to `dco` and `architectural-pr-review`
+(the latter also gets `terreno-agentic`). DCO skips if `GITHUB_TOKEN` is unset.
 `architectural-pr-review` also skips if `GITHUB_TOKEN` or `CURSOR_API_KEY` is
 unset, and it skips fork PRs. The job checks out `origin/master` before running
 the review script so a PR cannot rewrite the reviewer.
@@ -351,20 +352,35 @@ a closed PR.
 `manual-publish-package` also accepts `feature-flags`. Versions must be semver.
 Semver git tags (`57.3.0`, `57.3.0-beta.1`) automatically start
 `publish-release`; prereleases publish to their prerelease npm dist-tag.
-`scripts/ci/publish-package.sh` pins `workspace:*` to the tag version for the
-tarball, then compiles and tests against the root workspace install. It must
-not `bun install` after that pin: sibling `@terreno/*` packages are not on npm
-yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on the registry
-and fail the whole job. Tests use `test:ci` when that script exists, not
-`test`. `@terreno/ui`'s `test` is `bun test --watch` and would hang the
-publish step after the suite finishes. `publish-release` uses a 20-minute
-no-output timeout as a backstop. If a package's tag version is already on npm,
-`publish-package.sh` skips it so a recut of the same tag can finish the rest.
-
-Only stable tags (`57.3.0`) run `deploy-demo` after publish. Use
+`publish-release` compiles the 16 lockstep packages once with
+`bun run --filter ... compile` (dependency order), then runs
+`scripts/ci/publish-package.sh` for all of them in parallel with
+`TERRENO_PUBLISH_PREBUILT=1`. It does not rerun tests: the tagged commit
+already passed CI on master, and rerunning every suite per package made
+releases take 20+ minutes. The job has no Mongo sidecar. Each publish writes
+its own temporary npmrc (`NPM_CONFIG_USERCONFIG`) so parallel publishes do not
+remove each other's token.
+
+`publish-package.sh` pins `workspace:*` to the tag version for the tarball.
+It must not `bun install` after that pin: sibling `@terreno/*` packages are
+not on npm yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on
+the registry and fail the whole job. Without `TERRENO_PUBLISH_PREBUILT` (the
+manual single-package publish), it compiles the package and its workspace
+dependencies and runs `test:ci` when that script exists, not `test`.
+`@terreno/ui`'s `test` is `bun test --watch` and would hang. If a package's
+tag version is already on npm, `publish-package.sh` skips it so a recut of
+the same tag can finish the rest.
+
+Only stable tags (`57.3.0`) run `deploy-demo`. It builds the demo from source,
+so it runs alongside `publish-release` instead of waiting for it. Use
 `{"run-demo-deploy":true}` on `master` if a prerelease must also refresh the
 demo site.
 
+`scripts/ci/netlify-deploy.sh` builds each site itself and calls
+`netlify deploy --no-build`. Without `--no-build`, netlify-cli runs the root
+`netlify.toml` docs build (wipe `node_modules`, reinstall, full Docusaurus),
+which added about 3.5 minutes to every demo and frontend deploy.
+
 CircleCI does not receive GitHub `pull_request.closed` events, so
 `.github/workflows/preview-cleanup.yml` forwards them: it runs master's
 `scripts/ci/trigger-circleci-pipeline.sh` with `{"run-preview-cleanup":"<PR>"}`

package/src/docs/versioned/next/how-to/compare-chart-rendered-snapshots.md

@@ -33,4 +33,12 @@ easy-through-hard charts in the demo app and diffs those PNGs against goldens.
 Agents reviewing a fail should follow the `review-chart-visuals` skill and look at the
 PNGs, not only the code diff.
 
+Hard fixture `scorecard-sparkline-comparison` renders five KPI tiles with solid current
+and dotted previous-period sparklines.
+Cartesian parity fixtures are `bar-time-rotated-ticks`, `bar-day-of-week`, and
+`line-three-series`.
+Donut parity fixtures are `donut-center-and-share` and `donut-single-slice`.
+Hard fixture `hows-it-going-dashboard` composes KPI scorecards, time-series charts, donuts,
+and table placeholders in a spanning `DashboardGrid`.
+
 `CHART_VISUAL_BASE_URL` overrides the demo origin when the gallery is already hosted.

package/src/docs/versioned/next/how-to/install-agent-skills.md

@@ -70,7 +70,7 @@ scan stages come from
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
 | GitHub | issues, review, UI verification, release, dependency updates |
 | Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |
-| Expo and native | `track-upstream-expo`, `upgrading-expo`, deployment / EAS skills |
+| Expo and native | `track-upstream-expo`, `upgrading-expo`, `store-assets`, deployment / EAS skills |
 | Plugin agents | `pre-commit`, `ui-verifier` |
 
 `skills.sh.json` at the repo root groups those names on [skills.sh](https://skills.sh).

package/src/docs/versioned/next/how-to/preview-demo.md

@@ -0,0 +1,19 @@
+# Preview a component demo
+
+Open a component demo and change the shareable query. The preview bar is on demo and
+dev component routes. `?embed=1` applies the same query and hides the bar.
+
+```text
+/demo/Button?theme=dark&viewport=375&background=inverse&locale=en-US&rtl=1&reducedMotion=1
+```
+
+| Query | Values |
+| --- | --- |
+| `theme` | `light` (default) or `dark` (canonical dark role remap) |
+| `viewport` | `full` (default), `320`, `375`, `1024`, `1280` |
+| `background` | `default`, `inverse`, `transparent` |
+| `locale` | Passed to components that already read a locale, such as consent |
+| `rtl` | `1` sets document direction to `rtl` on web |
+| `reducedMotion` | `1` sets `data-reduced-motion="1"` on the document element |
+
+Reload keeps the query. The bar shows the current query when any value is not the default. Choosing a control's default removes that key from the URL. Leaving the component route restores the app theme and, on web, document direction and reduced motion. Custom palettes stay on `/palette`.

package/src/docs/versioned/next/how-to/product-announcements.md

@@ -11,6 +11,7 @@ import {AnnouncementsApp} from "@terreno/announcements";
 
 new AnnouncementsApp({
   defaultAcknowledgementPolicy: "dismiss-only",
+  uploadToken: process.env.ANNOUNCEMENTS_UPLOAD_TOKEN,
   // audienceType staff/patient/all is applied inside the plugin via matchAudienceByType.
   isStaff: (user) => (user as {admin?: boolean}).admin === true,
   matchAudience: (user, announcement) => {
@@ -46,6 +47,8 @@ For Flourish-style surfaces on one collection:
 
 2. Create announcements in admin (draft → publish). Use `AnnouncementOverview`, `AnnouncementEditor`, and (optionally) `AnnouncementList` from `@terreno/admin-frontend` with dedicated Expo routes (see `example-frontend/app/admin/announcements/`). The built-in admin screen widget key `announcements` renders the overview when your host uses `AdminScreenRouter` for custom screens. Published `title`/`body` edits auto-increment `version`, which re-shows the surface to users who only acknowledged the previous version.
 
+For release-driven batches, use an [announcement release pack](../reference/announcement-release-packs.md). It keeps one `pack.yaml` manifest plus multiple Markdown announcements in source control, validates release and build versioning, and can import idempotent drafts or explicitly publish the whole pack through a dedicated bearer token. The example Cloud Run service accepts `Authorization: Bearer terreno-example-announcement-upload` (Terraform variable `announcements_upload_token`).
+
 ### Admin editor fields
 
 `AnnouncementEditor` exposes structured targeting controls (no raw `requiresAcknowledgement` boolean):

package/src/docs/versioned/next/implementationPlans/ai-observability.md

@@ -274,7 +274,7 @@ Env (example-backend):
 | `AI_OBS_DATASETS_PRIMARY` | default `local` |
 | `AI_OBS_EXPERIMENTS_PRIMARY` | must equal datasets |
 | `AI_OBS_SAMPLE_RATE` | `0`–`1`, default `0` |
-| `AI_OBS_PRICE_MAP_JSON` | `{ "gemini-2.5-flash": { "inputPerMTok": 0.1, "outputPerMTok": 0.4 } }` |
+| `AI_OBS_PRICE_MAP_JSON` | `{ "gemini-3.8-flash": { "inputPerMTok": 0.1, "outputPerMTok": 0.4 } }` |
 | existing Langfuse keys | unchanged |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | optional OTLP |
 

package/src/docs/versioned/next/implementationPlans/b2b-platform-program.md

@@ -36,7 +36,7 @@ org switcher, dark mode).
 | C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); operations: `comms-admin-dashboard`; consumers: `password-reset-and-email-verification`, `notification-center` |
 | B | Billing | `inbound-webhooks`, `billing-stripe` (web-first, per D1), `mobile-iap-revenuecat` (Future) |
 | D | Zero-to-deployed DX | `create-terreno-app`, `mongo-migrations` (deploy items already exist in the OSS launch program) |
-| E | B2B UI surfaces | `data-grid-server-filters`, `charts-and-dashboards`, `dark-mode-theme`, `command-palette`, `wizard-stepper`, `wysiwyg-editor` (markdown stays for now, per D3), `global-search` |
+| E | B2B UI surfaces | `data-grid-server-filters`, `charts-and-dashboards`, `dashboard-chart-parity`, `dark-mode-theme`, `command-palette`, `wizard-stepper`, `wysiwyg-editor` (markdown stays for now, per D3), `global-search` |
 | F | Enterprise & scale | `framework-audit-log` (Next), `rate-limiting` (Next), `job-queues` (Next), `enterprise-sso`, `mfa-step-up-auth` |
 | — | Native baseline | `native-module-baseline` — all new native modules land in one major release |
 

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

@@ -194,8 +194,9 @@ None.
 
 ## Not Included / Future Work
 
-- Composition grammar (Phase 6) — recorded Grow decisions; implement on a follow-up Pick.
-- Multi-series cartesian beyond `dataKey` / `stackId` once the grammar ships.
+- Ops-dashboard parity (scorecards, comparison sparklines, additive multi-series, donut centers, spanning grid, table chrome) — [`dashboard-chart-parity.md`](dashboard-chart-parity.md).
+- Composition grammar (Phase 6) — recorded Grow decisions; implement on a follow-up Pick. Not required for the How’s it going dashboard.
+- Multi-series cartesian via additive `series` lands in `dashboard-chart-parity`; grammar `dataKey` / `stackId` remains later.
 - Wiring `CommsDashboardScreen` charts to the stats endpoint.
 - Example-frontend dashboard.
 - Zoom/pan.