@terreno/mcp 57.8.0 → 57.9.0

package/src/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/src/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/src/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/src/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`
 

package/src/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