freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.2

package/dist/assets/design/skills/motion-graphics/references/builder-contract.md

@@ -0,0 +1,38 @@
+# Builder contract — composition rules (detail behind agents/builder.md)
+
+## Root must be sized
+
+Root `#stage` (`data-composition-id`) needs `position: relative; width: <W>px; height: <H>px`. Without a resolved height, flex children collapse to ~0 and content piles into the top-left. Automated gates may miss it, so inspect proof snapshots.
+
+## Layout before animation
+
+1. Identify the **hero frame** (the moment most elements are visible) → build THAT in static CSS first, no GSAP.
+2. `.scene-content` fills the scene with padding, not offsets:
+   ```css
+   display: flex;
+   flex-direction: column;
+   justify-content: center;
+   width: 100%;
+   height: 100%;
+   padding: 120px 160px;
+   gap: 24px;
+   box-sizing: border-box;
+   ```
+   Never `position:absolute; top:Npx` on a content container (it overflows). Reserve absolute for decoratives. Keep ≥80px padding (title-safe margin).
+3. **Entrances**: use `gsap.from()` only for a non-clip element active from `t=0`. Inside `.clip`, in sub-compositions, and for later entrances, use explicit `fromTo()`. The CSS position is ground truth; the tween is the journey to it.
+4. **Exits**: only the final scene animates elements out; between scenes the transition IS the exit.
+
+## Timeline / clip contract
+
+- ONE `gsap.timeline({paused:true})` on `window.__timelines["<id>"]`; `tl.seek(0)`; never `tl.play()`.
+- Timed elements: `class="clip"` + `data-start`/`data-duration`/`data-track-index` + a stable `id`. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
+- Deterministic only — no `Date.now()` / `Math.random()` / network. Count-ups tween a proxy object via `onUpdate` (seek-safe), never a wall-clock counter.
+
+## Correctness
+
+- **Seek-safe reveal of delayed elements**: on a non-clip element or wrapper inside a clip, use one registered timeline `fromTo()` with an explicit `{ autoAlpha: 0 }` start and `{ autoAlpha: 1, ... }` end. Do not page-load `gsap.set()` a later `.clip`, and never target `.clip` visibility; the framework owns its lifecycle. _(Eval finding.)_
+- **Count-ups** tween a proxy via `onUpdate`; they only render when the host advances the timeline **with events enabled** (`tl.time()` / non-suppressed seek). A bare `seek(t, true)` freezes them at 0 — the HF render host must seek with events on. _(Eval finding.)_
+- Clamp at tween bounds; don't let a spring overshoot past a held value.
+- Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`).
+- One motif per scene. Run `freecodego_design_lint`; mark intentional overflow `data-layout-allow-overflow="true"`.
+- **Palette discipline**: define all colors in one `palette` object / CSS custom properties — no inline hex scattered through the markup (for `asset-fusion`, eyedropper the palette from the asset).

package/dist/assets/design/skills/motion-graphics/references/motion-vocabulary.md

@@ -0,0 +1,47 @@
+# text module · motion vocabulary (primitive → GSAP)
+
+<!-- registry-items: allow= -->
+
+This plugin ships no hosted look registry, so the local materials this skill carries are the catalogue.
+
+Named primitives the Director references in `motion` strings and the Builder implements. `code_hint`s are framework-neutral physics; the GSAP recipe is the HF implementation. Prefer an HF **registry component** (bottom) when one fits — don't reinvent.
+
+## Entry
+
+| primitive                     | GSAP recipe (into CSS end-state)                               | suits                     |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------- |
+| `slide_bottom/top/left/right` | `from({ y:±150 / x:±200, opacity:0, ease:"power4.out" })`      | calm, build, professional |
+| `scale_grow`                  | `from({ scale:0, opacity:0, duration:.6, ease:"power2.out" })` | calm, gentle              |
+| `scale_punch`                 | `from({ scale:.6, opacity:0, ease:"back.out(2.2)" })`          | impact, energetic         |
+| `fade_in`                     | `from({ opacity:0, duration:.4 })`                             | subtle                    |
+| `fade_blur`                   | `from({ opacity:0, filter:"blur(14px)" })`                     | cinematic, dreamy         |
+| `typewriter`                  | reveal via clip/`SplitText` width step                         | technical, narrative      |
+| `word_reveal`                 | per-word `from({opacity:0,y:..}, stagger:.1)`                  | storytelling              |
+| `wave`                        | per-letter `from({y:..}, stagger:{each:.04})`                  | flowing, musical          |
+| `bounce_in`                   | `from({y:-120}, ease:"bounce.out")`                            | playful                   |
+| `slam`                        | `from({ y:-300, ease:"power4.out" })` + shake on land          | impact, heavy             |
+
+## Emphasis (in place, often on a beat)
+
+| primitive     | GSAP recipe                                                          | suits              |
+| ------------- | -------------------------------------------------------------------- | ------------------ |
+| `scale_pulse` | `to({ scale:1.12, yoyo:true, repeat:1, ease:"sine.inOut" })` at beat | rhythmic, peak     |
+| `shake`       | `to({ keyframes:[{x:-9},{x:9},{x:0}], ease:"none" })`                | urgent, intense    |
+| `glow`        | `to({ textShadow:"0 0 46px <ink/accent>", yoyo:true, repeat:1 })`    | important, magical |
+| `color_shift` | `to({ color:"<accent>" })` (or accent on the word in CSS)            | dynamic            |
+
+## Exit
+
+| primitive   | GSAP recipe                                        | suits      |
+| ----------- | -------------------------------------------------- | ---------- |
+| `fade_out`  | `to({ opacity:0, duration:.4, ease:"power2.in" })` | ending     |
+| `slide_out` | `to({ y/x: off, opacity:0, ease:"power2.in" })`    | transition |
+| `scale_out` | `to({ scale:1.06, opacity:0, ease:"power2.in" })`  | transition |
+
+## Accent graphics (not text)
+
+`underline_sweep` `fromTo({scaleX:0},{scaleX:1}, transformOrigin:"left center")` · `bar_wipe` · `hold_breath` `to({scale:1.015, ease:"sine.inOut"})`.
+
+## Prefer HF registry components when they fit
+
+`caption-kinetic-slam` · `caption-editorial-emphasis` · `caption-neon-glow` · `caption-glitch-rgb` · `caption-particle-burst` · `caption-weight-shift` · `caption-matrix-decode` · `caption-pill-karaoke` · `shimmer-sweep`. These are pre-built, in-ecosystem, and already render-tested — the Builder should reach for them before hand-rolling an equivalent.

package/dist/assets/design/skills/motion-graphics/references/shot-plan-ir.md

@@ -0,0 +1,54 @@
+# shot-plan IR
+
+The single contract between Director and Builder. One file: `PROJECT_DIR/shot-plan.json`.
+
+```jsonc
+{
+  // ── envelope (every category) ──
+  "category": "kinetic-type | stat | charts | logo-reveal | lower-thirds | webpage | news | tweet | asset-fusion",
+  "duration_s": 6,
+  "fps": 30,
+  "canvas": { "w": 1080, "h": 1920, "aspect": "9:16" },
+  "style": "free-form visual direction (mood / energy / reference)",
+  "palette": ["#…"], // or "derive-from-asset"
+  "font": "<HF embed-list font>",
+  "beats": [12, 37], // optional accent frames/seconds
+  "export": "mp4", // or "alpha-overlay" (transparent webm/mov)
+
+  // ── sourcing seam (Director Part 1) — [] means skip the source phase ──
+  "asset_needs": [
+    {
+      "role": "hero",
+      "kind": "image|icon|logo|svg|news|web|tweet",
+      "query": "…",
+      "source": "…",
+      "treatment": "cutout|recolor|vectorize|none",
+    },
+  ],
+
+  // ── build directive (Director Part 2, reuse-first) ──
+  "block": "<catalog block id, e.g. data-chart | caption-kinetic-slam>", // optional
+  "customize": {
+    /* what to change on the block: data, text, palette, positions */
+  },
+
+  // ── category-specific content ──
+  "content": {
+    /* shape varies by category, below */
+  },
+}
+```
+
+**Per-category `content` shapes:**
+
+- `kinetic-type` → `scenes[]` `{ id, start, end, text, emphasis_words[], emotion, motion, beats[] }`
+- `stat` → `{ value, prefix, suffix, label, ring: bool }`
+- `charts` → `{ type: bar|line|pie|race|pct, data[], labels[], headline, axes: bool }`
+- `logo-reveal` → `{ logo: <asset path>, tagline, url }`
+- `lower-thirds` → `{ name, role, position, brand_colors[] }`
+- `webpage` → `{ url, capture, highlights: [ { selector|region, label } ] }` (step-highlight a real captured page)
+- `news` → `{ outlet, headline, body, keyword, layout: A|B, logo?, date?, subject? }` (article-highlight: lay text out readable — **no zoom** — then sweep a marker band over the keyword in place. Layout **A** = centered-emphasis 9:16 text-only; **B** = full article 16:9 with `logo` + `date` + `subject` (a person photo → `remove-background` cutout))
+- `tweet` → `{ author, handle, avatar, text, metrics }`
+- `asset-fusion` → `{ data_type, asset: <path>, affordance, element_positions: {center, extent, safe[], avoid[]}, derived_palette[], connectors[] }`
+
+**Invariants:** `scenes` (if present) partition `[0, duration_s]` with no gaps/overlaps · empty `asset_needs` ⇒ Step 2 (source) is skipped · a named `block` ⇒ the Builder reuses + customizes it rather than hand-authoring.

package/dist/assets/design/skills/motion-graphics/samples/asset-fusion/_ref-circle-highlight.html

@@ -0,0 +1,306 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>asset-fusion · circle-highlight TEMPLATE (drop-in)</title>
+    <!-- ============================================================
+         DROP-IN circle-highlight (editorial amber annotation style). To reuse:
+           1) set CFG below (asset path, EVEN stage dims, BOX from the locate protocol, LABEL)
+           2) render with even width/height (ODD width => ffmpeg encode fails!)
+         BOX comes from grounding/PROTOCOL.md (locate.mjs loop) — NEVER eyeball coords.
+         Everything (wash pool, double ring, connector, callout, brackets) is
+         computed from BOX. Set MODE='full' (ring+label+brackets) or 'circle'
+         (ring only). Gotchas are flagged inline.
+         ============================================================ -->
+    <style>
+      :root {
+        --ink: #0a0c10;
+        --amber: #f2c078;
+        --paper: #f5efe6;
+      }
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        overflow: hidden;
+        background: var(--ink);
+      }
+      #stage {
+        position: relative;
+        overflow: hidden;
+        background: #fff;
+        font-family:
+          "Inter",
+          -apple-system,
+          system-ui,
+          sans-serif;
+      }
+      .scene {
+        position: absolute;
+        inset: 0;
+      }
+      #shot {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        display: block;
+        z-index: 0;
+      }
+      #wash {
+        position: absolute;
+        inset: 0;
+        z-index: 1;
+      }
+      #ann {
+        position: absolute;
+        inset: 0;
+        z-index: 3;
+        pointer-events: none;
+        overflow: visible;
+      }
+      #ring-a,
+      #ring-b,
+      #conn {
+        stroke: var(--amber);
+        fill: none;
+        stroke-linecap: round;
+      }
+      #ring-a {
+        stroke-width: 8;
+        filter: drop-shadow(0 0 12px rgba(242, 192, 120, 0.5));
+      }
+      #ring-b {
+        stroke-width: 5;
+        opacity: 0.85;
+      }
+      #conn {
+        stroke-width: 5;
+      }
+      #callout {
+        position: absolute;
+        z-index: 4;
+        display: inline-flex;
+        align-items: center;
+        gap: 14px;
+        padding: 15px 28px;
+        background: var(--ink);
+        border: 2px solid var(--amber);
+        border-radius: 999px;
+        box-shadow: 0 14px 40px rgba(8, 9, 12, 0.6);
+        transform-origin: left center;
+      }
+      #callout .dot {
+        width: 12px;
+        height: 12px;
+        border-radius: 50%;
+        background: var(--amber);
+      }
+      #callout .label {
+        font-size: 33px;
+        font-weight: 700;
+        letter-spacing: 0.14em;
+        color: var(--paper);
+        text-transform: uppercase;
+        white-space: nowrap;
+      }
+      .tick {
+        position: absolute;
+        z-index: 5;
+        width: 56px;
+        height: 56px;
+        border: 3px solid var(--paper);
+        opacity: 0.55;
+      }
+      .tick.tl {
+        top: 44px;
+        left: 44px;
+        border-right: none;
+        border-bottom: none;
+      }
+      .tick.tr {
+        top: 44px;
+        right: 44px;
+        border-left: none;
+        border-bottom: none;
+      }
+      .tick.bl {
+        bottom: 44px;
+        left: 44px;
+        border-right: none;
+        border-top: none;
+      }
+      .tick.br {
+        bottom: 44px;
+        right: 44px;
+        border-left: none;
+        border-top: none;
+      }
+      #scan {
+        position: absolute;
+        inset: 0;
+        z-index: 5;
+        pointer-events: none;
+        mix-blend-mode: overlay;
+        background: repeating-linear-gradient(
+          to bottom,
+          rgba(245, 239, 230, 0.05) 0 1px,
+          transparent 1px 4px
+        );
+      }
+    </style>
+  </head>
+  <body>
+    <!-- UNVERIFIABLE data-width/height + the #stage width/height MUST be set STATICALLY here
+         (the renderer's StaticGuard reads them at compile time, BEFORE JS runs — JS
+         setAttribute is too late and the render falls back to portrait 1080×1920).
+         Keep these EQUAL to CFG.W/CFG.H below, and EVEN. -->
+    <div
+      id="stage"
+      style="width: 1998px; height: 1368px"
+      data-composition-id="circle-highlight"
+      data-start="0"
+      data-duration="6"
+      data-fps="30"
+      data-width="1998"
+      data-height="1368"
+    >
+      <div class="scene clip" data-start="0" data-duration="6" data-track-index="0">
+        <img id="shot" alt="asset" />
+        <div id="wash"></div>
+        <svg id="ann">
+          <ellipse id="ring-a" />
+          <ellipse id="ring-b" />
+          <path id="conn" />
+        </svg>
+        <div id="callout"><span class="dot"></span><span class="label"></span></div>
+        <div id="scan"></div>
+        <span class="tick tl"></span><span class="tick tr"></span><span class="tick bl"></span
+        ><span class="tick br"></span>
+      </div>
+    </div>
+
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      // ====== CONFIG — set these (BOX from the locate protocol) ======
+      const CFG = {
+        asset: "assets/shot.png",
+        W: 1998,
+        H: 1368, // EVEN dims (odd width => encode fails)
+        box: [0.244, 0.277, 0.607, 0.425], // [x0,y0,x1,y1] normalized, from locate.mjs
+        label: "HyperFrames",
+        mode: "full", // 'full' = ring+connector+label+brackets+scan ; 'circle' = ring only
+      };
+      // =====================================================
+      const S = document.getElementById("stage"); // dims are STATIC in the HTML above (must equal CFG.W/H)
+      document.getElementById("shot").src = CFG.asset;
+      const ann = document.getElementById("ann");
+      ann.setAttribute("viewBox", `0 0 ${CFG.W} ${CFG.H}`);
+      ann.setAttribute("width", CFG.W);
+      ann.setAttribute("height", CFG.H);
+
+      // geometry from BOX
+      const [x0, y0, x1, y1] = CFG.box;
+      const cx = ((x0 + x1) / 2) * CFG.W,
+        cy = ((y0 + y1) / 2) * CFG.H;
+      const bw = (x1 - x0) * CFG.W,
+        bh = (y1 - y0) * CFG.H;
+      const rxA = bw / 2 + 40,
+        ryA = bh / 2 + 42;
+      // wash: a lit radial pool centered on the box, dark elsewhere
+      const px = (((x0 + x1) / 2) * 100).toFixed(1),
+        py = (((y0 + y1) / 2) * 100).toFixed(1);
+      const ex = (((x1 - x0) / 2) * 1.15 * 100).toFixed(1),
+        ey = (((y1 - y0) / 2) * 1.4 * 100).toFixed(1);
+      document.getElementById("wash").style.background =
+        `radial-gradient(ellipse ${ex}% ${ey}% at ${px}% ${py}%, rgba(8,9,12,0) 0%, rgba(8,9,12,.1) 42%, rgba(8,9,12,.66) 70%, rgba(8,9,12,.9) 100%)`;
+      const ra = document.getElementById("ring-a"),
+        rb = document.getElementById("ring-b");
+      ra.setAttribute("cx", cx);
+      ra.setAttribute("cy", cy);
+      ra.setAttribute("rx", rxA);
+      ra.setAttribute("ry", ryA);
+      ra.setAttribute("transform", `rotate(-4 ${cx} ${cy})`);
+      rb.setAttribute("cx", cx);
+      rb.setAttribute("cy", cy);
+      rb.setAttribute("rx", rxA - 20);
+      rb.setAttribute("ry", ryA - 16);
+      rb.setAttribute("transform", `rotate(3 ${cx} ${cy})`);
+      // callout: above-right of the box (flip left if box is on the right edge)
+      const right = cx < CFG.W * 0.62;
+      const co = document.getElementById("callout");
+      co.querySelector(".label").textContent = CFG.label;
+      const coX = right ? Math.min(cx + rxA + 10, CFG.W - 360) : Math.max(cx - rxA - 360, 30);
+      const coY = Math.max(cy - ryA - 60, 40);
+      co.style.left = coX + "px";
+      co.style.top = coY + "px";
+      const conn = document.getElementById("conn");
+      const ex0 = cx + (right ? rxA * 0.75 : -rxA * 0.75),
+        ey0 = cy - ryA * 0.7;
+      conn.setAttribute(
+        "d",
+        `M ${ex0} ${ey0} C ${(ex0 + coX) / 2} ${ey0 - 50}, ${coX - 20} ${coY + 70}, ${coX + 2} ${coY + 26}`,
+      );
+
+      // ====== seek-safe timeline ======
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      // GOTCHA: getTotalLength can read 0 before layout -> dash fails -> a solid
+      // line shows at t=0. Fall back to a constant AND gate with autoAlpha:0.
+      const lenA = ra.getTotalLength() || 1900,
+        lenB = rb.getTotalLength() || 1750,
+        lenC = conn.getTotalLength() || 220;
+      const full = CFG.mode === "full";
+      gsap.set("#wash", { autoAlpha: 0 });
+      gsap.set(ra, { strokeDasharray: lenA, strokeDashoffset: lenA, autoAlpha: 0 });
+      gsap.set(rb, { strokeDasharray: lenB, strokeDashoffset: lenB, autoAlpha: 0 });
+      gsap.set(conn, { strokeDasharray: lenC, strokeDashoffset: lenC, autoAlpha: 0 });
+      gsap.set("#callout", { autoAlpha: 0, scale: 0.6 });
+      gsap.set("#scan", { autoAlpha: 0 });
+      gsap.set(".tick", { autoAlpha: 0 });
+      if (!full) {
+        document.getElementById("conn").remove();
+        document.getElementById("callout").remove();
+        document.getElementById("scan").remove();
+        document.querySelectorAll(".tick").forEach((t) => t.remove());
+      }
+
+      tl.to("#wash", { autoAlpha: 1, duration: 0.9, ease: "power2.out" }, 0.6);
+      if (full) {
+        tl.to("#scan", { autoAlpha: 1, duration: 0.8 }, 0.7);
+        tl.to(".tick", { autoAlpha: 0.55, duration: 0.5, stagger: 0.06 }, 0.8);
+      }
+      tl.to(ra, { autoAlpha: 1, duration: 0.08 }, 1.3);
+      tl.to(ra, { strokeDashoffset: 0, duration: 0.6, ease: "power2.inOut" }, 1.3);
+      tl.to(rb, { autoAlpha: 1, duration: 0.08 }, 1.68);
+      tl.to(rb, { strokeDashoffset: 0, duration: 0.5, ease: "power2.inOut" }, 1.68);
+      if (full) {
+        tl.to(conn, { autoAlpha: 1, duration: 0.05 }, 2.55);
+        tl.to(conn, { strokeDashoffset: 0, duration: 0.35, ease: "power3.out" }, 2.6);
+        tl.to("#callout", { autoAlpha: 1, scale: 1, duration: 0.45, ease: "back.out(2.4)" }, 2.95);
+      }
+      window.__timelines["circle-highlight"] = tl;
+      tl.seek(0);
+      if (!window.__HYPERFRAMES_HOST__) {
+        const fit = () => {
+          const s = Math.min(innerWidth / CFG.W, innerHeight / CFG.H) * 0.96;
+          S.style.transform = `scale(${s})`;
+          S.style.transformOrigin = "center center";
+          S.style.position = "absolute";
+          S.style.left = "50%";
+          S.style.top = "50%";
+          S.style.marginLeft = -(CFG.W / 2) + "px";
+          S.style.marginTop = -(CFG.H / 2) + "px";
+        };
+        addEventListener("resize", fit);
+        fit();
+        tl.eventCallback("onComplete", () => setTimeout(() => tl.restart(), 1000));
+        tl.play();
+      }
+    </script>
+  </body>
+</html>

package/dist/assets/design/skills/music-to-video/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: music-to-video
+description: "Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes."
+---
+
+> **First, keep this skill fresh — confirm with the user before running:** `this pack is bundled offline and is not updated at runtime music-to-video`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+
+# music-to-video — one music-grounded, beat-synced video workflow
+
+Use this skill to turn a **music track** into a beat-synced HyperFrames video. You analyze the track once, lay out the frames, fill in a per-frame plan, and build each frame as a composition. The input is a music track plus optional user images or videos — there is **no narration and no website capture**. Typography and templates are the floor (a complete video needs zero assets); any media the user supplies is cut in on the same beat grid.
+
+You are the **orchestrator**. Work in `videos/<project>/`. Run the steps in order and pass each **Gate** before moving on. Two steps need the user: **Step 3** (plan approval) and **Step 6** (render approval) — both are checkpoint gates per `../hyperframes/references/brief-contract.md` (read it before Step 0): in autonomous mode, post the summary as a heads-up and proceed instead of waiting. Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**. Keep design and motion rules out of this file — they live in `references/` and the `frame-worker` sub-agent.
+
+`SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos/<project-name>/`.
+
+Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze → `audiomap.json`; Step 2 skeleton → `STORYBOARD.md` (frames, groups `TBD`); Step 3 plan → complete `STORYBOARD.md` + `frame.md`; Step 4 build → `compositions/frames/NN-*.html`; Step 5 assemble → `index.html`; Step 6 render → `renders/video.mp4`.
+
+## Two ideas that shape everything
+
+- **One analyzer, and you trust it.** `analyze-beatgrid.py` is the only beat analyzer — never re-measure beats with another tool or by ear. Its energy / density / rolls / onsets / silences are always reliable. Its `bpm` and `beats_sec` are reliable **only when the music is genuinely rhythmic**; on calm music the grid is a metronome the tracker imposed, so pace by phrases and energy instead and never hard-cut to it. Deciding which case you're in is each frame's `pacing` (Step 2).
+- **One frame = one file; groups live inside.** Step 2 cuts the track into **frames**, and each frame becomes one composition file `compositions/frames/NN-<frame_id>.html`, built by one frame-worker. A frame can subdivide into **groups** (each a template or a motion-primitives combo). Extra density goes _inside_ a group, so **frame count tracks distinct treatments, not beats** — a fast track does not blow up the number of sub-agents.
+
+---
+
+## Step 0: Setup, BGM, and inputs
+
+Goal: Establish the music source, create the HyperFrames project, and note any user-supplied media.
+
+**The brief starts at the intent layer.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing it answers — its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists → resume from what's on disk; never re-interrogate. **(3)** A fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it confirms this route's must-haves (the music source, destination → aspect — `../hyperframes/references/routes/music-to-video.md`) and announces what stays deferred — brand and genre are chosen at Step 3 by design. Write `BRIEF.md` immediately after init (never before — `init` refuses a non-empty directory) and record the preference-backed answers (`brief-format.md`). Edit requests skip all of this.
+
+The **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user supplied audio — a music file, or a video to pull audio from — use it. Otherwise choose the mood from the request and generate a track through `/media-use` (`references/bgm.md`). This pack has no hosted account, so voice and music come from a provider the user configured or are omitted.
+
+- **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider.
+- **Autonomous:** state the status and continue through the available local provider.
+
+If no offline provider can satisfy the required music capability, surface the blocker. Never write keys into a per-repo `.env`. Auth ownership and offline fallbacks live in `/media-use` `references/setup-providers.md` § Providers. The resulting track lands at `assets/bgm.mp3`. Stage supplied images or videos so frames can use them on the beat grid; otherwise typography carries the video.
+
+**Lyric videos:** for lyrics synced to the vocals, get word/line timing by transcribing the track via `/media-use`, or ask the user for the lyrics text and place lines on the beat grid.
+
+Initialize only if `hyperframes.json` is missing. Name `<project>` from the brief in kebab-case, such as `midnight-drive-loop` — never a timestamp. `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
+
+```bash
+mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
+cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3"   # extract from a video first if needed
+# only if the user gave you images/videos:
+node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
+```
+
+The **brand** (font + palette) is chosen at Step 3, not here. Don't pick a genre or a track type up front — assets are just an optional ingredient, and the genre emerges from the per-frame choices.
+
+**Gate:** `hyperframes.json` + `assets/bgm.mp3` exist; aspect / length / fps and (if any) the asset inventory are noted.
+
+---
+
+## Step 1: Analyze the music
+
+Goal: Produce the one canonical timing analysis the whole video is built on.
+
+`analyze-beatgrid.py` is the **only** beat analyzer — never re-measure beats with another tool or by ear. It reads the track once and writes `audiomap.json`: energy phases (level / density / feel), onsets + `onset_rate`, rolls, silences, `hard_stops`, `key_moments`, phrases, tempo / grid, and `audio.duration_sec`. It's deterministic — the same file always gives the same map. Most fields are reliable on any music; `bpm` and `beats_sec` are reliable only when the music is genuinely rhythmic, and judging that is the call you make at Step 2.
+
+Prerequisites: Python 3 with `librosa`, `numpy`, and `soundfile` available. If import fails, install them into the active Python environment before running the analyzer:
+
+```bash
+python3 -m pip install librosa numpy soundfile
+```
+
+```bash
+python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
+  -o "$PROJECT_DIR/audiomap.json" --print
+```
+
+**Gate:** `audiomap.json` exists; `audio.duration_sec` is known.
+
+---
+
+## Step 2: Frame skeleton (structure only)
+
+Goal: Read the music and lay out the frames — the skeleton of `STORYBOARD.md`.
+
+Read [`references/frame-skeleton.md`](references/frame-skeleton.md). Turn `audiomap.json` into the **skeleton** of `STORYBOARD.md` yourself — there is no intermediate JSON. Cut the track into **frames** at real musical changes (`hard_stops`, SURGE / DROP `key_moments`, the edges of a roll, a stretch with no onsets, a big energy jump), snapping every boundary to an audiomap anchor. For each frame set `span_sec`, `pacing` (the verdict from Step 1's trust call — `beat_cut` when the grid is real, `phrase_flow` when it's a metronome imposed on calm music), `mood`, and a one-line `feel` (the plain music situation Step 3 matches a template against). Only classify and lay out here: leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank — no templates, copy, color, or fonts. Expect ~1–6 frames.
+
+**Gate:** frames tile the track (first at 0, last at `duration_s`); each carries `span_sec` + `pacing` + `mood` + `feel`; every `### Groups` is `TBD`; no content anywhere.
+
+---
+
+## Step 3: Fill the plan (user-gated)
+
+Goal: Turn the skeleton into an approved, complete `STORYBOARD.md`.
+
+Read [`references/planning.md`](references/planning.md), [`storyboard-format.md`](references/storyboard-format.md), [`template-catalog.md`](references/template-catalog.md), [`motion-primitive-catalog.md`](references/motion-primitive-catalog.md), and [`montage.md`](references/montage.md) (only if the user supplied assets). Editing the same file in place, do two things:
+
+1. **Pick the brand.** Choose one preset from `../hyperframes-creative/frame-presets/` using the table in `../hyperframes-creative/references/design-spec.md` (match the track's mood; **only its fonts and colors matter** — templates own composition). Copy it into `frame.md` **unmodified** and fill the frontmatter `style` (font + a ≤4–6 swatch palette) from it.
+2. **Fill every frame.** Decide its groups and give each a treatment: a matched template from the catalog (with bound params and real audiomap anchors), a free-compose from the primitive catalog, or an asset treatment that **obeys `pacing`**. This plugin ships no hosted look registry, so the local materials this skill carries are the catalogue.
+
+```bash
+node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
+  --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
+```
+
+Fix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then present the frame-by-frame summary in chat as a proposal (`../hyperframes/references/review-loop.md` § 1) and iterate on the user's replies until they approve; for `storyboard: yes`, also write it as `storyboard.html` (`../hyperframes-creative/references/storyboard-recipe.md` § 3) for them to open. In autonomous mode this is a checkpoint gate: post the summary as a heads-up and proceed (the `validate-plan.mjs` pass is a quality gate and still blocks).
+
+**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan (autonomous: the summary was posted as a heads-up).
+
+---
+
+## Step 4: Build frames from the plan
+
+Goal: Build every frame as a self-contained composition file.
+
+Create `compositions/frames/`. Read [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) and `../hyperframes/references/subagent-dispatch.md`. Dispatch **one frame-worker per frame**, in parallel where possible (otherwise in waves). Each worker gets exactly one frame and this context:
+
+```text
+PROJECT_DIR: <abs path>
+frame_id: <NN-frame_id>              # = the frame file stem, e.g. 02-f2; the composition id
+Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
+audiomap: PROJECT_DIR/audiomap.json
+frame.md: PROJECT_DIR/frame.md
+Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
+           <SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
+Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
+Canvas: <w>×<h>   Pacing: <beat_cut|phrase_flow>
+Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
+```
+
+The worker forks the cited materials, converts every anchor to frame-local seconds (`local_t = track_t − span_sec[0]`), gates its groups with 0ms cuts, and writes one seek-safe frame file. **The worker never runs the `hyperframes` CLI** — those commands operate on the assembled project, which doesn't exist yet, so they'd report on the wrong files. The worker just writes to the contract and stops; you verify after assembly (Step 6). As each worker returns, you can confirm its file landed on disk.
+
+**Gate:** every frame has its `compositions/frames/NN-*.html` on disk.
+
+---
+
+## Step 5: Assemble
+
+Goal: Wire the built frames + BGM into the playable `index.html`.
+
+`assemble-index.mjs` is deterministic — no subagent, no judgment. It references each frame file at its cumulative `data-start`, mounts `assets/bgm.mp3` on track 11, and hard-cuts frame → frame (frames tile the track with no gaps, so there is **no transition injector**).
+
+```bash
+node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
+  --hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
+```
+
+Fix any `✗` it reports — a missing or blank frame file means that worker wrote a partial file; re-dispatch it (Step 4) and re-assemble.
+
+**Gate:** `index.html` exists; total duration == `audiomap.audio.duration_sec`.
+
+---
+
+## Step 6: Verify and render
+
+Goal: Verify the assembled video, get user approval, and render the final MP4.
+
+Run the CLI on the **assembled project** — that's the correct unit (the per-frame workers couldn't run it). `check` runs structural lint and the headless-browser runtime, layout, motion, and contrast gate in one pass; `--snapshots` also emits the review frames.
+
+```bash
+( cd "$PROJECT_DIR" && freecodego_design_lint . --snapshots )
+```
+
+Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval (autonomous mode: ask the one kept question — "preview first, or render?" — then deliver the MP4 with the contact sheet):
+
+```bash
+( cd "$PROJECT_DIR" && freecodego_design_render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
+```
+
+**Gate:** `check` passed and the snapshots were inspected; the user approved (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.
+
+---
+
+## Resume table
+
+| You have                   | Continue from |
+| -------------------------- | ------------- |
+| `assets/bgm.mp3` only      | Step 1        |
+| `audiomap.json`            | Step 2        |
+| `STORYBOARD.md` (skeleton) | Step 3        |
+| `STORYBOARD.md` (complete) | Step 4        |
+| all frame files            | Step 5        |
+| `index.html`               | Step 6        |
+
+## Quick Reference
+
+**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the canvas once in the storyboard frontmatter (`canvas: { w, h, fps }`).
+
+**Scripts** under `scripts/`: `analyze-beatgrid.py` (the one analyzer), `validate-plan.mjs` (plan check), `assemble-index.mjs` (index assembly), `stage-assets.mjs` (stage user media), `lib/storyboard.mjs` (vendored parser). Everything else is the `hyperframes` CLI.
+
+| Read                                                                                                           | When                                                    |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| [`references/frame-skeleton.md`](references/frame-skeleton.md)                                                 | Step 2: read the music, lay out the frames, set pacing  |
+| [`references/planning.md`](references/planning.md) · [`storyboard-format.md`](references/storyboard-format.md) | Step 3: pick the brand, fill each frame, write the plan |
+| [`references/template-catalog.md`](references/template-catalog.md)                                             | Step 3: pick a template per group                       |
+| [`references/motion-primitive-catalog.md`](references/motion-primitive-catalog.md)                             | Step 3/4: L0 recipes for free-compose                   |
+| [`references/montage.md`](references/montage.md)                                                               | Step 3/4: asset treatments (beat-cut / ken-burns)       |
+| [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md)                                                     | Step 4: dispatch + build one frame                      |
+| `../hyperframes/references/subagent-dispatch.md`                                                               | Step 4: dispatch sub-agents safely                      |
+| `../hyperframes-creative/references/design-spec.md`                                                            | Step 3: pick the preset (the brand)                     |
+
+## Directory layout
+
+```
+music-to-video/
+  SKILL.md
+  references/   frame-skeleton.md · planning.md · storyboard-format.md
+                template-catalog.md · motion-primitive-catalog.md · montage.md
+                templates/<id>/          { index.html (+ assets/ · program.json) }  ← L1 catalog impls
+                motion-primitives/<id>/  { index.html (mounts the scene), scene.html (the sub-composition) } (+ ../assets/gsap.min.js shared by recipes) ← L0 catalog impls
+  scripts/      analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
+  sub-agents/   frame-worker.md   ← the one subagent (one per frame)
+```