@explorer02/cfm-survey-sdk 0.1.8 → 0.2.0

package/templates/docs/03-ui-specs/README.md

@@ -0,0 +1,79 @@
+# UI Specifications — Reference Implementation Guide
+
+> **Authoritative source:** [`apps/client/src/components/`](../../../../../../apps/client/src/components/) in the monorepo.
+> Agents must reproduce this UI when building survey apps. Read the spec for each question type present in the fetched survey.
+
+## How to Read a UI Spec
+
+Each file in this folder follows the same structure:
+
+1. **Config inventory** — every SDK field, whether the reference client implements it
+2. **Layout anatomy** — structured ASCII diagram
+3. **Config decision tree** — matches `if/else` branches in reference code
+4. **Interactive states** — default, hover, selected, disabled, focus
+5. **Tooltips & labels** — positioning formulas
+6. **Color tokens** — exact hex values from reference client
+7. **Answer mutation** — `onSelect` / `onAction CHANGE` shape
+8. **Agent checklist**
+
+## Design Tokens (Reference Client)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | `#e20074` | Borders, rings, dots, slider fill, selected text |
+| Selected bg | `#fdf2f8` | Card options, CSAT buttons, matrix cells |
+| NPS track highlight | `#fbe8f3` | Selected radio cell in NPS track row |
+| NPS track bar | `#f2f2f2` | Gray bar behind NPS radios |
+| Validation border | `#333333` | Error banner |
+| Validation bg | `#d9d9d9` | Error banner |
+| Row band | `#f3f4f6` | Slider matrix row background |
+| Zebra row | `rgba(249,250,251,0.8)` | Matrix alternating rows |
+| Tooltip bg | `#1f2937` | Hover tooltips on emoji/slider |
+| Likert carousel dot (active) | `#2563eb` | LikertMatrix carousel only |
+| CSAT carousel dot (active) | `#e20074` | CsatMatrix carousel |
+
+## Reference Component Index
+
+| Spec file | Reference component | `question.type` |
+|-----------|---------------------|-----------------|
+| [00-question-shell.md](00-question-shell.md) | `Question.tsx` | All (wrapper) |
+| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `rating` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `radio` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `text` |
+| [04-csat.md](04-csat.md) | `CsatScale.tsx` | `csat` |
+| [05-rating-scale.md](05-rating-scale.md) | *(gap — reuse CsatScale patterns)* | `rating_scale` |
+| [06-slider.md](06-slider.md) | *(gap — reuse CustomSliderTrack)* | `slider` |
+| [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `matrix` + CFM |
+| [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | CSAT/RATING matrix |
+| [09-slider-matrix.md](09-slider-matrix.md) | `SliderMatrixScale.tsx` | `slider_matrix` |
+| [10-file-upload.md](10-file-upload.md) | `FileUploadScale.tsx` | `file_upload` |
+| [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `text_and_media` |
+| [12-survey-chrome.md](12-survey-chrome.md) | `SurveyPage.tsx` + chrome | Shell |
+| [shared/custom-slider-track.md](shared/custom-slider-track.md) | `CustomSliderTrack.tsx` | Primitive |
+| [shared/matrix-dropdown.md](shared/matrix-dropdown.md) | `MatrixDropdown.tsx` | Primitive |
+
+## NPS Traffic-Light Colors
+
+Use `option.color` from SDK — never invent colors:
+
+| Value | Hex |
+|-------|-----|
+| 0 | `#e2001a` |
+| 1 | `#e4251b` |
+| 2 | `#ec610a` |
+| 3 | `#f18b00` |
+| 4 | `#f7b200` |
+| 5 | `#fcd900` |
+| 6 | `#fcd900` |
+| 7 | `#9fca00` |
+| 8 | `#6bb300` |
+| 9 | `#339a00` |
+| 10 | `#008000` |
+
+## When to Read
+
+After Phase 3 in [`index.md`](../index.md), for each question in `state.currentQuestions`:
+
+1. Read [`02-reference/question-types/`](../02-reference/question-types/) for data shape
+2. Read matching spec from this folder (see [`MANIFEST.json`](../MANIFEST.json) `uiSpecs`)
+3. Cross-check [`config-field-index.md`](../02-reference/config-field-index.md)

package/templates/docs/03-ui-specs/shared/custom-slider-track.md

@@ -0,0 +1,52 @@
+# UI Spec: Custom Slider Track (shared primitive)
+
+> **Reference:** `apps/client/src/components/CustomSliderTrack.tsx`
+> **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
+
+## Layer Architecture
+
+```
+1. Gray inactive track (#e5e7eb, 4px height)
+2. Magenta fill bar (width = percentage%, #e20074 or #9ca3af if disabled)
+3. Tick marks (1px × 8px at ticks positions)
+4. Invisible <input type="range"> overlay (opacity 0, full hit area)
+5. Visual thumb: circle OR emoji (sliderType === 'graphics')
+6. Tooltip bubble on hover/drag (#1f2937 bg, rounded value)
+```
+
+## Props
+
+| Prop | Role |
+|------|------|
+| `min`, `max`, `htmlStep` | Range input bounds |
+| `value` | Current position |
+| `disabled` | Gray theme, opacity 0.5, no interaction |
+| `displayValues` | Reserved — tooltip always shows on hover/drag in client |
+| `hasSelectedValue` | Reserved |
+| `sliderType: 'graphics'` | Emoji thumb via `getEmojiForIndex` |
+| `ticks` | Discrete tick count + emoji index scale |
+| `reverseScaleOrder` | Flip emoji index calculation |
+
+## Interactive States
+
+| State | Thumb | Tooltip |
+|-------|-------|---------|
+| Default | White circle, 2.5px magenta border | Hidden |
+| Hover/drag | Pink glow ring `rgba(226,0,116,0.2)` | Dark bubble with `Math.round(value)` |
+| Disabled | Gray border, opacity 0.5 | Hidden |
+| Graphics | Emoji at percentage position | Same tooltip |
+
+## Emoji Index Formula
+
+```typescript
+const idx = Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1));
+const displayIdx = reverseScaleOrder ? (ticks || 10) - 1 - idx : idx;
+getEmojiForIndex(displayIdx, ticks || 10)
+```
+
+## Agent Checklist
+
+- [ ] 4-layer overlay with invisible range input
+- [ ] Tooltip on hover AND drag
+- [ ] Graphics mode emoji thumb
+- [ ] Transition disabled while dragging

package/templates/docs/03-ui-specs/shared/matrix-dropdown.md

@@ -0,0 +1,38 @@
+# UI Spec: Matrix Dropdown (shared primitive)
+
+> **Reference:** `apps/client/src/components/MatrixDropdown.tsx`
+> **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
+
+## Modes
+
+| `multiple` | Trigger | Selection |
+|------------|---------|-----------|
+| `false` | Single line + chevron | One value; checkmark on selected option |
+| `true` | Tag chips with × | Toggle array; N/A mutex |
+
+## Interactive States
+
+| State | Trigger border | Shadow |
+|-------|----------------|--------|
+| Closed | `#d1d5db` | subtle |
+| Open | `#e20074` | `0 0 0 3px rgba(226,0,116,0.1)` |
+| Option hover | bg `#fdf2f8` | — |
+| Option selected | bg `#fdf2f8`, text `#e20074` | — |
+| N/A mutex (multi) | Other options opacity 0.5, disabled | — |
+
+## N/A Mutex (multi-select)
+
+```typescript
+if (val === null) {
+  if (multiValues.includes(null)) onChange([]);
+  else onChange([null]);
+}
+// When null selected, non-null options disabled
+```
+
+## Agent Checklist
+
+- [ ] Click-outside closes panel
+- [ ] HTML labels via dangerouslySetInnerHTML
+- [ ] Single: close on select
+- [ ] Multi: tag chips removable with ×

package/templates/docs/MANIFEST.json

@@ -0,0 +1,150 @@
+{
+  "version": "1.0.0",
+  "packageNames": {
+    "npm": "@explorer02/cfm-survey-sdk",
+    "monorepo": "@repo/sdk"
+  },
+  "entryPoint": "index.md",
+  "clientInputs": ["initialPrompt", "instanceIdJwt", "deployConfirmation"],
+  "phases": [
+    {
+      "id": 0,
+      "name": "orient",
+      "read": ["index.md", "../AGENT.md"],
+      "actions": ["detectFramework", "extractBrandingFromClientPrompt"]
+    },
+    {
+      "id": 1,
+      "name": "scaffold",
+      "read": ["00-integration/setup.md"],
+      "frameworks": ["nextjs", "vite", "cra"]
+    },
+    {
+      "id": 2,
+      "name": "instanceId",
+      "read": ["00-integration/useSurveySDK.md"]
+    },
+    {
+      "id": 3,
+      "name": "sdkContract",
+      "read": ["00-integration/useSurveySDK.md"]
+    },
+    {
+      "id": 4,
+      "name": "planAndIngest",
+      "read": [
+        "01-components/README.md",
+        "01-components/01-survey-page.md",
+        "01-components/02-question.md",
+        "01-components/03-rating-scale.md",
+        "01-components/04-csat-scale.md",
+        "01-components/05-csat-matrix-scale.md",
+        "01-components/06-likert-matrix-scale.md",
+        "01-components/07-slider-matrix-scale.md",
+        "01-components/08-file-upload-scale.md",
+        "01-components/09-custom-slider-track.md",
+        "01-components/10-header-footer.md",
+        "01-components/11-progress-bar.md",
+        "01-components/12-language-selector.md",
+        "01-components/13-matrix-dropdown.md"
+      ],
+      "template": "templates/implementation_plan.md",
+      "output": "implementation_plan.md"
+    },
+    {
+      "id": 5,
+      "name": "build",
+      "read": ["00-integration/constraints.md", "02-reference/routing-table.md"],
+      "onDemand": "02-reference/question-types"
+    },
+    {
+      "id": 6,
+      "name": "verify",
+      "read": ["00-integration/constraints.md"],
+      "checklist": [
+        "questionDispatcherCoversAll12Types",
+        "everyQuestionWrapperHasId",
+        "noInternalSdkImports",
+        "surveyPageFiveStates",
+        "npmRunBuildPasses"
+      ]
+    },
+    {
+      "id": 7,
+      "name": "deploy",
+      "command": "npx cfm-sdk deploy"
+    }
+  ],
+  "questionTypes": {
+    "rating": {
+      "component": "01-components/03-rating-scale.md",
+      "reference": "02-reference/question-types/01-rating.md"
+    },
+    "radio": {
+      "component": "01-components/02-question.md",
+      "reference": "02-reference/question-types/README.md#radio"
+    },
+    "text": {
+      "component": "01-components/02-question.md",
+      "reference": "02-reference/question-types/README.md#text"
+    },
+    "csat": {
+      "component": "01-components/04-csat-scale.md",
+      "reference": "02-reference/question-types/04-csat.md"
+    },
+    "rating_scale": {
+      "component": "01-components/03-rating-scale.md",
+      "reference": "02-reference/question-types/05-rating-scale.md"
+    },
+    "slider": {
+      "component": "01-components/09-custom-slider-track.md",
+      "reference": "02-reference/question-types/06-slider.md"
+    },
+    "matrix": {
+      "component": "01-components/06-likert-matrix-scale.md",
+      "reference": "02-reference/question-types/07-matrix-cfm.md",
+      "subTypes": {
+        "CFM_MATRIX": "01-components/06-likert-matrix-scale.md",
+        "CSAT_MATRIX": "01-components/05-csat-matrix-scale.md",
+        "RATING_MATRIX": "01-components/05-csat-matrix-scale.md"
+      }
+    },
+    "rating_matrix": {
+      "component": "01-components/05-csat-matrix-scale.md",
+      "reference": "02-reference/question-types/09-matrix-rating.md"
+    },
+    "slider_matrix": {
+      "component": "01-components/07-slider-matrix-scale.md",
+      "reference": "02-reference/question-types/10-slider-matrix.md"
+    },
+    "file_upload": {
+      "component": "01-components/08-file-upload-scale.md",
+      "reference": "02-reference/question-types/11-file-upload.md"
+    },
+    "text_and_media": {
+      "component": "01-components/02-question.md",
+      "reference": "02-reference/question-types/README.md#text_and_media"
+    }
+  },
+  "uiSpecs": {
+    "questionShell": "03-ui-specs/00-question-shell.md",
+    "rating": "03-ui-specs/01-rating.md",
+    "radio": "03-ui-specs/02-radio.md",
+    "text": "03-ui-specs/03-text.md",
+    "csat": "03-ui-specs/04-csat.md",
+    "rating_scale": "03-ui-specs/05-rating-scale.md",
+    "slider": "03-ui-specs/06-slider.md",
+    "matrix_CFM_MATRIX": "03-ui-specs/07-matrix-cfm.md",
+    "matrix_CSAT_MATRIX": "03-ui-specs/08-matrix-csat-rating.md",
+    "matrix_RATING_MATRIX": "03-ui-specs/08-matrix-csat-rating.md",
+    "slider_matrix": "03-ui-specs/09-slider-matrix.md",
+    "file_upload": "03-ui-specs/10-file-upload.md",
+    "text_and_media": "03-ui-specs/11-text-and-media.md",
+    "surveyChrome": "03-ui-specs/12-survey-chrome.md"
+  },
+  "sharedUiSpecs": {
+    "customSliderTrack": "03-ui-specs/shared/custom-slider-track.md",
+    "matrixDropdown": "03-ui-specs/shared/matrix-dropdown.md"
+  },
+  "configFieldIndex": "02-reference/config-field-index.md"
+}

package/templates/docs/index.md

@@ -1,151 +1,120 @@
 # CFM SURVEY SDK — AGENT DOCUMENTATION INDEX
 
-**@explorer02/cfm-survey-sdk**
+**@explorer02/cfm-survey-sdk** (npm) · **@repo/sdk** (monorepo)
 
-This file is the MASTER GUIDE for AI coding agents (Cursor, Copilot, etc.).
-It is a structured roadmap that tells the agent exactly which documentation files to read and in what order.
+Master guide for AI coding agents. Machine-readable index: `MANIFEST.json`.
 
-## ── HOW THIS DOCUMENTATION SYSTEM WORKS ──────────────────────────────────────
-
-The `docs/` folder mirrors the SDK's internal architecture:
+## Documentation Layout
 
 ```
 docs/
-├── index.md                    ← YOU ARE HERE — read this first
-├── 01-sdk-core/                ← SDK internals: fetch, map, paginate, validate, submit
-├── 02-question-types/          ← One doc per question type (12 types)
-├── 03-client-components/       ← One doc per UI component (13 components)
-└── 04-critical-rules/          ← Non-negotiable constraints, imports, troubleshooting
+├── index.md                 ← YOU ARE HERE
+├── MANIFEST.json            ← Phase + question-type routing (for tooling)
+├── 00-integration/          ← Setup, hook contract, constraints
+├── 01-components/           ← Wiring blueprints (read ALL before coding)
+├── 02-reference/            ← Routing table + config-field-index (on demand)
+├── 03-ui-specs/             ← Authoritative UI specs (reference-client driven)
+└── templates/
+    └── implementation_plan.md
 ```
 
-## ── CLIENT INTERACTION FLOW (3 INPUTS ONLY) ──────────────────────────────────
-
-The entire build process requires EXACTLY 3 inputs from the client:
-
-**INPUT 1: Client's initial prompt**
-→ "Build a survey like this image using @explorer02/cfm-survey-sdk"
-→ May include UI mockup screenshots, brand colors, or text description
-→ Agent begins project scaffolding and component architecture
-
-**INPUT 2: Instance ID (agent asks for it)**
-→ Agent asks: "Please provide your survey instance ID (JWT token)"
-→ Client pastes the instanceId string
-→ Agent wires it into SurveyPage.tsx and fetches the survey
-
-**INPUT 3: Deployment confirmation (agent asks at the end)**
-→ Agent asks: "Your survey is built and tested. Ready to deploy to Vercel?"
-→ Client confirms → Agent runs `npx vercel --prod --yes`
-
-## ── EXECUTION PIPELINE ───────────────────────────────────────────────────────
-
-Follow these phases IN ORDER. Each phase references specific doc files.
-
-### PHASE 1: PROJECT SCAFFOLDING
-Read: `04-critical-rules/01-import-rules.md`
-
-Actions:
-1. Create Next.js project:
-   `npx -y create-next-app@latest ./ --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm`
-2. Install SDK:
-   `npm install @explorer02/cfm-survey-sdk @tanstack/react-query`
-3. Configure `next.config.js`:
-   `transpilePackages: ["@explorer02/cfm-survey-sdk"]`
-
-### PHASE 2: ASK FOR INSTANCE ID (INPUT 2)
-Read: `01-sdk-core/01-fetch-survey.md`
-
-Ask the client in chat:
-"Please provide your survey instance ID (the JWT token string) so I can connect your survey."
-
-Wait for the client to paste the instanceId. Store it — you will wire it into SurveyPage.tsx in Phase 4.
-
-### PHASE 3: UNDERSTAND THE SDK PIPELINE
-Read these docs IN ORDER to understand how the SDK works:
-
-1. `01-sdk-core/01-fetch-survey.md`    — How survey data is fetched
-2. `01-sdk-core/02-survey-mapper.md`   — How raw API → Survey object
-3. `01-sdk-core/03-question-mappers.md` — How questions are typed/mapped
-4. `01-sdk-core/07-language-handling.md` — Translations & placeholders
-5. `01-sdk-core/04-pagination.md`      — Page navigation state
-6. `01-sdk-core/05-validation.md`      — Required field validation
-7. `01-sdk-core/06-submit-survey.md`   — Response submission format
-8. `01-sdk-core/08-icons-and-emojis.md` — CSAT emoji/star icon system
-
-Then understand what question types exist:
-9. `02-question-types/README.md`       — Overview of all 12 types
-
-*You do NOT need to read every question type doc upfront. Read them ON DEMAND when you encounter each type during component building.*
-
-### PHASE 4: UI ARCHITECTURE & WORKFLOW PLANNING (CRITICAL)
-Before writing ANY React code, you MUST enter Planning Mode and generate a deeply comprehensive \`implementation_plan.md\`.
-
-**DEEP CONTEXT INGESTION REQUIRED**:
-Before you even start writing the plan, you MUST read EVERY SINGLE markdown file inside \`03-client-components/\`. You cannot plan accurately without knowing the exact architectures required for CSAT bounds, file validations, and matrix transpositions.
-
-Read ALL the component architectural blueprints IN ORDER:
-1. \`03-client-components/README.md\`
-2. \`03-client-components/01-survey-page.md\`
-3. \`03-client-components/02-question.md\`
-4. \`03-client-components/03-rating-scale.md\`
-5. \`03-client-components/04-csat-scale.md\`
-6. \`03-client-components/05-csat-matrix-scale.md\`
-7. \`03-client-components/06-likert-matrix-scale.md\`
-8. \`03-client-components/07-slider-matrix-scale.md\`
-9. \`03-client-components/08-file-upload-scale.md\`
-10. \`03-client-components/09-custom-slider-track.md\`
-11. \`03-client-components/10-header-footer.md\`
-12. \`03-client-components/11-progress-bar.md\`
-13. \`03-client-components/12-language-selector.md\`
-14. \`03-client-components/13-matrix-dropdown.md\`
-
-Your \`implementation_plan.md\` MUST be structured professionally and precisely cover:
-1. **Data Fetching & State**: Precisely how \`useSurveySDK(instanceId)\` will be integrated. How to handle \`isLoading\`, \`error\`, \`empty\`, and \`submitted\` states properly.
-2. **Pagination, Actions, & Flow**: How you will iterate through pages, manage \`onAction({ type: 'NEXT' / 'PREVIOUS' })\`, and precisely wire up the \`ProgressBar\`.
-3. **Question Dispatching**: How \`Question.tsx\` will comprehensively route all 12 \`question.type\` variants (including \`text_and_media\` for \`CONTENT\` questions). How it will safely handle rich HTML parsing and validation error display.
-4. **Question Architectures & Component Checklist**: You must create a checklist inside your plan for EACH complex component. You must verify mappings, step sizes, ticks, hover effects, scale items positioning, and matrix transposition logic EXACTLY as detailed in the blueprints.
-5. **Theme, Brand & Logos**: How you will engineer CSS-only logos based on the client's mockup prompt and map specific brand colors to hover states.
-6. **Submit Survey**: How you will trigger the final \`submitSurvey\` dispatch and elegantly transition the UI to the Thank You screen.
-
-**ACTION**: Generate the \`implementation_plan.md\`. Once the plan is written, **DO NOT WAIT FOR APPROVAL**. Automatically proceed to trigger Phase 5 and start implementing the code!
-
-Then for EACH question type present in the fetched survey, read the matching question-type doc AND component doc:
-
-| `question.type` | Question Doc | Component Doc |
-|---|---|---|
-| `'rating'` | `02-question-types/01-rating` | `03-components/03-rating` |
-| `'radio'` | `02-question-types/02-radio` | (inline in Question) |
-| `'text'` | `02-question-types/03-text` | (inline in Question) |
-| `'csat'` | `02-question-types/04-csat` | `03-components/04-csat` |
-| `'rating_scale'` | `02-question-types/05-rating-s` | `03-components/03-rating` |
-| `'slider'` | `02-question-types/06-slider` | `03-components/09-slider` |
-| `'matrix'` CFM | `02-question-types/07-matrix-c` | `03-components/06-likert` |
-| `'matrix'` CSAT | `02-question-types/08-matrix-c` | `03-components/05-csat-m` |
-| `'matrix'` RATING| `02-question-types/09-matrix-r` | `03-components/05-csat-m` |
-| `'slider_matrix'`| `02-question-types/10-slider-m` | `03-components/07-slider` |
-| `'file_upload'` | `02-question-types/11-file-up` | `03-components/08-file` |
-| `'text_and_media'`| `02-question-types/12-text-med` | (inline in Question) |
-
-Also read these shared component docs:
-- `03-client-components/09-custom-slider-track.md` (used by CSAT matrix, slider matrix when sliderType='graphics')
-- `03-client-components/13-matrix-dropdown.md` (used by matrix dropdown fmt)
-
-### PHASE 5: APPLY CRITICAL RULES
-Read ALL files in `04-critical-rules/`:
-1. `01-import-rules.md`       — Package imports, 'use client', Suspense
-2. `02-action-dispatching.md` — onAction pattern, placeholder constants
-3. `03-scroll-navigation.md`  — id={question.id} requirement
-4. `04-logo-branding.md`      — CSS-only logo, no external image needed
-5. `05-troubleshooting.md`    — Common build errors and fixes
-
-Verify your implementation against every rule before proceeding.
-
-### PHASE 6: BUILD VERIFICATION
-1. Run: `npm run build`
-2. If errors → fix automatically → re-run until clean
-3. Run: `npm run dev`
-4. Verify: survey loads, navigation works, validation fires, submit works
-
-### PHASE 7: DEPLOYMENT (INPUT 3)
-Ask the client: "Your survey is built and verified. Ready to deploy to Vercel?"
-If yes → run: `npx vercel --prod --yes`
-Report the final deployment URL to the client.
+**Import rule:** Use whatever package name appears in the project's `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
+
+---
+
+## Client Inputs (3 only)
+
+1. **Initial prompt** — mockup, brand colors, layout preferences
+2. **Instance ID** — JWT token (agent asks in chat)
+3. **Deploy confirmation** — yes/no for production deploy
+
+**Branding comes from INPUT 1 only.** No setup wizard. No `survey-config.json`.
+
+---
+
+## Execution Pipeline
+
+### PHASE 0: ORIENT
+
+- Read this file and `AGENT.md`
+- Detect framework: read `package.json` — Next.js / Vite / CRA (see `00-integration/setup.md`)
+- Extract branding and layout from client prompt
+- For existing apps: read project structure; do not blindly scaffold
+
+### PHASE 1: SCAFFOLD
+
+Read: `00-integration/setup.md` (matching framework section)
+
+Install SDK + `@tanstack/react-query` + `react-icons`. Apply framework-specific config.
+
+### PHASE 2: INSTANCE ID (INPUT 2)
+
+Read: `00-integration/useSurveySDK.md`
+
+Ask: *"Please provide your survey instance ID (JWT token)."*
+
+### PHASE 3: SDK CONTRACT
+
+Read: `00-integration/useSurveySDK.md`
+
+Understand `useSurveySDK`, `onAction`, states. Do **not** read internal mapper/source paths.
+
+Optional: read `02-reference/routing-table.md` for type overview.
+
+### PHASE 4: PLAN + INGEST (CRITICAL)
+
+1. Read **every** file in `01-components/` (all 14 blueprints)
+2. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md`
+3. Fill every section — do **not** invent a different structure
+4. **Auto-proceed to Phase 5** — do not wait for approval
+
+For each question type in the fetched survey, also read matching docs from `02-reference/question-types/` (see `MANIFEST.json` or `02-reference/routing-table.md`).
+
+### PHASE 5: BUILD
+
+Read: `00-integration/constraints.md`
+
+For each question in `state.currentQuestions`:
+
+1. Read `02-reference/question-types/{type}.md` for data shape
+2. Read `03-ui-specs/{NN}-{type}.md` (use `MANIFEST.json` `uiSpecs`; split matrix by `subType`)
+3. If `matrixFormat`, `buttonType`, or `sliderType` is present → read `03-ui-specs/shared/` specs
+4. Cross-check `02-reference/config-field-index.md` for every non-default field
+5. Match reference client behavior in `apps/client/src/components/` when available
+
+Implement components per blueprints + UI specs. Use exported types:
+
+```typescript
+import { useSurveySDK, ACTIONS, type SurveyAction } from '@explorer02/cfm-survey-sdk';
+```
+
+### PHASE 6: VERIFY
+
+Read: `00-integration/constraints.md` (troubleshooting)
+
+Checklist:
+
+- [ ] `Question.tsx` switch covers all 12 `question.type` values
+- [ ] Every question wrapper has `id={question.id}`
+- [ ] No imports from `@explorer02/cfm-survey-sdk/src/...`
+- [ ] `SurveyPage` handles loading / error / empty / submitted / active
+- [ ] `npm run build` exits 0
+
+### PHASE 7: DEPLOY (INPUT 3)
+
+Ask: *"Your survey is built and verified. Ready to deploy?"*
+
+If yes: `npx cfm-sdk deploy` (preferred) or `npx vercel --prod --yes`
+
+---
+
+## Progressive Reading Guide
+
+| When | Read |
+|------|------|
+| Always first | `index.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
+| Before any React code | All `01-components/*.md` |
+| On demand | `02-reference/question-types/<type>.md` for types in survey |
+| Before building each question | `03-ui-specs/` per `MANIFEST.uiSpecs` |
+| Config audit | `02-reference/config-field-index.md` |
+| Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |