@terreno/mcp 57.2.0 → 57.4.0

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

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

@@ -0,0 +1,93 @@
+# Seed a database
+
+Use `runSeedCli` to keep development and test data aligned with code. Seed plans
+sync by default, can preview writes, and can reset only the data each step owns.
+
+## Define a seed plan
+
+```typescript
+import {runSeedCli, type SeedStep} from "@terreno/api";
+import mongoose from "mongoose";
+import {Todo} from "../models/todo";
+import {connectToMongoDB} from "../utils/database";
+
+const steps: SeedStep[] = [
+  {
+    name: "todos",
+    reset: async (context) => {
+      await context.deleteMany(Todo);
+    },
+    run: async (context) => {
+      await context.upsert(
+        Todo,
+        {seedKey: "welcome"},
+        {seedKey: "welcome", title: "Welcome to the app"}
+      );
+    },
+  },
+];
+
+const result = await runSeedCli({
+  allowProductionReset: () => process.env.ALLOW_SEED_RESET === "true",
+  connect: connectToMongoDB,
+  disconnect: async () => mongoose.disconnect(),
+  name: "bun run seed",
+  steps,
+});
+
+process.exit(result.exitCode);
+```
+
+Add the package command:
+
+```json
+{"scripts": {"seed": "bun run src/scripts/seed.ts"}}
+```
+
+## Run seeds
+
+```bash
+bun run seed                         # create or update code-defined data
+bun run seed --dry-run               # preview without writes
+bun run seed --only todos            # one step and its dependencies
+bun run seed --reset                 # reset managed data, then reseed
+```
+
+`--only` may be repeated. Declare `dependsOn` when one step needs records from
+another; dependencies run first. In reset mode, reset handlers run in reverse
+order so dependent records are removed before their parents.
+
+## Make sync runs idempotent
+
+Use `context.upsert(model, key, values)` with a stable, unique business key.
+The helper reports `created`, `updated`, or `unchanged` and writes only when the
+declared values differ. Nested arrays are compared without generated subdocument
+`_id`s, so feature-flag rules and similar payloads stay unchanged across syncs.
+`Map` values (for example consent-form `content`) compare as plain key/value
+objects so stored documents are not rewritten on every sync.
+If `isDeletedPlugin` hid a matching row, `upsert` restores that document instead
+of inserting a duplicate. If more than one document already shares the key,
+`upsert` keeps the first match, tombstones or deletes the extras, then syncs
+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.
+
+## Guard destructive resets
+
+Production reset mode is denied by default. It runs only when both conditions
+are true:
+
+1. The CLI receives `--force`.
+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 (`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/track-upstream-expo.md

@@ -0,0 +1,52 @@
+# Track upstream Expo SDK betas
+
+Morning maintainer loop: see if Expo published a **new SDK major beta**, keep
+a long-lived `release-X.Y.Z` branch building, and leave a log so the next
+morning can resume.
+
+Agent procedure: skill `track-upstream-expo`. Upgrade commands: skill
+`upgrading-expo`. Log contract: skill reference `loop-log.md`.
+
+## 1. Probe
+
+From latest `master`:
+
+```bash
+bun run expo:track-probe
+```
+
+| Exit | Meaning |
+| --- | --- |
+| `1` | Nothing newer **and** no `open`/`blocked` loop. Stop. |
+| `0` | `create-branch`, `continue-branch` (newer beta), or `resume-loop` (same beta, unfinished). |
+| `2` | Probe broke (network/git). Fix that; do not skip. |
+
+The probe ignores patches of the current catalog major. It watches
+`expo@next` and `expo@latest` for a **higher major**, fetches `origin`
+`release-*` refs, then reads `loopStatus` from
+`origin/<releaseBranch>:scripts/track-upstream-expo/tracked.json`.
+
+State files (in the repo, not linked from this page):
+
+- `scripts/track-upstream-expo/tracked.json` — `expoVersion`, `loopStatus`
+- `scripts/track-upstream-expo/loop-log.md` — tries, failures, release-notes draft
+
+## 2. Branch name
+
+Expo `58.0.0-preview.1` → `release-58.0.0`. Create from `origin/master` the
+first day. Later days check it out, merge `master`, and either bump to a
+newer preview or resume **Open** items from the log.
+
+Do not merge `release-*` to master from this job.
+
+## 3. Native modules stay on the SDK train
+
+Packages that change the EAS fingerprint update **on this branch only**.
+
+## 4. Handoff every session
+
+Before edits: read `loop-log.md` (**Next**, **Open**, **Do not retry**).
+
+After edits: prepend **Tried**, refresh **Next** / **Open**, extend
+**Release notes draft**, set `loopStatus` to `open`, `blocked`, or `ready`,
+and push the release branch. Tomorrow starts from that commit.

package/src/docs/versioned/next/how-to/update-dependencies.md

@@ -0,0 +1,54 @@
+# Update dependencies
+
+This runs **daily**. Use `/update-dependencies`. There is one rolling PR; later days push to it and rewrite its ledger instead of opening new PRs.
+
+```bash
+REPOSITORY="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
+OWNER="${REPOSITORY%%/*}"
+NAME="${REPOSITORY#*/}"
+gh pr list --state open --head chore/update-dependencies \
+  --json number,url,baseRefName,headRefName,headRepository,headRepositoryOwner,isCrossRepository \
+  | jq --arg owner "$OWNER" --arg name "$NAME" \
+      '[.[] | select(
+        .isCrossRepository == false and
+        .baseRefName == "master" and
+        .headRefName == "chore/update-dependencies" and
+        .headRepository.name == $name and
+        .headRepositoryOwner.login == $owner
+      )]'
+bun outdated
+```
+
+Prove each bump with an **exercise test** that imports that package. Keep Expo fingerprints for `example-frontend` and `demo` unchanged. Skip `isFingerprintSkip` names until a release.
+
+Why: [Dependency management](../explanation/dependency-management.md). Native Expo/React Native bumps wait for `upgrading-expo`.
+
+## Do now
+
+1. Find the same-repository PR with exact head `chore/update-dependencies`, base `master`, and `isCrossRepository: false`. Marker/title matches are not trust signals; ignore forks. Merge `origin/master` without rewriting history. If no trusted PR exists, create the canonical branch on this run.
+2. Inventory with `bun outdated`. Retry **Failed** rows from the PR body first. Skip `isFingerprintSkip` in `scripts/planning/fingerprintRisk.ts`.
+3. For each candidate: confirm a test imports the package (add a tracer if needed), bump the catalog pin or single-use version, `bun install`, re-run that test, recompute fingerprints. Revert only that bump on failure.
+4. Commit each success on the same branch. Push. Update the **same** PR body: Last run, Landed, Failed, Skipped, Deferred to release. Do not `gh pr create` when that PR is already open.
+5. Read the ledger tomorrow; do not start a new PR.
+
+## Guardrails
+
+| Rule | Action |
+| --- | --- |
+| Trusted rolling PR already exists | Push to its same-repository `chore/update-dependencies` head and edit that body |
+| Fork copies marker/title/branch | Ignore it; never checkout, copy, edit, close, or comment on it |
+| Fingerprint would change | Revert that bump. Defer to a release. Never add `fingerprint-acknowledged` |
+| No test imports the package | Write the tracer test first. Do not bump on `test:ci` alone |
+| Published < 7 days ago (non-CVE) | Skip; log under Skipped |
+| Major version | May land on the rolling PR if tests + fingerprints pass; no auto-merge |
+| Dependabot extra PRs | Do not merge skip-list packages; fold JS bumps into the rolling PR |
+
+## Fingerprints
+
+`example-frontend` and `demo` use `fingerprint.config.js`. Hash with `eas fingerprint:generate` when `EXPO_TOKEN` is set, otherwise `bunx @expo/fingerprint <app-dir>`. Take a baseline after rebase, before new installs. After each successful bump, the new hashes become the baseline for the next package.
+
+`eas.json` Bun pins feed the fingerprint. Do not bump them here.
+
+## Dependabot still runs
+
+GitHub Dependabot remains in `.github/dependabot.yml`. Root catalog ignores native/Expo packages. Treat Dependabot as a signal; land updates on the rolling PR from this guide.

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

@@ -84,7 +84,7 @@ The hook handles:
 
 ### 4. Admin: Configure thresholds
 
-Navigate to the admin panel and select "Version Config". Set:
+Open the admin panel's `/version-config` route directly. The configuration screen is not included in the main sidebar. Set:
 
 - **Web Warning Version**: Build number below which web users see a warning toast
 - **Web Required Version**: Build number below which web users are blocked

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

@@ -0,0 +1,78 @@
+# Upgrade Terreno
+
+Bump every `@terreno/*` package together. Mixing versions is unsupported ([versioning policy](../explanation/versioning-policy.md)).
+
+## 1. Check current versions
+
+From the app root:
+
+```bash
+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)).
+
+## 2. Fetch notes for the range
+
+```text
+terreno_get_upgrade_guide({ fromVersion, toVersion })
+```
+
+Or browse [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/). The tool lists recorded notes and names same-major minors with no file — a gap is not “nothing changed.”
+
+## 3. Order (do not skip)
+
+| Step | Why |
+| --- | --- |
+| Clean git tree, work on a branch | Rollback is `git checkout -- .` / `git reset --hard` on that branch. |
+| Backend `@terreno/*` first | `/openapi.json` is the contract the frontend typed client is generated from. Regenerating against an old backend omits new routes; screens fail at compile. |
+| Backend compile + tests | Catch API breaks before touching Expo or UI. |
+| Expo SDK (if the Terreno major tracks a new Expo) | `@terreno/ui` pins `react-native` (for example `~0.86.0` on the 57 line in `ui/package.json` `peerDependencies`). Installing Terreno frontend packages before Expo leaves unmet peers. |
+| Frontend `@terreno/*` | UI, syncdb, admin-frontend, admin-spa, rtk. |
+| Regenerate typed client | Only after the **upgraded** backend is running. |
+| Compile, lint, tests | Whole app. |
+| Run the app | UI verification. |
+
+Use the `upgrading-expo` skill at the Expo step. Do not copy Expo’s checklist into a Terreno-only bump.
+Maintainers watching the next SDK beta use `track-upstream-expo` / [`track-upstream-expo.md`](track-upstream-expo.md) instead of mixing native bumps onto master.
+
+### Backend vs frontend packages
+
+From `publish-on-tag.yml`: **backend** `api`, `test`, `admin-backend`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`. **frontend** `ui`, `rtk`, `syncdb`, `admin-frontend`, `admin-spa`.
+
+## 4. RTK → syncdb is not a version bump
+
+If the range includes the syncdb release (`56.0.0-beta.2` and later), treat collection CRUD as a **platform migration**. Follow [migrate-rtk-to-syncdb.md](migrate-rtk-to-syncdb.md) in a separate change from the routine lockstep bump. Keep `@terreno/rtk` for the OpenAPI SDK, Better Auth, feature flags, and sockets until that migration is done.
+
+## 5. Manual steps
+
+1. Branch from a clean tree. Confirm tests pass on HEAD so later failures are from the upgrade.
+2. Print `fromVersion`, `toVersion`, notes, affected packages, and this order. **Stop until the human confirms.**
+3. Bump backend packages to `toVersion`. `bun install`. `bun run compile` and backend tests.
+4. If Expo must move, run `upgrading-expo`, then rebuild native binaries.
+5. Bump frontend packages. `bun install`.
+6. Start the upgraded backend. `cd <frontend> && bun run sdk`.
+7. `bun run compile`, `bun run lint`, and the app test suite.
+8. Log in and exercise the screens that use changed APIs.
+
+Stop at the first failed compile or test. Do not continue. Compile is a typecheck (`tsc --noEmit`); a bundler that ignores types is not enough.
+
+## 6. Verification
+
+- Every `@terreno/*` version in the lockfile is `toVersion`.
+- `terreno_get_upgrade_guide` verification sections for notes in the range all pass.
+- App boots; auth and one write path work.
+
+## 7. Rollback
+
+On the upgrade branch, with no extra uncommitted work you need:
+
+```bash
+git status --short   # only upgrade edits
+git reset --hard HEAD
+# or restore the previous lockfile commit:
+git checkout <pre-upgrade-sha> -- package.json bun.lock
+bun install
+```
+
+If you already committed, `git revert` the upgrade commit or reset the branch to the pre-upgrade SHA before it was pushed. Do not leave a half-upgraded lockfile on `master`.

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

@@ -1,6 +1,9 @@
 # Implementation plan template
 
-Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with `docs/tasks/<slug>.md`.
+Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with
+`docs/tasks/<slug>.md`. Add `**Parent IP:** [other](other.md)` only when this plan
+rides on another plan's roadmap entry instead of getting its own. A filled Parent
+IP header skips reconcile for that file.
 
 **Status:** Draft | Approved | In progress | Complete | Deferred  
 **Branch:**  

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

@@ -1,6 +1,8 @@
 # Modular API Implementation Plan
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084  
+**Status:** Complete
+
 ## Overview
 
 This document outlines the implementation plan for a new modular API design in `@terreno/api`. The goal is to create a `TerrenoApp` class that provides a cleaner, more flexible interface for building APIs while maintaining backward compatibility with the existing `setupServer` function.

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

@@ -40,24 +40,27 @@ 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.
-
-For a small feature, an outer loop may use the plugin's **feature profile**: a compact
-approved task contract, one fresh Pick invocation per frontier task, independent Roast,
-then Brew and bounded Taste iterations. This preserves the former Grind behavior without
-putting orchestration inside a lifecycle skill.
-
-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.
-2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD.
-3. **Roast** (`terreno-3-roast`) — independently verify the implementation against the IP.
-4. **Brew** (`terreno-4-brew`) — commit, push, open the PR.
+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 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`.
 5. **Taste** (`terreno-5-taste`) — react once to current CI, mergeability, and review state.
 
-The outer loop owns stage selection, execution-state persistence, waiting, retries, and
-human/external escalation. Each stage emits the compact machine-readable result described
+The outer loop owns Grow/Brew/Taste selection, execution-state persistence, waiting,
+retries, and human/external escalation. Pick owns the inner task loop. Roast never
+invokes Pick. Each stage emits the compact machine-readable result described
 in [`plugins/terreno-planning/references/lifecycle-contract.md`](../../plugins/terreno-planning/references/lifecycle-contract.md)
 (collapsed behind a Details toggle in chat and on the PR).
 

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