@terreno/mcp 57.0.0-beta.1 → 57.1.0

package/dist/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/dist/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/dist/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/dist/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

package/dist/docs/versioned/next/explanation/roadmap-process.md

@@ -22,10 +22,10 @@ Discussion (Ideas/RFC)
     ▼
 Issue: Status = Shaping ─────────────────────────────┐
                                                       │  IP approved → roadmap-item
-Blend writes IP + task list  ────────────────────────┤  (sets IP field, Shaping → Planned)
+Grow writes IP + task list   ────────────────────────┤  (sets IP field, Shaping → Planned)
 (docs/implementationPlans/ + docs/tasks/)             ▼
                                           Issue: Status = Planned
-                                                      │  Roast → Cupping → Pour
+                                                      │  Pick → Roast → Brew
                                                       ▼
                                           PR: Fixes #NNN
                                                       │  merge
@@ -34,17 +34,17 @@ Blend writes IP + task list  ─────────────────
 ```
 
 The planning pipeline (the `terreno-planning` plugin) drives the design-and-build half;
-the roadmap skills drive the public-tracking half. They meet at one handoff: **Blend
+the roadmap skills drive the public-tracking half. They meet at one handoff: **Grow
 writes the IP, and once it is Approved hands off to `roadmap-item`.**
 
 | Transition | Who owns it | Authoritative artifact |
 | ---------- | ----------- | ---------------------- |
 | Idea debated and shaped | Community + maintainers | GitHub Discussion |
 | Discussion → first tracking issue (`Shaping`) | `roadmap-promote` | GitHub Issue + Project |
-| Design, scope, acceptance criteria | `terreno-1-blend` / `ip` | `docs/implementationPlans/<slug>.md` |
-| Task breakdown for implementation | `terreno-1-blend` / `ip` | `docs/tasks/<slug>.md` |
+| Design, scope, acceptance criteria | `terreno-1-grow` | `docs/implementationPlans/<slug>.md` |
+| Task breakdown for implementation | `terreno-1-grow` | `docs/tasks/<slug>.md` |
 | Approved IP → issue `Planned` + `IP` field set | `roadmap-item` | GitHub Issue + Project |
-| Implement, verify, submit, review | `terreno-2-roast` … `terreno-5-dialin` | the PR |
+| Implement, verify, submit, review | `terreno-2-pick` … `terreno-5-taste` | the PR |
 | Sprint estimates, assignees, internal-only work | Linear | Linear |
 | Public rendered list | CI (`roadmap:generate`) | `ROADMAP.md` |
 
@@ -60,7 +60,7 @@ The `terreno-planning` plugin is meant to run in any Terreno repo, including one
 Discussions and no roadmap board (Flourish, most consumer apps). There, only the design-and-build
 half applies:
 
-- **Blend** still writes the IP + task list — that dual-file model is the source of truth
+- **Grow** still writes the IP + task list — that dual-file model is the source of truth
   everywhere. It detects the absence of `.github/roadmap-fields.yml` and the `roadmap-item`
   skill and **skips the roadmap handoff** instead of inventing issues or labels.
 - Sprint execution is tracked in Linear and linked from the IP header; it is never copied
@@ -236,9 +236,9 @@ is the variable the generator reads.
 
 ## Maintainer skills
 
-Four agent skills cover the recurring roadmap work. Each one researches, proposes, and then
+Five agent skills cover the recurring roadmap work. Each one researches, proposes, and then
 **stops for a maintainer to approve** before touching GitHub — roadmap decisions are the most
-human part of the process, so none of them mutate state on their own. All four are
+human part of the process, so none of them mutate state on their own. All five are
 `disable-model-invocation`, meaning an agent will not start them on its own initiative;
 you invoke them explicitly.
 
@@ -248,6 +248,19 @@ you invoke them explicitly.
 | `roadmap-promote` | Maintainers accepted an Ideas or RFC discussion and it needs a tracked issue that links back to the thread |
 | `roadmap-item` | An approved IP needs its public tracking issue, or an existing entry's scope changed |
 | `roadmap-review` | Recurring hygiene: status drift, stale items, untriaged backlog, promotion candidates, then regenerate `ROADMAP.md` |
+| `roadmap-frontier` | A destination is too large or uncertain for one IP/context and needs a map, a small unblocked frontier, and repeated Grow → Taste delivery loops |
+
+### Huge features: frontier maps
+
+A frontier map is one low-resolution roadmap issue with an observable destination,
+resolved-decision index, current frontier, fog, and explicit out-of-scope boundary. Child
+tickets hold the detail and native blocking relationships. Work only the **frontier**:
+open, unblocked, unclaimed tickets.
+
+Decision tickets resolve one question. Delivery tickets link one approved IP/task pair and
+run the complete planning pipeline. After each ticket, update the map, graduate clarified
+fog into precise tickets, and return to the frontier with a fresh agent context. The map
+closes only when the destination is reached and no in-scope fog or open child tickets remain.
 
 Sources live in `.rulesync/skills/`; run `bun run rules` after editing to regenerate the
 per-agent mirrors.

package/dist/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -885,3 +885,42 @@ ad-hoc backfill scripts.
 - **Tasks:** *(not yet written)*
 - **RTK flag:** None
 - **Depends on:** —
+
+---
+
+# Shipped, umbrella, and declined IPs
+
+Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.
+Add each to the **Terreno Roadmap** project with the `IP` field set to the slug below.
+
+| IP slug | GitHub issue | Status |
+|---------|--------------|--------|
+| `admin-only` | https://github.com/FlourishHealth/terreno/issues/1075 | Shipped |
+| `admin-ui-v2-django-parity` | https://github.com/FlourishHealth/terreno/issues/1076 | Shipped |
+| `admin-script-runner` | https://github.com/FlourishHealth/terreno/issues/1077 | Shipped |
+| `consent-forms` | https://github.com/FlourishHealth/terreno/issues/1078 | Shipped |
+| `upgrade-banner` | https://github.com/FlourishHealth/terreno/issues/1079 | Shipped |
+| `apierror-standard-error-redesign` | https://github.com/FlourishHealth/terreno/issues/1080 | Shipped |
+| `syncdb-local-first` | https://github.com/FlourishHealth/terreno/issues/1081 | Shipped |
+| `feature-flags-openfeature` | https://github.com/FlourishHealth/terreno/issues/1082 | Shipped |
+| `design-blend-skill` | https://github.com/FlourishHealth/terreno/issues/1083 | Shipped |
+| `ModularAPI` | https://github.com/FlourishHealth/terreno/issues/1084 | Shipped |
+| `mcp-boost-parity` | https://github.com/FlourishHealth/terreno/issues/1085 | In progress |
+| `docs-site-and-versioning` | https://github.com/FlourishHealth/terreno/issues/1086 | Planned |
+| `syncdb-codegen` | https://github.com/FlourishHealth/terreno/issues/1087 | Planned |
+| `migrate-cicd-to-circleci` | https://github.com/FlourishHealth/terreno/issues/1088 | Planned |
+| `rbac-permissions` | https://github.com/FlourishHealth/terreno/issues/1089 | Planned |
+| `infra-mcp` | https://github.com/FlourishHealth/terreno/issues/1090 | Planned (blocked) |
+| `comms-admin-dashboard` | https://github.com/FlourishHealth/terreno/issues/1091 | Planned |
+| `model-router-mcp` | https://github.com/FlourishHealth/terreno/issues/1092 | Planned |
+| `terreno-langfuse-integration` | https://github.com/FlourishHealth/terreno/issues/1093 | Future |
+| `oss-launch-program` | https://github.com/FlourishHealth/terreno/issues/1094 | In progress |
+| `b2b-platform-program` | https://github.com/FlourishHealth/terreno/issues/1095 | Planned |
+| `offline-mode` | https://github.com/FlourishHealth/terreno/issues/1096 | Declined |
+| `model-router-actions` | https://github.com/FlourishHealth/terreno/issues/1097 | Declined |
+| `feature-flags` | https://github.com/FlourishHealth/terreno/issues/1098 | Declined |
+| `admin-improvements` | https://github.com/FlourishHealth/terreno/issues/1099 | Declined |
+
+Research and design sub-documents share the parent IP's issue: `admin-only-research` →
+#1075; `infra-mcp-research` → #1090; `migrate-cicd-to-circleci-research` → #1088;
+`syncdb-phase-c-design`, `terreno-syncdb-2`, and `syncdb-api-inventory` → #1081.

package/dist/docs/versioned/next/how-to/README.md

@@ -12,10 +12,13 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 ## Contents
 
+- [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
+- [Install agent skills](install-agent-skills.md) — Install Grow/Pick/Roast/Brew/Taste and domain skills with `npx skills`
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
 - [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer

package/dist/docs/versioned/next/how-to/admin-add-model.md

@@ -0,0 +1,41 @@
+# Add a model to the admin
+
+Add `admin` directly to the model's existing `modelRouter` options:
+
+```ts
+export const userRouter = modelRouter("/users", User, {
+  admin: {
+    displayName: "Users",
+    listFields: ["email", "name", "admin", "created"],
+    searchFields: ["email", "name"],
+    sortableFields: ["email", "name", "created"],
+    filters: [{field: "admin", kind: "boolean", label: "Admin user"}],
+  },
+  permissions: {
+    create: [Permissions.IsAdmin],
+    delete: [Permissions.IsAdmin],
+    list: [Permissions.IsAdmin],
+    read: [Permissions.IsAdmin],
+    update: [Permissions.IsAdmin],
+  },
+});
+```
+
+Register that router with `TerrenoApp`, then register `AdminApp`. The model appears in
+`GET /admin/config` and at `/admin/User` without a duplicate `AdminApp.models` entry.
+
+If the same Mongoose model is mounted at two `routePath`s (different filters or list
+columns), `/admin/config` keeps `name` as the model name for the registered entry and
+suffixes the others with the route slug (for example `Food-archived-foods`) so each list
+is reachable.
+
+Common fields:
+
+- `listFields`: columns and fields exposed to admin CRUD.
+- `searchFields`: string fields matched by the list search box (`q`) as a
+  case-insensitive partial (`$regex`) query.
+- `sortableFields`: the only columns with sorting enabled.
+- `filters`: typed filter drawer controls.
+- `fieldsets`: grouped form sections.
+- `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
+- `adminPermissions`: optional admin-specific permission methods.

package/dist/docs/versioned/next/how-to/admin-custom-home.md

@@ -0,0 +1,31 @@
+# Customize the admin home
+
+Configure home slots on `AdminApp`:
+
+```ts
+new AdminApp({
+  home: {
+    title: "Operations",
+    slots: {
+      contentTop: ["feature-flags-overrides"],
+      main: ["modelStats"],
+      navGlobal: ["scriptRunner"],
+      sidebar: ["versionConfig", "recentActivity"],
+    },
+  },
+});
+```
+
+Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`, and
+`recentActivity`. Plugins add IDs such as `feature-flags-overrides`.
+
+For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
+
+```tsx
+<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
+  <AdminHome api={api} />
+</AdminProvider>
+```
+
+Then place `"operationsSummary"` in a home slot. Unknown IDs render a visible missing-widget
+placeholder in development instead of crashing the dashboard.

package/dist/docs/versioned/next/how-to/admin-custom-widget.md

@@ -0,0 +1,42 @@
+# Add a custom admin field widget
+
+1. Name the widget in model admin metadata:
+
+```ts
+admin: {
+  displayName: "Articles",
+  listFields: ["title", "body"],
+  fieldOverrides: {body: {widget: "rich-text"}},
+}
+```
+
+2. Implement the field widget:
+
+```tsx
+const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
+  value,
+  onChange,
+  readOnly,
+}) => (
+  <RichTextEditor
+    disabled={Boolean(readOnly)}
+    onChange={onChange}
+    value={typeof value === "string" ? value : ""}
+  />
+);
+```
+
+3. Register it once around the admin routes:
+
+```tsx
+<AdminProvider
+  api={api}
+  apiBase="/admin"
+  routeBase="/admin"
+  widgets={{fields: {"rich-text": RichTextWidget}}}
+>
+  <AdminRoutes />
+</AdminProvider>
+```
+
+Host registrations override built-ins with the same ID.

package/dist/docs/versioned/next/how-to/admin-import-prebuilt.md

@@ -0,0 +1,25 @@
+# Import pre-built admins
+
+Register first-party plugins on the same `TerrenoApp` as `AdminApp`:
+
+```ts
+const app = new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp())
+  .register(new ConsentApp({auditTrail: true}))
+  .register(new DocumentStorageApp({bucketName: process.env.GCS_BUCKET ?? ""}))
+  .register(new AIAdminApp())
+  .register(new AdminApp({home: {slots: {main: ["modelStats"]}}}));
+```
+
+`AdminApp` aggregates each plugin's `adminContribution()`:
+
+- `FeatureFlagsApp`: FeatureFlag model and `feature-flags-overrides` home widget.
+- `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
+- `DocumentStorageApp`: `documents` custom screen.
+- `AIAdminApp`: `ai-requests` custom screen and explorer API.
+
+Wrap frontend admin routes in `AdminProvider`. First-party widgets are already in the built-in
+registry, so no consumer-side switch statement or custom-screen map is required.
+
+`featureFlagAdminConfig` and `AdminApp.models` remain compatibility paths, but new integrations
+should use plugin contributions and `modelRouter({admin: ...})`.