docs(prompting): polish pass — verify facts against sources, fix staleness

Five-way review of the section against docs.json, catalog pages, and
skills. Fixes: stale /hyperframes-media skill row (real name /media-use)
plus missing music-to-video and slideshow workflow rows; caption
identity misattributions (keynote/documentary are scene-embedded, stomp
carries no rail); prompts violating the guide's own ambient-idle rule;
grounded keying rationale (u2net_human_seg); broken forward references;
nested-backtick code spans; brand casing and frontmatter dash
consistency throughout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/prompting/anatomy.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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:

docs/prompting/captions-and-talking-heads.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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
@@ -44,7 +44,7 @@ You describe the *cards* — their content, timing, and how the speaker shares t
     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 `stomp` identity: heavy themed constitution, punch reactions on the climax. Rail carries the verbatim; the payoff line is the setpiece. 9:16.
+    > /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>
@@ -57,7 +57,7 @@ You describe the *cards* — their content, timing, and how the speaker shares t
 
 ## 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 like `anchor`, `keynote`, or `documentary`; 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.
+**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.
 

docs/prompting/code-and-prs.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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

docs/prompting/code-blocks.mdx

@@ -67,7 +67,7 @@ For "here's what changed," hand `code-diff` the before and after and let it colo
 
 **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`)`
+- ✅ `highlight line 7 (timeout: 30_000)`
 
 ### Prompting a scroll-through
 

docs/prompting/data-and-maps.mdx

@@ -24,7 +24,7 @@ Feed data inline or as a file. Small series go straight in the prompt; a CSV get
 
 **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`
+- ✅ `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`
@@ -67,7 +67,7 @@ The US map encodings combine — asking to "shade states *and* draw flows betwee
 
 **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`
+- ✅ `use the spain-map registry block`
 
 ### Routes and flights
 
@@ -82,6 +82,6 @@ For a point-to-point journey — a route drawing across a map with a landing bea
 ### 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-grid prompts to adapt.
+- [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.

docs/prompting/design-systems.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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.

docs/prompting/explainers.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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

docs/prompting/generated-artwork.mdx

@@ -5,10 +5,10 @@ description: "Code-drawn wins for UI, type, geometry, and 3D; illustration-led h
 
 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 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.
+> 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 — saliency matting can invert on flat art and keep the background instead. Save `remove-background` for photographic subjects.
+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.

docs/prompting/iterating.mdx

@@ -1,9 +1,9 @@
 ---
 title: Iterating
-description: "Talk to the agent like a video editor - small targeted edits beat re-specification."
+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:
+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.
 

docs/prompting/motion-graphics.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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
@@ -36,10 +36,10 @@ Each reuses a registry block, so the agent composes rather than hand-building fr
     > /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, holds. Use `code-particle-assemble` for the assembly.
+    > /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. Hold on the card at the end. Use the `x-post` and `vfx-liquid-background` registry blocks. No narration, no image or media files.
+    > /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.

docs/prompting/motion.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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:

docs/prompting/music-and-slideshows.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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

docs/prompting/overview.mdx

@@ -1,9 +1,9 @@
 ---
 title: Prompt Guide
-description: "How to prompt AI agents to author HyperFrames videos - setup, the two prompt shapes, and the map of this 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.
+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.
@@ -28,7 +28,7 @@ The installer shows a picker. Select the **core skills** below — every project
 | `/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`    |
-| `/hyperframes-media`    | Asset preprocessing — `tts`, `transcribe`, `remove-background`             |
+| `/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 |
 
@@ -43,10 +43,12 @@ The installer shows a picker. Select the **core skills** below — every project
 | `/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.
+  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>
 
 
@@ -70,7 +72,7 @@ Claude Design produces a valid first draft (brand identity, scene content, anima
 
 ## The two prompt shapes
 
-Most successful Hyperframes prompts fall into one of two shapes.
+Most successful HyperFrames prompts fall into one of two shapes.
 
 ### Cold start — describe the video
 
@@ -89,7 +91,7 @@ Cold-start prompts work best when you specify:
 
 ### 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.
+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`.
 

docs/prompting/product-launch.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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

docs/prompting/recreating-references.mdx

@@ -1,15 +1,15 @@
 ---
 title: Recreating something you saw
-description: "Transcribe motion, iterate with absolute targets, distill the constants - and know where the text-only ceiling is."
+description: "Transcribe motion, iterate with absolute targets, distill the constants — and know where the text-only ceiling is."
 ---
 
-Matching a specific reference from text alone is possible to roughly 90% — but only with a specific workflow, and knowing where the 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.
+**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:
 
@@ -18,7 +18,7 @@ A distilled spec that one-shots a broadcast-style animated globe:
   >
   > 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 with royal-blue ocean dominating (~30–35% coverage of the visible hemisphere).
+  > 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.
   >

docs/prompting/runtimes-and-3d.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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.

docs/prompting/specification-dial.mdx

@@ -1,6 +1,6 @@
 ---
 title: The specification dial
-description: "Spec density controls how far the result drifts from what you imagined - not whether it works."
+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.
@@ -9,7 +9,7 @@ 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 (next section). Use when you're recreating a specific look.
+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:
 

docs/prompting/variables-and-templating.mdx

@@ -1,6 +1,6 @@
 ---
 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."
+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.

docs/prompting/vfx-and-liquid-glass.mdx

@@ -38,7 +38,7 @@ The four `liquid-glass-*` panel blocks share the aurora-shader stage, so they co
 
 **"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`
+- ✅ `use the liquid-glass-widgets registry block for the stat cards`
 
 ### Shatter, portal, magnetic, and cursor moments
 
@@ -97,5 +97,5 @@ The Effects components above have none of this — they're plain CSS and animate
 
 - [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 shatter-into-text prompt to adapt.
+- [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.

docs/prompting/visual-specs.mdx

@@ -1,13 +1,13 @@
 ---
 title: High-fidelity looks
-description: "Write a visual spec - every element named, positioned, colored, and timed - to carry a specific look in words."
+description: "Write a visual spec — every element named, positioned, colored, and timed — to carry a specific look in words."
 ---
 
-Recreating a specific look from words alone works when the prompt reads like a designer's spec — every element named, positioned, colored, and timed. Compare a description ("dark night scene, mountain, glowing ring, title fades in") with a spec:
+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 (next section).
+- **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.

docs/prompting/vocabulary.mdx

@@ -1,6 +1,6 @@
 ---
 title: Vocabulary that changes output
-description: "Natural-language adjectives the skills map to specific framework settings - easing, captions, transitions, audio, voices."
+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.