@terreno/mcp 57.15.0 → 57.16.2

package/src/docs/versioned/57.15.0/roadmap.md

@@ -0,0 +1,9 @@
+# Roadmap
+
+Terreno's public roadmap lives on GitHub:
+
+- **[ROADMAP.md](https://github.com/TerrenoLabs/terreno/blob/master/ROADMAP.md)** — generated from the Terreno Roadmap project board (also in the repo root)
+- **[Roadmap process](explanation/roadmap-process.md)** — Discussions, triage, Linear bridge, maintainer setup
+- **[GitHub Discussions](https://github.com/TerrenoLabs/terreno/discussions)** — Ideas, Q&A, RFCs
+
+To propose work, start an [Ideas discussion](https://github.com/TerrenoLabs/terreno/discussions/new?category=ideas) rather than opening a tracking issue directly.

package/src/docs/versioned/57.15.0/scans/reduce-cold-compile-time/charter.md

@@ -0,0 +1,129 @@
+# Scan charter — reduce cold `bun run compile` wall-clock time
+
+- Slug: reduce-cold-compile-time
+- Status: approved (2026-09-20)
+- Owner: joshgachnang
+
+## Goal
+
+The terreno monorepo compiles with per-package standalone `tsc` and no build
+cache, TS project references, or shared-dep deduplication. A full cold
+`bun run compile` currently takes ~305s, and the pipeline recompiles shared
+packages (`@terreno/test`, `@terreno/api`, `@terreno/syncdb`, `@terreno/jobs`)
+multiple times per run. This campaign cuts cold compile wall-clock by 30% by
+removing redundant tsc passes, deduplicating shared-dependency recompiles,
+introducing project references, and trimming non-typecheck work from the compile
+path — without changing published dist output or weakening type-safety. Faster
+compiles shorten every bootstrap, CI run, and agent iteration.
+
+## Metric
+
+| Field | Value |
+| --- | --- |
+| Name | Cold full-monorepo compile wall-clock |
+| Command | `find . -maxdepth 2 -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete; rm -rf */dist; time bun run compile` (min of 3 runs, seconds) |
+| Unit | s |
+| Direction | down |
+| Protocol | Cold (dist + tsbuildinfo removed before each run), best (min) of 3 consecutive runs, same VM |
+| Baseline | 305 (measured 2026-09-20) |
+| Target | 214 |
+| Horizon | 4 rounds |
+
+Baseline evidence:
+
+```text
+run1 exit=0 elapsed=321s
+run2 exit=0 elapsed=305s
+run3 exit=0 elapsed=309s
+# best of 3 = 305s ; target -30% = 214s
+```
+
+## Scope
+
+- In scope: build/compile configuration only — root `package.json` compile
+  scripts, per-package `tsconfig.json` / `tsconfig.server.json`,
+  `.github/scripts/compile-workspace-deps.js`, per-package `compile` scripts,
+  and any new build tooling that measurably reduces cold compile time.
+- Out of scope: product/source logic, test assertions, runtime behavior,
+  dependency version bumps unrelated to the build.
+- Unacceptable trade-offs:
+  - **Published dist output must stay intact** — `declaration` (.d.ts) emit and
+    the published `dist/` layout for every `@terreno/*` package are preserved.
+  - **No type-safety loss** — no loosening `strict`/`strictNullChecks`, no
+    removing existing `skipLibCheck`, no `noEmit`-to-skip-checks tricks. Adding
+    `skipLibCheck` where absent is allowed.
+  - Publish-time behavior of `compile-workspace-deps.js` must be preserved
+    (it exists because tag-publish replaces `workspace:*` refs before install).
+
+New build dependencies ARE permitted (owner did not exclude them), provided the
+two guardrails above hold.
+
+## Detection rules
+
+| Rule | Query | Matches | Why it moves the metric | Hits |
+| --- | --- | --- | --- | --- |
+| redundant-pipeline | Inspect root `compile` script; `grep -rl compile-workspace-deps */package.json` | Root `compile` runs `@terreno/test` and `@terreno/api` explicitly, then `--filter '*'` recompiles them again; `api` and `admin-backend` re-`tsc` shared deps via `compile-workspace-deps.js` | Every duplicate tsc pass of a large package (api=90k LOC, syncdb, test) is pure cold-time waste | 4 |
+| no-project-references | For each compile-path tsconfig: `grep -L '"references"'`; check for a root solution tsconfig | 19 tsconfigs compile as isolated `tsc` with no `references`; no root solution tsconfig | Project references (`tsc -b`) compile each package once in dep order and enable parallelism, killing recompile overlap | 19 |
+| non-typecheck-work-in-compile | `grep -E 'sync-\|cp \|&&.*&&'` in each package `compile` script | `mcp-server` runs 3 doc-sync scripts at 8GB heap plus a `cp` before/around its `tsc` on every compile | Non-tsc work on the compile critical path adds fixed cold-time cost unrelated to type-checking | 1 |
+| missing-skiplibcheck | For each compile-participating tsconfig: `grep '"skipLibCheck"'` | `demo/tsconfig.json` and `website/tsconfig.json` lack `skipLibCheck` (their compile scripts use these configs) | Without `skipLibCheck`, tsc type-checks every `.d.ts` in the dependency tree — costly for RN/Expo/docs dep trees | 2 |
+
+## Exclusions
+
+Beyond the map-reduce defaults: `node_modules/`, `*/dist/`, `patches/`,
+`terraform/`, generated files (`openApiSdk.ts`, `plugins/terreno-claude/`), and
+`example-frontend` (no `compile` script — not on the compile path).
+
+## Validity rule
+
+A finding is valid only when applying it measurably reduces cold `bun run compile`
+wall-clock (best-of-3) while keeping published dist output identical and
+type-safety unchanged.
+
+## Severity rubric
+
+| Severity | Threshold |
+| --- | --- |
+| high | Plausibly removes ≥30s of cold compile time |
+| medium | Plausibly removes 5–30s |
+| low | Plausibly removes <5s |
+
+Effort: S = under an hour, M = under a day, L = more than a day or needs design.
+
+## Slice policy
+
+- Maximum 4 files and 3 findings per slice.
+- Never mix: a project-references migration with unrelated tsconfig flag tweaks;
+  or `compile-workspace-deps.js` changes with anything else.
+- Always its own slice: the `tsc -b` / project-references migration (touches
+  every package + CI; reviewer-heavy) and any `compile-workspace-deps.js`
+  change (publish-time behavior risk).
+
+## Review routing
+
+| Field | Value |
+| --- | --- |
+| Mode | fixed |
+| Reviewers | @joshgachnang |
+| Assignee | @joshgachnang |
+| Teams | — |
+| Draft | no |
+| Labels | reduce-cold-compile-time, build-perf |
+| Merge policy | human |
+| Notify | PR body mention |
+
+## Budget
+
+- Rounds: 4
+- Slices per round: 2
+- Open PRs at once (`wipLimit`): 1
+- Minimum metric step per round before reporting diminishing returns: 10s
+
+## Decisions
+
+| Decision | Question that prompted it |
+| --- | --- |
+| Goal = reduce cold `bun run compile` wall-clock | "What goal should this scan campaign drive toward?" |
+| Target = 214s (−30% of 305s baseline) | "How aggressive a cold-compile reduction should this campaign target?" |
+| Guardrails = keep published dist output + no type-safety loss; new build deps allowed | "What must this campaign NOT break while cutting compile time?" |
+| Review = fixed @joshgachnang, human merge | "Who reviews the campaign's PRs, and what's the merge policy?" |
+| Budget = 1 open PR, 2 slices/round, 4 rounds | "How much work-in-progress should the campaign carry per round?" |

package/src/docs/versioned/57.15.0/scans/reduce-cold-compile-time/round-1-findings.md

@@ -0,0 +1,62 @@
+# Round 1 findings — reduce cold `bun run compile` time
+
+- Goal: reduce cold `bun run compile` wall-clock across the terreno monorepo
+- Metric: cold compile seconds (best of 3). **Baseline 305s → target 214s (−30%)**
+- Head: `f8779a96`
+- Kept: 4 findings · Merged: 2 candidates · Dropped: 2 candidates
+
+## Measured evidence (Sift verification)
+
+| Measurement | Result |
+| --- | --- |
+| `@terreno/test` compile (cold) | 10s |
+| `@terreno/api` compile FULL (compile-workspace-deps + tsc, cold) | 50s |
+| `@terreno/api` tsc-only (deps prebuilt) | 31s → compile-workspace-deps adds **~19s per api compile** |
+| demo `tsc --noEmit` without vs with `--skipLibCheck` | 10s vs 10s → **0s** delta |
+| mcp-server sync scripts (sync-ui / sync-versioned / sync-package) | 0s + 5s + 0s = **~5s** |
+
+## Ranked findings
+
+| # | ID | Rule | Sev | Conf | Effort | Est. cold-time saving | Anchors |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | redundant-explicit-prefix | redundant-pipeline | high | high | S* | ~60s (1× test + 1× api) | `package.json:223` |
+| 2 | compile-workspace-deps-overlap | redundant-pipeline | high | high | M | ~19s+ per api compile, ×2–3 dependents | `.github/scripts/compile-workspace-deps.js:22`, `api/package.json:117`, `admin-backend/package.json:47` |
+| 3 | no-project-references | no-project-references | high | medium | L | large but unquantified; durable fix that enables #1/#2 safely | `api/tsconfig.json:1` + 18 more; no root solution tsconfig |
+| 4 | mcp-doc-sync-on-compile-path | non-typecheck-work-in-compile | medium | high | S | ~5s | `mcp-server/package.json:52` |
+
+\* #1 is a one-line edit but is **load-bearing for build ordering** — safe only once #2/#3 provide dependency-ordered builds. See coupling note below.
+
+## High-severity findings (adversarial verification)
+
+### 1. Redundant explicit `test`+`api` prefixes in root compile — CONFIRMED
+Root `compile` = `bun run --filter '@terreno/test' compile && bun run --filter '@terreno/api' compile && bun run --filter '*' compile`. The final `--filter '*'` already builds all 19 workspaces including `test` and `api`, so the two prefixes are a full extra cold compile of test (10s) + api (50s) = **~60s of duplication**.
+
+*Refutation attempted:* "The prefixes force build order; removing them breaks `*`." → Partially holds. `compile-workspace-deps.js` makes api self-build its deps, so api compiles fine inside `*`; but bun `--filter '*'` gives no guaranteed dependency order, so the prefixes currently serve as a crude ordering hack. Verdict: the **duplication is real and confirmed**, but the safe fix is to introduce real ordering (#2/#3), not to blindly delete the prefixes. Kept high.
+
+### 2. compile-workspace-deps.js re-tsc's shared deps every compile — CONFIRMED
+`compile-workspace-deps.js:22` (`const compiled = new Set()`) dedupes only within one node process. Each package's compile runs in its own `bun run` process, so api re-builds test+syncdb (+19s measured over tsc-only), and admin-backend re-builds api (~50s!)+jobs+test — while `--filter '*'` also builds those same packages as their own targets. Shared deps are cold-compiled multiple times per run.
+
+*Refutation attempted:* "The script is required so deps' `dist` exists before dependents compile." → Holds for the current unordered `*` build, and the script's own doc comment says it exists for tag-publish (post-`workspace:*`-replacement installs). Verdict: confirmed redundant **for the dev/monorepo build**; the fix must preserve publish-time behavior (charter guardrail) and supply ordering another way. Kept high, effort M.
+
+### 3. No TS project references / `tsc -b` solution build — CONFIRMED
+No package tsconfig has `references` or `composite`, and there is no root solution tsconfig (`grep -c '"composite"'` → 0 everywhere; `ls tsconfig.json` → not found). Every package is a full standalone `tsc`.
+
+*Refutation attempted:* "Project references help warm builds (via .tsbuildinfo reuse), not cold — this campaign measures cold." → Fails: even cold, `tsc -b` walks the reference graph and compiles each package **exactly once** in dependency order and parallelizes independent leaves, eliminating the multi-recompile waste that #1 and #2 describe. It is the durable structural fix that makes #1 and #2 safe. Verdict: confirmed high; magnitude unproven without doing the migration → confidence medium, effort L.
+
+## Coupling note (for Plot)
+
+Findings #1, #2, #3 are one problem at three depths: the pipeline recompiles shared packages because there is no dependency-ordered build. #3 (project references) is the durable fix and would subsume #1/#2. A lighter interim fix is bun topological filter ordering. Per charter slice policy: the project-references migration and any `compile-workspace-deps.js` change each get **their own slice**. Finding #4 is fully independent and is the cheapest standalone win.
+
+## Merged candidates
+
+- `s1-pipeline-3` ("test compiled 3×") — folded into #1 and #2; it is the same duplication counted from test's side.
+- `s3-mcpwork-2` ("8GB heap flag on copy scripts") — folded into #4; negligible sub-part of the same compile string.
+
+## Dropped candidates
+
+| Candidate | Reason |
+| --- | --- |
+| `s4-skiplibcheck-1` (demo) | **Invalid — refuted.** `skipLibCheck` is already inherited from `expo/tsconfig.base` (`skipLibCheck: true`). Measured delta 10s vs 10s = 0s. No metric movement. |
+| `s4-skiplibcheck-2` (website) | **Invalid — refuted.** `skipLibCheck` already inherited from `@docusaurus/tsconfig` (`skipLibCheck: true`). `--noEmit` + tiny source set → no measurable movement. |
+
+Drop reasons: 2/2 = already-satisfied-via-inheritance / no-metric-movement.

package/src/docs/versioned/57.15.0/superpowers/plans/2026-07-28-admin-mobile-navigation.md

@@ -0,0 +1,97 @@
+# Admin Mobile Navigation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** On viewports below 768px, replace the admin shell’s fixed sidebar with a hamburger-triggered left slide-over drawer.
+
+**Architecture:** Keep navigation content in one shared internal component. `AdminShell` uses `useWindowDimensions` to switch between desktop rail and mobile header + overlay drawer. Drawer closes on backdrop, close button, and nav selection.
+
+**Tech Stack:** React Native / Expo, `@terreno/ui` (`Box`, `Heading`, `Text`, `IconButton`), bun test + `@testing-library/react-native`.
+
+## Global Constraints
+
+- Breakpoint: below 768px → mobile; 768px and above → desktop sidebar.
+- Menu style: left slide-over drawer with dismissible backdrop.
+- Accessibility: hamburger labeled "Open navigation menu"; close labeled "Close navigation menu".
+- Do not change public `AdminShellProps` API unless required.
+- Always support React Native Web.
+
+---
+
+### Task 1: Failing AdminShell responsive tests
+
+**Files:**
+- Create: `admin-frontend/src/AdminShell.test.tsx`
+
+**Interfaces:**
+- Consumes: `AdminShell` from `./AdminShell`; mocked `./useAdminConfig` and `expo-router`
+- Produces: failing tests that assert desktop sidebar at ≥768, mobile header below 768, drawer open/close, nav closes drawer, a11y labels
+
+- [ ] **Step 1: Write the failing test file**
+
+Mock `useWindowDimensions` via a mutable width, mock `useAdminConfig` with a small config (Home + one model), mock `expo-router.router.push`. Assert:
+
+1. width 1024 → `admin-shell-sidebar` present; hamburger absent
+2. width 500 → sidebar absent; `admin-shell-menu-button` present with accessibilityLabel "Open navigation menu"
+3. press menu → `admin-shell-drawer` and backdrop appear; close button has "Close navigation menu"
+4. press backdrop / close → drawer gone
+5. open drawer, press Home nav → `router.push` called and drawer closed
+
+- [ ] **Step 2: Run tests and confirm failure**
+
+Run: `cd admin-frontend && bun test src/AdminShell.test.tsx`
+Expected: FAIL (missing mobile UI / testIDs)
+
+---
+
+### Task 2: Implement responsive AdminShell
+
+**Files:**
+- Modify: `admin-frontend/src/AdminShell.tsx`
+- Test: `admin-frontend/src/AdminShell.test.tsx`
+
+**Interfaces:**
+- Consumes: nav data from `useAdminConfig` (existing)
+- Produces: `MOBILE_BREAKPOINT = 768`; shared sidebar body; mobile header; overlay drawer with backdrop
+
+- [ ] **Step 1: Extract shared sidebar body**
+
+Create an internal `AdminShellSidebarNav` that receives navigate callbacks, grouped models, scripts, screens, configurationPath, footer, sidebarVariant, and optional `onNavigate` that runs after each nav press (used to close the drawer).
+
+- [ ] **Step 2: Wire responsive chrome**
+
+```tsx
+const MOBILE_BREAKPOINT = 768;
+const {width} = useWindowDimensions();
+const isMobileLayout = width < MOBILE_BREAKPOINT;
+const [isNavOpen, setIsNavOpen] = useState(false);
+```
+
+Desktop: existing fixed 280px sidebar.
+Mobile: compact header (`admin-shell-mobile-header`) with `IconButton` (`iconName="bars"`, testID `admin-shell-menu-button`) + "Admin" heading; main content full width.
+When `isNavOpen`: absolute full-screen overlay (`admin-shell-drawer`) with backdrop (`admin-shell-drawer-backdrop`) and 280px panel containing close `IconButton` (`iconName="xmark"`, testID `admin-shell-drawer-close`) + shared nav. Close on backdrop, close button, and after navigate.
+
+- [ ] **Step 3: Close drawer when resizing to desktop**
+
+`useEffect` clears `isNavOpen` when `!isMobileLayout`.
+
+- [ ] **Step 4: Run tests**
+
+Run: `cd admin-frontend && bun test src/AdminShell.test.tsx`
+Expected: PASS
+
+- [ ] **Step 5: Compile and lint**
+
+Run: `cd admin-frontend && bun run compile && bun run lint`
+Expected: clean
+
+---
+
+### Task 3: Manual UI verification
+
+**Files:** none (runtime check in example-frontend admin)
+
+- [ ] **Step 1:** With backend + `frontend:web` running, open `/admin` as `admin@example.com`
+- [ ] **Step 2:** Narrow viewport below 768 → hamburger header, no fixed sidebar
+- [ ] **Step 3:** Open drawer, navigate, confirm close; widen to ≥768 → sidebar returns
+- [ ] **Step 4:** Capture screenshot evidence under `.devdata/artifacts/`

package/src/docs/versioned/57.15.0/superpowers/specs/2026-07-28-admin-mobile-navigation-design.md

@@ -0,0 +1,36 @@
+# Admin Mobile Navigation Design
+
+## Goal
+
+Make the admin shell usable on narrow devices by replacing its fixed 280px sidebar with a hamburger-triggered navigation drawer below 768px.
+
+## Responsive behavior
+
+- At widths of 768px and above, preserve the existing sidebar and content layout.
+- Below 768px, hide the fixed sidebar and show a compact header with an accessible hamburger button and the Admin label.
+- Opening the hamburger displays the same grouped navigation in a left slide-over drawer above the page.
+- A backdrop covers the remaining page and dismisses the drawer when pressed.
+- The drawer also closes from its close button and after any navigation item is selected.
+
+## Component structure
+
+Extract the sidebar body into a shared internal component so desktop and mobile render the same links, groups, configuration entry, and footer. `AdminShell` owns responsive width detection and drawer open state. The existing main content, top bar, breadcrumbs, and header actions remain unchanged apart from the added mobile header.
+
+## Accessibility
+
+- The hamburger button has an "Open navigation menu" label.
+- The drawer close button has a "Close navigation menu" label.
+- Backdrop dismissal is available in addition to the explicit close button.
+- Existing navigation labels and hints remain intact.
+
+## Testing
+
+Add focused `AdminShell` tests covering:
+
+- Desktop sidebar rendering at 768px and above.
+- Mobile header rendering below 768px.
+- Opening and closing the drawer.
+- Closing after selecting a navigation item.
+- Hamburger and close-button accessibility labels.
+
+Run the admin frontend test suite, compile, lint, and responsive UI verification.

package/src/docs/versioned/57.15.0/tasks/README.md

@@ -0,0 +1,53 @@
+# Task lists
+
+Bot-consumable execution checklists. Most files pair with an implementation plan (IP)
+as described in [`docs/implementationPlans/README.md`](../implementationPlans/README.md):
+
+- **IP** (`docs/implementationPlans/<slug>.md`) — the design: what and why.
+- **Task list** (`docs/tasks/<slug>.md`) — the steps: the concrete, ordered work.
+
+The filename slug matches the IP it belongs to.
+
+The loop's small-feature profile may use a task file with `**Feature profile:** true` and
+no full IP when repository policy permits. The destination, scope, decisions, acceptance
+criteria, tracer, and verification seam live in that durable contract so Pick can
+implement one task, roast it, and continue to the next without conversation history.
+
+## Task shape
+
+Each task is a tracer-bullet vertical slice with explicit blocking edges:
+
+```markdown
+- [ ] **Task 1.1**: Short title
+  - Delivers: the narrow end-to-end behavior this makes usable
+  - Files: expected files to create or modify
+  - Blocked by: none | other task IDs
+  - Acceptance: observable proof, including focused Bun tests
+```
+
+Group tasks by phase (`### Phase 1: …`) and order them by dependency. Every normal task
+cuts through the required data, API, UI, documentation, and test layers rather than
+batching one layer across the whole feature. A completed task is demoable or independently
+verifiable and small enough for one fresh agent context. Work the **frontier**: any task
+whose blockers are complete.
+
+Wide mechanical refactors that cannot land green as vertical slices use
+**expand → migrate batches → contract**. The contract task is blocked by every migration
+batch. Grow-style runs may append a **Plan vs Actual** log after each task.
+
+## What lives here vs elsewhere
+
+| Concern | Home |
+| ------- | ---- |
+| Design, scope, acceptance criteria | the IP (`docs/implementationPlans/`) |
+| Concrete task steps and their status | this directory |
+| Public status and target | GitHub roadmap issue / Project (roadmap-enabled repos) |
+| Sprint estimates and assignees | Linear |
+| Current stage/attempt/head/result | loop-owned execution state (default `.terreno/pipeline/<slug>.json`) |
+
+Do not copy the full checklist into a GitHub issue or Linear. Create linked GitHub child
+issues only for tasks that outside contributors should be able to claim independently; the
+task file stays the source of truth for scope and acceptance.
+
+The docs site excludes this directory, so link to task files with full GitHub URLs from
+pages that render on the site.

package/src/docs/versioned/57.15.0/tasks/admin-improvements.md

@@ -0,0 +1,265 @@
+# Task List: Admin Improvements (post–Admin UI v2)
+
+*Executable checklist for the gap after [Admin UI v2](./admin-ui-v2-django-parity.md). See [admin-improvements.md](../implementationPlans/admin-improvements.md).*
+
+**Decisions (2026-08-20):** Full IP; bulk actions = v2 `bulk-patch` only (no `/actions/:name`); `home.slots`; static permissions; `filterParser`; widgets in `admin-frontend/src/widgets/`; atomic example migration; new roadmap issue.
+
+---
+
+## Phase 0 — Admin UI v2 baseline (complete)
+
+*Do not re-implement. Reference: `docs/implementationPlans/admin-ui-v2-django-parity.md`.*
+
+- [x] **Task 0.1**: Config contract `schemaVersion: 2`, model meta, `home.slots`, scripts, customScreens  
+  - Evidence: `admin-backend/src/adminApp.models.test.ts`
+
+- [x] **Task 0.2**: `bulk-patch` + `background-tasks` + script runner  
+  - Evidence: `admin-backend/src/adminApp.ts`, `admin-script-runner.md`
+
+- [x] **Task 0.3**: `AdminShell`, `AdminHome`, list search/filters/bulk (inline), form fieldsets/readonly  
+  - Evidence: `admin-frontend/src/AdminShell.tsx`, `AdminHome.tsx`, `AdminModelTable.tsx`, `AdminModelForm.tsx`
+
+- [x] **Task 0.4**: Audit log + `recentActivity` widget  
+  - Evidence: `example-backend` `AdminAuditLog`, `AdminHome.test.tsx`
+
+- [x] **Task 0.5**: admin-spa + example v2 demo  
+  - Evidence: `admin-spa/`, `example-backend/src/server.ts` v2 registrations
+
+---
+
+## Phase 1 — Core API surface (`@terreno/api`)
+
+- [x] **Task 1.0**: Extend `TerrenoPlugin.register` additively  
+  - `register(app, openApi?, terrenoApp?)`; `TerrenoApp.build()` passes `this`; rename `_buildWithOpenApi` → `_buildWithContext({openApi, terrenoApp})`; `setMaxListeners(50)`  
+  - Files: `api/src/terrenoPlugin.ts`, `terrenoApp.ts`, `api.ts`  
+  - Acceptance: Existing plugins compile; test receives `terrenoApp` as third arg.
+
+- [x] **Task 1.1**: `api/src/adminTypes.ts`  
+  - Export `AdminConfig`, `AdminFilter`, `AdminFieldset`, `AdminContribution`, `AdminModelContribution`, `AdminCustomScreen`, `AdminHomeWidgetContribution`, `AdminChangeEvent`, etc. (no `AdminAction.run` — bulk stays declarative v2 shape)  
+  - Files: `api/src/adminTypes.ts`, `index.ts`  
+  - Acceptance: `bun run compile` clean across monorepo.
+
+- [x] **Task 1.2**: `admin?: AdminConfig` on `ModelRouterOptions`  
+  - Files: `api/src/api.ts`  
+  - Depends on: 1.1
+
+- [x] **Task 1.3**: `TerrenoApp.getRegistrations()` + `getPlugins()`  
+  - Files: `api/src/terrenoApp.ts`, tests  
+  - Depends on: none
+
+- [x] **Task 1.4**: `TerrenoPlugin.adminContribution?()`  
+  - Files: `api/src/terrenoPlugin.ts`  
+  - Depends on: 1.1
+
+- [x] **Task 1.5**: Typed event bus (`admin:model.changed`)  
+  - Files: `api/src/terrenoApp.ts`, tests  
+  - Depends on: 1.1
+
+- [x] **Task 1.6**: `scrubAdminFields` helper + populated recursion  
+  - Files: `api/src/scrubAdminFields.ts`, tests  
+  - Depends on: 1.1
+
+- [x] **Task 1.7**: Emit scrubbed `admin:model.changed` when `admin.realtime`  
+  - Files: `api/src/api.ts`, tests  
+  - Depends on: 1.0, 1.2, 1.5, 1.6
+
+- [x] **Task 1.8**: `readonlyFields` / `excludeFields` enforcement on body-accepting routes  
+  - Files: `api/src/api.ts`, tests  
+  - Depends on: 1.0, 1.2, 1.6
+
+- [x] **Task 1.9**: Wire `scrubAdminFields` into admin response paths (populated refs)  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 1.6, 2.2
+
+---
+
+## Phase 2 — Admin backend aggregation
+
+- [x] **Task 2.1**: `legacy.ts` adapter + deprecation warnings  
+  - Files: `admin-backend/src/legacy.ts`, tests  
+  - Depends on: 1.1
+
+- [x] **Task 2.2**: Aggregate from modelRouter `admin:` + plugins + legacy `models`  
+  - Precedence: registered router > plugin > legacy; throw on duplicate registered `routePath`  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 1.3, 1.4, 2.1
+
+- [x] **Task 2.3**: Merge `customScreens`, `homeWidgets` → `widgetIds`, plugin `scripts`  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 2.2
+
+- [x] **Task 2.4**: Add `widgetIds`, `capabilities` to `/admin/config` (additive; v2 fields unchanged)  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 2.2
+
+- [x] **Task 2.5**: Static `permissions` flags on config (v2 behavior — **no per-user eval**)  
+  - Verify/document: flags reflect `adminPermissions` config, not runtime user  
+  - Files: `admin-backend/src/adminApp.ts` (docs/tests only if already correct)  
+  - Depends on: 2.4
+
+- [x] **Task 2.6**: `filterParser.ts` — strict per-type validation, injection hardening  
+  - Accept v2-compatible query shapes (`field`, `field_gte`/`field_lte` for dateRange, etc.)  
+  - Files: `admin-backend/src/filterParser.ts`, tests (matrix from original IP)  
+  - Depends on: 1.1
+
+- [x] **Task 2.7**: Wire filterParser + `adminFilter` async + `sortableFields` enforcement  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 2.6
+
+- [x] **Task 2.8**: `routePath` normalization + collision rules  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 2.2
+
+- [x] **Task 2.9**: Export types from `admin-backend/src/index.ts`  
+  - Depends on: 2.2
+
+---
+
+## Phase 3 — Admin frontend foundations
+
+- [x] **Task 3.1**: `AdminProvider` + three-bucket widget registry + hooks  
+  - Files: `admin-frontend/src/AdminProvider.tsx`, `types.ts`, tests  
+  - Depends on: none
+
+- [x] **Task 3.2**: Extend frontend types for `widgetIds`, `capabilities`, `autocompleteFields`, `excludeFields`  
+  - Files: `admin-frontend/src/types.ts`  
+  - Depends on: 2.4
+
+- [x] **Task 3.3**: `AdminScreenRouter`  
+  - Files: `admin-frontend/src/AdminScreenRouter.tsx`, tests  
+  - Depends on: 3.1, 3.2, 2.3
+
+- [x] **Task 3.4**: Refactor `AdminHome` — slots + registry (built-ins + plugin ids)  
+  - Extract widget renderers to `widgets/`; keep slot layout from v2  
+  - Files: `admin-frontend/src/AdminHome.tsx`, `widgets/*`, tests  
+  - Depends on: 3.1, 3.2
+
+- [x] **Task 3.5**: Extract built-in widgets to `widgets/`  
+  - `ModelsGridWidget`, `ModelStatsWidget`, `RecentActivityWidget`, `ScriptRunnerWidget`, `CustomScreensListWidget`, `VersionConfigWidget`  
+  - Files: `admin-frontend/src/widgets/*.tsx`, tests  
+  - Depends on: 3.4
+
+- [x] **Task 3.6**: `AdminFieldRenderer` + form widget lookup from context  
+  - Files: `AdminFieldRenderer.tsx`, `AdminModelForm.tsx`, tests  
+  - Depends on: 3.1
+
+- [x] **Task 3.7**: `AdminModelList` thin wrapper → `AdminHome` + deprecation for `customScreens` prop  
+  - Files: `AdminModelList.tsx`  
+  - Depends on: 3.4
+
+- [x] **Task 3.8**: Package exports (`AdminProvider`, `AdminScreenRouter`, `BUILT_IN_*_WIDGETS`)  
+  - Files: `admin-frontend/src/index.tsx`  
+  - Depends on: 3.1–3.7
+
+---
+
+## Phase 4 — Admin frontend feature lift
+
+- [x] **Task 4.1**: `AdminFilterDrawer` — replace inline filters in `AdminModelTable`  
+  - Mobile sheet; testIDs per original spec  
+  - Files: `AdminFilterDrawer.tsx`, `AdminModelTable.tsx`, tests  
+  - Depends on: 3.2
+
+- [x] **Task 4.2**: Extract `AdminActionMenu` — still uses `bulk-patch` / `background-tasks`  
+  - Files: `AdminActionMenu.tsx`, `AdminModelTable.tsx`, tests  
+  - Depends on: none (v2 logic move)
+
+- [x] **Task 4.3**: Bulk selection polish — clear on filter/search/sort change (verify v2)  
+  - Files: `AdminModelTable.tsx`, tests  
+  - Depends on: 4.1
+
+- [x] **Task 4.4**: `sortableFields` + `pageSize` UI enforcement (verify/complete v2)  
+  - Files: `AdminModelTable.tsx`, tests  
+  - Depends on: 2.7
+
+- [x] **Task 4.5**: `autocompleteFields` async ref picker  
+  - Files: `AdminRefField.tsx`, `AdminModelForm.tsx`, tests  
+  - Depends on: 3.2
+
+- [x] **Task 4.6**: Static permission UI — hide create/delete/actions when flags false  
+  - Files: `AdminModelTable.tsx`, `AdminModelForm.tsx`, `AdminActionMenu.tsx`  
+  - Depends on: 2.5, 4.2
+
+---
+
+## Phase 5 — Pre-built admin migrations
+
+- [x] **Task 5.1**: Document plugin widget location (`docs/explanation/admin-plugin-frontend.md`)
+  - Decision: widgets live in `admin-frontend/src/widgets/`  
+  - Depends on: none
+
+- [x] **Task 5.2**: `FeatureFlagsApp.adminContribution()` + deprecate `featureFlagAdminConfig`
+  - Files: `feature-flags/src/featureFlagsApp.ts`, tests  
+  - Depends on: 1.4, 2.2
+
+- [x] **Task 5.3**: `FeatureFlagOverridesWidget` in `admin-frontend/src/widgets/`
+  - Files: `widgets/FeatureFlagOverridesWidget.tsx`, tests, exports  
+  - Depends on: 3.1, 5.2
+
+- [x] **Task 5.4**: `ConsentApp.adminContribution()` + consent field widgets registry
+  - Files: consent app, `widgets/consentWidgets.ts`, tests  
+  - Depends on: 1.4, 2.2, 3.6
+
+- [x] **Task 5.5**: `DocumentStorageApp.adminContribution()` + `DocumentsScreenWidget`
+  - Files: `documentStorageApp.ts`, `widgets/DocumentsScreenWidget.tsx`, tests  
+  - Depends on: 1.4, 2.3, 3.3
+
+- [x] **Task 5.6**: `AIAdminApp` plugin + `AIRequestsScreenWidget`
+  - Files: `ai/src/aiAdminApp.ts`, `widgets/AIRequestsScreenWidget.tsx`, tests  
+  - Depends on: 1.4, 2.3
+
+---
+
+## Phase 6 — Examples, docs, E2E (single atomic PR)
+
+- [x] **Task 6.1**: Audit consent custom screens — `docs/explanation/admin-consent-migration.md`
+  - Depends on: 5.4
+
+- [x] **Task 6.2**: **Atomic** migrate `example-backend` — `admin:` on modelRouters, plugins only, one legacy `models[]` entry, `home.slots`
+  - Files: `example-backend/src/server.ts`, `api/todos.ts`, `api/users.ts`  
+  - Depends on: 5.2, 5.4, 5.5, 5.6
+
+- [x] **Task 6.3**: **Atomic** migrate `example-frontend` + `admin-spa` — `AdminProvider`, `AdminHome`, `AdminScreenRouter`
+  - Files: `example-frontend/app/admin/**`, `admin-spa/app/**`  
+  - Depends on: 3.8, 5.3, 5.5, 5.6
+
+- [x] **Task 6.4**: How-to: `admin-add-model.md`, `admin-custom-widget.md`, `admin-custom-home.md`, `admin-import-prebuilt.md`
+  - Depends on: 6.2, 6.3
+
+- [x] **Task 6.5**: Reference: `docs/reference/admin-config.md`
+  - Depends on: 1.1
+
+- [x] **Task 6.6**: Playwright E2E (split by feature file)
+  - `admin-home.spec.ts`, `admin-table-search-filter.spec.ts`, `admin-table-bulk-actions.spec.ts`, `admin-form.spec.ts`, `admin-custom-screens.spec.ts`  
+  - Depends on: 6.3
+
+---
+
+## Phase 7 — Deprecations & polish
+
+- [ ] **Task 7.1**: Update admin-backend + admin-frontend rule files  
+  - Files: `.cursor/rules/admin-*/`, `.claude/rules/admin-*/`
+
+- [ ] **Task 7.2**: MCP `generate_route` emits `admin:` block; optional `generate_admin_widget`  
+  - Files: `mcp-server/src/tools.ts`, `prompts.ts`
+
+- [ ] **Task 7.3**: CHANGELOG + minor version bump note  
+  - Files: package CHANGELOGs
+
+- [ ] **Task 7.4**: `docs/how-to/admin-migrate.md` for downstream consumers  
+  - Depends on: 6.3
+
+- [ ] **Task 7.5**: Structured admin telemetry logs (config size, filter errors, deprecation warnings)  
+  - Files: `admin-backend/src/adminApp.ts`, `filterParser.ts`, `legacy.ts`
+
+- [ ] **Task 7.6**: Monorepo compile + lint + test green  
+  - Depends on: all
+
+---
+
+## Removed from scope (per decisions)
+
+- ~~`actionRunner.ts` / `POST .../actions/:name`~~ → use v2 `bulk-patch`
+- ~~`AdminActionContext` / frozen action context~~ → not needed without custom action runners
+- ~~Per-user `/admin/config` permission booleans~~ → static flags; see RBAC IP
+- ~~`home.widgets` typed layout~~ → `home.slots` only