@explorer02/cfm-survey-sdk 0.2.4 → 0.2.6

package/templates/docs/00-integration/wizard-chrome-contract.md

@@ -0,0 +1,210 @@
+# Wizard Chrome Contract — Required DOM + CSS Hooks
+
+> **Mandatory Phase 5.** If any hook is missing, wizard live preview fails for that control — even though the survey may look fine in localhost dev without the wizard open.  
+> **Copy-first templates:** [`templates/Header.tsx`](../templates/Header.tsx), [`Footer.tsx`](../templates/Footer.tsx), [`ProgressBar.tsx`](../templates/ProgressBar.tsx), [`SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx), [`LanguageSelector.tsx`](../templates/LanguageSelector.tsx), [`PreviewBridgeInit.tsx`](../templates/PreviewBridgeInit.tsx), [`previewBridge.ts`](../../previewBridge.ts).
+
+Pipeline: [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) · [`apply-ui-config.md`](apply-ui-config.md)
+
+---
+
+## Symptom → missing hook (quick fix)
+
+| Wizard control / symptom | Required fix |
+|--------------------------|--------------|
+| Logo not updating in Branding / Header preview | `data-cfm-logo` img + `data-cfm-logo-text` fallback in `Header.tsx` |
+| Company name not updating | `data-cfm-company` span in `Header.tsx` |
+| Show header works but progress bar toggle does nothing | Progress bar needs `data-cfm-progress` + class `cfm-progress`; header needs class `cfm-header` only — **not** on sticky wrapper |
+| Show footer toggle does nothing | `footer` + class `cfm-footer` |
+| Question numbers / required asterisk toggles | `data-cfm-question-number` + `data-cfm-required` on every question title |
+| Question card padding/shadow/colors not live-updating | Question wrapper uses `var(--cfm-card-*)` — not hardcoded `bg-white shadow-sm` |
+| MCQ / NPS / dropzone style pickers | Root reads `html[data-cfm-mcq-style]`, `[data-cfm-nps-button-style]`, `[data-cfm-dropzone-style]` from bridge |
+| Scale selection colors not updating | Import `selectionStyles.ts`; use `var(--cfm-matrix-selected)` / `var(--cfm-input-focus-ring)` |
+| Nothing updates except static harness | Agent build missing token contract — re-copy templates above |
+
+---
+
+## Copy order (agents — do this in Phase 5)
+
+```bash
+# From SDK templates folder (monorepo or node_modules)
+cp templates/docs/templates/Header.tsx           src/components/Header.tsx
+cp templates/docs/templates/Footer.tsx           src/components/Footer.tsx
+cp templates/docs/templates/ProgressBar.tsx      src/components/ProgressBar.tsx
+cp templates/docs/templates/SurveyStickyChrome.tsx src/components/SurveyStickyChrome.tsx
+cp templates/docs/templates/LanguageSelector.tsx src/components/LanguageSelector.tsx
+cp templates/docs/templates/PreviewBridgeInit.tsx src/components/PreviewBridgeInit.tsx
+cp templates/previewBridge.ts                    src/lib/previewBridge.ts
+cp templates/survey-theme.css                    src/styles/survey-theme.css
+cp templates/docs/templates/selectionStyles.ts    src/lib/surveyUi/selectionStyles.ts
+cp templates/docs/templates/labelStyles.ts        src/lib/surveyUi/labelStyles.ts
+```
+
+Wire `PreviewBridgeInit` in `layout.tsx` (local dev). Wizard iframes use injected `preview-bridge.inline.js` at export time.
+
+Run verification:
+
+```bash
+bash templates/verify-agent-build.sh
+```
+
+---
+
+## Layer 1 — CSS variables (`--cfm-*`)
+
+Wizard sends SNAPSHOT (full) + DELTA (partial) CSS vars to `:root`.
+
+**Rule:** Every color, radius, spacing, or chrome dimension editable in the wizard must be consumed via `var(--cfm-…)` — not hardcoded `#e20074` / `bg-[#e20074]`.
+
+Minimum files:
+
+| File | Role |
+|------|------|
+| `src/styles/survey-theme.css` | All default `--cfm-*` vars |
+| `globals.css` | `@import './styles/survey-theme.css'` |
+| Scale components | `selectionStyles.ts` + `labelStyles.ts` |
+
+---
+
+## Layer 2 — Content patches (`data-cfm-*` + layout flags)
+
+Wizard sends `contentPatch` on SNAPSHOT (not DELTA). Preview bridge applies patches to matching DOM nodes.
+
+### Branding & header
+
+| Patch field | DOM target | Template location |
+|-------------|------------|-------------------|
+| `logoUrl` | `[data-cfm-logo]` → sets `src`, shows img; hides `[data-cfm-logo-text]` | `Header.tsx` |
+| `companyName` | `[data-cfm-company]` text; fills logo-text when img hidden | `Header.tsx` |
+| `layoutFlags.showCompanyName` | `[data-cfm-company]` display | bridge |
+
+### Layout toggles (independent — critical)
+
+| `layoutFlags` key | Bridge selector | Component requirement |
+|-------------------|-----------------|----------------------|
+| `showHeader` | `.cfm-header`, `header.cfm-header` | Class on `<header>` only |
+| `showProgressBar` | `.cfm-progress`, `[data-cfm-progress]` | **Separate** from header — `ProgressBar.tsx` |
+| `showFooter` | `.cfm-footer`, `footer.cfm-footer` | Class on `<footer>` |
+| `showLanguageSwitcher` | `[data-cfm-language]` | `LanguageSelector.tsx` |
+| `showNextButton` | `[data-cfm-btn-next]` | `SurveyPage.tsx` nav |
+| `showBackButton` | `[data-cfm-btn-back]` | `SurveyPage.tsx` nav |
+| `showQuestionNumbers` | `[data-cfm-question-number]` | `Question.tsx` title |
+| `showRequiredAsterisk` | `[data-cfm-required]` | `Question.tsx` title |
+| `showFooterLogo` | `[data-cfm-footer-logo]` | `Footer.tsx` |
+
+**Anti-pattern:** Putting `sticky top-0` on the same element as `cfm-header` — bridge used to hide progress when toggling header. Templates use `cfm-sticky-chrome` wrapper without using it for `showHeader`.
+
+### Survey chrome content
+
+| Patch field | DOM target |
+|-------------|------------|
+| `surveyTitle` | `[data-cfm-survey-title]` |
+| `thankYouMessage` | `[data-cfm-thank-you]` |
+| `buttonLabels.next` / `.back` | `[data-cfm-btn-next]` / `[data-cfm-btn-back]` |
+| `copyrightText` | `[data-cfm-copyright]` |
+| `footerLinks[]` | `[data-cfm-footer-links]` innerHTML |
+
+### Question-type DOM attributes (on `<html>`)
+
+Set via `contentPatch.domAttributes`:
+
+| Attribute | Wizard source | Component reads |
+|-----------|---------------|-----------------|
+| `data-cfm-mcq-style` | `questionTypes.MCQ.optionStyle` | MCQ card classes / CSS |
+| `data-cfm-nps-button-style` | `questionTypes.NPS_SCALE.buttonStyle` | `RatingScale.tsx` |
+| `data-cfm-dropzone-style` | `questionTypes.FILE_UPLOAD.dropzoneStyle` | `FileUploadScale.tsx` |
+
+Vite preview harness also applies `previewState` via `PreviewConfigContext` for placeholders, NPS hints, rank variant, etc.
+
+---
+
+## Question card (Theme step)
+
+Question outer wrapper **must** use theme vars:
+
+```tsx
+<section
+  id={question.id}
+  className="cfm-question-card space-y-4"
+  style={{
+    background: 'var(--cfm-card-bg, #fff)',
+    borderColor: 'var(--cfm-card-border-color, #e5e7eb)',
+    padding: 'var(--cfm-card-padding, 24px)',
+    boxShadow: 'var(--cfm-card-shadow, 0 1px 3px rgba(0,0,0,0.1))',
+    borderRadius: 'var(--cfm-border-radius, 12px)',
+    borderWidth: 1,
+    borderStyle: 'solid',
+  }}
+>
+```
+
+Question title hooks:
+
+```tsx
+<h2>
+  {question.questionNumber != null && (
+    <span data-cfm-question-number className="mr-1 font-semibold">
+      {question.questionNumber}.
+    </span>
+  )}
+  <span dangerouslySetInnerHTML={{ __html: displayQuestionText }} />
+  {question.required && (
+    <span data-cfm-required className="ml-1 text-red-500">*</span>
+  )}
+</h2>
+```
+
+TEXTFIELD placeholder live preview: `data-cfm-textfield` on input/textarea.
+
+---
+
+## SurveyPage wiring (content phase)
+
+```tsx
+<div className="flex min-h-screen flex-col" style={{ background: 'var(--cfm-background)' }}>
+  <SurveyStickyChrome progressPercentage={state.progressPercentage} />
+  <main style={{ maxWidth: 'var(--cfm-max-width)' }}>...</main>
+  <Footer />
+</div>
+```
+
+Intro / end / paused: standalone `<Header />` (not sticky chrome). Footer still uses `cfm-footer`.
+
+---
+
+## Local wizard quit — preview garbage collection
+
+When the client **quits** local wizard (`npx cfm-sdk customize`) without saving:
+
+1. Wizard SPA calls `POST /api/wizard-quit` on the customize server
+2. CLI deletes `out/previews/` on agent disk
+3. CLI exits; no orphan preview folders
+
+When client **saves**: config written; previews remain until CLI exits (then server stops).
+
+When CLI is **Ctrl+C**'d: customize server runs the same preview cleanup on shutdown.
+
+EC2 `customize-ui`: quit calls `POST /wizard/session/quit` — disk session folder deleted (see [`wizard-config-handoff.md`](wizard-config-handoff.md)).
+
+---
+
+## Verification checklist (blocking before Phase 6b)
+
+- [ ] Copied all templates from § Copy order
+- [ ] `grep -r data-cfm-logo src/components/Header.tsx` — match
+- [ ] `grep -r data-cfm-progress src/components/ProgressBar.tsx` — match
+- [ ] `grep -r cfm-footer src/components/Footer.tsx` — match
+- [ ] `grep -r data-cfm-question-number src/components/Question.tsx` — match
+- [ ] `grep -rE 'var\\(--cfm-' src/components/` — no wizard colors as hardcoded hex only
+- [ ] `bash templates/verify-agent-build.sh` exit 0
+- [ ] `npx cfm-sdk export-previews` exit 0
+
+---
+
+## Related
+
+| Doc | Role |
+|-----|------|
+| [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) | Full build guide |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Per-type CSS vars |
+| [`10-header-footer.md`](../01-components/10-header-footer.md) | Branding patterns |
+| [`12-survey-chrome.md`](../03-ui-specs/12-survey-chrome.md) | Chrome layout spec |

package/templates/docs/00-integration/wizard-config-handoff.md

@@ -11,14 +11,53 @@ This doc tells the agent **exactly** how to wait for the client to finish the wi
 
 **Do not apply wizard changes until the client has submitted the wizard.**
 
-- **AWS (`customize-ui`):** CLI blocks and polls until status `ready` — wait for CLI success message.
-- **Local (`customize`):** CLI blocks until client saves in browser — wait for `✅ UI configuration saved`.
+- **Default (`customize`):** CLI blocks until client saves — wait for `✅ UI configuration saved`.
+- **Remote client (`customize-ui`):** CLI blocks and polls until status `ready`.
 
-**Do not** guess final colors from memory, skip the diff, or proceed to deploy while `survey-ui-config.json` still holds the **seed** (AWS review mode).
+**Do not** guess final colors from memory or proceed to deploy before the wizard CLI exits 0.
 
 ---
 
-## AWS flow (default — review mode)
+## Default flow — `npx cfm-sdk customize`
+
+### Step 1 — Agent runs CLI (and waits)
+
+```bash
+npx cfm-sdk customize
+```
+
+The CLI will:
+
+1. Export all 11 component preview pages (`export-previews` if needed)
+2. Start wizard at `http://localhost:4200`
+3. Open browser on the **agent machine**
+4. **Block** until client clicks **Review & Build**
+5. Write `survey-ui-config.json` and exit 0
+
+**Agent must:**
+
+- [ ] Client is on the **same machine** (can see `localhost:4200`)
+- [ ] Keep terminal open until `✅ UI configuration saved`
+- [ ] Apply per Phase 6c from `survey-ui-config.json`
+
+**Artifact:** `survey-ui-config.json` — apply source for local flow.
+
+**Logo on local wizard (critical for AWS deploy):**
+
+When the client uploads a logo in the local wizard:
+
+1. CLI writes the file to `public/logo_{timestamp}_{name}.jpg` via `POST /api/upload-logo`.
+2. Saved config has `global.logo.fileName` — preview `data:` URL is **not** persisted (stripped on save).
+3. Agent **must** set `Header.tsx` `data-cfm-logo` to `src="./{fileName}"` during Phase 6c.
+4. `yarn build` copies `public/` → `out/`; Phase 7 uploads `out/` to `sites/{surveyId}/{deployId}/`.
+
+The logo is **not** fetched from wizard memory on CloudFront — only from the deploy bundle. See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
+**Local quit (preview GC):** If the client exits without saving, wizard calls `POST /api/wizard-quit` → CLI deletes `out/previews/` on agent disk. Ctrl+C on customize CLI runs the same cleanup.
+
+---
+
+## Remote client flow — `customize-ui` (fallback only)
 
 ### Step 1 — Agent runs CLI (and waits)
 
@@ -31,12 +70,12 @@ npx cfm-sdk customize-ui
 **Default is review mode** (no flags). The CLI will:
 
 1. Export component preview pages (`export-previews`)
-2. Upload preview HTML to S3 (one page per component key — `header`, `footer`, `MCQ_single`, …)
+2. Upload preview HTML to **EC2 disk** (local-server model — same as agent `customize`)
 3. Print the **deployed EC2 wizard link** — agent **must share this URL with the client**
 4. **Poll every ~3s** (`GET /wizard/config/:surveyId`) until the client submits
 5. Print `✅ Configuration ready` when `status === 'ready'`
 
-### Deployed wizard link (give to client after S3 upload)
+### Deployed wizard link (give to client after preview upload)
 
 The client does **not** use localhost. After previews are uploaded, the CLI prints:
 
@@ -45,8 +84,9 @@ The client does **not** use localhost. After previews are uploaded, the CLI prin
    http://43.204.26.213:3000/wizard-app/index.html?session=<uuid>&secret=<hex>
 ```
 
-- **Previews:** stored in S3 under `sites/{surveyId}/wizard-sessions/{sessionId}/previews/`; wizard iframes load them via EC2 proxy (`GET /wizard/preview/:sessionId/:component/...`)
-- **Wizard UI:** served from EC2 at `/wizard-app/` (not CloudFront `sites/_wizard` — agents and clients use the EC2 link from `customize-ui`)
+- **Previews:** stored on **EC2 disk** (`WIZARD_DATA_DIR/{sessionId}/previews/`); wizard iframes load via `GET /previews/{sessionId}/{component}/index.html` (local-server API — same model as `customize`)
+- **Wizard UI:** served from EC2 at `/wizard-app/`; inventory via `GET /api/inventory`
+- **On submit:** final config + permanent logo → S3 only
 
 Set `CFM_DEPLOY_API_BASE=http://43.204.26.213:3000` (or your EC2 host). The link is built from that base + session credentials returned by `POST /wizard/session/start`.
 
@@ -71,13 +111,16 @@ Set `CFM_DEPLOY_API_BASE=http://43.204.26.213:3000` (or your EC2 host). The link
 
 Poll response includes `logoUrl` and `logoKey` — CLI merges `logo.url` into final JSON.
 
+**EC2 logo vs deploy bundle:** `logoUrl` points to `sites/{surveyId}/assets/{fileName}` on CloudFront. That path is for **wizard handoff** (download into `public/` via `confirm-ui-config`). The **live survey** loads the logo from `sites/{surveyId}/{deployId}/{fileName}` only after you rebuild and run Phase 7 deploy. Apply `data-cfm-logo src="./{fileName}"` then deploy — see [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
 **If all diff counts are 0:** client submitted without changes — still verify; skip heavy apply.
 
 ### S3 garbage collection
 
 | When | Deleted | Kept |
 |------|---------|------|
-| Client **Review & Build** | `wizard-sessions/{sessionId}/` (previews, seed-config, temp logo) | `sites/{surveyId}/assets/{logo}`, `wizard/config.json` |
+| Client **Review & Build** | EC2 session disk folder (`data/wizard-sessions/{sessionId}/`) | `sites/{surveyId}/assets/{logo}`, `wizard/config.json` |
+| Client **Quit** (or tab close) | Same session prefix — `POST /wizard/session/quit` | N/A |
 | Session **expires** (2h default) | Same session prefix — auto sweep every 5 min | N/A |
 
 ### Step 3 — Agent reads diff before touching code
@@ -216,6 +259,8 @@ npx cfm-sdk fetch-ui-config
 - [ ] `src/styles/survey-theme.css` fully synced to final config
 - [ ] All `data-cfm-*` content hooks updated
 - [ ] Logo file exists in `public/` when config has `global.logo.fileName`
+- [ ] `out/{fileName}` exists after build when logo configured (AWS deploy gate)
+- [ ] `Header.tsx` uses `data-cfm-logo src="./{fileName}"` — not `data:` or `/assets/` URL
 - [ ] `placeholders` / `customFields` / `debug` wired if present in final
 - [ ] AWS: ran `npx cfm-sdk confirm-ui-config` after codebase apply
 - [ ] `verify-agent-build.sh` + `npm run build` pass
@@ -228,11 +273,14 @@ npx cfm-sdk fetch-ui-config
 | Mistake | Fix |
 |---------|-----|
 | Killed CLI during poll | Re-run `customize-ui`; client re-submits |
+| Client quit wizard | CLI exits with abandon message; S3 GC done — re-run `customize-ui` for new session |
 | Applied from `survey-ui-config.json` while still seed | Use `.final.json` or run `confirm-ui-config` after apply |
 | Only changed primary color, ignored diff | Read **entire** `diff.md` — clients often change 20+ paths |
 | Skipped `confirm-ui-config` | Active JSON stays seed; next wizard re-open is wrong |
 | Changed `Question.tsx` dispatch during apply | UI tokens only — see `apply-ui-config.md` scope |
 | Proceeded to deploy before apply | Complete Phase 6c first |
+| Logo works in wizard but broken on CloudFront | Preview uses memory; deploy needs `public/` → `out/` → S3 — see `aws-deploy.md` § Logos |
+| Used `global.logo.url` as Header src | Use `./{fileName}` only; download assets URL via `confirm-ui-config` |
 
 ---
 

package/templates/docs/00-integration/wizard-preview-build-guide.md

@@ -1,10 +1,13 @@
 # Wizard Live Preview — Client Build Guide
 
 > **Read during Phase 5 (BUILD) — mandatory.** Wizard **run** (Phase 6b) is optional; this contract is required for every agent build.  
+> **Authoritative hook list + copy commands:** [`wizard-chrome-contract.md`](wizard-chrome-contract.md) — fixes logo, layout toggles, question card, and per-type preview issues.  
 > Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
 
 Related docs:
 
+- [`wizard-chrome-contract.md`](wizard-chrome-contract.md) — **copy-first templates** + symptom → fix table
+
 - [`ui-customization-wizard.md`](ui-customization-wizard.md) — wizard flow and CLI
 - [`apply-ui-config.md`](apply-ui-config.md) — applying final `survey-ui-config.json` after wizard
 - [`wizard-api.md`](wizard-api.md) — EC2 `/wizard/*` API
@@ -20,13 +23,13 @@ The wizard does **not** re-render your React app. It loads **static preview page
 sequenceDiagram
   participant Agent as Agent_build
   participant CLI as export_previews
-  participant S3 as S3_previews
+  participant Disk as EC2_or_agent_disk
   participant Wizard as Wizard_SPA
   participant Iframe as Preview_iframe
 
   Agent->>Agent: Build components with token contract
-  Agent->>CLI: customize-ui / export-previews
-  CLI->>S3: Upload HTML + JS + CSS
+  Agent->>CLI: customize (default) / customize-ui (remote)
+  CLI->>Disk: Upload HTML + JS + CSS (local-server)
   Wizard->>Iframe: Load chrome / MCQ_single / etc.
   Wizard->>Iframe: postMessage SNAPSHOT + DELTA
   Iframe->>Iframe: Apply --cfm-* vars + content patches
@@ -51,14 +54,25 @@ If components use **hardcoded** colors (`bg-[#e20074]`) with no `var(--cfm-*)` h
 
 ## Required project artifacts (Phase 5)
 
-Create these **before** the client opens the wizard:
+**Copy wizard-ready templates first** (do not hand-write chrome from `apps/client`):
+
+| Template (SDK) | Copy to |
+|----------------|---------|
+| `templates/docs/templates/Header.tsx` | `src/components/Header.tsx` |
+| `templates/docs/templates/Footer.tsx` | `src/components/Footer.tsx` |
+| `templates/docs/templates/ProgressBar.tsx` | `src/components/ProgressBar.tsx` |
+| `templates/docs/templates/SurveyStickyChrome.tsx` | `src/components/SurveyStickyChrome.tsx` |
+| `templates/docs/templates/LanguageSelector.tsx` | `src/components/LanguageSelector.tsx` |
+| `templates/docs/templates/PreviewBridgeInit.tsx` | `src/components/PreviewBridgeInit.tsx` |
+| `templates/previewBridge.ts` | `src/lib/previewBridge.ts` |
+| `templates/survey-theme.css` | `src/styles/survey-theme.css` |
+| `templates/docs/templates/Question.tsx` | `src/components/Question.tsx` (dispatcher base) |
+
+Full symptom → fix table: [`wizard-chrome-contract.md`](wizard-chrome-contract.md).
 
 | File | Purpose |
 |------|---------|
-| `src/styles/survey-theme.css` | All `--cfm-*` CSS custom properties (defaults from mockup) |
 | `survey-ui-config.json` (draft) | Seeds wizard form fields from agent branding |
-| `src/lib/previewBridge.ts` | Live bridge in **local dev** (`npx cfm-sdk customize`) — copy from `templates/previewBridge.ts` |
-| `src/components/PreviewBridgeInit.tsx` | Mount bridge once in `layout.tsx` (local dev only) |
 
 Import theme in `globals.css`:
 
@@ -271,6 +285,7 @@ CLI resolution order:
 - **Image logo:** put file in `public/`, reference exact path on `<img data-cfm-logo src="/your-logo.svg" />`. CLI base64-encodes that file for the wizard preview.
 - **Text logo:** use `<span data-cfm-logo-text>` in the logo slot (CSS shapes optional). Omit `data-cfm-logo` img. Wizard shows company text until client uploads an image.
 - **After wizard upload:** `global.logo.fileName` in saved config takes precedence — do not fall back to `Header.tsx` or scan `public/logo_*`.
+- **AWS deploy:** logo file must be in `out/{fileName}` with `data-cfm-logo src="./{fileName}"` — wizard preview memory is not uploaded. See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
 
 Debug without opening wizard:
 
@@ -284,20 +299,20 @@ Keep draft JSON and `survey-theme.css` **in sync** (same primary color, title, c
 
 ## How `export-previews` uses your code
 
-When the client opts in, `customize-ui` runs `export-previews`:
+When the client opts in, **`npx cfm-sdk customize`** (default) or `customize-ui` (remote) runs `export-previews`:
 
 1. Copies `src/components/`, `src/lib/`, `public/`, `survey-theme.css` into a temp Vite harness
 2. Stubs `next/image` and `next/dynamic` for static build
 3. Builds one HTML page per preview key (`header`, `chrome`, `MCQ_single`, …) with canonical fixtures
 4. Injects `preview-bridge.inline.js` into each `index.html`
-5. Uploads each preview page to S3 via EC2 presigned PUTs
+5. Uploads each preview page to **EC2 disk** via `PUT /wizard/session/:id/preview-file` (local-server model)
 6. Prints the **deployed wizard link** for the client:
 
 ```
 http://43.204.26.213:3000/wizard-app/index.html?session=<uuid>&secret=<hex>
 ```
 
-7. Wizard iframes load previews via EC2 proxy (`GET /wizard/preview/:sessionId/:component/...`)
+7. Wizard iframes load previews from `/previews/{sessionId}/{component}/…` on the same EC2 host (`GET /api/inventory` + local-server API)
 
 **Agent handoff:** after step 5–6, copy the printed link and send it to the client. The client customizes on EC2 only — not localhost.
 
@@ -356,6 +371,10 @@ npx cfm-sdk export-previews
 | Logo `<Image>` without `data-cfm-logo` | Logo step doesn't update preview | Add `data-cfm-logo` to img |
 | Only Phase 6c tokenization | Worked after wizard, not during | Tokenize in Phase 5 (this guide) |
 | Skipped `export-previews` after component edits | Wizard shows old UI | Re-run `customize-ui` |
+| Used `customize-ui` when client is on same machine | Unnecessary complexity | Use **`customize`** (default) |
+| `surveyTypes` only lists fetched survey types | Wizard shows one question type (e.g. NPS only) | `customize-ui` exports all 11 types; mockup image ≠ wizard inventory |
+| Missing `data-cfm-progress` / `data-cfm-question-number` | Layout toggles don't work | Wire hooks per § Layer 2 table |
+| Hardcoded brand hex in scales | Only NPS-like paths look correct | Use `--cfm-*` + `selectionStyles.ts` |
 
 ---
 
@@ -365,7 +384,7 @@ npx cfm-sdk export-previews
 |-------|----------------|
 | **5 BUILD** | Implement components per this guide + UI specs; draft config + theme |
 | **6 VERIFY** | `npm run build`, verify script, localhost preview |
-| **6b WIZARD** (optional) | Client says yes → `customize-ui` → **wait** for submit → read `.diff.md` |
+| **6b WIZARD** (optional) | Client says yes → **`npx cfm-sdk customize`** → wait for save → apply config |
 | **6c APPLY** | Apply **all** paths from `survey-ui-config.final.json` per [`wizard-config-handoff.md`](wizard-config-handoff.md) + [`apply-ui-config.md`](apply-ui-config.md) → `confirm-ui-config` |
 | **7 DEPLOY** | Full static build upload (separate from wizard preview files) |
 

package/templates/docs/00-integration/wizard-question-type-styling.md

@@ -172,7 +172,9 @@ For production builds after wizard: syncing `survey-theme.css` is sufficient —
 
 ## Agent checklist (per survey type)
 
-For each type in survey inventory:
+**Wizard customization** exposes all **11** question types regardless of fetched survey inventory. Wire styling for every scale template you copy — not only types in the client's mockup image.
+
+For each type in **wizard export** (all 11):
 
 - [ ] Scale component uses `var(--cfm-*)` for every wizard-exposed token (no hardcoded brand hex)
 - [ ] Radio/scale selections use `selectionStyles.ts` pattern (focus ring + cell selected)
@@ -191,5 +193,5 @@ For each type in survey inventory:
 | [`templates/selectionStyles.ts`](../templates/selectionStyles.ts) | Copy to client `src/lib/surveyUi/` |
 | [`templates/labelStyles.ts`](../templates/labelStyles.ts) | Copy to client `src/lib/surveyUi/` |
 | [`templates/survey-theme.css`](../../survey-theme.css) | Full `--cfm-*` defaults |
-| [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md) | Chrome + bridge contract |
+| [`wizard-troubleshooting.md`](wizard-troubleshooting.md) | Mock preview, local vs EC2, toggle/logo fixes |
 | [`apply-ui-config.md`](apply-ui-config.md) | Post-wizard apply workflow |

package/templates/docs/00-integration/wizard-troubleshooting.md

@@ -0,0 +1,80 @@
+# Wizard Troubleshooting — Agent Guide
+
+> Companion: [`ui-customization-wizard.md`](ui-customization-wizard.md), [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md).
+
+## Default command
+
+**When client says yes → run `npx cfm-sdk customize`** (not `customize-ui` unless client is on another device).
+
+| | `customize` **(default)** | `customize-ui` **(fallback)** |
+|--|---------------------------|--------------------------------|
+| **When** | Client on same machine as agent | Client on different device |
+| **URL** | `localhost:4200` | EC2 link with `session` + `secret` |
+| **Previews** | `out/previews/` on agent disk | EC2 disk |
+| **Save** | `survey-ui-config.json` immediately | Poll → `.final.json` + `.diff.md` |
+| **GC** | CLI stops → no orphans | Session cleanup on EC2 |
+
+---
+
+## Mock preview instead of live components
+
+### Symptom
+
+Footer: **"Mock preview — run customize or customize-ui…"**
+
+### Fix
+
+1. Run `npx cfm-sdk customize` — auto-runs `export-previews` if needed
+2. Ensure `src/components/Question.tsx` exists (Phase 5 build complete)
+3. Re-run if you changed components after last export
+
+---
+
+## Client on another device opened localhost
+
+### Symptom
+
+Client cannot open `http://localhost:4200`
+
+### Fix
+
+Use EC2 fallback:
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+```
+
+Send **only the EC2 link** from CLI output.
+
+---
+
+## Storage service unavailable (EC2 only)
+
+Only applies to **`customize-ui`** on submit — S3 denied when saving final config/logo. Previews on EC2 disk do not need S3.
+
+Fix: EC2 IAM + `HOSTING_BUCKET` on deploy-api.
+
+For same-machine clients, use **`customize`** — no S3 during wizard at all.
+
+---
+
+## Logo / toggles / layout not updating
+
+Wire `data-cfm-*` hooks and `--cfm-*` CSS vars per [`wizard-preview-build-guide.md`](wizard-preview-build-guide.md).
+
+---
+
+## Only one question type showing
+
+`customize` exports **all 11** types. Mockup may show NPS only — wizard still customizes all types.
+
+---
+
+## Checklist
+
+- [ ] Used **`customize`** as default when client said yes
+- [ ] Waited for `✅ UI configuration saved`
+- [ ] Phase 5 preview bridge + `data-cfm-*` wired
+- [ ] EC2 only if client on remote device

package/templates/docs/01-components/10-header-footer.md

@@ -25,12 +25,12 @@ Agents must implement **one** of these wizard-compatible patterns in `Header.tsx
 
 | Mode | When | Required markup |
 |------|------|-----------------|
-| **Image** | Brand asset in `public/` | `<img data-cfm-logo src="/exact-file.svg" />` plus hidden `<span data-cfm-logo-text>` fallback |
+| **Image** | Brand asset in `public/` | `<img data-cfm-logo src="./exact-file.svg" />` for AWS deploy (`assetPrefix: './'`). Use `/exact-file.svg` only for local dev. Include hidden `<span data-cfm-logo-text>` fallback. |
 | **Text** | CSS-only logo from prompt (no image file) | `<span data-cfm-logo-text>Company</span>` in logo slot — no `data-cfm-logo` img |
 
-- **NO EXTERNAL URLS** for logos (`https://…`).
+- **NO EXTERNAL URLS** for logos (`https://…`, wizard `/assets/` URLs, or `data:image/…`).
 - **CSS-only logos** use `data-cfm-logo-text` (and optional CSS shapes) — wizard shows text until client uploads an image.
-- After wizard upload, saved `global.logo.fileName` is used on subsequent sessions — see `wizard-preview-build-guide.md`.
+- After wizard upload, set `src="./{global.logo.fileName}"` from saved config — see [`aws-deploy.md`](../00-integration/aws-deploy.md) § Logos & local assets.
 
 ## Theme Engineering
 - Map the primary brand color to the accent and border colors across the entire survey.

package/templates/docs/01-components/19-survey-sticky-chrome.md

@@ -1,30 +1,28 @@
 # Survey Sticky Chrome
 
-> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`
-> **Reference implementation:** `apps/client/src/components/SurveyStickyChrome.tsx`
+> **UI spec (authoritative):** `03-ui-specs/12-survey-chrome.md`  
+> **Wizard contract:** [`wizard-chrome-contract.md`](../00-integration/wizard-chrome-contract.md) — header and progress are **separate** toggle targets  
 > **Template:** [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx)
-> **Component**: `SurveyStickyChrome`
 
 ## Purpose
 
-Wrap **Header + ProgressBar** in a single `sticky top-0` container so the progress bar stays visible when the respondent scrolls to answer questions lower on the page (especially the last question on a multi-question page).
+Wrap **Header + ProgressBar** in a sticky container. The wizard toggles them **independently**:
 
-## Props
+| Toggle | Target |
+|--------|--------|
+| `showHeader` | `.cfm-header` on `<header>` only |
+| `showProgressBar` | `[data-cfm-progress]` / `.cfm-progress` only |
 
-```typescript
-type SurveyStickyChromeProps = {
-  progressPercentage: number; // from state.progressPercentage
-};
-```
+Do **not** put class `cfm-header` on the sticky wrapper.
 
-## Implementation
+## Implementation (wizard-ready)
 
 ```tsx
 export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyChromeProps) {
   return (
-    <div className="sticky top-0 z-30 bg-white shadow-[0_2px_8px_rgba(0,0,0,0.06)]">
+    <div className="cfm-sticky-chrome sticky top-0 z-30" style={{ background: 'var(--cfm-header-bg)' }}>
       <Header embedded />
-      <div className="mx-auto w-full max-w-4xl px-4 pb-5 pt-4 sm:px-6 lg:px-8">
+      <div className="mx-auto w-full px-4" style={{ maxWidth: 'var(--cfm-max-width)' }}>
         <ProgressBar progressPercentage={progressPercentage} />
       </div>
     </div>
@@ -32,48 +30,11 @@ export default function SurveyStickyChrome({ progressPercentage }: SurveyStickyC
 }
 ```
 
-## Spacing (logo → progress bar)
-
-Keep a visible gap between the logo block and the progress track — do **not** flush them together.
-
-| Token | Tailwind | Purpose |
-|-------|----------|---------|
-| Top inset | `pt-4` | 16px gap below logo / header row |
-| Bottom inset | `pb-5` | 20px gap above scrollable question content |
-| Horizontal | `px-4 sm:px-6 lg:px-8` | Align track with `main` content column (`max-w-4xl`) |
-
-## Header `embedded` prop
-
-When `Header` is inside sticky chrome, pass `embedded` to avoid a double shadow:
-
-```tsx
-<header className={`relative h-[120px] w-full bg-white ${embedded ? '' : 'z-10 shadow-[0_2px_8px_rgba(0,0,0,0.06)]'}`}>
-```
-
-Use the standalone `Header` (no `embedded`) on intro, end, loading, and terminal pages.
-
-## SurveyPage wiring (content phase only)
-
-```tsx
-<div className="flex min-h-screen flex-col bg-white">
-  <SurveyStickyChrome progressPercentage={state.progressPercentage} />
-
-  <main className="mx-auto w-full max-w-4xl flex-1 px-4 py-10 sm:px-6 lg:px-8">
-    <LanguageSelector ... />
-    {/* questions + nav */}
-  </main>
-
-  <Footer />
-</div>
-```
-
-Do **not** render a separate `ProgressBar` inside `<main>` — it belongs in sticky chrome only.
+Copy full file from [`templates/SurveyStickyChrome.tsx`](../templates/SurveyStickyChrome.tsx).
 
 ## Agent checklist
 
-- [ ] `SurveyStickyChrome` (or equivalent sticky wrapper) on `phase.kind === 'content'`
-- [ ] `ProgressBar` bound to `state.progressPercentage`
-- [ ] `sticky top-0 z-30 bg-white` on wrapper; single shadow on wrapper, not Header
-- [ ] `pt-4` gap between logo and progress track; `pb-5` below track
-- [ ] Progress track aligned to same `max-w-4xl` as question content
-- [ ] Standalone `Header` on intro / end / loading / terminal branches
+- [ ] `Header.tsx` has class `cfm-header` + `data-cfm-logo` + `data-cfm-company`
+- [ ] `ProgressBar.tsx` has `data-cfm-progress` + class `cfm-progress`
+- [ ] Sticky wrapper uses `cfm-sticky-chrome` — not `cfm-header`
+- [ ] `pt`/`pb` spacing via `--cfm-sticky-pt` / `--cfm-sticky-pb`