@terreno/mcp 57.17.0 → 57.19.2

package/dist/docs/versioned/57.17.0/implementationPlans/announcements-surfaces.md

@@ -0,0 +1,231 @@
+# Announcement Surfaces, Targeting, and Click Tracking
+
+**Status:** Complete — shipped with announcements
+**Parent IP:** [announcements](announcements.md)  
+**Branch:** `cursor/announcements-grow-bf9c`  
+**Owner:** Terreno  
+**Created:** 2026-09-15  
+**Linear:** https://linear.app/flourish-health/project/product-update-announcements-in-app-944f756c05c9/overview
+
+v1 (`@terreno/announcements` + blocking `AnnouncementNavigator`) lives on this same PR. This follow-up ships on that branch — do not open a second PR.
+
+## Goal
+
+One `Announcement` collection can serve **staff** (blocking modal + required ack) and **patients** (non-blocking banner / feed-only, dismiss-only) without a second plugin. Admins pick display mode, audience type, acknowledgement policy, and optional min build. Clients cap interrupt frequency locally. Primary-action clicks are first-class analytics.
+
+**Tracer bullet:** `GET /announcements/pending?platform=&version=` → `AnnouncementNavigator` renders **banner or modal** from `displayMode` → `POST /announcements/:id/click` on primary action.
+
+## Non-Goals
+
+- Multi-locale `title` / `body`.
+- Socket push when an announcement publishes.
+- Snooze / remind-later.
+- Per-platform min builds (`{ios, android, web}`).
+- Server-enforced cooldown or cross-device frequency caps.
+- Email/push digest (`@terreno/comms` stays separate).
+- Replacing opaque `audience` JSON — `audienceType` is additive; `matchAudience` still owns custom targeting.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Q1 — Min app version | Optional `minBuildNumber` (integer, same scale as `VersionCheckPlugin`). Client sends `?version=` on pending/feed/help. Omit/`0` on the announcement = no gate. Omit `version` query = do not hide gated items. |
+| Q2 — Frequency caps | Client-only in `AnnouncementNavigator` (AsyncStorage). Plugin UI props: `maxInterruptionsPerSession` (default `1`), `cooldownHours` (default unset = off), `skipFirstLaunch` (default `false`). Server still returns the full interrupt queue. |
+| Q3 — Acknowledgement | Per-announcement `acknowledgementPolicy: "required" \| "dismiss-only"`. Drop `acknowledgementMode` and `requiresAcknowledgement`. Consumer `defaultAcknowledgementPolicy` on `AnnouncementsApp` fills omitted policy at read time and pre-fills the admin editor. |
+| Q4 — CTA clicks | New `AnnouncementClickEvent` + `POST /announcements/:id/click` with `{action: "primaryAction"}`. Do not overload impressions. |
+| Q5 — Pending queue | `GET /pending` returns only `displayMode: "modal" \| "banner"`. `feed` is changelog-only. Existing rows default `displayMode: "modal"`. |
+| Q6 — Targeting | First-class `audienceType: "staff" \| "patient" \| "all"` (default `"all"`) composed with existing `audience` + `matchAudience`. Package exports `matchAudienceByType`. |
+| Q7 — Collection | Still one Mongoose `Announcement` model / one `AnnouncementsApp`. |
+
+## Architecture
+
+```
+Announcement
+  displayMode, audienceType, acknowledgementPolicy, minBuildNumber
+  + existing lifecycle / audience / platforms / primaryAction
+
+GET  /announcements/pending?platform=&version=   → interrupt queue only (modal + banner)
+GET  /announcements/feed?platform=&version=      → changelog (all display modes)
+GET  /announcements/config                       → { defaultAcknowledgementPolicy } (admin)
+POST /announcements/:id/click                    → AnnouncementClickEvent
+POST /announcements/:id/acknowledge | impression → same visibility as pending/feed (404 if hidden)
+
+AnnouncementNavigator
+  modal  → blocks children (today)
+  banner → children stay mounted; AnnouncementBanner overlay (one at a time)
+  frequency caps applied client-side after pending fetch
+```
+
+v1 is **not published**. Replace `requiresAcknowledgement` / `acknowledgementMode` in this PR. Read-path fallback if a local doc still has the boolean: `true` → `"required"`, else `defaultAcknowledgementPolicy`.
+
+## Models
+
+### Announcement (additive + replace ack fields)
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `displayMode` | `"modal" \| "banner" \| "feed"` | `"modal"` | Pending includes `modal` and `banner` only. |
+| `audienceType` | `"staff" \| "patient" \| "all"` | `"all"` | Admin control + `matchAudienceByType`. Opaque `audience` Mixed stays. |
+| `acknowledgementPolicy` | `"required" \| "dismiss-only"` | unset | Resolve: field ?? `defaultAcknowledgementPolicy` ?? `"dismiss-only"`. |
+| `minBuildNumber` | `number` optional | unset | Hide when query `version` is a finite integer **and** `version < minBuildNumber`. |
+
+Remove schema + options field `requiresAcknowledgement` and plugin option `acknowledgementMode`. Public DTO still includes **resolved** `requiresAcknowledgement: boolean` plus `displayMode` so the navigator does not re-implement policy.
+
+Every new schema field needs a `description` (OpenAPI). Types in `announcements/src/types.ts` updated in the same commit.
+
+### AnnouncementClickEvent (new)
+
+```typescript
+{
+  userId: ObjectId;           // ref User, required, indexed
+  announcementId: ObjectId;   // ref Announcement, required, indexed
+  version: number;            // announcement version at click
+  action: "primaryAction";    // enum — only this value in this slice
+  clickedAt: Date;
+  platform?: "ios" | "android" | "web";
+}
+```
+
+Plugins: `createdUpdatedPlugin`, `isDeletedPlugin`, `findExactlyOne`, `findOneOrNone`.  
+Index: `{ announcementId: 1, clickedAt: -1 }`. Not unique.
+
+## APIs
+
+Base path unchanged (`/announcements`). Auth: user routes `IsAuthenticated`; config + click-list `IsAdmin`.
+
+| Method | Path | Change |
+|--------|------|--------|
+| GET | `/announcements/pending` | Query `platform`, `version`. Filter: visible now, platform, min build, `matchAudience`, ack/impression pending rules, **`displayMode` in `modal`/`banner`**. Sort unchanged. `{ current, remainingCount }` among interrupts only. |
+| GET | `/announcements/feed` | Same visibility + min build + audience; **all** display modes. |
+| GET | `/announcements/help/*` | Same min-build and audience filters as pending/feed visibility. |
+| GET | `/announcements/config` | Admin. `{ data: { defaultAcknowledgementPolicy } }`. |
+| POST | `/announcements/:id/click` | Body `{ action: "primaryAction", platform? }`. 404 if announcement not visible to user. 400 if no `primaryAction` or bad `action`. |
+| GET | `/announcement-click-events` | Admin list/read via modelRouter (same pattern as impressions). |
+
+**Policy resolution** (pending, feed, help, public DTO):
+
+```
+policy = announcement.acknowledgementPolicy
+  ?? options.defaultAcknowledgementPolicy
+  ?? "dismiss-only"
+requiresAcknowledgement = policy === "required"
+```
+
+Queue advancement: required → acknowledgement row; dismiss-only → impression (unchanged).
+
+**`matchAudienceByType`:**
+
+```typescript
+matchAudienceByType({
+  announcement,
+  isStaff: (user) => boolean,
+}): boolean
+// all → true; staff → isStaff(user); patient → !isStaff(user)
+```
+
+Consumers compose: `matchAudienceByType(...) && customAudienceJson(...)`.
+
+## Notifications
+
+None. Still poll/refetch on navigator mount and focus.
+
+## UI
+
+### `@terreno/ui`
+
+| Piece | Behavior |
+|-------|----------|
+| `AnnouncementPublic` | Add `displayMode`. Keep resolved `requiresAcknowledgement`. |
+| `useAnnouncements` | Send `platform` and integer `version` (Expo `Constants.expoConfig.extra.buildNumber` / same source as `useUpgradeCheck`). |
+| `AnnouncementNavigator` | If `current.displayMode === "modal"`, block children (v1). If `"banner"`, render children **and** `AnnouncementBanner`. Frequency filter runs on `current` before show. |
+| `AnnouncementBanner` | Compose existing `Banner`. Title, dismiss (or ack when required), optional primary action. Impression on show. |
+| `AnnouncementScreen` | Unchanged modal body; primary action also `POST /click`. |
+| `useAcknowledgeAnnouncement` | Add `recordClick(id)`. |
+| Frequency helper | AsyncStorage keys namespaced by user id when available, else `"anon"`. Session counter in memory. Skip first launch: if no `hasLaunched` key, set it and skip interrupts this launch. Cooldown: last interrupt timestamp. Caps apply to **interrupts only**, not the feed screen. |
+
+```tsx
+<AnnouncementNavigator
+  api={terrenoApi}
+  frequency={{
+    maxInterruptionsPerSession: 1,
+    cooldownHours: 24,
+    skipFirstLaunch: true,
+  }}
+>
+  <AppTabs />
+</AnnouncementNavigator>
+```
+
+Example app: leave `skipFirstLaunch: false` so the seeded modal still appears on first run.
+
+### `@terreno/admin-frontend`
+
+`AnnouncementEditor` / `AnnouncementList`: structured selects for `displayMode`, `audienceType`, `acknowledgementPolicy` (pre-filled from `/announcements/config`), optional `minBuildNumber`. Keep `audience` JSON as an advanced field. List columns: status, displayMode, audienceType, policy.
+
+## Phases
+
+| Phase | Scope |
+|-------|--------|
+| **1 — Backend contracts** | Schema, pending/feed/help filters, config route, click model + POST, tests |
+| **2 — Consumer UI** | Banner navigator, version query, frequency, click mutation |
+| **3 — Admin + example + docs** | Editor fields, example `matchAudienceByType` + seeds, how-to/reference |
+| **4 — Admin launch overview** | Overview API + admin dashboard UI + nav/media wiring |
+
+## Phase 4 — Admin launch overview
+
+Launch-quality admin landing for announcements: one overview screen backed by aggregate metrics instead of scanning raw event collections.
+
+| Deliverable | Scope |
+|-------------|--------|
+| **4.1 API** | `GET /announcements/overview?page=&limit=` — admin-only; rows with resolved list fields + per-announcement metrics across all event versions; global totals and status counts via aggregation; deterministic sort (`priority` desc, `publishedAt` desc); pagination `{ data, totals, page, limit, total, more }`; OpenAPI for SDK |
+| **4.2 UI** | `@terreno/admin-frontend` overview screen consuming overview hook; summary cards from `totals`; table from `data` with metrics columns |
+| **4.3 Nav/media** | Grouped Announcements sidebar (overview + audit models), example route, platform multiselect, and rich launch seed with YouTube/screenshots |
+
+Task checklist: **`docs/tasks/announcements-surfaces.md`** (Phase 4).
+
+## Feature Flags & Migrations
+
+- Opt-in remains `AnnouncementsApp` registration.
+- No production backfill: package unreleased. Schema defaults cover new fields. Read-path maps leftover `requiresAcknowledgement` boolean.
+- Click collection is new. Admin `listFields` / `queryFields` updated for new announcement columns.
+
+## Activity Log & User Updates
+
+No activity-log integration. Admins list click events like impressions.
+
+## Not Included / Future Work
+
+- Localization, sockets, snooze, comms digest.
+- Per-platform `minBuildNumber`.
+- Server-side / cross-device frequency.
+- Additional `action` enum values beyond `primaryAction`.
+
+## Files to Create / Modify
+
+| Area | Files |
+|------|--------|
+| Models / types | `announcements/src/models/announcement.ts`, `announcementClickEvent.ts`, `announcements/src/types.ts`, `pending.ts` |
+| Plugin | `announcements/src/announcementsApp.ts`, `help.ts`, tests under `announcements/src/tests/` |
+| UI | `ui/src/AnnouncementBanner.tsx`, `AnnouncementNavigator.tsx`, `AnnouncementScreen.tsx`, `useAnnouncements.ts`, `useAcknowledgeAnnouncement.ts`, `announcementFrequency.ts` (+ tests) |
+| Admin | `admin-frontend/src/AnnouncementEditor.tsx`, `AnnouncementList.tsx` (+ tests) |
+| Example | `example-backend/src/server.ts`, seed scripts, `example-frontend` navigator props |
+| Docs | `docs/reference/announcements.md`, `docs/how-to/product-announcements.md`, this IP, parent IP pointer |
+| Knip | `knip.jsonc` only if a new entry file is not already reachable |
+
+## Task List
+
+Executable checklist: **`docs/tasks/announcements-surfaces.md`**.
+
+## Acceptance Criteria
+
+- [x] Pending never returns `displayMode: "feed"`. Feed still lists feed-only items.
+- [x] `minBuildNumber` hides the item from pending/feed/help when `version` is present and lower; omitted `version` does not hide.
+- [x] `acknowledgementPolicy` + `defaultAcknowledgementPolicy` resolve to public `requiresAcknowledgement`; `acknowledgementMode` is gone.
+- [x] `audienceType` is stored and honored by `matchAudienceByType`; example-backend uses `user.admin` as staff.
+- [x] Navigator: modal blocks; banner does not; frequency caps skip extra interrupts this session / cooldown / first launch.
+- [x] Primary action records `AnnouncementClickEvent` via `POST /announcements/:id/click`.
+- [x] Admin editor exposes display mode, audience type, policy, min build without requiring raw JSON for those fields.
+- [x] Admin overview shows launch guidance, aggregate totals, and per-announcement impressions, acknowledgements, and CTA clicks.
+- [x] Announcement admin routes share one Announcements sidebar group; the editor uses a platform multiselect.
+- [x] Example staff launch content renders markdown with a YouTube embed, feature screenshots, and tracked CTA.
+- [x] Reference + how-to match shipped behavior in the same slice. New files ≥90% coverage. `bun run announcements:test`, `ui` announcement tests, `admin-frontend` editor tests, `bun run lint`, `bun run compile`, `bun run analyze:full` pass.

package/dist/docs/versioned/57.17.0/implementationPlans/announcements.md

@@ -0,0 +1,290 @@
+# Product Update Announcements — In-App Core Feature
+
+**Status:** Complete — shipped with @terreno/announcements (57.6.x)
+**Roadmap:** Area=`api`, Target=`Released`, Impact=`Feature`  
+**Branch:** `cursor/announcements-grow-bf9c`  
+**Owner:** Terreno  
+**Created:** 2026-09-08  
+**Linear:** https://linear.app/flourish-health/project/product-update-announcements-in-app-944f756c05c9/overview
+
+**Follow-up (same PR):** [Announcement surfaces, targeting, and click tracking](announcements-surfaces.md) — display modes, `audienceType`, acknowledgement policy, client frequency caps, min build, CTA clicks. That IP overrides the v1 non-goals “no role targeting built into Terreno” and “no CTA tracking” for the slice listed there.
+
+## Goal
+
+Ship a **core Terreno feature** for admin-managed, in-app product update announcements — similar in scope to feature flags and consent forms. Admins create markdown announcements with scheduling, targeting metadata, and lifecycle controls. Authenticated users see a **priority-ordered modal queue** (one at a time) and can browse a **changelog feed**. Consumers (e.g. Flourish) configure audience matching and acknowledgement policy without forking the package.
+
+**Tracer bullet (v1 proof):** `GET /announcements/pending` → `AnnouncementNavigator` → `POST /announcements/:id/acknowledge`.
+
+## Non-Goals
+
+- Image upload / Terreno CDN hosting (v1 is **URL-only** markdown for images and video links).
+- Multi-locale content maps (v1 is single `title` + `body`).
+- Real-time socket push when announcements publish (poll/refetch on focus for v1).
+- Snooze / remind-later UX.
+- Role-based targeting built into Terreno (consumers supply `matchAudience` callback).
+- Replacing email/push comms (`@terreno/comms` remains separate).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Q1 — Package placement | New workspace package **`@terreno/announcements`** (plugin pattern like `@terreno/feature-flags`). |
+| Q2 — Consumer UI | Ship **`AnnouncementNavigator`** + **`AnnouncementScreen`** in **`@terreno/ui`** (mirror `ConsentNavigator`). |
+| Q3 — Targeting | `audience: Mixed` on `Announcement` + consumer **`matchAudience(user, announcement)`** callback. |
+| Q4 — Acknowledgement | **Superseded** by [announcements-surfaces.md](announcements-surfaces.md): per-announcement **`acknowledgementPolicy`** (`required` \| `dismiss-only`) + consumer **`defaultAcknowledgementPolicy`** (default `dismiss-only`). Legacy v1 `requiresAcknowledgement` / `acknowledgementMode` are removed. |
+| Q5 — Lifecycle | **`draft` → `published` → `archived`**; priority queue; **one modal at a time**. |
+| Q6 — Media (defaults) | **URL-only markdown** in v1 — no upload/CDN pipeline. |
+| Q7 — Re-show on edit (defaults) | **Auto `version` bump** when a **published** announcement's `title` or `body` changes; acknowledgements are per `(userId, announcementId, version)`. |
+| Q8 — Localization (defaults) | **Single `title` + `body`** strings in v1 (no locale map). |
+| Q9 — Admin UX | **Custom manager screen** with live markdown preview + publish/archive actions (like `ConsentFormEditor`), not generic CRUD only. |
+| Q10 — v1 extras | **`publishAt`**, **`expiresAt`**, **`platforms`**, **`primaryAction`**, **impression tracking**, **changelog feed** (`GET /announcements/feed`). |
+
+## Architecture
+
+```
+@terreno/announcements (TerrenoPlugin)
+  ├─ Announcement model (admin CRUD via modelRouter + adminContribution)
+  ├─ AnnouncementAcknowledgement model
+  ├─ AnnouncementImpression model
+  ├─ GET  /announcements/pending   → modal queue for current user
+  ├─ GET  /announcements/feed      → published changelog (paginated)
+  ├─ POST /announcements/:id/acknowledge
+  └─ POST /announcements/:id/impression
+
+@terreno/ui
+  ├─ AnnouncementNavigator (blocks children while queue non-empty)
+  ├─ AnnouncementScreen (markdown body, primary action, acknowledge/dismiss)
+  ├─ useAnnouncements / useAcknowledgeAnnouncement (RTK inject pattern)
+  └─ MarkdownView enhancement (YouTube + Loom embeds)
+
+@terreno/admin-frontend
+  ├─ AnnouncementEditor (MarkdownEditor + preview + publish)
+  └─ AnnouncementList
+
+Consumer app (example-frontend, later Flourish)
+  └─ AnnouncementsApp({ isStaff, defaultAcknowledgementPolicy, matchAudience })
+       + <AnnouncementNavigator api={terrenoApi} frequency={{ skipFirstLaunch: false, userId }} />
+```
+
+Mirror existing patterns:
+
+| Concern | Reference |
+|---------|-----------|
+| Plugin package | `feature-flags/src/featureFlagsApp.ts` |
+| User-blocking navigator | `ui/src/ConsentNavigator.tsx` |
+| Admin custom editor | `admin-frontend/src/ConsentFormEditor.tsx` |
+| Markdown admin widget | `admin-frontend/src/widgets/builtInFieldWidgets.tsx` (`widget: "markdown"`) |
+| RTK hook injection | `rtk/src/useTerrenoFeatureFlags.ts` |
+
+## Models
+
+### Announcement
+
+Admin-managed product update definition.
+
+```typescript
+{
+  title: string;                    // required, trim
+  body: string;                     // required, markdown
+  status: "draft" | "published" | "archived";
+  version: number;                  // default 1; auto-increment on published title/body edit
+  priority: number;                 // higher = shown first in modal queue; default 0
+  acknowledgementPolicy: "required" | "dismiss-only"; // per-announcement; see announcements-surfaces.md
+  audience: Mixed;                  // opaque JSON for consumer matchAudience (roles, segments, etc.)
+  publishAt?: Date;                 // optional scheduled publish (null = immediate when published)
+  expiresAt?: Date;                 // optional; excluded from pending/feed after expiry
+  platforms: ("ios" | "android" | "web")[]; // default all three
+  primaryAction?: {
+    label: string;
+    url: string;                    // deep link or external URL
+  };
+  publishedAt?: Date;               // set when status becomes published
+  archivedAt?: Date;
+}
+```
+
+Indexes: `{ status: 1, publishAt: 1 }`, `{ status: 1, priority: -1, publishedAt: -1 }`.
+
+Plugins: `createdUpdatedPlugin`, `isDeletedPlugin`, `findExactlyOne`, `findOneOrNone`.
+
+**Pre-save hook:** When `status === "published"` and `title` or `body` changes vs previous document, increment `version` (forces re-ack for users who only acknowledged the prior version).
+
+### AnnouncementAcknowledgement
+
+```typescript
+{
+  userId: ObjectId;           // ref User, required, indexed
+  announcementId: ObjectId;   // ref Announcement, required, indexed
+  version: number;            // announcement version at acknowledge time
+  acknowledgedAt: Date;
+}
+```
+
+Compound unique index: `{ userId: 1, announcementId: 1, version: 1 }`.
+
+### AnnouncementImpression
+
+```typescript
+{
+  userId: ObjectId;
+  announcementId: ObjectId;
+  version: number;
+  viewedAt: Date;
+  platform?: "ios" | "android" | "web";
+}
+```
+
+Index: `{ announcementId: 1, viewedAt: -1 }` (admin analytics). Not unique — one row per view event is acceptable for v1.
+
+## APIs
+
+Base path configurable (default **`/announcements`**). All routes behind `authenticateMiddleware()`.
+
+### Admin routes (IsAdmin) — via modelRouter + custom actions
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET/POST/PATCH/DELETE | `/announcements` | CRUD on `Announcement` |
+| POST | `/announcements/:id/publish` | `draft` → `published`; sets `publishedAt`; validates `publishAt` ≤ now unless scheduling |
+| POST | `/announcements/:id/archive` | `published` → `archived`; sets `archivedAt` |
+| GET | `/announcement-acknowledgements` | List acks (admin read) |
+| GET | `/announcement-impressions` | List impressions (admin read) |
+
+### User routes (IsAuthenticated)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/announcements/pending` | Modal queue: published, in window (`publishAt` ≤ now, `expiresAt` null or > now), platform match, `matchAudience` pass, not acknowledged at current `version` (when ack required). Sorted by `priority` desc, then `publishedAt` desc. Returns **at most one** “current” item plus `remainingCount` for UI hint. |
+| GET | `/announcements/feed` | Paginated published changelog (same filters except acknowledgement). Query: `limit`, `page` / cursor. |
+| POST | `/announcements/:id/acknowledge` | Create `AnnouncementAcknowledgement` for current version. Idempotent per version. |
+| POST | `/announcements/:id/impression` | Record view when modal opens or feed item becomes visible. Body optional `{ platform }`. |
+
+### Plugin constructor
+
+```typescript
+interface AnnouncementsOptions {
+  basePath?: string;  // default "/announcements"
+  defaultAcknowledgementPolicy?: "required" | "dismiss-only";  // default "dismiss-only"
+  isStaff?: (user: User) => boolean;  // default user.admin === true
+  matchAudience?: (
+    user: User,
+    announcement: AnnouncementDocument
+  ) => boolean | Promise<boolean>;
+  permissions?: Partial<ModelRouterPermissions>;       // override IsAdmin defaults
+}
+
+class AnnouncementsApp implements TerrenoPlugin {
+  constructor(options?: AnnouncementsOptions);
+  register(app: express.Application, openApi?: unknown): void;
+  adminContribution(): AdminContribution;
+}
+```
+
+**Acknowledgement resolution:** per-announcement `acknowledgementPolicy` with consumer `defaultAcknowledgementPolicy`. Legacy `requiresAcknowledgement: true` maps to `"required"` on read. See [announcements-surfaces.md](announcements-surfaces.md) and `docs/reference/announcements.md`.
+
+## Notifications
+
+None in v1. Queue is fetched on app launch / navigator mount and on RTK refetch (window focus). No push/email integration.
+
+## UI
+
+### `@terreno/ui`
+
+| Component | Description |
+|-----------|-------------|
+| `AnnouncementNavigator` | Wraps app content. Fetches `GET /announcements/pending`. While queue non-empty, renders `AnnouncementScreen` for current item. On acknowledge/dismiss, advances or refetches. Auth errors pass through to children (same as `ConsentNavigator`). |
+| `AnnouncementScreen` | Title, scrollable `MarkdownView` body, optional `primaryAction` link button, acknowledge button (when required) or dismiss. Records impression on mount. |
+| `useAnnouncements` | RTK-injected query for pending + feed. |
+| `useAcknowledgeAnnouncement` | RTK mutation; invalidates pending cache. |
+| `MarkdownView` (enhancement) | Custom link/image renderer: YouTube and Loom URLs render as embedded players (web: iframe; native: WebView or platform-appropriate embed). Plain image URLs continue to render as images. |
+
+### `@terreno/admin-frontend`
+
+| Component | Description |
+|-----------|-------------|
+| `AnnouncementEditor` | Create/edit: title, body (`MarkdownEditor`), priority, `displayMode`, `audienceType`, `acknowledgementPolicy` (pre-filled from config), optional `minBuildNumber`, advanced `audience` JSON, publishAt/expiresAt, platforms multi-select, primaryAction fields. Live preview pane. Actions: Save draft, Publish, Archive. |
+| `AnnouncementList` | Table: title, status, displayMode, audienceType, acknowledgement policy, priority, version, publishedAt, expiresAt. Row → editor. |
+
+Register via `AnnouncementsApp.adminContribution()` with custom routes pointing at these screens (same pattern as consent admin overrides).
+
+### Client integration
+
+```typescript
+import {AnnouncementNavigator} from "@terreno/ui";
+import {AnnouncementsApp} from "@terreno/announcements";
+
+// server.ts
+new TerrenoApp({ userModel: User })
+  .register(new AnnouncementsApp({
+    defaultAcknowledgementPolicy: "dismiss-only",
+    isStaff: (user) => user.admin === true,
+    matchAudience: (user, a) => mySegmentMatcher(user, a.audience),
+  }))
+  .start();
+
+// _layout.tsx (after auth)
+<AnnouncementNavigator api={terrenoApi}>
+  <AppTabs />
+</AnnouncementNavigator>
+```
+
+## Phases
+
+| Phase | Scope | Deliverable |
+|-------|--------|-------------|
+| **1 — Package + API** | Models, `AnnouncementsApp`, pending/feed/ack/impression routes, version bump hook, unit tests | `@terreno/announcements` backend complete |
+| **2 — Markdown embeds** | YouTube/Loom embed rules in `MarkdownView` + tests | Rich media in announcement body |
+| **3 — Consumer UI** | `AnnouncementNavigator`, `AnnouncementScreen`, hooks, tests | `@terreno/ui` integration |
+| **4 — Admin UI** | `AnnouncementEditor`, `AnnouncementList`, adminContribution wiring | Admins manage announcements |
+| **5 — Example + docs** | example-backend/frontend, SDK regen, reference/how-to docs | End-to-end demo |
+
+Phases 2 and 3 can run in parallel after Phase 1. Phase 4 can start after Phase 1 (admin does not require navigator).
+
+## Feature Flags & Migrations
+
+- **Feature flags:** None. Opt-in via `AnnouncementsApp` registration.
+- **Migrations:** New collections only. No changes to existing schemas.
+- **Workspace:** Add `announcements/` to root `package.json` workspaces; publish as `@terreno/announcements`.
+
+## Activity Log & User Updates
+
+No Terreno activity-log integration in v1. `AnnouncementAcknowledgement` and `AnnouncementImpression` provide audit/analytics for admins.
+
+## Not Included / Future Work
+
+Surfaces, `audienceType`, per-announcement acknowledgement policy, frequency caps, min build, and CTA click tracking are specified in **[announcements-surfaces.md](announcements-surfaces.md)** (same PR). Remaining later:
+
+- Terreno media upload / CDN for inline images.
+- Multi-locale `title` / `body` maps.
+- Socket live push when announcements publish.
+- Snooze / remind-later.
+- A/B variants of announcement content.
+- Email digest of changelog.
+
+## Files to Create / Modify
+
+| Area | Files |
+|------|--------|
+| New package | `announcements/package.json`, `announcements/src/announcementsApp.ts`, `announcements/src/models/*.ts`, `announcements/src/index.ts`, tests |
+| UI | `ui/src/AnnouncementNavigator.tsx`, `ui/src/AnnouncementScreen.tsx`, `ui/src/useAnnouncements.ts`, `ui/src/MarkdownView.tsx` (embed rules) |
+| Admin | `admin-frontend/src/AnnouncementEditor.tsx`, `admin-frontend/src/AnnouncementList.tsx` |
+| Example | `example-backend/src/server.ts`, `example-frontend/app/_layout.tsx`, SDK regen |
+| Docs | `docs/reference/announcements.md`, `docs/how-to/product-announcements.md` |
+| Root | `package.json` workspaces, root scripts (`announcements:compile`, `announcements:test`) |
+
+## Task List
+
+Executable checklist: **`docs/tasks/announcements.md`**.
+
+## Acceptance Criteria
+
+- [ ] `@terreno/announcements` registers as `TerrenoPlugin` with `adminContribution()`.
+- [ ] Admin can create draft, publish, and archive announcements via custom editor.
+- [ ] Published `title`/`body` edit bumps `version`; users with old ack see announcement again when ack required.
+- [ ] `GET /announcements/pending` respects `matchAudience`, `platforms`, schedule window, and acknowledgement state.
+- [ ] `AnnouncementNavigator` shows one modal at a time; children render when queue empty.
+- [ ] YouTube and Loom links in markdown render as embeds (web verified).
+- [ ] `GET /announcements/feed` returns paginated changelog for in-app “What’s new”.
+- [ ] Impression and acknowledgement records persist for admin list views.
+- [ ] Example app demonstrates full flow end-to-end.
+- [ ] Reference and how-to docs updated in same slice as implementation.