@mevdragon/vidfarm-devcli 0.14.0 → 0.16.0

package/.agents/skills/embedded-captions/themes/ransom.json

@@ -0,0 +1,62 @@
+{
+  "name": "ransom",
+  "voice": "kidnapper's collage — every word is a cutout chip clipped from a different page (cream Anton, black Inter, newsprint typewriter, accent-yellow marker) and PASTED crooked on the rail with torn edges and misaligned baselines; emphasis words get a 1-frame re-paste lift, spent chips are RIPPED off with paper-tear flashes. The apex: the sky darkens behind a collage scrim and the hero word slams in letter by letter as a ransom note — each letter a different chip, flight shadow popping tight on contact — then the whole word JOLTS as the last letter lands (the plate punches with it), looms crooked through the hold, and is torn off chip by chip.",
+  "when": "true crime, mystery / thriller content, heist energy, punk / DIY zine aesthetics, edgy product drops, unhinged-comedy hooks, \"勒索信/剪贴/拼贴字幕\" asks. Loud register; the solid chip backgrounds carry their own contrast on any scene.",
+  "register": "loud-collage",
+  "fonts": {
+    "body": "Anton",
+    "hero": "Anton",
+    "dark": "Inter",
+    "news": "Special Elite",
+    "accent": "Permanent Marker"
+  },
+  "palette": {
+    "body": "#f5f1e4",
+    "paper": "#f5f1e4",
+    "paperInk": "#17130d",
+    "dark": "#141414",
+    "darkInk": "#f7f5ef",
+    "news": "#d8d3c5",
+    "newsInk": "#262017",
+    "accent": "#ffd23f",
+    "accentInk": "#1c160c",
+    "flash": "#fffdf2"
+  },
+  "body": {
+    "paradigm": "ransomrail",
+    "layer": "fg",
+    "fontPx": 46,
+    "bottomPx": 56,
+    "letterSpacing": "0.02em",
+    "emphDelay": 0.23,
+    "seed": 3940,
+    "yield": { "dim": 0.5, "pre": 0.02, "post": 0.71 }
+  },
+  "hero": {
+    "setpiece": "ransomnote",
+    "layer": "bg",
+    "fontPx": 130,
+    "params": {
+      "step": 0.06,
+      "crush": 0.09,
+      "ripStag": 0.045,
+      "ripLead": 0.19,
+      "scrim": 0.44,
+      "pulse": 0.2,
+      "seed": 3939
+    }
+  },
+  "fx": {},
+  "plate": {
+    "punch": 0.04,
+    "punchDecay": 9,
+    "punchOffset": 0.64,
+    "shakeAmpX": 7,
+    "shakeAmpY": 5,
+    "shakeHz": 12,
+    "shakeDecay": 7,
+    "shakeWindow": 0.6,
+    "grain": 6
+  },
+  "linkages": []
+}

package/.agents/skills/embedded-captions/themes/scoreboard.json

@@ -0,0 +1,54 @@
+{
+  "name": "scoreboard",
+  "voice": "stadium split-flap departures board — every body word is a mechanical flap tile on a chyron bar that flip-cycles two seeded wrong words before clacking onto the real one (hot amber flash, cools to bone); a ROW counter flips at each line change and an odometer chip rolls beside the first emphasis line. The apex is a board takeover behind the subject: floodlights swing on, a giant departures housing clacks down, one huge flap tile per letter flip-cycles wrong glyphs then locks the word left→right under a crowd-flash, the status ticker types on, one tile re-flutters during the hold.",
+  "when": "sports, transit/travel, scores, countdowns, announcements and reveals — anything that should read as DEPARTURES-board mechanical. Loud register; needs a lower third that tolerates a dark chyron bar.",
+  "register": "loud",
+  "fonts": { "body": "Teko", "hero": "Anton", "tag": "Teko" },
+  "palette": {
+    "body": "#F5EEDD",
+    "hot": "#FFB347",
+    "accent": "#FFB347",
+    "grey": "#B9BEC7",
+    "boardBone": "#F6EFDF"
+  },
+  "body": {
+    "paradigm": "flaprail",
+    "layer": "fg",
+    "fontPx": 48,
+    "barH": 96,
+    "letterSpacing": "1px",
+    "seed": 808,
+    "chyron": { "tag": "DEPARTURES", "counter": "ROW" },
+    "chip": { "label": "LIMIT", "value": "1.2", "unit": "PX", "x": 884, "y": 563 },
+    "yield": { "dim": 0.55, "pre": 0.07, "post": 0.47 }
+  },
+  "hero": {
+    "setpiece": "flapboard",
+    "layer": "bg",
+    "fontPx": 138,
+    "params": {
+      "seed": 8088,
+      "glyphs": "ABCDEFGHIKLMNOPRSTUVXYZ0123456789",
+      "lockWindow": 0.34,
+      "gap": 7,
+      "headerLeft": "★ DEPARTURES",
+      "headerRight": "GATE 06  22:40",
+      "tag": "STATUS // NOW BOARDING"
+    }
+  },
+  "fx": { "crowdflash": [0.5, 0.45] },
+  "plate": {
+    "charge": 0.62,
+    "dim": 0.34,
+    "punch": 0.045,
+    "punchDecay": 9,
+    "punchOffset": 0.34,
+    "shakeAmpX": 7,
+    "shakeAmpY": 5,
+    "shakeHz": 12,
+    "shakeDecay": 7,
+    "shakeWindow": 0.6,
+    "grain": 6
+  },
+  "linkages": []
+}

package/.agents/skills/embedded-captions/themes/spectrum.json

@@ -0,0 +1,46 @@
+{
+  "name": "spectrum",
+  "voice": "an oscilloscope is listening — a dark scope band hosts an always-alive waveform (speech grows it, silence flattens it, every word kicks a local burst) and body words are traced on in phosphor mono with a just-traced flash; the apex is the trace itself LEAPING off the scope to hand-write the hero word in a thin phosphor stroke, fill flicker, hum, then collapse to a flatline — and on the final word the whole trace explodes, flatlines to a single dot and stamps SIGNAL LOST.",
+  "when": "science / signal / audio / measurement / astronomy explainers, data-nerd content, retro-lab or synth aesthetics, \"示波器/波形/信号字幕\" asks. The band brings its own dark glass; bright scenes fine.",
+  "register": "tech-retro",
+  "fonts": { "body": "VT323", "tag": "VT323", "strokeFont": "HersheyScript1.svg" },
+  "palette": {
+    "body": "#4dff88",
+    "accent": "#4dff88",
+    "bright": "#d6ffe4",
+    "flash": "#eafff2",
+    "em": "#ffb347",
+    "hud": "#2f8f55",
+    "panic": "#ff5f47"
+  },
+  "body": {
+    "paradigm": "scoperail",
+    "layer": "fg",
+    "fontPx": 40,
+    "bandH": 164,
+    "waveTop": 80,
+    "waveH": 84,
+    "lineDy": 34,
+    "hudL": "SPECTRUM // CH1",
+    "siglost": "— SIGNAL LOST —",
+    "waveSeed": 7,
+    "chipSeed": 11,
+    "yield": { "dim": 0.52, "pre": 0.13, "post": 0.97 }
+  },
+  "hero": {
+    "setpiece": "scopetrace",
+    "layer": "bg",
+    "params": {
+      "targetWidth": 720,
+      "window": 0.6,
+      "flickGap": 0.12,
+      "clearGap": 0.215,
+      "coreWidth": 4,
+      "haloWidth": 14,
+      "spill": 0.55
+    }
+  },
+  "fx": {},
+  "plate": { "scrim": 0.62, "grain": 5 },
+  "linkages": []
+}

package/.agents/skills/embedded-captions/themes/stardust.json

@@ -0,0 +1,29 @@
+{
+  "name": "stardust",
+  "voice": "celestial condensation — letters condense out of drifting dust into an accumulating poem; the apex assembles from inbound star particles; on the final word the entire visible poem disperses back into dust (semantic exit).",
+  "when": "introspective, poetic, memory, science-wonder monologues. The poem column needs one clear side; a soft gradient scrim (behind the subject) handles bright skies.",
+  "register": "poetic",
+  "fonts": { "body": "Cormorant Garamond" },
+  "palette": { "body": "#f7f0dd" },
+  "body": {
+    "paradigm": "poem",
+    "layer": "fg",
+    "fontPx": 58,
+    "left": 84,
+    "stanzaTops": [110, 222, 292],
+    "entrance": "condense",
+    "exit": "drift",
+    "bigScale": 2.0,
+    "emScale": 1.38,
+    "scrim": { "side": "left", "opacity": 0.62 },
+    "seed": 777
+  },
+  "hero": {
+    "setpiece": "assembly",
+    "inline": true,
+    "params": { "particles": 22, "spread": 150 }
+  },
+  "fx": {},
+  "plate": { "pushIn": 0.01, "grain": 5 },
+  "linkages": ["disperse-on-last-word"]
+}

package/.agents/skills/embedded-captions/themes/stomp.json

@@ -0,0 +1,43 @@
+{
+  "name": "stomp",
+  "voice": "full-frame typographic takeover — every beat is a hard-cut center card over a dimmed plate; a long-held card creeps with tension into a true VOID, then the apex detonates in the accent color; the final word dissolves to blur.",
+  "when": "hooks, manifestos, ads, hype openers. The plate runs dimmed throughout — content where the words ARE the show. Body stays bg (text behind the subject is the identity).",
+  "register": "takeover",
+  "fonts": { "body": "Anton" },
+  "palette": { "body": "#F5F1E8", "accent": "#FF5C39" },
+  "body": {
+    "paradigm": "takeover",
+    "layer": "bg",
+    "anchors": [
+      [640, 330],
+      [612, 302],
+      [668, 358],
+      [640, 388],
+      [618, 336]
+    ],
+    "baseDim": 0.42,
+    "entrance": "cut",
+    "creepScale": 1.1,
+    "hotSnap": 1.18,
+    "sizes": { "function": 150, "content": 200, "minor": 230 }
+  },
+  "hero": {
+    "setpiece": "colorflip",
+    "inline": true,
+    "fontPx": 196,
+    "params": { "crushFrom": 2.6, "dimKick": 0.62, "flash": 0.9, "dissolveLast": true }
+  },
+  "fx": { "flash": 0.9 },
+  "plate": {
+    "punch": 0.05,
+    "punchDecay": 9,
+    "shakeAmpX": 8,
+    "shakeAmpY": 5,
+    "shakeHz": 12,
+    "shakeDecay": 7,
+    "shakeWindow": 0.6,
+    "grain": 7,
+    "minorPunch": 0.02
+  },
+  "linkages": []
+}

package/.agents/skills/embedded-captions/themes/terminal.json

@@ -0,0 +1,49 @@
+{
+  "name": "terminal",
+  "voice": "console session — the transcript is a signal log typed into a docked glass panel; the apex decodes out of noise as slot-machine glyph reels, and the log REDACTS the apex words (█████) until the decode locks. The feed corrupts on the final word.",
+  "when": "tech, data, AI, engineering, investigative explainers. Cool scenes preferred (the cyan is scene-motivated on cool/dusk palettes).",
+  "register": "creator-tech",
+  "fonts": { "body": "VT323", "hero": "Orbitron", "tag": "VT323" },
+  "palette": {
+    "body": "#bfeefe",
+    "accent": "#66e0ff",
+    "magenta": "#ff5fd6",
+    "panelBg": "rgba(2,14,22,0.62)",
+    "prompt": "#4d7f93"
+  },
+  "body": {
+    "paradigm": "panel",
+    "layer": "fg",
+    "fontPx": 34,
+    "panel": { "left": 36, "bottom": 30, "width": 470, "header": "SIGNAL LOG_" },
+    "entrance": "type",
+    "exit": "hold",
+    "caret": true,
+    "yield": { "dim": 0.68 }
+  },
+  "hero": {
+    "setpiece": "decode",
+    "layer": "bg",
+    "x": 660,
+    "y": 255,
+    "fontPx": 112,
+    "params": {
+      "glyphs": "X017#%/<>+=*KZR",
+      "brackets": true,
+      "lockStagger": 0.045,
+      "exit": "crt-off",
+      "seed": 99
+    }
+  },
+  "fx": { "scanband": true, "lockflash": 0.55 },
+  "plate": {
+    "dim": 0.22,
+    "punch": 0.016,
+    "punchDecay": 10,
+    "shakeAmpX": 0,
+    "shakeAmpY": 0,
+    "rgbashift": 4,
+    "grain": 6
+  },
+  "linkages": ["redact-until-hero", "corrupt-on-last-word"]
+}

package/.agents/skills/embedded-captions/themes/thunder.json

@@ -0,0 +1,44 @@
+{
+  "name": "thunder",
+  "voice": "the storm is the editor — slate storm mood on the room, ambient slanted rain in front of the subject, and the sky 'kisses' (1-frame brighten) on every body word. Body words arrive on a rain-scrimmed lower third with a lit-bright lightning pop; emphasis words get a sheet-lightning double flash mirrored by a double sky-kiss. The apex is THE STRIKE: a hand-authored branched bolt flashes two frames before the word, then the word slams in lit HARD with its shadow flipped toward the bolt, ozone under-glow breathing through the hold while the rain doubles; everything washes downward with the rain.",
+  "when": "dramatic reveals, storm/weather content, epic hype beats, trailer-toned monologues, anything that should land like a thunderclap. Loud register; the charge-dim + word scrim make their own contrast on any plate (bright skies included).",
+  "register": "loud",
+  "fonts": { "body": "Sora", "hero": "Anton", "tag": "Sora" },
+  "palette": {
+    "body": "#EEF4FB",
+    "hero": "#F2F7FF",
+    "accent": "#9FD0FF",
+    "glow": "#CFE8FF",
+    "core": "#FFFFFF"
+  },
+  "body": {
+    "paradigm": "stormrail",
+    "layer": "fg",
+    "fontPx": 44,
+    "bottomPx": 98,
+    "letterSpacing": "0.015em",
+    "rain": { "count": 18, "opacity": 0.08, "seed": 9021, "seed2": 4477 },
+    "yield": { "dim": 0.5, "pre": 0.15, "post": 0.29 }
+  },
+  "hero": {
+    "setpiece": "boltstrike",
+    "layer": "bg",
+    "fontPx": 145,
+    "params": { "mood": 0.1, "side": "left", "hold": 2.05 }
+  },
+  "fx": { "strikeflash": 0.55 },
+  "plate": {
+    "charge": 0.3,
+    "dim": 0.22,
+    "punch": 0.04,
+    "punchDecay": 9,
+    "punchOffset": 0.02,
+    "shakeAmpX": 5,
+    "shakeAmpY": 4,
+    "shakeHz": 12,
+    "shakeDecay": 7,
+    "shakeWindow": 0.5,
+    "grain": 5
+  },
+  "linkages": []
+}

package/.agents/skills/embedded-captions/themes/transit.json

@@ -0,0 +1,44 @@
+{
+  "name": "transit",
+  "voice": "amber LED departure board — the whole video is a station PA system. Body words light column-by-column (L→R LED wipe + 1-frame arrival flicker) on a docked departure strip whose lines page in/out by scroll-snap; furniture: green platform tag, ticking seconds clock, a ⚠ DELAYED → ● ON TIME swap gag after the apex. The apex is a board takeover behind the subject: a big LED panel expands upward inside a chasing marquee border, the word illuminates column-by-column under a PA flash + two brightness 'ding' pulses, glow breathes with LED dropouts, then the word pages up and the panel collapses.",
+  "when": "travel/transit, announcements, schedules, countdowns, retro-terminal or arcade registers — anything that should read as an amber dot-matrix station board. Mid-loud register; needs a lower third that tolerates a dark LED strip.",
+  "register": "loud",
+  "fonts": { "body": "VT323", "hero": "VT323", "tag": "VT323" },
+  "palette": {
+    "body": "#FFB000",
+    "hot": "#FFE9B8",
+    "accent": "#FFB000",
+    "green": "#36E57A",
+    "warn": "#FF9E3D"
+  },
+  "body": {
+    "paradigm": "ledboard",
+    "layer": "fg",
+    "fontPx": 46,
+    "letterSpacing": "0.05em",
+    "board": { "left": 140, "width": 1000, "h": 116, "bottom": 30 },
+    "header": {
+      "plt": "PLT 4",
+      "clockPrefix": "19:42:0",
+      "statusWait": "⚠ DELAYED",
+      "statusOk": "● ON TIME"
+    },
+    "yield": { "dim": 0.5, "pre": 0.2, "post": 0.9 }
+  },
+  "hero": {
+    "setpiece": "ledwipe",
+    "layer": "bg",
+    "x": 620,
+    "y": 444,
+    "fontPx": 120,
+    "params": {
+      "panelW": 1080,
+      "wipeDur": 0.3,
+      "headerLeft": "NOW ARRIVING ▸ 19:42",
+      "headerRight": "GATE A4"
+    }
+  },
+  "fx": { "paflash": 0.5 },
+  "plate": { "charge": 0.5, "dim": 0.2, "grain": 5 },
+  "linkages": []
+}

package/.agents/skills/embedded-captions/themes/vhs.json

@@ -0,0 +1,47 @@
+{
+  "name": "vhs",
+  "voice": "camcorder tape playback — the whole frame is a VHS deck. A permanent lens vignette and OSD furniture (▶ PLAY, ● REC, green blinking timestamp) frame the clip; body words are an OSD lower third with a permanent 1px red+cyan misregistration fringe, arriving by tracking glitch (instant on + 2-frame y-shake + 1-frame band-slice shift) and exiting as REWIND streaks with flat-white echoes + scrub lines; the deck flips PLAY→REW in dead air. The apex is REC FREEZE: a 1-frame white tear band + head-switching noise bar, then the word slams in as a huge OSD readout behind the subject — three tracking-sliced bands shear in and SNAP into register, heavy red/cyan misregistration cools and keeps breathing through the hold under tape-weave jitter and an auto-iris pump, then the whole readout REWINDS off left.",
+  "when": "retro / nostalgia / found-footage / home-video registers, music and lifestyle edits, '90s tech content, '录像带/VHS/复古/DV' asks — anything that should read as a tape being played back. Mid-loud register; the backlight-comp scrim makes its own contrast on bright skies.",
+  "register": "retro-analog",
+  "fonts": { "body": "VT323", "hero": "VT323", "tag": "VT323" },
+  "palette": {
+    "body": "#F2F2EE",
+    "hot": "#FFFFFF",
+    "accent": "#D9F7D2",
+    "red": "#FF2E2E",
+    "cyan": "#3FE8E8",
+    "green": "#B9FFB0"
+  },
+  "body": {
+    "paradigm": "vhsrail",
+    "layer": "fg",
+    "fontPx": 44,
+    "bottomPx": 108,
+    "letterSpacing": "0.04em",
+    "osd": { "ts": ["JUN.11 2026 PM 7", "42"] },
+    "yield": { "dim": 0.55, "pre": 0.02, "post": 0.9 }
+  },
+  "hero": {
+    "setpiece": "vhsosd",
+    "layer": "bg",
+    "x": 640,
+    "y": 268,
+    "fontPx": 150,
+    "params": {
+      "bandClips": [
+        [0, 64],
+        [36, 30],
+        [70, 0]
+      ],
+      "bandShear": [-46, 40, -34],
+      "misregIn": 11,
+      "misreg": 3,
+      "weave": [-2, 1, -1, 2, -1, 1, -2, 0],
+      "vignette": 0.34,
+      "crush": 0.1,
+      "hold": 1.69
+    }
+  },
+  "plate": { "charge": 0.55, "dim": 0.12, "grain": 5 },
+  "linkages": []
+}

package/.agents/skills/faceless-explainer/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: faceless-explainer
+description: "turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video, up to ~3 min (sweet spot 30-90s), where every visual is invented (typography, abstract graphics, diagrams, data-viz) rather than captured. There is no URL, no website capture, and no real assets. Use this skill for topic explainers, concept breakdowns, how-tos, listicles, and narrative explainers. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a GitHub PR (use /pr-to-video), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first. This is the shot-sequence architecture: every 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.
+
+# Faceless Explainer to HyperFrames
+
+Use this skill to turn a body of text into an explainer video: pick a design system, plan a teaching story, and build it frame by frame in HyperFrames. **Faceless** means every visual is invented downstream — there is no capture step and no real asset inventory.
+
+> **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for **explaining a topic from text, with no product and no website to capture**. Route other intents elsewhere: a product launch/promo → `/product-launch-video`; a tour of a real site → `/website-to-video`; 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 brief → `capture/extracted/`; 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 topic in kebab-case, such as `compound-interest-explained`; 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: Brief (no capture)
+
+Goal: Fold the user's text into the project as the source of information. There is **no website capture and no real assets** — this is a faceless explainer.
+
+Save the user's full input verbatim, then create the synthetic capture package by hand:
+
+- `capture/extracted/visible-text.txt` — the full article / notes / topic / brief, verbatim. This is the source of **information**, not a story template (Step 3 reshapes it).
+- `capture/extracted/tokens.json` — `{ "title": "", "description": "", "colors": [], "fonts": [] }`. Fill `title`/`description` from the brief. Leave `colors`/`fonts` empty unless the user explicitly gave brand colors or fonts — then add them (the design preset supplies a complete palette regardless).
+
+If the user pasted a script or wants their wording kept, save it verbatim as `user_script.txt`, ask once "use it verbatim or restructure?", and store the answer as `VO_MODE` for Step 3.
+
+Do **not** run `npx hyperframes capture` (there is no URL). Do not create `asset-descriptions.md` or populate `capture/assets/` — faceless visuals are invented in Steps 4-5, not captured. The one exception: if the user supplied a real image, place it under `public/<basename>` and note it for Step 3.
+
+**Gate:** `capture/extracted/visible-text.txt` and `capture/extracted/tokens.json` exist; you can state the explainer's topic and audience in one clear sentence.
+
+---
+
+## 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 browse `../hyperframes-creative/frame-presets/`; pick the preset whose look best fits the topic, tone, and audience. 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 any brand tokens in `capture/extracted/tokens.json` (brand colors mapped onto the preset's color keys by role; 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 as soon as it exits 0 — no hand-editing of the spec.
+
+A faceless explainer usually has **no brand colors/fonts** (`tokens.json` colors/fonts empty) → the script keeps the preset's own palette, a complete shippable design. Only when the user named brand colors/fonts add them to `tokens.json` before running, and 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 text into an approved frame-by-frame teaching 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 the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching 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. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. 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 frame has the required narrative fields, `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. (The engine preflight already ran in Step 0; the engine falls back automatically.)
+
+`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 invented-visual treatment), plus 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 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 frame's **invented** content, and pace each Scene's reveal to the voiceover so the frame develops across its full duration instead of front-loading then freezing. Because the explainer is faceless, `focal`/`roles` name the **invented visual elements** (a hero word, a diagram node, a data-viz series) — you are designing them, not selecting captured assets. 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, `transition_in`, or the source text. Do not write HTML in this step. There is **no asset-staging step** — faceless visuals are built by the workers in Step 5. If the user supplied a real `public/<basename>` image, reference it by path in the relevant frame's `focal`/`roles`; otherwise nothing to stage.
+
+**Gate:** every frame has a time-coded shot sequence whose reveals are paced to the voiceover (no front-loading); each frame names its invented `focal` and/or `roles`; `## Video direction` exists.
+
+---
+
+## 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.
+
+**Known false-positive — do not chase it.** `inspect` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
+
+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=faceless-explainer --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.
+
+**Faceless deltas vs a captured-asset workflow:** no Step 1 capture (synthetic `tokens.json` + `visible-text.txt`); no `asset-descriptions.md` and no `capture/assets/`; no asset-staging in Step 4; `asset_candidates` empty by default; every visual is invented by the Step 5 workers (typography / abstract graphics / diagrams / data-viz). A user-supplied `public/<basename>` image is the only real asset path.
+
+**Background scripts:** the workflow ships only these 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; and `assemble-index`. Everything else is the `hyperframes` CLI.
+
+The reusable, domain-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 explainer 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.                            |