npm - @mevdragon/vidfarm-devcli - Versions diffs - 0.13.0 → 0.15.0 - Mend

@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (427) hide show

package/.agents/skills/motion-graphics/samples/asset-fusion/_ref-circle-highlight.html ADDED Viewed

@@ -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>
+    <!-- ⚠ 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/.agents/skills/product-launch-video/SKILL.md ADDED Viewed

@@ -0,0 +1,208 @@
+---
+name: product-launch-video
+description: "turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance."
+---
+> **vidfarm-media**: Before sourcing audio/images, read `../vidfarm-media` to resolve BGM/SFX/images via vidfarm — My Files search, the clip library, and the image-generation primitives. See the `../vidfarm-media` skill.
+# Product Launch to HyperFrames
+Use this skill to capture a product, understand its brand, plan a launch video, and build it frame by frame in HyperFrames.
+> **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue to the next step. This skill is for a **product being marketed, launched, promoted, or revealed**, including requests such as "promo for our site" when the purpose is promotional. Route other intents elsewhere: a general non-launch website tour -> `/website-to-video`; a topic explainer with no product -> `/faceless-explainer`; a GitHub PR -> `/pr-to-video`; captions on existing footage -> `/embedded-captions`; a short unnarrated motion graphic -> `/motion-graphics`. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+Workflow: Step 0 setup -> `hyperframes.json`; Step 1 capture -> `capture/`; Step 2 design system -> `frame.md`; Step 3 storyboard/script -> `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio -> `audio_meta.json`; Step 4 visual design -> enriched `STORYBOARD.md`; Step 5 frames -> `compositions/frames/NN-*.html` and `index.html`; Step 6 final render -> `renders/video.mp4`.
+---
+## Step 0: Setup and Brief
+Goal: Lock the core video brief and create the HyperFrames project if needed.
+Initialize only if `hyperframes.json` is missing. Name `<project>` from the brand or domain in kebab-case, such as `acme-promo`; never use workspace name or timestamp.
+`npx hyperframes init "videos/<project>" --non-interactive --example=blank` — `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date. In vidfarm-managed environments `HYPERFRAMES_SKIP_SKILLS=1` is set, so `init` skips that refresh and skills are managed with `vidfarm skills` instead.
+**Run the engine preflight before the brief** — check for saved AI provider keys (`vidfarm provider-keys`, or the `OPENAI_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY` env vars) and report which engines will be used: BYOK cloud TTS/STT (`vidfarm tts` / `vidfarm stt`) when a key exists, keyless local engines (Kokoro TTS via `--engine local`, whisper.cpp STT via `--engine whisper`) otherwise. There is no account sign-in — nothing to sign in to and no reason to stop; state the engine choice in one line and continue to the brief. Don't write keys into a per-repo `.env`. See `../vidfarm-media` → Preflight for the canonical guidance.
+**Gate:** `hyperframes.json` exists, and angle, length, aspect ratio, and language are locked; the engine preflight was reported (BYOK cloud or keyless local).
+---
+## Step 1: Capture assets
+Goal: Collect the source material, brand signals, and usable assets for the video.
+Classify the input and choose the path. Explicit URL -> capture it and use the site for narration and assets. Pasted script/brief -> save verbatim as `user_script.txt`, ask once "use it verbatim or restructure?", store answer as `VO_MODE`, then resolve capture target: URL in text -> use it; brand name only -> `WebSearch`, confirm URL in one line, then crawl; no URL/site -> no-capture path.
+Run capture with: `npx hyperframes capture "<URL>" -o ./capture`
+If `GEMINI_API_KEY`, `GOOGLE_API_KEY`, or an OpenRouter key exists, capture auto-captions assets into `capture/extracted/asset-descriptions.md`. This is not a review gate. Without a vision key, use DOM context and continue.
+No-capture path: create `capture/extracted/tokens.json`, `capture/extracted/visible-text.txt`, `capture/extracted/asset-descriptions.md`, and `capture/assets/` by hand. `tokens.json` should be `{ "title": "", "description": "", "colors": [], "fonts": [] }`; fill title/description from the brief when possible. `visible-text.txt` contains the full brief or script. `asset-descriptions.md` should say no assets were captured unless the user gave asset notes.
+**Gate:** `capture/extracted/tokens.json`, `capture/extracted/visible-text.txt`, `capture/extracted/asset-descriptions.md`, and `capture/assets/` exist; you can state the brand in one clear sentence. Treat `asset-descriptions.md` as the main asset inventory. If it is missing after real capture, stop and report capture incomplete. If `capture/BLOCKED.md` exists, follow it.
+---
+## Step 2: Design System
+Goal: Choose one shipped frame preset; a script turns it into this video's `frame.md` + caption skin.
+You make the one judgment call — **which preset**. Read `../hyperframes-creative/references/design-spec.md` and pick the preset whose look best fits the brand and brief. Then run:
+```bash
+node <SKILL_DIR>/scripts/build-frame.mjs --preset <name> --hyperframes .
+```
+The script does the rest deterministically: copies the preset's `FRAME.md` → `frame.md` and **remixes** it onto the brand tokens in `capture/extracted/tokens.json` (brand colors mapped onto the preset's color keys by role — ink, canvas, accents — keeping keys/structure/components; the preset's display + body fonts swapped for the brand's), copies the preset's caption skin to `.hyperframes/caption-skin.html`, and self-validates (exits 1 on a broken mapping). Proceed to the next step as soon as it exits 0 — no hand-editing of the spec.
+`tokens.json` with no brand colors/fonts (e.g. no capture) → the script keeps the preset's own palette, a complete shippable design. If the brief names brand colors/fonts the capture missed, add them to `capture/extracted/tokens.json` before running (or use the user's `design.md` to populate it); only adjust `frame.md` by hand afterward if a mapping truly needs it.
+**Gate:** `build-frame.mjs` exited 0 — `frame.md` exists from a named preset, and (when the preset ships one) `.hyperframes/caption-skin.html` exists as the caption skin source.
+---
+## Step 3: Storyboard and Script
+Goal: Turn the brief and captured material into an approved frame-by-frame story plan.
+Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
+Use `story-design.md` for story blueprint, hook, persuasion logic, beats, `VO_MODE`, and asset choices. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, note a candidate blueprint id when one fits. Story truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Choose each visual frame's `asset_candidates` from `capture/extracted/asset-descriptions.md` (the canonical inventory) — don't browse raw `capture/assets/`. Do not ask the user to pick assets unless that inventory is missing or unusable. Use the exact required fields from the storyboard and script references.
+After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6.
+**Gate:** `STORYBOARD.md` exists, every visual frame has `asset_candidates`, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan.
+---
+## Step 3.1: Audio
+Goal: Generate narration, word timings, music, and audio metadata from the approved script.
+Start audio after Step 3 approval. Run it in the background, then continue to Step 4.
+`node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &`
+The audio script is an adapter over the shared engine `../vidfarm-media/scripts/audio.mjs` (same `audio_request.json` → `audio_engine_meta.json` contract); it handles narration, word timings, BGM, and timing metadata. Narration TTS and word timings ride vidfarm's BYOK cloud or keyless local engines. BGM mood comes from the storyboard's `music:` field; BGM resolves from the user's My Files music, a user-provided file or URL, or is skipped gracefully when nothing matches. For provider details, read `../vidfarm-media/references/tts.md`.
+If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may still run if the storyboard has a music mood.
+**Gate:** audio job has started, or the project is marked silent.
+---
+## Step 4: Frame Visual Design
+Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.
+Edit `STORYBOARD.md` in place. Do not create another storyboard. Use `frame.md` as source of truth for color, type, layout feel, and style.
+Read `references/visual-design.md`, `../hyperframes-animation/blueprints-index.md`, `references/motion-language.md`, and `../hyperframes-animation/rules-index.md`. Use `visual-design.md` for the method (the time-coded shot sequence, the inline Layout vocabulary, and the required `## Video direction` block). Use `../hyperframes-animation/blueprints-index.md` to pick each frame's shot shape. Use `motion-language.md` (the motion vocabulary + the motion doctrine) and `../hyperframes-animation/rules-index.md` (valid rule names) for motion — do not invent motion names.
+For every visual frame, write a **time-coded shot sequence** into `STORYBOARD.md` per `visual-design.md`'s method: pick the frame's blueprint (or compose), instantiate it with THIS product's content, and pace each Scene's reveal to the voiceover so the frame develops across its full duration instead of front-loading then freezing. State layout and motion **inline** per Scene (vocabularies in `visual-design.md` and `motion-language.md`). Add one video-wide `## Video direction` block.
+Do not change story, script, asset choices, `asset_candidates`, `transition_in`, or captured source material. Do not write HTML in this step.
+Stage named assets after visual design is locked:
+`node <SKILL_DIR>/scripts/stage-assets.mjs --storyboard ./STORYBOARD.md --hyperframes .`
+**Gate:** every visual frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); `## Video direction` exists; `assets/` contains the named assets.
+---
+## Step 5: Build Frames
+Goal: Build every storyboard frame as an HTML composition and assemble the playable video.
+Wait for Step 3.1 audio to finish if audio was started. Then sync durations and fetch SFX; skip both if silent.
+`node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md`
+`node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .`
+Duration sync is mechanical: real voice duration wins; silent frames keep estimates; never hand-edit synced durations.
+Before dispatch, read `sub-agents/frame-worker.md` and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch one sub-agent per frame, in parallel if possible; otherwise run workers in waves. Each worker gets exactly one frame.
+Each worker context must include `PROJECT_DIR`, `frame_id`, canvas size, caption status and keep-out band if captions are enabled, and `RULES_DIR` as the absolute path to this skill's `../hyperframes-animation/rules/`. Each worker reads `frame.md`, its own `## Frame N` block from `STORYBOARD.md`, the local rule recipe (`../hyperframes-animation/rules/<id>.md`) for each cited motion, and the frame's blueprint template (`../hyperframes-animation/blueprints/<id>.md`). Each worker writes only `compositions/frames/NN-*.html`. Workers must never edit `STORYBOARD.md`.
+**Full-bleed backgrounds ride on a `class="clip"` layer, never the `#root`.** A frame's ground (color field / gradient / grid) is its own full-duration background clip — a `background` set on the `#root` / `data-composition-id` element is clip-gated to the frame's window and is not a dependable ground, so dark content can land on the black host `body` and render invisible. The video's base ground is painted by the assembler from `frame.md`'s `canvas` color onto the index `#root`. (Full rule + self-check: `sub-agents/frame-worker.md`.)
+As each worker returns, the orchestrator marks that frame as `animated` in `STORYBOARD.md`.
+After audio timings exist, build captions in the background and assemble the index:
+`node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &`
+`node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .`
+`captions.mjs` uses the project's `.hyperframes/caption-skin.html` (copied in Step 2) as the caption look, injecting brand tokens from `frame.md`; with no skin present it renders the built-in default pill. `captions: skipped (<reason>)` is valid. Continue without captions when explicitly skipped.
+**Gate:** every frame is marked `animated`, `index.html` exists, and captions are built or explicitly skipped.
+---
+## Step 6: Finalize
+Goal: Verify the assembled video, get user approval, and render the final MP4.
+Inject transitions, run checks, pause for review, then render.
+`node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .`
+`node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html`
+`npx hyperframes lint`
+`npx hyperframes validate`
+`npx hyperframes inspect`
+`npx hyperframes snapshot --at <frame-midpoints>`
+`snapshot` stitches the captured frames into one contact sheet (`snapshots/contact-sheet.jpg`). Glance at it; if nothing is obviously broken, move on — don't linger here.
+If a command fails, surface stderr and stop — don't pile on recovery commands. Fix it yourself: the cheapest safe edit to `compositions/frames/NN-*.html`, then rerun the failed check.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio.
+Preview: `npx hyperframes preview`
+Render only after user approval:
+`npx hyperframes render --skill=product-launch-video --quality high --output renders/video.mp4`
+Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless the user asks.
+**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause; `renders/video.mp4` exists. Final reply states MP4 path and final duration.
+---
+## Quick Reference
+**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the format once in the storyboard frontmatter.
+**Background scripts:** the workflow ships only these scripts under `scripts/`: `build-frame` for adopting + brand-remixing a frame preset into `frame.md` (+ caption skin); `audio` for TTS, transcription, BGM, SFX, and duration syncing; `captions`; `transitions` for inject and verify; `stage-assets` for copying frame-named assets into `assets/`; and `assemble-index`. Everything else is handled by the `hyperframes` CLI.
+The reusable, product-agnostic shot shapes live in `../hyperframes-animation/blueprints/` (indexed by `../hyperframes-animation/blueprints-index.md`).
+| Read                                                                                                                                                        | When                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                       |
+| `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                          |
+| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the product-launch story.                         |
+| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.      |
+| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                 |
+| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                     |
+| `[../vidfarm-media/references/tts.md](../vidfarm-media/references/tts.md)`                                                                                  | Step 3.1: TTS providers and voices — `vidfarm tts` (BYOK) or `npx hyperframes tts` (keyless local). |
+| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary). |
+| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.           |
+| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).  |
+| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.        |
+| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                            |
+| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                            |