@terreno/mcp 57.6.1 → 57.8.0

package/src/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/src/docs/versioned/next/implementationPlans/describe-model-schema.md

@@ -1,6 +1,6 @@
 # `describeModel()` schema metadata
 
-**Status:** Approved — 2026-08-24  
+**Status:** Complete — shipped in #1154  
 **Branch:** `cursor/architecture-ips-a7ec`  
 **Owner:** —  
 **Created:** 2026-08-24  

package/src/docs/versioned/next/implementationPlans/docs-reference-coverage.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Reference Documentation Coverage
 
-**Status:** In progress — remaining README, sanitization, and docs-audit work
+**Status:** Complete
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1009
 **Priority:** High
 **Effort:** Big batch

package/src/docs/versioned/next/implementationPlans/docs-site-and-versioning.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
 
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1086  
-**Status:** Approved
+**Status:** Complete — shipped in #754
 
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 

package/src/docs/versioned/next/implementationPlans/examples-demo-coverage.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Examples, Demo, and Test Coverage
 
-**Status:** Approved — key decisions recorded (2026-07-29)
+**Status:** Complete — shipped in #1299
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1016
 **Priority:** Medium
 **Effort:** Big batch

package/src/docs/versioned/next/implementationPlans/framework-audit-log.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Framework-level audit log
 
-**Status:** Approved  
+**Status:** Complete — shipped in #1301  
 **Branch:** `cursor/framework-audit-log-grow-0d6c`  
 **Owner:** —  
 **Created:** 2026-09-10  

package/src/docs/versioned/next/implementationPlans/gpt-chat-mascot.md

@@ -1,6 +1,7 @@
 # GPTChat optional mascot
 
 **Status:** Complete  
+**Roadmap:** Area=`ui`, Target=`Released`, Impact=`Feature`  
 **Branch:** `cursor/gpt-chat-mascot-d39f`  
 **Owner:** cloud agent  
 **Created:** 2026-09-15

package/src/docs/versioned/next/implementationPlans/inbound-webhooks.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Inbound webhook framework
 
-**Status:** Approved  
+**Status:** Complete — shipped in #1251  
 **Branch:** `cursor/inbound-webhooks-4945`  
 **Owner:** —  
 **Created:** 2026-09-01  

package/src/docs/versioned/next/implementationPlans/knip-cleanup.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Remove the Knip baseline
 
 **Status:** Complete  
+**Roadmap:** Area=`dx`, Target=`Released`, Impact=`Improvement`  
 **Created:** 2026-09-09  
 **Owner:** unassigned  
 **Primary packages:** repo-wide (`knip.jsonc`, `scripts/static-analysis/`, every workspace Knip currently fingerprints)  

package/src/docs/versioned/next/implementationPlans/mcp-doc-sync-off-compile-path.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Move mcp-server doc-sync off the compile path
 
-**Status:** Approved (2026-09-22)
+**Status:** Complete
+**Roadmap:** Area=`dx`, Target=`Released`, Impact=`Improvement`  
 **Scan goal:** reduce-cold-compile-time ([charter](../scans/reduce-cold-compile-time/charter.md)) — cold `bun run compile` 305s → 214s
 **Slice:** mcp-doc-sync-off-compile-path (round 1) — **must land before** `compile-pipeline-dedup`
 **Findings:** mcp-doc-sync-on-compile-path (medium, S)

package/src/docs/versioned/next/implementationPlans/mcp-service-tokens.md

@@ -1,6 +1,7 @@
 # Implementation Plan: MCP service tokens
 
-**Status:** Approved  
+**Status:** Complete — shipped in #1263  
+**Roadmap:** Area=`mcp`, Target=`Released`, Impact=`Feature`  
 **Branch:** TBD  
 **Owner:** unassigned  
 **Created:** 2026-09-03  

package/src/docs/versioned/next/implementationPlans/migrate-admin-to-syncdb.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Migrate built-in admin to syncdb
 
-**Status:** Approved
+**Status:** Complete
+**Roadmap:** Area=`admin`, Target=`Released`, Impact=`Improvement`  
 **Branch:** `cursor/migrate-admin-to-syncdb-de61`
 **Owner:** Josh Gachnang
 **Created:** 2026-09-01

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -214,7 +214,7 @@ are ported.
 | `codeql-analysis` | CircleCI job uploading SARIF to GitHub Code Scanning API **or** third-party SAST orb; preserve Security tab if possible |
 | `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
 | `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
-| `roadmap-generate` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
+| `roadmap-generate`, `roadmap-sync`, `roadmap-reconcile` | **Stay on GitHub Actions** (decided 2026-09-26). They only talk to GitHub (issues, Projects v2, `master` commits via `ROADMAP_PROJECT_TOKEN`), so moving them buys nothing. Exception to CC1. |
 | `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `push.branches-ignore: ["**"]`. |
 | Cursor Approval / Security / Bugbot | **Cannot move.** Cursor GitHub App automations, not repo workflows. |
 | `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |

package/src/docs/versioned/next/implementationPlans/mongodb-migrations-tooling.md

@@ -1,6 +1,6 @@
 # MongoDB migrations tooling
 
-**Status:** Approved — decisions 2026-09-10  
+**Status:** Complete  
 **Branch:** `cursor/mongodb-migrations-tooling-04f9`  
 **Owner:** —  
 **Created:** 2026-09-10  

package/src/docs/versioned/next/implementationPlans/notification-center.md

@@ -1,6 +1,6 @@
 # Implementation Plan: In-app notification center
 
-**Status:** Approved  
+**Status:** Complete — shipped in #1307  
 **Branch:** `cursor/notification-center-ip-b11f`  
 **Owner:** —  
 **Created:** 2026-09-10  

package/src/docs/versioned/next/implementationPlans/org-management-ui.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Organizations as a first-class primitive (admin UI + RBAC)
 
-**Status:** Approved
+**Status:** Complete
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
 **Priority:** High
 **Effort:** Big batch

package/src/docs/versioned/next/implementationPlans/password-reset-and-email-verification.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Password reset and email verification
 
-**Status:** Approved
+**Status:** Complete
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1023
 **Priority:** High
 **Effort:** Big batch

package/src/docs/versioned/next/implementationPlans/rate-limiting.md

@@ -1,6 +1,6 @@
 # Implementation Plan: API rate limiting
 
-**Status:** Approved  
+**Status:** Complete  
 **Branch:** `cursor/api-rate-limiting-d03a`  
 **Owner:** —  
 **Created:** 2026-08-30  

package/src/docs/versioned/next/implementationPlans/remove-legacy-realtime.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Remove legacy RTK realtime in Terreno 58
 
 **Status:** Approved  
+**Roadmap:** Area=`api`, Target=`58`, Impact=`Breaking`  
 **Branch:** `cursor/deprecate-realtime-for-58`  
 **Owner:** unassigned  
 **Created:** 2026-08-25  

package/src/docs/versioned/next/implementationPlans/support-agent.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Support answering agent (`@terreno/support`)
 
 **Status:** Draft — awaiting approval (Grow ran unattended; every Decisions row marked `assumed` is a recommended default the reviewer can change before Approve)  
+**Roadmap:** Area=`ai`, Target=`Future`, Impact=`Feature`  
 **Branch:** `cursor/support-agent-grow-fd63`  
 **Owner:** unassigned  
 **Created:** 2026-09-15  

package/src/docs/versioned/next/implementationPlans/syncdb-codegen.md

@@ -1,7 +1,7 @@
 # Implementation Plan: @terreno/syncdb-codegen
 
 **Status:** Complete — shipped as `syncdb/src/codegen` + `terreno-syncdb-codegen`
-**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1087
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1110
 **Branch:** cursor/syncdb-codegen-in-package-746d
 **Owner:**
 **Created:** 2026-07-08

package/src/docs/versioned/next/implementationPlans/terreno-langfuse-integration.md

@@ -1,7 +1,7 @@
 # @terreno/langfuse
 
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1093  
-**Status:** Approved
+**Status:** Complete
 
 > **See also:** Native in-app observability (prompts, traces, evals, experiments, review queue) is specified in [ai-observability.md](./ai-observability.md). This IP remains the **Langfuse Cloud/self-host vendor plugin**. Both plugins may be registered; traces/scores fan out (see that IP).
 

package/src/docs/versioned/next/implementationPlans/upgrade-guides-and-skill.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
 
-**Status:** Approved
+**Status:** Complete
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1013
 **Priority:** High
 **Effort:** Big batch

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

package/src/docs/versioned/next/reference/announcements.md

@@ -27,6 +27,7 @@ new TerrenoApp({ userModel: User })
 | `help.enabled` | `boolean` | `false` | Registers help search/detail routes for MCP and in-app help |
 | `matchAudience` | `(user, announcement) => boolean` | always `true` | Opaque audience JSON filter composed with `audienceType` via `matchAudienceByType` |
 | `isStaff` | `(user) => boolean` | `user.admin === true` | Staff check used by `matchAudienceByType` for `audienceType` |
+| `uploadToken` | `string` | unset | Dedicated bearer token for idempotent `POST /announcements/import-release` automation |
 | `permissions` | partial CRUD overrides | admin-only | Overrides default `IsAdmin` permissions on announcement CRUD |
 
 ## Acknowledgement policy
@@ -52,7 +53,7 @@ Legacy MongoDB documents that still store `requiresAcknowledgement: true` map to
 
 ## Models
 
-- **Announcement** — `title`, `body` (markdown), `status` (`draft` | `published` | `archived`), `version`, `priority`, `displayMode` (`modal` | `banner` | `feed`, default `modal`), `audienceType` (`staff` | `patient` | `all`, default `all`), `acknowledgementPolicy`, optional `minBuildNumber`, `audience` (Mixed), `publishAt`, `expiresAt`, `platforms`, `primaryAction`
+- **Announcement** — `title`, `body` (markdown), `status` (`draft` | `published` | `archived`), `version`, `priority`, `displayMode` (`modal` | `banner` | `feed`, default `modal`), `audienceType` (`staff` | `patient` | `all`, default `all`), `acknowledgementPolicy`, optional `minBuildNumber`, `audience` (Mixed), `publishAt`, `expiresAt`, `platforms`, `primaryAction`, and optional imported `release` metadata plus `releaseSlug`
 - **AnnouncementAcknowledgement** — per-user acknowledgement at a specific `version`
 - **AnnouncementImpression** — per-view analytics row
 - **AnnouncementClickEvent** — per-click analytics row (`action: "primaryAction"`, `version` at click time, optional `platform`)
@@ -83,7 +84,7 @@ The plugin applies `matchAudienceByType` before `matchAudience`. When `isStaff`
 | GET | `/announcements/pending` | Current interrupt (`modal` or `banner` only) + `remainingCount` (`platform` query: `ios` \| `android` \| `web`; optional `version` build number) |
 | GET | `/announcements/feed` | Paginated published changelog — all display modes (`platform` and optional `version` as above) |
 | POST | `/announcements/:id/acknowledge` | Record acknowledgement (idempotent per version). Same visibility as pending/feed; **404** when not visible. |
-| POST | `/announcements/:id/impression` | Record a view. Same visibility as pending/feed; **404** when not visible. |
+| POST | `/announcements/:id/impression` | Record a view (`{ platform? }`). Same visibility as pending/feed; **404** when not visible. **400** for unknown keys or an invalid `platform`. |
 | POST | `/announcements/:id/click` | Record a primary-action click (`{ action: "primaryAction", platform? }`; optional `?version=` for min-build visibility). Returns **404** when not visible (checked before action/CTA validation). **400** when `action` is invalid, `primaryAction` is absent, or an explicit `platform` value is invalid. |
 
 `current` and feed items include resolved `requiresAcknowledgement` (boolean) and `displayMode` derived from policy resolution and stored fields above.
@@ -96,7 +97,7 @@ Optional integer build number on `GET /pending`, `GET /feed`, and help routes. W
 - `?version=10` (or higher) shows it
 - omitting `version` does **not** hide gated items
 
-`POST /announcements/:id/acknowledge`, `POST /announcements/:id/impression`, and `POST /announcements/:id/click` use the same visibility rules as pending/feed (schedule, expiry, platform, min build, `audienceType`, and `matchAudience`). All three return **404** when the announcement is not visible to the caller, so targeted IDs cannot be confirmed by writing event rows. Click checks visibility before action/CTA validation. Returns **400** when `action` is not `"primaryAction"`, the announcement has no `primaryAction`, or an explicit body `platform` is not `ios` / `android` / `web` (omit `platform` to use query/user-agent resolution). Each click inserts a new row (not idempotent). Acknowledge is idempotent per `(userId, announcementId, version)`.
+`POST /announcements/:id/acknowledge`, `POST /announcements/:id/impression`, and `POST /announcements/:id/click` use the same visibility rules as pending/feed (schedule, expiry, platform, min build, `audienceType`, and `matchAudience`). All three return **404** when the announcement is not visible to the caller, so targeted IDs cannot be confirmed by writing event rows. Impression and click bodies are validated with strict Zod schemas (`{ platform? }` and `{ action: "primaryAction", platform? }`); unknown keys or invalid values return **400** `Validation failed` with per-field messages in `meta.fields`. Click validates `platform` first, then checks visibility before validating `action` and the CTA. Returns **400** when `action` is not `"primaryAction"`, the announcement has no `primaryAction`, or an explicit body `platform` is not `ios` / `android` / `web` (omit `platform` to use query/user-agent resolution). Each click inserts a new row (not idempotent). Acknowledge is idempotent per `(userId, announcementId, version)`.
 
 ## Admin routes
 
@@ -104,9 +105,12 @@ Admin CRUD is on `/announcements` via `modelRouter`. Custom actions:
 
 - `GET /announcements/config` — returns `{ data: { defaultAcknowledgementPolicy } }` from the plugin constructor (admin only; defaults to `"dismiss-only"` when omitted). Used to pre-fill the admin editor acknowledgement policy field.
 - `GET /announcements/overview` — paginated admin dashboard with per-announcement metrics and aggregate totals. Access uses `adminOverviewPermissions` (defaults to `IsAdmin`). Query: `page` (default `1`), `limit` (default `20`, max `100`).
+- `POST /announcements/import-release` — idempotently imports up to 100 announcements keyed by release product/version/channel plus slug. Admin auth or the configured `uploadToken` bearer token is required. New items default to draft; request `publish: true` to publish them. The example deployment's token is `terreno-example-announcement-upload`, seeded by Terraform.
 - `POST /announcements/:id/publish` — draft → published
 - `POST /announcements/:id/archive` — published → archived
 
+See [Announcement release packs](announcement-release-packs.md) for the Markdown/frontmatter format, JSON request shape, version rules, and draft/live behavior.
+
 ### `GET /announcements/overview`
 
 Admin-only list for launch dashboards. Includes **all** lifecycle statuses (`draft`, `published`, `archived`). Soft-deleted announcements and event rows are excluded.