@terreno/mcp 57.2.0 → 57.4.0

package/src/docs/versioned/next/explanation/dependency-management.md

@@ -1,192 +1,100 @@
 # Dependency Management
 
-Understanding how Terreno manages dependencies, updates, and security.
+Terreno pins shared versions in the Bun catalog, lands JavaScript updates through
+an agent skill that proves each bump with a test, and keeps Expo native
+fingerprints frozen until a release.
 
-## Overview
+## Layers
 
-Terreno uses a multi-layered approach to dependency management:
-- **Bun catalogs** for version consistency across the monorepo
-- **Dependabot** for automated dependency updates
-- **Auto-merge workflow** for hands-off maintenance
-- **7-day cooldown** for security and stability
+| Layer | Job |
+| --- | --- |
+| **Bun catalog** | One version for every dependency shared by two or more workspace packages (`catalog:` in manifests) |
+| **`update-dependencies` skill** | Daily rolling PR on `chore/update-dependencies`: cooldown, exercise test, fingerprint freeze, ledger of landed/failed |
+| **Dependabot** | Backup signal for bun + GitHub Actions. Native/Expo catalog names are ignored so auto-merge cannot change the fingerprint |
+| **Release + `upgrading-expo`** | Expo SDK, React Native, and other native-module bumps |
 
-## Bun Catalogs
+Operator steps: [Update dependencies](../how-to/update-dependencies.md). Catalog rule: workspace `package.json` files use `"catalog:"` for shared pins.
 
-Shared dependency versions are defined in the root `package.json` under the `catalog` field. Workspace packages reference catalog versions with `catalog:` prefix.
+## Bun catalogs
 
-**Benefits:**
-- Single source of truth for shared dependency versions
-- Consistent versions across all packages
-- Easier updates — change once, apply everywhere
+Shared versions live in the root `package.json` `catalog` field.
 
-**Example:**
-
-``````json
-// root package.json
+```json
 {
   "catalog": {
     "react": "19.1.0",
     "react-native": "0.81.5"
   }
 }
-``````
+```
 
-``````json
-// ui/package.json
+```json
 {
   "dependencies": {
     "react": "catalog:",
     "react-native": "catalog:"
   }
 }
-``````
-
-## Dependabot Configuration
-
-Dependabot monitors dependencies across the monorepo with different update schedules and grouping strategies.
-
-### Update Groups
-
-| Group | Packages | Schedule | Strategy |
-|-------|----------|----------|----------|
-| **GitHub Actions** | Workflow dependencies | Weekly | Individual PRs |
-| **Root** | Catalog & dev tools | Monthly | Grouped PR |
-| **Backend** | `api`, `example-backend`, `mcp-server` | Monthly | Grouped PR |
-| **Frontend** | `ui`, `rtk`, `demo`, `example-frontend` | Monthly | Grouped PR |
-
-### 7-Day Cooldown
-
-**Why:** Malicious actors occasionally compromise NPM packages. Most compromises are detected and removed within 24 hours.
-
-**How it works:**
-- Dependabot waits 7 days after a package version is published before creating a PR
-- Security updates **bypass** the cooldown (immediate PRs for CVEs)
-- Reduces risk of incorporating compromised dependencies
-
-**Configuration:**
-
-``````yaml
-cooldown:
-  default-days: 7
-``````
-
-### Ignored Dependencies
-
-Frontend packages ignore catalog-managed dependencies to prevent duplicate PRs. Updates to these dependencies must be done via the root `package.json` catalog.
-
-**Examples:**
-- `react`, `react-native`, `expo`, `typescript`
-- `@reduxjs/toolkit`, `luxon`, `lodash`
-- All other dependencies listed in the root catalog
-
-## Auto-Merge Workflow
-
-The `dependabot-auto-merge.yml` workflow automatically approves and merges Dependabot PRs once all CI checks pass.
-
-### How It Works
-
-1. **Trigger:** Runs on every pull request
-2. **Condition:** Only executes if author is `dependabot[bot]`
-3. **Approval:** Automatically approves the PR using `GITHUB_TOKEN`
-4. **Auto-merge:** Enables squash-merge with `--auto` flag
-5. **Merge:** PR merges automatically once all required status checks pass
-
-### Prerequisites
-
-For auto-merge to function:
-1. ✅ Enable "Allow auto-merge" in **Settings → General → Pull Requests**
-2. ✅ Configure branch protection on `master` with required status checks
-3. ✅ All configured CI workflows (api-ci, ui-ci, etc.) must pass
+```
 
-### Security Considerations
+Change a shared version in the catalog once. Do not pin a second copy in a workspace package. Exceptions (`@types/node`, `path-to-regexp`, `@opentelemetry/sdk-node`) are listed in `.rulesync/rules/01-dependency-catalog.md`.
 
-**Why this is safe:**
-- PRs only merge after **all CI checks pass** (tests, linting, builds)
-- Security updates bypass cooldown but still require passing tests
-- Grouped PRs reduce noise while maintaining test coverage
-- Failed CI checks prevent merge — human review required
+## Agent updates vs Dependabot
 
-**When human review is needed:**
-- CI failures on Dependabot PRs
-- Major version updates (may include breaking changes)
-- Updates that touch critical dependencies (e.g., Express, React Native core)
+Dependabot groups many packages and merges when CI is green. That misses two Terreno constraints:
 
-## Workflow Diagram
+1. **Exercise.** CI can pass without any test importing the bumped module. The skill requires a named test file that imports the package and that passed **after** the bump. If none exists, write a tracer-bullet test first.
+2. **Fingerprint.** Expo `runtimeVersion.policy: "fingerprint"` ties OTA runtime and EAS dev builds to native hashes of `example-frontend` and `demo`. Native module bumps belong in a release, not a weekday dependency PR.
 
-``````mermaid
-flowchart TD
-    A[Package Version Published] -->|Wait 7 days| B{Security Update?}
-    B -->|Yes| C[Immediate PR Creation]
-    B -->|No| D[Create PR after cooldown]
-    C --> E[Auto-merge Workflow Triggered]
-    D --> E
-    E --> F{All CI Checks Pass?}
-    F -->|Yes| G[Auto-approve PR]
-    F -->|No| H[Require Human Review]
-    G --> I[Enable Auto-merge]
-    I --> J[Squash & Merge]
-    H --> K[Fix Issues & Re-run CI]
-    K --> F
-``````
+`scripts/planning/fingerprintRisk.ts` (`isFingerprintSkip`) is the skip matcher. After every allowed bump the skill still recomputes hashes; a changed hash is reverted even if the matcher allowed the name.
 
-## Best Practices
+## Cooldown
 
-### When to Update the Catalog
+Non-security npm versions wait **7 days** after publish before a bump (`npm view <name> time`). Most malicious publishes are yanked inside a day. GitHub Dependabot uses the same `cooldown.default-days: 7`. CVE/advisory bumps skip the wait and still need an exercise test and a fingerprint freeze.
 
-Update root `package.json` catalog when:
-- Multiple packages need the same dependency update
-- Major version updates require coordinated changes
-- New shared dependencies are introduced
+## Fingerprint freeze
 
-### When to Update Individual Packages
+Do not bump from this path:
 
-Update individual package dependencies when:
-- Package-specific dependencies (not in catalog)
-- Testing new versions before promoting to catalog
-- Overriding catalog versions for specific use cases (rare)
+- `expo`, `expo-*`, `react-native`, `react-native-*` except `react-native-web`
+- `@react-native/*` and related community native modules
+- `@expo/config-plugins`, `@sentry/react-native`, `@shopify/flash-list`, `@shopify/react-native-skia`
+- `eas.json` Bun version (it is a fingerprint input)
 
-### Monitoring Dependabot
+Those wait for a Terreno release (`release` + `upgrading-expo` skills). Do not use the `fingerprint-acknowledged` label to sneak them through a dependency PR.
 
-Check Dependabot activity:
-1. Navigate to **Security → Dependabot** in GitHub repository
-2. Review open PRs with `dependencies` label
-3. Check for failed updates or security alerts
-4. Monitor auto-merge success rate in Actions tab
+JavaScript packages, GitHub Actions, and a few Expo JS-only names may update. Measure hashes for both apps anyway.
 
-## Troubleshooting
+## Dependabot configuration
 
-### Dependabot PR Not Auto-Merging
+`.github/dependabot.yml` still opens grouped PRs:
 
-**Symptom:** PR approved but not merging
+| Group | Ecosystem | Schedule |
+| --- | --- | --- |
+| GitHub Actions | `github-actions` at `/` | Weekly |
+| Root catalog and root tools | `bun` at `/` | Monthly |
+| Backend workspaces | `bun` under api, ai, backends, … | Monthly |
+| Frontend workspaces | `bun` under ui, rtk, demo, apps, … | Monthly |
 
-**Checks:**
-1. Are all required status checks passing?
-2. Is auto-merge enabled in repository settings?
-3. Is branch protection configured on `master`?
-4. Check Actions tab for workflow failures
+Frontend ignores catalog-managed names so those PRs do not duplicate the root catalog. Root ignores fingerprint-skip names. `dependabot-auto-merge.yml` still squash-merges Dependabot PRs when required checks pass. Do not merge a Dependabot PR that includes a skip-list package; redo it with [Update dependencies](../how-to/update-dependencies.md).
 
-### CI Failures on Dependency Updates
+## Daily rolling PR
 
-**Symptom:** Dependabot PR fails CI
+The skill runs every day against **one trusted** open PR: exact same-repository head `chore/update-dependencies`, base `master`, and `isCrossRepository: false`. The marker `<!-- terreno-update-dependencies -->` and title are display metadata, not trust signals. Forks that copy them are ignored.
 
-**Actions:**
-1. Review CI logs to identify breaking changes
-2. Check dependency changelog for migration guides
-3. Update code to accommodate breaking changes
-4. Push fixes to the Dependabot branch or close PR
+A later run merges current master into that branch without rewriting history, retries **Failed** rows, appends **Landed** / **Failed** / **Skipped**, and pushes to the same head. It does not open a second trusted PR while that one is open. After merge, the next day may open the next rolling PR.
 
-### Too Many Dependabot PRs
+Each package is still proven alone (exercise test + fingerprint) before it stays on the branch. Failures are reverted and kept in the PR body so the next day does not rediscover them from scratch.
 
-**Symptom:** Overwhelming number of update PRs
+## Best practices
 
-**Solutions:**
-- Verify grouping is configured correctly in `.github/dependabot.yml`
-- Adjust update schedules (weekly → monthly)
-- Add dependencies to ignore list if catalog-managed
-- Increase cooldown period if needed
+- One rolling PR; many proven commits on that branch.
+- Majors: exercise test + fingerprint freeze; no auto-merge.
+- Security: skip cooldown; do not skip tests or fingerprints.
+- New feature dependencies belong in that feature's slice, not this maintenance path.
 
-## Related Documentation
+## Related
 
-- [CI/CD Workflows](../how-to/setup-cicd.md) *(coming soon)*
-- [GitHub Actions Security](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
-- [Dependabot Documentation](https://docs.github.com/en/code-security/dependabot)
+- [Update dependencies](../how-to/update-dependencies.md)
+- [Install agent skills](../how-to/install-agent-skills.md)
+- [Bun catalogs](https://bun.sh/docs/install/catalogs)

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/explicit-any-policy.md

@@ -14,7 +14,7 @@ Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as
 
 Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
 
-- Mongoose `Schema<any, …>` accepting arbitrary consumer schemas (`api/src/plugins.ts`)
+- Mongoose model boundaries that inspect consumer-defined schemas (`api/src/populate.ts`)
 - RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
 - Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
 - Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
@@ -55,7 +55,8 @@ For test files with many mocks, a file-level header is fine:
 ```bash
 bun run check:explicit-any                         # summary report
 bun run check:explicit-any:json                    # JSON inventory
-bun run check:explicit-any:baseline                # fail if counts regress vs baseline
+bun run check:explicit-any:lint                    # fail on unmarked or unsuppressed any
+bun run check:explicit-any:baseline                # fail if global or per-file counts regress
 bun run check:explicit-any -- --undocumented       # only suppressed-but-undocumented
 bun run check:explicit-any -- --list --undocumented  # file:line list for remediation
 bun run check:explicit-any -- --production-only --undocumented --list
@@ -70,10 +71,11 @@ bun run check:explicit-any:remediate               # auto-add missing noExplicit
 | Layer | What it does |
 |-------|----------------|
 | **Biome `noExplicitAny: error`** | Blocks new unsuppressed `any` in every linted package |
-| **`bun run check:explicit-any:baseline`** | CI ratchet — total, undocumented, and violation counts must not increase |
-| **`bun run lint`** | Per-package lint including `noExplicitAny` |
+| **`bun run check:explicit-any:lint`** | Blocks suppressions without a `noExplicitAny:` rationale, including undocumented file-level suppressions |
+| **`bun run check:explicit-any:baseline`** | CI ratchet — total, per-file, undocumented, and violation counts must not increase; a new file starts with an allowance of zero |
+| **`bun run lint`** | Runs package lint, then the strict explicit-any marker check |
 
-Baseline file: `scripts/check-explicit-any/baseline.json`. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
+Baseline file: `scripts/check-explicit-any/baseline.json`. Its per-file counts prevent a new or existing file from adding explicit `any` even when another file removes the same number. After intentional reductions (removing or properly documenting `any`), refresh with `--write-baseline` and commit the updated baseline.
 
 ## Remediation workflow
 

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

@@ -44,7 +44,7 @@ Both apps use the same architecture pattern optimized for single-page applicatio
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                    GCS Bucket (Origin)                       │
-│   (e.g., gs://flourish-terreno-terreno-demo)                │
+│   (e.g., gs://your-project-terreno-demo)                    │
 │                                                              │
 │   ├── index.html                                            │
 │   ├── _expo/                                                │

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

@@ -12,12 +12,8 @@ Terreno separates engineering method from orchestration:
                shape
                   |
                   v
-               PICK
-               build
-                  |
-                  v
-              ROAST
-               prove
+         PICK ⇄ ROAST  (inner loop)
+         one task, prove it, next task
                   |
                   v
                BREW
@@ -42,28 +38,66 @@ durable artifacts. Pick can retry from exact Roast evidence; Roast can verify wi
 implementer's assumptions; Taste can react to the current PR head rather than an old
 green result.
 
-The outer loop decides **when, who, what next, when to retry, when to wait, and when to
-escalate**. Stages decide how to perform one transition correctly.
+Pick continues across tasks in one invocation. Roast proves the current task and
+returns. Each Roast cycle still reconstructs from artifacts and prefers a fresh context
+with a task-scoped briefing (criteria, file list, and patch). Fresh context is for
+independence, not for two children to each reload the repository.
+
+The outer loop decides **when, who, what next, when to retry Taste `PENDING`, and when
+to escalate**. Stages decide how to perform one transition correctly. Pick continues
+the inner loop until the approved task list is done. Roast never invokes Pick. Brew and
+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 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:
+
+- `/terreno-pick-roast-loop` works an approved plan until every task passes Roast or a
+  genuine human decision is required. It resumes only Pick or Roast. Stored `next: brew`
+  completes the loop without launching Brew. It keeps one run ledger and reports all
+  task, retry, evidence, and risk details at the end. A human question includes the
+  overall state, options/impact, and recommendation.
+- `/terreno-planning-loop` runs Grow, then Pick (Pick owns the pick-roast inner loop),
+  then optional Brew/Taste; pass `phases=` to restrict.
+- `/terreno-taste-sweep` drives the author's broken open PRs by reinvoking Taste.
+
+None is a sixth stage.
 
 ## The five transitions
 
 | Stage | Question | Primary evidence |
 | --- | --- | --- |
 | Grow | Is the work shaped and approved? | IP/tasks, decisions, criterion→verification map |
-| Pick | Was this slice implemented carefully? | red/green tests, checks, internal reviews |
-| Roast | Does the result actually satisfy the IP? | independent requirement→evidence verdict |
+| Pick | Was this slice implemented carefully? | red/green tests, checks, internal reviews; then Roast |
+| Roast | Does this task actually satisfy its criteria? | independent requirement→evidence verdict; emit next Pick or Brew |
 | Brew | Is the verified result correctly submitted? | final checks, commit/head, PR, artifacts |
-| Taste | What is actionable on the current PR head now? | CI, mergeability, reviews, bounded fixes |
+| Taste | What is actionable on the current PR head now? | CI on every discovered host, mergeability, reviews, bounded fixes |
 
 Roast is not another implementation review. It independently proves or disproves
-acceptance criteria. Taste is not a resident watcher. It observes once, acts once, emits
-`PASS`, `FAIL`, `BLOCKED`, or `PENDING`, then exits.
-
-## Portable plugin, local knowledge
-
-The reusable plugin defines contracts, invariants, evidence, and transitions. Repo-local
-skills define exact API/UI/database patterns, commands, test environments, generated
-code, deployment, and safety rules.
+acceptance criteria. Taste is one reactive iteration, not an unbounded fix-until-green
+daemon. It waits until async review bots (Bugbot, CodeQL, and similar) on the current
+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`, 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.
+A host with a documented path/config reason not to run is terminal `skipped`; an
+unexplained missing run is never green.
+
+## Combined plugin, local knowledge
+
+The reusable plugin defines contracts, invariants, evidence, and transitions and bundles
+Terreno's reusable API/UI/data/schema/admin/docs/upgrade/deploy workflows. Repo-local
+skills define only project-specific roadmap, release, and maintenance operations.
 
 Each stage inspects available skills and loads those whose descriptions match the
 affected domain. A useful skill is optional when absent; a capability required by
@@ -72,20 +106,22 @@ repository policy is a hard gate and produces `BLOCKED` if unavailable.
 Stages also load architecture docs before acting. Docs are the design; code implements
 them. Missing docs for a user-visible or architectural change is `FAIL`.
 
-This lets the same Pick method compose with backend API and test-environment knowledge,
-while Roast composes with UI conventions and real-app verification.
+This lets the same plugin install provide Pick/Roast plus backend API, test-environment,
+UI, and real-app verification knowledge in consumer projects.
 
-### Terreno's current project-skill layer
+### Terreno's bundled skill layer
 
-The canonical sources remain under `.rulesync/skills/` and are generated for supported
-agents. The current high-value composition points include:
+Reusable framework skills are canonical inside `plugins/terreno-planning/skills/`.
+Repository-only skills remain under `.rulesync/skills/`. High-value composition points
+include:
 
 | Domain | Repo-local skills stages may discover |
 | --- | --- |
 | Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
-| UI/app | `terreno-ui`, `building-terreno-apps`, `building-native-ui`, `verify-ui-changes` |
+| UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
 | AI/prompts | `ai-prompt-governance` |
-| Docs/submission | `update-docs`, `commit`, `create-pr`, `fix-conflicts` |
+| 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; 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
@@ -105,12 +141,24 @@ contain chain-of-thought or transcripts.
 
 ## Retry and stop rules
 
-- Roast failure returns exact expected/actual evidence to a fresh Pick.
+- Pick implements one task, Roast proves it, then Pick takes the next unblocked task.
+  Do not start the next task until Roast PASS. Roast never invokes Pick. Exactly one
+  driver continues after each Roast. Do not pick every task and roast once.
+- Roast failure returns exact expected/actual evidence to Pick for the same task.
 - Engineering retries require a new hypothesis and preserve failed approaches.
-- Taste `PENDING` lets the outer loop wait and invoke fresh Taste against current state.
+- The focused Pick–Roast outer loop continues through ordinary implementation, test,
+  lint, and Roast failures while a concrete safe engineering action remains. It asks
+  for human input only when evidence cannot choose a product, architecture, security,
+  data, destructive, compatibility, permission, or policy outcome.
+- Taste `PENDING` is for review-bot timeout, product-CI wait timeout, or a second
+  post-fix push. The outer loop then uses native provider watch hooks or harness
+  subscriptions where available and a timer only as fallback, then invokes fresh Taste.
+- Brew waits in-process while Bugbot, CodeQL, or similar review bots are running.
+  Taste waits in-process for those bots and for product CI (`gh` / `circleci` watch
+  loop), then continues without a loop reinvocation unless it timed out.
 - Human decisions are `BLOCKED`, never arbitrary retries.
-- Taste `PASS` requires all current-head checks terminal/non-failing, no conflicts, and
-  no actionable review findings.
+- Taste `PASS` requires all current-head jobs on every discovered CI host
+  terminal/non-failing, no conflicts, and no actionable review findings.
 
 The detailed contract, schemas, and three execution scenarios live under
 [`plugins/terreno-planning/references/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-planning/references).

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

@@ -2,20 +2,39 @@
 
 `modelRouter` can register **actions** — named operations at collection or instance scope — alongside standard CRUD. Actions reuse the same permission model, error envelope, and OpenAPI pipeline as CRUD routes, without hand-wiring `endpoints`, `asyncHandler`, and doc loading.
 
+CRUD **create, update, and delete** (not named actions) share one write pipeline: REST, Sync, and MCP all call `executeCreate` / `executeUpdate` / `executeDelete` in `api/src/sync/executors.ts`. MCP tools map arguments and `APIError` titles onto the MCP result envelope after the executor returns. RBAC User-role stripping runs in those executors **after** `transform` / `preCreate` / `preUpdate`. MCP passes the registry `modelName` so stripping still applies when the compiled mongoose `modelName` is not `"User"`. Invalid document `_id` values (`CastError` on path `_id`, BSON invalid ObjectId) load as 404 `Document not found`; `CastError` on populate paths is a GET error, not a missing document.
+
 ## 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: {