@terreno/mcp 57.0.0 → 57.1.0

package/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -0,0 +1,194 @@
+# Expose Model Context Protocol Tools
+
+Turn a `modelRouter` model into Model Context Protocol (MCP) tools that an LLM can call, reusing the permissions, query filters, population, and lifecycle hooks you already declared for REST.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- At least one model registered with `modelRouter`
+
+## Steps
+
+### 1. Add an `mcp` config to a model router
+
+```typescript
+import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  mcp: {
+    excludeFields: ["internalNote"],
+    maxLimit: 25,
+    methods: ["list", "read", "create", "update", "delete"],
+  },
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsOwner],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+  },
+  queryFields: ["completed", "title"],
+  queryFilter: OwnerQueryFilter,
+});
+```
+
+`methods` defaults to `["list", "read"]`, and `maxLimit` defaults to 50. A method whose `permissions` array is empty is never exposed as a tool, so REST and MCP cannot drift apart.
+
+### 2. Start the server
+
+`TerrenoApp` mounts `POST /mcp` automatically as soon as any model has an `mcp` config. Every other verb on `/mcp` returns a JSON-RPC 405. No extra registration is needed.
+
+Tools are named `{prefix}_{method}` — `todos_list`, `todos_read`, and so on.
+
+The endpoint speaks the `2026-07-28` MCP revision through the TypeScript SDK v2
+`createMcpHandler`. It is stateless: every request carries its protocol version,
+client identity, and capabilities, so requests can land on any backend instance.
+The SDK's stateless legacy fallback remains enabled, so 2025-era clients continue
+to work while clients migrate.
+
+### 3. Call the tools
+
+Point any MCP client at `POST /mcp` with the user's `Authorization: Bearer <token>` header. Both JWT and Better Auth sessions are accepted; the resolved user is what the permission checks run against, so an LLM can never see more than that user could see over REST.
+
+Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP.
+
+To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
+
+```typescript
+import {getMCPTools} from "@terreno/ai";
+
+const tools = getMCPTools(req.user);
+```
+
+`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
+version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
+hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
+`Mcp-Method` / `Mcp-Name` routing headers.
+
+## Naming tools
+
+The default prefix is the lowercase model name run through a simple pluralizer: `Todo` → `todos`, `Category` → `categories`, `Status` → `statuses`. Irregular nouns need an explicit prefix:
+
+```typescript
+mcp: {toolPrefix: "people"} // person_list -> people_list
+```
+
+## Filtering list results
+
+Only fields listed in `queryFields` can be filtered, exactly as in REST. A filter value may be an exact value or an operator object:
+
+```json
+{"completed": false, "title": {"$in": ["Buy milk", "Walk dog"]}}
+```
+
+Allowed operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$all`, `$size`, `$exists`, and `$regex` (with `$options`). Operators that can execute code or ignore indexes — `$where`, `$expr`, `$function`, `$accumulator`, `$jsonSchema`, `$text` — are rejected with an error rather than silently dropped, so the model can correct itself.
+
+Filters can be combined with top-level `$and` / `$or`, whose branches are validated against `queryFields` too:
+
+```json
+{"$or": [{"completed": true}, {"title": {"$regex": "^Urgent"}}]}
+```
+
+`queryFilter` still runs after the filter is built, so an `OwnerQueryFilter` keeps scoping results to the calling user no matter what the LLM sends.
+
+## Populating references
+
+Population comes from the model router's `populatePaths`, exactly as it does over REST. A tool may pass `populate` to request a **subset** of those declared paths — it can never introduce a new one, so the `fields` allowlist on each declared path always applies and a caller cannot pull back a whole referenced document:
+
+```typescript
+populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
+```
+
+`{"populate": "ownerId"}` is accepted; anything undeclared is refused with an error listing the allowed paths. Models with no `populatePaths` don't get a `populate` parameter at all.
+
+## Hiding fields
+
+`excludeFields` removes fields from both the generated tool schemas and the responses:
+
+- A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
+- A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
+
+## Customizing responses
+
+`mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
+
+```typescript
+mcp: {
+  mcpResponseHandler: async (value, method) => {
+    if (Array.isArray(value)) {
+      return value.map((todo) => ({id: String(todo._id), title: todo.title}));
+    }
+    return {id: String(value._id), title: value.title};
+  },
+}
+```
+
+`excludeFields` is applied after your handler runs.
+
+## Lifecycle hooks
+
+`preCreate`, `postCreate`, `preUpdate`, `postUpdate`, `preDelete`, and `postDelete` all run for MCP calls. An MCP tool call is JSON-RPC rather than HTTP, so `createMCPRequest` builds a stub Express-shaped `request` (`MCPRequest`):
+
+- `user` — the authenticated MCP user
+- `body` — the hook-stage payload after write denylist + transform, not the raw tool args (on delete, `id` is in `body`, not `params`)
+- `headers` / `query` / `params` — always `{}` (MCP does not forward HTTP headers)
+- `isMCPRequest` — `true`
+
+REST `responseHandler` gets the same stub with an empty `body`.
+
+```typescript
+import type {MCPRequest} from "@terreno/api";
+
+preCreate: (body, req) => {
+  if ((req as unknown as MCPRequest).isMCPRequest) {
+    // e.g. tag records created by an assistant
+    return {...body, source: "assistant"};
+  }
+  return body;
+},
+```
+
+A hook that reads `req.headers` or `req.query` gets an empty object instead of a crash, but anything genuinely HTTP-specific (cookies, IP address) is unavailable — branch on `isMCPRequest` when that matters.
+
+## Logging and error reporting
+
+Every generated tool call emits a structured backend audit log with stable
+`mcpTool`, `mcpMethod`, and `mcpModel` labels plus the active Terreno request
+context (`requestId`, `userId`, and trace fields when present):
+
+- successful calls log at `info` with `durationMs`
+- expected refusals (permissions, not found, invalid filters) log at `warn`
+- caught database, transform, and lifecycle-hook failures log at `error`
+
+When `USE_SENTRY_LOGGING=true`, expected failures are mirrored as Sentry logs.
+Unexpected exceptions and caught internal causes are also captured with
+`Sentry.captureException`, preserving their original stack. The client still
+receives the stable MCP error text — internal exceptions and stack traces stay
+server-side. Tool arguments are not logged.
+
+## Custom tools
+
+CRUD tools cover one model at a time. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
+
+```typescript
+import {registerMCPTool} from "@terreno/api";
+import {z} from "zod";
+
+registerMCPTool({
+  name: "users_todo_statuses",
+  description: "List every user with each of their todos and completed status. Admin only.",
+  zodSchema: z.object({}).strict(),
+  handler: async (_args, user) => {
+    if (!user?.admin) {
+      return {
+        content: [{type: "text", text: JSON.stringify({error: "Permission denied: admin required"})}],
+        isError: true,
+      };
+    }
+    // load users + todos and return JSON text
+    return {content: [{type: "text", text: JSON.stringify({users: []})}]};
+  },
+});
+```
+
+The example backend registers this as `users_todo_statuses` from `example-backend/src/api/usersTodoStatus.ts`.

package/src/docs/versioned/next/how-to/install-agent-skills.md

@@ -0,0 +1,46 @@
+# Install agent skills
+
+Install Terreno's agent skills into another repo or agent with the skills CLI.
+
+```bash
+npx skills add FlourishHealth/terreno
+npx skills add FlourishHealth/terreno --skill terreno-1-grow
+```
+
+That copies the committed `skills/` tree: lifecycle stages (Grow, Pick, Roast, Brew,
+Taste), repository skills, and published package skills.
+
+## What you get
+
+| Group | Skills |
+| --- | --- |
+| Lifecycle | `terreno-1-grow` … `terreno-5-taste` |
+| Terreno apps | backend, UI, data, schema, SDK |
+| Docs | `update-docs`, `update-agent-docs`, architecture skills |
+| GitHub | commit, PR, review, verify, release, deploy |
+
+`skills.sh.json` at the repo root groups those names on [skills.sh](https://skills.sh).
+
+## Keep copies in sync (Terreno maintainers)
+
+Canonical sources:
+
+1. `.rulesync/skills/` — repository skills (`bun run rules` generates agent copies)
+2. `plugins/terreno-planning/skills/` — portable lifecycle stages
+3. `<package>/.ai/skills/` — published package skills; these overlay the repo copies
+
+Regenerate the installable tree:
+
+```bash
+bun run skills:sync
+bun run check:lifecycle-skills
+```
+
+Do not hand-edit `skills/`.
+
+## Write human docs with the skills
+
+Skills read architecture docs before changing code. After a user-visible or architectural
+change, update `docs/` in the same slice using `update-docs`. See
+[lifecycle plugin](../reference/lifecycle-plugin.md) and the
+[documentation contract](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md).

package/src/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -21,6 +21,8 @@ This guide is **AI-context-first**: it is written for an agent (or human) perfor
 
 The example app completed both steps; todos are syncdb-only while profile/admin still use generated RTK hooks.
 
+**Validation (Task 3.5):** The profile screen (`example-frontend/app/(tabs)/profile.tsx`) was reviewed against this guide. `useGetMeQuery` / `usePatchMeMutation` are **non-synced** custom SDK routes — the guide §8 explicitly says to keep them on RTK. No profile migration is required; the guide is sufficient for that case.
+
 Reference: [`docs/reference/syncdb.md`](../reference/syncdb.md), and the package [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md).
 
 ## 2. Install and configure
@@ -318,6 +320,18 @@ Required for Better Auth socket sessions. Legacy JWT sockets continue to work wi
 
 ## 8. Codegen
 
+Synced collections use `bun run sync-sdk`, which runs `terreno-syncdb-codegen` from
+`@terreno/syncdb`. It reads `/openapi.json`, finds list operations tagged
+`x-terreno-sync`, and writes `store/syncDbSdk.ts` (`SYNC_COLLECTIONS` plus friendly
+hooks such as `useTodos` / `useTodo` / `useCreateTodo`). Do not edit that file.
+Custom collections call `createCollectionHooks` in a sibling file. Names are chosen
+so they do not collide with RTK `openApiSdk.ts` during dual-stack migration.
+
+```bash
+# Backend running on port 4000
+cd example-frontend && bun run sync-sdk
+```
+
 ### Does `bun run sdk` still work?
 
 **Yes.** `example-frontend/package.json` still defines:
@@ -332,7 +346,7 @@ It runs `@rtk-query/codegen-openapi` against `openapi-config.ts` and writes `sto
 
 | Still generated | Stop using for migrated collections |
 |-----------------|-------------------------------------|
-| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | `useGetTodosQuery`, `usePostTodosMutation`, etc. |
+| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | Collection CRUD — import from `store/syncDbSdk.ts` instead |
 | Custom REST / RPC endpoints | Todo `realtimeList` / `realtimeDocument` wiring in `store/sdk.ts` |
 
 Keep running `bun run sdk` after backend route changes — non-synced screens still import from `store/sdk.ts`.
@@ -342,8 +356,19 @@ Workflow:
 ```bash
 # Backend running on port 4000
 cd example-frontend && bun run sdk
+cd example-frontend && bun run sync-sdk
 ```
 
+### Syncdb hooks codegen
+
+For collections with `sync` enabled on the backend, generate local-first hooks from the same OpenAPI spec:
+
+```bash
+cd example-frontend && bun run sync-sdk
+```
+
+This writes `store/syncDbSdk.ts` with friendly hooks (`useTodos`, `useCreateTodo`, …) that intentionally differ from RTK names so both SDKs can coexist during migration. Import synced screens from `@/store/syncDbSdk`, not `store/sdk.ts`.
+
 ## 9. Feature flags
 
 Post-migration, feature flags stay on `@terreno/rtk` + OpenFeature — **not** on syncdb.

package/src/docs/versioned/next/how-to/websocket-integration.md

@@ -411,6 +411,7 @@ This logs:
 
 ## Related Documentation
 
-- [@terreno/rtk Reference](../reference/rtk.md) — Full API documentation
+- [@terreno/syncdb Reference](../reference/syncdb.md) — Local-first data layer (replaces RTK for synced collections)
+- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md) — RTK Query utilities during the support window
 - [Authentication Architecture](../explanation/authentication.md) — JWT system deep-dive
 - [Socket.io Documentation](https://socket.io/docs/v4/) — Official Socket.io docs

package/src/docs/versioned/next/implementationPlans/ModularAPI.md

@@ -1,5 +1,6 @@
 # Modular API Implementation Plan
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084
 ## Overview
 
 This document outlines the implementation plan for a new modular API design in `@terreno/api`. The goal is to create a `TerrenoApp` class that provides a cleaner, more flexible interface for building APIs while maintaining backward compatibility with the existing `setupServer` function.

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

@@ -7,7 +7,7 @@ An implementation plan (IP) is one half of a two-file pair:
 
 | File | Holds | Path |
 | ---- | ----- | ---- |
-| **IP** | Design goals, architecture, models/APIs, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
+| **IP** | Design goals, architecture, models/APIs, testing decisions, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
 | **Task list** | The bot-consumable execution checklist for that IP | `docs/tasks/<slug>.md` |
 
 The IP is the source of truth for *what and why*; the task list is the source of truth
@@ -15,11 +15,12 @@ for *the concrete steps*. External trackers (a GitHub roadmap issue, a Linear is
 discussion thread) link **to** these files — they never replace them. See
 [`docs/tasks/README.md`](../tasks/README.md) for the task-file shape.
 
-## The live index
+## Status lives on each IP
 
-[`PLAN_INDEX.md`](PLAN_INDEX.md) is the authoritative list of active, completed, and
-deferred plans — read it, not this page, to see what is current. This README explains the
-process; `PLAN_INDEX.md` tracks the state.
+There is no shared `PLAN_INDEX.md`. That file caused merge conflicts the same way a
+shared changelog Unreleased section did. Status is the `**Status:**` line in each
+`docs/implementationPlans/<slug>.md` (and in `archive/` after close). List those
+directories to see what exists; this README explains the process.
 
 ## When to write an IP
 
@@ -35,34 +36,47 @@ Substantial work is planned before coding. Quick rule (full table in
 
 ## How a plan gets written and built
 
-The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline:
+The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline.
 
-1. **Blend** (`terreno-1-blend`) — write the IP + task list, questions first.
-2. **Roast** (`terreno-2-roast`) — implement via TDD from the approved IP.
-3. **Cupping** (`terreno-3-cupping`) — independently verify against the IP.
-4. **Pour** (`terreno-4-pour`) — commit, push, open the PR.
-5. **Dial In** (`terreno-5-dialin`) — drive CI and review until mergeable.
+**Grow** interviews in grilling rounds (one frontier of decisions per message, recommended
+answers, then wait). After the user confirms shared understanding it writes the two files
+and ends with a **15-line verify table** — destination, in/out, tracer, task graph, test
+seam — so a human can check the plan without rereading the IP.
+
+For a small feature, an outer loop may use the plugin's **feature profile**: a compact
+approved task contract, one fresh Pick invocation per frontier task, independent Roast,
+then Brew and bounded Taste iterations. This preserves the former Grind behavior without
+putting orchestration inside a lifecycle skill.
+
+1. **Grow** (`terreno-1-grow`) — grill, then write the IP + tracer-bullet task list; end with the 15-line verify table.
+2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD.
+3. **Roast** (`terreno-3-roast`) — independently verify the implementation against the IP.
+4. **Brew** (`terreno-4-brew`) — commit, push, open the PR.
+5. **Taste** (`terreno-5-taste`) — react once to current CI, mergeability, and review state.
+
+The outer loop owns stage selection, execution-state persistence, waiting, retries, and
+human/external escalation. Each stage emits the common machine-readable result described
+in [`plugins/terreno-planning/references/lifecycle-contract.md`](../../plugins/terreno-planning/references/lifecycle-contract.md).
 
 You can also author an IP directly with the `ip` skill; both produce the same two files.
 
 ### Roadmap handoff (roadmap-enabled repos only)
 
 In repos that run a public roadmap (Discussions + a roadmap Project — currently Terreno),
-Blend hands off to `roadmap-item` once the IP is **Approved** to create or update the
+Grow hands off to `roadmap-item` once the IP is **Approved** to create or update the
 public tracking issue, and the IP header records the `Discussion:` and `Roadmap issue:`
 links. See [`docs/explanation/roadmap-process.md`](../explanation/roadmap-process.md) for
 the full IP ↔ roadmap lifecycle.
 
 In repos with **no** roadmap board (Flourish, most consumer apps), the pipeline is
-identical minus that handoff: the IP + task list plus `PLAN_INDEX.md` are the source of
-truth, and Linear tracks execution via the IP header `Linear:` link.
+identical minus that handoff: the IP + task list are the source of truth, and Linear
+tracks execution via the IP header `Linear:` link.
 
 ## Lifecycle
 
-1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header and
-   `PLAN_INDEX.md`).
+1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header).
 2. **In progress** → **Complete** — implemented, verified, merged.
-3. **Archive** — completed IPs move to `docs/implementationPlans/archive/` and the index is updated.
+3. **Archive** — completed IPs move to `docs/implementationPlans/archive/`.
 
 Plans that are fully implemented and now describe shipped architecture should be migrated
 to `docs/explanation/` as reference documentation.

package/src/docs/versioned/next/implementationPlans/admin-improvements-research.md

@@ -0,0 +1,136 @@
+# Research: Admin Improvements (post–Admin UI v2 gap)
+
+**Date:** 2026-08-20  
+**PRD:** Implement what did not ship in Admin UI v2 — finish the `admin-improvements` architectural overhaul on top of the landed `admin-ui-v2-django-parity` work.
+
+## Scope investigated
+
+- Existing IPs: `docs/implementationPlans/admin-improvements.md`, `docs/implementationPlans/admin-ui-v2-django-parity.md`, `docs/tasks/admin-improvements.md`, `docs/tasks/admin-ui-v2-django-parity.md`
+- Packages: `api/`, `admin-backend/`, `admin-frontend/`, `admin-spa/`, `feature-flags/`, `example-backend/`, `example-frontend/`
+- Roadmap: `.github/roadmap-fields.yml` present → roadmap handoff applies after IP approval
+
+## What Admin UI v2 already shipped
+
+`admin-ui-v2-django-parity` is marked **Implemented** with all task phases complete. Evidence in-repo:
+
+| Area | Shipped |
+|------|---------|
+| Config | `schemaVersion: 2`, extended model meta, `home.slots` (`navGlobal`, `contentTop`, `main`, `sidebar`) |
+| Backend routes | `POST .../bulk-patch` (≤1000 ids), `POST /admin/background-tasks` |
+| Scripts | `/admin/scripts/*`, `scripts[]` in config (see `admin-script-runner.md`) |
+| Shell / home | `AdminShell`, `AdminHome` with built-in widget ids (`modelsGrid`, `scriptRunner`, `recentActivity`, `versionConfig`, …) |
+| List | `AdminModelTable`: debounced search, inline typed filters, row select, declarative `actions` → bulk-patch or background enqueue |
+| Form | `AdminModelForm`: fieldsets, readonly (server strips PATCH body) |
+| Audit | `AdminAuditLog` + `onAdminAudit` + `recentActivity` widget (sidebar, last) |
+| Integration | `admin-spa`, `example-backend` v2 demo registrations, Playwright e2e |
+
+## What `admin-improvements` planned but did NOT ship
+
+All tasks in `docs/tasks/admin-improvements.md` remain **unchecked**. High-level gaps:
+
+### `@terreno/api` (Phase 1) — none landed
+
+- No `api/src/adminTypes.ts` (`AdminConfig`, `AdminContribution`, `AdminAction`, …)
+- No `admin?: AdminConfig` on `ModelRouterOptions`
+- `TerrenoPlugin.register` still `(app, openApi?)` — no `terrenoApp` third arg
+- No `getRegistrations()` / `getPlugins()` on `TerrenoApp`
+- No `adminContribution?()` on `TerrenoPlugin`
+- No typed `admin:model.changed` event bus on `TerrenoApp`
+- No shared `scrubAdminFields` with populated-doc recursion
+- `readonlyFields` / `excludeFields` enforcement lives in `admin-backend` only, not in `modelRouter` hooks
+
+### `@terreno/admin-backend` (Phase 2) — partial overlap with v2, architecture gap remains
+
+| Planned | Status |
+|---------|--------|
+| Aggregate admin from modelRouter `admin:` + plugin contributions + legacy `models[]` | **Not done** — still `AdminApp({ models: [...] })` only |
+| `legacy.ts` adapter + deprecation warnings | **Not done** |
+| `filterParser.ts` (strict per-type `filter[k]=v`) | **Not done** — list uses `queryFields`-compatible filters directly |
+| `actionRunner.ts` + `POST .../actions/:name` + frozen `AdminActionContext` | **Not done** — v2 uses `bulk-patch` + `background-tasks` with `patchKeys` |
+| Per-user permission booleans in `/admin/config` | **Partial** — `permissions` are static config flags (`create/update/delete !== false`), not evaluated per requesting user |
+| `adminFilter` async row scoping | **Not done** (only `queryFilter` on `AdminModelConfig`) |
+| `capabilities`, `widgetIds` top-level config | **Not done** |
+| `Cache-Control: private, no-store` on config | **Not verified** |
+
+### `@terreno/admin-frontend` (Phases 3–4) — v2 UI exists, provider/registry pattern missing
+
+| Planned | Status |
+|---------|--------|
+| `AdminProvider` + three-bucket widget registry (`fields`, `home`, `screens`) | **Not done** |
+| `AdminScreenRouter` | **Not done** — `example-frontend` still uses string-switch in `[model]/index.tsx` |
+| Widget modules under `widgets/` | **Not done** — widgets inline in `AdminHome.tsx` |
+| `AdminFilterDrawer` (right rail / mobile sheet) | **Not done** — filters inline in `AdminModelTable` |
+| `AdminActionMenu` component | **Not done** — bulk UI inline in table |
+| `AdminFieldRenderer` reads widgets from context | **Not done** — hardcoded switch |
+| Plugin home widgets via registry (`feature-flags-overrides`) | **Warn-only** in `AdminHome` — no injectable component |
+
+### Pre-built plugin migrations (Phase 5) — not started
+
+- `FeatureFlagsApp.adminContribution()` — still exports `featureFlagAdminConfig` passed manually in `example-backend`
+- `ConsentApp.adminContribution()` — consent admins wired manually in server
+- `DocumentStorageApp` / AI explorer — custom screens hand-rolled in example-frontend (`ADMIN_CUSTOM_SCREENS`, `AIAdminScreen`)
+
+### Docs / examples (Phase 6–7) — not started
+
+- No `docs/how-to/admin-*.md` or `docs/reference/admin-config.md`
+- Example apps not migrated to `admin:` on modelRouter / `AdminProvider` / `AdminScreenRouter`
+- MCP `generate_route` still emits legacy patterns
+
+## Contract tensions (v2 vs original admin-improvements IP)
+
+These need product decisions before rewriting the IP:
+
+1. **Bulk actions API**
+   - **v2:** declarative `actions[]` with `patchKeys` → `POST .../bulk-patch` or `background-tasks`
+   - **admin-improvements:** imperative `AdminAction.run(ctx)` → `POST .../actions/:name`
+   - Both can coexist or one can subsume the other.
+
+2. **Home layout config**
+   - **v2:** `home.slots` (Django template regions) with string widget ids
+   - **admin-improvements:** `home.widgets` array of typed specs (`{type:"modelStats"}`, plugin id strings, React components)
+   - Shipped contract is `slots`; IP must align to v2 unless breaking.
+
+3. **Filter wire format**
+   - **v2:** filters map to existing `queryFields` query params (kind-specific UI in table)
+   - **admin-improvements:** strict `filter[field]=value` parser module with injection hardening
+   - May be additive hardening on top of v2, or a new encoding.
+
+4. **Config field names**
+   - **v2:** kept `listFields`, `defaultSort`
+   - **admin-improvements:** originally considered `listDisplay` / `ordering` aliases — v2 added `listDisplay` alongside `listFields` in model meta
+
+5. **Per-user `/admin/config`**
+   - **admin-improvements:** evaluate permissions per request (uncacheable)
+   - **v2:** static permission flags on model config
+
+## Candidate delivery options (not chosen — for Step 3)
+
+| Option | Scope | Tradeoff |
+|--------|-------|----------|
+| **A. Architecture-only** | Phases 1–2 + 5 + 6 (api types, aggregation, plugin contributions, docs); keep v2 UI/components as-is | Fastest path to “admin on modelRouter”; least UI churn |
+| **B. Full original IP** | All phases including AdminProvider, ScreenRouter, filterParser, `/actions/:name`, drawer, docs, E2E | Largest diff; some v2 work duplicated or replaced |
+| **C. Incremental slices** | Ship A first, then provider/registry (Phase 3), then optional hardening (filterParser, per-user config) | Lower risk; longer calendar time |
+
+## Decisions recorded (2026-08-20)
+
+| # | Choice |
+|---|--------|
+| 1 | **B** — Full IP (provider, screen router, drawer, filterParser, plugins, docs, E2E) |
+| 2 | **A** — Bulk actions: v2 `bulk-patch` only; no `/actions/:name` |
+| 3 | **A** — `home.slots` canonical |
+| 4 | **B** — Static permission flags on config |
+| 5 | **A** — `filterParser` with v2-compatible wire shape |
+| 6 | **A** — Plugin widgets in `admin-frontend/src/widgets/` |
+| 7 | **A** — Atomic example-backend + frontend + admin-spa migration |
+| 8 | **B** — New roadmap tracking issue |
+
+IP and task list updated: `admin-improvements.md`, `docs/tasks/admin-improvements.md`.
+
+## References
+
+- `docs/implementationPlans/admin-improvements.md` — original full IP (pre–v2)
+- `docs/implementationPlans/admin-ui-v2-django-parity.md` — shipped v2 IP
+- `docs/tasks/admin-improvements.md` — unchecked task list
+- `example-backend/src/server.ts` — still uses `AdminApp({ models: [featureFlagAdminConfig, …] })`
+- `example-frontend/app/admin/[model]/index.tsx` — manual screen routing
+- `admin-frontend/src/AdminHome.tsx` — inline widgets, no `AdminProvider`