@explorer02/cfm-survey-sdk 0.2.3 → 0.2.5

package/templates/docs/00-integration/aws-deploy.md

@@ -110,13 +110,104 @@ Set `OUT_DIR` to `dist/`. Ensure asset paths in built HTML are **relative** (no
 
 | Rule | Detail |
 |------|--------|
-| Public logos | Use relative paths (`logo.svg`), not `/logo.svg` |
+| Public logos | Use **relative** paths (`./logo.svg` for AWS static export), not `/logo.svg` or `https://…` |
+| Wizard logos | Must exist in `public/` **and** `out/` before deploy — see § Logos & local assets below |
 | Rank-order images | Prefer `option.imageUrl` over `option.previewImageUrl` — preview `*_p.*` URLs often return 403 |
 | Footer hash links | Use plain `<a href="#">`, not `next/link` — avoids RSC prefetch on static export |
 | No AWS keys in code | JWT only in `Authorization: Bearer` header at deploy time |
 
 ---
 
+## Logos & local assets (wizard → S3 → CloudFront)
+
+### Why logos break on CloudFront
+
+The wizard **preview** shows logos from **browser memory** (`data:` URLs / base64). That works on `localhost:4200` only. CloudFront serves files from the **deploy bundle** at:
+
+```
+https://<cloudfront>/sites/{surveyId}/{deployId}/<filename>
+```
+
+It does **not** read wizard preview memory, and it does **not** automatically include logos stored under the separate wizard asset path (`sites/{surveyId}/assets/{fileName}`). Those S3 assets are for wizard handoff / re-download — the agent must copy the file into `public/` and ship it inside `out/` on every deploy.
+
+```mermaid
+flowchart LR
+  subgraph wizard [Wizard session]
+    Upload[Client uploads logo]
+    Mem[Preview: base64 in memory]
+    Disk[public/logo_*.jpg local OR S3 assets/ EC2]
+  end
+  subgraph agent [Agent Phase 6c]
+    Apply[Header data-cfm-logo src=./fileName]
+    Build[yarn build copies public to out/]
+  end
+  subgraph deploy [Phase 7 AWS]
+    S3[sites/surveyId/deployId/logo_*.jpg]
+    CF[CloudFront serves same prefix as index.html]
+  end
+  Upload --> Mem
+  Upload --> Disk
+  Disk --> Apply
+  Apply --> Build
+  Build --> S3
+  S3 --> CF
+```
+
+### Two storage locations (do not confuse)
+
+| Location | When written | Served on live survey? |
+|----------|--------------|------------------------|
+| `public/{fileName}` on dev machine | `customize` upload-logo API, or `confirm-ui-config` download | **Only after** `build` copies into `out/` and deploy uploads |
+| `sites/{surveyId}/assets/{fileName}` on S3 | EC2 wizard **Review & Build** complete | **No** — not in deploy prefix; use only as download source for `confirm-ui-config` |
+
+### Correct agent flow (mandatory when wizard uploaded a logo)
+
+**After Phase 6c apply, before Phase 7 deploy:**
+
+1. Read `global.logo.fileName` from `survey-ui-config.json` (local) or `.final.json` (EC2).
+2. Ensure the binary exists in `public/{fileName}`:
+   - **Local `customize`:** file written by `POST /api/upload-logo` when client uploaded in wizard.
+   - **EC2 `customize-ui`:** run `npx cfm-sdk confirm-ui-config` — downloads from `global.logo.url` (CloudFront assets URL) to `public/`.
+3. Update `Header.tsx`:
+
+```tsx
+<img data-cfm-logo src="./logo_1783069846059_download2.jpg" alt="Brand" />
+```
+
+Use `./{fileName}` for AWS static export (`assetPrefix: './'`). **Never** set `src` to:
+- `global.logo.url` when it is a `data:` URL (preview memory)
+- `https://…/sites/.../assets/...` (wrong path — outside deploy folder)
+- `/logo.png` (absolute — breaks under nested CloudFront prefix)
+
+4. Rebuild and verify file is in static output:
+
+```bash
+yarn build
+LOGO=$(python3 -c "import json; print(json.load(open('survey-ui-config.json'))['global']['logo']['fileName'])")
+test -f "public/$LOGO" && test -f "out/$LOGO" && echo "Logo ready for deploy"
+```
+
+5. Deploy — `deploy-to-aws.sh` uploads **every file under `out/`**, including the logo.
+
+6. Post-deploy verify (same deploy prefix as `index.html`):
+
+```bash
+# If index.html is .../66593925-.../index.html, logo must be:
+# .../66593925-.../logo_*.jpg  → HTTP 200
+```
+
+### Pre-deploy checklist (logo)
+
+- [ ] `global.logo.fileName` set in active config
+- [ ] `public/{fileName}` exists on disk
+- [ ] `Header.tsx` `data-cfm-logo` `src="./{fileName}"` (or `./your-seed-logo.svg` if no wizard upload)
+- [ ] `out/{fileName}` exists after `yarn build`
+- [ ] No `data:` or `https://` logo `src` in Header/Footer
+
+See also: [`apply-ui-config.md`](apply-ui-config.md) § Logo file, [`wizard-config-handoff.md`](wizard-config-handoff.md) § Logo capture.
+
+---
+
 ## Deploy Procedure (agent executes in order)
 
 ### Step 0 — Build
@@ -253,7 +344,26 @@ bash templates/deploy-to-aws.sh
 
 ---
 
-## Repeat Deploys
+## EC2 operator setup (one-time)
+
+On `43.204.26.213`, `/home/ec2-user/deploy-api/.env` must use **real** CloudFront values (not `.env.example` placeholders):
+
+```bash
+HOSTING_BUCKET=sprinklr-cfm-survey-sites-prod-unnat
+CLOUDFRONT_DISTRIBUTION_ID=EY6QXOHVFMVZ2
+CLOUDFRONT_BASE_URL=https://d81qbkjijbkjd.cloudfront.net
+```
+
+Verify after `pm2 restart sprinklr-api`:
+
+```bash
+curl -s http://43.204.26.213:3000/health/cloudfront | python3 -m json.tool
+# expect "ok": true
+```
+
+Placeholder IDs like `E1234567890ABC` cause `STORAGE_UNAVAILABLE` on `/deploy/complete` even when S3 uploads succeed.
+
+---
 
 Each deploy creates a **new** `deployId` folder under `sites/{surveyId}/`. Old deploys remain in S3.
 
@@ -269,9 +379,13 @@ After UI changes: rebuild → re-run Steps 1–3 (same `CFM_INSTANCE_ID` if same
 | 403 on `index.html.txt?_rsc` | Missing RSC payload file | Add `cp out/index.txt out/index.html.txt` to build script |
 | 403 on `*_p.png` / `*_p.jpg` images | Preview URL used | Use `option.imageUrl \|\| option.previewImageUrl` in RankOrderScale |
 | 401 `TOKEN_EXPIRED` | JWT expired | Ask client for new instanceId |
-| 503 `DEPLOY_UNAVAILABLE` | EC2 CloudFront/S3 env wrong | Report to operator |
+| 503 `STORAGE_UNAVAILABLE` on `/deploy/complete` | EC2 `.env` has placeholder `CLOUDFRONT_*` values | Fix `.env` with real distribution ID + domain; `pm2 restart` |
+| 503 `DEPLOY_UNAVAILABLE` | EC2 hosting env misconfigured — report to operator |
 | Some PUTs 403 | Presigned URLs expired (default 5 min) | Restart from Step 1; complete within window |
 | Blank page, HTML 200 | JS/CSS not uploaded or wrong paths | Re-check Channel 2 logs |
+| Broken logo on live site, HTML 200 | Logo only in wizard preview memory or wrong `src` | Apply `global.logo.fileName` to `data-cfm-logo` as `./fileName`; verify `out/{fileName}` before deploy |
+| Logo 404 under deploy URL | File not in `out/` or absolute `/logo.png` path | Rebuild after copying to `public/`; use `./fileName` not `/fileName` |
+| Used `global.logo.url` as img src | Often `data:` base64 or `/assets/` path outside deploy | Use local `./fileName` only — see § Logos & local assets |
 | Survey API errors in browser | Deploy JWT ≠ SurveyPage JWT | Align `SURVEY_INSTANCE_ID` |
 
 ---

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) |
@@ -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,94 +1,122 @@
 # 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`.
 
-**Copy portable templates from [`templates/`](../templates/) when available** — then customize branding. Otherwise implement from ui-spec Implementation Recipe.
+## Step 2: Copy Portable Templates (CRITICAL)
 
-| Portable template | Copy to |
-|-------------------|---------|
-| `templates/Question.tsx` | `src/components/Question.tsx` |
-| `templates/RankOrderScale.tsx` | `src/components/RankOrderScale.tsx` |
-| `templates/MatrixDropdown.tsx` | `src/components/MatrixDropdown.tsx` |
-| `templates/CustomSliderTrack.tsx` + `surveyUiIcons.tsx` | same folder |
-| `templates/heatmapCoords.ts` | `src/lib/heatmapCoords.ts` |
+**Copy from [`templates/`](../templates/) before customizing branding.** Do not implement matrix/slider UI from scratch.
 
-| 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` |
+### Copy order
 
-**Survey chrome (when applicable):**
+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
 
-| Component | When |
-|-----------|------|
-| `IntroPage.tsx` | `survey.introPage` |
-| `EndPage.tsx` | `survey.endPages` |
-| `PausedPage.tsx` | `survey.phaseFlags.paused` |
+| `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 |
 
-Always create **`Question.tsx`** from [`templates/Question.tsx`](../templates/Question.tsx).
+See [`client-lib-folder.md`](client-lib-folder.md) for full lib layout.
 
-## Flat Type Routing (CRITICAL)
+| 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` |
 
-Use `QUESTION_TYPE` — **no `subType`**:
+### Matrix label visibility gate
 
-```tsx
-import { QUESTION_TYPE } from '@explorer02/cfm-survey-sdk';
+Before `npm run build`, confirm every matrix question in your inventory will render:
 
-{question.type === QUESTION_TYPE.CFM_MATRIX && (
-  <LikertMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
-)}
+- [ ] **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`
 
-{(question.type === QUESTION_TYPE.CSAT_MATRIX ||
-  question.type === QUESTION_TYPE.RATING_MATRIX) && (
-  <CsatMatrixScale question={question} selectedValue={...} onSelect={onSelect} />
-)}
-```
+### 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 — keys from **fetch**, wire hook + Question ([`placeholders-and-custom-fields-wiring.md`](00-integration/placeholders-and-custom-fields-wiring.md))
+- [ ] **`SURVEY_PLACEHOLDERS`** keys discovered from fetched `{{TOKEN}}` text — not mockup
+- [ ] `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
+- [ ] **Layout toggles:** `data-cfm-progress`, `[data-cfm-question-number]`, `[data-cfm-required]`, `.cfm-footer` — see `wizard-troubleshooting.md` §3
+- [ ] Per-type scale vars per `wizard-question-type-styling.md` for **all 11 types** (wizard exports all; survey inventory may be smaller)
+- [ ] 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,19 @@ 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" />` for local dev. For **AWS static export**, use `src="./your-logo.svg"` (relative — required under `/sites/{surveyId}/{deployId}/`). **Never** use external URLs (`https://…`) or wizard `data:` URLs 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.
+- Wizard preview shows logo from **browser memory**; CloudFront serves only files in the **deploy bundle** (`out/` → S3 `sites/{surveyId}/{deployId}/`). See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+- After EC2 wizard complete, poll/final JSON includes `global.logo.url` (CloudFront `/assets/` URL) — agent downloads to `public/` via `confirm-ui-config`; still use `./{fileName}` in `Header.tsx`, not the assets URL.
 
 ## 5. Client Components