@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/how-to/password-reset.md

@@ -20,6 +20,8 @@ Set `publicAppUrl` and `sendMail`. Forgot-password always returns 202.
 ```typescript
 authOptions: {
   publicAppUrl: process.env.FRONTEND_URL || "http://localhost:8082",
+  // Set false if the host already owns POST /resetPassword.
+  legacyResetPasswordRoute: false,
   sendMail: async (message) => {
     await getCommsService().sendMail(message);
   },
@@ -34,6 +36,11 @@ authOptions: {
 | Send verify | `POST /auth/sendVerification` | authenticated → 202 after delivery; 501 if `publicAppUrl` is missing |
 | Verify | `POST /auth/verifyEmail` | `{token}` |
 
+Recovery routes default on for compatibility. Set `authOptions.passwordReset: false` to omit
+both password-reset routes and forgot-password. Set `authOptions.emailVerification: false` to
+omit both verification routes. Set `authOptions.legacyResetPasswordRoute: false` when the host
+owns `POST /resetPassword`; `POST /auth/resetPassword` remains registered.
+
 Reset links: `${publicAppUrl}/resetPassword?token=...`. Verify links: `${publicAppUrl}/verifyEmail?token=...`.
 
 Set `requireEmailVerification: true` to return 403 `email-not-verified` on JWT login until verify succeeds. Signup still returns JWTs and sends the verify mail.

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/TerrenoLabs/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).

package/src/docs/versioned/next/how-to/seed-a-database.md

@@ -71,6 +71,10 @@ of inserting a duplicate. If more than one document already shares the key,
 the survivor. Use `context.deleteMany()` only inside reset handlers.
 Custom writes must check `context.dryRun` themselves.
 
+The example backend seeds active, read, and archived notification rows for the default
+test user. This keeps the notification drawer and full history page populated for local
+development and browser tests.
+
 For Better Auth credentials, call `seedBetterAuthUser({auth, user, userModel})`.
 It creates a missing credential account, signs in when the account already
 exists, and reconciles the application user document.
@@ -84,5 +88,6 @@ are true:
 2. `allowProductionReset` returns `true` (normally from a dedicated environment variable).
 
 Reset handlers should delete only records owned by the seed plan. Preserve
-authentication, migration history, and operator-created data unless the plan
-explicitly manages them.
+authentication, migration history (`terreno_migrations`), and operator-created
+data unless the plan explicitly manages them. Do not `dropDatabase` or delete
+the history collection in seed `--reset`.

package/src/docs/versioned/next/how-to/set-up-terreno-mcp.md

@@ -0,0 +1,69 @@
+# Set up Terreno MCP
+
+Configure both Terreno servers: the hosted server supplies documentation and generators; the local
+stdio server inspects the app, database, logs, Metro, and Redux state.
+
+Install Bun 1.4 or newer to enable the local server's built-in WebView browser automation.
+
+## Cursor
+
+Add `.cursor/mcp.json` at the app repository root:
+
+```json
+{
+  "mcpServers": {
+    "terreno": {
+      "type": "http",
+      "url": "https://mcp.terreno.flourish.health/mcp"
+    },
+    "terreno-local": {
+      "command": "bunx",
+      "args": ["terreno-mcp-local"]
+    }
+  }
+}
+```
+
+## Claude Code
+
+Use the same project-scoped `.mcp.json`, or register the servers from the repository root:
+
+```bash
+claude mcp add --transport http terreno https://mcp.terreno.flourish.health/mcp
+claude mcp add terreno-local -- bunx terreno-mcp-local
+```
+
+## Configure local discovery
+
+Run the local server from the app root. It discovers bootstrap apps with `backend/` and `frontend/`,
+and this monorepo's `example-backend/` logs. Set these variables only when discovery needs help:
+
+| Variable | Use |
+| --- | --- |
+| `TERRENO_PROJECT_ROOT` | Absolute app/monorepo root |
+| `TERRENO_METRO_URL` | Metro origin when the frontend script does not expose `--port` |
+| `MONGO_URI` | MongoDB used by `database_schema` and read-only `database_query` |
+| `TERRENO_MCP_EVAL=1` | Explicitly enable `evaluate`, `navigate`, and SyncDB state changes |
+| `BUN_CHROME_PATH` | Chrome/Chromium/Edge binary when Bun cannot auto-discover one |
+
+Backend and browser JSONL normally live under `<backend cwd>/.terreno/logs/`. Keep Metro running to
+collect Metro `/events` and app console output over CDP. Hermes accepts one debugger connection, so
+close React Native DevTools if the local MCP reports that CDP is unavailable.
+
+## Verify
+
+Restart the editor's MCP clients, then ask it to call `application_info`. Confirm the result lists
+the app's installed `@terreno/*` versions. Next call `read_logs` with
+`{"sources":["backend","browser"]}`; an empty `entries` array is valid before the app logs anything.
+Call `browser` with `{"action":"open","url":"http://localhost:8082"}`, then `{"action":"snapshot"}`
+to confirm the agent can inspect the running web app. Finish with `{"action":"close"}`.
+If the app creates a SyncDB client with `debug: true`, call
+`get_syncdb_state` and confirm it returns the client name, status, collections,
+outbox, conflicts, cursors, and debug events.
+
+The CLI exposes the same local tools without MCP:
+
+```bash
+terreno info
+terreno logs --sources backend,browser
+```

package/src/docs/versioned/next/how-to/upgrade-terreno.md

@@ -10,7 +10,7 @@ From the app root:
 bun pm ls --all | rg '@terreno/'
 ```
 
-Or call MCP `application_info` (`terreno-mcp-local`) and read each `package.json`. Record the lowest `@terreno/*` version as `fromVersion` and the target as `toVersion` (usually the latest tag on [GitHub Releases](https://github.com/FlourishHealth/terreno/releases)).
+Or call MCP `application_info` (`terreno-mcp-local`) and read each `package.json`. Record the lowest `@terreno/*` version as `fromVersion` and the target as `toVersion` (usually the latest tag on [GitHub Releases](https://github.com/TerrenoLabs/terreno/releases)).
 
 ## 2. Fetch notes for the range
 

package/src/docs/versioned/next/implementationPlans/ModularAPI.md

@@ -1,6 +1,6 @@
 # Modular API Implementation Plan
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1084  
 **Status:** Complete
 
 ## Overview

package/src/docs/versioned/next/implementationPlans/README.md

@@ -40,16 +40,19 @@ The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline.
 
 **Grow** interviews in grilling rounds (one frontier of decisions per message, recommended
 answers, then wait). It stays on a question until the answer is executable. After the user
-confirms shared understanding it writes the two files and ends with a **15-line verify
-index** (destination, in/out, tracer, task graph, test seam). When grilling produced
-human decisions, it lists **every** one in a Decisions table with no row cap. If there
-were none, that table is omitted.
+confirms shared understanding it writes the two files and ends with a **standalone
+approval brief**: an orientation paragraph on where the repository is and where the change
+takes it, optional background on current state, the idea, then the plan (tasks, tracer,
+verification, risks). When grilling produced human decisions, a Decisions table with no
+row cap follows the plan, pairing each settled choice with the question that prompted it.
+If there were none, that table is omitted. The brief must stand on its own — a reviewer
+should not need the IP, the ticket, or the interview history to approve it.
 
 For a small feature, the plugin's **feature profile** uses a compact approved task
 contract: invoke Pick once; it implements one frontier task, roasts it, then picks the
 next until the list is done, then Brew and bounded Taste iterations.
 
-1. **Grow** (`terreno-1-grow`) — grill until answers are executable, then write the IP + tracer-bullet task list; end with the 15-line verify index and a full Decisions table when any exist.
+1. **Grow** (`terreno-1-grow`) — grill until answers are executable, then write the IP + tracer-bullet task list; end with the standalone approval brief (summary, background, idea, plan) and a full Decisions table when any exist.
 2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD, then continue the pick-roast inner loop.
 3. **Roast** (`terreno-3-roast`) — independently verify the current task, then return (`next: pick` or `next: brew`).
 4. **Brew** (`terreno-4-brew`) — commit, push, open the PR after every in-scope task has Roast `PASS`.

package/src/docs/versioned/next/implementationPlans/admin-improvements.md

@@ -4,7 +4,7 @@
 **Branch:** (implementation TBD)  
 **Owner:** Josh Gachnang  
 **Created:** 2026-06-01 (original); revised 2026-08-20 post–v2 gap analysis  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1099  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1099  
 **Prerequisite:** [Admin UI v2 — Django-parity admin](./admin-ui-v2-django-parity.md) (**Complete**)  
 **Research:** [admin-improvements-research.md](./admin-improvements-research.md)
 ## Goal

package/src/docs/versioned/next/implementationPlans/admin-only-research.md

@@ -2,7 +2,7 @@
 
 **Status:** Complete
 **Closed:** 2026-08-20 — Research incorporated into [admin-only.md](admin-only.md); shipped as `@terreno/admin-spa`.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1075
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1075
 
 ## Summary
 

package/src/docs/versioned/next/implementationPlans/admin-only.md

@@ -2,7 +2,7 @@
 
 **Status:** Complete
 **Closed:** 2026-08-20 — Shipped as `@terreno/admin-spa` (`AdminSpaServeApp`, pre-built Expo web export, Better Auth same-origin). See `admin-spa/` and `admin-only-research.md`.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1075
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1075
 **Branch:** `admin-only`
 **Owner:** Josh Gachnang
 **Created:** 2026-05-11

package/src/docs/versioned/next/implementationPlans/admin-script-runner.md

@@ -1,7 +1,7 @@
 # Admin Script Runner — Maintenance Scripts via `AdminApp`
 
 **Status:** Implemented (ships with Admin UI v2 work; documented here as its own IP)  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1077
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1077
 **Related:** [`admin-ui-v2-django-parity.md`](./admin-ui-v2-django-parity.md) (home `scriptRunner` widget, background-task patterns)  
 **Primary packages:** `@terreno/api` (`BackgroundTask`, script types), `@terreno/admin-backend`, `@terreno/admin-frontend`, `admin-spa`, `example-backend`
 

package/src/docs/versioned/next/implementationPlans/admin-scripts-durable-jobs.md

@@ -0,0 +1,44 @@
+# Implementation Plan: Admin scripts via durable jobs
+
+**Status:** Approved (operator) — 2026-09-14
+**Branch:** `cursor/scripts-via-durable-jobs-803d`
+**Task list:** [admin-scripts-durable-jobs.md](../tasks/admin-scripts-durable-jobs.md)
+**Depends on:** [job-queues.md](job-queues.md)
+
+## Goal
+
+Admin HTTP script runs (`POST /admin/scripts/:name/run`) enqueue `@terreno/jobs` job
+`admin/script` when `JobsApp` is registered, while the Scripts UI keeps polling
+`BackgroundTask` by `taskId`.
+
+## Non-Goals
+
+- Deleting `BackgroundTask` or merging Scripts and Jobs screens
+- Routing `runScriptCli` through the queue
+- Executing `POST /admin/background-tasks` kinds
+- Moving comms/webhooks/billing onto jobs
+- Requiring scripts to be idempotent (use `maxAttempts: 1`)
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Job name | `admin/script` |
+| Payload | `{scriptName, taskId, wetRun, args, createdByName?}` |
+| Retry | `maxAttempts: 1` |
+| UI | Unchanged poll/cancel on `BackgroundTask` |
+| Fallback | No `JobsApp` → existing in-process runner |
+| Worker | Same script catalog via `defineAdminScriptJob` |
+| Cloud Tasks | Inherited from `JobsApp` runner; execute process must load scripts |
+| GCP topology | Infra Manager queue pushes OIDC callbacks to a private Cloud Run tasks service |
+| Execution pool | Cloud Tasks rate limits + Cloud Run service instances; not Cloud Run worker pools (no HTTP ingress) |
+| PR isolation | Shared queue, per-PR tasks-service tag callback, and per-PR Mongo database |
+
+## Acceptance
+
+- With `JobsApp` + worker, run creates a `Job` and completes the `BackgroundTask`
+- Without `JobsApp`, existing admin-backend script tests still pass
+- Cancel marks `BackgroundTask` cancelled and cancels the job when present
+- Example worker defines `admin/script`
+- Deployed example backend selects `GcpCloudTasksRunner` and rejects unverified callbacks
+- Concurrent PR previews target only their matching tasks-service tag and database

package/src/docs/versioned/next/implementationPlans/admin-ui-v2-django-parity.md

@@ -1,7 +1,7 @@
 # Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
 
 **Status:** Implemented (phased tasks complete; acceptance criteria verified in-repo)  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1076
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1076
 **Branch:** Landed via `cursor/admin-ui-v2-backend-a736` (PR #782)  
 **Owner:** Josh Gachnang  
 **Created:** 2026-06-15