@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/website-to-video/references/step-0-capture.md

@@ -0,0 +1,55 @@
+# Step 0: Capture
+
+The capture pipeline downloads the site and extracts structured data for the rest of the workflow to read. Step 0 is a single command plus a sanity check. **All analysis (reading files, viewing contact sheets, deriving brand voice, picking assets) happens in Steps 1–3, not here.**
+
+## Run the capture
+
+No API keys required for the base capture. However, before running, ask the user:
+
+> "For the best results, it is recommended to set a Gemini API key — it gives me AI-powered descriptions of every captured image, which helps me choose the right assets for each scene. It costs about $0.001 per image. You can skip this if you want, but the video quality will be better with it. To set it up: add `GEMINI_API_KEY=your-key` to a `.env` file in the project root. You can get a free key at ai.google.dev."
+
+If the user provides the key or already has one set, proceed. If they skip it, proceed anyway — the capture works without it, but `asset-descriptions.md` will have DOM-context descriptions only (position, size, alt text) instead of AI vision descriptions.
+
+Create a project directory for your video if it doesn't exist yet, then capture the website into a `capture/` subfolder within it:
+
+```bash
+npx hyperframes capture <URL> -o <project-dir>/capture
+```
+
+Example: `npx hyperframes capture https://stripe.com -o videos/stripe-launch/capture`
+
+Keeping capture artifacts (`screenshots/`, `assets/`, `extracted/`, `AGENTS.md`, `CLAUDE.md`) in a dedicated `capture/` subfolder keeps them isolated from later build files (`SCRIPT.md`, `STORYBOARD.md`, `DESIGN.md`, `compositions/`, `index.html`, `narration.wav`, `transcript.json`, `renders/`, `snapshots/`), which all live at `<project-dir>/` root.
+
+For exploratory captures that aren't becoming a video yet, the default `./capture/` (or any `-o <name>` you pick) is fine — the isolation convention only matters when you're building a video on top of the capture.
+
+## Confirm it succeeded
+
+Wait for the capture to complete. Print one line summarizing what was captured:
+
+> "Captured N screenshots, M assets, K SVGs, F fonts. Ready for Step 1."
+
+If the command exited non-zero, the counts are all zero, or required directories (`extracted/`, `assets/`, `screenshots/`) are missing, surface the error and stop — don't advance to Step 1 with a broken capture.
+
+## What lives in `capture/` (reference table — DO NOT read these here)
+
+Each downstream step reads only what it needs. Don't pre-fetch everything in Step 0; that bloats context and produces summaries that get stale by the time they're used.
+
+| Path                                      | First read in                                 |
+| ----------------------------------------- | --------------------------------------------- |
+| `capture/extracted/tokens.json`           | Step 1 (DESIGN.md — colors / fonts)           |
+| `capture/extracted/design-styles.json`    | Step 1 (DESIGN.md — typography / components)  |
+| `capture/extracted/fonts-manifest.json`   | Step 1 (font identification)                  |
+| `capture/extracted/asset-descriptions.md` | Step 2 (brief grounding) and Step 3 (assets)  |
+| `capture/extracted/visible-text.txt`      | Step 2 (brief) and Step 3 (script)            |
+| `capture/assets/contact-sheet-*.jpg`      | Step 3 (asset picking)                        |
+| `capture/assets/svgs/contact-sheet-*.jpg` | Step 3 (SVG / logo picking)                   |
+| `capture/screenshots/contact-sheet-*.jpg` | Step 3 (visual mood reference)                |
+| `capture/extracted/animations.json`       | Step 3 / Step 5 (only if site has animations) |
+| `capture/extracted/lottie-manifest.json`  | Step 3 (only if site uses Lottie)             |
+| `capture/extracted/video-manifest.json`   | Step 3 (only if site embeds video)            |
+| `capture/extracted/shaders.json`          | Step 3 / Step 5 (only if site has WebGL)      |
+| `capture/assets/<individual files>`       | Step 5 (only when placing a specific asset)   |
+
+## Gate
+
+Capture exits 0. Asset / screenshot / font counts non-zero. Proceed to Step 1.

package/.agents/skills/website-to-video/references/step-1-design.md

@@ -0,0 +1,333 @@
+# Step 1: Write DESIGN.md (the brand-truth cheat sheet)
+
+DESIGN.md is a **brand-truth cheat sheet** — colors and fonts you'll **weave into your composed builds**. It is NOT a layout spec, not a moodboard, not a 400-line design system audit.
+
+DESIGN.md is the brand inflection sub-agents apply when building each beat: which color is "primary," which font is for headlines, what tone the brand carries — the load-bearing knobs they flip while building.
+
+**Target length: 250–350 lines.** Step 5 sub-agents read DESIGN.md to brand each beat — the more precise the component CSS values you encode here, the more brand-faithful the result. Going under 200 lines tends to produce generic dark-cinematic output because sub-agents have no brand component DNA to work from; going over 350 means you're over-investing in prose.
+
+**Fast-pacing exception:** For billboard-per-beat videos (short social ads where each beat is a single hero element on full-bleed background), a 50-line DESIGN.md with just colors + fonts + 3-5 do's/don'ts is enough. The Step 5 sub-agent prompt pastes brand values inline, so DESIGN.md depth only matters when the beats render full UIs.
+
+**User preferences always override brand rules.** If the user says "make it bright even though the site is dark" or "use serif fonts even though the brand is sans" — follow the user. DESIGN.md describes the captured website. The video might deliberately break that.
+
+**Read these now** — they're the inputs DESIGN.md is built from. Don't guess colors or sizes from screenshots:
+
+- `capture/extracted/tokens.json` — top brand colors (HEX) and font families with weight ranges.
+- `capture/extracted/design-styles.json` — computed CSS values from the live DOM: typography hierarchy (font-size, weight, line-height, letter-spacing per text role), button variants (background, padding, radius, shadow), card/container/nav styles, spacing scale, border-radius scale, box-shadow values with usage counts. **Primary data source for Sections 3–6 below.**
+
+**Font availability check — do this before writing anything else.** Read `capture/extracted/fonts-manifest.json`. The capture pipeline reads the OpenType `name` table embedded in every downloaded font file, so even hash-renamed Next.js/Webpack fonts are identified by their real family name (Inter, JetBrains Mono, Geist Mono, etc.). No guessing required.
+
+The manifest gives you two views:
+
+- `families[]` — one entry per distinct family with the weights captured, whether it's a variable font, and the files belonging to it
+- `files[]` — one entry per downloaded font with family, subfamily, weight, style, and any variation axes
+
+**How to use it:**
+
+- For each family you'll reference in DESIGN.md, name it by what's in `families[].family` (e.g. "Inter", not "f266e704 hashed font"). The hashed filenames are the `@font-face src` paths — they stay as-is on disk; only the display name comes from the manifest.
+- If a family has `variable: true` and `variationAxes` includes `"wght"`, you can use any weight 100-900 via `font-variation-settings: 'wght' <value>` even if only one static weight appears in the captured files. Note this in DESIGN.md so sub-agents know they have the full weight range available.
+- If the manifest's `unidentified[]` is non-empty, those files failed name-table extraction (rare — heavily subset fonts that strip metadata). Flag them as `unknown` in DESIGN.md and suggest a fallback rather than guessing.
+- Commercial fonts hosted on brand CDNs (GT Walsheim, Söhne, Graphik, Canela) won't be in the manifest because they aren't downloaded. Detect this by checking what the site uses (from `design-styles.json`) against what's in the manifest — anything used but missing is a CDN-hosted font. Flag explicitly: "Söhne not in capture; use Inter 600 as substitute."
+
+Sub-agents try to use the fonts you list. The manifest tells you exactly what's available — there's no excuse for claiming "Charlie Display 700" when no such file exists.
+
+---
+
+## The 5 sections to write
+
+### `## 1. Visual Theme (one paragraph)`
+
+3–5 sentences describing the brand's visual personality. Cover: dark-first or light-first, contrast strategy, dominant visual elements (gradients, illustrations, photography, UI mockups), overall mood, what makes it distinctive vs. generic.
+
+This is the only prose section. Make it specific to _this_ brand — not template-filling. A sentence that could describe any well-designed website is not useful.
+
+**Example:**
+
+> Stripe's visual language is light-first and clean, with deep navy (`#061B31`) and pure white as the foundation. The accent stack — Stripe Purple (`#533AFD`) for CTAs, Vibrant Orange (`#FF6118`) for energetic emphasis — keeps interactive elements unmistakable. Type is sohne-var Light (300) for display, weight 400 for body; the brand achieves hierarchy through size and weight, never color shifts. The mood is confident financial-tech — premium without theatrical drama. Distinctive: gradient overlays at 135° between purple and orange appear as subtle washes over white backgrounds, never as bold focal elements.
+
+---
+
+### `## 2. Quick Reference`
+
+A flat lookup of the values sub-agents grab while composing beats. Two sub-sections — keep them tight.
+
+#### Colors
+
+List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't.
+
+**For each text-on-surface combination the brand uses, compute the WCAG AA contrast ratio and flag failing pairings explicitly.** A real failure mode from prior runs: the brand's secondary-text color (`#68686A`) on its dark panel color (`#18191B`) = 3.16:1, which fails AA's 4.5:1 minimum. Sub-agents faithfully reproduced the brand's color choice and the result was unreadable. Encode the safe / unsafe pairings here so sub-agents pick text colors by surface context, not by "this is the brand's secondary text color." The `/hyperframes-contrast` skill audits ratios — run it before finalizing DESIGN.md.
+
+**Example:**
+
+```markdown
+#### Colors
+
+- **Stripe Purple** (`#533AFD`): Primary CTA, interactive elements, focus rings — the brand's action signal
+  - On Pure White: 6.2:1 ✅ — On Deep Navy: 3.8:1 ⚠ AA-only-Large
+- **Deep Navy** (`#061B31`): Primary text on light surfaces, also a dark surface tier
+  - As text on Pure White: 17.4:1 ✅ — As surface: see Slate-on-Navy pairings below
+- **Pure White** (`#FFFFFF`): Page background, card surfaces
+- **Light Gray** (`#F5F7FA`): Surface tier 2 (cards on white pages, alternating sections)
+- **Slate Blue** (`#273951`): Secondary text on LIGHT surfaces
+  - On Pure White: 12.6:1 ✅ — On Light Gray: 11.8:1 ✅ — On Deep Navy: 1.4:1 ❌ DO NOT USE
+- **Light Slate** (`#64748D`): Metadata, captions on light surfaces only
+  - On Pure White: 4.8:1 ✅ — On Light Gray: 4.5:1 ✅ — On Deep Navy: 3.0:1 ❌ — On Dark Panel: 2.9:1 ❌
+  - **For dark-surface metadata, use `#9A9A9E` instead: 6.4:1 on Deep Navy ✅, 6.1:1 on Dark Panel ✅**
+- **Subtle Border** (`#D4DEE9`): Card borders, dividers (not text — borders don't need AA)
+- **Vibrant Orange** (`#FF6118`): Energy accent — gradient endpoints, highlight bursts (never primary text)
+- **Error Red** (`#FF0022`): Validation errors. On Pure White: 4.5:1 ✅
+- **Success Green** (`#4CD963`): Confirmation states. On Pure White: 1.7:1 ❌ — must be paired with a darker outline or use as accent on dark surfaces
+```
+
+**Where the brand's own palette fails WCAG**, document the substitute (like the `#9A9A9E` override above). Sub-agents pick the safe color by surface — and if the deviation matters to the brand identity, the user can revisit at Step 6.
+
+#### Fonts
+
+List font families with their role AND **the exact file path per family + weight** from `fonts-manifest.json`. Sub-agents will copy the `@font-face` block verbatim — if you only name the family without the path, sub-agents have to guess which `.woff2` file belongs to which family and get it wrong half the time (a real failure mode from prior runs: agents pointed `@font-face` for "ES Build Neutral" at the Inter `.woff2` files and the wordmark rendered in Inter).
+
+**Example:**
+
+````markdown
+#### Fonts
+
+- **Display:** `"ES Build Neutral"` — wordmarks, headlines
+  - 600: `capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2`
+  - 700: `capture/assets/fonts/e8b276476c0ac6fa-s.p.woff2`
+- **Body:** `"Inter"` (variable 100–900, captured ✓) — body, labels, UI
+  - 400: `capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2`
+  - 600: `capture/assets/fonts/1b0b3615811be75b-s.p.woff2`
+- **Mono:** `"JetBrains Mono"` — code, metadata
+  - 400: `capture/assets/fonts/c7d2e9f5a1b3c8d4-s.p.woff2`
+- **Fallback stack:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
+
+**`@font-face` block to paste in every composition** (sub-agents copy this verbatim — do not invent file paths):
+
+```css
+@font-face {
+  font-family: "ES Build Neutral";
+  src: url("capture/assets/fonts/14d7ce3e41dcbb66-s.p.woff2") format("woff2");
+  font-weight: 600;
+  font-display: block;
+}
+@font-face {
+  font-family: "Inter";
+  src: url("capture/assets/fonts/9a8d3f06c4e89f2b-s.p.woff2") format("woff2");
+  font-weight: 400;
+  font-display: block;
+}
+/* + any other family/weight combinations the storyboard's beats need */
+```
+````
+
+The brand uses **size for hierarchy, weight for emphasis**. Display 1: 48px/600, Display 2: 32px/600, Body: 14px/400. (Adjust to the actual brand's hierarchy.)
+
+````
+
+The exact `@font-face` block lets sub-agents copy verbatim instead of constructing one from inference. If a beat needs a weight that isn't in the manifest, flag it explicitly here: e.g., "ES Build Neutral 900 NOT in capture; use ES Build Neutral 700 as substitute, or fall back to Inter 700."
+
+That's the whole typography section. If sub-agents need exact line-heights or letter-spacing, they read `design-styles.json` directly.
+
+---
+
+### `## 3. Component Stylings` (the build-step's spec sheet)
+
+This is the section sub-agents consult most when building beats in Step 5. **Without exact per-component CSS, sub-agents fall back to generic "dark bg + glow + centered text" patterns regardless of brand** — which is why every video starts looking the same. Encode the brand's actual component DNA here.
+
+Target **6-12 distinct components**. Document what the site actually uses; skip categories the brand doesn't have. For each component, name it descriptively ("Stripe Primary Button" not "Button 1") and provide exact CSS-level properties: background, text color, padding, border-radius, border, font size/weight, height, box-shadow, and any hover/active/disabled states.
+
+#### Buttons (always required)
+
+Cover every variant the site uses — typically Primary, Secondary/Ghost, and Icon. **Example:**
+
+```markdown
+#### Primary Button (Stripe Purple)
+
+- **Background:** `#533AFD`
+- **Text color:** `#FFFFFF`
+- **Font:** sohne-var 16px / 400
+- **Padding:** `15.5px 24px 16.5px 24px`
+- **Border radius:** `4px`
+- **Border:** none
+- **Height:** `48px` (with padding)
+- **Box shadow:** none
+- **Hover:** background `#4329E8`, opacity `0.95`
+- **Active:** background `#3720D4`, scale `0.98`
+- **Disabled:** background `#C9C3F0`, cursor `not-allowed`
+
+#### Secondary Button (outline)
+
+- **Background:** `#FFFFFF`
+- **Text color:** `#533AFD`
+- **Border:** `1px solid #533AFD`
+- **Padding / radius / font:** same as Primary
+- **Hover:** background `#F3F0FF`, border `#4329E8`
+
+#### Ghost Button (text-only link)
+
+- **Background:** transparent
+- **Text color:** `#533AFD`
+- **Font:** sohne-var 14px / 400
+- **Padding:** `12px 0`
+- **Hover:** background `rgba(83, 58, 253, 0.08)`, optional underline
+````
+
+#### Cards & Containers (always required if the site uses any)
+
+Document each distinct card type — Standard, Feature Highlight, Glass, Pricing, Testimonial — whatever this brand actually uses. **Example:**
+
+```markdown
+#### Standard Card
+
+- **Background:** `#FFFFFF`
+- **Border:** `1px solid #D4DEE9`
+- **Border radius:** `5px`
+- **Padding:** `32px`
+- **Box shadow:** `0 1px 2px rgba(0, 0, 0, 0.04)` (default), `0 4px 12px rgba(0, 0, 0, 0.08)` (hover)
+- **Hover:** border `#B8CCDB`
+
+#### Feature Highlight Card (gradient backdrop)
+
+- **Background:** linear-gradient(180deg, rgba(83, 58, 253, 0.05) 0%, rgba(255, 97, 24, 0.03) 100%)
+- **Border:** `1px solid #E5EDF5`
+- **Padding:** `36px`
+- **Box shadow:** none
+```
+
+#### Distinctive components (anything else the brand actually shows)
+
+Logo marquees, testimonial carousels, pricing tables, gradient overlays, glassmorphism panels, bento grids, code blocks, terminal UIs, dashboard mockups — name and document anything visually distinctive. Sub-agents will reach for these specs when the storyboard calls for a beat featuring the X.
+
+```markdown
+#### Glass Container (frosted overlay)
+
+- **Background:** `rgba(255, 255, 255, 0.9)`
+- **Border:** `1px solid rgba(255, 255, 255, 0.2)`
+- **Backdrop filter:** `blur(8px)`
+- **Use:** floating chat widgets, modal overlays, hero callouts only — the only place transparent fills appear in the system
+```
+
+**The rule:** if a sub-agent in Step 5 has to invent CSS values for a component this brand actually uses, you under-documented this section. The values should be lookup-able, not guessable.
+
+---
+
+### `## 4. Spacing & Layout`
+
+The brand's rhythm. Three sub-sections, kept tight.
+
+#### Spacing scale
+
+Identify the **base unit** (typically `4px` or `8px`) and the full scale with usage context. **Example:**
+
+```markdown
+**Base unit:** `4px`
+
+| Token | Value   | Used for                                                  |
+| ----- | ------- | --------------------------------------------------------- |
+| xs    | `4px`   | Inline icon gaps, tight badge padding                     |
+| sm    | `8px`   | Button-group gaps, small component padding                |
+| md    | `16px`  | Card padding, form-field gaps, standard component spacing |
+| lg    | `32px`  | Section vertical spacing, large card padding              |
+| xl    | `60px`  | Major section separation                                  |
+| 2xl   | `100px` | Page-level rhythm, hero section padding                   |
+
+Never use odd values (`13px`, `17px`) — the system only uses multiples of 4.
+```
+
+#### Border-radius scale
+
+Every radius the site uses, with what uses it.
+
+```markdown
+- `0px`: Form labels, technical UI markers
+- `4px`: Primary buttons, inputs, small badges
+- `8px`: Standard cards, dropdowns
+- `12px`: Feature cards, larger callouts
+- `40px`: Icon buttons (square pill)
+- `9999px`: Pill-shaped CTAs, status chips
+```
+
+#### Whitespace philosophy (one paragraph)
+
+How does this brand use whitespace — generous and architectural? Tight and information-dense? Section gaps in the 60–100px range, or 20–40px? Document the brand's actual rhythm.
+
+```markdown
+Generous whitespace as confidence. Section gaps are always `60–100px`. Content never touches viewport edges — minimum `40px` horizontal padding on mobile, `80–160px` on desktop. The brand uses negative space as active design, not emptiness.
+```
+
+---
+
+### `## 5. Iteration Guide` (the load-bearing section)
+
+5–10 numbered rules that encode the most important brand decisions. Each rule is a **single actionable sentence stating what to do, with the specific values from this site.** These are the "if in doubt, do this" rules sub-agents consult while composing beats.
+
+**The single most common failure mode is writing generic rules that could apply to any well-designed website.** A rule that doesn't name a specific value, a specific color, or a specific component this brand actually uses is doing nothing.
+
+**Test for any rule you write:** can you swap this brand for a different brand and have the rule still make sense? If yes, it's too generic. If no, ship it.
+
+#### ❌ Generic vs ✅ site-specific
+
+| Generic (delete)                                  | Site-specific (keep)                                                                                                                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Use the primary brand color for CTAs.             | All primary CTAs use Stripe Purple (`#533AFD`). Secondary actions use white background with `#533AFD` border + text. **There is no third button color anywhere in the system.** |
+| Maintain visual hierarchy through color contrast. | Body text is `#000000` on white, `#FFFFFF` on dark. Metadata uses `#64748D` on white only — never on dark. The brand has no mid-gray text on dark backgrounds.                  |
+| Use clear typographic hierarchy.                  | All type is sohne-var. H1 `48px`/300, H2 `32px`/300, body `14px`/400. **Never use weights above 400** — this brand has no bold variant.                                         |
+| Use consistent spacing.                           | Spacing is from a fixed scale: `4, 8, 12, 16, 20, 24, 32, 40, 60` px. Section gaps are always `60–100px`. Card padding is always `32px`. No exceptions.                         |
+| Buttons should have rounded corners.              | Buttons are `40px` tall minimum, `4px` radius, `15.5px 24px` padding. Pill-shape `9999px` radius is reserved for the floating chat trigger only.                                |
+
+#### One worked example (Framer — 5 rules)
+
+```markdown
+### Iteration Guide
+
+1. **All interactive elements use Framer Blue (`#0000EE`)** — links, primary buttons, active states, focus indicators. Secondary uses `#0099FF` for hover. **No other interactive color exists in the system.**
+
+2. **Typography: GT Walsheim Medium for headings, Inter for body.** Hierarchy enforced through size only, never color. H2 `62px`, H5 `85px`, body `14px`, labels `12px`/500. Text defaults to `#000000` on white, `#FFFFFF` on dark.
+
+3. **Spacing is base-4** — every margin / padding / gap is a multiple of `4px`. Section gaps `60–100px`. **Never use odd values like `13px` or `17px`** — the system has no place for them.
+
+4. **Cards: white (`#FFFFFF`), `1px` border `#EFEFEF`, `8px` radius, `16–20px` padding, no shadow by default.** Dark-mode cards swap to `#1A1A1A` background with `#242424` border. Shadow only appears on hover.
+
+5. **Glass containers** use `rgba(255,255,255,0.9)` background, `1px` border `rgba(255,255,255,0.2)`, optional `backdrop-filter: blur(8px)`. **These are the only place transparent fills appear** — everywhere else uses solid color.
+```
+
+If your draft has a rule like "all interactive elements require visible focus states for accessibility" — delete it. Not wrong, just not load-bearing for _this_ brand.
+
+---
+
+## Rules
+
+- Use **exact values** from `capture/extracted/tokens.json`. Cross-reference with screenshots when needed.
+- Name colors and components descriptively — "Stripe Purple" not "Accent 1."
+- When you can't extract exact values, estimate from visual inspection and note it.
+- No "Assets" section — `capture/extracted/asset-descriptions.md` is the asset index.
+- No "Motion" section — the storyboard specifies motion per-beat.
+- No separate "Components" section — Quick Reference is where components live.
+- No "Depth & Elevation" tables — shadow language is implied by the brand's mood (heavy shadows for premium, no shadows for flat/clean); sub-agents pick appropriate values without a table.
+
+---
+
+## Quick User Check (before moving to Step 2)
+
+30-second sanity check before Step 2:
+
+> "Here's what I extracted as [Brand Name]'s visual identity:
+>
+> - **Colors:** [primary], [accent], [2-3 others with roles]
+> - **Fonts:** [headline font], [body font]
+> - **Tone:** [1 sentence on the brand feel]
+>
+> Does this match how you want the video to feel? Any corrections or overrides before I start the storyboard?"
+
+If the user has corrections ("use the blue, not the gray" / "ignore the dark mode" / "we just rebranded, use [these values] instead") — update DESIGN.md now. One minute here saves thirty minutes of rebuilding.
+
+---
+
+## What makes a useful DESIGN.md
+
+A sub-agent reading just your Quick Reference + Iteration Guide should be able to:
+
+1. Pick the right color for any primary action, secondary action, body text, error state
+2. Pick the right font/weight/size for any headline, body, metadata
+3. Know which 2-3 rules they cannot break without losing the brand
+
+That's the test. If they can answer those three questions from a 60–120 line doc, you've nailed it. If they need to read 400 lines of mood-board prose to find a color, you've buried the signal.

package/.agents/skills/website-to-video/references/step-2-brief.md

@@ -0,0 +1,178 @@
+# Step 2: Strategy & Messaging
+
+**First, scan the Table of Contents in [capabilities.md](capabilities.md)** — the 24-row TOC tells you everything HyperFrames can do. You need this to tell users what's possible. Deep-dive specific sections only if a beat needs them.
+
+You've captured the site and you now understand the brand — what the product does, who it's for, what voice it speaks in, what mood it lives in. Before any creative decisions, **align with the user on the story this video must tell.** Captured assets exist as a brand toolkit you'll reach for late in Step 3; they are not what the conversation in this step is about.
+
+**Parse the user's prompt first.** Read what they already told you — video type, style, specific requests, duration. Only ask about things they DIDN'T specify. If they said "product demo, show me the kanban board and chat, moderate pace" — that's most of the brief already. Don't ask "what type of video?" when they literally said "product demo."
+
+Skip questions the user already answered. Ask only what's missing. If the prompt is detailed enough to build from, confirm the direction in one message and move to Step 3. The goal is to fill gaps, not interrogate.
+
+---
+
+## What to Ask
+
+Before asking the user anything, ground yourself in the brand: skim `DESIGN.md` (just written in Step 1) for colors / fonts / voice; read `capture/extracted/asset-descriptions.md` for what visual assets exist; skim `capture/extracted/visible-text.txt` for what the site says about itself. Don't summarize all of it back to the user — that's noise; they captured the site, they know what's there. Use it to draft a tight one-paragraph framing of the brand and proceed to the questions.
+
+Engage the user with the questions below. Use your agent's question/answer UI if available (multi-choice with custom option). If not, ask conversationally.
+
+### Question 1: What's this video for?
+
+Present options based on what makes sense for the captured site:
+
+**Example (Not a required options)**
+
+- **Social ad** (15–20s) — Instagram, TikTok, LinkedIn. Fast, punchy, hook in first 2s.
+- **Product demo** (30–60s) — Walk through key features. Narrated, professional.
+- **Launch teaser** (15–25s) — Build hype for a new feature or product. Dramatic reveal.
+- **Brand reel** (20–45s) — Showcase the brand identity. Visual-forward, minimal narration.
+- **Feature announcement** (15–30s) — Highlight a specific feature or update.
+- Or describe something else.
+
+This determines duration, beat count, narration density, and overall energy.
+
+### Question 2: What style/vibe?
+
+Ask the user to describe what they want — or react to concrete framings that describe motion and energy, not aesthetic presets.
+
+Do NOT present a labeled menu of styles with pre-filled descriptions ("Cinematic = dark + glow + Apple keynote energy"). Those descriptions become the brief even when they don't match the brand. "Cinematic" for a wellness brand should look completely different from "cinematic" for a security tool — but a label with a baked-in description collapses that distinction.
+
+Instead, ask them approachable open-ended questions:
+
+> "A few questions to get the direction right:
+>
+> - **Pace:** Should the video move slowly and let moments breathe, or be fast and punchy? Or somewhere in between?
+> - **Mood:** What atmosphere matches how you want viewers to feel — dark and dramatic, clean and light, energetic and vibrant, or something else?
+> - **Narration:** Should a voice guide viewers through the video, or let the visuals carry it?
+> - **Anything specific?** Any moments, techniques, or references you're drawn to? Or say 'surprise me' and I'll work from what I found in the capture."
+
+Their answers modify the brand-derived baseline you built in Step 1. When the user's words conflict with the brand, don't blindly override — let the brand and their direction converge. If the conflict is sharp (user says "dark cinematic" for a brand whose entire identity is white-and-pastel light), surface it and ask before resolving.
+
+### Question 3: What's the ONE thing this video must communicate?
+
+This is the strategy question. Every effective marketing video has a single core message — the one idea that has to land. Every beat serves that idea, or it doesn't belong. Get the user to articulate this BEFORE talking about visuals, assets, or specific scenes.
+
+Frame it like this:
+
+> "From your site, here's the brand frame I'm working from:
+>
+> - **What the product does:** [one sentence from the site summary — not features, the actual job]
+> - **Audience:** [who it's for, derived from copy and visual tone]
+> - **Brand voice:** [confident / playful / clinical / urgent / premium — what tone the brand speaks in]
+>
+> Before we plan visuals, two questions to anchor the story:
+>
+> 1. **What's the ONE thing this video must communicate?** If a viewer remembers only one sentence after watching, what should it be? (the value prop, a launch announcement, a specific feature claim, a brand feeling, a problem-solution pair, etc.)
+> 2. **What's the narrative shape?** Possible arcs: _Problem → Solution_ (most demos), _Reveal_ (launches, teasers), _Demonstration_ (feature showcase, walkthroughs), _Vibe piece_ (brand reels — feeling over information), _Comparison_ (vs. competitor / before-after). Pick or describe your own.
+>
+> Either give me your own answers, or say 'surprise me' and I'll make the call based on the brand and what you said in Question 1 ([video type])."
+
+Once those answers exist, **then** sketch the composed-beat directions — but ground each one in the message and arc, not in the asset list:
+
+> "Given [the message] and [the arc], here's how I'd shape it:
+>
+> - [Compose-first sketch grounded in the answer to Q1, e.g., "Open with the problem stated as kinetic typography — 'You waste 4 hours a week on context switches.' Cut to a composed kanban board where cards animate from chaos into organization. Close on the brand mark + tagline."]
+> - [Alternative sketch with a different arc, e.g., "Reveal arc: dark canvas → particles converging → product wordmark drawn stroke-by-stroke as the first feature lands. No problem statement — pure announcement energy."]
+> - [If user wants demo: "Three composed UI panels — kanban, AI chat, command palette — each in your palette with the brand logo stamped top-left. Narration walks through each. Closer holds the wordmark."]
+>
+> Brand accents I could layer in: [list 1-3 captured assets that *might* earn a place: the SVG logo for opener/closer, a hero illustration as a depth layer in one scene, a gradient image as an ambient bg wash. Note these are candidates, not assignments — most beats won't need any.]"
+
+**Important:** Lead every direction with **what the beat communicates**, then with **how it's built** (which primitives). The narrow no-go: if your first instinct is "the product-UI screenshot flies in," flip it — compose the UI from divs and CSS instead. That's the slideshow pattern this skill exists to break. For captured logos, illustrations, and hero art, no flip is needed — they're valid primary visuals when the concept calls for them.
+
+The captured assets are a brand toolkit you reach for late in the storyboard, where they serve the concept — never as the starting point of the concept itself.
+
+Present options:
+
+- **I have specific ideas** — let me describe them
+- **Surprise me** — you make the creative calls, I'll review the storyboard
+- **Let me see some options first** — propose 2–3 different creative directions and I'll pick
+
+### Question 4: Narration?
+
+Not every video needs a voiceover. Ask:
+
+- **Yes, with narration** — a voice guides the viewer through the video (most product demos, launch teasers, feature announcements)
+- **No narration, visual-only** — music/SFX only, the visuals tell the story (brand reels, social ads, music-driven pieces)
+- **Minimal narration** — just a hook sentence or tagline, rest is visual (short social ads, teasers)
+
+This decision changes the pipeline:
+
+- **With narration:** Step 3 includes a full script. Step 4 generates TTS, transcribes, maps timestamps to beats.
+- **Without narration:** Step 3 has no script (VO cues in storyboard are empty). Step 4 is skipped — beat durations are planned manually in the storyboard based on rhythm and pacing.
+
+### Question 5 (if applicable): Format?
+
+Only ask if not already specified by the user:
+
+- **Landscape** (1920×1080) — YouTube, LinkedIn, website embeds (default)
+- **Portrait** (1080×1920) — Instagram Stories, TikTok, YouTube Shorts
+- **Square** (1080×1080) — Instagram feed, Twitter/X
+
+---
+
+## How to Handle Responses
+
+### "Surprise me" / minimal direction
+
+When the user gives no creative direction, default to what the brand's visual identity and the video's purpose suggest. The minimum context you need before defaulting: **where the video is going** (social feed / landing page / pitch deck / TV ad) and **who it's for** (developers / consumers / enterprise / general audience). If either is missing, ask once — "where will this run, and who's the audience?" — then proceed.
+
+With that minimum in hand, still write an ambitious storyboard. "Surprise me" means "impress me," not "play it safe." Go bold.
+
+**Autonomous mode propagates — for user-preference gates only.** When the user signals "surprise me" / "decide for me" / "just build it" here at Step 2, that signal kills downstream user-preference 💬 gates: Step 3's storyboard approval, Step 4's TTS provider choice, music yes/no, captions yes/no. Make those creative decisions yourself and present the finished video at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.
+
+**Auto mode does NOT skip quality-verification gates.** These run regardless and must produce evidence in your final summary:
+
+- Asset Audit (Step 3) — view contact sheets, justify USE/SKIP per asset
+- Per-beat HTML evidence block (Step 5)
+- DoD checklist (Step 6) — animation-map, per-warning WCAG verification, audio + motion playback (or explicit "deferred" disclosure)
+- "What I did NOT verify" disclosure (Step 6)
+
+**Test for "preference vs quality gate":** if the answer changes the _content_ of the video (which voice? captions on? beat 3 cinematic or fast?), it's a preference — auto mode decides. If the answer is "did the verification happen?", it's a quality gate — auto mode does NOT apply. Reasoning "auto mode says bias toward action, so I'll skip the contact sheets" misuses auto mode.
+
+### Specific direction
+
+If they say something vague ("make it really cool"), push back gently:
+
+> "I want to make sure I nail what you're imagining. When you say 'cool' — do you mean: dramatic/cinematic(slow reveals and dark atmosphere)? Or high-energy (fast cuts and bold motion)? Or something else entirely?"
+
+### Mixed direction
+
+Parse each component separately. "Minimal but with cinematic transitions and a fast feature section" becomes:
+
+- **Base style:** Minimal (moderate pacing, minimal density, elegant motion)
+- **Transitions override:** Dramatic (shader effects for key moments)
+- **Beats 3–5 override:** Fast pacing, balanced density, energetic motion
+
+Note these per-beat overrides — they go into the storyboard.
+
+### "Let me see options"
+
+Propose 2–3 brief creative directions (3–4 sentences each) with different **narrative arcs** — what story the video tells, not what assets it shows. Each option leads with the message and the arc; visuals are composed scenes that serve them.
+
+> **Option A — Problem → Solution (cinematic, narrated):** Open with the problem stated as kinetic typography over a dark canvas with a single accent glow. Cut to a composed kanban board where chaotic cards animate into organized columns as narration lands the value prop. Closer: brand mark drawn stroke-by-stroke on a shader bloom of the brand gradient. Apple-keynote register. ~25s with full VO.
+>
+> **Option B — Reveal arc (announcement, music-led):** Cold open: particles converging in darkness, no copy. The product wordmark draws itself across the frame as the first beat lands. Three composed feature panels each unveiled by a hard cut — kinetic typography labels, brand color washes, no screenshots. Closes on the mark + tagline + macOS hint. ~15s, music-driven, minimal narration.
+>
+> **Option C — Demonstration (narrated walkthrough):** Three composed UI scenes — kanban from cards-as-divs, AI chat with typewriter narration sync, command palette with character-typed search — each in the brand palette with the captured logo stamped top-left as identity. CSS crossfades between. Narration walks each one. ~35s, full VO.
+
+Each option states: the arc, the primary visuals carrying it (composed or captured — whichever fits the beat), and any brand accents layered on top. **Never** an option whose primary content is a pasted product-UI screenshot — if you find yourself writing one, flip it: name what gets composed instead. Captured SVGs, illustrations, hero art, and brand photography are fine as primary visuals when the concept calls for them.
+
+Let the user pick one or combine elements.
+
+---
+
+## Gate
+
+Lock all of these before moving to Step 3. The first three are the strategic frame Step 3 builds the storyboard from — without them, the storyboard cannot land.
+
+1. **Message** — the ONE thing this video must communicate, in a single sentence. (Required. Step 3 fails without this.)
+2. **Narrative arc** — Problem→Solution / Reveal / Demonstration / Vibe / Comparison / custom. (Required.)
+3. **Audience** — who's watching, where they're watching. (Required.)
+4. **Video type** — social ad / product demo / launch teaser / brand reel / feature announcement / etc. Infer from prompt.
+5. **Duration** — infer from type if not stated (demo: 30-45s, social: 15-20s, teaser: 15-25s).
+6. **Style direction** — pace / mood / specifics — from the user's words, layered onto the brand baseline from Step 1.
+7. **Specific requests** — any scenes/effects/beats they explicitly asked for.
+8. **Narration** — yes / no / minimal.
+9. **Format** — landscape unless specified otherwise.
+
+**Do not ask the user to confirm what they already said.** If the prompt was "make a product demo for huly.io, show the kanban board, dark cinematic feel, full narration" — you already have type (demo), style (dark cinematic), specific requests (kanban board), and narration (full). Still need to derive or ask: the **message** ("the everything app for teams that hate context switches"), the **arc** (Demonstration), and the **audience** (small teams / fast-moving orgs). Proceed to Step 3 only when all 9 are locked.