@terreno/mcp 0.21.0

package/src/docs/versioned/0.20.0/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

package/src/docs/versioned/0.20.0/tasks/design-blend-skill.md

@@ -0,0 +1,147 @@
+# Task List: design-blend Skill
+
+Structured task breakdown for implementing the `design-blend` skill.
+
+## Phase 1: Planning Baseline
+
+- [x] **Task 1.1: Finalize IP contract**
+  - Description: Ensure the IP explicitly defines required outputs for models, modelRouters, model actions, UI composition, and conditional new components.
+  - Files: `docs/implementationPlans/design-blend-skill.md`
+  - Depends on: none
+  - Acceptance: IP contains concrete sections for REST-first gate, action gating, and component reuse-first policy.
+
+- [x] **Task 1.2: Publish executable task list**
+  - Description: Save this task list with dependency ordering and acceptance criteria.
+  - Files: `docs/tasks/design-blend-skill.md`
+  - Depends on: 1.1
+  - Acceptance: Task list exists and is consumable by an implementation subagent.
+
+## Phase 2: Skill Authoring
+
+- [x] **Task 2.1: Create `design-blend` skill**
+  - Description: Author `.rulesync/skills/design-blend/SKILL.md` with a workflow that starts from a Claude design file and produces a Terreno-focused implementation plan.
+  - Files: `.rulesync/skills/design-blend/SKILL.md`
+  - Depends on: 1.1, 1.2
+  - Acceptance: Skill includes purpose, required outputs, and deterministic execution steps.
+
+- [x] **Task 2.2: Enforce REST-first and action gate**
+  - Description: Add explicit decision logic that defaults to modelRouter CRUD and only permits model actions with documented justification.
+  - Files: `.rulesync/skills/design-blend/SKILL.md`
+  - Depends on: 2.1
+  - Acceptance: Skill includes "Action Decision Gate" and requires rejected action candidates.
+
+- [x] **Task 2.3: Enforce Terreno-first UI composition**
+  - Description: Require mapping design sections to existing `@terreno/ui` components before proposing new components.
+  - Files: `.rulesync/skills/design-blend/SKILL.md`
+  - Depends on: 2.1
+  - Acceptance: Skill includes component mapping table and conditional new-component contract.
+
+- [x] **Task 2.4: Add implementation execution behavior**
+  - Description: Require users to confirm plan/task list first, then execute via subagent, with "Plan vs Actual" comparison after each task.
+  - Files: `.rulesync/skills/design-blend/SKILL.md`
+  - Depends on: 2.1
+  - Acceptance: Skill has explicit per-task comparison output requirement.
+
+## Phase 3: Sync and Validation
+
+- [x] **Task 3.1: Run rulesync generation**
+  - Description: Sync `.rulesync/skills/design-blend/SKILL.md` to all configured targets.
+  - Files: generated by `rulesync` in target directories
+  - Depends on: 2.1, 2.2, 2.3, 2.4
+  - Acceptance: `bun run rules` succeeds and generated files include the new skill.
+
+- [x] **Task 3.2: Validate requirement coverage**
+  - Description: Verify the source and generated skill files contain required sections and no missing critical constraints.
+  - Files: `.rulesync/skills/design-blend/SKILL.md` plus synced outputs
+  - Depends on: 3.1
+  - Acceptance: Manual diff/read confirms all required sections are present in source and mirrors.
+
+## Plan vs Actual Log
+
+### Plan vs Actual: Task 1.1
+- Status: match
+- Planned:
+  - Finalize the IP contract with explicit required sections for models, APIs, actions, UI mapping, and conditional new components.
+- Actual:
+  - Expanded `docs/implementationPlans/design-blend-skill.md` with explicit contract sections and enforcement rules.
+- Evidence:
+  - IP file includes all required contract outputs and acceptance criteria.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 1.2
+- Status: match
+- Planned:
+  - Save a structured, dependency-ordered task list for implementation.
+- Actual:
+  - Created this file with phased tasks, dependencies, and acceptance criteria.
+- Evidence:
+  - `docs/tasks/design-blend-skill.md` contains phase-ordered tasks.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 2.1
+- Status: match
+- Planned:
+  - Create `design-blend` skill with purpose, required outputs, and deterministic workflow.
+- Actual:
+  - Authored `.rulesync/skills/design-blend/SKILL.md` with full structure and constraints.
+- Evidence:
+  - Source skill file includes required sections and workflow steps.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 2.2
+- Status: match
+- Planned:
+  - Enforce REST-first behavior and strict action gating.
+- Actual:
+  - Added mandatory REST-first contract and Action Decision Gate requirements.
+- Evidence:
+  - Skill requires both approved and rejected action candidate tracking.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 2.3
+- Status: match
+- Planned:
+  - Enforce Terreno-first component composition and conditional net-new component rules.
+- Actual:
+  - Added explicit Terreno Component Mapping output and New Component Contract gates.
+- Evidence:
+  - Skill requires proof of composition gap before allowing new components.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 2.4
+- Status: match
+- Planned:
+  - Require confirmation before implementation, then subagent execution with per-task comparisons.
+- Actual:
+  - Added explicit confirmation gate and mandatory per-task Plan vs Actual template.
+- Evidence:
+  - Skill includes confirmation phrase and reporting template section.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 3.1
+- Status: match
+- Planned:
+  - Run rulesync so source skill is mirrored to configured targets.
+- Actual:
+  - Ran `bun run rules`; all files reported up to date.
+- Evidence:
+  - Command output confirms rules/skills are synced.
+- Corrective action:
+  - none
+
+### Plan vs Actual: Task 3.2
+- Status: match
+- Planned:
+  - Validate that required sections are present in source and mirrored outputs.
+- Actual:
+  - Verified source and generated files exist and contain required contract sections.
+- Evidence:
+  - File verification completed across `.rulesync`, `.cursor`, `.claude`, `.windsurf`, `.github`, `.agents`.
+- Corrective action:
+  - none

package/src/docs/versioned/0.20.0/tasks/feature-flags-openfeature.md

@@ -0,0 +1,77 @@
+# Feature Flags → OpenFeature — Task List
+
+See `docs/implementationPlans/feature-flags-openfeature.md` for full details.
+
+## Phase 0: Catalog & deps
+
+- [x] **0.1** Add `@openfeature/server-sdk`, `@openfeature/web-sdk`, `@openfeature/react-sdk`, `@openfeature/core` to the root `package.json` `catalog` (pin minor; check latest at time of work). Verify with `bun install` from root.
+
+## Phase 1: Backend OpenFeature integration
+
+- [x] **1.1** Add `@openfeature/server-sdk` (catalog version) to `feature-flags/package.json` dependencies. Run `bun install`.
+- [x] **1.2** Add `defaultVariant` field to `FeatureFlag` schema (`feature-flags/src/featureFlagModel.ts`) with description and validation. **No getter** — use a `pre("save")` hook that populates `defaultVariant` when undefined (boolean → "off"; variant → first variant key). Validation: if set, boolean must be `"on"`/`"off"`; variant must be one of `variants[].key`. Add `defaultVariant` to `featureFlagAdminConfig.listFields`.
+- [x] **1.3** Update `FeatureFlagDocument` type in `feature-flags/src/types.ts` with optional `defaultVariant`. Add `FlagDefinition` and `FlagConfigurationResponse` interfaces.
+- [x] **1.4** Create `feature-flags/src/openFeatureProvider.ts` exporting `MongoFeatureFlagProvider` implementing OpenFeature's `Provider` interface. Use `findOneOrNone` (per repo rule — never `findOne`). Returns `FLAG_NOT_FOUND` / `TYPE_MISMATCH` `ResolutionDetails` shapes for missing or wrong-type flags. Delegates the targeting math to existing `evaluateFlag()`.
+- [x] **1.5** Update `FeatureFlagsApp.register()` (`feature-flags/src/featureFlagsApp.ts`): construct provider, call `OpenFeature.setProvider(domain, provider)` (default domain `"feature-flags"`), register new `/flagConfiguration` route, keep `/evaluate` with `Deprecation: true` + `Sunset: <90d>` headers + one-shot warn log.
+- [x] **1.6** Add `buildFlagDefinition(flag, targetingKey, user, segments)` helper. **Critical filter**: `/flagConfiguration` matches today's `evaluateAllFlags` filter (`archived: $ne true, enabled: true`) — disabled flags are omitted entirely. Every returned `FlagDefinition` has `disabled: false`.
+- [x] **1.7** Update `FeatureFlagsOptions` type (`feature-flags/src/types.ts`) to add `liveUpdates` and `openFeatureDomain` fields.
+- [x] **1.8** Update `feature-flags/src/index.ts` to export `MongoFeatureFlagProvider`, `FlagDefinition`, `FlagConfigurationResponse`.
+- [x] **1.9** Add `feature-flags/src/tests/openFeatureProvider.test.ts` covering: boolean and variant resolution; disabled flag returns default + reason "DISABLED"; `TYPE_MISMATCH` on wrong-type call; `FLAG_NOT_FOUND` on missing flag; rule-match path; segment-match path; deterministic-hash path; missing `targetingKey`; variant default fallback; `resolveNumberEvaluation` and `resolveObjectEvaluation` return `FLAG_NOT_FOUND`.
+- [x] **1.10** Extend `feature-flags/src/tests/featureFlagsApp.test.ts`: `/flagConfiguration` returns the right shape for both flag types; **explicitly verifies disabled flags are OMITTED**; verifies `defaultVariant` flows through; verifies `/evaluate` still works AND now includes `Deprecation` + `Sunset` headers. Add `featureFlagModel.test.ts` (or extend existing tests) with: legacy doc (no `defaultVariant`) can be saved and the hook populates a default; explicit `defaultVariant: "on"` on boolean passes; `defaultVariant: "bad"` on boolean is rejected.
+- [x] **1.11** Run `bun run --filter=@terreno/feature-flags compile test lint`. Fix issues.
+
+## Phase 2: Frontend OpenFeature integration
+
+- [x] **2.0 (blocking spike)** Verify `@openfeature/react-sdk` works under React Native. Write a tiny `bun test` using `@testing-library/react-native` that wraps a component in `<OpenFeatureProvider>` with a `TypedInMemoryProvider` and asserts `useBooleanFlagValue("k", false)` returns `true` after `PROVIDER_READY`. If it fails on RN, fall back to importing only from `@openfeature/web-sdk` and writing a thin React adapter inside `@terreno/rtk` that uses `useSyncExternalStore` against the OF client's event emitter. Do not proceed to 2.1 until this is green.
+- [x] **2.1** Add `@openfeature/web-sdk` + `@openfeature/react-sdk` as **peerDependencies** (NOT direct deps) in `rtk/package.json`. Add `@openfeature/core` as a direct dep for types. Run `bun install` from root.
+- [x] **2.2** Create `rtk/src/useTerrenoFeatureFlags.ts`. Critical behaviors:
+  - RTK Query endpoint cache key includes `userId` so user switching invalidates cache.
+  - On data success, `await OpenFeature.setProvider(domain, new TypedInMemoryProvider(data))`; subscribe to `PROVIDER_READY` via `client.addHandler`.
+  - `isLoading` stays `true` until BOTH RTK has data AND `PROVIDER_READY` has fired (gated by a ref-tracked boolean).
+  - On `userId` change: `OpenFeature.setContext(domain, {targetingKey: userId})` BEFORE the refetch resolves.
+  - Module-level ref counter for provider lifetime; do not clear provider on individual unmount; clear only when count returns to zero (last consumer leaves).
+  - StrictMode safety: ref tracks in-flight `setProvider` promise to dedupe double-effect.
+  - If `options.socket` is provided, subscribe to `socketEventName ?? "featureFlagsChanged"` → `refetch()`. Cleanup on unmount.
+  - Return `{flags, isLoading, error, refetch, client}`.
+- [x] **2.3** Rewrite `rtk/src/useFeatureFlags.ts` as a BC wrapper over `useTerrenoFeatureFlags`. Preserve overloaded signature (`string | UseFeatureFlagsOptions`). `getFlag` uses `client.getBooleanValue(key, false)`. `getVariant` returns `null` when `!flags[key]` (the flag is disabled/missing — disabled flags are filtered out of `/flagConfiguration`); otherwise returns `client.getStringValue(key, "") || null`. Build `flatFlags: Record<string, boolean | string | null>` from the raw `FlagConfiguration` map by projecting each `FlagDefinition`: boolean → `variants[defaultVariant]`, variant → `defaultVariant`. Add explicit type tests.
+- [x] **2.4** Update `rtk/src/index.ts` to export `useTerrenoFeatureFlags` and its types. Do **not** re-export OpenFeature hooks (consumers add `@openfeature/react-sdk` directly).
+- [x] **2.5** Update `rtk/src/useFeatureFlags.test.ts` to match the new wire shape. Cover: legacy options shape (string), modern options shape (object), `skip`, `getFlag`/`getVariant` for boolean and variant flags, `null` on disabled/missing, timing logs preserved, **snapshot test** locking the `flatFlags` projection so `profile.tsx`'s render output is byte-identical to before.
+- [x] **2.6** Add `rtk/src/useTerrenoFeatureFlags.test.ts` covering: provider is set on success; `isLoading` stays `true` until `PROVIDER_READY`; domain isolation (default provider not affected); refetch path; no-op when `skip: true`; `userId` change triggers context + refetch + provider replacement; StrictMode double-mount does not double-set provider; ref count prevents premature provider clearing; socket event triggers refetch.
+- [x] **2.7** Run `bun run --filter=@terreno/rtk compile test lint`. Fix issues.
+
+## Phase 3: Live updates (opt-in)
+
+- [x] **3.1** In `FeatureFlagsApp.register()`, when `options.liveUpdates?.socketIoServer` is provided (accept either a value or a `() => Server | null` getter — example-backend's `io` is lazily initialized), start `FeatureFlag.watch([], {fullDocument: "updateLookup"})`. On each change, emit `featureFlagsChanged` (configurable event name) plus call `provider.emitConfigurationChanged()`. Log on stream `error`; one auto-reconnect attempt, then disable + warn.
+- [x] **3.2** Add `feature-flags/src/tests/featureFlagsApp.liveUpdates.test.ts`. Test approach: **mock `FeatureFlag.watch`** to return a fake `EventEmitter` with the change-stream interface (`on`, `close`). The tests do NOT spin up a replica-set Mongo. Cover: emission on insert/update/delete (via emitting fake change events), custom event name, error handler logs a warn, double-error disables the stream.
+- [x] **3.3** In `useTerrenoFeatureFlags`, when `options.socket` is provided, subscribe to `options.socketEventName ?? "featureFlagsChanged"` and call `refetch()` on each event. Cleanup on unmount. Acknowledge that the emit is global broadcast (all connected clients) — no PII in the payload.
+- [x] **3.4** Add a test in `useTerrenoFeatureFlags.test.ts` proving: when a fake `EventEmitter` socket emits the event, the hook refetches and OF consumers re-render.
+- [x] **3.5** Document the Mongoose replica-set requirement (production must use a replica set, including single-node replica set) and Socket.io wiring in `docs/how-to/add-feature-flags.md` (new "Live updates" section). Also document the broadcast scope (flag-key payload visible to every authenticated socket) — acceptable since flag keys ship to every authed client via `/flagConfiguration` anyway.
+
+## Phase 4: Example apps + docs + SDK regen
+
+- [x] **4.1** Update `example-backend` `FeatureFlagsApp` construction to pass `liveUpdates: {socketIoServer: () => io}` — use a getter, since `example-backend/src/websockets.ts:24` initializes `io` lazily during `connectToWebsockets`.
+- [x] **4.2** Update `example-backend/src/scripts/seed-feature-flags.ts`: add `defaultVariant` to each `SEED_FLAGS` entry (`"off"` for boolean flags; for the `profile-layout` variant flag, `"compact"`). **Bump the seed**: either add a `seedVersion` field to FeatureFlag (skip if too invasive) OR add an idempotent "patch missing defaultVariant" upsert at the top of the script that updates existing docs in dev DBs to populate the new field. Document the dev-db backfill in the migration note.
+- [x] **4.3** Update `example-frontend/app/_layout.tsx` to wrap children in `<OpenFeatureProvider domain="feature-flags">` and call `useTerrenoFeatureFlags(terrenoApi, {socket, userId})` once user is authenticated.
+- [x] **4.4** Update `example-frontend/app/(tabs)/profile.tsx`: add a small section that uses `useBooleanFlagDetails("dark-mode-toggle", false)` and renders `reason` alongside value — verifies OF metadata is plumbed through and proves the `reason` field shape downstream.
+- [x] **4.5** Add `example-frontend/types/openfeature.d.ts` demonstrating the type-safe flag keys augmentation. Reference it from the docs.
+- [ ] **4.6** Regenerate frontend SDK: `cd example-frontend && bun run sdk`. Verify the new endpoint is in `openApiSdk.ts` and document that consumers should NOT call the generated hook directly; use `useTerrenoFeatureFlags`/`useFeatureFlags` instead.
+- [x] **4.7** Update `docs/reference/feature-flags.md`: new endpoint shape, `MongoFeatureFlagProvider` export, `defaultVariant` field semantics, recommended OF hooks for new code, BC notes, **number/object flag types not supported** (always returns default), **type-safe flag keys drift warning**, dev-db backfill note for existing seeded flags.
+- [x] **4.8** Update `docs/how-to/add-feature-flags.md`: recommend OF hooks for new code; show `useFeatureFlags` only in a "BC / migration" section.
+- [x] **4.9** Add a short note at the top of `docs/implementationPlans/feature-flags.md` linking to this new IP.
+- [x] **4.10** Add `example-frontend/e2e/feature-flags.spec.ts` Playwright test:
+  - Login as admin
+  - PATCH a flag via `/feature-flags/flags/:id` (e.g., toggle `enabled` on `todo-summary-card`)
+  - Within ~5s, assert the example-frontend's todos screen shows/hides the summary card accordingly **without** a page reload
+  - Verifies the full live-update loop (change stream → socket emit → hook refetch → OF re-render)
+  - Skip the test if the test environment does not have a Mongo replica set (use `test.skip` with a clear message) so CI doesn't fail when devs run without one.
+- [ ] **4.11** Run full workspace check: `bun run lint && bun run compile && bun run test`. Run example stack manually (`bun run backend:dev` + `bun run frontend:web`) and verify the profile screen shows flags identical to before.
+
+## Definition of Done
+
+- All workspace tests pass.
+- `example-frontend` runs end-to-end with seeded flags, showing identical values to before the migration.
+- Admin edits to a flag (via the admin panel) propagate to an open example-frontend session within ~1 second without a manual refresh.
+- A consumer using only `useFeatureFlags(api)` requires zero code changes.
+- A consumer can now also use `useBooleanFlagValue("key", false)` directly from `@openfeature/react-sdk`.
+- Type-safe flag keys augmentation is documented and demonstrated in `example-frontend`.
+- The legacy `/evaluate` endpoint still works, returns the old shape, and includes a `Deprecation` header.

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

@@ -0,0 +1,23 @@
+# 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.20.0/tasks/model-router-actions.md

@@ -0,0 +1,46 @@
+# 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.20.0/tasks/model-router-mcp.md

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