@terreno/mcp 57.7.0 → 57.9.0

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/implementationPlans/demo-workshop.md

@@ -0,0 +1,219 @@
+# Implementation Plan: Demo workshop
+
+**Status:** Approved
+**Branch:** `cursor/demo-workshop-cc39`
+**Owner:** —
+**Created:** 2026-09-26
+**Task list:** [demo-workshop.md](../tasks/demo-workshop.md)
+**Depends on:** —
+**RTK deprecation flag:** None
+**Supersedes:** the visual-regression non-goal in [examples-demo-coverage.md](examples-demo-coverage.md). Story coverage from that plan stays as it is.
+
+## Goal
+
+Turn the Expo demo into the workshop for `@terreno/ui`: a person can find a component, copy a usage snippet, change theme and viewport from the URL, and see whether every stable story passes interaction, accessibility, and visual checks on web and Android.
+
+Released demo majors stay online. The site opens on the newest released major (57 today). A dropdown lists older majors, such as 56, and the next major when `preview/<major>` exists, such as 58 preview.
+
+## Non-Goals
+
+- An addon or plugin system.
+- iOS simulator runs, iOS screenshot baselines, and iOS accessibility checks.
+- A translation catalog for `@terreno/ui`.
+- The commented combinatorial prop matrix in `demo/app/demo/[component].tsx`.
+- A pull-request comment bot.
+- Rebuilding frozen majors on later master commits.
+- Android baselines for historical majors. Android CI proves the branch under test.
+- Feature-branch Netlify aliases (`pr-*`) appearing in the version dropdown.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Platforms | Web and Android in this plan. iOS is a later plan. |
+| Visual coverage | Every stable named story. A story may opt out only with `stability: "exclude"` and a non-empty reason. |
+| Usage snippets | One curated `usageExample` string on each story config, shown with a copy button. |
+| Preview controls | Theme, viewport, background, locale, right-to-left, and reduced motion on demo and dev routes. State lives in the URL. Embeds apply the query and hide the bar. |
+| Theme values | Light, plus the existing canonical dark role remap (`demo/components/palette/darkTheme.ts`). Custom palettes stay on `/palette`. |
+| Viewports | The Box breakpoints already documented for web: 320, 375, 1024, and 1280. |
+| Locale | The toolbar passes the selected locale only to components that already read one (consent content, date and calendar formatting). Right-to-left is a separate control. |
+| Collaboration | CI artifacts and a check summary. No pull-request comment. |
+| Agent access | Public `@terreno/mcp` tools read a generated demo catalog and the version manifest URL. |
+| Visual comparison | Separate cropped web and Android PNG baselines. Reuse the chart pixel matcher. An Android-specific tolerance requires a note in the how-to. |
+| Android CI | The full Android suite blocks pull requests that change `ui/` or `demo/`. |
+| Preview branch | `preview/<major>` (for example `preview/58`) is the only branch labeled as the next-major preview. |
+| Frozen majors | When master moves to a new major, keep the previous major at its last master commit. The current major redeploys on every master merge. Backfill 56 from its last master commit. |
+| Version dropdown | Persistent top bar on the home, demo, and dev pages. Default is the highest released major, which is the production deploy. |
+| Docs embeds | A docs version embeds the demo major it documents. The next docs version embeds `preview/<major>` when that deploy exists. |
+| Accessibility | Web uses axe and fails a story on serious or critical violations. Android asserts the accessibility tree from the same step list. Moderate axe findings are warnings in the health report. |
+| Interaction source | One declarative step list per story. Playwright runs it on web. A generated Maestro flow runs it on Android. |
+
+## Architecture
+
+```text
+demo/demoConfig.tsx
+  usageExample, related routes, story stability, interaction steps
+        │
+        ├─ home/dev search + category filters + linked related components
+        ├─ preview bar (URL state) and version bar (versions.json)
+        ├─ web Playwright: interactions, axe, cropped PNG
+        ├─ Android Maestro: same steps, accessibility tree, cropped PNG
+        └─ demo-catalog.json ── @terreno/mcp list/get tools
+
+master deploy ── production site = current major (57)
+last 56 master commit ── Netlify alias v56 (frozen)
+preview/58 ── Netlify alias v58 (preview: true)
+production /versions.json ── dropdown on every major
+```
+
+### Catalog contract
+
+`DemoConfiguration` gains:
+
+- `usageExample: string` — copyable usage, including the import when it is a normal `@terreno/ui` import.
+- `related` entries resolve through `findDemoConfig`. Unknown names fail the catalog test.
+- `stories[name].stability`: `"stable"` by default, or `"exclude"` with `excludeReason`.
+- `stories[name].showInDemo` is honored. `false` hides that story from demo mode and keeps it on the dev route.
+- `stories[name].interactions`: ordered steps `{action: "press" | "type" | "expectText" | "expectRole", targetTestID?, value?, role?, name?}`.
+- Control defaults come from the control type: `false` for boolean, `0` for number, `""` for string. The `""` fallback for every type goes away.
+
+`demo/collectRegisteredStoryRenders.ts` remains the inventory. Story ids stay `<Component> / <story>`.
+
+### Preview and version chrome
+
+`DemoChrome` wraps home, demo, and dev. The version dropdown is on every non-embed page. Preview controls are on demo and dev component routes. `?embed=1` hides both and still applies preview query params.
+
+Preview query keys: `theme`, `viewport`, `background`, `locale`, `rtl`, `reducedMotion`.
+
+The version dropdown does not switch code inside one bundle. It navigates to that major's deploy. Every bundle loads `versions.json` from the production demo origin so a frozen major learns about a new preview without a rebuild. That file is served with CORS for the demo aliases.
+
+```typescript
+interface DemoVersionManifest {
+  currentMajor: number;
+  versions: {
+    major: number;
+    label: string;
+    url: string;
+    preview: boolean;
+    released: boolean;
+  }[];
+}
+```
+
+`currentMajor` is the highest `released && !preview` entry. Production is that major. `preview/58` adds `{major: 58, label: "58 preview", preview: true, released: false}` while the branch exists. Merging 58 to master freezes 57 onto alias `v57`, points production at 58, and removes the preview flag.
+
+Feature-branch aliases stay out of the manifest.
+
+### Proof
+
+| Check | Web | Android |
+| --- | --- | --- |
+| Render | Existing `demo/storiesSmoke.test.tsx` | Maestro opens the story |
+| Interaction | Playwright runs `interactions` | Generated Maestro flow |
+| Accessibility | axe, serious and critical fail | Accessibility-tree assertions from `expectRole` / labels |
+| Visual | Cropped PNG in `demo/rendered-snapshots/web/` | Cropped PNG in `demo/rendered-snapshots/android/` |
+
+Chart goldens stay in `demo/rendered-snapshots/` until the chart task moves them. The chart compare script keeps working for chart fixtures.
+
+A stable story without a web golden, an Android golden, or an exclusion fails CI. The same rule applies to interaction steps.
+
+`demo/story-health.json` is produced by those jobs and copied into the demo build. The component page shows pass, fail, or not-run for render, interaction, accessibility, and visual, per platform. Missing file means not-run.
+
+CI uploads the JSON, PNGs, and diffs as job artifacts and writes a check summary. It does not comment on the pull request.
+
+Android runs on a CircleCI Android image with one pinned emulator: Pixel 6, API 34. The job is path-filtered like today's Maestro demo job (`ui/**`, `demo/**`) and is required on those pull requests.
+
+### MCP
+
+`bun run demo:catalog` writes `demo/demo-catalog.json` with component name, category, route, snippet, story ids, stability, and the production `versions.json` URL. `@terreno/mcp` exposes:
+
+- `terreno_list_demo_stories`
+- `terreno_get_demo_story`
+
+Tools return catalog data. They do not drive a browser and they do not run Android.
+
+### Docs embeds
+
+`website` `DEMO_URL` becomes per docs version. Version 57.x points at the 57 demo alias (production while 57 is current). The next docs version points at the `preview/<major>` URL when the manifest lists that preview, and otherwise at production. `ComponentDemo` keeps `?embed=1`.
+
+## Models
+
+None.
+
+## APIs
+
+`GET /versions.json` on the production demo host, shape above.
+
+MCP tools `terreno_list_demo_stories` and `terreno_get_demo_story`. No new HTTP API on `@terreno/api`.
+
+## Notifications
+
+None.
+
+## UI
+
+- Home and dev: search box and category filters over `DemoConfig`.
+- Component page: copyable snippet, linked related components, preview controls, per-story health.
+- Persistent version dropdown on home, demo, and dev.
+- Embed mode unchanged except that preview query params apply.
+
+Frontend verification uses the running web demo. Android verification uses the emulator flow for Button, then the full stable catalog.
+
+## Phases
+
+1. Catalog contract, search, snippets, and the preview bar. Button is the tracer.
+2. Web interaction, axe, and visual baselines, then the health report.
+3. Android emulator CI for Button, then every stable story.
+4. Version manifest, frozen majors, preview branch, docs embeds.
+5. MCP catalog tools.
+
+## Feature Flags & Migrations
+
+None. New demo query params are optional. Existing `/demo/<component>` URLs keep working. Production keeps serving the current major at the existing demo host.
+
+## Not Included / Future Work
+
+- iOS simulator coverage and iOS goldens.
+- Library-wide translations.
+- Demo addon API.
+- Pixel baselines for every historical major.
+
+## Files to Create / Modify
+
+Create
+
+- `docs/how-to/preview-demo.md`
+- `docs/how-to/demo-versions.md`
+- `docs/how-to/compare-demo-snapshots.md`
+- `demo/components/DemoChrome.tsx`
+- `scripts/demo/` runners and manifest publisher
+- `demo/demo-catalog.json` (generated)
+
+Modify
+
+- `demo/demoConfig.tsx`, `demo/story-config/*.config.tsx`, `demo/app/demo/[component].tsx`
+- `demo/components/DemoHomePage.tsx`, `demo/components/DevHomePage.tsx`
+- `demo/README.md`
+- `docs/reference/test.md`, `docs/reference/ui.md`, `docs/reference/mcp-server.md`
+- `docs/how-to/run-tests-locally.md`, `docs/how-to/circleci.md`
+- `.circleci/config.yml`, `.circleci/continue-config.yml`
+- `scripts/ci/netlify-deploy.sh`
+- `website/src/components/ComponentDemo/index.tsx`, `website/docusaurus.config.ts`
+- `mcp-server/src/tools.ts`
+
+## Task List
+
+[docs/tasks/demo-workshop.md](../tasks/demo-workshop.md)
+
+## Acceptance Criteria
+
+- [ ] Search on the home grid finds Button by name and by category, and Button's related components are links.
+- [ ] Every registered component has a `usageExample`, and the Button page copies it.
+- [ ] A URL on the Button demo sets theme, viewport, background, locale, right-to-left, and reduced motion. Embed hides the bar and keeps the query.
+- [ ] Every stable story has web interaction steps or an exclusion reason, an axe result, and a web PNG baseline.
+- [ ] The same stable stories have Android interaction, accessibility-tree, and PNG results. The Android job fails the pull request when `ui/` or `demo/` changes.
+- [ ] The Button page shows health from `story-health.json`. CI publishes a check summary and artifacts and does not comment.
+- [ ] Production opens on major 57. Alias `v56` serves the last major-56 master commit. `preview/58` appears as "58 preview" and is not the default.
+- [ ] A 57 docs page embeds the 57 demo. The next docs version embeds the 58 preview when that alias exists.
+- [ ] `terreno_get_demo_story` returns Button's snippet, route, and the version manifest URL.
+- [ ] `demo/README.md`, the how-to pages named above, and the reference pages named above match this behavior.

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 |
+| `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,8 +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?)
@@ -281,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 |
 
@@ -309,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,
@@ -318,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);
 ```
@@ -329,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) |
@@ -445,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
 
@@ -461,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: {}}))
@@ -481,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 |