@terreno/mcp 57.16.2 → 57.18.0

package/dist/docs/versioned/57.17.0/tasks/comms-adapter-sendgrid.md

@@ -0,0 +1,43 @@
+# Tasks: Comms adapter — transactional email (SendGrid)
+
+IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
+
+## Phase 1 — Send path
+
+- [x] **Task 1.1**: `SendGridMailProvider` with config + sandbox mode
+  - Description: constructor/env config, from-address fallback chain, sandbox default under test
+  - Files: `comms/src/adapters/sendgrid.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests for text/html/template sends
+- [x] **Task 1.2**: Error classification
+  - Description: HTTP status → `errorCode`/`errorClass` per the IP table (400 permanent, 401/403 config, 429/5xx transient); full response body into `CommsMessage.metadata`; never throws
+  - Files: `comms/src/adapters/sendgrid.ts`
+  - Depends on: 1.1
+  - Acceptance: unverified-sender (config), bad-address (permanent), and 429 (transient) fixtures assert `errorClass`; permanent skips the inline retry
+- [x] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Description: capture `x-message-id`; `metadata.consoleUrl` Email Activity deep link; `onError` fires with the classified `SendResult`
+  - Files: `comms/src/adapters/sendgrid.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: accepted-send test asserts message id + consoleUrl; failed-send test asserts onError invocation
+- [x] **Task 1.4**: Peer dep + registration + docs
+  - Description: optional peer `@sendgrid/mail`; env-gated example-backend registration with fail-fast; reference + env docs incl. sender-verification checklist
+  - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+  - Depends on: 1.1
+  - Acceptance: boot without key skips registration; compile passes without the SDK installed
+
+## Phase 2 — Delivery events + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Task 3.3. The tables in the SendGrid IP remain the contract. Do not Pick these on this
+adapter branch.
+
+- [ ] **Task 2.1**: Event Webhook route
+  - Description: ECDSA signature verification via inbound-webhooks; event mapping per the IP table → `DeliveryEvent`; `x-message-id` prefix correlation
+  - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
+  - Depends on: inbound-webhooks Task 3.3
+  - Acceptance: signed fixtures per event type update `CommsMessage.status` (+ `errorCode` for bounce/dropped); unsigned rejected 401
+- [ ] **Task 2.2**: Opt-out events
+  - Description: `spamreport`/`unsubscribe`/`group_unsubscribe` → `OptOutEvent` → consumer `onOptOut`
+  - Files: `comms/src/adapters/sendgrid.ts` + tests
+  - Depends on: inbound-webhooks Task 3.3
+  - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

package/dist/docs/versioned/57.17.0/tasks/comms-adapter-twilio-sms.md

@@ -0,0 +1,43 @@
+# Tasks: Comms adapter — Twilio SMS
+
+IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.md)
+
+## Phase 1 — Send path
+
+- [x] **Task 1.1**: `TwilioSmsProvider` with config resolution
+  - Description: constructor/env config, messaging-service-first sender selection
+  - Files: `comms/src/adapters/twilioSms.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests cover both sender configs
+- [x] **Task 1.2**: E.164 validation + error classification
+  - Description: `libphonenumber-js` normalization; Twilio error-code → `errorCode`/`errorClass` map per the IP table (unknown codes → `transient`); full error payload into `CommsMessage.metadata`; Twilio SDK calls wrapped with `withApiErrorHandling`
+  - Files: `comms/src/adapters/twilioSms.ts`
+  - Depends on: 1.1
+  - Acceptance: invalid number → permanent `SendResult` before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
+- [x] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Description: `metadata.consoleUrl` deep link per message SID; `onError` fires with the classified `SendResult`
+  - Files: `comms/src/adapters/twilioSms.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: failed-send test asserts consoleUrl and onError invocation
+- [x] **Task 1.4**: Peer dep + example-backend registration + docs
+  - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
+  - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+  - Depends on: 1.1
+  - Acceptance: compile + boot without twilio installed when unconfigured
+
+## Phase 2 — Delivery callbacks + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Tasks 3.2–3.3. The tables in the Twilio SMS IP remain the contract. Do not Pick these on
+this adapter branch.
+
+- [ ] **Task 2.1**: Status callback route
+  - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework; status mapping per IP table incl. `ErrorCode` propagation
+  - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
+  - Depends on: inbound-webhooks Task 3.2
+  - Acceptance: signed payload updates `CommsMessage.status` (+ `errorCode` on failure); unsigned rejected 401
+- [ ] **Task 2.2**: STOP/START opt-out handling
+  - Description: inbound keyword webhook → `OptOutEvent` → consumer `onOptOut`; opt-in (START) emitted symmetrically
+  - Files: `comms/src/adapters/twilioSms.ts`, webhook registration + tests
+  - Depends on: inbound-webhooks Task 3.2
+  - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

package/dist/docs/versioned/57.17.0/tasks/comms-adapter-twilio-verify.md

@@ -0,0 +1,19 @@
+# Tasks: Comms adapter — Twilio Verify (OTP)
+
+IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-verify.md)
+
+- [x] **Task 1**: `TwilioVerifyProvider` start/check
+  - Description: provider per IP with config resolution and status mapping
+  - Files: `comms/src/adapters/twilioVerify.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
+- [x] **Task 2**: Redacted logging + error classification
+  - Description: `CommsMessage` rows with channel `verification`, fully redacted destination, no codes, and verification channel metadata on start; `errorCode`/`errorClass` mapping (rate-limit transient, expired/max-attempts permanent, bad SID config); rows flagged non-retryable; `onError` fires on failures
+  - Files: `comms/src/adapters/twilioVerify.ts`
+  - Depends on: Task 1
+  - Acceptance: log assertion tests prove no code/full destination in any row; failure fixtures assert class + onError
+- [x] **Task 3**: Registration + docs
+  - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
+  - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 1
+  - Acceptance: boot without config skips registration; with partial config throws at startup

package/dist/docs/versioned/57.17.0/tasks/comms-admin-dashboard.md

@@ -0,0 +1,52 @@
+# Tasks: Comms admin dashboard (errors, retries, log digging)
+
+IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
+
+## Phase 1 — Backend routes
+
+- [x] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
+  - Description: rich filters (channel/provider/status/errorClass/errorCode/userId/to/templateId/dates/`q`), pagination, `GET /comms/messages/:id` with attempts + metadata + retained payload
+  - Files: `comms/src/routes/commsDashboard.ts` + supertest
+  - Depends on: comms-abstraction Phase 2 (incl. hooks/error-taxonomy additions)
+  - Acceptance: every filter covered by a supertest case; non-admin 403
+- [x] **Task 1.2**: `retryMessage` facade + retry route
+  - Description: retryability validation (status, errorClass, payload retention, channel configured, not verification), linked rows via `retriedFromId`/`retriedById`, hooks fire with `isRetry: true`, acting admin recorded
+  - Files: `comms/src/commsService.ts`, `comms/src/routes/commsDashboard.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: each non-retryable reason returns 400 with its stable `code`; successful retry creates a linked row
+- [x] **Task 1.3**: `retryMany` + `/comms/stats`
+  - Description: bulk retry with cap + skipped reasons; aggregation by channel × provider × status with day buckets and failure rate
+  - Files: `comms/src/routes/commsDashboard.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: stats counts match list totals for the same filter/range; cap enforced
+
+## Phase 2 — Admin screens
+
+- [x] **Task 2.1**: `CommsDashboardScreen`
+  - Description: stats cards, filter bar (URL-persisted), DataTable with status badges + inline retry
+  - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx`, `CommsStatusBadge.tsx`, `useCommsDashboardApi.tsx` + tests
+  - Depends on: 1.1, 1.3
+  - Acceptance: loading/error/empty states; filters round-trip through the URL
+- [x] **Task 2.2**: `CommsMessageDetail`
+  - Description: attempt timeline, provider console links, JSON viewer for payload/metadata, confirmed retry button with disabled-reason tooltips
+  - Files: `admin-frontend/src/comms/CommsMessageDetail.tsx` + tests
+  - Depends on: 1.2, 2.1
+  - Acceptance: non-retryable rows show the specific reason; retry navigates to the new row
+- [x] **Task 2.3**: Example app + admin-spa wiring
+  - Description: expo-router screens under `app/admin/comms/`, admin-spa nav entry, `bun run sdk`
+  - Files: `example-frontend/app/admin/comms/*`, `example-frontend/store/openApiSdk.ts`, admin-spa nav
+  - Depends on: 2.1, 2.2
+  - Acceptance: frontend verification in the running example app with screenshots on the PR
+
+## Phase 3 — Bulk retry UI + docs
+
+- [x] **Task 3.1**: "Retry all failed" flow
+  - Description: filtered bulk retry with count confirmation modal; skipped-reason summary toast
+  - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx` + tests
+  - Depends on: 1.3, 2.1
+  - Acceptance: confirmation shows the exact count; result summarizes retried/skipped
+- [x] **Task 3.2**: Docs + rules
+  - Description: dashboard section in comms reference, admin reference update, rulesync
+  - Files: `docs/reference/comms.md`, `docs/reference/admin.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes

package/dist/docs/versioned/57.17.0/tasks/compile-pipeline-dedup.md

@@ -0,0 +1,61 @@
+# Tasks: Compile pipeline dedup
+
+IP: [compile-pipeline-dedup.md](../implementationPlans/compile-pipeline-dedup.md)
+Slice: pipeline-ordering-dedup · Scan goal: reduce-cold-compile-time (305s → 214s)
+
+Tracer-bullet order. Each task names files, acceptance, and verification.
+
+## T0 — Capture baseline artifacts (blocking, no code change)
+
+- **Files:** none (read-only).
+- **Do:** `rm -rf */dist && bun run compile 2>&1 | tee /tmp/baseline-build.log`; copy every
+  package's `dist/` into a baseline snapshot dir for later `diff -r`.
+- **Acceptance:** baseline build log + dist snapshot captured; note the cold time (best of
+  3 already recorded = 305s).
+- **Verify:** snapshot dir exists with per-package `dist/`.
+
+## T1 — Apply the three compile-script edits
+
+- **Files:** `package.json`, `api/package.json`, `admin-backend/package.json`.
+- **Do:**
+  - root `compile` → `bun run --filter '*' compile`
+  - `api` `compile` → `bun tsc`
+  - `admin-backend` `compile` → `bun tsc`
+- **Acceptance:** the three scripts match the IP; `.github/scripts/compile-workspace-deps.js`
+  is untouched (`git diff --stat` excludes it).
+- **Blockers:** none. **Docs:** none yet.
+
+## T2 — Prove correctness: single-build, clean, dist-identical
+
+- **Files:** none (verification).
+- **Do:** `rm -rf */dist && bun run compile 2>&1 | tee /tmp/new-build.log`; then
+  `diff -r` each package's new `dist/` against the T0 snapshot.
+- **Acceptance (IP criteria 1–3):**
+  - exit 0 from clean tree
+  - each buildable `@terreno/*` package appears once; **zero** `Compiling @terreno/... with
+    bun tsc` lines (that string only comes from `compile-workspace-deps.js`, which must not
+    run during the dev build)
+  - `diff -r` reports no differences in any `dist/`
+- **Verify:** grep `/tmp/new-build.log` for per-package compile count and for
+  `compile-workspace-deps` output (expect none).
+
+## T3 — Prove publish/CI unaffected
+
+- **Files:** none (verification).
+- **Do:** confirm `compile-workspace-deps.js` unchanged; re-read each caller
+  (`publish-on-tag.yml`, `.circleci/continue-config.yml`, `new-file-coverage.yml`,
+  `rtk-ci.yml`, `example-*-ci.yml`, `scripts/ci/*.sh`) and confirm each still calls the
+  script directly before its compile step.
+- **Acceptance (IP criterion 5):** every publish/CI compile is preceded by a direct
+  `compile-workspace-deps.js` call; script content unchanged.
+
+## T4 — Measure + docs
+
+- **Files:** build/compile explanation doc (if the root `compile` contract is documented).
+- **Do:** run the metric command best-of-3
+  (`find . -maxdepth 2 -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete; rm -rf */dist; time bun run compile`);
+  record min. Update the build doc to note reliance on Bun topological ordering (via
+  `update-docs` skill).
+- **Acceptance (IP criteria 4, 6):** cold time recorded with delta vs 305s; `bun run lint`,
+  `bun run api:test`, `bun run ui:test` green.
+- **Verify:** three timings recorded; lint/test exit 0.

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

@@ -0,0 +1,195 @@
+# Task List: Consent Forms System
+
+**Status:** Closed (2026-08-20) — IP complete. Shipped in `@terreno/api` (`ConsentApp`) and `@terreno/ui`. Open tasks below were not executed.
+
+*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/dist/docs/versioned/57.17.0/tasks/create-terreno-app.md

@@ -0,0 +1,82 @@
+# Tasks: create-terreno-app scaffolding CLI
+
+Plan: [`docs/implementationPlans/create-terreno-app.md`](../implementationPlans/create-terreno-app.md)
+
+**Status:** Approved — all in-scope tasks Roast PASS. **next: brew**.  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1174
+
+## Instructions for the implementing agent
+
+- Load `update-docs`. Generator/CLI tests use Bun `expect` in `create-terreno-app/` and `mcp-server/`.
+- TDD: failing test first per task. Public seam is the CLI bin / `generateAllFiles` / `handleBootstrapToolCall`, not private string helpers.
+- Do not clone `example-*`. Do not copy `example-backend/Dockerfile`. Do not add prompts or `bun install` to the CLI.
+- Hosted MCP must never write disk. Local write requires `TERRENO_MCP_WRITE_SCAFFOLD=1`.
+- After moving generators, `mcp-server` tests for dump shape must stay green.
+
+---
+
+### Phase 1: Shared generator
+
+- [x] **Task 1.1**: Workspace package + extracted `generateAllFiles`
+  - Delivers: `create-terreno-app` workspace package exports `generateAllFiles`; generated `@terreno/*` versions are `^` + this package’s `version`; `mcp-server` imports the export instead of inlining generators
+  - Files: `create-terreno-app/package.json`, `create-terreno-app/src/generate.ts` (and helpers split as needed), `create-terreno-app/src/__tests__/generate.test.ts`, `mcp-server/src/bootstrap.ts`, `mcp-server/package.json`, root `package.json` workspaces
+  - Blocked by: none
+  - Docs: none (package README stub only)
+  - Skills: `update-docs`
+  - Acceptance: `generateAllFiles({appName, appDisplayName})` returns the previous file set (backend, frontend, CI, MCP, seed); every `@terreno/*` range is `^<package.json version>`; `bun test` in `create-terreno-app` and `mcp-server` dump tests pass; no `"latest"` for `@terreno/*`
+
+---
+
+### Phase 2: CLI writer
+
+- [x] **Task 2.1**: `create-terreno-app` bin writes an empty target
+  - Delivers: `bunx create-terreno-app my-app --display-name "My App"` (cwd or explicit parent) writes files via `writeScaffold`; `--yes` derives display name; missing names or non-empty target (anything except `.git` / `.gitignore`) exits non-zero without writing app files; does not run install/seed
+  - Files: `create-terreno-app/src/cli.ts`, `create-terreno-app/src/writeScaffold.ts`, `create-terreno-app/src/__tests__/cli.test.ts`, `create-terreno-app/package.json` `bin`
+  - Blocked by: Task 1.1
+  - Docs: `create-terreno-app/README.md` (command table)
+  - Skills: `update-docs`
+  - Acceptance: temp-dir test writes `backend/package.json` and `frontend/package.json`; stdout includes next-step commands; dirty-dir test leaves the tree unchanged and non-zero; `--yes` without `--display-name` succeeds
+
+---
+
+### Phase 3: Deployable scaffold
+
+- [x] **Task 3.1**: Consumer Dockerfile, env examples, README deploy section
+  - Delivers: generator adds a consumer backend `Dockerfile` (`oven/bun`, `PORT`, `0.0.0.0`, `/health`), `backend/.env.example` + `frontend/.env.example`, keeps local `.env` defaults, README links [deployment baseline](../explanation/deployment-baseline.md), [deploy backend to Cloud Run](../how-to/deploy-backend-to-cloud-run.md), [build for web](../how-to/build-for-web.md)
+  - Files: generator helpers in `create-terreno-app/src/`, `create-terreno-app/src/__tests__/generate.test.ts`
+  - Blocked by: Task 1.1
+  - Docs: generated README in the scaffold (not repo docs yet)
+  - Skills: `update-docs`
+  - Acceptance: file list includes `Dockerfile` and both `.env.example` files; Dockerfile does not `COPY` Terreno monorepo packages or `example-backend`; README contains those three doc paths or their published URLs
+
+---
+
+### Phase 4: MCP delegate
+
+- [ ] **Task 4.1**: Dump names the CLI; write path uses the same generator
+  - Delivers: `handleBootstrapToolCall` dump leads with `bunx create-terreno-app …`; when `targetDir` is set and `TERRENO_MCP_WRITE_SCAFFOLD=1`, writes `<targetDir>/<appName>` with the same files as the CLI; without the env guard, `targetDir` is ignored and nothing is written
+  - Files: `mcp-server/src/bootstrap.ts`, `mcp-server/src/local/` (set the env guard in the local entry), `mcp-server/src/__tests__/bootstrap.test.ts`, `docs/reference/mcp-server.md`
+  - Blocked by: Task 1.1, Task 2.1
+  - Docs: `docs/reference/mcp-server.md` (`targetDir`, write guard, CLI)
+  - Skills: `update-docs`
+  - Acceptance: dump test asserts CLI command present; write test with env + temp `targetDir` creates files; write test without env does not create files even with `targetDir`
+
+---
+
+### Phase 5: Docs, publish, dogfood skill
+
+- [x] **Task 5.1**: Human docs + getting-started + how-to
+  - Delivers: first-run path is the CLI; clone-examples stays as a secondary path
+  - Files: `docs/tutorials/getting-started.md`, `docs/how-to/create-a-terreno-app.md`, `docs/how-to/README.md`, `docs/README.md` (package row)
+  - Blocked by: Task 2.1, Task 3.1
+  - Docs: those files
+  - Skills: `update-docs`
+  - Acceptance: getting-started step 1 is `bunx create-terreno-app` (or `npm create terreno-app`); how-to lists flags, refuse-non-empty, seed login, Dockerfile note; indexes link the how-to
+
+- [x] **Task 5.2**: Publish pipeline, changelog, build-terreno-app skill
+  - Delivers: unscoped package on tag publish; dogfood Phase 2 prefers the CLI and treats MCP dump as fallback
+  - Files: `.github/workflows/publish-on-tag.yml`, CircleCI publish list / `scripts/ci/publish-package.sh` if it enumerates packages, `changelog/unreleased/create-terreno-app.md`, `.rulesync/skills/build-terreno-app/SKILL.md` then `bun run skills:sync`, `docs/explanation/roadmap-seed-issues.md` (IP/task links already present — confirm)
+  - Blocked by: Task 2.1, Task 4.1, Task 5.1
+  - Docs: changelog fragment; skill; upgrade note if the next version file exists
+  - Skills: `update-docs`, `update-agent-docs`
+  - Acceptance: publish job includes `create-terreno-app`; changelog fragment `category: Added`; skill Phase 2 says to run `create-terreno-app` first; `bun run skills:sync` updates generated skill copies