@terreno/mcp 57.21.0 → 58.0.0-beta.2

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

@@ -0,0 +1,106 @@
+# GCP deployment architecture
+
+Reference topology for hosting a Terreno full-stack app on Google Cloud Platform.
+
+This page is conceptual — commands live in the [how-to guides](../how-to/deploy-to-gcp.md).
+
+## Topology
+
+```mermaid
+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"]
+  AR["Artifact Registry<br/>backend image"]
+  U -->|"web"| CDN
+  U -->|"native app"| CR
+  CDN -->|"API calls"| CR
+  CR --> SM
+  CR --> AT
+  CR --> GCS
+  CR -->|"enqueue"| CT
+  CT -->|"OIDC POST /jobs/execute"| JW
+  JW --> AT
+  AR --> CR
+```
+
+## Component responsibilities
+
+| Component | Role |
+|-----------|------|
+| **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 |
+| **GCS (uploads bucket)** | Private object storage for user uploads via `@terreno/api` file plugins |
+
+## Why Cloud Run (not App Engine or GKE)
+
+| Option | Tradeoff |
+|--------|----------|
+| **Cloud Run** | Pay-per-use, minimal ops, supports WebSockets with session affinity — fits Terreno's socket + HTTP model |
+| **App Engine** | Similar serverless model but less flexible for custom containers and long timeouts |
+| **GKE** | Full control but requires cluster management — overkill for a single Terreno backend |
+
+## Why Atlas (not self-hosted Mongo on GCP)
+
+| Option | Tradeoff |
+|--------|----------|
+| **MongoDB Atlas** | Managed replica sets, backups, and change streams out of the box |
+| **Self-hosted on Compute Engine** | You operate replica set elections, backups, and upgrades — documented as out of scope for launch |
+
+## Static web vs server-rendered
+
+| Approach | Tradeoff |
+|----------|----------|
+| **GCS + CDN (static export)** | Cheapest, simplest, works today with Expo `single`/`static` output — no SSR or API routes |
+| **Node/Bun server (SSR)** | Better SEO and API routes — requires Expo SDK ≥ 55; not available in the current `~54` catalog |
+
+Native iOS and Android apps call Cloud Run directly; only the web client uses the CDN origin.
+
+## gcloud quickstart vs Terraform
+
+| Approach | Tradeoff |
+|----------|----------|
+| **gcloud commands** | Fastest first deploy; nothing to install beyond the CLI, but resources drift and are hard to recreate |
+| **`terreno-backend` Terraform module** | Reviewable, repeatable infrastructure for production; adds Terraform state to manage |
+
+With the module, Terraform owns the structure (registry, identities, secrets, service settings) and the deploy step owns the payload (image, env vars, secret mounts). The module ignores image and env changes after creation so the two never fight.
+
+## 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
+- [Deploy to GCP](../how-to/deploy-to-gcp.md) — step-by-step guides

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

@@ -0,0 +1,78 @@
+# Deployment baseline
+
+Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), [Deploy to Vercel](../how-to/deploy-to-vercel.md)) map these to specific platforms; this page names them once.
+
+See also the [environment variables reference](../reference/environment-variables.md).
+
+## Seven baseline requirements
+
+| # | Requirement | Why Terreno needs it | When missing |
+|---|-------------|----------------------|--------------|
+| 1 | **MongoDB replica set** | Change streams power realtime and live feature-flag updates | Startup logs: `FeatureFlag.watch() failed — live updates require MongoDB as a replica set` (`feature-flags/src/featureFlagsApp.ts`) |
+| 2 | **Auth secrets** | JWT signing and sessions (or Better Auth encryption) | Login fails; tokens rejected |
+| 3 | **Long-lived backend process** | Socket.io connections are not request/response | Websockets drop on platforms with short request timeouts or aggressive scale-to-zero |
+| 4 | **Correct origins** | CORS and Better Auth `trustedOrigins` must include your web and native schemes | Browser: blocked by CORS; native: auth redirects fail |
+| 5 | **Build-time client config** | `EXPO_PUBLIC_*` values are inlined into the web bundle at build time | API calls go to `undefined` or localhost after deploy — see [Build for web](../how-to/build-for-web.md) |
+| 6 | **Health endpoint** | Load balancers and orchestrators need readiness probes | Platform marks the service unhealthy and stops routing traffic |
+| 7 | **Durable file storage** | Uploads must not live on ephemeral container disk | Files disappear on restart; use GCS/S3 and credentials |
+
+Requirements **1**, **3**, and **5** are the ones teams miss most often.
+
+### Symptom details
+
+**1 — Standalone MongoDB**
+
+Terreno's feature-flag plugin opens a change stream on startup. Without a replica set, live flag sync is disabled and logs:
+
+```text
+[feature-flags] FeatureFlag.watch() failed — live updates require MongoDB as a replica set (even single-node).
+```
+
+Use [MongoDB Atlas](https://www.mongodb.com/atlas) or a single-node replica set for development.
+
+**3 — Short-lived serverless timeouts**
+
+The RTK/socket client enables reconnection (`reconnection: true`, `reconnectionAttempts: 5` in `rtk/src/socket.ts`). When the backend drops idle connections (for example Cloud Run's default 300s request timeout), clients reconnect but realtime state may lag until the new socket attaches.
+
+**5 — Build-time API URL**
+
+If you set `EXPO_PUBLIC_API_URL` only at runtime on the static host, the bundle still contains whatever was present at `bun run export` time — often `http://localhost:4000`. The browser then fails network requests against localhost.
+
+## Web output modes
+
+Expo Router supports three web output modes. The choice determines hosting options.
+
+| Mode | Output | API routes | SSR | Hosting | Terreno status |
+|------|--------|-----------|-----|---------|----------------|
+| `single` | One `index.html` SPA | No | No | Any static host | Expo's default |
+| `static` | Per-route HTML files | No | No | Any static host | Used by `example-frontend` and `demo`; better SEO |
+| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Available (repo catalog is Expo `~57.0.14`) but unused; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#advanced-server-output) and [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md) |
+
+## Multi-environment checklist
+
+Staging and production differ in these values (each environment needs its **own web build** because of `EXPO_PUBLIC_API_URL`):
+
+| Item | Where to configure |
+|------|-------------------|
+| Secret values | Platform secret store / Secret Manager |
+| `MONGO_URI` | Separate cluster or database per environment |
+| `EXPO_PUBLIC_API_URL` | Set before `bun run export` — one build per environment |
+| `corsOrigin` | `setupServer({ corsOrigin })` in backend |
+| Better Auth `trustedOrigins` + `BETTER_AUTH_URL` | Better Auth config / env |
+| Feature-flag defaults | MongoDB documents or seed scripts |
+
+## Containerizing the backend
+
+The canonical Dockerfile is [`example-backend/Dockerfile`](https://github.com/TerrenoLabs/terreno/blob/master/example-backend/Dockerfile). It:
+
+1. Installs workspace dependencies and compiles packages in dependency order.
+2. Builds a Bun-compiled binary for production.
+3. Runs as a non-root user and exposes `/health` via `@terreno/api-health`.
+
+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/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/57.21.0/explanation/example-coverage.md

@@ -0,0 +1,49 @@
+# 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. |
+| UI blocks | yes — `uiBlocks` with `repair: true`, `exportDataset`, and the opt-in `scaleStepper` and `toggleChecklist` callbacks in `example-backend/src/ai/hostActions.ts`, wired from `example-backend/src/api/ai.ts`; `todoStats` in `example-backend/src/ai/tools.ts` stores a `ref` dataset; `findPhotos` in the same file cites the generated photo library, and `example-backend/src/api/photoLibrary.ts` signs its URLs | yes — `example-frontend/app/(tabs)/ai.tsx` (`uiBlocks`, dataset and action hooks, `hostActions` includes `exportDataset`, `scaleStepper`, and `toggleChecklist`, `resolveImage` resolves `file:` photo ids through `useLazyPhotoLibraryUrlQuery`) | e2e mocks a document with one inline and one `ref` chart. A second e2e test stores the Sunday roast reply (`blocks/src/fixtures/golden/sunday-roast.yaml` with `file:` photo ids) in a real `GptHistory`, streams it from the mocked model, and runs the stepper and checklist through the real `POST /gpt/actions`; photo URLs come from the real `GET /photoLibrary/:id/url`, and only the image download is stubbed (`example-frontend/e2e/helpers/seedGptHistory.ts`). Steps: [agent-ui-blocks.md](../how-to/agent-ui-blocks.md). |
+| Agent asks | yes — `asks: {approvals}` in `example-backend/src/api/ai.ts`, with the per-request `deleteCompletedTodos` approval tool from `example-backend/src/api/todoTools.ts`; it also passes `chat` to `addGptHistoryRoutes` for the headless `pendingAsks` and `turn` endpoints; keyless scripted agent with short compact-surface replies in `example-backend/src/api/demoAgent.ts` | yes — `example-frontend/app/(tabs)/ai.tsx` (`onAskSubmit`, `askErrors`), helpers in `example-frontend/lib/gptAsks.ts` | Without `GEMINI_API_KEY`, "Help me pick a plan" asks a `choice` in chat, "Pick toppings" asks a `select: "many"` `choice` with an Other field, "Send the weekly report" and "Archive old chats" ask a `confirm` (the second `destructive`), "Draft an announcement" asks a `markdown` edit of a draft, "Fill in the invoice details" asks a `form` with eight typed fields, "Upload a receipt" asks for `files`, sent as uploads when `GCS_BUCKET` is set and as data URLs otherwise, and "Delete my completed todos" calls `deleteCompletedTodos`, which runs only after the user approves the server's destructive approval card. e2e: `example-frontend/e2e/ai-chat.spec.ts`. Small clients: the curl walkthrough in the how-to and the demo's watch-sized `SimpleAskCard` story. Steps: [agent-ui-asks.md](../how-to/agent-ui-asks.md). |
+| 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)/documents.tsx` (Consents section), admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Seeded examples are drafts, so fresh databases do not interrupt sign-in. Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
+| What's new banner | n/a — generated from `CHANGELOG.md` by `bun run whats-new:generate` | yes — `WhatsNewBanner` in `example-frontend/components/SyncTodosScreen.tsx`, data in `example-frontend/constants/whatsNew.generated.json` | `bun run check:whats-new` keeps the data in sync with each release. |
+| File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/documents.tsx` (Files section, every signed-in user, 1 upload / IP / min), `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. Deployed bucket is terraform-managed (`google_storage_bucket.example_documents`). |
+| 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. |
+| List/detail layout | n/a — reuses the synced todos | yes — `example-frontend/app/todo-browser/` (`ListDetailLayout` group, opened from the todos screen's Browse button), list in `example-frontend/components/TodoBrowserList.tsx` | Phones push each todo; at 768px and wider the list stays on the left. e2e: `example-frontend/e2e/todo-browser.spec.ts` (phone, tablet, deep link, resize, keyboard). The demo inbox at `demo/app/demo/list-detail/` shows the same layout with static data. Steps: [build-list-detail-screens.md](../how-to/build-list-detail-screens.md). |
+| SyncDB diagnostics | n/a | yes — `debug` registration in `example-frontend/store/syncdb.ts`, debugger UI at `example-frontend/app/syncdb-debug.tsx` | `terreno-mcp-local` can inspect, snapshot/compare/merge, mutate, flush, reconcile/resync, and exercise offline/conflict paths against the running development client. |
+| RBAC | yes — `example-backend/src/rbacRoles.ts` (including optional `aiObservabilityViewer` / `aiObservabilityOperator` roles), `access.ts`, `accessControl: access` on `ObservabilityApp` / `AdminApp`, `access: {resource: "todo"}` on the todo router | yes — `example-frontend/app/admin/roles.tsx` | Shipped. 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/TerrenoLabs/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/TerrenoLabs/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/57.21.0/explanation/local-first-data.md

@@ -0,0 +1,65 @@
+# Local-first data in Terreno
+
+Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
+
+## What local-first means here
+
+In `@terreno/syncdb`, a TinyBase `MergeableStore` on the device is the **UI source of truth**. When a user taps "save," the mutation applies to local state immediately and lands in a durable outbox. The client then pushes the change to `@terreno/api` over the sync protocol (socket deltas with HTTP snapshot catch-up). The server remains the **authority** for permissions, validation, and conflict resolution — but the UI does not wait on the network for every write.
+
+There is no server-first mode and no opt-in flag: if you use syncdb, you adopt this model for every synced collection.
+
+## Mental model shift
+
+| Server-first (RTK Query) | Local-first (syncdb) |
+|--------------------------|----------------------|
+| UI reads from cache filled by HTTP | UI reads from the local store |
+| Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
+| Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
+| Optimistic updates are manual and fragile | Optimistic state is the default path |
+| Conflicts are rare / ignored | Conflicts are explicit and must be resolved |
+
+Think **apply locally, then reconcile** instead of **request, wait, update cache**.
+
+## What you stop doing
+
+1. **Manual optimistic updates** — `onQueryStarted` patches, temporary IDs, and rollback logic for writes.
+2. **Write-level loading spinners** — `isLoading` on mutations for "saving…" UX; the row updates instantly.
+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 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
+
+1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`, which waits `offlineGraceMs` — 3s by default — before showing "Offline" so startup and brief socket drops do not flash it).
+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. 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`.
+6. **Collections too large to sync whole** — List them in `createSyncDb({queryCollections})`. They skip snapshot bootstrap; screens load server-filtered *query windows* (`useWindowQuery`) from the `modelRouter` list endpoint. A window stores only membership (ordered ids); rows live once in the shared entity table. Overlapping windows therefore share rows — one delta updates both views — while each view lists only its own query's members, plus cached rows that newly match its `where` inside the loaded range. Live deltas still arrive on the user's normal streams; windows on screen refetch on reconnect to cover deltas missed offline.
+
+## First load and reconnects
+
+A fresh device has to download every row the user can see before the UI is complete. The
+client asks for all of the user's streams in one batched request per round, writes each
+round while the next one downloads, and writes rows in small chunks so the screen stays
+responsive. Reconnects use the same path: when nothing changed, catching up costs two
+requests however many collections the app syncs. Collections too large to download whole
+belong in `queryCollections` instead.
+
+## Tradeoffs
+
+**Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
+
+**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
+
+Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
+
+## Related docs
+
+- [syncdb reference](../reference/syncdb.md) — API ground truth
+- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
+- [Authentication architecture](authentication.md) — Better Auth + socket sessions

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

@@ -0,0 +1,195 @@
+# Loop engineering
+
+Terreno separates engineering method from orchestration:
+
+```text
+                 LOOP
+       orchestrate / persist / wait
+          retry / stop / escalate
+                  |
+                  v
+               GROW
+               shape
+                  |
+                  v
+         PICK ⇄ ROAST  (inner loop)
+         one task, prove it, next task
+                  |
+                  v
+               BREW
+              submit
+                  |
+                  v
+              TASTE
+             react once
+```
+
+Repository knowledge composes underneath every invocation:
+
+```text
+lifecycle stage + project skills + IP/task/state + evidence
+```
+
+## Why fresh invocations
+
+One enormous agent context accumulates assumptions, stale external state, and confidence
+in its own implementation. The lifecycle instead makes every stage reconstructable from
+durable artifacts. Pick can retry from exact Roast evidence; Roast can verify without the
+implementer's assumptions; Taste can react to the current PR head rather than an old
+green result.
+
+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 fetches latest `master` (merging it only when needed), 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; 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 on every discovered host, mergeability, reviews, bounded fixes |
+
+Roast is not another implementation review. It independently proves or disproves
+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 fetches latest
+`master` (merging it only when needed), 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
+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 plugin install provide Pick/Roast plus backend API, test-environment,
+UI, and real-app verification knowledge in consumer projects.
+
+### Terreno's bundled skill layer
+
+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`, `verify-ui-changes` |
+| Testing | `terreno-test-setup`, `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests`, `backfill-regression` |
+| AI/prompts | `ai-prompt-governance` — new features also follow [Develop an AI feature](../how-to/ai-feature-development.md) |
+| Docs/submission | `update-docs`, `backfill-user-guide`, 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
+catalog on every invocation.
+
+## State and evidence
+
+The IP remains the design/scope source of truth. The task file remains the execution
+checklist. Lightweight loop-owned state stores only current stage/attempt/task,
+branch/head/PR, the previous structured result, artifacts, attempted approaches, and next
+transition.
+
+The fallback state location is `.terreno/pipeline/<slug>.json`; the outer loop preserves
+or transports it and Brew excludes it from commits unless repository policy says
+otherwise. Stage results follow the plugin's JSON-schema-backed YAML contract and never
+contain chain-of-thought or transcripts.
+
+## Commits and pushes
+
+Every pushed commit starts a full CI run. Harnesses such as Cursor cloud agents push
+every commit automatically, so commit count turns directly into CI runs. Before these
+rules, one 30-commit dashboard PR had ten "mark slice roasted" commits and ten "harden"
+follow-ups, and `ui-ci` stayed red on every commit after the first.
+
+- One behavior-scoped commit per task, after Roast `PASS`: code, tests, docs, and the
+  task-file mark together. Roast-driven fixes fold into that commit.
+- Progress lives in execution state, not in standalone task-file commits.
+- Pick and Roast never push. Brew pushes once. Taste pushes at most once per reaction.
+- Pick does not continue on a head whose product CI shows a branch-caused failure.
+- Pick lists a behavior's edge cases before coding, so Roast proves them instead of
+  discovering them.
+- Roast runs the gate CI will run (root `prepush`, which mirrors the triggered CI jobs),
+  not only the task's test file.
+- Taste fetches `master` before every push but merges it only when the PR conflicts, a
+  failure traces to base drift, or the branch is otherwise merge-ready.
+
+## Direct invocation
+
+Outer loops (`terreno-planning-loop`, `terreno-taste-sweep`) consume Taste `PENDING`
+and invoke Taste again. When a human invokes Taste directly, no loop is waiting, so a
+`PENDING` would only tell them to come back later. In that case Taste uses
+**standalone entry**: it waits in-process with native watches and reacts again. It
+stops on `PASS`, `BLOCKED`, or `FAIL`, or after 3 fix pushes or 3 hours of waiting,
+which ends as `BLOCKED` with one concrete human action. A directly invoked Brew
+starts Taste as its next stage instead of exiting.
+
+## Retry and stop rules
+
+- 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.
+- 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 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/TerrenoLabs/terreno/tree/master/plugins/terreno-planning/references).
+