@explorer02/cfm-survey-sdk 0.2.2 → 0.2.3

package/templates/docs/03-ui-specs/10-file-upload.md

@@ -1,18 +1,18 @@
 # UI Spec: File Upload (`type: 'FILE_UPLOAD'`)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/FileUploadScale.tsx`
 > **SDK type:** `FileUploadQuestion` — `fetchSurvey/types/fileUpload.ts`
 > **Component blueprint:** `01-components/08-file-upload-scale.md`
+> **Upload API:** [`00-integration/file-upload-aws.md`](../00-integration/file-upload-aws.md)
 
 ## Config Inventory
 
-| Field | Implemented | UI impact |
-|-------|-------------|-----------|
-| `uploadMessage` | ✅ | HTML in dropzone (bold 16px) |
-| `supportedFileFormats` | ✅ | Validation + accept attribute |
-| `maxFileCount` | ✅ | Total file limit |
-| `fileSizeLimit` | ✅ | MB limit |
-| `fileSizeLimitType` | ✅ | `PER_FILE` or `IN_TOTAL` |
+| Field | UI impact |
+|-------|-----------|
+| `uploadMessage` | HTML in dropzone (bold 16px) |
+| `supportedFileFormats` | Validation + accept attribute |
+| `maxFileCount` | Total file limit |
+| `fileSizeLimit` | MB limit |
+| `fileSizeLimitType` | `PER_FILE` or `IN_TOTAL` |
 
 ## Layout Anatomy
 
@@ -20,7 +20,7 @@
 [uploadMessage HTML in dashed dropzone]
   File limit: N; File size limit: XMB/file|in total; Supports: ...
 [local error banner — red if validation fails]
-[file list cards: icon, name, size, remove ×]
+[file list cards: icon, name, size, uploading…, remove ×]
 ```
 
 ## Interactive States
@@ -31,24 +31,45 @@
 | Hover | `#e20074` | `#fdf2f8` |
 | Drag active | `#e20074` | `#fdf2f8` |
 
-## Local Validation (before SDK)
+## Implementation Recipe
 
-1. Max file count exceeded
-2. Unsupported extension
-3. PER_FILE size exceeded
-4. IN_TOTAL cumulative size exceeded
+### Phase 1 — Local pick + validate
 
-Error banner: `#fee2e2` bg, `#b91c1c` text.
+1. Hidden `<input type="file" multiple={maxFileCount > 1}>`
+2. Drag enter/over/leave/drop on dropzone
+3. Reject: wrong extension, count exceeded, size exceeded
+
+### Phase 2 — Upload (required for submit)
+
+```
+User picks File
+  → POST {uploadApi}/get-upload-url { fileName, contentType, questionId }
+  ← { uploadUrl, fileId, mediaUrl }
+  → PUT uploadUrl (binary body, file Content-Type)
+  → onSelect([...existing, { id: fileId, mediaUrl, name, mimeType, size }])
+  → onAction(CHANGE)
+```
+
+See [`file-upload-aws.md`](../00-integration/file-upload-aws.md).
+
+### Phase 3 — Remove
+
+Remove from list → `onSelect(undefined)` when empty, else updated `UploadedFileAnswer[]`.
 
 ## Answer Mutation
 
 ```typescript
-onSelect(File[] | undefined) // undefined when all removed
+// After upload completes — NOT raw File[]
+onSelect: (value: UploadedFileAnswer[] | undefined) => void
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: UploadedFileAnswer[] } })
 ```
 
+**Non-submittable:** storing `File[]` only — SDK submit drops attachments.
+
 ## Agent Checklist
 
-- [ ] Hidden `<input type="file">` triggered by dropzone click
-- [ ] Drag enter/over/leave/drop handlers
-- [ ] Dynamic constraints line in dropzone
-- [ ] File list with remove button (hover red)
+- [ ] Local validation before upload
+- [ ] Presigned upload wired; progress/spinner per file
+- [ ] Final answer shape: `UploadedFileAnswer[]` with `id` + `mediaUrl`
+- [ ] Remove clears answer or passes updated array
+- [ ] Matrix row: [`question-type-sdk-matrix.md#file_upload`](../00-integration/question-type-sdk-matrix.md#file_upload)

package/templates/docs/03-ui-specs/12-survey-chrome.md

@@ -55,6 +55,41 @@ Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-inte
 
 - Hidden when `languages.length <= 1`
 - Focus ring: `#2563eb`
+- Pass `language` in `useMemo` hook options — SDK remaps survey client-side (no refetch)
+
+## Question numbering
+
+Render ordinals from SDK on content pages:
+
+```tsx
+{question.questionNumber != null && (
+  <span className="mr-1 font-semibold">{question.questionNumber}.</span>
+)}
+```
+
+See [`question-numbering.md`](../00-integration/question-numbering.md).
+
+## Special pages
+
+| Phase | Component | Action |
+|-------|-----------|--------|
+| `intro` | `IntroPage` | `page={state.specialPage}` · `onStart={() => onAction({ type: 'START' })}` |
+| `paused` | `PausedPage` | `page={state.specialPage}` · read-only, no nav |
+| `end` | `EndPage` | `page={state.specialPage}` · terminal thank-you |
+
+## Terminal phases
+
+Render a simple message (no question nav) for:
+
+- `submitted` — already completed
+- `expired` — survey expired
+- `quota_fulfilled` — quota reached
+
+Keep Header/Footer chrome consistent across all phases.
+
+## Submit loading
+
+Disable primary Next/Submit when `submitSurveyResults.isLoading`; label "Submitting…" / "Wird gesendet…".
 
 ## Agent Checklist
 
@@ -64,3 +99,6 @@ Pink fill bar. Bound to `state.progressPercentage` (path-scoped — see `00-inte
 - [ ] Back uses `state.canGoBack`; primary uses `state.primaryButtonType`
 - [ ] ProgressBar receives `state.progressPercentage`
 - [ ] Header/Footer on every state branch
+- [ ] `questionNumber` prefix when present on content questions
+- [ ] Intro / Paused / End / terminal phase branches
+- [ ] Submit button disabled while `submitSurveyResults.isLoading`

package/templates/docs/03-ui-specs/13-heatmap.md

@@ -58,11 +58,18 @@ Use singular "spot" when `maxClicksAllowed === 1`.
 ## Answer Mutation
 
 ```typescript
-onSelect(HeatmapAnswer | undefined)
-// HeatmapAnswer = Array<{ id: string; x: number; y: number }>
+onSelect(HeatmapClickPoint[] | undefined)
+// HeatmapClickPoint = { id: string; x: number; y: number }
 // x, y normalized 0–1 relative to rendered image bounds
+onAction({ type: 'CHANGE', payload: { questionId, answerValue: spots } })
 ```
 
+Copy coord helpers from [`templates/heatmapCoords.ts`](../templates/heatmapCoords.ts): `getNormalizedClickFromImage`, `findSpotNearClick` (14px remove radius), `createNewSpot`.
+
+## Logic fields
+
+`HEATMAP` and `HEATMAP_REGION` — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
+
 ## Agent Checklist
 
 - [ ] Click handler on `<img>` element (not overlay) for precise coordinates

package/templates/docs/03-ui-specs/14-rank-order.md

@@ -2,58 +2,127 @@
 
 > **Reference:** `02-reference/question-types/13-rank-order.md`
 > **Blueprint:** `01-components/18-rank-order-scale.md`
-
-## Interaction Modes
+> **Portable template:** copy [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx)
+
+## Config gate
+
+| Field | Values | UI branch |
+|-------|--------|-----------|
+| `interactionMode` | `'dropdown'` | Rank `<select>` per row |
+| `interactionMode` | `'dragAndDrop'` | `@dnd-kit` sortable list |
+| `optionDisplay` | `textOnly` / `imageOnly` / `textAndImage` | Option content layout |
+| `requireRankAll` | boolean | Validation (SDK) |
+| `shuffleOptions` | boolean | **SDK shuffles at fetch** — render `question.options` as-is; do not re-shuffle client-side |
+
+## Dependencies
+
+```bash
+npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+Next.js: template includes `'use client'`. Optional in `Question.tsx`:
+
+```tsx
+const RankOrderScale = dynamic(() => import('./RankOrderScale').then(m => ({ default: m.RankOrderScale })), {
+  ssr: false,
+  loading: () => <p>Loading rank order…</p>,
+});
+```
+
+## SDK wiring
+
+```typescript
+import {
+  getVisibleRankOrderOptionsForAnswers,
+  normalizeRankOrderAnswers,
+  assignRankWithoutDuplicates,
+  buildRankOrderFromOrderedOptionIds,
+  getOrderedOptionIdsFromRanks,
+} from '@explorer02/cfm-survey-sdk';
+
+// Question.tsx — filter options + normalize answer
+const rankOrderQuestion = {
+  ...question,
+  options: getVisibleRankOrderOptionsForAnswers(question, allAnswers, allQuestions, customFieldValues),
+};
+<RankOrderScale
+  question={rankOrderQuestion}
+  selectedValue={normalizeRankOrderAnswers(selectedValue)}
+  onSelect={onSelect}
+/>
+```
+
+Answer shape: `RankOrderAnswers` = `Record<optionId, rank>` (1-based).
+
+## Interaction modes
 
 ### Dropdown (`interactionMode: 'dropdown'`)
 
 | Element | Behavior |
 |---------|----------|
 | Rank select | `-` (unassigned) or `1..N` per option row |
-| Duplicate ranks | Selecting rank R on option A clears R from any other option |
-| Layout | Rank select on left, option content on right |
+| Duplicate ranks | `assignRankWithoutDuplicates` clears rank R from other options |
+| Layout | Rank select left, option content right |
 
-### Drag and Drop (`interactionMode: 'dragAndDrop'`)
+### Drag and drop (`interactionMode: 'dragAndDrop'`)
 
 | Element | Behavior |
 |---------|----------|
-| Drag handle | Six-dot grip on left; pointer + keyboard sensors |
+| Drag handle | Six-dot grip; `PointerSensor` + `KeyboardSensor` |
 | Rank badge | Circular badge showing 1-based position |
-| Reorder | List order determines rank; smooth transform during drag |
-| Up/Down buttons | Keyboard fallback on right side of each row |
+| Reorder | List order → `buildRankOrderFromOrderedOptionIds(orderedIds)` |
+| Up/Down | Keyboard fallback; disabled on first/last |
+
+## Implementation Recipe — dnd-kit
+
+```typescript
+const sensors = useSensors(
+  useSensor(PointerSensor),
+  useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
+);
+
+const handleDragEnd = (event: DragEndEvent) => {
+  const { active, over } = event;
+  if (!over || active.id === over.id) return;
+  const oldIndex = orderedOptionIds.indexOf(String(active.id));
+  const newIndex = orderedOptionIds.indexOf(String(over.id));
+  if (oldIndex === -1 || newIndex === -1) return;
+  onSelect(buildRankOrderFromOrderedOptionIds(arrayMove(orderedOptionIds, oldIndex, newIndex)));
+};
+```
 
-## Option Display Variants
+Wrap list in `<DndContext collisionDetection={closestCenter}>` + `<SortableContext strategy={verticalListSortingStrategy}>`.
+
+Copy full implementation from [`templates/RankOrderScale.tsx`](../templates/RankOrderScale.tsx).
+
+## Option display
 
 | `optionDisplay` | Render |
 |-----------------|--------|
-| `textOnly` | Full-width text label only |
-| `imageOnly` | Large square thumbnail only (no label) |
-| `textAndImage` | Thumbnail + text label side by side |
-
-Use `dangerouslySetInnerHTML` for option labels (HTML from builder).
+| `textOnly` | Label via `dangerouslySetInnerHTML` |
+| `imageOnly` | Square thumbnail; prefer `option.imageUrl` over `previewImageUrl` |
+| `textAndImage` | Thumbnail + label side by side |
 
 ## Validation UX
 
-- Required + `requireRankAll`: every visible option must have a unique rank from 1..N
+- Required + `requireRankAll`: every visible option unique rank 1..N
 - Required + not `requireRankAll`: at least one visible option ranked
-- SDK surfaces `validationError` on the question shell — show the standard error banner
+- Show `validationError` from question shell
 
 ## Styling
 
-Match MCQ card styling:
-
-- Border: `#e5e5e5` default, `#e20074` when actively ranked (optional highlight)
-- Background hover: `hover:bg-gray-50/50`
-- Rank badge: `#fdf2f8` background, `#e20074` text
+- Border `#e5e5e5`, optional `#e20074` when ranked
+- Rank badge: `#fdf2f8` bg, `#e20074` text
 
-## Accessibility
+## Logic
 
-- Each rank select: `aria-label="Rank for {option label}"`
-- Drag handle: `aria-label="Drag to reorder {option label}"`
-- Up/Down: disabled on first/last item
+RANK_ORDER operators (ranked as/above/below) — see [`logic-fields-catalog.md`](../00-integration/logic-fields-catalog.md).
 
-## Do Not
+## Agent checklist
 
-- Store ranks in local component state without syncing to `onSelect`
-- Submit option labels — submit rank numbers via SDK formatter only
-- Hardcode logic operators in the client — all conditions are SDK-evaluated
+- [ ] Copied `templates/RankOrderScale.tsx` (or equivalent dnd-kit + dropdown)
+- [ ] `@dnd-kit/*` in package.json when survey has RANK_ORDER
+- [ ] `getVisibleRankOrderOptionsForAnswers` + `normalizeRankOrderAnswers`
+- [ ] `option.imageUrl` before `previewImageUrl`
+- [ ] No client-side re-shuffle when `shuffleOptions` is true
+- [ ] No stub placeholder text

package/templates/docs/03-ui-specs/README.md

@@ -38,17 +38,19 @@ Each file in this folder follows the same structure:
 | Spec file | Reference component | `question.type` |
 |-----------|---------------------|-----------------|
 | [00-question-shell.md](00-question-shell.md) | `Question.tsx` | All (wrapper) |
-| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `nps` |
-| [02-radio.md](02-radio.md) | `Question.tsx` inline | `mcq` |
-| [03-text.md](03-text.md) | `Question.tsx` inline | `text_input` |
-| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `csat` |
+| [01-rating.md](01-rating.md) | `RatingScale.tsx` | `NPS_SCALE` |
+| [02-radio.md](02-radio.md) | `Question.tsx` inline | `MCQ` |
+| [03-text.md](03-text.md) | `Question.tsx` inline | `TEXTFIELD` |
+| [04-csat.md](04-csat.md) | `CsatMatrixScale.tsx` | `CSAT_MATRIX` |
 | [05-rating-scale.md](05-rating-scale.md) | `RatingScale.tsx` | `star_rating` |
 | [06-slider.md](06-slider.md) | `CustomSliderTrack.tsx` | `slider` |
 | [07-matrix-cfm.md](07-matrix-cfm.md) | `LikertMatrixScale.tsx` | `cfm_matrix` |
 | [08-matrix-csat-rating.md](08-matrix-csat-rating.md) | `CsatMatrixScale.tsx` | `rating_matrix` |
 | [09-slider-matrix.md](09-slider-matrix.md) | `SliderMatrixScale.tsx` | `slider_matrix` |
 | [10-file-upload.md](10-file-upload.md) | `FileUploadScale.tsx` | `file_upload` |
-| [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `text_and_media` |
+| [11-text-and-media.md](11-text-and-media.md) | `Question.tsx` inline | `TEXT_AND_MEDIA` |
+| [13-heatmap.md](13-heatmap.md) | `HeatmapScale.tsx` | `HEATMAP` |
+| [14-rank-order.md](14-rank-order.md) | `RankOrderScale.tsx` | `RANK_ORDER` |
 | [12-survey-chrome.md](12-survey-chrome.md) | `SurveyPage.tsx` + chrome | Shell |
 | [shared/custom-slider-track.md](shared/custom-slider-track.md) | `CustomSliderTrack.tsx` | Primitive |
 | [shared/matrix-dropdown.md](shared/matrix-dropdown.md) | `MatrixDropdown.tsx` | Primitive |

package/templates/docs/03-ui-specs/shared/custom-slider-track.md

@@ -1,52 +1,45 @@
 # UI Spec: Custom Slider Track (shared primitive)
 
-> **Implement from this spec** (npm installs). Monorepo reference: `apps/client/src/components/CustomSliderTrack.tsx`
-> **Used by:** `SliderMatrixScale.tsx`, `CsatMatrixScale` (graphics), standalone `slider` (gap)
+> **Portable template:** copy [`templates/CustomSliderTrack.tsx`](../templates/CustomSliderTrack.tsx) + [`templates/surveyUiIcons.tsx`](../templates/surveyUiIcons.tsx)
+> **Used by:** `SliderMatrixScale`, `CsatMatrixScale` (graphics), matrix `displayStyle: graphics`
+
+## Scale column labels (Day 19 — CRITICAL)
+
+Matrix rows must pass **`tickLabels` from `scaleColumns[].label`** (filtered to visible columns):
+
+```typescript
+const tickLabels = visibleScaleColumns.map(col => col.label);
+<CustomSliderTrack tickLabels={tickLabels} ticks={tickLabels.length} ... />
+```
+
+Tooltip shows stripped HTML from `tickLabels[tickIndex]`; without labels, tooltips fall back to numeric value only.
 
 ## Layer Architecture
 
 ```
-1. Gray inactive track (#e5e7eb, 4px height)
-2. Magenta fill bar (width = percentage%, #e20074 or #9ca3af if disabled)
-3. Tick marks (1px × 8px at ticks positions)
-4. Invisible <input type="range"> overlay (opacity 0, full hit area)
-5. Visual thumb: circle OR emoji (sliderType === 'graphics')
-6. Tooltip bubble on hover/drag (#1f2937 bg, rounded value)
+1. Gray inactive track (#e5e7eb, 4px)
+2. Magenta fill bar (percentage%, #e20074 or #9ca3af if disabled)
+3. Tick marks at column positions
+4. Invisible <input type="range"> overlay
+5. Thumb: circle OR emoji (sliderType === 'graphics')
+6. Tooltip on hover/drag (#1f2937)
 ```
 
 ## Props
 
 | Prop | Role |
 |------|------|
-| `min`, `max`, `htmlStep` | Range input bounds |
+| `min`, `max`, `htmlStep` | Range bounds |
 | `value` | Current position |
-| `disabled` | Gray theme, opacity 0.5, no interaction |
-| `displayValues` | Reserved — tooltip always shows on hover/drag in client |
-| `hasSelectedValue` | Reserved |
-| `sliderType: 'graphics'` | Emoji thumb via client-side react-icons |
-| `ticks` | Discrete tick count + emoji index scale |
-| `reverseScaleOrder` | Flip emoji index calculation |
-
-## Interactive States
-
-| State | Thumb | Tooltip |
-|-------|-------|---------|
-| Default | White circle, 2.5px magenta border | Hidden |
-| Hover/drag | Pink glow ring `rgba(226,0,116,0.2)` | Dark bubble with `Math.round(value)` |
-| Disabled | Gray border, opacity 0.5 | Hidden |
-| Graphics | Emoji at percentage position | Same tooltip |
-
-## Emoji Index Formula
-
-```typescript
-const idx = Math.round(((value - min) / (max - min)) * ((ticks || 10) - 1));
-const displayIdx = reverseScaleOrder ? (ticks || 10) - 1 - idx : idx;
-// Map displayIdx to react-icons emoji — proportional mapping is client-implemented (not an SDK export)
-```
+| `disabled` | Gray theme, opacity 0.5 |
+| `sliderType: 'graphics'` | Emoji thumb via `surveyUiIcons.getEmojiForIndex` |
+| `ticks` | Discrete tick count |
+| **`tickLabels`** | **Column labels for tooltip + graphics index** |
+| `reverseScaleOrder` | Flip emoji index |
 
 ## Agent Checklist
 
-- [ ] 4-layer overlay with invisible range input
+- [ ] Copy portable template or match layer stack
+- [ ] Always pass `tickLabels` from matrix `scaleColumns` when available
 - [ ] Tooltip on hover AND drag
-- [ ] Graphics mode emoji thumb
-- [ ] Transition disabled while dragging
+- [ ] Graphics emoji thumb with `reverseScaleOrder` support

package/templates/docs/MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "docsSchemaVersion": "2.3.0",
+  "docsSchemaVersion": "2.4.0",
   "sdkTypesVersion": "0.2.1",
   "packageNames": {
     "npm": "@explorer02/cfm-survey-sdk",
@@ -107,8 +107,27 @@
     {
       "path": "00-integration/survey-lifecycle-analytics.md",
       "purpose": "Mark-as-started and question activity"
+    },
+    {
+      "path": "00-integration/logic-fields-catalog.md",
+      "purpose": "Logic field reference by question type for skip/display/answer/end"
+    },
+    {
+      "path": "00-integration/analytics-events-catalog.md",
+      "purpose": "Consolidated SDK analytics and client lifecycle events"
+    },
+    {
+      "path": "00-integration/file-upload-aws.md",
+      "purpose": "Presigned S3 upload flow for FILE_UPLOAD submit contract"
     }
   ],
+  "templateScaleFiles": [
+    "templates/RankOrderScale.tsx",
+    "templates/MatrixDropdown.tsx",
+    "templates/CustomSliderTrack.tsx",
+    "templates/surveyUiIcons.tsx",
+    "templates/heatmapCoords.ts"
+  ],
   "deployTargets": {
     "aws": {
       "doc": "00-integration/aws-deploy.md",
@@ -216,7 +235,9 @@
         "00-integration/partial-save-and-recovery.md",
         "00-integration/survey-lifecycle-analytics.md",
         "00-integration/end-page-logic.md",
-        "00-integration/progress.md"
+        "00-integration/progress.md",
+        "00-integration/logic-fields-catalog.md",
+        "00-integration/analytics-events-catalog.md"
       ]
     },
     {
@@ -225,6 +246,7 @@
       "readAlways": [
         "00-integration/component-checklist.md",
         "00-integration/question-type-sdk-matrix.md",
+        "00-integration/logic-fields-catalog.md",
         "03-ui-specs/00-question-shell.md",
         "03-ui-specs/12-survey-chrome.md",
         "01-components/01-survey-page.md",
@@ -271,7 +293,10 @@
         "npmRunBuildPasses",
         "nextStaticExportConfigured",
         "outIndexHtmlExists",
-        "outFileCountUnder500"
+        "outFileCountUnder500",
+        "rankOrderScaleTemplateCopied",
+        "dndKitWhenRankOrder",
+        "fileUploadPresignedFlowWhenFileUpload"
       ]
     },
     {

package/templates/docs/index.md

@@ -71,7 +71,7 @@ Ask: *"Please provide your survey instance ID (JWT token)."*
 
 ### PHASE 3: SDK CONTRACT
 
-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`
+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`
 
 Understand `useSurveySDK`, `onAction`, `state.answers`. Do **not** read internal mapper/source paths.
 
@@ -94,7 +94,7 @@ Optional: read `02-reference/routing-table.md` for type overview.
 
 Read: `00-integration/constraints.md`, `00-integration/component-checklist.md`, `00-integration/question-type-sdk-matrix.md`
 
-Create all required scale component files **before** wiring `Question.tsx`. For each question in the survey:
+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`)
@@ -166,8 +166,9 @@ export OUT_DIR="<absolute path to out/ or dist/>"
 | 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 | `00-integration/survey-lifecycle-analytics.md`, `00-integration/placeholders-and-tokens.md`, `00-integration/partial-save-and-recovery.md` |
-| Skip logic & progress | `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/end-page-logic.md`, `00-integration/answer-logic-and-navigation.md`, `00-integration/custom-field-logic-and-navigation.md`, `00-integration/progress.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`) |
 | Config audit | `02-reference/config-field-index.md` |