@terreno/mcp 57.7.0 → 57.8.0

package/dist/docs/resources/ui.md

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

package/dist/docs/upgrades/57.8.0.md

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

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

@@ -20,6 +20,7 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
 | Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
 | Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/consents.tsx`, admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| 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` | |
 | 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. |

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

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

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

@@ -1257,6 +1257,20 @@ IP and tracking issue; this entry is the release checklist, not a plan.
 
 ---
 
+## demo-workshop
+
+**Title:** `Demo workshop`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`demo-workshop`, Status=`Planned`
+
+Turn the Expo demo into the workshop for `@terreno/ui`: a person can find a component, copy a usage snippet, change theme and viewport from the URL, and see whether every stable story passes interaction, accessibility, and visual checks on web and Android.
+
+- **Implementation plan:** [demo-workshop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/demo-workshop.md)
+- **Tasks:** [demo-workshop.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/demo-workshop.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

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

@@ -351,20 +351,35 @@ a closed PR.
 `manual-publish-package` also accepts `feature-flags`. Versions must be semver.
 Semver git tags (`57.3.0`, `57.3.0-beta.1`) automatically start
 `publish-release`; prereleases publish to their prerelease npm dist-tag.
-`scripts/ci/publish-package.sh` pins `workspace:*` to the tag version for the
-tarball, then compiles and tests against the root workspace install. It must
-not `bun install` after that pin: sibling `@terreno/*` packages are not on npm
-yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on the registry
-and fail the whole job. Tests use `test:ci` when that script exists, not
-`test`. `@terreno/ui`'s `test` is `bun test --watch` and would hang the
-publish step after the suite finishes. `publish-release` uses a 20-minute
-no-output timeout as a backstop. If a package's tag version is already on npm,
-`publish-package.sh` skips it so a recut of the same tag can finish the rest.
-
-Only stable tags (`57.3.0`) run `deploy-demo` after publish. Use
+`publish-release` compiles the 16 lockstep packages once with
+`bun run --filter ... compile` (dependency order), then runs
+`scripts/ci/publish-package.sh` for all of them in parallel with
+`TERRENO_PUBLISH_PREBUILT=1`. It does not rerun tests: the tagged commit
+already passed CI on master, and rerunning every suite per package made
+releases take 20+ minutes. The job has no Mongo sidecar. Each publish writes
+its own temporary npmrc (`NPM_CONFIG_USERCONFIG`) so parallel publishes do not
+remove each other's token.
+
+`publish-package.sh` pins `workspace:*` to the tag version for the tarball.
+It must not `bun install` after that pin: sibling `@terreno/*` packages are
+not on npm yet, so bun would look up `@terreno/test@X.Y.Z` (and similar) on
+the registry and fail the whole job. Without `TERRENO_PUBLISH_PREBUILT` (the
+manual single-package publish), it compiles the package and its workspace
+dependencies and runs `test:ci` when that script exists, not `test`.
+`@terreno/ui`'s `test` is `bun test --watch` and would hang. If a package's
+tag version is already on npm, `publish-package.sh` skips it so a recut of
+the same tag can finish the rest.
+
+Only stable tags (`57.3.0`) run `deploy-demo`. It builds the demo from source,
+so it runs alongside `publish-release` instead of waiting for it. Use
 `{"run-demo-deploy":true}` on `master` if a prerelease must also refresh the
 demo site.
 
+`scripts/ci/netlify-deploy.sh` builds each site itself and calls
+`netlify deploy --no-build`. Without `--no-build`, netlify-cli runs the root
+`netlify.toml` docs build (wipe `node_modules`, reinstall, full Docusaurus),
+which added about 3.5 minutes to every demo and frontend deploy.
+
 CircleCI does not receive GitHub `pull_request.closed` events, so
 `.github/workflows/preview-cleanup.yml` forwards them: it runs master's
 `scripts/ci/trigger-circleci-pipeline.sh` with `{"run-preview-cleanup":"<PR>"}`

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

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

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

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

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

@@ -211,7 +211,7 @@ 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. `text` is required unless `content` has parts; an image-only assistant response saves `text: ""` |
 
 **Virtual:** `ownerId` aliases `userId` for `Permissions.IsOwner`.
 
@@ -254,6 +254,8 @@ GPT project with persistent context and memories.
 | `/gpt/histories/:id/rating` | PATCH | `IsAuthenticated` | Rate a prompt; body: `{promptIndex, rating: "up" \| "down" \| null}` |
 | `/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.
+
 AI resolution order: `x-ai-api-key` header + `createModelFn` → `createServerModelFn(modelId)` → configured `aiService` → demo SSE response when `demoMode` and none available.
 
 ### addGptHistoryRoutes(router, options?)

package/dist/docs/versioned/next/reference/announcement-release-packs.md

@@ -0,0 +1,146 @@
+# Announcement release packs
+
+An announcement release pack is a reviewable directory containing one manifest and one Markdown file per announcement. Import the pack through `POST /announcements/import-release`; imports are idempotent by product, release version, channel, and announcement slug.
+
+## Directory format
+
+```text
+announcements/releases/1.14.0/
+  pack.yaml
+  staff-required.md
+  patient-banner.md
+  changelog.md
+```
+
+`pack.yaml` carries release metadata, shared defaults, and the ordered file list:
+
+```yaml
+schema: terreno.announcement-pack/v1
+release:
+  product: example
+  version: "1.14.0"
+  buildNumber: 1842
+  channel: production
+defaults:
+  platforms: [ios, android, web]
+  audienceType: all
+  displayMode: feed
+  acknowledgementPolicy: dismiss-only
+  priority: 0
+announcements:
+  - staff-required.md
+  - patient-banner.md
+  - changelog.md
+```
+
+Each announcement is Markdown with YAML frontmatter:
+
+```markdown
+---
+slug: staff-1-14-required
+title: "Staff: version 1.14.0 is live"
+displayMode: modal
+audienceType: staff
+acknowledgementPolicy: required
+priority: 20
+primaryAction:
+  label: Read the release notes
+  url: https://example.com/releases/1.14.0
+---
+
+## What changed in 1.14.0
+
+The updated workflow is now available.
+```
+
+Frontmatter overrides manifest defaults. Supported fields are:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `slug` | Yes | Lowercase, hyphenated stable ID within the release. Re-importing the same slug updates instead of duplicating. |
+| `title` | Yes | Surface title. Include the user-facing release version. |
+| `displayMode` | No | `modal`, `banner`, or `feed`. |
+| `audienceType` | No | `all`, `staff`, or `patient`. |
+| `acknowledgementPolicy` | No | `required` or `dismiss-only`. |
+| `platforms` | No | Any non-empty subset of `ios`, `android`, and `web`. |
+| `priority` | No | Higher values appear first. |
+| `minBuildNumber` | No | Per-item override for the release build number. |
+| `publishAt`, `expiresAt` | No | ISO 8601 timestamps. |
+| `audience` | No | Consumer-defined targeting object. |
+| `primaryAction` | No | Object containing `label` and absolute `url`. |
+
+## Versioning
+
+The format has three separate versions:
+
+1. `schema` versions the pack contract. The current value is `terreno.announcement-pack/v1`.
+2. `release.version` is the user-facing product version and is stored with each imported announcement.
+3. `release.buildNumber` is the client build and becomes `minBuildNumber` unless an announcement overrides it.
+
+The announcement model's numeric `version` is server-managed content revision metadata. Do not put it in a pack. Editing the title or body of an already-published imported announcement increments it and re-shows required content where applicable.
+
+## Example pack
+
+`example-backend/announcements/releases/1.14.0/` is a complete pack with a required staff modal, a patient banner, and a changelog feed item. The example backend ships a loader that parses the pack, validates it with `announcementReleaseImportSchema`, and prints or uploads the JSON body:
+
+```bash
+cd example-backend
+bun run announcements:pack announcements/releases/1.14.0                  # print JSON
+bun run announcements:pack announcements/releases/1.14.0 --upload http://localhost:4000
+bun run announcements:pack announcements/releases/1.14.0 --publish --upload <api-url>
+```
+
+Uploads use `ANNOUNCEMENTS_UPLOAD_TOKEN`, falling back to the example default `terreno-example-announcement-upload`. Uploads are drafts unless `--publish` is passed.
+
+## Import API
+
+Enable automation with a dedicated secret:
+
+```typescript
+new AnnouncementsApp({
+  uploadToken: process.env.ANNOUNCEMENTS_UPLOAD_TOKEN,
+});
+```
+
+The example Cloud Run backend seeds `ANNOUNCEMENTS_UPLOAD_TOKEN` from Terraform (`announcements_upload_token`, default `terreno-example-announcement-upload`). Use that bearer token against the example preview or production URL. Preview deploys use the same default until the secret exists.
+
+Send the parsed manifest and Markdown files as JSON:
+
+```bash
+curl --fail-with-body \
+  -H "Authorization: Bearer $ANNOUNCEMENTS_UPLOAD_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data @announcement-release.json \
+  https://api.example.com/announcements/import-release
+```
+
+The request shape is:
+
+```json
+{
+  "release": {
+    "product": "example",
+    "version": "1.14.0",
+    "buildNumber": 1842,
+    "channel": "production"
+  },
+  "defaults": {
+    "platforms": ["ios", "android", "web"],
+    "displayMode": "feed"
+  },
+  "announcements": [
+    {
+      "slug": "changelog",
+      "title": "Version 1.14.0",
+      "body": "## What changed\n\nRelease details."
+    }
+  ],
+  "publish": false
+}
+```
+
+`publish` defaults to `false`, so new rows are drafts. Pass `"publish": true` only for an intentional live import. Draft re-imports do not unpublish an existing live announcement. An authenticated admin may also call the endpoint without the dedicated upload token.
+
+The response reports `created`, `updated`, `unchanged`, and `published` counts plus the ID, slug, status, and content version of each row.
+
+The body is validated with the exported Zod schema `announcementReleaseImportSchema` before any row is written. Unknown keys, malformed slugs, empty titles or bodies, invalid enum values, missing `release.product` / `release.version`, and duplicate slugs return **400** `Validation failed` with per-field messages in `meta.fields`. `importAnnouncementRelease` runs the same schema when called directly from server code.