@terreno/mcp 0.21.0

package/dist/docs/versioned/next/tasks/admin-only.md

@@ -0,0 +1,221 @@
+# Task List: Admin-Only — Serve Admin SPA From a Terreno Backend
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+See: `docs/implementationPlans/admin-only.md` for full plan.
+
+## Phase 0: admin-frontend prop split (prerequisite — verified blocker)
+
+- [ ] **Task 0.1**: Split `baseUrl` → `apiBase` + `routeBase` across admin-frontend
+  - Description: Add optional `apiBase` and `routeBase` props alongside the existing `baseUrl` to every exported admin-frontend component. Internally resolve `const apiBase = props.apiBase ?? props.baseUrl; const routeBase = props.routeBase ?? props.baseUrl;`. Replace each occurrence: `useAdminConfig(api, baseUrl)` → `useAdminConfig(api, apiBase)`; `useAdminApi(api, baseUrl, modelName)` → `useAdminApi(api, apiBase, modelName)`; every `router.push(\`${baseUrl}/...\`)` and `href: \`${baseUrl}/...\`` → use `routeBase` instead.
+  - Files: `admin-frontend/src/AdminModelList.tsx`, `AdminModelTable.tsx`, `AdminModelForm.tsx`, `AdminRefField.tsx`, `AdminScriptList.tsx`, `AdminVersionConfig.tsx`, `ConfigurationScreen.tsx`, `useAdminConfig.tsx`, `useAdminApi.ts`, `AdminScriptRunModal.tsx` (if it references baseUrl)
+  - Depends on: none
+  - Acceptance: `bun run admin-frontend:lint` + `bun run admin-frontend:compile` pass. Type-check passes.
+
+- [ ] **Task 0.2**: Tests for prop split
+  - Description: Add a focused test asserting that when `apiBase="/admin"` + `routeBase="/console"` are passed, `useAdminConfig` is called with `/admin` and `router.push` is invoked with `/console/${modelName}`. Also assert backward-compat: `baseUrl="/admin"` alone still works (both internally default to `/admin`).
+  - Files: `admin-frontend/src/AdminModelList.test.tsx`, `AdminModelTable.test.tsx`
+  - Depends on: 0.1
+  - Acceptance: `bun run admin-frontend:test` passes with new assertions.
+
+- [ ] **Task 0.3**: Verify embedded admin still works
+  - Description: Run `example-frontend` against `example-backend`. Log in as admin, navigate to `/admin`, click through a model. Verify no regression. No code change expected — this is a verification step.
+  - Files: (manual)
+  - Depends on: 0.1
+  - Acceptance: All embedded admin flows in example-frontend render and function identically to pre-Phase 0.
+
+## Phase 1: Package scaffolding
+
+- [ ] **Task 1.1**: Create `admin-spa/` workspace package files
+  - Description: Create `package.json` (`@terreno/admin-spa`, version 0.13.0, deps mirror needed runtime: `@terreno/admin-frontend`, `@terreno/rtk`, `@terreno/ui`, `expo`, `expo-router`, `react`, `react-native-web`, `redux-persist`, `better-auth`; peer dep `@terreno/api`; dev deps mirror `example-frontend`). Add `tsconfig.json` (extends Expo preset, covers `app/`, `store/`, `components/`), `tsconfig.server.json` (covers `src/`, outputs `src/dist/`), `biome.jsonc` and `bunfig.toml` copied from `admin-frontend`, `babel.config.js` and `metro.config.js` copied from `example-frontend` (with workspace path adjustments), `app.json` with `web.output: "static"` and `extra.BASE_URL: "__SAME_ORIGIN__"`.
+  - Files: `admin-spa/package.json`, `admin-spa/tsconfig.json`, `admin-spa/tsconfig.server.json`, `admin-spa/biome.jsonc`, `admin-spa/bunfig.toml`, `admin-spa/babel.config.js`, `admin-spa/metro.config.js`, `admin-spa/app.json`, `admin-spa/.gitignore` (must include `dist/`, `store/openApiSdk.ts`, `src/dist/`)
+  - Depends on: none
+  - Acceptance: `bun install` from root succeeds; `bun run --filter '@terreno/admin-spa' compile` is a no-op (succeeds with no source yet).
+
+- [ ] **Task 1.2**: Register workspace in root and add scripts
+  - Description: Add `"admin-spa"` to `workspaces` array in root `package.json`. Add `admin-spa:compile`, `admin-spa:lint`, `admin-spa:test`, `admin-spa:build`, `admin-spa:sdk` scripts mirroring the admin-backend/admin-frontend convention.
+  - Files: `package.json` (root)
+  - Depends on: 1.1
+  - Acceptance: `bun install` resolves admin-spa; `bun run admin-spa:lint` runs (even with no source).
+
+- [ ] **Task 1.3**: Stub server-side plugin entry
+  - Description: Create `src/index.ts` exporting `AdminSpaServeApp` (stub class implementing `TerrenoPlugin` with empty `register()`). Create `src/appConfig.ts` with `AdminSpaAppConfig` interface and `DEFAULT_APP_CONFIG`. Run `tsc -p tsconfig.server.json` and verify `src/dist/` is produced.
+  - Files: `admin-spa/src/index.ts`, `admin-spa/src/appConfig.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` outputs `src/dist/index.js` and `src/dist/appConfig.js`.
+
+- [ ] **Task 1.4**: Stub Expo Router app entry
+  - Description: Create minimal `app/_layout.tsx` (just `<Stack/>`) and `app/index.tsx` rendering a `<Box>Hello admin</Box>` from `@terreno/ui`. Goal: verify the static export pipeline works end-to-end before adding real logic.
+  - Files: `admin-spa/app/_layout.tsx`, `admin-spa/app/index.tsx`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' build:web` produces `dist/index.html`, `dist/_expo/...`, no errors. Open `dist/index.html` in a browser → "Hello admin" renders.
+
+## Phase 2: Same-origin BASE_URL support
+
+- [ ] **Task 2.1**: Add `__SAME_ORIGIN__` sentinel to `@terreno/rtk`
+  - Description: Add `export const SAME_ORIGIN_SENTINEL = "__SAME_ORIGIN__";` to `rtk/src/constants.ts`. Modify `resolveBaseUrls` signature to accept optional `windowOrigin?: string`. When `baseFromExtra === SAME_ORIGIN_SENTINEL` and `windowOrigin` (or `globalThis.location?.origin`) is set, return `{baseUrl: origin, baseTasksUrl: `${origin}/tasks`, baseWebsocketsUrl: `${origin.replace(/^http/, "ws")}/`}`. Module-level call passes `globalThis.location?.origin` (with safe `typeof` check).
+  - Files: `rtk/src/constants.ts`
+  - Depends on: none
+  - Acceptance: Existing tests pass; new sentinel-aware path returns expected URLs.
+
+- [ ] **Task 2.2**: Tests for same-origin sentinel
+  - Description: Add tests to `rtk/src/constants.test.ts` covering: (a) sentinel + `windowOrigin: "https://api.example.com"` → `https://...` + `wss://...`; (b) sentinel + `windowOrigin: "http://localhost:4000"` → `http://...` + `ws://...`; (c) sentinel + no window origin → falls back to existing resolution; (d) non-sentinel BASE_URL is unchanged; (e) sentinel + isDev=true behaves the same as production for the sentinel path.
+  - Files: `rtk/src/constants.test.ts`
+  - Depends on: 2.1
+  - Acceptance: `bun run rtk:test` passes including new cases.
+
+## Phase 3: Express plugin
+
+- [ ] **Task 3.1**: Implement `AdminSpaServeApp.register()`
+  - Description: Implement `src/serve.ts`: resolve `basePath` (default `/console`), `distDir` (default `path.resolve(__dirname, "../../dist")` so it works from `src/dist/serve.js`), merged `appConfig`. Register three Express handlers: `express.static` for `_expo/` and `assets/` with `{immutable: true, maxAge: "365d"}`, `GET ${basePath}/app-config.json` returning JSON with `Cache-Control: no-store`, `GET ${basePath}{/*splat}` returning `index.html` with `Cache-Control: no-store`. Log at info level on mount.
+  - Files: `admin-spa/src/serve.ts`, `admin-spa/src/index.ts` (export)
+  - Depends on: 1.3
+  - Acceptance: `bun run admin-spa:compile` produces `src/dist/serve.js`; manual import from Node ESM works.
+
+- [ ] **Task 3.2**: Plugin unit tests
+  - Description: Add `src/serve.test.ts` using `supertest`. Create a tmpdir with stub `index.html` ("STUB-SPA"), `_expo/static/js/web/foo.abc123.js` ("CONTENT"), and `assets/foo.png` (any bytes). Construct an Express app and register the plugin with `distDir` pointing at the tmpdir. Cases: `GET /console/` → 200 + STUB-SPA + `Cache-Control: no-store`; `GET /console/users` → 200 + STUB-SPA (fallback); `GET /console/users/abc123` → 200 + STUB-SPA; `GET /console/_expo/static/js/web/foo.abc123.js` → 200 + CONTENT + cache headers; `GET /console/app-config.json` → 200 + JSON with `brandName: "Terreno Admin"` (default) + `Cache-Control: no-store`; `GET /console/app-config.json` with custom appConfig → returns merged config; `GET /unrelated` → 404 (plugin doesn't catch outside `basePath`); custom `basePath: "/admin-ui"` works.
+  - Files: `admin-spa/src/serve.test.ts`
+  - Depends on: 3.1
+  - Acceptance: `bun run admin-spa:test` passes all cases.
+
+## Phase 4: SPA — gates and auth
+
+- [ ] **Task 4.1**: AppConfigGate component
+  - Description: Create `components/AppConfigGate.tsx`. Uses React context to expose `AdminSpaAppConfig`. On mount, fetches `./app-config.json` (relative to current URL — so `/console/app-config.json` when mounted at `/console`). Defines defaults to merge with response. Renders a centered `<Spinner>` with `testID="admin-spa-app-config-loading"` while loading. Errors → renders a `<Text>` with retry button. Exposes `useAppConfig()` hook.
+  - Files: `admin-spa/components/AppConfigGate.tsx`
+  - Depends on: 1.4, 3.1
+  - Acceptance: Build succeeds; importing `useAppConfig` outside the gate throws a clear error.
+
+- [ ] **Task 4.2**: StoreProvider component (replaces "factory function" pattern)
+  - Description: Create `components/StoreProvider.tsx`. Reads `useAppConfig()`. Inside the component body, memo-builds `authClient = createAuthClient({baseURL: window.location.origin, basePath: appConfig.authBasePath ?? "/api/auth"})` using `better-auth/react` **directly** (NOT `@terreno/rtk`'s factory — that one is RN-targeted with the expo plugin). Builds `{betterAuthReducer, middleware, selectors} = generateBetterAuthSlice(authClient)`, then `store = configureStore({reducer: {betterAuth: betterAuthReducer, [openapi.reducerPath]: openapi.reducer}, middleware: (gdm) => gdm().concat(openapi.middleware, ...middleware)})`, then `persistor = persistStore(store)`. Wraps children: `<Provider store={store}><PersistGate loading={<Spinner testID="admin-spa-persist-loading"/>} persistor={persistor}>{children}</PersistGate></Provider>`. The `loading` prop is **required** — without it, AdminGate flashes the login screen during rehydration.
+  - Files: `admin-spa/components/StoreProvider.tsx`, `admin-spa/store/sdk.ts` (re-exports `emptySplitApi as openapi` from `@terreno/rtk` with tag types)
+  - Depends on: 4.1, 6.1
+  - Acceptance: Build succeeds; type-check passes; no `expo-secure-store` import surfaces in the bundle (since this is web-only).
+
+- [ ] **Task 4.3**: AdminGate component
+  - Description: Create `components/AdminGate.tsx`. Wraps children. On mount, calls `authClient.getSession()`. Uses `useSelectIsAuthenticated`. Renders spinner with `testID="admin-spa-admin-gate-loading"` while loading. If unauth and not on `/login`, `router.replace("/login")`. If auth + `user.admin !== true` and not on `/forbidden`, `router.replace("/forbidden")`. If auth + admin and on `/login` or `/forbidden`, `router.replace("/")`. Otherwise pass through.
+  - Files: `admin-spa/components/AdminGate.tsx`
+  - Depends on: 4.2
+  - Acceptance: Build succeeds; gate logic verifiable via unit test of selector behavior (`bun test`).
+
+- [ ] **Task 4.4**: Login screen
+  - Description: Create `app/login.tsx`. Reads `useAppConfig().providers`. Renders form with `TextField` (email) + `TextField` (password, type="password") + `Button` ("Sign in") calling `authClient.signIn.email({email, password})`. For each provider in `providers` that isn't `"email"`, renders a `SocialLoginButton`. Handles loading, error display. On success, `router.replace("/")`. testIDs as listed in IP.
+  - Files: `admin-spa/app/login.tsx`
+  - Depends on: 4.3
+  - Acceptance: Rendering the SPA logged-out shows the login form; clicking submit attempts the better-auth signIn (verifiable by mock in unit test).
+
+- [ ] **Task 4.5**: Forbidden screen + signout
+  - Description: Create `app/forbidden.tsx`. Renders `<Page>` with heading "Admins only" and explanation text. Includes a "Sign out" button calling `authClient.signOut()` then `router.replace("/login")`.
+  - Files: `admin-spa/app/forbidden.tsx`
+  - Depends on: 4.3
+  - Acceptance: Build succeeds; testID on screen root.
+
+- [ ] **Task 4.6**: Root layout assembly (correct provider order)
+  - Description: Update `app/_layout.tsx`. Order: `<AppConfigGate><StoreProvider><TerrenoProvider><AdminGate><Stack screenOptions={{headerShown: false}}>...</Stack></AdminGate></TerrenoProvider></StoreProvider></AppConfigGate>`. AppConfigGate is outermost because it has no Redux dependency and its result is needed to build the store. StoreProvider includes Provider + PersistGate. TerrenoProvider is inside Provider so theme hooks can read store state. AdminGate is innermost so it sees fully-hydrated state.
+  - Files: `admin-spa/app/_layout.tsx`
+  - Depends on: 4.1, 4.2, 4.3, 4.4, 4.5
+  - Acceptance: `bun run admin-spa:build` succeeds with no Metro errors. Sequential render: loading splash → (rehydrating) spinner → (unauth) login OR (admin) model list. No login flash for authenticated admins.
+
+## Phase 5: Wire admin screens
+
+All screens pass `apiBase={appConfig.adminApiBasePath ?? "/admin"}` AND `routeBase=""` so navigation stays inside the SPA's `/console` root. Depends on Phase 0.
+
+- [ ] **Task 5.1**: Model list screen
+  - Description: `app/index.tsx` renders `<AdminModelList api={terrenoApi} apiBase={apiBase} routeBase={routeBase} />`. Get values from `useAppConfig()`: `const apiBase = appConfig.adminApiBasePath ?? "/admin"; const routeBase = "";`.
+  - Files: `admin-spa/app/index.tsx`
+  - Depends on: 4.6, 0.1
+  - Acceptance: After login, model list renders models from `${apiBase}/config`. Clicking a model card calls `router.push("/${modelName}")` (relative to SPA root), NOT `/admin/${modelName}`.
+
+- [ ] **Task 5.2**: Model table + form routes
+  - Description: Create `app/[model]/_layout.tsx` (`<Stack/>`), `app/[model]/index.tsx` (renders `<AdminModelTable>`), `app/[model]/[id].tsx` (renders `<AdminModelForm id={id}>`), `app/[model]/create.tsx` (renders `<AdminModelForm>`). Use `useLocalSearchParams()` for params. Handle the `__scripts` and `version-config` sentinels like example-frontend does.
+  - Files: `admin-spa/app/[model]/_layout.tsx`, `admin-spa/app/[model]/index.tsx`, `admin-spa/app/[model]/[id].tsx`, `admin-spa/app/[model]/create.tsx`
+  - Depends on: 5.1
+  - Acceptance: Navigating to `/console/Users` shows the table; clicking a row opens the form.
+
+- [ ] **Task 5.3**: Configuration + scripts + version-config screens
+  - Description: Create `app/configuration.tsx`, `app/scripts.tsx`, `app/version-config.tsx` wrapping the corresponding `@terreno/admin-frontend` screens (`ConfigurationScreen`, `AdminScriptList`, `AdminVersionConfig`).
+  - Files: `admin-spa/app/configuration.tsx`, `admin-spa/app/scripts.tsx`, `admin-spa/app/version-config.tsx`
+  - Depends on: 5.1
+  - Acceptance: Each screen renders without errors.
+
+- [ ] **Task 5.4**: Not-found + Expo Router conventions
+  - Description: Create `app/+not-found.tsx` rendering a friendly 404 with link back to `/`. Add `app/+html.tsx` if needed for static export head config (favicon, viewport).
+  - Files: `admin-spa/app/+not-found.tsx`, `admin-spa/app/+html.tsx`
+  - Depends on: 4.6
+  - Acceptance: Visiting `/console/nonexistent` shows the 404 screen.
+
+## Phase 6: SDK glue (no codegen by default)
+
+Admin endpoints are runtime-injected by `admin-frontend/src/useAdminApi.ts` — codegen is unnecessary for the admin flow itself.
+
+- [ ] **Task 6.1**: Hand-written `store/sdk.ts`
+  - Description: Create `store/sdk.ts` that re-exports `emptySplitApi as openapi` from `@terreno/rtk` and uses `.enhanceEndpoints({addTagTypes: ["admin-models", "admin-version-config", "admin-scripts", "profile"]})`. Export `const terrenoApi = openapi` for consumers.
+  - Files: `admin-spa/store/sdk.ts`
+  - Depends on: 1.1
+  - Acceptance: `bun run --filter '@terreno/admin-spa' compile` passes; importing `terrenoApi` from `store/sdk` works in app code.
+
+- [ ] **Task 6.2 (optional)**: Codegen config for consumers wanting extended SDKs
+  - Description: Create `openapi-config.ts` pointing at `http://localhost:4000/openapi.json`. Document in README as optional — not part of the standard build.
+  - Files: `admin-spa/openapi-config.ts`, `admin-spa/README.md` section
+  - Depends on: 6.1
+  - Acceptance: Running `bun run --filter '@terreno/admin-spa' sdk` against a live backend regenerates `store/openApiSdk.ts` with all endpoints.
+
+## Phase 7: Example backend integration
+
+- [ ] **Task 7.1**: Add admin-spa dep to example-backend
+  - Description: Add `"@terreno/admin-spa": "workspace:*"` to `example-backend/package.json` dependencies.
+  - Files: `example-backend/package.json`
+  - Depends on: 1.2
+  - Acceptance: `bun install` resolves.
+
+- [ ] **Task 7.2**: Register plugin in example-backend
+  - Description: In `example-backend/src/server.ts`, import `AdminSpaServeApp`. Register it (gated on `process.env.ADMIN_SPA_ENABLED === "true"`) with `basePath: "/console"`, `appConfig: {brandName: "Terreno Example", primaryColor: "#7C3AED", providers: ["email", "google"]}`.
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 7.1, 3.1
+  - Acceptance: With `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth bun run backend:dev`, server starts and logs "Admin SPA mounted at /console/".
+
+- [ ] **Task 7.3**: Manual smoke test
+  - Description: Start the backend with the env flags above. Open `http://localhost:4000/console/`. Confirm: (a) login screen renders with brand name "Terreno Example"; (b) sign in with an admin user → redirects to admin list; (c) clicking a model opens the table; (d) editing a row works; (e) `app-config.json` GET returns the configured shape; (f) non-admin user → forbidden screen. Document any gaps found.
+  - Files: (manual)
+  - Depends on: 7.2, 5.x complete
+  - Acceptance: All six checks pass.
+
+## Phase 8: Docs and rules
+
+- [ ] **Task 8.1**: README for admin-spa
+  - Description: Write `admin-spa/README.md`. Sections: overview, install, register with backend, customizing app-config, regenerating SDK, comparison with embedded admin-frontend usage.
+  - Files: `admin-spa/README.md`
+  - Depends on: 7.3
+  - Acceptance: Reading the README is sufficient for a new consumer to add admin to their backend.
+
+- [ ] **Task 8.2**: rulesync rule file
+  - Description: Author `.claude/rules/admin-spa/00-admin-spa.md` matching the shape of `.claude/rules/admin-frontend/00-admin-frontend.md`. Run `bun run rules` to regenerate `rulesync.jsonc` artifacts. Verify the rule appears in any AI consumer config files generated.
+  - Files: `.claude/rules/admin-spa/00-admin-spa.md`, plus regenerated rulesync artifacts
+  - Depends on: 8.1
+  - Acceptance: `bun run rules:check` passes (no diff after a clean regen).
+
+- [ ] **Task 8.3**: Update CLAUDE.local.md and admin-backend README
+  - Description: Add admin-spa to the packages list in `CLAUDE.local.md`. Add a "Standalone admin SPA" pointer to `admin-backend/README.md`.
+  - Files: `CLAUDE.local.md`, `admin-backend/README.md`
+  - Depends on: 8.1
+  - Acceptance: Both files mention admin-spa and reference the IP.
+
+- [ ] **Task 8.5**: Publish CI job
+  - Description: Add an `admin-spa` publish job to `.github/workflows/publish-on-tag.yml` mirroring the existing 8 publish jobs. Job must: `bun install` → `bun run admin-spa:build` → `bun run admin-spa:compile` → `bun publish --filter '@terreno/admin-spa'`. Without this, tagged releases publish an empty `dist/`.
+  - Files: `.github/workflows/publish-on-tag.yml`
+  - Depends on: 8.1
+  - Acceptance: Dry-run the workflow on a feature branch; verify the tarball contains `src/dist/`, `dist/index.html`, and at least one file in `dist/_expo/`.
+
+- [ ] **Task 8.6**: CI smoke test
+  - Description: New job (or extension of existing E2E workflow). Boots example-backend with `ADMIN_SPA_ENABLED=true AUTH_PROVIDER=better-auth` after running `bun run --filter '@terreno/admin-spa' build:web`. curl `/console/`, `/console/app-config.json`, and one `/console/_expo/static/js/web/*.js` asset. Assert 200s + correct cache headers. Catches path-rewrite regressions in CI.
+  - Files: `.github/workflows/admin-spa-smoke.yml` (new) or update an existing test workflow
+  - Depends on: 7.2, 3.1
+  - Acceptance: Workflow passes on a clean run; mutating the rewrite list in `serve.ts` to omit `_expo` causes a CI failure.
+
+## Optional Phases
+
+- [ ] **Task 9.1 (optional)**: Playwright E2E
+  - Description: Add `e2e/admin-spa.spec.ts` to example-frontend with three tests: anonymous user sees login screen, admin can log in and view model list, non-admin gets forbidden screen.
+  - Files: `example-frontend/e2e/admin-spa.spec.ts`, plus testIDs already added in Phase 4
+  - Depends on: 7.3
+  - Acceptance: `bun run --filter '@terreno/example-frontend' e2e -- admin-spa.spec.ts` passes locally with backend running.

package/dist/docs/versioned/next/tasks/admin-script-runner.md

@@ -0,0 +1,50 @@
+# Task List: Admin Script Runner
+
+*Companion to **Admin UI v2 — Django-parity** (`docs/tasks/admin-ui-v2-django-parity.md`). Script runner ships as part of the same admin stack; this list tracks script-specific deliverables.*
+
+**Status:** Complete — implementation lives in `@terreno/api`, `@terreno/admin-backend`, `@terreno/admin-frontend`, and `admin-spa`. See **`docs/implementationPlans/admin-script-runner.md`**.
+
+See: `docs/implementationPlans/admin-script-runner.md` for the full plan.
+
+## Phase A: Types and persistence (`@terreno/api`)
+
+- [x] **Task A.1**: `ScriptResult`, `ScriptContext`, `ScriptRunner`, `TaskCancelledError`  
+  - Files: `api/src/scriptRunner.ts`  
+  - Acceptance: Typed runner signature; context supports logs, progress, cancellation check.
+
+- [x] **Task A.2**: `BackgroundTask` Mongoose model  
+  - Files: `api/src/scriptRunner.ts`  
+  - Acceptance: Used by AdminApp for script runs; indexes and methods (`addLog`, `updateProgress`, `checkCancellation` static).
+
+## Phase B: HTTP surface (`@terreno/admin-backend`)
+
+- [x] **Task B.1**: Mount `{basePath}/scripts` router when `AdminOptions.scripts` non-empty  
+  - Files: `admin-backend/src/adminApp.ts`  
+  - Acceptance: Routes covered by `adminApp.test.ts`; `/admin/config` OpenAPI schema includes `scripts` array (see example-backend `openapi.test.ts` snapshot). Per-script `POST …/run` paths may not appear as separate paths in merged consumer OpenAPI; behavior is verified in admin-backend tests.
+
+- [x] **Task B.2**: Implement run → create task → async `runner(wetRun, ctx)` → terminal status  
+  - Acceptance: Tests in `admin-backend/src/adminApp.test.ts` (happy path, 403, 404, failure, cancel, wetRun query).
+
+- [x] **Task B.3**: Include `scripts: { name, description }[]` in `GET /admin/config`  
+  - Acceptance: `adminApp.test.ts` / `adminApp.models.test.ts` assertions.
+
+## Phase C: Admin frontend
+
+- [x] **Task C.1**: `useAdminScripts` — RTK mutations/queries for run, get task, cancel  
+  - Files: `admin-frontend/src/useAdminScripts.ts`, isolated hook tests.
+
+- [x] **Task C.2**: `AdminScriptRunModal` + `AdminScriptList`  
+  - Files: `AdminScriptRunModal.tsx`, `AdminScriptList.tsx`, tests + isolated specs.
+
+- [x] **Task C.3**: Shell nav + home **`scriptRunner`** widget  
+  - Files: `AdminShell.tsx`, `AdminHome.tsx`, `AdminHome.test.tsx`  
+  - Acceptance: Widget can live in `navGlobal` / other slots; tests ensure it does not incorrectly mount inside `main` when only `navGlobal` lists it (see Admin UI v2 home tests).
+
+## Phase D: `admin-spa` + example-backend
+
+- [x] **Task D.1**: Routes for scripts screen (`/__scripts`, dedicated `scripts` route)  
+  - Files: `admin-spa/app/[model]/index.tsx`, `admin-spa/app/scripts.tsx`.
+
+- [x] **Task D.2**: Example scripts (count, sync consents, seed flags)  
+  - Files: `example-backend/src/server.ts`  
+  - Acceptance: Scripts appear in config; runnable against dev server.

package/dist/docs/versioned/next/tasks/admin-ui-v2-django-parity.md

@@ -0,0 +1,135 @@
+# Task List: Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+**Status:** All phases below are complete. See `docs/implementationPlans/admin-ui-v2-django-parity.md` for acceptance criteria (also marked complete) and verification pointers.
+
+**Companion:** **Admin script runner** — `docs/implementationPlans/admin-script-runner.md` + `docs/tasks/admin-script-runner.md` (same delivery; documents `/admin/scripts/*`, `BackgroundTask`, and UI).
+
+See: `docs/implementationPlans/admin-ui-v2-django-parity.md` for full plan.
+
+## Phase 1: Admin config contract (backend)
+
+- [x] **Task 1.1**: Extend `AdminConfigResponse` / `GET /admin/config` for schema v2  
+  - Description: Add `schemaVersion`, per-model `group`, `listDisplay`, `listDisplayLinks`, `sortableFields`, `searchFields`, `filters` (typed: boolean, choice, text, dateRange, ref), `fieldsets`, `readonlyFields`, `hiddenFields`, declared `actions` (sync vs `background: true`), `permissions` (`create`/`update`/`delete` booleans), `pageSize`, `realtime`, `home` with **`title` + `slots`** (`navGlobal?`, `contentTop?`, `main?`, `sidebar?` — each an ordered `string[]` of widget ids; Django template-block analogue). Optionally accept legacy `home.widgets[]` for migration → normalize into `slots.main` + `recentActivity` forced last in `sidebar`. Include `customScreens`, existing `scripts`. Preserve v1 config fields for backward compatibility.  
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/index.ts` (exports if needed), tests under `admin-backend/src/*.test.ts`  
+  - Depends on: none  
+  - Acceptance: Typed response; tests assert v1 fields still present; new fields optional-safe for old clients.
+
+- [x] **Task 1.2**: Document OpenAPI for extended config  
+  - Description: Ensure generated OpenAPI documents the new response shape (or manual `openApiBuilder` attachment on config route if required).  
+  - Files: `admin-backend/src/adminApp.ts`  
+  - Depends on: 1.1  
+  - Acceptance: `openapi.json` from a test server includes `/admin/config` response schema additions.
+
+## Phase 2: Bulk patch + background tasks (backend)
+
+- [x] **Task 2.1**: Implement `POST {basePath}{routePath}/bulk-patch`  
+  - Description: Body `{ ids: string[]; patch: Record<string, unknown> }`. Enforce **max 1000** ids. Allowlist patch keys per model from config (or from schema paths). Use `updateMany` / batched updates with per-id validation where needed. Return `{ updated: number; failures?: ... }`.  
+  - Files: `admin-backend/src/adminApp.ts`, new helper module if >300 LOC, tests  
+  - Depends on: 1.1  
+  - Acceptance: Tests for cap, unknown keys rejected, partial failure reporting; `IsAdmin` only.
+
+- [x] **Task 2.2**: Implement `POST /admin/background-tasks` (name finalized in code)  
+  - Description: Map prototype `background: true` actions to enqueue `BackgroundTask` (or existing script runner) with `kind`, target route, ids, metadata. Return `{ taskId }`. Reuse logging/error patterns from script routes.  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 1.1, 2.1 (shared validation helpers optional)  
+  - Acceptance: Test covers enqueue + 403 non-admin; OpenAPI entry exists.
+
+## Phase 3: modelRouter metadata parity (backend / examples)
+
+- [x] **Task 3.1**: Align `modelRouter` registration options with config lists  
+  - Description: For each model exposed in `example-backend` (or chosen demo), set `queryFields`, `sort`, `defaultLimit`/`maxLimit`, `responseHandler` for hidden fields, and `permissions.delete: []` for DotPhrase-style demo.  
+  - Files: `example-backend/src/**`, any consumer `AdminApp` registration  
+  - Depends on: 1.1  
+  - Acceptance: List queries accept filters used in UI; delete disabled where specified.
+
+## Phase 4: Admin frontend — shell + navigation
+
+- [x] **Task 4.1**: Admin shell (sidebar groups, screens, tools, user footer)  
+  - Description: New layout components using `@terreno/ui`; consume config for groups and `customScreens`; support `apiBase`/`routeBase` from prior admin-spa work.  
+  - Files: `admin-frontend/src/**` (new shell module + exports in `index.tsx`)  
+  - Depends on: 1.1  
+  - Acceptance: Lint/compile; story or test renders grouped nav from mock config.
+
+- [x] **Task 4.2**: Top bar breadcrumbs + contextual actions  
+  - Description: Match prototype routes (home, list, form, tool, screen); “Add {singular}” when `permissions.create !== false`.  
+  - Files: `admin-frontend/src/**`  
+  - Depends on: 4.1  
+  - Acceptance: Unit test for breadcrumb labels from route + model meta.
+
+## Phase 5: Admin frontend — list (changelist)
+
+- [x] **Task 5.1**: List view v2 — search, filters, sort, pagination  
+  - Description: Wire `DataTable` to server sort/page; debounced search; typed filters mapped to query params; `listDisplayLinks` drives link columns; inline boolean uses PATCH.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, hooks, types  
+  - Depends on: 1.1, 3.1, 4.1  
+  - Acceptance: Tests with MSW or harness for query serialization; loading/error/empty states.
+
+- [x] **Task 5.2**: Bulk selection + action menu  
+  - Description: Sync actions call `bulk-patch`; confirm modals for `confirm` strings; background actions call enqueue endpoint; cap selection client-side at 1000 with user-visible message.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, possibly `AdminScriptRunModal.tsx` reuse  
+  - Depends on: 2.1, 2.2, 5.1  
+  - Acceptance: Tests for confirm + request bodies.
+
+## Phase 6: Admin frontend — form (change view)
+
+- [x] **Task 6.1**: Fieldsets + readonly + exclude/hidden fields  
+  - Description: Render `fieldsets` with `Accordion`/`Card`; readonly fields not submitted; hidden fields omitted from form and detail panels as specified.  
+  - Files: `admin-frontend/src/AdminModelForm.tsx`, types  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Test that PATCH body excludes readonly keys.
+
+- [x] **Task 6.2**: Autocomplete ref picker  
+  - Description: Debounced fetch against referenced model list endpoint; keyboard/accessibility basics.  
+  - Files: `admin-frontend/src/AdminRefField.tsx` or new component, tests  
+  - Depends on: 5.1 (shared debounce util optional)  
+  - Acceptance: Unit test uses mock list API.
+
+## Phase 7: Home dashboard widgets
+
+- [x] **Task 7.1**: Widget registry + **`home.slots`** layout  
+  - Description: Implement built-ins: `modelStats`, `modelsGrid`, `feature-flags-overrides` (or generic “quick toggles” plugin slot), `versionConfig` summary, `scriptRunner`, `recentActivity`. Render regions in order: **`navGlobal`** (horizontal strip) → **`contentTop`** (full-width above grid) → **`main` | `sidebar`** (two-column). Enforce **`recentActivity` last within `sidebar`** when present. Validate unknown widget ids in dev.  
+  - Files: `admin-frontend/src/**` (new `AdminHome.tsx` or similar), exports  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Tests: (1) `scriptRunner` only in `navGlobal` does not mount inside `main` model grid; (2) `recentActivity` is last in `sidebar` when configured.
+
+## Phase 8: admin-spa + example integration
+
+- [x] **Task 8.1**: Wire new shell + routes in `admin-spa`  
+  - Description: Routes for home v2, list, form, tools, deep links to plugin URLs for screens; regenerate admin SDK if needed.  
+  - Files: `admin-spa/app/**`, `admin-spa/store/**`  
+  - Depends on: 4.x–7.x  
+  - Acceptance: `bun run admin-spa:compile` / smoke script; manual checklist in plan.
+
+- [x] **Task 8.2**: Example-backend registration + seed  
+  - Description: Register illustrative models + `AdminApp` config entries matching v2 demo shape (subset acceptable).  
+  - Files: `example-backend/**`  
+  - Depends on: 3.1  
+  - Acceptance: Running example + admin-spa exercises list/form/home.
+
+## Phase 9 (last): Audit log + recent actions
+
+- [x] **Task 9.1**: `AdminAuditLog` model + persistence (consumer or example-backend)  
+  - Description: Schema with descriptions, indexes on `created`, `modelName`, `actorId`. Optional TTL for retention.  
+  - Files: `example-backend/src/models/**` (or consumer app), types  
+  - Depends on: 8.2 (demo path)  
+  - Acceptance: Model compiles; `checkModelsStrict` happy in non-prod.
+
+- [x] **Task 9.2**: `modelRouter` or read-only list route for audit entries  
+  - Description: `GET` list with pagination, `IsAdmin`, sort `-created`. Consider create-only via internal hooks (no public POST from browser) — prefer server-side logging middleware writing entries.  
+  - Files: `example-backend/src/api/**`, tests  
+  - Depends on: 9.1  
+  - Acceptance: supertest list route returns inserted fixture rows.
+
+- [x] **Task 9.3**: Emit audit rows from admin mutations  
+  - Description: Hook `postUpdate`/`postCreate`/`postDelete` on registered admin models or central middleware in `AdminApp` to write `AdminAuditLog` with verb + label resolution.  
+  - Files: `admin-backend/src/adminApp.ts` and/or example-backend hooks  
+  - Depends on: 9.2  
+  - Acceptance: `onAdminAudit` fires after POST/PATCH/DELETE on admin model routes — **`admin-backend/src/adminApp.models.test.ts`** (`describe("AdminApp onAdminAudit")`). Consumer persistence: `example-backend/src/server.ts` (`AdminAuditLog.create` in `onAdminAudit`).
+
+- [x] **Task 9.4**: Home `recentActivity` widget backed by API  
+  - Description: Fetch latest N audit rows; render as the **final widget in `home.slots.sidebar`**; empty/error states.  
+  - Files: `admin-frontend/src/**` (home widget), `useAdminApi` or dedicated hook  
+  - Depends on: 7.1, 9.3  
+  - Acceptance: UI or integration test shows `recentActivity` below other **sidebar** widgets when multiple sidebar ids are configured.

package/dist/docs/versioned/next/tasks/consent-forms.md

@@ -0,0 +1,193 @@
+# Task List: Consent Forms System
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Models + API
+
+- [ ] **Task 1.1**: ConsentForm Mongoose model
+  - Description: Create ConsentForm schema with all fields (title, slug, version, order, type, content map, defaultLocale, active, captureSignature, requireScrollToBottom, checkboxes with confirmationPrompt, agreeButtonText, allowDecline, declineButtonText, required). Add compound index on {slug, version}, plugins (createdUpdated, isDeleted), and TypeScript types. Every field must have a `description` property.
+  - Files: `api/src/models/consentForm.ts`, `api/src/types/consentForm.ts`
+  - Depends on: none
+  - Acceptance: Model can be imported, schema validates correctly, indexes created
+
+- [ ] **Task 1.2**: ConsentResponse Mongoose model
+  - Description: Create ConsentResponse schema with all fields (userId, consentFormId, agreed, agreedAt, checkboxValues map, locale, signature, signedAt, ipAddress, userAgent, contentSnapshot, formVersionSnapshot). Add index on {userId, consentFormId}, plugins, and TypeScript types. Every field must have a `description` property.
+  - Files: `api/src/models/consentResponse.ts`, `api/src/types/consentResponse.ts`
+  - Depends on: none
+  - Acceptance: Model can be imported, schema validates correctly, indexes created
+
+- [ ] **Task 1.3**: ConsentApp plugin skeleton
+  - Description: Create ConsentApp class implementing TerrenoPlugin. Accept config options (auditTrail, aiConfig, resolveConsentForms callback, supportedLocales). Register method mounts all consent routes on the Express app.
+  - Files: `api/src/consentApp.ts`, `api/src/types/consentApp.ts`
+  - Depends on: 1.1, 1.2
+  - Acceptance: Plugin can be registered with TerrenoApp, config validated
+
+- [ ] **Task 1.4**: ConsentForm CRUD routes via modelRouter
+  - Description: Register ConsentForm modelRouter at `/consent-forms` with IsAdmin permissions for all operations, queryFields (slug, type, active, version), sorting by order. Include validation.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: CRUD endpoints work, OpenAPI spec generated, admin-only access enforced
+
+- [ ] **Task 1.5**: ConsentResponse read routes via modelRouter
+  - Description: Register ConsentResponse modelRouter at `/consent-responses` with IsAdmin permissions. Disable create/update/delete (empty arrays). Enable list and read with populatePaths for consentFormId.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Admin can list and read responses, create/update/delete blocked
+
+- [ ] **Task 1.6**: GET /consents/pending endpoint
+  - Description: Custom route that: (1) fetches all active consent forms with highest version per slug, (2) runs resolveConsentForms callback to filter by user, (3) fetches user's existing ConsentResponses, (4) filters to forms where user hasn't responded to current version, (5) returns ordered by `order` field. Include OpenAPI docs via createOpenApiBuilder.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Returns only pending forms for authenticated user, respects resolver callback, ordered correctly, handles no-pending case
+
+- [ ] **Task 1.7**: POST /consents/respond endpoint
+  - Description: Custom route that creates a ConsentResponse. Validates: consentFormId exists and is active, required checkboxes are all true, signature provided if captureSignature is true. If auditTrail enabled, captures req IP, user agent, form content snapshot for the user's locale, and form version. Include OpenAPI docs.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Creates response with all validations, stores audit data when enabled, returns 400 on validation failures
+
+- [ ] **Task 1.8**: POST /consent-forms/:id/publish endpoint
+  - Description: Custom admin-only route that: (1) reads the consent form by id, (2) creates a new document with same fields but incremented version, (3) sets new document as active, (4) deactivates previous active version of same slug. Include OpenAPI docs.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.4
+  - Acceptance: New version created with incremented version, old version deactivated, returns new document
+
+- [ ] **Task 1.9**: GET /consents/audit/:userId endpoint
+  - Description: Admin-only endpoint that returns all ConsentResponses for a userId, populated with ConsentForm data, sorted by agreedAt descending. Only registers the route when auditTrail option is true. Include OpenAPI docs.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.7
+  - Acceptance: Returns full history with populated forms, 404 when auditTrail not enabled, admin-only
+
+- [ ] **Task 1.10**: Export ConsentApp from @terreno/api
+  - Description: Export ConsentApp class, ConsentForm model, ConsentResponse model, and all related types from api package index.ts.
+  - Files: `api/src/index.ts`
+  - Depends on: 1.3
+  - Acceptance: `import {ConsentApp, ConsentForm, ConsentResponse} from "@terreno/api"` works
+
+- [ ] **Task 1.11**: ConsentApp unit tests
+  - Description: Test all endpoints: CRUD operations on consent forms, pending logic (version checking, resolver callback filtering, ordering), respond (validation of required checkboxes, signature, audit trail data), publish (version increment, deactivation of old), audit endpoint (populated responses, disabled when auditTrail false). Use supertest and bun test.
+  - Files: `api/src/consentApp.test.ts`
+  - Depends on: 1.6, 1.7, 1.8, 1.9
+  - Acceptance: All tests pass, covers happy paths and edge cases (no pending forms, expired versions, missing required fields)
+
+## Phase 2: Admin UI
+
+- [ ] **Task 2.1**: MarkdownEditor component in ui
+  - Description: Split-pane component with textarea on left and MarkdownView preview on right. Props: value, onChange, placeholder, title, disabled, testID. Responsive — stacks vertically on mobile using mediaQueryLargerThan. Uses Box for layout, TextField (multiline) for editing, MarkdownView for preview.
+  - Files: `ui/src/MarkdownEditor.tsx`, `ui/src/MarkdownEditor.test.tsx`, `ui/src/index.tsx`
+  - Depends on: none
+  - Acceptance: Component renders, textarea edits update preview in real-time, responsive layout works, exported from @terreno/ui
+
+- [ ] **Task 2.2**: ConsentFormEditor component in admin-frontend
+  - Description: Custom form for creating/editing consent forms. Sections: (1) Basic fields — title (TextField), slug (TextField), type (SelectField with enum options), order (NumberField), required (BooleanField), active (BooleanField). (2) Form behavior — captureSignature (BooleanField), requireScrollToBottom (BooleanField). (3) Button config — agreeButtonText (TextField), allowDecline (BooleanField), declineButtonText (TextField, shown when allowDecline true). (4) Locale tabs — tab per supportedLocale, each with MarkdownEditor for content. (5) Checkbox list builder — add/remove rows with label (TextField), required (BooleanField), confirmationPrompt (TextField, optional). (6) "Publish New Version" button in edit mode header. Uses useAdminApi for CRUD operations.
+  - Files: `admin-frontend/src/ConsentFormEditor.tsx`
+  - Depends on: 2.1
+  - Acceptance: Can create and edit consent forms with all fields, locale tabs switch content, checkbox builder works, publish button creates new version
+
+- [ ] **Task 2.3**: ConsentFormList component in admin-frontend
+  - Description: Table view for consent forms using DataTable. Columns: title, type, version, active (boolean), order, created. Row click navigates to editor. Create button in header. Uses useAdminApi for list query.
+  - Files: `admin-frontend/src/ConsentFormList.tsx`
+  - Depends on: none
+  - Acceptance: Lists forms with correct columns, pagination works, navigation to editor works, create button works
+
+- [ ] **Task 2.4**: ConsentResponseViewer component in admin-frontend
+  - Description: Read-only detail view for a consent response using Page layout. Shows: form title (populated from consentFormId), userId, agreed status (Badge), agreedAt (formatted with Luxon), locale, checkbox values (list of label + checked/unchecked), signature (rendered as Image from base64 if present), audit trail section (ipAddress, userAgent, contentSnapshot rendered via MarkdownView, formVersionSnapshot) — only shown if audit fields are populated.
+  - Files: `admin-frontend/src/ConsentResponseViewer.tsx`
+  - Depends on: none
+  - Acceptance: Displays all response fields, signature renders correctly, audit section conditional
+
+- [ ] **Task 2.5**: Export admin consent components
+  - Description: Export ConsentFormEditor, ConsentFormList, ConsentResponseViewer from admin-frontend index.tsx.
+  - Files: `admin-frontend/src/index.tsx`
+  - Depends on: 2.2, 2.3, 2.4
+  - Acceptance: All three components importable from `@terreno/admin-frontend`
+
+## Phase 3: ConsentNavigator
+
+- [ ] **Task 3.1**: useConsentForms hook
+  - Description: Hook that accepts an RTK API instance and injects a `getPendingConsents` query endpoint targeting GET /consents/pending. Fetches on mount. Detects device locale via expo-localization or navigator.language. Returns `{forms, isLoading, error, refetch}`. Uses the dynamic endpoint injection pattern from useAdminApi.
+  - Files: `ui/src/useConsentForms.ts`
+  - Depends on: Phase 1
+  - Acceptance: Hook fetches pending forms, handles loading/error states, detects device locale, cache tagged for invalidation
+
+- [ ] **Task 3.2**: useSubmitConsent hook
+  - Description: Hook that accepts an RTK API instance and injects a `submitConsentResponse` mutation endpoint targeting POST /consents/respond. Returns `{submit, isSubmitting, error}`. On success, invalidates the pending consents cache tag. Accepts `{consentFormId, agreed, checkboxValues, signature, locale}`.
+  - Files: `ui/src/useSubmitConsent.ts`
+  - Depends on: Phase 1
+  - Acceptance: Hook submits response, invalidates pending forms cache on success, returns error on failure
+
+- [ ] **Task 3.3**: ConsentFormScreen component
+  - Description: Full-screen component rendering a single consent form. Layout: (1) Page with title from form.title, no back button. (2) Scrollable MarkdownView with content from form.content[locale] (fallback to form.defaultLocale). (3) Scroll-to-bottom tracking — when requireScrollToBottom is true, track scroll position and enable agree button only when scrolled to bottom. (4) Checkboxes section — render each form.checkboxes item as CheckBox. When checkbox has confirmationPrompt, show Modal with that text on toggle, require confirm before changing. (5) SignatureField when captureSignature is true. (6) Footer with agree Button (disabled until all requirements met: scroll, required checkboxes, signature). Optional decline Button when allowDecline is true. Props: form, locale, onAgree, onDecline, isSubmitting.
+  - Files: `ui/src/ConsentFormScreen.tsx`
+  - Depends on: 3.2
+  - Acceptance: All form configurations render correctly, requirements gate the agree button, confirmation modals work, decline button appears conditionally
+
+- [ ] **Task 3.4**: ConsentNavigator component
+  - Description: Inline wrapper component. Props: api (RTK API instance), children, onError (optional callback). On mount, calls useConsentForms to fetch pending forms. States: (1) Loading — show Spinner centered. (2) Pending forms — render ConsentFormScreen for forms[currentIndex]. On agree, call useSubmitConsent then advance currentIndex. On decline (optional forms only), advance currentIndex. When all forms completed, refetch pending to confirm empty, then render children. (3) No pending forms — render children immediately. (4) Error — show ErrorPage with retry, call onError if provided.
+  - Files: `ui/src/ConsentNavigator.tsx`
+  - Depends on: 3.1, 3.3
+  - Acceptance: Blocks children when consents pending, shows forms in order, renders children when complete, handles errors gracefully
+
+- [ ] **Task 3.5**: Export consent components from ui
+  - Description: Export ConsentNavigator, ConsentFormScreen, useConsentForms, useSubmitConsent from ui/src/index.tsx.
+  - Files: `ui/src/index.tsx`
+  - Depends on: 3.4
+  - Acceptance: All components importable from `@terreno/ui`
+
+- [ ] **Task 3.6**: ConsentNavigator tests
+  - Description: Test cases: (1) No pending forms — children render immediately. (2) Pending forms — shows ConsentFormScreen, not children. (3) Completing all forms — children render after last form agreed. (4) Decline on optional form (required: false) — skips to next form. (5) Loading state — shows spinner. (6) Error state — shows error page. Use renderWithTheme and mock API responses.
+  - Files: `ui/src/ConsentNavigator.test.tsx`
+  - Depends on: 3.4
+  - Acceptance: All test cases pass
+
+## Phase 4: AI Generation
+
+- [ ] **Task 4.1**: POST /consent-forms/generate endpoint
+  - Description: Backend endpoint that uses @terreno/ai's AIService (or direct Claude API call if AIService doesn't fit) to generate consent form markdown. Accepts `{type, description, locale}`. System prompt instructs AI to generate a legally-appropriate consent form in markdown format for the given type. Only registered when aiConfig is provided in ConsentApp options. Returns `{data: {content: string}}`. Include OpenAPI docs.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Generates reasonable consent markdown, returns 404 when aiConfig not set, admin-only
+
+- [ ] **Task 4.2**: POST /consent-forms/translate endpoint
+  - Description: Backend endpoint that uses AI to translate consent markdown from one locale to another. Accepts `{content, fromLocale, toLocale}`. System prompt instructs AI to translate preserving all markdown formatting, legal terminology accuracy, and document structure. Only registered when aiConfig is provided. Returns `{data: {content: string}}`. Include OpenAPI docs.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Translates content preserving markdown formatting, admin-only, 404 when aiConfig not set
+
+- [ ] **Task 4.3**: AI generate button in ConsentFormEditor
+  - Description: Add "Generate with AI" Button to the editor that opens a Modal with: type SelectField (pre-filled from form type), description TextField (multiline, placeholder "Describe the consent form you need..."), locale display (current tab's locale). On submit, calls POST /consent-forms/generate via injected RTK mutation, populates the MarkdownEditor for current locale with response. Shows loading state on button. Only visible when the backend supports AI (check for endpoint availability or pass as prop).
+  - Files: `admin-frontend/src/ConsentFormEditor.tsx`
+  - Depends on: 2.2, 4.1
+  - Acceptance: Generate button visible, modal works, generated content populates editor, loading state shown
+
+- [ ] **Task 4.4**: Translate button in ConsentFormEditor
+  - Description: Add "Translate from [defaultLocale]" Button on each non-default locale tab. On click, calls POST /consent-forms/translate with the default locale's content and target locale. Populates the MarkdownEditor for that locale tab with the translated content. Shows loading state. Confirms overwrite if content already exists in that locale.
+  - Files: `admin-frontend/src/ConsentFormEditor.tsx`
+  - Depends on: 2.2, 4.2
+  - Acceptance: Translate button visible per non-default locale tab, translated content populates editor, overwrite confirmation works
+
+## Phase 5: Example App + Docs
+
+- [ ] **Task 5.1**: Integrate ConsentApp into example-backend
+  - Description: Register ConsentApp plugin in example-backend/src/server.ts. Configure with auditTrail: true, supportedLocales: ["en", "es"], and a simple resolveConsentForms that returns all forms. Add CLAUDE_API_KEY to .env.example for AI features. Register ConsentForm and ConsentResponse in AdminApp models array.
+  - Files: `example-backend/src/server.ts`
+  - Depends on: Phase 1
+  - Acceptance: Backend serves all consent endpoints, shows in OpenAPI spec, admin can manage forms
+
+- [ ] **Task 5.2**: Integrate ConsentNavigator into example-frontend
+  - Description: Wrap the authenticated app content (inside tabs layout or root layout after auth check) with ConsentNavigator component, passing the terrenoApi instance. Regenerate SDK with `bun run sdk` to include consent endpoints.
+  - Files: `example-frontend/app/_layout.tsx` or `example-frontend/app/(tabs)/_layout.tsx`, `example-frontend/store/sdk.ts`
+  - Depends on: Phase 3, 5.1
+  - Acceptance: Consent flow blocks app when forms are pending, passes through when none, SDK includes consent types
+
+- [ ] **Task 5.3**: Add consent admin screens to example-frontend
+  - Description: Add admin routes using Expo Router file-based routing: (1) `app/admin/consent-forms/index.tsx` — ConsentFormList, (2) `app/admin/consent-forms/create.tsx` — ConsentFormEditor mode="create", (3) `app/admin/consent-forms/[id].tsx` — ConsentFormEditor mode="edit", (4) `app/admin/consent-responses/index.tsx` — AdminModelTable for responses, (5) `app/admin/consent-responses/[id].tsx` — ConsentResponseViewer.
+  - Files: `example-frontend/app/admin/consent-forms/index.tsx`, `example-frontend/app/admin/consent-forms/create.tsx`, `example-frontend/app/admin/consent-forms/[id].tsx`, `example-frontend/app/admin/consent-responses/index.tsx`, `example-frontend/app/admin/consent-responses/[id].tsx`
+  - Depends on: Phase 2, 5.1
+  - Acceptance: Admin can create/edit/publish consent forms, view responses, full CRUD flow works
+
+- [ ] **Task 5.4**: Seed example consent forms
+  - Description: Add a seed script that creates two sample consent forms: (1) Terms of Service (type: "agreement", required: true, requireScrollToBottom: true, captureSignature: true, order: 1), (2) Privacy Policy (type: "privacy", required: true, requireScrollToBottom: true, order: 2). Both with English content and active: true. Script should be idempotent (check if forms exist before creating).
+  - Files: `example-backend/src/seed.ts` or `example-backend/src/scripts/seedConsents.ts`
+  - Depends on: 5.1
+  - Acceptance: Running seed creates sample forms, re-running doesn't duplicate, example app shows consent flow