@explorer02/cfm-survey-sdk 0.2.3 → 0.2.5

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) and **[`placeholders-and-custom-fields-wiring.md`](placeholders-and-custom-fields-wiring.md)** for precise key discovery and two-point wiring.
+
+---
+
+## 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/mockup-ui-extraction.md

@@ -0,0 +1,113 @@
+# Mockup & Client Prompt — UI-Only Extraction
+
+> **Read in Phase 0–4** before fetch and before filling `implementation_plan.md`.  
+> Pipeline: [`agent-operating-contract.md`](agent-operating-contract.md) · [`agent-execution-flow.md`](agent-execution-flow.md)
+
+Client mockup images and prompts are **visual references** for chrome and styling. They are **not** the survey definition. Logic, language, question inventory, and CRM data come **only** from the fetched survey (JWT) and host-app context.
+
+---
+
+## Prime rule
+
+| Source | Authoritative for |
+|--------|-----------------|
+| **Mockup image / prompt** | UI look-and-feel only (see table below) |
+| **Fetched survey (JWT)** | Question types, text, logic, languages, placeholders in question copy, custom-field ids |
+| **Host / CRM / transaction** | `customFieldValues` runtime values |
+| **Client (explicit)** | JWT, wizard yes/no, deploy yes/no |
+
+**Never invent survey behavior from a mockup.** A single NPS screenshot does not mean the survey has only NPS, one language, or specific skip rules.
+
+---
+
+## Extract from mockup (UI only)
+
+Use mockup / prompt for **chrome and tokens** — record in `implementation_plan.md` §0 and draft `survey-theme.css` / `survey-ui-config.json`:
+
+| Extract | Examples | Where it goes |
+|---------|----------|---------------|
+| **Brand colors** | Primary pink, footer dark gray, page background | `--cfm-primary`, `--cfm-footer-bg`, `global.colorScheme` |
+| **Logo style** | Image vs text/CSS logo, placement | `Header.tsx` pattern (`data-cfm-logo` or `data-cfm-logo-text`) |
+| **Header layout** | Logo left, company name, sticky bar | `global.header.*`, header CSS vars |
+| **Footer layout** | Logo, links row, copyright | `global.footer.*`, `data-cfm-footer-links` |
+| **Chrome copy (display text)** | Survey title, company name, button labels, thank-you line, footer link labels | `global.surveyTitle`, `global.companyName`, `global.buttons`, `global.footer.links` — **wording only** |
+| **Progress bar presence** | Visible track under header | `global.layout.showProgressBar` default |
+| **Typography / corners** | Rounded cards, font family | `global.layout.borderStyle`, `global.layout.fontStyle` |
+| **Question card feel** | Card background, border, shadow | `global.theme.*` |
+| **Scale visual style (reference)** | NPS traffic-light, star vs numbered — as **styling hint** | Per-type tokens in `questionTypes.*` after you know types from fetch |
+
+Chrome text from mockup (e.g. "Telekom Umfrage", "Impressum") is **UI copy** — safe to seed branding. It does **not** replace question text from the API.
+
+---
+
+## Do NOT extract from mockup (survey myths)
+
+| Do not infer | Why | Correct source |
+|--------------|-----|----------------|
+| **Question types** in survey | Image shows one screen (e.g. NPS) | Unique `question.type` from **fetched** `survey.pages` |
+| **Question count / order** | Mockup is one page | Fetched survey structure |
+| **Question text / labels** | May be sample or translated | `question.questionText`, `options`, matrix rows from fetch |
+| **Language** (`de` vs `en`) | UI locale in screenshot ≠ survey language | `survey.language`, `supportedLanguages` from fetch; `useSurveySDK({ language })` |
+| **Skip / display / answer logic** | Not visible in static image | `skipLogics`, `displayLogic`, `answerLogic` on fetched pages |
+| **Custom field ids or values** | CRM data not in mockup | Scan fetch for `_c_…` ids — [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) |
+| **Placeholder keys** (`{{FIRST_NAME}}`) | Tokens in mockup may be examples | Scan **fetched** question text for `{{…}}` tokens |
+| **Validation rules** | Not shown in design | SDK + fetched `validation` |
+| **End pages / intro copy** | Unless clearly labeled as chrome | `survey.pages` / `endPages` from fetch |
+| **`surveyTypes` for wizard** | Mockup ≠ wizard inventory | All **11** types for wizard; fetched types for dispatch only |
+
+**Blocking rule:** `implementation_plan.md` §3b inventory table is filled from **fetch**, not from mockup filename or image content.
+
+---
+
+## Agent workflow
+
+### Phase 0 — Mockup pass (UI notebook only)
+
+1. Note colors, header/footer structure, logo mode, button style, card chrome.
+2. Write **Branding source** in `implementation_plan.md` §0 — describe UI only.
+3. Do **not** write question-type rows or logic rows yet.
+
+### Phase 2–4 — Fetch pass (survey truth)
+
+1. Ask client for JWT; fetch survey.
+2. List unique `question.type` values → §3b (from API).
+3. Scan logic → §3d custom fields, §3e logic inventory (from API).
+4. Scan question text for `{{TOKEN}}` → placeholder keys (from API).
+5. Override mockup only where client **explicitly** contradicts fetch in written prompt (rare — prefer fetch for survey content).
+
+### Phase 5 — Merge
+
+| From mockup | From fetch |
+|-------------|------------|
+| CSS vars, chrome layout, default button labels | `Question.tsx` branches, scale fixtures, logic wiring |
+| `data-cfm-*` hooks | `getVisible*ForAnswers`, `customFieldValues` |
+
+---
+
+## Common myths (avoid)
+
+| Myth | Reality |
+|------|---------|
+| "Mockup shows NPS → build only NPS" | Build all types in **fetch**; wizard still shows all 11 for customization |
+| "German text in image → hardcode `language: 'de'`" | Set language from survey + selector; mockup language is not authoritative |
+| "Footer says Datenschutz → survey has privacy logic" | Footer link is chrome — wire `global.footer.links`; no extra SDK logic |
+| "Question 6 in image → survey has 6 questions" | Numbering is path-scoped; count pages from fetch |
+| "Red asterisk in mockup → question.required on that id" | Required flags come from fetched questions |
+
+---
+
+## Wizard note
+
+Mockup drives **seed** colors and chrome text in `survey-ui-config.json`. Wizard **Question Types** step still lists all 11 literals — see [`wizard-troubleshooting.md`](wizard-troubleshooting.md) §4.
+
+---
+
+## Related docs
+
+| Doc | Role |
+|-----|------|
+| [`placeholders-and-tokens.md`](placeholders-and-tokens.md) | Placeholder keys from fetch |
+| [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) | `_c_…` ids from fetch |
+| [`logic-fields-catalog.md`](logic-fields-catalog.md) | Logic fields (do not invent) |
+| [`canonical-survey-fixtures.md`](canonical-survey-fixtures.md) | Matrix/slider shapes from fetch |
+| [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) | Tokenize UI for live preview |

package/templates/docs/00-integration/placeholders-and-custom-fields-wiring.md

@@ -0,0 +1,192 @@
+# Placeholders & Custom Fields — Precise SDK Wiring
+
+> **Read in Phase 4–5** after survey fetch. Companion: [`placeholders-and-tokens.md`](placeholders-and-tokens.md), [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md), [`mockup-ui-extraction.md`](mockup-ui-extraction.md).
+
+Agents must pass **exact keys** from the fetched survey and CRM context into `useSurveySDK` — not guesses from mockup text.
+
+---
+
+## Two different maps (do not conflate)
+
+| Map | Key format | Purpose | Value source |
+|-----|------------|---------|----------------|
+| **`placeholders`** | `FIRST_NAME`, `COMPANY` (no braces) | Replace `{{FIRST_NAME}}` in question copy at map time | CRM / marketing context or wizard `placeholders.*` |
+| **`customFieldValues`** | `_c_…` ids from logic rules | Skip, display, answer, end, progress evaluation | CRM / transaction API — **not** respondent UI |
+
+Mockup images do **not** define either map. Discover keys from **fetched survey JSON**.
+
+---
+
+## Step 1 — Discover placeholder keys (after fetch)
+
+Scan all `questionText`, `questionDescription`, display variant bodies, intro/end copy for tokens:
+
+```
+{{FIRST_NAME}}
+{{COMPANY}}
+{{SURVEY_QUESTION-:-<questionId>}}
+```
+
+**CRM placeholders** — add to `SURVEY_PLACEHOLDERS`:
+
+```typescript
+// src/lib/placeholders.ts (or module scope in SurveyPage.tsx)
+export const SURVEY_PLACEHOLDERS = {
+  FIRST_NAME: 'Alex',      // key = token name without {{ }}
+  COMPANY: 'Acme Corp',
+} as const;
+```
+
+Rules:
+
+- Key must match token name **exactly** (case-sensitive per survey).
+- Values are **display strings** for CRM/marketing — not survey answers.
+- Omit keys not present in fetched text (do not copy example lists from docs blindly).
+- **Answer tokens** `{{SURVEY_QUESTION-:-id}}` are **not** in `placeholders` — resolved at render via `resolveSurveyQuestionPlaceholders`.
+
+Record discovered keys in `implementation_plan.md`:
+
+```markdown
+## Placeholder inventory (from fetch)
+| Token | Key in SURVEY_PLACEHOLDERS | Example value | Found in question ids |
+| {{FIRST_NAME}} | FIRST_NAME | … | q1, q3 |
+```
+
+---
+
+## Step 2 — Wire placeholders (stable ref + hook)
+
+```typescript
+import { useMemo } from 'react';
+import { useSurveySDK } from '@explorer02/cfm-survey-sdk';
+import { SURVEY_PLACEHOLDERS } from '@/lib/placeholders';
+import { CUSTOM_FIELD_VALUES } from '@/lib/customFieldValues';
+
+const surveyOptions = useMemo(
+  () => ({
+    instanceId: SURVEY_INSTANCE_ID,
+    language: selectedLanguage,
+    placeholders: SURVEY_PLACEHOLDERS,
+    customFieldValues: CUSTOM_FIELD_VALUES,
+  }),
+  [selectedLanguage],
+);
+
+const { state, onAction, surveyQueryResults } = useSurveySDK({ options: surveyOptions });
+```
+
+**Failure modes:**
+
+| Mistake | Symptom |
+|---------|---------|
+| Inline `placeholders={{ ... }}` in component | Infinite re-fetch |
+| Key missing from map | Literal `{{FIRST_NAME}}` in UI |
+| Mockup name instead of token key | Wrong or missing substitution |
+
+---
+
+## Step 3 — Discover custom field ids (after fetch)
+
+Scan `survey.pages[].skipLogics`, `displayLogic`, `answerLogic`, and `endPages` for:
+
+```json
+"conditionEntity": { "entityType": "CUSTOM_FIELD", "id": "_c_67199096d294be011a2b4773", "fieldType": "TEXT" }
+```
+
+Collect **every** `_c_…` id. Fill `implementation_plan.md` §3d.
+
+Copy template → `src/lib/customFieldValues.ts`:
+
+```typescript
+import type { CustomFieldValueMap } from '@explorer02/cfm-survey-sdk';
+
+export const CUSTOM_FIELD_VALUES: CustomFieldValueMap = {
+  '_c_67199096d294be011a2b4773': 'abc',  // TEXT — exact id from fetch
+  // '_c_…': 2,                           // NUMBER
+  // '_c_…': 'picklist-option-uuid',      // PICKLIST
+};
+```
+
+### Value shape by `fieldType` (must match SDK evaluator)
+
+| fieldType | Pass |
+|-----------|------|
+| `TEXT`, `TEXT_MULTI`, `TEXTAREA` | `string` |
+| `NUMBER` | `number` or numeric `string` |
+| `PICKLIST` | option **id** string |
+| `PICKLIST_MULTISELECT` | `string[]` of option ids |
+| `DATETIME` | epoch ms (`number` or numeric string) |
+
+Missing keys → treated as empty for logic. Wrong shape → rule may never match.
+
+**Values come from CRM/transaction** — ask client or integration spec when not in prompt. Do **not** invent ids or values from mockup.
+
+---
+
+## Step 4 — Wire custom fields (two places — same map)
+
+### A. Hook
+
+```typescript
+customFieldValues: CUSTOM_FIELD_VALUES,  // inside useMemo surveyOptions
+```
+
+### B. Question + visibility helpers
+
+```tsx
+<Question
+  customFieldValues={CUSTOM_FIELD_VALUES}
+  allAnswers={state.answers}
+  allQuestions={allQuestions}
+  ...
+/>
+```
+
+Inside `Question.tsx` (from template):
+
+```typescript
+getVisibleMcqOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+getVisibleMatrixItemsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+getVisibleRankOrderOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues);
+```
+
+**Fourth argument must be the same map** as hook options whenever logic references `CUSTOM_FIELD`.
+
+---
+
+## Step 5 — Wizard overrides (Phase 6c)
+
+When client uses wizard, `survey-ui-config.json` may include:
+
+| Config path | Code update |
+|-------------|-------------|
+| `placeholders.firstName` etc. | Merge into `SURVEY_PLACEHOLDERS` (wizard keys → SDK token keys per [`apply-ui-config.md`](apply-ui-config.md)) |
+| `customFields._c_…` | Merge into `CUSTOM_FIELD_VALUES` |
+
+Wizard **Testing & Tokens** step edits config only — you still wire stable refs in code after `confirm-ui-config`.
+
+---
+
+## Verification checklist
+
+- [ ] Placeholder keys discovered by **scanning fetched survey text**, not mockup
+- [ ] `SURVEY_PLACEHOLDERS` at module scope; keys match `{{TOKEN}}` names
+- [ ] Every `_c_…` id in logic appears in `CUSTOM_FIELD_VALUES`
+- [ ] Value shapes match `fieldType` from fetch
+- [ ] `useMemo` wraps hook `options`
+- [ ] `customFieldValues` passed to hook **and** `Question`
+- [ ] `getVisible*ForAnswers` receives 4th arg when CRM logic exists
+- [ ] `resolveSurveyQuestionPlaceholders` used for answer tokens in question shell
+- [ ] No placeholder or custom-field keys invented from mockup image
+
+---
+
+## Related
+
+| Doc | Role |
+|-----|------|
+| [`mockup-ui-extraction.md`](mockup-ui-extraction.md) | UI-only vs fetch |
+| [`placeholders-and-tokens.md`](placeholders-and-tokens.md) | Token resolution stages |
+| [`custom-field-logic-and-navigation.md`](custom-field-logic-and-navigation.md) | Logic evaluation contract |
+| [`client-lib-folder.md`](client-lib-folder.md) | File layout |
+| [`templates/customFieldValues.ts`](../templates/customFieldValues.ts) | Copy template |

package/templates/docs/00-integration/placeholders-and-tokens.md

@@ -1,6 +1,7 @@
 # Placeholders and Tokens
 
-> Covers `sdkFeatures.placeholderResolution` — how CRM and dynamic answer tokens resolve in question text.
+> Covers `sdkFeatures.placeholderResolution` — how CRM and dynamic answer tokens resolve in question text.  
+> **Agent wiring (discover keys from fetch):** [`placeholders-and-custom-fields-wiring.md`](placeholders-and-custom-fields-wiring.md)
 
 ---
 

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/setup.md

@@ -132,6 +132,18 @@ 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

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

@@ -0,0 +1,123 @@
+# 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).
+
+## Default: local wizard (`customize`)
+
+When the client says **yes** to customization in agent chat, **always run:**
+
+```bash
+npx cfm-sdk customize
+```
+
+This is the **recommended default** because it:
+
+- Serves wizard + component previews from **one local server** (`localhost:4200`)
+- Auto-exports all **11** question-type previews from agent components
+- Writes `survey-ui-config.json` **directly** on save — no S3, no session polling
+- Cleans up automatically when the CLI exits (no orphan S3 garbage)
+- Updates live previews via the same iframe + preview bridge as production
+
+**Agent script after client says yes:**
+
+> *"I'll open the customization wizard in your browser. Complete all steps and click **Review & Build** when done — I'll apply your changes automatically."*
+
+The CLI **blocks** until the client saves. Wait for:
+
+```
+✅ UI configuration saved to survey-ui-config.json
+```
+
+Then apply per [`apply-ui-config.md`](apply-ui-config.md).
+
+### Who can use it
+
+| User | Can use `customize`? |
+|------|---------------------|
+| Client on **same machine** as agent (Cursor chat on dev laptop) | **Yes — default** |
+| Client on **another device** | **No** — use EC2 fallback below |
+
+`localhost:4200` is only reachable on the machine running the CLI.
+
+---
+
+## EC2 fallback (`customize-ui`) — remote clients only
+
+Use **only** when the client must customize from another PC/tablet/network:
+
+```bash
+export CFM_INSTANCE_ID="..." CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+```
+
+- Uploads previews to EC2 disk (local-server model on remote host)
+- Prints EC2 wizard link — agent sends link to client
+- CLI **polls** until client submits → writes `.final.json` + `.diff.md`
+- Requires deploy-api on EC2 + `CFM_INSTANCE_ID`
+
+See [`wizard-api.md`](wizard-api.md) and [`wizard-config-handoff.md`](wizard-config-handoff.md).
+
+**Do not** use `customize-ui` when client and agent share the same machine — `customize` is simpler and more reliable.
+
+---
+
+## When to ask (INPUT 3)
+
+After Phase 6 verify + dev server:
+
+> *"Your survey is running locally. Would you like to customize the UI through the web wizard?"*
+
+- **Yes** → `npx cfm-sdk customize` (default)
+- **Yes, but I'm on a different device** → `npx cfm-sdk customize-ui`
+- **No** → Phase 7 deploy ask
+
+---
+
+## How local wizard works
+
+```mermaid
+sequenceDiagram
+  participant Agent as Agent CLI
+  participant Srv as localhost:4200
+  participant Wizard as Wizard SPA
+  participant Prev as out/previews/
+
+  Agent->>Agent: export-previews (all 11 types)
+  Agent->>Srv: customize serves wizard + previews
+  Wizard->>Srv: GET /api/inventory
+  Wizard->>Prev: iframe /previews/MCQ_single/...
+  Wizard->>Srv: POST /api/save-config
+  Srv->>Agent: survey-ui-config.json written, CLI exits
+```
+
+| Route | Purpose |
+|-------|---------|
+| `/api/inventory` | Preview manifest + seed config |
+| `/previews/{key}/index.html` | Component-wise live preview |
+| `/api/save-config` | Client submit → JSON on disk |
+| `/api/upload-logo` | Logo → `public/` |
+
+---
+
+## Seed config
+
+| Priority | Source |
+|----------|--------|
+| 1 | `./survey-ui-config.json` (draft) |
+| 2 | `src/styles/survey-theme.css` |
+| 3 | `implementation_plan.md` |
+| 4 | `Header.tsx` logo contract |
+| 5 | SDK defaults |
+
+---
+
+## Agent checklist
+
+- [ ] Phase 5: wizard-preview artifacts wired
+- [ ] Client opted in (INPUT 3)
+- [ ] Ran **`npx cfm-sdk customize`** (default) and waited for CLI exit 0
+- [ ] Read `survey-ui-config.json` (or `.diff.md` if used EC2 fallback)
+- [ ] Phase 6c: applied per [`apply-ui-config.md`](apply-ui-config.md)
+- [ ] Re-ran verify + build
+
+See [`wizard-troubleshooting.md`](wizard-troubleshooting.md) if previews show mock UI.

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 |
 |-----------|-------|------|---------|