@explorer02/cfm-survey-sdk 0.2.4 → 0.2.5

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 automatically when the CLI exits (no orphan S3 garbage)
+- 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).

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

@@ -11,14 +11,51 @@ 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.
+
+---
+
+## Remote client flow — `customize-ui` (fallback only)
 
 ### Step 1 — Agent runs CLI (and waits)
 
@@ -31,12 +68,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 +82,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 +109,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 +257,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 +271,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

@@ -20,13 +20,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
@@ -271,6 +271,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 +285,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 +357,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 +370,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) |