@terreno/mcp 0.21.0

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

@@ -0,0 +1,417 @@
+# Implementation Plan: Consent Forms System
+
+*When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
+
+## **Models**
+
+### ConsentForm
+
+Admin-managed consent form definitions with i18n support and configurable behavior.
+
+```typescript
+const consentFormSchema = new mongoose.Schema({
+  title: {required: true, trim: true, type: String},
+  slug: {required: true, trim: true, type: String, index: true},
+  version: {required: true, type: Number, default: 1},
+  order: {required: true, type: Number, default: 0},
+  type: {
+    required: true,
+    type: String,
+    enum: ["agreement", "privacy", "hipaa", "research", "terms", "custom"],
+  },
+
+  // i18n content: { "en": "# Title\n...", "es": "# Titulo\n..." }
+  content: {type: Map, of: String, required: true},
+  defaultLocale: {type: String, default: "en"},
+  active: {type: Boolean, default: false},
+
+  // Form behavior
+  captureSignature: {type: Boolean, default: false},
+  requireScrollToBottom: {type: Boolean, default: false},
+  checkboxes: [{
+    label: {type: String, required: true},
+    required: {type: Boolean, default: false},
+    confirmationPrompt: {type: String}, // If set, shows "are you sure?" modal with this text
+  }],
+
+  // Button config
+  agreeButtonText: {type: String, default: "I Agree"},
+
+  // Decline behavior
+  allowDecline: {type: Boolean, default: false},
+  declineButtonText: {type: String, default: "Decline"},
+  required: {type: Boolean, default: true}, // If true + declined, blocks app access
+}, {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}});
+
+consentFormSchema.index({slug: 1, version: 1}, {unique: true});
+addDefaultPlugins(consentFormSchema); // created, updated, isDeleted
+```
+
+### ConsentResponse
+
+User completions with optional audit trail.
+
+```typescript
+const consentResponseSchema = new mongoose.Schema({
+  userId: {type: mongoose.Schema.Types.ObjectId, ref: "User", required: true, index: true},
+  consentFormId: {type: mongoose.Schema.Types.ObjectId, ref: "ConsentForm", required: true},
+  agreed: {type: Boolean, required: true},
+  agreedAt: {type: Date, required: true},
+  checkboxValues: {type: Map, of: Boolean},
+  locale: {type: String, required: true},
+
+  // Signature (optional, per form config)
+  signature: {type: String},       // base64 image
+  signedAt: {type: Date},
+
+  // Audit trail fields (optional, when auditTrail enabled on ConsentApp)
+  ipAddress: {type: String},
+  userAgent: {type: String},
+  contentSnapshot: {type: String}, // markdown content at time of signing
+  formVersionSnapshot: {type: Number},
+}, {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}});
+
+consentResponseSchema.index({userId: 1, consentFormId: 1});
+addDefaultPlugins(consentResponseSchema);
+```
+
+## **APIs**
+
+### ConsentApp Plugin Routes
+
+| Method | Path | Description | Permissions | Notes |
+|--------|------|-------------|-------------|-------|
+| GET | `/consents/pending` | Get pending consent forms for current user | IsAuthenticated | Runs `resolveConsentForms` callback, checks versions against existing responses, returns ordered forms |
+| POST | `/consents/respond` | Submit a consent response | IsAuthenticated | Body: `{consentFormId, agreed, checkboxValues, signature, locale}`. Adds audit trail fields if enabled |
+| GET | `/consents/audit/:userId` | Get full signing history for a user | IsAdmin | Returns responses with content snapshots. Only when `auditTrail: true` |
+
+### Standard CRUD via modelRouter (admin)
+
+| Method | Path | Description | Permissions |
+|--------|------|-------------|-------------|
+| GET | `/consent-forms` | List all consent forms | IsAdmin |
+| POST | `/consent-forms` | Create consent form | IsAdmin |
+| GET | `/consent-forms/:id` | Get single consent form | IsAdmin |
+| PATCH | `/consent-forms/:id` | Update consent form | IsAdmin |
+| DELETE | `/consent-forms/:id` | Soft-delete consent form | IsAdmin |
+| POST | `/consent-forms/:id/publish` | Publish new version (clones with incremented version, sets active) | IsAdmin |
+| GET | `/consent-responses` | List all responses | IsAdmin |
+| GET | `/consent-responses/:id` | Get single response | IsAdmin |
+
+### AI Generation Endpoints
+
+| Method | Path | Description | Permissions | Notes |
+|--------|------|-------------|-------------|-------|
+| POST | `/consent-forms/generate` | Generate consent form markdown from description | IsAdmin | Takes `{type, description, locale}`, returns markdown via Claude API |
+| POST | `/consent-forms/translate` | Translate content to another locale | IsAdmin | Takes `{content, fromLocale, toLocale}`, returns translated markdown |
+
+### ConsentApp Configuration
+
+```typescript
+new ConsentApp({
+  auditTrail: true,                          // Enable audit trail fields
+  aiConfig: {apiKey: process.env.CLAUDE_KEY}, // Optional, enables AI endpoints
+  resolveConsentForms: (user, forms) => {     // Optional, default: return all
+    return forms.filter(f => matchesUserRole(user, f));
+  },
+  supportedLocales: ["en", "es", "fr"],       // Available locales in admin
+})
+```
+
+## **Notifications**
+
+No notifications required. Consent forms are checked on every app launch via the `ConsentNavigator` — users are blocked from the app until they complete pending consents.
+
+## **UI**
+
+### New Components in `@terreno/ui`
+
+| Component | Description |
+|-----------|-------------|
+| `ConsentNavigator` | Inline wrapper. Fetches pending consents on mount. If pending, renders consent flow instead of `children`. |
+| `ConsentFormScreen` | Renders a single form: title, scrollable MarkdownView, checkboxes with confirmation modals, signature field, agree/decline buttons. |
+| `MarkdownEditor` | Split-pane editor: textarea on left, MarkdownView preview on right. |
+
+### New Components in `@terreno/admin-frontend`
+
+| Component | Description |
+|-----------|-------------|
+| `ConsentFormEditor` | Custom admin form with locale tabs for content (MarkdownEditor), checkbox list builder, button config, publish version button, AI generate/translate buttons. |
+| `ConsentFormList` | List view showing title, type, version, active status, order. |
+| `ConsentResponseViewer` | Read-only view of a response with signature display and audit trail. |
+
+### Client App Navigation Flow
+
+```
+App Launch
+  -> ConsentNavigator checks GET /consents/pending
+  -> If no pending forms: render children (normal app)
+  -> If pending forms:
+    -> Show ConsentFormScreen for forms[0]
+      -> User scrolls to bottom (if required)
+      -> User checks checkboxes (with confirmation modals as configured)
+      -> User signs (if signature required)
+      -> User taps "I Agree" -> POST /consents/respond
+      -> Advance to forms[1], etc.
+    -> All forms completed -> render children
+```
+
+### ConsentFormScreen States
+
+- **Loading** — fetching forms, show Spinner
+- **Displaying form** — markdown content scrollable, agree button disabled until requirements met (scroll, required checkboxes, signature)
+- **Submitting** — agree button shows loading state
+- **Error** — toast notification on submit failure, retry
+
+### Admin Flow
+
+```
+Admin Model List -> Consent Forms table
+  -> Create: ConsentFormEditor with MarkdownEditor, locale tabs, checkbox builder
+  -> Edit: Same editor, with "Publish New Version" button in header
+  -> AI: "Generate" button calls /consent-forms/generate, populates editor
+  -> Translate: Per-locale "Translate from [default]" button
+```
+
+### Client Integration (Minimal)
+
+```typescript
+import {ConsentNavigator} from "@terreno/ui";
+
+const App = () => (
+  <ConsentNavigator api={terrenoApi}>
+    <TabNavigator />
+  </ConsentNavigator>
+);
+```
+
+## Phases
+
+| Phase | Contents | Deliverable |
+|-------|----------|-------------|
+| **Phase 1: Models + API** | ConsentForm and ConsentResponse models, ConsentApp plugin with all routes (CRUD, pending, respond, publish, audit), resolver callback, tests | Backend fully functional |
+| **Phase 2: Admin UI** | ConsentFormEditor, ConsentFormList, ConsentResponseViewer, MarkdownEditor in ui, locale tabs, checkbox builder, publish version button | Admins can manage consent forms |
+| **Phase 3: ConsentNavigator** | ConsentNavigator and ConsentFormScreen in ui, scroll tracking, signature capture, checkbox confirmation modals, useConsentForms hook | Client apps can use consent flow |
+| **Phase 4: AI Generation** | Backend generate/translate endpoints, admin generate/translate buttons, aiConfig option | AI-powered content creation |
+| **Phase 5: Example App + Docs** | Integrate into example-backend/frontend, update SDK | Working end-to-end example |
+
+Phases 2 and 3 can run in parallel after Phase 1 lands.
+
+## Feature Flags & Migrations
+
+**Feature flags:** None. The system is opt-in — apps register `ConsentApp` and wrap UI with `ConsentNavigator`.
+
+**Migrations:** None. New models with new collections. No changes to existing schemas.
+
+**Rollout:** Ship each phase as it lands.
+
+## Activity Log & User Updates
+
+No activity logging for v1. The ConsentResponse model serves as the audit trail. The admin audit endpoint (`GET /consents/audit/:userId`) provides signing history.
+
+## **Not included/Future work**
+
+- Conditional logic within forms (branching based on answers)
+- PDF export of signed consents with audit trail
+- Consent form analytics/dashboards (completion rates, decline rates)
+- Offline consent completion
+- Consent expiration / annual renewal
+- Bulk-invalidate responses when a form is updated
+- Email notifications for pending consents
+- Pre-built consent form templates library
+
+---
+
+## Task List (Bot Consumption)
+
+*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, locale, active, captureSignature, requireScrollToBottom, checkboxes, buttons, decline config). Add indexes, plugins, and TypeScript types.
+  - 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, locale, signature, signedAt, audit trail fields). Add indexes, plugins, and TypeScript types.
+  - 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, supportedLocales). Register method mounts routes.
+  - 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, query fields, 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 (read-only — no create/update/delete via admin).
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Admin can list and read responses
+
+- [ ] **Task 1.6**: GET /consents/pending endpoint
+  - Description: Custom route that fetches active consent forms, runs resolveConsentForms callback, checks user's existing responses against form versions, returns ordered pending forms.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Returns only forms user hasn't completed at current version, respects resolver callback, ordered by `order` field
+
+- [ ] **Task 1.7**: POST /consents/respond endpoint
+  - Description: Custom route that creates a ConsentResponse. Validates consentFormId exists and is active. If auditTrail enabled, captures IP, user agent, content snapshot, form version.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Creates response, validates required checkboxes, stores audit data when enabled
+
+- [ ] **Task 1.8**: POST /consent-forms/:id/publish endpoint
+  - Description: Custom route that clones a consent form with incremented version number and sets it as active. Deactivates previous version of same slug.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.4
+  - Acceptance: New version created, old version deactivated, version number incremented
+
+- [ ] **Task 1.9**: GET /consents/audit/:userId endpoint
+  - Description: Admin-only endpoint returning full consent response history for a user with populated form data. Only available when auditTrail is enabled.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.7
+  - Acceptance: Returns responses with content snapshots, 404 when auditTrail disabled
+
+- [ ] **Task 1.10**: Export ConsentApp from @terreno/api
+  - Description: Export ConsentApp, models, and types from api package index. Update package.json exports if needed.
+  - Files: `api/src/index.ts`
+  - Depends on: 1.3
+  - Acceptance: `import {ConsentApp} from "@terreno/api"` works
+
+- [ ] **Task 1.11**: ConsentApp unit tests
+  - Description: Test all endpoints: CRUD, pending logic (version checking, resolver callback), respond (validation, audit trail), publish (version increment), audit endpoint.
+  - 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
+
+### 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, locale label. Responsive — stacks vertically on mobile.
+  - 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, exported from ui
+
+- [ ] **Task 2.2**: ConsentFormEditor component in admin-frontend
+  - Description: Custom form for creating/editing consent forms. Includes: basic fields (title, slug, type, order), locale tabs with MarkdownEditor per locale, checkbox list builder (add/remove/reorder with label, required, confirmationPrompt), button config (agreeText, allowDecline, declineButtonText, required), captureSignature and requireScrollToBottom toggles. "Publish New Version" button in edit mode.
+  - Files: `admin-frontend/src/ConsentFormEditor.tsx`
+  - Depends on: 2.1
+  - Acceptance: Can create and edit consent forms with all fields, locale tabs work
+
+- [ ] **Task 2.3**: ConsentFormList component in admin-frontend
+  - Description: Table view for consent forms showing title, type, version, active status, order. Links to editor. Create button.
+  - Files: `admin-frontend/src/ConsentFormList.tsx`
+  - Depends on: none
+  - Acceptance: Lists forms with correct columns, navigation to editor works
+
+- [ ] **Task 2.4**: ConsentResponseViewer component in admin-frontend
+  - Description: Read-only detail view for a consent response. Shows form title, user, agreed status, timestamp, checkbox values, rendered signature image, audit trail fields if present.
+  - Files: `admin-frontend/src/ConsentResponseViewer.tsx`
+  - Depends on: none
+  - Acceptance: Displays all response fields including signature and audit data
+
+- [ ] **Task 2.5**: Export admin consent components
+  - Description: Export ConsentFormEditor, ConsentFormList, ConsentResponseViewer from admin-frontend index.
+  - Files: `admin-frontend/src/index.tsx`
+  - Depends on: 2.2, 2.3, 2.4
+  - Acceptance: Components importable from `@terreno/admin-frontend`
+
+### Phase 3: ConsentNavigator
+
+- [ ] **Task 3.1**: useConsentForms hook
+  - Description: Hook that injects a `getPendingConsents` query endpoint into the provided RTK API, fetches on mount, returns `{forms, isLoading, error, refetch}`. Handles locale detection from device.
+  - Files: `ui/src/useConsentForms.ts`
+  - Depends on: Phase 1
+  - Acceptance: Hook fetches pending forms, handles loading/error states, detects device locale
+
+- [ ] **Task 3.2**: useSubmitConsent hook
+  - Description: Hook that injects a `submitConsentResponse` mutation endpoint. Returns `{submit, isSubmitting, error}`. 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
+
+- [ ] **Task 3.3**: ConsentFormScreen component
+  - Description: Renders a single consent form. Scrollable MarkdownView with scroll-to-bottom tracking. Checkbox list with confirmation modal support. SignatureField when captureSignature is true. Agree button (disabled until requirements met). Optional decline button. Locale-aware content selection.
+  - Files: `ui/src/ConsentFormScreen.tsx`
+  - Depends on: 3.2
+  - Acceptance: All form types render correctly, requirements gate the agree button, confirmation modals work
+
+- [ ] **Task 3.4**: ConsentNavigator component
+  - Description: Inline wrapper component. Takes `api` and `children` props. On mount, fetches pending forms via useConsentForms. If pending, renders ConsentFormScreen sequentially. On each completion, advances to next form. When all done, renders children. Manages current form index state internally.
+  - 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
+
+- [ ] **Task 3.5**: Export consent components from ui
+  - Description: Export ConsentNavigator, ConsentFormScreen, useConsentForms, useSubmitConsent from ui index.
+  - Files: `ui/src/index.tsx`
+  - Depends on: 3.4
+  - Acceptance: All components importable from `@terreno/ui`
+
+- [ ] **Task 3.6**: ConsentNavigator tests
+  - Description: Test ConsentNavigator rendering: no pending forms shows children, pending forms shows consent flow, completing all forms shows children, decline on optional form skips it, decline on required form blocks.
+  - 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 calls Claude API to generate consent form markdown. Accepts `{type, description, locale}`. Returns `{content: string}`. Only available when aiConfig is provided.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Generates reasonable consent markdown, returns 404 when aiConfig not set
+
+- [ ] **Task 4.2**: POST /consent-forms/translate endpoint
+  - Description: Backend endpoint that calls Claude API to translate consent markdown. Accepts `{content, fromLocale, toLocale}`. Returns `{content: string}`.
+  - Files: `api/src/consentApp.ts`
+  - Depends on: 1.3
+  - Acceptance: Translates content preserving markdown formatting
+
+- [ ] **Task 4.3**: AI generate button in ConsentFormEditor
+  - Description: Add "Generate" button to editor that opens a modal with type and description inputs, calls generate endpoint, populates the MarkdownEditor for current locale.
+  - Files: `admin-frontend/src/ConsentFormEditor.tsx`
+  - Depends on: 2.2, 4.1
+  - Acceptance: Generate button visible, modal works, generated content populates editor
+
+- [ ] **Task 4.4**: Translate button in ConsentFormEditor
+  - Description: Add per-locale "Translate from [default locale]" button that calls translate endpoint and populates the MarkdownEditor for 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
+
+### Phase 5: Example App + Docs
+
+- [ ] **Task 5.1**: Integrate ConsentApp into example-backend
+  - Description: Register ConsentApp plugin in example-backend server. Add configuration with resolveConsentForms callback and supportedLocales.
+  - Files: `example-backend/src/server.ts`
+  - Depends on: Phase 1
+  - Acceptance: Backend serves consent endpoints, shows in OpenAPI spec
+
+- [ ] **Task 5.2**: Integrate ConsentNavigator into example-frontend
+  - Description: Wrap main app content with ConsentNavigator. Update SDK to include consent endpoints.
+  - Files: `example-frontend/app/_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
+
+- [ ] **Task 5.3**: Add consent admin screens to example-frontend
+  - Description: Add admin routes for consent form management and response viewing using admin-frontend components.
+  - Files: `example-frontend/app/admin/consent-forms/` (index, create, [id]), `example-frontend/app/admin/consent-responses/` (index, [id])
+  - Depends on: Phase 2, 5.1
+  - Acceptance: Admin can create/edit/publish consent forms and view responses
+
+- [ ] **Task 5.4**: Seed example consent forms
+  - Description: Add a seed script or initial data that creates sample consent forms (terms of service, privacy policy) for the example app.
+  - Files: `example-backend/src/seed.ts` or similar
+  - Depends on: 5.1
+  - Acceptance: Example app has working consent forms out of the box

package/dist/docs/versioned/next/implementationPlans/design-blend-skill.md

@@ -0,0 +1,188 @@
+# Implementation Plan: design-blend Skill
+
+## Goal
+
+Create a new `design-blend` skill that converts a Claude design file into a Terreno implementation blueprint and execution steps, with these hard constraints:
+
+1. REST-first APIs via `modelRouter` CRUD by default.
+2. Model actions only when REST is a poor fit (command, aggregation, or performance path).
+3. Maximum reuse of existing `@terreno/ui` components.
+4. New UI components only when the design cannot be expressed with existing Terreno primitives/components.
+5. Two-stage flow in the skill: (a) plan with task list, then (b) implementation using a subagent with per-task plan comparison.
+
+## Scope
+
+- Add canonical skill definition at `.rulesync/skills/design-blend/SKILL.md`.
+- Preserve planning artifacts:
+  - `docs/implementationPlans/design-blend-skill.md` (this file)
+  - `docs/tasks/design-blend-skill.md` (bot task list)
+- Sync generated mirrors for all configured `rulesync` targets.
+
+## Required Outputs Enforced by the Skill (Contract)
+
+The `design-blend` skill must require the following explicit outputs whenever it is used.
+
+### 1) Models Output (Required)
+
+For every entity inferred from the design, output a model spec with:
+
+- `modelName`
+- `fields` (name, type, required, default, description)
+- `relations` (`ref`, cardinality)
+- `indexes`
+- `plugins`
+- `ownership/multitenancy` notes (`ownerId`, tenant key, soft delete)
+
+Required format in skill output:
+
+1. A "Model Inventory" table.
+2. A per-model schema checklist.
+3. A "No model needed" rationale when a design section is purely presentational.
+
+### 2) modelRouter REST Output (Required)
+
+For each model, output a modelRouter plan with:
+
+- Route base path (for example `/orders`)
+- CRUD endpoints:
+  - `POST /resource`
+  - `GET /resource`
+  - `GET /resource/:id`
+  - `PATCH /resource/:id`
+  - `DELETE /resource/:id` (or explicit disable rationale)
+- `permissions` per method
+- `queryFields`
+- `queryFilter` (ownership/tenant filter when relevant)
+- `sort`
+- `populatePaths` where needed
+
+Required format in skill output:
+
+1. "REST Endpoint Matrix" (method/path/permission/purpose).
+2. "modelRouter Options Block" for each model.
+3. Explicit statement if any CRUD endpoint is disabled and why.
+
+### 3) Model Actions Output (Conditional, Strictly Gated)
+
+Actions are allowed only if one of these is true:
+
+1. Non-resource command semantics (`publish`, `approve`, `submit`, `duplicate`).
+2. Aggregation/read-model endpoint where CRUD cannot express required shape efficiently.
+3. Performance-motivated path (batch operation or optimized read route) with measurable benefit.
+
+For each action, require:
+
+- `actionName`
+- `method` + `path`
+- `whyRestIsInsufficient` (mandatory)
+- `requestSchema` + `responseSchema`
+- `permissions`
+- `performanceNote` (mandatory if performance-motivated)
+
+Required format in skill output:
+
+1. "Action Decision Gate" checklist.
+2. "Approved Actions" table.
+3. "Rejected Candidate Actions" table (to prove REST-first evaluation happened).
+
+### 4) UI Composition Output (Required)
+
+For each screen/state in the design:
+
+- Map to existing `@terreno/ui` components first (for example `Page`, `Box`, `Card`, `DataTable`, `TextField`, `SelectField`, `Button`, `Modal`, `Spinner`, `Toast`).
+- Include loading, empty, error, and success states.
+- Note navigation and interaction flow.
+
+Required format in skill output:
+
+1. "Terreno Component Mapping" table by screen section.
+2. "State Coverage Matrix" (loading/empty/error/success).
+3. "Accessibility/Testability Notes" (testIDs and semantics).
+
+### 5) New UI Components Output (Conditional)
+
+No mandatory net-new UI components are required by this IP itself. New components are conditional and must only be created when a clear gap exists.
+
+If a gap exists, the skill must require:
+
+- `componentName`
+- `whyExistingTerrenoComponentsDoNotFit`
+- `propsApi`
+- `states`
+- `reusabilityTargets` (at least one additional use-case)
+
+Required format in skill output:
+
+1. "New Component Candidates" table.
+2. "Approved New Components" section with API contract.
+3. "Rejected Candidate Components" section with fallback composition.
+
+## Skill Behavior Requirements
+
+The skill must guide users through this order:
+
+1. Parse design file.
+2. Produce implementation plan covering models/APIs/actions/UI/new components.
+3. Produce structured task list.
+4. Wait for confirmation of plan/task list.
+5. Execute tasks using a subagent.
+6. After each task, publish "Plan vs Actual" comparison with:
+   - status (`match`, `partial`, `deviation`)
+   - notes
+   - corrective action (if needed)
+
+## Phases
+
+### Phase 1: Planning Artifacts
+
+- Finalize this IP with explicit contract sections.
+- Produce `docs/tasks/design-blend-skill.md`.
+
+### Phase 2: Skill Authoring
+
+- Implement `.rulesync/skills/design-blend/SKILL.md` with:
+  - REST-first gate
+  - required output templates
+  - subagent execution step
+  - per-task plan comparison requirement
+
+### Phase 3: Rulesync + Validation
+
+- Run `bun run rules`.
+- Verify synced files are generated for all targets.
+- Validate markdown quality and requirement coverage.
+
+## Acceptance Criteria
+
+1. `design-blend` skill exists in `.rulesync/skills/design-blend/SKILL.md`.
+2. Skill text explicitly enforces:
+   - models output format
+   - modelRouter CRUD matrix
+   - action gating and schemas
+   - Terreno-first UI mapping
+   - conditional new component contract
+3. Skill requires subagent execution after confirmed plan/task list.
+4. Skill requires per-task "Plan vs Actual" comparison.
+5. `bun run rules` succeeds and mirrors are generated.
+
+## Deliverables
+
+1. `docs/implementationPlans/design-blend-skill.md`
+2. `docs/tasks/design-blend-skill.md`
+3. `.rulesync/skills/design-blend/SKILL.md`
+4. Synced generated skill files from `rulesync`
+
+## Risks
+
+- Skill may drift into generic advice and skip enforceable output structure.
+- Users may bypass REST-first design and overuse actions.
+- New component proposals may be accepted too early without proving Terreno composition limits.
+- Mirror files may drift if rulesync is skipped.
+
+## Mitigations
+
+- Add strict required-output templates and checklists in the skill.
+- Require explicit "why REST is insufficient" text per action.
+- Require rejected-component table before approving any net-new component.
+- Run `bun run rules` in the same implementation flow and verify generated artifacts.
+