@explorer02/cfm-survey-sdk 0.2.3 → 0.2.4

package/templates/docs/03-ui-specs/09-slider-matrix.md

@@ -1,78 +1,105 @@
 # UI Spec: Slider Matrix (`type: 'SLIDER_MATRIX'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/SliderMatrixScale.tsx`
+> **COPY TEMPLATE FIRST:** [`templates/SliderMatrixScale.tsx`](../templates/SliderMatrixScale.tsx) + [`CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts)
+>
+> **Anti-pattern:** Do NOT build custom range overlay sliders. Lone pink circle with no track = broken implementation.
+>
 > **SDK type:** `SliderMatrixQuestion` — `fetchSurvey/types/sliderMatrix.ts`
 > **Component blueprint:** `01-components/07-slider-matrix-scale.md`
-> **Shared:** [`shared/custom-slider-track.md`](shared/custom-slider-track.md)
 
 ## Config Inventory
 
 | Field | Implemented | UI impact |
 |-------|-------------|-----------|
-| `rows[]` (min/max/step) | ✅ | Per-row slider range |
-| `labels[]` | ✅ | Header anchor labels |
-| `tickValues[]` | ✅ | Colored badges above track |
-| `ticks` | ✅ | Discrete marks + htmlStep |
-| `sliderType: 'graphics'` | ✅ | Plain text tick labels; emoji thumb |
+| `statementRows[]` (min/max/step) | ✅ | Per-row slider + **25% statement column** |
+| `scaleAnchorLabels?` | ✅ | Text labels above tick badge row |
+| `ticks.count` + `ticks.marks[]` | ✅ | Colored header badges (`tickPosition`, `tickLabel`) |
+| `sliderStyle: 'graphics'` | ✅ | Plain text tick labels; emoji thumb |
 | `enableInputBox` | ✅ | 80px input + stepper buttons |
 | `displayValues` | ✅ | Passed to CustomSliderTrack |
-| `enableNotApplicable` | ✅ | Checkbox; value `'N/A'` string |
+| `hasNotApplicableOption` | ✅ | Checkbox; answer value **`'N/A'`** string |
 
 ## Layout Anatomy
 
 ```
-[header: labels[] + tickValues badges OR computed marks]
+[header: scaleAnchorLabels? + colored tick badges from ticks.marks]
 ┌─ row band (#f3f4f6, rounded-xl) ─────────────────────────────┐
-│ 25% statement │ CustomSliderTrack │ 25% rightText? │ input? │ N/A? │
+│ 25% statementText │ CustomSliderTrack │ 80px input? │ N/A? │
 └───────────────────────────────────────────────────────────────┘
 ```
 
-## Header Tick Positioning
+## Statement text (CRITICAL)
+
+Every row MUST show `statementRows[].statementText` in the left 25% column:
+
+```tsx
+<div style={{ flex: '0 0 25%', paddingRight: '16px' }}>
+  {row.statementText && row.statementText !== 'Question' && (
+    <span dangerouslySetInnerHTML={{ __html: row.statementText }} />
+  )}
+</div>
+```
+
+Agents that hide statement text or merge it into the question title break multi-row sliders.
+
+## Header tick badges
 
 ```typescript
-percentage = ((tv.value - min) / (max - min)) * 100
-sliceWidth = tickValues.length > 1 ? 100 / (tickValues.length - 1) : 100
-// Colored badge: tv.color bg, white text, rounded 4px
-// graphics: plain text label instead of colored badge
+tickValues = ticks.marks.map((mark, i) => ({
+  value: mark.tickPosition,
+  label: mark.tickLabel,
+  color: tickColorFromIndex(i, ticks.count),
+}));
+percentage = ((tv.value - min) / (max - min)) * 100;
+htmlStep = ticks.count > 1 ? (max - min) / (ticks.count - 1) : row.step;
 ```
 
-## CustomSliderTrack per row — scale labels
+## CustomSliderTrack per row
 
 ```typescript
 <CustomSliderTrack
   min={row.min}
   max={row.max}
-  htmlStep={row.htmlStep}
+  htmlStep={htmlStep}
   value={rowVal as number}
-  tickLabels={row.tickLabels ?? scaleColumns.map(c => c.label)}
-  ticks={row.ticks}
+  disabled={rowVal === 'N/A'}
+  hasSelectedValue={typeof rowVal === 'number'}
+  displayValues={displayValues}
   sliderType={question.sliderStyle === 'graphics' ? 'graphics' : undefined}
+  ticks={ticks.count}
   onChange={v => updateRow(row.id, v)}
 />
 ```
 
-Pass **`scaleColumns[].label`** (or row tick labels) as `tickLabels` — required for correct tooltip text (Day 19 fix).
-
 ## N/A Behavior
 
-- Checked → `rowVal === 'N/A'`; slider disabled, input grayed
+- Checked → `rowVal === 'N/A'`; slider disabled
 - Unchecked → reset to `defaultValue ?? min`
 
-## Input Box
-
-- Clamp to row.min / row.max on change
-- Steppers use `htmlStep` increment/decrement
-
 ## Answer Mutation
 
 ```typescript
-onSelect(Record<string, number | null | 'N/A'>)
+onSelect(Record<string, number | 'N/A'>)
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: MatrixRowAnswers } })
 ```
 
 ## Agent Checklist
 
-- [ ] Shared header from first row min/max/step
-- [ ] Gray row bands with 25% statement columns
+- [ ] Copied portable templates — did not build slider from scratch
+- [ ] Shared header with colored 0–10 badges (even single-row questions)
+- [ ] Gray row bands with **visible** statement text in 25% column
 - [ ] CustomSliderTrack per row with correct htmlStep
-- [ ] tickValues colored badges (non-graphics)
-- [ ] N/A mutex disables slider + input
+- [ ] N/A uses `'N/A'` string, not null
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Tick label items | `--cfm-slider-tick-label-color`, `--cfm-slider-tick-label-bg` | Header badge row — `sliderTickLabelStyle()` |
+| Row band | `--cfm-slider-row-bg` | Gray statement band |
+| Thumb selection | `--cfm-matrix-selected`, `--cfm-input-focus-ring` | `CustomSliderTrack` thumb ring + annulus + dot |
+
+### Wizard checklist
+
+- [ ] Colored tick badges use `--cfm-number-*` when traffic-light mode applies
+- [ ] `labelStyles.ts` imported for tick label row

package/templates/docs/03-ui-specs/10-file-upload.md

@@ -73,3 +73,14 @@ onAction({ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswe
 - [ ] Final answer shape: `UploadedFileAnswer[]` with `id` + `mediaUrl`
 - [ ] Remove clears answer or passes updated array
 - [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Dropzone border | `--cfm-upload-border-color` | Dashed border on upload area |
+| Focus / drag-over | `--cfm-input-focus-ring` | Active dropzone outline |
+
+### Wizard checklist
+
+- [ ] Dropzone border uses `var(--cfm-upload-border-color)` not hardcoded hex

package/templates/docs/03-ui-specs/11-text-and-media.md

@@ -47,3 +47,7 @@ Container-level media (survey chrome) is separate — see `03-ui-specs/12-survey
 
 - [ ] No CHANGE action — display-only
 - [ ] Matrix row: [`question-type-sdk-matrix.md#text_and_media`](../00-integration/question-type-sdk-matrix.md#text_and_media)
+
+## Wizard customization (Phase 5 — required)
+
+Display-only — no selection tokens. Media caption may use `--cfm-question-title-color` for consistency.

package/templates/docs/03-ui-specs/12-survey-chrome.md

@@ -1,7 +1,7 @@
 # UI Spec: Survey Chrome
 
-> **Reference:** `SurveyPage.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`, `IntroPage.tsx`, `EndPage.tsx`, `PausedPage.tsx`
-> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `12-language-selector.md`, `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`
+> **Reference:** `SurveyPage.tsx`, `SurveyStickyChrome.tsx`, `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `LanguageSelector.tsx`, `IntroPage.tsx`, `EndPage.tsx`, `PausedPage.tsx`
+> **Component blueprints:** `01-components/01-survey-page.md`, `10-header-footer.md`, `11-progress-bar.md`, `19-survey-sticky-chrome.md`, `12-language-selector.md`, `14-intro-page.md`, `15-end-page.md`, `16-paused-page.md`
 
 ## SurveyPage — Phase Router
 
@@ -21,9 +21,8 @@
 ## Active Layout
 
 ```
-Header
+SurveyStickyChrome (sticky top-0 — Header + ProgressBar)
 main (max-w-4xl)
-  ProgressBar(progressPercentage)
   LanguageSelector (hidden if ≤1 language)
   Questions (space-y-12)
   Submit error (if any)
@@ -31,6 +30,25 @@ main (max-w-4xl)
 Footer
 ```
 
+### Sticky chrome (required on content phase)
+
+Long pages push the last question below the fold. Wrap **Header + ProgressBar** in one sticky container so progress stays visible while answering.
+
+```tsx
+<div className="sticky top-0 z-30 bg-white shadow-[0_2px_8px_rgba(0,0,0,0.06)]">
+  <Header embedded />
+  <div className="mx-auto w-full max-w-4xl px-4 pb-5 pt-4 sm:px-6 lg:px-8">
+    <ProgressBar progressPercentage={state.progressPercentage} />
+  </div>
+</div>
+```
+
+**Spacing:** `pt-4` (16px) between logo block and progress track; `pb-5` (20px) below the track before scrollable content. Do not flush the bar against the logo square.
+
+See [`01-components/19-survey-sticky-chrome.md`](../01-components/19-survey-sticky-chrome.md). Copy [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx).
+
+Use standalone `Header` (no sticky wrapper) on intro, end, paused, loading, and terminal phases.
+
 ## Navigation Labels
 
 German when `survey.language.startsWith('de')`:
@@ -51,6 +69,14 @@ German when `survey.language.startsWith('de')`:
 
 Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-integration/progress.md`).
 
+Render inside **`SurveyStickyChrome`** (sticky header + progress) on the content phase — not inside scrollable `<main>`. Clamp width to `0–100`.
+
+| Token | Value | Role |
+|-------|-------|------|
+| Gap above track | `pt-4` (16px) | Space between logo block and progress bar |
+| Gap below track | `pb-5` (20px) | Breathing room before question content |
+| Track height | `h-3` (12px) | Full-width rounded pill |
+
 ## LanguageSelector
 
 - Hidden when `languages.length <= 1`
@@ -97,8 +123,31 @@ Disable primary Next/Submit when `submitSurveyResults.isLoading`; label "Submitt
 - [ ] `onAction({ type: 'START' })` on intro
 - [ ] `onAction({ type: 'CHANGE' })` wired per question with `allAnswers` / `allQuestions`
 - [ ] Back uses `state.canGoBack`; primary uses `state.primaryButtonType`
-- [ ] ProgressBar receives `state.progressPercentage`
+- [ ] ProgressBar receives `state.progressPercentage` inside sticky chrome (`SurveyStickyChrome`)
+- [ ] Sticky `top-0 z-30` wrapper keeps progress visible on long pages
+- [ ] `pt-4` / `pb-5` spacing between logo, progress track, and question content
 - [ ] Header/Footer on every state branch
 - [ ] `questionNumber` prefix when present on content questions
 - [ ] Intro / Paused / End / terminal phase branches
 - [ ] Submit button disabled while `submitSurveyResults.isLoading`
+
+## Wizard customization (Phase 5 — required)
+
+> Full chrome contract: [`wizard-preview-build-guide.md`](../00-integration/wizard-preview-build-guide.md).
+
+| Element | `data-cfm-*` / CSS vars |
+|---------|-------------------------|
+| Logo | `data-cfm-logo` or `data-cfm-logo-text` |
+| Company | `data-cfm-company` |
+| Survey title | `data-cfm-survey-title` |
+| Thank you | `data-cfm-thank-you` |
+| Next / Back | `data-cfm-btn-next`, `data-cfm-btn-back` |
+| Footer | `data-cfm-copyright`, `data-cfm-footer-links` |
+| Progress | `--cfm-progress-track`, `--cfm-progress-fill` |
+| Header bg | `--cfm-header-bg`, `--cfm-header-text` |
+
+### Wizard checklist
+
+- [ ] All editable chrome strings use `data-cfm-*` attributes
+- [ ] Buttons and progress use `var(--cfm-*)` — not hardcoded Telekom hex
+- [ ] Logo: text/CSS **or** local `public/` image — never external URL (see `constraints.md` §4)

package/templates/docs/03-ui-specs/13-heatmap.md

@@ -1,6 +1,6 @@
 # UI Spec: Heatmap (`type: 'HEATMAP'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/HeatmapScale.tsx`
+> **Implement from this spec.** Portable template: `docs/templates/HeatmapScale.tsx`
 > **SDK type:** `HeatmapQuestion` — `fetchSurvey/types/heatmap.ts`
 > **Component blueprint:** `01-components/17-heatmap-scale.md`
 
@@ -78,3 +78,14 @@ Copy coord helpers from [`templates/heatmapCoords.ts`](../templates/heatmapCoord
 - [ ] Wait for `onLoad` before accepting clicks
 - [ ] Percentage-positioned spots (survives resize)
 - [ ] Do NOT render region overlays on respondent UI
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Spot color | `--cfm-heatmap-spot-color` | Click markers |
+| Spot border | `--cfm-heatmap-spot-border` | Marker outline |
+
+### Wizard checklist
+
+- [ ] Spot markers use `--cfm-heatmap-spot-*` vars

package/templates/docs/03-ui-specs/14-rank-order.md

@@ -126,3 +126,14 @@ RANK_ORDER operators (ranked as/above/below) — see [`logic-fields-catalog.md`]
 - [ ] `option.imageUrl` before `previewImageUrl`
 - [ ] No client-side re-shuffle when `shuffleOptions` is true
 - [ ] No stub placeholder text
+
+## Wizard customization (Phase 5 — required)
+
+| Control | CSS vars | Apply in |
+|---------|----------|----------|
+| Rank badge | `--cfm-rank-badge-bg`, `--cfm-rank-badge-color` | Drag handle / rank number |
+| Option border | `--cfm-rank-option-border` | List item cards |
+
+### Wizard checklist
+
+- [ ] Rank badges and option borders use `--cfm-rank-*` vars

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

@@ -1,9 +1,11 @@
 # UI Specifications — Reference Implementation Guide
 
 > **For npm installs:** implement from these specs + [`templates/Question.tsx`](../templates/Question.tsx).
-> **For monorepo devs:** Reference client at `apps/client/src/components/` aligns with SDK types — trust `03-ui-specs/`, `templates/Question.tsx`, and exported types.
+> **Shared lib utilities** (NPS colors, custom fields, heatmap coords) live in [`templates/`](../templates/) — see [`client-lib-folder.md`](../00-integration/client-lib-folder.md), not in this ui-specs folder.
 > Read the spec for **each question type present** in the fetched survey before writing React code.
 
+> **Wizard customization:** When the client may use the web wizard, hardcoded hex in § Design Tokens below are **defaults only**. Wire `var(--cfm-*)` per [`wizard-question-type-styling.md`](../00-integration/wizard-question-type-styling.md) — especially `--cfm-matrix-selected` (cell annulus) and `--cfm-input-focus-ring` (outer border + inner dot). Portable scale templates in `docs/templates/` are layout/logic baselines; extend with `selectionStyles.ts` + `labelStyles.ts` for live preview.
+
 ## How to Read a UI Spec
 
 Each file in this folder follows the same structure:
@@ -75,7 +77,7 @@ Use accent colors from SDK options — never invent colors for NPS:
 
 ## When to Read
 
-After Phase 3 in [`index.md`](../index.md), for each question in the fetched survey:
+After Phase 3 in [`index.md`](../index.md) and [`agent-execution-flow.md`](../00-integration/agent-execution-flow.md), for each question in the fetched survey:
 
 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) `questionTypes.{type}.uiSpec`)

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

@@ -1,6 +1,6 @@
 # UI Spec: Matrix Dropdown (shared primitive)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/MatrixDropdown.tsx`
+> **Implement from this spec.** Portable template: `docs/templates/MatrixDropdown.tsx`
 > **Used by:** `LikertMatrixScale`, `CsatMatrixScale` vertical list
 
 ## Modes

package/templates/docs/MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "docsSchemaVersion": "2.4.0",
+  "docsSchemaVersion": "2.6.0",
   "sdkTypesVersion": "0.2.1",
   "packageNames": {
     "npm": "@explorer02/cfm-survey-sdk",
@@ -13,8 +13,28 @@
   "clientInputs": [
     "initialPrompt",
     "instanceIdJwt",
+    "customizationWizardOptional",
     "deployConfirmation"
   ],
+  "surveyUiConfig": {
+    "artifact": "survey-ui-config.json",
+    "schema": "templates/survey-ui-config.schema.json",
+    "cliCommand": "npx cfm-sdk customize-ui",
+    "cliCommands": {
+      "aws": "npx cfm-sdk customize-ui",
+      "local": "npx cfm-sdk customize",
+      "exportPreviews": "npx cfm-sdk export-previews"
+    },
+    "wizardApiDoc": "00-integration/wizard-api.md",
+    "applyDoc": "00-integration/apply-ui-config.md",
+    "wizardDoc": "00-integration/ui-customization-wizard.md",
+    "previewBuildDoc": "00-integration/wizard-preview-build-guide.md",
+    "questionTypeStylingDoc": "00-integration/wizard-question-type-styling.md",
+    "agentExecutionFlowDoc": "00-integration/agent-execution-flow.md",
+    "agentOperatingContractDoc": "00-integration/agent-operating-contract.md",
+    "wizardConfigHandoffDoc": "00-integration/wizard-config-handoff.md",
+    "previewBridgeTemplate": "templates/previewBridge.ts"
+  },
   "hookContract": {
     "answersField": "state.answers",
     "customFieldValuesField": "options.customFieldValues",
@@ -44,6 +64,14 @@
     ]
   },
   "integrationDocs": [
+    {
+      "path": "00-integration/agent-operating-contract.md",
+      "purpose": "Anti-hallucination rules — read-before-write gates, doc routing, forbidden inventions (read FIRST)"
+    },
+    {
+      "path": "00-integration/agent-execution-flow.md",
+      "purpose": "Authoritative agent pipeline — client questions, phase order, wizard-ready build (read with index.md)"
+    },
     {
       "path": "00-integration/client-integration-guide.md",
       "purpose": "Master wiring map — start here for full client integration"
@@ -119,6 +147,38 @@
     {
       "path": "00-integration/file-upload-aws.md",
       "purpose": "Presigned S3 upload flow for FILE_UPLOAD submit contract"
+    },
+    {
+      "path": "00-integration/canonical-survey-fixtures.md",
+      "purpose": "Page-by-page UI expectations — matrix labels, slider header, template copy list"
+    },
+    {
+      "path": "00-integration/client-lib-folder.md",
+      "purpose": "src/lib layout — customFieldValues + surveyUi portable templates"
+    },
+    {
+      "path": "00-integration/wizard-preview-build-guide.md",
+      "purpose": "Build client components for wizard live preview — --cfm-* vars and data-cfm-* hooks (Phase 5)"
+    },
+    {
+      "path": "00-integration/wizard-question-type-styling.md",
+      "purpose": "Per-type wizard styling — selection colors, label items, all 11 question types (Phase 5)"
+    },
+    {
+      "path": "00-integration/wizard-config-handoff.md",
+      "purpose": "Wait for client submit, review artifacts (.final.json, .diff.md), confirm-ui-config order (Phase 6b→6c)"
+    },
+    {
+      "path": "00-integration/ui-customization-wizard.md",
+      "purpose": "Optional web wizard flow, CLI commands, wizard steps"
+    },
+    {
+      "path": "00-integration/apply-ui-config.md",
+      "purpose": "Apply survey-ui-config.json tokens after wizard (Phase 6c)"
+    },
+    {
+      "path": "00-integration/wizard-api.md",
+      "purpose": "EC2 /wizard/* API for customize-ui and preview hosting"
     }
   ],
   "templateScaleFiles": [
@@ -126,7 +186,15 @@
     "templates/MatrixDropdown.tsx",
     "templates/CustomSliderTrack.tsx",
     "templates/surveyUiIcons.tsx",
-    "templates/heatmapCoords.ts"
+    "templates/surveyUiScaleUtils.ts",
+    "templates/SliderMatrixScale.tsx",
+    "templates/RatingScale.tsx",
+    "templates/LikertMatrixScale.tsx",
+    "templates/CsatMatrixScale.tsx",
+    "templates/HeatmapScale.tsx",
+    "templates/FileUploadScale.tsx",
+    "templates/heatmapCoords.ts",
+    "templates/customFieldValues.ts"
   ],
   "deployTargets": {
     "aws": {
@@ -134,6 +202,8 @@
       "script": "templates/deploy-to-aws.sh",
       "apiBaseEnv": "CFM_DEPLOY_API_BASE",
       "apiBaseDefault": "http://43.204.26.213:3000",
+      "wizardClientUrlPattern": "{CFM_DEPLOY_API_BASE}/wizard-app/index.html?session={sessionId}&secret={sessionSecret}",
+      "wizardClientUrlNote": "Printed by customize-ui after component previews upload to S3 — agent copies link and sends to client",
       "instanceIdEnv": "CFM_INSTANCE_ID",
       "outDirEnv": "OUT_DIR",
       "healthPath": "/health",
@@ -190,7 +260,10 @@
       "name": "orient",
       "read": [
         "index.md",
-        "../AGENT.md"
+        "../AGENT.md",
+        "00-integration/agent-operating-contract.md",
+        "00-integration/agent-execution-flow.md",
+        "MANIFEST.json"
       ],
       "actions": [
         "detectFramework",
@@ -229,6 +302,7 @@
         "00-integration/display-logic-and-navigation.md",
         "00-integration/answer-logic-and-navigation.md",
         "00-integration/custom-field-logic-and-navigation.md",
+        "00-integration/client-lib-folder.md",
         "00-integration/question-display-variants.md",
         "00-integration/question-numbering.md",
         "00-integration/placeholders-and-tokens.md",
@@ -244,7 +318,12 @@
       "id": 4,
       "name": "planAndIngest",
       "readAlways": [
+        "00-integration/agent-operating-contract.md",
+        "00-integration/agent-execution-flow.md",
         "00-integration/component-checklist.md",
+        "00-integration/canonical-survey-fixtures.md",
+        "00-integration/client-lib-folder.md",
+        "00-integration/custom-field-logic-and-navigation.md",
         "00-integration/question-type-sdk-matrix.md",
         "00-integration/logic-fields-catalog.md",
         "03-ui-specs/00-question-shell.md",
@@ -266,7 +345,12 @@
       "id": 5,
       "name": "build",
       "read": [
+        "00-integration/agent-operating-contract.md",
+        "00-integration/agent-execution-flow.md",
         "00-integration/constraints.md",
+        "00-integration/component-checklist.md",
+        "00-integration/wizard-preview-build-guide.md",
+        "00-integration/wizard-question-type-styling.md",
         "02-reference/routing-table.md"
       ],
       "onDemand": "02-reference/question-types"
@@ -275,7 +359,10 @@
       "id": 6,
       "name": "verify",
       "read": [
-        "00-integration/constraints.md"
+        "00-integration/agent-operating-contract.md",
+        "00-integration/agent-execution-flow.md",
+        "00-integration/constraints.md",
+        "00-integration/component-checklist.md"
       ],
       "script": "templates/verify-agent-build.sh",
       "checklist": [
@@ -295,8 +382,76 @@
         "outIndexHtmlExists",
         "outFileCountUnder500",
         "rankOrderScaleTemplateCopied",
+        "sliderMatrixScaleTemplateCopied",
+        "ratingScaleTemplateCopied",
+        "matrixScaleTemplatesCopied",
+        "heatmapScaleTemplateCopied",
         "dndKitWhenRankOrder",
-        "fileUploadPresignedFlowWhenFileUpload"
+        "fileUploadPresignedFlowWhenFileUpload",
+        "surveyThemeCssPresent",
+        "selectionStylesCopied",
+        "labelStylesCopied",
+        "chromeDataCfmHooksPresent",
+        "draftSurveyUiConfigPresent"
+      ],
+      "postVerify": [
+        "startDevServer",
+        "askCustomizationWizard"
+      ]
+    },
+    {
+      "id": "6b",
+      "name": "optionalUiCustomization",
+      "optional": true,
+      "requiresClientConfirmation": true,
+      "read": [
+        "00-integration/wizard-config-handoff.md",
+        "00-integration/ui-customization-wizard.md",
+        "00-integration/wizard-preview-build-guide.md",
+        "00-integration/wizard-question-type-styling.md",
+        "00-integration/wizard-api.md"
+      ],
+      "cliCommand": "npx cfm-sdk customize-ui",
+      "cliCommandLocal": "npx cfm-sdk customize",
+      "cliConfirmCommand": "npx cfm-sdk confirm-ui-config",
+      "output": "survey-ui-config.final.json",
+      "outputArtifacts": [
+        "survey-ui-config.seed.json",
+        "survey-ui-config.final.json",
+        "survey-ui-config.diff.json",
+        "survey-ui-config.diff.md"
+      ],
+      "agentMustWait": true,
+      "waitUntil": "cliExit0ConfigurationReady",
+      "clientHandoff": "shareDeployedWizardUrlAfterS3Upload",
+      "prerequisites": [
+        "phase6VerifyPassed",
+        "devServerRunning"
+      ]
+    },
+    {
+      "id": "6c",
+      "name": "applyUiConfig",
+      "optional": true,
+      "when": "wizardUsedOrSurveyUiConfigExists",
+      "read": [
+        "00-integration/wizard-config-handoff.md",
+        "00-integration/apply-ui-config.md",
+        "00-integration/wizard-preview-build-guide.md",
+        "00-integration/wizard-question-type-styling.md"
+      ],
+      "inputFile": "survey-ui-config.final.json",
+      "inputFileLocal": "survey-ui-config.json",
+      "actions": [
+        "readDiffMdCompletely",
+        "validateAgainstSchema",
+        "regenerateSurveyThemeCssFromFinal",
+        "applyDataCfmContentHooks",
+        "applyLayoutToggles",
+        "applyQuestionTypesTokens",
+        "runConfirmUiConfigAws",
+        "crossCheckEveryDiffPath",
+        "reRunVerify"
       ]
     },
     {
@@ -305,7 +460,8 @@
       "requiresClientConfirmation": true,
       "selectTargetFromPrompt": {
         "awsKeywords": ["aws", "cloudfront", "s3", "ec2", "sprinklr"],
-        "default": "vercel"
+        "default": "vercel",
+        "fallbackFromConfig": "survey-ui-config.json deploy.target"
       },
       "targets": {
         "aws": {