@explorer02/cfm-survey-sdk 0.2.4 → 0.2.5

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

@@ -43,11 +43,11 @@ Use sources **only** in this order. Lower items never override higher ones.
 
 | Phase | Read these files **before any code** | Extract and record |
 |-------|--------------------------------------|--------------------|
-| **0** | `agent-operating-contract.md`, `agent-execution-flow.md`, `index.md`, `MANIFEST.json` | Framework, `typeLiterals`, branding notes |
+| **0** | `agent-operating-contract.md`, `agent-execution-flow.md`, `mockup-ui-extraction.md`, `index.md`, `MANIFEST.json` | Framework, `typeLiterals`; **UI-only** mockup notes |
 | **1** | `setup.md` (framework section) | Install list, AWS export flags if prompt mentions AWS |
 | **2** | `useSurveySDK.md` | `instanceId` wiring location — then **ask client for JWT** |
 | **3** | `client-integration-guide.md`, `question-type-sdk-matrix.md`, logic + lifecycle docs per MANIFEST phase 3 | `onAction` shapes, `state.answers`, visibility helpers |
-| **4** | `component-checklist.md`, `implementation_plan.md` template, `00-question-shell.md`, `12-survey-chrome.md`, **per-type** MANIFEST routes | Inventory table in `implementation_plan.md` §3b |
+| **4** | `component-checklist.md`, `implementation_plan.md` template, `mockup-ui-extraction.md`, `placeholders-and-custom-fields-wiring.md`, `00-question-shell.md`, `12-survey-chrome.md`, **per-type** MANIFEST routes | §3b from **fetch**; §3d placeholders + custom fields |
 | **5** | `constraints.md`, `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, **each** `03-ui-specs/{type}.md` in inventory | Tokens, `data-cfm-*`, selection pattern |
 | **6** | `constraints.md`, `component-checklist.md` Step 3–4 | Run `verify-agent-build.sh` — fix failures |
 | **6b** | `ui-customization-wizard.md`, `wizard-api.md` | CLI env vars — only if client said **yes** |
@@ -84,13 +84,15 @@ Use this table when deciding what to read. **Do not substitute similar-sounding
 | File upload | `03-ui-specs/10-file-upload.md`, `file-upload-aws.md` | Raw `File[]` in submit payload |
 | Heatmap | `03-ui-specs/13-heatmap.md`, `templates/heatmapCoords.ts` | Region overlays on respondent UI |
 | Rank order | `03-ui-specs/14-rank-order.md`, `templates/RankOrderScale.tsx` | Client-side re-shuffle |
-| Custom fields | `custom-field-logic-and-navigation.md`, `templates/customFieldValues.ts` | Skip wiring hook + Question prop |
+| Custom fields | `custom-field-logic-and-navigation.md`, `placeholders-and-custom-fields-wiring.md`, `templates/customFieldValues.ts` | Skip wiring hook + Question prop |
+| Mockup / prompt image | `mockup-ui-extraction.md` | UI chrome only — not question types or logic |
+| Placeholders + CRM tokens | `placeholders-and-custom-fields-wiring.md`, `placeholders-and-tokens.md` | Keys from fetched `{{TOKEN}}` text |
 | Wizard chrome | `wizard-preview-build-guide.md`, `03-ui-specs/12-survey-chrome.md` | External logo URLs |
 | Wizard per-type colors | `wizard-question-type-styling.md` | Hardcoded Telekom hex for wizard tokens |
 | Selection colors | `wizard-question-type-styling.md`, `templates/selectionStyles.ts` | Single color for ring + fill — use annulus pattern |
 | Matrix column labels | `wizard-question-type-styling.md`, `templates/labelStyles.ts` | Hint labels on CFM column headers |
 | Logo seed | `constraints.md` §4, `wizard-api.md`, `parse-client-header` behavior in wizard docs | Random `public/logo_*` scan |
-| Wizard session (wait) | `wizard-config-handoff.md`, `ui-customization-wizard.md` |
+| Wizard session (wait) | `wizard-config-handoff.md`, `ui-customization-wizard.md`, `wizard-troubleshooting.md` |
 | Apply all wizard paths | `apply-ui-config.md` | Changing `Question.tsx` dispatch |
 | Deploy AWS | `aws-deploy.md`, `setup.md#nextjs-aws-static-export` | `assetPrefix: "/"` for static export |
 
@@ -106,7 +108,11 @@ Use this table when deciding what to read. **Do not substitute similar-sounding
 | Default branch: "Not implemented" | Copy `templates/Question.tsx` — all types explicit |
 | Import `@repo/sdk/src/...` | Package root only — `hookContract.forbiddenImports` |
 | Implement from `apps/client` | Copy `docs/templates/*` |
-| `npx cfm-sdk customize` before build | Build + verify first; AWS = `customize-ui` |
+| `npx cfm-sdk customize-ui` when client is on **same machine** as agent | Use **`npx cfm-sdk customize`** (default) |
+| `npx cfm-sdk customize` when client is on **another device** | Use `customize-ui` + EC2 link |
+| Infer question types / logic / language from mockup image | Fetch survey (JWT) only — see `mockup-ui-extraction.md` |
+| Placeholder keys from mockup examples | Scan fetched question text for `{{TOKEN}}` |
+| `_c_…` ids or CRM values from mockup | Scan fetch + CRM spec — `placeholders-and-custom-fields-wiring.md` |
 | `survey-config.json` | `survey-ui-config.json` + schema in `templates/` |
 | NPS `option.accentColor` | Derive from value — `value-derivation.md` |
 | Matrix value = column label text | `matrixColumnStoredValue(col)` → column **`id`** |
@@ -115,6 +121,8 @@ Use this table when deciding what to read. **Do not substitute similar-sounding
 | Focus ring = cell fill (same element) | Ring = border + dot; cell selected = annulus between |
 | Wizard optional → skip `survey-theme.css` | Wizard-ready build is **mandatory** Phase 5 |
 | Logo from any `public/logo_*` | `Header.tsx` `data-cfm-logo` / `data-cfm-logo-text` contract |
+| `global.logo.url` as Header `src` | `./{fileName}` from `public/` built into `out/` — see `aws-deploy.md` § Logos |
+| Wizard logo “in memory” on CloudFront | Re-apply `fileName`, rebuild, redeploy — preview `data:` ≠ deploy bundle |
 | `getVisible*` without 4th arg when CRM logic exists | Pass `customFieldValues` — `hookContract.visibilityHelpers` |
 | New question types or SDK actions | Only documented `onAction` types in `useSurveySDK.md` |
 | Placeholder unstable inline object | Stable ref + `useMemo` on hook options |

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

@@ -8,11 +8,13 @@
 
 | Wizard mode | Apply source | When |
 |-------------|--------------|------|
-| AWS review (default) | `survey-ui-config.final.json` | After CLI prints `Configuration ready` |
-| AWS `--apply` | `survey-ui-config.json` | Immediately after CLI exits |
-| Local `customize` | `survey-ui-config.json` | After `UI configuration saved` |
+| **`customize` (default)** | `survey-ui-config.json` | After `✅ UI configuration saved` |
+| `customize-ui` review | `survey-ui-config.final.json` | After CLI prints `Configuration ready` |
+| `customize-ui --apply` | `survey-ui-config.json` | Immediately after CLI exits |
 
-**AWS review mode:** `survey-ui-config.json` remains **seed** until `npx cfm-sdk confirm-ui-config` — always apply codebase from **`.final.json`**.
+**Default:** apply directly from `survey-ui-config.json` after `npx cfm-sdk customize`.
+
+**EC2 review mode:** apply from `.final.json`; run `confirm-ui-config` after codebase apply.
 
 ---
 
@@ -74,8 +76,8 @@ Import in `globals.css`: `@import './styles/survey-theme.css';`
 | `global.buttons.next` | SurveyPage | `data-cfm-btn-next` text |
 | `global.buttons.back` | SurveyPage | `data-cfm-btn-back` text |
 | `global.buttons.submit` | SurveyPage submit label | button text |
-| `global.logo.fileName` | Header | `data-cfm-logo` src=`/${fileName}` (or `./${fileName}` for static AWS export); remove `data-cfm-logo-text` when image |
-| `global.logo.url` | Agent reference only | Public CloudFront URL after wizard — download to `public/`; do **not** use as `img src` in the survey |
+| `global.logo.fileName` | Header | `data-cfm-logo` src=`./${fileName}` for AWS static export (`/${fileName}` for local dev only) |
+| `global.logo.url` | Download source only | EC2: CloudFront `/assets/` URL → `confirm-ui-config` copies to `public/`. **Never** use as `img src` or `data:` preview URL |
 | `global.footer.copyrightText` | Footer | `data-cfm-copyright` |
 | `global.footer.links[]` | Footer | `data-cfm-footer-links` (render links) |
 | `questionTypes.MCQ.optionStyle` | `:root` or survey wrapper | `data-cfm-mcq-style` |
@@ -112,10 +114,33 @@ Import in `globals.css`: `@import './styles/survey-theme.css';`
 
 For each type in `surveyTypes[]`, apply `questionTypes.{TYPE}` per § Question types below.
 
-### 8. Logo file
+### 8. Logo file (required for AWS deploy)
+
+Wizard preview keeps the image in **browser memory** (`data:` URL). CloudFront only serves files that were **built into `out/`** and uploaded in Phase 7.
+
+| Wizard mode | Where binary lands | Agent action before deploy |
+|-------------|-------------------|----------------------------|
+| **`customize` (local)** | `public/{fileName}` via `POST /api/upload-logo` | Set `data-cfm-logo src="./{fileName}"` in `Header.tsx` |
+| **`customize-ui` (EC2)** | S3 `sites/{surveyId}/assets/{fileName}` + `global.logo.url` in `.final.json` | Run `confirm-ui-config` → copies to `public/`; then set Header `src="./{fileName}"` |
+
+**Rules:**
+
+1. **Authoritative path:** `global.logo.fileName` — not `global.logo.url` for `img src`.
+2. **`global.logo.url` after EC2 wizard:** public CloudFront URL under `/assets/` — use only to **download** into `public/` (`confirm-ui-config` or `downloadWizardLogoToPublic`). Do **not** use as `img src` in the survey (wrong S3 prefix vs deploy bundle).
+3. **`global.logo.url` after local wizard:** must be `null` (CLI strips `data:` on save). If you still see `data:image/…` in JSON, re-save from wizard or clear `url` manually.
+4. **AWS static export:** `src="./{fileName}"` (leading `./`). Absolute `/file.png` breaks under `/sites/{surveyId}/{deployId}/`.
+5. Prefer plain `<img data-cfm-logo>` over `next/image` for logo files — simpler relative paths in `out/`.
+
+**Verify before Phase 7:**
+
+```bash
+LOGO=$(python3 -c "import json; c=json.load(open('survey-ui-config.json')); print((c.get('global') or {}).get('logo', {}).get('fileName') or '')")
+test -n "$LOGO" && test -f "public/$LOGO" || echo "WARN: no logo file"
+yarn build
+test -f "out/$LOGO" && echo "Logo in static output — safe to deploy"
+```
 
-- Local / `confirm-ui-config`: file in `public/{fileName}`
-- If missing after confirm: re-run with `CFM_INSTANCE_ID` + `CFM_DEPLOY_API_BASE`
+Full deploy pipeline: [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
 
 ### 9. Promote active config (AWS review only)
 
@@ -352,7 +377,7 @@ Ensure components use `selectionStyles.ts` — config only changes CSS vars, not
 
 ## Re-run policy
 
-Do not re-run `customize-ui` unless the client explicitly requests another customization session. Each run overwrites review artifacts.
+Do not re-run the wizard unless the client explicitly requests another session. Each run overwrites config artifacts.
 
 ---
 

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/component-checklist.md

@@ -92,7 +92,8 @@ Store matrix values as column **`id`** — `matrixColumnStoredValue(col)` from S
 ## Step 3: Verify Before Build
 
 - [ ] Every type in survey inventory has matching component file(s)
-- [ ] **`src/lib/customFieldValues.ts`** when survey logic references `_c_…` ids
+- [ ] **`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)
@@ -115,6 +116,7 @@ Read: [`agent-execution-flow.md`](agent-execution-flow.md), [`wizard-preview-bui
 - [ ] `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
+- [ ] **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

@@ -34,11 +34,12 @@ Choose **one** pattern in `Header.tsx` — see [`wizard-preview-build-guide.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. |
+| **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.
-- 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`.
+- 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
 

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

@@ -18,7 +18,7 @@ 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).
+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.
 
 ---
 

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