@explorer02/cfm-survey-sdk 0.2.3 → 0.2.4

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

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

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

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

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

@@ -0,0 +1,134 @@
+# Wizard API (`/wizard/*`)
+
+> EC2 middle API routes for AWS-hosted UI customization. Consumed by `npx cfm-sdk customize-ui` and the survey-wizard SPA.
+
+Base URL: `CFM_DEPLOY_API_BASE` — production default: `http://43.204.26.213:3000`
+
+## Client wizard link (deployed)
+
+After `customize-ui` uploads component previews to S3, the CLI prints a **deployed wizard URL** for the client:
+
+```
+{CFM_DEPLOY_API_BASE}/wizard-app/index.html?session={sessionId}&secret={sessionSecret}
+```
+
+Example:
+
+```
+http://43.204.26.213:3000/wizard-app/index.html?session=abc-123&secret=fe7698d0...
+```
+
+| Piece | Role |
+|-------|------|
+| `/wizard-app/` | Wizard SPA on EC2 (customization forms + preview panel) |
+| `session` + `secret` | Tie the client to the S3 preview session |
+| S3 `previews/` | Component-wise HTML (`header`, `footer`, `MCQ_single`, …) — loaded via EC2 proxy |
+
+**Agent:** copy link from CLI → send to client. **Client:** opens link only (no localhost). **Agent:** keeps CLI polling until submit.
+
+`wizardUrl` in `POST /wizard/session/start` response is this full URL (built by `getWizardPublicUrl` in deploy-api).
+
+## Auth
+
+| Caller | Header |
+|--------|--------|
+| CLI | `Authorization: Bearer {CFM_INSTANCE_ID}` |
+| Wizard SPA | `X-Wizard-Session: {secret}` + `X-Wizard-Session-Id: {sessionId}` |
+
+## Endpoints
+
+### `POST /wizard/session/start`
+
+Starts session; returns presigned PUT URLs for preview HTML files.
+
+**Body:** `{ "files": [...], "surveyTypes": ["MCQ", "NPS_SCALE"], "initialConfig": { ... } }`
+
+`initialConfig` is optional. When present, the CLI sends the agent's resolved UI config (from draft `survey-ui-config.json`, parsed `survey-theme.css`, `Header.tsx` logo contract, or defaults). The API normalizes, validates, stores on the session, and persists to `sites/{surveyId}/wizard-sessions/{sessionId}/seed-config.json` for restart durability.
+
+**Response:** `{ sessionId, sessionSecret, wizardUrl, uploads[] }`
+
+### `POST /wizard/previews/upload/complete`
+
+**Body:** `{ "sessionId": "uuid" }`
+
+Activates session; builds same-origin `previewManifest` (API proxy URLs — session previews are private in S3).
+
+### `GET /wizard/preview/:sessionId/:component/index.html?secret=...`
+
+Serves preview HTML from S3 for wizard iframes. Auth via `secret` query param (iframes cannot send session headers).
+
+### `GET /wizard/session/:sessionId`
+
+Wizard boot — returns `surveyTypes`, `previewManifest`, `sessionExpiresAt`, and `initialConfig` when the session was seeded.
+
+**Response:** `{ surveyTypes, instanceId, previewManifest, sessionExpiresAt, initialConfig? }`
+
+The wizard SPA calls `loadConfig(initialConfig)` on boot so the client edits on top of the agent build.
+
+### `POST /wizard/logo`
+
+**Body:** `{ "filename": "logo.png", "base64": "data:image/png;base64,..." }`
+
+Max 512KB. Stores in session S3 prefix.
+
+### `POST /wizard/complete`
+
+**Body:** full `survey-ui-config.json` object.
+
+On success:
+
+1. Copies uploaded logo to **permanent** S3 key: `sites/{surveyId}/assets/{fileName}`
+2. Saves final config to `sites/{surveyId}/wizard/config.json` (with `logoKey` + `logoUrl` metadata)
+3. **Deletes** entire wizard session folder `sites/{surveyId}/wizard-sessions/{sessionId}/` (previews, seed-config, temp logo)
+4. Returns public logo URL: `{ logoUrl, logoKey, logoFileName }`
+
+Public logo URL format: `{CLOUDFRONT_BASE_URL}/sites/{surveyId}/assets/{fileName}` — readable by anyone with the link (via CloudFront, bucket stays private).
+
+### `GET /wizard/config/:surveyId`
+
+CLI poll. Query `?sessionId=` to scope to current session.
+
+**Pending:** `{ "status": "pending" }`  
+**Ready:** `{ "status": "ready", "config": { ... }, "logoUrl": "...", "logoKey": "...", "sessionId": "..." }`
+
+`config.global.logo.url` is populated with the public CloudFront URL when a logo was uploaded.
+
+### `GET /wizard/logo/:surveyId/:fileName`
+
+Returns `{ "downloadUrl": "presigned-get" }` for CLI to save logo to agent `public/` (fallback when CloudFront is not reachable from agent network).
+
+## Env (deploy-api)
+
+```bash
+WIZARD_DEV_URL=http://localhost:5173   # dev only
+WIZARD_PATH=/sites/_wizard               # prod CloudFront path
+WIZARD_SESSION_TTL_MS=7200000            # 2h — expired sessions trigger S3 GC
+```
+
+## AWS console (one-time — logo public URL)
+
+Logos are **not** public on S3 directly. They are served through **CloudFront** (same distribution as survey deploys).
+
+Verify (usually already done if deploy works):
+
+1. **CloudFront** → your distribution → Origins → hosting bucket is the origin
+2. **Origin access** → OAC/OAI allows CloudFront to read the bucket (bucket policy blocks public access)
+3. **Behavior** → default or `sites/*` path serves objects from the bucket
+
+No extra bucket policy for public read is required. The public URL is:
+
+`https://{CLOUDFRONT_DOMAIN}/sites/{surveyId}/assets/{logoFileName}`
+
+**IAM (EC2 instance role)** must allow: `s3:PutObject`, `s3:GetObject`, `s3:DeleteObject`, `s3:ListBucket` on the hosting bucket, plus `cloudfront:CreateInvalidation` on the distribution.
+
+## CLI flow (review mode — default)
+
+```bash
+export CFM_INSTANCE_ID="..." CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+# export-previews → upload component previews to S3 → print client wizard link →
+# POLL until client submits → survey-ui-config.final.json + .diff.md
+# Agent applies codebase → npx cfm-sdk confirm-ui-config
+```
+
+See [`wizard-config-handoff.md`](wizard-config-handoff.md).

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

@@ -0,0 +1,246 @@
+# Wizard Config Handoff — Wait, Capture, Apply
+
+> **Phase 6b → 6c.** Read with [`ui-customization-wizard.md`](ui-customization-wizard.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
+
+This doc tells the agent **exactly** how to wait for the client to finish the wizard, capture the JSON output, and apply **every** change without omission.
+
+---
+
+## Prime rule
+
+**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`.
+
+**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).
+
+---
+
+## AWS flow (default — review mode)
+
+### Step 1 — Agent runs CLI (and waits)
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="<EC2 URL>"
+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`, …)
+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)
+
+The client does **not** use localhost. After previews are uploaded, the CLI prints:
+
+```
+🔗 Client wizard link — share with the client:
+   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`)
+
+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`.
+
+**Agent must:**
+
+- [ ] Keep the terminal process **running** — do not Ctrl+C while polling
+- [ ] Tell the client: *"Please complete all wizard steps and click **Review & Build** / save to finish."*
+- [ ] Wait until CLI exits **0** with `Configuration ready`
+- [ ] **Not** start Phase 6c apply until this completes
+
+**Timeout:** default 2 hours (`CFM_WIZARD_TIMEOUT_MS`). If timeout, ask client to re-run or use `fetch-ui-config` (see §5).
+
+### Step 2 — Review artifacts (written on success)
+
+| File | Role |
+|------|------|
+| `survey-ui-config.seed.json` | Snapshot before client edits |
+| `survey-ui-config.final.json` | Client config + `global.logo.url` (public CloudFront URL) |
+| `survey-ui-config.diff.json` / `.diff.md` | Every changed path — **read before apply** |
+| `survey-ui-config.json` | Still **seed** until `confirm-ui-config` |
+| `public/{logoFileName}` | Logo file downloaded from `logoUrl` |
+
+Poll response includes `logoUrl` and `logoKey` — CLI merges `logo.url` into final JSON.
+
+**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` |
+| Session **expires** (2h default) | Same session prefix — auto sweep every 5 min | N/A |
+
+### Step 3 — Agent reads diff before touching code
+
+```bash
+# Agent MUST open and read:
+cat survey-ui-config.diff.md
+```
+
+For **every** section in the diff (`Changed`, `Added`, `Removed`):
+
+1. Find the config path (e.g. `global.colorScheme.primary`)
+2. Look up apply target in [`apply-ui-config.md`](apply-ui-config.md) § Complete mapping
+3. Apply to the listed file/CSS var/`data-cfm-*` attribute
+4. Mark the path done (mental checklist or notes in `implementation_plan.md`)
+
+**Blocking rule:** If a path appears in the diff, it **must** be reflected in the codebase after Phase 6c.
+
+### Step 4 — Apply to codebase (Phase 6c)
+
+Follow [`apply-ui-config.md`](apply-ui-config.md) using **`survey-ui-config.final.json`** as input.
+
+Order:
+
+1. Validate `survey-ui-config.final.json` against `templates/survey-ui-config.schema.json`
+2. Regenerate `src/styles/survey-theme.css` from **all** tokens in final config (not only diff paths — full sync prevents missed derived vars)
+3. Apply `data-cfm-*` content patches (title, buttons, footer links, logo)
+4. Apply layout toggles in `SurveyPage` / chrome
+5. Apply `placeholders`, `customFields`, `debug` in hook options
+6. Re-run `bash templates/verify-agent-build.sh` and `npm run build`
+
+### Step 5 — Promote config + logo
+
+After codebase apply succeeds:
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="<EC2 URL>"
+npx cfm-sdk confirm-ui-config
+```
+
+This:
+
+- Copies `survey-ui-config.final.json` → `survey-ui-config.json`
+- Downloads logo to `public/{fileName}` when `global.logo.fileName` is set
+
+**Do not run `confirm-ui-config` before applying tokens to the codebase** — you would promote JSON while the UI still shows seed styling.
+
+Optional: `npx cfm-sdk confirm-ui-config --diff-only` to re-print diff without writing.
+
+---
+
+## Local flow (`customize`)
+
+```bash
+npx cfm-sdk customize
+```
+
+1. CLI starts wizard at `http://localhost:4200`
+2. **Blocks** until client clicks save → `POST /api/save-config`
+3. Writes **`survey-ui-config.json` directly** (no `.final.json` / diff artifacts)
+4. Prints `✅ UI configuration saved` and exits
+
+**Agent must:**
+
+- [ ] Wait for CLI to exit 0 after client saves
+- [ ] Apply from `survey-ui-config.json` per [`apply-ui-config.md`](apply-ui-config.md)
+- [ ] No `confirm-ui-config` step (not used locally)
+
+---
+
+## Legacy AWS mode (`--apply`)
+
+```bash
+npx cfm-sdk customize-ui --apply
+```
+
+Writes final config + logo immediately (no review artifacts). Still requires Phase 6c codebase apply from `survey-ui-config.json`.
+
+**Prefer default review mode** so the agent can audit `survey-ui-config.diff.md` before apply.
+
+---
+
+## Detached session (`--no-wait`)
+
+```bash
+npx cfm-sdk customize-ui --no-wait
+# CLI prints wizard URL and exits — client works asynchronously
+```
+
+When client finishes:
+
+```bash
+export CFM_WIZARD_SESSION_ID="<sessionId from CLI output>"
+npx cfm-sdk fetch-ui-config
+# Writes .final.json + .diff.md — then apply + confirm-ui-config
+```
+
+**Do not apply** until `fetch-ui-config` succeeds.
+
+---
+
+## Agent ↔ client script
+
+**When starting wizard (tell client after you send the link):**
+
+> *"I've uploaded your survey component previews to the cloud. Open this customization link: [paste deployed wizard URL]. Adjust branding, colors, and question-type styling — the preview panel shows your real components. When finished, click **Review & Build** on the last step. I'll wait here until your changes are saved."*
+
+**While waiting (agent):**
+
+- Do not refactor unrelated code
+- Do not start deploy
+- Do not re-run `customize-ui` (overwrites session artifacts)
+
+**After CLI success (tell client):**
+
+> *"Your wizard changes are captured. I'm applying them to the survey UI now and will verify the build."*
+
+---
+
+## Phase checklist
+
+### Phase 6b — Wizard session
+
+- [ ] Client explicitly said yes to wizard (INPUT 3)
+- [ ] `CFM_INSTANCE_ID` and `CFM_DEPLOY_API_BASE` set
+- [ ] Ran `npx cfm-sdk customize-ui` (or `customize` locally)
+- [ ] **Waited** until CLI exit 0 (`Configuration ready` or `UI configuration saved`)
+- [ ] AWS: `survey-ui-config.final.json` and `survey-ui-config.diff.md` exist
+- [ ] Read `survey-ui-config.diff.md` completely
+
+### Phase 6c — Apply (no skipped paths)
+
+- [ ] Applied from **`survey-ui-config.final.json`** (AWS) or **`survey-ui-config.json`** (local)
+- [ ] Every diff path in `changed` + `added` + `removed` addressed
+- [ ] `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`
+- [ ] `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
+- [ ] Visually spot-check: header, footer, progress, one question type from inventory
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Killed CLI during poll | Re-run `customize-ui`; client re-submits |
+| 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 |
+
+---
+
+## Related docs
+
+| Doc | Role |
+|-----|------|
+| [`apply-ui-config.md`](apply-ui-config.md) | Complete config path → file mapping |
+| [`wizard-api.md`](wizard-api.md) | Poll endpoint, complete payload |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Per-type CSS vars |
+| [`agent-operating-contract.md`](agent-operating-contract.md) | Anti-hallucination gates |