dsh-hyperframes 0.2.0 → 0.3.0

package/skills/hyperframes/SKILL.md

@@ -1,366 +1,127 @@
 ---
 name: hyperframes
-description: "HyperFrames by HeyGen: HTML is the source of truth for video. Author video compositions with HTML + CSS + GSAP (data-* timing attributes, GSAP timelines, CSS appearance). Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). For CLI commands see the hyperframes-cli skill; registry blocks see hyperframes-registry; website-to-video see website-to-hyperframes; GSAP API reference see gsap. 中文：用 HyperFrames（HTML 写视频）制作视频、字幕、配音、音频响应动画、转场时使用。"
-compatibility: Requires Node.js >= 22 and FFmpeg on PATH; rendering runs through the `npx hyperframes` CLI.
-allowed-tools: Bash
+description: >
+  Mandatory entry point: read this first for any request to make, create, edit, animate, or render a
+  video, animation, or motion graphic, including a promo, explainer, captioned clip, title card,
+  overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also
+  use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames
+  project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing
+  footage, or music. It resumes project state, captures intent when applicable, selects and installs
+  the owning workflow, and routes domain capabilities. HyperFrames is the default output framework
+  unless the user explicitly chooses another framework for the deliverable or asks only to record a
+  browser session.
 ---
 
-# HyperFrames
+# HyperFrames entry point
 
-HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.
+HyperFrames **renders video from HTML** — a composition is an HTML file whose DOM declares timing with `data-*` attributes, whose animation runtime is seekable, and whose media playback is owned by the framework. The full authoring contract lives in `/hyperframes-core`; read it before writing composition HTML.
 
-## Approach
+## 1. Start from project state
 
-Before writing HTML, think at a high level:
+Apply the first matching row; do not evaluate lower state rows:
 
-1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats.
-2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions).
-3. **Timing** — which clips drive the duration, where do transitions land, what's the pacing.
-4. **Layout** — build the end-state first. See "Layout Before Animation" below.
-5. **Animate** — then add motion using the rules below.
+| State                                                                                                                         | Action                                                                                                                                                                                                      |
+| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Explicit port of existing Remotion source to HyperFrames                                                                      | Read `references/routes/remotion-to-hyperframes.md`, then route directly to that workflow. Skip the intent layer.                                                                                           |
+| Specific operation on an existing HyperFrames project: inspect, diagnose, validate, preview, render, publish, or batch-render | Perform only that operation. Skip intent and workflow routing; load `/hyperframes-cli` and any required domain skills.                                                                                      |
+| Specific edit to an existing project                                                                                          | Make the edit. Do not run the intent layer.                                                                                                                                                                 |
+| `BRIEF.md` exists                                                                                                             | Read `workflow` and `flow`. Execute that workflow; `flow: companion` always executes in `/general-video`. Ask no brief questions.                                                                           |
+| No brief, but `hyperframes.json` or `STORYBOARD.md` exists                                                                    | Resume from project files and recorded preferences. Infer the owning workflow from existing artifacts. If it cannot be determined uniquely, ask one routing-only question; do not run the intent interview. |
+| Fresh creation                                                                                                                | Run the intent layer — `references/intent-interview.md` — then route once using § 2's table.                                                                                                                |
 
-For small edits (fix a color, adjust timing, add one element), skip straight to the rules.
+If a fresh request does not identify the subject or input, ask what the video is about before routing. Check preferences and recipes before asking anything (`references/intent-interview.md`, step 1). A `figma.com` input or a named recipe changes intake, not routing — the interview's "Adapt orthogonal inputs" section handles both.
 
-### Visual Identity Gate
+### Keep the project's CLI current
 
-<HARD-GATE>
-Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors.
-
-Check in this order:
-
-1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
-2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.)
-3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns).
-4. **None of the above?** → Ask 3 questions before writing any HTML:
-   - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm)
-   - Light or dark canvas?
-   - Any specific brand colors, fonts, or visual references?
-     Then generate a minimal DESIGN.md from the answers.
-
-Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step.
-</HARD-GATE>
-
-For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like.
-
-## Layout Before Animation
-
-Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet.
-
-**Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion.
-
-### The process
-
-1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build.
-2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only.
-3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there.
-4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position.
-
-### Example
-
-```css
-/* scene-content fills the scene, padding positions content */
-.scene-content {
-  display: flex;
-  flex-direction: column;
-  justify-content: center;
-  width: 100%;
-  height: 100%;
-  padding: 120px 160px;
-  gap: 24px;
-  box-sizing: border-box;
-}
-.title {
-  font-size: 120px;
-}
-.subtitle {
-  font-size: 42px;
-}
-/* Container fills any scene size (1920x1080, 1080x1920, etc).
-   Padding positions content. Flex + gap handles spacing. */
-```
-
-**WRONG — hardcoded dimensions and absolute positioning:**
-
-```css
-.scene-content {
-  position: absolute;
-  top: 200px;
-  left: 160px;
-  width: 1920px;
-  height: 1080px;
-  display: flex; /* ... */
-}
-```
-
-```js
-// Step 3: Animate INTO those positions
-tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
-tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
-tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
-
-// Step 4: Animate OUT from those positions
-tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
-tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
-tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
-```
-
-### When elements share space across time
-
-If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error.
-
-### What counts as intentional overlap
-
-Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame.
-
-## Data Attributes
-
-### All Clips
-
-| Attribute          | Required                          | Values                                                 |
-| ------------------ | --------------------------------- | ------------------------------------------------------ |
-| `id`               | Yes                               | Unique identifier                                      |
-| `data-start`       | Yes                               | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) |
-| `data-duration`    | Required for img/div/compositions | Seconds. Video/audio defaults to media duration.       |
-| `data-track-index` | Yes                               | Integer. Same-track clips cannot overlap.              |
-| `data-media-start` | No                                | Trim offset into source (seconds)                      |
-| `data-volume`      | No                                | 0-1 (default 1)                                        |
-
-`data-track-index` does **not** affect visual layering — use CSS `z-index`.
-
-### Composition Clips
-
-| Attribute                    | Required | Values                                       |
-| ---------------------------- | -------- | -------------------------------------------- |
-| `data-composition-id`        | Yes      | Unique composition ID                        |
-| `data-start`                 | Yes      | Start time (root composition: use `"0"`)     |
-| `data-duration`              | Yes      | Takes precedence over GSAP timeline duration |
-| `data-width` / `data-height` | Yes      | Pixel dimensions (1920x1080 or 1080x1920)    |
-| `data-composition-src`       | No       | Path to external HTML file                   |
-
-## Composition Structure
-
-Sub-compositions loaded via `data-composition-src` use a `<template>` wrapper. **Standalone compositions (the main index.html) do NOT use `<template>`** — they put the `data-composition-id` div directly in `<body>`. Using `<template>` on a standalone file hides all content from the browser and breaks rendering.
-
-Sub-composition structure:
-
-```html
-<template id="my-comp-template">
-  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
-    <!-- content -->
-    <style>
-      [data-composition-id="my-comp"] {
-        /* scoped styles */
-      }
-    </style>
-    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
-    <script>
-      window.__timelines = window.__timelines || {};
-      const tl = gsap.timeline({ paused: true });
-      // tweens...
-      window.__timelines["my-comp"] = tl;
-    </script>
-  </div>
-</template>
-```
-
-Load in root: `<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`
-
-## Video and Audio
-
-Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
-
-```html
-<video
-  id="el-v"
-  data-start="0"
-  data-duration="30"
-  data-track-index="0"
-  src="video.mp4"
-  muted
-  playsinline
-></video>
-<audio
-  id="el-a"
-  data-start="0"
-  data-duration="30"
-  data-track-index="2"
-  src="video.mp4"
-  data-volume="1"
-></audio>
-```
-
-## Timeline Contract
-
-- All timelines start `{ paused: true }` — the player controls playback
-- Register every timeline: `window.__timelines["<composition-id>"] = tl`
-- Framework auto-nests sub-timelines — do NOT manually add them
-- Duration comes from `data-duration`, not from GSAP timeline length
-- Never create empty tweens to set duration
-
-## Rules (Non-Negotiable)
-
-**Deterministic:** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG if you need pseudo-random values (e.g. mulberry32).
-
-**GSAP:** Only animate visual properties (`opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms). Do NOT animate `visibility`, `display`, or call `video.play()`/`audio.play()`.
-
-**Animation conflicts:** Never animate the same property on the same element from multiple timelines simultaneously.
-
-**No `repeat: -1`:** Infinite-repeat timelines break the capture engine. Calculate the exact repeat count from composition duration: `repeat: Math.ceil(duration / cycleDuration) - 1`.
-
-**Synchronous timeline construction:** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler, so they're available immediately — no need to wait for font loading.
-
-**Never do:**
-
-1. Forget `window.__timelines` registration
-2. Use video for audio — always muted video + separate `<audio>`
-3. Nest video inside a timed div — use a non-timed wrapper
-4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`)
-5. Animate video element dimensions — animate a wrapper div
-6. Call play/pause/seek on media — framework owns playback
-7. Create a top-level container without `data-composition-id`
-8. Use `repeat: -1` on any timeline or tween — always finite repeats
-9. Build timelines asynchronously (inside `async`, `setTimeout`, `Promise`)
-10. Use `gsap.set()` on clip elements from later scenes — they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start` time instead.
-11. Use `<br>` in content text — forced line breaks don't account for actual rendered font width. Text that wraps naturally + a `<br>` produces an extra unwanted break, causing overlap. Let text wrap via `max-width` instead. Exception: short display titles where each word is deliberately on its own line (e.g., "THE\nIMMORTAL\nGAME" at 130px).
-
-## Scene Transitions (Non-Negotiable)
-
-Every multi-scene composition MUST follow ALL of these rules. Violating any one of them is a broken composition.
-
-1. **ALWAYS use transitions between scenes.** No jump cuts. No exceptions.
-2. **ALWAYS use entrance animations on every scene.** Every element animates IN via `gsap.from()`. No element may appear fully-formed. If a scene has 5 elements, it needs 5 entrance tweens.
-3. **NEVER use exit animations** except on the final scene. This means: NO `gsap.to()` that animates opacity to 0, y offscreen, scale to 0, or any other "out" animation before a transition fires. The transition IS the exit. The outgoing scene's content MUST be fully visible at the moment the transition starts.
-4. **Final scene only:** The last scene may fade elements out (e.g., fade to black). This is the ONLY scene where `gsap.to(..., { opacity: 0 })` is allowed.
-
-**WRONG — exit animation before transition:**
-
-```js
-// BANNED — this empties the scene before the transition can use it
-tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
-tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
-// transition fires on empty frame
-```
-
-**RIGHT — entrance only, transition handles exit:**
-
-```js
-// Scene 1 entrance animations
-tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
-tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
-// NO exit tweens — transition at 7.2s handles the scene change
-// Scene 2 entrance animations
-tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
-```
-
-## Animation Guardrails
-
-- Offset first animation 0.1-0.3s (not t=0)
-- Vary eases across entrance tweens — use at least 3 different eases per scene
-- Don't repeat an entrance pattern within a scene
-- Avoid full-screen linear gradients on dark backgrounds (H.264 banding — use radial or solid + localized glow)
-- 60px+ headlines, 20px+ body, 16px+ data labels for rendered video
-- `font-variant-numeric: tabular-nums` on number columns
-
-When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults.
-
-## Typography and Assets
-
-- **Fonts:** Just write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. If a font isn't supported, the compiler warns.
-- Add `crossorigin="anonymous"` to external media
-- For dynamic text overflow, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`
-- All files live at the project root alongside `index.html`; sub-compositions use `../`
-
-## Editing Existing Compositions
-
-- Read the full composition first — match existing fonts, colors, animation patterns
-- Only change what was requested
-- Preserve timing of unrelated clips
-
-## Output Checklist
-
-- [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass
-- [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked
-- [ ] Contrast warnings addressed (see Quality Checks below)
-- [ ] Layout issues addressed (see Quality Checks below)
-- [ ] Animation choreography verified (see Quality Checks below)
-
-## Quality Checks
-
-### Visual Inspect
-
-`hyperframes inspect` runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after `lint` and `validate`:
+A scaffolded project pins `hyperframes@<version>` in its `package.json` scripts so renders stay reproducible; the pin never advances on its own, and a pinned run of an older CLI prints no warning about it. When resuming a project whose scripts carry a pin, probe once before the first render-affecting command:
 
 ```bash
-npx hyperframes inspect
-npx hyperframes inspect --json
+npx hyperframes@latest upgrade --project . --check
 ```
 
-Failures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real `max-width` so text wraps inside the container, or using `window.__hyperframes.fitTextFontSize(...)` for dynamic copy.
+The probe is read-only and reports the pin against the latest release; keep the explicit `.` — on older CLI releases a bare `--project` followed by another flag consumes that flag as its directory value. When it reports the project behind — or any CLI output already shows it (the stderr notice `This project pins hyperframes@… (latest …)`, or `_meta.updateAvailable: true` in a `--json` result from a pinned script) — apply with `npx hyperframes@latest upgrade --project .`, then verify with `npx hyperframes check`. A passing check confirms the project's compositions still validate on the new version — not that rendered output is frame-identical to the old pin — so a successful bump is never silent: name the old and new version in the run's summary. A project with no composition yet needs no verification. If the check fails, revert the `package.json` change, continue on the pinned version, and report which version the project stays on and why. Act on the signal rather than relaying it to the user; never leave a bumped pin unverified.
 
-Use `--samples 15` for dense videos and `--at 1.5,4,7.25` for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
+## 2. Route fresh creation
 
-`hyperframes layout` is the compatibility alias for the same check.
+Use the first matching row. Match the requested **deliverable**, not a word or file type mentioned in passing.
 
-### Contrast
+| Priority | Request                                                                                                            | Workflow                   |
+| -------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| 1        | Explicitly port an existing Remotion source                                                                        | `/remotion-to-hyperframes` |
+| 2        | Author a presentation, pitch deck, or navigable interactive deck                                                   | `/slideshow`               |
+| 3        | Add plain captions or subtitles to existing talking-head footage without changing it                               | `/embedded-captions`       |
+| 4        | Add designed graphic overlays to existing talking-head, interview, or podcast footage without changing the footage | `/talking-head-recut`      |
+| 5        | Build a beat-synced video from a music track, with no narration or website capture                                 | `/music-to-video`          |
+| 6        | Create an explicitly short, unnarrated, motion-first unit, typically under 10s                                     | `/motion-graphics`         |
+| 7        | Explain a GitHub pull request or code change from a PR reference                                                   | `/pr-to-video`             |
+| 8        | Market or showcase a website, product site, app, or company from a URL or site-specific brief                      | `/product-launch-video`    |
+| 9        | Explain a topic, article, or notes with invented visuals and no product or site capture                            | `/faceless-explainer`      |
+| 10       | Any other custom video or composition                                                                              | `/general-video`           |
 
-`hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings:
+Before finalizing the route, read `references/routes/<workflow>.md` — one small file per route: the canonical input/output/trigger contract (available before lazy-installed workflow skills are present) plus that route's interview entry. If the candidate does not satisfy its contract, continue routing instead of forcing the match. Read only the matched route's file.
 
-```
-⚠ WCAG AA contrast warnings (3):
-  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)
-```
+### Resolve common ambiguities
 
-If warnings appear:
+- A short animated title, logo sting, stat hit, chart hit, map hit, or standalone lower-third is `/motion-graphics` when it is unnarrated and motion is the message. A static title card, narrated sequence, longer montage, or custom loop is `/general-video`.
+- An explicitly short motion graphic may use a URL, tweet, article, or screenshot as source material. A generic "make a video from this site" request is `/product-launch-video`.
+- Existing footage with captions routes to `/embedded-captions`; footage with designed information cards routes to `/talking-head-recut`. Retiming, reordering, recoloring, reframing, or remixing footage is a custom edit and falls through to `/general-video`.
+- A music file selects `/music-to-video` only when its beat grid drives the piece. Music used as a bed does not override the subject-matched route.
+- "I want a storyboard" changes the review process, not the workflow. With no other routing signal, use `/general-video`. A confirmed sketched board may itself be the requested deliverable; the review loop defines that stop point.
+- Specialized narrative workflows support up to about 3 minutes and are strongest around 30–90s. Route a clearly longer piece to `/general-video`. Length never overrides an explicit port, deck, caption, overlay, or music-driven deliverable.
 
-- On dark backgrounds: brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text, 24px+ or 19px+ bold)
-- On light backgrounds: darken it
-- Stay within the palette family — don't invent a new color, adjust the existing one
-- Re-run `hyperframes validate` until clean
+## 3. Route once, then leave
 
-Use `--no-contrast` to skip if iterating rapidly and you'll check later.
+For fresh creation the intent layer (`references/intent-interview.md`) runs the full conversation — memory, triage, pitch round, must-haves, run-shape, hand-off — and **ends by writing `BRIEF.md`. The brief is the only routing artifact the workflow reads**; nothing later re-opens this skill or the interview. Answer every later "what did the route require?" from `BRIEF.md`.
 
-### Animation Map
+## 4. Install and enter the workflow
 
-After authoring animations, run the animation map to verify choreography:
+Before reading the selected workflow, install or refresh it and the core domain skills:
 
 ```bash
-node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
-  --out <composition-dir>/.hyperframes/anim-map
+npx hyperframes skills update <workflow-name>
 ```
 
-Outputs a single `animation-map.json` with:
-
-- **Per-tween summaries**: `"#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"`
-- **ASCII timeline**: Gantt chart of all tweens across the composition duration
-- **Stagger detection**: reports actual intervals (`"3 elements stagger at 120ms"`)
-- **Dead zones**: periods over 1s with no animation — intentional hold or missing entrance?
-- **Element lifecycles**: first/last animation time, final visibility
-- **Scene snapshots**: visible element state at 5 key timestamps
-- **Flags**: `offscreen`, `collision`, `invisible`, `paced-fast` (under 0.2s), `paced-slow` (over 2s)
-
-Read the JSON. Scan summaries for anything unexpected. Check every flag — fix or justify. Verify the timeline shows the intended choreography rhythm. Re-run after fixes.
-
-Skip on small edits (fixing a color, adjusting one duration). Run on new compositions and significant animation changes.
-
----
-
-## References (loaded on demand)
-
-- **[references/captions.md](references/captions.md)** — Captions, subtitles, lyrics, karaoke synced to audio. Tone-adaptive style detection, per-word styling, text overflow prevention, caption exit guarantees, word grouping. Read when adding any text synced to audio timing.
-- **[references/tts.md](references/tts.md)** — Text-to-speech with Kokoro-82M. Voice selection, speed tuning, TTS+captions workflow. Read when generating narration or voiceover.
-- **[references/audio-reactive.md](references/audio-reactive.md)** — Audio-reactive animation: map frequency bands and amplitude to GSAP properties. Read when visuals should respond to music, voice, or sound.
-- **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text.
-- **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text.
-- **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations.
-- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md.
-- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified.
-- **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns.
-- **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns.
-- **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting.
-- **[references/dynamic-techniques.md](references/dynamic-techniques.md)** — Dynamic caption animation techniques (karaoke, clip-path, slam, scatter, elastic, 3D).
-
-- **[references/transitions.md](references/transitions.md)** — Scene transitions: crossfades, wipes, reveals, shader transitions. Energy/mood selection, CSS vs WebGL guidance. **Always read for multi-scene compositions** — scenes without transitions feel like jump cuts.
-  - [transitions/catalog.md](references/transitions/catalog.md) — Hard rules, scene template, and routing to per-type implementation code.
-  - Shader transitions are in `@hyperframes/shader-transitions` (`packages/shader-transitions/`) — read package source, not skill files.
-
-GSAP patterns and effects are in the `/gsap` skill.
+Use the bare name without `/`. If the command fails, surface the error; do not reconstruct the workflow from memory. Everything else about installation — the core-vs-lazy split, what `init` refreshes, diagnosis, CI opt-out, and the no-CLI fallback — lives in `references/skill-lifecycle.md`.
+
+## 5. Load domain skills on demand
+
+| Need                                                                                                                | Skill                    |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| Composition structure, timing attributes, tracks, variables, determinism                                            | `/hyperframes-core`      |
+| Motion rules, scene blueprints, transitions, runtime adapters                                                       | `/hyperframes-animation` |
+| Seek-safe GSAP, CSS, Anime.js, WAAPI, FLIP, paths, masks, SVG, 3D keyframes, or `hyperframes keyframes` diagnostics | `/hyperframes-keyframes` |
+| Design specs, concept, palette, typography, narration, beat planning                                                | `/hyperframes-creative`  |
+| Images, icons, logos, audio, captions, grades, LUTs, reusable media                                                 | `/media-use`             |
+| Voiceover carve, audio effect chains, automation envelopes, or one chain/fader across several tracks (submix bus)   | `/hyperframes-audio`     |
+| Init, lint, check, snapshots, compare, batch render, Studio, render, publish, or diagnostics                        | `/hyperframes-cli`       |
+| Registry blocks and components                                                                                      | `/hyperframes-registry`  |
+| Figma assets, tokens, components, or storyboard frames as reconstructed motion                                      | `/figma`                 |
+
+Creator edit phrases are cross-domain requests. Load every skill named in the matching row:
+
+| Creator request                                                                                                | Required domains                                                                                                                                                                  |
+| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| “cut this footage”, hard cut, trim, splice, reorder, or use a source range                                     | `/general-video` + `/hyperframes-core`; core owns `data-start`, `data-duration`, `data-media-start`, and track layout.                                                            |
+| zoom in here, punch-in / punch-out, smooth multi-state zoom or reframe, Ken Burns, or camera move              | `/general-video` + `/hyperframes-core` + `/hyperframes-keyframes`; animate the inner visual/crop wrapper, not the timed clip.                                                     |
+| match cut or whip pan camera transition                                                                        | `/general-video` + `/hyperframes-animation` + `/hyperframes-keyframes` + `/hyperframes-registry`; search/install a transition primitive before hand-authoring.                    |
+| fade, crossfade, track gain/volume, automation, duck/carve, audio effects, or one effect across several tracks | `/general-video` + `/hyperframes-core` + `/hyperframes-audio`; core places clips, audio mixes placed tracks — including a submix bus over a group of them.                        |
+| picture and sound edits that combine cuts with camera motion or mixing                                         | `/general-video` + `/hyperframes-core` + `/hyperframes-keyframes` when there is visual motion + `/hyperframes-audio` when sound is faded, mixed, ducked, automated, or processed. |
+| source or generate media, or preprocess an unsupported speed ramp/mid-source freeze                            | `/media-use`; sourcing/generation/preprocessing only, never placed-track mixing.                                                                                                  |
+
+Constant `data-playback-rate` is render-safe for picture and pitch-preserved
+sound. It does not make source speed ramps keyframeable; preprocess ramps.
+For copyable edit contracts, load `/hyperframes-core` → `references/creator-editing-recipes.md`.
+
+Broad feedback about how photographic media looks or behaves also routes to
+`/media-use`, even when the user never says “color grading” or “effect”: fix
+dark/flat/boring footage, stylize a clip, hide a face, or improve a media
+reveal. Read `../media-use/references/media-treatments.md` before editing a
+treatment; it governs how footage is treated, never whether media may be used.
+Do not substitute a generic LUT, CSS filter/overlay, or opacity tween for an
+existing canonical treatment primitive. Keep text/layout/motion-only edits in
+their owning domain.
+During a build with important photographic media, include one grounded
+media-polish scan in the final quality pass; leaving suitable media unchanged is
+a valid result.
+
+Domain skills never take ownership of the end-to-end deliverable. Load only what the active workflow needs.

package/skills/hyperframes/references/capability-menu.md

@@ -0,0 +1,47 @@
+# Capability menu — what HyperFrames can bring to a video
+
+One list, three readers. The **pitch round** (`pitch-round.md`) speaks it before anyone reads it as a menu: each pitch names the capability or two its concept rides, phrased from the middle column — the rows experienced inside concepts, which is how most users first learn what they're allowed to want. The **intent layer** (`/hyperframes` → `references/intent-interview.md`, step 7) recommends from it — one or two rows the confirmed concept specifically calls for and the chosen pitch didn't already name, with the route-filtered slice shown when the user asks what else is possible. **`/general-video` in companion mode** uses the same list as its execution map — as its **trigger list**: each row's plain-language line is also the moment to offer it, when the conversation touches what the row does — and as each pass's **upgrade channel**: a plan, sketch, or build checkpoint may carry one or two traced offers pointed at material the user is looking at.
+
+**Borrowing rule.** Capabilities marked with a home workflow live in that workflow's skill directory, and workflow skills install lazily. Before reaching across, run `npx hyperframes skills update <that-workflow>` with the bare name. Resolve the installed skill directory, invoke its script by absolute path, and pass the project root explicitly when the script accepts one. Keep the working directory at the project root. Never assume a sibling-relative path such as `../media-use` or `../music-to-video`; the project may live anywhere.
+
+Each row's last column reads **home → entry → what you get**: the owning skill, the exact doc or command to start from, and the artifact that comes back.
+
+| Capability                                                                                                                                             | Say it to the user as…                                                                                        | Home → entry → what you get                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Design spec (`frame.md`)** — one file that locks palette, type, and layout feel; every frame obeys it (the video-first sibling of a web `design.md`) | "a design system for the video — colors and typography stay consistent"                                       | `/hyperframes-creative` → `references/design-spec.md` (what a spec is + resolution order); presets: `frame-presets/<name>/` (always installed — browsing needs no borrow); applying machinery `build-frame.mjs` (home: `/faceless-explainer`, `/product-launch-video`) → `frame.md` at the project root. How to ask: **§ The design ask** below |
+| **Website capture** — headless-Chrome crawl of a real site: screenshots, brand tokens, assets                                                          | "I can capture your site and build from its real look"                                                        | CLI → `npx hyperframes capture <URL> -o ./capture` → `capture/` (screenshots, extracted tokens/text/assets); doctrine: `/product-launch-video`                                                                                                                                                                                                  |
+| **Beat analysis & audio-reactive motion** — a deterministic beat / energy map of a track; cuts land on the grid, elements pulse with the music         | "if there's music, I can cut the video to its beat — and make elements move with it"                          | grid: `/music-to-video` → `scripts/analyze-beatgrid.py` → `audiomap.json` (beats, energy, sections); element reaction: `/hyperframes-creative` → `references/audio-reactive.md` + `scripts/extract-audio-data.py`                                                                                                                               |
+| **Motion blueprints** — proven scene shapes (reveals, counters, charts, dioramas) picked per beat                                                      | "each scene gets a proven motion treatment, not improvised movement"                                          | `/hyperframes-animation` → `blueprints-index.md` + `rules-index.md` → per-beat `blueprint:` ids the build reads                                                                                                                                                                                                                                 |
+| **Voice, music, SFX, images, logos, media treatments** — resolved media plus source-aware color, effects, privacy, reveals, and justified overlays     | "narration, music, sound effects, real assets — and footage polished or stylized to fit the story"            | `/media-use` → deterministic resolve/operate tools plus `references/media-treatments.md`; shader pixels persist through `hyperframes media-treatment`, optional overlays come from Registry, and finite motion uses the host GSAP timeline                                                                                                      |
+| **Generative video** — an AI presenter delivers the script; a still photo becomes a talking clip; a finished video gets dubbed into another language   | "an AI presenter can read your script on camera; I can animate a photo into a talking clip, or dub the video" | `/media-use` → `references/operations.md` § Generate: video (`heygen video create` / `video-translate`; OAuth free allowance where eligible) → an mp4 clip adopted into `assets/` + manifest record                                                                                                                                             |
+| **Transcription & captions** — word-timed transcripts; styled caption skins on the finished video                                                      | "accurate captions, styled to match"                                                                          | `/media-use` → `scripts/transcribe.mjs` → word-timed transcript; caption machinery `captions.mjs` (home: `/faceless-explainer`) → the caption track                                                                                                                                                                                             |
+| **Cut footage by its transcript** — trim a clip by choosing sentences, not timecodes                                                                   | "I can trim your clip by picking the sentences to keep"                                                       | `/media-use` → `scripts/transcript-cut.mjs` → the trimmed clip + updated transcript                                                                                                                                                                                                                                                             |
+| **Designed overlays on user footage** — kinetic titles, lower-thirds, data callouts synced to what's said                                              | "your own clip can carry designed titles and info bars, timed to the speech"                                  | the **whole ask** = the `/talking-head-recut` route — route there, don't rebuild it; **one scene inside a bigger piece** = `/hyperframes-animation` lower-third / callout blueprints + `/talking-head-recut`'s safe-zone thinking → overlay comps on the footage track                                                                          |
+| **Real map scenes** — a genuine basemap with located pins, routes, or a flight path                                                                    | "for places and journeys — a real map, not a drawing of one"                                                  | `/motion-graphics` → `grounding/locate.mjs` (geocode) + `categories/maps/` (incl. `bake-basemap.mjs`) → a deterministic baked basemap + located pins                                                                                                                                                                                            |
+| **Figma import** — assets, brand tokens, components, storyboard frames read as motion states                                                           | "if the design lives in Figma, I can build from it directly"                                                  | `/figma` → REST/CLI import (+ MCP for Motion/shaders) → sanitized SVGs, `var()`-bound brand tokens, frames-as-states                                                                                                                                                                                                                            |
+| **Registry blocks** — 50+ installable scene compositions (data charts, device mockups, quote cards…)                                                   | "ready-made scenes we can drop in and restyle"                                                                | `/hyperframes-registry` → `npx hyperframes add <block>` → an installed sub-composition (wiring: `references/wiring-blocks.md`)                                                                                                                                                                                                                  |
+| **Scene transitions** — cuts, crossfades, wipes, WebGL shader transitions between scenes                                                               | "how one scene hands off to the next — up to full shader wipes"                                               | `/hyperframes-animation` → `transitions/overview.md` then `transitions/catalog.md`; assembly `transitions.mjs` (home: `/faceless-explainer`) → injected handoffs in the index                                                                                                                                                                   |
+| **User media on the timeline** — the user's own images / clips staged and woven into frames                                                            | "your own footage, screenshots, or photos placed into the video"                                              | staging `stage-assets.mjs` (home: `/music-to-video`, `/product-launch-video`); adoption: `/media-use` `--adopt` → files in `assets/` + manifest records                                                                                                                                                                                         |
+| **Publish to a stable link** — the finished piece on a public URL; re-publishing updates the same link                                                 | "when it's done I can publish it to a link you can share — updates keep the same URL"                         | `/hyperframes-cli` → `references/preview-render.md` (`npx hyperframes publish`) → a stable public URL                                                                                                                                                                                                                                           |
+
+Offer, don't unload: the intent layer recommends the one or two rows the confirmed concept itself calls for, states each as one plain-language line traced to the brief, and asks once — the route-filtered slice on request, the full table for the companion.
+
+## The design ask — have it, pick it, or leave it
+
+The design-spec row is a three-state question, not an explainer (what a spec **is** stays in `design-spec.md`):
+
+- **They have one.** Brand guidelines, a `frame.md`, a `design.md` — note the path in `BRIEF.md` § Assets; the workflow reads it as brand truth (resolution order: `/hyperframes-creative` → `references/design-spec.md`).
+- **They don't, but the look matters — show, don't name.** Pick 2–3 shipped presets whose look fits the content, tone, and audience (browse `/hyperframes-creative` → `frame-presets/`), and open each one's `frame-presets/<name>/frame-showcase.html` in the browser so the user picks **by eye**, never from a list of names. The choice lands in `BRIEF.md` as `style_preset` — a remembered preference key, so next run it's the recommended answer with a receipt. On a route that captures a real site, say the honest line as the showcases open: a showcase wears the preset's **own** palette, and the site's brand colors and fonts will be remixed onto whichever preset wins — **the pick is the layout bones, not the colors** — and offer the alternative of deferring the pick until after capture, when the look can be judged with the real brand in hand (a declared deferred ask; the sketch pass shows the remixed truth either way, before anything expensive is built).
+- **They don't care — or nothing shipped fits.** Don't care: no further questions; the workflow's design step decides and says why. Nothing fits: announce the **design picker** as a deferred ask — the workflow's design step generates mood boards contextual to their content to choose from (`/hyperframes-creative` → `references/design-picker.md`); it needs a project and a generation pass, so it never runs inside the intent conversation.
+
+## Genre lenses — the shipped workflows' taste, borrowable
+
+The narrative workflows carry genre-tuned design references — `story-design.md` (narrative archetypes and beats), `visual-design.md` (the genre's look), `motion-language.md` + `cut-catalog.md` (motion and cut doctrine). When a companion or freeform piece resembles a genre, read that workflow's lens before planning or building in it (borrowing rule above):
+
+| The piece resembles…                     | Borrow from                                                             |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| a product promo / launch / site showcase | `/product-launch-video` → `references/`                                 |
+| a topic / mechanism / concept explainer  | `/faceless-explainer` → `references/`                                   |
+| a code-change walkthrough                | `/pr-to-video` → `references/` (+ `code-vocabulary.md` for code frames) |
+
+`motion-language.md` and `cut-catalog.md` are near-identical across the three — take them from the genre you already resembled, or `/faceless-explainer`'s as the neutral default. **Borrow the shape and the taste, never the machinery**: their scripts and directory rules belong to their pipelines; the generic back half of any build lives in `hyperframes-core/references/production-loop.md`.