@explorer02/cfm-survey-sdk 0.2.2 → 0.2.4

package/templates/docs/00-integration/file-upload-aws.md

@@ -0,0 +1,116 @@
+# File Upload — Presigned S3 Flow
+
+> Required for **submittable** file-upload answers. Raw `File[]` in `state.answers` is **dropped** at submit — SDK expects `UploadedFileAnswer[]` with `id` and `mediaUrl`.
+
+Related: [`03-ui-specs/10-file-upload.md`](../03-ui-specs/10-file-upload.md) · [`02-reference/question-types/11-file-upload.md`](../02-reference/question-types/11-file-upload.md)
+
+---
+
+## Answer contract
+
+```typescript
+type UploadedFileAnswer = {
+  id: string;
+  mediaUrl: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
+};
+
+onAction({
+  type: 'CHANGE',
+  payload: { questionId, answerValue: UploadedFileAnswer[] },
+});
+```
+
+Submit formatter maps to `quesIdVsAttachmentDetails[questionId]`.
+
+---
+
+## Upload API (EC2 reference — Day 22)
+
+**Base URL:** configure via env (example: `http://43.204.26.213:3000` or project-specific upload service).
+
+### Step 1 — Request presigned URL
+
+```http
+POST /get-upload-url
+Content-Type: application/json
+
+{
+  "fileName": "report.pdf",
+  "contentType": "application/pdf",
+  "questionId": "<question.id>"
+}
+```
+
+**Response:**
+
+```json
+{
+  "uploadUrl": "https://s3.amazonaws.com/...",
+  "fileId": "generated-id",
+  "mediaUrl": "https://cdn.../path/to/file"
+}
+```
+
+### Step 2 — PUT file to S3
+
+```http
+PUT {uploadUrl}
+Content-Type: application/pdf
+Body: <file binary>
+```
+
+### Step 3 — Update SDK state
+
+Append to answer array and call `onAction(CHANGE)` with `{ id: fileId, mediaUrl, name, mimeType, size }`.
+
+---
+
+## Client implementation sketch
+
+```typescript
+async function uploadFile(file: File, questionId: string): Promise<UploadedFileAnswer> {
+  const res = await fetch(`${UPLOAD_API_BASE}/get-upload-url`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      fileName: file.name,
+      contentType: file.type,
+      questionId,
+    }),
+  });
+  const { uploadUrl, fileId, mediaUrl } = await res.json();
+  await fetch(uploadUrl, { method: 'PUT', body: file, headers: { 'Content-Type': file.type } });
+  return { id: fileId, mediaUrl, name: file.name, mimeType: file.type, size: file.size };
+}
+```
+
+Wire `UPLOAD_API_BASE` from env — **never** embed AWS credentials in client code.
+
+---
+
+## UI states
+
+| State | UX |
+|-------|-----|
+| Uploading | Spinner on file row; disable dropzone |
+| Success | Show file in list; call `onAction(CHANGE)` |
+| Failure | Red banner; keep local file uncommitted |
+| Remove | Update array; `undefined` when empty |
+
+---
+
+## Partial save
+
+Only call `onAction(CHANGE)` after upload completes — partial save should not POST raw `File` blobs.
+
+---
+
+## Agent checklist
+
+- [ ] Local validation before upload (format, count, size)
+- [ ] Presigned PUT wired per file
+- [ ] Final answer is `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Submit body includes attachments (verify in network tab)

package/templates/docs/00-integration/logic-fields-catalog.md

@@ -0,0 +1,105 @@
+# Logic Fields Catalog
+
+> Central reference for skip, display, answer, variant, and end-page logic fields by question type. Agents do **not** implement evaluators — wire UI + hook; SDK evaluates conditions.
+
+Cross-links: [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md) · [`display-logic-and-navigation.md`](display-logic-and-navigation.md) · [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md) · [`end-page-logic.md`](end-page-logic.md)
+
+---
+
+## MCQ
+
+| Field | Used in | Operators | Notes |
+|-------|---------|-----------|-------|
+| `SELECTED_OPTIONS` / option id | skip, display, end | contains, does not contain, equals | Single or multi option ids |
+| `NUM_OF_SELECTED_OPTIONS` | skip, display, end | `EQUALS`, `GT`, `LT`, etc. | Count of selected option ids; zero = missing for EXISTS |
+| Option-level answer logic | answer (UI) | same engine | `getVisibleMcqOptionsForAnswers` |
+
+---
+
+## TEXTFIELD / TEXT_AND_MEDIA
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `TEXT` / `CASE_SENSITIVE_TEXT` | skip, display, end | empty, contains, equals, etc. |
+| TEXT_AND_MEDIA | — | no answer stored |
+
+---
+
+## NPS_SCALE
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `TEN_POINT_SCALE` / scale value | skip, display, end | numeric compare `<`, `>`, `==`, `!=` |
+| Scale point answer logic | answer (UI) | `getVisibleScaleColumnsForAnswers` |
+
+---
+
+## CFM_MATRIX / CSAT_MATRIX / RATING_MATRIX
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| Per-row composite keys | skip, display | per statement row + column id |
+| Matrix cell values | skip, display | numeric or column id match |
+| Row/column answer logic | answer (UI) | `getVisibleMatrixItemsForAnswers` |
+
+Store answers as column **`id`** via `matrixColumnStoredValue`.
+
+---
+
+## SLIDER_MATRIX
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| Row statement values | skip, display | numeric compare |
+| Row answer logic | answer (UI) | `getVisibleStatementRowsForAnswers` |
+
+---
+
+## FILE_UPLOAD
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| Presence only | skip, display | `EXISTS`, `MISSING` |
+| Evaluation | on page entry | no discrete value-change events |
+
+---
+
+## HEATMAP
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `HEATMAP` | skip, display | spot count, presence |
+| `HEATMAP_REGION` | skip, display | region label match |
+
+Regions are **logic-only** — not rendered on respondent UI.
+
+---
+
+## RANK_ORDER
+
+| Field | Used in | Operators |
+|-------|---------|-----------|
+| `RANK_ORDER` (per option) | skip, display, answer | ranked as (`EQUALS`), ranked more/less than (`GT`/`LT`), ranked above/below (`BEFORE`/`AFTER`) |
+| Whole question | skip, display | `EXISTS`, `MISSING` |
+
+See [`02-reference/question-types/13-rank-order.md`](../02-reference/question-types/13-rank-order.md).
+
+---
+
+## CUSTOM_FIELD (all types)
+
+| Field | Used in | Value shapes |
+|-------|---------|--------------|
+| `_c_*` entity ids | skip, display, end, answer | TEXT, NUMBER, PICKLIST, DATETIME, multiselect |
+
+Pass stable `customFieldValues` to hook **and** visibility helpers. See [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
+
+---
+
+## Client wiring summary
+
+| Logic kind | Client action |
+|------------|---------------|
+| Skip / display / end / variants | Render `state.currentQuestions`; no client evaluators |
+| Answer logic | `getVisible*ForAnswers(..., customFieldValues?)` before render |
+| Custom fields | Two wiring points: hook options + Question visibility helpers |

package/templates/docs/00-integration/partial-save-and-recovery.md

@@ -63,6 +63,30 @@ Do not block navigation (NEXT/PREVIOUS) on partial save failure unless product e
 
 ---
 
+## Per-type debounce guidance
+
+| Question type | Client UI note |
+|---------------|----------------|
+| TEXTFIELD (long) | Debounce `onAction(CHANGE)` 300–500 ms to reduce partial-save churn |
+| SLIDER_MATRIX / graphics | Debounce slider `onChange` or rely on SDK debounce |
+| FILE_UPLOAD | Call `CHANGE` only **after** presigned upload completes — see [`file-upload-aws.md`](file-upload-aws.md) |
+| MCQ / matrix | Immediate `CHANGE` on selection is fine |
+| TEXT_AND_MEDIA | No CHANGE — excluded from partial save payload |
+
+---
+
+## Recovery (honest scope)
+
+Reload behavior depends on **backend** + instance configuration — the SDK debounces POST to `responseV2` with `surveySubmitted: false` but does not implement client-side resume UI. If product requires resume:
+
+- Enable `savePartialResponse`
+- Optionally show `partialSaveResults` status
+- Confirm with backend team whether refetch restores `state.answers`
+
+Path-change sanitization (skip/display) clears off-path answers before partial save — see [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md).
+
+---
+
 ## Verify checklist
 
 - [ ] `savePartialResponse` only set when required

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

@@ -52,10 +52,12 @@ Survey: 4 questions on active path (Q1–Q4 sequential).
 
 ## UI wiring
 
+On the **content** phase, render progress inside sticky chrome so it stays visible when scrolling to the last question on a page:
+
 ```tsx
-<ProgressBar progressPercentage={state.progressPercentage} />
+<SurveyStickyChrome progressPercentage={state.progressPercentage} />
 ```
 
-See [`01-components/11-progress-bar.md`](../01-components/11-progress-bar.md) and [`03-ui-specs/12-survey-chrome.md`](../03-ui-specs/12-survey-chrome.md).
+See [`01-components/19-survey-sticky-chrome.md`](../01-components/19-survey-sticky-chrome.md), [`01-components/11-progress-bar.md`](../01-components/11-progress-bar.md), and [`03-ui-specs/12-survey-chrome.md`](../03-ui-specs/12-survey-chrome.md).
 
 See also: [`skip-logic-and-navigation.md`](skip-logic-and-navigation.md).

package/templates/docs/00-integration/question-type-sdk-matrix.md

@@ -38,7 +38,9 @@ Legend: **opt** = option-level; **row+col** = statement rows and scale columns;
 | **Value derivation** | Store `option.id`; SDK maps to API value at submit |
 | **Performance notes** | Filter options once per render via helper; avoid re-fetch on option click |
 | **Docs to read** | [`02-question.md`](../01-components/02-question.md) · [`question-types/README.md#mcq`](../02-reference/question-types/README.md#mcq) · [`02-radio.md`](../03-ui-specs/02-radio.md) |
-| **Known limitations** | Multi-select array shape is client responsibility; verify `selectionMode` from survey config |
+| **Default answers** | SDK `applyMcqDefaults` seeds `state.answers` from `defaultOptionIds` on load — client binds `selectedValue` only |
+| **Answer conditions** | SDK validates `minSelections` / `maxSelections` on NEXT; client blocks add at max + shows `validationError` |
+| **Known limitations** | Multi-select stores `string[]`; use `selectionMode` not `isMultiSelect` |
 
 ---
 
@@ -160,18 +162,18 @@ Legend: **opt** = option-level; **row+col** = statement rows and scale columns;
 
 | Column | Value |
 |--------|-------|
-| **SDK type + answer shape** | `FileUploadQuestion`; answer `UploadedFile[]` |
+| **SDK type + answer shape** | `FileUploadQuestion`; answer `UploadedFileAnswer[]` (`{ id, mediaUrl, name?, mimeType?, size? }`) |
 | **Component file(s)** | `FileUploadScale.tsx` |
 | **Dispatcher branch** | `QUESTION_TYPE.FILE_UPLOAD` / `'FILE_UPLOAD'` |
 | **Visibility helper** | None |
 | **Answer logic scope** | None |
 | **Skip / display / variants / numbering** | SDK auto |
 | **Custom field logic** | Skip/display only |
-| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: UploadedFile[] } }` after upload completes |
-| **Value derivation** | SDK submit maps file metadata to API |
-| **Performance notes** | Upload to presigned URL before CHANGE; show progress UI |
-| **Docs to read** | [`08-file-upload-scale.md`](../01-components/08-file-upload-scale.md) · [`11-file-upload.md`](../02-reference/question-types/11-file-upload.md) · [`10-file-upload.md`](../03-ui-specs/10-file-upload.md) |
-| **Known limitations** | Blocking question — validate file count/size client-side per config |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswer[] } }` **after** presigned upload completes |
+| **Value derivation** | SDK submit maps to `quesIdVsAttachmentDetails` — raw `File[]` is **not submitted** |
+| **Performance notes** | Local validate → POST presigned URL → PUT file → then CHANGE; show progress UI |
+| **Docs to read** | [`file-upload-aws.md`](file-upload-aws.md) · [`08-file-upload-scale.md`](../01-components/08-file-upload-scale.md) · [`11-file-upload.md`](../02-reference/question-types/11-file-upload.md) · [`10-file-upload.md`](../03-ui-specs/10-file-upload.md) |
+| **Known limitations** | Must wire upload API; see [`file-upload-aws.md`](file-upload-aws.md) |
 
 ---
 
@@ -198,14 +200,14 @@ Legend: **opt** = option-level; **row+col** = statement rows and scale columns;
 
 | Column | Value |
 |--------|-------|
-| **SDK type + answer shape** | `HeatmapQuestion`; answer `HeatmapAnswer` (`{ clicks: HeatmapClickPoint[] }`) |
+| **SDK type + answer shape** | `HeatmapQuestion`; answer `HeatmapClickPoint[]` (array of `{ id, x, y }` normalized 0–1) |
 | **Component file(s)** | `HeatmapScale.tsx` + portable coord helper (see [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts)) |
 | **Dispatcher branch** | `QUESTION_TYPE.HEATMAP` / `'HEATMAP'` |
 | **Visibility helper** | None |
 | **Answer logic scope** | None |
 | **Skip / display / variants / numbering** | SDK auto |
 | **Custom field logic** | Skip/display only |
-| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: HeatmapAnswer } }` on each click add/remove |
+| **`onAction` pattern** | `{ type: 'CHANGE', payload: { questionId, answerValue: HeatmapClickPoint[] \| undefined } }` on each click add/remove |
 | **Value derivation** | Normalized 0–1 coordinates; respect `maxClicksAllowed` |
 | **Performance notes** | Normalize coords on image load; use `findSpotNearClick` for hit testing |
 | **Docs to read** | [`17-heatmap-scale.md`](../01-components/17-heatmap-scale.md) · [`12-heatmap.md`](../02-reference/question-types/12-heatmap.md) · [`13-heatmap.md`](../03-ui-specs/13-heatmap.md) |

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

@@ -132,21 +132,33 @@ else                           → ask client which React setup to use
 
 For **existing apps**, read `package.json` and project structure — do not scaffold from scratch unless the client asks.
 
+### Recommended `src/lib/` scaffold
+
+```
+src/lib/
+├── customFieldValues.ts      ← templates/customFieldValues.ts (when CUSTOM_FIELD logic)
+├── surveyUiScaleUtils.ts     ← templates/surveyUiScaleUtils.ts
+├── surveyUiIcons.tsx         ← templates/surveyUiIcons.tsx (optional co-locate)
+└── heatmapCoords.ts          ← templates/heatmapCoords.ts (HEATMAP only)
+```
+
+See [`client-lib-folder.md`](client-lib-folder.md).
+
 ---
 
 ## Survey-type conditional dependencies
 
 After fetching the survey, install extra packages only when those types appear:
 
-### RANK_ORDER — drag-and-drop mode
+### RANK_ORDER — dnd-kit (required when survey contains RANK_ORDER)
 
-When the survey contains `RANK_ORDER` with `interactionMode: 'dragAndDrop'` (or you implement drag UI):
+Install whenever the survey inventory includes **`RANK_ORDER`** — the portable template supports both dropdown and drag-and-drop modes:
 
 ```bash
 npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
 ```
 
-See [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md) and [`question-type-sdk-matrix.md#rank_order`](question-type-sdk-matrix.md#rank_order).
+Copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx) before building. See [`18-rank-order-scale.md`](../01-components/18-rank-order-scale.md).
 
 ### HEATMAP — coordinate normalization
 

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

@@ -77,4 +77,4 @@ Event: `optional_question_skipped` with `questionId` and `pageIndex`.
 - Use `state.canGoBack` for the Back button (not `currentPageIndex === 0`).
 - Use `state.primaryButtonType` for Next vs Submit label; SDK maps `NEXT` → `SUBMIT` on the last page when appropriate.
 
-See also: [`progress.md`](progress.md), [`useSurveySDK.md`](useSurveySDK.md), [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md).
+See also: [`progress.md`](progress.md), [`useSurveySDK.md`](useSurveySDK.md), [`display-logic-and-navigation.md`](display-logic-and-navigation.md), [`answer-logic-and-navigation.md`](answer-logic-and-navigation.md), [`logic-fields-catalog.md`](logic-fields-catalog.md).

package/templates/docs/00-integration/survey-lifecycle-analytics.md

@@ -79,7 +79,7 @@ useEffect(() => {
 
 ## Debug: `logic_session_summary`
 
-When `debug: true` is set in hook options, the SDK emits structured console events including lifecycle transitions. Cross-reference event names in [`useSurveySDK.md`](useSurveySDK.md) during integration testing.
+When `debug: true` is set in hook options, the SDK emits structured console events including lifecycle transitions. Full event catalog: [`analytics-events-catalog.md`](analytics-events-catalog.md).
 
 ---
 

package/templates/docs/00-integration/ui-customization-wizard.md

@@ -0,0 +1,144 @@
+# UI Customization Wizard
+
+> Optional **run** after Phase 6 verify. **Wizard-ready build** is mandatory in Phase 5 — see [`agent-execution-flow.md`](agent-execution-flow.md).  
+> **Wait + apply protocol:** [`wizard-config-handoff.md`](wizard-config-handoff.md).
+
+**Before the client opts in:** agents must already have wired [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) artifacts so AWS wizard previews update live (`--cfm-*` CSS vars + `data-cfm-*` content hooks).
+
+## When to Use
+
+After **Phase 6** (verify + `npm run dev`), ask the client:
+
+> *"Your survey is running locally. Would you like to customize the UI through the web wizard?"*
+
+- **Yes** → Phase 6b: run `npx cfm-sdk customize-ui` (AWS) or `customize` (local)
+- **No** → proceed to Phase 7 deploy
+
+## AWS flow (production) — agent waits for client
+
+```bash
+export CFM_INSTANCE_ID="..." CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+```
+
+**Default = review mode.** The CLI:
+
+1. Resolves seed config from project (`survey-ui-config.json` → `survey-theme.css` → `Header.tsx` → defaults)
+2. Exports component preview pages (`export-previews`) — one HTML per preview key (`header`, `footer`, `MCQ_single`, …)
+3. Uploads preview HTML to S3 via EC2 API (`POST /wizard/session/start` → presigned PUTs → `upload/complete`)
+4. Prints the **deployed wizard link** and opens it for the agent — **agent must copy this link to the client**
+5. **Polls until client submits** (`GET /wizard/config/:surveyId` → `status: ready`)
+6. Writes review artifacts — **does not auto-apply to codebase**
+
+### Client wizard link (after S3 upload)
+
+Once previews are on S3, the CLI prints:
+
+```
+✅ Previews uploaded
+🔗 Client wizard link — share with the client:
+   http://43.204.26.213:3000/wizard-app/index.html?session=<uuid>&secret=<hex>
+```
+
+| Who | Uses |
+|-----|------|
+| **Client** | Opens the **deployed EC2 wizard link** only — customizes branding, colors, question-type tokens; previews update live from S3-backed component pages |
+| **Agent** | Keeps `customize-ui` running (polls API); does **not** ask client to use localhost |
+
+**URL shape:** `{CFM_DEPLOY_API_BASE}/wizard-app/index.html?session={sessionId}&secret={sessionSecret}`
+
+Default production API: `http://43.204.26.213:3000` (see `MANIFEST.json` `apiBaseDefault`).
+
+**Agent script (after CLI prints the link):**
+
+> *"I've uploaded your survey component previews. Open this link to customize the UI: [paste wizard URL]. When you're done, click **Review & Build** on the last step. I'll wait here until your changes are saved."*
+
+**On success, CLI prints:**
+```
+✅ Configuration ready
+   Final: survey-ui-config.final.json
+   Diff:  survey-ui-config.diff.md
+   Apply when ready: npx cfm-sdk confirm-ui-config
+```
+
+**Agent must:**
+- [ ] Keep terminal open until CLI exits 0
+- [ ] **Copy the deployed wizard link from CLI output and send it to the client** (after previews upload to S3)
+- [ ] Tell client: *"Please complete the wizard and click Review & Build."*
+- [ ] Read `survey-ui-config.diff.md` before Phase 6c
+- [ ] Apply codebase per [`apply-ui-config.md`](apply-ui-config.md) from **`.final.json`**
+- [ ] Run `npx cfm-sdk confirm-ui-config` after codebase apply
+
+See [`wizard-config-handoff.md`](wizard-config-handoff.md) for full handoff checklist.
+
+### Legacy immediate write
+
+```bash
+npx cfm-sdk customize-ui --apply
+```
+
+Writes `survey-ui-config.json` + logo immediately (no diff review). Phase 6c apply still required.
+
+### Detached session
+
+```bash
+npx cfm-sdk customize-ui --no-wait
+# Later, when client done:
+export CFM_WIZARD_SESSION_ID="..."
+npx cfm-sdk fetch-ui-config
+```
+
+## Local flow (development)
+
+```bash
+npx cfm-sdk customize
+```
+
+Opens browser at `http://localhost:4200`. **Blocks** until client saves → writes `survey-ui-config.json` directly. Then Phase 6c apply from that file (no `confirm-ui-config`).
+
+## Seed config
+
+| Priority | Source |
+|----------|--------|
+| 1 | `./survey-ui-config.json` (draft) |
+| 2 | `src/styles/survey-theme.css` (`--cfm-*` vars) |
+| 3 | `implementation_plan.md` branding hints |
+| 4 | `Header.tsx` — `data-cfm-logo` / `data-cfm-logo-text` |
+| 5 | SDK defaults |
+
+Debug: `npx cfm-sdk resolve-ui-config --write`
+
+## Wizard Steps
+
+| Step | Controls |
+|------|----------|
+| Identity | Survey title, company name, tab title, thank-you message |
+| Logo | Upload → S3 (AWS) or `public/` (local) |
+| Header / Footer | Logo box, company, links, copyright, colors |
+| Theme & Colors | Presets, palette, question card (cell selected + focus ring) |
+| Layout & Chrome | Header/footer toggles, nav, width, font |
+| Question Types | Per-type tokens + format preview tabs |
+| Testing & Tokens | Placeholders, custom fields, debug |
+| Deploy | AWS or Vercel target |
+| Review & Build | **Client submits** — triggers CLI poll success |
+
+## Output artifacts
+
+| File | When |
+|------|------|
+| `survey-ui-config.final.json` | AWS — client's submitted config (apply source) |
+| `survey-ui-config.diff.md` | AWS — every changed path (audit before apply) |
+| `survey-ui-config.json` | Active config (seed until `confirm-ui-config`; or final for local/`--apply`) |
+
+Apply tokens per [`apply-ui-config.md`](apply-ui-config.md).
+
+## Agent Checklist
+
+- [ ] Phase 5: components wired per [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md)
+- [ ] Client opted in after localhost preview (INPUT 3)
+- [ ] Ran `customize-ui` or `customize` and **waited** for CLI exit 0
+- [ ] Read `survey-ui-config.diff.md` (AWS review mode)
+- [ ] Phase 6c: applied **all** diff paths per [`apply-ui-config.md`](apply-ui-config.md)
+- [ ] AWS: ran `confirm-ui-config` after codebase apply
+- [ ] Re-ran verify script + build
+- [ ] Did not modify SDK integration (`onAction`, dispatch logic)

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

@@ -88,7 +88,41 @@ Missing ids in the map are treated as empty for logic evaluation.
 
 When the survey uses custom-field logic, also pass the same map into `Question.tsx` visibility helpers — see [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md).
 
-## Return Shape
+---
+
+## Custom field values (required when survey uses CRM logic)
+
+Custom field values are **not** survey UI inputs — they come from CRM/transaction context (host app API, JWT claims, etc.) and enable SDK evaluation of rules where `entityType: 'CUSTOM_FIELD'`.
+
+| Situation | Action |
+|-----------|--------|
+| No `_c_…` ids in fetched survey logic | `customFieldValues: {}` or omit — empty map is fine |
+| Any skip/display/answer/end rule references `CUSTOM_FIELD` | **Required** — copy [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) → `src/lib/customFieldValues.ts` |
+
+### Import and wire (two places)
+
+```typescript
+import { CUSTOM_FIELD_VALUES } from '@/lib/customFieldValues';
+
+// 1. Hook options (skip, display, progress, validation, end-page logic)
+const surveyOptions = useMemo(
+  () => ({
+    instanceId,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [instanceId, selectedLanguage]
+);
+
+// 2. Question prop (answer-logic UI — same map)
+<Question customFieldValues={CUSTOM_FIELD_VALUES} ... />
+```
+
+**Both wiring points are mandatory** when custom-field logic exists. Hook-only wiring breaks answer-logic UI; Question-only wiring breaks skip/display/progress.
+
+Discovery steps: [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) · lib layout: [`client-lib-folder.md`](client-lib-folder.md).
+
+---
 
 | Namespace | Field | Type | Purpose |
 |-----------|-------|------|---------|