@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/explanation/deployment-architecture-gcp.md

@@ -11,6 +11,8 @@ flowchart TD
   U["User<br/>iOS / Android / Web"]
   CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
   CR["Cloud Run<br/>@terreno/api backend"]
+  CT["Cloud Tasks<br/>durable jobs push queue"]
+  JW["Cloud Run<br/>private jobs worker service"]
   SM["Secret Manager<br/>auth secrets, MONGO_URI"]
   AT["MongoDB Atlas<br/>replica set (change streams)"]
   GCS["GCS bucket<br/>user file uploads"]
@@ -21,6 +23,9 @@ flowchart TD
   CR --> SM
   CR --> AT
   CR --> GCS
+  CR -->|"enqueue"| CT
+  CT -->|"OIDC POST /jobs/execute"| JW
+  JW --> AT
   AR --> CR
 ```
 
@@ -30,6 +35,8 @@ flowchart TD
 |-----------|------|
 | **Artifact Registry** | Stores versioned backend container images built from `example-backend/Dockerfile` |
 | **Cloud Run** | Runs the long-lived `@terreno/api` process (HTTP + Socket.io) |
+| **Cloud Tasks** | Dispatches persisted `@terreno/jobs` rows to an authenticated HTTP worker with queue-level concurrency limits |
+| **Jobs worker service** | Runs the same example-backend image and job definitions; exposes only the Cloud Tasks execute callback through Cloud Run IAM |
 | **Secret Manager** | Holds `MONGO_URI`, JWT secrets, and other credentials — mounted as env vars |
 | **MongoDB Atlas** | Primary database; must be a replica set for change streams (realtime, feature flags) |
 | **GCS (web bucket)** | Serves static web export; CDN caches at the edge |
@@ -59,6 +66,31 @@ flowchart TD
 
 Native iOS and Android apps call Cloud Run directly; only the web client uses the CDN origin.
 
+## Durable jobs and PR isolation
+
+Cloud Tasks is a push service; it does not expose a pull-consumer API. Cloud Run worker
+pools do not have HTTP ingress, so the example uses a private Cloud Run service as the
+execution pool. Queue rate limits bound dispatch concurrency and Cloud Run scales the
+worker instances.
+
+Production and PR revisions share one queue safely because every task stores its complete
+callback URL. A PR backend targets the matching `pr-<number>` worker tag and uses
+`terreno-example-pr-<number>` as its Mongo database. Removing a preview removes both
+service tags. An old callback then fails closed instead of reaching production or another
+PR. A failed backend preview tag cannot stay on a not-Ready revision: CD rebuilds traffic
+from Ready tags, deploys the new revision without `--tag`, then tags it.
+
+Every example-frontend PR preview is paired with this isolated backend, including
+frontend-only PRs. The exported Netlify bundle targets the matching `pr-<number>` Cloud
+Run tag, whose CORS configuration trusts only that preview origin. Preview clients never
+fall back to the production backend or production database.
+
+Queue IAM grants `cloudtasks.enqueuer` and `iam.serviceAccountUser` on
+`terreno-jobs-invoker` only to `terreno-backend-runtime`, the example API Cloud Run
+identity. The project default Compute Engine SA (MCP and any other service that omits a
+runtime identity) cannot create tasks that present that OIDC token. The worker remains
+invokable only by `terreno-jobs-invoker`.
+
 ## Related
 
 - [Deployment baseline](deployment-baseline.md) — seven requirements every host must satisfy

package/src/docs/versioned/next/explanation/deployment-baseline.md

@@ -73,6 +73,6 @@ Three details consumers get wrong:
 
 - **`PORT`** — Cloud Run and other platforms assign the listen port via `PORT`. Terreno reads `process.env.PORT` in `api/src/terrenoApp.ts` (default `9000` if unset).
 - **Non-root** — Do not run the container as root in production.
-- **Compile order** — Workspace packages (`@terreno/api`, `@terreno/test`, etc.) must compile before the example backend bundles.
+- **Compile order** — Workspace packages (`@terreno/api`, `@terreno/jobs`, `@terreno/test`, etc.) must compile before the example backend bundles. Compile `@terreno/jobs` before `@terreno/admin-backend` — admin-backend imports jobs. The image `exports` point at `dist/`, so skipping a workspace compile fails `bun build --compile` with an unresolved `@terreno/*` import.
 
 CI builds the image on every PR that touches backend paths (`.github/workflows/example-backend-docker.yml`).

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -0,0 +1,43 @@
+# Example app coverage
+
+The `example-backend` and `example-frontend` apps are the living checklist for
+framework capabilities. When you add a capability to `@terreno/*`, update this
+matrix in the same slice.
+
+Citations are paths from the repository root. A "yes" means a reader can follow
+that file (and its imports) to a working example. Gaps stay explicit.
+
+## Capability matrix
+
+| Capability | example-backend | example-frontend | Notes |
+| --- | --- | --- | --- |
+| `modelRouter` CRUD | yes — `example-backend/src/api/todos.ts` | yes — `example-frontend/components/SyncTodosScreen.tsx` (syncdb hooks generated from the same collection) | Todos are synced; list/create/update/delete go through `@terreno/syncdb`, not RTK collection hooks. |
+| Owner permissions | yes — `OwnerQueryFilter` + `Permissions.IsOwner` in `example-backend/src/api/todos.ts` | yes — the todos screen only shows the signed-in user's rows after sync scopes apply | Also gated by RBAC `access: {resource: "todo"}`. |
+| Admin panel (embedded) | yes — Admin plugin registration in `example-backend/src/server.ts` | yes — `example-frontend/app/admin/` | Expo routes wrap `@terreno/admin-frontend` screens. |
+| Admin SPA | yes — `AdminSpaServeApp` in `example-backend/src/server.ts` | n/a | Standalone SPA is served from the backend; not a frontend route. |
+| AI streaming chat | yes — `example-backend/src/api/ai.ts` (`addGptRoutes`) | yes — `example-frontend/app/(tabs)/ai.tsx` (`GPTChat`, optional `mascot`) | Empty-chat mascot is consumer-owned; the example fox is not a framework default. |
+| AI structured output | no | no | `@terreno/ai` supports structured generation; the example only streams chat. Recorded gap — not claimed by a current tutorial. |
+| Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
+| Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
+| Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/consents.tsx`, admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/gcs-settings.tsx` | |
+| Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
+| syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |
+| RBAC | yes — `example-backend/src/rbacRoles.ts`, `access.ts`, `access: {resource: "todo"}` on the todo router | yes — `example-frontend/app/admin/roles.tsx` | Shipped. The IP snapshot that marked RBAC "not shipped" is stale. Plan: [rbac-permissions.md](../implementationPlans/rbac-permissions.md). |
+| Organizations | yes — `createAccess({organizations: true})`, `organizationSettingsSchema`, `orgScopedPlugin` on projects | yes — admin org directory/settings at `example-frontend/app/admin/orgs/` | Settings live on `Organization.settings`; example registers a nested timezone schema. |
+| Background jobs | no | no | No generic job queue example. Admin maintenance scripts (`example-backend/src/adminScripts.ts`, script runner widget) are a related but different surface. Plan: [admin-script-runner.md](../implementationPlans/admin-script-runner.md). |
+
+## Gaps
+
+| Gap | Why it stays | Follow-up |
+| --- | --- | --- |
+| AI structured output | Chat streaming already demonstrates the AI pillar; structured `generateObject`-style routes are unused by current tutorials | Track with [AI-first tutorials #1010](https://github.com/FlourishHealth/terreno/issues/1010) (`add-ai-features.md` requires one structured-output call). |
+| Generic background jobs | Unshipped as a first-class example; do not invent a queue UI here | Track with [Durable background jobs #1188](https://github.com/FlourishHealth/terreno/issues/1188). Admin script runner is a related surface — [admin-script-runner.md](../implementationPlans/admin-script-runner.md). |
+
+## Keeping the matrix true
+
+When you add a framework capability:
+
+1. Exercise it in `example-backend` and/or `example-frontend`.
+2. Update this page (cite the file).
+3. Mention the example in the PR.

package/src/docs/versioned/next/explanation/local-first-data.md

@@ -27,7 +27,10 @@ Think **apply locally, then reconcile** instead of **request, wait, update cache
 3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
 4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
 
-RTK Query remains appropriate for **non-synced** endpoints: `/auth/me`, admin RPC, AI routes, and anything that should stay request/response.
+RTK Query remains appropriate for **non-synced generated** endpoints such as
+`/auth/me` and AI routes. Built-in admin RPC stays request/response through its
+host-bound fetch client; ObjectId/API-only admin CRUD keeps RTK compatibility in
+Terreno 57.
 
 ## What you start doing
 
@@ -35,7 +38,7 @@ RTK Query remains appropriate for **non-synced** endpoints: `/auth/me`, admin RP
 2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
 3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
 4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
-5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server.
+5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.
 
 ## Tradeoffs
 

package/src/docs/versioned/next/explanation/loop-engineering.md

@@ -49,8 +49,10 @@ the inner loop until the approved task list is done. Roast never invokes Pick. B
 Taste additionally wait while async review bots are running, preferring provider CLI
 watch hooks or harness event subscriptions over timer polling. Taste also waits in a
 loop for product CI with `gh` or `circleci` until jobs are terminal or the wait times
-out. Before any push it always pulls latest `master`, then lints in a no-context
-subagent, then pushes and watches CI.
+out. Before any push it always pulls latest `master`, then records last-run failed tests
+and re-verifies them locally, then runs the repository's root
+`prepush` package script in a no-context subagent when present (falling back to affected
+package lint, typecheck, and tests), then pushes and watches CI.
 
 Invocable outer loops in the plugin:
 
@@ -81,9 +83,10 @@ daemon. It waits until async review bots (Bugbot, CodeQL, and similar) on the cu
 head have reported, then waits in a loop for product CI using GitHub CLI
 (`gh pr checks --watch`, `gh run watch`) or CircleCI CLI (`circleci run watch`) until
 jobs are terminal or the wait times out. Before any push it always pulls latest
-`master`, then proves lint, typecheck, and affected tests in a fresh subagent with no
-parent conversation, then pushes and watches CI. It emits `PASS`, `FAIL`, `BLOCKED`, or
-`PENDING`, and exits.
+`master`, records last-run failed tests and re-verifies them locally, then runs root
+`prepush` when present in a fresh subagent with no parent
+conversation. If absent, it proves affected-package lint, typecheck, and tests instead.
+It then pushes and watches CI, emits `PASS`, `FAIL`, `BLOCKED`, or `PENDING`, and exits.
 
 Brew review-bot waits use only hooks targeted to the matched bot so ordinary CI cannot
 extend Brew. Taste's product-CI wait uses unfiltered GitHub/CircleCI watches on purpose.
@@ -118,7 +121,7 @@ include:
 | UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
 | AI/prompts | `ai-prompt-governance` |
 | Docs/submission | `update-docs`, Brew, `fix-conflicts` |
-| GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract) |
+| GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract; unattended Grow may also write an IP) |
 | Deployment/runtime | `deploy-gcp`, Expo deployment/workflow skills |
 
 This inventory is descriptive, not a plugin dependency list. Stages inspect the actual

package/src/docs/versioned/next/explanation/model-router-actions.md

@@ -6,18 +6,35 @@ CRUD **create, update, and delete** (not named actions) share one write pipeline
 
 ## When to use actions
 
+Use `collectionActions` / `instanceActions` for every application GET or POST that is not
+plain document CRUD. Do **not** register `app.get`, `app.post`, `router.get`, or
+`router.post` for those endpoints.
+
 Use actions when an endpoint performs an operation that is not a plain create/read/update/delete on the model document:
 
 - **Collection scope** (`POST /todos/bulkComplete`) — operate on many documents or the collection as a whole.
 - **Instance scope** (`POST /todos/:id/markComplete`) — operate on one loaded document.
 
-Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) when the URL does not fit the `/:id/{actionName}` or `/{actionName}` pattern.
+Leave Express `app.get` / `app.post` only for:
+
+- Inbound webhooks (`WebhooksApp`)
+- Static SPA / file serving
+- Framework auth, health, and version-check plugins
+- SSE or other streaming handlers that write the response themselves
+- Tests and harnesses
+
+PATCH and DELETE are CRUD (or a POST action that performs the same work). Do not add a
+hand-rolled DELETE next to a modelRouter.
+
+Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) only when the
+URL cannot be `/{actionName}` or `/:id/{actionName}` **and** the exceptions above do not
+apply.
 
 ## Example
 
 ```typescript
 import {modelRouter, Permissions, z} from "@terreno/api";
-import {Todo} from "../models";
+import {Todo} from "../models/todo";
 
 export const todoRouter = modelRouter("/todos", Todo, {
   permissions: {

package/src/docs/versioned/next/explanation/organizations.md

@@ -0,0 +1,88 @@
+# How organization tenancy works
+
+Terreno treats organizations as an optional framework primitive. Existing
+single-tenant apps do not pay a migration or authorization cost; multi-tenant
+apps opt in at the access, application, model, and admin layers. New apps
+generated by `create-terreno-app` opt in by default.
+
+## Identity and authorization layers
+
+Platform and tenant authority are separate:
+
+| Authority | Storage | Scope |
+| --- | --- | --- |
+| `superadmin` | `User.roles` | Every framework permission |
+| `operator` | `User.roles` | Organization directory and every organization |
+| `org-admin` | `Membership.roleName` | One organization |
+| `member` | `Membership.roleName` | One organization; app permissions decide actions |
+
+`user.admin` does not imply operator access. `org-admin` is deliberately not a
+global RBAC role: putting it on `User.roles` grants nothing. During an
+organization request, `createAccess({organizations: true})` adds the current
+active Membership grants to the normal role permissions.
+
+## Request context
+
+Tenant routes resolve `X-Organization-Id` after authentication. An operator or
+superadmin may enter any organization but must choose one. An org-admin with
+exactly one administered organization may omit the header; Terreno infers it.
+Ambiguous or unauthorized context fails before model queries run.
+
+The resolved organization and membership are stored in AsyncLocalStorage as
+well as `req.organization` / `req.membership`. This lets `OrgQueryFilter` add
+the server-owned organization id without trusting a client query parameter.
+
+## Isolation boundaries
+
+Tenant isolation uses multiple checks rather than one convention:
+
+1. `orgContextMiddleware({required: true})` rejects missing or unauthorized context.
+2. `OrgQueryFilter` ANDs the selected organization into list and search queries.
+3. `Permissions.IsOrganizationMember` rejects cross-org object reads and writes.
+4. Create hooks overwrite client-supplied organization ids.
+5. `orgScopedPlugin` rejects any post-create change to `organizationId` (REST, admin, sync, direct save).
+6. Sync scopes resolve active Membership rows and partition streams by organization.
+
+`AdminApp({organizations: true})` applies these boundaries automatically to
+admin models whose schema contains `organizationId`. Models without that path
+remain platform-scoped.
+
+## Disabled organizations
+
+When `Organization.disabled` is `true`, tenant context and membership mutations
+stop, but operators can still manage the organization record itself:
+
+| Surface | Disabled org behavior |
+| --- | --- |
+| `orgContextMiddleware` / inferred org context | 403 `Organization is disabled` |
+| `GET /orgs/mine` | Disabled orgs omitted from the switcher list |
+| `GET /orgs` (operator directory) | Disabled orgs still listed |
+| `GET` / `PATCH /orgs/:id` | Allowed (operators use `PATCH` with `disabled: false` to re-enable) |
+| `POST` / `PATCH` / `DELETE /orgs/:id/members` | 403 while disabled |
+| Soft-deleted orgs | Still 404 everywhere |
+
+Disabling or deleting an organization suspends its memberships. Re-enabling does
+not automatically reactivate them.
+
+## Why organizations are optional
+
+Automatically registering routes, roles, or Mongoose models would change
+existing apps merely because they upgraded `@terreno/api`. Instead:
+
+- `createAccess` omits Membership grants and the `operator` seed unless
+  `organizations: true`;
+- `TerrenoApp` does not mount `/orgs` unless organizations are enabled;
+- `AdminApp` does not scope models unless organizations are enabled;
+- Organization and Membership Mongoose models register lazily on first use.
+  Apps add fields to `Organization.settings` with `createOrganizationSettingsSchema`
+  and `registerOrganizationSettings`, not by replacing the Organization model.
+
+This keeps upgrades backward compatible while letting bootstrap generate
+multi-tenant-ready apps.
+
+## Related
+
+- [Add organizations](../how-to/add-organizations.md)
+- [API reference](../reference/api.md#organizations)
+- [Admin backend reference](../reference/admin-backend.md#organization-scoping)
+- [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)

package/src/docs/versioned/next/explanation/planning-plugins.md

@@ -0,0 +1,114 @@
+# Planning plugins
+
+Terreno ships its agentic workflows as **two host plugins**. They divide along one line:
+the lifecycle plugin knows *how to build one approved thing correctly*, and the scan
+plugin knows *what is worth building next and whether it worked*.
+
+```text
+terreno-scan                            terreno (lifecycle)
+------------                            -------------------
+Aim     charter a measurable goal
+Sweep   shard + map the repository
+Sift    reduce to verified findings
+Plot    slice findings into briefs ───►  Grow    shape IP + tasks
+                                         Pick ⇄ Roast  build and prove
+                                         Brew    submit the PR
+                                         Taste   react to CI and review
+Track   re-measure, close findings  ◄───  (merged)
+```
+
+A scan never edits product code. The lifecycle never decides what the repository should
+become. Every slice crosses that boundary exactly once, as an approved IP and task list.
+
+## terreno (lifecycle plugin)
+
+Five bounded transitions plus three outer loops. Canonical source:
+`plugins/terreno-planning/`; Claude Code consumes the generated `plugins/terreno-claude/`.
+
+| Stage | Owns | PASS next |
+| --- | --- | --- |
+| Grow | Research, grilling, approved IP and dependency-aware task list, criterion → verification map | Pick |
+| Pick | Implement one task, then Roast it, then take the next until the list is done | Roast, or Brew when done |
+| Roast | Independently prove the current task against its criteria | Pick if tasks remain, else Brew |
+| Brew | Final checks, commit, push, PR, evidence, CI trigger, wait for review bots | Taste |
+| Taste | One reaction to the current head: bots, CI on every host, conflicts, comments | null or fresh Taste |
+
+| Outer loop | Walks |
+| --- | --- |
+| `pick-roast-loop` | An approved plan through every Pick/Roast retry, one ledger, stop only at completion or a genuine human gate |
+| `planning-loop` | Grow/Pick/Brew/Taste, restrictable with `phases=` |
+| `taste-sweep` | Every open PR of yours that is conflicting or failing, until each is mergeable |
+
+Full contract: [lifecycle plugin reference](../reference/lifecycle-plugin.md) and
+[loop engineering](loop-engineering.md).
+
+## terreno-scan (scan plugin)
+
+Five bounded transitions plus two outer loops. Canonical source: `plugins/terreno-scan/`;
+Claude Code consumes the generated `plugins/terreno-scan-claude/`. It depends on the
+lifecycle plugin — Plot hands every slice to Grow.
+
+| Stage | Owns | PASS next |
+| --- | --- | --- |
+| Aim | Charter: metric with a command, measured baseline, dry-run detection rules, exclusions, validity rule, severity rubric, slice policy, review routing, budget | Sweep |
+| Sweep | Run the rules, shard hits deterministically, map fresh workers into candidate findings | Sift |
+| Sift | Dedupe, adversarially verify, drop what does not reproduce, rank, write the findings report | Plot, or Track when dry |
+| Plot | Slice findings into PR-sized units with standalone Grow briefs | Track, handing off to Grow |
+| Track | Re-measure the metric, close or reopen findings with evidence, record the round, choose the next move | Plot, Sweep, or null |
+
+| Outer loop | Walks |
+| --- | --- |
+| `campaign` | Bounded rounds: Aim → Sweep → Sift → Plot → lifecycle → Track. Stops at every gate. |
+| `loop` | Resident session: the same rounds, plus a heartbeat over open campaign PRs — route, answer review through Taste, fix red CI, Track merges — refilling work up to `wipLimit`. |
+
+Full contract: [scan plugin reference](../reference/scan-plugin.md).
+
+## Which one to invoke
+
+| Situation | Start with |
+| --- | --- |
+| You know what to build | `1-grow` |
+| You have an approved plan and want it built | `pick-roast-loop` |
+| A PR of yours is red or conflicting | `5-taste`, or `taste-sweep` for all of them |
+| You know the outcome you want, not the work | `scan 1-aim` |
+| You want that outcome pursued unattended | `scan loop` |
+
+## What each plugin persists
+
+| Artifact | Owner | Committed |
+| --- | --- | --- |
+| IP and task list | Grow | yes |
+| Execution state (`.terreno/pipeline/<slug>.json`) | Lifecycle outer loops | no |
+| Charter (`docs/scans/<goal>/charter.md`) | Aim | yes |
+| Findings report (`docs/scans/<goal>/round-<n>-findings.md`) | Sift | yes |
+| Campaign state (`.terreno/scan/<goal>.json`) | Scan outer loops | no |
+
+Both plugins emit the same shaped result — `v: 2`, `status` of `PASS` / `FAIL` /
+`BLOCKED` / `PENDING`, a `next`, and a concrete `action` — in a collapsed details block,
+with `status` / `next` / `action` as the visible lines. Neither persists
+chain-of-thought.
+
+## Why the split
+
+Three properties fall out of keeping discovery and delivery in separate plugins:
+
+- **A finding must earn its slice.** Sift drops anything that cannot be tied to the
+  goal metric, so the lifecycle only ever receives work with a stated payoff.
+- **Delivery rules stay in one place.** Review response, CI waiting, the pre-push gate,
+  and documentation obligations live in the lifecycle, so a scan cannot invent a
+  shortcut around them.
+- **Progress is measured, not asserted.** Track re-runs the metric command after the
+  work merges, so "we improved it" is always a number with its command output.
+
+## Hosts
+
+| Host | Lifecycle | Scan |
+| --- | --- | --- |
+| 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` |
+
+Install both from the marketplaces described in
+[install agent skills](../how-to/install-agent-skills.md). Claude Code resolves a plugin
+skill's command from its frontmatter `name`, which is why the two `*-claude/` trees are
+generated with shortened names by `bun run skills:sync`.

package/src/docs/versioned/next/explanation/positioning.md

@@ -103,8 +103,8 @@ your codebase is the 20% that is unique to your product.
 
 The analogy earns two honest caveats. First, Terreno targets a document store
 (MongoDB via Mongoose), not a relational ORM, and it has no migrations framework.
-Second, it is younger — several Django/Rails staples (background jobs,
-server-side rendering, role-based access control) are not shipped yet. The
+Second, it is younger — several Django/Rails staples (server-side rendering,
+role-based access control) are not shipped yet. The
 comparison table below is deliberately straight about where the analogy holds and
 where it does not; being honest about the gaps is what makes the analogy credible
 rather than marketing.
@@ -125,7 +125,7 @@ shipped" row links the implementation plan or roadmap item that tracks it.
 | Auth + permissions | Better Auth (`api/src/betterAuthApp.ts`) + `Permissions` (`api/src/permissions.ts`) | Fine-grained RBAC is in progress ([`rbac-permissions`](../implementationPlans/rbac-permissions.md)) |
 | Templates / views | `@terreno/ui` components — one universal codebase for iOS, Android, and web | Server-side rendering for web is not shipped yet ([`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md)) |
 | `manage.py` / generators | MCP server tools — the *tool* layer (`mcp-server/src/tools.ts`) + the `/terreno-*` SDLC pipeline — the *process* layer (`plugins/terreno-planning/skills/`) | Agent-driven rather than CLI-driven; the pipeline is not yet packaged for consumer apps ([`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md) Task 2.5) |
-| Celery / ActiveJob (background jobs) | Not shipped | On the [roadmap](../../ROADMAP.md) |
+| Celery / ActiveJob (background jobs) | `@terreno/jobs` `JobsApp` (`jobs/`) | [How-to](../how-to/background-jobs.md), [reference](../reference/jobs.md); optional GCP Cloud Tasks and Vercel Queues runners |
 | Migrations | No migrations framework | Schema evolution is convention plus the published `mongoose-schema-safety` skill |
 
 ## Language rules

package/src/docs/versioned/next/explanation/repository-settings.md

@@ -31,8 +31,9 @@ descriptions):
 **Path:** Settings → Branches → Branch protection rules → `master`
 
 - Require a pull request before merging
-- Require status checks to pass (include Repository policies, package CI, and
-  Rulesync Check jobs relevant to the change)
+- Require status checks to pass (include CircleCI `repo-policies`, package CI,
+  and Rulesync Check jobs relevant to the change — see the check name map in
+  [how-to/circleci.md](../how-to/circleci.md))
 - Require branches to be up to date before merging
 - Do not allow bypassing the above settings
 
@@ -50,9 +51,9 @@ as GitHub App checks; they are not CircleCI jobs.
 
 **Path:** Settings → Environments
 
-Same-repo PR jobs in `cd.yml` (`Terraform preview`, `Backend deploy (preview)`)
-skip when `head.repo.full_name != github.repository`. Also restrict the
-`gcp-cd-preview` environment (create it on first deploy if missing) with a
+Same-repo PR jobs in `cd.yml` (`Terraform preview`, `Tasks deploy (preview)`,
+`Backend deploy (preview)`) skip when `head.repo.full_name != github.repository`.
+Also restrict the `gcp-cd-preview` environment (create it on first deploy if missing) with a
 **deployment branch policy** or **required reviewers** so a fork that edits
 `cd.yml` cannot mint a prod WIF token.
 

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -553,7 +553,9 @@ org-admins manage only the current org. Invites and billing are design-only plac
 
 - **Implementation plan:** [org-management-ui.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/org-management-ui.md)
 - **Tasks:** [org-management-ui.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/org-management-ui.md)
-- **RTK flag:** Partial — admin screens use generated SDK / `useAdminApi`
+- **RTK flag:** Partial — custom non-synced routes use the generated SDK;
+  ObjectId admin compatibility may use `useAdminApi` in Terreno 57, while
+  eligible String-`_id` CRUD uses windowed syncdb
 - **Depends on:** rbac-permissions
 
 ---
@@ -605,15 +607,15 @@ same binary. Manifest finalized 2026-08-09 (decisions D1/D3/D7); TenTap excluded
 **Title:** `create-terreno-app scaffolding CLI`
 
 **Labels:** `area:dx`, `type:feature`
-**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`create-terreno-app`, Status=`In progress`
 
 Today the MCP bootstrap tool returns markdown instructions and writes no files. This ships
 a real `create-terreno-app` CLI (or template repo) that produces a running, deployable app
 — backend, Expo app, env files, seeded auth — in one command, with the MCP bootstrap
 delegating to it.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
+- **Implementation plan:** [create-terreno-app.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/create-terreno-app.md)
+- **Tasks:** [create-terreno-app.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/create-terreno-app.md)
 - **RTK flag:** Partial — scaffold output follows the syncdb + Better Auth direction
 - **Depends on:** deployment-foundation
 
@@ -624,15 +626,14 @@ delegating to it.
 **Title:** `Charts and dashboard primitives`
 
 **Labels:** `area:ui`, `type:feature`
-**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=`charts-and-dashboards`, Status=`In progress`
 
-`@terreno/ui` has a stubbed `Chart` export and no implementation. Adds themed chart
-components (line, bar, area, donut) on `victory-native` — JS-only, since its Skia /
-Reanimated / Gesture Handler peers are already linked — plus a simple dashboard grid
-layout, with demo stories and docs.
+`@terreno/ui` ships themed `LineChart`, `BarChart`, `AreaChart`, `DonutChart` on owned
+`react-native-svg` (not `victory-native`) plus `DashboardGrid`. Demo stories and Diátaxis
+docs are the proof; comms admin stats consume these primitives later.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
+- **Implementation plan:** [charts-and-dashboards.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/charts-and-dashboards.md)
+- **Tasks:** [charts-and-dashboards.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/charts-and-dashboards.md)
 - **RTK flag:** None
 - **Depends on:** —
 
@@ -662,14 +663,14 @@ root views and system chrome follow the scheme.
 **Title:** `DataTable server-side filtering and search`
 
 **Labels:** `area:ui`, `type:feature`
-**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=`datatable-server-side-filtering`, Status=`Planned`
 
 DataTable sorts and paginates but has no filter UI. Adds per-column filter controls and a
 search box that emit modelRouter-compatible query params (`queryFields`, `$and`/`$or`), so
 list screens get server-side filtering without custom plumbing. Admin tables adopt it.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
+- **Implementation plan:** [datatable-server-side-filtering.md](../implementationPlans/datatable-server-side-filtering.md)
+- **Tasks:** [datatable-server-side-filtering.md](../tasks/datatable-server-side-filtering.md)
 - **RTK flag:** Partial — query wiring examples depend on the frontend data layer
 - **Depends on:** —
 
@@ -699,14 +700,14 @@ native module baseline regardless, so this lands as a JS/OTA feature when schedu
 **Title:** `In-app notification center`
 
 **Labels:** `area:ui`, `type:feature`
-**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=`notification-center` (Approved), Status=`Planned`
 
 Adds a Notification model with per-user preferences, realtime delivery over the existing
 change-stream socket layer, and a bell/inbox UI in `@terreno/ui` with read/unread state —
 the in-app channel beside `@terreno/comms` mail/SMS/push.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
+- **Implementation plan:** [notification-center.md](../implementationPlans/notification-center.md)
+- **Tasks:** [notification-center.md](../tasks/notification-center.md)
 - **RTK flag:** Partial — inbox screens target the syncdb data layer where available
 - **Depends on:** comms-abstraction
 
@@ -826,17 +827,20 @@ enforcement hooks in the permission layer.
 **Title:** `Framework-level audit log`
 
 **Labels:** `area:api`, `type:feature`
-**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=`framework-audit-log`, Status=`Planned`
 
 Generalizes the admin/consent audit patterns into a first-class audit log: an AuditEvent
 model, modelRouter hooks that record who changed what (with before/after diffs), org
 scoping, retention policy, and an admin viewer — a hard requirement for compliance-minded
 B2B customers.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
+Shipping this work **closes** https://github.com/FlourishHealth/terreno/issues/1186.
+
+- **Implementation plan:** [framework-audit-log.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/framework-audit-log.md)
+- **Tasks:** [framework-audit-log.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/framework-audit-log.md)
+- **How-to:** [audit-log.md](../how-to/audit-log.md)
 - **RTK flag:** None
-- **Depends on:** org-management-ui
+- **Depends on:** — (optional `organizationId` now; org-admin list filter waits on org-management-ui)
 
 ---
 
@@ -866,15 +870,19 @@ Shipping this work **closes** https://github.com/FlourishHealth/terreno/issues/1
 **Title:** `Durable background jobs`
 
 **Labels:** `area:api`, `type:feature`
-**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Project fields:** Area=`api`, Target=`Released`, Impact=`Feature`, IP=`job-queues`, Status=`Shipped`
 
-Terreno has an in-process cron helper and admin script runner but no durable queue. Adds a
-job abstraction with retries, scheduling, and dead-lettering — Mongo-backed by default with
-a Redis/BullMQ driver — so email sends, webhook retries, and billing sync survive restarts.
+Adds `@terreno/jobs`: Mongo-recorded jobs with retries, schedules, dead-lettering, in-process or
+standalone workers, and pluggable runners (Mongo, GCP Cloud Tasks, Vercel Queues, custom).
+Email/webhook/billing consumers enqueue later; this item ships the queue.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
-- **RTK flag:** None
+Shipping this work **closes** https://github.com/FlourishHealth/terreno/issues/1188.
+
+- **Implementation plan:** [job-queues.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/job-queues.md)
+- **Tasks:** [job-queues.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/job-queues.md)
+- **How-to:** [background-jobs.md](../how-to/background-jobs.md)
+- **Reference:** [jobs.md](../reference/jobs.md)
+- **RTK flag:** Partial — admin screens use generated SDK
 - **Depends on:** —
 
 ---
@@ -883,15 +891,17 @@ a Redis/BullMQ driver — so email sends, webhook retries, and billing sync surv
 
 **Title:** `MongoDB migrations tooling`
 
-**Labels:** `area:api`, `type:feature`
-**Project fields:** Area=`api`, Target=`Future`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Labels:** `area:api`, `type:feature`  
+**Project fields:** Area=`api`, Target=`Future`, Impact=`Feature`, IP=`mongodb-migrations-tooling`, Status=`Planned`
 
 A migrations runner for Terreno apps: versioned migration files, up/down with a lock
-collection, CI checks, and integration with the mongoose-schema-safety guidance — replacing
-ad-hoc backfill scripts.
+collection, CI checks, CLI generate-from-schema-diff, optional boot apply, and an admin
+Migrations page — replacing ad-hoc backfill scripts for once-per-environment schema changes.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
+Shipping this work **closes** https://github.com/FlourishHealth/terreno/issues/1189.
+
+- **Implementation plan:** [mongodb-migrations-tooling.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/mongodb-migrations-tooling.md)
+- **Tasks:** [mongodb-migrations-tooling.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/mongodb-migrations-tooling.md)
 - **RTK flag:** None
 - **Depends on:** —