@terreno/mcp 57.2.0 → 57.4.0

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

@@ -0,0 +1,85 @@
+# Implementation Plans
+
+Forward-looking design docs for significant features and architectural changes to
+Terreno packages, written **before implementation**.
+
+An implementation plan (IP) is one half of a two-file pair:
+
+| File | Holds | Path |
+| ---- | ----- | ---- |
+| **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
+for *the concrete steps*. External trackers (a GitHub roadmap issue, a Linear issue, a
+discussion thread) link **to** these files — they never replace them. See
+[`docs/tasks/README.md`](../tasks/README.md) for the task-file shape.
+
+## Status lives on each IP
+
+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
+
+Substantial work is planned before coding. Quick rule (full table in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#when-to-write-an-implementation-plan-ip)):
+
+| Needs an IP | Does not need an IP |
+| ----------- | ------------------- |
+| New published package | Bug fix in one package |
+| New public API surface | Documentation-only change |
+| Cross-package architectural change | Small internal refactor |
+| Breaking change | Test or CI fix |
+
+## How a plan gets written and built
+
+The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline.
+
+**Grow** interviews in grilling rounds (one frontier of decisions per message, recommended
+answers, then wait). It stays on a question until the answer is executable. After the user
+confirms shared understanding it writes the two files and ends with a **15-line verify
+index** (destination, in/out, tracer, task graph, test seam). When grilling produced
+human decisions, it lists **every** one in a Decisions table with no row cap. If there
+were none, that table is omitted.
+
+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 until answers are executable, then write the IP + tracer-bullet task list; end with the 15-line verify index and a full Decisions table when any exist.
+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 compact machine-readable result described
+in [`plugins/terreno-planning/references/lifecycle-contract.md`](../../plugins/terreno-planning/references/lifecycle-contract.md)
+(collapsed behind a Details toggle in chat and on the PR).
+
+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),
+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 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).
+2. **In progress** → **Complete** — implemented, verified, merged.
+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/57.2.0/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`

package/src/docs/versioned/57.2.0/implementationPlans/admin-improvements.md

@@ -0,0 +1,207 @@
+# Implementation Plan: Admin Improvements (post–Admin UI v2)
+
+**Status:** Approved  
+**Branch:** (implementation TBD)  
+**Owner:** Josh Gachnang  
+**Created:** 2026-06-01 (original); revised 2026-08-20 post–v2 gap analysis  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1099  
+**Prerequisite:** [Admin UI v2 — Django-parity admin](./admin-ui-v2-django-parity.md) (**Complete**)  
+**Research:** [admin-improvements-research.md](./admin-improvements-research.md)
+## Goal
+
+Finish the **architectural** admin overhaul that Admin UI v2 did not ship: co-locate admin config on `modelRouter`, aggregate admins from plugins via `adminContribution()`, introduce `AdminProvider` + a three-bucket widget registry + `AdminScreenRouter`, harden list filters with a strict parser, lift field scrubbing into `@terreno/api`, and migrate pre-built plugin admins — **on top of** the v2 shell, `home.slots`, `bulk-patch`, and script runner already in production.
+
+## Non-Goals
+
+- Replacing Admin UI v2 UX that already works (shell, slots layout, bulk-patch, background tasks, audit log, scripts).
+- `POST /admin/{resource}/actions/:name` or imperative `AdminAction.run()` handlers — **bulk actions stay on v2** (`bulk-patch` + declarative `patchKeys`, `background: true` → `/admin/background-tasks`).
+- Per-user permission evaluation on `/admin/config` — defer to [RBAC permissions](./rbac-permissions.md); v2 static `permissions.{create,update,delete}` flags remain.
+- `home.widgets` typed array — canonical layout is v2 **`home.slots`** only.
+- Socket.io server / realtime UI push (event bus API surface only).
+- True related-model inlines, `date_hierarchy`, `prepopulated_fields`, `list_editable`, `show_facets`.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Delivery scope | **Full IP** (provider, screen router, filter drawer, filterParser, plugin migrations, docs, E2E) — not architecture-only |
+| Bulk actions API | **v2 only** — `bulk-patch` + `background-tasks`; no `/actions/:name` |
+| Home layout | **`home.slots`** (`navGlobal`, `contentTop`, `main`, `sidebar`); plugin widgets by string id in slots |
+| `/admin/config` permissions | **Static flags** (v2) — not evaluated per requesting user |
+| Filter hardening | **`filterParser`** module with injection tests; **keep v2 query param shape** where compatible |
+| Plugin frontend widgets | **`admin-frontend/src/widgets/`** (option A) |
+| Example migration | **Single atomic PR** — backend + frontend + admin-spa together |
+| Roadmap | **New tracking issue** (not extending admin-ui-v2 issue) |
+| Field names | **No renames** — `listFields`, `defaultSort`, etc. stay; additive options only |
+| TerrenoPlugin signature | Extend `register(app, openApi?, terrenoApp?)` additively; `TerrenoApp.build()` passes `this` |
+| Collision precedence | Registered `modelRouter` with `admin:` **>** plugin `adminContribution()` **>** legacy `AdminApp.models` |
+| Widget registry shape | `{ fields, home, screens }` — locked before implementation |
+
+### Already shipped (Admin UI v2 — out of scope for re-implementation)
+
+Treat as baseline; extend, do not rewrite:
+
+- `schemaVersion: 2`, extended model meta, `home.slots`, `customScreens`, `scripts`
+- `POST .../bulk-patch`, `POST /admin/background-tasks`, script runner routes
+- `AdminShell`, `AdminHome` (built-in widget ids), `AdminModelTable` (search, inline filters, bulk select, declarative actions), `AdminModelForm` (fieldsets, readonly PATCH strip)
+- `AdminAuditLog` + `recentActivity` widget, `admin-spa` + example v2 wiring
+
+## Architecture
+
+```
+@terreno/api
+  modelRouter(..., { admin?: AdminConfig })
+  TerrenoApp.getRegistrations() / getPlugins()
+  TerrenoPlugin.adminContribution?()
+  scrubAdminFields() — shared exclude/hidden + populated recursion
+  TerrenoApp.on/off/emit("admin:model.changed") — no transport
+
+@terreno/admin-backend
+  AdminApp.register() aggregates:
+    1. modelRouter registrations with admin:
+    2. plugin adminContribution()
+    3. legacy AdminApp.models[] (deprecated, one release)
+  filterParser.ts — strict validation on declared filters
+  /admin/config — + widgetIds, capabilities (additive)
+
+@terreno/admin-frontend
+  AdminProvider { api, baseUrl, widgets: { fields, home, screens } }
+  AdminScreenRouter — custom screen vs model table
+  AdminHome — slots + registry (refactor existing)
+  AdminFilterDrawer — replaces inline filter rail
+  widgets/* — built-ins + plugin widgets (FeatureFlagOverrides, Documents, AI, consent field widgets)
+```
+
+## Models
+
+No new framework models. Consumers keep domain models; optional `AdminAuditLog` remains example-only (v2).
+
+## APIs
+
+### Unchanged (v2 — keep)
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /admin/config` | Aggregated metadata + `home.slots` + scripts + screens |
+| CRUD `/admin/{resource}/*` | Per-model admin routes |
+| `POST /admin/{resource}/bulk-patch` | Sync bulk patch (`ids`, `patch`); ≤1000 ids |
+| `POST /admin/background-tasks` | Background bulk / long jobs |
+| `POST /admin/scripts/:name/run` | Curated maintenance scripts |
+
+### New / extended
+
+| Surface | Change |
+|---------|--------|
+| `modelRouter` options | Optional `admin: AdminConfig` (types in `@terreno/api`) |
+| `TerrenoPlugin` | Optional `adminContribution(): AdminContribution` |
+| List queries | `filterParser` validates declared `filters[]` before merge into Mongoose query (same wire shape as v2 `queryFields`) |
+| `TerrenoApp` | `admin:model.changed` emit when `admin.realtime === true` (scrubbed payload) |
+
+### Explicitly rejected
+
+- `POST /admin/{resource}/actions/:name` — use `bulk-patch` / `background-tasks` instead.
+
+## Notifications
+
+In-app **Toast** only (v2). No email/push for admin events.
+
+## UI
+
+- **Shell:** Keep v2 `AdminShell` / `AdminShellLayout`.
+- **Home:** Keep **`home.slots`**; resolve widget ids via `AdminProvider.widgets.home` + built-ins in `widgets/`.
+- **List:** Extract **filter drawer** (`AdminFilterDrawer`); keep v2 search debounce and bulk UI (refactor to `AdminActionMenu` component, still calling `bulk-patch`).
+- **Form:** Field widgets from `AdminProvider.widgets.fields`; `autocompleteFields` async ref search via list endpoint.
+- **Screens:** `AdminScreenRouter` + `widgets.screens` for Documents, AI explorer, consent custom flows.
+- **testIDs:** Preserve v2 ids; add drawer/menu ids from original task spec.
+
+## Phases
+
+### Phase 0 — Baseline (complete)
+
+Admin UI v2. See [admin-ui-v2-django-parity.md](./admin-ui-v2-django-parity.md).
+
+### Phase 1 — Core API surface (`@terreno/api`)
+
+`adminTypes.ts`, `admin` on `modelRouter`, plugin + TerrenoApp extensions, `scrubAdminFields`, event bus, `excludeFields` / `readonlyFields` enforcement at router layer where applicable.
+
+### Phase 2 — Admin backend aggregation
+
+Rewrite `AdminApp` discovery; `legacy.ts`; `filterParser.ts`; `widgetIds` + `capabilities` on config; `adminFilter` async merge into list queries.
+
+### Phase 3 — Admin frontend foundations
+
+`AdminProvider`, registry, `AdminScreenRouter`, refactor `AdminHome` to use registry, extract widgets to `widgets/`.
+
+### Phase 4 — Admin frontend feature lift
+
+`AdminFilterDrawer`, `AdminActionMenu` (bulk-patch), field widgets from context, `autocompleteFields`, permission-gated UI (static flags).
+
+### Phase 5 — Pre-built admin migrations
+
+`FeatureFlagsApp`, `ConsentApp`, `DocumentStorageApp`, `AIAdminApp` → `adminContribution()` + frontend widgets in `admin-frontend/src/widgets/`.
+
+### Phase 6 — Examples, docs, E2E (atomic)
+
+Single PR: `example-backend` + `example-frontend` + `admin-spa`; four how-to docs + `admin-config` reference; Playwright specs.
+
+### Phase 7 — Deprecations & polish
+
+Legacy warnings, rule files, MCP `generate_route`, CHANGELOG.
+
+## Feature Flags & Migrations
+
+- **No breaking config version bump** — stay on `schemaVersion: 2`; additive fields only.
+- `AdminApp.models[]` deprecated one minor cycle with one-time warning per entry.
+- `AdminModelList` `customScreens` prop deprecated when `AdminProvider` is used.
+
+## Activity Log & User Updates
+
+Covered by v2 `AdminAuditLog` + `recentActivity`. No changes unless aggregation hooks need audit labels for plugin-registered models.
+
+## Not Included / Future Work
+
+- Per-user `/admin/config` permission booleans ([rbac-permissions](./rbac-permissions.md)).
+- Custom `AdminAction.run()` / `/actions/:name`.
+- Socket.io fan-out of `admin:model.changed`.
+- `home.widgets` alternate layout API.
+- Cross-model global search, CSV export, granular admin roles beyond `IsAdmin`.
+
+## Files to Create / Modify (summary)
+
+| Area | Key files |
+|------|-----------|
+| api | `adminTypes.ts`, `scrubAdminFields.ts`, `terrenoApp.ts`, `terrenoPlugin.ts`, `api.ts` |
+| admin-backend | `adminApp.ts`, `legacy.ts`, `filterParser.ts`, tests |
+| admin-frontend | `AdminProvider.tsx`, `AdminScreenRouter.tsx`, `AdminFilterDrawer.tsx`, `AdminActionMenu.tsx`, `widgets/*`, refactor `AdminHome.tsx` |
+| plugins | `feature-flags`, consent, `documentStorageApp`, `ai/src/aiAdminApp.ts` |
+| examples | `example-backend/src/server.ts`, `example-frontend/app/admin/**`, `admin-spa/**` |
+| docs | `docs/how-to/admin-*.md`, `docs/reference/admin-config.md` |
+
+## Task List
+
+See **[docs/tasks/admin-improvements.md](../tasks/admin-improvements.md)**.
+
+## Acceptance Criteria
+
+- [ ] `admin: { ... }` on a `modelRouter` appears in `/admin/config` without duplicating entry in `AdminApp.models`.
+- [ ] `new FeatureFlagsApp()` registered on `TerrenoApp` auto-registers FeatureFlag admin; `"feature-flags-overrides"` in `home.slots` renders when listed.
+- [ ] `filterParser` rejects operator injection and prototype-pollution; compatible v2 list URLs still work.
+- [ ] Bulk select + action uses **`bulk-patch`** or **background-tasks** (not `/actions/:name`).
+- [ ] `AdminProvider` + `AdminScreenRouter` replace example-frontend string-switch; Documents + AI screens work via registry.
+- [ ] `AdminFilterDrawer` replaces inline filter rail; mobile sheet behavior preserved.
+- [ ] `excludeFields` / `hiddenFields` scrub populated refs using referenced model's admin config.
+- [ ] `admin.realtime: true` emits scrubbed `admin:model.changed` (unit test); no socket server started.
+- [ ] Legacy `AdminApp.models[]` works with one deprecation warning per entry.
+- [ ] Atomic example migration: backend boots, admin-spa + example-frontend admin E2E green.
+- [ ] How-to + reference docs published; types exported from `@terreno/api`, `@terreno/admin-backend`, `@terreno/admin-frontend`.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Duplicating v2 work | Phase 0 checklist; tasks mark v2 items complete; refactor don't rewrite |
+| `TerrenoApp` ↔ `AdminApp` wiring | Third `terrenoApp` arg on `register`; `_buildWithContext` internal rename |
+| routePath collisions | Throw on duplicate registered routers; warn on plugin vs legacy |
+| Filter parser breaks existing URLs | Parser accepts v2 shapes; tests include v2 example-backend filter queries |
+| Atomic example PR size | Single PR still split into logical commits inside the PR |
+| Widget bundle size | Consumers pass only widgets they import at `AdminProvider` construction |