feat(skill): website-to-hyperframes — concept-first authoring + per-beat read protocol

skills/website-to-hyperframes/SKILL.md

@@ -14,79 +14,80 @@ Users say things like:
 - "Turn this website into a 15-second social ad for Instagram"
 - "Create a 30-second product tour from https://..."
 
-The workflow has 7 steps. Each produces an artifact that gates the next.
+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"), every 💬 gate is skipped; see step-2-brief.md for how that propagates.
 
 ---
 
-## Step 1: Capture & Understand
+## Step 0: Capture & Understand the Brand
 
-**Read:** [references/step-1-capture.md](references/step-1-capture.md)
+**Read:** [references/step-0-capture.md](references/step-0-capture.md)
 
-Run the capture, read the extracted data, and build a working summary using the write-down-and-forget method.
+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.
 
-**Gate:** Print your site summary (name, top colors, fonts, key assets, one-sentence vibe).
+**Gate:** Site summary printed — strategy-first (what the product does, who it's for, brand voice) before the asset / color / font inventory.
 
 ---
 
-## Step 2: Write DESIGN.md
+## Step 1: Brand Identity
 
-**Read:** [references/step-2-design.md](references/step-2-design.md)
+**Read:** [references/step-1-design.md](references/step-1-design.md)
 
-Write a simple brand reference for the captured website. 6 sections, ~90 lines. This is a cheat sheet, not the creative plan — that comes in Step 4.
+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.
 
-**Gate:** `DESIGN.md` exists in the project directory.
+**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 3: Write SCRIPT
+## Step 2: Strategy & Messaging
 
-**Read:** [references/step-3-script.md](references/step-3-script.md)
+**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)
 
-Write the narration script. The story backbone. Scene durations come from the narration, not from guessing.
+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:** `SCRIPT.md` exists in the project directory.
+**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 4: Write STORYBOARD
+## Step 3: Storyboard + Script 💬
 
-**Read:** [references/step-4-storyboard.md](references/step-4-storyboard.md)
+**Read:** [references/step-3-storyboard.md](references/step-3-storyboard.md)
 
-Write per-beat creative direction: mood, camera, animations, transitions, assets, depth layers, SFX. This is the creative north star — the document the engineer follows to build each composition.
+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` exists with beat-by-beat direction and an asset audit table.
+**Gate:** `STORYBOARD.md` + `SCRIPT.md` exist AND the user has approved the plan.
 
 ---
 
-## Step 5: Generate VO + Map Timing
+## Step 4: VO, Timing + Captions 💬
 
-**Read:** [references/step-5-vo.md](references/step-5-vo.md)
+**Read:** [references/step-4-vo.md](references/step-4-vo.md)
 
-Generate TTS audio, transcribe for word-level timestamps, and map timestamps to beats. Update STORYBOARD.md with real durations.
+If Step 2 said no narration — ask about background music, then skip to Step 5. Otherwise: ask the user which TTS provider (HeyGen TTS, ElevenLabs, or Kokoro), generate audio, transcribe, map timestamps to beats. Then ask about captions.
 
-**Gate:** `narration.wav` (or .mp3) + `transcript.json` exist. Beat timings in STORYBOARD.md updated.
+**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 6: Build Compositions
+## Step 5: Build Compositions
 
 **Read:** The `hyperframes` skill (load it — every rule matters)
-**Read:** [references/step-6-build.md](references/step-6-build.md)
+**Read:** [references/step-5-build.md](references/step-5-build.md)
 
-Build each composition following the storyboard. After each one: self-review for layout, asset placement, and animation quality.
+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 composition has been self-reviewed. No overlapping elements, no misplaced assets, no static images without motion.
+**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 7: Validate & Deliver
+## Step 6: Validate & Deliver
+
+**Read:** [references/step-6-validate.md](references/step-6-validate.md)
 
-**Read:** [references/step-7-validate.md](references/step-7-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.
 
-Lint, validate, snapshot, preview. Deliver the localhost Studio project URL
-(`http://localhost:<port>/#project/<project-name>`) to the user first — only
-render to MP4 on explicit request. Do not treat `index.html` as the project
-handoff link; it is source-code context only.
+**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.
 
@@ -96,13 +97,17 @@ handoff link; it is source-code context only.
 
 ### Video Types
 
-| Type                  | Duration | Beats | Narration              |
-| --------------------- | -------- | ----- | ---------------------- |
-| Social ad (IG/TikTok) | 10-15s   | 3-4   | Optional hook sentence |
-| Product demo          | 30-60s   | 5-8   | Full narration         |
-| Feature announcement  | 15-30s   | 3-5   | Full narration         |
-| Brand reel            | 20-45s   | 4-6   | Optional, music focus  |
-| Launch teaser         | 10-20s   | 2-4   | Minimal, high energy   |
+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
 
@@ -112,13 +117,15 @@ handoff link; it is source-code context only.
 
 ### Reference Files
 
-| File                                                     | When to read                                                                                                                                                                   |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| [step-1-capture.md](references/step-1-capture.md)        | Step 1 — reading captured data                                                                                                                                                 |
-| [step-2-design.md](references/step-2-design.md)          | Step 2 — writing DESIGN.md                                                                                                                                                     |
-| [step-3-script.md](references/step-3-script.md)          | Step 3 — writing the narration script                                                                                                                                          |
-| [step-4-storyboard.md](references/step-4-storyboard.md)  | Step 4 — per-beat creative direction                                                                                                                                           |
-| [step-5-vo.md](references/step-5-vo.md)                  | Step 5 — TTS, transcription, timing                                                                                                                                            |
-| [step-6-build.md](references/step-6-build.md)            | Step 6 — building compositions with self-review                                                                                                                                |
-| [step-7-validate.md](references/step-7-validate.md)      | Step 7 — lint, validate, snapshot, preview                                                                                                                                     |
-| [techniques.md](../hyperframes/references/techniques.md) | Steps 4 & 6 — 11 visual techniques with code patterns (SVG drawing, Canvas 2D, 3D, typography, Lottie, video, typing, variable fonts, MotionPath, transitions, audio-reactive) |
+| 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 (6 sections, 250-350 lines)                                                                         |
+| [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)                                                    |

skills/website-to-hyperframes/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.

skills/website-to-hyperframes/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."
+  }
+}