@su-record/vibe 3.1.0 → 3.2.0

package/skills/clone/SKILL.md

@@ -71,36 +71,15 @@ Input: a URL (or multiple URLs for multi-page clones)
 → Phase 3C: Responsive merge (clone-merge-responsive.js — mobile-first @media)
 → Phase 4: Compile gate
 → Phase 5: Pixel verification loop (BOTH viewports after merge)
-
-Working directory:
-  /tmp/{feature}/
-  ├── mo/ (375×812)  — rendered.html, computed.json, screenshot.png, assets/, sections.json
-  ├── pc/ (1440×900) — rendered.html, computed.json, screenshot.png, assets/, sections.json
-  └── tokens.json    — extracted design tokens (colors/fonts/spacing)
-
-Code output: placed directly in the project directory per detected stack
-  components/{feature}/, components/{feature}/_specs/{mo,pc}/,
-  styles/{feature}/{mo,pc}/ (per-BP drafts) → styles/{feature}/ (Phase 3C merged),
-  public/images/{feature}/, public/ (favicons/OG from assets/seo/)
 ```
 
+> Read `references/setup-and-layout.md` for the working-directory layout and code-output paths.
+
 ---
 
 ## Phase 0: Setup
 
-```
-1. Stack detection:
-   - .vibe/config.json → stack (react/vue/next/svelte/vanilla, scss/tailwind/css-modules)
-   - Fallback: package.json deps
-2. Feature name: URL hostname → kebab-case (e.g. stripe.com → stripe-clone)
-   - User may override with --name=<custom>
-3. Directories:
-   - components/{feature}/, styles/{feature}/, public/images/{feature}/
-4. Component indexing → /tmp/{feature}/component-index.json
-   (scan up to 50 existing components, extract props/slots/classes, within 2 minutes)
-5. Design token scan → /tmp/{feature}/project-tokens.json
-   (SCSS > CSS Variables > Tailwind > CSS-in-JS)
-```
+> Read `references/setup-and-layout.md` for the full Phase 0 setup steps (stack detection, feature naming, directories, component indexing, design token scan).
 
 ---
 
@@ -130,50 +109,7 @@ node {{VIBE_PATH}}/hooks/scripts/clone-extract.js capture <URL> \
 ⛔ **Do NOT use WebFetch or curl** — they cannot render JS-driven SPAs.
 ✅ Use clone-extract.js. If output is unsatisfactory, modify the script.
 
-### Output per breakpoint
-
-```
-/tmp/{feature}/{bp}/
-  ├── rendered.html       — final DOM after JS execution
-  ├── computed.json       — per-element computed CSS + bounding box
-  ├── screenshot.png      — full-page screenshot
-  ├── states.json         — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
-  ├── behaviors.json      — ACTIVE sweep: scroll / tab / hover / in-view / time-driven + scrollLib
-  ├── assets/
-  │   ├── images/         — all <img>, background-image, <picture> sources
-  │   ├── fonts/          — @font-face srcs
-  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
-  └── asset-map.json      — remote URL → local path mapping
-```
-
-### Capture rules
-
-```
-1. Wait for `networkidle2` (no in-flight requests for 500ms) before snapshot
-2. Scroll to bottom slowly to trigger lazy-loaded content
-3. Resolve all <img src>, srcset, and computed background-image URLs
-4. Resolve @font-face src() URLs from all stylesheets
-5. Download assets in parallel (concurrency=8), preserve original extensions
-6. Rewrite asset URLs in rendered.html and computed.json to local paths
-7. Strip inline analytics/tracking scripts before saving rendered.html
-8. Harvest non-default state rules from all stylesheets → states.json
-   (deterministic: read :hover/:focus/:active/:checked/[aria-*]/[data-state]/.is-*/.active/
-    .scrolled/.sticky/.pinned/… declarations straight from CSS — NO scripted clicking)
-9. ACTIVE interaction sweep → behaviors.json (runs after lazy-load, before freeze).
-   Drives the live page to capture JS-set state that CSS harvesting can't see:
-   - Scroll-state diff: tag sticky/fixed/top-bar headers+nav, snapshot computed CSS at
-     scroll 0, scroll past threshold, re-snapshot, diff → {prop: {from, to}, triggerScrollY}
-   - Tab groups: click tab-like sibling sets, detect whether content swaps on click
-   - Hover diff: hover interactive elements (1 sample per tag+class signature, max 30),
-     diff computed styles → JS-set hover states that :hover harvesting misses
-   - In-view entrance: fresh reload, tag below-fold "waiting to animate" nodes
-     (opacity 0 / transform offset), scroll each into view, diff → fade-up/slide-in
-   - Time-driven: 3s no-input MutationObserver watch → carousel/auto-cycle candidates
-   - Scroll-lib detection: Lenis / Locomotive Scroll (native scrolling feels different —
-     the user spots it immediately; wire the lib page-level, not per-section)
-   Disable with --no-interact (restores the old fully-deterministic, screenshot-stable capture).
-10. SEO asset harvest: favicon / apple-touch-icon / webmanifest / og:image → assets/seo/
-```
+> Read `references/capture-rules.md` for the full per-breakpoint output directory listing and the deterministic capture rule set (networkidle wait, asset resolution, states/behaviors harvesting, SEO asset harvest).
 
 ---
 
@@ -203,63 +139,7 @@ node {{VIBE_PATH}}/hooks/scripts/clone-refine.js \
 ⛔ **Do NOT parse rendered.html with custom Python/Node scripts.**
 ✅ Use clone-refine.js output as-is. If unsatisfactory, modify the script.
 
-### Refinement rules
-
-```
-Refinement applied when converting rendered.html + computed.json → sections.json:
-  1. Strip <script>, <noscript>, <style>, tracking pixels
-  2. Strip nodes with display:none, visibility:hidden, opacity:0, size 0
-  3. Detect sections: <header>, <nav>, top-level <section>/<main> children, <footer>
-     Fallback: top-level children of <body> with height > 100px
-  4. Detect repeated patterns (sibling nodes with same tag+class signature, count >= 3)
-     → mark as component candidates
-  5. Extract design tokens:
-     - colors: unique color/background-color values, sorted by frequency
-     - typography: font-family/size/weight combinations
-     - spacing: padding/margin values (px), bucketed to nearest 4px
-  6. Background images (background-image: url) → images.bg
-  7. Inline <img> → images.content
-  8. Keep CSS subset: layout (display/flex/grid/position/inset/margin/padding/width/height/gap),
-     typography (font-*, line-height, letter-spacing, text-*, color),
-     decoration (background, border, border-radius, box-shadow, opacity),
-     transform/transition
-  9. Classify interaction model per section (static-DOM heuristic) → section.interaction
-     = { model, confidence, signals[], note }. model ∈ static | click-driven | scroll-driven
-     | time-driven | hover. This is a best-guess + ranked SIGNALS, NOT a silent decision —
-     the builder confirms it against the live site (Phase 5). Misidentifying the interaction
-     model is the #1 clone failure mode (scroll-driven original built as a click UI, etc.).
- 10. Attach matching state rules from states.json to each section → section.states
-     (rules whose selector references a class/leaf-tag inside that section's subtree)
-```
-
-### Output
-
-```
-/tmp/{feature}/{bp}/sections.json:
-  {
-    meta: { feature, url, viewport, bp },
-    tokens: { colors: [...], typography: [...], spacing: [...] },
-    sections: [
-      {
-        name: "Header" | "Hero" | "Features" | ...,
-        nodeRef, tag, size, css,
-        interaction: {        // static-DOM heuristic — builder confirms in Phase 5
-          model: "static" | "click-driven" | "scroll-driven" | "time-driven" | "hover",
-          confidence: "high" | "medium" | "low",
-          signals: [...],     // ranked evidence (sticky, infinite animation, role=tab, …)
-          note
-        },
-        text,                 // text content (placeholder candidates)
-        components: [...],    // detected repeated patterns
-        states: [             // non-default state rules scoped to this section
-          { selector, media, css }
-        ],
-        children: [...],      // full recursive subtree
-        images: { bg, content: [...] }
-      }
-    ]
-  }
-```
+> Read `references/refine-rules.md` for the full refinement rule set and the sections.json output schema.
 
 ---
 
@@ -324,44 +204,8 @@ node {{VIBE_PATH}}/hooks/scripts/clone-validate.js \
 ⛔ **Do NOT write custom SCSS / spec generation scripts.**
 ⛔ **Do NOT proceed past a section without a clone-validate.js PASS for it.**
 
-```
 Phase 3A: MO Scaffold — parallel builder dispatch
   Input: /tmp/{feature}/mo/sections.json
-  Prep (sequential, once):
-    a. Step 0: clone-spec.js → emit _specs/mo/{Section}.spec.md for every section
-    b. Step A: clone-to-scss.js → SCSS draft in styles/{feature}/mo/ (computed values)
-    c. Orchestrator resolves every spec TODO BEFORE dispatch:
-       ├─ Confirm the interaction model (spec.interaction is a heuristic guess;
-       │  the spec's active-capture "Dynamic behaviors" block overrides it on conflict)
-       ├─ List the states to implement (spec.states + Dynamic behaviors)
-       ├─ Mark copyrighted text for placeholder replacement (skip with --real-content)
-       └─ Map component candidates against component-index.json (reuse vs create)
-    d. 150-line split rule (mechanical — wc -l, don't override with "but it's related"):
-       a completed spec over 150 lines means the section is too big for one builder →
-       split into sub-component specs (one per card variant / repeated pattern) + one
-       wrapper spec that imports them.
-  Dispatch (parallel):
-    ⛔ Every builder prompt embeds the FULL spec text INLINE — never "go read the file".
-       The spec file stays on disk as the audit trail; the prompt must be self-sufficient.
-    ⛔ Builders that write files in parallel run in worktree isolation; sub-component
-       builders complete before their wrapper builder starts.
-    Builder contract (each agent):
-      1. Build HTML structure + semantic tags + framework-specific component file
-         ⛔ No CSS in <style> blocks — only @import/@use of styles/{feature}/mo/
-         ⛔ Build for the CONFIRMED interaction model in the spec; wire every state
-         Framework mapping:
-           - React/Next → .tsx with CSS Modules or styled-components per stack
-           - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
-           - Svelte     → .svelte with <style> @import only
-           - Vanilla    → .html + linked .scss
-      2. Asset references → public/images/{feature}/ (already populated in Phase 1)
-      3. SCSS edits per Immutable Rule 1 (evidence-cited only)
-      4. Verify compile (tsc --noEmit or stack equivalent) before finishing
-  Merge (orchestrator, as builders complete):
-    5. Merge worktrees; resolve conflicts (you have full context on every spec)
-    6. clone-validate.js per section — Step B
-       ├─ PASS → section done
-       └─ FAIL → fix discrepancies → re-run step 6 (loop until P1=0, no round cap)
   → Phase 4 (MO compile) → Phase 5 (MO pixel verification)
 
 Phase 3B: PC Scaffold
@@ -375,27 +219,12 @@ Phase 3C: Responsive Integration (after both MO+PC pass Phase 5)
        --out=/path/to/project/styles/{feature}/ \
        [--breakpoint=1024]
      → mobile-first merge: MO declarations = base, PC diffs → @media (min-width) block
-  2. Switch component style imports from styles/{feature}/{bp}/index.scss to the merged
-     styles/{feature}/index.scss
-  3. Review pc-only/mo-only selectors in the merge report — hide/show them with the
-     media query if the original does (evidence: the two sections.json trees)
-  4. → Phase 4 (compile) → Phase 5 at BOTH viewports against each BP's screenshot.
+  → Phase 4 (compile) → Phase 5 at BOTH viewports against each BP's screenshot.
      ⛔ The clone is NOT complete until the MERGED build passes Phase 5 at both.
-
-Claude's role:
-  ✅ Component candidates: decide which patterns become reusable components
-  ✅ HTML semantics: section/h1/p/button/nav tag selection
-  ✅ Text replacement: substitute copyrighted copy with placeholders or user-supplied text
-  ✅ Interaction model: confirm the spec's heuristic guess, then build for the real model
-  ✅ Interactions: implement every state in the spec (hover/focus/active/open), click handlers
-  ✅ SCSS value edits WITH cited evidence (computed.json/states.json/behaviors.json) —
-     clone-validate.js PASS is the judge
-  ❌ Do NOT invent CSS values without extraction evidence
-  ❌ Do NOT write CSS directly in <style> blocks
-  ❌ Do NOT hand-write vw/clamp/@media in Phase 3A/3B (responsive comes from Phase 3C merge)
-  ❌ Do NOT hotlink remote URLs — all assets must use local public/images/ paths
 ```
 
+> Read `references/scaffold-phases.md` for the full Phase 3A prep/dispatch/merge builder contract (framework mapping, 150-line split rule, clone-validate.js PASS/FAIL loop detail), Phase 3C steps 2–3 (import switch, pc-only/mo-only selector review), and Claude's role checklist.
+
 ---
 
 ## Phase 4: Compile Gate
@@ -462,41 +291,6 @@ Cleanup: shut down browser + dev server
 
 ---
 
-## Legal & Ethical Notes
-
-```
-This skill is intended for:
-  ✅ "Clone coding" learning exercises (markup/layout study)
-  ✅ Rebuilding the user's own previously-deployed sites
-  ✅ Authorized redesigns where the user has rights to the source
-
-NOT intended for:
-  ❌ Republishing copyrighted content (text, images, logos) without permission
-  ❌ Deceptive look-alike sites (phishing, brand impersonation)
-  ❌ Bypassing robots.txt or rate-limiting protections
-
-Claude must:
-  - Replace copyrighted text content with placeholders (e.g. "[Lorem ipsum]") by default
-  - --real-content: ask ONE explicit confirmation (site ownership / permission) before
-    Phase 3; on confirmation keep text verbatim (clone-spec.js --real-content)
-  - Skip and warn when robots.txt disallows fetching the target path
-  - Refuse if the user's stated intent is brand impersonation or deception
-```
-
----
+## Legal, Ethical & Error Recovery Reference
 
-## Error Recovery
-
-| Failure | Recovery |
-|---------|----------|
-| clone-extract.js Puppeteer launch failure | Verify Node ≥18 and that Chromium is installed (`npx puppeteer browsers install chrome`). Retry once. |
-| Target site blocks headless (403/Cloudflare) | Retry with `--stealth` flag (uses puppeteer-extra stealth plugin). If still blocked, report to user. |
-| Asset download 404 | Log to asset-map.json with `status: missing`. Use a 1×1 transparent placeholder. Continue. |
-| robots.txt disallows path | Halt Phase 1. Inform user; require explicit `--ignore-robots` flag to proceed. |
-| clone-refine.js produces empty sections | Site likely uses Shadow DOM or canvas rendering. Report and ask whether to fall back to screenshot-only mode. |
-| Pixel diff stuck > 0.05 after 5 rounds | Likely font fallback or anti-aliasing. Report metric, allow user to accept threshold. |
-| Interaction model guess wrong (Phase 5) | section.interaction is a static-DOM heuristic. Re-observe the live site, correct the model in the spec, rebuild the section for the confirmed model. |
-| states.json empty but site has hover/tabs | States may be set via inline JS, not CSS rules. Check behaviors.json (active sweep captures scroll/tab JS state). If still missing, note in the spec and capture manually during Phase 5. |
-| behaviors.json missing or empty | Active sweep was disabled (--no-interact), hit no sticky/tab elements, or errored (logged, non-fatal). Falls back to static states.json. Re-run without --no-interact to retry. |
-| clone-merge-responsive.js reports many mo-only/pc-only selectors | Section detection diverged between BPs (layout differs structurally). Expected for hidden-on-mobile elements; verify each against the two sections.json trees and gate with the media query manually if needed. |
-| Merged build fails Phase 5 at one viewport only | The merge dropped or mis-bucketed a declaration. Diff the failing viewport's computed CSS against its sections.json; fix in the merged SCSS with that evidence. |
+> Read `references/legal-and-error-recovery.md` for the full legal/ethical usage notes (intended use, prohibited use, --real-content flow) and the Error Recovery troubleshooting table.

package/skills/clone/references/capture-rules.md

@@ -0,0 +1,48 @@
+# Clone — Phase 1 Capture Output & Rules
+
+> Loaded by vibe.clone SKILL.md Phase 1 (Capture) — full per-breakpoint output directory listing and the deterministic capture rule set.
+
+### Output per breakpoint
+
+```
+/tmp/{feature}/{bp}/
+  ├── rendered.html       — final DOM after JS execution
+  ├── computed.json       — per-element computed CSS + bounding box
+  ├── screenshot.png      — full-page screenshot
+  ├── states.json         — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
+  ├── behaviors.json      — ACTIVE sweep: scroll / tab / hover / in-view / time-driven + scrollLib
+  ├── assets/
+  │   ├── images/         — all <img>, background-image, <picture> sources
+  │   ├── fonts/          — @font-face srcs
+  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
+  └── asset-map.json      — remote URL → local path mapping
+```
+
+### Capture rules
+
+```
+1. Wait for `networkidle2` (no in-flight requests for 500ms) before snapshot
+2. Scroll to bottom slowly to trigger lazy-loaded content
+3. Resolve all <img src>, srcset, and computed background-image URLs
+4. Resolve @font-face src() URLs from all stylesheets
+5. Download assets in parallel (concurrency=8), preserve original extensions
+6. Rewrite asset URLs in rendered.html and computed.json to local paths
+7. Strip inline analytics/tracking scripts before saving rendered.html
+8. Harvest non-default state rules from all stylesheets → states.json
+   (deterministic: read :hover/:focus/:active/:checked/[aria-*]/[data-state]/.is-*/.active/
+    .scrolled/.sticky/.pinned/… declarations straight from CSS — NO scripted clicking)
+9. ACTIVE interaction sweep → behaviors.json (runs after lazy-load, before freeze).
+   Drives the live page to capture JS-set state that CSS harvesting can't see:
+   - Scroll-state diff: tag sticky/fixed/top-bar headers+nav, snapshot computed CSS at
+     scroll 0, scroll past threshold, re-snapshot, diff → {prop: {from, to}, triggerScrollY}
+   - Tab groups: click tab-like sibling sets, detect whether content swaps on click
+   - Hover diff: hover interactive elements (1 sample per tag+class signature, max 30),
+     diff computed styles → JS-set hover states that :hover harvesting misses
+   - In-view entrance: fresh reload, tag below-fold "waiting to animate" nodes
+     (opacity 0 / transform offset), scroll each into view, diff → fade-up/slide-in
+   - Time-driven: 3s no-input MutationObserver watch → carousel/auto-cycle candidates
+   - Scroll-lib detection: Lenis / Locomotive Scroll (native scrolling feels different —
+     the user spots it immediately; wire the lib page-level, not per-section)
+   Disable with --no-interact (restores the old fully-deterministic, screenshot-stable capture).
+10. SEO asset harvest: favicon / apple-touch-icon / webmanifest / og:image → assets/seo/
+```

package/skills/clone/references/legal-and-error-recovery.md

@@ -0,0 +1,40 @@
+# Clone — Legal & Ethical Notes + Error Recovery
+
+> Loaded by vibe.clone SKILL.md — full legal/ethical usage notes and the Error Recovery troubleshooting table.
+
+## Legal & Ethical Notes
+
+```
+This skill is intended for:
+  ✅ "Clone coding" learning exercises (markup/layout study)
+  ✅ Rebuilding the user's own previously-deployed sites
+  ✅ Authorized redesigns where the user has rights to the source
+
+NOT intended for:
+  ❌ Republishing copyrighted content (text, images, logos) without permission
+  ❌ Deceptive look-alike sites (phishing, brand impersonation)
+  ❌ Bypassing robots.txt or rate-limiting protections
+
+Claude must:
+  - Replace copyrighted text content with placeholders (e.g. "[Lorem ipsum]") by default
+  - --real-content: ask ONE explicit confirmation (site ownership / permission) before
+    Phase 3; on confirmation keep text verbatim (clone-spec.js --real-content)
+  - Skip and warn when robots.txt disallows fetching the target path
+  - Refuse if the user's stated intent is brand impersonation or deception
+```
+
+## Error Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| clone-extract.js Puppeteer launch failure | Verify Node ≥18 and that Chromium is installed (`npx puppeteer browsers install chrome`). Retry once. |
+| Target site blocks headless (403/Cloudflare) | Retry with `--stealth` flag (uses puppeteer-extra stealth plugin). If still blocked, report to user. |
+| Asset download 404 | Log to asset-map.json with `status: missing`. Use a 1×1 transparent placeholder. Continue. |
+| robots.txt disallows path | Halt Phase 1. Inform user; require explicit `--ignore-robots` flag to proceed. |
+| clone-refine.js produces empty sections | Site likely uses Shadow DOM or canvas rendering. Report and ask whether to fall back to screenshot-only mode. |
+| Pixel diff stuck > 0.05 after 5 rounds | Likely font fallback or anti-aliasing. Report metric, allow user to accept threshold. |
+| Interaction model guess wrong (Phase 5) | section.interaction is a static-DOM heuristic. Re-observe the live site, correct the model in the spec, rebuild the section for the confirmed model. |
+| states.json empty but site has hover/tabs | States may be set via inline JS, not CSS rules. Check behaviors.json (active sweep captures scroll/tab JS state). If still missing, note in the spec and capture manually during Phase 5. |
+| behaviors.json missing or empty | Active sweep was disabled (--no-interact), hit no sticky/tab elements, or errored (logged, non-fatal). Falls back to static states.json. Re-run without --no-interact to retry. |
+| clone-merge-responsive.js reports many mo-only/pc-only selectors | Section detection diverged between BPs (layout differs structurally). Expected for hidden-on-mobile elements; verify each against the two sections.json trees and gate with the media query manually if needed. |
+| Merged build fails Phase 5 at one viewport only | The merge dropped or mis-bucketed a declaration. Diff the failing viewport's computed CSS against its sections.json; fix in the merged SCSS with that evidence. |

package/skills/clone/references/refine-rules.md

@@ -0,0 +1,61 @@
+# Clone — Phase 2 Refinement Rules & Output Schema
+
+> Loaded by vibe.clone SKILL.md Phase 2 (Refine) — full refinement rule set and the sections.json output schema.
+
+### Refinement rules
+
+```
+Refinement applied when converting rendered.html + computed.json → sections.json:
+  1. Strip <script>, <noscript>, <style>, tracking pixels
+  2. Strip nodes with display:none, visibility:hidden, opacity:0, size 0
+  3. Detect sections: <header>, <nav>, top-level <section>/<main> children, <footer>
+     Fallback: top-level children of <body> with height > 100px
+  4. Detect repeated patterns (sibling nodes with same tag+class signature, count >= 3)
+     → mark as component candidates
+  5. Extract design tokens:
+     - colors: unique color/background-color values, sorted by frequency
+     - typography: font-family/size/weight combinations
+     - spacing: padding/margin values (px), bucketed to nearest 4px
+  6. Background images (background-image: url) → images.bg
+  7. Inline <img> → images.content
+  8. Keep CSS subset: layout (display/flex/grid/position/inset/margin/padding/width/height/gap),
+     typography (font-*, line-height, letter-spacing, text-*, color),
+     decoration (background, border, border-radius, box-shadow, opacity),
+     transform/transition
+  9. Classify interaction model per section (static-DOM heuristic) → section.interaction
+     = { model, confidence, signals[], note }. model ∈ static | click-driven | scroll-driven
+     | time-driven | hover. This is a best-guess + ranked SIGNALS, NOT a silent decision —
+     the builder confirms it against the live site (Phase 5). Misidentifying the interaction
+     model is the #1 clone failure mode (scroll-driven original built as a click UI, etc.).
+ 10. Attach matching state rules from states.json to each section → section.states
+     (rules whose selector references a class/leaf-tag inside that section's subtree)
+```
+
+### Output
+
+```
+/tmp/{feature}/{bp}/sections.json:
+  {
+    meta: { feature, url, viewport, bp },
+    tokens: { colors: [...], typography: [...], spacing: [...] },
+    sections: [
+      {
+        name: "Header" | "Hero" | "Features" | ...,
+        nodeRef, tag, size, css,
+        interaction: {        // static-DOM heuristic — builder confirms in Phase 5
+          model: "static" | "click-driven" | "scroll-driven" | "time-driven" | "hover",
+          confidence: "high" | "medium" | "low",
+          signals: [...],     // ranked evidence (sticky, infinite animation, role=tab, …)
+          note
+        },
+        text,                 // text content (placeholder candidates)
+        components: [...],    // detected repeated patterns
+        states: [             // non-default state rules scoped to this section
+          { selector, media, css }
+        ],
+        children: [...],      // full recursive subtree
+        images: { bg, content: [...] }
+      }
+    ]
+  }
+```

package/skills/clone/references/scaffold-phases.md

@@ -0,0 +1,59 @@
+# Clone — Phase 3A/3B/3C Builder Contract
+
+> Loaded by vibe.clone SKILL.md Phase 3 (Scaffold) — full prep/dispatch/merge steps for MO/PC scaffold, the 150-line split rule, framework mapping, Phase 3C's import-switch/selector-review steps, and Claude's role checklist. Phase headers, Input lines, and script invocation commands stay in SKILL.md; this file covers the supporting detail only.
+
+```
+  Prep (sequential, once):
+    a. Step 0: clone-spec.js → emit _specs/mo/{Section}.spec.md for every section
+    b. Step A: clone-to-scss.js → SCSS draft in styles/{feature}/mo/ (computed values)
+    c. Orchestrator resolves every spec TODO BEFORE dispatch:
+       ├─ Confirm the interaction model (spec.interaction is a heuristic guess;
+       │  the spec's active-capture "Dynamic behaviors" block overrides it on conflict)
+       ├─ List the states to implement (spec.states + Dynamic behaviors)
+       ├─ Mark copyrighted text for placeholder replacement (skip with --real-content)
+       └─ Map component candidates against component-index.json (reuse vs create)
+    d. 150-line split rule (mechanical — wc -l, don't override with "but it's related"):
+       a completed spec over 150 lines means the section is too big for one builder →
+       split into sub-component specs (one per card variant / repeated pattern) + one
+       wrapper spec that imports them.
+  Dispatch (parallel):
+    ⛔ Every builder prompt embeds the FULL spec text INLINE — never "go read the file".
+       The spec file stays on disk as the audit trail; the prompt must be self-sufficient.
+    ⛔ Builders that write files in parallel run in worktree isolation; sub-component
+       builders complete before their wrapper builder starts.
+    Builder contract (each agent):
+      1. Build HTML structure + semantic tags + framework-specific component file
+         ⛔ No CSS in <style> blocks — only @import/@use of styles/{feature}/mo/
+         ⛔ Build for the CONFIRMED interaction model in the spec; wire every state
+         Framework mapping:
+           - React/Next → .tsx with CSS Modules or styled-components per stack
+           - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
+           - Svelte     → .svelte with <style> @import only
+           - Vanilla    → .html + linked .scss
+      2. Asset references → public/images/{feature}/ (already populated in Phase 1)
+      3. SCSS edits per Immutable Rule 1 (evidence-cited only)
+      4. Verify compile (tsc --noEmit or stack equivalent) before finishing
+  Merge (orchestrator, as builders complete):
+    5. Merge worktrees; resolve conflicts (you have full context on every spec)
+    6. clone-validate.js per section — Step B
+       ├─ PASS → section done
+       └─ FAIL → fix discrepancies → re-run step 6 (loop until P1=0, no round cap)
+
+  2. Switch component style imports from styles/{feature}/{bp}/index.scss to the merged
+     styles/{feature}/index.scss
+  3. Review pc-only/mo-only selectors in the merge report — hide/show them with the
+     media query if the original does (evidence: the two sections.json trees)
+
+Claude's role:
+  ✅ Component candidates: decide which patterns become reusable components
+  ✅ HTML semantics: section/h1/p/button/nav tag selection
+  ✅ Text replacement: substitute copyrighted copy with placeholders or user-supplied text
+  ✅ Interaction model: confirm the spec's heuristic guess, then build for the real model
+  ✅ Interactions: implement every state in the spec (hover/focus/active/open), click handlers
+  ✅ SCSS value edits WITH cited evidence (computed.json/states.json/behaviors.json) —
+     clone-validate.js PASS is the judge
+  ❌ Do NOT invent CSS values without extraction evidence
+  ❌ Do NOT write CSS directly in <style> blocks
+  ❌ Do NOT hand-write vw/clamp/@media in Phase 3A/3B (responsive comes from Phase 3C merge)
+  ❌ Do NOT hotlink remote URLs — all assets must use local public/images/ paths
+```

package/skills/clone/references/setup-and-layout.md

@@ -0,0 +1,30 @@
+# Clone — Setup Steps & Output Layout
+
+> Loaded by vibe.clone SKILL.md Full Flow / Phase 0 (Setup) — working-directory + code-output layout and the full Phase 0 setup steps.
+
+```
+Working directory:
+  /tmp/{feature}/
+  ├── mo/ (375×812)  — rendered.html, computed.json, screenshot.png, assets/, sections.json
+  ├── pc/ (1440×900) — rendered.html, computed.json, screenshot.png, assets/, sections.json
+  └── tokens.json    — extracted design tokens (colors/fonts/spacing)
+
+Code output: placed directly in the project directory per detected stack
+  components/{feature}/, components/{feature}/_specs/{mo,pc}/,
+  styles/{feature}/{mo,pc}/ (per-BP drafts) → styles/{feature}/ (Phase 3C merged),
+  public/images/{feature}/, public/ (favicons/OG from assets/seo/)
+```
+
+```
+1. Stack detection:
+   - .vibe/config.json → stack (react/vue/next/svelte/vanilla, scss/tailwind/css-modules)
+   - Fallback: package.json deps
+2. Feature name: URL hostname → kebab-case (e.g. stripe.com → stripe-clone)
+   - User may override with --name=<custom>
+3. Directories:
+   - components/{feature}/, styles/{feature}/, public/images/{feature}/
+4. Component indexing → /tmp/{feature}/component-index.json
+   (scan up to 50 existing components, extract props/slots/classes, within 2 minutes)
+5. Design token scan → /tmp/{feature}/project-tokens.json
+   (SCSS > CSS Variables > Tailwind > CSS-in-JS)
+```

package/skills/docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs
-description: 프로젝트 문서 생성 본체 — README / 아키텍처 / 사용자 가이드 / 릴리즈 노트.
+description: 프로젝트 문서 생성 본체 — README / 아키텍처 / 사용자 가이드 / 릴리즈 노트 / Mermaid 다이어그램 / codemaps.
 when_to_use: /vibe.docs 진입점에서 체인 호출. 직접 호출 금지.
 user-invocable: false
 tier: standard
@@ -179,6 +179,41 @@ Output: `RELEASE_NOTES.md` or append to `CHANGELOG.md`
 - refactor/docs/chore items
 ```
 
+### `/vibe.docs diagram` — Diagram Generation
+
+Generate Mermaid diagrams for architecture, ERD, flowchart, or sequence
+visualization directly (native capability — no dedicated agent). Ground the
+diagram in sources first: folder structure and imports for architecture;
+`models/`, `migrations/`, `schema.*`, ORM definitions for ERDs; the real
+branch/return structure of the code for flowcharts.
+
+**Options:**
+- `/vibe.docs diagram` (default): Architecture overview
+- `/vibe.docs diagram --er`: Entity-Relationship Diagram
+- `/vibe.docs diagram --flow`: Flowchart
+- `/vibe.docs diagram --seq`: Sequence Diagram
+
+> Read `references/diagram-spec.md` for the full output conventions (Mermaid syntax per diagram type, save location, accuracy constraints).
+
+**Example:**
+```
+/vibe.docs diagram --er
+```
+
+### `/vibe.docs codemaps` — Codemaps Generation
+
+Generate auto-documentation from codebase structure directly (native
+capability — no dedicated agent).
+
+**Output Location:** `docs/CODEMAPS/`
+
+> Read `references/codemaps-output.md` for the full generated-files tree, per-file contents, and tools used.
+
+**Example:**
+```
+/vibe.docs codemaps
+```
+
 ## Pipeline Integration
 
 `/vibe.docs` completes the development pipeline:
@@ -202,9 +237,9 @@ 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 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
+- For `/vibe.docs release` (changelog mode), follow `references/api-docs-changelog.md` natively — no dedicated agent
+- For API-heavy projects (api-docs mode), follow `references/api-docs-changelog.md` natively
+- For `/vibe.docs arch` and `/vibe.docs diagram` Mermaid generation, follow `references/diagram-spec.md` natively
 - Use the `agents-md` skill for `/vibe.docs agent` — applies equally to CLAUDE.md and AGENTS.md
 
 ### DON'T

package/skills/docs/references/api-docs-changelog.md

@@ -0,0 +1,34 @@
+# docs — API Docs & Changelog Spec
+
+> Loaded by docs SKILL.md for `/vibe.docs release` (changelog mode) and API-heavy projects (api-docs mode) — documentation rules for the two artifacts that go stale fastest: API docs and changelogs.
+
+## API Mode
+
+Walk the route handlers/controllers in the given scope and document each
+endpoint: method + path, auth requirement, parameters (path/query/body with
+types, required vs optional, enum values), success and error responses (all
+status codes actually returned), and a runnable example (curl or fetch). List
+endpoints that exist in code but lack documentation — the gap list is as
+valuable as the docs.
+
+## Changelog Mode
+
+From `git diff` and `git log`, classify changes as breaking / added /
+changed / fixed / performance / internal / dependencies. Recommend the
+semantic version bump with a one-line reason. Every breaking change gets
+migration steps; every fix states old vs new behavior.
+
+## Constraints
+
+Return documentation as text output only — never create or write files; the
+calling command decides where content lands. Descriptions are user-facing:
+what changed for the consumer, not which internal function was refactored
+(pure refactors go under Internal, briefly). Document what the code actually
+does, not what comments claim — when they disagree, flag the discrepancy
+rather than picking one silently.
+
+## Done
+
+- API mode: every endpoint in scope documented or explicitly listed as an undocumented gap
+- Changelog mode: all changes classified, version bump recommended with reason, breaking changes have migration steps
+- Output is paste-ready text; zero files created

package/skills/docs/references/codemaps-output.md

@@ -0,0 +1,23 @@
+# docs — Codemaps: Generated Files & Contents
+
+> Loaded by docs SKILL.md `codemaps` mode — full generated-files tree, per-file contents, and tools used.
+
+**Generated Files:**
+```
+docs/CODEMAPS/
+├── INDEX.md          # Overview of all areas
+├── frontend.md       # Frontend structure
+├── backend.md        # API/backend structure
+├── database.md       # Schema documentation
+└── integrations.md   # External services
+```
+
+**Each file contains:**
+- Module table (name, path, description)
+- Data flow diagram (Mermaid)
+- Dependencies list
+- Related areas
+
+**Tools Used:**
+- ts-morph (TypeScript AST)
+- madge (dependency graph)