diff --git a/docs/concepts/compositions.mdx b/docs/concepts/compositions.mdx
index fecb3d2ecb..d68e32e3ae 100644
--- a/docs/concepts/compositions.mdx
+++ b/docs/concepts/compositions.mdx
@@ -37,6 +37,8 @@ You can embed one composition inside another in two ways: loading from an extern
   <Tab title="External file">
     Reference another HTML file with `data-composition-src`. The framework automatically fetches the file, extracts the `<template>` content, mounts it, executes scripts, and registers the timeline.
 
+    `data-composition-src` paths resolve relative to the **project root**, not the referencing file — a nested composition one level deep still writes `compositions/foo.html`, never `../compositions/foo.html`.
+
     ```html index.html
     <div
       id="el-5"
diff --git a/docs/docs.json b/docs/docs.json
index 986d6b0034..52e32f5f9a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -71,6 +71,60 @@
               "concepts/determinism"
             ]
           },
+          {
+            "group": "Prompt Guide",
+            "pages": [
+              "prompting/overview",
+              {
+                "group": "Fundamentals",
+                "pages": [
+                  "prompting/anatomy",
+                  "prompting/examples",
+                  "prompting/specification-dial",
+                  "prompting/vocabulary",
+                  "prompting/iterating",
+                  "prompting/rules-and-anti-patterns"
+                ]
+              },
+              {
+                "group": "Making it look good",
+                "pages": [
+                  "prompting/visual-specs",
+                  "prompting/motion",
+                  "prompting/generated-artwork",
+                  "prompting/recreating-references"
+                ]
+              },
+              {
+                "group": "By video type",
+                "pages": [
+                  "prompting/product-launch",
+                  "prompting/explainers",
+                  "prompting/code-and-prs",
+                  "prompting/music-and-slideshows",
+                  "prompting/captions-and-talking-heads",
+                  "prompting/motion-graphics"
+                ]
+              },
+              {
+                "group": "By feature",
+                "pages": [
+                  "prompting/transitions",
+                  "prompting/captions-catalog",
+                  "prompting/overlays-and-lower-thirds",
+                  "prompting/code-blocks",
+                  "prompting/data-and-maps",
+                  "prompting/vfx-and-liquid-glass",
+                  "prompting/rendering-and-output",
+                  "prompting/editing-existing-videos",
+                  "prompting/media-and-audio",
+                  "prompting/variables-and-templating",
+                  "prompting/runtimes-and-3d",
+                  "prompting/design-systems"
+                ]
+              }
+            ]
+          },
           {
             "group": "Guides",
             "pages": [
@@ -86,7 +140,6 @@
               "guides/copilot-cli",
               "guides/claude-design",
               "guides/open-design",
-              "guides/prompting",
               "guides/hyperframes-vs-remotion",
               "guides/gsap-animation",
               "guides/keyframes",
@@ -410,5 +463,11 @@
     "socials": {
       "github": "https://github.com/heygen-com/hyperframes"
     }
-  }
-}
+  },
+  "redirects": [
+    {
+      "source": "/guides/prompting",
+      "destination": "/prompting/overview"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx
deleted file mode 100644
index 49907ccc6a..0000000000
--- a/docs/guides/prompting.mdx
+++ /dev/null
@@ -1,298 +0,0 @@
----
-title: Prompt Guide
-description: "How to prompt Claude Code, Cursor, Codex, Google Antigravity, GitHub Copilot CLI, and other AI agents to author Hyperframes compositions — with copy-pasteable examples and vocabulary tables."
----
-
-Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage.
-
-## One-time setup
-
-Install the skills in your project (or globally for your agent):
-
-```bash
-npx skills add heygen-com/hyperframes
-```
-
-The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow.
-
-**Core skills — install all of these**
-
-| Slash command           | What it loads                                                              |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `/hyperframes`          | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow |
-| `/hyperframes-core`     | Composition contract — HTML structure, `data-*` attributes, clips, tracks  |
-| `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) |
-| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats   |
-| `/hyperframes-cli`      | Dev-loop CLI — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `doctor` |
-| `/media-use`    | Asset preprocessing — `tts`, `transcribe`, `remove-background`             |
-| `/hyperframes-registry` | Block and component installation via `hyperframes add`                     |
-| `/general-video`        | The general authoring workflow — fallback for any video that doesn't match a specific workflow below |
-
-**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)
-
-| Slash command            | Input → output                                                              |
-| ------------------------ | --------------------------------------------------------------------------- |
-| `/product-launch-video`  | A product URL / brief / script → launch or promo video                      |
-| `/website-to-video`      | A general website / URL → a video of the site (tour / showcase / social clip) |
-| `/faceless-explainer`    | Arbitrary text (no URL) → faceless explainer with its own TTS narration     |
-| `/pr-to-video`           | A GitHub PR → code-change explainer                                         |
-| `/embedded-captions`     | An existing talking-head video → the same footage with captions / subtitles |
-| `/talking-head-recut`      | An existing talking-head video → footage packaged with designed graphic cards |
-| `/motion-graphics`       | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
-| `/music-to-video`        | A music track (audio file or video) → a beat-synced video (lyric, slideshow, or kinetic promo) |
-| `/slideshow`             | A presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching |
-| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML         |
-
-<Tip>
-  To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
-</Tip>
-
-## Claude Design
-
-Claude Design uses a different setup. Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub (click the ↓ button), then **attach it to your chat** (don't paste the URL — file attachments produce better output):
-
-```text
-Use the attached skill. 25-second LinkedIn video for my startup.
-
-Problem: Sales teams waste 3 hours/day on manual CRM updates.
-Solution: AutoCRM — AI that logs every call, email, and meeting.
-Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
-CTA: autocrmhq.com
-```
-
-Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.
-
-## The two prompt shapes
-
-Most successful Hyperframes prompts fall into one of two shapes.
-
-### Cold start — describe the video
-
-You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head.
-
-> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
-
-> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
-
-Cold-start prompts work best when you specify:
-
-- **Duration** (e.g. "10 seconds", "30s", "5 scenes of 3s each")
-- **Aspect ratio** ("16:9", "9:16 vertical", "1:1 square") — defaults to 1920x1080 otherwise
-- **Mood / style** ("minimal Swiss grid", "warm grain analog", "high-energy social")
-- **Key elements** (title, lower third, captions, background video, music)
-
-### Warm start — turn context into a video
-
-You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where Hyperframes shines because the agent does the research/summarization step *and* the production step in one flow.
-
-> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`.
-
-> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.
-
-> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`.
-
-> Turn this CSV into an animated bar chart race using `/hyperframes`.
-
-Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy.
-
-## Iterating
-
-Hyperframes is a conversation. After the first render, talk to the agent the way you'd talk to a video editor — don't re-prompt from scratch:
-
-> Make the title 2x bigger.
-
-> Swap to dark mode.
-
-> Add a fade-out at the end and a lower third at 0:03 with my name and title.
-
-> The captions are too small and they overlap the lower third. Move them up and shrink them.
-
-> Replace the background music with `assets/track.mp3`.
-
-The agent already has the composition open and the skills loaded — small targeted edits produce better results than long re-specifications.
-
-## Vocabulary that changes output
-
-The skills map natural-language adjectives to specific framework settings. Using the right word gets you the right result without specifying technical details.
-
-### Motion & easing
-
-Describe how motion should *feel* and the agent picks the matching GSAP ease:
-
-| Say this    | Agent uses       | Feels like                     |
-| ----------- | ---------------- | ------------------------------ |
-| smooth      | `sine` / `power1`| Natural deceleration           |
-| snappy      | `power4.out`     | Quick and decisive             |
-| bouncy      | `back.out`       | Overshoots then settles        |
-| springy     | `elastic.out`    | Oscillates into place          |
-| dramatic    | `expo.out`       | Fast start, long glide         |
-| dreamy      | `sine.inOut`     | Slow, symmetrical              |
-
-**Timing shorthand:** fast (0.2s) = energy, medium (0.4s) = professional, slow (0.6s) = luxury, very slow (1–2s) = cinematic.
-
-### Caption tones
-
-Describe the *energy* of your captions and the agent picks matching typography, size, and animation:
-
-| Tone         | Typography             | Animation    | Size range |
-| ------------ | ---------------------- | ------------ | ---------- |
-| Hype         | Heavy weight fonts     | Scale-pop    | 72–96px    |
-| Corporate    | Clean sans-serif       | Fade + slide | 56–72px    |
-| Tutorial     | Monospace              | Typewriter   | 48–64px    |
-| Storytelling | Serif                  | Slow fade    | 44–56px    |
-| Social       | Rounded, playful       | Bounce       | 56–80px    |
-
-```
-"Hype-style captions with scale-pop"
-"Calm, elegant subtitles with slow fades"
-"Karaoke-style word highlighting"
-```
-
-Per-word styling also works:
-
-```
-"Make brand names larger with accent color"
-"Add bounce to emotional keywords"
-"Highlight numbers differently"
-```
-
-### Transitions
-
-Every multi-scene composition benefits from transitions. Describe the energy level:
-
-| Energy  | CSS option       | Shader option       |
-| ------- | ---------------- | ------------------- |
-| Calm    | Blur crossfade   | Cross-warp morph    |
-| Medium  | Push slide       | Whip pan            |
-| High    | Zoom through     | Glitch, ridged burn |
-
-Or describe by mood:
-
-```
-"Warm transitions for this wellness brand"
-"Cold, clinical transitions for tech"
-"Playful bouncy transitions"
-"Dramatic zoom for the reveal"
-```
-
-### Audio-reactive animation
-
-Map audio frequency bands to visual properties. The agent uses these defaults:
-
-| Audio band | Maps to   | Visual effect       |
-| ---------- | --------- | ------------------- |
-| Bass       | `scale`   | Pulse on the beat   |
-| Treble     | `glow`    | Shimmer intensity   |
-| Amplitude  | `opacity` | Breathing           |
-| Mids       | `borderRadius` | Shape morphing |
-
-```
-"Make the text pulse with the beat"
-"Add bass-driven scale to the logo"
-"Create glow that responds to treble"
-```
-
-<Tip>
-  Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%).
-</Tip>
-
-### Marker highlights
-
-Hand-drawn emphasis effects for text:
-
-| Mode        | Effect             | Best for      |
-| ----------- | ------------------ | ------------- |
-| `highlight` | Marker sweep       | Key phrases   |
-| `circle`    | Hand-drawn ellipse | Single words  |
-| `burst`     | Radiating lines    | Hype moments  |
-| `scribble`  | Chaotic scratch    | Rough emphasis|
-| `sketchout` | Cross-hatch lines       | Crossing out |
-
-```
-"Add a marker highlight sweep on 'revolutionary'"
-"Circle this keyword with hand-drawn effect"
-"Add burst lines around 'AMAZING'"
-```
-
-### Text-to-speech voices
-
-HyperFrames supports three TTS providers: **HeyGen** (Starfish voices, requires sign-in via `npx hyperframes auth`), **ElevenLabs** (requires API key), and **Kokoro** (free, runs locally, no API key needed). The agent asks which provider to use — or picks automatically in autonomous mode. Describe the content and the agent picks a voice, or request one directly:
-
-| Content type  | Kokoro voices              |
-| ------------- | -------------------------- |
-| Product demo  | `af_heart`, `af_nova`      |
-| Tutorial      | `am_adam`, `bf_emma`       |
-| Marketing     | `af_sky`, `am_michael`     |
-
-```
-"Generate narration for this script"
-"Create voiceover with a professional female voice"
-"Add TTS with British male voice at 1.1x speed"
-"Use HeyGen TTS for this narration"
-```
-
-### Rendering quality
-
-| Quality    | Use for                  |
-| ---------- | ------------------------ |
-| `draft`    | Fast iteration           |
-| `standard` | Review and feedback      |
-| `high`     | Final delivery           |
-
-```
-"Quick draft render"
-"Render at high quality"
-"Export as transparent WebM"
-```
-
-## Rules to know
-
-The skills enforce these automatically, but if you hand-edit compositions or debug issues, these are the rules that matter:
-
-1. **Register all timelines** on `window.__timelines` — the renderer can't seek animations it doesn't know about.
-2. **Video elements must be `muted`** — audio goes in separate `<audio>` elements so the renderer can mix it.
-3. **No `Math.random()`** — random values produce different frames on each render, breaking determinism. Use a seeded PRNG (e.g. mulberry32) if you need pseudo-random values.
-4. **Synchronous timeline construction** — no `async`/`await` or `fetch()` during GSAP timeline setup.
-5. **Timed elements need `class="clip"`** — plus `data-start`, `data-duration`, and `data-track-index`.
-6. **Add entrance animations to every scene** — elements appearing without animation feel broken on video.
-7. **Add transitions between scenes** — jump cuts between scenes are almost always unintentional in composed video.
-
-<Warning>
-  Rules 1–5 are technical requirements — breaking them produces incorrect renders. Rules 6–7 are best practices that the skills apply by default. You can override them when you have a reason to.
-</Warning>
-
-## Anti-patterns
-
-Things that cause friction (or wrong output):
-
-- **Don't ask for React / Vue components.** Hyperframes compositions are plain HTML with `data-*` attributes and a GSAP timeline. Asking for "a React component for the intro" forces the agent to translate later.
-- **Don't ask for 4K or 60fps unless you need it.** Defaults (1920×1080, 30fps) render fast and look great. Higher specs slow rendering meaningfully.
-- **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.).
-- **Don't paste long error logs into the prompt without context.** Run `npx hyperframes lint` and `npx hyperframes validate` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems).
-- **Don't assume the agent knows your assets.** Mention file paths explicitly (`assets/intro.mp4`, `assets/logo.png`) — the agent will check what's there but a hint speeds it up.
-
-## Recommended workflow
-
-1. `npx hyperframes init my-video` — scaffold a project (skills install automatically)
-2. Open the project in Claude Code (or Cursor / Codex)
-3. Prompt with `/hyperframes` and one of the shapes above
-4. `npx hyperframes preview` — watch in the browser as the agent edits
-5. Iterate with small targeted prompts
-6. `npx hyperframes render --output final.mp4` when you're happy
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Quickstart" icon="rocket" href="/quickstart">
-    Build and render your first video
-  </Card>
-  <Card title="Common Mistakes" icon="circle-exclamation" href="/guides/common-mistakes">
-    Pitfalls the linter can't catch
-  </Card>
-  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
-    Add fade, slide, scale, and custom animations
-  </Card>
-  <Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
-    50+ ready-to-use blocks and components
-  </Card>
-</CardGroup>
diff --git a/docs/prompting/anatomy.mdx b/docs/prompting/anatomy.mdx
new file mode 100644
index 0000000000..7ff58673fb
--- /dev/null
+++ b/docs/prompting/anatomy.mdx
@@ -0,0 +1,72 @@
+---
+title: Anatomy of a one-shot prompt
+description: "The six-part skeleton — route, spec, beats, copy, technique, negatives — that removes the decisions agents most often get wrong."
+---
+
+The [copy-paste examples](/prompting/examples) share one skeleton. Each part removes a decision agents most often get wrong on a first try:
+
+```text
+[route]      /motion-graphics
+[spec]       8-second 1920x1080 video.
+[beats]      Beat 1 (0-4s): ...  Beat 2 (4-5s): ...  Beat 3 (5-8s): ...
+[copy]       the exact on-screen text, quoted
+[technique]  Adapt the `code-typing` and `vfx-shatter` registry blocks.
+[negatives]  No narration, no image or media files.
+```
+
+- **Route** with a slash command — it loads the right workflow and the framework rules.
+- **Spec** duration and resolution up front. Defaults are 1920x1080 at 30fps.
+- **Beats** get timestamps. Include pacing instructions ("then hold on the blinking cursor") — agents skip breathing room unless told.
+- **Copy** is quoted exactly, with `/` for line breaks. Unquoted copy gets paraphrased.
+- **Technique**: name registry blocks exactly as they appear in the [catalog](/catalog/blocks/data-chart) — they're adapted starting points, not drop-ins (blocks ship with demo content the agent rewrites to your beat, so naming one pins the *technique*). Pin a technique wherever the default choice can fail (see [the specification dial](/prompting/specification-dial)).
+- **Negatives** close the gaps: "no narration" is not "silent" — if you want no sound at all, say "no audio". Avoid ambiguous phrases like "no external assets" (CDN-loaded runtimes are normal; say "no image or media files" if that's what you mean).
+
+Assembled:
+
+> /motion-graphics Make an 8-second 1920x1080 video. Beat 1 (0-4s): dark macOS terminal types "npx skills add heygen-com/hyperframes" character by character, then hold on the blinking cursor. Beat 2 (4-5s): the terminal shatters into fragments. Beat 3 (5-8s): bold white kinetic text on black slams in word by word, snappy: "YOU JUST MADE THIS / WITH HYPERFRAMES." Adapt the `code-typing` and `vfx-shatter` registry blocks; hand-author the kinetic text. No narration, no image or media files.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-anatomy-terminal.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+## The beat formula
+
+The skeleton above structures the *ask*. Inside each beat, describe the *content* with the same five slots every time:
+
+```text
+[element]   what's on screen        a giant number · the tweet card · "SHOWREEL"
+[motion]    what it does            counts up with an odometer roll · slides up · fades in per letter
+[layout]    where it sits           top-center · filling the lower half · bottom-right
+[style]     how it looks            dark navy, green accent · 8-bit pixel · thin geometric sans
+[timing]    when, inside the beat   at 1s · over 3s, easing out as it lands · staggered 0.1s apart
+```
+
+One sentence per element, slots in any order: *"a giant number **(element)** counts up to $4.2M with an odometer roll **(motion)**, easing out as it lands **(timing)**, centered **(layout)** in green on dark navy **(style)**."* Elements you don't describe, the agent designs — which is fine when you trust its taste and a drift risk when you don't (see [the specification dial](/prompting/specification-dial)).
+
+<Tip>
+  Beat-timestamped prompting — `Beat 2 (4-5s): ...` — is HyperFrames' native language. Diffusion video models bolt time segmentation on top of a single clip; here every beat maps directly to a timed clip in the composition, so per-beat descriptions translate losslessly. Use timestamps liberally.
+</Tip>
+
+## Common rewrites
+
+The fixes that come up most, as before/after pairs — each exists because of how the engine actually behaves:
+
+**Freezing the hold.** Compositions hold their final state, so a literal "hold" renders a frozen frame — the single biggest cheap-motion tell.
+- ❌ `then everything holds motionless to the end`
+- ✅ `then everything settles into a gentle ambient idle (breathing scale, slow drift)`
+
+**Simultaneity collisions.** Two things "at 4s" overlap for a few frames; the renderer does exactly what you wrote.
+- ❌ `at 4s the counter fades out and READY stamps in`
+- ✅ `the counter fades out fully by 4.2s; at 4.2s READY stamps in`
+
+**Vague negatives.** "No external assets" is ambiguous — CDN-loaded runtimes are normal infrastructure.
+- ❌ `no external assets`
+- ✅ `no image or media files`
+
+**Prose where copy belongs.** Unquoted text gets paraphrased; quoted text renders verbatim.
+- ❌ `show a tagline about shipping faster`
+- ✅ `tagline: "Ship faster."`
+
+**Format-blind numbers.** An odometer needs fixed digit columns — "counts $0 → $4.2M" forces an awkward "$0.0M" start.
+- ❌ `counts from $0 to $4.2M`
+- ✅ `counts up to $4.2M`
diff --git a/docs/prompting/captions-and-talking-heads.mdx b/docs/prompting/captions-and-talking-heads.mdx
new file mode 100644
index 0000000000..6672e7c0a6
--- /dev/null
+++ b/docs/prompting/captions-and-talking-heads.mdx
@@ -0,0 +1,87 @@
+---
+title: Captions and talking-head footage
+description: "Two ways to dress an existing talking-head clip — readable captions or designed graphic overlays — both leaving the footage itself untouched."
+---
+
+## Two things you can add to a talking head
+
+Both workflows take an existing talking-head / interview / podcast clip and add a layer on top. Neither edits the footage — no trims, no recolor, no reframe, no reorder. The clip plays untouched underneath; you're choosing what rides on top of it.
+
+| You want | Route | What it adds |
+| --- | --- | --- |
+| The spoken words as readable text | `/embedded-captions` | Captions / subtitles — a rail, with earned climax embeds |
+| Designed on-screen graphics synced to the talk | `/talking-head-recut` | Overlay cards — titles, lower-thirds, data callouts, quotes, PiP |
+
+If the words themselves need to read, you want captions. If you want a produced look — kinetic titles, a stat callout, a pull-quote card, the speaker shrunk into a corner while a chart fills the frame — you want overlay cards. When it's genuinely both, caption first, then package; they're siblings, not substitutes.
+
+`/embedded-captions` runs locally end to end — it transcribes and mattes the subject itself, no API key — and needs a **single-subject clip**. Multi-speaker clips or hard cuts get split per shot or refused, because the matte is one person.
+
+## Base prompt — captions
+
+Captions route by **identity**, not by mode. You pick one look from the catalog; the engine behind it is a lookup detail you never have to name. The default is a clean verbatim rail — `anchor` — with the occasional peak word composited behind the subject.
+
+> /embedded-captions Add captions to ./interview.mp4. Use the `anchor` identity — clean verbatim rail carrying the spoken words, readable lower-third. Promote the single hardest-hitting word to an embed behind the speaker; highlight one key word in each rail line. Keep the source aspect ratio. Footage stays untouched.
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/captions-anchor-rail.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above on generated avatar footage, unedited — one earned embed behind the speaker, everything else on the rail.*
+
+
+The rail carries most of the text; an **embed** is the scarce, earned peak — one big word matted behind the subject at the climax, never every line. Embedding the whole transcript is the most common mistake this skill guards against.
+
+## Base prompt — overlay cards
+
+> /talking-head-recut Package ./founder-clip.mp4 with designed graphic overlay cards synced to the transcript. 9:16 portrait, warm-paper style. Open with a fullscreen kicker + title hook, drop a lower-third when she names the company, a data callout card counting up the "200+ teams / $1.2M ARR" stat, and a pull-quote card for the strongest line. Speaker stays full-bleed under the cards; shrink her into a corner PiP while the data card holds. The clip plays untouched underneath.
+
+You describe the *cards* — their content, timing, and how the speaker shares the canvas with them (full-bleed, split, PiP, or glass overlay). The skill designs and writes each card; there's no fixed archetype list, so the overlays follow what the transcript actually says.
+
+## Variants
+
+<AccordionGroup>
+  <Accordion title="Cinematic caption embed (mood over verbatim)">
+    > /embedded-captions Cinematic captions on ./poem.mp4 — no rail, hero typography composited behind the speaker, words accumulating as a column. Use the `editorial` identity (lowercase-italic hero). One apex word per thought, air between them. 4:5. Never grade the footage.
+
+    Column-flow identities drop the rail and make everything embed-style — reach for them on poetic / social / "cinematic" asks where mood beats strict readability, never on an explainer where the words must read.
+  </Accordion>
+  <Accordion title="Bright-scene captions">
+    > /embedded-captions Add verbatim captions to ./outdoor-vlog.mp4. It's a bright daylight scene, so use the `ink` identity — near-black type printed onto the surface — not a light-on-bright look that washes out. Keep it a readable rail. 16:9.
+
+    Screen-blend cream looks wash out over bright backdrops (luminance > ~180); `ink` is built for bright surfaces. Match the identity to the scene rather than asking the engine to recolor a look.
+  </Accordion>
+  <Accordion title="VFX-grade themed captions">
+    > /embedded-captions Bring the energy on ./hype-clip.mp4 — I want the captions to hit hard. Use the `ordnance` identity: a stamped verbatim rail with a detonation apex. Rail carries the verbatim; the payoff line is the setpiece. 9:16.
+
+    Themed identities (`ordnance`, `terminal`, `stomp`, `neonsign`, `stardust`, …) are the answer to "make it explode / 特效 / like AE did it". Theme mode is the one place a register-gated reaction beat may touch the frame — applied after the matte composite so subject, text, and plate move as one — but the a-roll is still never graded.
+  </Accordion>
+  <Accordion title="Landscape data recut">
+    > /talking-head-recut Recut ./analyst-interview.mp4 as a 16:9 explainer with a clinical style. Split layout: speaker on the right, data cards on the left. Cards for each claim — a count-up for the headline number, a swiss-grid comparison for the two options, a terminal-style callout for the technical bit. Auto-pace the card count for a 5-minute clip. Footage untouched.
+
+    Layout (split / stack / pip / overlay) sets how speaker and cards share the canvas; card count auto-infers from duration and information density, with a floor of five so even a short clip has rhythm.
+  </Accordion>
+</AccordionGroup>
+
+## The knobs that matter
+
+**Identity and tone (captions).** One identity picks the entire look — surface, palette, motion, climax behavior. Route by content: explainer / interview / must-read words → a rail-carrying identity, with `anchor` the conservative default where every word has to read; poetic / social / cinematic → a column-flow identity by register (`editorial`, `cream`, `loud`, `neon`); "炸 / 特效 / VFX" → a themed identity (`ordnance`, `terminal`, `stomp`). Unsure → `anchor`: the words read and the scene stays safe. Don't ask for "Standard vs Cinematic vs Theme" — those are engine names; name the identity.
+
+**Verbatim rail vs climax embed.** The rail is the default and carries most of the text. An embed is a promotion — one peak word matted behind the subject, scarce and spaced (roughly one per beat, never two co-visible, at most one apex). Tell the skill *which* lines earn the embed; leave the rest on the rail.
+
+**Style, layout, and canvas (recut).** Pick a style group (warm-paper / clinical / experimental), a layout (split / stack / pip / overlay), and a canvas ratio; the video frame follows from layout × style. The recommended ratio matches the source, but you choose — 16:9 for desktop / YouTube, 9:16 for Reels / Shorts, 4:5 for feed.
+
+**Keyword highlighting.** On the caption rail, a punch word can carry an inline `emphasis` — an accent-color or active-word pop — without leaving the rail. Ask for "highlight the key word in each line" and it stays readable.
+
+## Failure modes
+
+**Asking for footage edits.** Both skills add a layer and leave the a-roll exactly as shot. Trimming, speeding up, recoloring, reframing, or reordering is NLE editing and out of scope — captions and cards are the only additions.
+- ❌ `add captions and trim the dead air at the start, and warm up the color to match my brand`
+- ✅ `add captions; leave the footage untouched` — do the trim / grade in an editor first, then bring the finished clip here.
+
+**Embedding every word.** On a talking head the rail is the verbatim default; matting every caption behind the subject buries the words and spends the climax on nothing.
+- ❌ `composite every caption behind the speaker for a cinematic look` (on an explainer)
+- ✅ `verbatim rail; promote only the two payoff lines to an embed`
+
+**Multi-subject clips.** The caption matte is one person; two speakers or hard cuts flicker or get refused.
+- ❌ `caption this two-person podcast in one pass`
+- ✅ `split the clip per shot / per speaker first, then caption each` — or use a single-subject cut.
+
+<Tip>
+  For the beat-timestamped skeleton these prompts share, see [Prompt anatomy](/prompting/anatomy); for adjectives that map to motion and emphasis settings, [Vocabulary](/prompting/vocabulary). To build a video from scratch instead of dressing existing footage, start at the router in `/hyperframes`.
+</Tip>
diff --git a/docs/prompting/captions-catalog.mdx b/docs/prompting/captions-catalog.mdx
new file mode 100644
index 0000000000..1587bd21b2
--- /dev/null
+++ b/docs/prompting/captions-catalog.mdx
@@ -0,0 +1,91 @@
+---
+title: Caption styles
+description: "Map caption tone to named caption components, and prompt per-word emphasis for composed videos."
+---
+
+## What caption styles do and when they trigger
+
+Caption components are drop-in snippets that render animated on-screen text — one visual identity per component, animating per word or per line. Prompts trigger this layer when you ask for captions, subtitles, kinetic text, lyric-style words, or word-by-word titles inside a composition you're building. Describe the *energy* of the captions and the agent picks matching typography, size, and animation; name a component to lock the look.
+
+<Note>
+  These components are for **composed videos** — captions you author into a HyperFrames composition. To add captions to an existing **talking-head MP4**, use the [`/embedded-captions`](/prompting/captions-and-talking-heads) workflow instead: it carries its own catalog of caption identities built around subject matting and occlusion (the caption sits *behind* the speaker), which the composition snippets below don't do.
+</Note>
+
+## Tone → caption component
+
+| Tone | Components |
+| ---- | ---------- |
+| **Hype / high-energy social** | [`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam), [`caption-highlight`](/catalog/components/caption-highlight), [`caption-particle-burst`](/catalog/components/caption-particle-burst), [`caption-emoji-pop`](/catalog/components/caption-emoji-pop) |
+| **Clean / corporate** | [`caption-clip-wipe`](/catalog/components/caption-clip-wipe), [`caption-weight-shift`](/catalog/components/caption-weight-shift) |
+| **Elegant / editorial** | [`caption-editorial-emphasis`](/catalog/components/caption-editorial-emphasis), [`caption-gradient-fill`](/catalog/components/caption-gradient-fill), [`caption-weight-shift`](/catalog/components/caption-weight-shift) |
+| **Neon / nightlife / music** | [`caption-neon-glow`](/catalog/components/caption-neon-glow), [`caption-neon-accent`](/catalog/components/caption-neon-accent) |
+| **Tech / cyber / glitch** | [`caption-glitch-rgb`](/catalog/components/caption-glitch-rgb), [`caption-matrix-decode`](/catalog/components/caption-matrix-decode) |
+| **Karaoke / lyric / follow-along** | [`caption-pill-karaoke`](/catalog/components/caption-pill-karaoke), [`caption-highlight`](/catalog/components/caption-highlight) |
+| **Textured / cinematic display type** | [`caption-texture`](/catalog/components/caption-texture), [`texture-mask-text`](/catalog/components/texture-mask-text) |
+| **Depth / 3D layering** | [`caption-parallax-layers`](/catalog/components/caption-parallax-layers) |
+
+## Text-effect components
+
+Three [Text Effects](/catalog/components/morph-text) components do one focused job rather than caption a whole track:
+
+| Component | Use when |
+| --------- | -------- |
+| [`caption-blend-difference`](/catalog/components/caption-blend-difference) | Text sits over busy or shifting footage and must stay legible — it auto-inverts per pixel against whatever is behind it. |
+| [`morph-text`](/catalog/components/morph-text) | You want one spot to cycle through a short word list with a gooey morph ("fast / simple / yours"). |
+| [`texture-mask-text`](/catalog/components/texture-mask-text) | A large display word filled with a physical texture (brick, rock, wood, metal, lava). |
+
+## Example prompts
+
+> /faceless-explainer 30-second vertical explainer. Add [`caption-highlight`](/catalog/components/caption-highlight) captions, TikTok-style — the visible line stays up, one word highlighted at a time.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-captions-catalog.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+<Note>
+  Caption components ship as demos — a fixed word list, landscape sizing, an 8-second timeline. The agent re-authors the words and timings to your narration and re-sizes for your format; that's expected, not a workaround. If you want one full-screen word at a time (no visible line), that's [`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam), not `caption-highlight`.
+</Note>
+
+> Hype captions with [`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam): one full-screen word per beat, alternating slam-in direction.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/caption-kinetic-slam.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above with an authored 24-word line, unedited.*
+
+
+> Neon music-video captions using [`caption-neon-glow`](/catalog/components/caption-neon-glow). Make brand names larger with an accent color and highlight the numbers differently.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/caption-neon-glow.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited — the brand renders 1.4x in magenta, numbers in amber, distinct from the default cyan.*
+
+
+> Fill the hero word "STONE" with [`texture-mask-text`](/catalog/components/texture-mask-text) using the rock texture.
+
+## Knobs
+
+- **Tone** picks typography, size, and animation — Hype (heavy, 72–96px, scale-pop) through Storytelling (serif, 44–56px, slow fade). See the caption-tone table in [vocabulary](/prompting/vocabulary).
+- **Per-word emphasis.** "Make brand names larger with accent color," "highlight numbers differently," "add bounce to emotional keywords" all work — several components key off this: [`caption-editorial-emphasis`](/catalog/components/caption-editorial-emphasis) drives a dramatic size contrast on emphasis words, [`caption-particle-burst`](/catalog/components/caption-particle-burst) fires on keywords, and the neon components carry keyword accent colors.
+- **Texture variable.** [`caption-texture`](/catalog/components/caption-texture) ships lava, marble, metal, wood, concrete, and rock — name the one you want.
+- **Word list.** [`morph-text`](/catalog/components/morph-text) cycles an editable list; quote the words in order.
+- **Format.** Full-screen single-word styles ([`caption-kinetic-slam`](/catalog/components/caption-kinetic-slam)) and TikTok-style highlights ([`caption-highlight`](/catalog/components/caption-highlight)) are built for vertical / social framing — say "vertical" or "9:16" so sizing and safe areas match.
+
+## Failure modes
+
+**Don't stack a heavy effect on every word.** Caption components already animate per word; layering another emphasis on top of that competes and turns illegible. Emphasize only the keywords.
+- ❌ `make every word explode with particles`
+- ✅ `caption-particle-burst, firing only on the keywords`
+
+**Don't mix caption styles in one section.** One identity per composition (or per section) reads as designed; two competing styles read as a mistake.
+- ❌ `use caption-neon-glow and caption-matrix-decode together`
+- ✅ pick one; switch styles only across a clear section break
+
+**Don't reach for these on talking-head footage.** These are composition snippets, not the matting/occlusion pipeline — captions won't sit behind the speaker.
+- ❌ `/hyperframes add caption-highlight to my interview.mp4`
+- ✅ `/embedded-captions` (see [captions and talking heads](/prompting/captions-and-talking-heads))
+
+**Don't match a hype style to calm content.** A high-energy caption on a corporate explainer fights the tone; let the tone table pick the identity.
+- ❌ `glitchy RGB captions` (on a wellness brand piece)
+- ✅ `clean captions with caption-clip-wipe`
+
+**Don't invent caption names.** Only the components in the [Captions](/catalog/components/caption-highlight) and [Text Effects](/catalog/components/morph-text) groups exist.
+- ❌ `add typewriter-bounce captions`
+- ✅ describe the tone ("tutorial, monospace, typewriter") or name a real component
diff --git a/docs/prompting/code-and-prs.mdx b/docs/prompting/code-and-prs.mdx
new file mode 100644
index 0000000000..a195016f5a
--- /dev/null
+++ b/docs/prompting/code-and-prs.mdx
@@ -0,0 +1,78 @@
+---
+title: Code changes and PRs
+description: "What to say to turn a GitHub pull request into a code-change explainer — changelog, feature reveal, fix, or refactor walkthrough."
+---
+
+## What this makes
+
+A code-change explainer built from a GitHub pull request. The [`/pr-to-video`](/prompting/overview) workflow reads the PR through `gh` — the diff, commits, files, and contributors — reshapes it into a story, and builds it frame by frame, rendering code beats on a purpose-built diff surface.
+
+The input is a **code change**, not a website or a product page. A PR link (`https://github.com/owner/repo/pull/N`), an `owner/repo#N` ref, or "this PR" in a checked-out repo all work. A product to sell → [`/product-launch-video`](/prompting/product-launch); a topic with no PR → [`/faceless-explainer`](/prompting/explainers). Unsure → start at `/hyperframes`.
+
+## Base prompt
+
+Verified, from the [examples](/prompting/examples) page — a 30-second feature reveal:
+
+> /pr-to-video Make a 30-second 1920x1080 feature-reveal video from [PR URL]. Lead with what users get, not the diff; show the key code change with the `code-diff` block for one beat only; end on version number + repo URL. No narration, kinetic captions instead.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-pr-video.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+## Variants
+
+<AccordionGroup>
+  <Accordion title="Changelog roundup">
+    > /pr-to-video Make a ~40-second 1920x1080 changelog video from [PR URL]. Changelog angle: open with the release line, then one beat per notable change — a short label and a one-line "what it does" each. Show at most two `code-diff` hunks across the whole video. End on version + repo URL. Calm male TTS narration, no captions.
+    
+    <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/variant-pr-changelog.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from this prompt with [PR URL] = heygen-com/hyperframes#2092, unedited.*
+
+    A changelog trades depth for breadth — many small changes, each a beat, rather than one change explored deeply. Keep code beats sparse so the pace stays fast. A PR doesn't carry its shipping version — the agent finds it from the release tag or the package manifest on main.
+  </Accordion>
+  <Accordion title="Fix explainer">
+    > /pr-to-video Make a ~40-second 1920x1080 fix-explainer from [PR URL], for developers. Fix angle: state the bug's symptom first, then the root cause, then the one-line fix on the `code-diff` block. End on version + repo URL. No narration, kinetic captions.
+
+    A fix reads as symptom → cause → fix. Lead with what users saw break, not the stack trace — the diff is the payoff, not the opening.
+  </Accordion>
+  <Accordion title="Refactor walkthrough">
+    > /pr-to-video Make a ~70-second 1920x1080 refactor-walkthrough from [PR URL], for developers. Refactor angle: why the old shape hurt, then the new shape, showing the before/after with the `code-morph` block for the key file. End on version + repo URL. Calm male TTS narration.
+
+    A refactor changes shape without changing behavior, so the story is *why* the new structure is better. `code-morph` animates one form transforming into another — the right block when the point is the transition, not a line-by-line delta.
+  </Accordion>
+</AccordionGroup>
+
+## The knobs that matter
+
+| Knob | What to say | Why it matters |
+| --- | --- | --- |
+| **Impact vs diff** | "lead with what users get, not the diff" | The video explains the *change*, it doesn't read the diff aloud; opening on impact answers "why should I care?" before the code |
+| **How many hunks** | "one `code-diff` beat only" / "at most two hunks" | Code beats feature 2-4 real hunks total, each a small legible snippet — a whole file is unreadable at video scale |
+| **Which code block** | `code-diff` for a delta · `code-morph` for a refactor · `code-typing` for new code | The block matches the story: a diff shows added/removed lines, a morph shows one shape becoming another |
+| **Angle** | "changelog" / "feature-reveal" / "fix-explainer" / "refactor-walkthrough" | Sets the story shape; the workflow reshapes the PR into it rather than walking files in diff order |
+| **Audience** | "for developers" (default) / "mixed technical" / "non-technical stakeholders" | Shifts how much the narration assumes — a non-technical cut leans harder on impact and lighter on code |
+| **End card** | "end on version number + repo URL" | The conventional close for a code explainer; state what goes on it so it's a real CTA, not an afterthought |
+| **Narration vs captions** | "calm male narration" or "no narration, kinetic captions instead" | Both are supported; captions-only keeps it silent-friendly for social, narration carries a longer walkthrough |
+| **Length** | "~30s" for one headline, up to ~3 min for a large PR | The workflow reads the change size and recommends a tier — a huge PR is a ceiling on story, not a floor to fill |
+
+<Tip>
+  The style is fixed to the workflow's warm-editorial preset with a navy code surface built for diffs — it's what makes the code beats legible. You don't choose a theme here; you choose the angle, the hunks, and the narration.
+</Tip>
+
+## Common failure modes
+
+**Forcing a theme over the preset.** The style is fixed for a reason — the navy code surface is tuned for diff legibility; a foreign theme fights it and produces a compromise (see [rules and anti-patterns](/prompting/rules-and-anti-patterns)).
+- ❌ `/pr-to-video ... dark theme, neon accents`
+- ✅ let the preset carry the look; spend your specificity on the angle and the code beats
+
+**Asking for the whole diff.** A PR video explains the change; it doesn't recite every file. A full diff is unreadable at video scale.
+- ❌ `walk through the entire diff, file by file`
+- ✅ `feature the 2-3 key hunks, each a small legible snippet`
+
+**Opening on the code.** The diff is the payoff, not the hook — lead with what the change means.
+- ❌ `start with the diff, then explain what it does`
+- ✅ `lead with what users get, then show the key hunk`
+
+**Hard-timing a narrated cut.** With narration the spoken length sets the runtime; state a range, not a fixed number.
+- ❌ `a 40-second narrated walkthrough`
+- ✅ `a ~40-second narrated walkthrough`
diff --git a/docs/prompting/code-blocks.mdx b/docs/prompting/code-blocks.mdx
new file mode 100644
index 0000000000..7ed7fd6066
--- /dev/null
+++ b/docs/prompting/code-blocks.mdx
@@ -0,0 +1,135 @@
+---
+title: Code animations
+description: "Prompt code walkthroughs — typing, diffing, highlighting, scrolling — and pick a terminal or editor theme by name."
+---
+
+Code is the one subject where the framework does the hard part for you. The [Code Animations](/catalog/blocks/code-typing) blocks handle syntax highlighting, caret tracking, diff coloring, and camera moves deterministically — you describe the *walkthrough*, name the block, and paste your snippet. This page is the vocabulary for doing that well; for turning a real pull request into a code-change video, see [Code and PRs](/prompting/code-and-prs).
+
+Everything here follows the [one-shot skeleton](/prompting/anatomy): route, spec, beats, copy, technique, negatives. The "technique" slot is where you name the block, and the "copy" slot is where your code goes — quoted exactly, because unquoted code gets paraphrased into something that won't compile.
+
+### Pick the motion by what the viewer should learn
+
+Each Code Animations block answers a different "what is the viewer supposed to notice." Map the intent to the block:
+
+| You want to show…                          | Name this block                                         | Length |
+| ------------------------------------------ | ------------------------------------------------------- | ------ |
+| Code being written, character by character | [`code-typing`](/catalog/blocks/code-typing)            | 5s     |
+| An edit — before → after, red/green        | [`code-diff`](/catalog/blocks/code-diff)                | 6s     |
+| One line as *the* line, everything else dim | [`code-highlight`](/catalog/blocks/code-highlight)      | 5s     |
+| Walking a long file to a spot deep inside  | [`code-scroll`](/catalog/blocks/code-scroll)            | 6s     |
+| One snippet transforming into another      | [`code-morph`](/catalog/blocks/code-morph)              | 7s     |
+| Snippets flying in and stacking up         | [`code-snippet-flight`](/catalog/blocks/code-snippet-flight) | 6s |
+| Code on a rotating 3D slab (title-card feel) | [`code-3d-extrude`](/catalog/blocks/code-3d-extrude)    | 8s     |
+| Code resolving out of a shader dissolve    | [`code-shader-dissolve`](/catalog/blocks/code-shader-dissolve) | 7s |
+| Code assembling from a particle swarm      | [`code-particle-assemble`](/catalog/blocks/code-particle-assemble) | 8s |
+
+The first four are the workhorses of a code *walkthrough* — they keep the code readable and the viewer oriented. The last three are entrance spectacle: they look great as an opener or a hero moment, but they trade legibility for motion, so don't ask them to carry an explanation.
+
+<Tip>
+  `code-morph` re-drives Shiki Magic Move as a paused GSAP timeline, and `code-diff` collapses removed lines and expands added lines. Both read "an edit happened" far more clearly than retyping the whole snippet with `code-typing` — reach for them when the story is *a change*, not *authoring from scratch*.
+</Tip>
+
+### Prompting a typing reveal
+
+`code-typing` reveals code character by character with a caret that tracks the frontier — no CSS animation, so it seeks cleanly. Give it the exact code and a pace; the agent re-bakes the block's syntax tokens to your snippet.
+
+> /motion-graphics 6-second 1920x1080 video. A dark editor types this snippet, character by character, caret tracking the frontier, then holds on the blinking cursor for the final second:
+> ```
+> export async function render(comp: Composition) {
+>   await comp.seek(0);
+>   return comp.capture();
+> }
+> ```
+> Use the `code-typing` registry block. No narration, no image or media files.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-code-typing.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+**Quote the code as a literal block.** Prose descriptions of code get paraphrased.
+- ❌ `type out a function that seeks to zero and captures`
+- ✅ paste the actual snippet in a fenced block — it renders verbatim
+
+**Give the caret somewhere to rest.** Compositions hold their final state, so if you don't ask for a hold the last frame is a frozen full snippet — the [dead-motion tell](/prompting/motion).
+- ❌ `types the code and ends`
+- ✅ `types the code, then holds on the blinking cursor for the final second`
+
+### Prompting a diff or a highlight
+
+For "here's what changed," hand `code-diff` the before and after and let it color the delta. For "look at *this* line," give `code-highlight` the full context and name the target line.
+
+> /motion-graphics 6-second 1920x1080 video. Show this edit to `api.ts` as a colored diff — the removed line collapses in red, the added line expands in green:
+> removed: `const res = await fetch(url)`
+> added: `const res = await fetch(url, { signal })`
+> Use the `code-diff` registry block. No audio.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-code-diff.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+> /motion-graphics 5-second 1920x1080 video. Show a 12-line config file; a highlight band sweeps to line 7 (`timeout: 30_000`) while the surrounding lines dim. Hold with line 7 lit. Use the `code-highlight` registry block. No audio.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-code-highlight.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited — the agent authors plausible surrounding config lines; paste all 12 if the exact file matters.*
+
+
+**Name the target line unambiguously.** The block dims context around one line — tell it which.
+- ❌ `highlight the important line`
+- ✅ `highlight line 7 (timeout: 30_000)`
+
+### Prompting a scroll-through
+
+`code-scroll` moves the camera down a long file to bring a target line to center and spotlights it — the block for walking real modules, not toy snippets.
+
+> /motion-graphics 6-second 1920x1080 video. Scroll a ~60-line source file so line 44 (`return dedupeFrames(frames)`) arrives at center and gets spotlighted; ease the scroll and let it settle without snapping. Use the `code-scroll` registry block. No audio.
+
+**Ask the scroll to ease and settle, not snap.** A linear scroll that stops dead reads mechanical.
+- ❌ `scroll straight to the line`
+- ✅ `ease the scroll and let it settle` — pair with the [motion grammar](/prompting/motion)
+
+### Choosing a theme by name
+
+The [Code Snippets](/catalog/blocks/code-snippet-monokai) blocks are pre-styled shells with per-character typing already built in. There are two families, and you select one by asking for it in plain language — the exact block name is the theme name.
+
+**macOS Terminal.app profiles** — a real terminal window chrome. Say "apple terminal, ocean profile" → [`code-snippet-apple-terminal-ocean`](/catalog/blocks/code-snippet-apple-terminal-ocean). The full set of profiles:
+
+| Profile      | Block                                     | Profile        | Block                                       |
+| ------------ | ----------------------------------------- | -------------- | ------------------------------------------- |
+| Basic        | `code-snippet-apple-terminal-basic`       | Novel          | `code-snippet-apple-terminal-novel`         |
+| Clear Dark   | `code-snippet-apple-terminal-clear-dark`  | Ocean          | `code-snippet-apple-terminal-ocean`         |
+| Clear Light  | `code-snippet-apple-terminal-clear-light` | Pro            | `code-snippet-apple-terminal-pro`           |
+| Grass        | `code-snippet-apple-terminal-grass`       | Red Sands      | `code-snippet-apple-terminal-red-sands`     |
+| Homebrew     | `code-snippet-apple-terminal-homebrew`    | Silver Aerogel | `code-snippet-apple-terminal-silver-aerogel`|
+| Man Page     | `code-snippet-apple-terminal-man-page`    | Solid Colors   | `code-snippet-apple-terminal-solid-colors`  |
+
+**VS Code workbench themes** — full editor chrome (activity bar, sidebar, tabs, terminal, status bar). Say "monokai" or "visual studio dark":
+
+| Say this               | Block                                 | Say this            | Block                              |
+| ---------------------- | ------------------------------------- | ------------------- | ---------------------------------- |
+| Monokai                | `code-snippet-monokai`                | Solarized Light     | `code-snippet-solarized-light`     |
+| Dark Modern            | `code-snippet-dark-modern`            | Light Modern        | `code-snippet-light-modern`        |
+| Dark Plus              | `code-snippet-dark-plus`              | Light Plus          | `code-snippet-light-plus`          |
+| Dark 2026              | `code-snippet-dark-2026`              | Light 2026          | `code-snippet-light-2026`          |
+| High Contrast          | `code-snippet-high-contrast`          | High Contrast Light | `code-snippet-high-contrast-light` |
+| Visual Studio Dark     | `code-snippet-visual-studio-dark`     | Visual Studio Light | `code-snippet-visual-studio-light` |
+
+> /motion-graphics 5-second 1920x1080 video. A macOS Terminal window in the Ocean profile types `npx skills add heygen-com/hyperframes` character by character, then holds on the prompt. Use the `code-snippet-apple-terminal-ocean` registry block. No narration.
+
+**Match the theme to the surface you're claiming to show.** A terminal command in a VS Code editor chrome reads wrong; a source file in Terminal.app reads wrong.
+- ❌ `monokai theme typing a shell command`
+- ✅ `apple terminal homebrew profile typing a shell command`
+
+<Tip>
+  Ambiguity resolves to the closest named block. "Dark theme" is under-specified — the agent picks one of a dozen dark variants and you may not get the one you pictured. Say the theme name. This is the [specification dial](/prompting/specification-dial) applied to code: name the block when the default choice can miss.
+</Tip>
+
+### Pairing with a pull request
+
+When the code you're animating comes from a real PR, don't hand-write the beats — the [`/pr-to-video`](/prompting/code-and-prs) workflow reads the diff and composes `code-diff`, `code-highlight`, and `code-scroll` around the actual changed hunks. Use the blocks on this page directly when you're illustrating a concept; route through the PR workflow when you're narrating a specific change set.
+
+### Where to go next
+
+- [Anatomy of a one-shot prompt](/prompting/anatomy) — the skeleton every prompt above uses.
+- [Copy-paste examples](/prompting/examples) — full prompts you can adapt.
+- [Code and PRs](/prompting/code-and-prs) — turning a GitHub PR into a code-change video.
+- [Motion that reads premium](/prompting/motion) — the hold-and-settle rules the code blocks still need from you.
diff --git a/docs/prompting/data-and-maps.mdx b/docs/prompting/data-and-maps.mdx
new file mode 100644
index 0000000000..57b8b46424
--- /dev/null
+++ b/docs/prompting/data-and-maps.mdx
@@ -0,0 +1,87 @@
+---
+title: Data and maps
+description: "Prompt animated charts, count-up stats, and maps — highlight regions, draw flows, size bubbles — or hand-draw a chart for full control."
+---
+
+Numbers and geography are the two subjects where "what data" and "how it moves" are separate decisions. The [Data](/catalog/blocks/data-chart) blocks give you a polished chart or map you feed values into; the count-up [showcase](/catalog/blocks/apple-money-count) blocks handle the odometer-and-flourish moment. Everything here plugs into the [one-shot skeleton](/prompting/anatomy) — the data goes in the "copy" slot, the block name in "technique."
+
+### Charts: name the block, or hand-draw
+
+There are two ways to get a chart, and the choice is about control:
+
+- **Name [`data-chart`](/catalog/blocks/data-chart)** to get the built animated bar + line chart — staggered reveal, value labels, NYT-style typography — and feed it your numbers. Fast, consistent, no design decisions.
+- **Say "hand-draw everything — no chart library"** to make the agent build the chart from inline SVG and GSAP instead. You give up the polish of the block for total control over shape, motion, and layout — a bar race that overtakes mid-animation, an arc that draws to match a counter, a layout no library ships.
+
+Feed data inline or as a file. Small series go straight in the prompt; a CSV gets referenced and parsed at build time (keep it deterministic — no [render-time fetches](/concepts/determinism)).
+
+> 12-second 1920x1080 video. Turn this into an animated bar chart with a staggered reveal and value labels counting up on each bar:
+> ```
+> Python 41, TypeScript 33, Rust 19, Go 14, Java 9
+> ```
+> Use the `data-chart` registry block. No audio.
+
+> 10-second 1920x1080 video, dark slate background. Title "Top languages 2026" top-left. Five horizontal bars (Python, TypeScript, Rust, Go, Java) grow from zero with staggered starts, overtaking each other twice mid-animation; each bar has a right-edge value label counting up to its final %. End state holds 2s with the leader pulsing once. Hand-draw everything — no chart library. No audio.
+
+**State the block *or* opt out of it — don't leave it implicit.** "Animate this data" without a decision drifts between a generic block and an improvised layout.
+- ❌ `animate this CSV as a chart`
+- ✅ `turn this CSV into an animated bar chart — use the data-chart registry block` **or** `…hand-draw everything, no chart library`
+
+**Format numbers for the animation you asked for.** An odometer count-up needs fixed digit columns; a `$0 → $4.2M` range forces an awkward `$0.0M` start.
+- ❌ `counts from $0 to $4.2M`
+- ✅ `counts up to $4.2M`
+
+### Count-up stats
+
+For a single hero number, [`apple-money-count`](/catalog/blocks/apple-money-count) is the Apple-style finance counter — it rolls from $0, flashes green, and bursts money icons with sound. Name it when you want that exact flourish; hand-draw when you want a bare number in your own type.
+
+> /motion-graphics 6-second 1920x1080 video, dark navy background. Beat 1 (0-1s): label "ARR" fades up small, top-center. Beat 2 (1-4s): a giant number counts up to $4.2M with an odometer roll, easing out as it lands. Beat 3 (4-6s): "+312% YoY" stamps in below in green, then settles into a gentle ambient idle. Use the `apple-money-count` registry block as base. No narration.
+
+### Maps: match the ask to the map
+
+Each map block answers a different geographic question. Say what the map is *for* and name the matching block:
+
+| You want to…                                    | Name this block                                    | Length |
+| ----------------------------------------------- | -------------------------------------------------- | ------ |
+| Shade US states by a value (choropleth)         | [`us-map`](/catalog/blocks/us-map)                 | 12s    |
+| Size US cities by a value (proportional bubbles)| [`us-map-bubble`](/catalog/blocks/us-map-bubble)   | 12s    |
+| Draw connections between US cities (origin→dest)| [`us-map-flow`](/catalog/blocks/us-map-flow)       | 12s    |
+| Show US states as an equal-weight hex grid      | [`us-map-hex`](/catalog/blocks/us-map-hex)         | 10s    |
+| Shade Spain by autonomous community             | [`spain-map`](/catalog/blocks/spain-map)           | 12s    |
+| Shade the world country by country              | [`world-map`](/catalog/blocks/world-map)           | 14s    |
+
+The US map encodings combine — asking to "shade states *and* draw flows between two cities" gets you one composition: the agent merges the blocks at source onto a shared projection so arcs land exactly on the choropleth's states.
+
+> 12-second 1920x1080 video. A US choropleth shades states by adoption rate with staggered reveals and a gradient legend, then connection arcs draw between San Francisco, Austin, and New York. Use the `us-map` and `us-map-flow` registry blocks. No audio.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-us-map-flows.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+<Note>
+  The map blocks fetch their geo data from a CDN at runtime, which violates the deterministic-render rules — the agent bakes the projected geometry into the composition instead. You never need to ask for this; it's part of building the map correctly.
+</Note>
+
+**Pick the encoding, don't just say "map."** Choropleth (color), bubble (size), hex (equal weight), and flow (arcs) tell different stories from the same data.
+- ❌ `put California's number on a US map`
+- ✅ `size each city as a proportional bubble` → `us-map-bubble`, or `shade each state by value` → `us-map`
+
+**Name the region's block.** The choropleths are region-specific with baked-in projections (`spain-map` is D3 conic conformal, `world-map` is Natural Earth) — there's no generic "any country" map.
+- ❌ `a map of Spain's regions` (leaves the projection and geography to chance)
+- ✅ `use the spain-map registry block`
+
+### Routes and flights
+
+For a point-to-point journey — a route drawing across a map with a landing beat — [`nyc-paris-flight`](/catalog/blocks/nyc-paris-flight) is the Apple-style flight animation: a plane flies New York → Paris with a marker circle, landing pop, and sound effects. Use it as the base and re-point the endpoints in your prompt.
+
+> /motion-graphics 6-second 1920x1080 video. A realistic map with a plane flying between two cities, a marker circle at the origin, and a landing pop at the destination. Use the `nyc-paris-flight` registry block as base. No narration.
+
+**A route is a flow with a vehicle, not a static arc.** If you want the drawn arc without the plane and sound, that's `us-map-flow`; if you want the journey performance, that's `nyc-paris-flight`.
+- ❌ `draw a line from NYC to Paris` (ambiguous between arc-only and full flight)
+- ✅ `a plane flies the route with a landing pop` → `nyc-paris-flight`
+
+### Where to go next
+
+- [Anatomy of a one-shot prompt](/prompting/anatomy) — the skeleton, and why odometers need fixed digit columns.
+- [Copy-paste examples](/prompting/examples) — bar-chart race and stat-tile prompts to adapt.
+- [Generated artwork](/prompting/generated-artwork) — where hand-drawn HTML/CSS/SVG shines, and where it doesn't.
+- [The specification dial](/prompting/specification-dial) — deciding when to name a block versus hand-draw.
diff --git a/docs/prompting/design-systems.mdx b/docs/prompting/design-systems.mdx
new file mode 100644
index 0000000000..06efa86a86
--- /dev/null
+++ b/docs/prompting/design-systems.mdx
@@ -0,0 +1,88 @@
+---
+title: Design systems and brand
+description: "Point the agent at a source of brand truth — a design spec, a site, or a Figma file — instead of asking for 'on-brand', and let it compose the frame."
+---
+
+"Make it on-brand" is the single vaguest thing you can ask. The agent has no way to know what your brand *is*, so it invents one. The fix is always the same: give it a **source of brand truth** — a design spec, a live site, or a Figma file — and name it in the prompt. Everything on this page is a way to do that.
+
+## Point at a spec, don't describe a vibe
+
+HyperFrames projects can carry a design spec — `frame.md` (video-first) or `design.md` — whose frontmatter tokens are the machine-readable brand: exact hex values, font families, weight relationships, and the brand's Do's and Don'ts. When one exists, name it:
+
+> Use the palette and type from `frame.md`. Build a 15-second feature announcement.
+
+- ❌ `make it feel on-brand and premium`
+- ✅ `pull colors and fonts from design.md; premium means generous spacing and one restrained accent`
+
+The engine rationale: `on-brand` is a mood the agent guesses at. A spec's frontmatter is normative — the agent quotes the hex and font family verbatim instead of approximating, and reads the prose sections for intent. If your brand lives somewhere else (a PDF brand guide, a screenshot, pasted hex codes), attach it — attachments and pasted tokens are read more reliably than a described impression.
+
+## Brand is truth for color and type — not for layout
+
+A design spec tells the agent what the brand *looks like*; it does **not** dictate how to compose a video frame. Say what's sacred and let the agent stage the rest:
+
+> Colors and fonts are locked to the brand — keep the exact hexes and the display/body pairing. Layout, spacing, and motion are yours to compose for video.
+
+The engine rationale: web-scale brand values don't survive video. A `1px` border with a `0.06`-opacity shadow is invisible after H.264 compression; a web body size vanishes on a 1080p frame. The brand color, background choice (if the brand is a light canvas, keep it light), fonts, and weight relationships are strict — but type sizes, decorative opacity, and border weight get scaled up for the medium. Over-specifying layout from a web design system fights this; pin the palette and typography, delegate the frame.
+
+## Use the site's own palette and fonts
+
+When there's no spec but there is a brand out there, point at it and let the agent extract:
+
+> Match this site's look — pull its palette and fonts — and make a 20-second launch clip: `https://…`
+
+For a well-known brand, naming it is often enough for the agent to research the palette and typography. One caveat worth stating: a single-page-app homepage often returns a near-empty shell, so if the palette comes back thin, point the agent at a blog, press, or docs page instead. This is the same brand-truth move — the *site* is the source instead of a file.
+
+## Bringing in a Figma frame, brand, or logo
+
+If the brand lives in Figma, ask for it directly — the agent imports it rather than eyeballing a screenshot:
+
+> Bring in the brand tokens from this Figma file, then build the intro: `https://figma.com/…`
+
+> Import this Figma frame as the opening scene and this logo as an SVG: `<links>`
+
+The [Figma import](/guides/figma) path freezes each import as a local asset with recorded provenance (so renders stay deterministic) and imports brand variables as composition brand tokens. Two things worth knowing when you phrase the ask:
+
+- **Import tokens before components.** Say "brand tokens first, then the components" — that's what lets imported component colors link to your brand variables instead of baking in duplicate hexes.
+- **Storyboard frames are states, not slides.** If you point at a strip of scene frames, ask the agent to *reconstruct the motion between them* — a frame showing an element at four positions is one element animating, not four stills to flip through.
+
+## Keeping a multi-video series consistent
+
+For a series — a launch set, a weekly clip, a per-region cut — consistency comes from a **shared source of truth**, not from re-describing the brand each time:
+
+> All four videos share `frame.md` for palette and type. Only the headline and the stat change per video.
+
+Because the runtime exposes every declared brand token as a CSS custom property, the parts that stay constant come from the one spec (or one set of imported Figma tokens), and the parts that vary become [variables](/prompting/variables-and-templating). Change one brand value in the spec and every video re-skins on the next render — you don't touch four files. This is where design systems and templating meet: the brand is shared, the content is parameterized.
+
+## Supplying brand assets by path
+
+Logos, fonts, textures, and product shots are inputs — hand the agent the path, don't ask it to draw them:
+
+> Logo at `assets/logo.svg`, brand font files in `assets/fonts/`, product shot at `assets/hero.png`. Use them; don't invent placeholders.
+
+Prefer an SVG logo (scalable, animatable) over a raster one. State the paths explicitly so the agent wires the real assets instead of generating stand-ins — and so the render is deterministic, with every asset present locally before it starts.
+
+## Supply inputs a workflow accepts — don't fight its preset
+
+The creation workflows (`/product-launch-video`, `/website-to-video`, and the rest) each come with a designed look. The productive move is to feed that look your brand inputs, not to override its composition after the fact:
+
+- ❌ `run /product-launch-video, then restyle every scene to my colors afterward`
+- ✅ `run /product-launch-video with my palette, fonts, and logo as inputs up front`
+
+The engine rationale: a workflow's preset is a coherent, tested system — colors, spacing, motion, and component treatments that hang together. Supplying brand inputs at the start lets it apply your palette and type *within* that system. Restyling scene-by-scene afterward pulls threads out of a design that was balanced as a whole, and you spend more effort fighting the preset than you'd have spent handing it a spec.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Figma Import" icon="figma" href="/guides/figma">
+    Import brand tokens, assets, components, and motion from a Figma file.
+  </Card>
+  <Card title="Variables and templating" icon="sliders" href="/prompting/variables-and-templating">
+    Turn brand tokens into variables that re-skin a whole series from one value.
+  </Card>
+  <Card title="The specification dial" icon="gauge" href="/prompting/specification-dial">
+    How pinning exact hexes and type direction removes drift.
+  </Card>
+  <Card title="Claude Design" icon="message" href="/guides/claude-design">
+    Attach a brand guide or screenshot to seed a first draft from your look.
+  </Card>
+</CardGroup>
diff --git a/docs/prompting/editing-existing-videos.mdx b/docs/prompting/editing-existing-videos.mdx
new file mode 100644
index 0000000000..967035d362
--- /dev/null
+++ b/docs/prompting/editing-existing-videos.mdx
@@ -0,0 +1,130 @@
+---
+title: Editing existing videos
+description: "Direct the agent like an editor — trim, move, retime, swap, restyle — with the NLE verb you already know mapped to the prompt that lands it in one pass."
+---
+
+Most HyperFrames time isn't the first render — it's the twenty edits after it. A composition is plain HTML with `data-*` timing attributes and a GSAP timeline, so every edit you'd make in a non-linear editor maps to a specific, inspectable change in the source. You don't re-specify the video; you name the edit the way you'd say it to a human editor, and the agent makes the smallest change that does it.
+
+This page maps the editor verbs to the prompts that land them. The examples name elements from a typical composition — swap the noun ("the lower third", "scene 2") for whatever yours is called. Two habits from [Iterating](/prompting/iterating) apply to every one of them, so keep them in mind: **change one thing per render**, and **state targets as absolute values** ("scene 2 = 2 seconds", not "a bit shorter") so the agent lands it in a single pass instead of oscillating.
+
+## The verb → edit map
+
+Every timeline verb resolves to a `data-*` attribute or an inline style. This is what each one touches under the hood — useful to know because it's why absolute targets work and why some edits are cheap:
+
+| You say | Editor verb | What the agent edits |
+| --- | --- | --- |
+| "start scene 2 later / earlier" | Move | `data-start` |
+| "put the captions on top of the video" | Restack | `data-track-index` + inline `z-index` |
+| "end the logo sooner" | Trim (right) | `data-duration` |
+| "skip the first second of the clip" | Trim (front, media only) | `data-media-start` / `data-playback-start` |
+| "make scene 2 two seconds long" | Retime | `data-duration` (and the GSAP timeline length) |
+| "the audio bed is too loud" | Level | `data-volume` |
+
+<Note>
+  The mental model the Studio timeline uses: **move** changes when a clip *starts*, **right trim** changes when it *ends*, and **front trim** only exists for media clips — a `<video>` or `<audio>` can skip into its own content, but a GSAP-driven `<div>` can't start halfway through its animation. See [Timeline editing](/guides/timeline-editing) for the full clip-type breakdown. One more surface the map can't show: retiming a scene that spans the whole composition also needs the root's `data-duration` bumped — the root governs total length, so a longer child never renders past it.
+</Note>
+
+## Trim, move, and restack
+
+These are the pure-timing edits — no visual change, just when and where a layer lives on the timeline.
+
+> Trim the intro so it ends at 0:03 instead of 0:05.
+
+> Move the lower third to start at 0:06.
+
+> The captions are rendering behind the video — put them on a higher track so they sit on top.
+
+Bound moves by the composition's length — a 4-second clip moved to 0:08 in a 10-second video barely appears before the end. And absolute targets matter most here: "make the intro shorter" invites a guess; "the intro should end at 3.0s" is a single `data-duration` write with nothing to overshoot.
+
+- ❌ `tighten up the opening`
+- ✅ `intro clip duration = 3s; leave its animation and position alone` — one attribute, and the freeze clause stops a rebuild from drifting on axes you'd already settled
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/editing-before.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Before — the untouched composition.*
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/editing-after.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*After — four verbatim edits from this page (move, right-trim, retime, restyle-with-freeze); each touched exactly the attribute the verb map promises, gates green after every edit.*
+
+
+## Split a scene
+
+The Studio timeline exposes move and trim as drag gestures but does **not** yet offer split, slip, slide, ripple, or roll. You can still split by directing the agent, because it edits the HTML directly — a split is just one clip becoming two with adjusted `data-start` / `data-duration`:
+
+> Split scene 2 at 0:04 so I can drop a transition between the two halves.
+
+Name the exact cut point. The agent turns one clip into two adjacent clips; you then treat each half as its own layer.
+
+## Retime a scene
+
+Retiming is a duration change, but with one catch worth knowing: a scene driven by a GSAP timeline needs the timeline to be at least as long as the new duration, or the render cuts off early.
+
+> Make scene 2 run 4 seconds instead of 2.5 — keep the animation, just give it more room.
+
+- ❌ `stretch scene 2` — ambiguous whether you mean slower motion or a longer hold
+- ✅ `scene 2 duration = 4s, same motion, add the extra time as a hold at the end`
+
+<Warning>
+  If a retimed scene cuts off before its new end, the fix is extending the GSAP timeline length (the `tl.set({}, {}, <seconds>)` sentinel pattern). The agent handles this; it's the single most common reason a lengthened clip renders short. See the [Video editor cheatsheet](/guides/video-editor-cheatsheet#timing-cheatsheet).
+</Warning>
+
+## Make it snappier (retiming *feel*, not just duration)
+
+"Snappier," "punchier," "more relaxed" are pacing words, and they map to concrete easing and timing choices — [Vocabulary](/prompting/vocabulary) has the full table. The agent reads "snappy" as a decisive ease (`power4.out`) and tighter durations, "dreamy" as slow symmetrical motion, and so on.
+
+> Make scene 2 snappier — quicker entrances, harder cuts.
+
+> The reveal feels robotic; give it a bouncy overshoot.
+
+Change one scene's feel per render so you can attribute what helped. If a scene keeps missing, strip it to the minimal version (subject + its motion only), confirm it reads, then re-layer.
+
+## Adjust a keyframe
+
+Individual animation properties are editable — the value, the ease, the timing of any tween. You can direct these by prompt, or edit them yourself in the Studio Design Panel; either way they resolve to the same GSAP code.
+
+> The title slides in from too far — change its entrance to travel 40px, not 200.
+
+> Give the add-to-cart item an arc instead of a straight diagonal, like it's being tossed into the cart.
+
+State the property target absolutely (`Move X = 40`, `arc curviness ≈ 1.5`). [Keyframes & arc motion](/guides/keyframes) covers what's editable, arc-motion paths, and gesture recording.
+
+<Tip>
+  For an element-specific edit, the Design Panel's clipboard icon copies structured context — the element's id, position, size, and current animation — ready to paste into your prompt. It gives the agent exact spatial context instead of a vague "the title."
+</Tip>
+
+## Swap an asset
+
+Replacing a video, image, logo, or audio track is a source-swap. The one rule: **name the path.** The agent will search for "my logo," but a path skips the search and removes the ambiguity of which file you mean.
+
+> Replace the background music with `assets/track.mp3`.
+
+> Swap the hero image for `assets/product-v2.png` and keep its animation.
+
+- ❌ `use the new logo`
+- ✅ `swap the logo for assets/logo-2025.svg`
+
+## Change copy
+
+On-screen text is edited verbatim when you quote it. Unquoted text gets paraphrased — the agent treats a description as an instruction to write copy, not to place it exactly.
+
+> Change the headline to "Ship faster." — exact text, keep the styling.
+
+- ❌ `update the title to say something about speed`
+- ✅ `title copy: "Ship faster."`
+
+## Restyle one element
+
+Visual tweaks — color, size, weight, position of a single element — are where the "freeze the rest" clause earns its keep. Without it, a restyle prompt can trigger a rebuild that drifts on layout or motion you'd already approved.
+
+> Make the CTA button 20% larger and switch it to the accent color — don't touch anything else.
+
+- ❌ `make the CTA pop more`
+- ✅ `CTA background = accent color, font-size = 1.2× current; framing and motion are right, leave them`
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Iterating" href="/prompting/iterating">One variable per edit, absolute targets, freeze what works</Card>
+  <Card title="Vocabulary" href="/prompting/vocabulary">Pacing and easing words that retime the *feel* of a scene</Card>
+  <Card title="Timeline editing" href="/guides/timeline-editing">Which edits the Studio timeline persists, and how</Card>
+  <Card title="Video editor cheatsheet" href="/guides/video-editor-cheatsheet">The `data-*` attributes as timeline controls</Card>
+</CardGroup>
diff --git a/docs/prompting/examples.mdx b/docs/prompting/examples.mdx
new file mode 100644
index 0000000000..4f2a3c9a15
--- /dev/null
+++ b/docs/prompting/examples.mdx
@@ -0,0 +1,108 @@
+---
+title: Verified example prompts
+description: "18 copy-paste prompts, every one run end-to-end to a finished video that passes lint and validate."
+---
+
+Every prompt below has been run end-to-end and one-shots a finished video that passes `lint` and `validate`. Swap the copy, colors, and inputs for your own.
+
+### With registry blocks and workflows
+
+<AccordionGroup>
+  <Accordion title="Stat count-up">
+    > /motion-graphics 6-second 1920x1080 video, dark navy background. Beat 1 (0-1s): label "ARR" fades up small, top-center. Beat 2 (1-4s): a giant number counts up to $4.2M with an odometer roll, easing out as it lands. Beat 3 (4-6s): "+312% YoY" stamps in below in green, then everything settles into a gentle ambient idle (subtle breathing scale, slow particle drift). Use the `apple-money-count` registry block as base. No narration.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-stat-countup.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Animated social post">
+    > /motion-graphics 7-second 1080x1350 vertical video. A real tweet card (handle @hyperframes, text "we render video from HTML now. no timeline UI. just code.") slides up over a soft animated gradient, likes counter ticks 0→1.2K, then the card tilts in 3D and a highlight sweeps the second sentence. Hold on the card at the end. Use the `x-post` and `vfx-liquid-background` registry blocks. No narration, no image or media files.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-tweet.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Map route">
+    > /motion-graphics 8-second 1920x1080 video. Dark world map, a glowing arc animates from San Francisco to Tokyo over 3s, destination pin drops with a pulse, then camera zooms into Tokyo and the label "LATENCY: 89ms" types on. Use the `nyc-paris-flight` registry block as the base pattern, restyle to teal on charcoal. No narration.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-map-route.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Logo sting with shader transition">
+    > /motion-graphics 5-second 1920x1080 logo sting. Beat 1 (0-2s): the word "ACME" assembles from scattered particles. Beat 2 (2-3s): full-frame `swirl-vortex` shader transition. Beat 3 (3-5s): logo lockup + tagline "Ship faster." settles on white, holds. Use `code-particle-assemble` for the assembly.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-logo-sting.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Product launch from a URL">
+    > /product-launch-video Make a 45-second 1920x1080 launch video for https://linear.app. Energetic but minimal, use the site's own palette and screenshots. Structure: hook stating the problem, 3 feature beats with UI captures and one-line captions, end card with logo + "Try it free". Female TTS voice, confident tone, subtle electronic BGM under -18dB.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-product-launch.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Explainer from pasted text">
+    > /faceless-explainer Turn this into a ~60-second 1080x1920 vertical explainer: [paste your text]. One idea per scene, big typography, diagrams over stock footage, brand color #FF5533 on off-black. Male TTS voice, calm. Embedded captions, keywords highlighted in the brand color.
+
+    With a verbatim script, final duration follows the narration — ask for "~60 seconds", not exactly 60.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-explainer.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="GitHub PR reveal">
+    > /pr-to-video Make a 30-second 1920x1080 feature-reveal video from [PR URL]. Lead with what users get, not the diff; show the key code change with the `code-diff` block for one beat only; end on version number + repo URL. No narration, kinetic captions instead.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-pr-video.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Beat-synced slideshow">
+    > /music-to-video 20-second 1080x1080 video from ./track.mp3 (pick the best 20 seconds of the track) and the 8 photos in ./shots/. Cut on the beat grid, one photo per bar, punch-in on downbeats, `whip-pan` transitions on phrase changes. End on the last photo with "SUMMER '26" in condensed caps. No TTS.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-music-slideshow.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+</AccordionGroup>
+
+### Freeform — no blocks, hand-built HTML/CSS/SVG/GSAP
+
+<AccordionGroup>
+  <Accordion title="Kinetic quote">
+    > 12-second 1920x1080 video, off-white background. The quote "Simplicity is the ultimate sophistication" builds word by word in massive black serif type, each word snapping in with a slight overshoot; "sophistication" lands last in italic with a hand-drawn underline drawing on. Attribution "— Leonardo da Vinci" fades in small, bottom-right, at 9s. Settle into a barely-visible ambient idle to the end. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-kinetic-quote.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Countdown title card">
+    > 6-second 1920x1080 video. Numbers 3, 2, 1 each fill the frame for one second — each number wipes in with a diagonal mask and its background alternates black/white with inverted text. At 3s the frame slams to "LAUNCH DAY" in condensed caps with a screen-shake, holds with a subtle grain flicker. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-countdown.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Bar chart race">
+    > 10-second 1920x1080 video, dark slate background. Title "Top languages 2026" top-left. Five horizontal bars (Python, TypeScript, Rust, Go, Java) grow from zero with staggered starts, overtaking each other twice mid-animation; each bar has a right-edge value label counting up to its final %. End state holds 2s with the leader pulsing once. Hand-draw everything — no chart library. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-bar-race.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Before / after split">
+    > 8-second 1920x1080 video. Vertical split: left half labeled "BEFORE" shows a cluttered mock UI (grey, 12 overlapping windows drawn in CSS), right half "AFTER" shows one clean card. Both halves settle within the first second. A vertical divider line sweeps left to right at 4s, wiping the clutter into the clean state across the full frame. End on "One tool." centered. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-before-after.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Loader → reveal">
+    > 7-second 1920x1080 video, black background. A thin white progress ring draws from 0° to 360° over 4s while a percentage counter (0→100) ticks in the center in mono type, matching the arc exactly. Ring and counter fade out fully by 4.2s; at 4.2s the ring bursts outward into short radial dashes and "READY." stamps into the center, then holds. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-loader-ready.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="3D cards (Three.js)">
+    > 9-second 1920x1080 video, light warm cream background. Build the scene in Three.js via the adapter: three rounded card meshes labeled "Design", "Build", "Ship" lie flat on the ground plane, camera at a fixed 3/4 isometric angle, soft directional light + ambient so the cards cast soft shadows. One at a time each card lifts and straightens upright to face the viewer center-frame while the other two slide apart and dim; then it returns. Finish with all three standing upright in a row by 8.5s, hold. All easing power3.inOut. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-3d-cards.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="SVG line-draw logo reveal">
+    > 6-second 1920x1080 video, deep green background. A minimal mountain-range logo draws on as an SVG stroke over 2.5s, then the stroke fills with cream, the wordmark "NORTHTRAIL" letterspaces in beneath it, and a thin rule expands from center. Hold the last 1.5s. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-svg-logo.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Word-swap headline">
+    > 8-second 1920x1080 video, white background. Static sentence "Make it ___." in huge black type stays centered while the blank cycles through "faster", "simpler", "yours" — each swap flips vertically like a split-flap board, 1.5s apart, with a slight blur on motion. Final word "yours." lands in orange and the period pops. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-word-swap.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Stat tile dashboard">
+    > 10-second 1920x1080 video, near-black background. Four stat tiles slide up in a 2x2 grid, staggered: "99.99% uptime", "42ms p50", "18M req/day", "0 incidents". Each tile's number counts or decrements to its value with its own easing; sparklines draw underneath in teal. At 8s the grid scales back and "Built to hold." fades in above. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-data-ticker.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+  <Accordion title="Vertical social hook">
+    > 9-second 1080x1920 vertical video, charcoal background. Social-style hook: "nobody talks about this" types on center in bold white, then each following phrase replaces it on a hard cut every 1.5s — "it's not your code", "it's your prompts", "here's the fix" — with yellow highlight bars behind key words, alternating tilt. Last phrase holds with an arrow-down bounce. No audio.
+      <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-vertical-hook.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *Rendered from the prompt above, unedited.*
+  </Accordion>
+</AccordionGroup>
diff --git a/docs/prompting/explainers.mdx b/docs/prompting/explainers.mdx
new file mode 100644
index 0000000000..632e5008c0
--- /dev/null
+++ b/docs/prompting/explainers.mdx
@@ -0,0 +1,80 @@
+---
+title: Explainers
+description: "What to say to turn an article, notes, or a topic into a faceless explainer — where every visual is invented, not captured."
+---
+
+## What this makes
+
+A faceless explainer: arbitrary text — an article, notes, a topic, a brief — becomes a narrated video where every visual is invented per scene (typography, abstract graphics, diagrams, data-viz). The [`/faceless-explainer`](/prompting/overview) workflow picks a design system, reshapes your text into a teaching story, generates its own TTS narration, and builds it frame by frame.
+
+**Faceless means there's nothing to capture.** No site, no footage, no asset inventory — the visuals are designed downstream. If you have a product to sell use [`/product-launch-video`](/prompting/product-launch); if you have a real site to show use `/website-to-video`; a GitHub PR goes to [`/pr-to-video`](/prompting/code-and-prs). Unsure → start at `/hyperframes`.
+
+## Base prompt
+
+Verified, from the [examples](/prompting/examples) page — a ~60-second vertical explainer from pasted text:
+
+> /faceless-explainer Turn this into a ~60-second 1080x1920 vertical explainer: [paste your text]. One idea per scene, big typography, diagrams over stock footage, brand color #FF5533 on off-black. Male TTS voice, calm. Embedded captions, keywords highlighted in the brand color.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-explainer.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+Note the `~` — with a supplied script the runtime follows the spoken words, so ask for *about* a minute, not exactly one. See the [anatomy](/prompting/anatomy) for the rest of the skeleton.
+
+## Variants
+
+<AccordionGroup>
+  <Accordion title="30-second landscape topic explainer (16:9)">
+    > /faceless-explainer Make a ~30-second 1920x1080 explainer on how HTTPS keeps a request private, for a non-technical audience — the takeaway: your data is sealed before it leaves the browser. Concept angle: one idea per scene, big geometric type, a simple lock-and-key diagram as the centerpiece (swap the metaphor with the topic). Near-black ink on off-white with a deep-blue accent. Female TTS voice, warm and clear. Embedded captions, key terms highlighted in the accent color.
+
+    Shorter runtime, landscape for YouTube / embed. Fewer scenes means the topic has to compress — naming the takeaway tells the workflow what to keep.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/variant-explainer-landscape.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from this prompt with the topic swapped to HTTP caching (cache diagram as the metaphor), unedited — 26s, because the narration sets the length.*
+
+  </Accordion>
+  <Accordion title="Listicle">
+    > /faceless-explainer Make a ~45-second 1080x1920 listicle: "5 habits of fast-shipping teams". Listicle angle — one habit per scene, each with a big number and a one-line label, escalating energy toward #1. Off-black with a lime accent. Male TTS voice, upbeat. Embedded captions, the habit label highlighted each scene.
+
+    The listicle angle gives each item its own scene with a consistent number-and-label shape, so the structure reads as a countdown rather than a wall of points.
+  </Accordion>
+  <Accordion title="How-to with diagrams">
+    > /faceless-explainer Make a ~60-second 1920x1080 how-to on setting up a CI pipeline, for developers. How-to angle: one step per scene, each built around a simple node-and-arrow diagram that draws on as the narration explains it. Charcoal with a teal accent. Calm male TTS voice. Embedded captions, the step name highlighted.
+
+    A how-to leans on diagrams as the load-bearing visual. Describe the diagram *shape* per step ("node-and-arrow", "a pipeline that fills left to right") and let the workflow invent the specifics.
+  </Accordion>
+</AccordionGroup>
+
+## The knobs that matter
+
+| Knob | What to say | Why it matters |
+| --- | --- | --- |
+| **Verbatim vs summarized** | "use my wording verbatim" or "restructure it freely" | The workflow asks once. Verbatim keeps your voice but locks the word count; summarized lets it cut and reorder for pace |
+| **Duration** | "~60 seconds", never "60 seconds" | With a script the narration sets the real length; a hard number forces the agent to trim or pad the words |
+| **Scene density** | "one idea per scene" | A faceless scene has one invented focal to animate; two ideas in a scene leave nothing to build the motion around, and it reads as a text dump |
+| **Angle** | "concept" / "how-to" / "listicle" / "narrative" | The angle decides the story shape — the workflow reshapes your text into it rather than reading paragraphs in order |
+| **Caption style** | "embedded captions, keywords highlighted in the accent color" | Captions are burned in; naming the highlight color ties them to the palette instead of a default pill |
+| **Palette** | "brand color #FF5533 on off-black" | With no site to borrow from, the preset supplies a full palette; a named accent + ground personalizes it |
+| **Voice** | "male TTS voice, calm" / "warm female voice" | Gender and tone are prompt words; the provider is a workflow decision |
+
+<Tip>
+  The single biggest quality lever here is scene density. "One idea per scene" turns a dense paragraph into a paced sequence — the workflow reorders and compresses your text to hit it, which is exactly what makes an explainer teach instead of recite.
+</Tip>
+
+## Common failure modes
+
+**"60 seconds" instead of "~60 seconds".** A supplied script's spoken duration is not knowable until the TTS renders; a hard target makes the agent mangle the words to hit the clock.
+- ❌ `a 60-second explainer from this text: ...`
+- ✅ `a ~60-second explainer from this text: ...`
+
+**Cramming ideas into a scene.** Every faceless visual is invented around a single focal; overload the scene and there's no clear thing to animate.
+- ❌ `explain all five caching layers in one scene`
+- ✅ `one idea per scene — one caching layer at a time`
+
+**Asking it to capture or pull real imagery.** There is no capture step; a faceless explainer invents its visuals.
+- ❌ `pull screenshots from the site and explain the feature`
+- ✅ that's a site or product video — use `/website-to-video` or [`/product-launch-video`](/prompting/product-launch)
+
+**Leaving the look unspecified when you care.** With no brand to read, the preset picks the palette; if you have colors, name them.
+- ❌ `make it look on-brand`
+- ✅ `brand color #FF5533 on off-black`
diff --git a/docs/prompting/generated-artwork.mdx b/docs/prompting/generated-artwork.mdx
new file mode 100644
index 0000000000..fd6a9084e8
--- /dev/null
+++ b/docs/prompting/generated-artwork.mdx
@@ -0,0 +1,24 @@
+---
+title: When to generate artwork
+description: "Code-drawn wins for UI, type, geometry, and 3D; illustration-led hero art comes from an image model, animated as layers."
+---
+
+Code-drawn HTML/CSS/SVG excels where the medium is native: UI mockups, typography, geometric shapes, charts, pixel art, and 3D via Three.js. For **illustration-led** hero art — characters, painterly scenes, sculptural objects — hand-drawn SVG tops out at clipart quality no matter how well you prompt. The fix is a hybrid:
+
+> Generate the hero artwork as an image (via the media-use skill's image generation), then animate it with code. Anything that must move independently — eyelids, light beams, drawing lines — stays a code layer on top of the static art.
+
+Three rules that make this work:
+
+1. **Generate on a solid contrasting background** (magenta works) so the subject keys out cleanly. A light subject on a light background gets silently eaten.
+2. **Key flat vector-style art with a chroma key** (`ffmpeg colorkey`), not AI background removal — `remove-background`'s matting model is tuned for photographic and human subjects and reads flat art unreliably, sometimes keeping the background instead of the subject. Reserve `remove-background` for photographs.
+3. **Put a restraint clause in the generation prompt** ("minimal, lots of negative space") — image models fill the frame by default, and a busy generated texture reads as cheap as bad vector art.
+
+## The difference, side by side
+
+The same brief — four people arm in arm, warm gradient sweaters, flat-illustration style — built both ways. Same animation beats, same craft layer (lighting, atmosphere, grade); the only variable is where the figures came from.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/artwork-hand-drawn.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Hand-drawn SVG figures — clean, but the proportions and gesture read as clipart.*
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/artwork-generated.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Generated illustration animated as layers — real anatomy and editorial shading; the animated line still passes behind the figures because the artwork was keyed to transparency.*
diff --git a/docs/prompting/iterating.mdx b/docs/prompting/iterating.mdx
new file mode 100644
index 0000000000..c6f0e1aa27
--- /dev/null
+++ b/docs/prompting/iterating.mdx
@@ -0,0 +1,38 @@
+---
+title: Iterating
+description: "Talk to the agent like a video editor — small targeted edits beat re-specification."
+---
+
+HyperFrames is a conversation. After the first render, talk to the agent the way you'd talk to a video editor — don't re-prompt from scratch:
+
+> Make the title 2x bigger.
+
+> Swap to dark mode.
+
+> Add a fade-out at the end and a lower third at 0:03 with my name and title.
+
+> The captions are too small and they overlap the lower third. Move them up and shrink them.
+
+> Replace the background music with `assets/track.mp3`.
+
+The agent already has the composition open and the skills loaded — small targeted edits produce better results than long re-specifications.
+
+## Editing is for nudging, not gambling
+
+Three moves keep iteration convergent instead of circular:
+
+1. **One variable per edit.** Change one thing, render, judge, repeat. A request that moves three things at once ("bigger title, warmer colors, faster cuts") makes it impossible to attribute what helped and what hurt.
+2. **Layer one element type at a time.** Building up a complex scene? Start with the minimal version (subject + its motion only), confirm it reads, then add exactly one layer per pass — camera move, then background motion, then style treatment. Every addition stays attributable.
+3. **Strip, then re-layer.** When a scene keeps misfiring, don't pile on corrections — strip it back to the simplest version that works (freeze the camera, simplify the motion, clear the background), confirm, then reintroduce complexity one layer at a time until you find the ingredient that breaks it.
+
+## Calibrate with absolute targets
+
+When you're dialing in a look, relative corrections oscillate — "make the dots finer" overshoots, "a bit bigger" overshoots back. State targets as absolute values and the agent lands them in one pass:
+
+- ❌ `make the dots 2x finer`
+- ✅ `dot radius = 25% of row spacing, with clear gaps between dots`
+
+- ❌ `the glow is too strong`
+- ✅ `glow at ~35% peak opacity, always subtler than the orb itself`
+
+And freeze what already works: "the framing and motion are right — don't touch them; only change the dot size." Without the freeze clause, a rebuild can drift on axes you'd already settled.
diff --git a/docs/prompting/media-and-audio.mdx b/docs/prompting/media-and-audio.mdx
new file mode 100644
index 0000000000..ebdf57a1ec
--- /dev/null
+++ b/docs/prompting/media-and-audio.mdx
@@ -0,0 +1,104 @@
+---
+title: Media and audio
+description: "Ask for the voiceover, music, sound, captions, cutouts, and assets a composition needs — with the precise, unambiguous phrasing the media pipeline acts on."
+---
+
+HyperFrames owns media *playback*; a companion media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say.
+
+## Voiceover (TTS)
+
+Text-to-speech runs locally through Kokoro — no API key needed — with a HeyGen TTS upsell behind it. Describe the content and the agent picks a fitting voice, or name the voice, tone, and speed directly:
+
+> Generate narration for this script with a professional female voice.
+
+> Add TTS voiceover, British male voice, at 1.1× speed.
+
+The [Vocabulary](/prompting/vocabulary#text-to-speech-voices) table maps content types to Kokoro voices (for example `af_heart` / `af_nova` for a product demo, `am_adam` / `bf_emma` for a tutorial, `af_sky` / `am_michael` for marketing). Name one directly if you already know it; otherwise describe the read and let the agent choose.
+
+- ❌ `add a voice`
+- ✅ `warm, unhurried female narration of the quoted script` — tone and pace are what actually change the delivery
+
+## Background music
+
+Music resolves from a large catalog by mood, and it should almost always sit *under* the narration, not compete with it. Give the mood **and** a loudness target — the pipeline can duck and normalize to a level, so an explicit target lands a mix instead of a guess:
+
+> Add subtle electronic BGM, kept under −18 dB so it stays beneath the voiceover.
+
+> Upbeat tech-launch music bed at a low level, ducking under narration.
+
+- ❌ `add background music` — you'll get a full-volume track fighting the VO
+- ✅ `subtle background music, ducked ~12 dB under the voice` — a mix instruction the pipeline can execute
+
+<Tip>
+  A stated loudness target ("under −18 dB," "ducked under the voice") is the difference between music that supports the piece and music that buries it. When there's narration, always say the bed goes under it.
+</Tip>
+
+## Sound effects
+
+SFX resolve from a small bundled library plus the catalog. Cue them to specific moments — a transition, a stamp-in, an impact — rather than sprinkling them:
+
+> Add a whoosh on each of the three scene transitions.
+
+> Put a soft click on the button press at 0:04.
+
+## Captions and transcription
+
+Captions come from word-level timestamps. When you generate a voiceover, the timing comes with it; for existing footage, transcription produces the timing (Parakeet by default, with a whisper.cpp fallback). Scaffolding a project from a source video can generate captions from its audio directly.
+
+> Transcribe the narration and add karaoke-style captions synced to it.
+
+> Generate captions from `assets/interview.mp4` and style them hype, scale-pop.
+
+Caption *look* is its own vocabulary (tone, size, per-word emphasis) — see [Captions catalog](/prompting/captions-catalog) for the styles. This page is about producing the timed text; that page is about styling it.
+
+## Background removal (transparent cutouts)
+
+The `remove-background` command mattes a subject out of a video or image locally and hands you a transparent WebM you can drop into any scene as a `<video>`:
+
+> Remove the background from `assets/presenter.mp4` and float the subject over the scene.
+
+One caveat is load-bearing: the built-in model is **purpose-built for people** — head-and-shoulders or full-body, reasonably stable framing, a background that contrasts with the subject. It returns a mostly-empty mask on **non-human subjects** (products, animals, objects). If you need to cut out a product, say so — the agent should route to a different tool rather than run the person model and get nothing.
+
+- ❌ `remove the background from this product shot` with the built-in command — the human-matting model can't see it
+- ✅ `matte the presenter out of assets/talk.mp4` (person) — or, for a product, flag that it's a non-human subject so a different matter is used
+
+The [Remove background guide](/guides/remove-background) covers the person-only caveat, the two-layer plate for text-behind-subject, and alternatives for objects and hair-fine mattes.
+
+## Video-in-video and picture-in-picture
+
+Layering footage — a talking head over a scene, a subject in front of a headline, PiP inset — is a compositing prompt. Two grounded rules keep it frame-accurate, and the agent applies them for you, but naming the layout you want helps:
+
+> Put the transparent presenter cutout in the bottom-right, over the chart scene.
+
+> Layer the headline *behind* the presenter so their silhouette occludes the text.
+
+<Note>
+  Two mechanics the workflow skills handle automatically (from the [Remove background guide](/guides/remove-background#compositing-patterns-and-pitfalls)): a cutout that reveals into view is wrapped in a non-timed `<div>` and the *wrapper* is animated (the framework forces `opacity: 1` on timed clips, so animating the video directly does nothing); and both the base video and the cutout mount at `data-start="0"` so their decoders stay in sync at the cut. You rarely need to say this — but it's why "late-mounting" a PiP clip can land a frame off.
+</Note>
+
+## The supplied-assets rule
+
+The single most reliable media instruction is an explicit path. The agent will search when you describe an asset, but a path removes every ambiguity about *which* file — and for your own brand assets, it's the only way to guarantee the right one:
+
+- ❌ `use my logo`
+- ✅ `use assets/logo.svg`
+
+This matters even when resolution would otherwise work: brand and entity assets should point at *your* file, not a resolved lookalike. (Third-party logos are a separate case — the pipeline pulls official marks from a logo cascade and never hand-redraws them, so "add the LinkedIn logo" is fine; "add my company's logo" needs a path.)
+
+## Say what "no sound" actually means
+
+The most common audio mistake is a negative that means less than you think. "No narration" removes the voiceover — it does **not** silence music or sound effects. If you want genuine silence, say so:
+
+- ❌ `no narration` when you mean a completely silent video — music and SFX can still be added
+- ✅ `no audio at all` — the unambiguous way to ask for silence
+
+This mirrors the negatives discipline in [Anatomy](/prompting/anatomy): close the gap explicitly, because the engine acts on the literal words.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Vocabulary" href="/prompting/vocabulary">Voice names, caption tones, and audio-reactive mappings</Card>
+  <Card title="Captions catalog" href="/prompting/captions-catalog">Styling the timed text this page produces</Card>
+  <Card title="Remove background guide" href="/guides/remove-background">The matting command, its person-only caveat, and alternatives</Card>
+  <Card title="Video components" href="/guides/video-components">Installable overlays, captions, and effects</Card>
+</CardGroup>
diff --git a/docs/prompting/motion-graphics.mdx b/docs/prompting/motion-graphics.mdx
new file mode 100644
index 0000000000..b557ce57e7
--- /dev/null
+++ b/docs/prompting/motion-graphics.mdx
@@ -0,0 +1,75 @@
+---
+title: Motion graphics
+description: "Short, design-led pieces where motion is the message — kinetic type, a stat hit, a logo sting — and the knobs that decide MP4 versus transparent overlay."
+---
+
+## What a motion graphic is
+
+A motion graphic is a short, design-led piece where **motion is the message** — kinetic typography, a stat count-up, a chart hit, a logo sting, a lower-third or social overlay, an animated map, tweet, or headline. It's usually under 10 seconds (up to ~30s), has no narration and no live-action subject, and renders to an MP4 or a transparent overlay.
+
+Route with `/motion-graphics`. The workflow is autonomous by design — at most one clarifying question, then straight through to render. Reach for a different workflow when the piece grows past what "motion is the message" covers:
+
+| If the piece is… | Route instead |
+| --- | --- |
+| Longer, multi-scene, or narrated | `/general-video` |
+| A narrated video of a website | `/website-to-video` |
+| A topic explainer with a voice-over | `/faceless-explainer` |
+| A product promo / launch | `/product-launch-video` |
+| Captions on existing footage | `/embedded-captions` |
+
+## Base prompt
+
+The canonical shape: routed, spec'd, beat-timestamped, copy quoted, technique pinned, gaps closed.
+
+> /motion-graphics Make an 8-second 1920x1080 video. Beat 1 (0-4s): dark macOS terminal types "npx skills add heygen-com/hyperframes" character by character, then hold on the blinking cursor. Beat 2 (4-5s): the terminal shatters into fragments. Beat 3 (5-8s): bold white kinetic text on black slams in word by word, snappy: "YOU JUST MADE THIS / WITH HYPERFRAMES." Adapt the `code-typing` and `vfx-shatter` registry blocks; hand-author the kinetic text. No narration, no image or media files.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-anatomy-terminal.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+## Variants
+
+Each reuses a registry block, so the agent composes rather than hand-building from scratch.
+
+<AccordionGroup>
+  <Accordion title="Stat count-up">
+    > /motion-graphics 6-second 1920x1080 video, dark navy background. Beat 1 (0-1s): label "ARR" fades up small, top-center. Beat 2 (1-4s): a giant number counts up to $4.2M with an odometer roll, easing out as it lands. Beat 3 (4-6s): "+312% YoY" stamps in below in green, then everything settles into a gentle ambient idle (subtle breathing scale, slow particle drift). Use the `apple-money-count` registry block as base. No narration.
+  </Accordion>
+  <Accordion title="Logo sting">
+    > /motion-graphics 5-second 1920x1080 logo sting. Beat 1 (0-2s): the word "ACME" assembles from scattered particles. Beat 2 (2-3s): full-frame `swirl-vortex` shader transition. Beat 3 (3-5s): logo lockup + tagline "Ship faster." settles on white, then holds with a subtle ambient idle (slow breathing scale). Use `code-particle-assemble` for the assembly.
+  </Accordion>
+  <Accordion title="Animated tweet">
+    > /motion-graphics 7-second 1080x1350 vertical video. A real tweet card (handle @hyperframes, text "we render video from HTML now. no timeline UI. just code.") slides up over a soft animated gradient, likes counter ticks 0→1.2K, then the card tilts in 3D and a highlight sweeps the second sentence. Settle into a gentle ambient idle on the card at the end. Use the `x-post` and `vfx-liquid-background` registry blocks. No narration, no image or media files.
+  </Accordion>
+  <Accordion title="Map route">
+    > /motion-graphics 8-second 1920x1080 video. Dark world map, a glowing arc animates from San Francisco to Tokyo over 3s, destination pin drops with a pulse, then camera zooms into Tokyo and the label "LATENCY: 89ms" types on. Use the `nyc-paris-flight` registry block as the base pattern, restyle to teal on charcoal. No narration.
+  </Accordion>
+</AccordionGroup>
+
+## The knobs that matter
+
+**Duration.** Keep it short — motion graphics live under 10 seconds, up to ~30. A 2-second idea stretched to 8 feels slow no matter how it's animated; if the piece genuinely needs multiple scenes or a longer runtime, it's a `/general-video`, not a motion graphic.
+
+**MP4 vs transparent overlay.** The default output is an MP4. Ask for a transparent overlay — a lower-third, a callout, a bug meant to composite over other footage — and the render targets `webm` or `mov` with alpha. Transparency only makes sense when part of the frame is *meant* to be empty. A full-frame design (its own background, edge-to-edge composition) has nothing to be transparent, so asking for a transparent WebM there produces either an opaque file or a broken-looking one. Say "transparent overlay, alpha channel" only for pieces designed to sit on top of something else.
+
+**Registry blocks vs freeform.** Naming a block (`apple-money-count`, `x-post`, `data-chart`, `code-typing`, `us-map` / `world-map`) makes the agent compose reuse-first: install the block, customize in place, hand-author only the gaps. Omit the block and it hand-builds from your description — fine for one-off looks, more drift on the details you didn't pin. Name blocks exactly as they appear in the [catalog](/catalog/blocks/data-chart).
+
+**Easing and motion feel.** The words you use for *how* motion feels — "snappy", "bouncy", "settles with overshoot" — map to specific eases. Spend them; they're cheap precision. See [Vocabulary](/prompting/vocabulary) for the adjective-to-ease table and [Premium motion](/prompting/motion) for the grammar that keeps a piece from reading cheap (nothing fully stops, action overlaps, the camera acts).
+
+## Failure modes
+
+**Transparent output on a full-frame design.** Alpha is for overlay elements, not for pieces that fill the frame. A design with its own background has no transparent region to export.
+- ❌ `an 8s full-screen stat count-up on dark navy — export as a transparent WebM`
+- ✅ `an 8s stat count-up on dark navy, MP4` — or, for a bug to composite over footage: `just the count-up chip, no background, transparent overlay (webm)`
+
+**Narration on a motion-is-the-message piece.** Motion graphics are unnarrated by definition — the visual carries it. A voice-over means a different workflow.
+- ❌ `/motion-graphics a 10s logo sting with a voice-over reading the tagline`
+- ✅ `/motion-graphics a 10s logo sting, no narration` — for a spoken track, use `/faceless-explainer` or `/general-video`.
+
+**Stretching a short idea long.** Runtime is a knob, and past ~30s a single motion beat runs out of things to do.
+- ❌ `a 45-second kinetic-type piece of one headline`
+- ✅ `an 8-second kinetic-type piece of one headline` — or promote it to a multi-scene `/general-video`.
+
+<Tip>
+  For the six-part skeleton and the per-beat content formula these prompts share, see [Prompt anatomy](/prompting/anatomy); for the full set of run-verified examples, [Verified examples](/prompting/examples). Unsure whether your ask is a motion graphic at all? Start at the router in `/hyperframes`.
+</Tip>
diff --git a/docs/prompting/motion.mdx b/docs/prompting/motion.mdx
new file mode 100644
index 0000000000..d69267ea24
--- /dev/null
+++ b/docs/prompting/motion.mdx
@@ -0,0 +1,25 @@
+---
+title: Motion that reads premium
+description: "Six motion-grammar rules from frame-by-frame study of professional work — nothing stops, the camera acts, action overlaps."
+---
+
+Static frames can be perfect and the video still feels cheap if the motion is dead. Professional motion design follows a grammar you can put directly in prompts:
+
+1. **Nothing ever fully stops.** Every "hold" carries ambient idle motion — a 1-2% breathing scale, slow drift, a shimmer. Never write "holds motionless"; write "settles into a gentle ambient idle." A frozen final second is the single biggest cheap-motion tell.
+2. **The camera is an actor.** Give each scene one continuous camera move — a 4-8% push-in, a slow orbit, parallax between layered planes — easing gently but never settling on screen (compute the ease over a window slightly longer than the render).
+3. **Overlapping action.** No two elements share a start or end time. Entrances stagger at irregular offsets; the next element begins while the last is still settling.
+4. **Overshoot and follow-through.** Every pop scales past its target and settles back; letters can tumble in individually with rotation.
+5. **Depth planes.** One or two large, heavily-blurred foreground elements drifting near the lens sell depth instantly.
+6. **Match pacing to genre.** Showreel-style cuts run 1.5-4 seconds per idea; a stretched 8-second version of a 2-second idea feels slow no matter how it's animated.
+
+## The grammar, measured
+
+The same composition built twice — identical content, identical layout; the only variable is the motion treatment. The first build commits the anti-patterns above: simultaneous identical entrances, no camera, a frozen final 2.4 seconds. The second applies the six rules.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-before.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Every anti-pattern: tiles enter together, nothing overlaps, the last seconds are a freeze-frame.*
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/motion-after.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*The six rules: staggered overshoot entrances, a continuous 5% push, ambient idle, a blurred foreground plane, sparkline draw-ins as secondary motion.*
+
+The difference is measurable, not just visible: in the final second the frozen build has bit-identical consecutive frames, while the motion-grammar build changes every single frame — corroborated by the encoder (211KB vs 2.5MB for the same content). A frozen final second is the cheap-motion tell you can test for.
diff --git a/docs/prompting/music-and-slideshows.mdx b/docs/prompting/music-and-slideshows.mdx
new file mode 100644
index 0000000000..c6a45282ca
--- /dev/null
+++ b/docs/prompting/music-and-slideshows.mdx
@@ -0,0 +1,75 @@
+---
+title: Music videos and slideshows
+description: "Two music- and slide-driven outputs that look alike in a brief but ship differently — a beat-synced MP4 versus a navigable deck — and how to route to the right one."
+---
+
+## Two outputs that a brief blurs together
+
+"Make a slideshow from these photos and this track" and "make a slideshow deck for my pitch" both say *slideshow*, but they produce different things and route to different workflows. Name the output you want up front.
+
+| You want | Route | Output |
+| --- | --- | --- |
+| Photos / clips cut to a music track, exported as a video | `/music-to-video` | A beat-synced **MP4** with audio |
+| A presentation you click through — slides, reveals, speaker notes | `/slideshow` | A **navigable deck**, not an MP4 |
+
+`/music-to-video` turns a **music track** — an audio file, a video to pull audio from, or a track generated from a mood brief — into a beat-synced video. The music drives all pacing; any photos or clips you supply are cut onto the same beat grid, and a complete video needs zero assets (typography carries it otherwise). There is no narration and no website capture.
+
+`/slideshow` authors a HyperFrames deck — discrete slides with fragment reveals, hotspot branching, and a built-in presenter mode with speaker notes. Its output is the **running deck**, served with `hyperframes present`. Do not point `render` at a deck: it resolves only the first scene and emits a silently truncated MP4. If the user didn't explicitly ask for a slideshow, the skill confirms the deck route before authoring — that's a routing decision, not a style preference. One authoring detail worth knowing: fragment reveal times are absolute positions on the deck's master timeline, not per-slide offsets.
+
+## Base prompt — beat-synced slideshow
+
+The verified starting point: photos cut to a track, exported to a square MP4.
+
+> /music-to-video 20-second 1080x1080 video from ./track.mp3 (pick the best 20 seconds of the track) and the 8 photos in ./shots/. Cut on the beat grid, one photo per bar, punch-in on downbeats, `whip-pan` transitions on phrase changes. End on the last photo with "SUMMER '26" in condensed caps. No TTS.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-music-slideshow.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+Every timing decision here is delegated to the track's own analysis — you describe the *treatment* ("one photo per bar", "punch-in on downbeats"), and the beat grid supplies the *times*.
+
+## Variants
+
+<AccordionGroup>
+  <Accordion title="Lyric video">
+    > /music-to-video 30-second 1080x1920 lyric video from ./song.mp3 (pick the strongest 30-second section — a verse into the hook). Transcribe the vocals for word timing. Lines rise in one at a time on the beat, big condensed type on a dark grain background; the hook lands with each word punching in on its downbeat. Keyword in each line highlighted in acid green. No photos — typography only. No TTS.
+
+    Word-level timing comes from transcribing the track (or from lyrics you paste, placed on the beat grid). No supplied assets needed — type is the whole video.
+  </Accordion>
+  <Accordion title="Kinetic promo from a mood brief (no track)">
+    > /music-to-video 15-second 1080x1080 kinetic promo. No track supplied — generate one: driving synthwave, high energy. Cut hard on the beat: full-frame word cards ("FASTER", "SHARPER", "SHIP IT") slam in on downbeats, alternating black/white with inverted type, a glitch flash on each phrase change. End on the wordmark "NOVA" holding with a subtle ambient idle. No TTS.
+
+    With no audio supplied, the track is generated from the mood you describe; the beat grid it produces still drives every cut. Fast, high-energy briefs suit this workflow best.
+  </Accordion>
+  <Accordion title="Presentation deck (slideshow)">
+    > /slideshow Build a 5-slide pitch deck, 1920x1080. One idea per slide, each headline a complete-sentence claim (not a label), punchline first. Slide 2 reveals three pain points one at a time as fragments. Slide 3 shows bottom-up market math (accounts × ACV), not a bare "$40B TAM". Add presenter notes to every slide, and a hotspot on slide 3 that branches to a "sizing methodology" detail slide. I'll present it with `hyperframes present`.
+
+    This produces a clickable deck, not a video. Fragments are reveal hold-points inside a slide; the hotspot branches off the main line and returns on Back. Headlines follow the deck's hard rules — complete-sentence claims, one idea + one visual per slide, font no smaller than a 30pt equivalent.
+  </Accordion>
+</AccordionGroup>
+
+## The knobs that matter
+
+**The beat grid.** `/music-to-video` analyzes the track once into energy phases, onsets, rolls, silences, hard stops, and phrases, then cuts at real musical changes. You steer *how* it cuts, not *when*: "one photo per bar" sets cut density, "punch-in on downbeats" adds the accent, "transitions on phrase changes" reserves the visible moves for structural boundaries. On genuinely rhythmic music the grid is trustworthy and cuts snap to the beat; on calm music the grid is a metronome the analyzer imposed, so the skill paces by phrase and energy instead of hard-cutting — say "let it flow, no hard cuts" if the track is ambient.
+
+**Track section — describe, don't timestamp.** Ask for "the best 20 seconds" or "the verse into the hook" and let the analyzer choose boundaries that land on musical anchors. Hard timestamps ("use 0:32–0:52") cut mid-phrase and fight the grid.
+
+**Asset supply.** Zero assets is valid — typography and templates carry a complete video. Any photos or clips you hand it are woven in *on the same beat grid* (beat-cut or Ken Burns), so more assets means more to cut between, not a different pacing model. Point at a directory ("the 8 photos in ./shots/") and name the end card.
+
+**Deck structure (slideshow).** Fragments (reveal hold-points), hotspots + branch sequences (off-line detail slides), and presenter notes are the deck's structural knobs. Ask for them by name — "reveal the bullets as fragments", "branch to a detail slide from a hotspot", "add speaker notes" — and the island wiring follows.
+
+## Failure modes
+
+**Hard track timestamps.** The whole point of `/music-to-video` is that the track's structure sets the cuts. A literal time window ignores the analyzed beat grid and lands cuts mid-phrase.
+- ❌ `use the section from 0:32 to 0:52`
+- ✅ `pick the best 20 seconds of the track`
+
+**Expecting an MP4 from `/slideshow`.** A deck is authored as several top-level scenes with no master-root composition, so `render` resolves only the first one and truncates. The supported outputs are the live `present` deck and per-slide snapshots.
+- ❌ `/slideshow ... then render it to deck.mp4`
+- ✅ `/slideshow ... I'll present it with hyperframes present` — or, if you actually need a rendered video, use `/music-to-video` (beat-synced) or `/general-video`.
+
+**Wrong workflow for the output.** Photos set to music that you'll export and post is `/music-to-video`; a thing you click through live is `/slideshow`. Picking by the word "slideshow" alone builds the wrong deliverable.
+
+<Tip>
+  Both prompts here are unnarrated. `/music-to-video` has no TTS by design; if you want a spoken voice-over instead of a music bed, that's a different workflow (see the router in `/hyperframes`). For the six-part skeleton these prompts share, see [Prompt anatomy](/prompting/anatomy); for adjectives that map to eases and transitions, [Vocabulary](/prompting/vocabulary).
+</Tip>
diff --git a/docs/prompting/overlays-and-lower-thirds.mdx b/docs/prompting/overlays-and-lower-thirds.mdx
new file mode 100644
index 0000000000..04289893c9
--- /dev/null
+++ b/docs/prompting/overlays-and-lower-thirds.mdx
@@ -0,0 +1,103 @@
+---
+title: Overlays and lower thirds
+description: "Prompt named lower-third and social-post overlay blocks with timing, copy, and brand tone."
+---
+
+## What overlays do and when they trigger
+
+Overlays are timed blocks that sit on top of your footage or scene — a lower third that names a speaker, a broadcast ticker, or a replica social-media card. Because each is a timed clip, prompts trigger this layer when you ask to *add* something *at* a moment: "add a lower third at 0:03 with the name and title," "show an animated tweet during the intro," "put a Spotify now-playing card in the corner." Give the timestamp, the copy, and the tone; the agent places the block on a track above the footage.
+
+Two groups:
+
+- **[Lower thirds](/catalog/blocks/lt-clean-bar)** — name/title identifiers for speakers, interviews, podcasts, and news.
+- **[Social overlays](/catalog/blocks/x-post)** — animated replicas of platform UI (posts, cards, notifications, follow prompts).
+
+## Brand tone → lower third
+
+Lower thirds split into **cards** (a filled shape behind the text) and **cardless** (text with a rule or sweep, designed to overlay live footage without boxing it in).
+
+| Tone | Blocks |
+| ---- | ------ |
+| **Minimal / clean / corporate** | [`lt-clean-bar`](/catalog/blocks/lt-clean-bar), [`lt-soft-pill`](/catalog/blocks/lt-soft-pill) |
+| **High-energy / podcast / bold** | [`lt-bold-block`](/catalog/blocks/lt-bold-block), [`lt-color-block`](/catalog/blocks/lt-color-block) |
+| **Cardless over footage** (interview, talking head) | [`lt-accent-underline`](/catalog/blocks/lt-accent-underline), [`lt-kicker-name`](/catalog/blocks/lt-kicker-name), [`lt-mask-reveal`](/catalog/blocks/lt-mask-reveal), [`lt-side-rule`](/catalog/blocks/lt-side-rule) |
+| **Card over bright footage** | [`lt-dark-card`](/catalog/blocks/lt-dark-card) |
+| **Broadcast / news** | [`lower-third-bild`](/catalog/blocks/lower-third-bild), [`news-ticker`](/catalog/blocks/news-ticker) |
+| **Two-part wipe (name + role)** | [`lt-stack-bars`](/catalog/blocks/lt-stack-bars) |
+
+<Tip>
+  Over live footage, prefer a **cardless** lower third — they're text-shadowed for legibility without a box that fights the shot. Use a **card** ([`lt-dark-card`](/catalog/blocks/lt-dark-card) charcoal for bright scenes) when the background is too busy for cardless text to read.
+</Tip>
+
+## Use → social overlay
+
+Each social overlay is a self-contained animated card with editable placeholder content.
+
+| You want | Block |
+| -------- | ----- |
+| An animated tweet / X post with engagement metrics | [`x-post`](/catalog/blocks/x-post) |
+| A Reddit post card with upvotes and comments | [`reddit-post`](/catalog/blocks/reddit-post) |
+| A Spotify now-playing card with album art and progress | [`spotify-card`](/catalog/blocks/spotify-card) |
+| A macOS notification banner | [`macos-notification`](/catalog/blocks/macos-notification) |
+| An Instagram follow prompt | [`instagram-follow`](/catalog/blocks/instagram-follow) |
+| A TikTok follow prompt | [`tiktok-follow`](/catalog/blocks/tiktok-follow) |
+| A YouTube subscribe lower third | [`yt-lower-third`](/catalog/blocks/yt-lower-third) |
+
+## Example prompts
+
+Quote the exact copy — unquoted names and titles get paraphrased (see [anatomy](/prompting/anatomy)).
+
+> Add a lower third at 0:03 for 5 seconds, on a track above the footage, with [`lt-clean-bar`](/catalog/blocks/lt-clean-bar). Name: "Dana Ríos". Title: "Head of Design".
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-lower-third.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above over stand-in footage, unedited.*
+
+
+<Note>
+  Give a lower third at least the block's own timeline length (most run ~5 seconds including their designed exit) — a shorter window hard-cuts the block before its settle-out animation plays.
+</Note>
+
+> Podcast clip. Bring in [`lt-bold-block`](/catalog/blocks/lt-bold-block) when the guest starts talking, holding 5 seconds — name "MARCUS LEE", tag "GUEST" — brand accent #FF5A1F.
+
+> During the intro, show an [`x-post`](/catalog/blocks/x-post) card with the quote "we shipped it in a weekend" and 12.4K likes, then slide it out before the demo.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/overlay-xpost.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above over stand-in scenes, unedited — the card's built-in like-tap ticks 12.4K → 12.5K.*
+
+
+> /motion-graphics Transparent overlay only — a [`spotify-card`](/catalog/blocks/spotify-card) now-playing widget animating in, bottom-left. Export as transparent WebM so I can drop it over footage in my editor.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/overlay-spotify-preview.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*MP4 preview of the transparent WebM over a checkerboard — the delivered file carries real VP9 alpha (verified via ALPHA_MODE + alphaextract).*
+
+
+## Knobs
+
+- **Timing.** "at 0:03," "for 4 seconds," "slide it out before the demo" set the block's start and duration — an overlay is a timed clip, so it needs both.
+- **Copy.** Quote every editable field: name, title, handle, headline, metrics, ticker text. The blocks ship with placeholder content you replace.
+- **Track placement.** Overlays go on a track *above* the footage so they composite on top; say "over the footage" if you're layering onto an existing clip.
+- **Brand accent.** Give a hex or brand color — most lower thirds carry an accent bar, tab, or block that takes it.
+- **Card vs cardless.** State it when it matters, or let the tone table decide.
+- **Transparent output.** For use in an external NLE, render the overlay on its own as a transparent WebM — see [rendering and output](/prompting/rendering-and-output).
+
+## Failure modes
+
+**Don't leave the copy unquoted.** Unquoted names and titles get paraphrased; quoted text renders verbatim.
+- ❌ `add a lower third with the speaker's name and role`
+- ✅ `lt-clean-bar — name: "Dana Ríos", title: "Head of Design"`
+
+**Don't omit the timestamp.** An overlay is a timed clip; without a start (and ideally a duration) the agent has to guess when it appears and how long it holds.
+- ❌ `put a lower third somewhere in the intro`
+- ✅ `lower third at 0:03, holding 4 seconds`
+
+**Don't let the overlay render behind the footage.** It has to sit on a track above the clip, or the video covers it.
+- ❌ `add the tweet card to the video` (ambiguous layering)
+- ✅ `x-post card on a track above the footage, top-right`
+
+**Don't over-spec real account data.** These are stylized replicas with editable placeholders — provide the copy you want shown, not a live URL to scrape.
+- ❌ `pull my actual Spotify page`
+- ✅ `spotify-card: track "Midnight City", artist "M83"`
+
+**Don't invent overlay names.** Only the blocks in the [Social Overlays](/catalog/blocks/x-post) and [Lower Thirds](/catalog/blocks/lt-clean-bar) groups exist.
+- ❌ `add a linkedin-post overlay`
+- ✅ pick a real block, or describe the card and let the agent build a custom one in a freeform composition
diff --git a/docs/prompting/overview.mdx b/docs/prompting/overview.mdx
new file mode 100644
index 0000000000..f331515299
--- /dev/null
+++ b/docs/prompting/overview.mdx
@@ -0,0 +1,147 @@
+---
+title: Prompt Guide
+description: "How to prompt AI agents to author HyperFrames videos — setup, the two prompt shapes, and the map of this guide."
+---
+
+HyperFrames is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage.
+
+<Note>
+  **Before you prompt**, have three things in place: the skills installed (below), a scaffolded project (`npx hyperframes init my-video`), and the live preview running (`npx hyperframes preview`) so you can judge each render the moment it lands. Prompting without the preview open turns every iteration into a blind guess.
+</Note>
+
+## One-time setup
+
+Install the skills in your project (or globally for your agent):
+
+```bash
+npx skills add heygen-com/hyperframes
+```
+
+The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow.
+
+**Core skills — install all of these**
+
+| Slash command           | What it loads                                                              |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `/hyperframes`          | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow |
+| `/hyperframes-core`     | Composition contract — HTML structure, `data-*` attributes, clips, tracks  |
+| `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) |
+| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats   |
+| `/hyperframes-cli`      | Dev-loop CLI — `init`, `lint`, `inspect`, `preview`, `render`, `doctor`    |
+| `/media-use`            | Media OS — TTS voiceover (`tts`), `transcribe`, `remove-background`, plus BGM / SFX / image resolution |
+| `/hyperframes-registry` | Block and component installation via `hyperframes add`                     |
+| `/general-video`        | The general authoring workflow — fallback for any video that doesn't match a specific workflow below |
+
+**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)
+
+| Slash command            | Input → output                                                              |
+| ------------------------ | --------------------------------------------------------------------------- |
+| `/product-launch-video`  | A product URL / brief / script → launch or promo video                      |
+| `/website-to-video`      | A general website / URL → a video of the site (tour / showcase / social clip) |
+| `/faceless-explainer`    | Arbitrary text (no URL) → faceless explainer with its own TTS narration     |
+| `/pr-to-video`           | A GitHub PR → code-change explainer                                         |
+| `/embedded-captions`     | An existing talking-head video → the same footage with captions / subtitles |
+| `/talking-head-recut`      | An existing talking-head video → footage packaged with designed graphic cards |
+| `/motion-graphics`       | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
+| `/music-to-video`        | A music track + your images → beat-synced video (lyric / slideshow / kinetic promo) |
+| `/slideshow`             | A deck outline or slides → navigable presentation with presenter mode (not a rendered MP4) |
+| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML         |
+
+<Tip>
+  To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start HyperFrames prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
+</Tip>
+
+
+
+## Claude Design
+
+Claude Design uses a different setup. Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub (click the ↓ button), then **attach it to your chat** (don't paste the URL — file attachments produce better output):
+
+```text
+Use the attached skill. 25-second LinkedIn video for my startup.
+
+Problem: Sales teams waste 3 hours/day on manual CRM updates.
+Solution: AutoCRM — AI that logs every call, email, and meeting.
+Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
+CTA: autocrmhq.com
+```
+
+Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.
+
+
+
+## The two prompt shapes
+
+Most successful HyperFrames prompts fall into one of two shapes.
+
+### Cold start — describe the video
+
+You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head.
+
+> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
+
+> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
+
+Cold-start prompts work best when you specify:
+
+- **Duration** (e.g. "10 seconds", "30s", "5 scenes of 3s each")
+- **Aspect ratio** ("16:9", "9:16 vertical", "1:1 square") — defaults to 1920x1080 otherwise
+- **Mood / style** ("minimal Swiss grid", "warm grain analog", "high-energy social")
+- **Key elements** (title, lower third, captions, background video, music)
+
+### Warm start — turn context into a video
+
+You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where HyperFrames shines because the agent does the research/summarization step *and* the production step in one flow.
+
+> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`.
+
+> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.
+
+> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`.
+
+> Turn this CSV into an animated bar chart race using `/hyperframes`.
+
+Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy.
+
+
+
+## Recommended workflow
+
+1. `npx hyperframes init my-video` — scaffold a project (skills install automatically)
+2. Open the project in Claude Code (or Cursor / Codex)
+3. Prompt with `/hyperframes` and one of the shapes above
+4. `npx hyperframes preview` — watch in the browser as the agent edits
+5. Iterate with small targeted prompts
+6. `npx hyperframes render --output final.mp4` when you're happy
+
+
+
+## What a prompt buys you
+
+Three prompts from this guide and their unedited renders — one workflow warm start, one registry-block piece, one dense freeform spec:
+
+> /product-launch-video Make a 45-second 1920x1080 launch video for https://linear.app. Energetic but minimal, use the site's own palette and screenshots. Structure: hook stating the problem, 3 feature beats with UI captures and one-line captions, end card with logo + "Try it free". Female TTS voice, confident tone, subtle electronic BGM under -18dB.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-product-launch.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+> /motion-graphics 6-second 1920x1080 video, dark navy background. Beat 1 (0-1s): label "ARR" fades up small, top-center. Beat 2 (1-4s): a giant number counts up to $4.2M with an odometer roll, easing out as it lands. Beat 3 (4-6s): "+312% YoY" stamps in below in green, then everything settles into a gentle ambient idle. Use the `apple-money-count` registry block as base. No narration.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-stat-countup.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+And at the far end of the [specification dial](/prompting/specification-dial), a full visual+motion spec one-shots a broadcast-style animated globe — see [Recreating something you saw](/prompting/recreating-references) for the spec:
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/recreate-globe-oneshot.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*One-shot render from the distilled spec, no iteration.*
+
+## Explore the guide
+
+<CardGroup cols={2}>
+  <Card title="Prompt anatomy" href="/prompting/anatomy">The six-part skeleton every one-shot prompt shares</Card>
+  <Card title="Verified examples" href="/prompting/examples">18 copy-paste prompts, each one-shots a finished video</Card>
+  <Card title="The specification dial" href="/prompting/specification-dial">How much to specify, and what density buys</Card>
+  <Card title="Vocabulary" href="/prompting/vocabulary">Words that map to specific framework settings</Card>
+  <Card title="Premium motion" href="/prompting/motion">The six-rule grammar that keeps video from feeling cheap</Card>
+  <Card title="Recreating references" href="/prompting/recreating-references">Match something you saw, from text alone</Card>
+</CardGroup>
diff --git a/docs/prompting/product-launch.mdx b/docs/prompting/product-launch.mdx
new file mode 100644
index 0000000000..144f12ecb1
--- /dev/null
+++ b/docs/prompting/product-launch.mdx
@@ -0,0 +1,93 @@
+---
+title: Product launch videos
+description: "What to say to turn a product URL, a script, or a brief into a launch or promo video — and when to reach for a site tour instead."
+---
+
+## What this makes
+
+A launch or promo that *sells*: SaaS promos, feature reveals, product demos, app and company launches. The [`/product-launch-video`](/prompting/overview) workflow captures the product's site (or takes a pasted script), reads its brand, writes a story, and builds it frame by frame.
+
+**Route it right — the distinction is intent, not input:**
+
+| You want… | Route |
+| --- | --- |
+| To market, launch, promote, or reveal a product (the default for any commercial URL) | `/product-launch-video` |
+| A video *of* a general site — a portfolio / blog / docs / landing-page tour or showcase, not a sales pitch | `/website-to-video` (see the [guide](/guides/website-to-video)) |
+
+"Promo for our site" is a launch, even though it names a site — use `/product-launch-video`. A neutral walkthrough of a docs site is a tour — use `/website-to-video`. Unsure → start at `/hyperframes` and let it route.
+
+## Base prompt
+
+Verified, from the [examples](/prompting/examples) page — a 45-second launch from a live URL:
+
+> /product-launch-video Make a 45-second 1920x1080 launch video for https://linear.app. Energetic but minimal, use the site's own palette and screenshots. Structure: hook stating the problem, 3 feature beats with UI captures and one-line captions, end card with logo + "Try it free". Female TTS voice, confident tone, subtle electronic BGM under -18dB.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-product-launch.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited.*
+
+
+Read the [anatomy](/prompting/anatomy) of that skeleton — route, spec, structure, copy, voice, level — then swap in your own product.
+
+## Variants
+
+<AccordionGroup>
+  <Accordion title="20-second vertical teaser (9:16)">
+    > /product-launch-video Make a ~20-second 1080x1920 teaser for https://linear.app. Super minimal, just the hook. Beat 1 (0-4s): the problem in one line, big type. Beat 2 (4-16s): two feature beats, one UI capture each with a three-word caption. Beat 3 (16-20s): logo + "Try it free" end card, then settle into a gentle idle. Use the site's own palette. Female TTS voice, confident; no BGM.
+
+    A teaser trades feature coverage for pace — fewer beats, one idea each. Keep the destination (Shorts / TikTok → 9:16) and let the workflow scale the story to the shorter runtime.
+  </Accordion>
+  <Accordion title="Pasted script, no capture">
+    > /product-launch-video Make a ~20-second 1920x1080 launch video from this script — use it verbatim: "Your CRM is three hours of busywork a day. AutoCRM logs every call, email, and meeting for you. 200 teams already switched. Try it free at autocrmhq.com." No site to capture — invent clean product-y visuals from the script. Male TTS voice, calm and confident; subtle BGM under -18dB.
+
+    With no URL the workflow takes the no-capture path: no screenshots, no site palette to borrow, so name your brand colors and fonts if you have them (or the agent invents a palette). Verbatim scripts set the duration — figure roughly 130 spoken words per minute, so a 30-second video wants a 65–70 word script. Saying "use it verbatim" pre-answers the workflow's keep-or-restructure question.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/variant-launch-script.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from this prompt shape with a different, longer script (78 words, fictional dev-tool "Relay"), unedited — it ran 35.5s because the words set the length.*
+
+  </Accordion>
+  <Accordion title="Brand name only (agent finds the URL)">
+    > /product-launch-video Make a ~45-second 1920x1080 launch video for Linear. Find the official site, capture it, and use its own palette and screenshots. Angle: speed as the whole pitch. End card with logo + "Try it free". Confident female TTS voice, subtle electronic BGM under -18dB.
+
+    Given a name instead of a link, the workflow searches for the official URL, confirms it in one line, then captures — you get the site-grounded result without pasting the link yourself.
+  </Accordion>
+  <Accordion title="Site tour instead (website-to-video)">
+    > /website-to-video Make a 30-second 1920x1080 tour of https://example.com built from its own screenshots. Calm, editorial pace — show the homepage, two inner pages, and the footer. Full narration, warm male voice. This is a showcase, not a sales pitch.
+
+    Reach for this when the goal is to *show the site*, not sell a product. It builds from captured screenshots and the site's brand assets. A launch or promo — even from the same URL — belongs to `/product-launch-video`.
+  </Accordion>
+</AccordionGroup>
+
+## The knobs that matter
+
+Decisions specific to a launch. Set the ones you care about; leave the rest to the workflow's taste.
+
+| Knob | What to say | Why it matters |
+| --- | --- | --- |
+| **Capture vs no-capture** | Give a URL to capture the real site; give a script or brief for the no-capture path; give just a brand name to have the agent find the URL | Capture borrows the real palette and screenshots; no-capture invents visuals, so it needs your brand colors named |
+| **Palette source** | "use the site's own palette" | The workflow remixes the captured brand tokens onto its frame preset — you get the product's real colors, not a generic theme |
+| **Structure** | "hook stating the problem, N feature beats with captions, end card with CTA" | The workflow leads value-before-evidence; naming the beats keeps the hook and CTA from getting dropped |
+| **Voice & tone** | "female TTS voice, confident" / "calm male voice" | Voice gender and tone are prompt words; the provider itself is a workflow decision — see the [skill](/prompting/overview) for provider mechanics |
+| **BGM level** | "subtle electronic BGM under -18dB" (or "no BGM") | A stated ceiling keeps music under the voice; leave it off entirely for a teaser |
+| **Length & destination** | "~45 seconds", "9:16 for TikTok" | Sweet spot is 30-90s; destination sets the aspect (16:9 embed · 1:1 feed · 9:16 Shorts) |
+
+<Tip>
+  Duration and destination are the two cheapest, highest-leverage things to state. Everything else the workflow will choose well if you stay quiet — see [the specification dial](/prompting/specification-dial) for how much to delegate.
+</Tip>
+
+## Common failure modes
+
+**Hard-timing a verbatim script.** With supplied narration, the real TTS duration sets the length — a hard number forces the agent to cut or pad your words.
+- ❌ `a 45-second launch video from this exact script: ...`
+- ✅ `a ~45-second launch video from this script: ...`
+
+**Overriding the designed structure.** The workflow builds hook → value → evidence → CTA for a reason; drop the hook and the promo never answers "why should I care?"
+- ❌ `skip the intro, just list all six features back to back`
+- ✅ `hook stating the problem, then 3 feature beats, then the CTA end card`
+
+**Fighting the art-directed preset.** Each workflow adopts a frame preset and injects transitions; forcing a foreign theme yields a compromise, not your look (see [rules and anti-patterns](/prompting/rules-and-anti-patterns)).
+- ❌ `/product-launch-video ... plain white, no transitions between scenes`
+- ✅ pick the angle and tone, and let the preset carry the visual system
+
+**Assuming the agent knows your assets.** On the no-capture path there's no site to read; an unnamed logo or color is invented.
+- ❌ `use our brand colors`
+- ✅ `brand colors #5E6AD2 on off-black; logo at assets/logo.svg`
diff --git a/docs/prompting/recreating-references.mdx b/docs/prompting/recreating-references.mdx
new file mode 100644
index 0000000000..d557876095
--- /dev/null
+++ b/docs/prompting/recreating-references.mdx
@@ -0,0 +1,34 @@
+---
+title: Recreating something you saw
+description: "Transcribe motion, iterate with absolute targets, distill the constants — and know where the text-only ceiling is."
+---
+
+In practice, matching a specific reference from text alone reaches roughly 90% — but only with a specific workflow, and knowing where the ceiling is.
+
+**Transcribe motion, not just composition.** Watch the reference frame by frame and write down: the exact duration, the camera's path, what each element does with timestamps, how entrances overlap, which layers are blurred, sampled colors. A prompt built this way one-shots ~75% of the target — structure and motion arc land, rendering calibration doesn't.
+
+**Iterate with absolute targets.** Compare your render against the reference frame by frame, then correct one axis at a time while freezing everything that already matches. State corrections as absolute values, not relative nudges — "dot radius = 25% of row spacing", not "make dots 2x finer". Relative corrections pendulum: too big, then too small, then too big. Expect a handful of rounds to converge.
+
+**Distill the converged values back into the prompt.** Iteration is a search; the found constants are reusable. A prompt carrying them one-shots ~80–90% of the converged quality on a fresh build — the discrete facts (timings, counts, hexes, ratios, camera arcs) transfer losslessly, while continuous qualities (glow prominence, framing feel) still vary by a calibration note or two. And the converged composition file itself is the pixel-exact artifact: renders are deterministic, so re-rendering it reproduces the result bit-for-bit.
+
+A distilled spec that one-shots a broadcast-style animated globe:
+
+<Accordion title="Worked example: the hologram globe (full distilled spec)">
+  > 1.8-second 1920x1080 video, Three.js via the adapter (seek-driven, no rAF). One continuous shot; every element is still moving on the final frame.
+  >
+  > FIELD: blue-violet background, linear #2a24a8 → #12105e top-to-bottom with a soft radial lift at center; faint blurred vertical cyan light-streaks (#5ee0e8 at ~10% opacity, ~340px spacing) drifting 70px left across the piece; deep corner vignette; soft-light film grain at ~6% (seeded noise).
+  >
+  > GLOBE: royal-blue sphere (#4348f2), lit from upper-left with a 0.58 ambient floor; a broad subtle satin band (#6470ff, very wide falloff, ~30% mix) sweeping the upper curve; a strong cyan rim-light line (#5ee8f0) tracing only the top edge. Continents in TWO layers: (a) a heavily-blurred darker-blue silhouette (#3439c2, 80% opacity) just under the surface, reading as a soft shadow shape; (b) a dot-matrix just above the surface on an equal-area grid (0.9° latitude rows, longitude step widening with latitude): dot radius = 24–28% of row spacing — clear blue gaps between dots — growing slightly toward the equator, 85% dot opacity; two color populations — cyan-aqua #5ee0e8 north, spring-green #7ce97a from latitude ~32° southward — with seeded ±30% per-dot brightness variance; dots dimmed to 40% in the view-space lower-right shadow zone. Continents read as distinct dotted landmasses covering ~30–35% of the visible hemisphere, with royal-blue ocean dominating the rest.
+  >
+  > CAMERA: open EXTREMELY close — the sphere's curve fills the entire frame, horizon exiting the upper corners — then one continuous pull-back + crane (fov 52°→40°) ending with the dome filling the lower half edge-to-edge, its silhouette touching both frame edges, horizon at ~45%. Ease power1.inOut computed over a 2.0s window while rendering 1.8s so the move never settles on-screen. The globe rotates 28° about its vertical axis, linear, continents drifting right-to-left, never stopping.
+  >
+  > ORBS — 12 across three depth planes, world-anchored on the upper hemisphere so stems stay vertical, popping at staggered starts 0.45s→1.15s (0.06–0.13s apart), each rising 0.44–0.56s with back.out overshoot (vary 1.7–2.6 per orb), then bobbing ±8px on phase-offset sines forever. 5 midground (~90–110px at end framing): soft mint body #a7ecc4 with a darker-green under-shade #3f9b5e at lower-left and a pale rim #d6ffe8 top-right, no white core; each wrapped in a soft additive bloom sprite ~3.5x its diameter whose texture is HOLLOW-centered peaking ~35% just outside the orb edge (a bright-cored additive glow over the opaque orb blows the mint to lime); plus a thin soft halo ring ~4.2x radius at 60% opacity, always subtler than the orb itself, with a slow 5% scale pulse. 4 background (~30px, sharp, tighter bloom). 3 foreground near-lens bokeh (~160–190px, dense mint radial-gradient sprites riding the camera at center-left / lower-center / upper-right, ~70% opacity, drifting ±30px laterally, no stems). Stems: 2–3px additive cyan cylinders fading to transparent at the surface. Tag canvas-generated sprite textures sRGB or the mints wash out pale.
+  >
+  > CAPTION: "Across 82 Countries" — Inter 300, 34px, 0.06em tracking, white at 90%, top-center 12% from the top; left-to-right per-letter fade starting t=1.0s completing ~1.45s, then a slow 6px upward drift still easing at the final frame.
+  >
+  > No audio.
+    <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/recreate-globe-oneshot.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+    *The one-shot render produced by this exact spec on a fresh build — no iteration.*
+  </Accordion>
+
+The honest ceiling: words carry discrete, countable things losslessly and underdetermine continuous perceptual qualities — bloom falloff, material feel, optical color mixing. That last 10% doesn't close from text; it oscillates. If pixel-exact matters, keep the composition file.
diff --git a/docs/prompting/rendering-and-output.mdx b/docs/prompting/rendering-and-output.mdx
new file mode 100644
index 0000000000..93b91b6d28
--- /dev/null
+++ b/docs/prompting/rendering-and-output.mdx
@@ -0,0 +1,115 @@
+---
+title: Rendering and output
+description: "What to say to get the right file out — quality tier, format, resolution, framerate, and cloud rendering — without over-speccing a render that slows to no benefit."
+---
+
+Everything before this point shapes the composition. This page is about the *export*: the words that pick a quality tier, a container format, a resolution, and where the render runs. The defaults — MP4, 1920×1080, 30fps, `standard` quality — are deliberately good, so most of the skill here is knowing when *not* to ask for more. The mechanics live in the [Rendering guide](/guides/rendering); this page owns what to say.
+
+## Quality tier
+
+Say the tier by name and the agent selects the matching encode preset — you don't specify CRF or encoder speed:
+
+| Say this | Tier | Best for |
+| --- | --- | --- |
+| "draft" / "quick render" | `draft` | Fast iteration while you're still judging the cut |
+| nothing, or "review render" | `standard` (default) | General use — visually lossless at 1080p |
+| "final" / "high quality" | `high` | Delivery masters |
+
+The tiers trade encode time for fidelity. `standard` (the default) is already visually lossless at 1080p — most people can't tell it from source — so reserve `high` for the master you'll actually hand off, and use `draft` freely while iterating.
+
+- ❌ `render everything at high quality`
+- ✅ `draft renders while we iterate, then one high-quality final` — you spend the slow encode once, on the cut you've already approved
+
+## Format
+
+MP4 is the default and the right answer for almost everything — it plays everywhere. Ask for a different container only when the delivery target needs one:
+
+> Render this as a transparent WebM overlay.
+
+> Export a MOV I can drop into Premiere with the background knocked out.
+
+Transparency has a container hierarchy, and the tradeoffs are real:
+
+| Ask for | You get | Watch out for |
+| --- | --- | --- |
+| "transparent MOV" | ProRes 4444 with alpha | The editor-grade choice (Premiere, Final Cut, Resolve, After Effects). Files are large — expected for an editing intermediate. |
+| "transparent WebM" | VP9 with alpha | Small, but **only browsers decode the alpha** — every video editor renders the transparent areas black. Browser playback only. |
+| "PNG sequence" | Lossless RGBA frames | For compositing in After Effects / Nuke / Fusion. Largest of all. |
+
+Transparency also only *means something* on a design that has empty space to see through. A lower third, a subscribe card, or a logo sting is mostly empty canvas — transparency lets it composite over other footage. A full-frame scene (edge-to-edge background, full-bleed video, a title card with its own backdrop) has nothing to be transparent; the request produces a file that looks identical to the opaque one but is larger and plays in fewer places.
+
+- ❌ `render my full-screen product promo as a transparent WebM`
+- ✅ `render the promo as MP4; export just the lower-third overlay as transparent WebM` — transparency belongs to the layer meant to sit *over* other footage, not the finished full-frame film
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/overlay-spotify-preview.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*A transparent VP9 WebM overlay previewed over a checkerboard. To verify alpha from the CLI: VP9 stores it out-of-band, so look for ALPHA_MODE=1 in ffprobe (a pix_fmt-only check false-negatives) or extract it with ffmpeg alphaextract.*
+
+
+<Note>
+  A transparent render also depends on the composition leaving `html` / `body` backgrounds unset — the transparency comes through only where nothing is painted. The workflow skills handle this; see the [Rendering guide](/guides/rendering#transparent-video) if you're hand-authoring an overlay.
+</Note>
+
+## Resolution and framerate
+
+1920×1080 at 30fps is the default. Both cost real time when you raise them, and both are frequently asked for out of habit rather than need.
+
+**4K** is a render-time flag — the composition stays at its authored size and Chrome supersamples it to 3840×2160. That buys crisp text, SVG, and CSS at any scale, but it does *nothing* for content already locked to a pixel grid: a 1080p `<video>`, a fixed-size `<canvas>`, or a sub-4K image gain no detail from it. And it isn't free — a 4K render is roughly **4× slower per frame** and produces a **3–5× larger file**. Ask for it when the delivery surface genuinely needs it (a 4K display, a client spec), not reflexively.
+
+> Render this at 4K for the trade-show display.
+
+**Framerate** follows the same logic: 60fps doubles the frames the engine captures and encodes. It's worth it for fast motion graphics destined for a high-refresh screen; it's wasted on a talking-head clip or a slow title sequence.
+
+- ❌ `render in 4K 60fps` for a clip headed to Instagram — the platform will transcode it down anyway, and you paid the slow render for nothing
+- ✅ say nothing for social; name `4K` (or `60fps`) only when the target actually resolves it
+
+<Warning>
+  A few 4K constraints will stop a render before it starts (all grounded in the [4K guide](/guides/4k-rendering#constraints)): the target orientation must match the composition's aspect ratio, the scale must be a whole number (1080p → 4K is exactly 2×), and **4K cannot be combined with HDR** in one pass. If you need both, render HDR at composition resolution and upscale separately.
+</Warning>
+
+## HDR
+
+HDR output is **HDR10 MP4** (H.265 10-bit, BT.2020) and it is *source-driven* — the render only goes HDR when your composition actually references HDR media (video tagged BT.2020 with PQ or HLG transfer, or a 16-bit PNG). Text, gradients, and GSAP animation are not HDR sources; a composition made entirely of them has nothing to render in HDR.
+
+> This composition has an HDR drone clip — render it as HDR10.
+
+By default HDR is auto-detected, so with a real HDR source in the project you often need to say nothing. Force it explicitly only to override the probe:
+
+- "force HDR" → forces the HDR path even without a detected HDR source
+- "force SDR" → forces standard range even when HDR sources are present
+
+HDR is **MP4 only** (a transparent MOV/WebM request falls back to SDR) and it is **not available on Lambda** (distributed rendering is SDR-only). See the [HDR guide](/guides/hdr) for source requirements and verification.
+
+## Where the render runs
+
+Local rendering is the default and the right choice for the whole iteration loop. Reach for cloud rendering only when a single machine is the bottleneck:
+
+> Render this on Lambda.
+
+That routes to HyperFrames' AWS Lambda path, which fans the render across many parallel workers. It's the right call for renders that are **too long or too large for one host** — multi-minute videos, 4K masters, or large parallel batches — and it needs AWS credentials configured first. For dev-loop iteration, stay on local `render`; the round-trip is faster than any cloud dispatch. Lambda is SDR-only (no HDR) and bills by compute time; the [AWS Lambda guide](/deploy/aws-lambda) covers setup, cost shape, and the conservative concurrency default.
+
+- ❌ `set up Lambda so I can preview edits faster` — cloud dispatch adds latency to a fast local loop
+- ✅ `render the final 3-minute 4K cut on Lambda` — the workload that actually justifies fanning out
+
+## Preview before you commit the slow render
+
+The cheapest way to avoid a wasted `high`/4K/HDR render is to judge the frame first. The habit the workflow skills follow:
+
+1. Keep `preview` running and scrub the timeline — same runtime as the render, so what you see is what you get.
+2. Iterate with `draft` renders when you need a real file to check.
+3. Only when the cut is locked, ask for the final tier / resolution / format.
+
+- ❌ `render the final 4K HDR master` on a cut you haven't watched end to end
+- ✅ `draft render so I can check timing` → approve → `now the 4K final`
+
+<Tip>
+  Rendering is user-gated by design — the agent pauses at preview and renders only when you approve. Use that pause to lock the cut before you pay for the expensive export.
+</Tip>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Iterating" href="/prompting/iterating">Small targeted edits between renders, not re-specification</Card>
+  <Card title="Rules and anti-patterns" href="/prompting/rules-and-anti-patterns">Why over-speccing resolution and framerate backfires</Card>
+  <Card title="Rendering guide" href="/guides/rendering">Formats, quality presets, workers — the mechanics</Card>
+  <Card title="AWS Lambda" href="/deploy/aws-lambda">Cloud rendering setup and cost</Card>
+</CardGroup>
diff --git a/docs/prompting/rules-and-anti-patterns.mdx b/docs/prompting/rules-and-anti-patterns.mdx
new file mode 100644
index 0000000000..d68d802e77
--- /dev/null
+++ b/docs/prompting/rules-and-anti-patterns.mdx
@@ -0,0 +1,54 @@
+---
+title: Rules and anti-patterns
+description: "The technical rules that keep renders correct, and the prompt patterns that cause friction."
+---
+
+## Rules to know
+
+The skills enforce these automatically, but if you hand-edit compositions or debug issues, these are the rules that matter:
+
+1. **Register all timelines** on `window.__timelines` — the renderer can't seek animations it doesn't know about.
+2. **Video elements must be `muted`** — audio goes in separate `<audio>` elements so the renderer can mix it.
+3. **No `Math.random()`** — random values produce different frames on each render, breaking determinism. Use a seeded PRNG (e.g. mulberry32) if you need pseudo-random values.
+4. **Synchronous timeline construction** — no `async`/`await` or `fetch()` during GSAP timeline setup.
+5. **Timed elements need `class="clip"`** — plus `data-start`, `data-duration`, and `data-track-index`.
+6. **Add entrance animations to every scene** — elements appearing without animation feel broken on video.
+7. **Add transitions between scenes** — jump cuts between scenes are almost always unintentional in composed video.
+
+<Warning>
+  Rules 1–5 are technical requirements — breaking them produces incorrect renders. Rules 6–7 are best practices that the skills apply by default. You can override them when you have a reason to.
+</Warning>
+
+
+
+## Anti-patterns
+
+Each one causes friction or wrong output for a specific engine reason — with the fix.
+
+**Don't ask for React / Vue components.** Compositions are plain HTML with `data-*` attributes and a GSAP timeline; framework components force a translation step.
+- ❌ `build a React component for the intro`
+- ✅ `build the intro scene` (the agent writes composition HTML directly)
+
+**Don't over-spec resolution or framerate.** Defaults (1920×1080, 30fps) render fast and look great; higher specs slow rendering meaningfully.
+- ❌ `render in 4K 60fps` (for a social clip)
+- ✅ say nothing — or `4K` only when the delivery target actually needs it
+
+**Don't skip the slash command.** Without `/hyperframes`, the agent guesses at HTML video conventions instead of loading the framework's actual rules.
+- ❌ `make me a video of...`
+- ✅ `/hyperframes make me a video of...`
+
+**Don't paste raw error logs.** Lint and validate localize the problem first; a bare log makes the agent re-derive what the tools already know.
+- ❌ pasting 200 lines of console output
+- ✅ `lint passes but validate reports a missing asset in scene 2 — fix it`
+
+**Don't assume the agent knows your assets.** It will look, but a path skips the search.
+- ❌ `use my logo`
+- ✅ `use assets/logo.svg`
+
+**Don't override a workflow's designed style.** Each workflow skill carries an art-directed preset; fighting it produces a compromise, not your theme.
+- ❌ `/pr-to-video ... dark theme`
+- ✅ let the preset carry the look, or use a freeform build when you need full style control
+
+**Don't hard-time a verbatim script.** With supplied narration text, duration follows the spoken words.
+- ❌ `a 60-second explainer from this script: ...`
+- ✅ `a ~60-second explainer from this script: ...`
diff --git a/docs/prompting/runtimes-and-3d.mdx b/docs/prompting/runtimes-and-3d.mdx
new file mode 100644
index 0000000000..deb67a9512
--- /dev/null
+++ b/docs/prompting/runtimes-and-3d.mdx
@@ -0,0 +1,83 @@
+---
+title: Runtimes and 3D
+description: "GSAP is the default and you rarely name it — but real 3D, existing animation files, and scene transitions each have a runtime worth pinning in the prompt."
+---
+
+HyperFrames animates through the [frame-adapter](/concepts/frame-adapters) pattern: any runtime that can answer "what should the screen look like at frame N?" plugs in and renders deterministically. [GSAP](/guides/gsap-animation) is the default adapter and covers most motion — you rarely need to name it. The cases below are the ones where the default choice can go wrong, so the prompt should pick the runtime for you.
+
+## Real 3D → Three.js via the adapter
+
+This is the one pin to state every time. For anything with genuine **depth, lighting, or a camera** — a rotating product, a scene you move through, surfaces that catch light — ask for Three.js explicitly:
+
+> Build the scene in **Three.js via the adapter**: a product model on a turntable, one key light and a soft fill, slow rotation.
+
+- ❌ `isometric cards floating in CSS 3D with perspective`
+- ✅ `build the isometric scene in Three.js via the adapter, with real depth and lighting`
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/example-3d-cards.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*The Three.js version of the isometric-cards prompt — real shadows and lighting, one-shot.*
+
+
+The engine rationale: CSS `perspective` transforms skew flat planes — they read flat the moment lighting or parallax matters, because there is no light source and no camera, only projected rectangles. Three.js is a first-party seek-safe runtime (`hf-seek` events plus `window.__hfThreeTime`), so a real 3D scene renders frame-accurately like everything else. This is a validated default, not a preference — treat "real 3D" as "Three.js" unless you specifically want a flat, stylized fake-3D look.
+
+Camera moves are part of the same rule. A "drone orbit", dolly, or push-in only exists where there's an actual camera:
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-orbit.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*A seek-driven Three.js drone orbit — the camera sweeps a continuous arc; impossible with CSS transforms.*
+
+
+- ❌ `a drone-orbit camera move around the logo` (with no runtime named — CSS has no camera to orbit)
+- ✅ `orbit the camera around the logo — Three.js via the adapter`
+
+## Existing animation files → Lottie
+
+If you already have a designed animation — an After Effects export, a `.json` or `.lottie` file, an icon animation from a designer — don't ask the agent to redraw it. Point at the file and ask for Lottie:
+
+> Play this Lottie file (`assets/loader.lottie`) centered, then fade to the title.
+
+The Lottie adapter seeks the existing animation frame-by-frame, so the designer's work renders exactly as authored. Asking the agent to recreate it in GSAP throws away the source and lands somewhere approximate.
+
+## Simple UI and text motion → the default
+
+Fades, slides, staggers, counters, kinetic type, hover-style reveals — the everyday motion — is what GSAP does natively, and it's already the default. You don't name a runtime here; you describe the motion (see [Premium motion](/prompting/motion)):
+
+> The headline slides up per word, staggered 0.1s apart, easing out as it lands.
+
+CSS keyframes and the Web Animations API are also supported adapters, worth naming only when you're bringing existing CSS `@keyframes` or WAAPI code you want kept as-is. For a fresh ask, let the default handle it.
+
+## Scene-to-scene → shader transitions
+
+Motion *within* a scene is one thing; the handoff *between* scenes is another. For a designed transition — a wipe, a glitch, a liquid dissolve — ask for a shader transition at that specific moment:
+
+> Hard-cut between the first three scenes; use a **shader transition** (glitch) into the final logo scene.
+
+Name the moments — shader transitions are for the two or three beats that deserve them, not every cut. See [Transitions](/prompting/transitions) for the vocabulary.
+
+## Determinism surfaces in the prompt
+
+Every runtime renders under the same [determinism](/concepts/determinism) contract: the frame clock is `t = frame / fps`, and there is **no wall clock, no live network at render time, and no unseeded randomness**. Two asks bump into this, so phrase them accordingly:
+
+- ❌ `fetch the current BTC price and count up to it` — a render-time fetch isn't allowed; the render must be reproducible
+- ✅ `count up to $67,400` (a fixed value baked in), or `read the target from a variable I pass at render time`
+
+- ❌ `scatter 200 particles randomly` — unseeded randomness renders differently each frame and breaks reproducibility
+- ✅ `scatter 200 particles from a seeded random layout` — say **seeded** and the positions are stable across frames and re-renders
+
+The rule of thumb: anything the video needs to *know* must be present before rendering starts — baked in, or passed as a [variable](/prompting/variables-and-templating). Anything random must be seeded.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Frame adapters (concept)" icon="plug" href="/concepts/frame-adapters">
+    The seek-by-frame contract and the full list of supported runtimes.
+  </Card>
+  <Card title="Deterministic rendering" icon="lock" href="/concepts/determinism">
+    Why no live data and no unseeded randomness — the reproducibility guarantee.
+  </Card>
+  <Card title="Premium motion" icon="wand-magic-sparkles" href="/prompting/motion">
+    Describing everyday GSAP motion so it doesn't read as cheap.
+  </Card>
+  <Card title="Transitions" icon="film" href="/prompting/transitions">
+    Naming the scene-to-scene handoffs worth a shader transition.
+  </Card>
+</CardGroup>
diff --git a/docs/prompting/specification-dial.mdx b/docs/prompting/specification-dial.mdx
new file mode 100644
index 0000000000..b384eefcac
--- /dev/null
+++ b/docs/prompting/specification-dial.mdx
@@ -0,0 +1,17 @@
+---
+title: The specification dial
+description: "Spec density controls how far the result drifts from what you imagined — not whether it works."
+---
+
+How much you specify sets how much you delegate — it controls how far the result can drift from what you imagined, not whether it works. Mood-level prompts ("snappy", "cinematic") get a designer's interpretation: coherent, but the agent picks the colors, staging, and details. Dense specs — hexes, timestamps, easings, pinned techniques — get *your* frame.
+
+Three settings:
+
+1. **Mood words** — "a warm, minimal logo sting". Fastest to write; the agent owns the look.
+2. **Style tokens** — exact hexes, named textures ("halftone-dot", "paper-cut matte", "8-bit pixel"), type direction ("condensed caps", "thin geometric sans, wide tracking"). Cheap precision, no downside.
+3. **Full visual spec** — every element gets shape + color + position + timing (see [visual specs](/prompting/visual-specs)). Use when you're recreating a specific look.
+
+Density never hurts — a stronger model just uses less of its own taste. It matters most for technique choices a smaller model won't default well. Two worth pinning every time:
+
+- **3D**: any real depth, lighting, or camera motion → say **"Three.js via the adapter"**. CSS perspective transforms read flat on lighting-critical scenes, and Three.js is a supported seek-safe runtime.
+- **Sequencing**: resolve simultaneity in the text. "The counter fades out and READY stamps in at 4s" produces an overlap; "fades out fully by 4.2s; at 4.2s READY stamps in" doesn't.
diff --git a/docs/prompting/transitions.mdx b/docs/prompting/transitions.mdx
new file mode 100644
index 0000000000..d7cd49449d
--- /dev/null
+++ b/docs/prompting/transitions.mdx
@@ -0,0 +1,89 @@
+---
+title: Transitions
+description: "Map energy and mood to named shader and CSS transition blocks, and prompt them per seam."
+---
+
+## What transitions do and when they trigger
+
+A transition tells the viewer how two scenes relate — a crossfade says "this continues," a whip pan says "next point," a burn says "something changed." Any composition with more than one scene needs them: without a transition, a scene change reads as an unintentional jump cut (see [rules and anti-patterns](/prompting/rules-and-anti-patterns)). The skills add transitions by default, so prompts trigger this layer whenever you describe scene changes, crossfades, wipes, reveals, or a mood ("warm," "clinical," "glitchy") — or when you name a block directly.
+
+Two families, both first-class:
+
+- **[Shader transitions](/catalog/blocks/cross-warp-morph)** composite both scenes per-pixel on a WebGL canvas — they warp, dissolve, and morph in ways CSS cannot. Reach for these when the *handoff itself* is a moment (a hero reveal, a topic pivot with weight).
+- **CSS transitions** animate the scene containers with opacity, transforms, clip-path, and filters. Simpler and lighter; reach for these for the 60–70% of ordinary scene changes where the content is just continuing.
+
+Choose by the effect you want, not by which is easier. See also the transitions table in [vocabulary](/prompting/vocabulary).
+
+<Note>
+  The catalog pages linked here are standalone demos of each effect. In a real multi-scene build the agent wires the same effects through the `@hyperframes/shader-transitions` package (`HyperShader.init`) — you never need to say that; naming the transition is enough.
+</Note>
+
+## Energy → transition
+
+Pick **one primary** transition for most scene changes, plus one or two accents for topic changes and the climax. Never use a different transition on every seam — that reads as chaos, not design.
+
+| Energy | Shader primary | CSS primary | Feels like |
+| ------ | -------------- | ----------- | ---------- |
+| **Calm** (wellness, brand story, luxury) | [`cross-warp-morph`](/catalog/blocks/cross-warp-morph), [`thermal-distortion`](/catalog/blocks/thermal-distortion) | [`transitions-blur`](/catalog/blocks/transitions-blur), [`transitions-dissolve`](/catalog/blocks/transitions-dissolve) | Soft, slow, drifting |
+| **Medium** (corporate, SaaS, explainer) | [`whip-pan`](/catalog/blocks/whip-pan), [`cinematic-zoom`](/catalog/blocks/cinematic-zoom) | [`transitions-push`](/catalog/blocks/transitions-push), [`transitions-cover`](/catalog/blocks/transitions-cover) | Clean, directional, decisive |
+| **High** (promos, sports, music, launch) | [`ridged-burn`](/catalog/blocks/ridged-burn), [`glitch`](/catalog/blocks/glitch), [`chromatic-radial-split`](/catalog/blocks/chromatic-radial-split) | [`transitions-scale`](/catalog/blocks/transitions-scale), [`transitions-destruction`](/catalog/blocks/transitions-destruction), [`transitions-light`](/catalog/blocks/transitions-light) | Fast, punchy, aggressive |
+
+## Mood → transition
+
+Energy sets tempo; mood sets meaning. Describe the brand feeling and the agent picks a matching block.
+
+| Mood | Shader | CSS |
+| ---- | ------ | --- |
+| **Warm / inviting** | [`light-leak`](/catalog/blocks/light-leak), [`thermal-distortion`](/catalog/blocks/thermal-distortion), [`cross-warp-morph`](/catalog/blocks/cross-warp-morph) | [`transitions-light`](/catalog/blocks/transitions-light), [`transitions-blur`](/catalog/blocks/transitions-blur) |
+| **Cold / clinical** | [`gravitational-lens`](/catalog/blocks/gravitational-lens) | [`transitions-mechanical`](/catalog/blocks/transitions-mechanical), [`transitions-grid`](/catalog/blocks/transitions-grid) |
+| **Editorial / magazine** | [`whip-pan`](/catalog/blocks/whip-pan) | [`transitions-push`](/catalog/blocks/transitions-push) |
+| **Tech / futuristic** | [`glitch`](/catalog/blocks/glitch), [`chromatic-radial-split`](/catalog/blocks/chromatic-radial-split) | [`transitions-grid`](/catalog/blocks/transitions-grid) |
+| **Tense / edgy** | [`ridged-burn`](/catalog/blocks/ridged-burn), [`glitch`](/catalog/blocks/glitch), [`domain-warp-dissolve`](/catalog/blocks/domain-warp-dissolve) | [`transitions-distortion`](/catalog/blocks/transitions-distortion) |
+| **Playful / fun** | [`ripple-waves`](/catalog/blocks/ripple-waves), [`swirl-vortex`](/catalog/blocks/swirl-vortex) | [`transitions-3d`](/catalog/blocks/transitions-3d), [`transitions-radial`](/catalog/blocks/transitions-radial) |
+| **Dramatic / cinematic** | [`cinematic-zoom`](/catalog/blocks/cinematic-zoom), [`gravitational-lens`](/catalog/blocks/gravitational-lens), [`domain-warp-dissolve`](/catalog/blocks/domain-warp-dissolve) | [`transitions-scale`](/catalog/blocks/transitions-scale) |
+| **Premium / luxury** | [`cross-warp-morph`](/catalog/blocks/cross-warp-morph), [`thermal-distortion`](/catalog/blocks/thermal-distortion) | [`transitions-blur`](/catalog/blocks/transitions-blur), [`transitions-dissolve`](/catalog/blocks/transitions-dissolve) |
+| **Retro / analog** | [`light-leak`](/catalog/blocks/light-leak) | [`transitions-light`](/catalog/blocks/transitions-light) |
+
+Special-purpose seams: [`flash-through-white`](/catalog/blocks/flash-through-white) for a bright cut on an impact beat, [`sdf-iris`](/catalog/blocks/sdf-iris) for a clean iris reveal into a hero shot.
+
+## Example prompts
+
+Name the block and the seam — transitions are the one place where per-seam control usually beats letting the agent decide.
+
+> /general-video Six-scene SaaS explainer. Use [`whip-pan`](/catalog/blocks/whip-pan) as the primary transition between related points, and one [`cinematic-zoom`](/catalog/blocks/cinematic-zoom) into the final pricing reveal. Medium energy, ~0.4s each.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-transitions.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above, unedited — whip-pan on four seams, cinematic-zoom into the pricing reveal.*
+
+
+> Between beats 2 and 3, transition with [`swirl-vortex`](/catalog/blocks/swirl-vortex); keep every other seam on a plain blur crossfade.
+
+> Warm transitions for this wellness brand — [`light-leak`](/catalog/blocks/light-leak) between scenes, nothing sharp or mechanical. Slow, 0.6–0.8s.
+
+> Music promo, high energy. [`glitch`](/catalog/blocks/glitch) on the phrase changes, [`ridged-burn`](/catalog/blocks/ridged-burn) on the drop. Fast cuts, 0.15–0.25s.
+
+## Knobs
+
+- **Duration** follows energy: calm 0.5–0.8s, medium 0.3–0.5s, high 0.15–0.3s. Say a number to pin it.
+- **Primary + accents.** One primary carries most seams; spend your boldest accent on the climax. State the split ("`whip-pan` throughout, one `ridged-burn` on the reveal").
+- **Per-seam placement.** "on phrase changes," "between beats 2 and 3," "into the final scene" all bind a transition to a specific cut.
+- **Blur intensity** (CSS blur crossfades): heavier (20–30px) for calm, light (3–6px) for high energy.
+- **Easing presets:** `snappy`, `smooth`, `gentle`, `dramatic`, `instant`, `luxe` map to tuned duration/ease pairs.
+
+## Failure modes
+
+**Don't fade the outgoing scene out, then fade the next one in.** The renderer holds each scene's final state, so an explicit fade-out followed by an entrance renders as a jump cut with a dip in the middle — not a transition. The transition *is* the exit; both scenes hand off at the same instant.
+- ❌ `fade scene 1 out, then fade scene 2 in`
+- ✅ `cross-warp-morph from scene 1 to scene 2`
+
+**Don't ask for a different transition on every seam.** A new effect at each cut reads as noise; consistency is what makes the one bold accent land.
+- ❌ `use a different transition between each scene`
+- ✅ `whip-pan as the primary, one glitch on the hero reveal`
+
+**Don't leave "add transitions" unqualified when tone matters.** Bare requests get a sensible default; if the brand feeling is load-bearing, name the energy or mood (see [the specification dial](/prompting/specification-dial)).
+- ❌ `add some transitions`
+- ✅ `medium-energy editorial transitions — whip-pan primary`
+
+**Don't invent transition names.** Only the blocks in the [shader](/catalog/blocks/cross-warp-morph) and CSS transition groups exist; a made-up name (`page-curl`, `star-iris`) sends the agent guessing at raw GLSL or an unsupported CSS effect.
+- ❌ `add a page-curl transition`
+- ✅ pick a real block, e.g. `sdf-iris` for an iris reveal
diff --git a/docs/prompting/variables-and-templating.mdx b/docs/prompting/variables-and-templating.mdx
new file mode 100644
index 0000000000..71e499867f
--- /dev/null
+++ b/docs/prompting/variables-and-templating.mdx
@@ -0,0 +1,83 @@
+---
+title: Variables and templating
+description: "Ask for the parts that should change to become named slots, then re-render the same composition with different values — one output per record."
+---
+
+Most videos have a few things that vary and a lot that doesn't. When you know a composition will be reused — a card per customer, a stat per quarter, a name per recipient — say so in the prompt, and name the parts that change. The agent turns them into declared [variables](/concepts/variables): typed, labeled slots filled at render time instead of hardcoded into the HTML.
+
+The trigger phrase is simple — call out the slots:
+
+> Build a 6-second title card. Make the **name**, the **logo**, and the **accent color** variables; everything else stays fixed.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-variables-default.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Default variable values.*
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-variables-variant.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*The same composition re-rendered with `--variables` overrides — different name, logo, and accent, zero re-prompting.*
+
+
+
+The agent declares `data-composition-variables` on the composition root with the right type for each slot — `string` for the name, `color` for the accent, and a `string` URL for the logo (the escape hatch for any media asset — image, video, audio, or logo). A plain `<img>` logo needs no timing attributes; only `<video>`/`<audio>` variables involve the media wiring described in [variables](/concepts/variables). One composition, many fills.
+
+## Say what type each slot is
+
+The five variable types (`string`, `number`, `color`, `boolean`, `enum`) each render a different input in [Studio](/packages/studio) and validate differently at render time. You don't write the JSON — but naming the type in the prompt removes a guess:
+
+> Variables: `plan` (enum: Free / Pro / Enterprise), `price` (number, shown as `$`), `featured` (boolean — toggles the ribbon), `headline` (text).
+
+- ❌ `make the plan and price editable`
+- ✅ `plan is an enum (Free / Pro / Enterprise); price is a number in dollars`
+
+The engine rationale: an `enum` with declared options gets validated against that list at render time (`enum-out-of-range` is caught), and a `number` with a `unit` renders `$` formatting the odometer needs. A vague "editable" leaves the agent to pick a type, and a mistyped value only surfaces later.
+
+## Template, then render one per record
+
+Once the varying parts are variables, the same source renders once per data row. This is a real batch mode, not a copy-paste-per-video loop — the composition is authored once and fed a list of value sets:
+
+> Build this as a template with `name` and `title` variables, then render one video per row of my data — output to `renders/{name}.mp4`.
+
+The agent authors the composition, then runs a [batch render](/concepts/variables#batch-renders): a JSON array where each row is one set of variable values, one output file per row, with `{key}` placeholders in the output path drawn from each row. If your source is a CSV, say so — the agent converts it to the row array the batch expects. Add "fail on any undeclared or mistyped value" and it renders with `--strict-variables`, so a typo in a column name stops the run instead of silently rendering the default.
+
+Everything shares one composition, so a design fix propagates to every output on the next render — you're not editing a hundred near-duplicate files.
+
+## Personalization asks
+
+Personalized-at-scale videos are the same pattern with the value set coming from your data:
+
+> A 10-second welcome clip that greets each new signup by first name and shows their company logo. I'll supply a list of `{ firstName, logoUrl }` records.
+
+The `firstName` is a `string`; the `logoUrl` is a `string` variable your composition assigns to an `<img src>`. Pass assets as **URL references, not inlined data** — URL-shaped values travel cleanly through both the local renderer and distributed [Lambda renders](/deploy/templates-on-lambda). If you're wiring this behind your own product UI or an agent rather than the CLI, the [`@hyperframes/sdk`](/packages/sdk) opens a base template and layers a sparse override set per instance, so the host stores only each record's delta.
+
+## Declare up front — don't bake values in
+
+The most common miss is describing the finished video with the values already fixed, then asking to "make it reusable" afterward:
+
+- ❌ `Make a card that says "Acme — Pro plan — $49". Later I'll want other companies too.`
+- ✅ `Make a plan card. Variables: company (text), plan (enum), price (number, $). Show "Acme / Pro / 49" as the default.`
+
+The engine rationale: variables are runtime values a script applies to the live DOM, resolved from declared defaults, per-instance overrides, or the CLI in that precedence order. Declaring them up front means the reusable structure exists from the first render and the default is just one more value set. Baking `"Acme — Pro — $49"` into the markup produces a composition with no slots — reuse then means an edit pass over hardcoded text for every variant, which is exactly what variables exist to avoid.
+
+## What can't be a variable
+
+A few inputs are read once at compile time and no variable can move them: composition **dimensions** (`data-width` / `data-height`), the **root composition's total duration**, **frame rate**, and **output format / codec**. So this doesn't do what it reads like:
+
+- ❌ `make the video length a variable so each render can be a different duration`
+- ✅ `author one composition per target length` — or vary a *clip's* duration (that one is re-read from the live DOM)
+
+If total length must differ per output, that's a different root `data-duration` per render, not a variable. See [what can't be a variable](/concepts/variables#what-cant-be-a-variable) for the full list and the compile-time-vs-live-DOM rule behind it.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Variables (concept)" icon="sliders" href="/concepts/variables">
+    The mechanics: declaring types, per-instance overrides, batch renders, precedence.
+  </Card>
+  <Card title="@hyperframes/sdk" icon="code" href="/packages/sdk">
+    Template + sparse-override editing behind your own product UI or agent.
+  </Card>
+  <Card title="The specification dial" icon="gauge" href="/prompting/specification-dial">
+    How much to specify — and why naming the type is cheap precision.
+  </Card>
+  <Card title="Design systems and brand" icon="palette" href="/prompting/design-systems">
+    Brand tokens as variables that re-skin every reuse from one value.
+  </Card>
+</CardGroup>
diff --git a/docs/prompting/vfx-and-liquid-glass.mdx b/docs/prompting/vfx-and-liquid-glass.mdx
new file mode 100644
index 0000000000..b017d83434
--- /dev/null
+++ b/docs/prompting/vfx-and-liquid-glass.mdx
@@ -0,0 +1,101 @@
+---
+title: VFX and liquid glass
+description: "Prompt device mockups, liquid-glass UI, shatter/portal/magnetic moments, and ambient polish — and know which effects need the canvas pipeline."
+---
+
+This is the showy end of the catalog: 3D device mockups, frosted-glass Apple UI, and cinematic moments where HTML shatters or gets sucked through a portal. Two groups do the work — the [HTML-in-Canvas](/catalog/blocks/vfx-iphone-device) blocks (real WebGL, live HTML rendered as GPU textures) and the [Effects](/catalog/components/vignette) components (lightweight CSS polish). Knowing which is which is the difference between an effect that renders and one that surprises you. All of it slots into the [one-shot skeleton](/prompting/anatomy) at the "technique" step.
+
+### Device mockups
+
+To put your product UI inside a real phone or laptop, name [`vfx-iphone-device`](/catalog/blocks/vfx-iphone-device) — real GLTF iPhone 15 Pro Max and MacBook Pro models with live HTML-in-Canvas screen content, a product-review camera choreography, and a 360° turntable. For a styled iOS/macOS *environment* (home screen, desktop, dock) rather than a bare device, reach for the liquid-glass system blocks below.
+
+> /product-launch-video 15-second 1920x1080 video. Our dashboard UI lives on the screen of a real iPhone 15 Pro Max that turntables slowly under product-review lighting, then a MacBook Pro slides in beside it showing the same UI wider. Use the `vfx-iphone-device` registry block. No narration.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/validate-device-mockup.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the prompt above (the block's demo UI on screen), unedited.*
+
+
+**Ask for the device *and* what's on its screen.** The block renders live HTML into the screen but ships with its own demo UI — describing your UI (or pointing at screenshots/paths) is what makes the agent replace the block's screen content instead of shipping the demo.
+- ❌ `show my app on an iPhone` (you'll get the block's built-in demo UI)
+- ✅ `our dashboard UI (screenshots in assets/ui/) on the screen of the iPhone 15 Pro Max, turntabling`
+
+### Liquid-glass UI treatments
+
+The liquid-glass blocks are frosted-glass Apple-style UI floating over an aurora shader background. Pick by the surface you want:
+
+| You want…                                        | Name this block                                                  | Length |
+| ------------------------------------------------ | ---------------------------------------------------------------- | ------ |
+| A full iOS 26 home screen on a 3D iPhone          | [`ios26-liquid-glass`](/catalog/blocks/ios26-liquid-glass)       | 15s    |
+| A macOS Tahoe desktop on a 3D MacBook             | [`macos-tahoe-liquid-glass`](/catalog/blocks/macos-tahoe-liquid-glass) | 15s |
+| Glass notification cards                          | [`liquid-glass-notification`](/catalog/blocks/liquid-glass-notification) | 8s |
+| A glass context menu                              | [`liquid-glass-context-menu`](/catalog/blocks/liquid-glass-context-menu) | 8s |
+| Glass media / playback controls                   | [`liquid-glass-media-controls`](/catalog/blocks/liquid-glass-media-controls) | 8s |
+| Glass stat cards, panels, pill chips              | [`liquid-glass-widgets`](/catalog/blocks/liquid-glass-widgets)   | 8s     |
+
+The four `liquid-glass-*` panel blocks share the aurora-shader stage, so they compose cleanly into one scene; `ios26-liquid-glass` and `macos-tahoe-liquid-glass` are complete device environments and generally stand alone.
+
+> 8-second 1920x1080 video. Frosted glass notification cards drift in and stack over an aurora shader background, each reading a fake alert ("Build passed", "Deploy live", "0 incidents"). Use the `liquid-glass-notification` registry block. No audio.
+
+**"Liquid glass" means the block, not a filter you're describing.** These are complete WebGL stages; asking for "a glassy blur on my div" gets you a CSS `backdrop-filter`, not this look.
+- ❌ `add a liquid glass effect over my text`
+- ✅ `use the liquid-glass-widgets registry block for the stat cards`
+
+### Shatter, portal, magnetic, and cursor moments
+
+The `vfx-*` blocks are single cinematic beats — spend them on a transition or a reveal, not a whole video:
+
+| The moment                                       | Name this block                                     | Length |
+| ------------------------------------------------ | --------------------------------------------------- | ------ |
+| HTML shatters into glass fragments               | [`vfx-shatter`](/catalog/blocks/vfx-shatter)        | 12s    |
+| A dimension breach with volumetric light         | [`vfx-portal`](/catalog/blocks/vfx-portal)          | 10s    |
+| A magnetic-field particle visualization          | [`vfx-magnetic`](/catalog/blocks/vfx-magnetic)      | 15s    |
+| HTML floating over an organic liquid surface     | [`vfx-liquid-background`](/catalog/blocks/vfx-liquid-background) | 12s |
+| A dramatic text reveal with chromatic shadow rays | [`vfx-text-cursor`](/catalog/blocks/vfx-text-cursor) | 8s    |
+
+> /motion-graphics 8-second 1920x1080 video. Beat 1 (0-4s): a landing-page hero holds under directional light. Beat 2 (4-6s): the whole page shatters into glass fragments that scatter. Beat 3 (6-8s): bold white text slams in on black. Use the `vfx-shatter` registry block. No narration, no image or media files.
+
+**Name the exact effect — "explode," "break," "burst" don't map.** Each block is a specific simulation.
+- ❌ `make the UI explode`
+- ✅ `the page shatters into glass fragments` → `vfx-shatter`, or `gets pulled through a portal` → `vfx-portal`
+
+### Ambient polish
+
+The [Effects](/catalog/components/vignette) components are lightweight, pure-CSS finishing passes you layer *on top* of a finished scene — grain, vignette, a light sweep, a subtle push:
+
+| Say this                       | Component                                              |
+| ------------------------------ | ------------------------------------------------------ |
+| Film grain / texture           | [`grain-overlay`](/catalog/components/grain-overlay)   |
+| Darkened cinematic edges       | [`vignette`](/catalog/components/vignette)             |
+| A light sweep across text      | [`shimmer-sweep`](/catalog/components/shimmer-sweep)   |
+| Slow push-in on a card         | [`parallax-zoom`](/catalog/components/parallax-zoom)   |
+| Card pulls back to reveal siblings | [`parallax-unzoom`](/catalog/components/parallax-unzoom) |
+| Screen dissolves into a grid   | [`grid-pixelate-wipe`](/catalog/components/grid-pixelate-wipe) |
+
+These are the ambient layer of the [motion grammar](/prompting/motion): grain and a slow `parallax-zoom` keep a "held" beat alive instead of freezing. Never write "holds motionless" — a still final second is the biggest cheap-motion tell; let a grain overlay and a 2% push carry the hold.
+
+> 6-second 1920x1080 video. A product logo settles center-frame, then holds — but keep it alive with a film grain overlay and a slow 3% push-in, plus one shimmer sweep across the wordmark at 4s. Use the `grain-overlay`, `parallax-zoom`, and `shimmer-sweep` registry components. No audio.
+
+**Reach for grain over a literal freeze.** The engine holds the final state exactly as written.
+- ❌ `logo appears and holds still to the end`
+- ✅ `logo settles, then a grain overlay and slow push keep the hold breathing` (see [ambient idle](/prompting/motion))
+
+### When an effect needs the canvas pipeline
+
+The distinction that trips people up: the **HTML-in-Canvas blocks are not CSS**. The device mockups, liquid-glass stages, and `vfx-*` blocks render live DOM into WebGL textures via the experimental `drawElementImage` API — which needs a Chrome flag. The [HTML-in-Canvas guide](/guides/html-in-canvas) documents the real behavior:
+
+- **Rendering enables the flag automatically** (`--enable-features=CanvasDrawElement`), including inside Docker — so a video render of these blocks works with no setup.
+- **Live preview in the Studio needs the flag turned on manually** (`chrome://flags/#canvas-draw-element` → *Enabled* → restart). Without it, these blocks fall back rather than showing the effect in preview.
+- The blocks **feature-detect and degrade gracefully**, so a browser without the flag won't crash — it just won't show the WebGL treatment.
+
+The Effects components above have none of this — they're plain CSS and animate everywhere, preview included. So if you need something visible in Studio preview today with zero setup, prefer the CSS Effects; the HTML-in-Canvas group is where the flag caveat lives.
+
+<Warning>
+  Don't promise a stakeholder a live Studio preview of a liquid-glass or device block without confirming the Chrome flag is enabled on that machine — the rendered MP4 is unaffected, but the in-browser preview may fall back. See the [HTML-in-Canvas guide](/guides/html-in-canvas).
+</Warning>
+
+### Where to go next
+
+- [Anatomy of a one-shot prompt](/prompting/anatomy) — the skeleton, and quoting on-screen copy.
+- [Motion that reads premium](/prompting/motion) — the ambient-idle rule these polish layers serve.
+- [Copy-paste examples](/prompting/examples) — a `vfx-liquid-background` social-card prompt to adapt.
+- [HTML-in-Canvas guide](/guides/html-in-canvas) — how `drawElementImage` works and the flag details.
diff --git a/docs/prompting/visual-specs.mdx b/docs/prompting/visual-specs.mdx
new file mode 100644
index 0000000000..ce35b6a1b7
--- /dev/null
+++ b/docs/prompting/visual-specs.mdx
@@ -0,0 +1,28 @@
+---
+title: High-fidelity looks
+description: "Write a visual spec — every element named, positioned, colored, and timed — to carry a specific look in words."
+---
+
+You can carry a specific look in words alone when the prompt reads like a designer's spec — every element named, positioned, colored, and timed. Compare a loose description ("dark night scene, mountain, glowing ring, title fades in") with a spec:
+
+> 8-second 1920x1080 title card. Scene, back to front: #0a0e2a night sky with faint grain; a huge concentric ring system (5 rings, 1px strokes at 8% white opacity, innermost ring glowing #4a5fd9) centered 40% from the top; behind the rings an orange radial glow (#ff6a2b core → transparent, ~300px) igniting at the peak's right shoulder from 2s; a low-poly mountain (6-8 dark navy facets, #141a3d–#1e2650) filling the lower third, a white road S-curving up its face with a soft glow; thin horizontal cloud streaks (white, 6% opacity) drifting right at two heights; a man's silhouette, pure black, ~90px tall, bottom-right, fading in at 2.5s. At 3.5s "SHOWREEL" — thin geometric sans, ~140px, 0.35em tracking, white at 90% — fades in per letter across the ring center, the orange glow bleeding through the O. Slow 4% push-in across the full 8s. No audio.
+
+Every element is a primitive the agent can build directly. Two honest limits:
+
+- **Organic illustration** (drawn characters, painterly texture) can't be fully carried by text — words underdetermine a drawing. Steer to geometric shape language ("flat rounded-geometric figure, circle head, no facial features"), or generate the artwork (see [When to generate artwork](/prompting/generated-artwork)).
+- **Photographic and live-action content** must be supplied as files — mention the paths explicitly.
+
+## Two more worked specs
+
+The same density applied to a product-UI piece and a typographic piece — both one-shot from these exact words. Where a builder had to make a judgment call on the first pass, the spec below pins it, which is the editing loop these specs live by: build, see what the words underdetermined, tighten the words.
+
+> 6-second 1920x1080. A frosted-glass command palette (640x84px, 20px radius, rgba(255,255,255,0.08) fill, 1px rgba(255,255,255,0.25) border, heavy backdrop blur) centered on a #0b0f1a field with two soft accent glows drifting slowly — #5b6cff upper-left, #22d3a5 lower-right, ~400px, 20% opacity. At 0.4s the palette scales in 0.96→1 settling with back.out(1.2). At 0.8s a grey placeholder "Search commands…" types on; at 2.2s it fades out over 0.2s and the query "render 4k" types in white. At 2.8s three result rows (56px tall, 12px gaps: icon square, label, shortcut chip) cascade in as a detached list below the fixed bar, staggered 0.12s, each rising 12px with back.out(1.4). At 4.2s a 10%-opacity #5b6cff fill sweeps left to right across the first row and its shortcut chip pulses once. Rows and glows keep a barely-visible drift to the end. No audio.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/spec-command-palette.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the spec above, unedited.*
+
+> 7-second 1920x1080. Off-black #101014 field with fine static film grain at 4%. The word "PRECISION" in ~220px heavy condensed caps (a heavy system face condensed with scaleX 0.82), white, 0.02em tracking, centered: its letters assemble from alternating top/bottom 40px offsets with power3.out and a 0.05s stagger, starting 0.3s. At 1.8s a 2px hairline rule draws left-to-right beneath the word, 60% of its width, centered. At 2.4s a 40px tabular-mono counter fades in below and ticks 99.999 → 00.001 mm over 2.2s with expo.out deceleration. At 5.2s the whole lockup eases to 1.03 scale over 0.5s while the word cools from white to #d8d8de, then settles into a slow ±1% breathing idle to the end. No audio.
+
+<video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/spec-precision-type.mp4" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
+*Rendered from the spec above, unedited.*
+
diff --git a/docs/prompting/vocabulary.mdx b/docs/prompting/vocabulary.mdx
new file mode 100644
index 0000000000..c15b720292
--- /dev/null
+++ b/docs/prompting/vocabulary.mdx
@@ -0,0 +1,190 @@
+---
+title: Vocabulary that changes output
+description: "Natural-language adjectives the skills map to specific framework settings — easing, captions, transitions, audio, voices."
+---
+
+The skills map natural-language adjectives to specific framework settings. Using the right word gets you the right result without specifying technical details.
+
+### Motion & easing
+
+Describe how motion should *feel* and the agent picks the matching GSAP ease:
+
+| Say this    | Agent uses       | Feels like                     |
+| ----------- | ---------------- | ------------------------------ |
+| smooth      | `power2.out`     | Natural deceleration           |
+| snappy      | `power4.out`     | Quick and decisive             |
+| bouncy      | `back.out`       | Overshoots then settles        |
+| springy     | `elastic.out`    | Oscillates into place          |
+| dramatic    | `expo.out`       | Fast start, long glide         |
+| dreamy      | `sine.inOut`     | Slow, symmetrical              |
+
+**Timing shorthand:** fast (0.2s) = energy, medium (0.4s) = professional, slow (0.6s) = luxury, very slow (1–2s) = cinematic.
+
+Each word, rendered — the same move, only the ease changes:
+
+<table><tbody>
+<tr><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/ease-power2-out.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>smooth · power2.out</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/ease-power4-out.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>snappy · power4.out</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/ease-back-out.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>bouncy · back.out</div></td></tr>
+<tr><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/ease-elastic-out.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>springy · elastic.out</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/ease-expo-out.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>dramatic · expo.out</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/ease-sine-inout.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>dreamy · sine.inOut</div></td></tr>
+</tbody></table>
+
+
+### Camera language
+
+Compositions have no physical camera, but camera words translate directly into scene transforms (or real camera moves in Three.js scenes):
+
+| Say this            | Agent builds                                              |
+| ------------------- | --------------------------------------------------------- |
+| slow push-in        | 4–8% scale increase across the scene, gentle ease          |
+| pull back / widen   | scale decrease, often paired with elements entering        |
+| pan across          | horizontal translate of the scene layer                    |
+| drone orbit         | continuous camera orbit (Three.js scenes)                  |
+| crane down/up       | vertical camera drift combined with a look-at shift        |
+| whip to             | fast blurred slide into the next framing                   |
+| parallax            | layers translating at different rates for depth            |
+
+The same scene under each camera word:
+
+<table><tbody>
+<tr><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-push-in.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>slow push-in</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-pull-back.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>pull back</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-pan.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>pan across</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-crane.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>crane down</div></td></tr>
+<tr><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-whip.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>whip to</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-parallax.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>parallax</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/camera-orbit.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>drone orbit (Three.js)</div></td></tr>
+</tbody></table>
+
+
+### Depth language
+
+| Say this               | Agent builds                                             |
+| ---------------------- | -------------------------------------------------------- |
+| near-lens / foreground bokeh | large, heavily-blurred elements drifting close to camera |
+| depth planes           | 2–3 layers moving at different speeds                     |
+| out-of-focus background | blurred, slower-moving back layer                        |
+| shallow depth of field | sharp subject, blurred everything-else                    |
+
+### Pacing language
+
+| Say this          | Agent builds                                        |
+| ----------------- | --------------------------------------------------- |
+| punchy cuts       | 1.5–4s per idea, hard cuts, overlapping entrances    |
+| cinematic holds   | longer beats with ambient idle motion                |
+| beat-synced       | cuts and accents on the music's beat grid            |
+| breathing room    | a held moment before the next beat starts            |
+| ambient idle      | 1–2% breathing scale + slow drift during holds       |
+
+### Caption tones
+
+Describe the *energy* of your captions and the agent picks matching typography, size, and animation:
+
+| Tone         | Typography             | Animation    | Size range |
+| ------------ | ---------------------- | ------------ | ---------- |
+| Hype         | Heavy weight fonts     | Scale-pop    | 72–96px    |
+| Corporate    | Clean sans-serif       | Fade + slide | 56–72px    |
+| Tutorial     | Monospace              | Typewriter   | 48–64px    |
+| Storytelling | Serif                  | Slow fade    | 44–56px    |
+| Social       | Rounded, playful       | Bounce       | 56–80px    |
+
+```
+"Hype-style captions with scale-pop"
+"Calm, elegant subtitles with slow fades"
+"Karaoke-style word highlighting"
+```
+
+Per-word styling also works:
+
+```
+"Make brand names larger with accent color"
+"Add bounce to emotional keywords"
+"Highlight numbers differently"
+```
+
+### Transitions
+
+Every multi-scene composition benefits from transitions. Describe the energy level:
+
+| Energy  | CSS option       | Shader option       |
+| ------- | ---------------- | ------------------- |
+| Calm    | Blur crossfade   | Cross-warp morph    |
+| Medium  | Push slide       | Whip pan            |
+| High    | Zoom through     | Glitch, ridged burn |
+
+Or describe by mood:
+
+```
+"Warm transitions for this wellness brand"
+"Cold, clinical transitions for tech"
+"Playful bouncy transitions"
+"Dramatic zoom for the reveal"
+```
+
+### Audio-reactive animation
+
+Map audio frequency bands to visual properties. The agent uses these defaults:
+
+| Audio band | Maps to   | Visual effect       |
+| ---------- | --------- | ------------------- |
+| Bass       | `scale`   | Pulse on the beat   |
+| Treble     | `glow`    | Shimmer intensity   |
+| Amplitude  | `opacity` | Breathing           |
+| Mids       | `shape`   | Morphing            |
+
+```
+"Make the text pulse with the beat"
+"Add bass-driven scale to the logo"
+"Create glow that responds to treble"
+```
+
+<Tip>
+  Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%).
+</Tip>
+
+### Marker highlights
+
+Hand-drawn emphasis effects for text:
+
+| Mode        | Effect             | Best for      |
+| ----------- | ------------------ | ------------- |
+| `highlight` | Marker sweep       | Key phrases   |
+| `circle`    | Hand-drawn ellipse | Single words  |
+| `burst`     | Radiating lines    | Hype moments  |
+| `scribble`  | Chaotic scratch    | Crossing out  |
+| `sketchout` | Rectangle outline  | Callouts      |
+
+```
+"Add a marker highlight sweep on 'revolutionary'"
+"Circle this keyword with hand-drawn effect"
+"Add burst lines around 'AMAZING'"
+```
+
+The five modes on the same sentence:
+
+<table><tbody>
+<tr><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/marker-highlight.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>highlight</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/marker-circle.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>circle</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/marker-burst.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>burst</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/marker-scribble.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>scribble</div></td><td style={{ padding: "6px", border: "none" }}><video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/marker-sketchout.mp4" style={{ width: "100%", borderRadius: "0.4rem" }}></video><div style={{ fontSize: "0.8em", textAlign: "center", opacity: 0.7 }}>sketchout</div></td></tr>
+</tbody></table>
+
+### Text-to-speech voices
+
+TTS runs locally via Kokoro (no API key needed). Describe the content and the agent picks a voice, or request one directly:
+
+| Content type  | Recommended voices         |
+| ------------- | -------------------------- |
+| Product demo  | `af_heart`, `af_nova`      |
+| Tutorial      | `am_adam`, `bf_emma`       |
+| Marketing     | `af_sky`, `am_michael`     |
+
+```
+"Generate narration for this script"
+"Create voiceover with a professional female voice"
+"Add TTS with British male voice at 1.1x speed"
+```
+
+### Rendering quality
+
+| Quality    | Use for                  |
+| ---------- | ------------------------ |
+| `draft`    | Fast iteration           |
+| `standard` | Review and feedback      |
+| `high`     | Final delivery           |
+
+```
+"Quick draft render"
+"Render at high quality"
+"Export as transparent WebM"
+```
diff --git a/plans/prompt-guide-expansion.md b/plans/prompt-guide-expansion.md
new file mode 100644
index 0000000000..1c898443b6
--- /dev/null
+++ b/plans/prompt-guide-expansion.md
@@ -0,0 +1,266 @@
+# Prompt Guide expansion plan
+
+Status: draft 2026-07-08. Owner: Vance. Source of validated content: the 2026-07-07/08
+prompting-guide work (18 verified example prompts, showreel recreation, motion grammar,
+asset-gen hybrid, recreation protocol; renders in ~/src/hyperframes-prompt-examples,
+preview page https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe).
+
+## Goal
+
+Promote `guides/prompting` from a single page to a top-level **Prompt Guide** nav group:
+the current page splits into focused sub-pages, each expanded, and every documented
+feature that _implies_ a promptable action gets actual prompting guidance. Standing
+rule carried over from the original guide: **no prompt ships unverified** — every
+example is built, rendered, and (where feasible) embedded next to its prompt.
+
+## Navigation (docs.json)
+
+New top-level group between **Concepts** and **Guides**:
+
+```
+[Prompt Guide]
+  prompting/overview
+  [Fundamentals]
+    prompting/anatomy
+    prompting/specification-dial
+    prompting/vocabulary
+    prompting/iterating
+    prompting/rules-and-anti-patterns
+  [Making it look good]
+    prompting/visual-specs
+    prompting/motion
+    prompting/generated-artwork
+    prompting/recreating-references
+  [By video type]
+    prompting/product-launch
+    prompting/explainers
+    prompting/code-and-prs
+    prompting/music-and-slideshows
+    prompting/captions-and-talking-heads
+    prompting/motion-graphics
+  [By feature]
+    prompting/transitions
+    prompting/captions-catalog
+    prompting/overlays-and-lower-thirds
+    prompting/code-blocks
+    prompting/data-and-maps
+    prompting/vfx-and-liquid-glass
+    prompting/rendering-and-output
+    prompting/editing-existing-videos
+    prompting/media-and-audio
+    prompting/variables-and-templating
+    prompting/runtimes-and-3d
+    prompting/design-systems
+```
+
+`guides/prompting` becomes a redirect to `prompting/overview`. Keep the page count out
+of prose (drift rule, same as skills.mdx).
+
+## Page-by-page
+
+### prompting/overview
+
+Landing: what prompting a video means, one-time skill setup (moved from current page),
+the two prompt shapes (cold/warm), the recommended workflow loop, and a map of the
+section. Ends with 3 "best of" example prompts w/ embedded renders.
+
+### Fundamentals (split + expand current content — all already validated)
+
+- **anatomy** — the 6-part skeleton, per-part rationale, assembled terminal example,
+  plus 3 dissections: take a weak prompt, show the fixed version, diff annotated.
+- **specification-dial** — mood → style tokens → full spec; cross-model validation
+  result; the two always-pins (Three.js, sequencing). Expand: when looseness is a
+  feature (creative exploration) vs when density is mandatory.
+- **vocabulary** — existing mapping tables (easing, caption tones, transition energy,
+  audio-reactive, marker highlights, TTS voices, render quality) + new validated ones:
+  camera language ("push in 6%", "drone orbit"), depth language ("near-lens bokeh"),
+  pacing language ("punchy 2s cuts" vs "cinematic holds").
+- **iterating** — talk-like-an-editor edits (existing) + the calibration rules from the
+  recreation work: absolute targets not relative nudges, one axis at a time, freeze
+  what works.
+- **rules-and-anti-patterns** — the 7 technical rules, anti-patterns, plus the newly
+  validated ones: never "holds motionless", don't create simultaneity conflicts,
+  don't override skill-mandated styles, "~60s" with verbatim scripts.
+
+### Making it look good (current sections promoted to pages, each gains examples)
+
+- **visual-specs** — density ladder + mountain-title worked example + 2 more specs
+  (one UI piece, one typographic piece) with renders.
+- **motion** — the six-rule premium-motion grammar; before/after render pair
+  (frozen-hold build vs motion-pass build of the same piece — we have both).
+- **generated-artwork** — hybrid pattern, 3 keying/restraint rules, before/after
+  (hand-drawn SVG team vs asset-gen team — we have both renders).
+- **recreating-references** — the transcribe → iterate → distill protocol, fidelity
+  table, globe worked example + its one-shot render; honest-ceiling callout.
+
+### By video type (one page per workflow; the 8 current examples seed them)
+
+Each page: what the workflow does, 3-5 verified prompts (the existing one + variants:
+different durations, aspect ratios, tones), the knobs that matter for that workflow
+(e.g. explainer: verbatim vs summarized script, caption style, scene density), and
+common failure modes. NEW VALIDATION NEEDED: ~2-4 variant builds per page.
+Pages: product-launch (also covers website-to-video), explainers, code-and-prs
+(pr-to-video + code blocks context), music-and-slideshows, captions-and-talking-heads
+(embedded-captions + talking-head-recut), motion-graphics (also logo stings, stats).
+
+### By feature — the "implied but unguided" gap pages
+
+Sourced from existing docs that document a capability without prompting guidance:
+
+- **transitions** (sources: 14 shader + 13 CSS catalog groups, transitions skill) —
+  energy/mood → named block mapping, when shader vs CSS, per-seam prompting
+  ("whip-pan on phrase changes"), full block name table. Validation: montage build
+  exercising ~6 transitions.
+- **captions-catalog** (sources: 15 caption components + embedded-captions skill) —
+  tone → component mapping ("karaoke pill", "kinetic slam", "matrix decode"), per-word
+  styling asks, safe-area/vertical notes. Validation: one clip rendered with 4 styles.
+- **overlays-and-lower-thirds** (sources: social overlays, lower-thirds, news-ticker
+  catalog groups) — "add a lower third at 0:03 with name/title" class of prompts,
+  picking styles by brand tone, transparent-overlay output for NLEs.
+- **code-blocks** (sources: code animations + 24 code-snippet themes) — prompting
+  code walkthroughs: typing, diff, highlight, scroll; theme selection language.
+- **data-and-maps** (sources: data-chart, 5 US-map variants, world/spain maps) — chart
+  prompts from CSV/inline data, map highlight/flow/bubble asks, the animated-map
+  motion-graphics pattern.
+- **vfx-and-liquid-glass** (sources: HTML-in-Canvas group, html-in-canvas guide) —
+  device mockups, liquid glass, shatter/portal/magnetic effects; when these need the
+  canvas pipeline and what to say.
+- **rendering-and-output** (sources: rendering, 4k-rendering, hdr, deploy/lambda) —
+  quality/format/framerate asks, transparent WebM (and when it's incoherent — full-frame
+  designs), 4K/HDR guidance incl. cost warnings, "render this on Lambda" cloud prompts.
+- **editing-existing-videos** (sources: timeline-editing, keyframes,
+  video-editor-cheatsheet, studio docs) — NLE-verb prompts: trim/split/move/retime
+  scenes, keyframe nudges, "make scene 2 snappier", swap assets; maps the cheatsheet's
+  editor verbs to prompt phrasings. Likely the highest-traffic page of the group.
+- **media-and-audio** (sources: video-components, remove-background, media-use skill)
+  — TTS voice/tone/speed asks, BGM mood + loudness targets ("under -18dB"), SFX cues,
+  transcription/captions from audio, background removal, video-in-video/PiP, and the
+  supplied-assets rule (explicit paths).
+- **variables-and-templating** (sources: concepts/variables, sdk) — parameterized
+  compositions ("make name/logo/color variables"), batch/personalization prompts,
+  template-then-instantiate pattern.
+- **runtimes-and-3d** (sources: concepts/frame-adapters, gsap-animation) — the
+  Three.js-via-adapter pin with worked language, when Lottie/CSS/WAAPI make sense to
+  request, shader transition requests, canvas/WebGL determinism caveats in prompt form.
+- **design-systems** (sources: claude-design, open-design, figma skill) — design.md /
+  brand-token driven prompting, "use the site's own palette", Figma import asks.
+
+## Validation & build plan
+
+Reuse the proven pipeline: Opus builder subagents, one-shot from the page's prompts,
+lint+validate+render gates, frame verification; embed finished MP4s next to prompts
+(Mintlify supports video embeds; assets go wherever docs media lives today — confirm
+hosting path, else link the HeyGenVerse gallery).
+
+Phasing (each phase shippable):
+
+1. **Restructure** — split current page into overview + Fundamentals + Making-it-look-good
+   (no new validation needed; content exists). Add nav group + redirect. ~1 PR.
+2. **High-traffic gaps** — editing-existing-videos, rendering-and-output,
+   media-and-audio, transitions, captions-catalog. Each needs a validation build day.
+3. **By video type** — 6 pages, variant builds per workflow.
+4. **Long tail** — remaining feature pages (data-and-maps, vfx, variables, runtimes,
+   design-systems, overlays, code-blocks).
+
+## Competitive research findings (2026-07-08, adversarially verified)
+
+Deep-research survey of first-party prompt guides — Sora 2 (OpenAI Cookbook), Runway
+Gen-3/Gen-4, Veo (DeepMind + Cloud Veo 3.1), Luma, Anthropic prompt-engineering docs.
+(Pika/Kling/Midjourney/Gemini/Copilot claims failed verification — resurvey later.)
+What the best guides converge on, and what we adopt:
+
+1. **Named content-slot anatomy.** Every major guide teaches a slot formula
+   (camera + subject + action + context + style [+ audio]); Veo 3.1 and Runway Gen-3
+   make it a literal bracket template. We already have a _process_ skeleton
+   (route/spec/beats/copy/technique/negatives) — ADD a named _content_ formula whose
+   slots map to HyperFrames concepts (beat + element + motion + layout + style/brand
+   - audio), demonstrated in one worked example. Lives on the anatomy page.
+2. **Keyword→Output tables.** Runway Gen-3's gold standard: six categorized keyword
+   tables where every row pairs the keyword with the actual generated output. Our
+   vocabulary tables get the same treatment: motion verbs → GSAP behavior, camera
+   terms → transform/Three.js choreography, style terms → CSS treatment — each row
+   with a small rendered clip. (Borrow the format, not their legacy keywords.)
+3. **Output pairing is the differentiator.** Even the best guides skip outputs on
+   their most complex examples (Sora's longest templates ship without any; both Veo
+   guides mostly unpaired — refuted 0-3). Our article standard (every prompt +
+   unedited render) beats the field; keep it absolute.
+4. **❌/✅ paired rewrites under named rules with engine rationale** — Runway's
+   dominant device (e.g. ❌ "no clouds in the sky" → ✅ "a clear blue sky", because
+   negative prompts backfire). Adopt across anatomy + rules pages using our own
+   validated pairs: ❌ "holds motionless" → ✅ "settles into ambient idle";
+   ❌ "both at 4s" → ✅ "fades out by 4.2s; at 4.2s..."; ❌ "make dots 2x finer" →
+   ✅ "dot radius = 25% of row spacing".
+5. **Iteration as single-variable science.** Sora: "editing is for nudging, not
+   gambling" — one change per edit; Runway Gen-4: minimal motion-only prompt first,
+   then add ONE element type at a time; strip-then-relayer when a shot misfires.
+   Expand the iterating page with these three moves + our absolute-targets rule.
+6. **Timestamped/beat-segmented prompting as a signature device.** Veo 3.1's
+   [00:00-00:02] per-segment prompting is the survey's most distinctive device — and
+   it maps one-to-one onto HyperFrames' native data-* timing. Our "Beat N (x-ys)"
+   convention is this; promote it explicitly ("more native here than in any
+   diffusion model") on anatomy + by-video-type pages.
+7. **Anthropic's IA moves**: thin-router overview, one consolidated living
+   best-practices reference (legacy URLs 301 into anchors), prerequisite gate
+   ("before prompting, have X"). Adopt: keep overview thin; add a short
+   prerequisites block (skills installed, preview running, project scaffolded);
+   plan redirects when pages consolidate later.
+8. **Efficacy evidence as differentiation** (research open question): no surveyed
+   guide shows its advice measurably works. Ours can — renders are deterministic and
+   cheap; we already hold before/after pairs (frozen vs motion-passed, hand-drawn vs
+   generated, loose vs dense builds). Add "before/after" render pairs as a standard
+   device on making-it-look-good pages.
+
+Full cited report: deep-research run wf_c81199b6-b15 (22 confirmed claims, 3 refuted;
+sources incl. cookbook.openai.com, help.runwayml.com, deepmind.google, cloud.google.com,
+lumalabs.ai, platform.claude.com).
+
+## Incorporate the article's drafted guidance
+
+The HeyGenVerse article (https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe)
+drafted guidance and presentation patterns beyond the current mdx — these become the
+template for every expanded page:
+
+- **Proof pairing**: every example prompt is immediately followed by its unedited
+  render with the label "Rendered from the prompt above, unedited." This is the
+  guide's core credibility device — pages without renders don't ship.
+- **Provenance line**: each page states how its claims were validated (built,
+  rendered, frame-verified) and when. The article's footer wording is the model.
+- **Example tags**: prompts carry a visible registry-block / workflow / freeform tag
+  so readers learn which layer of the system they're exercising.
+- **Drafted section prose to carry over into the split pages** (the article's phrasing
+  is tighter than the mdx in places — reconcile toward the article):
+  - Specification dial: "controls how far the result drifts from what you imagined,
+    not whether it works" + the two-pins callout as a distinct highlighted element.
+  - Generated artwork: the wins/loses two-column comparison (code-drawn wins /
+    code-drawn loses) rather than prose paragraphs.
+  - Motion: six numbered rules with the "frozen final second is the biggest
+    cheap-motion tell" line.
+  - Recreation: the 3-row fidelity table (transcribe ~75% / iterate ~90% /
+    distill ~80-90%) + honest-ceiling callout, with the one-shot render embedded
+    under the distilled spec (not the hand-tuned version — the honest artifact).
+- **Article lifecycle**: the HV page stays the shareable preview/marketing surface;
+  it gets regenerated from the docs content at the end of each phase so the two never
+  fork. Renders already uploaded as HV assets (19 MP4s) are reusable by URL in the
+  docs if we choose the link-out hosting option (open question 2).
+
+## Consistency obligations
+
+- CLAUDE.md "skill catalog maintenance" applies: skills' SKILL.md descriptions stay the
+  source of truth for one-line blurbs; the by-video-type pages must link the matching
+  skill and not fork its routing language.
+- llms.txt regenerates from docs — verify the new group lands there.
+- Vocabulary tables must match what skills actually implement (easing map, caption
+  tones) — audit against skills/hyperframes-animation + embedded-captions at write time.
+- Catalog pages already demo each block; feature pages link to them rather than
+  duplicating block docs. Prompting pages own only the "what to say" layer.
+
+## Open questions
+
+1. Group vs tab in docs.json (Mintlify): group keeps single-sidebar; tab gives the
+   guide its own sidebar. Current nav is single-tab groups — start as group, promote to
+   tab if it crowds.
+2. Where do example MP4s live for docs embeds — repo (heavy), CDN bucket, or link out
+   to the HeyGenVerse gallery page? Decide before Phase 1 ships renders.
+3. Do by-video-type pages absorb the existing standalone guides (website-to-video) or
+   link them? Proposal: link, don't absorb — those guides cover mechanics, prompting
+   pages cover phrasing.
diff --git a/skills-manifest.json b/skills-manifest.json
index 82e22e1c56..c2cb8b913f 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -22,7 +22,7 @@
       "files": 1
     },
     "hyperframes-animation": {
-      "hash": "16ecdf00cf5cebf1",
+      "hash": "1c58fa2ea614e477",
       "files": 99
     },
     "hyperframes-cli": {
@@ -30,7 +30,7 @@
       "files": 7
     },
     "hyperframes-core": {
-      "hash": "511a6283a5dbd7ea",
+      "hash": "73e6f4cad4701e6d",
       "files": 14
     },
     "hyperframes-creative": {
diff --git a/skills/hyperframes-animation/adapters/gsap-transforms-and-perf.md b/skills/hyperframes-animation/adapters/gsap-transforms-and-perf.md
index cc932de898..c64260e03d 100644
--- a/skills/hyperframes-animation/adapters/gsap-transforms-and-perf.md
+++ b/skills/hyperframes-animation/adapters/gsap-transforms-and-perf.md
@@ -54,6 +54,7 @@ Animate any custom property. Works for color, length, number — anything CSS wi
 
 - `svgOrigin` sets transform origin in the SVG's global coordinate space (not the element's local box). **Do not** combine `svgOrigin` with `transformOrigin` on the same element — pick one.
 - Animate SVG transform attributes via the same alias names (`x`, `y`, `rotation`) — GSAP handles the SVG-specific quirks.
+- **Runtime-created SVG (`createElementNS`) has no reliable center pivot.** GSAP can't resolve `transformOrigin`/`svgOrigin` to the geometric center of an element built at runtime, so `scale`/`rotation` pivot on the SVG's `(0,0)` origin instead of the shape's middle. Fix: draw the animated geometry centered at local `(0,0)` and place it with a wrapping `<g transform="translate(x,y)">` — the group positions it, the tween scales/rotates it about its own center.
 
 ## Performance Rules
 
diff --git a/skills/hyperframes-core/SKILL.md b/skills/hyperframes-core/SKILL.md
index 9df077c6d5..4faa9f9b96 100644
--- a/skills/hyperframes-core/SKILL.md
+++ b/skills/hyperframes-core/SKILL.md
@@ -49,6 +49,13 @@ The standalone root needs an explicit **sized box** (`width`/`height` in px), an
 
 Each composition registers **exactly one** `gsap.timeline({ paused: true })` at `window.__timelines["<id>"]` (key = root `data-composition-id`), built **synchronously** at page load. Render duration = root `data-duration`, not timeline length. Don't manually nest sub-timelines into the host. Full contract (incl. non-GSAP runtimes) → `references/determinism-rules.md` + `hyperframes-animation/adapters/`.
 
+### First-pass lint gotchas (a guaranteed first build failure)
+
+Two rules that `lint` **does** catch, but only after the fact — write them right the first time:
+
+- The **root** composition element must carry `data-start="0"` (alongside `data-composition-id`/`data-width`/`data-height`); omitting it fails `lint` with `root_composition_missing_data_start`.
+- Never pair a CSS initial `transform` with a GSAP tween on the **same** property — the CSS value and the tween's start fight and `lint` rejects it with `gsap_css_transform_conflict`. Set the initial state inside the tween with `gsap.fromTo(el, { x: -40 }, { x: 0 })` instead of a CSS `transform: translateX(-40px)`.
+
 ### Non-negotiable rules (silent bugs `lint`/`validate`/`inspect` won't catch)
 
 Surfaced here; full rationale in the linked reference. Do not violate: