@terreno/mcp 57.1.0 → 57.2.0

package/src/docs/versioned/0.27.0/tasks/admin-only.md

@@ -1,221 +0,0 @@
-# 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/src/docs/versioned/0.27.0/tasks/consent-forms.md

@@ -1,193 +0,0 @@
-# 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

package/src/docs/versioned/0.27.0/tasks/feature-flags.md

@@ -1,23 +0,0 @@
-# Feature Flags — Task List
-
-## Phase 1: Backend + Evaluation Engine
-
-- [ ] **Task 1.1**: Create `feature-flags/` package with FeatureFlag model (including archived field)
-- [ ] **Task 1.2**: Implement FeatureFlagsApp plugin with modelRouter CRUD
-- [ ] **Task 1.3**: Implement evaluation engine (field rules with dot notation, segment rules, deterministic hashing for boolean rollout and variant assignment)
-- [ ] **Task 1.4**: Implement `/evaluate` and `/segments` custom endpoints
-- [ ] **Task 1.5**: Write tests for evaluation logic
-- [ ] **Task 1.6**: Integrate with example-backend
-
-## Phase 2: Frontend Hook
-
-- [ ] **Task 2.1**: Add `useFeatureFlags()` hook to `@terreno/rtk`
-- [ ] **Task 2.2**: Export from rtk index
-
-## Phase 3: Example App Integration
-
-- [ ] **Task 3.1**: Wire up FeatureFlagsApp in example-backend, register model in AdminApp
-- [ ] **Task 3.2**: Add sample flags and use `useFeatureFlags()` in example-frontend
-- [ ] **Task 3.3**: Regenerate SDK
-
-See `docs/implementationPlans/feature-flags.md` for full details on each task.

package/src/docs/versioned/0.27.0/tasks/model-router-actions.md

@@ -1,46 +0,0 @@
-# modelRouter Actions — Task List
-
-## Phase 1: Foundation (types + runtime + per-route OpenAPI middleware)
-
-- [ ] **Task 1.1**: Add `zod ^4.3.6` as a **peerDependency** of `@terreno/api` (also pin `^4.3.6` in `devDependencies` so the package compiles/tests on its own) and `@asteasolutions/zod-to-openapi ^8.5.0` as a regular `dependency` (it bundles its own usage). Use Bun catalog for Zod if a catalog version exists.
-- [ ] **Task 1.2**: Create `api/src/docLoader.ts` exporting `loadDocOr404(model, id, populatePaths?)`. Behavior matches the existing permission middleware doc-load (`permissions.ts:148–200`): 404 on missing, soft-delete-aware metadata via `model.collection.findOne` fallback.
-- [ ] **Task 1.3**: Refactor `permissionMiddleware` in `api/src/permissions.ts` to call `loadDocOr404`. Add a regression test asserting soft-delete 404 metadata is intact. No public API change.
-- [ ] **Task 1.4**: Create `api/src/actions.ts` with public types: `ActionContext`, `BaseActionConfig`, `InstanceActionConfig`, `CollectionActionConfig`. Also export `defineInstanceAction()` and `defineCollectionAction()` identity helpers that preserve per-action generics across the `Record<string, ...>` boundary.
-- [ ] **Task 1.5**: Implement `runActionPermissions(action, scope, req, doc?)` in `api/src/actions.ts`. Maps HTTP method + scope → CRUD method. Pre-doc denial → **405** (matches `permissions.ts:136`). Post-doc denial → **403** (matches `permissions.ts:203`). Uses existing `checkPermissions` helper so `[]` arrays disable the action via 405.
-- [ ] **Task 1.6**: Implement `validateActionRequest(action, req)` in `api/src/actions.ts`. Runs Zod `safeParse` on body/query when schemas provided. On failure throws `APIError({status: 400, title: "Validation failed", fields})` — emitted as `meta.fields` on the wire by `errors.ts:117–121`. Parsed values returned through `ctx`, NOT by mutating `req.query` (Express 5 getter).
-- [ ] **Task 1.7**: Implement `wrapActionResponse(handlerResult, action, res)` — auto-wraps in `{data: ...}` with `status ?? 200`; skips wrap if `res.headersSent`. Default `null` for `undefined` return.
-- [ ] **Task 1.8**: Implement `assertNoActionCollisions(model, options)` — throws synchronously on:
-  - Action name doesn't match `/^[A-Za-z][A-Za-z0-9_-]+$/` (incl. empty names).
-  - Action name matches a Mongoose array-field path (would collide with `POST /:id/:field` at `api.ts:1159–1175`).
-- [ ] **Task 1.9**: Implement `createActionOpenApiMiddleware({action, scope, actionName, model})` in `api/src/actions.ts`. Per-request middleware that on first request through the route calls `options.openApi.path()` with an Operation Object built from inlined Zod-derived schemas (`OpenApiGeneratorV3.generateSchema()`). No-op when `options.openApi` is undefined. Sets `operationId: '${tag}_${actionName}'`. Tag defaults to `model.collection.collectionName`.
-- [ ] **Task 1.10**: Implement `registerActionRoutes(router, model, options)` — composes the middleware chain in order: `authenticateMiddleware(options.allowAnonymous)` → action OpenAPI middleware → pre-doc `runActionPermissions` → (instance only) `loadDocOr404` + post-doc `runActionPermissions` → `validateActionRequest` → wrapped `asyncHandler(action.handler)` → `wrapActionResponse`.
-- [ ] **Task 1.11**: Extend `ModelRouterOptions<T>` in `api/src/api.ts` with `instanceActions?` and `collectionActions?`. Inside `_buildModelRouter`, call `assertNoActionCollisions` and `registerActionRoutes` in the pre-CRUD `endpoints` slot (before the user's `options.endpoints` callback runs, so actions take precedence on path conflicts).
-- [ ] **Task 1.12**: Re-export `ActionContext`, `InstanceActionConfig`, `CollectionActionConfig`, `defineInstanceAction`, `defineCollectionAction` from `api/src/index.ts`.
-- [ ] **Task 1.13**: Write tests in `api/src/actions.test.ts` covering all Phase 1 acceptance criteria: registration validation (missing perms throws, empty perms registers but returns 405, action-name regex, array-field collision, empty name); routing (instance + collection happy path for GET + POST; `ctx.doc` set on instance; `req.obj` set on instance for parity with CRUD); permission flow (pre-doc → 405, post-doc → 403, 401 from passport, `IsAuthenticatedOrReadOnly` GET works with `allowAnonymous: true`, `IsOwner` doc-aware); validation (good body, bad body → 400 with `meta.fields`, query schema, Zod coercion through `ctx`, `req.query` not mutated, Zod `.strip` default observed); response shape (envelope, custom `status`, null/undefined return, `res.headersSent` escape hatch, custom list-style envelope via `res.json` + return); doc loading (404 missing, 404 metadata on soft-deleted); **type ergonomics**: a TS-level compile-only test that `defineInstanceAction<TDoc>({body: z.object({x: z.string()}), handler: async ({doc, body}) => {}})` infers `doc: TDoc` and `body: {x: string}` correctly.
-- [ ] **Task 1.14**: Add a regression test for **co-registration**: a modelRouter using BOTH `instanceActions: {foo: ...}` AND `endpoints: (router) => router.get('/:id/foo', ...)` — assert that the action wins (registered first in the pre-CRUD slot, before user `options.endpoints`). Same test for `collectionActions` colliding with a user `endpoints` route. Documents the precedence.
-
-## Phase 2: OpenAPI verification
-
-- [ ] **Task 2.1**: Tests against the generated `openapi.json` for actions registered via `TerrenoApp`: operation appears under `paths`; correct method + path; default tag = `model.collection.collectionName`; per-action `tag` override; inlined request body schema; inlined response schema under configured status; `id` path param present for instance actions; deterministic `operationId`.
-- [ ] **Task 2.2**: Same suite but for actions registered via the legacy `setupServer` path (`expressServer.ts:257`) — verifies the per-request OpenAPI emission fires on first hit and produces parity with the `TerrenoApp` path.
-
-## Phase 3: Migration + dogfooding
-
-- [ ] **Task 3.1**: Migrate `api/src/consentApp.ts` `/consent-forms` `endpoints` actions (scope: only those three actions; `/consents/*` routes at lines 195–457 are out of scope):
-  - `generate` → `collectionActions.generate`, conditional on `aiConfig` (built at runtime into the `collectionActions` map before passing to `modelRouter`).
-  - `translate` → `collectionActions.translate`, same conditional.
-  - `/:id/publish` → `instanceActions.publish`.
-- [ ] **Task 3.2**: Confirm all existing consent-form tests pass without modification.
-- [ ] **Task 3.3**: Add a `markComplete` instance action and a `bulkComplete` collection action to `example-backend/src/api/todos.ts` to demonstrate both scopes (and document the Zod `.strict()` recommendation in the example).
-- [ ] **Task 3.4**: Regenerate `example-frontend` SDK: `cd example-frontend && bun run sdk`.
-- [ ] **Task 3.5**: Smoke-test: run `bun run backend:dev` and `bun run frontend:web` together; exercise both new todo actions end-to-end (curl + the regenerated hooks).
-
-## Phase 4: Consumer compile-check + docs
-
-- [ ] **Task 4.1**: Run `bun run compile` (and `bun run test` where present) in each in-repo consumer of `@terreno/api`: `admin-backend`, `admin-frontend`, `ai`, `api-health`, `feature-flags`, `mcp-server`, `rtk`, `example-backend`, `example-frontend`. Fix any breakage from the new deps.
-- [ ] **Task 4.2**: Document in the explainer that `zod` is a `peerDependency` of `@terreno/api` — consumers must install Zod themselves (already true for `example-backend`). Note this in the changelog as a breaking install requirement.
-- [ ] **Task 4.3**: Write `docs/explanation/model-router-actions.md` covering: motivation; call-site example; semantics (permission method mapping, 405 vs 403 status codes, response envelope, validation error wire shape at `meta.fields`, collision detection, Zod `.strict()` recommendation, concurrency caveat for action handlers, `queryFilter` not applied to instance auto-load); migration notes from hand-rolled `endpoints` actions.
-- [ ] **Task 4.4**: Update `mcp-server/src/tools.ts` `generate_route` (and any related prompt in `prompts.ts`) to suggest `instanceActions`/`collectionActions`.
-- [ ] **Task 4.5**: Bump `@terreno/api` package version in `api/package.json`. Prepare a changelog entry mentioning: the new feature, the new deps (`zod`, `@asteasolutions/zod-to-openapi`), the behavior-preserving permission middleware refactor, and the new `operationId`-based hook names in regenerated SDKs.
-
-See `docs/implementationPlans/model-router-actions.md` for full details on each task.

package/src/docs/versioned/0.27.0/tasks/model-router-mcp.md

@@ -1,105 +0,0 @@
-# Tasks: modelRouter MCP Tools
-
-*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
-
----
-
-### Phase 1: Core MCP Infrastructure
-
-- [ ] **Task 1.1**: Define MCP types and interfaces
-  - Description: Create `MCPConfig` interface (with `methods` defaulting to `['list', 'read']`, `excludeFields` for hiding sensitive fields, `maxLimit` defaulting to 50), `MCPRegistryEntry`, and add `mcp?: MCPConfig` to `ModelRouterOptions`. Create the `api/src/mcp/` directory structure.
-  - Files: `api/src/mcp/types.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (add mcp to ModelRouterOptions)
-  - Depends on: none
-  - Acceptance: Types compile, existing tests still pass, `mcp` is an optional field on `ModelRouterOptions`
-
-- [ ] **Task 1.2**: Build MCP tool registry
-  - Description: Create a global registry that collects MCP tool entries as `modelRouter()` is called. When a modelRouter has `mcp` config, it pushes an entry to the registry. Export `getMCPRegistry()` internally and `getMCPTools()` publicly (returns `Record<string, CoreTool>`).
-  - Files: `api/src/mcp/registry.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (register in modelRouter function)
-  - Depends on: Task 1.1
-  - Acceptance: Calling `modelRouter(Todo, { ..., mcp: { methods: ['list', 'read'] } })` adds entries to the registry. `getMCPTools()` returns CoreTool objects.
-
-- [ ] **Task 1.3**: Generate Zod schemas from Mongoose models
-  - Description: Build a utility that converts a Mongoose model's schema into Zod schemas suitable for MCP tool `inputSchema`. Handle common field types (String, Number, Boolean, Date, ObjectId, Array, Mixed). Generate separate schemas for create (required fields), update (all optional + id required), read (id + optional populate), list (queryFields + pagination), and delete (id only). Respect `excludeFields` — omit listed fields from all generated schemas.
-  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
-  - Depends on: Task 1.1
-  - Acceptance: Given a Mongoose model, produces valid Zod schemas for each CRUD method. Tests cover all common field types. `excludeFields` removes specified fields from schemas.
-
-- [ ] **Task 1.4**: Generate MCP tool definitions from registry entries
-  - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel `ai` SDK `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
-  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
-  - Depends on: Task 1.2, Task 1.3
-  - Acceptance: Registry entry with `methods: ['list', 'read']` produces exactly `todos_list` and `todos_read` tools with correct schemas and descriptions.
-
-- [ ] **Task 1.5**: Implement MCP tool handlers (CRUD execution)
-  - Description: Build the execute functions for each CRUD tool. Each handler: (1) extracts user from auth context, (2) checks permissions via `checkPermissions()`, (3) for read/update/delete: loads document and checks object-level permissions, (4) applies queryFilter and population for list, (5) enforces `maxLimit` cap on list results (default 50), (6) runs pre/post hooks, (7) strips `excludeFields` from response data, (8) serializes via `mcpResponseHandler` or default. Reuse internal logic from REST handlers but decoupled from Express req/res.
-  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/handlers.test.ts`
-  - Depends on: Task 1.4
-  - Acceptance: Each CRUD handler works with correct permission checks, population, filtering. List enforces maxLimit. excludeFields are stripped from responses. Tests cover: successful CRUD, permission denied (403), not found (404), validation errors, owner filtering, population, maxLimit enforcement, excludeFields stripping.
-
-- [ ] **Task 1.6**: Auth-agnostic user extraction for MCP
-  - Description: Build middleware/utility that extracts user from MCP transport headers using whichever auth provider is configured (JWT via passport or Better Auth via `auth.api.getSession()`). Should mirror `authenticateMiddleware` behavior but work with raw headers instead of Express req.
-  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`
-  - Depends on: Task 1.1
-  - Acceptance: Given headers with a valid JWT, returns User. Given headers with a valid Better Auth session token, returns User. Given no/invalid headers with `allowAnonymous: false`, returns null. Works with both auth providers.
-
-- [ ] **Task 1.7**: Mount MCP server in TerrenoApp
-  - Description: In `TerrenoApp`'s startup flow, check if the MCP registry has any entries. If so, create an `McpServer` instance from `@modelcontextprotocol/sdk`, register all tools from the registry, set up `StreamableHTTPServerTransport`, and mount on `/mcp`. Wire up `ListToolsRequestSchema` and `CallToolRequestSchema` handlers.
-  - Files: `api/src/mcp/server.ts`, `api/src/expressServer.ts` (or TerrenoApp equivalent — integrate into startup)
-  - Depends on: Task 1.4, Task 1.5, Task 1.6
-  - Acceptance: Starting a TerrenoApp with MCP-configured models auto-mounts `/mcp`. MCP clients can list tools and call them. No MCP config = no `/mcp` endpoint.
-
-- [ ] **Task 1.8**: Integration tests
-  - Description: End-to-end tests that spin up a TerrenoApp with MCP-configured models and test the full flow: MCP client connects, lists tools, performs CRUD via tool calls, verifies permissions block unauthorized access, verifies population and query filtering work.
-  - Files: `api/src/mcp/integration.test.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Full CRUD lifecycle works over MCP. Permission denials return appropriate errors. Owner filtering restricts results. Population returns nested data.
-
-- [ ] **Task 1.9**: Export public API
-  - Description: Export `MCPConfig`, `getMCPTools()`, and any other public interfaces from `@terreno/api`'s main index. Update package exports.
-  - Files: `api/src/index.ts`, `api/src/mcp/index.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Consumers can `import { MCPConfig, getMCPTools } from "@terreno/api"`.
-
----
-
-### Phase 2: Frontend Integration
-
-- [ ] **Task 2.1**: `useTerrenoChat` hook
-  - Description: Create a hook wrapping `@ai-sdk/react`'s `useChat()` pre-configured for a Terreno MCP backend. Handles Bearer token injection from auth state (reads from Redux store — JWT token or Better Auth session). Accepts `baseURL` and optional `tools` override.
-  - Files: `rtk/src/useTerrenoChat.ts`, `rtk/src/useTerrenoChat.test.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Hook connects to MCP-enabled backend, streams responses with tool calls, injects auth token automatically.
-
-- [ ] **Task 2.2**: `useMCPTools` hook
-  - Description: Create a hook that discovers available MCP tools from the backend. Uses `@ai-sdk/mcp`'s `createMCPClient()` to connect and list tools. Caches result. Returns typed tool list.
-  - Files: `rtk/src/useMCPTools.ts`, `rtk/src/useMCPTools.test.ts`
-  - Depends on: Task 1.7
-  - Acceptance: Hook returns list of available tools with names, descriptions, and input schemas. Handles connection errors gracefully.
-
-- [ ] **Task 2.3**: Export frontend public API
-  - Description: Export `useTerrenoChat` and `useMCPTools` from `@terreno/rtk`. Add `@ai-sdk/react` and `@ai-sdk/mcp` as dependencies.
-  - Files: `rtk/src/index.ts`, `rtk/package.json`
-  - Depends on: Task 2.1, Task 2.2
-  - Acceptance: Consumers can `import { useTerrenoChat, useMCPTools } from "@terreno/rtk"`.
-
----
-
-### Phase 3: Examples & Polish
-
-- [ ] **Task 3.1**: Add MCP config to example backend models
-  - Description: Add `mcp` config to the existing Todo and Food models in `example-backend`. Todos: read-only (`list`, `read`). Food: full CRUD. Include `mcpResponseHandler` example on one model.
-  - Files: `example-backend/src/routes/todos.ts`, `example-backend/src/routes/food.ts`
-  - Depends on: Task 1.9
-  - Acceptance: Starting example-backend mounts `/mcp` with todo and food tools. MCP client can list and call them.
-
-- [ ] **Task 3.2**: Demo chat screen in example frontend
-  - Description: Add a simple chat screen to `example-frontend` that uses `useTerrenoChat()` to connect to the MCP-enabled backend. Show tool calls inline (e.g., "Searching todos..." with results). Navigation from home screen.
-  - Files: `example-frontend/app/chat.tsx`, `example-frontend/app/_layout.tsx` (add nav)
-  - Depends on: Task 2.3, Task 3.1
-  - Acceptance: User can chat with the AI, which calls MCP tools to query/modify data. Tool calls and results visible in the UI.
-
-- [ ] **Task 3.3**: Refine auto-generated tool descriptions
-  - Description: Improve description generation quality. Include field types, required vs optional, enum values, ref model names. Test with multiple model shapes to ensure descriptions are helpful for LLMs.
-  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
-  - Depends on: Task 1.4
-  - Acceptance: Descriptions include actionable detail. LLM can understand what each tool does and what inputs are expected without additional context.