@terreno/mcp 57.3.0 → 57.4.0

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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:** —
 

package/dist/docs/versioned/next/explanation/source-rules.md

@@ -49,7 +49,7 @@ bun test scripts/check-source-rules/
 | Layer | What it does |
 | --- | --- |
 | **`bun run check:source-rules`** | Scans scoped production sources and fails on any remaining hit |
-| **Repository policies CI** | GitHub Actions job `Production source rules` (CircleCI twin `source-rules`) |
+| **Repository policies CI** | CircleCI job `repo-policies` (includes `check:source-rules`) |
 | **`bun run check`** | Local aggregate that includes this scanner |
 
 A **new** production file that uses `export function`, `Date.now()`, `throw new Error`, `console.log`, `Model.findOne`, or unsuppressed `as any` fails CI.

package/dist/docs/versioned/next/explanation/static-analysis.md

@@ -3,6 +3,18 @@
 Run `bun run analyze:full` before pushing changes that alter imports, exports, package
 dependencies, or module boundaries.
 
+Taste does not need to infer that policy in this repository. The root `prepush` package
+script is the canonical local gate and runs lint, TypeScript compilation, and full static
+analysis:
+
+```bash
+bun run prepush
+```
+
+The reusable Taste stage checks for a root `prepush` script before every push and runs it
+in a fresh, no-context subagent. Repositories without one retain Taste's fallback:
+package-level lint, typecheck, and locally affected tests.
+
 Terreno uses two analysis speeds so agents receive quick edit feedback without replacing
 repository-wide correctness checks with a partial changed-file scan.
 
@@ -12,7 +24,8 @@ repository-wide correctness checks with a partial changed-file scan.
 | --- | --- | --- | --- |
 | Biome | `bun run analyze:fast` | Changed and untracked analyzable files | Agent post-edit hooks |
 | Biome | `bun run analyze:staged` | Staged analyzable files | Git pre-commit |
-| Knip | `bun run analyze:full` | Both development and production module graphs | Agent stop hooks and CI |
+| Knip | `bun run check:knip` | Both development and production module graphs | Dedicated GitHub workflow |
+| Knip | `bun run analyze:full` | Both development and production module graphs | Agent stop hooks and CircleCI |
 | dependency-cruiser | `bun run analyze:full` | Workspace source dependency graph | Agent stop hooks and CI |
 
 Biome runs from the nearest workspace configuration. Knip finds unused files, exports,
@@ -26,28 +39,73 @@ development runs `bun run bootstrap`; without that exclusion, each package's com
 `dist/*.d.ts` entry point contributes unlisted-dependency findings that CI can never
 reproduce.
 
-## Ratchets
+## Entry graph
+
+Knip only follows files reachable from entries. Register executed-but-unimported files
+in `knip.jsonc` `workspaces.<name>.entry` instead of deleting them or stuffing them into
+the JSON baseline.
+
+Setting `entry` **replaces** Knip’s default `{index,cli,main}` / `src/{index,cli,main}`
+patterns for that workspace, so those defaults must be repeated next to extra globs.
+
+| Kind | Why Knip misses it | Entry |
+| --- | --- | --- |
+| `*.isolated.ts(x)` | Run as `bun test $file`, not `*.test.ts` | `src/isolated/**/*.isolated.{ts,tsx}` on the owning package |
+| `scripts/**/*.test.ts`, `.github/scripts/**/*.test.ts` | Root `test` is `bun run --filter '*' test:ci`, so the Bun plugin never loads them | Root workspace `"."` |
+| `example-frontend/e2e/**/*.ts` | Playwright helpers and setup files are executed through project configuration, not app imports | `example-frontend` entry glob |
+| Generated SDK contracts not yet imported by a screen | Codegen output is retained for compatibility verification | `ignoreFiles` for only the unused-file issue; exports and dependencies remain analyzed |
+| OpenAPI codegen configs, Metro `jspdf` stubs, Expo fingerprint configs, Playwright CI config, `ui/babel.config.js`, Docusaurus `src/theme/**` swizzles, `scripts/ci/prepare-package-publish.mjs` | Invoked by Expo/Metro/Docusaurus/CI, not imported from app `index` | Extra `entry` globs on the owning workspace |
+| Generated `expo-cicd-workflows/scripts/*.js` (including `.rulesync/`) | Skill copies; they import `ajv` / `js-yaml` outside this repo’s package graph | `ignore` globs |
+| `example-backend` production dependencies | Knip's package-script entry for `bun run src/index.ts` shadows the explicit `src/index.ts!` entry in production mode | Keep default-mode enforcement; use exact dependency names suffixed with `!` as production-only exceptions |
+| `mcp-server/src/__tests__/preload.ts` | `bunfig.toml` `test.preload`; Knip's Bun plugin is disabled for this workspace | `mcp-server` extra entry |
+
+## Runtime-only dependencies
+
+Do not remove an Expo, React Native, or Metro dependency solely because Knip cannot find
+a static import. Expo autolinking, `app.json` plugin strings, Metro aliases/polyfills,
+platform-specific modules, and published UI peer surfaces load dependencies outside
+Knip's source graph. Keep those dependencies in the owning `package.json` and list them
+under that workspace's `ignoreDependencies` in `knip.jsonc`, with a comment naming the
+runtime loader.
+
+The same rule covers externally installed CLIs (`maestro`, `eas`), catalog pins retained
+for native fingerprint compatibility, and optional peers consumed by published-package
+users. Declare those narrowly with `ignoreBinaries` or `ignoreDependencies`; do not add a
+fake local import.
+
+## Exports and test seams
+
+Remove `export` from unused module internals. Keep published package-entry exports for
+compatibility even when this monorepo has no consumer; suppress only their `exports` or
+`types` issue on the defining file, with a public-API comment in `knip.jsonc`.
+
+Some internal helpers are intentionally exported so tests can exercise deterministic
+logic without widening the npm entry point. Mark those declarations `@internal`: default
+Knip still proves that tests use them, while production mode excludes the test-only seam.
+Generated SDK files use a path-scoped `ignoreIssues` entry instead of hand edits.
 
-The repository already contains findings that cannot be removed in one change. The
-checked-in baselines allow existing findings to remain while rejecting new ones:
+## Zero-finding policy
 
-- `scripts/static-analysis/knip-baseline.json`
-- `.dependency-cruiser-known-violations.json`
+Knip has no baseline. `bun run check:knip` runs the default and production graphs and
+fails on every finding. The dedicated `Knip / Zero findings` GitHub workflow runs this
+command for every pull request and every push to `master`.
 
-Knip fingerprints omit line and column positions, so moving an existing declaration does
-not create a false regression. A renamed symbol, moved file, or new finding must be fixed
-or deliberately reviewed into the baseline.
+Fix every Knip finding or add the narrowest justified exception to `knip.jsonc` with a
+comment naming the runtime loader, public compatibility promise, generated source, or
+tool limitation. Do not create a Knip baseline or any other separate finding inventory.
 
-After intentionally accepting repository-wide analysis changes, regenerate both
-baselines:
+dependency-cruiser still uses `.dependency-cruiser-known-violations.json` to ratchet its
+remaining findings. After intentionally accepting repository-wide dependency-graph
+changes, regenerate only that baseline:
 
 ```bash
-bun run analyze:baseline
+bun run analyze:dependency-baseline
 bun run analyze:full
 ```
 
-Review the baseline diff before committing it. Never run `knip --fix` unattended because
-an incomplete entry graph can remove runtime-loaded code.
+Review the dependency-cruiser baseline diff before committing; findings may only stay
+level or decrease. Never run `knip --fix` unattended because an incomplete entry graph
+can remove runtime-loaded code.
 
 ## Agent hooks
 
@@ -56,7 +114,9 @@ native configuration for Cursor, Claude Code, Codex CLI, GitHub Copilot, Copilot
 Google Antigravity CLI, and Devin.
 
 Post-edit events run the changed-file Biome command. Stop events run both repository-wide
-ratchets. Hook failure and retry behavior differs by host, so CircleCI remains the merge
+ratchets. `analyze:full` retries Knip without `--cache` when a concurrent stop-hook and
+prepush run corrupt or lock the cache, so the stop hook does not fail with empty JSON.
+Hook failure and retry behavior differs by host, so CircleCI remains the merge
 gate and the real Git pre-commit hook covers commits made outside an agent.
 
 `simple-git-hooks` installs the pre-commit hook during `bun install` through the root
@@ -69,7 +129,7 @@ gate and the real Git pre-commit hook covers commits made outside an agent.
 | `knip.jsonc` | Entry graph, plugins, generated-code exceptions |
 | `.dependency-cruiser.js` | Dependency rules and resolver conditions |
 | `.rulesync/hooks.json` | Canonical agent lifecycle hooks |
-| `scripts/static-analysis/` | Portable hook commands, ratchet logic, and tests |
+| `scripts/static-analysis/` | Portable direct Knip checks, dependency ratchet logic, and tests |
 
 Generated agent hook files must not be edited directly. Change `.rulesync/hooks.json`,
 then run `bun run rules`.