@explorer02/cfm-survey-sdk 0.1.8 → 0.1.9

package/templates/docs/02-question-types/01-rating.md

@@ -21,14 +21,6 @@ type RatingQuestion = QuestionBase & {
 ## Answer Shape: `number`
 Example: `7` (the selected badge value)
 
-## Options Auto-Generation
-If the API provides no explicit options, the SDK generates 0-10:
-```typescript
-Array.from({ length: 11 }, (_, i) => ({
-  id: String(i), label: String(i), value: i, color: getColor(i)
-}));
-```
-
 ## NPS Traffic-Light Colors
 ```
 0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)

package/templates/docs/02-reference/question-types/01-rating.md

@@ -0,0 +1,52 @@
+# Rating Question (NPS 0-10)
+
+> **Type**: `'rating'` | **API Source**: `SCALE` with `SCALE_TYPE=TEN_POINT` or `NPS_SCALE`
+> **Mapper**: `ratingMapper.ts` | **Component**: `RatingScale`
+
+## TypeScript Type
+
+```typescript
+type RatingQuestion = QuestionBase & {
+  type: 'rating';
+  options: SurveyOption[];       // 0-10 with NPS traffic-light colors
+  minLabel?: string;             // Left label (e.g. "Not Likely")
+  midLabel?: string;             // Middle label (e.g. "Neutral")
+  maxLabel?: string;             // Right label (e.g. "Extremely Likely")
+  midLabelIndex?: number;        // Fractional position for mid-label CSS
+  reverseScaleOrder?: boolean;   // Render high→low
+  buttonVariant?: 'radio' | 'numbered' | 'emoji';
+};
+```
+
+## Answer Shape: `number`
+Example: `7` (the selected badge value)
+
+## Options Auto-Generation
+If the API provides no explicit options, the SDK generates 0-10:
+```typescript
+Array.from({ length: 11 }, (_, i) => ({
+  id: String(i), label: String(i), value: i, color: getColor(i)
+}));
+```
+
+## NPS Traffic-Light Colors
+```
+0: #e2001a (red)     3: #f18b00 (orange)   6: #fcd900 (yellow)
+1: #e4251b           4: #f7b200            7: #9fca00 (lime)
+2: #ec610a           5: #fcd900            8: #6bb300 (green)
+                                            9: #339a00
+                                            10: #008000
+```
+
+## Mid-Label Positioning
+```typescript
+// CSS left percentage for mid-label
+const left = (midLabelIndex / (options.length - 1)) * 100;
+// For 11-point scale: midLabelIndex defaults to 7.5
+```
+
+## Rendering Guidance
+- Display as horizontal row of numbered badge buttons
+- Each badge uses `option.color` as background
+- Selected badge: emphasized border/scale, all others dimmed
+- Labels positioned: minLabel (left), midLabel (calculated %), maxLabel (right)

package/templates/docs/02-reference/question-types/README.md

@@ -0,0 +1,71 @@
+# Question Types Reference
+
+> Read **on demand** — only for types present in the fetched survey.
+> UI implementation: `01-components/`. Routing table: `02-reference/routing-table.md`.
+
+## Discriminated Union
+
+```typescript
+type SurveyQuestion =
+  | RatingQuestion        // 'rating'
+  | RadioQuestion         // 'radio'
+  | TextQuestion          // 'text'
+  | CsatQuestion          // 'csat'
+  | RatingScaleQuestion   // 'rating_scale'
+  | SliderQuestion        // 'slider'
+  | MatrixQuestion        // 'matrix' (check subType)
+  | RatingMatrixQuestion  // 'rating_matrix'
+  | SliderMatrixQuestion  // 'slider_matrix'
+  | FileUploadQuestion    // 'file_upload'
+  | TextAndMediaQuestion; // 'text_and_media'
+```
+
+## Shared `QuestionBase` Properties
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `id` | `string` | **MUST** be DOM `id` on wrapper |
+| `text` | `string` | HTML — use `dangerouslySetInnerHTML` |
+| `description` | `string?` | HTML |
+| `required` | `boolean?` | |
+| `requiredErrorMessage` | `string?` | Custom validation message |
+| `questionNumber` | `number?` | 1-indexed |
+
+---
+
+## radio {#radio}
+
+- **Type:** `RadioQuestion` — `type: 'radio'`
+- **Answer:** `string | number` (option id or value)
+- **UI:** Inline MCQ radio cards in `Question.tsx` — see `01-components/02-question.md`
+- **No separate reference doc needed**
+
+## text {#text}
+
+- **Type:** `TextQuestion` — `type: 'text'`
+- **Answer:** `string`
+- **UI:** Inline `<textarea>` or `<input>` in `Question.tsx`
+- **No separate reference doc needed**
+
+## text_and_media {#text_and_media}
+
+- **Type:** `TextAndMediaQuestion` — `type: 'text_and_media'`
+- **Answer:** none — display-only, skipped in validation and submission
+- **UI:** Inline `<video>` or `<img>` from `question.mediaUrl` — no scale component
+- **No separate reference doc needed**
+
+---
+
+## Detailed Reference Docs
+
+| File | Type | When to read |
+|------|------|--------------|
+| `01-rating.md` | `rating` | NPS / numeric scales |
+| `04-csat.md` | `csat` | CSAT emoji/star (≤5 options) |
+| `05-rating-scale.md` | `rating_scale` | Star/emoji rating |
+| `06-slider.md` | `slider` | Single range slider |
+| `07-matrix-cfm.md` | `matrix` + `CFM_MATRIX` | Likert text grid |
+| `08-matrix-csat.md` | `matrix` + CSAT/RATING | Satisfaction grid |
+| `09-matrix-rating.md` | `rating_matrix` | NPS-style grid |
+| `10-slider-matrix.md` | `slider_matrix` | Slider grid |
+| `11-file-upload.md` | `file_upload` | File attachments |

package/templates/docs/02-reference/routing-table.md

@@ -0,0 +1,37 @@
+# Question Type → Component Routing
+
+> Canonical mapping. For UI implementation details, read `01-components/`. For data shapes, read `02-reference/question-types/`.
+
+| `question.type` | `question.subType` | Component | Answer Shape | Reference Doc |
+|-----------------|-------------------|-----------|--------------|---------------|
+| `'rating'` | — | `RatingScale` | `number` | `question-types/01-rating.md` |
+| `'radio'` | — | Inline in `Question` | `string \| number` | `question-types/README.md#radio` |
+| `'text'` | — | Inline in `Question` | `string` | `question-types/README.md#text` |
+| `'csat'` | — | `CsatScale` | `number \| null` | `question-types/04-csat.md` |
+| `'rating_scale'` | — | `RatingScale` | `number` | `question-types/05-rating-scale.md` |
+| `'slider'` | — | `CustomSliderTrack` | `number` | `question-types/06-slider.md` |
+| `'matrix'` | `'CFM_MATRIX'` | `LikertMatrixScale` | `MatrixAnswerMap` | `question-types/07-matrix-cfm.md` |
+| `'matrix'` | `'CSAT_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` |
+| `'matrix'` | `'RATING_MATRIX'` | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/08-matrix-csat.md` |
+| `'rating_matrix'` | — | `CsatMatrixScale` | `MatrixAnswerMap` | `question-types/09-matrix-rating.md` |
+| `'slider_matrix'` | — | `SliderMatrixScale` | `MatrixAnswerMap` | `question-types/10-slider-matrix.md` |
+| `'file_upload'` | — | `FileUploadScale` | `UploadedFile[]` | `question-types/11-file-upload.md` |
+| `'text_and_media'` | — | Inline in `Question` | (no answer) | `question-types/README.md#text_and_media` |
+
+## Component Blueprint Docs
+
+| Component | Blueprint |
+|-----------|-----------|
+| `SurveyPage` | `01-components/01-survey-page.md` |
+| `Question` | `01-components/02-question.md` |
+| `RatingScale` | `01-components/03-rating-scale.md` |
+| `CsatScale` | `01-components/04-csat-scale.md` |
+| `CsatMatrixScale` | `01-components/05-csat-matrix-scale.md` |
+| `LikertMatrixScale` | `01-components/06-likert-matrix-scale.md` |
+| `SliderMatrixScale` | `01-components/07-slider-matrix-scale.md` |
+| `FileUploadScale` | `01-components/08-file-upload-scale.md` |
+| `CustomSliderTrack` | `01-components/09-custom-slider-track.md` |
+| `Header` / `Footer` | `01-components/10-header-footer.md` |
+| `ProgressBar` | `01-components/11-progress-bar.md` |
+| `LanguageSelector` | `01-components/12-language-selector.md` |
+| `MatrixDropdown` | `01-components/13-matrix-dropdown.md` |

package/templates/docs/MANIFEST.json

@@ -0,0 +1,129 @@
+{
+  "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"
+    }
+  }
+}

package/templates/docs/index.md

@@ -1,151 +1,109 @@
 # 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/           ← UI blueprints (read ALL before coding)
+├── 02-reference/            ← Routing table + question-type data (on demand)
+└── 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`
+
+Implement components per blueprints. 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 |
+| Tooling | `MANIFEST.json`, `templates/implementation_plan.md` |

package/templates/docs/templates/implementation_plan.md

@@ -0,0 +1,78 @@
+# Survey UI Implementation Plan
+
+> Copy this file to `./implementation_plan.md` in the project root. Fill every section before writing React code.
+
+## 0. Project Context
+
+- **Framework:** [ ] Next.js App Router  [ ] Vite  [ ] CRA  [ ] Existing app
+- **Package import name:** (from `package.json` — `@explorer02/cfm-survey-sdk` or `@repo/sdk`)
+- **instanceId:** (JWT — wired in SurveyPage)
+- **Branding source:** (client prompt / mockup description — no wizard)
+
+## 1. Data Fetching & State
+
+- [ ] `useSurveySDK` options: instanceId, language, placeholders, debug
+- [ ] `SurveyPage` 5-state machine: loading / error / empty / submitted / active
+- [ ] `surveyQueryResults.isLoading`, `.error`, `.data` handling
+- [ ] `submitSurveyResults.isLoading`, `.error`, `.data` handling
+
+## 2. Pagination, Actions & Flow
+
+- [ ] `onAction` NEXT / PREVIOUS / SUBMIT wiring
+- [ ] `ProgressBar` bound to `state.progressPercentage`
+- [ ] Back/Next button visibility per layout config
+- [ ] Last-page NEXT → auto SUBMIT behavior
+
+## 3. Question Dispatching (`Question.tsx`)
+
+Exhaustive switch — check each:
+
+- [ ] `rating` → `RatingScale`
+- [ ] `csat` → `CsatScale`
+- [ ] `radio` → inline MCQ
+- [ ] `text` → inline textarea/input
+- [ ] `rating_scale` → `RatingScale` (star/emoji)
+- [ ] `slider` → `CustomSliderTrack`
+- [ ] `matrix` + `CFM_MATRIX` → `LikertMatrixScale`
+- [ ] `matrix` + `CSAT_MATRIX` / `RATING_MATRIX` → `CsatMatrixScale`
+- [ ] `rating_matrix` → `CsatMatrixScale`
+- [ ] `slider_matrix` → `SliderMatrixScale`
+- [ ] `file_upload` → `FileUploadScale`
+- [ ] `text_and_media` → inline media (no scale)
+- [ ] `dangerouslySetInnerHTML` for `question.text` / `description`
+- [ ] `validationError` banner per question
+- [ ] `id={question.id}` on every question wrapper
+
+## 4. Component Architecture Checklist
+
+| Component | In survey? | Blueprint doc | Key constraints verified |
+|-----------|------------|---------------|--------------------------|
+| RatingScale | | `01-components/03-rating-scale.md` | |
+| CsatScale | | `01-components/04-csat-scale.md` | |
+| CsatMatrixScale | | `01-components/05-csat-matrix-scale.md` | |
+| LikertMatrixScale | | `01-components/06-likert-matrix-scale.md` | |
+| SliderMatrixScale | | `01-components/07-slider-matrix-scale.md` | |
+| FileUploadScale | | `01-components/08-file-upload-scale.md` | |
+| CustomSliderTrack | | `01-components/09-custom-slider-track.md` | |
+| Header / Footer | | `01-components/10-header-footer.md` | |
+| ProgressBar | | `01-components/11-progress-bar.md` | |
+| LanguageSelector | | `01-components/12-language-selector.md` | |
+| MatrixDropdown | | `01-components/13-matrix-dropdown.md` | |
+
+## 5. Theme, Brand & Logo
+
+- [ ] CSS-only logo (no `<img>`, no `public/` uploads)
+- [ ] Primary / hover colors from client prompt
+- [ ] Header / Footer / ProgressBar / LanguageSelector per layout
+
+## 6. Submit & Thank You
+
+- [ ] `onAction({ type: 'SUBMIT' })` on final page
+- [ ] Thank-you screen when `submitSurveyResults.data` is set
+- [ ] Custom thank-you message from client prompt if provided
+
+## 7. Pre-Build Verification
+
+- [ ] No imports from `.../src/` internal paths
+- [ ] All mutations via `onAction` — no direct state mutation
+- [ ] `npm run build` passes