@terreno/mcp 58.0.0-beta.3 → 58.0.0-beta.4

package/dist/docs/versioned/57.22.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/dist/docs/versioned/57.22.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/dist/docs/versioned/57.22.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).
+

package/dist/docs/versioned/57.22.0/explanation/organizations.md

@@ -0,0 +1,125 @@
+# How organization tenancy works
+
+Terreno treats organizations as an optional framework primitive. Existing
+single-tenant apps do not pay a migration or authorization cost; multi-tenant
+apps opt in at the access, application, model, and admin layers. New apps
+generated by `create-terreno-app` opt in by default.
+
+## Identity and authorization layers
+
+Platform and tenant authority are separate:
+
+| Authority | Storage | Scope |
+| --- | --- | --- |
+| `superadmin` | `User.roles` | Every framework permission |
+| `operator` | `User.roles` | Organization directory and every organization |
+| `org-admin` | `Membership.roleName` | One organization |
+| `member` | `Membership.roleName` | One organization; app permissions decide actions |
+
+`user.admin` does not imply operator access. `org-admin` is deliberately not a
+global RBAC role: putting it on `User.roles` grants nothing. During an
+organization request, `createAccess({organizations: true})` adds the current
+active Membership grants to the normal role permissions.
+
+## Request context
+
+Tenant routes resolve `X-Organization-Id` after authentication. An operator or
+superadmin may enter any organization but must choose one. An org-admin with
+exactly one administered organization may omit the header; Terreno infers it.
+Ambiguous or unauthorized context fails before model queries run.
+
+The resolved organization and membership are stored in AsyncLocalStorage as
+well as `req.organization` / `req.membership`. This lets `OrgQueryFilter` add
+the server-owned organization id without trusting a client query parameter.
+
+## Isolation boundaries
+
+Tenant isolation uses multiple checks rather than one convention:
+
+1. `orgContextMiddleware({required: true})` rejects missing or unauthorized context.
+2. `OrgQueryFilter` ANDs the selected organization into list and search queries.
+3. `Permissions.IsOrganizationMember` rejects cross-org object reads and writes.
+4. Create hooks overwrite client-supplied organization ids.
+5. `orgScopedPlugin` rejects any post-create change to `organizationId` (REST, admin, sync, direct save).
+6. Sync scopes resolve active Membership rows and partition streams by organization.
+
+`AdminApp({organizations: true})` applies these boundaries automatically to
+admin models whose schema contains `organizationId`. Models without that path
+remain platform-scoped.
+
+Adding, changing, or removing a membership through `POST` / `PATCH` / `DELETE
+/orgs/:id/members` clears that user's cached permissions, so a new org-admin can open the
+admin page (and a demoted or removed one loses it) on their next request instead of after
+the permission cache's 30-second TTL. Disabling (`PATCH /orgs/:id` with `disabled: true`) or
+deleting (`DELETE /orgs/:id`) an organization suspends all of its memberships and clears the
+cached permissions of every member the same way.
+
+## Disabled organizations
+
+When `Organization.disabled` is `true`, tenant context and membership mutations
+stop, but operators can still manage the organization record itself:
+
+| Surface | Disabled org behavior |
+| --- | --- |
+| `orgContextMiddleware` / inferred org context | 403 `Organization is disabled` |
+| `GET /orgs/mine` | Disabled orgs omitted from the switcher list |
+| `GET /orgs` (operator directory) | Disabled orgs still listed |
+| `GET` / `PATCH /orgs/:id` | Allowed (operators use `PATCH` with `disabled: false` to re-enable) |
+| `POST` / `PATCH` / `DELETE /orgs/:id/members` | 403 while disabled |
+| Soft-deleted orgs | Still 404 everywhere |
+
+Disabling or deleting an organization suspends its memberships. Re-enabling does
+not automatically reactivate them.
+
+## Member recovery
+
+When the app registers `AccountSecurityApp`, an org-admin can help a locked-out member without
+platform staff. `OrgsApp` mounts the same recovery handlers the platform uses at
+`/orgs/:orgId/members/:userId/security/*`, behind an org authorizer.
+
+- **Reach.** An org-admin may act on any active member of their org, even one who also belongs
+  to other orgs (D2). A suspended member, or a user outside the org, answers `404`, so the routes
+  do not reveal who exists elsewhere.
+- **Guards.** Platform staff (`superadmin`, `operator`) and `admin: true` users are never reachable
+  through an org (D3). Neither is anyone who holds a permission the org-admin lacks, nor the
+  org-admin themselves (D9). Disabled orgs answer `403`.
+- **Disable means suspend.** One org must not lock a user out of every other org, so the org
+  path has no account disable. It offers `suspend-membership` instead, which suspends the
+  membership in that org only (Q8). The user still signs in and keeps their other orgs.
+  `User.disabled` and `issue-sign-in-link` stay platform-only.
+- **Attach-then-act.** An org-admin can attach any existing user by email
+  (`POST /orgs/:id/members`). Every org-admin action is audited with the org's id and emails the
+  user, so they learn about it ([notifications](../reference/account-security.md#notifications);
+  the org is named only with `notifications.includeOrgName`). Apps that want more can set
+  `orgRecovery.minMembershipDays` to refuse members who joined too recently.
+- **Platform staff** holding `user:manageSecurity` pass the org checks. The target must still be
+  an active member of the org in the path. Their reach check is the platform one: both sides are
+  resolved outside the organization, so an org-only grant does not put the member out of reach.
+
+See [Recover a locked-out user](../how-to/recover-locked-out-user.md) for who can do what, and
+the [account security reference](../reference/account-security.md#org-admin-routes) for every
+response.
+
+## Why organizations are optional
+
+Automatically registering routes, roles, or Mongoose models would change
+existing apps merely because they upgraded `@terreno/api`. Instead:
+
+- `createAccess` omits Membership grants and the `operator` seed unless
+  `organizations: true`;
+- `TerrenoApp` does not mount `/orgs` unless organizations are enabled;
+- `AdminApp` does not scope models unless organizations are enabled;
+- Organization and Membership Mongoose models register lazily on first use.
+  Apps add fields to `Organization.settings` with `createOrganizationSettingsSchema`
+  and `registerOrganizationSettings`, not by replacing the Organization model.
+
+This keeps upgrades backward compatible while letting bootstrap generate
+multi-tenant-ready apps.
+
+## Related
+
+- [Add organizations](../how-to/add-organizations.md)
+- [Recover a locked-out user](../how-to/recover-locked-out-user.md)
+- [API reference](../reference/api.md#organizations)
+- [Admin backend reference](../reference/admin-backend.md#organization-scoping)
+- [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)

package/dist/docs/versioned/57.22.0/explanation/planning-plugins.md

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