takomi 2.5.1 → 2.5.5

package/assets/.agent/skills/hyperframes-creative/references/motion-principles.md

@@ -1,150 +1,150 @@
-# Motion Principles
-
-## Contents
-
-- Guardrails
-- What you do not do without being told
-- Visual composition
-- Image motion treatment
-- Load-bearing GSAP rules
-
-## Guardrails
-
-You know these rules but you violate them. Stop.
-
-- **Don't use the same ease on every tween.** You default to `power2.out` on everything. Vary eases like you vary font weights — no more than 2 independent tweens with the same ease in a scene.
-- **Don't use the same speed on everything.** You default to 0.4-0.5s for everything. The slowest scene should be 3× slower than the fastest. Vary duration deliberately.
-- **Don't enter everything from the same direction.** You default to `y: 30, opacity: 0` on every element. Vary: from left, from right, from scale, opacity-only, letter-spacing.
-- **Don't use the same stagger on every scene.** Each scene needs its own rhythm.
-- **Don't use ambient zoom on every scene.** Pick different ambient motion per scene: slow pan, subtle rotation, scale push, color shift, or nothing. Stillness after motion is powerful.
-- **Don't start at t=0.** Offset the first animation 0.1-0.3s. Zero-delay feels like a jump cut.
-
-## What You Don't Do Without Being Told
-
-### Easing is emotion, not technique
-
-The transition is the verb. The easing is the adverb. A slide-in with `expo.out` = confident. With `sine.inOut` = dreamy. With `elastic.out` = playful. Same motion, different meaning. Choose the adverb deliberately.
-
-**Direction rules — these are not optional:**
-
-- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is your default.
-- `.in` for elements leaving. Starts slow, accelerates away. Throws them off.
-- `.inOut` for elements moving between positions.
-
-You get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.
-
-### Speed communicates weight
-
-- Fast (0.15-0.3s) — energy, urgency, confidence
-- Medium (0.3-0.5s) — professional, most content
-- Slow (0.5-0.8s) — gravity, luxury, contemplation
-- Very slow (0.8-2.0s) — cinematic, emotional, atmospheric
-
-### Scene structure: build / breathe / resolve
-
-Every scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.
-
-- **Build (0-30%)** — elements enter, staggered. Don't dump everything at once.
-- **Breathe (30-70%)** — content visible, alive with ONE ambient motion.
-- **Resolve (70-100%)** — exit or decisive end. Exits are faster than entrances.
-
-### Transitions are meaning
-
-- **Crossfade** = "this continues"
-- **Hard cut** = "wake up" / disruption
-- **Slow dissolve** = "drift with me"
-
-You crossfade everything. Use hard cuts for disruption and register shifts.
-
-### Choreography is hierarchy
-
-The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for completion — overlap entries. Total stagger sequence under 500ms regardless of item count.
-
-### Asymmetry
-
-Entrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.
-
-## Visual Composition
-
-You build for the web. Video frames are not pages.
-
-- **Two focal points minimum per scene.** The eye needs somewhere to travel. Never a single text block floating in empty space.
-- **Fill the frame.** Hero text: 60-80% of width. You will try to use web-sized elements. Don't.
-- **Three layers minimum per scene.** Background treatment (glow, oversized faded type, color panel). Foreground content. Accent elements (dividers, labels, data bars).
-- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid #000 reads as "nothing loaded."
-- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.
-- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.
-- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).
-
-## Image Motion Treatment
-
-Never embed a raw flat image. Every image must have motion treatment:
-
-- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
-- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
-- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
-- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
-- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
-
-## Load-Bearing GSAP Rules
-
-Rules below came out of two independent website capture builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author.
-
-- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds.
-
-- **Never stack two transform tweens on the same element.** A common failure: a `y` entrance plus a `scale` Ken Burns on the same `<img>`. The second tween's `immediateRender: true` writes the element's initial state at construction time, overwriting whatever the first tween set — leaving the element invisible or offscreen with no lint warning. A secondary mechanism: `tl.from()` resets to its declared "from" state when the playhead is seeked past the timeline's end, so an element that looked correct in linear playback vanishes in the capture engine's non-linear seek. Fix one of two ways:
-
-  ```html
-  <!-- BAD: two transforms on one element -->
-  <img class="hero" src="..." />
-  <script>
-    tl.from(".hero", { y: 50, opacity: 0, duration: 0.6 }, 0);
-    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // kills the entrance
-  </script>
-
-  <!-- GOOD option A: combine into one tween -->
-  <script>
-    tl.fromTo(
-      ".hero",
-      { y: 50, opacity: 0, scale: 1.0 },
-      { y: 0, opacity: 1, scale: 1.04, duration: beat, ease: "none" },
-      0,
-    );
-  </script>
-
-  <!-- GOOD option B: split across parent + child -->
-  <div class="hero-wrap"><img class="hero" src="..." /></div>
-  <script>
-    tl.from(".hero-wrap", { y: 50, opacity: 0, duration: 0.6 }, 0); // entrance on parent
-    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // Ken Burns on child
-  </script>
-  ```
-
-- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic:
-
-  ```js
-  // BRITTLE: immediateRender interacts badly with scene boundaries
-  tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t);
-
-  // DETERMINISTIC: state is defined at both ends, no immediateRender surprise
-  tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t);
-  ```
-
-- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview:
-
-  ```js
-  // BAD: lives outside the timeline, never renders in capture
-  gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 });
-
-  // GOOD: seekable, deterministic, renders
-  tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);
-  ```
-
-- **Hard-kill every scene boundary, not just captions.** The caption hard-kill rule above generalizes: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation:
-
-  ```js
-  tl.to(el, { opacity: 0, duration: 0.3 }, beatEnd);
-  tl.set(el, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // deterministic kill
-  ```
-
-These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them.
+# Motion Principles
+
+## Contents
+
+- Guardrails
+- What you do not do without being told
+- Visual composition
+- Image motion treatment
+- Load-bearing GSAP rules
+
+## Guardrails
+
+You know these rules but you violate them. Stop.
+
+- **Don't use the same ease on every tween.** You default to `power2.out` on everything. Vary eases like you vary font weights — no more than 2 independent tweens with the same ease in a scene.
+- **Don't use the same speed on everything.** You default to 0.4-0.5s for everything. The slowest scene should be 3× slower than the fastest. Vary duration deliberately.
+- **Don't enter everything from the same direction.** You default to `y: 30, opacity: 0` on every element. Vary: from left, from right, from scale, opacity-only, letter-spacing.
+- **Don't use the same stagger on every scene.** Each scene needs its own rhythm.
+- **Don't use ambient zoom on every scene.** Pick different ambient motion per scene: slow pan, subtle rotation, scale push, color shift, or nothing. Stillness after motion is powerful.
+- **Don't start at t=0.** Offset the first animation 0.1-0.3s. Zero-delay feels like a jump cut.
+
+## What You Don't Do Without Being Told
+
+### Easing is emotion, not technique
+
+The transition is the verb. The easing is the adverb. A slide-in with `expo.out` = confident. With `sine.inOut` = dreamy. With `elastic.out` = playful. Same motion, different meaning. Choose the adverb deliberately.
+
+**Direction rules — these are not optional:**
+
+- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is your default.
+- `.in` for elements leaving. Starts slow, accelerates away. Throws them off.
+- `.inOut` for elements moving between positions.
+
+You get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.
+
+### Speed communicates weight
+
+- Fast (0.15-0.3s) — energy, urgency, confidence
+- Medium (0.3-0.5s) — professional, most content
+- Slow (0.5-0.8s) — gravity, luxury, contemplation
+- Very slow (0.8-2.0s) — cinematic, emotional, atmospheric
+
+### Scene structure: build / breathe / resolve
+
+Every scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.
+
+- **Build (0-30%)** — elements enter, staggered. Don't dump everything at once.
+- **Breathe (30-70%)** — content visible, alive with ONE ambient motion.
+- **Resolve (70-100%)** — exit or decisive end. Exits are faster than entrances.
+
+### Transitions are meaning
+
+- **Crossfade** = "this continues"
+- **Hard cut** = "wake up" / disruption
+- **Slow dissolve** = "drift with me"
+
+You crossfade everything. Use hard cuts for disruption and register shifts.
+
+### Choreography is hierarchy
+
+The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for completion — overlap entries. Total stagger sequence under 500ms regardless of item count.
+
+### Asymmetry
+
+Entrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.
+
+## Visual Composition
+
+You build for the web. Video frames are not pages.
+
+- **Two focal points minimum per scene.** The eye needs somewhere to travel. Never a single text block floating in empty space.
+- **Fill the frame.** Hero text: 60-80% of width. You will try to use web-sized elements. Don't.
+- **Three layers minimum per scene.** Background treatment (glow, oversized faded type, color panel). Foreground content. Accent elements (dividers, labels, data bars).
+- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid #000 reads as "nothing loaded."
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.
+- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.
+- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).
+
+## Image Motion Treatment
+
+Never embed a raw flat image. Every image must have motion treatment:
+
+- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
+- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
+- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
+- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
+- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
+
+## Load-Bearing GSAP Rules
+
+Rules below came out of two independent website capture builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author.
+
+- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds.
+
+- **Never stack two transform tweens on the same element.** A common failure: a `y` entrance plus a `scale` Ken Burns on the same `<img>`. The second tween's `immediateRender: true` writes the element's initial state at construction time, overwriting whatever the first tween set — leaving the element invisible or offscreen with no lint warning. A secondary mechanism: `tl.from()` resets to its declared "from" state when the playhead is seeked past the timeline's end, so an element that looked correct in linear playback vanishes in the capture engine's non-linear seek. Fix one of two ways:
+
+  ```html
+  <!-- BAD: two transforms on one element -->
+  <img class="hero" src="..." />
+  <script>
+    tl.from(".hero", { y: 50, opacity: 0, duration: 0.6 }, 0);
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // kills the entrance
+  </script>
+
+  <!-- GOOD option A: combine into one tween -->
+  <script>
+    tl.fromTo(
+      ".hero",
+      { y: 50, opacity: 0, scale: 1.0 },
+      { y: 0, opacity: 1, scale: 1.04, duration: beat, ease: "none" },
+      0,
+    );
+  </script>
+
+  <!-- GOOD option B: split across parent + child -->
+  <div class="hero-wrap"><img class="hero" src="..." /></div>
+  <script>
+    tl.from(".hero-wrap", { y: 50, opacity: 0, duration: 0.6 }, 0); // entrance on parent
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // Ken Burns on child
+  </script>
+  ```
+
+- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic:
+
+  ```js
+  // BRITTLE: immediateRender interacts badly with scene boundaries
+  tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t);
+
+  // DETERMINISTIC: state is defined at both ends, no immediateRender surprise
+  tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t);
+  ```
+
+- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview:
+
+  ```js
+  // BAD: lives outside the timeline, never renders in capture
+  gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 });
+
+  // GOOD: seekable, deterministic, renders
+  tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);
+  ```
+
+- **Hard-kill every scene boundary, not just captions.** The caption hard-kill rule above generalizes: any element whose visibility changes at a beat boundary needs a deterministic `tl.set()` kill after its fade, because later tweens on the same element (or `immediateRender` from a sibling tween) can resurrect it. Apply to every element with an exit animation:
+
+  ```js
+  tl.to(el, { opacity: 0, duration: 0.3 }, beatEnd);
+  tl.set(el, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // deterministic kill
+  ```
+
+These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them.

package/assets/.agent/skills/hyperframes-creative/references/narration.md

@@ -1,92 +1,92 @@
-# Narration & Script
-
-How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS.
-
-## Pacing
-
-- **2.5 words per second** is natural speaking pace
-- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
-- Leave room for pauses. Silence between sentences is a feature, not dead air
-- The script should feel SHORTER than the video — visual breathing room matters
-
-## Tone
-
-Write like a person, not a brochure:
-
-- Use contractions: "it's", "you'll", "that's", "we've"
-- Vary sentence length — short punchy phrases mixed with longer flowing ones
-- Read it out loud. If it sounds robotic, rewrite it
-- Avoid jargon unless the audience expects it
-
-## Number Pronunciation
-
-Write what you want the voice to say. TTS reads literally.
-
-| In the product | Write in script as                |
-| -------------- | --------------------------------- |
-| 135+           | more than one hundred thirty five |
-| $1.9T          | nearly two trillion dollars       |
-| 99.999%        | ninety nine point nine percent    |
-| 200M+          | over two hundred million          |
-| 10x            | ten times                         |
-| API            | A P I                             |
-| stripe.com     | stripe dot com                    |
-
-The visual can show the exact figure while the voice rounds it.
-
-## Structure
-
-For product videos:
-
-1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.
-2. **Story** — what does the product do? Who uses it? Keep it concrete.
-3. **Proof** — stats, customer names, social proof. Real numbers from the product.
-4. **CTA** — what should the viewer do? "Start building at stripe dot com."
-
-Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.
-
-## The Opening Line
-
-The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.
-
-Patterns that work:
-
-- **A bold claim**: "The financial infrastructure that powers the internet economy."
-- **A question that provokes**: "What if your database could think?"
-- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."
-- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)
-
-If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.
-
-## Example
-
-From a 62-second product launch video (team reference):
-
-```
-Your AI agent already knows how to make videos.
-It just needs the right format.
-
-This is Hyperframes. An open source framework. HTML in, video out.
-
-A div is a keyframe. Data attributes are your timeline.
-CSS is your look. G-Sap is your animation engine.
-
-Anything a browser can render can be a frame in your video.
-
-CSS animations. G-Sap. Lottie. Shaders. Three.js.
-
-Drop in music, sound effects, footage — it all composes together.
-
-No new framework for the agent to learn.
-Just HTML.
-
-The agent writes it. The renderer captures every frame as MP4.
-It's deterministic. Identical outputs, every time.
-
-Give your agent the CLI. Tell it what to make.
-Watch it build.
-
-Hyperframes. Go make something.
-```
-
-Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.
+# Narration & Script
+
+How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS.
+
+## Pacing
+
+- **2.5 words per second** is natural speaking pace
+- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
+- Leave room for pauses. Silence between sentences is a feature, not dead air
+- The script should feel SHORTER than the video — visual breathing room matters
+
+## Tone
+
+Write like a person, not a brochure:
+
+- Use contractions: "it's", "you'll", "that's", "we've"
+- Vary sentence length — short punchy phrases mixed with longer flowing ones
+- Read it out loud. If it sounds robotic, rewrite it
+- Avoid jargon unless the audience expects it
+
+## Number Pronunciation
+
+Write what you want the voice to say. TTS reads literally.
+
+| In the product | Write in script as                |
+| -------------- | --------------------------------- |
+| 135+           | more than one hundred thirty five |
+| $1.9T          | nearly two trillion dollars       |
+| 99.999%        | ninety nine point nine percent    |
+| 200M+          | over two hundred million          |
+| 10x            | ten times                         |
+| API            | A P I                             |
+| stripe.com     | stripe dot com                    |
+
+The visual can show the exact figure while the voice rounds it.
+
+## Structure
+
+For product videos:
+
+1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.
+2. **Story** — what does the product do? Who uses it? Keep it concrete.
+3. **Proof** — stats, customer names, social proof. Real numbers from the product.
+4. **CTA** — what should the viewer do? "Start building at stripe dot com."
+
+Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.
+
+## The Opening Line
+
+The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.
+
+Patterns that work:
+
+- **A bold claim**: "The financial infrastructure that powers the internet economy."
+- **A question that provokes**: "What if your database could think?"
+- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."
+- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)
+
+If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.
+
+## Example
+
+From a 62-second product launch video (team reference):
+
+```
+Your AI agent already knows how to make videos.
+It just needs the right format.
+
+This is Hyperframes. An open source framework. HTML in, video out.
+
+A div is a keyframe. Data attributes are your timeline.
+CSS is your look. G-Sap is your animation engine.
+
+Anything a browser can render can be a frame in your video.
+
+CSS animations. G-Sap. Lottie. Shaders. Three.js.
+
+Drop in music, sound effects, footage — it all composes together.
+
+No new framework for the agent to learn.
+Just HTML.
+
+The agent writes it. The renderer captures every frame as MP4.
+It's deterministic. Identical outputs, every time.
+
+Give your agent the CLI. Tell it what to make.
+Watch it build.
+
+Hyperframes. Go make something.
+```
+
+Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.

package/assets/.agent/skills/hyperframes-creative/references/prompt-expansion.md

@@ -1,68 +1,68 @@
-# Prompt Expansion
-
-Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against the design spec (`frame.md` or `design.md`) and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way.
-
-Runs AFTER design direction is established (Step 1). The expansion consumes the design spec (`frame.md` or `design.md`, if present) and produces output that cites its exact values.
-
-## Prerequisites
-
-Read before generating:
-
-- the design spec — `frame.md` → `design.md` → `DESIGN.md` (read the first that exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
-- `references/beat-direction.md` — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
-- `references/video-composition.md` — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
-- `house-style.md` — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.
-
-If no design spec (`frame.md` or `design.md`) exists yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
-
-## Why always run it
-
-**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly.
-
-Even a detailed 7-scene brief lacks things only the expansion adds:
-
-- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them.
-- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead.
-- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request.
-- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target.
-- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands.
-- **Exact hex values, typography parameters, ease choices** from the design spec — no vagueness left for the scene subagent to guess.
-
-Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive.
-
-The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one.
-
-**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions.
-
-## What to generate
-
-Expand into a full production prompt with these sections:
-
-1. **Title + style block** — cite the design spec's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.
-
-2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. Use `references/beat-direction.md` for rhythm templates by video type.
-
-3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).
-
-4. **Per-scene beats** — for each scene, use the beat-direction format:
-   - **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL?
-   - **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm")
-   - **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md.
-   - **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed.
-   - **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut."
-
-5. **Recurring motifs** — visual threads across scenes from the brand palette.
-
-6. **Negative prompt** — what to avoid, informed by the design spec's constraints if present.
-
-## Output
-
-Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines.
-
-Tell the user:
-
-> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md`
->
-> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed."
-
-Only move to construction after the user approves or says to continue.
+# Prompt Expansion
+
+Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against the design spec (`frame.md` or `design.md`) and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way.
+
+Runs AFTER design direction is established (Step 1). The expansion consumes the design spec (`frame.md` or `design.md`, if present) and produces output that cites its exact values.
+
+## Prerequisites
+
+Read before generating:
+
+- the design spec — `frame.md` → `design.md` → `DESIGN.md` (read the first that exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
+- `references/beat-direction.md` — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
+- `references/video-composition.md` — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
+- `house-style.md` — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.
+
+If no design spec (`frame.md` or `design.md`) exists yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
+
+## Why always run it
+
+**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly.
+
+Even a detailed 7-scene brief lacks things only the expansion adds:
+
+- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them.
+- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead.
+- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request.
+- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target.
+- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands.
+- **Exact hex values, typography parameters, ease choices** from the design spec — no vagueness left for the scene subagent to guess.
+
+Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive.
+
+The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one.
+
+**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions.
+
+## What to generate
+
+Expand into a full production prompt with these sections:
+
+1. **Title + style block** — cite the design spec's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.
+
+2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. Use `references/beat-direction.md` for rhythm templates by video type.
+
+3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).
+
+4. **Per-scene beats** — for each scene, use the beat-direction format:
+   - **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL?
+   - **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm")
+   - **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md.
+   - **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed.
+   - **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut."
+
+5. **Recurring motifs** — visual threads across scenes from the brand palette.
+
+6. **Negative prompt** — what to avoid, informed by the design spec's constraints if present.
+
+## Output
+
+Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines.
+
+Tell the user:
+
+> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md`
+>
+> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed."
+
+Only move to construction after the user approves or says to continue.