@terreno/mcp 57.8.0 → 57.9.0

package/dist/docs/versioned/next/reference/ui.md

@@ -4,9 +4,9 @@ React Native UI component library (a large component library). Layout (Box, Page
 
 ## Key exports
 
-- Layout: `Box`, `Page`, `SplitPage`, `Card`, `DashboardGrid`
+- Layout: `Box`, `Page`, `SplitPage`, `Card`, `ChartCard`, `DashboardGrid`, `DashboardGridItem`
 - Forms: `TextField`, `SelectField`, `DateTimeField`, `CheckBox`
-- Display: `Text`, `Heading`, `Badge`, `DataTable`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`
+- Display: `Text`, `Heading`, `Badge`, `DataTable`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
 - Notifications: `NotificationBell`, `NotificationInbox`, `NotificationPreferences`
@@ -32,11 +32,11 @@ supported and is convenient when startup cost is not material:
 import {Box, DataTable, Icon} from "@terreno/ui";
 ```
 
-Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
+Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, `ChartCard`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
 re-exported from the root entry through lazy boundaries. Importing them from `@terreno/ui` stays type-compatible, but
 their implementation modules load on first render instead of during the initial root import. `DashboardGrid` stays eager.
-their implementation modules load on first render instead of during the initial root import. `MarkdownView` and
-`DataTable` header info defer `react-native-markdown-display`; `EmojiSelector` defers `emoji-datasource` until open.
+`MarkdownView` and `DataTable` header info defer `react-native-markdown-display`;
+`EmojiSelector` defers `emoji-datasource` until open.
 
 For the smallest cold-start graph, keep using subpaths for screens that only need a few primitives (for example
 `import {Button} from "@terreno/ui/Button"`).
@@ -60,21 +60,72 @@ const customStyle: StyleProp<ViewStyle> = {
 - Ensures type compatibility when passing styles to @terreno/ui components
 - Simplifies imports (one package instead of two)
 
-### DashboardGrid
+### DashboardGrid and DashboardGridItem
 
 Eager layout-only wrapping grid. Default columns `{sm: 1, md: 2, lg: 3}`. Children stay caller-supplied `Card`s. Cell width is `(rowWidth - gap × (columns - 1)) / columns` so flex `gap` does not wrap extra columns.
+Wrap a child in `DashboardGridItem` when it must span more than one responsive column.
+Plain children remain one column.
 
 ```tsx
-<DashboardGrid>
+<DashboardGrid columns={{sm: 1, md: 2, lg: 4}}>
+  <DashboardGridItem span={{sm: 1, md: 2, lg: 2}}>
+    <Card>
+      <LineChart data={points} legendLabel="Signups" />
+    </Card>
+  </DashboardGridItem>
   <Card>
     <LineChart data={points} legendLabel="Signups" />
   </Card>
 </DashboardGrid>
 ```
 
+### ChartCard
+
+Card chrome for a chart or table: title, optional filter summary, and an optional period
+badge. Pass `onPeriodPress` to make the badge a button; omit it for display-only copy.
+
+```tsx
+<ChartCard title="Cost by Device" periodLabel="Last 30 days">
+  <DonutChart data={points} />
+</ChartCard>
+```
+
+### Scorecard
+
+Compact KPI tile with a title, formatted value, and optional current/comparison
+sparkline. Numeric values use `formatValue`; string values render unchanged.
+
+```tsx
+<Scorecard
+  title="Cost"
+  value={569}
+  formatValue={(value) => `$${value}`}
+  sparklineData={current}
+  comparisonData={previous}
+/>
+```
+
+### SparklineChart
+
+Plot-only line chart for compact metrics. `data` draws the current solid line;
+`comparisonData` draws a dotted previous-period line on the same scale. It has no axes,
+grid, legend, tooltip row, or empty-state copy.
+
+```tsx
+<SparklineChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  comparisonData={[{label: "Mon", value: 4}, {label: "Tue", value: 4}]}
+/>
+```
+
 ### LineChart
 
-Single-series line chart drawn with `react-native-svg`. Empty data shows `emptyText` (default `"No data"`). `loading` shows a `Spinner`. Press or hover a point for `{label}: {value}`.
+Line chart drawn with `react-native-svg`. Keep the simple `data` + `legendLabel` path for
+one series, or pass named `series` for multiple lines and legend items.
+`comparisonData` adds a dotted previous-period overlay on the shared scale. Empty data
+shows `emptyText` (default `"No data"`). `loading` shows a `Spinner`.
+Set `xTickPolicy` to `auto` (default), `rotate`, or `truncate`. `title`,
+`periodLabel`, and `onPeriodPress` use the same header chrome as `ChartCard`.
 
 ```tsx
 <LineChart
@@ -88,7 +139,10 @@ Hit targets use `Box` `onClick`, so testIDs are `{testID}.point.{index}-clickabl
 
 ### BarChart
 
-Single-series bar chart on the same owned-SVG contract as `LineChart` (empty, loading, legend, tooltip).
+Bar chart on the same owned-SVG contract as `LineChart` (empty, loading, legend,
+tooltip, tick policy, and header shortcuts). `comparisonData` paints lighter bars behind
+the current period. When `series` is passed in this facade, its first entry supplies the
+bars and legend; grouped bars remain future work.
 
 ```tsx
 <BarChart
@@ -101,6 +155,8 @@ Single-series bar chart on the same owned-SVG contract as `LineChart` (empty, lo
 ### AreaChart
 
 Filled area plus line on the same owned-SVG contract as `LineChart`.
+Named `series` render one fill/line pair and legend item each; `comparisonData` stays a
+dotted line rather than a filled area.
 
 ```tsx
 <AreaChart
@@ -112,11 +168,16 @@ Filled area plus line on the same owned-SVG contract as `LineChart`.
 
 ### DonutChart
 
-One slice per `{label, value}` point. Per-slice `color` overrides the theme paint. Legend is one row per slice (`legendLabel` is ignored).
+One slice per `{label, value}` point. Per-slice `color` overrides the theme paint.
+Legend rows show label + percent by default; customize with `formatShare`.
+`centerValue` and `centerTitle` put an aggregate in the donut hole. `title` /
+`periodLabel` use `ChartCard` chrome (`legendLabel` remains ignored).
 
 ```tsx
 <DonutChart
   data={[{label: "Open", value: 3}, {color: "#112233", label: "Closed", value: 5}]}
+  centerValue="8"
+  centerTitle="Total"
   testID="status-donut"
 />
 ```
@@ -189,6 +250,14 @@ Buttons automatically size to their content unless `fullWidth` is specified:
 
 Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
 
+### TextField grow and maxHeight
+
+`grow` makes a multiline field expand with its content. Pair it with `maxHeight` (pixels) to cap the expansion; past the cap the content scrolls.
+
+```tsx
+<TextArea grow maxHeight={200} onChange={setNotes} value={notes} />
+```
+
 ### TextField password visibility
 
 `type="password"` masks the value and renders a show/hide eye control at the end of the field.
@@ -295,7 +364,15 @@ Streaming chat surface for `@terreno/ai`. Histories, messages, submit, and optio
 
 Pass `mascot` when the app owns a character. Terreno ships none. The node renders only while `currentMessages` is empty, centered in the chat panel above the suggested prompts. The empty hero uses the message viewport height as a minimum so short content stays centered, while taller mascots still scroll. Streaming feedback shares that centered hero instead of creating a second pane. Omit the prop for the default empty chat.
 
-The composer row (attachment picker, tools, input, Send) is vertically centered, so controls stay aligned with the input as it grows. The attachment cell is omitted when `onAttachFiles` is not provided.
+The composer row (attachment picker, tools, input, Send) is vertically centered, so controls stay aligned with the input as it grows. The composer input grows with its text up to 200px, then scrolls. The attachment cell is omitted when `onAttachFiles` is not provided.
+
+Each history row keeps rename and delete in a three-dot overflow menu (`gpt-history-menu-{id}`), anchored with `DropdownPanel`. Rename uses an outlined pencil in the dark secondary text color. Titles truncate before the menu trigger, so the trigger stays aligned at any sidebar width.
+
+"Scroll to bottom" appears only when content sits more than 100px below the viewport. It never shows in an empty chat.
+
+Image content parts render copy-image and (web) download actions. The message copy button on an image-only reply copies the image, not text. On web the image is written to the clipboard as PNG; on native it uses `expo-clipboard` `setImageAsync` for `data:` URLs.
+
+The attach control (`FilePickerButton`) opens an anchored dropdown with **Photo Library** and **Document**. On web both open a browser file input from the press itself and return `data:` URLs, so attachments survive a reload; on native they use `expo-image-picker` and `expo-document-picker`.
 
 ```tsx
 <GPTChat
@@ -362,6 +439,12 @@ Buttons use a scale animation by default. Set `pressAnimation="opacity"` for an
 
 Disabled and loading buttons use a non-interactive pressable regardless of the selected animation.
 
+### Toast
+
+`TerrenoProvider` mounts the toast container. Call `useToast()` for `success`, `info`, `warn`, `error`, `show`, `hide`, and `catch`.
+
+On web, that container is portaled to `document.body` (`position: fixed`, `z-index: 999999`, `pointerEvents: "box-none"`), so a toast stays above an open `Modal` and its backdrop. The web container is sized with `100%` rather than the measured window, so statically exported pages (where `Dimensions` reports 0×0 at build time) still center the toast on screen. Native iOS and Android keep the in-tree absolute container sized to the window.
+
 ## Authentication Components
 
 ### SocialLoginButton

package/dist/docs/versioned/next/tasks/dashboard-chart-parity.md

@@ -0,0 +1,145 @@
+# Tasks: Dashboard chart parity
+
+IP: [dashboard-chart-parity.md](../implementationPlans/dashboard-chart-parity.md)  
+**Follows:** https://github.com/TerrenoLabs/terreno/issues/1175  
+**Roadmap issue:** set after IP approval
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (scorecard)
+
+- [x] **Task 1.1**: `SparklineChart` + dotted `comparisonData`
+  - Delivers: public plot-only sparkline; solid current series; dotted comparison aligned on `label`; no axes/grid/legend/tooltip row; empty input does not throw
+  - Files: `ui/src/SparklineChart.tsx`, `ui/src/SparklineChart.test.tsx`, `ui/src/charts/paths.ts` (reuse line path), `ui/src/Common.ts` (TypeDoc props), `ui/src/index.tsx` / `heavyOptionalExports.tsx`
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: stub `SparklineChart` on `docs/reference/ui.md` Display list
+  - Acceptance: bun tests — N points → path present; comparison path present when `comparisonData` set; empty data shows nothing / emptyText if provided; `ui` compile green
+
+- [x] **Task 1.2**: `Scorecard` + `ChartCard`
+  - Delivers: KPI tile with title, formatted value, optional sparkline; `ChartCard` with title, period badge, optional `onPeriodPress`, optional `filterSummary`
+  - Files: `ui/src/Scorecard.tsx`, `ui/src/Scorecard.test.tsx`, `ui/src/ChartCard.tsx`, `ui/src/ChartCard.test.tsx`, lazy exports
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: stub both on `docs/reference/ui.md`
+  - Acceptance: bun tests — value + title render; sparkline mounts when `sparklineData` set; badge press fires; period badge has no press handler when `onPeriodPress` omitted
+
+- [x] **Task 1.3**: Scorecard demo + first golden
+  - Delivers: demo story; gallery fixture `scorecard-sparkline-comparison` (five KPI tiles, static data); PNG golden
+  - Files: `demo/stories/Scorecard.stories.tsx`, `demo/stories/ChartCard.stories.tsx`, `demo/demoConfig.tsx`, `demo/chartVisual/fixtureCatalog.ts`, `demo/chartVisual/fixtures.tsx`, `demo/rendered-snapshots/scorecard-sparkline-comparison.png`
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `review-chart-visuals`, `verify-ui-changes`
+  - Docs: `docs/how-to/compare-chart-rendered-snapshots.md` lists the new id
+  - Acceptance: fixture catalog test includes the id; `bun run ui:charts:compare` green for it; story registered
+
+## Phase 2 — Cartesian additive facades
+
+- [x] **Task 2.1**: `series` + `comparisonData` on `LineChart` / `AreaChart`
+  - Delivers: multi-series lines from `series`; single `data` still works; dotted comparison overlay; per-series legend; markers stay
+  - Files: `ui/src/LineChart.tsx`, `ui/src/AreaChart.tsx`, matching tests, `ui/src/charts/scales.ts` (shared x domain across series)
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` Line/Area props
+  - Acceptance: bun tests — three `series` → three paths + three legend labels; `{label,value}[]` only still draws one series; comparison path exists when set
+
+- [x] **Task 2.2**: `xTickPolicy` + bar comparison + header shortcuts
+  - Delivers: `"auto"` rotates when labels would truncate, stays horizontal for ≤7 categories; `BarChart` accepts `series` (grouped later if >1 — this slice: first series only unless a second is comparison) and `comparisonData`; `title` / `periodLabel` / `onPeriodPress` on cartesian facades
+  - Files: `ui/src/BarChart.tsx`, `ui/src/LineChart.tsx`, `ui/src/charts/layout.ts`, `ui/src/BarChart.test.tsx`, `ui/src/LineChart.test.tsx`
+  - Blocked by: 2.1
+  - Skills: `terreno-ui`
+  - Docs: tick policy in `docs/explanation/charts.md`
+  - Acceptance: bun tests — 14 long date labels with `auto` → rotated tick style; 7 weekday labels stay horizontal; facade title renders when set and `ChartCard` is not wrapping (documented exclusive use)
+
+- [x] **Task 2.3**: Cartesian goldens
+  - Delivers: fixtures `bar-time-rotated-ticks`, `line-three-series`, `bar-day-of-week`
+  - Files: `demo/chartVisual/**`, `demo/rendered-snapshots/*.png`
+  - Blocked by: 2.2
+  - Skills: `review-chart-visuals`, `verify-ui-changes`
+  - Docs: compare-how-to fixture table
+  - Acceptance: `bun run ui:charts:compare` green for the three ids
+
+## Phase 3 — Donut center and share legend
+
+- [x] **Task 3.1**: Donut hole + percent legend
+  - Delivers: `centerTitle`, `centerValue`; legend `swatch + label + formatShare` (default percent of total); 100% single-slice still draws a ring + center
+  - Files: `ui/src/DonutChart.tsx`, `ui/src/DonutChart.test.tsx`
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` Donut props
+  - Acceptance: bun tests — center copy present; legend includes `%`; one-slice data still has one path; existing slice color override still works
+
+- [x] **Task 3.2**: Donut goldens
+  - Delivers: `donut-center-and-share`, `donut-single-slice`
+  - Files: `demo/chartVisual/**`, goldens
+  - Blocked by: 3.1
+  - Skills: `review-chart-visuals`
+  - Docs: compare-how-to
+  - Acceptance: compare green for both ids
+
+## Phase 4 — Spanning grid
+
+- [x] **Task 4.1**: `DashboardGridItem` spans
+  - Delivers: eager `DashboardGridItem` with `span` per breakpoint; default span 1; children without a wrapper keep current equal-column behavior
+  - Files: `ui/src/DashboardGrid.tsx` and/or `ui/src/DashboardGridItem.tsx`, `ui/src/DashboardGrid.test.tsx`, `ui/src/index.tsx` (eager)
+  - Blocked by: 1.2
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` Layout
+  - Acceptance: bun tests — span 2 in a 4-column row yields ~2× cell width minus gap; unwrapped children still fill 1 column
+
+- [ ] **Task 4.2**: `hows-it-going-dashboard` chart composition
+  - Delivers: hard fixture matching the reference layout (5 scorecards, cost/conv bar, 3-line imp share, DOW bar, two donuts). Table slot may be a `ChartCard` placeholder until 5.2
+  - Files: `demo/chartVisual/fixtures.tsx`, `fixtureCatalog.ts`, golden
+  - Blocked by: 2.3, 3.2, 4.1
+  - Skills: `review-chart-visuals`, `verify-ui-changes`
+  - Docs: how-to example rewritten to this composition
+  - Acceptance: compare green; fixture uses `Scorecard` / `ChartCard` / `DashboardGridItem`, not ad-hoc `Box` widths only
+
+## Phase 5 — Table chrome
+
+- [ ] **Task 5.1**: Header groups, footer rows, range status, wrapLines
+  - Delivers: `headerGroups` second header row; `footerRows` sticky totals; range copy `start–end of total` with existing pagination; `wrapLines={2}` wraps cell text inside `rowHeight` (virtualization unchanged)
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`, `ui/src/Pagination.tsx` (if range lives there), `ui/src/Common.ts`
+  - Blocked by: 4.1
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: `docs/reference/ui.md` DataTable; pointer from charts how-to
+  - Acceptance: bun tests — grouped header text visible; footer row present; range text `1–50 of 452` with page 1 size 50 total 452; pinned column scroll still syncs with groups/footer; wrapLines 2 does not change `rowHeight`
+
+- [ ] **Task 5.2**: Table card in the hard fixture
+  - Delivers: one `ChartCard` + `DataTable` in `hows-it-going-dashboard` (Search Terms or Ad Group Check-in static rows, totals, period headers)
+  - Files: `demo/chartVisual/fixtures.tsx`, update golden
+  - Blocked by: 5.1, 4.2
+  - Skills: `review-chart-visuals`, `verify-ui-changes`
+  - Docs: how-to shows table in the same grid
+  - Acceptance: compare green after intentional golden update; wrapped first-column names visible in the PNG
+
+## Phase 6 — Packaging and docs
+
+- [ ] **Task 6.1**: Lazy root + import regression
+  - Delivers: `Scorecard`, `SparklineChart`, `ChartCard`, chart facades stay on `heavyOptionalExports`; `DashboardGrid` / `DashboardGridItem` eager; root import does not evaluate chart files
+  - Files: `ui/src/lazyBoundaries/heavyOptionalExports.tsx`, `ui/src/index.tsx`, `ui/src/RootImportRegression.test.tsx`, `docs/reference/ui-performance.md`
+  - Blocked by: 4.1, 5.1, 2.1, 3.1
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: performance page lists new lazy exports
+  - Acceptance: `RootImportRegression` fails if new chart files load with the root import; subpath imports work
+
+- [ ] **Task 6.2**: Diátaxis + changelog + rules
+  - Delivers: how-to rewritten for easy-build composition; explanation covers scorecard, comparison stroke, additive facades vs grammar; reference complete; changelog fragment; ui rule export list; TypeDoc
+  - Files: `docs/how-to/charts-and-dashboards.md`, `docs/explanation/charts.md`, `docs/reference/ui.md`, `docs/how-to/README.md`, `.rulesync/rules/ui/00-ui.mdc`, `changelog/unreleased/dashboard-chart-parity.md`; `bun run website:generate` if needed
+  - Blocked by: 6.1, 5.2
+  - Skills: `update-docs`, `docs-audit`, `terreno-ui`
+  - Docs: the files listed above
+  - Acceptance: a stranger can copy the how-to into a screen that resembles the reference; explanation states grammar is not required; changelog `category: Added`; existing single-series how-to steps still valid as a subset
+
+## Verification mapping
+
+| Criterion | Method |
+|-----------|--------|
+| Scorecard + sparkline + comparison | bun tests + `scorecard-sparkline-comparison` PNG |
+| Multi-series line | bun tests + `line-three-series` PNG |
+| Rotated vs horizontal ticks | bun tests + `bar-time-rotated-ticks` / `bar-day-of-week` |
+| Donut center + share | bun tests + donut goldens |
+| Grid spans + reference layout | `hows-it-going-dashboard` PNG + grid unit tests |
+| Table chrome | bun tests + table region of hard golden |
+| Facade compatibility | existing `*Chart.test.tsx` stay green |
+| Lazy charts | `RootImportRegression` |
+| Frontend proof | `verify-ui-changes` on demo gallery; artifacts on the implementation PR |

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.8.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.8.0"
+  "version": "57.9.0"
 }

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

@@ -21,7 +21,7 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | 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`). |
 | 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` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/gcs-settings.tsx` | |
+| 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/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`

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.

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