@terreno/mcp 57.0.0 → 57.1.0

package/src/docs/upgrades/56.0.0-beta.2.md

@@ -38,6 +38,40 @@ encrypted web persistence). Install as `@terreno/syncdb@beta` (or the exact vers
 `@terreno/syncdb` does not replace the generated OpenAPI SDK, Better Auth wiring, or
 feature flags — only collection sync/CRUD offline paths.
 
+## `@terreno/rtk` deprecated for data sync
+
+As of **56.0.0**, RTK Query hooks for **collection CRUD** are deprecated. Migrate to
+`@terreno/syncdb` using the migration guide above. Keep `@terreno/rtk` for:
+
+- `bun run sdk` / `store/openApiSdk.ts` (non-synced routes)
+- Better Auth session Redux (`generateBetterAuthSlice`)
+- Feature flags and socket helpers
+
+`@terreno/rtk` remains published through the current major line and will not ship in the
+next major release.
+
+### Read hook (before → after)
+
+```typescript
+// Before — RTK Query
+const {data, isLoading} = useGetTodosQuery({completed: false});
+
+// After — syncdb
+const todos = useQuery<Todo>("todos", {filter: (t) => !t.completed});
+```
+
+### Write hook (before → after)
+
+```typescript
+// Before — RTK Query
+const [createTodo, {isLoading}] = usePostTodosMutation();
+await createTodo({title, completed: false}).unwrap();
+
+// After — syncdb
+const {create} = useMutate("todos");
+create({data: {title, completed: false}});
+```
+
 ## `excludeArchivedPlugin` now filters `findOne`
 
 `excludeArchivedPlugin` applies the same archived filter to `findOne` that it already

package/src/docs/upgrades/57.1.0.md

@@ -0,0 +1,126 @@
+# 57.1.0
+
+Terreno packages move in lockstep. Bump every `@terreno/*` dependency to `57.1.0`, then:
+
+```bash
+bun add @terreno/ui @terreno/api @terreno/rtk
+# optional
+bun add @terreno/syncdb @terreno/admin-frontend @terreno/comms
+```
+
+- `bun run compile` and `bun run lint` at the app root
+- `cd <your frontend> && bun run sdk` after any `@terreno/api` route or model surface change
+
+This is a minor on the Expo SDK 57 line. No Expo upgrade is required if you are already on `57.0.0`.
+
+## `@terreno/rtk` data sync is deprecated
+
+Collection CRUD through `@terreno/rtk` is deprecated (first called out for `56.0.0`). The package still publishes through this major and remains required for the OpenAPI SDK, Better Auth Redux, feature flags, and sockets. It will not ship in the next major.
+
+Migrate collection screens to [`@terreno/syncdb`](../../../docs/reference/syncdb.md) using [migrate-rtk-to-syncdb.md](../../../docs/how-to/migrate-rtk-to-syncdb.md). New apps from `terreno_bootstrap_app` now scaffold Better Auth + syncdb instead of JWT `generateAuthSlice`.
+
+Typed collection hooks can be generated with the `terreno-syncdb-codegen` bin of `@terreno/syncdb` (not a separate package):
+
+```bash
+bunx terreno-syncdb-codegen --schema http://localhost:4000/openapi.json --out store/syncDbSdk.ts
+```
+
+## RBAC (`@terreno/api`)
+
+RBAC is opt-in. If you do not call `createAccess` / `accessControl`, skip this section except the `RbacRoleModel` singleton removal if you imported those names.
+
+### Register models on your connection
+
+Importing `@terreno/api` no longer registers `RbacRole` / `RbacAudit` on the default mongoose connection. The `RbacRoleModel` / `RbacAuditModel` **value** singletons are gone; the `RbacRoleModel` **type** remains.
+
+```typescript
+// Before
+import {RbacRoleModel} from "@terreno/api";
+await RbacRoleModel.find();
+
+// After
+import {createAccess, createRbacRoleModel} from "@terreno/api";
+import mongoose from "mongoose";
+
+const access = createAccess({
+  connection: mongoose.connection,
+  statements: appStatements,
+  userModel: User,
+});
+// or, in scripts/tests only:
+const RbacRole = createRbacRoleModel(mongoose.connection);
+```
+
+See `example-backend/src/access.ts`.
+
+### Fail closed
+
+- `createView: "deny"` and unknown field-view names deny instead of granting a full mask.
+- Nested omits clone documents; write masks honor dotted paths; bulk create and array mutations use the same write mask as single-document writes.
+- Admin CRUD for a resource missing from statements fails closed (list/read, search, and writes).
+- Permission-source refresh with `staleOnFailure: "deny"` (default) keeps last-cached **deny** grants; additive `roles` / `permissions` from that source are omitted.
+
+If a previously unknown view name silently allowed a full mask, tighten statements or name the view.
+
+### AdminApp + `admin:access`
+
+`admin:access` is no longer enough for model CRUD. Each resource needs its list/read/create/update/delete actions. Framework statements now include `featureFlag`, `consentForm`, and `consentResponse`.
+
+| Action | Required permission |
+| --- | --- |
+| Admin model CRUD | Resource verb **and** `admin:access` |
+| `POST /admin/background-tasks` | `admin:runScripts` |
+| Version-config GET / PUT | `configuration:read` / `configuration:update` |
+| Change User `admin` (RBAC on) | `rbac:assignRoles` **and** an actor who already has the legacy admin flag (`rbac:manageRoles` is not a substitute) |
+| Assign / unassign roles | Actor already holds the target user's current permissions |
+
+The seeded `auditor` role no longer receives `admin:access` from read-only expansion.
+
+Without RBAC, admin User CRUD may still set `admin`. With RBAC, `roles` go through `RoleManager.assign`. Echoed unchanged `admin` values on create/update are allowed.
+
+### Privilege fields are stripped on self-service writes
+
+Signup, `PATCH /auth/me`, and ordinary User modelRouter / sync / MCP writes drop `admin`, `roles`, and `organizationIds`. Change organization membership through a privileged server path, not self-service.
+
+`example-backend` `backfillAdmins` is a dry run unless `RBAC_BACKFILL_ADMINS=true`. Live production admin script resets require `ALLOW_ADMIN_DB_RESET=true`.
+
+### Custom `modelRouter` actions
+
+`runActionPermissions` **combines** legacy `action.permissions` with RBAC (it does not replace them). Actions without `access` inherit the router's `access.resource` and the mapped CRUD verb (`instance` POST → `update`, `collection` POST → `create`). Set `access` on custom actions that must not inherit, or they follow that mapping.
+
+MCP and SyncDB registries use TerrenoApp-injected `accessControl` (not pre-build legacy permission arrays). User `roles` on modelRouter writes are dropped when `accessControl` is set.
+
+### Audit
+
+`RoleManager` writes `RbacAudit` (with `permissionDelta`) on create/update/remove/assign/unassign. HTTP `rbacRouter` no longer writes a second row. Pass `auditSink` (one function or an array) to fan into an app log; `persistAudit: false` skips the built-in collection and then requires at least one sink.
+
+Assignment **preview** does not write denied-assign rows. Denied mutation audits are stored only for the escalation `403` (`Cannot grant permissions you do not hold`).
+
+## Admin frontend
+
+`@terreno/admin-frontend` is now provider-backed: wrap screens in `AdminProvider`, use the widget registry / `AdminScreenRouter`, and prefer `AdminRolesField` / `AdminRolesList` over raw role arrays. The sidebar groups Scripts, Roles, Version, Audit Log, Feature Flags, and Configuration under **Platform**. Empty sections hide.
+
+If you still pass the deprecated `customScreens` prop, migrate to the widget registry (`mergeWidgetRegistry`, `BUILT_IN_WIDGET_REGISTRY`).
+
+## MCP on `modelRouter`
+
+Opt a model in with `mcp` on `modelRouter`. Tools are served at `POST /mcp` with the same permissions, filters, and hooks as REST. Lifecycle hooks receive a stub request from `createMCPRequest` (`isMCPRequest: true`); they do not see forwarded HTTP headers. Register extra tools with `registerMCPTool`. `@terreno/rtk` adds `useMCPTools()` and `useTerrenoChat()`.
+
+## Comms
+
+Optional `SendGridMailProvider` lives at `@terreno/comms/adapters/sendgrid` (peer `@sendgrid/mail`). Phase 1 hooks: `beforeSend` may mutate or cancel; `onRetry` stays `(context, result)` with `context.attempt`. Push prune treats `errorClass: "permanent"` like `isPermanentFailure`.
+
+## `@terreno/ui`
+
+React Native Web `shadow*` and `props.pointerEvents` deprecation warnings are fixed inside the library. No app code change is required unless you copied those patterns locally — use `style.pointerEvents` and `boxShadow`.
+
+`Host` and `Portal` are exported from `@terreno/ui` (replacing `react-native-portalize`).
+
+## Verification
+
+- Compile and lint the app against `@terreno/*@57.1.0`.
+- If you imported `RbacRoleModel` as a value, switch to `createAccess` / `createRbacRoleModel`.
+- If RBAC is on, confirm admin list/create still works for each model and that `admin:access`-only roles cannot mutate resources.
+- Confirm signup / `PATCH /auth/me` cannot set `admin`, `roles`, or `organizationIds`.
+- If you use collection RTK Query hooks, start the syncdb migration (see above).
+- Regenerated OpenAPI SDK after enabling `mcp` or new admin/RBAC routes.

package/src/docs/versioned/next/README.md

@@ -16,16 +16,28 @@ Documentation for the Terreno monorepo: shared packages for full-stack applicati
 |---------|-------------|
 | [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
 | [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
 | [@terreno/syncdb](reference/syncdb.md) | Local-first data layer (offline sync, conflicts) |
+| [@terreno/ai](reference/ai.md) | AI service, GPT routes, request logging |
 | [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
 | [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
+| [@terreno/admin-spa](reference/admin-spa.md) | Standalone admin SPA + Express serve plugin |
 | [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
-| [@terreno/comms](reference/comms.md) | Pluggable communications providers and delivery logging |
+| [@terreno/comms](reference/comms.md) | Pluggable communications providers |
+| [@terreno/feature-flags](reference/feature-flags.md) | Feature flags and A/B testing plugin |
 | [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
+| [@terreno/test](reference/test.md) | Bun test helpers and in-memory MongoDB |
+
+### Legacy
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/rtk](reference/legacy/rtk.md) (deprecated) | RTK Query utilities — superseded by syncdb for data sync; still used for OpenAPI SDK, auth, and feature flags during migration |
+
+**Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
 
 ## Quick links
 
 - [Getting started](tutorials/getting-started.md)
+- [Local-first data](explanation/local-first-data.md)
 - [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
-- [.cursorrules](../.cursorrules) — Project and code style rules
+- [ROADMAP.md](../ROADMAP.md) — Public roadmap

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

@@ -10,6 +10,9 @@ Understanding-oriented documentation: concepts, architecture, and context.
 
 ## Contents
 
+- [Local-first data](local-first-data.md) — Why the local store is the UI source of truth
+- [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
+- [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add FlourishHealth/terreno`
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
 - [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
 - [Configuration system](configuration-system.md) — Runtime configuration with database persistence

package/src/docs/versioned/next/explanation/admin-consent-migration.md

@@ -0,0 +1,15 @@
+# Consent admin migration audit
+
+The example keeps specialized consent routes where generic model screens do not cover the workflow.
+
+| Route file | Disposition | Reason |
+| --- | --- | --- |
+| `consent-forms/index.tsx` | Keep as a hand-written route | Adds consent-specific list navigation and publishing workflow. |
+| `consent-forms/create.tsx` | Keep as a hand-written route | Uses `ConsentFormEditor` for localized content, AI generation, and consent validation. |
+| `consent-forms/[id].tsx` | Keep as a hand-written route | Supports publish/version behavior beyond generic CRUD editing. |
+| `consent-responses/index.tsx` | Keep as a hand-written route | Presents consent-response-specific navigation. |
+| `consent-responses/[id].tsx` | Keep as a hand-written route | Uses `ConsentResponseViewer` for signatures, snapshots, and audit details. |
+
+`ConsentApp.adminContribution()` still contributes generic ConsentForm and ConsentResponse models.
+Those models provide searchable tables and field widgets, while Expo Router gives the explicit
+routes above precedence for the richer consent workflows.

package/src/docs/versioned/next/explanation/admin-plugin-frontend.md

@@ -0,0 +1,12 @@
+# Admin plugin frontend widgets
+
+Backend plugins contribute stable widget IDs through `adminContribution()`. Their React
+implementations ship from `@terreno/admin-frontend`, under `src/widgets/`.
+
+This keeps the first-party integration in one frontend package and avoids making backend-only
+packages depend on React Native. The built-in registry includes consent field widgets, feature
+flag home widgets, and Documents/AI custom screens. Hosts can override any ID through
+`AdminProvider.widgets`.
+
+Third-party plugins should publish their own frontend package and ask the host to spread its
+registry into `AdminProvider`; `@terreno/admin-frontend` only owns first-party Terreno widgets.

package/src/docs/versioned/next/explanation/announcements/rtk-deprecation.md

@@ -0,0 +1,29 @@
+# RTK deprecation announcement (draft)
+
+**Do not post until maintainers review.** Target: GitHub Discussions → Announcements.
+
+---
+
+## `@terreno/rtk` data sync is deprecated — migrate to `@terreno/syncdb`
+
+Starting with **56.0.0**, Terreno's default frontend data path is **local-first** via [`@terreno/syncdb`](https://github.com/FlourishHealth/terreno/blob/master/docs/reference/syncdb.md). Collection reads and writes apply to an on-device store first; the server reconciles over the sync protocol. This replaces RTK Query hooks for CRUD lists and mutations.
+
+### What changed
+
+- **New:** `@terreno/syncdb` — `useQuery`, `useMutate`, offline outbox, conflict resolution, sync status UX
+- **Deprecated:** RTK Query hooks for synced collections (`useGetTodosQuery`, `usePostTodosMutation`, manual optimistic updates)
+- **Unchanged:** `bun run sdk` still generates the OpenAPI SDK for auth, profile, admin, AI, and other non-synced routes
+
+### What you need to do
+
+1. **By next major:** move collection screens from RTK Query to syncdb. `@terreno/rtk` will not publish in the next major line.
+2. **Support window:** `@terreno/rtk` continues to publish with a deprecation notice through the **current major** (56.x beta and stable 0.x).
+3. **Recommended order:** migrate to **Better Auth** first, then syncdb per screen ([migration guide](https://github.com/FlourishHealth/terreno/blob/master/docs/how-to/migrate-rtk-to-syncdb.md)).
+
+### Why local-first
+
+Instant UI, durable offline writes, and simpler screen code — at the cost of explicit conflict and sync-status handling. See [local-first data](https://github.com/FlourishHealth/terreno/blob/master/docs/explanation/local-first-data.md).
+
+### Questions
+
+Open a thread in [Docs feedback](https://github.com/FlourishHealth/terreno/discussions/categories/docs-feedback) or reply here.

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

@@ -1,30 +1,59 @@
 # Authentication Architecture
 
-Understanding how authentication works in @terreno/api — from JWT tokens to OAuth strategies to automatic token refresh.
+Understanding how authentication works in @terreno/api — Better Auth sessions for new apps, with JWT/Passport documented for legacy consumers.
 
 ## Overview
 
-@terreno/api provides two complete authentication systems to choose from:
+**Better Auth is the default path** for new Terreno apps. It provides session-based authentication with MongoDB storage, built-in social OAuth (Google, GitHub, Apple), and clean integration with `@terreno/syncdb` (`betterAuthAdapter`, `RealtimeApp` socket sessions).
 
-**JWT/Passport Authentication (Default)**
-- **JWT (JSON Web Tokens)** for stateless session management
-- **Passport.js** for authentication strategy management
-- **Multiple strategies**: Email/password, GitHub OAuth, Anonymous
-- **Automatic token refresh** to maintain long-lived sessions
-- **Token storage utilities** for secure frontend storage (via @terreno/rtk)
+Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On the client, use `createBetterAuthClient` + `generateBetterAuthSlice` from `@terreno/rtk` for session Redux state, then wire `betterAuthAdapter` into `createSyncDb`.
 
-**Better Auth (Optional)**
-- **Session-based authentication** with MongoDB storage
-- **Built-in OAuth providers**: Google, GitHub, Apple
-- **Modern OAuth 2.0 flows** with PKCE
-- **Automatic session management** via cookies
-- **Redux integration** for session state (via @terreno/rtk)
+**JWT/Passport (legacy)** remains supported through the current major release line for existing deployments. It uses stateless tokens, Passport strategies (email/password, GitHub OAuth, anonymous), and manual token refresh via `@terreno/rtk`. New projects should not start on JWT unless they have a specific requirement (custom token contracts, non-cookie clients, or a phased migration).
 
-Choose your authentication provider via `AUTH_PROVIDER` environment variable. Both systems can run in parallel, allowing gradual migration.
+Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
+
+## When to choose which
+
+| Choose Better Auth | Stay on JWT (legacy) |
+|--------------------|----------------------|
+| New app or greenfield screen | Existing production JWT deployment |
+| Social login (Google, GitHub, Apple) | Custom JWT payload requirements |
+| `@terreno/syncdb` local-first data | Non-cookie API clients only |
+| Socket sessions via `RealtimeApp` | Gradual migration in progress |
+
+**Setup:** [Configure Better Auth](../how-to/configure-better-auth.md). **Data layer:** migrate auth before or with syncdb — see [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) §7.
 
 ## Authentication Strategies
 
-### Email/Password (Local Strategy)
+### Better Auth (default)
+
+Modern session-based authentication with built-in social OAuth support.
+
+**Flow:**
+1. Configure Better Auth with `AUTH_PROVIDER=better-auth` and register `BetterAuthApp`
+2. User chooses social provider (Google, GitHub, Apple) or email/password
+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
+
+**Key properties:**
+- Session-based (cookies / bearer session) vs. stateless JWT
+- Built-in OAuth providers with PKCE
+- `betterAuthAdapter` for syncdb socket auth
+- `sync:auth-expired` socket event when the session is no longer valid
+
+**Endpoints (when enabled):**
+- `POST /api/auth/signup/email` — Email/password signup
+- `POST /api/auth/signin/email` — Email/password signin
+- `GET /api/auth/signin/{provider}` — Initiate OAuth flow (google, github, apple)
+- `GET /api/auth/callback/{provider}` — OAuth callback handler
+- `POST /api/auth/signout` — Sign out session
+- `GET /api/auth/session` — Get current session
+
+**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
+
+### Email/Password (JWT / Local Strategy — legacy)
 
 Traditional username/password authentication using `passport-local-mongoose`.
 
@@ -39,7 +68,7 @@ Traditional username/password authentication using `passport-local-mongoose`.
 - `POST /auth/signup` — Create new user account
 - `POST /auth/login` — Authenticate and receive tokens
 
-### GitHub OAuth Strategy
+### GitHub OAuth Strategy (JWT — legacy)
 
 OAuth 2.0 authentication with GitHub.
 
@@ -60,45 +89,7 @@ OAuth 2.0 authentication with GitHub.
 
 **Learn more:** [How to add GitHub OAuth](../how-to/add-github-oauth.md)
 
-### Better Auth Strategy
-
-Modern session-based authentication with built-in social OAuth support. Better Auth runs **alongside** JWT/Passport authentication as an optional alternative.
-
-**Flow:**
-1. Configure Better Auth with `AUTH_PROVIDER=better-auth`
-2. User chooses social provider (Google, GitHub, Apple) or email/password
-3. Backend redirects to OAuth provider or validates credentials
-4. Better Auth creates session in MongoDB
-5. Frontend receives session cookie
-6. Session middleware populates `req.user` for subsequent requests
-
-**Key differences from JWT auth:**
-- Session-based (cookies) vs. stateless (tokens)
-- Built-in OAuth providers vs. custom Passport strategies
-- Automatic session management vs. manual token refresh
-- Modern OAuth 2.0 flows with PKCE
-
-**Use Better Auth when you need:**
-- Social login (Google, GitHub, Apple)
-- Session-based authentication
-- Modern OAuth 2.0 flows
-
-**Use JWT authentication when you need:**
-- Stateless authentication
-- Simpler token-based auth
-- No social login required
-
-**Endpoints (when enabled):**
-- `POST /api/auth/signup/email` — Email/password signup
-- `POST /api/auth/signin/email` — Email/password signin
-- `GET /api/auth/signin/{provider}` — Initiate OAuth flow (google, github, apple)
-- `GET /api/auth/callback/{provider}` — OAuth callback handler
-- `POST /api/auth/signout` — Sign out session
-- `GET /api/auth/session` — Get current session
-
-**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
-
-### Anonymous Strategy
+### Anonymous Strategy (JWT — legacy)
 
 Allows limited access without authentication.
 
@@ -116,7 +107,9 @@ modelRouter(Model, {
 });
 ``````
 
-## JWT Token System
+## JWT Token System (legacy)
+
+> JWT/Passport auth is **legacy**. It remains supported through the current major line but is not the recommended path for new apps. Prefer Better Auth above.
 
 ### Token Types
 
@@ -435,4 +428,4 @@ router.post("/webhook", asyncHandler(async (req, res) => {
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Create a model](../how-to/create-a-model.md)
 - [API reference](../reference/api.md)
-- [@terreno/rtk reference](../reference/rtk.md)
+- [@terreno/rtk reference (legacy)](../reference/legacy/rtk.md)

package/src/docs/versioned/next/explanation/local-first-data.md

@@ -0,0 +1,52 @@
+# 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** endpoints: `/auth/me`, admin RPC, AI routes, and anything that should stay request/response.
+
+## 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`).
+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.
+
+## 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/next/explanation/loop-engineering.md

@@ -0,0 +1,117 @@
+# Loop engineering
+
+Terreno separates engineering method from orchestration:
+
+```text
+                 LOOP
+       orchestrate / persist / wait
+          retry / stop / escalate
+                  |
+                  v
+               GROW
+               shape
+                  |
+                  v
+               PICK
+               build
+                  |
+                  v
+              ROAST
+               prove
+                  |
+                  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.
+
+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.
+
+## 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 |
+| 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 |
+
+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.
+
+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 Pick method compose with backend API and test-environment knowledge,
+while Roast composes with UI conventions and real-app verification.
+
+### Terreno's current project-skill layer
+
+The canonical sources remain under `.rulesync/skills/` and are generated for supported
+agents. The current 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` |
+| AI/prompts | `ai-prompt-governance` |
+| Docs/submission | `update-docs`, `commit`, `create-pr`, `fix-conflicts` |
+| 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.
+
+## Retry and stop rules
+
+- Roast failure returns exact expected/actual evidence to a fresh Pick.
+- Engineering retries require a new hypothesis and preserve failed approaches.
+- Taste `PENDING` lets the outer loop wait and invoke fresh Taste against current state.
+- Human decisions are `BLOCKED`, never arbitrary retries.
+- Taste `PASS` requires all current-head checks 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/repository-settings.md

@@ -36,6 +36,14 @@ descriptions):
 - Require branches to be up to date before merging
 - Do not allow bypassing the above settings
 
+### CircleCI dual-run (in progress)
+
+Package CI / policy / Playwright twins live under `.circleci/` (see
+[how-to/circleci.md](../how-to/circleci.md)). **Keep requiring the existing GitHub
+Actions check names** until a twin is trusted; then add the CircleCI job name and
+remove the GHA workflow. Do not require CircleCI deploy jobs yet (deploys not
+ported).
+
 ## Merge settings
 
 **Path:** Settings → General → Pull Requests