dsh-hyperframes 0.9.1 → 0.9.3

package/skills/talking-head-recut/SKILL.md

@@ -1,1220 +1,10 @@
 ---
 name: talking-head-recut
-description: Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.
+description: Compatibility entry for the retired talking-head-recut skill; routes to the current official hyperframes skill.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+# talking-head-recut: compatibility entry
 
-> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update talking-head-recut`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+The current official HyperFrames release merged this workflow into the `hyperframes` skill. Load `hyperframes` from the DSH skill registry and follow its current instructions for the user's task. Use its bundled resources; do not reconstruct the retired workflow or download standalone skills.
 
-# Talking Head Recut
-
-Talking Head Recut takes a local video that **plays in full** and layers a sequence of
-timed, designed **graphic cards** onto it — titles, lower-thirds, data callouts,
-quotes, side panels, picture-in-picture — synced to what's being said. The agent
-designs the cards (timing + content) and **writes each card's HTML directly in the
-conversation**, then assembles a single composition HTML and renders it to MP4 via
-`hyperframes`. There is no fixed archetype list and no prescribed card structure —
-the overlays emerge from what the transcript actually says.
-
-> **The front door is `/hyperframes`.** This skill packages an **existing talking-head clip** with **designed graphic cards** (titles, lower-thirds, data callouts, quotes, side panels, PiP) — not plain captions (the spoken words as text). **The clip plays untouched.** Any other intent — plain subtitles, a standalone graphic, a from-scratch video — or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
-
-> **Graphic-packaging sibling of `embedded-captions`.** Captions add the _spoken words_
-> as a readable subtitle; this adds _designed graphics_ on top of the playing video.
-> Plain subtitles → `embedded-captions`. Build a video from scratch → the creation
-> workflows (`product-launch-video` / `faceless-explainer` / …).
-
-Routed through `/hyperframes`, the intent layer confirms only the input (which clip) and **announces** the render-strategy questions as deferred asks — aspect, layout, style group, and card count stay at Step 7, where the probed footage and transcript ground the recommendations; the layer's run-shape questions don't apply. A `BRIEF.md`, when present, carries the confirmed input and any user notes — read it first.
-
-Inspectable intermediate files in the work directory:
-
-- `metadata.json` — duration / width / height / fps
-- `audio.mp3` — extracted audio
-- `transcript.json` — a flat **word array** `[{ text, start, end }, …]` (Whisper; no `segments`, no `words` wrapper)
-- `storyboard.json` — lightweight card outline (the agent's plan)
-- `public/cards/card-XX.html` — one HTML fragment per card
-- `public/index.html` — final assembled composition
-- `output.mp4` — rendered video
-
-## CLI Resolution
-
-```bash
-# hyperframes — transcription (local Whisper) + rendering the assembled HTML to MP4
-npx hyperframes --help
-```
-
-This skill runs entirely on the **hyperframes** CLI plus system `ffmpeg` / `ffprobe`.
-Transcription is local **Whisper** via `hyperframes transcribe` — no third-party
-service, API key, or rate-limited proxy.
-
-## Workflow
-
-### 1. Check Environment
-
-```bash
-npx hyperframes doctor          # ffmpeg, headless browser, render deps
-# confirm bundled assets:
-ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"
-```
-
-Required:
-
-- `ffmpeg` / `ffprobe` (system)
-- `<SKILL_DIR>/assets/fonts/*.woff2`, `<SKILL_DIR>/assets/vendor/gsap.min.js` (bundled inside this skill, staged to work dir in Step 9)
-
-Transcription needs no key — `hyperframes transcribe` runs Whisper locally (Step 4).
-
-Strongly recommended on macOS for `hyperframes render`:
-
-```bash
-export PRODUCER_BROWSER_GPU_MODE=hardware
-```
-
-### 2. Create a Work Directory
-
-All artifacts live under `videos/<project-name>/` — the same convention as the other
-video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video`). Keep
-the cwd at the workspace root; everything below writes under this one subdirectory.
-
-```bash
-VIDEO_PATH="/absolute/path/input.mp4"
-WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
-mkdir -p "$WORK_DIR"
-```
-
-### 3. Extract Audio and Metadata
-
-```bash
-# metadata — duration / width / height / fps
-ffprobe -v error -select_streams v:0 \
-  -show_entries stream=width,height,r_frame_rate \
-  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
-# audio
-ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"
-```
-
-Outputs: `metadata.json` (read `width`/`height`/`duration`; fps = the `r_frame_rate`
-fraction evaluated, e.g. `30000/1001 → 29.97`) + `audio.mp3`.
-
-### 4. Transcribe
-
-```bash
-npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en
-```
-
-Local **Whisper** — no API key, no proxy, no rate limit. Writes a word-level
-`transcript.json` into the work dir (word `text` + `start` / `end` timestamps).
-Read it for the word / sentence timings that drive card timing in Step 6; group
-words into sentences yourself at punctuation / pauses if you need segment-level
-chunks.
-
-**Clamp to media duration.** Whisper can return the final word's `end` a hair past the
-actual clip length — clamp every card `endSec` and `composition.durationSeconds` to the
-`metadata.json` duration, or the render will show a black tail past the video.
-
-### 5. Correct Transcript
-
-`transcript.json` is a **flat array of word objects** — `[{ "text": "...", "start": s, "end": s }, …]` (no `segments` array, no `words` wrapper; the per-word key is **`text`**). Read it and fix obvious ASR errors:
-
-- Homophones, product names, technical terms, punctuation
-- Edit a word's `text` in place; **preserve its `start` / `end`** timestamps
-- There is no pre-grouped `segments` array — **group words into sentences yourself** (split at terminal punctuation / pauses) when you need segment-level chunks for card timing
-
-### 6. Draft a Lightweight Storyboard (in chat)
-
-**No CLI involved.** Read `transcript.json` + `metadata.json` and design
-cards directly. `storyboard.json` is an agent-internal planning artifact
-— no CLI command consumes it; it exists so you can think clearly
-about timing and content before writing each card's HTML. Keep the
-shape consistent with the example below so the same outline can drive
-the composition you author in Step 9:
-
-```json
-{
-  "schemaVersion": 3,
-  "composition": {
-    "fps": 30,
-    "width": 1080,
-    "height": 1920,
-    "durationSeconds": 121.2,
-    "layout": "portrait",
-    "themeId": "noir",
-    "seed": 42
-  },
-  "videoTrack": {
-    "sourcePath": "input-video.mp4",
-    "startSec": 0,
-    "endSec": 121.2,
-    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
-  },
-  "subtitles": { "enabled": false },
-  "cards": [
-    {
-      "id": "card-01",
-      "intent": "Hook with the speaker's anxious midnight question",
-      "startSec": 0.5,
-      "endSec": 13.0,
-      "accentIndex": 0,
-      "zone": "fullscreen",
-      "contentHints": {
-        "kicker": "AN HONEST QUESTION",
-        "title": "The soul-searching question at 11 PM",
-        "detail": "Client's 60-second voice message: 'If the RMB appreciates, does that mean my USD policy is a terrible loss?'"
-      }
-    }
-  ]
-}
-```
-
-**Required Card fields:**
-
-| field                   | type                                       | purpose                                                                                               |
-| ----------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| `id`                    | string                                     | stable id used in card HTML & GSAP selectors                                                          |
-| `intent`                | string                                     | natural-language description; fed to card synthesis                                                   |
-| `startSec` / `endSec`   | number                                     | times in seconds (endSec > startSec)                                                                  |
-| `accentIndex`           | 0 \| 1 \| 2 \| 3 \| 4                      | which of the 5 theme accent colors this card pulls                                                    |
-| `zone`                  | enum (see below)                           | where on the canvas the card lives                                                                    |
-| `contentHints`          | object                                     | free-form bag; agent puts kicker/title/detail/data/quote here                                         |
-| `archetype` (optional)  | string                                     | free-form label you may attach to remember a card's pattern; absent = free-form, which is the default |
-| `transition` (optional) | enum: `cut` \| `fade` \| `slide` \| `wipe` | declarative card-to-card transition                                                                   |
-
-**Five `zone` values:**
-
-| zone              | resolved bounds                                | when to use                             |
-| ----------------- | ---------------------------------------------- | --------------------------------------- |
-| `fullscreen`      | covers whole canvas                            | hero moments, big numbers, mantras      |
-| `whiteboard-area` | inset 40px margin (or 45% of portrait height)  | dense data / annotated content          |
-| `lower-third`     | bottom 30% band                                | annotation over visible video           |
-| `side-panel`      | right 42% (landscape) or bottom 40% (portrait) | data side, video other side             |
-| `video-overlay`   | full canvas, expects mostly-transparent card   | annotation overlays on full-bleed video |
-
-When you assemble the composition in Step 9, resolve each card's `zone`
-into pixel bounds on the card-host wrapper following the table above.
-Video bounds are set **once** at composition level (`videoTrack.bounds`);
-to make video appear to "move between cards", author GSAP tweens against
-`#video-wrap` in the composition's `<script>` (see Step 9).
-
-**No prescribed card roles, no prescribed narrative arc.** Cards emerge
-from what the video actually says — could be all quotes or all data,
-could open with a number or with a story. Let the transcript drive the
-rhythm.
-
-**How many takeaways? — auto-infer from duration + density.** No fixed
-upper limit. Pick a **base pace** from the video duration, then adjust
-by **information density**. Only **floor is fixed: minimum 5 cards** so
-even short videos have rhythm.
-
-**Step 1 — base pace by duration** (the natural sec/card for medium density):
-
-| video duration     | base pace (sec per card) | rationale                                   |
-| ------------------ | ------------------------ | ------------------------------------------- |
-| < 60s (short reel) | **6–8s**                 | viewers expect fast cuts in short-form      |
-| 60s – 3 min        | **8–12s**                | normal social pace                          |
-| 3 – 10 min         | **12–20s**               | give breathing room; each card carries more |
-| 10 – 30 min        | **20–35s**               | long-form lecture / interview rhythm        |
-| > 30 min           | **30–60s**               | episodic, near-chapter feel                 |
-
-**Step 2 — density multiplier** (multiplies the base pace):
-
-| signal in the transcript                                                                                                    | multiplier | effect                   |
-| --------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ |
-| **High density** — many numbers, distinct claims, staccato pacing, list-like enumeration, every 1–2 sentences is a new idea | **× 0.7**  | cuts faster, more cards  |
-| **Medium density** — mixed flow with both data and narrative                                                                | **× 1.0**  | base pace                |
-| **Low density** — one extended story, repeated reframing, slow reflective pacing, single argument unfolding                 | **× 1.5**  | cuts slower, fewer cards |
-
-**Step 3 — compute:**
-
-```
-secPerCard = basePace × densityMultiplier
-cardCount  = max(5, round(videoDurationSec / secPerCard))
-```
-
-Examples (notice — **no upper clamp**; long videos naturally produce more cards):
-
-- **30s reel, single punchline (low density)** → 7 × 1.5 = 10.5s/card → round(30/10.5)=3 → floor to **5** cards
-- **60s reflective monologue (low density)** → 10 × 1.5 = 15s/card → **4** → floor to **5** cards
-- **121s talking-head with rich data (high density)** → 10 × 0.7 = 7s/card → **17** cards
-- **5 min interview, mixed density** → 16 × 1.0 = 16s/card → **19** cards
-- **10 min deep-dive, high density** → 16 × 0.7 = 11s/card → **55** cards
-- **30 min lecture, medium density** → 28 × 1.0 = 28s/card → **64** cards
-- **1 hr podcast, low density** → 45 × 1.5 = 67.5s/card → **53** cards
-
-When a card holds longer than ~15s, plan for a richer card (data block,
-multi-step reveal, several sub-points unfolding with staggered
-animations) — a static one-liner gets boring past 8s. For long pieces
-where many cards exceed 30s, consider **chunking the timeline into
-sub-compositions** (one .html per chapter, mounted with
-`data-composition-src`) so the GSAP timeline per file stays manageable
-— see the `timeline_track_too_dense` HyperFrames lint warning.
-
-`content` can be a plain string ("Title: annualized 5.69%\nNotes: ...") or any JSON
-shape that captures the data. The agent decides the shape per card.
-
-**Optional outro.** This skill ships **no fixed brand outro**. If the user wants a closing card, design a neutral one yourself (wordmark + one-line tagline, ~1.5-2s, fade in -> short hold -> fade out), append it to `cards[]`, and extend `composition.durationSeconds` to its `endSec`. Otherwise end on the last content card.
-
-### 7. Decide Render Strategy
-
-#### Confirm Visual Direction with User (DO THIS FIRST)
-
-Before you start designing cards or deciding bounds, **ask the user to
-pick the output ratio, the layout, the style, and the card-density
-preset**. Frames are auto-selected from the chosen layout × style
-combination (see "Auto-pick frame" table below). Before sending the
-question, **precompute two things**:
-
-1. **`recommendedRatio`** from the source video's aspect ratio
-   (`metadata.json` width / height):
-   - `sourceAspect = width / height`
-   - `sourceAspect ≥ 1.5` (≥ ~3:2 wide) → recommend **`16:9`**
-   - `sourceAspect ≤ 0.7` (≤ ~9:13 tall) → recommend **`9:16`**
-   - `0.7 < sourceAspect < 1.5` (near-square) → recommend **`4:5`**
-
-   Mark the recommended option's label with " (recommended · matches source video X:Y)"
-   so the user sees why it's recommended.
-
-2. **`autoCount`** from Step 6 (`max(5, round(videoSec / (basePace ×
-densityMultiplier)))`) so the "auto" option's label can show the
-   concrete number.
-
-**Environment compatibility — pick the best available question channel.**
-Not every runtime exposes the same structured-question tool. Apply this
-order:
-
-1. **Native clarification tool** — use the structured 4-question call below.
-2. **Other native clarification tool** (e.g. `ask_question`,
-   `request_user_input`, IDE-specific prompt) — use that tool with the
-   same 4 question texts and option lists. Preserve the recommendation
-   markers and the precomputed values.
-3. **No native tool** (Codex CLI, plain text-only runtimes) — **ask
-   directly in normal conversation**. Use the plain-text template at the
-   end of this section. Keep it to **one message, 4 numbered questions**
-   (the global cap is 2–5 questions per round; we stay inside it).
-
-Rules that apply to every channel:
-
-- Ask **at most 2–5 questions per round**. Our 4 here fits.
-- Even if missing info doesn't block rendering, **ask once to confirm
-  the parameters that materially affect the final output** (ratio,
-  layout, style, cardCount).
-- If the user has already pre-approved defaults ("just use defaults",
-  "no need to ask", "auto-pick everything"), asked you not to ask, or the
-  run carries an ongoing autonomous signal ("surprise me" / "decide for me" —
-  `../hyperframes/references/brief-contract.md` § 1) — **skip
-  the question entirely** and use: `recommendedRatio`, `layout="stack"`
-  (safest cross-ratio default), `style` chosen from transcript tone in
-  the most neutral group (editorial/data), `autoCount`. Tell the user
-  what you picked in one sentence and continue.
-
-**Channel A — native `AskUserQuestion`:**
-
-```
-// Precompute before the call:
-//   recommendedRatio = "16:9" | "9:16" | "4:5"
-//   autoCount        = integer (from Step 6)
-
-AskUserQuestion({
-  questions: [
-    {
-      question: "Output video aspect ratio (canvas):",
-      header: "Aspect ratio",
-      multiSelect: false,
-      // Reorder so the recommended option appears FIRST (per AskUserQuestion convention).
-      // Append " (recommended · matches source video W×H)" to the recommended option's label.
-      options: [
-        { label: "16:9 (1920×1080) landscape", description: "TV / YouTube / desktop playback. Most natural when the source video is already landscape; widest canvas." },
-        { label: "9:16 (1080×1920) portrait", description: "TikTok / Reels / short-form mobile. Most natural for portrait source; native mobile experience." },
-        { label: "4:5 (1080×1350) near-portrait", description: "Instagram feed / WeChat Moments. Best when source is near-square or you want to cover both platforms." }
-      ]
-    },
-    {
-      question: "Choose the overall layout: how should the video and cards coexist on the canvas?",
-      header: "Layout",
-      multiSelect: false,
-      options: [
-        { label: "side-by-side (split)",  description: "Video and card each take half the canvas. Most stable for interview / data side-by-side; clear visual separation." },
-        { label: "top-bottom (stack)",    description: "Video on top (~52%), card below. Classic combo of speaker face + summary card; works well in portrait too." },
-        { label: "picture-in-picture (pip)", description: "Card fills the canvas, video shrinks to a rounded corner window. Use when content is primary and speaker is secondary." },
-        { label: "full-screen overlay (overlay)", description: "Video plays full-bleed, card floats as a glass layer on top. Strong cinematic / emotional feel." }
-      ]
-    },
-    {
-      question: "Choose the card visual style (style):",
-      header: "Style group",
-      multiSelect: false,
-      // NOTE: these 3 groups intentionally match the frame auto-pick matrix
-      // rows below, so picking a group resolves both `style` group AND the
-      // frame matrix column in one step. Memberships are mutually exclusive.
-      options: [
-        { label: "warm paper (warm-paper)", description: "academic notebook · editorial big-type · whiteboard hand-drawn · xhs social. Best for interview reflections, product launches, lifestyle, emotional stories." },
-        { label: "clinical / cold (clinical)",   description: "audit magazine · swiss grid · terminal CLI · minimal modern. Best for financial analysis, investigative reports, technical tutorials, serious presentations." },
-        { label: "experimental / avant-garde (experimental)", description: "geom color-clash geometry · spotlight dark-background. Best for short-form highlights, product launches, strong emotion, cinematic feel." }
-      ]
-    },
-    {
-      question: "Card count (takeaway pacing): how many cards to cut?",
-      header: "Card count",
-      multiSelect: false,
-      options: [
-        { label: "Auto (recommended) · approx N cards", description: "Inferred automatically from video duration and information density (see Step 6 rules). This run estimates approx N cards. Substitute the real N (your autoCount) into the label." },
-        { label: "Fewer · approx round(N × 0.6) cards", description: "Sparser cuts, each card holds longer — suits reflective / slow-paced content." },
-        { label: "More · approx round(N × 1.5) cards", description: "Tighter cuts, faster rhythm — suits staccato / data-dense / short-form highlight content." }
-      ]
-    }
-  ]
-})
-```
-
-**About "Other"** — `AskUserQuestion` automatically adds an "Other" option to the card count question. The user can type a number directly (e.g. "8", "20") as the cardCount target. Parse the input as an integer: if parsing succeeds → use that value (minimum 5 as a floor); if parsing fails → fall back to "auto".
-
-**Channel B — plain-text fallback** (Codex CLI, runtimes without a
-native question tool). Post this as one normal message, then wait for
-the reply. Bullet-style 1/2/3/4 keeps the reply parseable:
-
-```
-I need to confirm four visual decisions with you before I start cutting cards:
-
-1) Output aspect ratio (canvas):
-   A. 16:9 landscape (1920×1080) — TV / YouTube / desktop playback
-   B. 9:16 portrait (1080×1920) — TikTok / Reels / short-form mobile
-   C. 4:5 near-portrait (1080×1350) — Instagram feed / works for both platforms
-   ▸ My recommendation:  <recommendedRatio>  (matches source video W×H = <sourceW>×<sourceH>)
-
-2) Overall layout (how video & card coexist):
-   A. split   side-by-side (50/50)
-   B. stack   top-bottom (video top, card bottom)
-   C. pip     picture-in-picture (card full canvas, video rounded corner window)
-   D. overlay full-screen glass overlay (video full-bleed, card glass layer)
-
-3) Card style group (maps to frame auto-pick matrix, pick 1 of 3):
-   A. warm paper (warm-paper)      (academic / editorial / whiteboard / xhs)
-   B. clinical / cold (clinical)   (audit / swiss / terminal / minimal)
-   C. experimental (experimental)  (geom / spotlight)
-
-4) Card count (takeaway pacing):
-   A. Auto (recommended) — approx <autoCount> cards
-   B. Fewer — approx round(<autoCount> × 0.6) cards
-   C. More — approx round(<autoCount> × 1.5) cards
-   D. Give me a specific number (e.g. "8", "20")
-
-Reply format: "1A 2C 3B 4A" or natural language is fine.
-If you want all recommended defaults, reply "default" / "auto" / "use all recommendations".
-```
-
-Parsing the plain-text reply:
-
-- Accept loose formats: `"1A 2C 3B 4A"`, `"A C B A"`, `"16:9 / pip /
-data / auto"`, full sentences, or `default`.
-- If any answer is ambiguous → re-ask only the ambiguous ones (still
-  inside the 2–5 cap).
-- If the user says "default / auto / use all recommendations" → skip without re-asking.
-
-After the user answers (any channel):
-
-1. **Resolve the output canvas** from the ratio answer — these are the
-   exact `storyboard.composition.width / height` values to write:
-
-   | user choice | composition.width × height | storyboard.layout field                                       |
-   | ----------- | -------------------------- | ------------------------------------------------------------- |
-   | `16:9`      | **1920 × 1080**            | `"landscape"`                                                 |
-   | `9:16`      | **1080 × 1920**            | `"portrait"`                                                  |
-   | `4:5`       | **1080 × 1350**            | `"portrait"` (schema treats 4:5 as portrait — height > width) |
-
-   For **4:5 bounds inside `references/layouts/*.html`** — those files
-   only document landscape (1920×1080) and portrait (1080×1920). For
-   4:5 (1080×1350) derive bounds by **proportional scaling from
-   portrait**: keep horizontal values, scale vertical values by
-   `1350/1920 ≈ 0.703`. Example: `overlay` portrait card =
-   `{ x: 24, y: 1280, w: 1032, h: 564 }` → 4:5 card =
-   `{ x: 24, y: round(1280 × 0.703), w: 1032, h: round(564 × 0.703) }`
-   = `{ x: 24, y: 900, w: 1032, h: 397 }`.
-
-2. **Map the style group to a specific style** by looking at the
-   transcript tone — pick the one that best fits, but stay inside the
-   user's chosen group. If you're unsure between two specific styles
-   inside the group, send a second `AskUserQuestion` with those 2–4
-   specific style options.
-
-3. **Resolve final cardCount** from the density answer:
-
-   | user choice             | final cardCount                           |
-   | ----------------------- | ----------------------------------------- |
-   | Auto (recommended)      | the `autoCount` you already computed      |
-   | Fewer                   | `max(5, round(autoCount × 0.6))`          |
-   | More                    | `round(autoCount × 1.5)` (no upper clamp) |
-   | Other = "<n>" (integer) | `max(5, parseInt(n))`                     |
-   | Other = anything else   | fall back to `autoCount`                  |
-
-4. **Auto-pick the video frame** from this table (frames don't ask the
-   user — they follow from layout × style):
-
-   | layout    | warm-paper styles (academic / whiteboard / editorial / xhs) | clinical styles (audit / swiss / terminal / minimal) | experimental styles (geom / spotlight) |
-   | --------- | ----------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------- |
-   | `split`   | `polaroid`                                                  | `hairline`                                           | `clean`                                |
-   | `stack`   | `polaroid`                                                  | `hairline`                                           | `clean`                                |
-   | `pip`     | `clean` (pip pill already has chrome)                       | `clean`                                              | `clean`                                |
-   | `overlay` | `clean` (full-bleed forbids deco frames)                    | `clean`                                              | `clean`                                |
-
-5. **Tell the user what you chose** in one sentence — ratio (+ canvas
-   size), layout, specific style, frame, and final cardCount — then
-   proceed with the rest of Step 7 (per-card layouts, motion patterns).
-6. Record the five values (ratio / layout / style / frame / cardCount)
-   in working memory (no schema field needed); you'll reference them
-   while writing each card's HTML in Step 8 and while reading the
-   matching `references/<dim>/<key>.html` for tokens and structure.
-
-If the user picks an answer via "Other" with a free-text style name not
-in the 10-style library, treat it as a hint to design a fresh card
-visual yourself, but still anchor on the chosen layout's bounds.
-
-#### Render Strategy Inputs
-
-With ratio / layout / style / cardCount / frame locked from Step 7.0,
-the remaining per-card decisions are:
-
-- **Source-video fit inside the GSAP target**: video element has
-  `object-fit: cover` and is clipped to `#video-wrap`'s tween bounds.
-  If you want NO cropping (e.g. portrait source on landscape canvas
-  shouldn't get its top/bottom chopped), aim the tween at a rect that
-  matches the source's aspect ratio and let surrounding canvas show
-  through (or fill with the card / a backdrop).
-- **`card.zone` per card**: derive from your chosen composition layout
-  (split → side-panel, stack → lower-third, pip → fullscreen, overlay
-  → video-overlay), OR pick a different zone for one-off variants
-  (fullscreen for hero / quote, whiteboard-area for dense data).
-- **`accentIndex` per card**: each card pulls one of the 5 theme accent
-  colors. Vary across cards for rhythm; reuse the same index when two
-  cards belong to the same narrative beat.
-- **Motion vocabulary**: pick 2–3 repeatable patterns from
-  `data-anim` kinds (see the table later) and stick to them so the
-  composition feels coherent.
-
-Pick from these `themeId` palettes (use them as `--accent-N` /
-`--bg` / `--text` CSS variables in your composition `<style>` block):
-
-| themeId | accent palette (5 colors)                 | board bg          | text      |
-| ------- | ----------------------------------------- | ----------------- | --------- |
-| classic | `#1971c2 #e03131 #2f9e44 #e8590c #9c36b5` | `#FFF9E3` (paper) | `#1e1e1e` |
-| noir    | `#4cc9f0 #f72585 #4ade80 #fb923c #a78bfa` | `#1a1a1a`         | `#f1f1f1` |
-| mint    | `#0077b6 #d62828 #2d6a4f #e76f51 #7209b7` | `#e8faf0`         | `#1b4332` |
-| craft   | `#bf5700 #d62728 #6c757d #e9b54a #3d5a80` | `#f6efe1`         | `#2d2d2d` |
-| slate   | `#0ea5e9 #ef4444 #22c55e #f97316 #a855f7` | `#1e293b`         | `#f1f5f9` |
-| mono    | `#000 #555 #888 #aaa #ccc`                | `#fff`            | `#000`    |
-
-Available fonts (woff2 in `<SKILL_DIR>/assets/fonts/`, staged to work dir in Step 9): `Caveat` (handwriting),
-`LXGW WenKai TC` (Chinese hand-script), `Inter` (modern sans), `Virgil`
-(geometric hand). Reference via `@font-face` or `font-family` directly.
-
-For inspiration on visual patterns, `<SKILL_DIR>/references/styles/`
-ships 10 self-contained reference cards (academic / editorial / minimal
-/ spotlight / geom / whiteboard / audit / terminal / swiss / xhs) that
-you can copy as starting points — but **do not feel constrained to
-match any of these**. Each card is your own design.
-
-#### Visual Design Library (<SKILL_DIR>/references/)
-
-Beyond the composition-level `themeId`, the skill ships a richer **reference
-library** at `<SKILL_DIR>/references/` covering three **orthogonal**
-visual dimensions you can freely mix:
-
-```
-Style  ×  Layout  ×  VideoFrame
- (10)      (4)         (3)
-```
-
-| dimension  | keys                                                                                              | what it decides                                                          |
-| ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| **style**  | `academic` `editorial` `minimal` `spotlight` `geom` `whiteboard` `audit` `terminal` `swiss` `xhs` | the card's visual language — fonts, colors, ornament, layout-within-card |
-| **layout** | `split` `stack` `pip` `overlay`                                                                   | how the source video and the card share the canvas                       |
-| **frame**  | `clean` `hairline` `polaroid`                                                                     | the decorative chrome around the video element                           |
-
-Read `<SKILL_DIR>/references/DESIGN_INDEX.md`
-for the full matrix and a loose decision guide (interview / product launch / data analysis /
-social clip / technical tutorial / emotional story …). When you decide to use a specific
-style / layout / frame, Read the corresponding file:
-
-- `references/styles/<key>.html` — self-contained card fragment with that
-  style's CSS tokens (colors, fonts, padding, ornament) and a placeholder
-  takeaway. Copy the `.card[data-card-id="ref-<key>"]` style block, rename
-  the data-card-id to your card's id, swap the placeholder content for the
-  real takeaway, and you're done.
-- `references/layouts/<key>.html` — exact `videoBounds` + `cardBounds` for
-  both landscape and portrait, with a copy-paste JSON snippet for
-  `storyboard.json`'s per-card `layout` field.
-- `references/frames/<key>.html` — decorative HTML to add as a sibling of
-  `#video-wrap`, plus placement instructions for the composition CSS.
-
-Pick `style × layout × frame` **per card** — you can change all three
-between cards as long as the transitions read smoothly. A common rhythm:
-open `editorial × overlay × clean`, switch to `audit × split × hairline`
-for the data card, close on `whiteboard × pip × polaroid`.
-
-The 10 styles are skill-side design tokens, **not composition-level themes** —
-they don't need to be declared in `storyboard.composition`; they live
-inside each card's HTML. The `themeId` field can still pick a
-composition-level palette (table above) that controls page-body background
-and video border chrome.
-
-#### Layout Compositions (Card + Video)
-
-Two coordinated decisions per card define how it shares the canvas with
-the source video:
-
-- **`card.zone`** (declared in `storyboard.json`) — one of the 5 schema
-  values; resolve it into pixel bounds (per the table in Step 6) when
-  you write the card-host wrapper's inline `style` in Step 9.
-- **`#video-wrap` bounds at this card's time window** (declared
-  imperatively in the composition's GSAP timeline) — the agent tweens
-  `#video-wrap` to a target rect for each layout transition.
-
-Schema does NOT store per-card video bounds. `videoTrack.bounds` is
-**one-time** at composition level (defaults to full canvas). Video
-"moving" between cards is purely a GSAP animation authored in
-`index.html`. There is no `card.layout` field — earlier versions of this
-doc invented one; the real schema only has `card.zone`.
-
-**4 composition layouts** (from `references/layouts/`) — each is a
-recipe pairing a `zone` with a `#video-wrap` tween target:
-
-| composition layout | recommended `card.zone` | GSAP target for `#video-wrap` (landscape 1920×1080)                       | GSAP target for `#video-wrap` (portrait 1080×1920)                | when to use                                     |
-| ------------------ | ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
-| `split`            | `side-panel`            | `{ left: 960, top: 0, width: 960, height: 1080 }`                         | `{ left: 0, top: 960, width: 1080, height: 960 }` (bottom half)   | speaker + data side-by-side / 50:50 weight      |
-| `stack`            | `lower-third`           | `{ left: 14, top: 14, width: 1892, height: 548 }` (top 52%)               | `{ left: 0, top: 0, width: 1080, height: 844 }` (top 44%)         | speaker on top + summary card below             |
-| `pip`              | `fullscreen`            | `{ left: 1480, top: 760, width: 400, height: 300 }` + add `.framed` class | `{ left: 690, top: 28, width: 360, height: 203 }` + add `.framed` | content-heavy card + corner pip                 |
-| `overlay`          | `video-overlay`         | `{ left: 0, top: 0, width: 1920, height: 1080 }` (full-bleed)             | `{ left: 0, top: 0, width: 1080, height: 1920 }`                  | cinematic / dramatic / glass card on full video |
-
-For 4:5 (1080×1350), scale portrait y/h values by `1350/1920 ≈ 0.703`
-(see Step 7.0 Channel A / Channel B `recommendedRatio` resolution
-table).
-
-**Other zone values for one-off variants** (still uses `card.zone`; no
-fake "layout" field):
-
-| `zone`            | resolved bounds                                        | common use                            |
-| ----------------- | ------------------------------------------------------ | ------------------------------------- |
-| `fullscreen`      | covers whole canvas                                    | hero card, video tweens to hidden/pip |
-| `whiteboard-area` | inset 40px margin (landscape) or bottom 45% (portrait) | dense data card, free margins         |
-| `lower-third`     | bottom 30% band                                        | talking-head annotation               |
-| `side-panel`      | right 42% (landscape) or bottom 40% (portrait)         | sidebar / "split" recipe              |
-| `video-overlay`   | full canvas; expect transparent card root              | glass overlay on full-bleed video     |
-
-You can mix recipes per card — choose `card.zone` based on what suits
-the moment, then write the GSAP tween for `#video-wrap` between cards.
-
-#### Storyboard Render Contract
-
-`storyboard.json` is an agent-internal planning artifact — no CLI
-command parses it. It exists to keep your timing and content decisions
-explicit before you write each card's HTML. Stick to the v3-style
-shape below so the same outline drives the composition you assemble in
-Step 9.
-
-Required structure (see Step 6 for the full example):
-
-- `schemaVersion: 3`
-- `composition: { fps, width, height, durationSeconds, layout, themeId, seed }` — note `durationSeconds`/`fps`/`themeId`/`layout` live **inside** `composition`, NOT at top level
-- `videoTrack: { sourcePath, startSec, endSec, bounds? }` — video bounds default to full canvas
-- `subtitles: { enabled, ... }`
-- `cards[]` — each card has the 6 required fields: `id`, `intent`, `startSec`, `endSec`, `accentIndex`, `zone`, `contentHints`
-
-Rules:
-
-- Card times stay inside `composition.durationSeconds` and should not overlap unless intentional (use `data-track-index` to control z-order when they do).
-- Visual details live in card HTML fragments (Step 8), NOT in `contentHints`. `contentHints` is your own structured prompt for designing the card; the rendered look is the HTML.
-- Keep the storyboard shape stable — even though nothing parses it, you read it back while authoring Step 8/9, and consistency keeps card IDs and timing in sync.
-- Agent-side decisions like "I picked overlay × geom × clean" do NOT belong in `storyboard.json` — keep them in working memory and use them when authoring card HTML + GSAP tweens.
-
-**Transparent card backgrounds for cards that share canvas with video.**
-When the GSAP tween leaves video visible behind/beside the card (overlay
-recipe, pip recipe, or any `card.zone = 'lower-third' | 'video-overlay'`
-moment), the card's `.root` MUST NOT paint a full opaque background —
-otherwise it occludes the video. Two patterns:
-
-```css
-/* Pattern A: transparent root, page body provides the cream backdrop */
-html,
-body {
-  background: var(--bg);
-}
-.card[data-card-id="card-X"] .root {
-  background: transparent;
-}
-
-/* Pattern B: explicit per-card background ONLY for fullscreen cards */
-.card[data-card-id="card-hero"] .root {
-  background: var(--bg);
-}
-.card[data-card-id="card-overlay"] .root {
-  background: transparent;
-}
-```
-
-For `side-panel`-zone cards (split recipe), the card-host is already
-only half the canvas, so an opaque card bg is fine — it only covers its
-half.
-
-### 8. Write Each Card's HTML
-
-Create `$WORK_DIR/public/cards/{card-id}.html` for each card. Each file
-contains a single rooted HTML fragment that follows this contract:
-
-#### Card HTML Contract
-
-```html
-<div class="card" data-card-id="{cardId}">
-  <style>
-    /* MUST: every rule starts with .card[data-card-id="{cardId}"] */
-    .card[data-card-id="card-01"] .root {
-      width: 100%; height: 100%;
-      display: flex; ...;
-      font-family: 'Caveat', 'LXGW WenKai TC', serif;
-      color: var(--text);
-      background: var(--bg);
-    }
-    .card[data-card-id="card-01"] .title { font-size: 84px; ... }
-  </style>
-
-  <div class="root">
-    <h1
-      id="card-01-title"
-      data-anim="kinetic-chars"
-      data-anim-at="0.3"
-      data-anim-duration="0.5"
-      data-anim-stagger="0.04"
-      data-anim-pattern="pop"
-    >
-      <span class="char">S</span>
-      <span class="char">u</span>
-    </h1>
-    <div
-      id="card-01-line"
-      data-anim="grow-x"
-      data-anim-at="0.65"
-      data-anim-duration="0.5"
-      data-anim-target-w="420"
-      style="width:0;height:8px;background:var(--accent-0);border-radius:4px;"
-    ></div>
-  </div>
-</div>
-```
-
-**Hard rules** (`hyperframes` lint will reject violations):
-
-- Single root `<div class="card" data-card-id="{cardId}">`
-- Inline `<style>` rules MUST be prefixed with the scope selector above
-- **No `<script>` tags**
-- **No external URLs** in `src=` / `href=` (no CDN, no remote fonts)
-- **No inline event handlers** (`onclick=` etc.)
-- All assets via relative paths into the same `public/` directory
-- Colors via `var(--accent-N)` etc. for portability across themes
-
-**Animations are declared, not coded.** Use `data-anim-*` attributes
-only; never write `<script>` to animate. You compile every `data-anim-*`
-declaration into the single master GSAP timeline in Step 9.
-
-#### Card Sizing — Mobile-First in Portrait
-
-The 10 `references/styles/*.html` are sized for a **1920×1080 landscape**
-preview. When `storyboard.layout = "portrait"` (1080×1920, the dominant
-case for social / mobile), **scale every visual size up** — phones hold
-the screen close, and the same pixel count reads smaller than on a
-landscape TV-style canvas.
-
-| token                     | landscape baseline | **portrait target** | scale         |
-| ------------------------- | ------------------ | ------------------- | ------------- |
-| title (h1/h2 hero)        | 64–96px            | **88–132px**        | ×1.35         |
-| detail / body             | 24–30px            | **30–40px**         | ×1.30         |
-| kicker / chip label       | 14–16px            | **18–22px**         | ×1.30         |
-| timecode / meta           | 12–14px            | **16–18px**         | ×1.30         |
-| data block primary number | 48–60px            | **64–88px**         | ×1.40         |
-| line-height multiplier    | 1.05–1.5           | same                | (don't scale) |
-
-**Rule of thumb:** `portraitPx = round(landscapePx × 1.3)`, then floor
-to a nearby 4px multiple for visual rhythm. Hero headlines may go up to
-×1.4; small meta text stays at ×1.2 to avoid crowding.
-
-Padding **shrinks slightly** in portrait — the card is narrower so big
-landscape padding (40–64px) eats too much width. Use 24–36px horizontal
-padding in portrait.
-
-If you're producing a single card that must work in **both** layouts,
-prefer a `@container` query on the card root over hard-coding sizes:
-
-```css
-.card[data-card-id="X"] .root {
-  container-type: inline-size;
-}
-.card[data-card-id="X"] .title {
-  font-size: clamp(64px, 8.5cqi, 132px);
-}
-.card[data-card-id="X"] .detail {
-  font-size: clamp(24px, 3.2cqi, 40px);
-}
-```
-
-But for most cards, a single layout choice is fine — just pick the size
-table column that matches the storyboard's `layout` field.
-
-#### Available `data-anim` Kinds
-
-This list is closed, and deliberately so: a card is an HTML fragment whose motion this
-skill compiles into the shared overlay timeline in Step 9 (see the GSAP mapping table
-there). That is why this workflow does not search the HyperFrames component registry the
-way the composition workflows do — `npx hyperframes catalog` returns standalone
-compositions that carry their own timeline, and a card has no place to mount one. Reach a
-look the kinds below cannot express with plain CSS inside the card's scoped `<style>`.
-
-| kind            | use for             | key params                                                                                      |
-| --------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
-| `fade-in`       | enter               | `at`, `duration`, `ease?`                                                                       |
-| `fade-out`      | exit                | `at`, `duration`, `ease?`                                                                       |
-| `slide-in`      | slide enter         | `at`, `duration`, `from=left\|right\|top\|bottom`, `distance`                                   |
-| `kinetic-chars` | per-char pop        | `at`, `duration`, `stagger`, `pattern=pop\|fade` — element needs `<span class="char">` children |
-| `typewriter`    | per-char fade       | same as kinetic-chars but slower default stagger                                                |
-| `count-up`      | animate number      | `at`, `duration`, `from`, `to`, `format=.0f\|.1f\|.2f\|,d`                                      |
-| `draw-path`     | SVG path reveal     | `at`, `duration` — element should be a `<path>`                                                 |
-| `grow-y`        | bar height          | `at`, `duration`, `target-h` (px) — element starts `height:0`                                   |
-| `grow-x`        | bar width           | `at`, `duration`, `target-w` (px) — element starts `width:0`                                    |
-| `scale-pop`     | pop entrance        | `at`, `duration`                                                                                |
-| `blur-in`       | unfocused → focused | `at`, `duration`                                                                                |
-| `mask-reveal`   | clip reveal         | `at`, `duration`, `direction=left\|right\|top\|bottom`                                          |
-| `morph-to`      | tween any CSS       | `at`, `duration`, `props='{...JSON...}'`                                                        |
-
-`data-anim-at` is **seconds relative to the card's startSec** — when you
-compile each declaration into the GSAP timeline in Step 9, add the
-card's `startSec` to get the absolute time and quantize to 1/fps.
-
-### 9. Assemble the Composition HTML
-
-Stage the assets and write `$WORK_DIR/public/index.html`:
-
-```bash
-# SKILL_DIR is injected by the host ("Base directory for this skill: …")
-SKILL_DIR="<SKILL_DIR>"
-
-mkdir -p "$WORK_DIR/public/fonts" "$WORK_DIR/public/vendor" "$WORK_DIR/public/cards"
-cp -n "$SKILL_DIR/assets/fonts/"*            "$WORK_DIR/public/fonts/"
-cp -n "$SKILL_DIR/assets/vendor/gsap.min.js" "$WORK_DIR/public/vendor/"
-# stage the input video — RE-ENCODE with dense keyframes. Sources with a sparse GOP
-# (keyframe interval > ~1s) freeze on seek in the renderer (a frozen frame under the
-# overlays); -g / -keyint_min set to your composition fps make every frame seekable.
-# (Set both to your fps — 30 shown; use 24/25/60 to match.)
-ffmpeg -y -i "$VIDEO_PATH" -c:v libx264 -crf 18 -g 30 -keyint_min 30 \
-  -pix_fmt yuv420p -movflags +faststart -c:a aac "$WORK_DIR/public/input-video.mp4"
-```
-
-#### Composition Template
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <style>
-      @font-face {
-        font-family: "Caveat";
-        src: url("fonts/Caveat-400-latin.woff2") format("woff2");
-        font-weight: 400;
-        font-display: block;
-      }
-      @font-face {
-        font-family: "Caveat";
-        src: url("fonts/Caveat-700-latin.woff2") format("woff2");
-        font-weight: 700;
-        font-display: block;
-      }
-      @font-face {
-        font-family: "LXGW WenKai TC";
-        src: url("fonts/LXGWWenKaiTC-400-latin.woff2") format("woff2");
-        font-weight: 400;
-        font-display: block;
-      }
-      @font-face {
-        font-family: "Inter";
-        src: url("fonts/Inter-400-latin.woff2") format("woff2");
-        font-weight: 400;
-        font-display: block;
-      }
-      @font-face {
-        font-family: "Inter";
-        src: url("fonts/Inter-700-latin.woff2") format("woff2");
-        font-weight: 700;
-        font-display: block;
-      }
-      @font-face {
-        font-family: "Virgil";
-        src: url("fonts/Virgil.woff2") format("woff2");
-        font-display: block;
-      }
-
-      :root {
-        /* Pick from the themeId palette table in Step 7 — example: classic */
-        --bg: #fff9e3;
-        --text: #1e1e1e;
-        --accent-0: #1971c2;
-        --accent-1: #e03131;
-        --accent-2: #2f9e44;
-        --accent-3: #e8590c;
-        --accent-4: #9c36b5;
-        --font-family: "Caveat", "LXGW WenKai TC", serif;
-      }
-      * {
-        box-sizing: border-box;
-      }
-      /* Body font-family MUST list concrete font names (not just var(--font-family)) —
-   the HyperFrames renderer's static analyzer doesn't expand CSS variables when
-   resolving fonts, so a var-only chain triggers `font_family_without_font_face`
-   lint and falls back to a generic. Use the concrete chain here; cards that
-   want the theme font can still reference var(--font-family) internally. */
-      html,
-      body {
-        margin: 0;
-        padding: 0;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-        background: #000;
-        font-family: "Inter", "Caveat", "LXGW WenKai TC", ui-sans-serif, system-ui, sans-serif;
-      }
-      #stage {
-        position: relative;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-      }
-
-      /* video-wrapper holds the source video. Its position / size are animated
-   over time by the master timeline (one tween per layout transition). */
-      .video-wrapper {
-        position: absolute;
-        left: 0;
-        top: 0;
-        width: 1920px;
-        height: 1080px;
-        overflow: hidden;
-        border-radius: 0;
-        box-shadow: none;
-      }
-      .video-wrapper video {
-        width: 100%;
-        height: 100%;
-        object-fit: cover;
-      }
-
-      .card-host {
-        position: absolute;
-        pointer-events: none;
-        overflow: hidden;
-      }
-      .card-host .card {
-        position: relative;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-      }
-      .card-host .char {
-        display: inline-block;
-        visibility: visible;
-      }
-
-      /* Subtle drop shadow + rounded corners for non-fullscreen video framings */
-      .video-wrapper.framed {
-        border-radius: 16px;
-        box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
-      }
-    </style>
-  </head>
-  <body>
-    <div
-      id="stage"
-      data-composition-id="talking-head-recut"
-      data-start="0"
-      data-duration="121.2"
-      data-fps="30"
-      data-width="1920"
-      data-height="1080"
-    >
-      <!-- Layer 1: source video — initial position matches card-01's layout -->
-      <div class="video-wrapper" id="video-wrap">
-        <video
-          id="bg-video"
-          src="input-video.mp4"
-          muted
-          playsinline
-          data-start="0"
-          data-duration="121.2"
-          data-track-index="1"
-        ></video>
-      </div>
-      <!-- Preserve the source program audio while the visual video stays muted. -->
-      <audio
-        id="source-audio"
-        src="input-video.mp4"
-        data-start="0"
-        data-duration="121.2"
-        data-track-index="10"
-        data-volume="1"
-      ></audio>
-
-      <!-- Layer 2: each card-host sits at the bounds dictated by its layout. -->
-      <!-- IMPORTANT: every card-host MUST carry BOTH "card-host" and "clip" classes. -->
-      <!--   - "card-host"  → our positioning + pointer-events styles                 -->
-      <!--   - "clip"       → the marker Studio and the linter use to recognise a     -->
-      <!--                    clip. Visibility itself comes from data-start /         -->
-      <!--                    data-duration, which the runtime honours with or        -->
-      <!--                    without this class                                      -->
-      <!--                    (lint: timed_element_missing_clip_class, a warning).    -->
-      <!-- Example: card-01 with zone="fullscreen" → card-host covers (0,0,1920,1080) -->
-      <div
-        class="card-host clip"
-        data-card-id="card-01"
-        data-start="1.0000"
-        data-duration="6.5000"
-        data-track-index="2"
-        style="left:0;top:0;width:1920px;height:1080px;visibility:hidden;opacity:0;"
-      >
-        <!-- paste the contents of public/cards/card-01.html here -->
-      </div>
-
-      <!-- Example: card-02 with zone="side-panel" (split composition layout) → card on left half -->
-      <div
-        class="card-host clip"
-        data-card-id="card-02"
-        data-start="8.0000"
-        data-duration="12.0000"
-        data-track-index="2"
-        style="left:0;top:0;width:960px;height:1080px;visibility:hidden;opacity:0;"
-      >
-        <!-- card-02 HTML -->
-      </div>
-
-      <!-- ...one "card-host clip" per card with inline bounds matching resolveZoneBounds(card.zone)... -->
-
-      <script src="vendor/gsap.min.js"></script>
-      <script>
-        (function () {
-          // count-up formatter helper
-          window.__fmt = function (v, fmt) {
-            if (typeof fmt === "string" && /^\.[0-9]+f$/.test(fmt)) {
-              return Number(v).toFixed(Number(fmt.slice(1, -1)));
-            }
-            if (fmt === ",d") return Math.round(v).toLocaleString();
-            return String(Math.round(v));
-          };
-
-          const tl = window.gsap.timeline({ paused: true });
-
-          // ── Card lifecycle (one block per card) ──
-          // Example for card-01 [1.0, 7.5] with kinetic-chars at +0.3, grow-x at +0.65:
-
-          // Enter (fade in over 0.4s)
-          tl.set('.card-host[data-card-id="card-01"]', { visibility: "visible" }, 1.0);
-          tl.fromTo(
-            '.card-host[data-card-id="card-01"]',
-            { opacity: 0 },
-            { opacity: 1, duration: 0.4, ease: "power2.out" },
-            1.0,
-          );
-
-          // Card-internal anims (compile each data-anim-* declaration here)
-          tl.from(
-            '.card[data-card-id="card-01"] #card-01-title .char',
-            { opacity: 0, y: 8, scale: 0.8, duration: 0.5, ease: "power2.out", stagger: 0.04 },
-            1.3,
-          );
-          tl.fromTo(
-            '.card[data-card-id="card-01"] #card-01-line',
-            { width: 0 },
-            { width: 420, duration: 0.5, ease: "power2.out" },
-            1.65,
-          );
-
-          // Exit (fade out over 0.35s, ending at endSec)
-          tl.to(
-            '.card-host[data-card-id="card-01"]',
-            { opacity: 0, duration: 0.35, ease: "power2.in" },
-            7.15,
-          );
-          tl.set('.card-host[data-card-id="card-01"]', { visibility: "hidden" }, 7.5);
-
-          // ── Video framing transitions ──
-          // When the next card uses a different composition layout, animate the
-          // video-wrapper to its new bounds. Example: card-01 = fullscreen
-          // (video hidden behind), card-02 = split composition (zone="side-panel"
-          // → video on right, card on left).
-
-          // Card-02 enters at 8.0s with the split composition. Animate video to
-          // the right half during the card-01 → card-02 gap (between 7.5 and 8.0s).
-          tl.set("#video-wrap", { className: "video-wrapper framed" }, 7.5);
-          tl.to(
-            "#video-wrap",
-            { left: 960, top: 0, width: 960, height: 1080, duration: 0.6, ease: "power2.inOut" },
-            7.5,
-          );
-
-          // Card-02 enter — same pattern as card-01
-          tl.set('.card-host[data-card-id="card-02"]', { visibility: "visible" }, 8.0);
-          tl.fromTo(
-            '.card-host[data-card-id="card-02"]',
-            { opacity: 0 },
-            { opacity: 1, duration: 0.4, ease: "power2.out" },
-            8.0,
-          );
-          // ...card-02 internal anims...
-
-          // ── repeat for each card; if the NEXT card's layout differs,
-          //    insert another tl.to('#video-wrap', ...) tween before its enter ──
-
-          window.__timelines = window.__timelines || {};
-          window.__timelines["talking-head-recut"] = tl;
-        })();
-      </script>
-    </div>
-  </body>
-</html>
-```
-
-#### GSAP Statement Cheat Sheet
-
-Compile each `data-anim` attribute into a GSAP statement. Times are
-**absolute seconds** = card.startSec + data-anim-at, quantized to 1/fps.
-Selector is `.card[data-card-id="X"] #elementId`.
-
-| data-anim                       | GSAP statement template                                                                                                                                                                                            |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `fade-in`                       | `tl.fromTo(SEL, { opacity: 0 }, { opacity: 1, duration: D, ease: 'power2.out' }, T);`                                                                                                                              |
-| `fade-out`                      | `tl.to(SEL, { opacity: 0, duration: D, ease: 'power2.in' }, T);`                                                                                                                                                   |
-| `slide-in` (from=left, dist=80) | `tl.fromTo(SEL, { opacity: 0, x: -80 }, { opacity: 1, x: 0, duration: D, ease: 'power2.out' }, T);`                                                                                                                |
-| `kinetic-chars` (pop)           | `tl.from(SEL + ' .char', { opacity: 0, y: 8, scale: 0.8, duration: D, ease: 'power2.out', stagger: S }, T);`                                                                                                       |
-| `count-up`                      | `(function(){const o={v:FROM};tl.to(o,{v:TO,duration:D,ease:'power2.out',onUpdate:function(){const el=document.querySelector(SEL);if(el)el.textContent=__fmt(o.v,'FMT');}},T);})();`                               |
-| `draw-path`                     | `(function(){const el=document.querySelector(SEL);if(el){const L=el.getTotalLength();tl.set(SEL,{strokeDasharray:L,strokeDashoffset:L},T);tl.to(SEL,{strokeDashoffset:0,duration:D,ease:'power2.inOut'},T);}})();` |
-| `grow-x` (target-w=W)           | `tl.fromTo(SEL, { width: 0 }, { width: W, duration: D, ease: 'power2.out' }, T);`                                                                                                                                  |
-| `grow-y` (target-h=H)           | `tl.fromTo(SEL, { height: 0 }, { height: H, duration: D, ease: 'power2.out' }, T);`                                                                                                                                |
-| `scale-pop`                     | `tl.fromTo(SEL, { opacity: 0, scale: 0.6 }, { opacity: 1, scale: 1, duration: D, ease: 'back.out(1.6)' }, T);`                                                                                                     |
-| `mask-reveal` (direction=left)  | `tl.fromTo(SEL, { clipPath: 'inset(0 100% 0 0)' }, { clipPath: 'inset(0 0 0 0)', duration: D, ease: 'power2.inOut' }, T);`                                                                                         |
-
-Quantize: `T = Math.round(absSec * fps) / fps`. At 30fps the smallest
-step is `1/30 ≈ 0.0333s`; rounding to 4 decimals (`.toFixed(4)`) is fine
-inside the JS literal.
-
-#### Video Framing Reference (per `layout` value)
-
-The selector for the video container is `#video-wrap`. Animate its
-bounds between cards using `tl.to('#video-wrap', { ...bounds }, T)`.
-Initial bounds should be set inline on the element to match card-01's
-layout. Pick a transition duration of 0.5–0.7s with `ease: 'power2.inOut'`.
-
-**Decorative frames** (`clean` / `hairline` / `polaroid`) sit as a
-**sibling** of `#video-wrap` and follow it through layout transitions.
-See
-[`references/frames/`](references/frames/) for each frame's placement
-HTML, suggested CSS, and which layouts it pairs with. Quick rule:
-`overlay` layout suppresses decorative frames (the full-bleed video
-clashes with chrome); PiP layouts already have their own pill treatment
-(border-radius + white ring + shadow), so add a decorative frame only on
-top of `split` / `stack`.
-
-**GSAP target lookup table** for `#video-wrap` per composition layout
-(landscape 1920×1080 — for portrait & 4:5 see `references/layouts/*.html`
-which list all three ratios):
-
-| composition layout                   | typical card.zone | `#video-wrap` GSAP target                                                 | extra css class                            |
-| ------------------------------------ | ----------------- | ------------------------------------------------------------------------- | ------------------------------------------ |
-| `split`                              | `side-panel`      | `{ left: 960, top: 0, width: 960, height: 1080 }`                         | —                                          |
-| `stack`                              | `lower-third`     | `{ left: 14, top: 14, width: 1892, height: 548 }` (top 52%)               | —                                          |
-| `pip` (bottom-right)                 | `fullscreen`      | `{ left: 1480, top: 760, width: 400, height: 300 }`                       | `pip-pill` (border-radius + ring + shadow) |
-| `pip` (top-left)                     | `fullscreen`      | `{ left: 40, top: 40, width: 400, height: 300 }`                          | `pip-pill`                                 |
-| `overlay` (video full-bleed)         | `video-overlay`   | `{ left: 0, top: 0, width: 1920, height: 1080 }` (no change from default) | —                                          |
-| **hide video** (pure-graphic moment) | `fullscreen`      | `{ opacity: 0 }` (or move off-canvas)                                     | —                                          |
-
-To toggle the pip-pill chrome (border-radius + white ring + drop shadow)
-when entering or leaving a pip moment:
-
-```js
-// Enter pip — add chrome
-tl.set("#video-wrap", { className: "video-wrapper pip-pill" }, T);
-tl.to(
-  "#video-wrap",
-  { left: 1480, top: 760, width: 400, height: 300, duration: 0.6, ease: "power2.inOut" },
-  T,
-);
-
-// Leave pip — back to clean full-bleed
-tl.set("#video-wrap", { className: "video-wrapper" }, T_NEXT);
-tl.to(
-  "#video-wrap",
-  { left: 0, top: 0, width: 1920, height: 1080, duration: 0.6, ease: "power2.inOut" },
-  T_NEXT,
-);
-```
-
-**Card-host bounds match the zone**. Resolve the card's `zone` into
-pixel bounds using the table at the top of Step 6, then write those
-into the card-host's inline `style="left:Xpx;top:Ypx;width:Wpx;
-height:Hpx;..."`. For `video-overlay` zone (overlay recipe), the
-card-host fills the full canvas — your CSS inside `.card .root`
-decides where the actual visible card sits.
-
-#### HyperFrames Layout / Animation QA Rules
-
-- Build each card's static hero frame first: the moment where the card is fully visible and readable.
-- Confirm video, cards, subtitles/captions, and diagrams do not unintentionally overlap.
-- Confirm hidden video areas are clipped by the frame and not visible outside intended bounds.
-- Register one paused master timeline as `window.__timelines["talking-head-recut"]`.
-- Build timelines synchronously at page load; no `async`, `setTimeout`, Promises, or media `play()` calls.
-- Do not use `Math.random()` or `Date.now()` in render paths.
-- Do not use `repeat: -1`; calculate finite repeats from the video duration.
-- Prefer GSAP transforms and opacity (`x`, `y`, `scale`, `rotation`, `opacity`) over layout properties (`top`, `left`, `width`, `height`) for motion.
-- Animate wrappers such as `#video-wrap`, not the video element dimensions directly.
-- Avoid animating the same property on the same element from multiple timelines at the same time.
-- Use `data-track-index`, not `data-layer`; use `data-duration`, not `data-end`.
-- Every timed element (`card-host`, sub-composition, etc.) should include `class="clip"` alongside its own classes — e.g. `class="card-host clip"`. Visibility itself is driven by `data-start` / `data-duration`: the runtime gates every `[data-start]` element to its window whether or not this class is present. `.clip` is the marker Studio and the GSAP clip-ownership rules read to recognise a clip, so leaving it off makes the element harder to edit and to lint (lint: `timed_element_missing_clip_class`, a warning).
-- For body / global `font-family`, list **concrete font names** (`'Inter', 'Caveat', …`) — not a CSS variable like `var(--font-family)`. The HyperFrames font resolver doesn't expand CSS vars during static analysis (lint: `font_family_without_font_face`). Cards may still use `var(--font-family)` internally since their `@font-face` declarations are loaded.
-
-### 10. Render to MP4
-
-```bash
-cd "$WORK_DIR"
-PRODUCER_BROWSER_GPU_MODE=hardware npx hyperframes render public \
-  --skill=talking-head-recut \
-  -o output.mp4 \
-  --fps 30
-```
-
-`hyperframes render <dir>` reads `<dir>/index.html` and produces the MP4.
-The canonical composition keeps the visual `<video>` muted and mounts the same
-source as the root `#source-audio` track, so the rendered MP4 preserves the
-talking-head audio without a manual remux. This uses a separate audio track
-rather than `data-has-audio="true"` so its volume and ducking remain independently
-controllable on the timeline.
-The flag `PRODUCER_BROWSER_GPU_MODE=hardware` (or `--browser-gpu`) is
-strongly recommended on macOS — software-only Chrome rendering times out
-on most laptops.
-
-For a sanity check before the full render, capture a single frame at a
-specific timestamp:
-
-```bash
-npx hyperframes snapshot public --at 5    # → public/snapshots/frame-00-at-5s.png (a single --at ignores --out)
-```
-
-### 11. Report Results
-
-Tell the user:
-
-- Work directory path
-- `storyboard.json` (the card outline you designed)
-- `public/cards/*.html` (one HTML per card)
-- `public/index.html` (the assembled composition)
-- `output.mp4` (the final video)
-- ASR provider used
-- Card count + how you chose them (in 1 sentence)
-- Any missing keys or quality caveats
-
-**Optional live preview (on request only).** The clip plays unchanged inside `public/index.html` with the overlays on top, so it previews faithfully. **Don't open it during the run.** When the user asks, start a long-lived server **after** render and report the URL:
-
-```bash
-(cd "$WORK_DIR/public" && npx hyperframes preview --background)   # or `npx hyperframes play` for a shareable link
-```
-
-Do not delete the work directory unless the user asks.
+For an existing project, preserve its files and dependencies. DSH plugin management owns this installed skill bundle. The upstream plugin launcher pins HyperFrames 0.8.207 and suppresses standalone skill installation; run it in the user's project directory. This entry preserves the previous DSH skill name while using the current workflow.