@explorer02/cfm-survey-sdk 0.2.4 → 0.2.6

package/templates/docs/00-integration/agent-execution-flow.md

@@ -25,7 +25,7 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 
 | # | When | Agent asks (verbatim intent) | On answer |
 |---|------|------------------------------|-----------|
-| **1** | Start (usually given) | *(Client prompt — mockup, brand, deploy target hints)* | Extract branding; note AWS/Vercel keywords |
+| **1** | Start (usually given) | *(Client prompt — mockup, brand, deploy target hints)* | UI-only notes per `mockup-ui-extraction.md`; **not** survey structure |
 | **2** | Phase 2 | *"Please provide your survey instance ID (JWT token)."* | Store as `CFM_INSTANCE_ID` / `SURVEY_INSTANCE_ID`; fetch survey |
 | **3** | Phase 6 (after verify + dev server) | *"Your survey is running locally. Would you like to customize the UI through the web wizard?"* | **Yes** → Phase 6b. **No** → Phase 7 ask |
 | **4** | Phase 7 | *"Your survey is built and verified. Ready to deploy to production?"* | **Yes** → deploy per prompt/config. **No** → stop |
@@ -42,7 +42,8 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 
 **Do:**
 - Detect framework from `package.json` → `setup.md`
-- Extract colors, logo style, layout from client prompt into notes for `implementation_plan.md`
+- Extract **UI-only** from mockup/prompt per [`mockup-ui-extraction.md`](mockup-ui-extraction.md) — colors, chrome, header/footer format, display copy
+- Do **not** infer question types, language, or logic from mockup
 
 ---
 
@@ -102,8 +103,9 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 
 **Do:**
 1. Fetch survey with instanceId
-2. List unique `question.type` values in `implementation_plan.md` §3b
-3. Copy `templates/implementation_plan.md` → project root; fill all sections
+2. List unique `question.type` values in `implementation_plan.md` §3b (**from fetch only**)
+3. Scan placeholders + `_c_…` custom fields per [`placeholders-and-custom-fields-wiring.md`](placeholders-and-custom-fields-wiring.md)
+4. Copy `templates/implementation_plan.md` → project root; fill all sections
 4. Copy `templates/Question.tsx` as dispatcher starting point
 5. **Auto-proceed to Phase 5** — no approval wait
 
@@ -112,6 +114,7 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 ### Phase 5 — Build (wizard-ready)
 
 **Read:**
+- `00-integration/wizard-chrome-contract.md` **(required — copy-first templates)**
 - `00-integration/constraints.md`
 - `00-integration/component-checklist.md`
 - `00-integration/wizard-preview-build-guide.md` **(required)**
@@ -123,6 +126,7 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 
 | Source (`docs/templates/`) | Destination |
 |----------------------------|-------------|
+| `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`, `LanguageSelector.tsx`, `PreviewBridgeInit.tsx` | `src/components/` |
 | `survey-theme.css` | `src/styles/survey-theme.css` |
 | `selectionStyles.ts` | `src/lib/surveyUi/selectionStyles.ts` |
 | `labelStyles.ts` | `src/lib/surveyUi/labelStyles.ts` |
@@ -136,6 +140,11 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 @import "./styles/survey-theme.css";
 ```
 
+**Copy before coding chrome** (from `templates/docs/templates/`):
+
+- `Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`, `LanguageSelector.tsx`, `PreviewBridgeInit.tsx`
+- `previewBridge.ts` → `src/lib/previewBridge.ts`
+
 **Wire in root `layout.tsx`:** `<PreviewBridgeInit />` (see `wizard-preview-build-guide.md`)
 
 **Chrome contract (`data-cfm-*`):**
@@ -177,36 +186,35 @@ Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
 
 ### Phase 6b — Wizard session (optional, INPUT 3 = Yes)
 
-**Read:** `wizard-config-handoff.md`, `ui-customization-wizard.md`, `wizard-api.md`, `wizard-preview-build-guide.md`
+**Default:** `npx cfm-sdk customize` — local wizard on `localhost:4200`. Best for preview smoothness, direct JSON save, and automatic cleanup.
+
+**EC2 fallback:** `customize-ui` — only when client customizes from **another device**.
+
+**Read:** `ui-customization-wizard.md`, `wizard-preview-build-guide.md`, `wizard-troubleshooting.md`, `apply-ui-config.md`
 
 **Prerequisites:** Phase 6 passed; draft `survey-ui-config.json` exists
 
-**Run (agent blocks until client submits):**
+**Run (default — agent blocks until client saves):**
 ```bash
-export CFM_INSTANCE_ID="<JWT>"
-export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
-npx cfm-sdk customize-ui
+npx cfm-sdk customize
 ```
 
 **Sequence:**
-1. CLI exports component previews and uploads to S3
-2. CLI prints **deployed wizard link** — agent **copies and sends to client**
-3. Client opens EC2 link, customizes, clicks **Review & Build**
-4. Agent keeps CLI open until `✅ Configuration ready`
+1. CLI auto-exports all 11 component previews to `out/previews/`
+2. Opens wizard at `http://localhost:4200`
+3. Client customizes (same machine as agent); live iframes from local previews
+4. Client clicks **Review & Build** → `survey-ui-config.json` written
+5. CLI exits 0 → agent applies per Phase 6c
 
-**Agent must:**
-1. Share the deployed wizard URL with the client (from CLI output, after S3 upload)
-2. Tell client to complete wizard and click **Review & Build**
-2. **Keep CLI running** — poll until `✅ Configuration ready` (do not Ctrl+C)
-3. Read `survey-ui-config.diff.md` when CLI exits 0
-4. **Do not apply** to codebase yet — proceed to Phase 6c
+**Tell the client:** *"Complete the wizard in the browser that just opened and click **Review & Build**."*
 
-**Artifacts (AWS review mode):**
-- `survey-ui-config.final.json` — apply source
-- `survey-ui-config.diff.md` — audit every changed path
-- `survey-ui-config.json` — still **seed** until Phase 6c confirm step
-
-**Local alternative:** `npx cfm-sdk customize` — blocks until `UI configuration saved` → writes `survey-ui-config.json` directly.
+**Remote client only:**
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+```
+Share EC2 link; keep CLI open until `✅ Configuration ready`. See `wizard-config-handoff.md`.
 
 **If client said No:** skip to Phase 7 ask.
 
@@ -229,8 +237,10 @@ npx cfm-sdk customize-ui
 6. Wire `placeholders`, `customFields`, `debug` from final config
 7. Apply per-type `questionTypes.*` for every type in `surveyTypes[]`
 8. AWS: `npx cfm-sdk confirm-ui-config` (promotes final → active + downloads logo)
-9. Re-run `verify-agent-build.sh` + `npm run build`
-10. **Do not** change dispatch logic in `Question.tsx`
+9. When `global.logo.fileName` is set: update `Header.tsx` `data-cfm-logo src="./{fileName}"`; verify `public/{fileName}` exists
+10. Re-run `verify-agent-build.sh` + `npm run build`
+11. Verify logo in static output: `test -f out/$(jq -r '.global.logo.fileName' survey-ui-config.json)` when fileName set
+12. **Do not** change dispatch logic in `Question.tsx`
 
 **Blocking:** Do not proceed to Phase 7 until diff paths are applied and verify passes.
 
@@ -240,6 +250,15 @@ npx cfm-sdk customize-ui
 
 **Ask:** deploy confirmation (see table)
 
+**Before AWS deploy (when wizard set a logo):**
+
+```bash
+LOGO=$(python3 -c "import json; print(json.load(open('survey-ui-config.json')).get('global',{}).get('logo',{}).get('fileName') or '')")
+test -z "$LOGO" || test -f "out/$LOGO" || { echo "Logo missing from out/ — fix Phase 6c Header + public/"; exit 1; }
+```
+
+See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
 **Route:**
 - AWS keywords in prompt → `aws-deploy.md` + `deploy-to-aws.sh`
 - Else / Vercel → `npx cfm-sdk deploy`

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

@@ -2,7 +2,7 @@
 
 > **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.
+> **Wizard-ready build (Phase 5 — mandatory):** Copy chrome templates from [`wizard-chrome-contract.md`](wizard-chrome-contract.md) (`Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`, etc.) and wire live-preview contract per [`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.
 
@@ -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)
@@ -107,7 +108,9 @@ bash 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)
+Read: [`wizard-chrome-contract.md`](wizard-chrome-contract.md), [`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)
+
+- [ ] **Copied** `templates/docs/templates/Header.tsx`, `Footer.tsx`, `ProgressBar.tsx`, `SurveyStickyChrome.tsx`, `LanguageSelector.tsx`, `PreviewBridgeInit.tsx` (do not use `apps/client` as reference)
 
 - [ ] `src/styles/survey-theme.css` with full `--cfm-*` set (copy from `templates/survey-theme.css`)
 - [ ] `selectionStyles.ts` + `labelStyles.ts` in `src/lib/surveyUi/`
@@ -115,6 +118,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`, `cfm-header` — see [`wizard-chrome-contract.md`](wizard-chrome-contract.md)
+- [ ] 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 |