@terreno/mcp 57.2.0 → 57.3.0

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

@@ -0,0 +1,421 @@
+# Implementation Plan: Consent Forms System
+
+**Status:** Complete
+**Closed:** 2026-08-20 — Shipped via `ConsentApp`, `ConsentForm`/`ConsentResponse` models, and `@terreno/ui` consent screens (`ConsentNavigator`, `ConsentFormScreen`, `useConsentForms`).
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1078
+
+*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/57.2.0/implementationPlans/deploy-to-gcp.md

@@ -0,0 +1,167 @@
+# Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+**Status:** Approved — decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1005
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`deployment-foundation`](deployment-foundation.md) for the shared Dockerfile and env reference (soft dependency — Phase 1 can start in parallel)
+**RTK deprecation flag:** None for the backend and infrastructure. The frontend build step is data-layer agnostic (`expo export -p web` output is static either way). The only RTK-adjacent content is the `EXPO_PUBLIC_API_URL` env var, which survives the syncdb migration.
+
+## Goal
+
+Turn Terreno's GCP deployment story from "how Flourish deploys Terreno" into "how anyone deploys a Terreno app to GCP", and give agents a skill that can execute it. Today `docs/how-to/deploy-to-gcp.md` hardcodes the `flourish-terreno` project, `flourish-terreno-terreno-demo` bucket names, and Flourish's service-account layout; `terraform/README.md` is Flourish-specific; and `scripts/setup-gcs-hosting.sh` provisions Flourish's two static sites. None of it is reusable by an outside user, and no skill wraps any of it.
+
+## Non-Goals
+
+- Multi-region or multi-environment (staging/prod) topologies beyond a documented single extra environment.
+- Kubernetes/GKE. Cloud Run only.
+- Managing MongoDB inside GCP. Mongo Atlas is the documented path; self-hosted Mongo is explicitly out of scope.
+- Replacing Flourish's existing terraform — that is relocated, not rewritten (see program question P5).
+
+## Blocking questions
+
+**Recorded 2026-07-29.**
+
+| # | Question | Decision |
+|---|----------|----------|
+| GC1 | Frontend web hosting | **GCS + Cloud CDN as GCP default**, plus **Netlify** (document the existing Flourish/Terreno Netlify pattern as a first-class alternative for static web export) |
+| GC2 | Database guidance | **MongoDB Atlas only** for launch; add a **future-work note** toward Postgres when the data layer supports it |
+| GC3 | terraform or gcloud | **C** — `gcloud` quickstart + terraform for production |
+| GC4 | Reusable terraform module | **B** — `terraform/modules/terreno-backend/` |
+| GC5 | Flourish infra location (→ P5) | **C** — `infra/flourish/` now; **migrate to B** (private repo) post-launch |
+| GC6 | `deploy-gcp` skill deploys? | **C** — full deploy behind explicit confirmation gate |
+| GC7 | Secret management | **A** — Secret Manager for secrets; plain env for non-secrets |
+
+## Architecture
+
+### Reference topology (documented default)
+
+**GCP path:** GCS + Cloud CDN for static web export (see diagram below).
+
+**Netlify path:** Document the existing Terreno/Flourish Netlify static hosting pattern as a first-class alternative for `expo export -p web` — same backend topology, different static host.
+
+```mermaid
+flowchart TD
+  U["User<br/>iOS / Android / Web"]
+  CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
+  CR["Cloud Run<br/>@terreno/api backend"]
+  SM["Secret Manager<br/>auth secrets, MONGO_URI"]
+  AT["MongoDB Atlas<br/>replica set (change streams)"]
+  GCS["GCS bucket<br/>user file uploads"]
+  AR["Artifact Registry<br/>backend image"]
+  U -->|"web"| CDN
+  U -->|"native app"| CR
+  CDN -->|"API calls"| CR
+  CR --> SM
+  CR --> AT
+  CR --> GCS
+  AR --> CR
+```
+
+### Required GCP resources
+
+| Resource | Purpose | Notes |
+|----------|---------|-------|
+| Artifact Registry repo | backend container images | Regional, Docker format |
+| Cloud Run service | backend | Min instances 0 for dev, ≥1 for prod (cold starts break websockets); `--session-affinity` required for Socket.io |
+| Secret Manager secrets | auth secrets + `MONGO_URI` | Mounted as env vars via `--set-secrets` |
+| GCS bucket (web) | static web export | `notFoundPage=index.html` for client-side routing |
+| Backend bucket + URL map + IP + proxy + forwarding rule | Cloud CDN in front of the web bucket | The five resources the current script creates |
+| GCS bucket (uploads) | user file storage | Separate from the web bucket; not public |
+| Service account (runtime) | Cloud Run identity | `roles/secretmanager.secretAccessor`, `roles/storage.objectAdmin` on the uploads bucket only |
+| Service account (deploy) | CI identity | Prefer Workload Identity Federation over JSON keys |
+
+### Websocket and change-stream constraints to document
+
+These are the non-obvious failure modes and must be called out explicitly:
+
+- Socket.io on Cloud Run requires `--session-affinity` and a request timeout raised from the 300s default.
+- Change streams (realtime + feature-flag live updates) require a replica set. A standalone `mongod` silently fails at startup — the guide must say so.
+- Scaling to zero drops websocket connections; the client reconnects, but feature-flag live updates lag. Recommend `--min-instances=1` for anything user-facing.
+- `corsOrigin` in `setupServer` must include the CDN domain, and Better Auth needs the web origin in `trustedOrigins`.
+
+### `deploy-gcp` skill shape
+
+New skill at `.rulesync/skills/deploy-gcp/SKILL.md`, generated into all agent targets. Structure:
+
+1. **Preflight** — detect project layout (bootstrap `backend/`+`frontend/` vs monorepo), read `gcloud config`, verify required APIs enabled, verify `MONGO_URI` points at a replica set.
+2. **Plan** — print the exact resources to be created/updated and the target project, region, and service names. Require explicit user confirmation before mutating anything (GC6).
+3. **Backend** — build image, push to Artifact Registry, create/update secrets, deploy Cloud Run with session affinity and the correct env/secret wiring.
+4. **Frontend** — `expo export -p web`, sync to the web bucket, invalidate CDN cache.
+5. **Verify** — `curl <backend>/health` expecting `"healthy":true`, fetch the web root, confirm the SPA loads, print URLs.
+6. **Troubleshoot** — a table of symptom → cause → fix covering the four constraints above.
+
+## Models
+
+None.
+
+## APIs
+
+None new. The guide relies on the existing `/health` endpoint from `@terreno/api-health` for verification.
+
+## Notifications
+
+None.
+
+## UI
+
+None.
+
+## Phases
+
+1. **Generalize the how-to** — rewrite `docs/how-to/deploy-to-gcp.md` as a project-agnostic guide covering backend + frontend, with placeholder variables and the constraints section.
+2. **Terraform module** — extract a reusable `terraform/modules/terreno-backend/` module; relocate Flourish-specific config to `infra/flourish/`.
+3. **Scripts** — parameterize `scripts/setup-gcs-hosting.sh` to take project/bucket/site names as arguments instead of hardcoding Flourish's.
+4. **Skill** — author `deploy-gcp` in `.rulesync/skills/` and generate mirrors.
+5. **Validate** — deploy the example stack to a scratch GCP project using only the public guide, then fix what the guide got wrong.
+
+## Feature Flags & Migrations
+
+No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenced by `.github/workflows/cd.yml` and `terraform/README.md`; both must be updated in the same commit.
+
+## Not Included / Future Work
+
+- Multi-environment terraform workspaces beyond one documented staging example.
+- Cost estimation guidance.
+- Cloud Armor / WAF configuration.
+- Deploying the hosted MCP server (that is Flourish's own infra, documented in `infra/flourish/`).
+- SSR-capable web hosting — depends on [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md).
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/how-to/deploy-backend-to-cloud-run.md`
+- `docs/how-to/deploy-web-to-gcs-cdn.md`
+- `docs/explanation/deployment-architecture-gcp.md`
+- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,README.md}`
+- `.rulesync/skills/deploy-gcp/SKILL.md`
+- `.rulesync/skills/deploy-gcp/references/troubleshooting.md`
+
+**Modify**
+
+- `docs/how-to/deploy-to-gcp.md` (becomes an index pointing at the two new guides, or is deleted with redirects)
+- `docs/how-to/README.md`
+- `scripts/setup-gcs-hosting.sh` (parameterize)
+- `terraform/README.md` (split generic vs Flourish)
+- `.github/workflows/cd.yml`, `.github/workflows/demo-deploy.yml`, `.github/workflows/frontend-example-deploy.yml` (path updates if terraform moves)
+- `example-backend/Dockerfile` (created by [`deployment-foundation`](deployment-foundation.md); referenced here)
+
+## Task List
+
+See [`docs/tasks/deploy-to-gcp.md`](../tasks/deploy-to-gcp.md).
+
+## Acceptance Criteria
+
+- [ ] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
+- [ ] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
+- [ ] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
+- [ ] `terraform/modules/terreno-backend/` applies cleanly against a scratch project with only variables supplied, creating Cloud Run + Artifact Registry + secrets + service accounts.
+- [ ] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
+- [ ] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
+- [ ] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
+- [ ] A full deploy of `example-backend` + `example-frontend` to a scratch GCP project succeeds following only the public docs, and `curl <backend>/health` returns `"healthy":true`.
+- [ ] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.