@explorer02/cfm-survey-sdk 0.2.6 → 0.2.8

package/templates/docs/00-integration/wizard-config-handoff.md

@@ -1,6 +1,7 @@
 # Wizard Config Handoff — Wait, Capture, Apply
 
 > **Phase 6b → 6c.** Read with [`ui-customization-wizard.md`](ui-customization-wizard.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> **Phase 6c runbook (all formats + build):** [`wizard-post-customize-build.md`](wizard-post-customize-build.md).  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 This doc tells the agent **exactly** how to wait for the client to finish the wizard, capture the JSON output, and apply **every** change without omission.
@@ -53,7 +54,9 @@ When the client uploads a logo in the local wizard:
 
 The logo is **not** fetched from wizard memory on CloudFront — only from the deploy bundle. See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
 
-**Local quit (preview GC):** If the client exits without saving, wizard calls `POST /api/wizard-quit` → CLI deletes `out/previews/` on agent disk. Ctrl+C on customize CLI runs the same cleanup.
+**Local quit (preview GC):** If the client exits without saving, wizard calls `POST /api/wizard-quit` → CLI deletes `out/previews/`.
+
+**After save:** `POST /api/save-config` also deletes `out/previews/` before CLI exits (preview garbage collection).
 
 ---
 
@@ -141,7 +144,7 @@ For **every** section in the diff (`Changed`, `Added`, `Removed`):
 
 ### Step 4 — Apply to codebase (Phase 6c)
 
-Follow [`apply-ui-config.md`](apply-ui-config.md) using **`survey-ui-config.final.json`** as input.
+Follow [`wizard-post-customize-build.md`](wizard-post-customize-build.md) (ordered checklist + format matrix), then [`apply-ui-config.md`](apply-ui-config.md) path tables using **`survey-ui-config.final.json`** (EC2) or **`survey-ui-config.json`** (local) as input.
 
 Order:
 
@@ -288,6 +291,7 @@ npx cfm-sdk fetch-ui-config
 
 | Doc | Role |
 |-----|------|
+| [`wizard-post-customize-build.md`](wizard-post-customize-build.md) | Phase 6c runbook — all question formats + verify/build |
 | [`apply-ui-config.md`](apply-ui-config.md) | Complete config path → file mapping |
 | [`wizard-api.md`](wizard-api.md) | Poll endpoint, complete payload |
 | [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Per-type CSS vars |

package/templates/docs/00-integration/wizard-post-customize-build.md

@@ -0,0 +1,405 @@
+# Wizard Post-Customize Build — All Types, All Formats
+
+> **Phase 6c runbook.** Read after the client clicks **Review & Build** and the CLI prints `✅ UI configuration saved`.  
+> Companion docs: [`wizard-config-handoff.md`](wizard-config-handoff.md) · [`apply-ui-config.md`](apply-ui-config.md) · [`wizard-question-type-styling.md`](wizard-question-type-styling.md) · [`wizard-chrome-contract.md`](wizard-chrome-contract.md)
+
+This doc answers two agent questions:
+
+1. **What does the wizard expose** for every question type and format — and which component must honor it?
+2. **What is the exact build sequence** after the client confirms customization — without re-running the wizard or skipping tokens?
+
+---
+
+## End-to-end flow (confirmation → deploy)
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Wizard as Wizard SPA
+  participant CLI as cfm-sdk customize
+  participant Agent
+  participant Build as npm run build
+  participant Deploy as Phase 7
+
+  Client->>Wizard: Review and Build
+  Wizard->>CLI: POST /api/save-config
+  CLI->>CLI: Write survey-ui-config.json
+  CLI->>CLI: Delete out/previews/ (GC)
+  CLI->>Agent: Exit 0 — UI configuration saved
+  Agent->>Agent: Phase 6c apply (this doc)
+  Agent->>Build: verify-agent-build.sh
+  Build->>Agent: out/ + logo in out/
+  Agent->>Deploy: After INPUT 4 confirm
+```
+
+**Agent must not** start Phase 6c until CLI exit 0. **Agent must not** proceed to Phase 7 until verify + build pass after apply.
+
+---
+
+## Phase 6c — ordered runbook (copy-paste checklist)
+
+Run from project root after `✅ UI configuration saved`.
+
+### A. Capture
+
+```bash
+# Local wizard (default)
+test -f survey-ui-config.json && echo "OK: config captured"
+
+# EC2 review mode only — also read diff before editing code
+test -f survey-ui-config.final.json && cat survey-ui-config.diff.md
+```
+
+### B. Validate
+
+- [ ] JSON parses; validate against `templates/survey-ui-config.schema.json`
+- [ ] `surveyTypes[]` still matches fetched survey inventory (types in survey, not wizard tabs)
+- [ ] EC2: every path in `survey-ui-config.diff.json` (`changed` + `added` + `removed`) has a planned apply target
+
+### C. Regenerate theme (full — never partial)
+
+- [ ] Regenerate **entire** `src/styles/survey-theme.css` from final config (all `global.*` + all `questionTypes.*`)
+- [ ] Confirm `@import` in `globals.css` (or equivalent)
+- [ ] Theme → Question card tokens present: `--cfm-matrix-selected`, `--cfm-input-focus-ring`
+
+### D. Chrome + content hooks
+
+Copy/sync if missing — see [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
+| Area | Config paths | Wire in |
+|------|--------------|---------|
+| Logo | `global.logo.fileName` | `Header.tsx` via `uiConfig.getLogoSrc()` → `src="./{fileName}"` |
+| Company | `global.companyName`, `global.header.showCompanyName` | `data-cfm-company` in brand row after logo |
+| Title / thank you | `global.surveyTitle`, `global.thankYouMessage` | `data-cfm-survey-title`, `data-cfm-thank-you` |
+| Buttons | `global.buttons.*` | `data-cfm-btn-next`, `data-cfm-btn-back` |
+| Footer | `global.footer.*` | `cfm-footer`, `data-cfm-copyright`, `data-cfm-footer-links` |
+| Layout | `global.layout.*` | `SurveyPage` / `SurveyStickyChrome` conditionals |
+| Progress | `global.theme.progress*` | `data-cfm-progress` + `.cfm-progress` (separate from header) |
+
+**Logo rule:** never hand-edit `fileName` to a seed SVG. Use wizard value; file must exist in `public/{fileName}`.
+
+```bash
+LOGO=$(python3 -c "import json; print(json.load(open('survey-ui-config.json')).get('global',{}).get('logo',{}).get('fileName') or '')")
+test -z "$LOGO" || test -f "public/$LOGO" || echo "FAIL: logo file missing in public/"
+```
+
+### E. Per-type tokens (all wizard types — not only survey inventory)
+
+The wizard **Question Types** step exposes **10 type families** (TEXT_AND_MEDIA uses theme vars only). Apply `questionTypes.{TYPE}` for **every** type block in saved JSON — even if the client's survey does not include that type. This keeps `survey-theme.css` complete and future-proof.
+
+Use the format matrix below. Detailed token tables: [`wizard-question-type-styling.md`](wizard-question-type-styling.md) and [`apply-ui-config.md`](apply-ui-config.md).
+
+### F. Hook options
+
+- [ ] `placeholders.*` → `useSurveySDK({ options: { placeholders } })` (stable ref)
+- [ ] `customFields` → `customFieldValues.ts` + SurveyPage + Question prop
+- [ ] `debug.enabled` → hook `debug: true`
+
+### G. EC2 promote (review mode only)
+
+```bash
+npx cfm-sdk confirm-ui-config   # downloads logo → public/
+```
+
+### H. Verify + build (blocking)
+
+```bash
+bash templates/verify-agent-build.sh
+```
+
+Script runs `npm run build`. Additionally confirm logo in static output:
+
+```bash
+test -z "$LOGO" || test -f "out/$LOGO" || echo "FAIL: logo not in out/"
+```
+
+### I. Phase 7 gate
+
+Only after H passes → ask deploy (INPUT 4). See [`aws-deploy.md`](aws-deploy.md) § Logos.
+
+**Do not re-run** `npx cfm-sdk customize` unless the client explicitly requests another session.
+
+**Do not re-run** `npx cfm-sdk export-previews` after wizard save — previews were deleted on purpose (GC). Export-previews is for **component structure changes** during Phase 5, not for applying saved config.
+
+---
+
+## Wizard steps → live preview keys
+
+| Wizard step | Default preview | What updates live |
+|-------------|-----------------|-------------------|
+| **Branding & Header** | `header` | Logo upload, company name, header dimensions/colors |
+| **Footer** | `footer` | Copyright, links, footer logo, colors |
+| **Theme & Colors** | `survey_page` | Palette, header/footer/progress/language colors, **Question card** (cell selected + focus ring) |
+| **Layout & Chrome** | `survey_page` | showHeader/Footer/Progress, nav buttons, question numbers, asterisk, width, font |
+| **Question Types** | per format tab | Per-type panels (see matrix below) |
+| **Testing & Tokens** | `survey_page` | Placeholders, custom fields, debug |
+| **Deploy & Build** | `survey_page` | Deploy target metadata (informational) |
+
+Chrome previews also exist: `intro`, `end`, `chrome` — used by harness; agent wires same hooks on Intro/End/SurveyPage.
+
+---
+
+## Question type format matrix (wizard → config → component)
+
+### How to read this table
+
+| Column | Meaning |
+|--------|---------|
+| **Preview key** | Iframe loaded in wizard right panel |
+| **Survey `question.type`** | Flat literal in `Question.tsx` dispatch |
+| **Wizard controls** | Fields in Question Types step for that tab |
+| **Config block** | `survey-ui-config.json` path (shared across formats of same type) |
+| **Scale / branch** | Component that must use `var(--cfm-*)` + `selectionStyles` / `labelStyles` |
+| **DOM attrs** | `data-cfm-*` set on `:root` or elements |
+
+**Shared across almost all scale types:** Theme → Question card → `cellSelectedColor` → `--cfm-matrix-selected`; `focusRingColor` → `--cfm-input-focus-ring`. Use [`selectionStyles.ts`](../templates/selectionStyles.ts).
+
+**Matrix multi-row:** Toggle **Preview multiple statements** on CFM, CSAT, Rating, Slider types. `LikertMatrixScale` / `CsatMatrixScale` must map **all** `statementRows` — not a single hardcoded row.
+
+---
+
+### MCQ — `questionTypes.MCQ`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `MCQ_single` | Single select | Option style, gap, radius, padding | `Question.tsx` MCQ branch + radio ring/dot |
+| `MCQ_multiple` | Multi select | Same | Checkbox: ring border + fill from theme |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `optionStyle` | `data-cfm-mcq-style` on `:root` |
+| `optionGap` | `--cfm-mcq-option-gap` |
+| `borderRadius` | `--cfm-mcq-border-radius` |
+| `optionPadding` | `--cfm-mcq-card-padding` |
+| Selection | `--cfm-input-focus-ring`, `--cfm-matrix-selected`, `--cfm-mcq-selected-bg` |
+
+---
+
+### TEXTFIELD — `questionTypes.TEXTFIELD`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `TEXTFIELD_short` | Short | Placeholder text, radius, border, placeholder color | `Question.tsx` + `data-cfm-textfield` |
+| `TEXTFIELD_long` | Long | Same | `textarea` with same hooks |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `inputRadius` | `--cfm-input-radius` |
+| `borderColor` | `--cfm-input-border` |
+| `placeholderColor` | `--cfm-input-placeholder` + `::placeholder` rule in theme CSS |
+| `defaultPlaceholder` | Default placeholder string (cosmetic) |
+| Focus | `--cfm-input-focus-ring` |
+
+---
+
+### NPS_SCALE — `questionTypes.NPS_SCALE`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `NPS_SCALE` | Radio / numbered / pill | Button style, track colors, hint labels, number labels | `RatingScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `buttonStyle` | `data-cfm-nps-button-style` |
+| `selectedFill`, `trackBarColor`, `trackHighlightColor` | `--cfm-nps-*` |
+| `hintMinText`, `hintMaxText`, hint colors | `hintLabelStyle()` |
+| `numberLabelMode`, per-index colors | `--cfm-number-*`, `resolveNumberLabelColor()` for **unselected** badges |
+| Selection | `scaleRadioRingStyle`, `scaleRadioDotStyle` |
+
+---
+
+### CFM_MATRIX — `questionTypes.CFM_MATRIX`
+
+Wizard tabs: **Likert**, **Bipolar**. Harness also ships `CFM_transpose`, `CFM_carousel`, `CFM_dropdown` — same config block.
+
+| Preview key | Matrix variant | Wizard controls | Scale / branch |
+|-------------|----------------|-----------------|----------------|
+| `CFM_likert` | Likert grid | Row width, bipolar %, label items | `LikertMatrixScale.tsx` |
+| `CFM_bipolar` | Bipolar anchors | Same + bipolar column width | Same |
+| `CFM_transpose` | Transposed | *(no extra wizard fields)* | `LikertMatrixScale` / matrix utils |
+| `CFM_carousel` | Carousel | Label items + theme selection | Matrix carousel branch |
+| `CFM_dropdown` | Dropdown | Label items | `MatrixDropdown.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| `bipolarColumnWidthPercent` | `--cfm-matrix-bipolar-width` |
+| `columnLabelColor`, `columnLabelBgColor` | `matrixColumnLabelStyle()` |
+| Selection | `matrixRadioRingStyle`, `matrixRadioDotStyle` |
+
+**No** per-format accent overrides in wizard — Question card tokens only.
+
+---
+
+### CSAT_MATRIX — `questionTypes.CSAT_MATRIX`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `CSAT_emoji` | Emoji | Emoji size, unselected opacity, label items | `CsatMatrixScale.tsx` emoji cells |
+| `CSAT_star` | Star | Unselected opacity, label items | Star row; selected = `cellSelectedVar` |
+| `CSAT_numbered` | Numbered | Opacity, label items, number labels | Number badges + selection pattern |
+| `CSAT_graphics` | Graphics slider | Label items | `CustomSliderTrack.tsx` thumb pattern |
+| `CSAT_carousel` | Carousel | Label items | Dot indicators = cell selected when active |
+| `CSAT_dropdown` | Dropdown | Label items | `MatrixDropdown` + list radio |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `emojiSize` | `--cfm-csat-emoji-size` |
+| `unselectedOpacity` | `--cfm-csat-unselected-opacity` |
+| `columnLabelColor`, `columnLabelBgColor` | `csatColumnLabelStyle()` |
+| Number labels (numbered tab) | `--cfm-number-*` |
+| Selection | theme Question card vars |
+
+---
+
+### RATING_MATRIX — `questionTypes.RATING_MATRIX`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `RATING_star` | Star | Unselected star opacity, label items | `CsatMatrixScale.tsx` (shared path) |
+| `RATING_numbered` | Numbered | Opacity, label items, number labels | Numbered badges |
+| `RATING_radio` | Radio grid | Opacity, label items | Horizontal radio grid — `matrixRadioRingStyle` |
+| `RATING_emoji` | Emoji | Emoji size, opacity, label items | Emoji cells |
+| `RATING_graphics` | Graphics | Opacity, label items | `CustomSliderTrack` |
+| `RATING_slider` | Slider | Label items | Slider thumb pattern |
+
+Config block mirrors CSAT where formats overlap; uses `unselectedStarOpacity` instead of `unselectedOpacity` in JSON.
+
+---
+
+### SLIDER_MATRIX — `questionTypes.SLIDER_MATRIX`
+
+| Preview key | Format | Wizard controls | Scale / branch |
+|-------------|--------|-----------------|----------------|
+| `SLIDER_matrix` | Slider matrix | Track, thumb, tick colors, row width, tick label items, tick number labels | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `trackColor`, `thumbColor`, `tickColor` | `--cfm-slider-track`, `--cfm-slider-thumb`, `--cfm-slider-tick` |
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| Tick label items | `sliderTickLabelStyle()` |
+| Tick number labels | `--cfm-number-*` |
+| Row band | `--cfm-slider-row-band` / `--cfm-row-band` from theme |
+| Thumb selection | focus ring + cell selected on knob |
+
+---
+
+### FILE_UPLOAD — `questionTypes.FILE_UPLOAD`
+
+| Preview key | Wizard controls | Scale / branch |
+|-------------|-----------------|----------------|
+| `FILE_UPLOAD` | Dropzone border style, border color, fill, padding | `FileUploadScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `dropzoneStyle` | `data-cfm-dropzone-style` |
+| `borderColor` | `--cfm-upload-border-color` (not hardcoded gray) |
+| `dropzoneFillColor`, `dropzonePadding` | `--cfm-upload-fill`, `--cfm-upload-padding` |
+| Focus / drag | `--cfm-input-focus-ring`, `--cfm-mcq-selected-bg` |
+
+Presigned upload flow unchanged — styling only.
+
+---
+
+### HEATMAP — `questionTypes.HEATMAP`
+
+| Preview key | Wizard controls | Scale / branch |
+|-------------|-----------------|----------------|
+| `HEATMAP` | Pin color, border, size | `HeatmapScale.tsx` |
+
+| Config field | CSS / DOM |
+|--------------|-----------|
+| `pinColor` | `--cfm-heatmap-pin` |
+| `pinBorderColor` | `--cfm-heatmap-pin-border` |
+| `pinSize` | `--cfm-heatmap-pin-size` |
+
+---
+
+### RANK_ORDER — `questionTypes.RANK_ORDER`
+
+| Preview key | Variant | Wizard controls | Scale / branch |
+|-------------|---------|-----------------|----------------|
+| `RANK_drag` | Drag & drop | Item bg, handle, badge | `RankOrderScale.tsx` + `@dnd-kit` |
+| `RANK_dropdown` | Dropdown | Item bg, select border, badge | Dropdown rank UI in same scale |
+
+| Config path | CSS var |
+|-------------|---------|
+| `drag.itemBg` / `dropdown.itemBg` | `--cfm-rank-item-bg` |
+| `drag.dragHandleColor` | `--cfm-rank-handle` |
+| `*.rankBadgeColor` | `--cfm-rank-badge` |
+| `drag.itemGap`, `itemPadding` | `--cfm-rank-item-gap`, `--cfm-rank-item-padding` |
+| `dropdown.selectBorderColor` | `--cfm-rank-select-border` |
+
+Do not change `interactionMode` or answer payload shapes.
+
+---
+
+### TEXT_AND_MEDIA — theme only
+
+| Preview key | Wizard step | Tokens |
+|-------------|-------------|--------|
+| `TEXT_AND_MEDIA` | Theme (media) | `--cfm-media-max-width`, `--cfm-media-radius` |
+
+No dedicated Question Types panel — wire in `Question.tsx` TEXT_AND_MEDIA branch.
+
+---
+
+## Phase 5 prerequisite — why post-customize apply works smoothly
+
+If Phase 5 copied all wizard-ready artifacts **before** the wizard ran, Phase 6c is mostly **config sync** — not rewriting components:
+
+| Artifact | Required before wizard |
+|----------|------------------------|
+| `survey-theme.css` | Full `--cfm-*` scaffold |
+| `selectionStyles.ts`, `labelStyles.ts` | Selection + label helpers |
+| `Header.tsx`, `Footer.tsx`, chrome templates | All `data-cfm-*` hooks |
+| `uiConfig.ts` | No bare `UI_CONFIG` |
+| Scale components per inventory | `var(--cfm-*)` not hardcoded hex |
+| `previewBridge.ts` | `layoutFlags` handler (dev preview) |
+
+If a wizard control does not live-update during Phase 6b, fix the **missing hook** in Phase 5 templates first — then re-run wizard. See symptom table in [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
+
+---
+
+## Post-apply smoke checks (by type in survey)
+
+For each `question.type` in the **fetched survey** (not all 11), spot-check in `npm run dev` after apply:
+
+| Type | Check |
+|------|-------|
+| MCQ | Option gap/radius; selected ring uses theme focus + cell colors |
+| TEXTFIELD | Placeholder color on focus/blur |
+| NPS_SCALE | Number badge traffic colors when unselected; selected uses theme |
+| CFM_MATRIX | Column label item colors; multi-row if multiple statements |
+| CSAT / RATING | Format-specific opacity/size; carousel dots if used |
+| SLIDER_MATRIX | Thumb ring+dot; tick label item colors |
+| FILE_UPLOAD | Dropzone border color from config |
+| HEATMAP | Pin size/color |
+| RANK_ORDER | Drag handle + badge colors |
+| TEXT_AND_MEDIA | Media max-width |
+
+---
+
+## Common mistakes after confirmation
+
+| Mistake | Fix |
+|---------|-----|
+| Partial CSS update (only changed colors) | Full regen `survey-theme.css` from entire JSON |
+| Changed `logo.fileName` manually | Use wizard `fileName`; keep `public/` file in sync |
+| Re-ran `export-previews` after save | Unnecessary — previews GC'd; apply config to client app instead |
+| Skipped types not in survey inventory | Still apply `questionTypes.*` blocks from saved JSON to CSS |
+| Edited `Question.tsx` dispatch | Forbidden — cosmetic tokens only |
+| Deploy before `out/{logo}` exists | Run build + logo preflight in Phase 6c H |
+
+---
+
+## Related
+
+| Doc | When |
+|-----|------|
+| [`wizard-config-handoff.md`](wizard-config-handoff.md) | Wait protocol, GC, EC2 link |
+| [`apply-ui-config.md`](apply-ui-config.md) | Full config path → CSS tables |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Selection patterns, code snippets |
+| [`wizard-chrome-contract.md`](wizard-chrome-contract.md) | Copy commands, symptom → fix |
+| [`agent-execution-flow.md`](agent-execution-flow.md) | Full pipeline phases |
+| [`verify-agent-build.sh`](../templates/verify-agent-build.sh) | Automated gate before deploy |

package/templates/docs/00-integration/wizard-question-type-styling.md

@@ -1,6 +1,7 @@
 # Wizard Question-Type Styling
 
 > **Read during Phase 5 (BUILD) — mandatory.** Alongside [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> **After client saves wizard:** [`wizard-post-customize-build.md`](wizard-post-customize-build.md) — full format matrix + Phase 6c runbook.  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 **Do not change** `Question.tsx` dispatch logic, answer shapes, SDK visibility helpers, or matrix routing algorithms — styling only.
@@ -75,10 +76,26 @@ Single-select radio: outer border = focus ring, annulus = cell selected, inner d
 
 ### TEXTFIELD (`TEXTFIELD_short`, `TEXTFIELD_long`)
 
-| Wizard section | CSS vars |
-|----------------|----------|
-| Input radius, border, placeholder | `--cfm-input-radius`, `--cfm-input-border`, `--cfm-input-placeholder` |
-| Focus | `--cfm-input-focus-ring` on focus outline |
+| Wizard section | CSS vars | Apply in |
+|----------------|----------|----------|
+| Input radius, border, padding | `--cfm-input-radius`, `--cfm-input-border`, `--cfm-input-padding` | `Question.tsx` textarea |
+| **Placeholder color** | `--cfm-input-placeholder` | `data-cfm-textfield` + CSS `::placeholder { color: var(--cfm-input-placeholder) }` |
+| Focus | `--cfm-input-focus-ring` | focus outline |
+
+```tsx
+<textarea
+  data-cfm-textfield
+  style={{ borderColor: 'var(--cfm-input-border)', ... }}
+  className="placeholder:cfm-input-ph"
+/>
+```
+
+```css
+[data-cfm-textfield]::placeholder {
+  color: var(--cfm-input-placeholder);
+  opacity: 1;
+}
+```
 
 ### NPS_SCALE (`NPS_SCALE`)
 
@@ -101,6 +118,8 @@ Single-select radio: outer border = focus ring, annulus = cell selected, inner d
 
 **No** per-type accent/ring overrides in CFM — use Question card tokens only.
 
+**Matrix multi-row preview:** Wizard **Question Types → CFM** has a **multi-statement** toggle. Preview harness injects a second `statementRow` when enabled. `LikertMatrixScale.tsx` **must** map over `question.statementRows` — never hardcode a single row.
+
 ### CSAT_MATRIX (`CSAT_carousel`, `CSAT_dropdown`, `CSAT_emoji`, `CSAT_graphics`, `CSAT_numbered`, `CSAT_star`)
 
 | Format | Wizard sections | Key styling |
@@ -174,6 +193,8 @@ For production builds after wizard: syncing `survey-theme.css` is sufficient —
 
 **Wizard customization** exposes all **11** question types regardless of fetched survey inventory. Wire styling for every scale template you copy — not only types in the client's mockup image.
 
+**Format-level matrix** (every preview tab → component): [`wizard-post-customize-build.md`](wizard-post-customize-build.md) § Question type format matrix.
+
 For each type in **wizard export** (all 11):
 
 - [ ] Scale component uses `var(--cfm-*)` for every wizard-exposed token (no hardcoded brand hex)

package/templates/docs/MANIFEST.json

@@ -457,9 +457,11 @@
       "when": "wizardUsedOrSurveyUiConfigExists",
       "read": [
         "00-integration/wizard-config-handoff.md",
+        "00-integration/wizard-post-customize-build.md",
         "00-integration/apply-ui-config.md",
         "00-integration/wizard-preview-build-guide.md",
-        "00-integration/wizard-question-type-styling.md"
+        "00-integration/wizard-question-type-styling.md",
+        "00-integration/wizard-chrome-contract.md"
       ],
       "inputFile": "survey-ui-config.final.json",
       "inputFileLocal": "survey-ui-config.json",

package/templates/docs/index.md

@@ -30,6 +30,7 @@ templates/docs/
 │   ├── agent-operating-contract.md ← Anti-hallucination — read FIRST
 │   ├── agent-execution-flow.md   ← Pipeline, client questions, wizard-ready build
 │   ├── wizard-preview-build-guide.md
+│   ├── wizard-post-customize-build.md  ← Phase 6c — all formats + build gate
 │   ├── wizard-question-type-styling.md
 │   └── …
 ├── 01-components/                ← Wiring blueprints (per type from MANIFEST)
@@ -80,7 +81,7 @@ Full step-by-step: [`agent-execution-flow.md`](00-integration/agent-execution-fl
 | **5** Build | Wizard-ready UI | `wizard-chrome-contract.md`, `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, `03-ui-specs/*` |
 | **6** Verify | Build + dev server | `verify-agent-build.sh` — **ask wizard** |
 | **6b** Wizard | Optional customize | **`npx cfm-sdk customize`** (default) — EC2 `customize-ui` only if client on another device |
-| **6c** Apply | Sync final config | `apply-ui-config.md` |
+| **6c** Apply | Sync final config | `wizard-post-customize-build.md`, `apply-ui-config.md` |
 | **7** Deploy | Production | **ask deploy** — `aws-deploy.md` or Vercel |
 
 **Auto-proceed:** Phase 4 → 5 and Phase 5 → 6 without waiting for approval.
@@ -135,7 +136,7 @@ npx cfm-sdk customize   # DEFAULT — opens localhost:4200, WAITS until client s
 
 **Phase 6b:** Client on same machine → `customize` writes `survey-ui-config.json` directly. Remote client → `customize-ui` + EC2 link (see `wizard-troubleshooting.md`). Apply per `apply-ui-config.md`.
 
-**Phase 6c:** Apply from `survey-ui-config.final.json` per [`wizard-config-handoff.md`](00-integration/wizard-config-handoff.md) + [`apply-ui-config.md`](00-integration/apply-ui-config.md) — **every** diff path. Then:
+**Phase 6c:** Apply from `survey-ui-config.json` (local) or `.final.json` (EC2) per [`wizard-post-customize-build.md`](00-integration/wizard-post-customize-build.md) — all question types/formats + chrome — then [`apply-ui-config.md`](00-integration/apply-ui-config.md) for path tables. Then:
 
 ```bash
 npx cfm-sdk confirm-ui-config
@@ -154,7 +155,7 @@ Re-run verify script + build.
 | Phase 4 plan | `mockup-ui-extraction.md`, `placeholders-and-custom-fields-wiring.md`, `component-checklist.md`, per-type `03-ui-specs/*` |
 | Wizard build | `wizard-preview-build-guide.md`, `wizard-question-type-styling.md` |
 | Wizard run | `wizard-config-handoff.md`, `ui-customization-wizard.md`, `wizard-api.md`, `wizard-troubleshooting.md` |
-| After wizard (apply all paths) | `apply-ui-config.md` |
+| After wizard (apply all paths) | `wizard-post-customize-build.md`, `apply-ui-config.md` |
 | Deploy | `aws-deploy.md` (§ Logos & local assets), `setup.md#nextjs-aws-static-export` |
 | Config audit | `02-reference/config-field-index.md` |