@terreno/mcp 57.0.0 → 57.2.0

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

package/src/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/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -481,16 +481,14 @@ dispatch — required by Stripe billing and by Twilio/Expo delivery status callb
 **Title:** `[Roadmap] Organizations, teams, and multi-tenant scoping`
 
 **Labels:** `area:api`, `type:feature`
-**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=`orgs-and-teams`, Status=`Planned`
+**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=`orgs-and-teams`, Status=`Superseded`
 
-Terreno's data model is per-user: `ownerId`, `OwnerQueryFilter`, and owner permissions.
-B2B apps need organizations. This adds Organization and Membership models, an org-context
-middleware, an `OrgQueryFilter` and org-scoping schema plugin for modelRouter, and
-membership-aware permission classes — the tenant analog of the existing owner stack.
-Invitations and the management UI are separate items.
+Superseded by `org-management-ui` (native orgs + RBAC + admin UI). Do not open new work
+from this item.
 
-- **Implementation plan:** [orgs-and-teams.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/orgs-and-teams.md)
-- **Tasks:** [orgs-and-teams.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/orgs-and-teams.md)
+- **Implementation plan:** [orgs-and-teams.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/orgs-and-teams.md) (superseded)
+- **Canonical IP:** [org-management-ui.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/org-management-ui.md)
+- **Tasks:** [org-management-ui.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/org-management-ui.md)
 - **RTK flag:** None
 - **Depends on:** —
 
@@ -507,7 +505,7 @@ Replaces the binary `admin` flag + owner checks with a first-class RBAC module:
 permission vocabulary on Better Auth's access-control engine, DB-backed roles editable in
 the admin panel, document-level scopes, field-level views, and one `can()` check enforced
 across REST, websockets, MCP tools, and admin. An API design draft already exists;
-`orgs-and-teams` extends it with org-scoped grants.
+`org-management-ui` extends it with org-scoped membership grants (`org-admin` / `member`).
 
 - **Implementation plan:** [rbac-permissions.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/rbac-permissions.md)
 - **Tasks:** *(TBD — design doc predates task split)*
@@ -530,25 +528,25 @@ billing can later enforce. Emails go through `@terreno/comms`.
 - **Implementation plan:** *(not yet written)*
 - **Tasks:** *(not yet written)*
 - **RTK flag:** None
-- **Depends on:** orgs-and-teams, comms-abstraction, comms-adapter-sendgrid
+- **Depends on:** org-management-ui, comms-abstraction, comms-adapter-sendgrid
 
 ---
 
 ## org-management-ui
 
-**Title:** `[Roadmap] Org switcher and member management screens`
+**Title:** `[Roadmap] Organizations as a first-class primitive (admin UI + RBAC)`
 
-**Labels:** `area:ui`, `type:feature`
-**Project fields:** Area=`ui`, Target=`Next`, Impact=`Feature`, IP=*(not yet written)*, Status=`Planned`
+**Labels:** `area:api`, `type:feature`
+**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=`org-management-ui`, Status=`Planned`
 
-The frontend counterpart of the tenancy track: an organization switcher, members list with
-roles, invite flow, and org settings screens in `@terreno/ui` + example-frontend, working
-on web and native.
+Native Organization and Membership models, RBAC (`org-admin`, `operator`, `superadmin`),
+and admin-panel directory / switcher / members / settings. Operators manage all orgs;
+org-admins manage only the current org. Invites and billing are design-only placeholders.
 
-- **Implementation plan:** *(not yet written)*
-- **Tasks:** *(not yet written)*
-- **RTK flag:** Partial — screens should target the syncdb data layer where available
-- **Depends on:** orgs-and-teams, rbac-permissions, invitations-and-seats
+- **Implementation plan:** [org-management-ui.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/org-management-ui.md)
+- **Tasks:** [org-management-ui.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/org-management-ui.md)
+- **RTK flag:** Partial — admin screens use generated SDK / `useAdminApi`
+- **Depends on:** rbac-permissions
 
 ---
 
@@ -568,7 +566,7 @@ are a separate item.
 - **Implementation plan:** [billing-stripe.md](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/billing-stripe.md)
 - **Tasks:** [billing-stripe.md](https://github.com/FlourishHealth/terreno/blob/master/docs/tasks/billing-stripe.md)
 - **RTK flag:** None
-- **Depends on:** orgs-and-teams, inbound-webhooks
+- **Depends on:** org-management-ui, inbound-webhooks
 
 ---
 
@@ -793,7 +791,7 @@ baseline.
 - **Implementation plan:** *(not yet written)*
 - **Tasks:** *(not yet written)*
 - **RTK flag:** None
-- **Depends on:** orgs-and-teams, native-module-baseline
+- **Depends on:** org-management-ui, native-module-baseline
 
 ---
 
@@ -830,7 +828,7 @@ B2B customers.
 - **Implementation plan:** *(not yet written)*
 - **Tasks:** *(not yet written)*
 - **RTK flag:** None
-- **Depends on:** orgs-and-teams
+- **Depends on:** org-management-ui
 
 ---
 
@@ -885,3 +883,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/src/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/src/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/src/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/src/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/src/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: ...})`.