@terreno/mcp 57.0.0 → 57.2.0

package/dist/docs/versioned/57.1.0/tasks/comms-abstraction.md

@@ -0,0 +1,96 @@
+# Tasks: Pluggable communications layer (@terreno/comms)
+
+IP: [comms-abstraction](../implementationPlans/comms-abstraction.md)
+
+## Phase 1 — Package + contracts
+
+- [x] **Task 1.1**: Scaffold `@terreno/comms` workspace package
+  - Description: `comms/` package with tsconfig/biome/bun test setup mirroring `feature-flags/`; root workspace entry + `comms:*` scripts
+  - Files: `comms/package.json`, `comms/tsconfig.json`, `comms/biome.jsonc`, root `package.json`
+  - Depends on: none
+  - Acceptance: `bun run comms:compile` and `bun run comms:lint` pass
+- [x] **Task 1.2**: Finish provider types for remaining contracts
+  - Description: Add `cancelled` to `CommsMessageStatus`; expand `CommsHookContext` (`message`, `userId`, `isRetry`, `attempt`, `messageId`); add `OptOutEvent`; add `errorCode`/`errorClass` on `DeliveryEvent`; keep shipped `onRetry(context, result)` and `isPermanentFailure` alias
+  - Status: base provider/message/`errorCode`/`errorClass` shipped; listed fields remain
+  - Files: `comms/src/types.ts`, `comms/src/index.ts`
+  - Depends on: 1.1
+  - Acceptance: types compile and are exported; existing SendGrid tests still typecheck against `onRetry(context, result)`
+- [x] **Task 1.3**: Console adapters
+  - Description: dev adapters for all four channels logging via `logger.info`
+  - Files: `comms/src/adapters/console.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: each adapter returns `accepted: true` and logs
+- [x] **Task 1.4**: `CommsMessage` attempt history + dashboard fields
+  - Description: add `status: cancelled`, `attempts[]`, `attemptCount`, `lastAttemptAt`, `retriedFromId`/`retriedById`, `templateId`, `payload`, `payloadExpiresAt`; `logSend` creates the first row; `appendAttempt` never throws; `clearExpiredPayloads` unsets expired `payload` only (limit 50)
+  - Files: `comms/src/models/commsMessage.ts`, `comms/src/modelTypes.ts` + tests
+  - Depends on: 1.2
+  - Acceptance: send logging survives a forced model error (logged, not thrown); a second attempt appends without a second row; Mongo TTL index is not used
+  - Status: model, `errorCode`/`errorClass`, and non-throwing `logSend` shipped; listed fields remain
+- [x] **Task 1.5**: Channel-wide transient retry + no rethrow
+  - Description: wrap provider throws as `{accepted: false, errorClass: "transient", errorCode: "provider-throw"}`; retry once on transient for `sendMail`, `sendSms`, `startVerification`; for `sendPushToUser`, retry only tokens whose first result is transient; do not retry `checkVerification`; prune tokens when `errorClass === "permanent"` or `isPermanentFailure === true`
+  - Status: mail retry shipped; SMS/push/verification still rethrow; prune is `isPermanentFailure` only
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 1.2, 1.3, 1.4
+  - Acceptance: unit tests cover happy path + unconfigured channel in both env modes; permanent/config failures do not retry; SMS throw returns a `SendResult` instead of rejecting
+- [x] **Task 1.6**: Lifecycle hooks + event intake
+  - Description: `beforeSend` (mutate/cancel, once before first attempt; throwing beforeSend = no cancel); `onSend`/`onError`/`onRetry` (keep `(context, result)`, set `context.attempt`); `recordDeliveryEvent` / `recordOptOut` invoke `onDeliveryEvent` / `onOptOut` and update the log row by `providerMessageId` when present; wrap every hook
+  - Files: `comms/src/commsService.ts`, `comms/src/types.ts` + tests
+  - Depends on: 1.5
+  - Acceptance: one test per hook (fires with correct context) plus one throwing-hook test per hook; cancelled send has `status: "cancelled"` and zero provider calls
+- [x] **Task 1.7**: Payload retention + redaction
+  - Description: `retainPayloadDays` (default 30) stores the channel payload after `redactPayload`; `retainPayloadDays: 0` stores nothing; push payload omits tokens; verification start stores `{channel}` only; `clearExpiredPayloads` runs best-effort from `logSend`/`appendAttempt`
+  - Files: `comms/src/commsService.ts`, `comms/src/models/commsMessage.ts` + tests
+  - Depends on: 1.4, 1.5, 1.6
+  - Acceptance: payload stored redacted; expired payload cleared without deleting the row; `retainPayloadDays: 0` stores nothing
+
+## Phase 2 — CommsApp + routes
+
+- [x] **Task 2.1**: `PushToken` model
+  - Description: model per IP with unique token upsert semantics
+  - Files: `comms/src/models/pushToken.ts` + tests
+  - Depends on: 1.1
+  - Acceptance: duplicate token registration updates the existing row
+- [x] **Task 2.2**: `CommsApp` TerrenoPlugin
+  - Description: options wiring, `getCommsService()` accessor, route mounting on `register()`
+  - Files: `comms/src/commsApp.ts` + tests
+  - Depends on: 1.5, 2.1
+  - Acceptance: plugin registers on `TerrenoApp` and service accessor returns configured providers
+- [x] **Task 2.3**: Push token routes
+  - Description: custom idempotent registration/list/deactivation endpoints plus modelRouter owner read; persisted `userId` scoping
+  - Files: `comms/src/routes/pushTokens.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: acceptance criteria bullets 2 pass under supertest
+- [x] **Task 2.4**: Admin delivery explorer
+  - Description: `GET /comms/messages` admin-only, paginated, filtered; OpenAPI builder
+  - Files: `comms/src/routes/commsExplorer.ts` + supertest
+  - Depends on: 2.2
+  - Acceptance: non-admin gets 403; filters work
+- [x] **Task 2.5**: `sendPushToUser` token resolution + pruning
+  - Description: resolve active tokens per user; deactivate tokens whose `SendResult` reports permanent failure
+  - Files: `comms/src/commsService.ts` + tests
+  - Depends on: 2.1, 1.5
+  - Acceptance: dead token is `active: false` after a failed send
+  - Note: remaining prune-by-`errorClass` work is in Task 1.5
+
+## Phase 3 — Integration + docs
+
+- [x] **Task 3.1**: example-backend registration
+  - Description: register `CommsApp` with console adapters; env-gated
+  - Files: `example-backend/src/server.ts`
+  - Depends on: 2.2
+  - Acceptance: backend boots; `/comms/pushTokens` in `/openapi.json`
+- [x] **Task 3.2**: Reference docs + rules
+  - Description: `docs/reference/comms.md`, rulesync source rule, `bun run rules`
+  - Files: `docs/reference/comms.md`, `.rulesync/**`
+  - Depends on: 2.x
+  - Acceptance: `bun run rules:check` passes
+- [x] **Task 3.3**: CI + publish wiring
+  - Description: `comms-ci` workflow; add `@terreno/comms` to `publish-on-tag.yml`
+  - Files: `.github/workflows/comms-ci.yml`, `.github/workflows/publish-on-tag.yml`
+  - Depends on: 1.x
+  - Acceptance: CI green on the PR
+- [x] **Task 3.4**: Docs refresh for gap-fill APIs
+  - Description: document `beforeSend`, `recordDeliveryEvent`/`recordOptOut`, attempt history, payload retention, channel-wide retry, and the `onRetry`/`isPermanentFailure` aliases in reference docs + comms rule
+  - Files: `docs/reference/comms.md`, `.rulesync/rules/comms/00-comms.md`
+  - Depends on: 1.6, 1.7
+  - Acceptance: `bun run rules:check` passes; docs match the Approved IP

package/dist/docs/versioned/57.1.0/tasks/comms-adapter-expo-push.md

@@ -0,0 +1,29 @@
+# Tasks: Comms adapter — Expo push notifications
+
+IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
+
+- [ ] **Task 1**: `ExpoPushProvider` implementation
+  - Description: token validation, chunked send, ticket collection per IP
+  - Files: `comms/src/adapters/expoPush.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: mocked-client tests pass, one `SendResult` per token
+- [ ] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
+  - Description: poll receipts after configurable delay; map `DeviceNotRegistered` to permanent failure
+  - Files: `comms/src/adapters/expoPush.ts`
+  - Depends on: Task 1
+  - Acceptance: dead token deactivated in test
+- [ ] **Task 3**: Dependency moves
+  - Description: optional peer `expo-server-sdk` on comms; remove from `@terreno/api`
+  - Files: `comms/package.json`, `api/package.json`, root catalog if needed
+  - Depends on: Task 1
+  - Acceptance: `bun install` + full compile pass; api tests unaffected
+- [ ] **Task 4**: example-frontend token registration + dev test-send
+  - Description: register token on login via `POST /comms/pushTokens`; profile dev row triggers `sendPushToUser`
+  - Files: `example-frontend/app/_layout.tsx` or profile screen, `example-backend` dev route
+  - Depends on: Task 1, comms-abstraction Phase 2
+  - Acceptance: UI verification per verify-ui-changes with screenshots
+- [ ] **Task 5**: Docs
+  - Description: adapter section in `docs/reference/comms.md` with env/config table
+  - Files: `docs/reference/comms.md`
+  - Depends on: Task 1
+  - Acceptance: docs build passes

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

@@ -0,0 +1,39 @@
+# 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 (gated on inbound-webhooks)
+
+- [ ] **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 IP
+  - 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: 2.1
+  - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

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

@@ -0,0 +1,39 @@
+# Tasks: Comms adapter — Twilio SMS
+
+IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.md)
+
+## Phase 1 — Send path
+
+- [ ] **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
+- [ ] **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 → 400 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
+- [ ] **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
+- [ ] **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 (gated on inbound-webhooks)
+
+- [ ] **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 IP
+  - 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: 2.1
+  - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

package/dist/docs/versioned/57.1.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)
+
+- [ ] **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
+- [ ] **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
+- [ ] **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.1.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
+
+- [ ] **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
+- [ ] **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
+- [ ] **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
+
+- [ ] **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
+- [ ] **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
+- [ ] **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
+
+- [ ] **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
+- [ ] **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.1.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.1.0/tasks/deploy-to-gcp.md

@@ -0,0 +1,99 @@
+# Task List: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy-to-gcp.md)
+
+**RTK deprecation flag:** None. The only client-side surface is `EXPO_PUBLIC_API_URL`, which is unchanged by PR #869. Safe to implement before #869 merges.
+
+## Instructions for the implementing agent
+
+- Use placeholder variables in all documentation: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$WEB_BUCKET`, `$UPLOADS_BUCKET`. Never hardcode a real project ID, bucket, or URL.
+- Grep for `flourish` in every file you write or edit before committing: `rg -i flourish <file>`. The only permitted matches are inside `infra/flourish/`.
+- Do **not** run `gcloud` commands that create or modify resources unless the user has explicitly named a target project in the request.
+- Verify every `gcloud` flag you document against `gcloud run deploy --help` before writing it. Do not guess flag names.
+- Run `bun run lint` before each commit; run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Generalize the how-to guides
+
+- [x] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Description: New guide covering: prerequisites (gcloud installed and authenticated, billing enabled, required APIs — `run`, `artifactregistry`, `secretmanager`, `compute`); creating an Artifact Registry repo; building and pushing the backend image; creating Secret Manager secrets for `MONGO_URI`, `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, and `BETTER_AUTH_SECRET`; creating the runtime service account with least-privilege roles; the `gcloud run deploy` invocation with `--session-affinity`, `--timeout`, `--min-instances`, `--set-secrets`, and `--set-env-vars`; and verification via `curl $SERVICE_URL/health`. Use placeholder variables throughout. Read `example-backend/src/server.ts` and `docs/reference/environment-variables.md` to get the env var list right — do not copy it from this task description without checking.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md` (new)
+  - Depends on: none
+  - Acceptance: `rg -i flourish docs/how-to/deploy-backend-to-cloud-run.md` returns nothing; every env var named exists in `docs/reference/environment-variables.md` or the backend source; every `gcloud` flag used appears in `gcloud run deploy --help`.
+
+- [x] **Task 1.2**: Add the production constraints section
+  - Description: Add a "Production constraints" section to the backend guide as a symptom → cause → fix table covering at minimum: (a) websockets disconnect every few requests → no session affinity → add `--session-affinity`; (b) long-lived socket connections drop at 5 minutes → default request timeout → raise `--timeout`; (c) realtime and live feature flags stop working → MongoDB is not a replica set → use Atlas or a replica set, because change streams require one; (d) first request after idle is slow and sockets churn → scaled to zero → `--min-instances=1`; (e) browser requests fail CORS → `corsOrigin` in `setupServer` and Better Auth `trustedOrigins` do not include the web origin. Verify claim (c) against `feature-flags` live-update code before writing it.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Depends on: Task 1.1
+  - Acceptance: all five rows present with a concrete symptom; the change-streams claim is verified against the source and the source path is cited in the guide.
+
+- [x] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Description: New guide covering: building the web bundle (`bunx expo export -p web` — confirm the exact command against `example-frontend/package.json` scripts), the requirement to set `EXPO_PUBLIC_API_URL` at build time because it is inlined into the bundle, creating and configuring the GCS bucket with public read and `notFoundPage=index.html` for client-side routing, the five CDN resources (backend bucket, URL map, static IP, HTTP(S) proxy, forwarding rule), pointing DNS at the IP, and cache invalidation after each deploy. Include a note that this is a static-only path and link [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md) for the SSR future.
+  - Files: `docs/how-to/deploy-web-to-gcs-cdn.md` (new)
+  - Depends on: none
+  - Acceptance: no Flourish strings; the export command matches an actual script in `example-frontend/package.json`; the guide explains why `EXPO_PUBLIC_API_URL` must be set before building, not after.
+
+- [x] **Task 1.4**: Write the architecture explainer
+  - Description: Create `docs/explanation/deployment-architecture-gcp.md` explaining the reference topology (reuse the mermaid diagram from the IP), what each component is responsible for, why Cloud Run rather than App Engine or GKE, why Atlas rather than self-hosted Mongo, and the tradeoffs of static web hosting versus a server-rendered deployment. Keep it conceptual — no commands.
+  - Files: `docs/explanation/deployment-architecture-gcp.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: contains the topology diagram; contains no shell commands; explains at least three explicit tradeoffs.
+
+- [x] **Task 1.5**: Rewire the existing GCP how-to and index
+  - Description: Replace `docs/how-to/deploy-to-gcp.md` with a short index page linking the two new guides and the explainer, preserving the old anchor names where practical so existing links do not break. Update `docs/how-to/README.md` to list the new guides. Check `website/` for any hardcoded reference to the old page path and update it.
+  - Files: `docs/how-to/deploy-to-gcp.md`, `docs/how-to/README.md`, `website/` (as needed)
+  - Depends on: Task 1.1, Task 1.3, Task 1.4
+  - Acceptance: `bun run website:build` succeeds with no new broken-link warnings introduced by this change.
+
+## Phase 2: Terraform module and Flourish separation
+
+- [ ] **Task 2.1**: Extract the generic backend module
+  - Description: Create `terraform/modules/terreno-backend/` with `main.tf`, `variables.tf`, `outputs.tf`, and `README.md`. Resources: Artifact Registry repository, Cloud Run v2 service (session affinity, timeout, min/max instances, secret env refs), Secret Manager secrets (created empty, values supplied out-of-band), runtime service account with `secretmanager.secretAccessor` and object admin on a supplied uploads bucket, and optional Workload Identity Federation pool for CI. Every value that could differ between users must be a variable with a description and no Flourish default. Outputs: service URL, service account email, registry path.
+  - Files: `terraform/modules/terreno-backend/main.tf`, `variables.tf`, `outputs.tf`, `README.md` (all new)
+  - Depends on: Task 1.1
+  - Acceptance: `terraform init && terraform validate` passes in the module directory; `rg -i flourish terraform/modules/` returns nothing; every variable has a `description`.
+
+- [ ] **Task 2.2**: Relocate Flourish-specific terraform
+  - Description: Move Flourish's environment configuration from `terraform/` to `infra/flourish/`, leaving only `terraform/modules/` behind. Update every path reference: `.github/workflows/cd.yml`, `terraform/README.md` (split into a generic module README and `infra/flourish/README.md`), `AGENTS.md` / `CLAUDE.md` if they reference `terraform/README.md`, and any script under `scripts/`. Use `git mv` so history is preserved.
+  - Files: `infra/flourish/**` (moved), `terraform/README.md`, `.github/workflows/cd.yml`, `AGENTS.md`, `CLAUDE.md`, `scripts/**`
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "terraform/" --glob '!infra/**' --glob '!terraform/**'` shows no stale paths pointing at moved files; the `cd.yml` workflow references the new location; `bun run rules:check` exits 0 after regenerating rules.
+
+- [x] **Task 2.3**: Parameterize the GCS hosting script
+  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, `--bucket`, and `--domain` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact, with HTTPS as the only public serving path. Add a `--dry-run` flag that prints commands without executing them.
+  - Files: `scripts/setup-gcs-hosting.sh`
+  - Depends on: Task 1.3
+  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces HTTPS commands containing the supplied values, no port 80 forwarding rule, and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
+
+## Phase 3: The `deploy-gcp` skill
+
+- [x] **Task 3.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-gcp/SKILL.md` with frontmatter (`name: deploy-gcp`, a `description` that names the trigger phrases "deploy to GCP", "deploy to Cloud Run", "ship the backend", and `targets: ['*']`). Body sections in this order: When to use / When not to use; Preflight checks (project layout detection, `gcloud config get-value project`, required APIs, replica-set verification of `MONGO_URI`); **Plan and confirm** — print target project, region, service name, and every resource to be created or updated, then stop and require explicit user confirmation before any mutating command; Backend deploy steps; Frontend deploy steps; Verification (`curl $SERVICE_URL/health` expecting `"healthy":true`, fetch web root); Troubleshooting (link the reference file). Include an explicit prohibition: never deploy to a project the user did not name in the request, and never create or modify secrets without echoing which secret names will change.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: frontmatter has `name`, `description`, and `targets`; the confirmation gate appears before the first mutating command; every command in the skill also appears in the how-to guides (no skill-only knowledge).
+
+- [x] **Task 3.2**: Add the troubleshooting reference
+  - Description: Create `.rulesync/skills/deploy-gcp/references/troubleshooting.md` containing the symptom → cause → fix table from Task 1.2 plus deploy-time failures: image push permission denied, secret access denied at cold start, Cloud Run revision failing health checks because `PORT` is not read from the environment, and CDN serving a stale bundle after deploy. For each, give the exact log line or error message the user will see.
+  - Files: `.rulesync/skills/deploy-gcp/references/troubleshooting.md` (new)
+  - Depends on: Task 3.1
+  - Acceptance: at least nine rows; each row quotes an actual error string rather than paraphrasing.
+
+- [x] **Task 3.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit every generated file under `.cursor/skills/`, `.claude/skills/`, `.devin/skills/`, `.github/skills/`, and `.agents/skills/`. Do not hand-edit generated files.
+  - Files: generated skill mirrors
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-gcp` appears under each configured target directory.
+
+## Phase 4: Validation
+
+- [ ] **Task 4.1**: Dry-run the guide end to end
+  - Description: Following **only** `docs/how-to/deploy-backend-to-cloud-run.md` and `docs/how-to/deploy-web-to-gcs-cdn.md` (no internal knowledge, no `infra/flourish/`), deploy `example-backend` and `example-frontend` to a scratch GCP project. Record every point where the guide was wrong, incomplete, or required outside knowledge. Fix the guides. Capture the successful `curl $SERVICE_URL/health` output and the loaded web app as artifacts under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`, `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Depends on: Task 1.1, Task 1.3, Task 2.3
+  - Acceptance: the deploy succeeds; `/health` returns `"healthy":true`; the web app loads and can log in against the deployed backend; every guide correction is committed.
+
+- [ ] **Task 4.2**: Exercise the skill against the validated guide
+  - Description: Run the `deploy-gcp` skill in a fresh agent session against the same scratch project and confirm it reaches the same result, including the confirmation gate firing before any mutation. Note any step where the skill needed information the guide did not provide and fix the skill.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` plus mirrors
+  - Depends on: Task 3.3, Task 4.1
+  - Acceptance: the skill run produces a working deploy; the confirmation gate is observed in the transcript; `bun run rules:check` exits 0 after any skill edits.