@terreno/mcp 57.1.0 → 57.3.0

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

@@ -12,6 +12,8 @@ Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On t
 
 Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
 
+**MCP service tokens** are a third, opt-in credential. They authenticate the consumer app's `POST /mcp` only. They are not Better Auth sessions, not JWTs, and not a REST personal-access-token. Enable them with `mcpServiceTokens` on `TerrenoApp`. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
+
 ## When to choose which
 
 | Choose Better Auth | Stay on JWT (legacy) |
@@ -35,7 +37,10 @@ Modern session-based authentication with built-in social OAuth support.
 3. Backend redirects to OAuth provider or validates credentials
 4. Better Auth creates session in MongoDB
 5. Frontend receives session cookie (web) or bearer session token (native)
-6. Session middleware populates `req.user` for subsequent requests
+6. On the first authenticated request, session middleware looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`)
+7. `req.user` is that app document for subsequent `modelRouter` permissions
+
+Email/password create omits `oauthProvider`. Apps that never use social login can keep `strict: "throw"` without declaring that field. OAuth create sets `oauthProvider` and the User schema must declare it.
 
 **Key properties:**
 - Session-based (cookies / bearer session) vs. stateless JWT
@@ -89,6 +94,16 @@ OAuth 2.0 authentication with GitHub.
 
 **Learn more:** [How to add GitHub OAuth](../how-to/add-github-oauth.md)
 
+### MCP service tokens (opt-in, `/mcp` only)
+
+Personal `mcp_` keys for remote MCP clients (Perplexity, Cursor JSON config) that cannot hold a session cookie. `TerrenoApp` must set `mcpServiceTokens`. Users mint keys from `POST /mcp/service-tokens` or **Profile → MCP connections**. The plaintext secret is returned **once**; the database stores SHA-256 `tokenHash`.
+
+`extractUserFromHeaders` on `/mcp` tries a `mcp_` Bearer first, then Better Auth, then JWT. A match loads the owning `User` and updates `lastUsedAt`. Revoked, expired, or disabled-user keys resolve to no user. The same Bearer is ignored on REST, sync, admin, and on the mint/list/revoke routes (a key cannot mint another key).
+
+This is not OAuth 2.1. Interactive MCP clients that cannot send a static key wait for the app MCP OAuth work ([app MCP server](../implementationPlans/app-mcp-server.md)). It is also not the hosted `@terreno/mcp` codegen server ([MCP server reference](../reference/mcp-server.md)).
+
+**Learn more:** [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md)
+
 ### Anonymous Strategy (JWT — legacy)
 
 Allows limited access without authentication.
@@ -259,7 +274,8 @@ modelRouter(Model, {
 - Use HTTPS in production
 - Validate token issuer (`TOKEN_ISSUER`)
 - Set appropriate token expiration times
-- Implement rate limiting on auth endpoints
+- Enable `TerrenoApp` `rateLimit` so login/signup/refresh use the stricter `auth` bucket (20 / 15 min). See [Rate limiting](../how-to/rate-limiting.md).
+- Keep login/signup/refresh reachable when the client still sends an expired access JWT. Those three routes skip JWT verification; `/auth/me` and other APIs still 401.
 - Log authentication failures
 
 ❌ **Don't:**
@@ -280,7 +296,7 @@ modelRouter(Model, {
 ❌ **Don't:**
 - Store tokens in localStorage on web (use httpOnly cookies in production)
 - Log tokens to console
-- Send tokens in URL query parameters
+- Send tokens in URL query parameters (MCP service tokens included)
 - Ignore token refresh failures
 
 ## Environment Variables
@@ -402,29 +418,29 @@ modelRouter(Model, {
 
 ### Webhook Authentication
 
-Verify webhook signatures instead of JWT:
+Verify signatures on `WebhooksApp` using `req.rawBody`. Do not `JSON.stringify(req.body)`
+and do not put webhook POSTs in OpenAPI.
 
-``````typescript
-import crypto from "crypto";
-
-router.post("/webhook", asyncHandler(async (req, res) => {
-  const signature = req.headers["x-signature"];
-  const payload = JSON.stringify(req.body);
-  const expected = crypto
-    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
-    .update(payload)
-    .digest("hex");
-  
-  if (signature !== expected) {
-    throw new APIError({status: 401, title: "Invalid signature"});
-  }
-  
-  // Process webhook
-}));
-``````
+```typescript
+import {hmacSignature, TerrenoApp, WebhooksApp} from "@terreno/api";
+
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+webhooks.route({
+  path: "/webhooks/example",
+  source: "example",
+  verify: hmacSignature({secret: process.env.WEBHOOK_SECRET!, header: "X-Webhook-Signature"}),
+  eventId: (req) => String((req.body as {id?: string})?.id ?? ""),
+  handler: async () => undefined,
+});
+
+new TerrenoApp({userModel: User}).register(webhooks).start();
+```
+
+See [Receive inbound webhooks](../how-to/inbound-webhooks.md).
 
 ## Learn More
 
+- [Receive inbound webhooks](../how-to/inbound-webhooks.md)
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Create a model](../how-to/create-a-model.md)
 - [API reference](../reference/api.md)

package/src/docs/versioned/next/explanation/configuration-system.md

@@ -207,29 +207,19 @@ router.post("/admin/config", async (req, res) => {
 ### Tunable Parameters
 
 ``````typescript
-// Rate limiting
-Configuration.register("RATE_LIMIT_MAX", {
-  defaultValue: 100,
-  envVar: "RATE_LIMIT_MAX",
-  description: "Maximum requests per window",
+// Page size — app Configuration, not the HTTP limiter
+Configuration.register("DEFAULT_PAGE_SIZE", {
+  defaultValue: 20,
+  envVar: "DEFAULT_PAGE_SIZE",
+  description: "Default list page size",
   type: "number",
 });
 
-Configuration.register("RATE_LIMIT_WINDOW_MS", {
-  defaultValue: 900000, // 15 minutes
-  envVar: "RATE_LIMIT_WINDOW_MS",
-  description: "Rate limit window in milliseconds",
-  type: "number",
-});
-
-// Use in middleware
-const rateLimit = require("express-rate-limit");
-const limiter = rateLimit({
-  max: await Configuration.get<number>("RATE_LIMIT_MAX"),
-  windowMs: await Configuration.get<number>("RATE_LIMIT_WINDOW_MS"),
-});
+const pageSize = await Configuration.get<number>("DEFAULT_PAGE_SIZE");
 ``````
 
+HTTP rate limiting is **not** a Configuration key. Pass `rateLimit` on `TerrenoApp` (see [Rate limiting](../how-to/rate-limiting.md)). Do not register `RATE_LIMIT_MAX` as if it enabled the framework limiter.
+
 ### Environment-Specific Defaults
 
 ``````typescript

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/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/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,63 @@ 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 lints in a no-context
+subagent, 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`, 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.
+
+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 +103,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) |
 | Deployment/runtime | `deploy-gcp`, Expo deployment/workflow skills |
 
 This inventory is descriptive, not a plugin dependency list. Stages inspect the actual
@@ -105,12 +138,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,6 +2,8 @@
 
 `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 actions when an endpoint performs an operation that is not a plain create/read/update/delete on the model document:

package/src/docs/versioned/next/explanation/modular-api-design.md

@@ -158,6 +158,14 @@ This would be nearly impossible with `setupServer()` because installing an app r
 
 With TerrenoApp, an "app" is just a function that receives the `TerrenoApp` instance and calls its methods.
 
+#### 6. One collection catalog for surfaces
+
+`modelRouter` registers each collection once in an in-memory **collection catalog** keyed by route path (for example `/todos`). The record holds the Mongoose model, `ModelRouterOptions`, and which surfaces are active (`mcp`, `realtime`, `sync`). TerrenoApp option enrichment calls `replaceCollectionOptions` once per path after RBAC injects `accessControl`.
+
+MCP, realtime, and sync read **views** of that catalog — they do not keep separate option arrays. `registerMCPModel`, `registerRealtime`, `registerSync`, and the `update*RegistryOptions` helpers remain as wrappers for tests and legacy callers. `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the **whole** catalog so tests cannot leave a stale MCP entry after a sync-only clear.
+
+Custom MCP tools stay on a separate list; they are not collections. Sync schema validation and index enqueue still run when a collection first opts into `sync`.
+
 ## Design Principles
 
 ### 1. Explicit over Implicit

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

@@ -126,7 +126,7 @@ shipped" row links the implementation plan or roadmap item that tracks it.
 | 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) |
-| Migrations | No migrations framework | Schema evolution is convention plus the `mongoose-schema-safety` skill (`.claude/skills/mongoose-schema-safety/`) |
+| Migrations | No migrations framework | Schema evolution is convention plus the published `mongoose-schema-safety` skill |
 
 ## Language rules