@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/how-to/in-app-notifications.md

@@ -0,0 +1,147 @@
+# In-app notifications
+
+Add an owner-scoped inbox, channel preferences, and optional comms fan-out to a Terreno app.
+
+## 1. Register `NotificationsApp`
+
+On your `TerrenoApp`, register the plugin and pass your user model. When you already use
+`@terreno/comms`, pass `getComms` so `notify()` can fan out to mail, SMS, and push.
+
+```typescript
+import {NotificationsApp, TerrenoApp} from "@terreno/api";
+import {CommsApp, getCommsService} from "@terreno/comms";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new NotificationsApp({
+      getComms: getCommsService,
+      retainDays: 0,
+      userModel: User,
+    })
+  )
+  .register(new CommsApp({/* providers */}))
+  .start();
+```
+
+`retainDays` defaults to `0` (keep all rows). Set a positive number to tombstone rows older
+than that many days (no Mongo TTL index).
+
+## 2. Wire comms preferences
+
+Export `notificationsBeforeSend` from `@terreno/api` and compose it into `CommsApp`
+`beforeSend`. It cancels outbound mail, SMS, or push when the user turned that channel off.
+The `verification` channel is never cancelled.
+
+```typescript
+import {notificationsBeforeSend} from "@terreno/api";
+
+new CommsApp({
+  beforeSend: async (context) => {
+    const pref = await notificationsBeforeSend({
+      channel: context.channel,
+      userId: context.userId,
+    });
+    if (pref?.cancel) {
+      return {cancel: true};
+    }
+    return undefined;
+  },
+  mail: mailProvider,
+});
+```
+
+## 3. Send notifications from server code
+
+Only the service inserts inbox rows (HTTP create is disabled).
+
+```typescript
+import {getNotificationService} from "@terreno/api";
+
+await getNotificationService().notify({
+  userId: String(user._id),
+  title: "Todo completed",
+  body: "Your task is done.",
+  href: "/todos",
+  kind: "todo",
+});
+```
+
+Fan-out order: inbox write (when `inapp` is on), then mail, SMS, and push when each
+preference is on and a destination exists. Missing email, phone, or push tokens skip that
+channel without failing `notify()`. A provider rejection on one channel is logged and
+does not skip later channels.
+
+## 4. Sync collections on the client
+
+Regenerate syncdb hooks (not RTK CRUD) for `notifications` and `notification-preferences`:
+
+```bash
+cd example-frontend
+bun run sync-sdk
+```
+
+Add the generated `SYNC_COLLECTIONS` to `createSyncDb`. Use `useQuery` / `useMutate` (or
+generated hooks) for list, mark-read (`readAt`), and dismiss (delete).
+
+## 5. Presentational UI
+
+Import the bell, inbox, and right-side drawer from `@terreno/ui`. The components take
+data and callbacks only — wire them to syncdb in your screen:
+
+```typescript
+import {NotificationBell, NotificationInbox, SideDrawer} from "@terreno/ui";
+
+<NotificationBell unreadCount={unreadCount} onPress={() => setOpen((value) => !value)} />
+<SideDrawer
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  position="right"
+  renderContent={() => (
+    <NotificationInbox
+      items={items}
+      onMarkRead={(item) => patch({id: item.id, data: {readAt: DateTime.now().toISO()}})}
+      onMarkUnread={(item) => patch({id: item.id, data: {readAt: null}})}
+      onDismiss={(item) => remove({id: item.id})}
+      onOpen={(item) => item.href?.startsWith("/") && router.push(item.href)}
+    />
+  )}
+>
+  {screen}
+</SideDrawer>
+```
+
+Customize the bell without reimplementing its tap target or unread accessibility label:
+
+```typescript
+<NotificationBell
+  unreadCount={unreadCount}
+  onPress={() => setOpen((value) => !value)}
+  renderIcon={({testID}) => <BrandBell testID={testID} />}
+  renderBadge={({testID, unreadCount}) => (
+    <BrandBubble count={unreadCount} testID={testID} />
+  )}
+/>
+```
+
+Treat dismissed rows as archived, not deleted. Dismiss PATCHes `archivedAt` through
+syncdb so the row stays in the owner snapshot with its payload. The active inbox
+filters `archivedAt` out; the full history page uses the same `useQuery("notifications")`
+and splits on `archivedAt`. Retention (`retainDays`) still tombstones old rows with
+`deleted: true`; those drop out of history after compaction. Map `archivedAt` (or a
+legacy `deleted` tombstone still in the local store) to `NotificationInboxItem.archived`.
+Archived rows remain readable but `NotificationInbox` hides their dismiss and read-state
+actions.
+
+See `example-frontend/components/NotificationCenter.tsx` and
+`example-frontend/app/notifications.tsx` for the drawer and complete history page.
+These components are not in the `@terreno/ui` component demo.
+
+The example todo router also demonstrates lifecycle-generated activity notifications:
+`postCreate` reports added todos, `postUpdate` reports a false-to-true `completed`
+transition, and `postDelete` reports deletion.
+
+## Reference
+
+- API shapes: [In-app notifications](../reference/api.md#in-app-notifications)
+- UI props: [Notification components](../reference/ui.md#notification-components)
+- Comms hook: [beforeSend composition](../reference/comms.md#notification-preferences-hook)

package/src/docs/versioned/next/how-to/install-agent-skills.md

@@ -13,15 +13,20 @@ skills.
 
 ## Install as a host plugin
 
-The combined lifecycle and Terreno app workflows ship as one host plugin. Stage names
-differ by host because Claude Code takes a plugin skill's command from the frontmatter
-`name`.
+Two plugins ship from this marketplace: the combined lifecycle and Terreno app workflows,
+and the optional goal-driven scan plugin. Stage names differ by host because Claude Code
+takes a plugin skill's command from the frontmatter `name`.
 
-| Host | Plugin | Invoke Grow |
-| --- | --- | --- |
-| Cursor | `terreno-planning` | `/terreno-1-grow` |
-| Codex | `terreno-planning` | `$terreno-1-grow` |
-| Claude Code | `terreno` | `/terreno:1-grow` |
+| Host | Plugin | Invoke Grow | Scan plugin | Invoke Aim |
+| --- | --- | --- | --- | --- |
+| Cursor | `terreno-planning` | `/terreno-1-grow` | `terreno-scan` | `/terreno-scan-1-aim` |
+| Codex | `terreno-planning` | `$terreno-1-grow` | `terreno-scan` | `$terreno-scan-1-aim` |
+| Claude Code | `terreno` | `/terreno:1-grow` | `terreno-scan` | `/terreno-scan:1-aim` |
+
+`terreno-scan` depends on the lifecycle plugin: Plot hands each slice to Grow. Its
+resident loop (`/terreno-scan:loop`, `/terreno-scan-loop`, `$terreno-scan-loop`) keeps a
+goal running and heartbeats over the PRs it opens. See the
+[scan plugin reference](../reference/scan-plugin.md).
 
 ### Cursor
 
@@ -32,6 +37,7 @@ Install `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://gith
 ```text
 codex plugin marketplace add FlourishHealth/terreno
 codex plugin install terreno-planning --source terreno-plugins
+codex plugin install terreno-scan --source terreno-plugins
 $terreno-1-grow
 ```
 
@@ -45,12 +51,15 @@ Codex installs the canonical plugin at
 ```text
 /plugin marketplace add FlourishHealth/terreno
 /plugin install terreno@terreno-plugins
+/plugin install terreno-scan@terreno-plugins
 /terreno:1-grow
 ```
 
 Marketplace: [`.claude-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.claude-plugin/marketplace.json).
 Claude Code stages, app skills, and agents come from the generated copy at
-[`plugins/terreno-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-claude).
+[`plugins/terreno-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-claude);
+scan stages come from
+[`plugins/terreno-scan-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-scan-claude).
 
 ## What you get
 
@@ -60,6 +69,7 @@ Claude Code stages, app skills, and agents come from the generated copy at
 | Terreno apps | backend, UI, admin interfaces, data, schema, SDK, prompts, upgrades, deployment |
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
 | GitHub | issues, review, UI verification, release, dependency updates |
+| Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |
 | Expo and native | `track-upstream-expo`, `upgrading-expo`, deployment / EAS skills |
 | Plugin agents | `pre-commit`, `ui-verifier` |
 
@@ -73,10 +83,12 @@ Canonical sources:
 
 1. `plugins/terreno-planning/skills/` — lifecycle and reusable Terreno app workflows
 2. `plugins/terreno-planning/agents/` — reusable verification agents
-3. `.rulesync/skills/` — repository-only and optional Expo skills (`bun run rules` generates agent copies)
-4. `<package>/.ai/skills/` — package/MCP-specific copies; not installable overlays
+3. `plugins/terreno-scan/skills/` — scan stages and the campaign loop
+4. `.rulesync/skills/` — repository-only and optional Expo skills (`bun run rules` generates agent copies)
+5. `<package>/.ai/skills/` — package/MCP-specific copies; not installable overlays
 
-`plugins/terreno-claude/` is generated from sources 1 and 2 with shortened lifecycle names.
+`plugins/terreno-claude/` is generated from sources 1 and 2, and
+`plugins/terreno-scan-claude/` from source 3, both with shortened skill names.
 Codex uses the canonical plugin plus committed `.codex-plugin/plugin.json` and
 `.agents/plugins/marketplace.json` — do not generate a third plugin tree.
 

package/src/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -21,7 +21,9 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 1. **Step A — Auth:** Move login/session to Better Auth (`generateBetterAuthSlice`, `betterAuthAdapter`, `syncDb.start()` on login). Screens can still read/write via RTK Query during this step.
 2. **Step B — Data:** For each collection, replace RTK Query hooks with syncdb hooks and delete the RTK path for that screen.
 
-The example app completed both steps; todos are syncdb-only while profile/admin still use generated RTK hooks.
+The example app completed both steps. Product Todos and eligible built-in admin
+String-`_id` model CRUD use syncdb. Profile and other non-synced routes keep
+generated RTK hooks; admin RPC uses its host-bound fetch client.
 
 **Validation (Task 3.5):** The profile screen (`example-frontend/app/(tabs)/profile.tsx`) was reviewed against this guide. `useGetMeQuery` / `usePatchMeMutation` are **non-synced** custom SDK routes — the guide §8 explicitly says to keep them on RTK. No profile migration is required; the guide is sufficient for that case.
 
@@ -348,7 +350,7 @@ It runs `@rtk-query/codegen-openapi` against `openapi-config.ts` and writes `sto
 
 | Still generated | Stop using for migrated collections |
 |-----------------|-------------------------------------|
-| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | Collection CRUD — import from `store/syncDbSdk.ts` instead |
+| Auth routes, `GET /auth/me`, AI routes, feature flags, ObjectId admin compatibility CRUD | Collection CRUD — import from `store/syncDbSdk.ts` instead |
 | Custom REST / RPC endpoints | Todo `realtimeList` / `realtimeDocument` wiring in `store/sdk.ts` |
 
 Keep running `bun run sdk` after backend route changes — non-synced screens still import from `store/sdk.ts`.
@@ -371,6 +373,20 @@ cd example-frontend && bun run sync-sdk
 
 This writes `store/syncDbSdk.ts` with friendly hooks (`useTodos`, `useCreateTodo`, …) that intentionally differ from RTK names so both SDKs can coexist during migration. Import synced screens from `@/store/syncDbSdk`, not `store/sdk.ts`.
 
+### Built-in admin
+
+For a synced String-`_id` model, set `sync.adminBroadcast: true` on its existing
+`modelRouter` sync config and inject a dedicated `createSyncDb` client with
+`windowCollections` into `AdminProvider`. REST remains the list membership,
+search, sort, pagination, and bulk-patch surface; TinyBase overlays rows and
+`useMutate` handles create/update/delete. Pass the host's `useConflicts()` result
+as `syncConflicts`.
+
+Admin RPC (config, scripts, roles, comms, consent, documents, version config,
+background tasks) uses admin-frontend's host-bound native fetch client. Do not
+add new admin `injectEndpoints`. Terreno 57 keeps `useAdminApi` and the required
+`api` prop only for ObjectId/API-only compatibility; Terreno 58 removes them.
+
 ## 9. Feature flags
 
 Post-migration, feature flags stay on `@terreno/rtk` + OpenFeature — **not** on syncdb.
@@ -453,7 +469,7 @@ Before a collection can sync:
 - [ ] `syncPlugin` on schema (`_syncSeq` stamping)
 - [ ] `modelRouter("/path", Model, {sync: {scope: ...}})` three-argument form
 - [ ] Custom scopes include `snapshotFilter`
-- [ ] `new SyncApp({getUserScopes?})` for tenant/custom scopes
+- [ ] `new SyncApp({getUserScopes?, accessControl?})` for tenant/custom scopes and admin-window `admin:access` (mount `AdminApp` too so admin `queryFilter` / resource actions apply to hydrate and `|admin` deltas)
 - [ ] `new RealtimeApp({betterAuth?})` + MongoDB replica set
 - [ ] No `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete`, or `bulkWrite` on synced models
 

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

@@ -0,0 +1,155 @@
+# Product announcements
+
+Use `@terreno/announcements` on the backend and `AnnouncementNavigator` on the frontend to show admin-managed update surfaces.
+
+## Backend
+
+1. Register the plugin on your `TerrenoApp`:
+
+```typescript
+import {AnnouncementsApp} from "@terreno/announcements";
+
+new AnnouncementsApp({
+  defaultAcknowledgementPolicy: "dismiss-only",
+  // audienceType staff/patient/all is applied inside the plugin via matchAudienceByType.
+  isStaff: (user) => (user as {admin?: boolean}).admin === true,
+  matchAudience: (user, announcement) => {
+    const audience = announcement.audience as {organizationIds?: string[]};
+    if (!audience.organizationIds?.length) {
+      return true;
+    }
+    const userOrganizationIds = (user as {organizationIds?: string[]}).organizationIds ?? [];
+    return audience.organizationIds.some((organizationId) =>
+      userOrganizationIds.includes(organizationId)
+    );
+  },
+});
+```
+
+Use admin `audienceType` for staff vs patient vs all. Reserve the `audience` JSON field for custom segments (orgs, tiers, feature cohorts) in `matchAudience`. Do **not** call `matchAudienceByType` in your app — the plugin composes it before your callback.
+
+When the admin shell uses Terreno RBAC without the legacy `user.admin` flag, pass the same read permission to the overview:
+
+```typescript
+new AnnouncementsApp({
+  adminOverviewPermissions: [access.permission({adminAnnouncement: ["read"]})],
+});
+```
+
+For Flourish-style surfaces on one collection:
+
+| Audience | Typical `displayMode` | `acknowledgementPolicy` |
+|----------|----------------------|-------------------------|
+| `staff` | `modal` (blocking) | `required` |
+| `patient` | `banner` or `feed` | `dismiss-only` |
+| `all` | any | per announcement or `defaultAcknowledgementPolicy` |
+
+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.
+
+### Admin editor fields
+
+`AnnouncementEditor` exposes structured targeting controls (no raw `requiresAcknowledgement` boolean):
+
+| Field | Control | Notes |
+|-------|---------|-------|
+| `displayMode` | Select | `modal`, `banner`, or `feed` |
+| `audienceType` | Select | `all`, `staff`, or `patient` — composed with `matchAudience` |
+| `acknowledgementPolicy` | Select | `required` or `dismiss-only`. On **create**, pre-filled from `GET /announcements/config` (`defaultAcknowledgementPolicy`); defaults to `dismiss-only` when config is unavailable |
+| `minBuildNumber` | Number (optional) | Minimum client build; cleared with `null` on edit when empty |
+| `platforms` | Multiselect | One or more of iOS, Android, and web; at least one is required |
+| `audience` | JSON textarea (advanced) | Opaque metadata for `matchAudience`; use audience type for staff/patient/all |
+
+### Admin overview
+
+`AnnouncementOverview` calls `GET /announcements/overview` (via RTK `injectEndpoints`) and shows:
+
+- Launch workflow guidance (draft → targeting → preview → publish) with a primary **Create announcement** action
+- Summary cards for published, drafts, impressions, acknowledgements, and CTA clicks
+- A paginated table with per-row metrics and an edit action
+- Optional quick links to the raw acknowledgement, impression, and click-event admin tables
+
+Register the screen through `AnnouncementsApp.adminContribution()` (`customScreens: [{ name: "announcements", displayName: "Overview", group: "Announcements" }]`) and rely on `ANNOUNCEMENTS_ADMIN_WIDGETS` from `@terreno/admin-frontend` (merged into `BUILT_IN_SCREEN_WIDGETS`). Grouped custom screens appear in the **Announcements** sidebar group before model links; ungrouped screens stay under **Screens**.
+
+`AnnouncementList` remains available for a CRUD-style list; the overview is the launch dashboard.
+
+`AnnouncementEditor` uses `MultiselectField` for platforms and requires at least one platform before save.
+
+<img alt="Announcement overview with delivery metrics" src="/img/announcements/admin-overview.png" />
+
+<img alt="Platform multiselect in the announcement editor" src="/img/announcements/admin-editor-platforms.png" />
+
+## Frontend
+
+Wrap authenticated app content:
+
+```tsx
+import {AnnouncementNavigator} from "@terreno/ui";
+
+<AnnouncementNavigator api={terrenoApi}>
+  <AppTabs />
+</AnnouncementNavigator>
+```
+
+Place it after consent/onboarding wrappers if you use `ConsentNavigator`. The navigator sends the native platform (`ios` / `android` / `web`) and, when available, the app build number from `Constants.expoConfig.extra.buildNumber` (same source as `useUpgradeCheck`) on pending and feed requests. Only pending failures block the app — changelog feed errors are non-fatal. These surfaces are not in the `@terreno/ui` component demo; wire them in the app (`example-frontend`) the same way.
+
+## Modal vs banner
+
+| `displayMode` | Navigator behavior |
+|---------------|-------------------|
+| `modal` | Renders `AnnouncementScreen` and hides children until the announcement is cleared. |
+| `banner` | Keeps children mounted and renders `AnnouncementBanner` above them (one interrupt at a time). |
+| `feed` | Changelog-only; never shown by `AnnouncementNavigator` even if it appears unexpectedly in `pending.current`. |
+
+`AnnouncementBanner` composes the existing `Banner` component: title text, a dismiss or acknowledgement action, and an optional primary-action button. When used inside `AnnouncementNavigator`, primary CTA presses call `POST /announcements/:id/click` (via `useAcknowledgeAnnouncement().recordClick`) and then open the URL; tracking failures never block navigation.
+
+Acknowledgement policy still resolves to `requiresAcknowledgement` on the public DTO:
+
+| Policy | Banner / modal behavior |
+|--------|-------------------------|
+| `required` | Primary action is **Got it**, which acknowledges through the existing handler. |
+| `dismiss-only` | Dismiss records an impression only. |
+
+Impressions are recorded once per announcement version while the modal or banner is visible.
+
+## Client frequency caps
+
+Interrupt frequency is enforced **client-side** in `AnnouncementNavigator` before a modal or banner is shown. The server still returns the full pending queue; caps never filter `useAnnouncements` feed data.
+
+```tsx
+<AnnouncementNavigator
+  api={terrenoApi}
+  frequency={{
+    cooldownHours: 24,
+    skipFirstLaunch: false,
+    userId: currentUser?.id,
+  }}
+>
+  <AppTabs />
+</AnnouncementNavigator>
+```
+
+`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so seeded interrupts still appear on first launch.
+
+| Prop | Default | Behavior |
+|------|---------|----------|
+| `maxInterruptionsPerSession` | `1` | In-memory module session counter. After the cap is reached, pending interrupts are skipped until the JS runtime reloads (cold start / full app restart). Remounting `AnnouncementNavigator` alone does **not** reset the counter. |
+| `cooldownHours` | off | When set, skips interrupts if the last shown interrupt was within this many hours. Timestamp is persisted in AsyncStorage when an interrupt becomes visible. |
+| `skipFirstLaunch` | `false` | When `true`, the first app launch ever (no `hasLaunched` key) records the flag and skips interrupts for that launch only. |
+| `userId` | `"anon"` | AsyncStorage namespace for frequency keys when a signed-in user id is available. |
+
+When a cap applies, the navigator renders children (does not block the app) and does **not** record an impression. AsyncStorage read/write failures fail open with a `console.warn` and allow the interrupt to show. If `hasLaunched` cannot be persisted on first launch, the interrupt is shown and the in-memory first-launch skip is not armed for the rest of the session.
+
+Tests call `resetFrequencySessionStateForTests()` to simulate a cold start; that helper is not part of the production API.
+
+## Media in markdown
+
+Paste YouTube or Loom URLs in the announcement `body` using markdown links or images, for example `[Watch the demo](https://www.youtube.com/watch?v=...)`. `MarkdownView` renders them as embeds (iframe on web, WebView on native). Banner surfaces show the title only; use modal mode or the feed when the full body should be visible.
+
+## Example app
+
+`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds:
+
+- **Staff modal (required)** — `audienceType: "staff"`, `displayMode: "modal"`, `acknowledgementPolicy: "required"` (`Example staff operations bulletin`)
+- **Patient banner (dismiss-only)** — `audienceType: "patient"`, `displayMode: "banner"`, `acknowledgementPolicy: "dismiss-only"` (`Example patient care tip`)
+
+The staff launch example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. Re-running the seed updates that example in place. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently so it no longer blocks the patient banner. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile); non-staff users therefore see only the patient banner interrupt under the default session cap of `1`.

package/src/docs/versioned/next/how-to/run-mongodb-migrations.md

@@ -0,0 +1,127 @@
+# Run MongoDB migrations
+
+Use `terreno-migrate` for schema and data changes that must run once per environment. Keep ad-hoc admin scripts for one-off maintenance.
+
+## Add a file
+
+Put TypeScript modules in `migrations/`:
+
+```text
+migrations/20260910120000-add-todos-index.ts
+```
+
+The exported `id` must match the filename stem. `up` is required; `down` is optional.
+
+```typescript
+export const id = "20260910120000-add-todos-index";
+
+export const up = async ({dryRun, mongoose}): Promise<void> => {
+  if (dryRun) {
+    return;
+  }
+  await mongoose.connection.collection("todos").createIndex({owner: 1});
+};
+
+export const down = async ({dryRun, mongoose}): Promise<void> => {
+  if (dryRun) {
+    return;
+  }
+  await mongoose.connection.collection("todos").dropIndex("owner_1");
+};
+```
+
+## First apply
+
+1. Generate a draft from the current models vs the last `schemaAfter` snapshot:
+   `terreno-migrate generate --dir ./migrations --models ./src/models.ts`
+2. Dry-run pending files (no history write):
+   `terreno-migrate up --dir ./migrations --dry`
+3. Apply for real:
+   `terreno-migrate up --dir ./migrations`
+4. In production, set `ALLOW_MIGRATIONS=true` and pass `--force` on that last command.
+
+If generate prints `No schema changes`, there is nothing to apply. Replace any fail-closed stub in the new file before step 2.
+
+## Commands
+
+`terreno-migrate` is the `@terreno/api` bin. `up`, `down`, and `status` need `MONGO_URI` or `MONGODB_URI`.
+
+| Command | Mongo | Effect |
+|---------|-------|--------|
+| `terreno-migrate check --dir ./migrations` | No | Load and validate files (CI) |
+| `terreno-migrate generate --dir ./migrations --models ./src/models.ts [--name slug]` | No | Diff current models vs last `schemaAfter`; write one file or print `No schema changes` |
+| `terreno-migrate status --dir ./migrations` | Yes | List applied and pending ids |
+| `terreno-migrate up --dir ./migrations [--dry] [--force]` | Yes | Apply pending `up` in filename order |
+| `terreno-migrate down --dir ./migrations [--dry] [--force] [--steps N]` | Yes | Roll back the last `N` applied files (default 1) |
+
+`--dry` calls `up`/`down` with `dryRun: true` and does **not** write `terreno_migrations` history. Authors must no-op writes when `dryRun` is true.
+
+`down` fails with `Migration has no down` when the target file omits `down`. History stays unchanged.
+
+## What generate can emit
+
+`buildSchemaCatalog` / `diffSchemaCatalog` classify model changes. `terreno-migrate generate` writes one file per non-empty diff:
+
+| Diff | Safe? | Generated `up` |
+|------|-------|----------------|
+| Add optional field | Yes | Snapshot only (Mongo is schemaless); comment, no write |
+| Add / drop non-unique index | Yes | `createIndex` / `dropIndex`, skipped when `dryRun` |
+| Add required field (no default) | No | Fail-closed stub that throws in dry-run and wet until you write a backfill |
+| Unique index | No | Fail-closed stub (valid JavaScript `throw`) |
+| Rename (removed + added field, same type) | No | Fail-closed stub |
+| Remove field | No | Fail-closed stub |
+| Same-path type change | No | Fail-closed stub |
+
+A file with any unsafe op is still a throw stub (dry-run and wet). Safe `createIndex` /
+`dropIndex` calls are kept as comments in that stub and listed in the throw message.
+
+Do not inspect the live database during generate. Baseline is the last `schemaAfter` snapshot in `migrations/`.
+
+## Admin HTTP
+
+Pass `migrations: {dir: "./migrations"}` into `AdminApp`. Both routes are
+`modelRouter` collection actions under the `adminMigrations` OpenAPI tag, so they appear in
+`/openapi.json` and in generated SDKs. Then:
+
+| Method | Path | Gate | Effect |
+|--------|------|------|--------|
+| GET | `/admin/migrations/status` | `admin:access` (or `IsAdmin`) | Applied, pending, lock (`{data: ...}`) |
+| POST | `/admin/migrations/run?wetRun=true\|false` | `admin:runScripts` (or `IsAdmin`) | `{data: {taskId}}` — one BackgroundTask (`migrations:up`) |
+| GET/DELETE | `/admin/scripts/tasks/:id` | `viewBackgroundTasks` / `runScripts` | Poll or cancel that task |
+
+Dry-run and Apply use the same `admin:runScripts` gate as Scripts (`platformTools.runScripts`
+disables the buttons when the caller cannot run scripts). Status listing stays on
+`admin:access`. Collection-action permission denials are **405** (modelRouter). Admin wet
+in production still needs `ALLOW_MIGRATIONS=true` (**403**). The admin UI is
+**Migrations** under Platform (`/admin/__migrations` or `/console/__migrations`):
+status list plus Dry run / Apply pending. Task logs poll `GET /admin/scripts/tasks/:id`.
+
+## Example app
+
+`example-backend` keeps files in `migrations/` and wires `resolveExampleMigrationsDir()` into
+`TerrenoApp` and `AdminApp`. From `example-backend/`:
+
+```bash
+bun run migrate:check
+bun run migrate:status
+bun run migrate:up
+```
+
+Compiled deploys (`bun build --compile`, Cloud Run) cannot scandir `$bunfs`. The example
+Dockerfile copies `migrations/` to `/app/migrations` and sets `MIGRATIONS_DIR`. GET
+`/admin/migrations/status` returns **404** `Migration directory not found` when that path is
+missing, not a generic 500.
+
+
+## Production wet apply
+
+`NODE_ENV=production` wet `up`/`down` requires both:
+
+1. `ALLOW_MIGRATIONS=true`
+2. `--force`
+
+Dry-run is allowed in production without those. Non-production wet apply does not need `--force`.
+
+## History and lock
+
+Applied ids live in Mongo collection `terreno_migrations` (lock row `_id: "_lock"`). Do not wipe that collection in seed `--reset`. See [Seed a database](seed-a-database.md).

package/src/docs/versioned/next/how-to/run-tests-locally.md

@@ -0,0 +1,102 @@
+# Run Terreno tests locally
+
+Every CircleCI test job has a local command. On Cursor Cloud, run the failed tests
+from the last CI run with these commands before pushing.
+
+Package unit tests use in-memory Mongo from `@terreno/test`. Playwright, Maestro, and
+the example-backend **dev** server need a replica-set `mongod` (see
+[AGENTS.md](https://github.com/FlourishHealth/terreno/blob/master/AGENTS.md) Cursor Cloud
+section).
+
+## Do now — package tests
+
+From the repo root after `bun bootstrap`:
+
+```bash
+bun run test          # every workspace `test:ci`
+bun run test:agent    # same suites; passing cases suppressed
+```
+
+Closest package during a red/green cycle:
+
+```bash
+bun test --only-failures <path>
+```
+
+| CircleCI job | Local command |
+| --- | --- |
+| `api-ci` | `bun run api:test` |
+| `ai-ci` | `cd ai && bun run test:ci` |
+| `ui-ci` | `bun run ui:test` |
+| `rtk-ci` | `bun run rtk:test` |
+| `syncdb-ci` | `bun run syncdb:test` |
+| `comms-ci` | `bun run comms:test` |
+| `jobs-ci` / jobs package | `bun run jobs:test` |
+| `mcp-server-ci` | `cd mcp-server && bun run test:ci` |
+| `create-terreno-app-ci` | `cd create-terreno-app && bun run test:ci` |
+| `packages-ci` (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) | `cd <package> && bun run test:ci` |
+| `example-backend-ci` | `cd example-backend && bun run test:ci` |
+| `example-frontend-ci` | `bun run frontend:test` |
+| `ui-demo-ci` | `cd demo && bun run test:ci` then `bun run check:demo-coverage` |
+| `new-file-coverage` | `bun run check:new-file-coverage --base=origin/master --threshold=90` |
+| `repo-policies` | `bun run prepush` (lint, compile, `analyze:full`) |
+
+Coverage gate for a published package: `cd <package> && bun run test:coverage`.
+
+## Playwright (example-frontend e2e)
+
+1. Install Chromium once: `cd example-frontend && bunx playwright install --with-deps chromium`
+2. Start a replica-set `mongod` on `127.0.0.1:27017` (Cursor Cloud steps in AGENTS.md).
+3. Re-run one failed spec (Playwright starts backend + web if they are not up):
+
+```bash
+cd example-frontend
+MONGO_URI="mongodb://127.0.0.1:27017/terreno-e2e?replicaSet=rs0" \
+  bunx playwright test e2e/<spec>.spec.ts --reporter=list
+```
+
+| CircleCI shard | Specs |
+| --- | --- |
+| `e2e` `auth` | `login` `signup` `consents` `forgot-password` `reset-password` `verify-email` |
+| `e2e` `app` | `todos` `profile` `realtime` `ai-chat` `pdf` |
+| `e2e` `admin-core` | `admin` `admin-home` `admin-form` `admin-todo-crud` `admin-title-update-depth` |
+| `e2e` `admin-table` | `admin-table-search-filter` `admin-table-bulk-actions` `admin-custom-screens` `admin-comms-back` |
+| `e2e` `syncdb` | `syncdb-load-delta` `syncdb-offline` `syncdb-conflicts` `syncdb-storage` `syncdb-chaos` |
+
+Full local suite: `bun run frontend:e2e`. Nightly load (`e2e-load` / `syncdb-loadlab`) is
+not PR-blocking; run `bunx playwright test e2e/syncdb-loadlab.spec.ts` only when that job
+failed.
+
+CircleCI skips a shard no changed file can reach. Ask for the same verdict before
+pushing with `bun run check:e2e-affected` (see
+[the affected gate](circleci.md#e2e-affected-gate)).
+
+## Admin SPA
+
+```bash
+cd admin-spa
+bun run test:ci
+bunx playwright install --with-deps chromium
+bun run test:e2e
+bun run test:integration    # needs Mongo + example-backend; job `admin-spa-integration`
+```
+
+## Maestro web e2e
+
+Install CLI if missing: `curl -fsSL "https://get.maestro.mobile.dev" | bash`, then put
+`$HOME/.maestro/bin` on `PATH`.
+
+```bash
+bun run maestro:test
+```
+
+Demo-only flows: `bun run demo:maestro:test`. Job `maestro-e2e` uses a static web export
+plus replica-set Mongo; local Maestro talks to the running example-frontend on 8082.
+
+## Taste mapping
+
+When CircleCI names a failed test, copy the file/case from the log and run the matching
+row above. Record that command in Taste `checks.ev`. Re-run it after the fix and before
+`git push`. `bun run prepush` does not replace that re-verify.
+
+Appium Android/iOS is not in CircleCI (Maestro web covers those flows).