@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

package/templates/docs/00-integration/canonical-survey-fixtures.md

@@ -0,0 +1,94 @@
+# Canonical Survey Fixtures
+
+> Ground-truth UI expectations for integration-test surveys. When your fetched survey matches these patterns, **copy portable templates** from [`templates/`](../templates/) — do not rebuild matrix/slider UI from prose.
+
+Related: [`component-checklist.md`](component-checklist.md) · [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md)
+
+---
+
+## Template copy order (all matrix types)
+
+0. `customFieldValues.ts` → `src/lib/` when survey logic references `_c_…` ids
+1. `surveyUiScaleUtils.ts` + `surveyUiIcons.tsx`
+2. `CustomSliderTrack.tsx` + `MatrixDropdown.tsx`
+3. Scale component for each type in survey
+4. `Question.tsx` from template (includes `questionNumber`, matrix visibility helpers, `customFieldValues` prop)
+
+---
+
+## Page-by-page fixture map
+
+| Page | Type | Key config | Expected UI | Copy |
+|------|------|------------|-------------|------|
+| 1 | `NPS_SCALE` | 11 options 0–10, `minLabel`/`maxLabel` | Traffic-light badges + anchor labels | `RatingScale.tsx` |
+| 2 | `SLIDER_MATRIX` | 1 row, `ticks.count: 11`; skip uses `_c_67199096d294be011a2b4773` | Colored 0–10 header + gray row + track; CRM field in `customFieldValues.ts` | `SliderMatrixScale.tsx` + `customFieldValues.ts` |
+| 3 | `FILE_UPLOAD` | `maxFileCount: 1` | Dropzone → presigned upload → `UploadedFileAnswer[]` | `FileUploadScale.tsx` |
+| 4 | `MCQ` | `selectionMode: single`, `defaultOptionIds` | Radio; pre-select default | `Question.tsx` inline |
+| 6 | `MCQ` | `minSelections`/`maxSelections` | Checkbox + validation message | `Question.tsx` inline |
+| 7 | `CFM_MATRIX` | `statementLayout: bipolar`, `showColumnHeaders: false`, 3 anchor labels, 10 cols | 25% left stmt \| radios \| 25% right stmt | `LikertMatrixScale.tsx` |
+| 9 | `CSAT_MATRIX` | `displayStyle: emoji`, 5 anchors, N/A | 180px stmt column + emoji row + anchors | `CsatMatrixScale.tsx` |
+| 10 | `CFM_MATRIX` | `transposeTable: true`, `selectionMode: multiple` | Rows=Scale Items, cols=Statement Items, **checkboxes** | `LikertMatrixScale.tsx` |
+| 11 | `RATING_MATRIX` | `displayStyle: graphics` | Per-row `CustomSliderTrack` (NOT SliderMatrixScale) | `CsatMatrixScale.tsx` |
+| 12 | `SLIDER_MATRIX` | 2 rows + 2 anchor labels | Shared header + 2 row bands with visible statements | `SliderMatrixScale.tsx` |
+| 14 | multi | star + slider + numbered rating | Three separate components; all labels visible | all three templates |
+
+---
+
+## Common agent failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Lone pink circle, no slider track | Built stub thumb instead of `SliderMatrixScale` | Copy template |
+| Matrix with no row labels | Omitted 180px / 25% statement column | See ui-spec statement visibility |
+| Matrix with no column labels | Ignored `scaleAnchorLabels` and `showColumnHeaders` | Render header row |
+| CSAT shows radios instead of emojis | Skipped `displayStyle: emoji` branch | Copy `CsatMatrixScale` |
+| RATING numbered shows native radios | Skipped `displayStyle: numbered` branch | 40×40 badges |
+| Bipolar missing right text | Ignored `oppositeStatementText` | 25% right column |
+| Transposed matrix wrong orientation | Ignored `transposeTable` | Swap gridRows/gridCols |
+| Custom-field skip never fires | `customFieldValues` omitted from hook or wrong `_c_` id | Copy `customFieldValues.ts`; wire hook + Question |
+
+---
+
+## Custom field fixture (Page 2)
+
+SLIDER_MATRIX skip when CRM field `_c_67199096d294be011a2b4773` `CASE_SENSITIVE_TEXT` equals `"abc"`:
+
+```typescript
+// src/lib/customFieldValues.ts
+export const CUSTOM_FIELD_VALUES = {
+  '_c_67199096d294be011a2b4773': 'abc',
+};
+```
+
+Import in `SurveyPage` and pass to `useSurveySDK` + `Question`. See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
+## Statement text rules (all matrix types)
+
+```tsx
+// Always render — never hide statementRows[].statementText
+<span dangerouslySetInnerHTML={{ __html: row.statementText }} />
+```
+
+For CFM bipolar, also render `row.oppositeStatementText` on the right.
+
+For CFM transposed, row labels come from `scaleColumns[].label`; column headers from `statementRows[].statementText`.
+
+---
+
+## Label header rules
+
+At least one header row MUST be visible when configured:
+
+- `scaleAnchorLabels.length > 0` → anchor row (positioning formulas in ui-specs)
+- `showColumnHeaders === true` → column label row from `scaleColumns[].label` or transposed `statementText`
+- CSAT without anchors → column header row from `scaleColumns[].label`
+
+---
+
+## Agent checklist
+
+- [ ] Read this doc when survey contains matrix or slider types
+- [ ] Copied all required templates before Phase 5 BUILD
+- [ ] Verified row labels + column/anchor labels render on every matrix question
+- [ ] Verified slider has header badges + track (not orphan circle)
+- [ ] `customFieldValues.ts` populated and wired to hook + Question when survey uses CRM logic

package/templates/docs/00-integration/client-integration-guide.md

@@ -1,6 +1,6 @@
 # Client Integration Guide
 
-> **Start here** after Phase 2 (instanceId). Single map of everything the client must wire to integrate all SDK features correctly.
+> **Start here** after Phase 2 (instanceId). Full pipeline order: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 Import only from the package root (`@explorer02/cfm-survey-sdk` or `@repo/sdk`). Never from `/src/` paths.
 
@@ -34,7 +34,7 @@ flowchart TB
 | Dispatcher | `Question.tsx` | Route on `question.type`; filter options/rows via visibility helpers; placeholder text |
 | Scales | `*Scale.tsx` | Render one question type; store answers via `onSelect` callback |
 
-Reference implementation: `apps/client/src/components/SurveyPage.tsx`.
+Reference implementation: portable templates in `docs/templates/` — not `apps/client` (monorepo snapshot only).
 
 ---
 
@@ -51,7 +51,7 @@ Reference implementation: `apps/client/src/components/SurveyPage.tsx`.
 | Question display variants | Render `question.questionText` from `currentQuestions` (no client variant logic) | Conditional variant text via same logic engine |
 | Answer logic UI | `getVisible*ForAnswers` + pass `customFieldValues` | Condition evaluation engine |
 | Custom fields | Stable `customFieldValues` → hook **and** `Question` | Skip/display/validation/progress evaluation |
-| Progress | Bind `state.progressPercentage` | Active-path denominator + earned credits |
+| Progress | `SurveyStickyChrome` with `state.progressPercentage` | Sticky header + bar; active-path denominator + earned credits |
 | Question numbering | Render `question.questionNumber` from `currentQuestions` | Active-path ordinals (same denominator as progress); see [`question-numbering.md`](question-numbering.md) |
 | Placeholders | Stable `placeholders` ref + `language` option | Token replacement at map time |
 | Mark as started | `onAction(SCROLL)` once on first scroll | One-time API call (also fires on CHANGE) |
@@ -61,7 +61,7 @@ Reference implementation: `apps/client/src/components/SurveyPage.tsx`.
 | Per-type integration | Read [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) before building scales | Answer shapes, visibility helpers, performance notes per type |
 | Validation scroll | `id={question.id}` on question wrapper | Scroll-to-first-error on failed NEXT/SUBMIT |
 
-Deep dives: [`useSurveySDK.md`](useSurveySDK.md) · [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) · [`placeholders-and-tokens.md`](placeholders-and-tokens.md) · [`partial-save-and-recovery.md`](partial-save-and-recovery.md) · [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md) · [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) · [`display-logic-and-navigation.md`](display-logic-and-navigation.md) · [`question-display-variants.md`](question-display-variants.md) · [`question-numbering.md`](question-numbering.md) · [`end-page-logic.md`](end-page-logic.md) · [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) · [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) · [`progress.md`](progress.md) · [`constraints.md`](constraints.md)
+Deep dives: [`useSurveySDK.md`](useSurveySDK.md) · [`question-type-sdk-matrix.md`](question-type-sdk-matrix.md) · [`placeholders-and-tokens.md`](placeholders-and-tokens.md) · [`partial-save-and-recovery.md`](partial-save-and-recovery.md) · [`survey-lifecycle-analytics.md`](survey-lifecycle-analytics.md) · [`analytics-events-catalog.md`](analytics-events-catalog.md) · [`logic-fields-catalog.md`](logic-fields-catalog.md) · [`file-upload-aws.md`](file-upload-aws.md) · [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) · [`display-logic-and-navigation.md`](display-logic-and-navigation.md) · [`question-display-variants.md`](question-display-variants.md) · [`question-numbering.md`](question-numbering.md) · [`end-page-logic.md`](end-page-logic.md) · [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) · [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) · [`progress.md`](progress.md) · [`constraints.md`](constraints.md)
 
 ---
 
@@ -161,10 +161,11 @@ function SurveyContent({
   }, [state.currentQuestions, onAction]);
 
   return (
-    <main>
-      <ProgressBar progressPercentage={state.progressPercentage} />
+    <>
+      <SurveyStickyChrome progressPercentage={state.progressPercentage} />
 
-      {state.currentQuestions.map(question => (
+      <main className="mx-auto w-full max-w-4xl flex-1 px-4 py-10">
+        {state.currentQuestions.map(question => (
         <Question
           key={question.id}
           question={question}
@@ -189,7 +190,8 @@ function SurveyContent({
       >
         {state.primaryButtonType === 'submit' ? 'Submit' : 'Next'}
       </button>
-    </main>
+      </main>
+    </>
   );
 }
 

package/templates/docs/00-integration/client-lib-folder.md

@@ -0,0 +1,115 @@
+# Client Lib Folder — Portable Templates
+
+> Maps the reference monorepo [`apps/client/src/lib/`](../../../../apps/client/src/lib/) layout to portable templates agents copy into their project. **Do not import from `apps/client/` in npm installs.**
+
+Related: [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) · [`component-checklist.md`](component-checklist.md) · [`constraints.md`](constraints.md)
+
+---
+
+## Reference → portable mapping
+
+| Reference file (monorepo) | Portable template | Used by | Agent action |
+|---------------------------|-------------------|---------|--------------|
+| `lib/customFieldValues.ts` | [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) | `SurveyPage` → `useSurveySDK` + `Question` | Copy to `src/lib/`; populate `_c_…` ids from fetched survey |
+| `lib/surveyUi/getAccentColor.ts` + `scaleValues.ts` | [`templates/surveyUiScaleUtils.ts`](../templates/surveyUiScaleUtils.ts) | NPS colors, slider tick colors, matrix column helpers | Copy to `src/lib/` or co-locate with scale components |
+| `lib/surveyUi/icons.tsx` | [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx) | CSAT emoji/star (`CsatMatrixScale`) | Copy; add `react-icons` to `package.json` |
+| `lib/surveyUi/heatmapCoords.ts` | [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts) | `HeatmapScale` | Copy to `src/lib/heatmapCoords.ts` |
+| — (wizard styling) | [`templates/selectionStyles.ts`](../templates/selectionStyles.ts) | All scale radio/numbered selections | Copy to `src/lib/surveyUi/selectionStyles.ts` |
+| — (wizard styling) | [`templates/labelStyles.ts`](../templates/labelStyles.ts) | Matrix/slider label items | Copy to `src/lib/surveyUi/labelStyles.ts` |
+
+Scale **components** live in `src/components/` — see [`component-checklist.md`](component-checklist.md). Lib files are shared utilities and CRM data, not React components.
+
+---
+
+## Recommended project layout
+
+```
+src/
+├── lib/
+│   ├── customFieldValues.ts      ← CRM map for useSurveySDK (copy template)
+│   ├── surveyUiScaleUtils.ts     ← NPS/tick/matrix helpers
+│   ├── surveyUiIcons.tsx         ← emoji/star icons (optional co-locate)
+│   ├── surveyUi/selectionStyles.ts  ← wizard: focus ring + cell selected (copy template)
+│   ├── surveyUi/labelStyles.ts        ← wizard: label item colors (copy template)
+│   └── heatmapCoords.ts          ← when survey has HEATMAP
+└── components/
+    ├── SurveyPage.tsx
+    ├── Question.tsx
+    ├── RatingScale.tsx
+    └── ...scale components from templates/
+```
+
+Placeholders follow the same stable-ref rule — define **`SURVEY_PLACEHOLDERS`** outside the component (often in `SurveyPage.tsx` module scope or a separate `lib/placeholders.ts`).
+
+---
+
+## `customFieldValues.ts` — CRM input for SDK logic
+
+Custom field values are **not** survey UI inputs. They come from CRM/transaction context (API payload, JWT claims, host app state) and are passed to the SDK so skip, display, progress, end-page, and answer logic can evaluate rules referencing `entityType: 'CUSTOM_FIELD'`.
+
+```typescript
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+import { CUSTOM_FIELD_VALUES } from '@/lib/customFieldValues';
+
+const surveyOptions = useMemo(
+  () => ({
+    instanceId,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [instanceId, selectedLanguage]
+);
+```
+
+Pass the **same map** to `Question`:
+
+```tsx
+<Question customFieldValues={CUSTOM_FIELD_VALUES} ... />
+```
+
+See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) for discovery, value shapes, and the two wiring points.
+
+---
+
+## `surveyUiScaleUtils.ts` — scale UI helpers
+
+Exports used by portable scale templates:
+
+| Export | Purpose |
+|--------|---------|
+| `getAccentColor(value)` | NPS 0–10 traffic-light badge colors |
+| `tickColorFromIndex(index, total)` | SLIDER_MATRIX header tick badge colors |
+| `matrixColumnStoredValue(col)` | Matrix answer storage — column `id` or `null` for N/A |
+| `npsValueFromOption` / `starValueFromOption` | NPS badge numeric values |
+| `nonNaScaleColumns` | Filter N/A column from scale columns |
+
+Prefer SDK `matrixColumnStoredValue` when importing from package; template re-exports the same contract for co-located components.
+
+---
+
+## `surveyUiIcons.tsx` — CSAT emoji and star icons
+
+- `getEmojiForIndex(index, totalColumns)` — CSAT emoji matrix cells
+- `CsatStarIcons` — filled/empty star nodes for `displayStyle: 'star'`
+
+Requires `react-icons` (`fa6`, `fa`).
+
+---
+
+## `heatmapCoords.ts` — normalized click coordinates
+
+Used by `HeatmapScale`:
+
+- `getNormalizedClickFromImage(event, imageElement)`
+- `findSpotNearClick(clickX, clickY, spots, imageRect)`
+- `createNewSpot(x, y)`
+
+---
+
+## Agent checklist
+
+- [ ] Copied lib templates before Phase 5 BUILD — do not read `apps/client/src/lib` at runtime
+- [ ] `customFieldValues.ts` created when survey logic references any `_c_…` custom field id
+- [ ] `CUSTOM_FIELD_VALUES` defined **outside** React components (stable ref)
+- [ ] Same map passed to `useSurveySDK` options **and** `Question` prop
+- [ ] Scale utils/icons copied when survey contains NPS, matrix emoji/star, SLIDER_MATRIX, or HEATMAP

package/templates/docs/00-integration/component-checklist.md

@@ -1,84 +1,120 @@
 # Required Component Files Checklist
 
-> **Blocking gate before Phase 5 (BUILD).** After fetching the survey with `instanceId`, list every `question.type` and ensure all required files exist.
+> **Blocking gate before Phase 5 (BUILD).** Read [`agent-operating-contract.md`](agent-operating-contract.md) §2–§3 first — do not invent files or paths from memory.
+>
+> **Wizard-ready build (Phase 5 — mandatory):** Every agent build wires live-preview contract per [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md), and [`wizard-question-type-styling.md`](wizard-question-type-styling.md) — `var(--cfm-*)`, `data-cfm-*` hooks, `selectionStyles.ts`, `labelStyles.ts`, draft `survey-ui-config.json`. Running the wizard (Phase 6b) is optional; wizard-ready artifacts are not.
+>
+> Read [`canonical-survey-fixtures.md`](canonical-survey-fixtures.md) when matrix/slider labels are missing.
 
 ## Step 1: Inventory Question Types
 
 From `survey.pages`, collect unique `question.type` values — see `MANIFEST.json` `typeLiterals`:
 
-| questionId | type |
-|------------|------|
-| | |
+| questionId | type | displayStyle / statementLayout / transposeTable |
+|------------|------|--------------------------------------------------|
+| | | |
 
-## Step 2: Create Required Files
+Note matrix variants: `displayStyle`, `statementLayout`, `transposeTable`, `selectionMode`.
 
-| If survey contains | Agent MUST create before `npm run build` | UI spec |
-|--------------------|------------------------------------------|---------|
-| `NPS_SCALE` | `RatingScale.tsx` | `03-ui-specs/01-rating.md` |
-| `CFM_MATRIX` | `LikertMatrixScale.tsx`, `MatrixDropdown.tsx` | `03-ui-specs/07-matrix-cfm.md` |
-| `CSAT_MATRIX` | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/04-csat.md` |
-| `RATING_MATRIX` | `CsatMatrixScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/08-matrix-csat-rating.md` |
-| `SLIDER_MATRIX` | `SliderMatrixScale.tsx`, `CustomSliderTrack.tsx` | `03-ui-specs/09-slider-matrix.md` |
-| `FILE_UPLOAD` | `FileUploadScale.tsx` | `03-ui-specs/10-file-upload.md` |
-| `MCQ`, `TEXTFIELD`, `TEXT_AND_MEDIA` | Inline in `Question.tsx` | `03-ui-specs/02-radio.md`, `03-text.md`, `11-text-and-media.md` |
-| `RANK_ORDER` | `RankOrderScale.tsx` (+ `@dnd-kit/*`) | `03-ui-specs/14-rank-order.md` |
-| `HEATMAP` | `HeatmapScale.tsx`, `lib/heatmapCoords.ts` (copy from `templates/heatmapCoords.ts`) | `03-ui-specs/13-heatmap.md` |
+## Step 2: Copy Portable Templates (CRITICAL)
 
-**Survey chrome (when applicable):**
+**Copy from [`templates/`](../templates/) before customizing branding.** Do not implement matrix/slider UI from scratch.
 
-| Component | When |
-|-----------|------|
-| `IntroPage.tsx` | `survey.introPage` |
-| `EndPage.tsx` | `survey.endPages` |
-| `PausedPage.tsx` | `survey.phaseFlags.paused` |
+### Copy order
 
-Always create **`Question.tsx`** from [`templates/Question.tsx`](../templates/Question.tsx).
+0. **`customFieldValues.ts`** → `src/lib/` when any `_c_…` id in survey logic (see [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md))
+0b. **`selectionStyles.ts`**, **`labelStyles.ts`** → `src/lib/surveyUi/` (**required** — see [`wizard-question-type-styling.md`](wizard-question-type-styling.md))
+1. `surveyUiScaleUtils.ts` → `src/lib/` (or co-locate with components)
+2. `surveyUiIcons.tsx` → same folder as scale components
+3. `CustomSliderTrack.tsx`, `MatrixDropdown.tsx`, `heatmapCoords.ts`
+4. Scale components per survey types
+5. `Question.tsx` from template
 
-## Flat Type Routing (CRITICAL)
+| `templates/customFieldValues.ts` | `src/lib/customFieldValues.ts` | Any `CUSTOM_FIELD` in skip/display/answer/end logic |
+| `templates/selectionStyles.ts` | `src/lib/surveyUi/selectionStyles.ts` | **Required** — radio/scale selection colors |
+| `templates/labelStyles.ts` | `src/lib/surveyUi/labelStyles.ts` | **Required** — matrix/slider label items |
+| `templates/survey-theme.css` | `src/styles/survey-theme.css` | **Required** — full `--cfm-*` defaults |
+| `templates/previewBridge.ts` | `src/lib/previewBridge.ts` | **Required** — local `customize` live preview |
 
-Use `QUESTION_TYPE` — **no `subType`**:
+See [`client-lib-folder.md`](client-lib-folder.md) for full lib layout.
 
-```tsx
-import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
+| Portable template | Copy to | When survey contains |
+|-------------------|---------|----------------------|
+| `templates/Question.tsx` | `src/components/Question.tsx` | Always |
+| `templates/RatingScale.tsx` | `src/components/RatingScale.tsx` | `NPS_SCALE` |
+| `templates/LikertMatrixScale.tsx` | `src/components/LikertMatrixScale.tsx` | `CFM_MATRIX` |
+| `templates/CsatMatrixScale.tsx` | `src/components/CsatMatrixScale.tsx` | `CSAT_MATRIX`, `RATING_MATRIX` |
+| `templates/SliderMatrixScale.tsx` | `src/components/SliderMatrixScale.tsx` | `SLIDER_MATRIX` |
+| `templates/FileUploadScale.tsx` | `src/components/FileUploadScale.tsx` | `FILE_UPLOAD` |
+| `templates/HeatmapScale.tsx` | `src/components/HeatmapScale.tsx` | `HEATMAP` |
+| `templates/RankOrderScale.tsx` | `src/components/RankOrderScale.tsx` | `RANK_ORDER` |
 
-{question.type === QUESTION_TYPE.CFM_MATRIX && (
-  <LikertMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
-)}
+### Matrix label visibility gate
 
-{(question.type === QUESTION_TYPE.CSAT_MATRIX ||
-  question.type === QUESTION_TYPE.RATING_MATRIX) && (
-  <CsatMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
-)}
-```
+Before `npm run build`, confirm every matrix question in your inventory will render:
+
+- [ ] **Row labels**: `statementRows[].statementText` in 180px (or 25% bipolar) column
+- [ ] **Column labels**: `scaleColumns[].label` header row OR `scaleAnchorLabels` anchor row
+- [ ] **Bipolar**: `oppositeStatementText` in 25% right column
+- [ ] **Transposed**: row labels from `scaleColumns[].label`; column headers from `statementRows[].statementText`
+
+### Slider visibility gate
+
+- [ ] Colored tick header row (0–10 badges from `ticks.marks`)
+- [ ] Gray row band with statement text + `CustomSliderTrack` (not orphan circle)
+
+| If survey contains | Also copy | UI spec |
+|--------------------|-----------|---------|
+| `SLIDER_MATRIX` | `CustomSliderTrack.tsx`, `surveyUiScaleUtils.ts` | `03-ui-specs/09-slider-matrix.md` |
+| `CFM_MATRIX` | `MatrixDropdown.tsx` (if dropdown layout) | `03-ui-specs/07-matrix-cfm.md` |
+| `CSAT_MATRIX` / `RATING_MATRIX` | `surveyUiIcons.tsx`, `CustomSliderTrack.tsx` (graphics) | `03-ui-specs/04-csat.md`, `08-matrix-csat-rating.md` |
+| `RANK_ORDER` | `@dnd-kit/*` in package.json | `03-ui-specs/14-rank-order.md` |
+| `HEATMAP` | `heatmapCoords.ts` | `03-ui-specs/13-heatmap.md` |
+| `MCQ`, `TEXTFIELD`, `TEXT_AND_MEDIA` | inline in `Question.tsx` | `03-ui-specs/02-radio.md`, etc. |
+
+## Flat Type Routing (CRITICAL)
+
+Use `QUESTION_TYPE` — **no `subType`**. Pass filtered matrix questions from `getVisibleMatrixItemsForAnswers`.
 
 ## Shared Primitives
 
 | File | Used by |
 |------|---------|
-| `CustomSliderTrack.tsx` | `SLIDER_MATRIX`, matrix `displayStyle: graphics` |
-| `MatrixDropdown.tsx` | `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX` dropdown/selectbox modes |
+| `CustomSliderTrack.tsx` | `SLIDER_MATRIX`, RATING/CSAT `displayStyle: graphics` |
+| `MatrixDropdown.tsx` | Matrix dropdown/selectbox modes |
+| `surveyUiScaleUtils.ts` | NPS colors, tick colors, matrix column values |
+| `surveyUiIcons.tsx` | CSAT emoji/star icons |
+| `selectionStyles.ts` | Focus ring + cell selected pattern (all scale radios) |
+| `labelStyles.ts` | Hint / column / tick label item colors |
 
 Store matrix values as column **`id`** — `matrixColumnStoredValue(col)` from SDK.
 
-## Answer logic (when survey has gated options / rows / columns)
-
-- [ ] MCQ: filter options with `getVisibleMcqOptionsForAnswers(question, answers, allQuestions, customFieldValues)`
-- [ ] Matrix (CSAT/CFM/RATING/SLIDER): filter rows (and CSAT/CFM columns) with `getVisibleMatrixItemsForAnswers(question, answers, allQuestions, customFieldValues)`
-- [ ] Pass `customFieldValues` from `SurveyPage` → `Question` when survey logic references `CUSTOM_FIELD` entities
-- [ ] Wire `onAction({ type: 'CHANGE' })` so answer logic re-evaluates when prior answers change
-
-See [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) and [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
-
 ## Step 3: Verify Before Build
 
-- [ ] Every type in the survey inventory has a matching component file
-- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` with all **11** type branches wired
-- [ ] `SurveyPage` handles all `state.phase` values
-- [ ] No `default` fallback rendering stub text (see `constraints.md` §7)
-- [ ] RANK_ORDER: `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities` in `package.json`
-- [ ] Per-type wiring verified against `question-type-sdk-matrix.md`
-- [ ] Grep project: `not yet implemented` → **zero matches**
+- [ ] Every type in survey inventory has matching component file(s)
+- [ ] **`src/lib/customFieldValues.ts`** when survey logic references `_c_…` ids
+- [ ] `CUSTOM_FIELD_VALUES` wired in `SurveyPage` hook options **and** `Question` prop
+- [ ] Matrix row + column/anchor labels visible (see canonical fixtures)
+- [ ] Slider has header + track (see canonical fixtures)
+- [ ] `Question.tsx` has `questionNumber` prefix and all 11 type branches
+- [ ] `react-icons` in package.json when CSAT/RATING/NPS emoji modes present
+- [ ] Grep: `not yet implemented` → zero matches
 
 ```bash
-grep -r "not yet implemented" src/ components/ app/ 2>/dev/null || true
+bash templates/verify-agent-build.sh
+# or from SDK package root: node_modules/@explorer02/cfm-survey-sdk/templates/docs/templates/verify-agent-build.sh
 ```
+
+## Step 4: Wizard-ready build (Phase 5 — mandatory)
+
+Read: [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md), [`wizard-question-type-styling.md`](wizard-question-type-styling.md)
+
+- [ ] `src/styles/survey-theme.css` with full `--cfm-*` set (copy from `templates/survey-theme.css`)
+- [ ] `selectionStyles.ts` + `labelStyles.ts` in `src/lib/surveyUi/`
+- [ ] Draft `./survey-ui-config.json` synced with mockup branding
+- [ ] `previewBridge.ts` + `PreviewBridgeInit` in root layout
+- [ ] Header/Footer/ProgressBar/SurveyPage use `var(--cfm-*)` — no hardcoded brand hex for wizard-controlled tokens
+- [ ] `data-cfm-logo` / `data-cfm-logo-text`, `data-cfm-company`, `data-cfm-survey-title`, `data-cfm-btn-next`, `data-cfm-btn-back`, `data-cfm-thank-you` on chrome
+- [ ] Per-type scale vars per `wizard-question-type-styling.md` for types in survey inventory
+- [ ] Selection pattern: focus ring = outer border + inner dot; cell selected = annulus fill
+- [ ] `npx cfm-sdk export-previews` succeeds from project root (when previews needed for AWS wizard)

package/templates/docs/00-integration/constraints.md

@@ -1,6 +1,7 @@
 # Critical Constraints
 
-> Non-negotiable rules. Violating any of these breaks the build or survey UX.
+> Non-negotiable rules. Violating any of these breaks the build or survey UX.  
+> Agent enforcement: [`agent-operating-contract.md`](agent-operating-contract.md) §4 hallucination blocklist.
 
 ## 1. Top-Level Imports Only
 
@@ -26,11 +27,18 @@ Every question card **must** have `id={question.id}` on its outermost element:
 
 Required for scroll-to-error when validation fails.
 
-## 4. CSS-Only Logo
+## 4. Logo (wizard-compatible)
 
-- **Never** use `<img>` with external URLs for the brand logo
-- **Never** save logo files to `public/`
-- Build logos with Tailwind CSS divs — derive design from **client prompt** (INPUT 1)
+Choose **one** pattern in `Header.tsx` — see [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) and [`10-header-footer.md`](../01-components/10-header-footer.md):
+
+| Mode | Rules |
+|------|--------|
+| **Text / CSS-only** | Build logo with HTML + CSS; use `<span data-cfm-logo-text>`. No `public/` logo file required. |
+| **Local image** | Put asset in `public/`; reference with `<img data-cfm-logo src="/your-logo.svg" />`. **Never** use external URLs (`https://…`) in the built survey. |
+
+- Do **not** drop unrelated `public/logo_*` files during agent build — CLI seeds from `Header.tsx`, not newest `logo_*`.
+- After wizard upload, `survey-ui-config.json` `global.logo.fileName` is authoritative on re-open.
+- After wizard complete, poll/final JSON includes `global.logo.url` (public CloudFront URL) for agent handoff; the agent still copies the file to `public/` and uses a local `src` in `Header.tsx`.
 
 ## 5. Client Components
 

package/templates/docs/00-integration/custom-field-logic-and-navigation.md

@@ -18,6 +18,61 @@ Survey logic rules may reference **custom fields** instead of survey questions:
 
 Inspect fetched survey data: any `skipLogics`, `displayLogic`, or `answerLogic` with `entityType: 'CUSTOM_FIELD'` requires client-supplied values.
 
+Copy portable template: [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) → `src/lib/customFieldValues.ts`. See [`client-lib-folder.md`](client-lib-folder.md).
+
+---
+
+## Agent implementation recipe
+
+1. **After fetch** — scan `survey.pages` (and `endPages` logic) for `conditionEntity.entityType === 'CUSTOM_FIELD'`. Collect every `conditionEntity.id` (`_c_…`).
+2. **Record** each id in `implementation_plan.md` §3d with `fieldType`, logic kind (skip/display/answer/end), and expected CRM value shape.
+3. **Copy** [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) → `src/lib/customFieldValues.ts`. Populate from CRM/transaction API — **not** inline in `SurveyPage`.
+4. **Wire hook** — import map and pass in stable `useMemo` options:
+
+```typescript
+import { CUSTOM_FIELD_VALUES } from '@/lib/customFieldValues';
+
+const surveyOptions = useMemo(
+  () => ({
+    instanceId,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [instanceId, selectedLanguage]
+);
+```
+
+5. **Wire Question** — pass the **same** map as `customFieldValues` prop (template `Question.tsx` already forwards it to `getVisible*ForAnswers`).
+6. **Verify** — trigger a custom-field skip rule on Next; no per-question client evaluator code needed.
+
+**Blocking gate:** if any `_c_…` id exists in fetched survey → `src/lib/customFieldValues.ts` must exist before Phase 5 BUILD.
+
+### Fixture example (integration-test survey)
+
+Page 2 `SLIDER_MATRIX` has a skip rule:
+
+```json
+{
+  "conditionEntity": {
+    "id": "_c_67199096d294be011a2b4773",
+    "entityType": "CUSTOM_FIELD",
+    "fieldType": "TEXT"
+  },
+  "field": "CASE_SENSITIVE_TEXT",
+  "values": ["abc"]
+}
+```
+
+Client map:
+
+```typescript
+export const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_67199096d294be011a2b4773': 'abc',
+};
+```
+
+When this value matches, SDK skip logic runs on Next — values must be in **hook options**, not typed by the respondent.
+
 ---
 
 ## Client value map
@@ -172,3 +227,4 @@ When a question has several `skipLogics[]` entries (including custom-field rules
 - [`display-logic-and-navigation.md`](display-logic-and-navigation.md) — question-level gating
 - [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) — option/row/column gating + visibility helpers
 - [`client-integration-guide.md`](client-integration-guide.md) — full wiring map
+- [`client-lib-folder.md`](client-lib-folder.md) — lib folder layout + portable templates

package/templates/docs/00-integration/display-logic-and-navigation.md

@@ -46,4 +46,19 @@ Display logic may gate questions on **custom field** values (`conditionEntity.en
 
 Alternate question wording (`questionDisplayVariants`) uses the same condition engine but **does not hide** the question — the SDK resolves `questionText` on `state.currentQuestions`. See [`question-display-variants.md`](question-display-variants.md).
 
-See also: [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md), [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`progress.md`](progress.md).
+See also: [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md), [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md), [`progress.md`](progress.md), [`logic-fields-catalog.md`](logic-fields-catalog.md).
+
+---
+
+## Worked example — dynamic display on same page
+
+**Setup:** Page 1 has Q1 (MCQ trigger) and Q2 (display-gated, `isDynamicAppearanceEnabled: true`). Q2 hidden until Q1 selects option A.
+
+1. User loads page → `currentQuestions` = [Q1] only; progress denominator excludes Q2.
+2. User selects A → SDK evaluates display logic → `currentQuestions` = [Q1, Q2]; Q2 animates in; progress total increases.
+3. User answers Q2 → normal CHANGE flow.
+4. User changes Q1 away from A → SDK sanitizes Q2 answer; Q2 hidden again; progress credits adjust.
+
+**Client:** render `state.currentQuestions` only — no manual show/hide. Re-run IntersectionObserver effect when `currentQuestions` changes.
+
+**Back navigation:** if display logic hides all questions on a page, SDK skips empty pages — user never sees a blank screen (see skip/display integration tests).