@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/website-to-video/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: website-to-video
+description: "Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes."
+---
+
+> **media sourcing**: Before sourcing audio/images, read `../vidfarm-media` — it resolves BGM/SFX/images through vidfarm surfaces: My Files search, the clip library, and image generation.
+
+# Website to HyperFrames
+
+Capture a website, then produce a professional video from it.
+
+> **Confirm the route before Step 0.** This skill makes a video _of / from a general site_. If the user is really **marketing / launching / promoting a product** (even from this URL, even "promo for our site") → `/product-launch-video`. A **topic explainer with no site** → `/faceless-explainer`; a **GitHub PR** → `/pr-to-video`; **re-cutting / recoloring / reordering an existing video file** → out of scope. Routed here on a vague "make a video", or unsure launch-vs-general-site? **Read `/hyperframes` first** (full routing table + § What HyperFrames cannot do).
+
+Users say things like:
+
+- "Turn this website into a 15-second social clip for Instagram"
+- "Make a 30-second site tour / showcase from https://..."
+- "Capture our homepage and build a video from its own visuals"
+
+The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped; see step-2-brief.md for how that propagates.
+
+**Autonomous mode is NOT "skip all gates."** Auto mode covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:
+
+- Asset Audit (Step 3) — viewing contact sheets and justifying USE/SKIP for each asset
+- Per-beat HTML read (Step 5) — structured evidence block per beat
+- DoD checklist (Step 6) — including animation-map, per-warning WCAG verification, audio/motion playback
+- Honest disclosure section (Step 6) — "What I did NOT verify" must appear in your final summary
+
+If you find yourself reasoning "auto mode says bias toward action, so I'll skip X" — and X is a verification gate, not a preference question — that reasoning is wrong. Bias toward action applies to deciding _what to build_, not to deciding _whether to verify_.
+
+---
+
+## Step 0: Capture & Understand the Brand
+
+**Read:** [references/step-0-capture.md](references/step-0-capture.md)
+
+Capture the site, then read the extracted data to understand the **brand and product** — what it does, who it's for, what voice it speaks in, what mood it lives in. The captured assets are a brand toolkit for later, not the building blocks the video is made from.
+
+**Run the provider preflight before the brief** — check which AI provider keys are saved (`vidfarm provider-keys`, or env: `OPENAI_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY` / `ELEVENLABS_API_KEY`) and report which audio engines this run will use: **BYOK cloud** — `vidfarm tts` (promptable voice) and `vidfarm stt` (real word timestamps on an OpenAI whisper-1 key) when a key is present — or the **keyless local engines** (`vidfarm tts --engine local` Kokoro-82M, `vidfarm stt --engine whisper` whisper.cpp) when not. There is no sign-in or account step — vidfarm is BYOK; if no key is saved, note that the local engines need no key and continue. See `../vidfarm-media/references/tts.md` for the canonical guidance.
+
+**Gate:** Site summary printed — strategy-first (what the product does, who it's for, brand voice) before the asset / color / font inventory; provider status was shown (BYOK cloud engines, or keyless local engines).
+
+---
+
+## Step 1: Brand Identity
+
+**Read:** [references/step-1-design.md](references/step-1-design.md)
+
+Write DESIGN.md — a brand cheat sheet covering the visual identity: colors, typography, component styles, layout principles. Use `design-styles.json` for exact computed values.
+
+**Speed option:** For fast-pacing videos (billboard-per-beat), DESIGN.md can be a 50-line summary of colors + fonts + do's/don'ts — not a 300-line document. The sub-agent prompt in Step 5 pastes brand values directly, so DESIGN.md depth only matters for complex compositions.
+
+**Gate:** `DESIGN.md` exists (any length) with at minimum: color palette, font choices, and do's/don'ts.
+
+---
+
+## Step 2: Strategy & Messaging
+
+**Read:** [references/step-2-brief.md](references/step-2-brief.md), [references/capabilities.md](references/capabilities.md) (scan the Table of Contents — deep-dive sections only as needed)
+
+Align with the user on **what the video must communicate** before talking visuals or assets. Parse the user's prompt — they probably already gave you the video type and style. Ask only what's missing: the ONE thing this video must say, the narrative arc, and the audience.
+
+**Gate:** Video type, duration, format, and — critically — the message and narrative arc are locked. Without those, Step 3 can't write a concept-first storyboard.
+
+---
+
+## Step 3: Storyboard + Script 💬
+
+**Read:** [references/step-3-storyboard.md](references/step-3-storyboard.md)
+
+Write the storyboard concept-first: message → narrative arc → beats that serve the arc → techniques per beat → brand accents pass at the end. Then write the narration script to match. Present both to the user with a beat-by-beat summary. Iterate until they approve.
+
+**Gate:** `STORYBOARD.md` + `SCRIPT.md` exist AND the user has approved the plan.
+
+---
+
+## Step 4: VO, Timing + Captions 💬
+
+**Read:** [references/step-4-vo.md](references/step-4-vo.md)
+
+If Step 2 said no narration — ask about background music, then skip to Step 5. Otherwise: ask the user which TTS provider (vidfarm BYOK TTS — promptable voice, with word timings via `vidfarm captions generate` / `vidfarm stt`; ElevenLabs; or local Kokoro), generate audio, transcribe, map timestamps to beats. Then ask about captions.
+
+**Gate:** Either (a) no narration was requested and storyboard has manual beat timings, or (b) `narration.wav` + `transcript.json` exist and beat timings updated with real durations.
+
+---
+
+## Step 5: Build Compositions
+
+**Read:** The `hyperframes` skill (load it — every rule matters)
+**Read:** [references/step-5-build.md](references/step-5-build.md)
+
+Build index.html and compositions following the architecture and pacing chosen in the storyboard (Step 3). Sub-agents run `hyperframes lint` and `hyperframes snapshot` on each beat before reporting back.
+
+**Gate:** Every `compositions/beat-N.html` has been read top-to-bottom by the main agent against DESIGN.md and STORYBOARD.md. The per-beat checklist lives in [step-5-build.md](references/step-5-build.md).
+
+---
+
+## Step 6: Validate & Deliver
+
+**Read:** [references/step-6-validate.md](references/step-6-validate.md)
+
+Lint, validate, take snapshots scaled to video length (formula: `max(beats × 3, ceil(duration_seconds / 2))`), and review each one. Fix issues before delivering. Deliver the localhost Studio project URL — only render to MP4 on explicit user request. Surface that Studio URL **only at handoff** — it is the final, stable preview; the build-phase snapshots are headless, so do not pop a preview mid-build.
+
+**Deliver something you're proud of.** Before handing off, ask yourself: would I post this on social media with my name on it? If not, fix what's wrong.
+
+**Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors, and the final response includes the active Studio project URL.
+
+---
+
+## Quick Reference
+
+### Video Types
+
+Typical constraints by video type — use as a starting point, not a formula. Beat count should follow from the content and the narration, not from a target range.
+
+| Type                  | Typical duration | Duration driver    | Narration             |
+| --------------------- | ---------------- | ------------------ | --------------------- |
+| Social ad (IG/TikTok) | 10–15s           | Platform limit     | Optional              |
+| Product demo          | 30–60s           | Script length      | Full narration        |
+| Feature announcement  | 15–30s           | Feature complexity | Full narration        |
+| Brand reel            | 20–45s           | Music track        | Optional, music focus |
+| Launch teaser         | 10–20s           | Hook energy        | Minimal               |
+
+Beat count is not in this table intentionally — it should come from the storyboard, not from "social ad = 3-4 beats." A social ad for a complex product might need 5 well-timed beats. A brand reel with one strong visual thesis might need 3.
+
+### Format
+
+- **Landscape**: 1920x1080 (default)
+- **Portrait**: 1080x1920 (Instagram Stories, TikTok)
+- **Square**: 1080x1080 (Instagram feed)
+
+### Reference Files
+
+| File                                                                               | When to read                                                                                                                                   |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [step-0-capture.md](references/step-0-capture.md)                                  | Step 0 — capture, understand the brand and product, write strategy-first site summary                                                          |
+| [step-1-design.md](references/step-1-design.md)                                    | Step 1 — write DESIGN.md brand cheat sheet (5 sections, 250-350 lines; 50-line fast-path for billboard-style social ads)                       |
+| [step-2-brief.md](references/step-2-brief.md)                                      | Step 2 — align on message, narrative arc, audience with user                                                                                   |
+| [capabilities.md](references/capabilities.md)                                      | Steps 2 & 5 — full inventory of what HyperFrames can do (24 sections). Scan the TOC during the brief, deep-dive specific sections during build |
+| [step-3-storyboard.md](references/step-3-storyboard.md)                            | Step 3 — storyboard + script (combined) with user review gate                                                                                  |
+| [step-4-vo.md](references/step-4-vo.md)                                            | Step 4 — TTS provider choice, generation, timing                                                                                               |
+| [step-5-build.md](references/step-5-build.md)                                      | Step 5 — build index.html + compositions                                                                                                       |
+| [step-6-validate.md](references/step-6-validate.md)                                | Step 6 — lint, validate, snapshots (scaled to video length), preview                                                                           |
+| [techniques.md](../hyperframes/references/techniques.md)                           | Steps 3 & 5 — 13 primitive animation techniques with code patterns (adapt, don't copy-paste)                                                   |
+| [html-in-canvas-patterns.md](../hyperframes/references/html-in-canvas-patterns.md) | Step 5 — complete code patterns for HTML-in-Canvas effects (lives in the hyperframes skill)                                                    |

package/.agents/skills/website-to-video/assets/sfx/CREDITS.md

@@ -0,0 +1,35 @@
+# SFX Credits
+
+All sound effects in this directory are sourced from [Pixabay](https://pixabay.com/sound-effects/) and used under the [Pixabay Content License](https://pixabay.com/service/license-summary/).
+
+The Pixabay license allows free use for commercial and non-commercial purposes without attribution, but attribution is appreciated and given here for transparency.
+
+## Files
+
+The following `.mp3` files are bundled with this skill:
+
+- `chime.mp3`
+- `click.mp3` / `click-soft.mp3`
+- `error.mp3`
+- `glitch-1.mp3` / `glitch-2.mp3` / `glitch-3.mp3`
+- `impact-bass-1.mp3` / `impact-bass-2.mp3`
+- `key-press.mp3`
+- `notification.mp3`
+- `ping.mp3`
+- `pop.mp3`
+- `riser.mp3`
+- `sparkle.mp3`
+- `typing.mp3`
+- `whoosh.mp3` / `whoosh-short.mp3` / `whoosh-cinematic.mp3`
+
+See `manifest.json` for per-file metadata (duration, energy character, recommended use).
+
+## License
+
+All files are distributed under the [Pixabay Content License](https://pixabay.com/service/license-summary/), which permits:
+
+- Commercial and non-commercial use
+- Modification and remixing
+- Redistribution as part of derivative works (such as videos rendered with HyperFrames)
+
+without any attribution requirement.

package/.agents/skills/website-to-video/assets/sfx/manifest.json

@@ -0,0 +1,97 @@
+{
+  "chime": {
+    "file": "chime.mp3",
+    "duration": 2.5,
+    "description": "This is a soft, melodic chime sound effect perfect for signaling a gentle transition or a lighthearted moment in a video."
+  },
+  "click-soft": {
+    "file": "click-soft.mp3",
+    "duration": 0.37,
+    "description": "This is a smooth, medium-energy swoosh sound effect, perfect for transitioning between two scenes or highlighting a sleek reveal."
+  },
+  "click": {
+    "file": "click.mp3",
+    "duration": 0.37,
+    "description": "This is a sharp, medium-energy digital \"whoosh\" effect that works perfectly for a quick transition between video clips."
+  },
+  "error": {
+    "file": "error.mp3",
+    "duration": 1.62,
+    "description": "This is a sharp, medium-energy digital glitch sound that serves as an effective, abrupt transition for a video cut or error screen."
+  },
+  "glitch-1": {
+    "file": "glitch-1.mp3",
+    "duration": 2.64,
+    "description": "This is a high-energy, distorted digital impact sound effect that works perfectly for a sudden reveal or a punchy transition in a fast-paced edit."
+  },
+  "glitch-2": {
+    "file": "glitch-2.mp3",
+    "duration": 3.5,
+    "description": "This is a harsh, distorted digital glitch effect with high energy that serves as a jarring transition or a chaotic digital reveal."
+  },
+  "glitch-3": {
+    "file": "glitch-3.mp3",
+    "duration": 3.1,
+    "description": "This is a low-energy, subtle electronic click sound effect that works well as a minimal audio transition or a UI element for a subtle selection reveal."
+  },
+  "impact-bass-1": {
+    "file": "impact-bass-1.mp3",
+    "duration": 2.12,
+    "description": "This is a medium-energy, sharp electronic chime that works perfectly as an accent for a quick transition or a brief, high-tech visual reveal."
+  },
+  "impact-bass-2": {
+    "file": "impact-bass-2.mp3",
+    "duration": 2.59,
+    "description": "This sound effect is a shimmering, ethereal synth riser with a medium energy level, perfect for creating anticipation before a magical transition or reveal."
+  },
+  "key-press": {
+    "file": "key-press.mp3",
+    "duration": 0.4,
+    "description": "This is a medium-energy, distorted digital impact sound effect that works well for a sudden glitch transition or a glitchy text reveal."
+  },
+  "notification": {
+    "file": "notification.mp3",
+    "duration": 2.46,
+    "description": "This is a medium-energy, whimsical digital transition sound effect that fits perfectly with a playful visual reveal or a cute UI interaction."
+  },
+  "ping": {
+    "file": "ping.mp3",
+    "duration": 1.32,
+    "description": "This is a medium-energy, sharp electronic impact sound that works perfectly for punchy transitions or highlighting key on-screen reveals."
+  },
+  "pop": {
+    "file": "pop.mp3",
+    "duration": 0.72,
+    "description": "This is a medium-energy, metallic clinking sound that works perfectly as an accent or a subtle impact for a precise visual reveal or UI element."
+  },
+  "riser": {
+    "file": "riser.mp3",
+    "duration": 10.03,
+    "description": "This is a high-energy cinematic air whoosh transition that builds tension before suddenly cutting, making it perfect for a dramatic scene change or a quick reveal."
+  },
+  "sparkle": {
+    "file": "sparkle.mp3",
+    "duration": 1.8,
+    "description": "This is a bright, high-energy \"whoosh\" transition sound with a fast, ascending pitch that is perfect for a rapid scene change or a quick reveal."
+  },
+  "typing": {
+    "file": "typing.mp3",
+    "duration": 1.5,
+    "description": "This is a hard, high-pitched \"ding\" sound that works well as an accent for a reveal or a quick transition."
+  },
+  "whoosh-cinematic": {
+    "file": "whoosh-cinematic.mp3",
+    "duration": 5.54,
+    "description": "This is a medium-energy, cinematic whoosh effect, ideal for smooth scene transitions or emphasizing a quick reveal."
+  },
+  "whoosh-short": {
+    "file": "whoosh-short.mp3",
+    "duration": 0.57,
+    "description": "This is a medium-energy, organic wooden texture sound effect that works well as a subtle transition or a background accent."
+  },
+  "whoosh": {
+    "file": "whoosh.mp3",
+    "duration": 0.57,
+    "description": "This is a hard, metallic impact sound effect that works well for a sudden reveal or a punchy transition."
+  }
+}

package/.agents/skills/website-to-video/references/beat-builder-guide.md

@@ -0,0 +1,263 @@
+# Beat Builder Guide
+
+You are building ONE beat of a multi-beat video composition. This file tells you what to read, how to build, how to verify, and how to report back.
+
+## Step 1: Read and understand
+
+**Required (every beat):**
+
+1. **Load the `hyperframes` skill** — composition rules, data attributes, timeline contract, deterministic rendering. Read the whole skill.
+2. **[capabilities.md](capabilities.md)** — full inventory of HyperFrames capabilities (24 sections). Read the Table of Contents first, then deep-dive sections your beat needs.
+3. **The beat spec** the main agent gave you — concept, choreography, assets, brand values, timing.
+
+**Read based on what your beat needs (pick relevant ones):**
+
+| Resource                                                                              | What it covers                                                                                                                | Read when                                         |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| [techniques.md](../../hyperframes/references/techniques.md)                           | 13 primitive animation techniques: SVG path drawing, Canvas 2D, CSS 3D, kinetic type, variable fonts, MotionPath, etc.        | Beat uses any of these techniques                 |
+| [text-effects.md](../../hyperframes/references/text-effects.md)                       | 24 named text animations from `pixel-point/animate-text` (separate skill — load via `/animate-text` for specs)                | Beat has text animation                           |
+| [html-in-canvas-patterns.md](../../hyperframes/references/html-in-canvas-patterns.md) | HTML-in-Canvas: iPhone/MacBook mockups, liquid glass, magnetic, portal, shatter, text cursor                                  | Beat uses device mockups or WebGL effects on HTML |
+| [transitions.md](../../hyperframes/references/transitions.md)                         | Shader transition API, HyperShader.init() pattern, all 14 WebGL shaders                                                       | Beat has shader transitions                       |
+| [transitions/](../../hyperframes/references/transitions/)                             | 14 CSS transition category files: push, scale, dissolve, blur, 3D flip, light leak, distortion, grid, mechanical, destruction | Beat uses CSS transitions                         |
+| [css-patterns.md](../../hyperframes/references/css-patterns.md)                       | Text markers: highlight sweeps, hand-drawn circles, burst lines, scribble, sketchout                                          | Beat uses text emphasis/markers                   |
+| [audio-reactive.md](../../hyperframes/references/audio-reactive.md)                   | Bass→scale, mid→shape, treble→glow mappings                                                                                   | Beat reacts to music/audio                        |
+| [captions.md](../../hyperframes/references/captions.md)                               | Per-word karaoke, tone-adaptive styling, positioning                                                                          | Beat includes captions                            |
+| [typography.md](../../hyperframes/references/typography.md)                           | Font hierarchy, variable fonts, responsive type scaling                                                                       | Beat has complex typography                       |
+| [motion-principles.md](../../hyperframes/references/motion-principles.md)             | Velocity matching, easing philosophy, motion continuity                                                                       | Beat needs polished motion design                 |
+| [dynamic-techniques.md](../../hyperframes/references/dynamic-techniques.md)           | Counter animations, data-driven visuals, dynamic content                                                                      | Beat has counters or data visualization           |
+| [video-composition.md](../../hyperframes/references/video-composition.md)             | Frame composition, color presence, scale, density rules                                                                       | General composition quality                       |
+
+**Other skills you can load if needed:**
+
+- `/gsap` or `/gsap-core`, `/gsap-timeline`, `/gsap-plugins` — deeper GSAP reference
+- `/animate-text` — curated text animation catalog with exact JSON specs
+- `/hyperframes-registry` — if you need to install and wire registry blocks
+- `/hyperframes-contrast` — audit color contrast (WCAG)
+- `/lottie`, `/three`, `/waapi`, `/animejs`, `/css-animations` — if beat uses these engines
+
+**Always open the captured assets folder before designing the beat:**
+
+- `capture/assets/svgs/` — brand logos, icons, decorative marks. SVGs are infinitely scalable and stroke-animatable (path drawing, dash offset). A logo SVG drawing itself onto frame can carry an entire beat.
+- `capture/assets/` — hero illustrations, screenshots, product art, gradients, photography. These are first-class beat subjects, not background decoration. A breathing hero illustration with a single line of kinetic type is a complete shot.
+- VIEW every image before placing text on it. Check safe zones, contrast, actual content, where the focal point sits.
+
+**If your beat spec names a captured asset, USE it.** Don't substitute a CSS recreation. The user captured these from the real brand site precisely so the video carries the brand's actual visual identity.
+
+## Step 2: Build the composition
+
+Save to the path the main agent specified (usually `compositions/beat-N-name.html`).
+
+```html
+<template>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    /* your styles */
+  </style>
+
+  <div
+    id="beat-N-name"
+    data-composition-id="beat-N-name"
+    data-width="1920"
+    data-height="1080"
+    style="width:1920px; height:1080px; position:relative; overflow:hidden; background:#YOUR_BG;"
+  >
+    <!-- your elements -->
+  </div>
+
+  <script>
+    (function () {
+      var BEAT = 5.5; // MUST match data-duration on the host div in index.html
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+
+      // your GSAP animations
+
+      window.__timelines["beat-N-name"] = tl;
+    })();
+  </script>
+</template>
+```
+
+**Critical:** `data-composition-id`, `data-width`, `data-height` on the root div MUST match the host div in index.html.
+
+## Step 3: Lint
+
+```bash
+npx hyperframes lint .
+```
+
+Fix ALL errors. Zero errors required.
+
+## Step 4: Snapshot and verify
+
+```bash
+npx hyperframes snapshot . --frames 3
+```
+
+**READ the contact sheet** (`snapshots/contact-sheet.jpg`). For each frame:
+
+- Is content visible? (not black, blank, or loading)
+- Is text readable, properly positioned, correct font/color?
+- Are assets at the right size and position?
+- Does the animation state match the beat spec at this timestamp?
+
+**If anything is wrong:** fix, re-snapshot, re-check. You are done ONLY when every frame matches the spec.
+
+## Step 5: Report back honestly
+
+After lint passes, snapshots are taken, and you've fixed every issue you saw — report back to the main agent with concrete observations. Not "0 errors, looks good." That phrasing is what got prior videos shipped with mismatched brand colors, missing logos, and headlines too small to read.
+
+**The main agent will OPEN your composition file and read it top-to-bottom** to cross-check against DESIGN.md and STORYBOARD.md — does the brand bg/accent hex actually appear in your CSS, are the captured assets the storyboard called for actually referenced, is the headline ≥80px, does the GSAP timeline cover the full beat duration. You cannot pass that check by claiming things you didn't do; the file is on disk, the truth is in the file.
+
+So in your report, name the hex codes you used, the captured asset paths you placed, the headline `font-size`, and the GSAP timeline's last `tl.fromTo(...)` timestamp. Brief, concrete, true. If anything diverges from DESIGN.md or the storyboard, say so explicitly — the main agent can decide whether to accept the divergence or send you back to fix it. Surprises caught at this hand-off cost minutes; surprises caught at Step 6 cost iterations.
+
+### FLAG protocol — required phrasing for non-blocking issues
+
+When you find any of these, surface them as **FLAGS** in your report, not as conditional suggestions:
+
+- Visual states that briefly look broken (empty containers, hanging elements, gap moments)
+- Spec ambiguities you had to resolve by guessing
+- Linter bugs you worked around
+- Tween values you changed from the spec because they wouldn't fit
+
+**Forbidden phrasing:** "if the X feels too long, you could...", "consider tweaking Y", "might want to..."
+
+**Required phrasing — concrete, actionable, with line numbers:**
+
+```
+FLAG: at beat-local t=1.2s the doc card is visible but its inner content is still
+       opacity 0 — a 0.4s empty-panel window.
+       RECOMMENDED FIX: pull title typewriter from 1.6s → 1.4s
+       in compositions/beat-5-name.html line 234.
+```
+
+The main agent MUST EITHER apply each FLAG's fix OR write a one-sentence rejection with reason. Silently dropping a FLAG is a verification failure that gets caught at Step 6 (or worse, in the user's preview).
+
+### Spec ambiguity — escalate, don't paper over
+
+If STORYBOARD.md gives you a transition or transformation but doesn't establish the **start** state, do NOT guess. Examples of ambiguity worth flagging:
+
+- "Row 1 transitions from Huly Blue to Huly Orange at 3.5s" — but Row 1's initial color isn't specified
+- "Headline grows" — but the start size isn't specified
+- "Cards slide in" — but the off-screen position isn't specified
+- "Subhead appears after the headline" — but exact timing offset isn't specified
+
+**Required action:** FLAG the ambiguity in your report verbatim:
+
+```
+FLAG: STORYBOARD.md beat 3 says "Row 1 transitions blue → orange at 3.5s" but
+       Row 1's initial color is not specified anywhere. I interpreted Row 1 starts
+       blue and tweened to orange. CONFIRM or correct.
+```
+
+The main agent then confirms or corrects before Step 6 advances. Picking an interpretation silently means the build looks "fine" while diverging from intent — and the user only notices in motion.
+
+### Sub-agent diagnoses are unverified claims, not facts
+
+When a sub-agent reports "this is a linter false positive" / "this is a known bug" / "this attribute doesn't work as documented" — those are HYPOTHESES, not findings. Sub-agents diagnose from one symptom; they don't have repo-wide context.
+
+Before propagating any sub-agent diagnosis (e.g., applying the same "workaround" to another beat, or telling the user "this is a known bug"), do ONE of:
+
+1. **Verify by reading the source.** Open the file the sub-agent claims is buggy. Confirm the bug exists. Example: "I read `packages/core/src/lint/utils.ts:42` and confirmed the regex matches `url(\"data:image/svg+xml...\")` incorrectly. The workaround is to base64-encode the URI."
+2. **Disclose the unverified claim.** Don't suppress it — surface it. Example: "Sub-agent for beat 2 diagnosed `root_missing_composition_id` as a linter false positive on inline SVG data URIs. I applied the same workaround to beat 4 WITHOUT verifying the underlying claim. Worth filing as a regression against `packages/core/src/lint/utils.ts` to confirm."
+
+**Forbidden:** silently adopting the workaround pattern and presenting "lint passes" as evidence. If the workaround came from an unverified diagnosis, "lint passes because the diagnosis was correct AND I worked around it" and "lint passes because the diagnosis was wrong but the workaround happened to make the symptom disappear" are both possible. Without verification, you don't know which. The next session inherits the workaround AND the unverified diagnosis.
+
+### When you accept a sub-agent's divergence from spec — UPDATE the spec
+
+If a sub-agent reports "I diverged from STORYBOARD.md because..." AND you accept the divergence, you MUST update STORYBOARD.md to reflect the actual implementation. Otherwise the spec lies about the artifact.
+
+Examples:
+
+- Sub-agent: "Storyboard says 'HULY' uppercase but the actual logo asset is lowercase 'huly'. I used lowercase." Accept → edit STORYBOARD.md beat N to say "huly" lowercase. Note the change inline.
+- Sub-agent: "Storyboard says cells at 56px but they read too small at 1920×1080. I used 96px." Accept → edit STORYBOARD.md beat N's cell size to 96px.
+- Sub-agent: "Storyboard says SFX at t=4.7s but the visual moment lands at t=5.2s; I aligned SFX to the visual." Accept → edit STORYBOARD.md SFX line to t=5.2s.
+
+**Forbidden:** accepting the divergence silently and leaving the storyboard with the wrong spec. The next session reading STORYBOARD.md will trust it as ground truth. The spec is a contract; if you break the contract, update the contract.
+
+---
+
+## Continuous motion — the most important rule
+
+A beat is a SHOT in a film, not a webpage with entrance animations. Your GSAP timeline should have events spread across the ENTIRE beat duration — not just entrance tweens in the first 1-2 seconds followed by nothing. If an element is on screen, it should be doing something. After elements enter, add continuous hold motion: camera dolly, parallax layers moving at different speeds, secondary elements appearing mid-beat, real depth shifts.
+
+## You are building a SHOT, not a webpage
+
+The storyboard tells you the shot framing (close-up / medium / wide / etc.) and the camera move. Implement them. A beat is a moment, not a screenshot. The distinction is **what the camera is doing**, not whether the subject is a UI element or a logo — a tight push-in on a real product screenshot is a shot; a centered card on a parked camera is a webpage.
+
+**Patterns that turn a shot back into a webpage:**
+
+These are defaults to avoid, **not absolute prohibitions.** If the storyboard genuinely calls for "the kanban app interface" or "the browser chrome" as the subject of a specific beat (a product tour, a "this is how it works" demo, a stylized window mockup for the closer), then build it. The rule is: don't reach for these patterns by default when the storyboard didn't ask for them.
+
+- ⚠ **macOS / browser window chrome reproduced in CSS** — traffic-light dots, URL bars, browser tabs. Fine when the storyboard makes the chrome the subject (e.g. "stylized macOS window framing the product UI" for a closer). NOT fine when it's a frame you added around a card "to make it look like an app."
+- ⚠ **Full webpage layout** (sidebar + header + footer + main content area) — fine when the beat is genuinely a product tour shot. NOT fine when the beat was supposed to be about _the kanban moment_ and you defaulted to drawing the whole app around it.
+- ❌ **Parked-camera composition** — centered card with 60–120px margins on all sides and no camera move. Almost always wrong. Either give it a real push-in / dolly / parallax, or reframe.
+- ❌ **"Hold with breathing"** implemented as `y: ±1–2px` or `scale: 1.01` — invisible at 1920×1080+ scale. If continuous motion is required, use camera dolly (scale 1.0 → 1.05), parallax pan (x/y ±30–80px), or progressive reveals.
+- ❌ **Hover-state simulations** — videos have no hover. If the brand uses hover effects, show the BEFORE and AFTER as discrete frames in the timeline.
+- ❌ **Counter pulses + dot pulses + tiny scale wobbles** as the only motion during the hold — these are "I ran out of ideas" filler.
+
+The test: if the storyboard says _"this beat is the product tour, viewer sees the app interface"_, building a CSS dashboard with chrome is correct. If the storyboard says _"this beat is the kanban moment, single card sliding home"_, drawing the full app around it is wrong. Read the beat spec carefully.
+
+**Patterns that ARE shots (do these freely):**
+
+- ✅ **Captured SVG logo drawing itself stroke-by-stroke** (DrawSVG / path dashoffset) — a complete opener or stinger.
+- ✅ **Captured hero illustration with camera dolly** — push-in from 1.0 → 1.08 over 4s, focal element holds frame.
+- ✅ **Captured product screenshot with parallax layers** — separate the foreground UI from background panels and move them at different speeds, or use HTML-in-Canvas for an iPhone/MacBook mockup.
+- ✅ **Captured asset as the bed, kinetic type as the punchline** — the brand's hero image holds the frame while a one-line message arrives, splits, reflows.
+- ✅ **Composed-from-divs UI moment** when the beat is specifically about that UI's interaction (a card sliding into a column, a search result resolving) — this is the legit case for CSS-only composition.
+
+**Required motion magnitudes** (anything smaller is invisible at video scale):
+
+| Motion type     | Minimum magnitude                           |
+| --------------- | ------------------------------------------- |
+| Translate (y/x) | 30px (entrance) / 8px (drift during hold)   |
+| Scale           | 0.05 change (1.0 → 1.05 or larger)          |
+| Opacity         | full 0 → 1 or vice versa for reveals        |
+| Rotate          | 4° minimum to read (Dutch angles, ticks)    |
+| Camera dolly    | scale 1.0 → 1.06 minimum over beat duration |
+
+**Required cinematography per beat** (the storyboard should give you these; if it doesn't, escalate):
+
+- A **shot type** (close-up / medium / wide / over-the-shoulder / Dutch)
+- A **camera move** (dolly in/out, push, parallax pan, orbit, rack focus)
+- A **depth strategy** (what's foreground / midground / background)
+- A **purpose** (what specific feeling or noticing the shot delivers)
+
+If any are missing from the beat spec, the beat is under-defined. Don't fill the gap with "centered layout + breathing" — re-read the spec, and if it's genuinely missing, ask the main agent.
+
+## Rules
+
+- SCRIPT PLACEMENT: scripts inside `<template>`, never after `</template>`. Scripts outside see no DOM.
+- GSAP FROM TRAP: never `gsap.from(el, {opacity:0})` with CSS `opacity:0`. It animates 0→0. Use `tl.fromTo()`.
+- STYLE: avoid CSS `opacity:0` on GSAP-animated elements. Use GSAP fromTo for initial states.
+- ASSET PATHS: project-root-relative. `capture/assets/file.png` ✅ `../capture/assets/file.png` ❌
+- SVG VIA IMG: `<img src="logo.svg">` can't inherit CSS color. Inline SVG or `filter: brightness(0) invert(1)`.
+- CSS CENTERING: no `transform: translate(-50%, -50%)` with GSAP transforms. Use flexbox or `xPercent/yPercent`.
+- QUERYSELECTOR: `document.getElementById("id")` with null guards. No method calls without null check.
+- CHARACTER SPANS: `display:inline-block` on spaces collapses them. Use `&nbsp;` or per-word spans.
+- COUNTERS: no `onUpdate` for numeric counters — use discrete `tl.set(el, {textContent: "42"}, 2.5)` at timestamps. `onUpdate` and `tl.call()` ARE supported for canvas/WebGL rendering loops and character-by-character typing — see capabilities.md §10.
+- TIMELINE: `window.__timelines["beat-N-name"] = tl` synchronously. Key = `data-composition-id`.
+- DETERMINISTIC: no `Math.random()`, `Date.now()`, `requestAnimationFrame`, `repeat:-1`.
+- Always `tl.fromTo()` not `tl.from()` for entrances.
+- Never stack two transform tweens on same element at same time.
+- FONTS: copy the `@font-face` block VERBATIM from DESIGN.md's Fonts section. Do NOT guess which `.woff2` file belongs to which family — capture filenames are content-hashed (`14d7ce3e41dcbb66-s.p.woff2`) and there is no visible mapping. If DESIGN.md doesn't include exact `src:` paths per family, STOP and ask the main agent to add them; never pair an arbitrary `.woff2` file with a family name from memory.
+
+## Easing — pick per intent
+
+Do NOT default to `power2.out` on everything.
+
+| Intent          | GSAP Ease             | Use for                              |
+| --------------- | --------------------- | ------------------------------------ |
+| Snap (iOS feel) | `power4.out`          | Hero text, UI elements               |
+| Whip overshoot  | `back.out(1.7)`       | Numbers, badges, impact              |
+| Soft land       | `expo.out`            | Per-word reveals, gentle entrances   |
+| Mechanical      | `power1.out`          | Terminal text, code typing           |
+| Bounce settle   | `elastic.out(1, 0.5)` | Counters, CTA buttons                |
+| Dramatic        | `expo.inOut`          | Full-screen statements, hero reveals |
+| Drift           | `"none"`              | Parallax, Ken Burns, camera drift    |
+
+Staggered items: `power4.out` with `stagger: 0.08` to `0.15`.