@explorer02/cfm-survey-sdk 0.2.4 → 0.2.6

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

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

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

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

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

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

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

@@ -1,134 +1,126 @@
-# Wizard API (`/wizard/*`)
+# Wizard API — EC2 fallback (`customize-ui` only)
 
-> EC2 middle API routes for AWS-hosted UI customization. Consumed by `npx cfm-sdk customize-ui` and the survey-wizard SPA.
+> **Default wizard is `npx cfm-sdk customize` on localhost** — no EC2 API needed.  
+> This doc applies **only** when the client customizes from another device.
 
-Base URL: `CFM_DEPLOY_API_BASE` — production default: `http://43.204.26.213:3000`
+Base URL: `CFM_DEPLOY_API_BASE` — default: `http://43.204.26.213:3000`
 
-## Client wizard link (deployed)
+## Architecture
 
-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}
+```mermaid
+flowchart LR
+  CLI[customize-ui CLI] -->|PUT preview files| Disk[EC2 disk data/wizard-sessions/]
+  Client[Client browser] --> SPA[wizard-app SPA]
+  SPA -->|GET /api/inventory| API[deploy-api]
+  SPA -->|iframe /previews/...| Disk
+  SPA -->|POST /api/save-config| API
+  API -->|final config + logo| S3[S3 hosting bucket]
+  CLI -->|poll GET /wizard/config| API
 ```
 
-Example:
+| During session | Storage |
+|----------------|---------|
+| Preview HTML | EC2 disk (`WIZARD_DATA_DIR/{sessionId}/previews/`) |
+| Seed config | EC2 disk (`seed-config.json`) |
+| Temp logo | EC2 disk (`assets/`) |
+| **On submit** | Final JSON + permanent logo → S3 |
+
+Previews are **not** loaded from S3 during customization — avoids "Storage service unavailable" on preview iframes.
+
+## Client wizard link
 
 ```
-http://43.204.26.213:3000/wizard-app/index.html?session=abc-123&secret=fe7698d0...
+{CFM_DEPLOY_API_BASE}/wizard-app/index.html?session={sessionId}&secret={sessionSecret}
 ```
 
-| Piece | Role |
+| Route | 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
+| `/wizard-app/` | Wizard SPA |
+| `/api/inventory` | Session metadata + `previewManifest` (local-server API) |
+| `/previews/{sessionId}/{key}/index.html` | Component preview iframes |
+| `/api/save-config` | Client submit (same as local `customize`) |
 
-### `POST /wizard/session/start`
-
-Starts session; returns presigned PUT URLs for preview HTML files.
-
-**Body:** `{ "files": [...], "surveyTypes": ["MCQ", "NPS_SCALE"], "initialConfig": { ... } }`
+## Local-server routes (`/api/*`, `/previews/*`)
 
-`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.
+Same contract as `packages/sdk/src/cli/customize.ts`:
 
-**Response:** `{ sessionId, sessionSecret, wizardUrl, uploads[] }`
+### `GET /api/inventory?session=&secret=`
 
-### `POST /wizard/previews/upload/complete`
+Returns `{ surveyTypes, instanceId, previewUrl, previewManifest, initialConfig, localServer: true }`.
 
-**Body:** `{ "sessionId": "uuid" }`
+### `GET /api/preview-url`
 
-Activates session; builds same-origin `previewManifest` (API proxy URLs — session previews are private in S3).
+Health check for preview availability indicator.
 
-### `GET /wizard/preview/:sessionId/:component/index.html?secret=...`
+### `POST /api/upload-logo?session=&secret=`
 
-Serves preview HTML from S3 for wizard iframes. Auth via `secret` query param (iframes cannot send session headers).
+Body: `{ filename, base64 }` — stores logo on EC2 disk for session.
 
-### `GET /wizard/session/:sessionId`
+### `POST /api/save-config?session=&secret=`
 
-Wizard boot — returns `surveyTypes`, `previewManifest`, `sessionExpiresAt`, and `initialConfig` when the session was seeded.
+Body: full `survey-ui-config.json`. Persists final config + logo to S3, cleans session disk.
 
-**Response:** `{ surveyTypes, instanceId, previewManifest, sessionExpiresAt, initialConfig? }`
+## Session management (`/wizard/*`)
 
-The wizard SPA calls `loadConfig(initialConfig)` on boot so the client edits on top of the agent build.
+### `POST /wizard/session/start`
 
-### `POST /wizard/logo`
+**Auth:** `Authorization: Bearer {JWT}`
 
-**Body:** `{ "filename": "logo.png", "base64": "data:image/png;base64,..." }`
+**Body:** `{ files, surveyTypes, initialConfig }`
 
-Max 512KB. Stores in session S3 prefix.
+**Response:** `{ sessionId, sessionSecret, wizardUrl, uploads[], localServer: true }`
 
-### `POST /wizard/complete`
+`uploads[].uploadUrl` → `PUT /wizard/session/:sessionId/preview-file?path=previews/...` (EC2 disk, not S3 presign).
 
-**Body:** full `survey-ui-config.json` object.
+### `PUT /wizard/session/:sessionId/preview-file?path=...`
 
-On success:
+**Auth:** `X-Wizard-Session` + `X-Wizard-Session-Id`
 
-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 }`
+Raw file body → written to session disk.
 
-Public logo URL format: `{CLOUDFRONT_BASE_URL}/sites/{surveyId}/assets/{fileName}` — readable by anyone with the link (via CloudFront, bucket stays private).
+### `POST /wizard/previews/upload/complete`
 
-### `GET /wizard/config/:surveyId`
+**Auth:** JWT. Verifies all files on disk; activates session; builds manifest with `/previews/{sessionId}/…` URLs.
 
-CLI poll. Query `?sessionId=` to scope to current session.
+### `POST /wizard/session/quit`
 
-**Pending:** `{ "status": "pending" }`  
-**Ready:** `{ "status": "ready", "config": { ... }, "logoUrl": "...", "logoKey": "...", "sessionId": "..." }`
+Deletes session disk folder + in-memory session. CLI poll returns `status: abandoned`.
 
-`config.global.logo.url` is populated with the public CloudFront URL when a logo was uploaded.
+### `GET /wizard/config/:surveyId?sessionId=`
 
-### `GET /wizard/logo/:surveyId/:fileName`
+CLI poll after client submit.
 
-Returns `{ "downloadUrl": "presigned-get" }` for CLI to save logo to agent `public/` (fallback when CloudFront is not reachable from agent network).
+- **pending** — waiting
+- **abandoned** — client quit
+- **ready** — `{ config, logoUrl, … }`
 
 ## 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
+WIZARD_DATA_DIR=./data/wizard-sessions   # preview + seed + temp logo on disk
+WIZARD_SESSION_TTL_MS=7200000
+HOSTING_BUCKET=...                        # final config + permanent logo only
+CLOUDFRONT_BASE_URL=...
 ```
 
-## AWS console (one-time — logo public URL)
+## IAM (EC2 instance role)
 
-Logos are **not** public on S3 directly. They are served through **CloudFront** (same distribution as survey deploys).
+Required for **submit** (not previews):
 
-Verify (usually already done if deploy works):
+- `s3:PutObject`, `s3:GetObject` on hosting bucket
+- `cloudfront:CreateInvalidation` (logo cache bust)
 
-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)
+## CLI flow
 
 ```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).
+1. `export-previews` on agent machine
+2. Upload preview files to EC2 disk
+3. Print client wizard link
+4. Poll until `status: ready`
+5. Write `.final.json` + `.diff.md`
+
+See [`wizard-config-handoff.md`](wizard-config-handoff.md), [`ui-customization-wizard.md`](ui-customization-wizard.md).