@terreno/mcp 57.8.0 → 57.9.0

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

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

@@ -0,0 +1,275 @@
+# Implementation Plan: Dashboard chart parity
+
+**Status:** Approved — 2026-09-25  
+**Branch:** `cursor/dashboard-chart-parity-8a50`  
+**Owner:** —  
+**Created:** 2026-09-24  
+**Roadmap issue:** — (create via `roadmap-item` after this IP is Approved; follow-up to [#1175](https://github.com/TerrenoLabs/terreno/issues/1175))  
+**Task list:** [dashboard-chart-parity.md](../tasks/dashboard-chart-parity.md)  
+**Depends on:** [charts-and-dashboards.md](charts-and-dashboards.md) (shipped Phases 1–5)  
+**RTK deprecation flag:** None  
+**Program:** [B2B platform](b2b-platform-program.md) track E  
+
+## Goal
+
+Make `@terreno/ui` able to compose an ops dashboard like the “How’s it going?”
+reference: KPI scorecards with comparison sparklines, titled chart cards with period
+badges, multi-series lines, donut hole labels, spanning grids, and Looker-like table
+chrome — without copying Looker paint, and without requiring the Chart children grammar.
+
+App authors rebuild that page from first-class primitives (`Scorecard`, `SparklineChart`,
+`ChartCard`, spanning `DashboardGrid`, additive chart facades, `DataTable` extras). Proof
+is a demo gallery fixture of the reference layout plus rendered PNG goldens.
+
+## Non-Goals
+
+- Pixel-identical Looker colors, fonts, or screenshot matching of the PDF JPEG.
+- Shipping a date-range picker. Period badges may call `onPeriodPress`.
+- Variable `DataTable` row height (would break virtualization).
+- Dual-period numbers inside one table cell (current + previous stacked in the same cell).
+- Replacing `{label, value}[]` facades with composition-only `Chart*` children.
+- Implementing the Phase 6 composition grammar in this slice (still future work on
+  `charts-and-dashboards`).
+- Example-frontend screen, comms dashboard wiring, zoom/pan, combo charts, maps, heatmaps.
+- Cross-chart filtering / drill-down.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Scope | All chart surfaces, headers, period badges, KPI cards, spanning grid, and the table chrome named below. Not the whole PDF pixel-for-pixel. |
+| Easy-build surface | `ChartCard` (title + period badge + child) + `Scorecard` + spanning `DashboardGrid`. |
+| Scorecards | Dedicated `Scorecard` facade plus reusable `SparklineChart`. |
+| Comparison | First-class `comparisonData` with dotted stroke on sparkline and optional cartesian overlay. |
+| Facades vs grammar | Keep `LineChart` / `BarChart` / `AreaChart` / `DonutChart`. Add additive props. This dashboard must not require a composition tree. |
+| Visual language | Capabilities are theme-configurable. Default paint stays Terreno tokens, not a Looker preset. |
+| Responsive grid | Configurable `span` on items. Reference fixture: KPI row 5→2→1; lower chart row 3→1. |
+| Tables | Same IP. After the chart tracer: period header groups, sticky totals row, `1–50 of N` range status. Reuse existing pin/sort/pagination. |
+| Wrapped names | Wrap up to two lines inside the existing `rowHeight`. Keep virtualization. |
+| Period badge | Label plus optional `onPress`. No picker in this slice. |
+
+## Architecture
+
+```
+DashboardGrid
+  DashboardGridItem span={{sm,md,lg}}
+    ChartCard title periodLabel onPeriodPress?
+      Scorecard | LineChart | BarChart | DonutChart | DataTable
+    Scorecard
+      SparklineChart (plot only; solid + dotted comparison)
+```
+
+Existing facades stay the simple path. `ChartCard` is chrome around any child (chart or
+table). Facade `title` / `periodLabel` / `onPeriodPress` are shortcuts that render the
+same header inside the chart; callers use **either** `ChartCard` **or** those props, not
+both.
+
+### Public props (additive)
+
+```typescript
+interface ChartSeries {
+  color?: string;
+  data: Array<{color?: string; label: string; value: number}>;
+  id: string;
+  label: string;
+  stroke?: "solid" | "dotted";
+}
+
+interface CartesianChartProps {
+  comparisonData?: Array<{label: string; value: number}>;
+  data: Array<{color?: string; label: string; value: number}>;
+  formatValue?: (value: number) => string;
+  onPeriodPress?: () => void;
+  periodLabel?: string;
+  series?: ChartSeries[];
+  title?: string;
+  xTickPolicy?: "auto" | "truncate" | "rotate";
+  // existing: height, legendLabel, emptyText, loading, accessibilityLabel, testID
+}
+
+interface DonutChartProps extends CartesianChartProps {
+  centerTitle?: string;
+  centerValue?: string;
+  formatShare?: (value: number, total: number) => string;
+}
+
+interface SparklineChartProps {
+  comparisonData?: Array<{label: string; value: number}>;
+  data: Array<{label: string; value: number}>;
+  height?: number;
+  testID?: string;
+}
+
+interface ScorecardProps {
+  comparisonData?: Array<{label: string; value: number}>;
+  formatValue?: (value: number) => string;
+  onPeriodPress?: () => void;
+  periodLabel?: string;
+  sparklineData?: Array<{label: string; value: number}>;
+  title: string;
+  value: number | string;
+  testID?: string;
+}
+
+interface ChartCardProps {
+  children: React.ReactNode;
+  filterSummary?: string;
+  onPeriodPress?: () => void;
+  periodLabel?: string;
+  title: string;
+  testID?: string;
+}
+
+interface DashboardGridItemProps {
+  children: React.ReactNode;
+  span?: {lg?: number; md?: number; sm?: number};
+  testID?: string;
+}
+
+interface DataTableProps {
+  footerRows?: DataTableCellData[][];
+  headerGroups?: Array<{columnCount: number; subtitle?: string; title: string}>;
+  rangeStart?: number;
+  rangeTotal?: number;
+  wrapLines?: 1 | 2; // default 1; 2 = wrap inside rowHeight
+  // existing page / setPage / totalPages remain; range copy uses page size math
+}
+```
+
+`series` when present is the cartesian data source (`data` is ignored except as a
+single-series fallback). `comparisonData` aligns on `label` and paints a dotted stroke
+(sparkline/line) or a lighter overlay (bar — if labels match). Default `xTickPolicy` is
+`"auto"`: rotate ~45° when labels would truncate; keep horizontal for ≤7 categorical
+labels.
+
+Donut legend rows become `swatch + label + formatShare` (default percent of total).
+`centerTitle` / `centerValue` sit in the hole via overlay `Text`.
+
+`DashboardGridItem` span is in column units of the current breakpoint count (span 5 in a
+5-column KPI row is full width on `sm` when `columns.sm === 1`).
+
+`SparklineChart` draws no axes, grid, legend, or reserved tooltip row. Hit targets stay
+≥24px when press/hover is wired; default is non-interactive (KPI sparkline).
+
+`headerGroups` paint a second header row above `columns` (period title + optional
+subtitle such as `(Previous period)`). `footerRows` stick to the bottom of the scroll
+body. Range status is `rangeStart–rangeEnd of rangeTotal` next to existing pagination.
+
+### File layout
+
+| Path | Role |
+|------|------|
+| `ui/src/SparklineChart.tsx` | Public sparkline |
+| `ui/src/Scorecard.tsx` | Public KPI tile |
+| `ui/src/ChartCard.tsx` | Public title + period badge chrome |
+| `ui/src/DashboardGridItem.tsx` | Public span wrapper (or named export from `DashboardGrid.tsx` — no barrel) |
+| `ui/src/LineChart.tsx` etc. | Additive `series`, `comparisonData`, ticks, header shortcuts |
+| `ui/src/DonutChart.tsx` | Center stack + share legend |
+| `ui/src/DataTable.tsx` | Header groups, footer rows, range status, wrapLines |
+| `ui/src/Pagination.tsx` | Range copy when totals provided |
+| `demo/chartVisual/fixtureCatalog.ts` | New hard fixtures including `hows-it-going-dashboard` |
+| `docs/how-to/charts-and-dashboards.md` | Rewrite around Scorecard + ChartCard + spans |
+
+`DashboardGrid` stays eager. New chart widgets join `heavyOptionalExports`. `ChartCard`
+and `Scorecard` are layout+text heavy enough to sit with charts (lazy). `DashboardGridItem`
+stays eager with the grid.
+
+### Chart visual regression
+
+Add fixtures that exercise the reference patterns (not the JPEG pixels):
+
+| id | Pattern |
+|----|---------|
+| `scorecard-sparkline-comparison` | Five KPI tiles, solid + dotted sparkline |
+| `bar-time-rotated-ticks` | Vertical bars, rotated dates, y `formatValue` |
+| `line-three-series` | Three lines, markers, per-series legend |
+| `bar-day-of-week` | Seven categorical bars, horizontal ticks |
+| `donut-center-and-share` | Hole label + percent legend |
+| `donut-single-slice` | One 100% slice + center total |
+| `hows-it-going-dashboard` | Spanning grid: 5 KPIs, time bar, 3-line, DOW bar, two donuts, one table card |
+
+`bun run ui:charts:compare` must cover these. Agents use `review-chart-visuals`.
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+Universal React Native + web. Demo stories + visual gallery only. Tables stay `DataTable`
+inside `ChartCard`.
+
+## Phases
+
+1. **Tracer:** `SparklineChart` + `Scorecard` + `ChartCard` + `comparisonData` on the
+   sparkline; demo story; docs stub; golden for `scorecard-sparkline-comparison`.
+2. **Cartesian additive:** `series`, `comparisonData`, `xTickPolicy`, header shortcuts on
+   line/bar/area; goldens for time bar and 3-line.
+3. **Donut:** center stack + share legend; goldens for two-slice and 100% slice.
+4. **Grid spans:** `DashboardGridItem`; reference KPI wrap; compose `hows-it-going-dashboard`
+   charts (table slot placeholder ok until Phase 5).
+5. **Table chrome:** header groups, footer rows, range status, `wrapLines={2}`; table card
+   in the hard fixture.
+6. **Packaging + docs:** lazy exports, import regression, how-to rewrite, explanation,
+   reference, TypeDoc, changelog, ui rule export list.
+
+## Feature Flags & Migrations
+
+None. Additive public props. Existing `{label, value}[]` callers stay valid. Not a major.
+
+`legendLabel` remains for single-series cartesian. Multi-series uses `series[].label`.
+Donut still ignores `legendLabel`.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Chart children grammar (`Chart`, `ChartXAxis`, …) — still `charts-and-dashboards` Phase 6.
+- Date-range picker control.
+- Dual-period table cells.
+- Variable row height.
+- Example-frontend / comms wiring.
+- Zoom/pan, combo charts.
+
+## Files to Create / Modify
+
+See the task list. Docs in-slice:
+
+- `docs/how-to/charts-and-dashboards.md` (rewrite)
+- `docs/explanation/charts.md` (multi-series, scorecard, why not grammar-first)
+- `docs/reference/ui.md` (new exports)
+- `docs/how-to/compare-chart-rendered-snapshots.md` (new fixture ids)
+- `.rulesync/rules/ui/00-ui.mdc`
+- `changelog/unreleased/dashboard-chart-parity.md`
+- TypeDoc props (`bun run website:generate` in the docs task)
+
+## Task List
+
+[docs/tasks/dashboard-chart-parity.md](../tasks/dashboard-chart-parity.md)
+
+## Acceptance Criteria
+
+- [ ] `Scorecard`, `SparklineChart`, and `ChartCard` are importable from `@terreno/ui` and subpaths.
+- [ ] A scorecard shows title, formatted value, and a sparkline with dotted `comparisonData`.
+- [ ] `LineChart` renders three series from `series` with a legend item each.
+- [ ] Time-series x ticks can rotate; day-of-week ticks stay horizontal under `auto`.
+- [ ] `DonutChart` draws `centerTitle` / `centerValue` and percent legend rows.
+- [ ] `DashboardGridItem` spans reproduce 5→2→1 KPI and 3→1 chart wrapping in the reference fixture.
+- [ ] `DataTable` shows period header groups, a sticky totals row, `1–50 of N`, and two-line wrap inside `rowHeight`.
+- [ ] Existing single-series `{label, value}[]` charts and tests stay green.
+- [ ] `bun run ui:charts:compare` matches goldens including `hows-it-going-dashboard`.
+- [ ] How-to shows the easy-build composition (Scorecard + ChartCard + spans), not only raw `Card` + `LineChart`.
+- [ ] Chart implementations stay lazy on the root; grid item stays eager.
+- [ ] Frontend verification: demo gallery exercised on web; artifacts on the implementation PR.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Dual header APIs (`ChartCard` vs facade title) | Document exclusive use; tests assert no double header when only one is set |
+| `DataTable` wrap vs virtualization | Cap at two lines; keep `rowHeight`; screenshot a wrapped first column |
+| Additive `series` vs later grammar | Facades remain the supported easy path; grammar stays a follow-up |
+| Golden flake on dense dashboards | One hard fixture at a fixed gallery width; review-chart-visuals on mismatch |
+| Header groups vs pinned columns | Totals and groups must align with `pinnedColumns` scroll sync; regression tests |

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

@@ -104,7 +104,7 @@ import {AIService} from "@terreno/ai";
 import {google} from "@ai-sdk/google";
 
 const aiService = new AIService({
-  model: google("gemini-2.5-flash"),
+  model: google("gemini-3.8-flash"),
   defaultTemperature: 1.0,
 });
 ```
@@ -211,7 +211,9 @@ Conversation history with multi-modal prompts.
 | `userId` | ObjectId | Owner (required) |
 | `title` | string? | Auto-generated on first `/gpt/prompt` response when empty |
 | `projectId` | ObjectId? | Optional project association |
-| `prompts` | array | Messages: `text`, `type` (`user` \| `assistant` \| `system` \| `tool-call` \| `tool-result`), optional `content` parts, `model`, `rating`, tool fields. `text` is required unless `content` has parts; an image-only assistant response saves `text: ""` |
+| `prompts` | array | Messages: `text`, `type` (`user` \| `assistant` \| `system` \| `tool-call` \| `tool-result`), optional `content` parts, `model`, `rating`, tool fields, `status`, `streamId`. `text` is required unless `content` has parts or `status` is set; an image-only assistant response saves `text: ""` |
+
+Assistant replies from `/gpt/prompt` carry `streamId` and `status`: `streaming` while partial text is persisted, then `complete` or `error`. `buildMessages` skips `streaming` replies and `error` replies with no output. Attachment `content` parts carry an optional `gcsKey` when the file was uploaded to durable storage.
 
 **Virtual:** `ownerId` aliases `userId` for `Permissions.IsOwner`.
 
@@ -252,10 +254,36 @@ GPT project with persistent context and memories.
 | `/gpt/prompt` | POST | `IsAuthenticated` | SSE streaming chat; body: `prompt`, optional `historyId`, `systemPrompt`, `attachments`, `model`, `projectId` |
 | `/gpt/remix` | POST | `IsAuthenticated` | Non-streaming text remix; body: `{text}` |
 | `/gpt/histories/:id/rating` | PATCH | `IsAuthenticated` | Rate a prompt; body: `{promptIndex, rating: "up" \| "down" \| null}` |
+| `/gpt/histories/:id/stream` | GET | `IsAuthenticated` (owner) | SSE resume of an in-flight reply; query: optional `streamId`, `offset` |
 | `/gpt/tools` | GET | `IsAuthenticated` | List builtin + MCP tools |
 
 Generated images (image-output models such as `gemini-3-pro-image`) arrive as SSE `image` events: `{image: {mimeType, url}}` with a base64 data URL. Each image is sent once, even when the model reports it both as a stream file part and in the final `result.files`. The saved assistant prompt stores one `image` content part per image. On later turns, `buildMessages` sends an image-only assistant prompt to the model as the text `[Generated image]`, because providers reject empty assistant turns.
 
+#### Attachments
+
+Each `attachments` item is `{type: "image" | "file", url, mimeType, filename?}`. The `url` must be `http(s):` or `data:`. Client-only URLs (`blob:`, `file:`, `content:`, `ph:`) return `400` before streaming starts, because neither the model provider nor a later page load can read them. Upload the file with `POST /files/upload` first, or send it as a `data:` URL.
+
+When `fileStorageService` is set, `data:` attachments are uploaded with `FileStorageService.upload`. The saved user prompt then stores the storage `url` plus `gcsKey`, not the base64 payload. The model still receives the original data for that turn. On later turns, parts with a `gcsKey` are sent to the model as 1-hour signed URLs. A failed upload returns `502 Attachment upload failed`. Without storage, attachments are saved as sent.
+
+`fileUploadsEnabled` turns uploads off without removing storage. Pass `false`, or a function that returns `false`, and any prompt that includes attachments returns `403 File uploads are disabled` before streaming. Omit it, or pass `true`, to leave uploads enabled. The example app wires this to the `file-uploads` feature flag.
+
+#### Stream events and resume
+
+`/gpt/prompt` saves the user turn and a `status: "streaming"` assistant placeholder before streaming. While the reply streams, partial text is persisted about every second (`streamPersistIntervalMs`), plus a heartbeat every 10 seconds. The final reply replaces the placeholder with `status: "complete"`. On failure, partial text is kept with `status: "error"`; an empty placeholder is removed.
+
+| Event | Sent by | Meaning |
+|-------|---------|---------|
+| `{historyId, started: true, streamId}` | prompt | First event; the turn is saved and resumable |
+| `{historyId, resumed: true, streamId?}` | resume | First event; `streamId` is absent when nothing is streaming |
+| `{text}` | both | Text delta |
+| `{replace: true, text}` | resume | Authoritative whole reply: sent first when the client provides `offset`, and whenever persisted text was rewritten (for example, a step became a tool call) |
+| `{image: {mimeType, url}}` | both | Generated image |
+| `{file}`, `{toolCall}`, `{toolResult}` | prompt | File and tool events |
+| `{error}` | both | Error; resume sends it when the reply ended as `error` or went stale |
+| `{done: true, historyId, title?}` | both | Reply finished |
+
+`GET /gpt/histories/:id/stream` re-attaches after a reload or remount. Pass `offset` as the number of characters the client already shows, usually the stored placeholder `text`. The endpoint polls the stored history (`streamResumePollIntervalMs`, default 500 ms), so it works across server instances. A `streaming` reply with no update for `streamStaleAfterMs` (default 60 s) is marked `error`.
+
 AI resolution order: `x-ai-api-key` header + `createModelFn` → `createServerModelFn(modelId)` → configured `aiService` → demo SSE response when `demoMode` and none available.
 
 ### addGptHistoryRoutes(router, options?)
@@ -283,7 +311,7 @@ Requires `fileStorageService` and `gcsBucket` (registered by `AiApp` when both a
 
 | Endpoint | Method | Auth | Description |
 |----------|--------|------|-------------|
-| `/files/upload` | POST | `IsAuthenticated` | Multipart upload (`file` field); allowed MIME: images, PDF, plain text, CSV, JSON |
+| `/files/upload` | POST | `IsAuthenticated` | Multipart upload (`file` field); allowed MIME: images, PDF, plain text, CSV, JSON. Returns `403` when `fileUploadsEnabled` is off |
 | `/files/*gcsKey` | GET | None | Returns signed read URL (1 hour) |
 | `/files/*gcsKey` | DELETE | `IsAuthenticated` (owner) | Soft-delete attachment and remove from GCS |
 
@@ -311,7 +339,7 @@ Requires `mcpService` (registered by `AiApp` when set).
 import {AiApp, AIService, FileStorageService, MCPService} from "@terreno/ai";
 import {google} from "@ai-sdk/google";
 
-const aiService = new AIService({model: google("gemini-2.5-flash")});
+const aiService = new AIService({model: google("gemini-3.8-flash")});
 
 new AiApp({
   aiService,
@@ -320,7 +348,7 @@ new AiApp({
   mcpService: new MCPService([{name: "tools", transport: {type: "sse", url: "..."}}]),
   tools: myToolDefinitions,
   demoMode: false,
-  createModelFn: (apiKey, modelId) => google(modelId ?? "gemini-2.5-flash", {apiKey}),
+  createModelFn: (apiKey, modelId) => google(modelId ?? "gemini-3.8-flash", {apiKey}),
   openApiOptions: options,
 }).register(app);
 ```
@@ -331,7 +359,8 @@ new AiApp({
 | `createModelFn` | Build model from per-request `x-ai-api-key` |
 | `createServerModelFn` | Server-side model factory (e.g. Vertex ADC) without per-request key |
 | `demoMode` | Return canned responses when no AI service resolves |
-| `fileStorageService` + `gcsBucket` | Enable file upload routes |
+| `fileStorageService` + `gcsBucket` | Enable file upload routes and durable `/gpt/prompt` attachments |
+| `fileUploadsEnabled` | `false` or a function returning `false` rejects uploads and chat attachments with `403`. Omit to leave uploads enabled |
 | `mcpService` | Enable MCP routes and tool discovery in chat |
 | `tools` | Static Vercel AI SDK tool definitions for chat |
 | `toolChoice` | `"auto"` \| `"none"` \| `"required"` (default `"auto"` when tools present) |
@@ -447,10 +476,10 @@ import {
 } from "@terreno/ai";
 
 const vertex = await createVertexProvider({project: "my-gcp-project"});
-const model = vertex.languageModel("gemini-2.5-flash");
+const model = vertex.languageModel("gemini-3.8-flash");
 ```
 
-Env fallbacks: `GOOGLE_VERTEX_PROJECT`, `GOOGLE_VERTEX_LOCATION` (default `us-central1`).
+Env fallbacks: `GOOGLE_VERTEX_PROJECT`, `GOOGLE_VERTEX_LOCATION` (default `global`).
 
 ## Web search types
 
@@ -463,7 +492,7 @@ import {TerrenoApp} from "@terreno/api";
 import {AiApp, AIService, LangfuseApp} from "@terreno/ai";
 import {google} from "@ai-sdk/google";
 
-const aiService = new AIService({model: google("gemini-2.5-flash")});
+const aiService = new AIService({model: google("gemini-3.8-flash")});
 
 new TerrenoApp({userModel: User})
   .register(new AiApp({aiService, openApiOptions: {}}))
@@ -483,7 +512,7 @@ Legacy `setupServer` pattern: call `addGptHistoryRoutes`, `addGptRoutes`, etc. i
 | Variable | Used by | Description |
 |----------|---------|-------------|
 | `GOOGLE_VERTEX_PROJECT` | `createVertexProvider` | GCP project for Vertex models |
-| `GOOGLE_VERTEX_LOCATION` | `createVertexProvider` | Vertex region (default `us-central1`) |
+| `GOOGLE_VERTEX_LOCATION` | `createVertexProvider` | Vertex region (default `global`) |
 | `LANGFUSE_PUBLIC_KEY` | `LangfuseApp` | Langfuse public key |
 | `LANGFUSE_SECRET_KEY` | `LangfuseApp` | Langfuse secret key |
 | `LANGFUSE_BASE_URL` | Langfuse client | Langfuse host URL |

package/dist/docs/versioned/next/reference/environment-variables.md

@@ -120,7 +120,7 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 | `GEMINI_API_KEY` | `@terreno/ai` | ❌ | — | Yes | server |
 | `OPENAI_API_KEY` | `@terreno/ai` | ❌ | — | Yes | server |
 | `GOOGLE_VERTEX_PROJECT` | `@terreno/ai` | ❌ | — | No | server |
-| `GOOGLE_VERTEX_LOCATION` | `@terreno/ai` | ❌ | — | No | server |
+| `GOOGLE_VERTEX_LOCATION` | `@terreno/ai` | ❌ | `global` | No | server |
 | `GOOGLE_VERTEX_ALLOWED_MODELS` | `@terreno/ai` | ❌ | all | No | server |
 | `CLAUDE_KEY` | tooling | ❌ | — | Yes | tooling |
 | `LANGFUSE_SECRET_KEY` | `@terreno/ai` | ❌ | — | Yes | server |

package/dist/docs/versioned/next/reference/feature-flags.md

@@ -63,7 +63,7 @@ New code can also use OpenFeature React hooks (`useBooleanFlagValue`, `useString
 
 ## OpenFeature integration
 
-`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/rtk`, or migrate direct HTTP callers to `/flagConfiguration`.
+`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). Disabled **boolean** flags are included and resolve to `off`, so a client can tell a turned-off flag from one that was never created. Disabled variant flags and archived flags are omitted. The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/rtk`, or migrate direct HTTP callers to `/flagConfiguration`.
 
 ### `defaultVariant` on `FeatureFlag`