@explorer02/cfm-survey-sdk 0.2.3 → 0.2.5

package/templates/docs/index.md

@@ -4,173 +4,170 @@
 
 Master guide for AI coding agents. Machine-readable index: `MANIFEST.json`.
 
+**Authoritative execution order:** [`00-integration/agent-operating-contract.md`](00-integration/agent-operating-contract.md) (read **first**) → [`agent-execution-flow.md`](00-integration/agent-execution-flow.md) → this file.
+
 **Installed package path:** `node_modules/@explorer02/cfm-survey-sdk/templates/docs/` (docs ship inside `templates/` — no postinstall copy needed).
 
+## Anti-hallucination (agents)
+
+Client-side coding agents **must not guess** SDK behavior. Before any code:
+
+1. Read [`agent-operating-contract.md`](00-integration/agent-operating-contract.md) — source hierarchy, phase gates, hallucination blocklist, doc routing table
+2. Read [`agent-execution-flow.md`](00-integration/agent-execution-flow.md) — pipeline and client questions
+3. For each fetched `question.type`, read MANIFEST `blueprint` + `reference` + `uiSpec` **before** implementing that type
+4. Copy from `docs/templates/` — do not rewrite dispatchers or scales from memory
+5. Run `verify-agent-build.sh` before claiming the build is done
+
+**Prime directive:** If it is not in these docs or templates, do not implement it.
+
 ## Documentation Layout
 
 ```
-templates/docs/              ← installed npm package layout
-packages/sdk/templates/docs/ ← monorepo layout
-├── index.md                 ← YOU ARE HERE
-├── MANIFEST.json            ← Phase + question-type routing (for tooling)
-├── 00-integration/          ← Setup, hook contract, constraints
-├── 01-components/           ← Wiring blueprints (read per type from MANIFEST)
-├── 02-reference/            ← Routing table, exports, config-field-index
-├── 03-ui-specs/             ← Authoritative UI specs
+templates/docs/
+├── index.md                      ← YOU ARE HERE
+├── MANIFEST.json                 ← Phase + question-type routing
+├── 00-integration/
+│   ├── agent-operating-contract.md ← Anti-hallucination — read FIRST
+│   ├── agent-execution-flow.md   ← Pipeline, client questions, wizard-ready build
+│   ├── wizard-preview-build-guide.md
+│   ├── wizard-question-type-styling.md
+│   └── …
+├── 01-components/                ← Wiring blueprints (per type from MANIFEST)
+├── 02-reference/                 ← Data shapes, routing, config fields
+├── 03-ui-specs/                  ← UI anatomy + wizard token sections
 └── templates/
-    ├── implementation_plan.md
-    ├── survey-inventory.schema.json
-    ├── verify-agent-build.sh
-    ├── deploy-to-aws.sh
-    ├── heatmapCoords.ts
-    └── Question.tsx           ← Canonical dispatcher (copy before building)
+    ├── Question.tsx              ← Canonical dispatcher (copy first)
+    ├── selectionStyles.ts        ← Wizard selection colors (copy to src/lib/surveyUi/)
+    ├── labelStyles.ts            ← Matrix/slider label items
+    ├── survey-theme.css          ← Full --cfm-* defaults
+    └── implementation_plan.md
 ```
 
-**Import rule:** Use whatever package name appears in the project's `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
+**Import rule:** Use whatever package name appears in `package.json` (`@explorer02/cfm-survey-sdk` or `@repo/sdk`).
 
 ## Do Not Read
 
 - Internal SDK mapper/source paths (`packages/sdk/src/**` or `node_modules/.../src/**`)
-- `cfm-sdk init`, `survey-config.json`, or any setup wizard
-- Stale `apps/client` code without verifying type literals against `MANIFEST.json` `typeLiterals`
+- Legacy `survey-config.json` or pre-build setup wizard
+- `apps/client` as implementation source — it is a reference snapshot only; agents build from `docs/templates/` + these docs
 
 ---
 
-## Client Inputs (3 only)
+## Client inputs (4) — when to ask
 
-1. **Initial prompt** — mockup, brand colors, layout preferences
-2. **Instance ID** — JWT token (agent asks in chat)
-3. **Deploy confirmation** — yes/no for production deploy
+| # | Phase | Agent question | Doc |
+|---|-------|----------------|-----|
+| 1 | Start | *(Client prompt — usually provided)* | Extract branding → `implementation_plan.md` |
+| 2 | Phase 2 | *"Please provide your survey instance ID (JWT token)."* | `useSurveySDK.md` |
+| 3 | Phase 6 | *"Your survey is running locally. Would you like to customize the UI through the web wizard?"* | `ui-customization-wizard.md` |
+| 4 | Phase 7 | *"Your survey is built and verified. Ready to deploy to production?"* | `aws-deploy.md` / deploy CLI |
 
-**Branding comes from INPUT 1 only.** No setup wizard. No `survey-config.json`.
+**Branding defaults from INPUT 1.** Wizard (INPUT 3) is optional — but Phase 5 build must still be **wizard-ready**.
 
 ---
 
-## Execution Pipeline
-
-### PHASE 0: ORIENT
+## Execution pipeline (summary)
 
-- Read this file and `AGENT.md`:
-  - **Monorepo:** `packages/sdk/templates/AGENT.md`
-  - **Installed npm:** `node_modules/@explorer02/cfm-survey-sdk/templates/AGENT.md`
-- Detect framework: read `package.json` — Next.js / Vite / CRA (see `00-integration/setup.md`)
-- Extract branding and layout from client prompt
-- For existing apps: read project structure; do not blindly scaffold
+Full step-by-step: [`agent-execution-flow.md`](00-integration/agent-execution-flow.md).
 
-### PHASE 1: SCAFFOLD
+| Phase | Goal | Key reads |
+|-------|------|-----------|
+| **0** Orient | Framework + branding | `index.md`, `AGENT.md`, `agent-execution-flow.md`, `MANIFEST.json` |
+| **1** Scaffold | Install SDK | `setup.md` |
+| **2** Instance ID | Get JWT | `useSurveySDK.md` — **ask client** |
+| **3** SDK contract | Hook + logic | `client-integration-guide.md`, `question-type-sdk-matrix.md`, logic docs |
+| **4** Plan | Inventory + copy dispatcher | `component-checklist.md`, per-type MANIFEST docs, `implementation_plan.md` |
+| **5** Build | Wizard-ready UI | `constraints.md`, `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, `03-ui-specs/*` |
+| **6** Verify | Build + dev server | `verify-agent-build.sh` — **ask wizard** |
+| **6b** Wizard | Optional customize | **`npx cfm-sdk customize`** (default) — EC2 `customize-ui` only if client on another device |
+| **6c** Apply | Sync final config | `apply-ui-config.md` |
+| **7** Deploy | Production | **ask deploy** — `aws-deploy.md` or Vercel |
 
-Read: `00-integration/setup.md` (matching framework section)
+**Auto-proceed:** Phase 4 → 5 and Phase 5 → 6 without waiting for approval.
 
-Install SDK + `@tanstack/react-query` + `react-icons`. Apply framework-specific config.
-
-### PHASE 2: INSTANCE ID (INPUT 2)
+---
 
-Read: `00-integration/useSurveySDK.md`
+### PHASE 5 — Build (wizard-ready, required artifacts)
 
-Ask: *"Please provide your survey instance ID (JWT token)."*
+Every agent build includes these even if the client later skips the wizard:
 
-### PHASE 3: SDK CONTRACT
+| Artifact | Source | Destination |
+|----------|--------|-------------|
+| Theme CSS | `templates/survey-theme.css` | `src/styles/survey-theme.css` |
+| Selection helpers | `templates/selectionStyles.ts` | `src/lib/surveyUi/selectionStyles.ts` |
+| Label helpers | `templates/labelStyles.ts` | `src/lib/surveyUi/labelStyles.ts` |
+| Preview bridge | `templates/previewBridge.ts` | `src/lib/previewBridge.ts` |
+| Dispatcher | `templates/Question.tsx` | `src/components/Question.tsx` |
+| Scale components | `templates/*Scale*.tsx` etc. | `src/components/` per inventory |
+| Draft config | agent-written | `./survey-ui-config.json` |
 
-Read: `00-integration/client-integration-guide.md` (start here), `00-integration/question-type-sdk-matrix.md`, `00-integration/useSurveySDK.md`, `02-reference/exports.md`, `00-integration/skip-logic-and-navigation.md`, `00-integration/display-logic-and-navigation.md`, `00-integration/question-display-variants.md`, `00-integration/question-numbering.md`, `00-integration/placeholders-and-tokens.md`, `00-integration/partial-save-and-recovery.md`, `00-integration/survey-lifecycle-analytics.md`, `00-integration/end-page-logic.md`, `00-integration/answer-logic-and-navigation.md`, `00-integration/custom-field-logic-and-navigation.md`, `00-integration/progress.md`, `02-reference/value-derivation.md`, `00-integration/logic-fields-catalog.md`, `00-integration/analytics-events-catalog.md`
+**Chrome:** `data-cfm-logo` / `data-cfm-logo-text`, `data-cfm-company`, `data-cfm-btn-next`, `data-cfm-btn-back`, `data-cfm-survey-title`, `data-cfm-thank-you` — see `wizard-preview-build-guide.md`.
 
-Understand `useSurveySDK`, `onAction`, `state.answers`. Do **not** read internal mapper/source paths.
+**Selection pattern:** focus ring = outer border + inner dot; cell selected = annulus fill — see `wizard-question-type-styling.md`.
 
-Optional: read `02-reference/routing-table.md` for type overview.
+**Forbidden:** stub branches, `subType` routing, changing `onAction` payloads, hardcoded hex for wizard-controlled tokens.
 
-### PHASE 4: PLAN + INGEST (CRITICAL)
+Copy scale templates: `SliderMatrixScale`, `LikertMatrixScale`, `CsatMatrixScale`, `RatingScale`, `FileUploadScale`, `HeatmapScale`, `RankOrderScale`, `MatrixDropdown`, `CustomSliderTrack`, `surveyUiIcons`, `surveyUiScaleUtils`, `heatmapCoords`, `customFieldValues` (when needed).
 
-1. Fetch survey with `instanceId`; extract unique `question.type` values from `survey.pages`
-2. Write inventory to `implementation_plan.md` §3b (validate against `templates/survey-inventory.schema.json`)
-3. Read **always**: `component-checklist.md`, `00-integration/question-type-sdk-matrix.md`, `03-ui-specs/00-question-shell.md`, `03-ui-specs/12-survey-chrome.md`, `01-components/01-survey-page.md`, `01-components/02-question.md`, `01-components/14-intro-page.md`, `01-components/15-end-page.md`, `01-components/16-paused-page.md`
-4. For **each type in the survey**, read MANIFEST `questionTypes.{type}` → blueprint + reference + uiSpec; cross-check the matching row in `question-type-sdk-matrix.md`
-5. When config flags match MANIFEST `sharedUiSpecTriggers` (e.g. `gridLayout:dropdown`, `displayStyle:graphics`) → read matching `03-ui-specs/shared/` specs
-6. Copy `docs/templates/implementation_plan.md` → `./implementation_plan.md` and fill every section
-7. Copy `docs/templates/Question.tsx` as the dispatcher starting point
-8. **Auto-proceed to Phase 5** — do not wait for approval
+---
 
-**Fallback:** If survey fetch fails, read all `01-components/*.md` blueprints before coding.
+### PHASE 6 — Verify checklist
 
-### PHASE 5: BUILD
+- [ ] `Question.tsx` covers all **11** `question.type` values (flat literals)
+- [ ] Zero `"not yet implemented"` matches
+- [ ] `src/styles/survey-theme.css` + `selectionStyles.ts` + `labelStyles.ts` present
+- [ ] Chrome `data-cfm-*` hooks on Header, SurveyPage, Intro/End
+- [ ] `npm run build` exits 0
+- [ ] Dev server loads survey
+- [ ] AWS: `out/index.html` exists; file count ≤ 500
 
-Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`, `00-integration/question-type-sdk-matrix.md`
+Run: `bash templates/verify-agent-build.sh`
 
-Create all required scale component files **before** wiring `Question.tsx`. **Copy portable templates** from `docs/templates/` when listed in `component-checklist.md` (`RankOrderScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx`, `surveyUiIcons.tsx`, `heatmapCoords.ts`). For each question in the survey:
+---
 
-1. Read the matching row in `question-type-sdk-matrix.md` (answer shape, visibility helper, performance)
-2. Read `02-reference/question-types/` doc for data shape (MANIFEST `reference`)
-2. Read matching `03-ui-specs/` (MANIFEST `uiSpec`)
-3. If `gridLayout`, `displayStyle`, or `statementLayout` triggers shared specs → read `03-ui-specs/shared/`
-4. Cross-check `02-reference/config-field-index.md` for every non-default field
-5. Implement per ui-spec — trust SDK Integration Checklist in blueprint/reference + `templates/Question.tsx` + exported SDK types + `02-reference/value-derivation.md`
+### PHASE 6b / 6c — Wizard (wait → apply every change)
 
-Implement components per blueprints + UI specs. Use exported types:
+Only after Phase 6 passes and client says **yes**:
 
-```typescript
-import { useSurveySDK, ACTIONS, QUESTION_TYPE, type SurveyAction } from '@explorer02/cfm-survey-sdk';
+```bash
+npx cfm-sdk customize   # DEFAULT — opens localhost:4200, WAITS until client saves
 ```
 
-**Dispatch on flat `question.type` only** — **11** `QUESTION_TYPE` literals, no `subType`. See `MANIFEST.json` `typeLiterals`.
-
-**AWS deploy prep (when client prompt mentions AWS / CloudFront / S3 / EC2 / Sprinklr):** apply Next.js static export config **during this phase**, not at deploy time. Read `00-integration/setup.md#nextjs-aws-static-export` and `00-integration/aws-deploy.md` § Build Config. Fill `implementation_plan.md` §8.
-
-### PHASE 6: VERIFY
-
-Read: `00-integration/constraints.md` (troubleshooting)
+**Phase 6b:** Client on same machine → `customize` writes `survey-ui-config.json` directly. Remote client → `customize-ui` + EC2 link (see `wizard-troubleshooting.md`). Apply per `apply-ui-config.md`.
 
-Run: `bash templates/verify-agent-build.sh` (from project root, after copying script if needed)
-
-Checklist:
-
-- [ ] `Question.tsx` copied from `docs/templates/Question.tsx` — covers all **11** `question.type` values
-- [ ] Each matrix variant routes by its own type literal (`CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`) — **no `subType`**
-- [ ] All scale components from `component-checklist.md` exist for types in survey
-- [ ] **Zero stub text:** `grep -r "not yet implemented" src/ components/ app/` returns no matches
-- [ ] Every question wrapper has `id={question.id}`
-- [ ] No imports from `@explorer02/cfm-survey-sdk/src/...` or `@repo/sdk/src/...`
-- [ ] `SurveyPage` handles loading / error / empty / all `state.phase` values / active content
-- [ ] Hook uses `state.answers`, `state.canGoBack`, `state.primaryButtonType`, and `payload.answerValue`
-- [ ] Stable `customFieldValues` ref when survey uses custom-field logic; passed to hook and `Question` visibility helpers
-- [ ] `SURVEY_PLACEHOLDERS` stable ref; `surveyOptions` in `useMemo` (see `placeholders-and-tokens.md`)
-- [ ] `SCROLL` + `RECORD_QUESTION_VIEW` lifecycle effects wired (see `survey-lifecycle-analytics.md`)
-- [ ] Monorepo: `packages/sdk` built before client dev (`npm run build`)
-- [ ] `npm run build` exits 0
-- [ ] **AWS intent:** `out/index.html` exists; file count ≤ 500; Next.js static export configured (`output: export`, `assetPrefix: "./"`)
-
-### PHASE 7: DEPLOY (INPUT 3)
-
-Ask: *"Your survey is built and verified. Ready to deploy?"*
-
-**Route by client prompt** (see MANIFEST `deployTargets` and `phases[7].selectTargetFromPrompt`):
-
-| Prompt mentions | Target | Action |
-|-----------------|--------|--------|
-| AWS, CloudFront, S3, EC2, Sprinklr | **AWS** | Read `00-integration/aws-deploy.md`; set env vars; run 3-channel deploy or `bash templates/deploy-to-aws.sh` |
-| Vercel or unspecified (default) | **Vercel** | `npx cfm-sdk deploy` (requires `VERCEL_TOKEN` or Vercel CLI) |
-
-**AWS env vars (dev machine):**
+**Phase 6c:** Apply from `survey-ui-config.final.json` per [`wizard-config-handoff.md`](00-integration/wizard-config-handoff.md) + [`apply-ui-config.md`](00-integration/apply-ui-config.md) — **every** diff path. Then:
 
 ```bash
-export CFM_INSTANCE_ID="<same JWT as SurveyPage>"
-export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
-export OUT_DIR="<absolute path to out/ or dist/>"
+npx cfm-sdk confirm-ui-config
 ```
 
-**AWS success:** print live CloudFront HTTPS URL from `/deploy/complete`; ask client to open in browser.
-
-**Vercel success:** CLI prints production URL.
+Re-run verify script + build.
 
 ---
 
-## Progressive Reading Guide
+## Progressive reading guide
 
 | When | Read |
 |------|------|
-| Always first | `index.md`, `00-integration/client-integration-guide.md`, `00-integration/question-type-sdk-matrix.md`, `00-integration/setup.md`, `00-integration/useSurveySDK.md`, `00-integration/constraints.md` |
-| Lifecycle & placeholders | `survey-lifecycle-analytics.md`, `placeholders-and-tokens.md`, `partial-save-and-recovery.md`, `analytics-events-catalog.md` |
-| Skip logic & progress | `skip-logic-and-navigation.md`, `display-logic-and-navigation.md`, `question-display-variants.md`, `question-numbering.md`, `end-page-logic.md`, `answer-logic-and-navigation.md`, `custom-field-logic-and-navigation.md`, `progress.md`, `logic-fields-catalog.md` |
-| File upload submit | `file-upload-aws.md`, `03-ui-specs/10-file-upload.md` |
-| Before any React code | `component-checklist.md`, `templates/Question.tsx`, MANIFEST `readAlways` docs |
-| After instanceId fetch | Per-type docs from MANIFEST `questionTypes` (blocking: `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX`, `FILE_UPLOAD`) |
+| **Always first** | `agent-operating-contract.md`, `agent-execution-flow.md`, `mockup-ui-extraction.md`, `index.md`, `client-integration-guide.md`, `constraints.md` |
+| Phase 3 contract | `question-type-sdk-matrix.md`, `useSurveySDK.md`, logic/navigation docs |
+| Phase 4 plan | `mockup-ui-extraction.md`, `placeholders-and-custom-fields-wiring.md`, `component-checklist.md`, per-type `03-ui-specs/*` |
+| Wizard build | `wizard-preview-build-guide.md`, `wizard-question-type-styling.md` |
+| Wizard run | `wizard-config-handoff.md`, `ui-customization-wizard.md`, `wizard-api.md`, `wizard-troubleshooting.md` |
+| After wizard (apply all paths) | `apply-ui-config.md` |
+| Deploy | `aws-deploy.md` (§ Logos & local assets), `setup.md#nextjs-aws-static-export` |
 | Config audit | `02-reference/config-field-index.md` |
-| AWS deploy | `00-integration/aws-deploy.md`, `setup.md#nextjs-aws-static-export`, `templates/deploy-to-aws.sh` |
-| Tooling | `MANIFEST.json`, `templates/implementation_plan.md`, `templates/survey-inventory.schema.json` |
+
+---
+
+## Wizard styling (all types)
+
+| Token | Variable | Applies to |
+|-------|----------|------------|
+| Cell selected | `--cfm-matrix-selected` | Radio annulus; numbered/star cell fill |
+| Focus ring | `--cfm-input-focus-ring` | Radio outer border + inner dot |
+| Label items | `--cfm-*-column-label-*` | Matrix column headers (not hint labels on CFM) |
+| Hint labels | `--cfm-hint-label-*` | NPS min/max anchors |
+| Number labels | `--cfm-number-*` | Traffic-light badges (unselected only) |
+
+Full per-type table: [`wizard-question-type-styling.md`](00-integration/wizard-question-type-styling.md).