@su-record/vibe 2.16.4 → 3.0.0

package/skills/docs/SKILL.md

@@ -126,24 +126,22 @@ Cursor is not supported — do not generate or check Cursor-specific context fil
    - **If exists** → regenerate from current `CLAUDE.md` + substitution, preserving user-specific additions outside the VIBE block.
 4. **CLI substitution for `AGENTS.md`** (Codex): `Claude Code` → `Codex` · `~/.claude/` → `~/.codex/` · `.claude/` → `.codex/` · `CLAUDE.md` → `AGENTS.md`. `CLAUDE.md` itself gets no substitution.
 5. **CLI substitution for `GEMINI.md`** (Antigravity): `Claude Code` → `Antigravity CLI` · `~/.claude/` → `~/.gemini/` · `.claude/` → `.gemini/` · `CLAUDE.md` → `GEMINI.md`.
-6. **Validate every touched file (whether newly created or modified)** via the `claude-md-guide` → `agents-md` skill chain — see validation block below. **Never write or save without running this step.**
+6. **Validate every touched file (whether newly created or modified)** via the `agents-md` skill — see validation block below. **Never write or save without running this step.**
 7. Report per file: created / updated / skipped / validation warnings.
 
 **Idempotent:** Re-running re-syncs the behavioral block and re-applies substitutions without duplication.
 
-**Mandatory validation (every create & every update) — invoke `claude-md-guide` → `agents-md`:**
+**Mandatory validation (every create & every update) — Load skill `agents-md`:**
 
-1. **`claude-md-guide`**:
-   - Size target 60–150 lines (Optimal). Warn at 200+, force split/trim at 300+.
-   - 4-question check per line (outside `VIBE-BEHAVIORAL` block):
-     - Would the agent make a mistake without this? (No → delete)
-     - Needed every session? (No → move to SPEC/plan)
-     - Can a linter/hook replace it? (Yes → move)
-     - Discoverable from code? (Yes → delete)
-   - Lost-in-the-Middle: critical rules at top, frequently-violated rules at bottom.
-2. **`agents-md`**:
-   - Addy Osmani test: "Can the agent discover this by reading the code?" → Yes = delete.
-   - Strip tech-stack name-drops already stated in `package.json`.
+- Size target 60–150 lines (Optimal). Warn at 200+, force split/trim at 300+.
+- 4-question check per line (outside `VIBE-BEHAVIORAL` block):
+  - Would the agent make a mistake without this? (No → delete)
+  - Needed every session? (No → move to SPEC/plan)
+  - Can a linter/hook replace it? (Yes → move)
+  - Discoverable from code? (Yes → delete)
+- Lost-in-the-Middle: critical rules at top, frequently-violated rules at bottom.
+- Addy Osmani test: "Can the agent discover this by reading the code?" → Yes = delete.
+- Strip tech-stack name-drops already stated in `package.json`.
 
 Report line ranges to trim per file. Do not auto-delete; surface findings for user approval before finalizing.
 
@@ -204,10 +202,10 @@ When `/vibe.trace` completes with all scenarios passing, suggest:
 - Preserve existing documentation that's still accurate
 - Include concrete code examples from the actual project
 - Keep language consistent with project (Korean/English based on CLAUDE.md)
-- Use changelog-writer agent for `/vibe.docs release`
-- Use api-documenter agent for API-heavy projects
+- Use documenter agent (changelog mode) for `/vibe.docs release`
+- Use documenter agent (api-docs mode) for API-heavy projects
 - Use diagrammer agent for `/vibe.docs arch` Mermaid generation
-- Use `claude-md-guide` → `agents-md` chain for `/vibe.docs agent` — applies equally to CLAUDE.md and AGENTS.md
+- Use the `agents-md` skill for `/vibe.docs agent` — applies equally to CLAUDE.md and AGENTS.md
 
 ### DON'T
 - Don't generate placeholder text ("Lorem ipsum", "TODO: fill in")

package/skills/e2e-commerce/SKILL.md

@@ -4,7 +4,7 @@ invocation: [auto]
 tier: core
 description: "E2E test scenarios for commerce checkout and payment flows. Provides ready-made Playwright test templates for cart→checkout→payment→confirmation flows, including PG sandbox testing (Toss/Stripe), error scenarios (payment failure, timeout, stock exhaustion), and idempotency verification. Use when writing E2E tests for any e-commerce feature — checkout, payment, order status, or refund flows."
 triggers: [e2e commerce, checkout test, payment test, order flow test]
-priority: 65
+priority: 60
 ---
 
 # E2E Commerce Test Scenarios

package/skills/event-comms/SKILL.md

@@ -4,7 +4,7 @@ invocation: [auto]
 tier: standard
 description: "Event communication automation — SMS via Aligo, email via Gmail OAuth, SNS posts for LinkedIn/Threads. Handles templates, BCC rules, and confirmation protocol."
 triggers: [sms, aligo, gmail, event email, event sms, 문자 발송, 메일 발송, SNS 홍보]
-priority: 65
+priority: 60
 ---
 # Event Communications
 

package/skills/event-ops/SKILL.md

@@ -3,8 +3,8 @@ name: event-ops
 invocation: [auto]
 tier: standard
 description: "Event operations — nametags, checklists, operational slides, Slido plans, image generation specs, settlement reports."
-triggers: [nametag, checklist, event slide, slido, 이름표, 체크리스트, 운영 슬라이드, 정산]
-priority: 65
+triggers: [nametag, event checklist, event slide, slido, 이름표, 행사 체크리스트, 운영 슬라이드, 정산]
+priority: 60
 ---
 # Event Operations
 

package/skills/event-planning/SKILL.md

@@ -4,7 +4,7 @@ invocation: [auto]
 tier: standard
 description: "Community event automation — D-Day timeline, community patterns, proactive task execution. Auto-activates for event planning, meetup/webinar/conference management."
 triggers: [event planning, meetup, webinar, conference, 행사, 밋업, 웨비나, D-Day, 이벤트 준비]
-priority: 70
+priority: 60
 ---
 # Event Planning
 

package/skills/exec-plan/SKILL.md

@@ -4,8 +4,8 @@ user-invocable: false
 invocation: [auto, chain]
 tier: core
 description: "Convert a SPEC (3+ phases or multi-file) into a self-contained execution plan — explicit file paths, interfaces, acceptance criteria — that agents can run autonomously."
-triggers: [exec plan, execution plan, autonomous plan, self-contained plan, long-running, execute this spec, run this plan, parallel implementation]
-priority: 70
+triggers: [exec plan, execution plan, autonomous plan, self-contained plan, execute this spec, run this plan, parallel implementation]
+priority: 60
 chain-next: [commit-push-pr]
 ---
 

package/skills/figma/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figma
-description: Figma → 코드 본체 — tree 기반 구조적 코드 생성.
+description: Figma → 코드 본체 — tree 기반 구조적 코드 생성 (extract/convert 모드 통합).
 when_to_use: /vibe.figma 진입점에서 체인 호출. 직접 호출 금지.
 user-invocable: false
 tier: standard
@@ -16,20 +16,16 @@ The Figma tree is the source of truth for code. Screenshots are for verification
 ✅ Figma Auto Layout → CSS Flexbox 1:1 mechanical mapping
 ✅ Figma CSS properties → SCSS direct conversion (no guessing)
 ✅ Claude handles semantic decisions only: tag selection, component splitting, interactions
-✅ Screenshots are used for verification only, not generation
 ```
 
 ## Immutable Rules
 
 ```
-1. Do NOT render content as images via screenshot
-   ✅ BG rendering (backgrounds with no TEXT children), vector-text GROUPs, section screenshots (verification only)
-   ❌ Frames with TEXT children, INSTANCE repetitions, buttons/prices, rendering entire sections
-
+1. Do NOT render content as images (frames with TEXT children, INSTANCEs, buttons/prices,
+   whole sections). Image rendering only for BG, vector-text GROUPs, verification screenshots.
 2. BG must use CSS background-image only. <img> tag is forbidden.
-
-3. No new screenshot calls during Phase 4 code generation.
-   Use only Phase 2 materials. No matter how complex — implement with HTML+CSS.
+3. No new screenshot calls during Phase 4. Use only Phase 2 materials —
+   no matter how complex, implement with HTML+CSS.
 ```
 
 ## Full Flow
@@ -42,20 +38,15 @@ Input: receive all URLs at once
 
 → Phase 0: Setup
 → Phase 1: Storyboard analysis → functional spec document
-→ Phase 2: Gather materials (→ vibe.figma.extract)
+→ Phase 2: Gather materials (→ Extract Mode section below)
 → Phase 3: Remapping (MO↔PC matching → remapped.json)
-→ Phase 4: Sequential code generation (→ vibe.figma.convert)
+→ Phase 4: Sequential code generation (→ Convert Mode section below)
 → Phase 5: Compile gate
 → Phase 6: Visual verification loop
 
-Working directory:
-  /tmp/{feature}/
-  ├── mo-main/tree.json, bg/, content/, sections/
-  ├── pc-main/tree.json, bg/, content/, sections/
-  └── remapped.json ← sole input for Phase 4
-
-Code output: placed directly in the project directory
-  components/{feature}/, styles/{feature}/
+Working directory: /tmp/{feature}/{mo,pc}-main/{tree.json, bg/, content/, sections/}
+  + remapped.json ← sole input for Phase 4
+Code output: directly in the project — components/{feature}/, styles/{feature}/
 ```
 
 ---
@@ -66,11 +57,10 @@ Code output: placed directly in the project directory
 1. Stack detection: package.json → react/vue/svelte, next/nuxt, scss/tailwind
 2. Feature name: Figma filename → kebab-case
 3. Directories: components/{feature}/, public/images/{feature}/, styles/{feature}/
-4. Component indexing → /tmp/{feature}/component-index.json
-   (scan up to 50 components, extract props/slots/classes, within 2 minutes)
-5. Hooks/Types/Constants → /tmp/{feature}/context-index.json
-6. Design token scan → /tmp/{feature}/project-tokens.json
-   (SCSS > CSS Variables > Tailwind > CSS-in-JS)
+4. Component indexing → component-index.json (≤50 components, props/slots/classes, ≤2 min)
+5. Hooks/Types/Constants → context-index.json
+6. Design token scan → project-tokens.json (SCSS > CSS Variables > Tailwind > CSS-in-JS)
+   (all indexes under /tmp/{feature}/)
 ```
 
 ---
@@ -78,53 +68,41 @@ Code output: placed directly in the project directory
 ## Phase 1: Storyboard Analysis
 
 ```
-User input: enter URLs or PDF/images separated by newlines
-
-URL classification (automatic):
-  Different fileKey → storyboard vs design
+User input: URLs or PDF/images separated by newlines
+URL classification (automatic): different fileKey → storyboard vs design;
   ROOT name contains "MO" → mobile, "PC" → desktop
 
-Storyboard analysis:
-  Collect frames at depth=3 → classify by name pattern
+Storyboard analysis: collect frames at depth=3 → classify by name pattern
   SPEC (functional definition) → CONFIG (resolution) → PAGE (main sections) → SHARED (common)
   PDF/images follow the same structural extraction
 
 ❌ No code file creation during Phase 1
 
-Output (text only):
-  1. Section list table (name, Figma name, height, description)
-  2. Functional definition per section ([Function] + [Interaction] + [State])
-  3. Common component list
-  4. TypeScript interface draft
+Output (text only): section list table · per-section functional definition
+  ([Function] + [Interaction] + [State]) · common component list · TS interface draft
 ```
 
 ---
 
 ## Phase 2: Gather Materials ← Research (parallel)
 
-**→ Follow the rules of the vibe.figma.extract skill.**
+**→ Follow the Extract Mode rules below.**
 **Coordinator pattern: run MO/PC extraction as parallel workers.**
 
 ```
 # [FIGMA_SCRIPT] = {{VIBE_PATH}}/hooks/scripts/figma-extract.js
 
-Simultaneous MO/PC extraction (each as an independent worker):
-  Worker-MO: screenshot → tree → images → asset rendering → sections/
-  Worker-PC: screenshot → tree → images → asset rendering → sections/
-  → Proceed to Phase 3 only after both workers have completed
-
+Simultaneous MO/PC extraction — each worker: screenshot → tree → images →
+  asset rendering → sections/. Proceed to Phase 3 only after both complete.
 Single BP: run sequentially with 1 worker
-
-Multi-frame (same BP, different pages):
-  Sequential extraction (500ms interval), partial failure allowed
+Multi-frame (same BP, different pages): sequential (500ms interval), partial failure allowed
 ```
 
 ---
 
 ## Phase 3: Data Refinement ← Synthesis (independent per BP)
 
-**Split and refine each BP's tree.json by section.**
-**MO↔PC matching (responsive) is NOT done at this stage.**
+**Split and refine each BP's tree.json by section. MO↔PC matching is NOT done here.**
 
 ### BLOCKING Command — Writing custom refine scripts is strictly forbidden
 
@@ -145,76 +123,49 @@ node {{VIBE_PATH}}/hooks/scripts/figma-refine.js \
 ```
 
 ⛔ **Phase 4 is blocked until these commands are executed.**
-⛔ **Do NOT write custom refine scripts** (refine-sections.mjs, refine.js, etc. — all forbidden)
-⛔ **Do NOT parse tree.json directly with Python/Node to produce sections.json**
-✅ Use only the output of figma-refine.js. If the output is unsatisfactory, modify figma-refine.js.
-
-### Core Principles
+⛔ **No custom refine scripts, no parsing tree.json directly to produce sections.json.**
+✅ Use only figma-refine.js output. If unsatisfactory, modify figma-refine.js.
 
 ```
-⛔ Refine each BP independently. Do NOT mix MO and PC.
-⛔ The refined JSON is the sole input for Phase 4.
-⛔ The full subtree (recursive children) for each section must be included.
+⛔ Refine each BP independently — do NOT mix MO and PC.
+⛔ The refined JSON (full recursive subtree per section) is the sole input for Phase 4.
 ```
 
 ### Output
 
 ```
-/tmp/{feature}/
-  mo-main/
-    sections.json    ← MO refinement result
-  pc-main/
-    sections.json    ← PC refinement result
+/tmp/{feature}/{mo,pc}-main/sections.json    ← per-BP refinement result
 
 sections.json structure:
   {
-    meta: { feature, designWidth, bp (the corresponding BP) },
-    sections: [
-      {
-        name: "Hero",
-        nodeId, name, type, size, css,
-        text,          // TEXT nodes only
-        imageRef,      // image fill
-        fills,         // multiple fills (2 or more)
-        layoutSizingH, // HUG/FILL/FIXED
-        layoutSizingV,
-        children: [    // ⛔ full recursive subtree — down to leaf nodes
-          { nodeId, name, type, size, css, children: [...] }
-        ],
-        images: {
-          bg: "bg/hero-bg.webp",
-          content: ["content/hero-title.webp"]
-        }
-      }
-    ]
+    meta: { feature, designWidth, bp },
+    sections: [{
+      name: "Hero", nodeId, type, size, css,
+      text, imageRef, fills, layoutSizingH, layoutSizingV,
+      children: [ ... ],   // ⛔ full recursive subtree — down to leaf nodes
+      images: { bg: "bg/hero-bg.webp", content: ["content/hero-title.webp"] }
+    }]
   }
 ```
 
-### Node Refinement Rules
-
-```
-Refinement applied when converting tree.json → sections.json:
-  1. Nodes with size 0px → remove
-  2. VECTOR decorative lines (w/h ≤ 2px) → remove
-  3. isMask nodes → remove
-  4. BG frames → separate from children, move to images.bg
-  5. Vector-text GROUPs → separate from children, add to images.content
-  6. Design text (TEXT with multiple/gradient fills or effects) → add to images.content
-  7. Remaining nodes → keep in children (with CSS, recursive)
-```
-
-### Multi-frame (same BP, different pages)
+### Node Refinement Rules (tree.json → sections.json)
 
 ```
-Identify common elements → extract shared components
-Union of common tokens → shared _tokens.scss
+1. size-0px nodes, VECTOR decorative lines (w/h ≤ 2px), isMask nodes → remove
+2. BG frames → separate from children, move to images.bg
+3. Vector-text GROUPs + design text (TEXT with multiple/gradient fills or effects)
+   → separate from children, add to images.content
+4. Remaining nodes → keep in children (with CSS, recursive)
+
+Multi-frame (same BP, different pages): identify common elements → shared components;
+  union of common tokens → shared _tokens.scss
 ```
 
 ---
 
 ## Phase 4: Per-BP Static Implementation ← Implement (sequential per BP)
 
-**→ Follow the rules of the vibe.figma.convert skill.**
+**→ Follow the Convert Mode rules below.**
 **⛔ Implement MO fully first → pass verification → then implement PC. No responsive conversion.**
 **⛔ CSS values must use Figma original px as-is. vw conversion, clamp, @media are forbidden.**
 
@@ -233,44 +184,32 @@ node {{VIBE_PATH}}/hooks/scripts/figma-validate.js \
   --section={SectionName}
 ```
 
-⛔ **Writing SCSS files directly without calling figma-to-scss.js invalidates Phase 4.**
-⛔ **Do NOT write custom SCSS generation scripts** (to-scss.mjs, generate-scss.js, etc. — all forbidden)
+⛔ **Writing SCSS directly (or via custom generation scripts) invalidates Phase 4.**
 ⛔ **Do NOT proceed to the next section without a figma-validate.js PASS.**
-⛔ **Do NOT write CSS values directly inside scoped style blocks** — only @import of external SCSS files is allowed.
+⛔ **No CSS values inside scoped style blocks** — only @import/@use of external SCSS files.
 ✅ Use figma-to-scss.js output as-is. If unsatisfactory, modify figma-to-scss.js.
 
 ```
-Phase 4A: MO Static Implementation
-  Input: /tmp/{feature}/mo-main/sections.json
+Phase 4A: MO Static Implementation (input: mo-main/sections.json)
   ⛔ No parallelism. Process one section at a time:
     1. Read the target section from sections.json
-    2. Write an image vs HTML classification table (BLOCKING)
+    2. Write an image vs HTML classification table (BLOCKING — see Convert Mode §C1)
     3. figma-to-scss.js → auto-generate SCSS skeleton (px as-is) — Step A once
     4. Claude: HTML structure + semantic tags + layout + interactions (Vue/React files only)
-       ⛔ No CSS written directly in <style> blocks — only @import or @use allowed
-    5. figma-validate.js → compare SCSS vs sections.json — Step B
-       ├─ PASS → next section
-       └─ FAIL → fix discrepancies → re-run step 5 (repeat until P1=0, no round cap)
+    5. figma-validate.js — Step B: PASS → next section │ FAIL → fix → re-run
+       (repeat until P1=0, no round cap)
   → Phase 5 (MO compile) → Phase 6 (MO visual verification)
 
-Phase 4B: PC Static Implementation
-  Input: /tmp/{feature}/pc-main/sections.json
-  Same process as MO
-  → Phase 5 (PC compile) → Phase 6 (PC visual verification)
+Phase 4B: PC Static Implementation (input: pc-main/sections.json)
+  Same process as MO → Phase 5 (PC compile) → Phase 6 (PC visual verification)
 
 Phase 4C: Responsive Integration (after both MO+PC pass verification)
   → Separate flow to be established (TODO)
 
-Claude's role (restricted):
-  ✅ Image classification: BG / content / decoration / vector-text
-  ✅ HTML semantics: section/h1/p/button tag selection
-  ✅ Component splitting: v-for repetition, shared components
-  ✅ Interactions: @click, state variables, conditional rendering
-  ✅ Execute figma-to-scss.js / figma-validate.js commands
-  ❌ Do NOT modify SCSS CSS values (use figma-to-scss.js output as-is)
-  ❌ Do NOT write CSS directly in <style> blocks
-  ❌ Do NOT use vw conversion, clamp, @media, or create custom functions/mixins
-  ❌ Do NOT write custom refine/generate scripts (refine.mjs, to-scss.mjs, etc.)
+Claude's role (restricted): semantic decisions only (Convert Mode §C3) + image classification
+  + executing figma-to-scss.js / figma-validate.js.
+  ❌ No modifying SCSS values, no CSS in <style> blocks, no vw/clamp/@media,
+     no custom functions/mixins, no custom refine/generate scripts.
 
 SCSS Setup (before the first section):
   index.scss, _tokens.scss, _base.scss
@@ -291,35 +230,29 @@ Multi-frame:
 ```
 No round cap. Loop until compile succeeds (or stuck → ask user).
 
-0. Capture baseline (before Phase 4): record existing tsc + build errors
-   → Phase 5 only fixes NEW errors
-
+0. Capture baseline (before Phase 4): record existing tsc + build errors → fix NEW errors only
 1. TypeScript: vue-tsc/svelte-check/tsc --noEmit
 2. Build: npm run build (120s timeout)
 3. Dev server: npm run dev → detect port → polling
 
 On error: parse → auto-fix → re-check
-Termination conditions:
+Termination:
   ✅ Success: all checks pass → enter Phase 6
-  ⚠️ Stuck: same errors as previous round → ask user
-      1. Provide direct fix instructions → retry next round
-      2. "proceed" — record remaining errors as TODO, proceed to Phase 6
-      3. "abort" — halt workflow
-  ultrawork mode: on stuck, record TODO without prompting and proceed to Phase 6
+  ⚠️ Stuck (same errors as previous round) → ask user: fix instructions │ "proceed"
+     (record TODO, go to Phase 6) │ "abort". ultrawork: record TODO + proceed silently.
 
 On completion: preserve dev server PID → used in Phase 6
 
-⛔ After Phase 5 passes (or user proceeds), must enter Phase 6. Do NOT output a "completion summary".
-⛔ Do NOT declare work complete without Phase 6.
+⛔ After Phase 5 passes (or user proceeds), must enter Phase 6.
+   Do NOT output a "completion summary" or declare work complete without Phase 6.
 ```
 
 ---
 
 ## Phase 6: Visual Verification Loop ← Verify (parallel) MANDATORY
 
-**⛔ Phase 6 is mandatory, not optional. Enter automatically upon Phase 5 completion.**
-**⛔ If Phase 6 is skipped, the entire task is considered "incomplete".**
-**Coordinator pattern: independent per-section verification can be run as parallel workers.**
+**⛔ Mandatory — enter automatically upon Phase 5 completion; skipping = task "incomplete".**
+**Coordinator pattern: independent per-section verification can run as parallel workers.**
 
 ```
 No round cap. Loop until P1=0 (or stuck → ask user).
@@ -332,18 +265,12 @@ Infrastructure: src/infra/lib/browser/ (Puppeteer + CDP)
 3. Check for missing images and text
 4. Fix P1 issues first (refer to tree.json, no guessing) → revalidate compile → reload
 
-Narrowing scope (noise reduction):
-  Round 1: P1+P2+P3 all
-  Round 2: P1+P2
-  Round 3+: P1 only (continue until P1=0)
+Narrowing scope: Round 1 P1+P2+P3 → Round 2 P1+P2 → Round 3+ P1 only (until P1=0)
 
-Termination conditions:
+Termination:
   ✅ Success: P1 = 0 AND no new findings → complete
-  ⚠️ Stuck: same findings as previous round → ask user
-      1. Provide direct resolution → retry next round
-      2. "proceed" — record remaining issues as TODO, complete
-      3. "abort" — halt workflow
-  ultrawork mode: on stuck, record TODO without prompting and complete
+  ⚠️ Stuck (same findings as previous round) → ask user: direct resolution │ "proceed"
+     (record TODO, complete) │ "abort". ultrawork: record TODO + complete silently.
 
 Responsive: after MO verification, change viewport → same loop against PC screenshots
 Cleanup: shut down browser + dev server
@@ -353,12 +280,177 @@ Cleanup: shut down browser + dev server
 
 ---
 
+## Extract Mode (Phase 2 body) — Acquire Code Generation Data
+
+Uses the Figma REST API (`src/infra/lib/figma/`) to extract **all data needed for structural code generation**. Priority: 1st node tree + CSS (PRIMARY source) → 2nd image assets → 3rd screenshots (Phase 6 validation only, never for generation).
+
+### E1. Node Tree + CSS — Source of Truth
+
+```
+Bash:
+  node "{{VIBE_PATH}}/hooks/scripts/figma-extract.js" tree {fileKey} {nodeId}
+
+Returns (FigmaNode JSON):
+  { nodeId, name, type, size, css: { display, flexDirection, gap, ... },
+    text (TEXT only), imageRef, imageScaleMode (FILL/FIT/CROP/TILE),
+    layoutSizingH/V (FIXED/HUG/FILL), fills (only when 2+), isMask,
+    raw: { itemSpacing, padding*, cornerRadius, strokeWeight, strokeAlign, blendMode,
+           opacity, fontSize, lineHeightPx, letterSpacing, fontWeight, leadingTrim,
+           textBoxTrim },   ← Figma numbers for Phase 6 raw-vs-computed reconciliation
+    warnings: [{ property, value, severity: "P1"|"P2", reason }],  ← translation-loss only
+    children: [...] }
+
+Root node also carries:
+  auditSummary: { total, p1, p2, items: [{ nodeId, name, property, value, severity, reason }] }
+
+→ Save to /tmp/{feature}/tree.json
+
+Figma property → CSS mapping (what the extractor auto-converts): rubrics/css-mapping.md
+```
+
+### E2. Translation-loss Audit (Figma → CSS Incompatibilities)
+
+The extractor flags properties CSS cannot reproduce cleanly (per-node `warnings[]`, rolled up as root `auditSummary`).
+
+**P1 (block Phase 3 until resolved or waived):** `strokeAlign` ≠ `CENTER` (CSS border only renders centered strokes) · `blendMode` ∈ { `LINEAR_BURN`, `LINEAR_DODGE`, `PLUS_DARKER`, `PLUS_LIGHTER` } (no CSS equivalent).
+
+**P2 (record + proceed):** `leadingTrim`/`textBoxTrim` ≠ `NONE` (limited `text-box-trim` support) · `constraints` ∈ { `SCALE`, `CENTER` } (no direct CSS layout mapping) · `individualStrokeWeights` with `strokeAlign` ≠ `CENTER`.
+
+**Gate rule:** if `auditSummary.p1 > 0`, resolve each item (replace layer in Figma, accept approximation with user sign-off, or mark as known deviation) before Phase 3. Log P2 items into feature notes for Phase 6 reviewer attention.
+
+### E3. Image Assets — Node Rendering Based
+
+Full determination rules and real-world failure cases: `rubrics/image-rules.md`.
+
+```
+Do NOT download imageRef individually (shared texture fill → multi-MB originals).
+All images are rendered as nodes:
+  node "{{VIBE_PATH}}/hooks/scripts/figma-extract.js" screenshot {fileKey} {nodeId} --out=...
+
+BG frames → bg/{section}-bg.webp
+  Identification: name contains "BG"/"bg", OR same size as parent (±10%) + 3+ child images
+Content nodes → content/{name}.webp
+  Icons (VECTOR/GROUP ≤ 64px) · item/reward/token/coin thumbnails
+  · vector-text GROUPs (3+ VECTORs, each <60px)
+  · design text (TEXT with 2+ fills, effects, GRADIENT fill, or non-web-font fontFamily)
+    → must be rendered; placed as <img alt="text content">, never CSS text
+  · decorative panels (textured backgrounds) → render like BG frames
+
+imageRef download is a fallback only (API failure, DOCUMENT level); >5MB → texture-fill warning.
+Screenshots (validation only): full-screenshot.webp + per 1-depth child → sections/{name}.webp
+```
+
+### E4. Extraction Completion Validation (Required Before Phase 3)
+
+```
+If any item is missing → re-extract (do NOT proceed to Phase 3)
+
+1. tree.json exists + root children > 0 · 2. BG per section exists in bg/
+3. Every design-text TEXT node (2+ fills or effects) rendered in content/
+4. Every vector-text GROUP (3+ VECTORs) rendered in content/
+5. Per-section validation screenshots exist in sections/ · 6. All filenames kebab-case
+```
+
+---
+
+## Convert Mode (Phase 4 body) — Tree-Based Structured Code Generation
+
+**Mechanically map sections.json to HTML. Do not guess.**
+**Claude handles only semantic decisions (tag selection, component separation, interactions). SCSS comes from figma-to-scss.js (Phase 4 blocking commands).**
+
+### C0. Reuse Check (Before Writing Code)
+
+```
+Matching component in component-index.json?
+  ✅ Import and customize via props — do not create a new one
+  ❌ Never modify an existing component's internals or duplicate a 90%-similar one
+```
+
+### C1. Image vs HTML Determination (BLOCKING)
+
+```
+⛔ Before writing code: write the determination table first.
+
+YES on any one → HTML:
+  Q1. TEXT children? · Q2. repeating INSTANCE? (→ v-for, inner assets only as <img>)
+  Q3. interactive? (btn, CTA → <button>) · Q4. dynamic data? (price, quantity, duration)
+  All NO → image rendering is acceptable
+
+⛔ Design text (Q1 exception — must be image; D1–D5, same as Extract Mode E3):
+  D1. 2+ fills · D2. effects (DROP_SHADOW, stroke) · D3. GRADIENT fill
+  D4. parent GROUP/FRAME has 3+ VECTORs · D5. fontFamily not in project web fonts
+  → <img src="content/{section}-{name}.webp" alt="text content"> — no CSS text attempt
+
+BG frames: ❌ no <img> tags — parent SCSS background-image only
+  .section { background-image: url('bg.webp'); background-size: cover; }
+```
+
+### C2. Node → HTML Mapping (Mechanical)
+
+```
+FRAME + Auto Layout → <div> + flex (direction/gap/padding directly mapped)
+FRAME + no Auto Layout → <div> + position:relative (children absolute)
+TEXT → <span> (Claude promotes to h2/p/button)
+IMAGE fill (passed determination) → <img>
+VECTOR/GROUP ≤64px → icon <img>
+INSTANCE repeated 2+ → v-for / .map()
+Size 0px, VECTOR ≤2px → skip
+```
+
+CSS property mapping reference (grounding for figma-to-scss.js output review, plus legacy vw/responsive rules): `rubrics/css-mapping.md` — Phase 4 forbids hand-writing these values.
+
+### C3. Claude Semantic Decisions (The Only Inference Area)
+
+```
+1. Tag promotion: <span> → <h2> (section title) / <p> (description) / <button> (clickable)
+2. Component separation: 1st-depth children = sections, INSTANCE repetition = shared
+3. Interactions: @click handlers, state variables, conditional rendering
+4. Accessibility: decorative → alt="" aria-hidden="true" · content → alt="description"
+   · interactive → role, aria-label
+5. Semantic HTML: top-level <section>, heading order h1~h6, lists <ul>/<ol>
+```
+
+Component skeleton template: `templates/component.md`.
+
+### C4. SCSS File Structure
+
+```
+layout/     → position, display, flex, width, height, padding, gap, overflow, z-index
+components/ → font, color, border, shadow, opacity, background
+_base.scss  → .{feature} { width: 100%; max-width: 720px; margin: 0 auto; overflow-x: hidden; }
+_tokens.scss → reference existing tokens (@use); if no mapping, create a new
+               feature-scoped token ($feature-color-xxx)
+```
+
+### C5. Self-Validation
+
+```
+⛔ Any failure → rewrite that section's code (do not proceed to the next section)
+
+1. All template classes defined in SCSS · 2. Image src files actually exist
+3. Auto Layout node → flex present in SCSS
+4. ⛔ No @function/@mixin defined in SCSS (existing token @use is allowed)
+5. ⛔ Every SCSS property grounded in sections.json css object
+   (aspect-ratio, container queries, etc. not in the tree → FAIL)
+6. ⛔ Image filenames kebab-case (hash filenames like 68ad470b.webp → FAIL)
+```
+
+---
+
 ## Error Recovery
 
 | Failure | Recovery |
 |---------|----------|
-| figma-extract.js script error | Check Node.js version (>=18 required). Verify Figma API token in config. Retry once. |
-| figma-to-scss.js parse failure | Validate input tree.json structure. If malformed, re-run extract phase. |
-| figma-validate.js comparison failure | Skip automated validation, present screenshot side-by-side for manual review |
-| Puppeteer/CDP not available | Skip visual verification phase, rely on manual browser check |
-| Figma API rate limit (429) | Wait 60s and retry. If persistent, reduce node scope. |
+| figma-extract.js script error | Node.js >=18? API token in config? Retry once. |
+| Figma API 401 | Prompt user to set FIGMA_ACCESS_TOKEN in env or ~/.vibe/config.json |
+| Figma API 404 | Verify fileKey from URL; check file is shared/accessible |
+| Figma API 429 (rate limit) | Wait 60s, retry with reduced node scope (single page) |
+| API timeout on large file | Split request by page via nodeId parameter |
+| Screenshot download failure | Proceed with tree.json only (visual verification → manual) |
+| tree.json missing in Phase 4 | Run Extract Mode (Phase 2) first |
+| component-index.json missing | Generate minimal index from tree.json section names |
+| sections.json malformed | Regenerate from tree.json via figma-refine.js |
+| SCSS output empty | Check sections.json for valid style nodes; else default reset styles |
+| figma-to-scss.js parse failure | Validate tree.json structure; if malformed, re-run Extract Mode |
+| figma-validate.js comparison failure | Skip automated validation; screenshot side-by-side manual review |
+| Puppeteer/CDP not available | Skip visual verification; manual browser check |