@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

package/templates/docs/00-integration/agent-operating-contract.md

@@ -0,0 +1,260 @@
+# Agent Operating Contract — Anti-Hallucination Guide
+
+> **Read with** [`agent-execution-flow.md`](agent-execution-flow.md) and [`index.md`](../index.md).  
+> This doc tells the **client-side coding agent** exactly how to use SDK docs — and what is **forbidden** to invent.
+
+**Prime directive:** If a behavior, API, file path, CSS variable, answer shape, or CLI command is **not** written in these docs (or copied from `docs/templates/`), **do not implement it from memory**.
+
+---
+
+## 1. Authoritative source hierarchy
+
+Use sources **only** in this order. Lower items never override higher ones.
+
+| Priority | Source | Use for |
+|----------|--------|---------|
+| **1** | [`MANIFEST.json`](../MANIFEST.json) | Phase order, `typeLiterals`, per-type `blueprint` / `reference` / `uiSpec` paths |
+| **2** | [`agent-execution-flow.md`](agent-execution-flow.md) | Pipeline, client questions, phase gates |
+| **3** | This file | Anti-hallucination rules, doc routing, verification |
+| **4** | `00-integration/*` | Wiring, constraints, wizard, deploy |
+| **5** | `01-components/*` + `03-ui-specs/*` | UI anatomy per type |
+| **6** | `02-reference/*` | Data shapes, exports, value derivation |
+| **7** | `docs/templates/*` | Copy-paste starting code (`Question.tsx`, scales, libs) |
+
+### Forbidden sources (never use to implement)
+
+| Forbidden | Why |
+|-----------|-----|
+| `packages/sdk/src/**` or `node_modules/.../src/**` | Internal SDK — not a public contract |
+| `apps/client/**` | Monorepo snapshot — may be stale; not agent deliverable |
+| Legacy `survey-config.json` | Replaced by `survey-ui-config.json` + wizard |
+| Training memory / other survey libs | Wrong answer shapes, wrong hooks, wrong types |
+| Guessing from component names alone | Types and helpers are defined in docs only |
+
+**If two docs conflict:** `MANIFEST.json` + `agent-execution-flow.md` win. Open an issue in the monorepo — do not pick a guess.
+
+---
+
+## 2. Read-before-write protocol (mandatory)
+
+**Never write or edit React/TS/CSS until the listed docs for the current phase are read.**
+
+### Phase gate table
+
+| Phase | Read these files **before any code** | Extract and record |
+|-------|--------------------------------------|--------------------|
+| **0** | `agent-operating-contract.md`, `agent-execution-flow.md`, `index.md`, `MANIFEST.json` | Framework, `typeLiterals`, branding notes |
+| **1** | `setup.md` (framework section) | Install list, AWS export flags if prompt mentions AWS |
+| **2** | `useSurveySDK.md` | `instanceId` wiring location — then **ask client for JWT** |
+| **3** | `client-integration-guide.md`, `question-type-sdk-matrix.md`, logic + lifecycle docs per MANIFEST phase 3 | `onAction` shapes, `state.answers`, visibility helpers |
+| **4** | `component-checklist.md`, `implementation_plan.md` template, `00-question-shell.md`, `12-survey-chrome.md`, **per-type** MANIFEST routes | Inventory table in `implementation_plan.md` §3b |
+| **5** | `constraints.md`, `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, **each** `03-ui-specs/{type}.md` in inventory | Tokens, `data-cfm-*`, selection pattern |
+| **6** | `constraints.md`, `component-checklist.md` Step 3–4 | Run `verify-agent-build.sh` — fix failures |
+| **6b** | `ui-customization-wizard.md`, `wizard-api.md` | CLI env vars — only if client said **yes** |
+| **6c** | `apply-ui-config.md`, `wizard-question-type-styling.md` | UI tokens only |
+| **7** | `aws-deploy.md` or deploy section in `setup.md` | Deploy target from prompt / config |
+
+### Per-question-type gate (Phase 4–5)
+
+For **each** `question.type` in the fetched survey, read **all three** MANIFEST paths before touching that component:
+
+```
+questionTypes.{TYPE}.blueprint   → 01-components/*
+questionTypes.{TYPE}.reference   → 02-reference/question-types/*
+questionTypes.{TYPE}.uiSpec      → 03-ui-specs/*
+```
+
+**Blocking rule:** If you have not read the ui-spec for a type, you may not implement that type.
+
+---
+
+## 3. Doc routing — task → exact files
+
+Use this table when deciding what to read. **Do not substitute similar-sounding docs.**
+
+| Task | Read (in order) | Do not guess |
+|------|-----------------|--------------|
+| Wire `useSurveySDK` | `useSurveySDK.md`, `client-integration-guide.md` | Hook return field names |
+| Dispatch questions | `templates/Question.tsx`, `question-type-sdk-matrix.md`, `routing-table.md` | `subType`, stub fallbacks |
+| NPS scale | `03-ui-specs/01-rating.md`, `templates/RatingScale.tsx`, `value-derivation.md` | `optionValue`, `accentColor` on options |
+| MCQ | `03-ui-specs/02-radio.md`, `question-type-sdk-matrix.md#mcq` | `isMultiSelect` — use `selectionMode` |
+| Matrix CFM | `03-ui-specs/07-matrix-cfm.md`, `templates/LikertMatrixScale.tsx`, `canonical-survey-fixtures.md` | Bare radio grid without row labels |
+| Matrix CSAT/Rating | `03-ui-specs/04-csat.md`, `08-matrix-csat-rating.md`, `templates/CsatMatrixScale.tsx` | Separate RatingMatrixScale file |
+| Slider matrix | `03-ui-specs/09-slider-matrix.md`, `templates/SliderMatrixScale.tsx` | Orphan slider without header row |
+| File upload | `03-ui-specs/10-file-upload.md`, `file-upload-aws.md` | Raw `File[]` in submit payload |
+| Heatmap | `03-ui-specs/13-heatmap.md`, `templates/heatmapCoords.ts` | Region overlays on respondent UI |
+| Rank order | `03-ui-specs/14-rank-order.md`, `templates/RankOrderScale.tsx` | Client-side re-shuffle |
+| Custom fields | `custom-field-logic-and-navigation.md`, `templates/customFieldValues.ts` | Skip wiring hook + Question prop |
+| Wizard chrome | `wizard-preview-build-guide.md`, `03-ui-specs/12-survey-chrome.md` | External logo URLs |
+| Wizard per-type colors | `wizard-question-type-styling.md` | Hardcoded Telekom hex for wizard tokens |
+| Selection colors | `wizard-question-type-styling.md`, `templates/selectionStyles.ts` | Single color for ring + fill — use annulus pattern |
+| Matrix column labels | `wizard-question-type-styling.md`, `templates/labelStyles.ts` | Hint labels on CFM column headers |
+| Logo seed | `constraints.md` §4, `wizard-api.md`, `parse-client-header` behavior in wizard docs | Random `public/logo_*` scan |
+| Wizard session (wait) | `wizard-config-handoff.md`, `ui-customization-wizard.md` |
+| Apply all wizard paths | `apply-ui-config.md` | Changing `Question.tsx` dispatch |
+| Deploy AWS | `aws-deploy.md`, `setup.md#nextjs-aws-static-export` | `assetPrefix: "/"` for static export |
+
+---
+
+## 4. Hallucination blocklist — never invent these
+
+| ❌ Hallucination | ✅ Doc-backed truth |
+|-----------------|---------------------|
+| `question.subType` routing | Flat `question.type` — 11 literals in `MANIFEST.json` `typeLiterals` |
+| `state.values` for answers | `state.answers` — `MANIFEST.json` `hookContract.answersField` |
+| `isMultiSelect` on MCQ | `selectionMode: 'single' \| 'multiple'` |
+| Default branch: "Not implemented" | Copy `templates/Question.tsx` — all types explicit |
+| Import `@repo/sdk/src/...` | Package root only — `hookContract.forbiddenImports` |
+| Implement from `apps/client` | Copy `docs/templates/*` |
+| `npx cfm-sdk customize` before build | Build + verify first; AWS = `customize-ui` |
+| `survey-config.json` | `survey-ui-config.json` + schema in `templates/` |
+| NPS `option.accentColor` | Derive from value — `value-derivation.md` |
+| Matrix value = column label text | `matrixColumnStoredValue(col)` → column **`id`** |
+| FILE_UPLOAD answer = `File[]` | `UploadedFileAnswer[]` after presigned upload |
+| CFM column headers = hint labels | `matrixColumnLabelStyle()` — label **items** only |
+| Focus ring = cell fill (same element) | Ring = border + dot; cell selected = annulus between |
+| Wizard optional → skip `survey-theme.css` | Wizard-ready build is **mandatory** Phase 5 |
+| Logo from any `public/logo_*` | `Header.tsx` `data-cfm-logo` / `data-cfm-logo-text` contract |
+| `getVisible*` without 4th arg when CRM logic exists | Pass `customFieldValues` — `hookContract.visibilityHelpers` |
+| New question types or SDK actions | Only documented `onAction` types in `useSurveySDK.md` |
+| Placeholder unstable inline object | Stable ref + `useMemo` on hook options |
+| Slider matrix without tick header | `canonical-survey-fixtures.md` + ui-spec |
+| RATING_MATRIX as new component | Reuse `CsatMatrixScale.tsx` |
+| Killed CLI during wizard poll | Keep running until `Configuration ready`; see `wizard-config-handoff.md` |
+| Applied before client submitted | Wait for CLI exit 0; use `.final.json` not seed |
+| Skipped diff paths | Read entire `survey-ui-config.diff.md`; apply every path |
+
+---
+
+## 5. Copy-first code generation
+
+**Default action = copy template, then extend.** Not rewrite from ui-spec prose.
+
+| Always copy first | Destination |
+|-------------------|-------------|
+| `templates/Question.tsx` | `src/components/Question.tsx` |
+| `templates/survey-theme.css` | `src/styles/survey-theme.css` |
+| `templates/selectionStyles.ts` | `src/lib/surveyUi/selectionStyles.ts` |
+| `templates/labelStyles.ts` | `src/lib/surveyUi/labelStyles.ts` |
+| `templates/previewBridge.ts` | `src/lib/previewBridge.ts` |
+| Per-inventory scale templates | `src/components/` |
+
+**After copy, only change:**
+
+- Branding tokens (`var(--cfm-*)`) per client prompt
+- Imports paths for project alias
+- Cosmetic styling per `wizard-question-type-styling.md`
+
+**Never change in copied dispatcher:**
+
+- `onAction` payload shapes
+- `question.type` switch cases / missing branches
+- Visibility helper call signatures
+
+---
+
+## 6. Phase completion evidence
+
+Do **not** tell the client a phase is done without evidence.
+
+| Phase | Required evidence |
+|-------|-------------------|
+| **4** | `implementation_plan.md` exists; §3b lists every fetched `question.type` |
+| **5** | All inventory components exist; draft `survey-ui-config.json` present |
+| **6** | `bash templates/verify-agent-build.sh` exit 0; `npm run build` exit 0; dev server loads |
+| **6b** | Client explicitly said yes; `survey-ui-config.json` updated by CLI |
+| **6c** | Tokens synced per `apply-ui-config.md`; verify script re-run |
+| **7** | Deploy only after INPUT 4 yes |
+
+### Verification commands (run, do not assume)
+
+```bash
+# From project root — paths may vary; see component-checklist.md
+bash templates/verify-agent-build.sh
+npm run build
+grep -r "not yet implemented" src/ components/ app/   # must be empty
+grep -r "subType" src/components/Question.tsx          # must be empty
+```
+
+---
+
+## 7. When uncertain — stop and read
+
+| Situation | Action | Do not |
+|-----------|--------|--------|
+| Field not in ui-spec config table | Check `02-reference/config-field-index.md` | Add imaginary prop |
+| Matrix labels missing in API | Read `canonical-survey-fixtures.md` | Omit label row |
+| Unknown `question.type` in survey | Re-fetch; check `typeLiterals` | Add `default` stub |
+| Wizard token name unclear | Read `wizard-question-type-styling.md` + `survey-theme.css` | Invent `--cfm-*` name |
+| CLI fails | Read error + `constraints.md` troubleshooting | Retry random flags |
+| Custom field id `_c_…` | Read `custom-field-logic-and-navigation.md` | Ignore in visibility |
+| AWS vs Vercel deploy | Prompt keywords + `survey-ui-config.json` `deploy.target` | Assume Vercel |
+
+**Uncertainty rule:** Open the MANIFEST-routed doc for that topic. If still absent, ask the client — do not implement.
+
+---
+
+## 8. Client communication rules
+
+### Exact questions (only these four)
+
+1. *(Prompt — usually provided at start)*
+2. *"Please provide your survey instance ID (JWT token)."* — Phase 2 only
+3. *"Your survey is running locally. Would you like to customize the UI through the web wizard?"* — Phase 6 only
+4. *"Your survey is built and verified. Ready to deploy to production?"* — Phase 7 only
+
+**Do not ask:** architecture opinions, stub approval, wizard before build, or "should I read the docs."
+
+### Status updates to client
+
+When reporting progress, cite **phase number** and **doc section** completed, e.g.:
+
+- "Phase 4 complete — inventory: NPS_SCALE, MCQ, CFM_MATRIX per `implementation_plan.md` §3b"
+- "Phase 5 — wired `--cfm-matrix-selected` / `--cfm-input-focus-ring` per `wizard-question-type-styling.md`"
+
+Do not claim "integrated SDK" without naming hook doc and verify result.
+
+---
+
+## 9. Wizard-ready build checklist (Phase 5 — non-optional)
+
+Even when the client will skip the wizard, verify each item:
+
+- [ ] `src/styles/survey-theme.css` copied from template
+- [ ] `selectionStyles.ts` + `labelStyles.ts` in `src/lib/surveyUi/`
+- [ ] `./survey-ui-config.json` draft at project root
+- [ ] `data-cfm-logo` or `data-cfm-logo-text`, `data-cfm-btn-next`, `data-cfm-btn-back`, `data-cfm-survey-title` in chrome
+- [ ] Scale components use `var(--cfm-*)` for wizard-controlled tokens
+- [ ] Selection pattern: focus ring = border + dot; cell selected = annulus
+- [ ] `previewBridge.ts` + layout init for local `customize`
+
+---
+
+## 10. Quick self-audit before handoff
+
+Answer **yes** to all before telling the client the survey is ready:
+
+1. Did I read `agent-operating-contract.md` and `agent-execution-flow.md` at session start?
+2. Did I read ui-specs for **every** type in the fetched survey?
+3. Did I copy `Question.tsx` from templates (not write a new dispatcher)?
+4. Are all 11 `typeLiterals` handled with no stub branch?
+5. Did `verify-agent-build.sh` pass?
+6. Did I ask wizard question only after Phase 6 verify?
+7. Did I avoid `apps/client` and SDK `/src/` imports?
+8. Are matrix row + column labels visible per `canonical-survey-fixtures.md`?
+9. Is FILE_UPLOAD using presigned flow if present?
+10. Is `customFieldValues` wired in hook **and** Question when `_c_…` ids exist?
+
+**Any "no" → go back to the routed doc in §3; do not hand off.**
+
+---
+
+## Related docs
+
+| Doc | Role |
+|-----|------|
+| [`agent-execution-flow.md`](agent-execution-flow.md) | Phase order and client inputs |
+| [`component-checklist.md`](component-checklist.md) | File inventory and copy table |
+| [`constraints.md`](constraints.md) | Hard limits (logo, imports, stubs) |
+| [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) | Answer shapes + visibility per type |
+| [`index.md`](../index.md) | Master index |

package/templates/docs/00-integration/analytics-events-catalog.md

@@ -0,0 +1,54 @@
+# Analytics Events Catalog
+
+> Consolidated SDK telemetry and client-wired lifecycle events. Most events log to console as `[SDK:ANALYTICS]` — **no client code required** unless noted.
+
+See also: [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md) · [`client-integration-guide.md`](client-integration-guide.md) § Debug logging
+
+---
+
+## Client must wire
+
+| Event / action | How | When |
+|----------------|-----|------|
+| Mark as started | `onAction({ type: 'SCROLL' })` once on first window scroll | First content engagement |
+| Question viewed | `onAction({ type: 'RECORD_QUESTION_VIEW', payload: { questionId } })` via IntersectionObserver on `#question.id` | Question 50% visible |
+| Partial save feedback | Monitor `partialSaveResults.isLoading` / `.error` | When `savePartialResponse: true` |
+
+First `CHANGE` also triggers mark-as-started (SDK) — no extra client call.
+
+---
+
+## SDK-emitted (always — no `debug` flag required)
+
+| Event | When | Metadata highlights |
+|-------|------|---------------------|
+| `fetch_survey_latency` | Survey GET completes | durationMs, status, payloadSize (UTF-8 KB) |
+| `fetch_survey_error` | Survey GET fails | status, url, message |
+| `submit_survey_latency` | Submit POST completes | durationMs, status |
+| `submit_survey_error` | Submit fails | status, message |
+| `page_time_spent` | Leaving a content page | pageIndex, durationMs |
+| `optional_question_skipped` | Optional question left blank on forward nav | questionId, pageIndex |
+| `backtrack_revisited` | User returns to earlier page and changes answers | fromPage, toPage, changedAnswers |
+| `question_viewed` | After RECORD_QUESTION_VIEW deduped | questionId |
+| `display_logic_matched` | Display condition newly true | questionId, logic details |
+| `answer_logic_matched` | Answer-logic sub-entity newly visible | entity scope |
+| `question_variant_matched` | Variant text switches | variant id |
+| `end_page_logic_matched` | Resolved end page changes | endPageId |
+| `skip_logic_triggered` | Skip logic newly activates | skip target |
+
+---
+
+## Post-submit rollups
+
+| Event | When | Contents |
+|-------|------|----------|
+| `survey_session_summary` | Successful submit | `completed`, `maxVisitedPageIndex`, `totalDurationMs`, question counts (total/answered/skipped), `validationErrorsCount`, `backtrackCount`, `validationHistory` |
+| `logic_session_summary` | Successful submit | Per-logic-kind counts, viewed vs on-path-not-viewed, final end page, `logicEventTimeline` audit (console.table) |
+
+Enable `debug: true` in hook options for additional `[SDK:INFO]` transition logs (display/answer/variant/end/skip matches on answer change).
+
+---
+
+## Validation error tracking
+
+SDK increments validation error counts and records per-page error history in session summary. Client displays `state.validationErrors[questionId]` banners and uses `id={question.id}` for scroll-to-error.

package/templates/docs/00-integration/apply-ui-config.md

@@ -0,0 +1,365 @@
+# Apply UI Config (`survey-ui-config.json`)
+
+> **Phase 6c** — after wizard handoff. Read [`wizard-config-handoff.md`](wizard-config-handoff.md) first (wait protocol + review artifacts).  
+> **Build-time contract:** [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md).  
+> **Per-type tokens:** [`wizard-question-type-styling.md`](wizard-question-type-styling.md).
+
+## Which file to apply from
+
+| Wizard mode | Apply source | When |
+|-------------|--------------|------|
+| AWS review (default) | `survey-ui-config.final.json` | After CLI prints `Configuration ready` |
+| AWS `--apply` | `survey-ui-config.json` | Immediately after CLI exits |
+| Local `customize` | `survey-ui-config.json` | After `UI configuration saved` |
+
+**AWS review mode:** `survey-ui-config.json` remains **seed** until `npx cfm-sdk confirm-ui-config` — always apply codebase from **`.final.json`**.
+
+---
+
+## Scope (UI-only)
+
+**May change:** CSS vars, chrome components, nav labels, logo path, placeholders, debug flag, cosmetic scale tokens.
+
+**Must NOT change:** `Question.tsx` dispatch, `onAction` payloads, answer shapes, visibility helpers, matrix routing, file upload presigned flow.
+
+---
+
+## Apply workflow (ordered — do not skip steps)
+
+### 1. Capture and audit
+
+```bash
+# AWS review mode — mandatory read
+cat survey-ui-config.diff.md
+```
+
+- Count entries: `changed + added + removed` from CLI output or diff JSON
+- Open `survey-ui-config.final.json` (or `survey-ui-config.json` for local)
+
+### 2. Validate
+
+- JSON parses without error
+- Validate against `templates/survey-ui-config.schema.json`
+- `surveyTypes` matches fetched survey inventory
+
+### 3. Sync CSS (full regen — not diff-only)
+
+**Regenerate entire `src/styles/survey-theme.css`** from final config so derived tokens stay consistent.
+
+Use the mapping tables below: every config field → `--cfm-*` var. Reference implementation: wizard `configToCssVars()` (same var names as `templates/survey-theme.css`).
+
+Minimum global vars from `global.colorScheme` + `global.theme`:
+
+```css
+:root {
+  --cfm-primary: /* global.colorScheme.primary */;
+  --cfm-accent: /* global.colorScheme.accent */;
+  --cfm-matrix-selected: /* global.theme.cellSelectedColor */;
+  --cfm-input-focus-ring: /* global.theme.focusRingColor */;
+  --cfm-mcq-selected-accent: var(--cfm-matrix-selected);
+  /* … all vars in templates/survey-theme.css */
+}
+```
+
+Import in `globals.css`: `@import './styles/survey-theme.css';`
+
+### 4. Apply content patches (`data-cfm-*`)
+
+| Config path | DOM target | Attribute / content |
+|-------------|------------|---------------------|
+| `global.surveyTitle` | Intro / title slot | `data-cfm-survey-title` text |
+| `global.companyName` | Header | `data-cfm-company` text |
+| `global.thankYouMessage` | End page | `data-cfm-thank-you` text |
+| `global.browserTabTitle` | `layout.tsx` / metadata | `document.title` |
+| `global.buttons.next` | SurveyPage | `data-cfm-btn-next` text |
+| `global.buttons.back` | SurveyPage | `data-cfm-btn-back` text |
+| `global.buttons.submit` | SurveyPage submit label | button text |
+| `global.logo.fileName` | Header | `data-cfm-logo` src=`/${fileName}` (or `./${fileName}` for static AWS export); remove `data-cfm-logo-text` when image |
+| `global.logo.url` | Agent reference only | Public CloudFront URL after wizard — download to `public/`; do **not** use as `img src` in the survey |
+| `global.footer.copyrightText` | Footer | `data-cfm-copyright` |
+| `global.footer.links[]` | Footer | `data-cfm-footer-links` (render links) |
+| `questionTypes.MCQ.optionStyle` | `:root` or survey wrapper | `data-cfm-mcq-style` |
+| `questionTypes.NPS_SCALE.buttonStyle` | `:root` | `data-cfm-nps-button-style` |
+| `questionTypes.FILE_UPLOAD.dropzoneStyle` | `:root` | `data-cfm-dropzone-style` |
+
+### 5. Apply layout toggles (chrome only)
+
+| `global.layout.*` | Apply in |
+|-------------------|----------|
+| `showHeader` | `SurveyPage` — conditional `<Header />` |
+| `showFooter` | Conditional `<Footer />` |
+| `showProgressBar` | `SurveyStickyChrome` / `ProgressBar` |
+| `showLanguageSwitcher` | `LanguageSelector` |
+| `showNextButton` / `showBackButton` | Nav button visibility |
+| `showQuestionNumbers` | Question title prefix |
+| `showRequiredAsterisk` | Required `*` in shell |
+| `width` | Container `max-w-*` via `--cfm-max-width` |
+| `borderStyle` | `--cfm-border-radius` |
+| `fontStyle` | `--cfm-font-family` |
+
+| `global.header.*` | CSS vars on `:root` (see § Header) |
+| `global.footer.*` | CSS vars + footer structure |
+
+### 6. Apply hook options
+
+| Config path | Wire in |
+|-------------|---------|
+| `placeholders.*` | `useSurveySDK({ options: { placeholders } })` — stable ref |
+| `customFields` | `src/lib/customFieldValues.ts` + hook + `Question` prop |
+| `debug.enabled` | `debug: true` in hook options |
+
+### 7. Per-type tokens (inventory only)
+
+For each type in `surveyTypes[]`, apply `questionTypes.{TYPE}` per § Question types below.
+
+### 8. Logo file
+
+- Local / `confirm-ui-config`: file in `public/{fileName}`
+- If missing after confirm: re-run with `CFM_INSTANCE_ID` + `CFM_DEPLOY_API_BASE`
+
+### 9. Promote active config (AWS review only)
+
+```bash
+npx cfm-sdk confirm-ui-config
+```
+
+Run **after** codebase apply succeeds.
+
+### 10. Verify nothing missed
+
+```bash
+bash templates/verify-agent-build.sh
+npm run build
+```
+
+**Diff cross-check:** For each path in `survey-ui-config.diff.json` → `changed` + `added` + `removed`, confirm a corresponding update exists (CSS var, DOM attr, or layout branch). If a path has no mapping in this doc, search `wizard-question-type-styling.md` and `templates/survey-theme.css`.
+
+---
+
+## Complete config path → apply target
+
+### `global.colorScheme`
+
+| Path | CSS variable |
+|------|----------------|
+| `primary` | `--cfm-primary` |
+| `secondary` | `--cfm-secondary` |
+| `accent` | `--cfm-accent` |
+| `background` | `--cfm-background` (fallback; `theme.pageBackground` wins) |
+| `text` | `--cfm-text` |
+| `buttonText` | `--cfm-button-text` |
+
+### `global.theme` (Question card + chrome)
+
+| Path | CSS variable / effect |
+|------|----------------------|
+| `pageBackground` | `--cfm-background` |
+| `cardBackground` | `--cfm-card-bg` |
+| `cardBorderColor` | `--cfm-card-border-color` |
+| `cardPadding` | `--cfm-card-padding` |
+| `cardShadowEnabled` | `--cfm-card-shadow` |
+| `cellSelectedColor` | `--cfm-matrix-selected`, `--cfm-mcq-selected-accent`, `--cfm-csat-ring-color` |
+| `focusRingColor` | `--cfm-input-focus-ring` |
+| `selectedBackground` | `--cfm-selected-bg`, `--cfm-mcq-selected-bg` |
+| `zebraRowColor` | `--cfm-zebra-row` |
+| `rowBandColor` | `--cfm-row-band` |
+| `validationBorder` | `--cfm-validation-border` |
+| `validationBackground` | `--cfm-validation-bg` |
+| `tooltipBackground` | `--cfm-tooltip-bg` |
+| `progressTrackHeight` | `--cfm-progress-height` |
+| `progressTrackColor` | `--cfm-progress-track` |
+| `progressFillColor` | `--cfm-progress-fill` |
+| `stickyChromePaddingTop` | `--cfm-sticky-pt` |
+| `stickyChromePaddingBottom` | `--cfm-sticky-pb` |
+| `languageSelectorBackground` | `--cfm-language-bg` |
+| `languageSelectorTextColor` | `--cfm-language-text` |
+| `languageSelectorBorderColor` | `--cfm-language-border` |
+
+### `global.header`
+
+| Path | CSS variable |
+|------|----------------|
+| `height` | `--cfm-header-height` |
+| `logoBoxWidth` | `--cfm-header-logo-width` |
+| `logoBoxHeight` | `--cfm-header-logo-height` |
+| `logoPadding` | `--cfm-header-logo-padding` |
+| `logoPlacement` | `--cfm-header-logo-col`, `--cfm-header-logo-justify` |
+| `showCompanyName` | `--cfm-header-show-company` |
+| `companyNamePlacement` | `--cfm-header-company-col`, `--cfm-header-company-justify` |
+| `companyNameFontSize` | `--cfm-header-company-size` |
+| `companyNameFontWeight` | `--cfm-header-company-weight` |
+| `companyNameColor` | `--cfm-header-company-color` |
+| `backgroundColor` | `--cfm-header-bg` |
+| `shadowEnabled` | `--cfm-header-shadow` |
+| `borderBottomColor` | `--cfm-header-border` |
+| `contentPaddingX` | `--cfm-header-padding-x` |
+
+### `global.footer`
+
+| Path | CSS variable / DOM |
+|------|-------------------|
+| `backgroundColor` | `--cfm-footer-bg` |
+| `textColor` | `--cfm-footer-text` |
+| `linkColor` | `--cfm-footer-link` |
+| `linkHoverColor` | `--cfm-footer-link-hover` |
+| `showLogo` | layout flag + footer logo slot |
+| `logoWidth` / `logoHeight` | `--cfm-footer-logo-width`, `--cfm-footer-logo-height` |
+| `logoPlacement` | `--cfm-footer-logo-col`, grid vars |
+| `copyrightText` | `data-cfm-copyright` |
+| `layout` | `--cfm-footer-layout`, `--cfm-footer-inner-display` |
+| `paddingY` / `paddingX` | `--cfm-footer-padding-y`, `--cfm-footer-padding-x` |
+| `links[]` | `data-cfm-footer-links` |
+
+### `global.typography` + `global.motion`
+
+| Path | CSS variable |
+|------|----------------|
+| `typography.fontFamily` | fallback for `--cfm-font-family` |
+| `typography.headingWeight` | `--cfm-heading-weight` |
+| `motion.durationMs` | `--cfm-motion-duration` |
+
+### `questionTypes.MCQ`
+
+| Path | Apply |
+|------|-------|
+| `optionStyle` / `cardStyle` | `data-cfm-mcq-style` |
+| `optionGap` | `--cfm-mcq-option-gap` |
+| `borderRadius` | `--cfm-mcq-border-radius` |
+| `optionPadding` / `cardPadding` | `--cfm-mcq-card-padding` |
+| `hoverBorderColor` | `--cfm-mcq-hover-border` |
+| Selection colors | from `global.theme` cellSelected + focusRing |
+
+### `questionTypes.TEXTFIELD`
+
+| Path | CSS variable |
+|------|----------------|
+| `inputRadius` | `--cfm-input-radius` |
+| `borderColor` | `--cfm-input-border` |
+| `inputPadding` | `--cfm-input-padding` |
+| `inputHeight` | `--cfm-input-height` |
+| `placeholderColor` | `--cfm-input-placeholder` |
+| `defaultPlaceholder` | placeholder text in preview / optional default |
+
+### `questionTypes.NPS_SCALE`
+
+| Path | CSS variable / DOM |
+|------|-------------------|
+| `buttonStyle` | `data-cfm-nps-button-style` |
+| `selectedFill` | `--cfm-nps-selected-fill` |
+| `trackBarColor` | `--cfm-nps-track-bar` |
+| `trackHighlightColor` | `--cfm-nps-track-highlight` |
+| `cellSize` / `cellGap` | `--cfm-nps-cell-size`, `--cfm-nps-cell-gap` |
+| `hintMinText` / `hintMaxText` | NPS anchor row text |
+| `hintLabelColor` / `hintLabelBgColor` | `--cfm-hint-label-color`, `--cfm-hint-label-bg` |
+| `numberLabelMode` | `--cfm-number-label-mode` |
+| `monochromeNumberColor` | `--cfm-number-mono-color` |
+| `individualNumberColors[n]` | `--cfm-number-color-{n}` |
+
+### `questionTypes.CFM_MATRIX`
+
+| Path | CSS variable |
+|------|----------------|
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| `bipolarColumnWidthPercent` | `--cfm-matrix-bipolar-width` |
+| `cellPadding` | `--cfm-matrix-cell-padding` |
+| `columnLabelColor` / `columnLabelBgColor` | `--cfm-matrix-column-label-color`, `--cfm-matrix-column-label-bg` |
+
+### `questionTypes.CSAT_MATRIX` / `RATING_MATRIX`
+
+| Path | CSS variable |
+|------|----------------|
+| `emojiSize` | `--cfm-csat-emoji-size` |
+| `unselectedOpacity` | `--cfm-csat-unselected-opacity` |
+| `cellSize` | `--cfm-csat-cell-size` |
+| `tooltipBg` | `--cfm-csat-tooltip-bg` |
+| `rowLabelWidth` | `--cfm-matrix-row-width` |
+| `columnLabelColor` / `columnLabelBgColor` | `--cfm-csat-column-label-*` |
+| Number label fields | same as NPS `--cfm-number-*` |
+
+### `questionTypes.SLIDER_MATRIX`
+
+| Path | CSS variable |
+|------|----------------|
+| `trackColor` / `thumbColor` | slider track vars in theme |
+| `tickLabelColor` / `tickLabelBgColor` | `--cfm-slider-tick-label-color`, `--cfm-slider-tick-label-bg` |
+| Row band | `--cfm-row-band` from global theme |
+
+### `questionTypes.FILE_UPLOAD`
+
+| Path | Apply |
+|------|-------|
+| `dropzoneStyle` | `data-cfm-dropzone-style` |
+| `borderColor` | `--cfm-upload-border-color` |
+
+### `questionTypes.HEATMAP`
+
+| Path | CSS variable |
+|------|----------------|
+| `pinColor` | `--cfm-heatmap-pin` |
+| `pinSize` | `--cfm-heatmap-pin-size` |
+| `pinBorderColor` | `--cfm-heatmap-pin-border` |
+
+### `questionTypes.RANK_ORDER`
+
+| Path | CSS variable |
+|------|----------------|
+| `drag.itemBg` / `dropdown.itemBg` | `--cfm-rank-item-bg` |
+| `drag.rankBadgeColor` / `dropdown.rankBadgeColor` | `--cfm-rank-badge` |
+| `drag.itemPadding` / `itemGap` | `--cfm-rank-item-padding`, `--cfm-rank-item-gap` |
+| `drag.dragHandleColor` | `--cfm-rank-handle` |
+| `dropdown.selectBorderColor` | `--cfm-rank-select-border` |
+
+### `deploy`
+
+| Path | Phase 7 |
+|------|---------|
+| `deploy.target` | `aws` → `aws-deploy.md`; `vercel` → `npx cfm-sdk deploy` |
+| `deploy.autoDeploy` | informational — agent still asks INPUT 4 |
+
+---
+
+## Diff-driven apply (zero omissions)
+
+When `survey-ui-config.diff.json` exists:
+
+1. Load `diff.changed`, `diff.added`, `diff.removed`
+2. For each entry, look up `entry.path` in the tables above
+3. Apply the **After** value (or remove DOM/CSS for `removed`)
+4. Track progress: `appliedCount === changed.length + added.length + removed.length`
+
+**Categories easy to miss** (always check diff for these):
+
+- `global.footer.links` (array — full replace)
+- `global.header.showCompanyName` + placement pairs
+- `questionTypes.*.individualNumberColors` (array)
+- `placeholders.*` (every key)
+- `customFields.*` (every `_c_` key)
+- `global.theme.cellSelectedColor` + `focusRingColor` (drive all scale selections)
+- `global.logo.fileName` (image swap)
+- `global.logo.url` (download reference — ensure file in `public/`)
+
+---
+
+## Selection styling (verify after apply)
+
+```tsx
+import { scaleRadioRingStyle, scaleRadioDotStyle } from '@/lib/surveyUi/selectionStyles';
+```
+
+Ensure components use `selectionStyles.ts` — config only changes CSS vars, not component structure.
+
+---
+
+## Re-run policy
+
+Do not re-run `customize-ui` unless the client explicitly requests another customization session. Each run overwrites review artifacts.
+
+---
+
+## Related
+
+| Doc | Role |
+|-----|------|
+| [`wizard-config-handoff.md`](wizard-config-handoff.md) | Wait + capture + confirm order |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Visual selection patterns |
+| [`agent-operating-contract.md`](agent-operating-contract.md) | Do not change dispatch logic |