From e60bef3f579a27d8be2d93b62109f063459646f6 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 3 Aug 2026 16:40:22 -0700
Subject: [PATCH 1/5] docs: rewrite the guides and landing pages

Rewrites the pages that survive the restructure so they lead with what a reader
can accomplish, and points them at the sections added in the previous commit.
Page set and navigation are unchanged here; only content moves.

Keeps the skill count in README. CLAUDE.md's catalog-maintenance rule requires
the count to live in README and CLAUDE.md, and both now agree with the 19
directories under skills/.
---
 docs/examples.mdx                        | 362 +++++----------
 docs/guides/4k-rendering.mdx             | 185 ++------
 docs/guides/authentication.mdx           |  58 ++-
 docs/guides/claude-design-hyperframes.md |  10 +-
 docs/guides/color-grading.mdx            | 565 ++++-------------------
 docs/guides/deploy.mdx                   | 229 +++------
 docs/guides/feedback.mdx                 | 261 ++---------
 docs/guides/figma.mdx                    |  46 +-
 docs/guides/gsap-animation.mdx           | 194 ++++----
 docs/guides/hdr.mdx                      | 211 ++-------
 docs/guides/html-in-canvas.mdx           | 160 +++----
 docs/guides/hyperframes-vs-remotion.mdx  | 185 +++-----
 docs/guides/mcp.mdx                      | 380 ++++-----------
 docs/guides/media-effects.mdx            | 369 +++------------
 docs/guides/open-design-hyperframes.md   |   2 +-
 docs/guides/performance.mdx              | 157 ++-----
 docs/guides/remove-background.mdx        | 464 ++++---------------
 docs/guides/rendering.mdx                | 477 ++++---------------
 docs/guides/skills.mdx                   | 220 +++++----
 docs/guides/troubleshooting.mdx          | 310 +++++++------
 docs/guides/video-components.mdx         | 191 +++-----
 docs/introduction.mdx                    | 173 ++-----
 docs/quickstart.mdx                      | 291 ++----------
 docs/weekly-updates.mdx                  |  17 +-
 24 files changed, 1570 insertions(+), 3947 deletions(-)

diff --git a/docs/examples.mdx b/docs/examples.mdx
index a980c933d6..846262755b 100644
--- a/docs/examples.mdx
+++ b/docs/examples.mdx
@@ -1,274 +1,128 @@
 ---
-title: Examples
-description: "Built-in examples for common video patterns. Hover to preview animations."
+title: "Examples"
+description: "Watch finished HyperFrames videos, inspect real production projects, or start from a working template."
 ---
 
-Hyperframes includes starter examples to help you scaffold compositions quickly. Each example gives you a working project with the correct [composition structure](/concepts/compositions), [data attributes](/concepts/data-attributes), and a [GSAP timeline](/guides/gsap-animation) already wired up.
-
-<Note>
-  Looking for finished videos and production projects? Start with the [Showcase](/showcase).
-</Note>
-
-```bash Terminal
-npx hyperframes init my-video --example <name>
-```
-
-## Landscape Templates
-
-<div className="not-prose grid grid-cols-2 gap-4 my-6">
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/warm-grain.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/warm-grain.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.7))"}}><strong className="text-sm font-semibold text-white block">Warm Grain</strong><span className="text-xs text-zinc-300">Branding & lifestyle</span></div>
-  </div>
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/play-mode.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/play-mode.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Play Mode</strong><span className="text-xs text-zinc-300">Social media</span></div>
-  </div>
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/swiss-grid.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/swiss-grid.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Swiss Grid</strong><span className="text-xs text-zinc-300">Corporate & technical</span></div>
-  </div>
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/kinetic-type.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/kinetic-type.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Kinetic Type</strong><span className="text-xs text-zinc-300">Promos & title cards</span></div>
-  </div>
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/decision-tree.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/decision-tree.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Decision Tree</strong><span className="text-xs text-zinc-300">Explainers & tutorials</span></div>
-  </div>
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/product-promo.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/product-promo.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Product Promo</strong><span className="text-xs text-zinc-300">Product showcases</span></div>
-  </div>
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full aspect-video object-cover block" src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/nyt-graph.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/nyt-graph.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">NYT Graph</strong><span className="text-xs text-zinc-300">Data stories</span></div>
+import { DocsVideo } from "/snippets/docs-video.jsx";
+
+## Finished films
+
+Each preview links to the complete source project.
+
+<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-4 my-7">
+  <a className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950" href="https://github.com/heygen-com/hyperframes-launches/tree/main/hyperframes-launch">
+    <video className="aspect-video w-full object-cover" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/hyperframes-launch-preview.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/hyperframes-launch-poster.jpg" autoPlay muted loop playsInline preload="metadata" />
+    <div className="p-4">
+      <strong className="block text-sm">HyperFrames launch</strong>
+      <span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">Product film · source included</span>
+    </div>
+  </a>
+
+  <a className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950" href="https://github.com/heygen-com/hyperframes-launches/tree/main/timeline-launch">
+    <video className="aspect-video w-full object-cover" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/timeline-editor-preview.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/timeline-editor-poster.jpg" autoPlay muted loop playsInline preload="metadata" />
+    <div className="p-4">
+      <strong className="block text-sm">Timeline editor launch</strong>
+      <span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">Feature reveal · source included</span>
+    </div>
+  </a>
+
+<a
+  className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950"
+  href="https://github.com/heygen-com/hyperframes-launches/tree/main/website-to-hyperframes"
+>
+  <video
+    className="aspect-video w-full object-cover"
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/website-to-hyperframes-preview.mp4"
+    poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/website-to-hyperframes-poster.jpg"
+    autoPlay
+    muted
+    loop
+    playsInline
+    preload="metadata"
+  />
+  <div className="p-4">
+    <strong className="block text-sm">Website to HyperFrames</strong>
+    <span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">
+      Product story · source included
+    </span>
   </div>
+</a>
+
+  <a className="group overflow-hidden rounded-xl border border-zinc-200 bg-white text-inherit no-underline dark:border-zinc-800 dark:bg-zinc-950" href="https://github.com/heygen-com/hyperframes-launches/tree/main/texture-launch-video">
+    <video className="aspect-video w-full object-cover" src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/texture-launch-preview.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/texture-launch-poster.jpg" autoPlay muted loop playsInline preload="metadata" />
+    <div className="p-4">
+      <strong className="block text-sm">Texture launch</strong>
+      <span className="mt-1 block text-xs text-zinc-500 dark:text-zinc-400">Motion design · source included</span>
+    </div>
+  </a>
 </div>
 
-## Portrait Templates
-
-<div className="not-prose grid grid-cols-3 gap-3 my-6">
-  <div className="tpl-card relative rounded-xl overflow-hidden bg-zinc-900 transition-transform hover:-translate-y-0.5 hover:shadow-xl">
-    <video className="w-full object-cover block" style={{aspectRatio: "9/16"}} src="https://static.heygen.ai/hyperframes-oss/docs/images/templates/vignelli.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/templates/vignelli.png" muted loop playsInline preload="metadata" />
-    <div className="absolute bottom-0 left-0 right-0 pt-6 pb-2 px-3" style={{background: "linear-gradient(transparent, rgba(0,0,0,0.75))"}}><strong className="text-sm font-semibold text-white block">Vignelli</strong><span className="text-xs text-zinc-300">Headlines & announcements</span></div>
-  </div>
-</div>
-
-<Tip>
-  Looking for a minimal starting point? Use **blank** — it gives you an empty composition with just the scaffolding, no visual design.
-
-  ```bash Terminal
-  npx hyperframes init my-video --example blank
-  ```
-</Tip>
-
-## Choosing an Example
-
-| Example | Style | Format | Best for |
-|----------|-------|--------|----------|
-| `warm-grain` | Organic, textured | Landscape | Lifestyle, branding, editorial |
-| `play-mode` | Energetic, elastic | Landscape | Social media, product launches |
-| `swiss-grid` | Clean, structured | Landscape | Corporate, data, technical |
-| `kinetic-type` | Dramatic type | Landscape | Promos, intros, title cards |
-| `decision-tree` | Diagrammatic | Landscape | Explainers, tutorials |
-| `product-promo` | Multi-scene | Landscape | Product showcases, demos |
-| `nyt-graph` | Editorial data | Landscape | Data stories, reports |
-| `vignelli` | Bold, typographic | Portrait | Headlines, announcements |
-| `blank` | Minimal scaffolding | — | Full control, agent-generated |
-
-## Example Details
-
-<Tabs>
-  <Tab title="warm-grain">
-    ### warm-grain
-
-    Cream-toned aesthetic with grain texture overlay.
-
-    **What it produces:** A composition with warm color grading, textured grain, and smooth transitions. Includes an intro sub-composition and captions support.
+## One project, open end to end
 
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    ├── compositions/
-    │   ├── intro.html
-    │   ├── graphics.html
-    │   └── captions.html
-    └── assets/
-    ```
-  </Tab>
-  <Tab title="play-mode">
-    ### play-mode
+This is the same small project used in the Quickstart. Its request, brief,
+source, revision notes, checks, and final render are all public.
 
-    Playful elastic animations with bold, energetic motion.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    ├── compositions/
-    │   ├── intro.html
-    │   ├── stats.html
-    │   └── captions.html
-    └── assets/
-    ```
-  </Tab>
-  <Tab title="swiss-grid">
-    ### swiss-grid
-
-    Structured grid layout inspired by Swiss/International Typographic Style.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    ├── compositions/
-    │   ├── intro.html
-    │   ├── graphics.html
-    │   └── captions.html
-    └── assets/
-    ```
-  </Tab>
-  <Tab title="vignelli">
-    ### vignelli
-
-    Bold typography with red accents (1080×1920 portrait).
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    ├── compositions/
-    │   ├── overlays.html
-    │   └── captions.html
-    └── assets/
-    ```
-  </Tab>
-  <Tab title="kinetic-type">
-    ### kinetic-type
-
-    Bold kinetic typography promo with dramatic text animations.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    └── compositions/
-        └── main-graphics.html
-    ```
-  </Tab>
-  <Tab title="decision-tree">
-    ### decision-tree
-
-    Animated flowchart with branching paths and progressive reveal.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    └── compositions/
-        └── decision_tree.html
-    ```
-  </Tab>
-  <Tab title="product-promo">
-    ### product-promo
-
-    Multi-scene product showcase with SVG assets.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    ├── compositions/
-    │   ├── scene1-logo-intro.html
-    │   ├── scene2-4-canvas.html
-    │   └── scene5-logo-outro.html
-    └── assets/
-        ├── figma-cursors.svg
-        ├── figma-logo-pieces.svg
-        └── figma-logo-pills.svg
-    ```
-  </Tab>
-  <Tab title="nyt-graph">
-    ### nyt-graph
-
-    Animated data chart in print editorial style.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    └── compositions/
-        └── nyt-chart.html
-    ```
-  </Tab>
-  <Tab title="blank">
-    ### blank
-
-    Empty composition with just the scaffolding.
-
-    ```
-    my-video/
-    ├── meta.json
-    ├── index.html
-    └── compositions/
-        └── captions.html
-    ```
-  </Tab>
-</Tabs>
-
-## Passing a Source Video
-
-```bash Terminal
-npx hyperframes init my-video --example warm-grain --video ./my-clip.mp4
+```text
+Using /hyperframes, make a 10-second product intro for https://example.com.
 ```
 
-The CLI will probe the video for duration, resolution, and codec. If the video uses an incompatible codec, it will be automatically transcoded to H.264 MP4 if FFmpeg is available.
-
-## Custom Examples
+<div className="not-prose my-6 grid overflow-hidden rounded-xl border border-zinc-200 bg-white md:grid-cols-4 dark:border-zinc-800 dark:bg-zinc-950">
+  <a className="border-b border-zinc-200 p-4 text-inherit no-underline md:border-b-0 md:border-r dark:border-zinc-800" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/BRIEF.md">
+    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Brief</span>
+    <strong className="mt-1 block text-sm">What the agent decided</strong>
+  </a>
+  <a className="border-b border-zinc-200 p-4 text-inherit no-underline md:border-b-0 md:border-r dark:border-zinc-800" href="https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project">
+    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Source</span>
+    <strong className="mt-1 block text-sm">Every editable project file</strong>
+  </a>
+  <a className="border-b border-zinc-200 p-4 text-inherit no-underline md:border-b-0 md:border-r dark:border-zinc-800" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md#2-v1--v2">
+    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Revision</span>
+    <strong className="mt-1 block text-sm">What changed after review</strong>
+  </a>
+  <a className="p-4 text-inherit no-underline" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md">
+    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Checks</span>
+    <strong className="mt-1 block text-sm">The real verification report</strong>
+  </a>
+</div>
 
-Any directory with an `index.html` can serve as an example. Your custom example needs:
+<div style={{ maxWidth: "36rem", margin: "1.5rem auto" }}>
+  <DocsVideo
+    title="The verified 10-second Reference Project render"
+    src="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/reference-project-v2.mp4"
+    poster="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/poster-v2.jpg"
+  />
+</div>
 
-1. An `index.html` with a [`data-composition-id`](/concepts/data-attributes#composition-attributes) root element
-2. A [GSAP timeline](/guides/gsap-animation) registered in `window.__timelines`
-3. Any assets in the same directory or a subdirectory
+The result is not a sealed demo. Open any stage above and use the same shape for
+your own project: request → brief → source → revision → render.
 
-```html index.html
-<div id="root" data-composition-id="my-example"
-     data-start="0" data-width="1920" data-height="1080">
+## Start from a template
 
-  <!-- Your elements here -->
+Create a project with a working example:
 
-  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-    // Add your animations...
-    window.__timelines = window.__timelines || {};
-    window.__timelines["my-example"] = tl;
-  </script>
-</div>
+```bash
+npx hyperframes init my-video --example <name>
 ```
 
-After creating a custom example, validate it with the [linter](/packages/cli#lint):
+| Example         | Good starting point for                      |
+| --------------- | -------------------------------------------- |
+| `warm-grain`    | Branding, lifestyle, and editorial work      |
+| `play-mode`     | Energetic social videos and product launches |
+| `swiss-grid`    | Technical, structured, and corporate stories |
+| `kinetic-type`  | Type-led promos, intros, and title cards     |
+| `decision-tree` | Explainable diagrams and tutorials           |
+| `product-promo` | Multi-scene product showcases                |
+| `nyt-graph`     | Editorial charts and data stories            |
+| `vignelli`      | Bold portrait announcements                  |
+| `blank`         | Agent-generated or fully custom work         |
 
-```bash Terminal
-npx hyperframes lint
-```
+<Tip>
+  Choose a template for its structure and tone, then replace the sample content. If none fits, start
+  with `blank` and let the agent build from the brief.
+</Tip>
 
-## Next Steps
+## Related topics
 
-<CardGroup cols={2}>
-  <Card title="Quickstart" icon="rocket" href="/quickstart">
-    Create, preview, and render your first video
-  </Card>
-  <Card title="Launch Videos" icon="github" href="/launch-videos">
-    Real production projects from HeyGen's launches — open-source for you to read and remix.
-  </Card>
-  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
-    Add animations to your example
-  </Card>
-  <Card title="Compositions" icon="layer-group" href="/concepts/compositions">
-    Understand the composition data model
-  </Card>
-</CardGroup>
+- [Make your first video](/quickstart)
+- [Choose a creation workflow](/workflows)
+- [Take more control of an existing project](/go-further)
diff --git a/docs/guides/4k-rendering.mdx b/docs/guides/4k-rendering.mdx
index c5b08b9e26..9a0597d1c5 100644
--- a/docs/guides/4k-rendering.mdx
+++ b/docs/guides/4k-rendering.mdx
@@ -1,167 +1,70 @@
 ---
-title: 4K Rendering
-description: "Render any composition to 4K (3840×2160) without rewriting it — the CLI supersamples a 1080p composition via Chrome's device scale factor."
+title: Render in 4K
+description: Author at 4K or supersample an existing composition at render time.
 ---
 
-Hyperframes renders to 4K (3840×2160) two ways. Both produce a true 4K MP4; pick the one that matches your project.
-
-<CardGroup cols={2}>
-  <Card title="Author at 4K" icon="ruler">
-    Scaffold the project at 4K so the composition is laid out at 4K natively. Best when you want crisp 4K-native typography and assets.
-    ```bash
-    npx hyperframes init my-video --resolution 4k
-    ```
-  </Card>
-  <Card title="Supersample at render" icon="up-right-and-down-left-from-center">
-    Keep your existing 1080p composition. Pass `--resolution 4k` at render time and Chrome renders at 2× DPR so the screenshot lands at 4K.
-    ```bash
-    npx hyperframes render --resolution 4k --output 4k.mp4
-    ```
-  </Card>
-</CardGroup>
-
-## Quickstart
-
-<Steps>
-  <Step title="Render an existing project at 4K">
-    ```bash Terminal
-    npx hyperframes render --resolution 4k --output my-video-4k.mp4
-    ```
-
-    The composition's `data-width` / `data-height` are unchanged. Chrome's `deviceScaleFactor` is set to `2`, so the captured screenshot for each frame is 3840×2160. ffmpeg auto-detects the dimensions from the screenshot stream and encodes at 4K.
-  </Step>
-  <Step title="Or scaffold a new project at 4K">
-    ```bash Terminal
-    npx hyperframes init my-video --resolution 4k
-    ```
-
-    Every scaffolded HTML file is patched in place: `data-width="3840"`, `data-height="2160"`, `data-resolution="landscape-4k"`, `#stage` CSS dimensions, and the `<meta viewport>` tag.
-  </Step>
-  <Step title="Verify the output is 4K">
-    ```bash Terminal
-    ffprobe -v error -select_streams v:0 -show_entries stream=width,height my-video-4k.mp4
-    ```
-
-    Expected:
-    ```
-    width=3840
-    height=2160
-    ```
-  </Step>
-</Steps>
-
-## Resolution presets
-
-`--resolution` accepts these values on both `init` and `render`:
-
-| Preset | Dimensions | Aliases |
-|--------|-----------|---------|
-| `landscape` | 1920×1080 | `1080p`, `hd` |
-| `portrait` | 1080×1920 | `1080p-portrait` |
-| `square` | 1080×1080 | `1080p-square`, `square-1080p` |
-| `landscape-4k` | 3840×2160 | `4k`, `uhd` |
-| `portrait-4k` | 2160×3840 | `4k-portrait` |
-| `square-4k` | 2160×2160 | `4k-square` |
-
-Examples:
-
-```bash Terminal
-npx hyperframes render --resolution 4k         # landscape 4K
-npx hyperframes render --resolution portrait-4k # vertical 4K (TikTok / Reels at max quality)
-npx hyperframes render --resolution 1080p       # explicit 1080p (no-op on 1080p compositions)
-```
-
-## How `--resolution` works (supersampling)
-
-The composition stays at its authored dimensions. Hyperframes computes a `deviceScaleFactor` from the ratio of output to composition dimensions and passes it to Chrome:
-
-| Composition | `--resolution` | `deviceScaleFactor` | Output |
-|-------------|---------------|--------------------|--------|
-| 1920×1080 | `4k` | 2 | 3840×2160 |
-| 1080×1920 | `portrait-4k` | 2 | 2160×3840 |
-| 3840×2160 | `4k` | 1 (no-op) | 3840×2160 |
-
-Chrome then renders the page at the higher DPR — effectively rendering each CSS pixel as 2×2 device pixels — so the captured screenshot is at the requested resolution.
+## Render an existing project in 4K
 
-<Tip>
-  This approach is intentionally simple — no composition edits, no second authoring pass. The tradeoff: 4K renders take roughly 4× as long per frame because there are 4× the pixels to capture and encode.
-</Tip>
-
-## What scales, what doesn't
-
-Supersampling re-renders the page at higher DPR. That genuinely helps anything the browser rasterizes from a vector or high-resolution source, and does nothing for content already locked to a fixed pixel grid. Knowing which is which sets correct expectations before a 4K render:
+```bash
+npx hyperframes render --resolution 4k --output final-4k.mp4
+```
 
-| Asset type | Behavior at `--resolution 4k` |
-|------------|------------------------------|
-| Text (HTML, SVG `<text>`, web fonts) | ✅ **Re-rasterized at 4K.** Glyphs are vector and the browser shapes/rasterizes them at the new DPR. Crisp at any scale. |
-| SVG / vector graphics | ✅ **Re-rasterized at 4K.** Same story as text — paths are vector. |
-| CSS shapes, gradients, borders, shadows | ✅ **Re-rasterized at 4K.** Browser-generated raster. |
-| Images with intrinsic dimensions ≥ 4K | ✅ **Full benefit.** A 3840×2160 source serves all the detail. |
-| Images smaller than 4K (e.g. a 1920×1080 PNG) | ⚠️ **No new detail.** Browser upscales the source bitmap; output is no sharper than rendering at 1080p and upscaling externally — but no worse either. |
-| `<video>` elements | ❌ **Locked to source resolution.** A 1080p MP4 stays 1080p; the supersample only helps the surrounding DOM. Encode source video at the target resolution if you need 4K throughout. |
-| `<canvas>` (2D and WebGL) | ❌ **Locked to canvas's intrinsic dimensions.** `<canvas width="1920" height="1080">` is a 1080p bitmap regardless of DPR. To render canvas content at 4K, multiply `canvas.width` / `canvas.height` by your target DPR and scale the drawing context (`ctx.scale(2, 2)` for a 2× canvas with the same logical layout). |
-| Pre-rendered video frames injected by the engine | ❌ **Locked to extraction resolution.** When the producer pre-extracts `<video>` frames via ffmpeg, they're decoded at the source video's dimensions. |
+HyperFrames keeps the composition's layout unchanged and captures it at a higher device-pixel ratio. A 1920×1080 composition becomes a 3840×2160 file.
 
-**Rule of thumb**: if the asset is *vector or generated by the browser*, supersampling helps. If it's a *bitmap with fixed pixel dimensions* (video, canvas, low-res PNG), it doesn't — author it at the target resolution instead.
+Use the matching preset for portrait or square work:
 
-## Constraints
+| Preset | Output |
+| --- | --- |
+| `4k` or `landscape-4k` | 3840×2160 |
+| `portrait-4k` | 2160×3840 |
+| `square-4k` | 2160×2160 |
 
-`--resolution` enforces three guards before any frames are captured. If any fail, the render exits before doing work.
+## Author a project at 4K
 
-### Aspect ratio must match
+If the project should use a 4K canvas from the start:
 
 ```bash
-# OK — both landscape
-hyperframes render --resolution 4k         # composition is 1920×1080
-
-# Error — composition is landscape, target is portrait
-hyperframes render --resolution portrait-4k  # composition is 1920×1080
-# → outputResolution portrait-4k (2160×3840) does not match the aspect ratio
-#   of the composition (1920×1080). Pick a preset whose orientation matches.
+npx hyperframes init my-video --resolution 4k
 ```
 
-### The scale must be an integer
-
-The width ratio (output ÷ composition) must be a positive integer. 1080p → 4K is exactly `2×`. 720p → 4K would be `3×` and works. Non-integer scales like 900p → 4K (`2.4×`) introduce aliasing on subpixel-positioned text — Hyperframes refuses rather than producing a blurry render.
-
-### Downsampling is not supported
-
-`--resolution` only supersamples. A 4K composition cannot be downsampled to 1080p with this flag — render at the composition's native resolution and downscale separately with ffmpeg if needed.
-
-### Not yet supported with `--hdr`
+Choose this when canvas or WebGL code, fixed-resolution media, or layout decisions need to know the final pixel dimensions while you author.
 
-The HDR layered compositor processes pixel buffers at composition dimensions; supersample + HDR would need parallel scaling for those buffers. The combination is rejected with a clear error message. Render in two passes if you need both: HDR at composition resolution, then upscale separately.
+## What gets sharper
 
-## Performance
+| Content | Result when supersampled |
+| --- | --- |
+| HTML text, SVG, CSS shapes, gradients | Re-rasterized at 4K |
+| High-resolution images | Use their available source detail |
+| 1080p images and video | Scaled up; no new source detail |
+| `<canvas>` and WebGL | Limited by the canvas's intrinsic dimensions |
 
-A 1080p → 4K supersample is roughly 4× more pixels to capture, encode, and write. Expect:
+For a fully sharp 4K result, use 4K source media and size canvas/WebGL buffers for the target resolution.
 
-- **Per-frame capture**: 3–4× slower (Chrome paints 4× the pixels and the screenshot transfer is 4× larger)
-- **Encoding**: 2–3× slower (depends on codec; H.264 scales sublinearly with resolution)
-- **Memory**: bounded — the engine's frame data-URI cache is byte-budgeted (default 1500 MB per worker, configurable via `PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB`)
-- **Output file size**: at the default CRF, expect 3–5× the file size of the 1080p render. Pass `--video-bitrate 25M` (or higher) for predictable file sizes.
-
-For a 4K render of a 30-second composition, plan on a few minutes of wall time on a modern laptop. Add `--workers 4` (or more) on a render box for parallel capture.
+## Constraints
 
-## Studio support
+`--resolution` only works when:
 
-The Renders panel in Studio includes a resolution dropdown next to the format and quality selectors. Pick `4K` (or `4K ↕` for portrait) and hit **Export** — the same supersampling path runs as the CLI flag, no composition edits required.
+- the preset has the same aspect ratio as the composition;
+- the target is an integer multiple of the authored dimensions;
+- the target is not smaller than the composition;
+- the output is MP4 rather than an alpha format;
+- HDR is not forced for the same render.
 
-The dropdown defaults to `Auto` (render at the composition's authored size). Available presets:
+HyperFrames checks these conditions before opening the browser. Render at the composition's native size and resize separately when a combination is unsupported.
 
-- **Auto** — composition's native dimensions
-- **1080p ↔** / **1080p ↕** — 1920×1080 / 1080×1920
-- **4K ↔** / **4K ↕** — 3840×2160 / 2160×3840
+## Verify the file
 
-The resolution applies per render, not per project — your composition files are unchanged. The same [constraints](#constraints) apply; when the producer rejects a combination, the failure surfaces in the Studio render queue.
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height final-4k.mp4
+```
 
-You can also drive resolution from the CLI:
+For landscape 4K, the output should report `3840` by `2160`.
 
-- **New project**: `hyperframes init my-video --resolution 4k`
-- **Existing project**: `hyperframes render --resolution 4k --output 4k.mp4`
+4K captures four times as many pixels as 1080p, so expect more render time, memory use, and output data. Start with `--quality draft` for review, then render the approved version at the quality you need.
 
-## See also
+## Related topics
 
-- [`render` CLI reference](/packages/cli#render) — every render flag including `--video-bitrate` and `--crf`
-- [`init` CLI reference](/packages/cli#init) — the `--resolution` flag at scaffold time
-- [HDR Rendering](/guides/hdr) — color pipeline guide; HDR + 4K is not yet a supported combination
+- [Render from the command line](/guides/rendering)
+- [Improve render performance](/guides/performance)
+- [Deliver an HDR project](/guides/hdr)
diff --git a/docs/guides/authentication.mdx b/docs/guides/authentication.mdx
index 797b79e679..31650ef2d0 100644
--- a/docs/guides/authentication.mdx
+++ b/docs/guides/authentication.mdx
@@ -1,9 +1,12 @@
 ---
 title: Authentication & API keys
-description: "Sign in to HeyGen, and how the keys for voice, music, and capture resolve across the CLI and skills — including the priority order and the fully local fallback."
+description: "Sign in to HeyGen and understand how agent workflows choose voice, music, sound, and optional capture-description providers."
 ---
 
-HyperFrames uses a HeyGen credential for premium voiceover (TTS) and the music / sound-effects library. Other providers are optional, and **everything runs without any key** — voice and music fall back to fully local engines. This page covers signing in, the keys each capability uses, and the order they resolve.
+You can create and render locally without an account. Voice and music can fall
+back to local engines when no provider key is available. Sign in when you want
+HeyGen voice and music, managed cloud rendering, hosted MCP, or ownership of a
+published project that you can update later.
 
 ## Sign in
 
@@ -37,12 +40,15 @@ Signing in is the same OAuth step as creating an account — new users land on t
 The credential lives in `~/.heygen/credentials` (mode `0600`) — no per-repo `.env` to manage. Browser OAuth is a `hyperframes auth login` feature. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) (its own install — there's no `npx heygen`) is API-key-only, so `heygen auth login` just stores a key you paste. Both read the same `~/.heygen/credentials`, so signing in with one carries to the other.
 
 <Tip>
-  No account needed to try HyperFrames. With no credential, voice uses **Kokoro** and music uses **MusicGen**, both fully local and offline — see [Working offline](#working-offline).
+  No account is needed to try HyperFrames locally. With no credential, voice can
+  use **Kokoro** and music can use **MusicGen** — see [Working
+  offline](#working-offline).
 </Tip>
 
-## How credentials resolve
+## How the HeyGen credential resolves
 
-The HeyGen credential drives TTS and music / SFX **retrieval**. It resolves first-match-wins:
+Bundled media workflows use the HeyGen credential for hosted TTS and music /
+sound retrieval. It resolves first-match-wins:
 
 1. `HEYGEN_API_KEY` — environment variable
 2. `HYPERFRAMES_API_KEY` — alias, for parity with other tools
@@ -50,28 +56,52 @@ The HeyGen credential drives TTS and music / SFX **retrieval**. It resolves firs
 
 Point at a different config directory with `HEYGEN_CONFIG_DIR`, or a different backend with `HEYGEN_API_URL`.
 
-## Keys by capability
+## Providers used by agent workflows
 
-Each capability picks the **first available provider** in order; the last is always a local engine that needs no key. Cloud providers below the HeyGen line need their own key *and* a local Python dependency.
+After the workflow's sign-in preflight, each media capability uses the first
+available provider in its order. Voice, music, and sound have offline
+fallbacks; capture descriptions are optional and are skipped when no supported
+vision key is available.
 
 | Capability | Provider order | Key(s) — first match wins | Local dependency |
 |------------|----------------|---------------------------|------------------|
 | **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | `HEYGEN_API_KEY` → `HYPERFRAMES_API_KEY` → `~/.heygen` · then `ELEVENLABS_API_KEY` | Kokoro: `pip install kokoro-onnx soundfile` |
 | **Music (BGM)** | HeyGen library → Lyria → MusicGen | HeyGen credential (above) · then `GEMINI_API_KEY` → `GOOGLE_API_KEY` | MusicGen: `pip install transformers torch soundfile numpy` |
 | **Sound effects** | HeyGen library → bundled library | HeyGen credential (above) | bundled — no deps |
-| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | — (optional; for [website capture](/guides/website-to-video)) |
+| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | None; optional for [website capture](/guides/product-launch-video) |
 
-Run `npx hyperframes doctor` to check which local dependencies are installed. The media skills also run `hyperframes auth status` as a preflight before generating, so you always know whether a run will use HeyGen or a local engine before it starts.
+Run `npx hyperframes doctor` to check which local dependencies are installed.
+The media workflows run `hyperframes auth status` before generation and tell
+you which path they will use.
+
+<Note>
+  `npx hyperframes tts` itself is the local Kokoro CLI. Hosted HeyGen and
+  ElevenLabs voices are selected by the bundled media workflow helpers, not by
+  that command.
+</Note>
 
 ## Working offline
 
-No key configured is a normal state, not an error. The workflow runs entirely on local models:
+No key configured is a normal state for local work. After their dependencies
+and model files are installed, these fallbacks run locally:
 
 - **Voice** — Kokoro-82M (54 voices), with Whisper for word-level caption alignment.
 - **Music** — MusicGen (`facebook/musicgen-small`).
 - **Sound effects** — a bundled library.
 
-Local engines are free and offline; HeyGen gives higher-quality voices and a professionally produced music library. Sign in any time to switch a project from local to HeyGen.
+Local engines do not call a hosted generation API after setup. Their first use
+may download model files. HeyGen provides managed voices and a produced music
+library; sign in when you want those services or cloud rendering.
+
+## Publishing without an account
+
+`npx hyperframes publish` works while signed out. It uploads the project and
+prints a URL containing a claim token. Open that URL and authenticate in the web
+app to claim the project.
+
+Sign in with `npx hyperframes auth login` before publishing when you want the CLI
+to own the project immediately, update the same URL with `--update`, or publish
+to a shared space with `--space`.
 
 ## Environment variables
 
@@ -85,4 +115,8 @@ Local engines are free and offline; HeyGen gives higher-quality voices and a pro
 | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Lyria music generation (and capture descriptions). |
 | `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step. |
 
-See the [`hyperframes auth`](/packages/cli#hyperframes-auth) command reference for subcommand details, and [Cloud rendering](/deploy/cloud) for using the same credential to render in HeyGen's cloud.
+## Related topics
+
+- [Open the authentication command reference](/packages/cli#hyperframes-auth)
+- [Render with HyperFrames Cloud](/deploy/cloud)
+- [Choose where to create](/guides/choose-creation-path)
diff --git a/docs/guides/claude-design-hyperframes.md b/docs/guides/claude-design-hyperframes.md
index f009be5dd7..172b4b1bb5 100644
--- a/docs/guides/claude-design-hyperframes.md
+++ b/docs/guides/claude-design-hyperframes.md
@@ -523,7 +523,7 @@ composition with `-c` rather than as a bare path.
 npx hyperframes render -o output.mp4
 ```
 
-1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 3840x2160` to override.
+1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 4k` to override.
 ````
 
 ### Skeleton A -- Social Reel (1080x1920, 15s, 6 scenes)
@@ -1231,8 +1231,8 @@ tl.to("#s5-headline", { backgroundSize: "100% 30%", duration: 0.6, ease: "power2
 Everything critical is inlined above. These are for edge cases:
 
 - Core composition contract (data attributes, sub-comp wiring): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/SKILL.md
-- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/motion-principles.md
-- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/typography.md
-- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/transitions.md
-- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/captions.md
+- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/motion-principles.md
+- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-creative/references/typography.md
+- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes-animation/transitions/overview.md
+- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/embedded-captions/SKILL.md
 - Full docs: https://hyperframes.heygen.com/
diff --git a/docs/guides/color-grading.mdx b/docs/guides/color-grading.mdx
index f2fa71cc48..e712bc3a65 100644
--- a/docs/guides/color-grading.mdx
+++ b/docs/guides/color-grading.mdx
@@ -1,501 +1,128 @@
 ---
-title: Color Grading
-description: "Correct and creatively grade video or image media with presets, scopes, color wheels, curves, HSL selections, and custom LUTs."
+title: "Color grade images and footage"
+sidebarTitle: "Color grading"
+description: "Correct exposure and color, shape a look, apply a LUT, and review the result in Studio."
 ---
 
-Use Color Grading to correct and creatively grade real `<video>` and `<img>`
-media in Studio or through an agent with the same validated SDR/Rec.709 shader
-contract in preview and render.
+Use Color Grading when an image or video needs correction or a deliberate
+visual look. It changes that media element only; text, captions, SVG, and normal
+HTML remain separate layers.
 
-## Choose the Right Tool
+<Frame caption="The same source before and after a restrained natural-portrait grade.">
+  <img
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/color-grading-before-after-v1.png"
+    alt="The same presenter frame before and after a restrained natural portrait grade"
+  />
+</Frame>
 
-| Stage | Purpose | HyperFrames tools |
-| --- | --- | --- |
-| Correct | Fix exposure, contrast, tonal balance, and casts | Adjust controls and source analysis |
-| Grade | Shape color and mood | Tonal wheels, RGB curves, hue curves, and HSL color selections |
-| Apply a look | Start from a tested style or an existing external look | Presets and custom 3D `.cube` LUTs |
-| Finish | Add restrained optical texture | Vignette and grain |
-| Stylize | Transform the pixels beyond normal grading | [Media Effects](/guides/media-effects) |
-| Dress | Add an authored HUD, flash, light leak, or freeze-frame layer | [Media Overlays](/guides/media-overlays) |
+## Work in this order
 
-All pixel-level stages are stored together on the selected media element. An
-overlay is different: it is an ordinary editable composition layer whose final
-paint order follows its authored track and CSS `z-index`.
-
-## Quick Start
-
-<Tabs>
-  <Tab title="Studio">
-    Select a real `<img>` or `<video>` element to open Color Grading in the
-    Design panel.
-
-    <Steps>
-      <Step title="Correct the source">
-        Open **Scopes**, then adjust exposure, tonal balance, white balance, and
-        saturation before applying a stronger look.
-      </Step>
-      <Step title="Shape the grade">
-        Use tonal wheels, curves, or an HSL Color Selection only where the
-        source needs more precise control.
-      </Step>
-      <Step title="Choose a look and verify">
-        Preview a preset or load a 3D `.cube` LUT, compare with the source, and
-        scrub representative frames before rendering.
-      </Step>
-    </Steps>
-  </Tab>
-  <Tab title="Agent / CLI">
-    Inspect the media, apply one validated payload, then verify representative
-    frames:
-
-    ```bash Terminal
-    npx hyperframes media-treatment \
-      --project . \
-      --file compositions/interview.html \
-      --selector '#interview' \
-      --analyze \
-      --json
-
-    npx hyperframes media-treatment \
-      --project . \
-      --file compositions/interview.html \
-      --selector '#interview' \
-      --grading '{"adjust":{"highlights":-0.08,"shadows":0.06},"wheels":{"midtones":{"hue":32,"amount":0.05}}}' \
-      --apply \
-      --json
-    ```
-
-    Use `--dry-run` when target or scope is uncertain. Use `--clear` to remove
-    the complete treatment.
-  </Tab>
-</Tabs>
-
-To reuse a grade in Studio, use **Copy grade to**, choose **Current file media**
-or **All project media**, then click **Apply**. Project-wide copy refuses
-project-relative LUT paths because the same path may resolve differently in
-another composition; use current-file copy or a project-root path/data URL. The
-copy changes only the treatment payload, not overlays, captions, or DOM layers.
-
-Project-local media is the reliable path. Remote media requires compatible CORS
-headers. Color Grading does not process captions, text, SVG, arbitrary DOM, or
-CSS background images.
-
-## Professional Controls
-
-### Color Wheels
-
-The three wheels target broad tonal zones:
-
-- **Shadows** shapes dark regions.
-- **Midtones** shapes most faces, products, and general scene color.
-- **Highlights** shapes bright regions and specular areas.
-
-Use small amounts first. The **Level** control changes the brightness of the
-same tonal zone, while hue and amount introduce color.
-
-### RGB Curves
-
-- **Master** remaps overall luminance.
-- **Red**, **Green**, and **Blue** remap individual channels.
-
-Curve points are normalized `[input, output]` pairs. Resolved curves contain
-input endpoints `0` and `1`; HyperFrames infers missing endpoints, and the
-2–16-point limit includes those inferred points. An S-curve increases contrast;
-lifting the lower-left region raises shadows; channel curves can build
-split-tone or cast-removal adjustments.
-
-### Hue Curves
-
-- **Hue vs Hue** moves a selected hue toward another hue.
-- **Hue vs Saturation** changes saturation around a selected hue.
-- **Hue vs Luma** changes brightness around a selected hue.
-
-Hue curve points are `[hueDegrees, delta]` pairs and wrap around the color
-wheel. An authored hue curve requires 3–16 unique hue inputs from `0` up to,
-but not including, `360`.
+| Pass | Purpose |
+| --- | --- |
+| Correct | Fix exposure, white balance, contrast, and saturation |
+| Grade | Shape tonal ranges or a selected color |
+| Apply a look | Start from a preset or a compatible `.cube` LUT |
+| Finish | Add restrained detail or film effects |
 
-### HSL Color Selections
+Correct before stylizing. A strong preset cannot rescue clipped highlights,
+unreadable shadows, or the wrong source.
 
-A color selection qualifies pixels by hue, saturation, and luma, then applies a
-correction only inside that matte. This is useful for restrained tasks such as
-reducing an overly saturated shirt, cooling a background color, or protecting
-skin from a broad creative grade.
+## Grade in Studio
 
-HyperFrames supports up to four ordered selections. These are static
-media-level qualifiers: they do not include object tracking, rotoscoping,
-facial recognition, or spatial masks. To confine a grade to a region of the
-frame rather than a range of colors, see
-[Limiting a Grade to Part of the Frame](#limiting-a-grade-to-part-of-the-frame).
+1. Select an image or video on the canvas, in Layers, or on the timeline.
+2. Open **Color grading** in **Design**.
+3. Start with a preset or small corrections.
+4. Use the scopes and compare control to check the result.
+5. Scrub several moments before judging moving footage.
 
-### Scopes
+The controls answer different questions:
 
-| Scope | Use it for |
+| Control | Use it for |
 | --- | --- |
-| Histogram | Overall distribution from dark to bright |
+| Preset and strength | Establish a starting look |
+| Exposure, contrast, highlights, shadows, white point, black point | Correct brightness and contrast |
+| Warmth, tint, vibrance, saturation | Correct or shape color |
+| Color wheels | Shift shadows, midtones, or highlights |
+| RGB curves | Remap luminance or individual channels |
+| Hue curves | Move, saturate, or brighten a selected hue |
+| HSL selections | Correct pixels inside a hue, saturation, and luma range |
+| Grain, vignette, blur, and effects | Finish or deliberately degrade the image |
+| Custom LUT | Apply a known 3D `.cube` transform |
+
+HyperFrames supports up to four ordered HSL selections. They are static
+pixel-value qualifiers, not object tracking, rotoscoping, or spatial masks.
+
+Studio scopes are inspection tools:
+
+| Scope | Shows |
+| --- | --- |
+| Histogram | Overall dark-to-bright distribution |
 | Waveform | Brightness by horizontal image position |
-| RGB Parade | Channel balance and clipped individual channels |
+| RGB Parade | Channel balance and clipping |
 | Vectorscope | Hue direction and saturation |
 
-Studio scopes analyze a captured selected-media frame with the current
-treatment applied. They refresh as the grade changes, but are inspection tools
-and do not modify the grade.
-
-## Presets
-
-HyperFrames ships tested shader-setting presets, not bundled LUT files:
-
-| Intent | Presets |
-| --- | --- |
-| Natural and corrective | Neutral, Warm Daylight, Clean Studio, Skin Soft, Food Pop, Night Lift |
-| Editorial and tonal | Muted Editorial, Vintage Wash, Soft Boost, Bright Pop, Deep Contrast |
-| Monochrome | Mono Clean, Mono Fade |
-
-Use these as starting points and tune them for the actual source. Presets that
-also activate a stylized shader treatment are documented under
-[Media Effects](/guides/media-effects).
-
-## Agent Guidance
-
-Agents should use the CLI as the normal authoring surface. The
-`data-color-grading` attribute is the persistence contract, not the first thing
-an agent needs to memorize.
-
-Users do not need to name a technical control. Requests such as _"this
-interview feels too dark and cold"_ or _"polish the footage without making it
-look filtered"_ route through the `media-use` skill, which inspects the source,
-discovers the relevant contract, applies a deterministic payload, and verifies
-the result.
-
-Start with the concise capability overview, then query only the contract needed
-for the current intent:
-
-```bash Terminal
-npx hyperframes media-treatment --capabilities --json
-npx hyperframes media-treatment --capability grading --json
-npx hyperframes media-treatment --capability curves --json
-```
-
-Focused queries such as `wheels`, `hue-curves`, `secondary`, `scopes`, or `lut`
-return exact controls, bounds, and examples. Start from source analysis or a
-tested preset, then add small, explainable adjustments. Avoid inventing many
-unrelated curve and secondary values: they are difficult to review and easy to
-overcook.
-
-For worked examples — ten graded A/B renders, each with the plain-language
-prompt that produced it and the payload it compiled to — see
-[Color grading and film effects](/prompting/color-grading) in the Prompt Guide.
-It covers the failures this page cannot: choosing a source that actually has
-something for the treatment to remove, and separating a subject so one part of
-the frame can be graded while the rest is protected.
-
-## Low-Level HTML Contract
-
-The CLI and Studio persist the resolved grade in `data-color-grading`:
-
-```html index.html
-<video
-  id="interview"
-  src="assets/interview.mp4"
-  data-start="0"
-  data-duration="6"
-  muted
-  playsinline
-  data-color-grading='{
-    "preset":"clean-studio",
-    "intensity":0.85,
-    "adjust":{
-      "exposure":0.04,
-      "highlights":-0.08,
-      "shadows":0.06,
-      "temperature":0.03
-    },
-    "wheels":{
-      "shadows":{"hue":218,"amount":0.04,"level":-0.01},
-      "midtones":{"hue":32,"amount":0.05,"level":0.01},
-      "highlights":{"hue":42,"amount":0.03,"level":0}
-    },
-    "curves":{
-      "master":[[0,0],[0.28,0.25],[0.72,0.76],[1,1]]
-    },
-    "hueCurves":{
-      "hueVsSaturation":[[0,0],[28,-0.05],[52,0]]
-    },
-    "secondaries":[{
-      "enabled":true,
-      "key":{
-        "hue":{"center":28,"range":18,"softness":12},
-        "saturation":{"min":0.15,"max":0.9,"softness":0.08},
-        "luma":{"min":0.12,"max":0.95,"softness":0.08}
-      },
-      "correction":{"saturation":-0.04,"temperature":0.03}
-    }],
-    "details":{"vignette":0.05,"grain":0.03},
-    "colorSpace":"rec709"
-  }'
-></video>
-```
-
-The contract rejects unknown keys and clamps numeric values to Core-owned
-bounds. Query the current contract instead of copying bounds into agent
-instructions:
-
-```bash Terminal
-npx hyperframes media-treatment --capability secondary --json
-npx hyperframes media-treatment --all --json
-```
-
-Use `--all` only for exhaustive tooling or contract inspection.
+## Give the agent the visible problem
 
-## Animating a Grade
-
-Nine grading properties are exposed as CSS custom properties and can be tweened
-directly:
+You do not need to prescribe shader values:
 
 ```text
---hf-color-grading-ascii      --hf-color-grading-bloom     --hf-color-grading-blur
---hf-color-grading-dither     --hf-color-grading-exposure  --hf-color-grading-intensity
---hf-color-grading-kuwahara   --hf-color-grading-pixelate
---hf-color-grading-lut-intensity
-```
-
-```js
-tl.to("#plate", { "--hf-color-grading-pixelate": 0.5, duration: 3, ease: "power2.inOut" }, 0.3);
+The interview looks too dark and slightly cold.
+Keep skin natural, recover the background enough to read, and avoid a filtered look.
 ```
 
-Start the value at identity in the payload and in an inline `style`, so frame 0
-is the ungraded reference and every intermediate value is rendered rather than
-just the endpoints.
-
-Two things this list does **not** give you:
-
-- **`--hf-color-grading-intensity` scales the primary grade only.** The shader
-  mixes between the ungraded sample and the graded one at that value, so it
-  ramps `adjust`, `wheels`, `curves`, `hueCurves`, `secondaries` and the LUT.
-  `details` and `effects` sit outside that mix entirely and it scales neither.
-  Some of them shape the sampled media *before* the mix — CRT warp, blur,
-  Kuwahara, pixelate, the tape family, chromatic aberration, digital glitch —
-  and so are already present on both sides of it. Others run *after* it —
-  grain, halftone, bloom, scanlines, vignette. Either way intensity does not
-  reach them, so it is not a master "ramp the whole look" dial when the look is
-  effect-based; animate the specific effect instead.
-- **Every other property — `halftone`, `twoInkPrint`, `tapeDamage`, hue curves,
-  secondaries — has no custom property**, so it cannot be tweened this way.
-
-For some of those, you can drive the payload itself from the timeline.
-Rewriting `data-color-grading` re-applies the grade:
-
-```js
-const plate = document.getElementById("plate");
-const v = { halftone: 0, bloom: 0 };
-
-tl.to(v, {
-  halftone: 0.72,
-  bloom: 0.7,
-  duration: 3.4,
-  ease: "power2.inOut",
-  onUpdate: () => {
-    plate.setAttribute("data-color-grading", JSON.stringify({
-      intensity: 1,
-      effects: {
-        halftone: v.halftone, halftoneSize: 0.38,
-        bloom: v.bloom, bloomRadius: 18,
-      },
-    }));
-  },
-}, 0.3);
-```
-
-This stays deterministic: the value is derived from timeline position, never
-from wall-clock time, so seeking to a frame always produces the same result.
-It costs a payload parse per tick, so prefer a custom property when one exists.
-
-<Warning>
-  **This does not work for every effect.** It is verified working for `halftone`
-  and `twoInkPrint`. It is verified *not* working for `crtCurvature`,
-  `scanlines`, `chromaBleed`, and `chromaticAberration` — the identical payload
-  applied statically renders correctly, but the same values driven through
-  `setAttribute` produce no visible change, and seeding them non-zero at init
-  does not help. Measure the effect you intend to animate before committing to
-  it, and fall back to a static treatment if the ramp does not move.
-</Warning>
-
-## Limiting a Grade to Part of the Frame
-
-Grading qualifies pixels **by value, never by position**. Selections key on hue,
-saturation, and luma; the one spatially-varying control, `vignette`, is locked
-to the frame centre and cannot be moved or reshaped into a power window. There
-are no masks, shapes, or tracked regions in the contract.
-
-A grade also applies to a whole media element. So to treat part of the frame,
-split that part into its own layer and grade the layer:
-
-| You want | Build |
-| --- | --- |
-| Subject graded, background clean | Matted cutout on top, graded; original clip underneath, clean |
-| Background graded, subject clean | Original clip underneath, graded; matted cutout on top, clean |
-| One region of the subject graded | Two copies of the cutout — clean underneath, graded copy on top clipped to the region |
-
-Two rules that are easy to get wrong:
-
-- **Use the original clip as the background plate, not a subject-removed
-  plate.** A subject-removed plate is a hole where the subject was, and a
-  feathered cutout composited over it produces a dark rim.
-- **If your cutout ships premultiplied alpha**, the browser composites it as
-  straight and edge pixels get multiplied twice, giving a black outline. Rebuild
-  it from the original plus its matte:
-  `ffmpeg -i clip.mp4 -i matte.mp4 -filter_complex "[1:v]format=gray[m];[0:v][m]alphamerge" -c:v libvpx-vp9 out.webm`
-
-### Worked Example: Redacting a Face
-
-Only the face is pixelated. The rest of the subject and the entire room are
-untouched. Three layers, and the region comes from `clip-path` on the third:
-
-```html index.html
-<div class="band">
-  <!-- 1. the room, clean -->
-  <video src="media/room.mp4" muted
-         data-start="0" data-duration="4" data-track-index="2"></video>
-
-  <!-- 2. the subject, clean -->
-  <video src="media/subject.webm" muted class="fg"
-         data-start="0" data-duration="4" data-track-index="3"></video>
+The agent can inspect the current capability contract and analyze a local
+source before changing it:
 
-  <!-- 3. the same subject, graded, clipped to the head -->
-  <video src="media/subject.webm" muted class="fx"
-         data-start="0" data-duration="4" data-track-index="4"
-         style="clip-path: ellipse(9.8% 15.5% at 50.7% 14.5%)"
-         data-color-grading='{"intensity":1,"effects":{"pixelate":0.5}}'></video>
-</div>
-```
-
-```css
-.band .fg { z-index: 2; }
-.band .fx { z-index: 3; }
-```
-
-Everything outside the clip falls through to the clean copy beneath. Because the
-graded layer *is* the cutout, the ellipse can overshoot the head without
-touching the room — there is nothing outside the silhouette to paint — so size
-it generously rather than tightly around the features.
-
-Pixelate preserves alpha, so the block grid clips to the silhouette instead of
-filling a rectangle.
-
-<Warning>
-  A fixed `clip-path` is only valid for footage where the subject barely moves.
-  Measure before relying on it. Anything with real subject movement needs a
-  tracked matte produced outside HyperFrames — there is no tracking in the
-  grading pipeline.
-</Warning>
-
-The prompt that produces the composition above:
-
-```text
-Take room.mp4 and its matted cutout subject.webm and build a 4-second
-1920x1080 composition that redacts only the subject's face.
-
-Three stacked layers inside one band, all playing the same 4 seconds:
-  1. room.mp4, no grading at all
-  2. subject.webm, no grading at all
-  3. subject.webm again, on top, carrying the grade
-
-Layer 3 is the only graded element: pixelate at 0.5, held constant for the
-whole shot — no ramp and no fade-up. A redaction that animates on reads as an
-effect; one that is simply on reads as policy. Mid strength should leave a
-recognisable human shape without a readable face.
-
-Limit layer 3 to the head with a CSS clip-path ellipse. Do not try to do this
-with the grading payload — it has no spatial masking. Size the ellipse
-generously so it takes in the hairline, ears, and jaw rather than sitting tight
-on the features; it can overshoot the head safely, because outside the
-silhouette the cutout is transparent and there is nothing to paint.
-
-Use the original room clip as the background plate rather than a
-subject-removed plate, and if the cutout has premultiplied alpha, rebuild it
-with ffmpeg alphamerge first so the edges do not come out with a black rim.
-```
-
-## Custom LUTs
-
-HyperFrames supports project-local 3D `.cube` LUTs:
-
-```json data-color-grading
-{
-  "lut": {
-    "src": "assets/luts/product-look.cube",
-    "intensity": 0.7
-  }
-}
+```bash
+npx hyperframes media-treatment --capabilities --json
+npx hyperframes media-treatment --selector '#interview' --analyze --json
 ```
 
-- 3D `.cube` LUTs up to `LUT_3D_SIZE 64` are supported.
-- 1D and mixed 1D+3D `.cube` files are not supported.
-- Common `DOMAIN_MIN`, `DOMAIN_MAX`, and DaVinci/IRIDAS-style
-  `LUT_3D_INPUT_RANGE` headers are supported.
-- HyperFrames does not bundle third-party LUT packs.
-- A LUT is only correct when its expected input color space matches the source.
-- Rec.709 creative LUTs are the safest current workflow.
-- Camera LOG conversion LUTs can be loaded, but HyperFrames does not identify
-  camera profiles or apply ACES/OCIO input transforms automatically.
-
-Never paste a `.cube` body into an agent prompt. LUT files commonly contain
-tens of thousands of numeric rows. Keep the file local and use metadata,
-validation, and rendered comparisons to evaluate it.
+For source-sensitive prompts and worked A/B examples, continue to
+[Color grading and film effects](/prompting/color-grading).
 
-## Support Matrix
+## Reuse a grade carefully
 
-| Source or workflow | Status | What to expect |
-| --- | --- | --- |
-| 1080p SDR video | Supported | Recommended default path |
-| 4K SDR video or image | Supported | Higher preview/render cost; output resolution still follows the composition |
-| iPhone SDR video | Supported | Treated as normal browser-decoded SDR media |
-| iPhone HDR, HLG, or Dolby Vision-style upload | Partial | Studio can show an SDR shader preview, but native HDR delivery bypasses the SDR treatment for native HDR source pixels |
-| HDR delivery render | Separate workflow | The native HDR compositor preserves HDR source pixels and does not apply this SDR grading/effects pipeline to native HDR layers |
-| LOG camera footage | Partial | Requires a known matching transform/LUT; no automatic camera profile management |
-| Full-scene grade including DOM/text | Not supported | Current grading targets individual media elements |
-| Face or region tracking | Not supported | No masks or tracking in the contract. Isolate the region as its own layer — see [Limiting a Grade to Part of the Frame](#limiting-a-grade-to-part-of-the-frame) |
-| Remote media | Partial | Requires compatible CORS headers; project-local assets are reliable |
-| ACES/OCIO finishing | Not supported | Outside the current browser shader pipeline |
+In Studio, use **Copy grade to** for other media in the current file or project.
+Treat the copy as a starting point and inspect each source.
 
-## Render and Performance
+Project-wide copy rejects project-relative LUT paths because the same path can
+resolve differently from another composition. Use a project-root path, a data
+URL, or copy only within the current file.
 
-The runtime creates a sibling WebGL canvas, uploads the current image/video
-frame as a texture, applies the same grading contract used by Studio, and hides
-the native source after a shader frame is ready. During final rendering,
-HyperFrames injects exact video frames and waits for the grading runtime to
-redraw before capture.
+## Use LUTs with known intent
 
-That render-parity statement applies to SDR output. In the native HDR render
-path, HyperFrames keeps HDR source pixels out of the SDR DOM capture and
-composites them separately at higher bit depth. The current SDR grading canvas
-is therefore not applied to native HDR layers. Convert or tone-map the source to
-SDR first when these grading controls must appear in the result, or use
-[HDR Rendering](/guides/hdr) to preserve the untreated HDR source.
+Import a project-local 3D `.cube` LUT only when you know the look or conversion
+it expects. HyperFrames does not identify camera profiles or apply an automatic
+ACES/OCIO workflow.
 
-For 4K output, follow [4K Rendering](/guides/4k-rendering). A 1080p source does
-not gain new detail merely because the composition is rendered at 4K.
+A creative Rec.709 LUT is the safest normal path. LOG or HDR footage requires a
+known source transform.
 
-When animating a graded media layer's opacity, animate a wrapper rather than the
-`<video>` itself. The visible pixels are drawn by the sibling grading canvas,
-so wrapper opacity keeps the media and canvas together.
 
-Project-local media is the safest path. Remote media must provide compatible
-CORS headers and should use `crossorigin="anonymous"` when pixel access is
-required.
+## Current limits
 
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Media Effects" icon="wand-magic-sparkles" href="/guides/media-effects">
-    Apply and animate shader-based optical, retro, print, and art treatments.
-  </Card>
-  <Card title="Media Overlays" icon="layer-group" href="/guides/media-overlays">
-    Add editable HUD, flash, light-leak, and freeze-frame composition layers.
-  </Card>
-  <Card title="HDR Rendering" icon="sun" href="/guides/hdr">
-    Render HDR10 outputs and understand the boundary with SDR grading.
-  </Card>
-  <Card title="4K Rendering" icon="up-right-and-down-left-from-center" href="/guides/4k-rendering">
-    Render at 4K and understand source-versus-output resolution.
-  </Card>
-</CardGroup>
+| Source or workflow | Status |
+| --- | --- |
+| SDR image or video | Supported |
+| 4K SDR media | Supported with higher preview and render cost |
+| iPhone HDR, HLG, or Dolby Vision-style media | Studio can show an SDR preview; native HDR delivery is a separate path |
+| LOG footage | Requires a known matching transform or LUT |
+| Full-scene grade including HTML text | Not supported; grading targets individual media elements |
+| Face or region tracking | Not supported |
+| Remote media | Requires compatible CORS headers |
+| ACES/OCIO finishing | Outside the current browser shader pipeline |
+
+Continue to [Media effects](/guides/media-effects) for blur, bloom, retro,
+print, glitch, and art treatments. Use [HDR rendering](/guides/hdr) when the
+final delivery must remain HDR.
+
+<Card title="Implement a grade in HTML" icon="code" href="/reference/color-grading">
+  Persist a grade, animate supported properties, or isolate a graded region.
+</Card>
+
+## Related topics
+
+- [Apply media effects](/guides/media-effects)
+- [Use images and video](/guides/video-components)
+- [Deliver an HDR render](/guides/hdr)
diff --git a/docs/guides/deploy.mdx b/docs/guides/deploy.mdx
index 711f146d73..60f99a4ce7 100644
--- a/docs/guides/deploy.mdx
+++ b/docs/guides/deploy.mdx
@@ -1,184 +1,109 @@
 ---
-title: Deploy
-description: "Run a Hyperframes preview + render API in the cloud from an official template."
+title: "Deploy a preview and render API"
+sidebarTitle: "Hosted templates"
+description: "Start from an official Vercel, Cloudflare, or Modal template when you need a hosted preview and MP4 render endpoint."
 ---
 
-Hyperframes ships three official deployment templates that wrap a composition in a small web app: an in-browser preview and a `/api/render` endpoint that produces an MP4 server-side. All are open source, Apache-2.0 — Vercel and Cloudflare deploy from a single button, Modal from a single `modal deploy`.
+HyperFrames has three official hosting templates. Each one previews a bundled
+composition in `<hyperframes-player>` and renders it to MP4 on server-side
+Chrome and FFmpeg.
 
-| Template | Compute | Storage | Deploy |
-|----------|---------|---------|--------|
-| [Vercel](https://github.com/heygen-com/hyperframes-vercel-template) | [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) (Firecracker microVM) | [Vercel Blob](https://vercel.com/docs/vercel-blob) | [vercel.com/templates/ai/hyperframes-on-vercel](https://vercel.com/templates/ai/hyperframes-on-vercel) |
-| [Cloudflare](https://github.com/heygen-com/hyperframes-cloudflare-template) | [Cloudflare Containers](https://developers.cloudflare.com/containers/) (Workers + Durable Object) | [R2](https://developers.cloudflare.com/r2/) | One-click button in the repo README |
-| [Modal](https://github.com/heygen-com/hyperframes-modal-template) | [Modal Functions](https://modal.com/docs/guide/webhooks) (serverless containers, scale-to-zero) | [Modal Volume](https://modal.com/docs/guide/volumes) | `modal deploy src/app.py` |
+Use these templates for a small hosted application. For managed rendering,
+distributed infrastructure, or a Node backend, start with
+[Choose a rendering path](/deploy/overview).
 
-All three templates use the same shape:
+| Template | Rendering runtime | Output storage | Best fit |
+| --- | --- | --- | --- |
+| [Vercel](https://github.com/heygen-com/hyperframes-vercel-template) | Vercel Sandbox | Vercel Blob | A Next.js application already deployed on Vercel |
+| [Cloudflare](https://github.com/heygen-com/hyperframes-cloudflare-template) | Cloudflare Container | R2 | A Workers application that needs a containerized renderer |
+| [Modal](https://github.com/heygen-com/hyperframes-modal-template) | Spawned Modal Function | Modal Volume | A Python service with render jobs that run outside the web request |
 
-- **Preview** the bundled `ui-3d-reveal` composition in the browser via the [`<hyperframes-player>`](/packages/player) web component.
-- **Render** to MP4 by POSTing to `/api/render`. The handler ships the composition to a sandboxed runtime that has Chromium, FFmpeg, and `hyperframes` pre-installed, then streams the MP4 back to storage and returns a URL.
-- **Author locally**, deploy the preview + render API. Compositions are still built on your machine with `npx hyperframes init`, then dropped into the template's compositions directory.
+## Vercel
 
-## Choosing a template
+The Vercel template is a Next.js application. Its `/api/render` route restores
+a prepared Sandbox, runs `hyperframes render`, uploads the MP4 to Blob, and
+returns a public URL.
 
-<Tabs>
-  <Tab title="Vercel">
-    Pick this if you already deploy on Vercel, want zero-config Blob storage, or want to reuse Vercel's CI/preview environments.
+[Deploy the Vercel template](https://vercel.com/new/clone?demo-title=HyperFrames+on+Vercel&demo-description=Preview+HTML+video+compositions+in+the+browser+and+render+MP4s+server-side+on+Vercel+Sandbox.&demo-image=https%3A%2F%2Fraw.githubusercontent.com%2Fheygen-com%2Fhyperframes-vercel-template%2Fmain%2Fdocs%2Fpreview.png&demo-url=https%3A%2F%2Fhyperframes-on-vercel.vercel.app&from=templates&project-name=hyperframes-on-vercel&repository-name=hyperframes-on-vercel&repository-url=https%3A%2F%2Fgithub.com%2Fheygen-com%2Fhyperframes-vercel-template&stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D)
 
-    [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fheygen-com%2Fhyperframes-vercel-template&stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D)
+Deployment provisions the Blob store. Sandbox access uses Vercel's runtime
+identity. Follow the repository README for current account requirements and
+platform limits.
 
-    **What you get**
+## Cloudflare
 
-    - A Next.js app with `<hyperframes-player>` preview and a `POST /api/render` route.
-    - A pre-baked Vercel Sandbox snapshot built during `next build` — cold renders skip the Chromium/FFmpeg install and restore from snapshot in ~100 ms.
-    - A Vercel Blob store provisioned automatically on deploy. `BLOB_READ_WRITE_TOKEN` is injected for you.
+The Cloudflare template is a TanStack Start application on Workers. A
+`RenderContainer` Durable Object runs the renderer and streams the result to
+R2. The template also includes optional prompt-based generation with a user's
+own OpenRouter credential.
 
-    **Performance**
+[Deploy the Cloudflare template](https://deploy.workers.cloudflare.com/?url=https://github.com/heygen-com/hyperframes-cloudflare-template)
 
-    Renders run on `standard-4` (4 vCPU). With `--workers auto`, three parallel Chrome workers cut render time meaningfully vs. single-worker. Concrete render time depends on composition length, complexity, and asset size.
+Cloudflare Containers require a Workers Paid plan. Disable the optional AI
+generation surface before hosting a public demo unless you intend visitors to
+submit their own compositions.
 
-    **Pricing**
+## Modal
 
-    Vercel Pro plans include Sandbox credit each month. See [Vercel Sandbox pricing](https://vercel.com/docs/vercel-sandbox/pricing) for current per-vCPU and per-GB rates and the up-to-date credit allowance.
+The Modal template exposes a FastAPI application. `POST /api/render` starts a
+separate render function and returns a call ID; the browser polls until the MP4
+is available from a Modal Volume.
 
-    <Note>
-      Vercel Functions cap at 300s and a 50 MB compressed bundle, which can't fit Chromium + FFmpeg. The template uses Vercel Sandbox specifically because it's the purpose-built primitive for this workload — up to 5 hours of runtime and up to 8 vCPUs per render.
-    </Note>
-  </Tab>
-  <Tab title="Cloudflare">
-    Pick this if you're already on Cloudflare Workers, want R2's free egress, or want full control over the renderer image.
-
-    [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/heygen-com/hyperframes-cloudflare-template)
-
-    **What you get**
-
-    - A Worker that serves preview HTML and forwards `/api/render` requests to a `RenderContainer` Durable Object.
-    - A pre-built OCI container image with Chromium + FFmpeg + `hyperframes` baked in — no install at request time.
-    - An R2 bucket (`hyperframes-renders`) provisioned automatically on deploy.
-
-    **Performance**
-
-    Renders run on `standard-4` (4 vCPU, 12 GiB). With `--workers auto`, three parallel Chrome workers cut render time meaningfully vs. single-worker. Container instances sleep after 10 minutes of inactivity, so the next request after a quiet period pays a cold-start penalty.
-
-    **Pricing**
-
-    Cloudflare Containers bills per-10ms for memory, CPU, and disk; R2 storage has no egress within Cloudflare's network. Requires a [Workers Paid](https://developers.cloudflare.com/workers/platform/pricing/) plan. See [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/) and [R2 pricing](https://developers.cloudflare.com/r2/pricing/) for current rates.
-
-    <Note>
-      Cloudflare's hosted [Browser Rendering](https://developers.cloudflare.com/browser-rendering/) API can't install FFmpeg — that's why the template uses Cloudflare Containers, which gives you a real OCI container in a Worker-bound Durable Object with up to 4 vCPUs and 12 GiB RAM.
-    </Note>
-  </Tab>
-  <Tab title="Modal">
-    Pick this if you already run on Modal, want containers that scale to zero with per-second billing, or want the render to run as a spawned function decoupled from the request.
-
-    Modal deploys from the CLI rather than a button:
-
-    ```bash Terminal
-    uv sync
-    source .venv/bin/activate
-    modal setup                 # one-time auth
-    modal deploy src/app.py
-    ```
-
-    **What you get**
-
-    - A FastAPI app (`@modal.asgi_app`) that serves the `<hyperframes-player>` preview and a `POST /api/render` route.
-    - A Modal image with Node.js 22, Python 3.12, FFmpeg, `hyperframes`, and `chrome-headless-shell` baked in at build time — no install at request time.
-    - A Modal Volume (`hyperframes-renders`) that persists the MP4, served back from the `/renders/:name` endpoint.
-
-    **Performance**
-
-    First deploy takes ~2 min to build the image; subsequent deploys are ~2s. Renders cold-boot in ~1s and containers scale to zero when idle. With `--workers auto`, three parallel Chrome workers cut render time (GPU is disabled via `--no-browser-gpu`). A 12s 1080p30 composition renders in roughly 10–90s depending on complexity.
-
-    **Pricing**
-
-    You pay per second of render time and nothing while idle, since containers scale to zero. See [Modal pricing](https://modal.com/pricing) for current per-CPU and per-GB rates.
-
-    <Note>
-      Modal web endpoints cap at 150s per request, so `POST /api/render` returns a `call_id` immediately and the render runs in a spawned Modal Function (up to 15 min, `timeout=900`). Poll `GET /api/render/:id` — it returns `202` while the render is still running, then the finished MP4.
-    </Note>
-  </Tab>
-</Tabs>
-
-## Architecture
-
-All three templates follow the same flow: the browser plays a preview locally, then POSTs to a render endpoint that delegates to a sandboxed runtime with Chromium + FFmpeg.
-
-```
- Browser                    Edge / Function              Sandboxed renderer
-┌──────────────────┐       ┌────────────────────┐       ┌──────────────────────────┐
-│ <hyperframes-    │ ────▶ │ /api/render        │ ────▶ │ hyperframes render       │
-│  player>         │       │  ship composition  │       │  (Chromium + FFmpeg,     │
-│ preview iframe   │       │  → renderer        │       │   pre-installed)         │
-│                  │ ◀──── │  ← stream MP4      │ ◀──── │                          │
-│                  │  url  │  → upload to blob  │  mp4  │                          │
-└──────────────────┘       └────────────────────┘       └──────────────────────────┘
-                                    │
-                                    └─▶ Vercel Blob / Cloudflare R2 / Modal Volume
+```bash
+uv sync
+source .venv/bin/activate
+modal setup
+modal deploy src/app.py
 ```
 
-The key cost-saver in all three templates is **pre-baking the renderer**. Installing Chromium system libraries plus `chrome-headless-shell` takes 30–60s, which would dominate every cold render. Vercel's template snapshots the sandbox at build time; Cloudflare's and Modal's templates bake everything into the container image. All restore in milliseconds and let you spend the entire request budget on actual rendering.
+## Use your own composition
 
-## Swapping the composition
+Author and check the project locally first:
 
-All three templates ship with one bundled composition (`ui-3d-reveal`). To use your own:
-
-<Steps>
-  <Step title="Author locally">
-    Compositions are HTML — author them on your machine with the [CLI](/packages/cli):
-
-    ```bash Terminal
-    npx hyperframes init my-video
-    cd my-video
-    npx hyperframes preview
-    ```
-  </Step>
-  <Step title="Drop the bundle into the template">
-    Copy your composition into the template's compositions directory — `public/compositions/<your-name>/` for Vercel and Cloudflare, `compositions/<your-name>/` for Modal.
-  </Step>
-  <Step title="Point the template at it">
-    - **Vercel**: edit `PREVIEW_COMPOSITION_DIR` at the top of `lib/preview.ts` and the dimensions in `app/page.tsx` if it isn't 1920×1080.
-    - **Cloudflare**: set `PREVIEW_COMPOSITION_DIR=compositions/<your-name>` when running `npm run deploy`, or edit the default in `scripts/build.mjs`. Update player dimensions in `public/index.html` if needed.
-    - **Modal**: set `PREVIEW_COMPOSITION = "<your-name>"` in `src/app.py`. Update the `<hyperframes-player>` dimensions in `web/index.html` if it isn't 1920×1080.
-  </Step>
-  <Step title="Deploy">
-    ```bash Terminal
-    # Vercel
-    vercel deploy
+```bash
+npx hyperframes init my-video
+cd my-video
+npx hyperframes preview
+npx hyperframes check
+```
 
-    # Cloudflare
-    npm run deploy
+Then replace the bundled composition in the selected template:
 
-    # Modal
-    modal deploy src/app.py
-    ```
-  </Step>
-</Steps>
+| Template | Composition folder | Select the composition |
+| --- | --- | --- |
+| Vercel | `public/compositions/<name>/` | Update `PREVIEW_COMPOSITION_DIR` in `lib/preview.ts` |
+| Cloudflare | `public/compositions/<name>/` | Set `PREVIEW_COMPOSITION_DIR=compositions/<name>` when building or deploying |
+| Modal | `compositions/<name>/` | Update `PREVIEW_COMPOSITION` in `src/app.py` |
 
-## When to use a template vs. roll your own
+If the authored canvas is not 1920×1080, also update the player dimensions in
+the template. Each repository README names the current file.
 
-Templates are optimized for **a single render endpoint behind a preview UI**. They're the fastest way to get a hosted Hyperframes render API running. If you need:
+## Before exposing the endpoint
 
-- A **render queue** with retries, deduplication, or priorities — start from a template, then add your own queue (e.g. Vercel Queues, Cloudflare Queues, SQS).
-- **Multi-tenant rendering** with per-user composition uploads — start from a template, replace the bundled composition with a runtime-fetched one.
-- **Self-hosted** rendering — see the [Rendering guide](/guides/rendering) and run `hyperframes render --docker` on your own infrastructure.
+These repositories are working examples, not a complete multi-tenant render
+service. Add authentication, request limits, input validation, and cost controls
+before accepting public render requests. Add a queue when jobs need retries,
+priorities, or controlled concurrency.
 
-For everything else, the templates are the recommended starting point.
+For infrastructure designed around distributed jobs, use
+[AWS Lambda](/deploy/aws-lambda) or [Google Cloud Run](/deploy/gcp-cloud-run).
 
-## Next Steps
+## Source
 
-<CardGroup cols={2}>
-  <Card title="Rendering" icon="film" href="/guides/rendering">
-    Render compositions locally or in Docker
-  </Card>
-  <Card title="Player package" icon="play" href="/packages/player">
-    Embed `<hyperframes-player>` in any HTML page
+<CardGroup cols={3}>
+  <Card title="Vercel" icon="github" href="https://github.com/heygen-com/hyperframes-vercel-template">
+    Next.js, Sandbox, and Blob
   </Card>
-  <Card title="Vercel template" icon="github" href="https://github.com/heygen-com/hyperframes-vercel-template">
-    Source on GitHub
+  <Card title="Cloudflare" icon="github" href="https://github.com/heygen-com/hyperframes-cloudflare-template">
+    TanStack Start, Containers, and R2
   </Card>
-  <Card title="Cloudflare template" icon="github" href="https://github.com/heygen-com/hyperframes-cloudflare-template">
-    Source on GitHub
-  </Card>
-  <Card title="Modal template" icon="github" href="https://github.com/heygen-com/hyperframes-modal-template">
-    Source on GitHub
+  <Card title="Modal" icon="github" href="https://github.com/heygen-com/hyperframes-modal-template">
+    FastAPI, spawned functions, and Volume storage
   </Card>
 </CardGroup>
+
+## Related topics
+
+- [Compare every rendering path](/deploy/overview)
+- [Deploy distributed rendering on AWS Lambda](/deploy/aws-lambda)
+- [Deploy distributed rendering on Google Cloud Run](/deploy/gcp-cloud-run)
diff --git a/docs/guides/feedback.mdx b/docs/guides/feedback.mdx
index 5d5a397119..3f3a7a1195 100644
--- a/docs/guides/feedback.mdx
+++ b/docs/guides/feedback.mdx
@@ -1,248 +1,77 @@
 ---
-title: Feedback Collection
-description: "How HyperFrames collects feedback, what data is collected, and how to opt out."
+title: "Share feedback"
+description: "Report a problem or tell the HyperFrames team what would make the product better."
 ---
 
-HyperFrames occasionally asks how likely you are to recommend the render experience or Studio. This page explains why we do it, when prompts appear, what data is collected, and how to disable them.
+Useful feedback explains the outcome you wanted and what stopped you from reaching it.
 
-## Why We Ask
+## Send feedback from the command line
 
-We use anonymous recommendation scores to understand whether the tool is actually working well — not just whether it runs without errors. A render that takes 10 minutes and produces a broken file counts as a success in logs but a failure in practice. The feedback prompt is the only signal we have for that gap.
-
-No account, email, or identity is tied to responses. Each installation generates a random UUID at setup; that is the only identifier.
-
-## How It Works
-
-### CLI — post-render prompt
-
-After a successful `hyperframes render`, a short prompt may appear:
-
-```
-  How likely are you to recommend HyperFrames? [0=not likely 10=extremely likely, enter to skip]
-  Any details? (enter to skip)
-```
-
-**When it shows:**
-
-- First ever successful render
-- Then every 15 renders after that (16th, 31st, 46th...)
-- At most once per process — re-renders in the same session don't trigger a second prompt
-- Automatically suppressed in quiet mode (`--quiet`), non-TTY shells, and CI environments
-
-The prompt has a **10-second auto-timeout** — if you don't respond, it silently disappears and the CLI continues normally.
-
-The render interval is configurable:
+From a HyperFrames project, run:
 
 ```bash
-# Show prompt every 5 renders instead of 15 (useful for testing)
-HYPERFRAMES_FEEDBACK_INTERVAL=5 hyperframes render --output out.mp4
+npx hyperframes feedback --rating 7 --comment "The render finished, but the captions were missing."
 ```
 
-### Studio — session feedback bar
-
-A thin 32px bar slides in at the bottom of the preview area periodically:
-
-- Never on the first session — only starting from the 10th
-- Then every 10 sessions (10th, 20th, 30th...)
-- Slides in 3 seconds after page load to avoid flash
-- Auto-dismisses after 20 seconds if ignored
-- After any interaction (dismiss or submit), the session counter resets — next prompt after 10 more sessions
-
-The session interval is configurable at build time:
-
-```
-VITE_HYPERFRAMES_FEEDBACK_INTERVAL=3
-```
-
-Invalid values (non-integer, zero, negative) fall back to the default.
-
-**Note:** Disabling CLI telemetry (`hyperframes telemetry disable`) does not suppress the Studio bar — Studio feedback is gated separately. The submitted data is still sent through the same anonymous PostHog pipeline, so the same privacy guarantees apply.
+The rating is from 0 to 10. The comment is optional, but a specific example is usually more useful than a score alone.
 
-### `hyperframes feedback` command
+## Report a reproducible bug
 
-You can submit feedback manually at any time:
+Use `--file-issue` when the project can be shared publicly:
 
 ```bash
-# Quick rating
-hyperframes feedback --rating 10
-
-# Rating with details
-hyperframes feedback --rating 7 --comment "render succeeded but GSAP timeline didn't animate text overlay"
-```
-
-| Flag | Description |
-|------|-------------|
-| `--rating` | Recommendation score, 0–10 (required) |
-| `--comment` | Optional free-text details |
-| `--file-issue` | Also open a pre-filled GitHub issue with a published minimal repro (opt-in) |
-| `--dir` | Project directory to publish as the repro (default: current directory) |
-| `--yes` | Skip the publish + file-issue consent prompt (for scripts) |
-
-This command collects a doctor summary automatically, flushes telemetry, and exits. It appears under the **Settings** group in `hyperframes --help`.
-
-### Filing a GitHub issue (`--file-issue`)
-
-When a render misbehaves, add `--file-issue` so maintainers can reproduce it:
-
-```bash
-hyperframes feedback --rating 3 --comment "GSAP timeline froze on seek" --file-issue
-```
-
-This is **opt-in** and **consented**. With `--file-issue` set, after the usual feedback is sent the CLI:
-
-1. Asks you to confirm (interactive) or requires `--yes` in non-interactive shells, because it will **publicly publish** the project at `--dir`.
-2. Publishes a minimal repro of the project and gets a public URL (the same upload as `hyperframes publish`).
-3. Opens your browser with a **pre-filled** GitHub issue draft, labelled `bug`, containing the rating, your comment, the public repro link, and the environment summary. It also prints the URL so you can copy it if no browser opens.
-
-The issue is **not auto-submitted**: you review and file it under your own GitHub account. There is no token, backend, or `gh` invocation; if publishing fails the issue still opens, just without a repro link.
-
-## Agent Runtimes
-
-When an AI agent is detected, HyperFrames **skips the interactive readline prompt** and prints a structured hint instead:
-
-```
-  [hyperframes] Agent feedback: hyperframes feedback --rating <0-10> --comment "..."
+npx hyperframes feedback \
+  --rating 3 \
+  --comment "The timeline freezes when this GSAP scene is opened." \
+  --file-issue
 ```
 
-Agents can then submit feedback using the `hyperframes feedback` command above.
+<Warning>
+  This flow asks for confirmation before uploading the selected project directory to a public URL.
+  It is not a privacy scrubber and may include most of that project. The safest approach is to copy
+  only the files needed to reproduce the bug into a separate clean folder, inspect it, then pass
+  that folder with `--dir`. Never publish private media, customer data, credentials, or secrets.
+</Warning>
 
-The same cadence gate applies: the hint only appears on the first render, then every 15th.
+HyperFrames then opens a prepared GitHub issue in your browser. Review it before submitting; the issue is not posted automatically.
 
-**Detected agents and their markers:**
+You can also [open a GitHub issue directly](https://github.com/heygen-com/hyperframes/issues).
 
-| Agent | Environment markers |
-|-------|---------------------|
-| Claude Code | `CLAUDECODE` present, or `CLAUDE_CODE_ENTRYPOINT` present |
-| Codex | `CODEX_THREAD_ID`, `CODEX_CI`, or `CODEX_SANDBOX_NETWORK_DISABLED` present |
-| Cursor | `TERM_PROGRAM` equals `cursor` |
-| GitHub Copilot Agent | `GITHUB_ACTIONS` equals `true` and (`COPILOT_AGENT_ID` present or `RUNNER_NAME` equals `Copilot`) |
-| Replit | `REPL_ID` or `REPLIT_USER` present |
-| Hermes | `HERMES_QUIET` present |
-| openclaw | `OPENCLAW_STATE_DIR` or `OPENCLAW_CONFIG_PATH` present |
-| Pi | `PI_CODING_AGENT` present |
+## Include enough evidence
 
-Only the existence (or in some cases the value) of these variables is checked — API keys and secrets that happen to share a prefix are never read.
+A useful report includes:
 
-## What Is Collected
+- what you were trying to make;
+- the action or command you used;
+- what you expected;
+- what happened instead;
+- the exact error message;
+- whether it happens every time;
+- a screenshot or short recording for a visual problem;
+- a small project when it is safe to share.
 
-### CLI feedback
+Do not include API keys, access tokens, credentials, private media, or customer information.
 
-Event: `cli_render_feedback`
+## About feedback data
 
-| Field | Value |
-|-------|-------|
-| `rating` | Raw rating (0–10) |
-| `rating_scale` | `10` for the current recommendation scale |
-| `comment` | Free-text comment (only when provided) |
-| `render_duration_ms` | Time the render took in milliseconds |
-| `doctor_summary` | System context (see below) |
+HyperFrames may occasionally show a short rating prompt after a render or during a Studio session. You can ignore or dismiss it.
 
-The `doctor_summary` is a compact string with environment context — included automatically so you don't need to run `hyperframes doctor` when reporting a problem:
+Feedback can include the rating, an optional comment, and basic environment information used to understand the problem. It does not include your composition HTML, video files, project names, file paths, or environment-variable values.
 
-```
-os=darwin/arm64 node=v22.11.0 cpu=10cores mem=32GB ffmpeg=yes
-```
-
-It may also include `wsl` or sandbox runtime flags when those environments are detected.
-
-### Studio feedback
-
-Event: `studio_feedback`
-
-| Field | Value |
-|-------|-------|
-| `rating` | Raw rating (0–10) |
-| `rating_scale` | `10` for the current recommendation scale |
-| `comment` | Free-text comment (only when provided) |
-| `source` | `studio` |
-| `doctor_summary` | Browser context (platform, screen, CPU cores, device memory, network type) |
-
-## What Is NOT Collected
-
-- File paths or project names
-- Composition content, HTML, or video files
-- Environment variable values
-- Personally identifiable information
-- IP addresses or precise location
-
-Feedback is anonymous. Each installation has a random UUID (`anonymousId`) — there is no account, login, or email association.
-
-## Rating Scale Compatibility
-
-New feedback stores the raw integer together with `rating_scale: 10`.
-
-Feedback collected before this change remains on the historical 1–5 satisfaction scale. Historical events have no `rating_scale`, and historical Slack or GitHub records retain their `/5` denominator. Consumers must treat a missing scale as legacy 1–5 data and must not reinterpret those scores as NPS.
-
-## Config File
-
-The CLI persists feedback state in `~/.hyperframes/config.json`:
-
-```json
-{
-  "telemetryEnabled": true,
-  "anonymousId": "a1b2c3d4-...",
-  "telemetryNoticeShown": true,
-  "commandCount": 47,
-  "renderSuccessCount": 14,
-  "lastFeedbackPromptAt": 1
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `renderSuccessCount` | Total successful renders across all sessions |
-| `lastFeedbackPromptAt` | The `renderSuccessCount` value when the prompt last appeared — used to compute whether 15 renders have passed |
-
-Studio stores the equivalent state in `localStorage` under the `hyperframes-studio:` prefix.
-
-## Opting Out
-
-### CLI — disable telemetry entirely
-
-Disabling telemetry suppresses the CLI feedback prompt, all other CLI usage tracking, and enrolment in any [canary rollout](/contributing/canary-rollouts) — an install that reports nothing is never picked for a staged rollout:
+To turn off CLI telemetry:
 
 ```bash
-# Via CLI command (persisted to ~/.hyperframes/config.json)
-hyperframes telemetry disable
-
-# Or via environment variable (per-session)
-HYPERFRAMES_NO_TELEMETRY=1 hyperframes render --output out.mp4
-
-# Or via DO_NOT_TRACK (respects the global standard)
-DO_NOT_TRACK=1 hyperframes render --output out.mp4
-```
-
-Once disabled, the `hyperframes feedback` command will print `Telemetry is disabled. Feedback not sent.` and exit without sending anything.
-
-### CLI — suppress output without disabling telemetry
-
-```bash
-# Quiet mode: renders without any post-render output (including the feedback prompt)
-hyperframes render --quiet --output out.mp4
-```
-
-### CI environments
-
-The CLI feedback prompt is automatically suppressed when the `CI` environment variable is set (GitHub Actions, CircleCI, etc. set this by default).
-
-### Studio
-
-The Studio feedback bar is not affected by the CLI telemetry setting. To disable it at build time, set:
-
+npx hyperframes telemetry disable
 ```
-VITE_HYPERFRAMES_NO_FEEDBACK=1
-```
-
-When set to `"1"`, the bar never shows — `shouldShowFeedback()` returns `false` unconditionally regardless of session count or `localStorage` state.
 
-The session interval is still configurable independently:
+That also stops the feedback prompt and takes the install out of any
+[canary rollout](/contributing/canary-rollouts) — nothing that reports nothing
+is ever picked for a staged release.
 
-```
-VITE_HYPERFRAMES_FEEDBACK_INTERVAL=20
-```
+Studio feedback is controlled separately from the CLI setting.
 
-## Related
+## Related topics
 
-- [Telemetry](/packages/cli#telemetry) — full telemetry settings and what usage data is collected
-- [`hyperframes feedback`](/packages/cli#feedback) — CLI command reference
-- [Troubleshooting](/guides/troubleshooting) — if a prompt is blocking your pipeline unexpectedly
+- [Get unstuck](/help)
+- [Diagnose common project and render problems](/guides/troubleshooting)
+- [Search or open a GitHub issue](https://github.com/heygen-com/hyperframes/issues)
diff --git a/docs/guides/figma.mdx b/docs/guides/figma.mdx
index 6d180861ea..e2c45f6b2e 100644
--- a/docs/guides/figma.mdx
+++ b/docs/guides/figma.mdx
@@ -1,32 +1,38 @@
 ---
-title: Figma Import
+title: Figma integration
 description: "Bring Figma designs into HyperFrames — frozen assets, brand tokens, editable components, storyboard reconstruction, and Figma Motion timelines translated to GSAP."
 ---
 
-The work your designer already did in Figma — layout, color, type, motion — becomes the starting point of a composition instead of a thing to rebuild by hand. Point at a Figma URL; the artifact lands as a native HyperFrames piece: a frozen local file, a composition variable, editable HTML, or a paused GSAP timeline.
+Import the parts of a Figma design that should survive into the project: assets,
+brand values, editable components, motion, or storyboard states. HyperFrames
+stores the result locally so the render does not depend on Figma.
 
 ## What you can import
 
 | Capability | What you get | Surface |
 | --- | --- | --- |
 | **Static assets** | A frame/layer rendered to SVG/PNG/JPG/PDF, frozen under `.media/` | `hyperframes figma asset` |
-| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` (Enterprise) or the `/figma` skill via MCP (any plan) |
+| **Brand tokens** | Figma variables/styles as composition brand variables | `hyperframes figma tokens` or the `/figma` skill via a Figma connector |
 | **Components** | A frame as editable HTML with brand-linked colors | `hyperframes figma component` |
 | **Motion** | A Figma Motion timeline as an editable, paused GSAP timeline | `/figma` skill (agent, MCP) |
 | **Shaders** | A shader fill/effect as a frozen still or clip | `/figma` skill (agent, MCP) |
-| **Storyboards** | Scene frames reconstructed as motion — frames read as states, not slides | `/figma` skill (agent) |
+| **Storyboards** | Scene frames reconstructed as motion — frames read as states, not slides | `/figma` skill (agent; REST assets are enough) |
 
-Two transports, split by what Figma exposes: assets, tokens, and components run over the **REST API** (headless, works in CI, generous per-minute rate limits). Motion and shaders exist only on Figma's **MCP server**, so an agent drives those. Every path freezes files locally — **renders never call Figma**.
+Assets, tokens, and components use Figma's **REST API** and can run headlessly.
+Motion and shader data can come through a compatible **Figma connector**; if
+that surface is unavailable, provide a native export instead. Storyboard
+reconstruction uses ordinary frame exports plus the agent's analysis.
 
 ## One-time setup
 
-There are two credentials, and most people only need to set up one to start:
+Most people only need one connection:
 
 | You want to import… | Set up |
 | --- | --- |
 | A logo, image, or a whole frame as HTML (assets, components) | A **token** — Step A below |
 | Brand colors (tokens) | Either works, but on a non-Enterprise plan the **MCP connector** (Step B) gets you there in one click — the token path needs an Enterprise plan for this specific pull |
-| Motion, shaders, or a storyboard | The **MCP connector** only — no token, no setup beyond connecting it |
+| Motion or shaders | A compatible **Figma connector**, or a native export |
+| Storyboard frames | A token for frame exports; no connector is required |
 
 Do both if your project needs everything; each is independent, so it doesn't matter which you set up first.
 
@@ -52,15 +58,20 @@ Needed for anything you run from the `hyperframes figma` CLI.
     export FIGMA_TOKEN="figd_…"
     ```
 
-    Add the line to your shell profile or the project's `.env` so future sessions skip this step. The same token covers every Figma file your account can view.
+    Add the line to your shell profile or the project's `.env` so future
+    sessions skip this step. The token can read files that its Figma account
+    and scopes allow.
   </Step>
 </Steps>
 
-### Step B — Figma MCP connector (motion, shaders, storyboards — and an easier token-free path to brand colors)
+### Step B — Figma connector (motion, shaders, and a token-free path to brand colors)
 
 No token, no scopes to pick — connect it once when your agent asks (a one-click OAuth) and it stays connected.
 
-This is also the easiest way to pull brand colors on **any** Figma plan, including free: the connector's variable-reading tool isn't Enterprise-gated, only rate-limited by plan — Starter/free caps at **6 calls/month**, a paid Full/Dev seat gets 200–600/day. Fine for an occasional brand pull; not for iterating call-by-call.
+This is also a convenient way to read the brand values used by a selection when
+the REST variables endpoint is unavailable on your plan. Connector
+availability and usage limits depend on Figma's current plan and client rules,
+so the agent should batch requests and cache the result.
 
 ## Import an asset
 
@@ -85,7 +96,10 @@ imported image_007 → .media/images/image_007.svg
 hyperframes figma tokens KEY
 ```
 
-Reads the file's variables (or published styles), writes a `figma-tokens.json` sidecar plus a binding index, and prints entries for the composition's `data-composition-variables`. Every scene that references a brand role — instead of a hard-coded hex — is on-brand automatically, and stays on-brand when the file changes.
+Reads the file's variables (or published style metadata), writes a
+`figma-tokens.json` sidecar plus a binding index, and prints entries for the
+composition's `data-composition-variables`. Scenes that reference those roles
+use the same local values. Run `tokens` again when the Figma file changes.
 
 <Tip>
 Import tokens **before** components. That's what lets an imported component's colors link to your brand variables instead of baking duplicate literals.
@@ -112,7 +126,9 @@ These run through the `/figma` agent skill:
 
 - **Motion** — a Figma Motion timeline (keyframes, easing, repeats) translates structurally into a paused, finite GSAP timeline registered on `window.__timelines`, seekable frame-by-frame like any hand-authored animation, and editable afterward. Tracks that can't translate faithfully fall back to a baked video clip — the agent tells you which path it took and why.
 - **Shaders** — Figma's export path doesn't execute shaders, so the default is a native Figma export (PNG or Motion MP4) imported as an asset/clip.
-- **Storyboards** — a section of scene frames is decoded, not slideshowed: frames sharing an element are treated as that element's keyframes over time, diffed into element chains and tweened, with text under the strip read as director notes. When the frames depict one product UI in successive states, the agent escalates further — rebuilds the UI as live DOM and performs each frame delta as a real interaction (cursor, click, navigation), so the result reads as a continuous screen recording. See the `/figma` skill for the full grammar.
+- **Storyboards** — a section of scene frames is decoded, not slideshowed:
+  repeated elements become continuity clues and the differences between frames
+  become motion or interaction. A connector is not required for this path.
 
 ## Provenance and refresh
 
@@ -129,3 +145,9 @@ Every import records where it came from (`fileKey`, `nodeId`, `version`) in `.me
 | `RATE_LIMITED` (429) | Figma's per-minute limit | The client retries with backoff automatically (honoring `Retry-After`); if it still surfaces, wait a minute or batch fewer nodes |
 | "Render timeout" on batch export | Too many large frames in one `/v1/images` call | Chunk to ~4 ids per call |
 | `ref has no node id` | Link points at a file, not a node | Copy the link with `?node-id=…` (right-click layer → Copy link) |
+
+## Related topics
+
+- [Bring a design into a project](/guides/design-tools)
+- [Work on the imported project in Studio](/studio)
+- [Manage project media](/guides/media)
diff --git a/docs/guides/gsap-animation.mdx b/docs/guides/gsap-animation.mdx
index 591cb8c28c..32dc2c4dd6 100644
--- a/docs/guides/gsap-animation.mdx
+++ b/docs/guides/gsap-animation.mdx
@@ -1,134 +1,116 @@
 ---
-title: GSAP Animation
-description: "Add animations to your Hyperframes compositions with GSAP."
+title: "Animate with GSAP"
+sidebarTitle: "GSAP animation"
+description: "Create a paused timeline that HyperFrames can seek to any frame."
 ---
 
-Hyperframes uses [GSAP](https://gsap.com/) for animation. Timelines are paused and controlled by the runtime — you define the animations, the framework handles playback. For background on how animation runtimes plug into Hyperframes, see [Frame Adapters](/concepts/frame-adapters).
-
-## Setup
-
-Include GSAP and create a paused timeline:
-
-```html index.html
-<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
-<script>
-  // 1. Create a paused timeline — the framework controls playback
-  const tl = gsap.timeline({ paused: true });
-
-  // 2. Add animations using the position parameter (3rd arg) for absolute timing
-  tl.to("#title", { opacity: 1, duration: 0.5 }, 0);
-
-  // 3. Initialize the global timelines registry (if not already present)
-  window.__timelines = window.__timelines || {};
-
-  // 4. Register the timeline using the data-composition-id as the key
-  window.__timelines["root"] = tl;
-</script>
+GSAP is the primary animation runtime for HyperFrames compositions. You author the motion; HyperFrames owns the playhead.
+
+## Minimal contract
+
+Give the composition a finite duration, create a paused timeline, and register it under the composition ID:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="intro"
+      data-start="0"
+      data-duration="3"
+      data-width="1920"
+      data-height="1080"
+    >
+      <h1 id="title" class="clip" data-start="0" data-duration="3" data-track-index="0">
+        HyperFrames
+      </h1>
+    </div>
+
+    <script>
+      const timeline = gsap.timeline({ paused: true });
+
+      timeline.fromTo(
+        "#title",
+        { opacity: 0, y: 32 },
+        { opacity: 1, y: 0, duration: 0.6, ease: "power3.out" },
+        0,
+      );
+
+      window.__timelines = window.__timelines || {};
+      window.__timelines.intro = timeline;
+    </script>
+  </body>
+</html>
 ```
 
-<Note>
-  The key you use in `window.__timelines` must match the `data-composition-id` attribute on your composition's root element. See [Compositions](/concepts/compositions) for how the root element is structured.
-</Note>
-
-## Key Rules
+The registry key must match `data-composition-id`.
 
-1. **Always create timelines with `{ paused: true }`** — the framework controls playback via [deterministic seeking](/concepts/determinism)
-2. **Register timelines on `window.__timelines`** with the [`data-composition-id`](/concepts/data-attributes#composition-attributes) as key
-3. **Use the position parameter** (3rd argument) for absolute timing: `tl.to(el, vars, 1.5)`
-4. **Only animate visual properties** — never control media playback in scripts
+## Rules that matter
 
-## Supported Methods
+1. Create the timeline with `{ paused: true }`.
+2. Register it on `window.__timelines`.
+3. Give important tweens an explicit position.
+4. Prefer `fromTo()` when both endpoints matter; it remains reliable after backward or random seeks.
+5. Animate transforms and opacity for movement. Avoid repeatedly animating layout properties such as `top`, `left`, `width`, or `height`.
+6. Let HyperFrames control clip visibility and media playback.
 
-| Method | Description |
-|--------|-------------|
-| `tl.to(target, vars, position)` | Animate to values |
-| `tl.from(target, vars, position)` | Animate from values |
-| `tl.fromTo(target, fromVars, toVars, position)` | Animate from/to values |
-| `tl.set(target, vars, position)` | Set values instantly |
+The normal timeline methods are `to()`, `from()`, `fromTo()`, and `set()`. GSAP supports many CSS properties, but the [HyperFrames animation skill](https://github.com/heygen-com/hyperframes/tree/main/skills/hyperframes-animation) contains the render-safe patterns used by agents.
 
-## Supported Properties
+## Duration
 
-`opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `color`, `backgroundColor`, and other CSS-animatable transform/color properties. Do **not** animate `visibility`, `width`, or `height` — these break deterministic rendering.
+An explicit root `data-duration` is the composition's render length:
 
-## Timeline Duration and Composition Duration
-
-A composition's duration equals its GSAP timeline duration. The two are directly linked:
-
-```javascript compositions/intro-anim.html
-// Your last animation ends at 3 seconds...
-tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
-tl.to("#title", { opacity: 0, duration: 1 }, 2);
-// ...so this composition is exactly 3 seconds long.
+```html
+<div data-composition-id="demo" data-duration="12"></div>
 ```
 
-If your composition contains a video clip that is 283 seconds long, but your last GSAP animation ends at 8 seconds, the composition will be only 8 seconds long and the video will be cut short. To extend the timeline to match the video:
+This is the clearest choice for a complete composition. If the root omits `data-duration`, HyperFrames can infer length from registered timelines and supported media after the page initializes.
 
-```javascript index.html
-// All your visual animations
-tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
-
-// Extend the timeline to 283 seconds to match the video length.
-// This adds a zero-duration tween at 283s without affecting any elements.
-tl.set({}, {}, 283);
-```
+Do not assume a long source video automatically extends a shorter explicit root duration. The authored duration is the output window.
 
-<Warning>
-  This is one of the most common mistakes in Hyperframes. If your video cuts off early, the timeline is too short. See [Common Mistakes: Composition Duration Shorter Than Video](/guides/common-mistakes) for more details.
-</Warning>
+## Media belongs to the runtime
 
-## What NOT to Do
+Do not play or seek media from the GSAP timeline:
 
-These patterns will break your composition or cause sync issues:
+```js
+// Do not do this.
+document.querySelector("video").play();
+document.querySelector("audio").currentTime = 5;
+```
 
-```javascript index.html
-// WRONG: Playing media in scripts — the framework owns media playback
-document.getElementById("el-video").play();
-document.getElementById("el-audio").currentTime = 5;
+Use media timing attributes instead. If a video needs to move or resize, animate a wrapper around it rather than the video element itself.
 
-// WRONG: Creating a non-paused timeline
-const tl = gsap.timeline(); // missing { paused: true }!
+## Nested compositions
 
-// WRONG: Animating dimensions directly on a <video> element
-tl.to("#el-video", { width: 500, height: 280 }, 5);
+Each nested composition owns and registers its own timeline. The parent decides when the nested scene appears through its host element:
 
-// WRONG: Manually nesting sub-timelines
-const masterTL = window.__timelines["root"];
-masterTL.add(window.__timelines["intro-anim"], 0);
+```html
+<div
+  data-composition-id="intro"
+  data-composition-src="compositions/intro.html"
+  data-start="2"
+  data-duration="4"
+></div>
 ```
 
-The framework automatically manages [media playback](/reference/html-schema#framework-managed-behavior), [clip lifecycle](/concepts/compositions#two-layers-primitives-and-scripts), and [sub-composition nesting](#sub-composition-timelines). Scripts that duplicate this behavior will conflict.
+Do not manually add the child timeline to the parent's GSAP timeline. HyperFrames maps the parent playhead into the nested scene.
 
-## Sub-Composition Timelines
+## Verify the motion
 
-Each [nested composition](/concepts/compositions#nested-compositions) registers its own timeline. The framework automatically nests sub-composition timelines into the parent based on [`data-start`](/concepts/data-attributes#timing-attributes):
+```bash
+npx hyperframes lint
+npx hyperframes check
+npx hyperframes snapshot --at 0,0.6,2.9
+```
 
-```javascript compositions/intro-anim.html
-// In compositions/intro-anim.html
-const tl = gsap.timeline({ paused: true });
-tl.from(".title", { opacity: 0, y: -50, duration: 1 });
-window.__timelines["intro-anim"] = tl;
+Check the first frame, the moving state, and the end state. A timeline that looks correct only during continuous browser playback may still fail when the renderer seeks directly to a frame.
 
-// DO NOT manually add sub-timelines to the master:
-// masterTL.add(window.__timelines["intro-anim"], 0); // UNNECESSARY
-```
+## Related topics
 
-<Warning>
-  Don't animate `width`, `height`, `top`, or `left` directly on `<video>` elements — this can cause the browser to stop rendering frames. Wrap the video in a `<div>` and animate the wrapper instead. See [Common Mistakes](/guides/common-mistakes) for a detailed explanation.
-</Warning>
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Compositions" icon="layer-group" href="/concepts/compositions">
-    Understand the building blocks that timelines animate
-  </Card>
-  <Card title="Frame Adapters" icon="plug" href="/concepts/frame-adapters">
-    Learn how GSAP plugs into the render pipeline
-  </Card>
-  <Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
-    Avoid pitfalls that break animations
-  </Card>
-  <Card title="HTML Schema Reference" icon="code" href="/reference/html-schema">
-    Full reference for composition attributes
-  </Card>
-</CardGroup>
+- [Edit animation and keyframes in Studio](/studio/animation)
+- [Understand deterministic rendering](/concepts/determinism)
+- [Use the HTML composition schema](/reference/html-schema)
diff --git a/docs/guides/hdr.mdx b/docs/guides/hdr.mdx
index 150e579af6..93e2d75d94 100644
--- a/docs/guides/hdr.mdx
+++ b/docs/guides/hdr.mdx
@@ -1,133 +1,27 @@
 ---
-title: HDR Rendering
-description: "Render compositions to HDR10 MP4 (BT.2020 PQ or HLG, 10-bit H.265) when sources contain HDR video or images."
+title: Render HDR video
+description: Preserve BT.2020 PQ or HLG sources in a 10-bit H.265 MP4.
 ---
 
-Hyperframes can render to HDR10 MP4 (H.265 10-bit, BT.2020) when your composition references HDR video or HDR still images. HDR is auto-detected by default from your media sources and falls back to SDR when none are present.
-
-<Note>
-  By default, Hyperframes probes your media and enables HDR only when HDR sources are present. Use `--hdr` to force HDR even without HDR sources, or `--sdr` to force SDR even when HDR sources are present.
-</Note>
-
-## Quickstart
-
-<Steps>
-  <Step title="Add an HDR source to your composition">
-    Hyperframes detects HDR from the source's color space metadata. The most reliable HDR sources are:
-
-    - **HDR video** tagged BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`) transfer
-    - **HDR still images** as 16-bit PNG with BT.2020 PQ encoding
-
-    See [Source Media](#source-media-requirements) for full details.
-  </Step>
-  <Step title="Render normally">
-    ```bash Terminal
-    npx hyperframes render --output output.mp4
-    ```
-
-    HDR output requires `--format mp4`. If Hyperframes detects HDR sources, it renders HDR automatically. If you also pass `--format mov` or `--format webm`, Hyperframes logs a warning and falls back to SDR.
-  </Step>
-  <Step title="Verify the output is HDR">
-    Use `ffprobe` to confirm the encoded stream carries HDR color tagging and HDR10 metadata:
-
-    ```bash Terminal
-    ffprobe -v error -show_streams output.mp4 | grep -E 'color_transfer|color_primaries|color_space'
-    ```
-
-    See [Verifying HDR output](#verifying-hdr-output) for what to look for.
-  </Step>
-</Steps>
-
-## How HDR Mode Works
-
-During render, the producer:
-
-<Steps>
-  <Step title="Probes every video and image source">
-    Runs `ffprobe` on each `<video>` and `<img>` source to read its color space (primaries, transfer function, matrix). This probe drives the default auto-detect behavior and is skipped only when you explicitly force SDR with `--sdr`.
-  </Step>
-  <Step title="Picks the dominant HDR transfer">
-    If any source uses PQ (`smpte2084`), the output uses **PQ**. Otherwise, if any source uses HLG (`arib-std-b67`), the output uses **HLG**. If no HDR sources are found, the render stays SDR.
-  </Step>
-  <Step title="Encodes to H.265 10-bit BT.2020">
-    The video encoder switches to `libx265` with `-pix_fmt yuv420p10le`, color tagging `colorprim=bt2020:transfer=<smpte2084|arib-std-b67>:colormatrix=bt2020nc`, and HDR10 static metadata (`master-display` and `max-cll`). Without that metadata, players (QuickTime, YouTube, HDR TVs) tone-map the stream as if it were SDR BT.2020 — which looks wrong.
-  </Step>
-  <Step title="Composites HDR sources natively, converts SDR overlays">
-    HDR videos and images are extracted as 16-bit linear-light pixels via FFmpeg, kept out of the DOM screenshot, and composited server-side at full bit depth. SDR DOM overlays (text, shapes, UI from your HTML) are converted from **sRGB** to **BT.2020** before being layered on top, so colors do not shift.
-  </Step>
-</Steps>
-
-## Source Media Requirements
-
-### HDR video
-
-Hyperframes recognizes HDR video from its `ffprobe` color space metadata:
-
-| Indicator | Recognized as HDR |
-|-----------|-------------------|
-| `color_primaries` contains `bt2020` | Yes |
-| `color_space` contains `bt2020` | Yes |
-| `color_transfer = smpte2084` (PQ) | Yes — PQ |
-| `color_transfer = arib-std-b67` (HLG) | Yes — HLG |
-| All else (e.g. `bt709`, `smpte170m`) | No — treated as SDR |
-
-A valid HDR source is any MP4 whose stream metadata reports BT.2020 primaries plus PQ or HLG transfer. Hyperframes will detect it automatically:
-
-```bash Terminal
-ffprobe -v error -show_streams assets/clip.mp4 | grep color
-# color_primaries=bt2020
-# color_transfer=smpte2084
-# color_space=bt2020nc
-```
-
-### HDR still images
+HyperFrames detects HDR media during render. When an MP4 project contains a BT.2020 PQ or HLG source, the output uses 10-bit H.265 and keeps the HDR signal. Projects without HDR media stay SDR.
 
-Hyperframes supports HDR still images delivered as **16-bit PNGs** tagged with BT.2020 primaries and PQ transfer. Drop them into the composition as a normal `<img>`:
+## Render and verify
 
-```html index.html
-<img class="clip" data-start="0" data-duration="3"
-     src="./assets/hdr-photo.png" />
+```bash
+npx hyperframes render --output final-hdr.mp4
 ```
 
-When HDR is enabled, the image is decoded once to 16-bit linear-light RGB and composited natively into the HDR output.
-
-<Note>
-  HDR `<img>` decoding is limited to **16-bit PNG**. JPEG, WebP, AVIF, and APNG are not recognized as HDR sources — they load through the normal SDR DOM path. For HDR motion, use a `<video>` element.
-</Note>
-
-### SDR sources mixed with HDR
-
-You can freely mix SDR and HDR media in the same composition:
-
-- **SDR videos** stay in the DOM screenshot path and get the sRGB → BT.2020 conversion described above
-- **HDR videos** are extracted natively at 16-bit and composited underneath the SDR DOM layer
-- **SDR images and DOM elements** (text, shapes, gradients, GSAP animations) are converted from sRGB to BT.2020
-
-This is the same pipeline that handles compositions where, for example, an HDR drone clip plays under an SDR lower-third with animated text.
-
-## Output Format Requirements
-
-| Output format | HDR supported |
-|---------------|---------------|
-| `mp4` | Yes — H.265 10-bit BT.2020, HDR10 metadata |
-| `mov` | No — falls back to SDR |
-| `webm` | No — falls back to SDR |
-| `gif` | No — falls back to SDR |
-
-If HDR is enabled and you also pass `--format mov`, `--format webm`, or `--format gif`, Hyperframes logs a message and produces the equivalent SDR render. There is no error — the render still completes — so check the logs (or your verification step) to confirm you got HDR.
+Check the result:
 
-## Verifying HDR Output
-
-Use `ffprobe` to confirm both the color tagging and the HDR10 static metadata are present:
-
-```bash Terminal
-ffprobe -v error -show_streams -select_streams v:0 output.mp4 \
-  | grep -E 'codec_name|pix_fmt|color_transfer|color_primaries|color_space'
+```bash
+ffprobe -v error -select_streams v:0 -show_entries \
+  stream=codec_name,pix_fmt,color_space,color_primaries,color_transfer \
+  final-hdr.mp4
 ```
 
-For a PQ HDR10 render you should see:
+A PQ output should report values equivalent to:
 
-```
+```text
 codec_name=hevc
 pix_fmt=yuv420p10le
 color_space=bt2020nc
@@ -135,63 +29,36 @@ color_primaries=bt2020
 color_transfer=smpte2084
 ```
 
-Then check the HDR10 SEI / container boxes:
+HLG reports `arib-std-b67` as the transfer.
 
-```bash Terminal
-ffprobe -v error -show_frames -read_intervals "%+#1" \
-  -show_entries frame=side_data_list output.mp4
-```
+## Control detection
 
-You should see entries for **Mastering display metadata** and **Content light level metadata**. Without them, HDR-aware players will treat the file as SDR BT.2020 and the colors will look washed-out or wrong on an HDR display.
+| Command | Use it when |
+| --- | --- |
+| `hyperframes render` | Let source metadata decide between HDR and SDR |
+| `hyperframes render --hdr` | Force HDR; without detected HDR media, HyperFrames uses HLG and warns |
+| `hyperframes render --sdr` | Deliver an SDR version even when the project contains HDR media |
 
-For HLG renders the only difference is `color_transfer=arib-std-b67` — the rest of the checks are the same.
+The source files must contain correct color metadata. HyperFrames recognizes video tagged as BT.2020 with PQ (`smpte2084`) or HLG (`arib-std-b67`). It can also preserve supported HDR still images through the native HDR image path.
 
-## Docker Rendering
+## Mixed compositions
 
-Docker uses the same auto-detect logic as local rendering, so you can produce HDR10 MP4 output from the containerized renderer without extra flags:
+You can place HTML text, CSS graphics, and SDR media over HDR footage. HyperFrames keeps native HDR layers outside the normal browser screenshot, converts the SDR DOM layer into the HDR color space, and composites the result before encoding.
 
-```bash Terminal
-npx hyperframes render --docker --output output.mp4
-```
+This is why a lower third or animated interface can remain visually consistent over an HDR source instead of forcing the whole project through an SDR screenshot.
+
+## Limits
+
+- HDR output is MP4 only. MOV, WebM, GIF, PNG sequence, and alpha output fall back to SDR.
+- HDR and `--resolution` supersampling cannot be combined in one render. Author at the target dimensions or resize in a separate step.
+- Distributed AWS Lambda and Cloud Run renders are currently SDR.
+- Hardware H.265 encoding carries the color tags but does not include the same static mastering metadata as the software `libx265` path. Use software encoding for HDR10 delivery.
+- Browser playback depends on the host browser, display, and operating system; `<hyperframes-player>` does not add its own HDR playback pipeline.
+
+If the file looks SDR, run `ffprobe` on both the source and output before changing the composition. Missing or incorrect source metadata is the most common cause.
+
+## Related topics
 
-The container runs the same probe → composite → encode pipeline as the local renderer. Verify the output with the same `ffprobe` checks described in [Verifying HDR output](#verifying-hdr-output).
-
-<Note>
-  Docker HDR rendering currently runs **CPU-side** for the SDR DOM layer (the container falls back to software WebGL because GPU passthrough is not configured by default). Frame capture is therefore slower than local headed Chrome — measure your own composition with `--quiet` off and compare wall-clock times before sizing CI runners. The encoded HDR10 metadata and pixel data are identical to a local render.
-</Note>
-
-## Limitations
-
-- **MP4 only** — HDR output with `--format mov` or `--format webm` falls back to SDR
-- **HDR images: 16-bit PNG only** — other formats (JPEG, WebP, AVIF, APNG) are not decoded as HDR and fall through the SDR DOM path
-- **H.265 only — H.264 is stripped** — calling the encoder with `codec: "h264"` and `hdr: { transfer }` is rejected; the encoder logs a warning, drops `hdr`, and tags the output as SDR/BT.709. `libx264` cannot encode HDR, so the alternative would be a "half-HDR" file (BT.2020 container tags but a BT.709 VUI block in the bitstream) which confuses HDR-aware players.
-- **GPU H.265 emits color tags but no static mastering metadata** — `useGpu: true` with HDR (nvenc, videotoolbox, amf, qsv, vaapi) tags the stream with BT.2020 + the correct transfer (smpte2084 / arib-std-b67) but does **not** embed `master-display` or `max-cll` SEI. ffmpeg does not let those flags pass through hardware encoders. The output is suitable for previews and authoring but not for HDR10-aware delivery (Apple TV, YouTube, Netflix). For spec-compliant HDR10 production output, leave `useGpu: false` so the SW `libx265` path embeds the mastering metadata.
-- **Player support** — the [`<hyperframes-player>`](/packages/player) web component plays back the encoded MP4 in the browser and inherits whatever HDR support the host browser provides; it does not implement its own HDR pipeline
-- **Headed Chrome HDR DOM capture** — the engine ships a separate WebGPU-based capture path for rendering CSS-animated DOM directly into HDR (`initHdrReadback`, `launchHdrBrowser`). It requires headed Chrome with `--enable-unsafe-webgpu` and is not used by the default render pipeline. See [Engine: HDR](/packages/engine#hdr-apis) if you are building a custom integration.
-
-## Common Pitfalls
-
-| Symptom | Likely cause |
-|---------|--------------|
-| Output looks identical to SDR | Source media is SDR, or SDR was forced with `--sdr`. Run `ffprobe` on your inputs and check the render logs |
-| Output is "kind of HDR" but tone-mapped wrong on YouTube/QuickTime | Missing HDR10 static metadata on the encoded stream. Verify with the ffprobe snippet above |
-| Docker render is much slower than local | Expected — the container falls back to software WebGL for SDR DOM capture. Pixel output is the same |
-| Used `--format webm` and got SDR | Expected — HDR output is MP4 only |
-| HDR `<img>` looks SDR / washed out | Source is not a 16-bit PNG. Re-export as 16-bit PNG (BT.2020 PQ) or use a `<video>` element instead |
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Rendering" icon="film" href="/guides/rendering">
-    Local vs Docker, quality presets, workers
-  </Card>
-  <Card title="CLI" icon="terminal" href="/packages/cli">
-    Full `render` command reference including HDR auto-detect, `--hdr`, and `--sdr`
-  </Card>
-  <Card title="Engine: HDR APIs" icon="gear" href="/packages/engine#hdr-apis">
-    Public HDR utilities exported from `@hyperframes/engine`
-  </Card>
-  <Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
-    Pitfalls that affect render output
-  </Card>
-</CardGroup>
+- [Render from the command line](/guides/rendering)
+- [Open every render flag](/packages/cli#render)
+- [Render at 4K](/guides/4k-rendering)
diff --git a/docs/guides/html-in-canvas.mdx b/docs/guides/html-in-canvas.mdx
index cdbb6acd74..fb2ce6a715 100644
--- a/docs/guides/html-in-canvas.mdx
+++ b/docs/guides/html-in-canvas.mdx
@@ -1,130 +1,104 @@
 ---
-title: "HTML-in-Canvas"
-description: "Render live HTML as WebGL textures — GPU shaders, 3D geometry, and cinematic effects on any DOM content."
+title: "HTML in Canvas"
+description: "Use live DOM content as a texture for WebGL and canvas effects."
 ---
 
-# HTML-in-Canvas
+HTML in Canvas uses Chrome's experimental `drawElementImage()` API to copy rendered DOM content into a canvas. That canvas can become a Three.js texture or the input to a shader effect.
 
-The HTML-in-Canvas API (`drawElementImage`) lets you capture live, rendered DOM elements directly into a canvas at GPU speed. This means you can take any HTML — dashboards, forms, landing pages, app UIs — and render them as textures in WebGL scenes with shaders, 3D transformations, and post-processing effects.
+Use it when the visual treatment depends on both real HTML and GPU effects—for example, an interface inside a 3D device or a DOM scene passing through a distortion shader. It is an advanced, browser-dependent technique.
 
-<Warning>
-**Chrome flag required.** The `drawElementImage` API is experimental and must be enabled manually:
+## Start with a proven block
 
-1. Open `chrome://flags/#canvas-draw-element` in Chrome or Brave
-2. Set **CanvasDrawElement** to **Enabled**
-3. Restart the browser
+The fastest path is to install a Catalog block that already handles capability detection and fallback behavior:
 
-HyperFrames enables this flag automatically during rendering (`--enable-features=CanvasDrawElement`), so rendered videos work without manual setup. The flag is only needed for live preview in the Studio.
-</Warning>
+```bash
+npx hyperframes add vfx-iphone-device
+```
 
-## How it works
+Other relevant examples include [Portal](/catalog/blocks/vfx-portal), [Shatter](/catalog/blocks/vfx-shatter), and [Liquid Glass Notification](/catalog/blocks/liquid-glass-notification).
 
-1. Place HTML content inside a `<canvas layoutsubtree>` element
-2. The browser renders the HTML children as normal DOM
-3. Call `ctx.drawElementImage(element, x, y, w, h)` to capture the rendered pixels into the canvas
-4. Use the canvas as a Three.js texture, apply shaders, map to 3D geometry
+Install every block tagged `html-in-canvas` only when you want to compare the full set:
 
-```html
-<!-- 1. HTML content lives inside the canvas -->
-<canvas id="capture" layoutsubtree width="1920" height="1080">
-  <div class="my-dashboard">
-    <h1>Revenue: $4.2M</h1>
-    <div class="chart">...</div>
-  </div>
-</canvas>
-
-<!-- 2. WebGL canvas for 3D rendering -->
-<canvas id="theater" width="1920" height="1080"></canvas>
+```bash
+npx hyperframes add html-in-canvas
 ```
 
-```javascript
-// 3. Capture HTML to canvas
-var capCanvas = document.getElementById("capture");
-var ctx = capCanvas.getContext("2d");
-ctx.drawElementImage(capCanvas.querySelector(".my-dashboard"), 0, 0, 1920, 1080);
+## Browser support
 
-// 4. Use as Three.js texture
-var texture = new THREE.CanvasTexture(capCanvas);
-var material = new THREE.MeshBasicMaterial({ map: texture });
-```
+`drawElementImage()` is an experimental Chromium feature. The feature flag only works in browser builds that contain the API.
 
-## What makes this different
+HyperFrames enables `CanvasDrawElement` when it launches Chrome and checks whether the API is actually available. The render engine can fall back to its normal capture path when the fast-capture API is unavailable or unsafe for a composition.
 
-Traditional approaches like `html2canvas` re-parse and re-render the DOM in JavaScript — they're slow, lossy, and miss CSS features like `backdrop-filter`, complex shadows, and web fonts. The `drawElementImage` API uses the browser's own compositor, so:
+To refresh the browser used by the CLI:
 
-- **Pixel-perfect** — every CSS feature is supported because the browser renders it natively
-- **GPU-accelerated** — captures at 60fps, fast enough for real-time animation
-- **Live content** — the HTML can animate, scroll, and change between captures
-- **Multiple captures simultaneously** — no nesting restrictions, multiple `<canvas layoutsubtree>` elements can capture different content in the same composition
+```bash
+npx hyperframes browser ensure --force
+```
 
-## Feature detection
+For a normal browser preview, enable `chrome://flags/#canvas-draw-element` in a compatible Chrome or Brave build and restart it. Keep a visual fallback because collaborators may open the composition in a browser without the feature.
 
-Always feature-detect before using the API. Compositions should fall back gracefully for browsers without the flag enabled.
+## Minimal pattern
 
-```javascript
-function isSupported() {
-  var tc = document.createElement("canvas");
-  if (!("layoutSubtree" in tc)) return false;
-  tc.setAttribute("layoutsubtree", "");
-  var ctx = tc.getContext("2d");
-  return ctx && typeof ctx.drawElementImage === "function";
-}
+```html
+<canvas id="capture" layoutsubtree width="1920" height="1080">
+  <section id="source">
+    <h1>Revenue: $4.2M</h1>
+  </section>
+</canvas>
 
-if (isSupported()) {
-  ctx.drawElementImage(element, 0, 0, w, h);
-} else {
-  // Fallback: draw text directly on canvas, use static image, etc.
-}
+<canvas id="scene" width="1920" height="1080"></canvas>
 ```
 
-## Re-capturing every frame
+```javascript
+var captureCanvas = document.getElementById("capture");
+var source = document.getElementById("source");
+var captureContext = captureCanvas.getContext("2d");
 
-For animated content (scrolling, transitions, counters), call `drawElementImage` inside your render loop to update the texture every frame:
+function supportsHtmlInCanvas() {
+  var probe = document.createElement("canvas");
+  probe.setAttribute("layoutsubtree", "");
+  var context = probe.getContext("2d");
 
-```javascript
-function render() {
-  // Update HTML state
-  scrollContainer.style.transform = "translateY(-" + scrollOffset + "px)";
-  counterEl.textContent = Math.round(currentValue);
-
-  // Re-capture
-  ctx.clearRect(0, 0, W, H);
-  ctx.drawElementImage(htmlElement, 0, 0, W, H);
-  texture.needsUpdate = true;
-
-  // Render 3D scene with updated texture
-  renderer.render(scene, camera);
+  return "layoutSubtree" in probe && typeof context?.drawElementImage === "function";
 }
-```
 
-## Catalog blocks
+if (supportsHtmlInCanvas()) {
+  captureContext.drawElementImage(source, 0, 0, 1920, 1080);
+} else {
+  // Draw a simpler canvas version or use a static image.
+}
+```
 
-Install all HTML-in-Canvas blocks at once:
+After capture, use `captureCanvas` like any other canvas texture:
 
-```bash
-npx hyperframes add html-in-canvas
+```javascript
+var texture = new THREE.CanvasTexture(captureCanvas);
+var material = new THREE.MeshBasicMaterial({ map: texture });
 ```
 
-Or install individually:
+If the DOM changes, capture it again and set `texture.needsUpdate = true`.
 
-| Block | Description | Install |
-|-------|-------------|---------|
-| [iOS 26 Liquid Glass Home Screen](/catalog/blocks/ios26-liquid-glass) | iPhone home screen with live Liquid Glass notifications and widgets | `npx hyperframes add ios26-liquid-glass` |
-| [macOS Tahoe Liquid Glass Desktop](/catalog/blocks/macos-tahoe-liquid-glass) | MacBook desktop with liquid glass windows, dock, and notifications | `npx hyperframes add macos-tahoe-liquid-glass` |
-| [Liquid Glass Notification](/catalog/blocks/liquid-glass-notification) | Native-feeling glass notification stack with progress and reply states | `npx hyperframes add liquid-glass-notification` |
-| [iPhone & MacBook](/catalog/blocks/vfx-iphone-device) | Real 3D GLTF devices with live HTML screens | `npx hyperframes add vfx-iphone-device` |
-| [Text Cursor](/catalog/blocks/vfx-text-cursor) | Dramatic text reveal with chromatic shadows | `npx hyperframes add vfx-text-cursor` |
-| [Portal](/catalog/blocks/vfx-portal) | Dimension breach with volumetric light | `npx hyperframes add vfx-portal` |
-| [Shatter](/catalog/blocks/vfx-shatter) | HTML shatters into glass fragments | `npx hyperframes add vfx-shatter` |
-| [Magnetic](/catalog/blocks/vfx-magnetic) | Magnetic field particle visualization | `npx hyperframes add vfx-magnetic` |
-| [Liquid Background](/catalog/blocks/vfx-liquid-background) | Organic liquid simulation | `npx hyperframes add vfx-liquid-background` |
+## Know the limits
 
-## Rendering
+The browser's paint-record path does not reproduce every compositor effect. Filters, backdrop filters, some 3D transforms, masks, blend modes, and similar effects can force HyperFrames back to the normal capture path.
 
-HyperFrames enables the Chrome flag automatically during rendering. No special configuration needed:
+That fallback protects the final result, but it also means HTML in Canvas is not a promise of universal CSS support or faster rendering. Test the actual composition:
 
 ```bash
-npx hyperframes render --output my-video.mp4
+npx hyperframes lint
+npx hyperframes check
+npx hyperframes render --output html-in-canvas.mp4
 ```
 
-For Docker renders, the flag is also enabled automatically inside the container.
+Review transition frames and effects in the rendered file, not only in a live preview.
+
+## Related topics
+
+<CardGroup cols={2}>
+  <Card title="Shader transitions" icon="wand-magic-sparkles" href="/packages/shader-transitions">
+    Apply built-in WebGL transitions between scenes.
+  </Card>
+  <Card title="Browse visual blocks" icon="grid-2" href="/catalog">
+    Start from a working effect instead of rebuilding its capture logic.
+  </Card>
+</CardGroup>
diff --git a/docs/guides/hyperframes-vs-remotion.mdx b/docs/guides/hyperframes-vs-remotion.mdx
index f617afab65..8dc8073f65 100644
--- a/docs/guides/hyperframes-vs-remotion.mdx
+++ b/docs/guides/hyperframes-vs-remotion.mdx
@@ -1,162 +1,103 @@
 ---
-title: Hyperframes vs Remotion
-description: "Why we built Hyperframes, how it differs from Remotion in practice, and where each tool fits."
+title: "HyperFrames or Remotion?"
+description: "A practical comparison of HTML-first HyperFrames and React-first Remotion."
 ---
 
-[Remotion](https://www.remotion.dev) is an awesome project, and we used Remotion in HeyGen's production pipelines for many months. Remotion promoted the idea of using code to orchestrate and animate video production, and it proved that headless Chrome could be a reliable, deterministic video renderer. Several patterns in the Hyperframes source come directly from what the Remotion team pioneered — Chrome launch flags, port selection, image2pipe streaming into FFmpeg, in-order frame buffering. We kept attribution comments in our code on purpose so the lineage stays visible to anyone reading the source.
+Both tools create videos with web technology and render them through a browser. The main difference is the authoring model.
 
-This guide is the honest breakdown of where Hyperframes and Remotion differ, written by the team that built Hyperframes. We picked different bets; each one has strengths the other doesn't, and this doc walks through both.
+- **HyperFrames** treats HTML, CSS, and browser animation as the composition.
+- **Remotion** treats React components and frame-based React code as the composition.
 
-## Why we built Hyperframes
-
-As we scaled our code-to-video pipelines at HeyGen, we kept running into the same kinds of limits inside a React-first authoring model. We debated internally whether to keep building on Remotion or write a renderer from scratch. Two factors pushed us to build Hyperframes.
-
-### 1. The agent-native workflow
-
-In our evals, LLMs writing Remotion compositions produced less creative visual outputs and needed a lot more guardrails and prompting than the same LLMs writing HTML + [GSAP](/guides/gsap-animation) compositions directly.
-
-Two related issues compounded it:
-
-- Animation libraries with their own internal clocks (GSAP, Anime.js, Motion One) don't compose cleanly with React's per-frame render.
-- Arbitrary HTML or CSS that wasn't written as React doesn't have a clean path into a React composition — you have to rewrite it.
-
-### 2. The human editing workflow
-
-We want the same code to be the render layer _and_ the data layer, because we need a UI for humans on top of the agentic experience.
-
-HTML is both the render layer and the editable source of truth — the same DOM is what you see and what you edit. That makes a real visual editor (selection, drag-and-drop, property panels, timeline) much more natural to build, the same way [Paper.Design](https://paper.design) does it. With Remotion, the source of truth is code plus a build step, so round-tripping through a visual editor is painful and fragile. The Remotion team has made progress here, but it's much more difficult to build a real-time editor on top of React than on top of HTML.
-
-We architected Hyperframes to be the most native to agents while making it easy to build a human interface on top.
+Neither choice is universally better. Pick the one that fits the source material, team, and workflow.
 
 ## At a glance
 
-| | **Hyperframes** | **Remotion** |
+| Question | HyperFrames | Remotion |
 | --- | --- | --- |
-| Authoring | HTML + CSS + GSAP | React components (TSX) |
-| Runtime | Browser DOM, no framework | React reconciliation per frame |
-| Build step | None; `index.html` plays as-is | Required (webpack, bundler) |
-| Library-clock animations (GSAP, Anime.js, Motion One) | Seekable; frame-accurate | Plays at wall-clock during render |
-| Arbitrary HTML / CSS passthrough | Paste and animate | Rewrite as JSX |
-| Distributed rendering | [AWS Lambda](/deploy/aws-lambda) support | [Remotion Lambda](https://www.remotion.dev/lambda), mature and production-tested |
-| [HDR output](/guides/hdr) | Supported | Documented as unsupported |
-| Visual editor over render source | Native; same DOM is editable | Source is code plus a build step |
-| License | [Apache 2.0](https://github.com/heygen-com/hyperframes/blob/main/LICENSE) | [Commercial](https://www.remotion.pro/license) |
-
-The rest of this guide walks through what each row means and where each tool actually wins.
-
-## The core difference: React vs HTML
-
-Hyperframes and Remotion both drive headless Chrome. Both are deterministic. Both ship agent skills. They differ on one decision: what the primary author writes.
-
-Remotion's bet is React. Video compositions are React components. You get typed JSX, the React ecosystem, component reuse, and the whole of React tooling. Remotion's strengths come from committing to that surface: years of production use, Lambda at hyperscale, a large community, careful type-safe APIs.
-
-Hyperframes' bet is HTML. Video compositions are HTML pages. You can paste in a landing page, a design-system component, or a CodePen demo and animate it. We think that's the right surface for two specific use cases: AI agents writing video, and visual editors built directly on the DOM the renderer consumes.
-
-Different bets, different strengths. The rest of this doc breaks down where each shows up.
-
-## What the difference means in practice
+| Main authoring surface | HTML, CSS, and JavaScript | React and TypeScript |
+| Agent workflow | Built around agent skills and plain HTML projects | Provides agent skills and React video workflows |
+| Visual editing | HyperFrames Studio edits the rendered DOM and project source | Remotion Studio can edit and animate React compositions visually, then save changes back to code |
+| Existing web material | Can often be used directly or adapted as HTML | Usually translated into React components |
+| Animation model | Seeks registered browser timelines frame by frame | Commonly derives visuals from the current frame in React |
+| Reuse | HTML scenes, components, and Catalog items | React components and the React ecosystem |
+| Cloud rendering | Local, hosted cloud, AWS Lambda, and other deployment paths | Mature AWS Lambda and server-rendering options |
+| License | Apache 2.0 | Custom license with free and paid eligibility rules |
 
-### Agents express visuals better in HTML than in React
+## Choose HyperFrames when
 
-When an LLM writes Hyperframes, it's writing the medium it was trained on most heavily. The web as browsers see it — HTML, CSS, JavaScript, GSAP idioms from CodePen, 25+ years of accumulated web animation content — is the deepest well in a model's training data. React-specific sources are a much smaller slice.
+HyperFrames is a strong fit when:
 
-From running both systems in production: an agent asked to write a Remotion composition spends tokens learning framework rules (which hooks are allowed, which APIs are forbidden, how to scaffold a project) before it can be creative. Output tends to converge on a narrow visual vocabulary — centered titles, stock transitions, conventional typography. The same agent writing HTML with GSAP reaches for a wider creative range, because that's what its training data looks like.
+- an AI agent will do most of the authoring;
+- the source is a website, HTML prototype, design artifact, or browser animation;
+- you want GSAP and other browser timelines to be seeked deterministically;
+- a human should review and edit the same DOM the renderer consumes;
+- Apache 2.0 licensing matters;
+- you want a project that can remain mostly plain HTML.
 
-### Animation libraries with their own clocks
+The main tradeoff is ecosystem maturity. HyperFrames is newer, and some advanced deployment and integration surfaces have less history than Remotion’s.
 
-Asking an agent to port a GSAP animation or an existing web page into Remotion loses details on the first try: timing nuances, audio level relationships, text sizing. The HTML-first path avoids the translation step entirely.
+## Choose Remotion when
 
-We gave both tools the same 4-second GSAP timeline: 11 letters of "HYPERFRAMES" enter staggered with a back-out ease, hold for 1.5 seconds, then each letter rotates and falls out of frame. Identical animation code, identical easings, identical stagger. The only thing we changed was the renderer.
+Remotion is a strong fit when:
 
-**Hyperframes output — what the animation is meant to look like:**
+- your team already builds in React and TypeScript;
+- you want to reuse React components and tooling;
+- frame-driven React code is a natural way to express the animation;
+- you depend on Remotion’s established templates, community, or production infrastructure;
+- its mature Lambda ecosystem is important;
+- your organization is comfortable with its current license.
 
-<img src="https://static.heygen.ai/hyperframes-oss/docs/images/comparisons/gsap-hf.gif" alt="Hyperframes GSAP render — letters enter, hold, then fall away over the full 4 seconds" />
+The main tradeoff is translation. Existing HTML, imperative browser animation, or a non-React design artifact may need to be adapted into React’s model.
 
-All four seconds are used. Letters fly in one by one, the full word holds in the center for about a second and a half, then the letters spin and drop away.
+## Animation is the deepest technical difference
 
-**Remotion output — same timeline, same code:**
+Remotion compositions commonly calculate visual state from the current frame. This is explicit and works naturally with React.
 
-<img src="https://static.heygen.ai/hyperframes-oss/docs/images/comparisons/gsap-remotion.gif" alt="Remotion GSAP render — GSAP plays through its entire timeline in the first second, leaving most of the render as an empty stage" />
+HyperFrames can also use frame-derived logic, but its distinctive path is a **frame adapter**: the renderer pauses a browser animation timeline and seeks it to the exact output time before capturing the frame.
 
-GSAP plays through its entire 4-second animation in roughly the first second of render wall-clock time. By the time Remotion captures later frames, GSAP's timeline has already completed and every letter has exited — the remainder of the render captures an empty stage.
+That makes GSAP, Web Animations, Lottie, and other supported browser runtimes usable without letting their wall clock control the render.
 
-**Why:** GSAP drives its own timeline via `performance.now()`, which ticks at real-time speed during render. Hyperframes pauses GSAP and seeks it to `frame / fps` before capturing each frame, so the library runs in lockstep with the output. Remotion has no equivalent primitive, so GSAP's internal ticker races through the timeline at wall-clock speed while Remotion captures a handful of frames during the entrance and mostly-empty frames after.
+See [Frame adapters](/concepts/frame-adapters) and [Deterministic rendering](/concepts/determinism).
 
-Everything GSAP supports — SplitText, ScrollTrigger, MotionPath, physics, 15 years of snippets on CodePen — works the same way in Hyperframes. The pattern generalizes to Anime.js, Motion One, and any other library with its own clock; any JS library without its own clock just works. Wrapping a library clock in a Remotion component is possible but awkward, and you give up most of what the library is good at.
+## Studio works differently
 
-See the [GSAP animation guide](/guides/gsap-animation) for how this integrates, and [Deterministic Rendering](/concepts/determinism) for how seek-driven capture works under the hood.
+HyperFrames Studio selects and edits elements in the live composition DOM. It includes Storyboard and Preview views, direct canvas editing, layers, a timeline, animation controls, assets, captions, variables, source files, lint handoff, and export.
 
-### Arbitrary HTML, CSS, JavaScript
+That does not mean every structural change should be made visually. Broader story and source changes are often better handled by the agent.
 
-Every web page is a potential Hyperframes composition. Landing pages. Claude Design artifacts. Design-system docs. CodePen embeds. You paste in the HTML and render.
+Remotion Studio is a development and visual-editing environment for React compositions. It supports direct manipulation and animation controls, then saves the result back to React code. Remotion also publishes tooling for building custom editing applications.
 
-Remotion asks you to translate first: rewrite HTML as JSX, convert CSS for React, wrap imperative code (Canvas, WebGL, GSAP) in React components with refs and effects. Every translation step is a chance for an agent or a human to lose fidelity or introduce bugs. The translation is round-tripping work anyway — both frameworks ultimately serve HTML to the browser to render.
+The two Studios are not interchangeable. HyperFrames Studio operates on the DOM and HTML project that HyperFrames renders; Remotion Studio operates on React compositions.
 
-The [website-to-video guide](/guides/website-to-video) walks through the full capture-to-render pipeline that the HTML-first model enables.
+## Rendering and deployment
 
-### Auto-fallback for edge primitives
+Remotion Lambda is a mature distributed-rendering system with extensive AWS documentation.
 
-Hyperframes has two capture modes.
+HyperFrames supports local rendering, HeyGen-hosted cloud rendering, AWS Lambda, Google Cloud Run, and custom deployment. The right comparison depends on the destination, expected volume, and how much infrastructure the team wants to operate.
 
-- **BeginFrame mode** (Linux + `chrome-headless-shell`) drives Chrome's compositor atomically via `HeadlessExperimental.beginFrame`, producing byte-for-byte reproducible frames across machines.
-- **Screenshot mode** (macOS, Windows, and as an automatic fallback) runs Chrome in real time and takes ordinary screenshots — the same approach Remotion uses.
-
-The renderer inspects each composition at compile time and falls back to screenshot mode when it spots primitives BeginFrame can't handle: inline `<iframe>`s, raw `requestAnimationFrame` loops outside a [Frame Adapter](/concepts/frame-adapters). It injects a virtual-time shim so rAF and iframe content stay frame-driven instead of wall-clock-driven. You get a diagnostic explaining the fallback, and the render produces visibly-correct output. When the composition can run in BeginFrame mode, you get determinism for free.
-
-In practice: GSAP timelines, CSS `@keyframes` (via the Web Animations API adapter), Lottie, Three.js, and the Web Animations API all render deterministically in BeginFrame mode. Raw canvas loops and live-web embeds get screenshot mode automatically.
-
-### React component reuse (Remotion's home turf)
-
-If your team already has a design system in React components, Remotion lets you compose videos from the same primitives you ship in your app. Type safety, IDE completion, cross-file refactoring — everything React brings to developer ergonomics. For teams with existing React investment, this is a real advantage Hyperframes doesn't try to match.
-
-### Distributed rendering
-
-[Remotion Lambda](https://www.remotion.dev/lambda) splits long videos across hundreds of AWS Lambda functions. It's mature, production-tested, and well-documented — a thing teams have used in production for years.
-
-Hyperframes now ships an [AWS Lambda deployment path](/deploy/aws-lambda): one Lambda function behind a Step Functions workflow that fans renders out across chunk workers, stores intermediates in S3, and exposes `lambda render`, `lambda render-batch`, progress polling, and SDK usage. The surface is newer than Remotion Lambda, so the practical tradeoff is maturity versus Hyperframes' HTML-native composition model.
-
-### Visual editing over the render source (Hyperframes' natural bet)
-
-The DOM you render is the DOM you edit. [Hyperframes Studio](/packages/studio) previews compositions in a live iframe, and because the renderer and the editor share one DOM, direct manipulation works against the same source of truth the render pipeline consumes. That UX — click to select, drag to reposition, edit properties in a panel — already ships for captions today, with broader element coverage building out from the same architectural foundation.
-
-Building the same editor on top of React is harder because the source of truth is code plus a build step. Round-tripping a visual edit back to JSX means re-compiling. That's why tools like [Paper.Design](https://paper.design) chose HTML as the editable source in the first place.
-
-### HDR output
-
-Both tools currently render through headless Chrome, which outputs sRGB. Remotion [documents this as unsupported](https://www.remotion.dev/docs/hdr). Hyperframes [supports HDR output](/guides/hdr) via a two-pass compositing pipeline that combines a DOM layer with native HLG/PQ video.
-
-## Open source vs source-available
-
-This is one of the clearest differences between the two projects, and one of the most common reasons teams pick one over the other.
-
-| | **Hyperframes** | **Remotion** |
-| --- | --- | --- |
-| Classification | Open source ([OSI-approved](https://opensource.org/licenses/Apache-2.0)) | Source-available, not open source |
-| License | [Apache 2.0](https://github.com/heygen-com/hyperframes/blob/main/LICENSE) | [Custom Remotion License](https://www.remotion.pro/license) |
-| Commercial use | Free at any scale | Requires a paid company license above small-team thresholds |
-| Per-render fees | None | Yes, above thresholds |
-| Redistribution | Permitted under Apache 2.0 | Restricted by the Remotion License |
+See [HyperFrames deployment](/developers) and [Remotion Lambda](https://www.remotion.dev/docs/lambda).
 
-Both projects publish their source on GitHub, but the licenses work very differently. Apache 2.0 is an [Open Source Initiative-approved license](https://opensource.org/licenses/Apache-2.0) — you can self-host, modify, redistribute, and use Hyperframes commercially at any scale with no per-render fees and no seat caps. The Remotion License is a custom commercial license: you can read the code and self-host for small teams, but commercial use above their thresholds requires a paid company license.
+## Licensing
 
-If open-source licensing matters to you — OSI compliance, redistribution rights, no per-use fees, long-term independence from a vendor's pricing decisions — this is a first-order decision point. If your use case fits within Remotion's free tier or your company is comfortable with a commercial license, it's a non-issue. See the [Remotion license page](https://www.remotion.pro/license) for their current terms.
+HyperFrames is available under the [Apache 2.0 license](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).
 
-We open-sourced Hyperframes under Apache 2.0 so anyone can build on it — including commercially, at any scale — and so the project can outlive any single company's priorities.
+Remotion uses its own license. Its current terms allow free use for individuals and companies of up to three people, with a Company License required for larger organizations. Pricing and eligibility can change, so check the [official Remotion license page](https://www.remotion.pro/license) instead of relying on a copied price here.
 
-## Recap
+## Moving an existing project
 
-The single difference between Remotion and Hyperframes is the choice of React vs HTML (+ CSS + JavaScript). That decision leads to many differences downstream. For our needs — most native to agents, architected to support a UI layer for humans — HTML + CSS + JavaScript was the obvious bet:
+Do not migrate only because one framework looks newer. First identify what the current project depends on:
 
-1. Agents already "think" in HTML. LLMs have seen massive amounts of web code.
-2. True "one file in, video out." No `package.json`, no installs, no bundler config, no composition setup. Fewer moving parts = way fewer random failures in automated and agentic workflows.
-3. Highest creative ceiling — anything the browser can render, HTML can represent.
-4. HTML is both the render layer and the editable source of truth. The same DOM is what you see and what you edit.
+- React components and React-specific libraries;
+- imperative browser animation;
+- cloud-rendering infrastructure;
+- visual editing;
+- licensing;
+- team familiarity.
 
-We at HeyGen are all-in on Hyperframes, but we can't do this alone — that's why we open-sourced it under Apache 2.0, so together we can build the foundation for agentic video creation.
+If a Remotion composition is a good candidate for HyperFrames, ask `/hyperframes` to route the work through the Remotion-to-HyperFrames migration workflow. Validate the result scene by scene; source migration is not a mechanical file conversion.
 
-## Further reading
+## Related topics
 
-- [Deterministic Rendering](/concepts/determinism) — how seek-driven frame capture works
-- [GSAP animation guide](/guides/gsap-animation) — library-clock integration in practice
-- [Frame Adapters](/concepts/frame-adapters) — the extension point for animation runtimes
-- [Website to video](/guides/website-to-video) — the HTML-first capture-to-render pipeline
+- [Understand the HyperFrames project model](/concepts)
+- [Choose a rendering path](/deploy/overview)
+- [Build on HyperFrames](/developers)
diff --git a/docs/guides/mcp.mdx b/docs/guides/mcp.mdx
index 703063e9bd..f960d48c67 100644
--- a/docs/guides/mcp.mdx
+++ b/docs/guides/mcp.mdx
@@ -1,332 +1,154 @@
 ---
-title: HyperFrames MCP
-description: "Author, preview, and render HyperFrames videos directly inside Claude.ai, ChatGPT, and Grok — no local install required."
+title: "Create through an AI chat"
+description: "Use the hosted HyperFrames MCP connector to create and render without installing the local CLI."
 ---
 
-The HyperFrames MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server that lets you create, edit, preview, and render HyperFrames video compositions from inside Claude.ai, ChatGPT, or Grok.
+HyperFrames MCP is a hosted connector for supported AI chat products. It lets
+the chat call HyperFrames creation and rendering tools through your HeyGen
+account without installing the local CLI.
 
 <Note>
-  **In beta.** Features and pricing may change. Found a bug or have feedback? [File an issue on GitHub](https://github.com/heygen-com/hyperframes/issues).
+  This path is in beta. Availability, interface wording, features, credits, and plan requirements
+  can change.
 </Note>
 
-## What you can do
+## Choose hosted or local
 
-- Create compositions from natural-language prompts
-- Edit existing compositions conversationally — *"make the title 2x bigger"*, *"add hype-style captions"*
-- Preview the result inline in the chat with a video player widget
-- Render to `mp4`, `webm`, or `mov` — output URL streamed back to chat
-- Revisit compositions you've created previously
-- Check your render credits
+Use the hosted connector when you want:
 
-The agent behind `compose` has 25+ HyperFrames-specific skills baked in — typography, color palettes, motion principles, GSAP effects, audio-reactive animation, and captions. You don't have to specify any of this directly; describe the video you want and the agent picks the right tools.
+- no local HyperFrames setup;
+- a conversational creation flow;
+- cloud rendering;
 
-<Note>
-  Looking for the open-source CLI? See the [Quickstart](/quickstart). The MCP is a hosted product for zero-install authoring inside an LLM chat. The CLI gives you full control of rendering and runtime; the MCP gives you instant authoring with cloud rendering.
-</Note>
-
-## Setup
-
-### 1. Get a HeyGen account
-
-The MCP requires a HeyGen account for authentication and credits. Sign up at [heygen.com](https://heygen.com) if you don't have one.
-
-### 2. Add the connector
-
-<Tabs>
-  <Tab title="Claude.ai">
-    <Steps>
-      <Step title="Open Settings → Connectors">
-        In Claude.ai web or desktop: **Settings → Connectors**.
-      </Step>
-      <Step title="Find HyperFrames">
-        Search the connector catalog for **HyperFrames** and click **Connect**.
-
-        Don't see it in the catalog? Add it manually: **Add custom connector**, then paste:
-        ```
-        https://mcp.heygen.com/mcp/hyperframes
-        ```
-      </Step>
-      <Step title="Sign in to HeyGen">
-        OAuth opens in a new window. Authorize the HyperFrames connector to access your HeyGen account.
-      </Step>
-      <Step title="Start a new chat">
-        Open a new Claude.ai chat. Try:
-
-        > Make me a 10-second product intro for [your product] with bouncy captions and a high-energy soundtrack.
-      </Step>
-    </Steps>
-  </Tab>
-  <Tab title="ChatGPT">
-    <Steps>
-      <Step title="Open Apps & Connectors">
-        In ChatGPT: **Settings → Apps & Connectors → Add MCP server**.
-      </Step>
-      <Step title="Enter the URL">
-        Paste:
-        ```
-        https://mcp.heygen.com/mcp/hyperframes
-        ```
-      </Step>
-      <Step title="Sign in to HeyGen">
-        Authorize via OAuth.
-      </Step>
-      <Step title="Start a new chat">
-        Open a new chat. Same prompts work as in Claude.ai.
-      </Step>
-    </Steps>
-  </Tab>
-  <Tab title="Grok">
-    <Steps>
-      <Step title="Open Settings → Connectors">
-        In Grok: **Settings → Connectors**.
-      </Step>
-      <Step title="Find HyperFrames">
-        Search the connector catalog for **HyperFrames** and click **Connect**.
-
-        Don't see it in the catalog? Add it manually: **Add custom connector**, then paste:
-        ```
-        https://mcp.heygen.com/mcp/hyperframes
-        ```
-      </Step>
-      <Step title="Sign in to HeyGen">
-        Authorize via OAuth.
-      </Step>
-      <Step title="Start a new chat">
-        Open a new chat. Same prompts work as in Claude.ai.
-      </Step>
-    </Steps>
-  </Tab>
-</Tabs>
-
-## Available tools
-
-The MCP exposes six tools to the LLM. You don't call them directly — the model picks the right tool based on your message.
-
-| Tool | What it does | Cost |
-|---|---|---|
-| `compose` | Create a new composition or edit an existing one | Author credits |
-| `list_compositions` | List your previously created compositions | Free |
-| `get_composition` | Open a specific composition with an inline player | Free |
-| `render_video` | Submit a cloud render to mp4 / webm / mov | Render credits |
-| `get_render_status` | Poll a long-running render job | Free |
-| `get_credits` | Check your remaining credits and tier | Free |
-
-### compose
-
-Authors a new composition or applies an edit to an existing one. The HyperFrames agent handles captions, blocks, layout, transitions, color, and timing internally based on your natural-language prompt.
-
-**Triggered by prompts like:**
-
-- "Make a 30-second product intro about [topic]" → creates a fresh composition
-- "Change the title font to a bold serif" → edits the most recent composition
-- "Add a flash transition before the call-to-action" → applies a structured edit
-
-**Returns:** A composition reference (id, title, thumbnail) plus an inline player widget. Progress notifications stream during the run so you can see what the agent is doing — *"Drafting outline...", "Selecting style...", "Generating HTML...", "Rendering preview frame..."*
-
-### list_compositions
-
-Lists compositions you've previously created. Newest first, paginated.
-
-**Triggered by prompts like:** *"show me my recent videos"*, *"what did I work on yesterday?"*
-
-### get_composition
-
-Fetches metadata for a single composition along with an inline player widget.
-
-**Triggered by prompts like:** *"open that video again"*, *"show me the one I made about [topic]"*
-
-### render_video
-
-Submits a cloud render. Defaults to `mp4` at `30fps`.
+Use the [local Quickstart](/quickstart) when you need:
 
-**Format options:**
+- full project files;
+- local rendering;
+- direct Studio and source editing;
+- custom automation or deployment;
+- precise debugging and validation.
 
-| Format | Codec | Use it for |
-|---|---|---|
-| `mp4` (default) | H.264 | Broadest compatibility, social media, web |
-| `webm` | VP9 | Smaller files; supports alpha channel for transparent overlays |
-| `mov` | ProRes | Lossless quality for editing pipelines |
+## Connect HyperFrames
 
-**Frame rate options:** `24`, `30` (default), `60`.
+The production MCP address is:
 
-**Returns:** Either the rendered video URL (if the render finishes within 25 seconds) or a `job_id` for polling. Either way, an inline render-progress widget shows live status.
-
-**Triggered by prompts like:** *"render this"*, *"export to webm"*, *"render at 60fps for editing"*.
+```text
+https://mcp.heygen.com/mcp/hyperframes/
+```
 
-### get_render_status
+You need a HeyGen account and access to the HyperFrames connector.
 
-Polls an in-progress render. Used internally by the model when `render_video` returns a `job_id` (long renders).
+Each host controls where custom connectors appear and which plans or workspace
+roles can add them. Use the steps below as orientation, then follow the linked
+host documentation when its interface differs.
 
-### get_credits
+<Tabs>
+  <Tab title="Claude">
+    1. Open **Customize → Connectors**.
+    2. Choose **Add custom connector** and enter the MCP address above.
+    3. Complete the HeyGen sign-in.
+    4. In a new chat, open the **+** menu, choose **Connectors**, and enable HyperFrames.
 
-Returns your tier and remaining credits.
+    See [Anthropic’s current connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for plan and workspace requirements.
 
-**Triggered by:** *"how many renders do I have left?"*, *"what's my plan?"*
+  </Tab>
+  <Tab title="ChatGPT">
+    If HyperFrames appears in **Settings → Apps**, choose **Connect** and complete HeyGen authorization.
 
-## Prompting tips
+    To add the MCP address as a custom app, an authorized user enables the host's developer mode, creates an app from the endpoint, scans the tools, and completes OAuth. Workspace admins may control publishing and action access.
 
-### Be specific about what you want
+    See [OpenAI’s current MCP app instructions](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta).
 
-The agent has lots of creative latitude — give it enough direction to use it well.
+  </Tab>
+  <Tab title="Grok">
+    1. Open [grok.com/connectors](https://grok.com/connectors).
+    2. Choose **New Connector → Custom**.
+    3. Enter the MCP address above.
+    4. Complete HeyGen authorization.
 
-| Less effective | More effective |
-|---|---|
-| "make a video" | "make a 15-second TikTok hook about home composting with bouncy captions and a warm earthy palette" |
-| "add captions" | "add hype-style captions in my brand color #FF6A00" |
-| "make it shorter" | "trim to 10 seconds total — cut the third scene" |
-| "more energetic" | "swap to a neon-electric palette and tighten all transitions to 200ms" |
+    See [xAI’s current connector instructions](https://docs.x.ai/grok/connectors) for workspace requirements.
 
-### Iterate conversationally
+  </Tab>
+</Tabs>
 
-Once a composition exists, the agent loads the current state and applies edits in place. Keep talking to it.
+Host products change their connector interfaces independently. If a menu or button is missing, check that host’s current plan and workspace permissions before treating it as a HyperFrames failure.
 
-```
-You:    "20-second product intro for my app, dark theme, hype style"
-Agent:  [composition + player widget appears]
+## Create a first composition
 
-You:    "make the logo bigger and add a pulse animation on the CTA"
-Agent:  [updated player widget]
+Describe the video as you would to an editor:
 
-You:    "render to webm with alpha"
-Agent:  [render-progress widget, then player widget with download link]
+```text
+Make a 15-second vertical product intro for a meditation app.
+Audience: people who have trouble falling asleep.
+Style: quiet, spacious, and warm.
+Show the breathing timer and end with “Rest starts here.”
 ```
 
-### Reference your existing HeyGen assets
-
-If you've uploaded logos, fonts, or other assets to your HeyGen account, the agent can use them. Just say *"use my logo"* or *"use my brand font."* The agent resolves the asset by name and recency.
-
-### Pick the right format up front
-
-Mention the output format if you have a specific use case:
-
-- *"render to mp4"* — default, social media
-- *"render to webm with alpha"* — transparent overlay you'll composite later
-- *"render to mov for After Effects"* — ProRes for editing
-
-## Debugging
+The connector proposes and builds the composition through the tools exposed in
+that chat. Follow the returned tool result rather than expecting a specific
+preview widget: hosts present MCP output differently.
 
-### Inspect the MCP with MCP Inspector
+## Revise it conversationally
 
-For developers building integrations or debugging tool responses, the MCP Inspector lets you see exactly what tools are exposed and what they return:
+Continue in the same conversation:
 
-```bash
-npx @modelcontextprotocol/inspector npx -y mcp-remote https://mcp.heygen.com/mcp/hyperframes
+```text
+Reveal the product two seconds earlier.
+Keep the current colors.
+Make the captions smaller and slow down the final transition.
 ```
 
-Complete the OAuth flow in the inspector's browser tab. Once authenticated, you can call each tool with custom parameters and see raw responses, including `tool_data` and `widget_data`.
+Name the visible problem and desired outcome. Avoid restarting the full brief for every revision.
 
-### Watch progress notifications
+## Render
 
-The MCP emits MCP `notifications/progress` events during long-running `compose` and `render_video` calls. The host (Claude.ai, ChatGPT, or Grok) displays them inline:
+Ask for the destination you need:
 
+```text
+Render this as an MP4 at 30 fps.
 ```
-You:    "make me a 30-second product intro"
-Agent:  [calls compose]
-  ↳ "Drafting outline..."           ← progress notification
-  ↳ "Selecting style..."            ← progress notification
-  ↳ "Generating HTML..."            ← progress notification
-  ↳ "Rendering preview frame..."    ← progress notification
-  ↳ [composition + player widget]
-Agent:  "Here's your video — [player]"
-```
-
-If progress stops mid-flow, the run failed. The agent's next message should explain what went wrong.
-
-### Common issues
-
-<AccordionGroup>
-  <Accordion title="OAuth keeps failing or loops">
-    Verify you're using the production URL: `https://mcp.heygen.com/mcp/hyperframes`. The dev URL (`mcp.dev.heygen.com`) only accepts dev accounts.
-
-    If OAuth completes but you see "not authorized" errors, your HeyGen account may not have access to the MCP — contact support or check your tier.
-  </Accordion>
-
-  <Accordion title="Render is stuck or never completes">
-    Renders normally finish in 10-90 seconds depending on length, fps, and format.
-
-    If `get_render_status` shows `status: rendering` for more than 5 minutes, something has stuck. Try:
-
-    1. Start a new chat thread
-    2. Run `compose("regenerate this composition")` — the underlying composition may reference an asset that's failing to load
-    3. If the issue persists, file an issue at [github.com/heygen-com/hyperframes/issues](https://github.com/heygen-com/hyperframes/issues) including the `job_id` from `render_video`
-  </Accordion>
-
-  <Accordion title='"Composition not found" error'>
-    The `composition_id` is owned by the HeyGen space (account) that created it. If you're signed into a different space, you can't access compositions from another. Run `list_compositions` to see what's available from your current account.
-  </Accordion>
-
-  <Accordion title="Player widget shows blank or loads forever">
-    Usually a transient connection issue between the widget and `mcp.heygen.com`. Refresh the chat or call `get_composition` again.
-
-    If it persists, your composition may reference a media asset that failed to upload — recreate the composition with `compose("regenerate this")`.
-  </Accordion>
-
-  <Accordion title="Out of credits">
-    The MCP returns an error with an upgrade URL when your credits are exhausted. Visit [heygen.com/pricing](https://heygen.com/pricing) to upgrade your tier.
-  </Accordion>
-
-  <Accordion title="Tool call timed out in the host">
-    `compose` runs can take 30+ seconds for complex prompts. If your client times out before the response comes back, the underlying run is likely still progressing — wait 30 seconds and run `list_compositions`. The composition is probably already created.
-  </Accordion>
-
-  <Accordion title="Agent ignored part of my prompt">
-    The agent prefers structural decisions (palette, layout, motion) over fine-grained pixel positioning. If a specific edit doesn't land, try rephrasing more directively:
 
-    - Less effective: *"the title is a little off"*
-    - More effective: *"move the title 40px down and increase its weight to 800"*
+MP4 is the normal sharing format. WebM can be useful for web delivery and transparent overlays. MOV can be useful for another editing workflow.
 
-    For pixel-precise control, use the [open-source CLI](/quickstart) — the MCP is optimized for fast natural-language iteration.
-  </Accordion>
-</AccordionGroup>
+The connector renders on hosted infrastructure. Keep any composition or render
+identifier the tool returns so you can refer to the same work in a follow-up.
 
-### Reporting issues
+OAuth connects the server to your current HeyGen account. Plans, limits, and
+billing can change independently of HyperFrames, so confirm them in the account
+before starting repeated or long renders.
 
-For bugs or feature requests, file an issue at [github.com/heygen-com/hyperframes/issues](https://github.com/heygen-com/hyperframes/issues). Include:
+## Current limits
 
-- The prompt you used
-- The `composition_id` and `job_id` (if applicable) — these are visible in the tool response details
-- A description of what you expected vs. what happened
-- The host (Claude.ai web/desktop, ChatGPT, Grok, etc.)
+- Rendering runs on HeyGen infrastructure. Use the local path when you need local rendering or self-hosting.
+- The exact tool list and result presentation depend on the deployed server and the chat host.
+- Hosted output does not give you the same local project folder, Studio surface, or debugging access as the local path.
+- Precise source and pixel-level editing belongs in the local project and Studio.
 
-## Limitations
+## Troubleshooting
 
-- **Cloud-only rendering.** All renders run on HeyGen infrastructure. Use the [CLI](/quickstart) if you need local rendering.
-- **Single-user.** Each composition is owned by one HeyGen account. No team sharing in v1.
-- **No binary uploads from chat.** You can reference assets you've already uploaded to HeyGen via the web UI, but the MCP does not currently accept new file uploads through chat. Upload via [app.heygen.com](https://app.heygen.com) first, then reference the asset by name.
-- **Aspect ratios:** `16:9`, `9:16`, `1:1`, `4:5`. Other ratios fall back to the closest match.
-- **No fine-grained editing tools.** Edits go through the agent. For pixel-precise control, use the [CLI](/quickstart) and a coding agent like Claude Code or Cursor.
-- **Widget rendering requires a host that supports MCP widgets.** Claude.ai web/desktop, ChatGPT (Apps SDK), and Grok support widgets today. Text-only MCP clients (Claude Code CLI, Cursor, Windsurf) will see a clickable preview URL instead — full text-mode support is on the roadmap.
+If authorization loops:
 
-## How this relates to the open-source framework
+1. confirm the production MCP address;
+2. disconnect and reconnect HyperFrames;
+3. confirm that your host plan and workspace permit the connector;
+4. confirm that pop-ups and the HeyGen sign-in window are not blocked.
 
-[HyperFrames itself is open source](https://github.com/heygen-com/hyperframes) — the HTML composition format, CLI, renderer, and player. You can use HyperFrames locally without the MCP.
+If a create or render action stalls:
 
-The MCP is a HeyGen-hosted product that wraps:
+1. keep the last tool result and any identifier it returned;
+2. retry from a new chat if the host session has expired;
+3. report the prompt, expected result, actual result, host, and identifier.
 
-- The HyperFrames composition agent (the LLM that authors compositions)
-- HeyGen's cloud rendering pipeline
-- HeyGen's asset libraries
-- OAuth, credits, and tier management
+Use [Share feedback](/guides/feedback) when the failure belongs to HyperFrames. Use the host product’s support when the connector cannot be installed or invoked at all.
 
-| You want… | Use… |
-|---|---|
-| Zero local install, fast natural-language authoring | The MCP |
-| Pixel-precise control, custom rendering, self-hosting | The [CLI](/quickstart) |
-| Both | Author with the MCP, then download and refine with the CLI (planned export feature) |
+<Warning>
+  Only connect the production HyperFrames server shown on this page. As with any external connector,
+  review the permissions and do not send secrets or private material that the destination should not
+  receive.
+</Warning>
 
-## Next steps
+## Related topics
 
-<CardGroup cols={2}>
-  <Card title="Quickstart" href="/quickstart">
-    Try HyperFrames locally with the open-source CLI.
-  </Card>
-  <Card title="Prompting guide" href="/prompting/overview">
-    Tips for getting the best results when working with AI agents.
-  </Card>
-  <Card title="Catalog" href="/catalog/blocks/data-chart">
-    Browse 50+ ready-to-use blocks the agent draws from.
-  </Card>
-  <Card title="Examples" href="/examples">
-    Reference compositions you can clone.
-  </Card>
-</CardGroup>
+- [Make a locally editable first video](/quickstart)
+- [Choose where to create](/guides/choose-creation-path)
+- [Share connector feedback](/guides/feedback)
diff --git a/docs/guides/media-effects.mdx b/docs/guides/media-effects.mdx
index fcfcb24f18..b2756c6d19 100644
--- a/docs/guides/media-effects.mdx
+++ b/docs/guides/media-effects.mdx
@@ -1,323 +1,108 @@
 ---
-title: Media Effects
-description: "Apply deterministic shader effects to video and image media, combine them with color grading, and animate supported strengths with GSAP."
+title: "Apply media effects"
+sidebarTitle: "Media effects"
+description: "Apply editable blur, bloom, retro, print, glitch, and art treatments to images and video."
 ---
 
-Use Media Effects to transform real `<video>` and `<img>` pixels with
-deterministic blur, retro, print, and art treatments that can share one payload
-with [Color Grading](/guides/color-grading).
+Media effects transform a selected image or video without baking a new source
+file. They stay editable in Studio and render from the same project data.
 
-## Effect Families
+<Frame caption="Four current HyperFrames renders from one source. Effects stay on the media element, so the original file remains unchanged.">
+  <img
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/media-effects-grid-v1.png"
+    alt="One presenter frame shown as the original, pixelated, two-ink print, and ASCII treatments"
+  />
+</Frame>
 
-### Essentials
+## Choose the effect
 
-| Effect | What it does |
-| --- | --- |
-| Blur | Defocuses or softens the complete media layer |
-| Pixelate | Converts the layer into a block mosaic |
-| Bloom | Adds thresholded glow around bright regions |
+| Intent                                                  | Start with                         |
+| ------------------------------------------------------- | ---------------------------------- |
+| Soften, conceal, or lift bright areas                   | Blur, Pixelate, or Bloom           |
+| Add tape, film, CRT, or digital damage                  | Retro & Glitch                     |
+| Turn media into dots, ink, or a limited palette         | Print                              |
+| Create ASCII, engraving, crosshatch, or painted media   | Art                                |
+| Add grain or darkened edges                             | Grain or Vignette in Color Grading |
+| Add a HUD, light leak, flash, or freeze-frame treatment | A [Catalog](/catalog) overlay      |
 
-### Retro & Glitch
+Effects apply to the complete selected media element. They do not track a face,
+screen, or object. Isolate a region into its own cropped or masked media layer
+when only that region should change.
 
-| Effect | What it does |
-| --- | --- |
-| Chroma Softening | Smears chroma while retaining central luma |
-| Tape Damage | Adds deterministic tracking errors, noise, ghosting, and dropouts |
-| Film Artifacts | Adds deterministic dust and short scratches |
-| Scanlines | Adds configurable horizontal display lines |
-| CRT Curvature | Warps media toward curved display geometry |
-| Channel Separation | Offsets color channels along an angle |
-| Digital Glitch | Combines line tears, blocks, displacement, pixelation, and channel split |
+## Try effects in Studio
 
-When authoring JSON directly, **Chroma Softening** uses `chromaBleed` and
-**Channel Separation** uses `chromaticAberration`. Query the capability command
-for the canonical payload keys of all other controls.
+Select an image or video and open **Effects** in the Inspector. The effect
+browser is grouped into:
 
-### Print
+- **Essentials:** Blur, Pixelate, Bloom
+- **Retro & Glitch:** Chroma Softening, Tape Damage, Film Artifacts, Scanlines,
+  CRT Curvature, Channel Separation, Digital Glitch
+- **Print:** Halftone, Two-Ink Print, Ordered Dither, Mono Screen
+- **Art:** ASCII, Engraving, Crosshatch, Kuwahara Paint
 
-| Effect | What it does |
-| --- | --- |
-| Halftone | Renders source color through a print-dot raster |
-| Two-Ink Print | Reduces media to the built-in two-ink treatment |
-| Ordered Dither | Quantizes media into an ordered limited palette |
-| Mono Screen | Builds monochrome dot, shape, or line artwork |
+Choose one effect for the job, adjust its controls, then play or scrub the
+beginning, middle, and end. Some effects are much more expensive to render than
+others, especially Blur, Bloom, and Kuwahara Paint across large media layers.
 
-### Art
+## Ask the agent
 
-| Effect | What it does |
-| --- | --- |
-| ASCII | Renders media as configurable procedural glyph cells |
-| Engraving | Translates luminance into directional engraved lines |
-| Crosshatch | Translates media into layered hand-hatched lines |
-| Kuwahara Paint | Applies edge-preserving painterly smoothing |
+Describe the result instead of guessing control values:
 
-## Quick Start
-
-<Tabs>
-  <Tab title="Studio">
-    <Steps>
-      <Step title="Select real media">
-        Select a real `<img>` or `<video>` in the preview, Layers panel, or
-        Timeline. Effects do not appear for arbitrary divs or CSS background
-        images.
-      </Step>
-      <Step title="Choose and tune an effect">
-        Preview an effect preset or open **Effects**. Enabling an effect uses a
-        calibrated default; expand it to adjust only the controls relevant to
-        the intended result.
-      </Step>
-      <Step title="Verify motion and framing">
-        Play and scrub videos at the beginning, middle, and end. Confirm that
-        moving effects and object-fit/object-position framing remain correct.
-      </Step>
-    </Steps>
-  </Tab>
-  <Tab title="Agent / CLI">
-    Discover the narrow effect contract, then apply the complete treatment in
-    one mutation:
-
-    ```bash Terminal
-    npx hyperframes media-treatment --capabilities --json
-    npx hyperframes media-treatment --capability digitalGlitch --json
-
-    npx hyperframes media-treatment \
-      --project . \
-      --file compositions/scene.html \
-      --selector '#hero' \
-      --grading '{"effects":{"digitalGlitch":0.55,"digitalGlitchColorSplit":0.25,"digitalGlitchLineTear":0.25,"digitalGlitchPixelate":0.15,"digitalGlitchBlockAmount":0.5,"digitalGlitchBlockDisplacement":0.25,"digitalGlitchSpeed":0.5}}' \
-      --apply \
-      --json
-    ```
-  </Tab>
-</Tabs>
-
-Project-local media is recommended; remote media requires compatible CORS.
-[Media Overlays](/guides/media-overlays) are separate editable composition
-layers rather than shader properties.
-
-<Warning>
-  Media Effects use the SDR/Rec.709 shader pipeline. Studio can preview that
-  pipeline on browser-decoded HDR media, but native HDR rendering preserves the
-  HDR source separately and does not apply these SDR effects to native HDR
-  layers. Convert or tone-map to SDR when an effect must appear in the final
-  output. See [Color Grading support](/guides/color-grading#support-matrix) and
-  [HDR Rendering](/guides/hdr).
-</Warning>
-
-## Effect Presets
-
-`Creator Camcorder`, `VHS Playback`, `8mm Home Movie`, `Editorial Halftone`, and
-`Two-Ink Print` provide tested combinations of effect, correction, and
-finishing settings. Preview one as a starting point, then tune the underlying
-controls. They are normal shader payloads, not baked media or bundled LUTs.
-
-## Agent Guidance
-
-Agents should discover only the part of the toolbox relevant to the user's
-intent:
-
-The user may simply ask for _"an old home-video feel"_, _"a useful privacy
-reveal"_, or _"something more graphic for this poster."_ The `media-use` skill
-classifies that intent, then queries the narrow effect or recipe details instead
-of loading the exhaustive contract.
-
-```bash Terminal
-npx hyperframes media-treatment --capabilities --json
-npx hyperframes media-treatment --capability retro-glitch --json
-npx hyperframes media-treatment --capability digitalGlitch --json
-```
-
-The concise overview lists capability families. A focused query returns the
-effect's calibrated apply payload, controls, render lane, palette support, and
-seek-safe animation path. Use the canonical payload instead of guessing
-sub-control defaults.
-
-Recipes are tested shortcuts, not a closed list. An agent may assemble a custom
-payload when the source and intent justify it, but it should:
-
-1. Choose one primary visual intent.
-2. Query the exact effect or family contract.
-3. Add only controls that visibly support that intent.
-4. Avoid stacking several dominant stylizations without a reason.
-5. Verify representative frames and a short render.
-
-## Palettes
-
-`palette` accepts two to six exact `#RRGGBB` colors in authored order.
-Dark-to-light order creates normal luminance mapping; reversing the array
-intentionally inverts that mapping.
-
-```json data-color-grading
-{
-  "effects": {
-    "dither": 1,
-    "ditherSize": 0.5
-  },
-  "palette": ["#080717", "#3c185f", "#d9339f", "#ff6b66", "#aafae0"]
-}
+```text
+Make this product clip feel like a clean two-ink editorial print.
+Keep the product shape and label readable.
 ```
 
-Compatible effects are ASCII, Ordered Dither, Mono Screen, Engraving, and
-Crosshatch. A palette alone does not activate an effect.
-
-Discover built-in palettes without copying their values into instructions:
+The agent can inspect the live capability catalog before editing:
 
-```bash Terminal
-npx hyperframes media-treatment --capability palettes --json
-npx hyperframes media-treatment --capability electric-ink --json
+```bash
+npx hyperframes media-treatment --capabilities --json
+npx hyperframes media-treatment --capability twoInkPrint --json
 ```
 
-## Animation and Keyframes
-
-The following paths have seek-safe CSS custom properties and may be animated by
-a paused, registered GSAP timeline:
+Then it can apply a validated patch:
 
-- Global treatment intensity
-- LUT intensity
-- Exposure
-- Blur
-- Bloom
-- Kuwahara Paint
-- Pixelate
-- ASCII
-- Ordered Dither
-
-Example blur-to-focus reveal:
-
-```html index.html
-<div
-  class="clip"
-  data-composition-id="media-effect-demo"
-  data-start="0"
-  data-duration="4"
->
-  <video
-    id="hero"
-    src="assets/hero.mp4"
-    muted
-    playsinline
-    style="--hf-color-grading-blur: 0.8"
-    data-color-grading='{"effects":{"blur":0.8}}'
-  ></video>
-</div>
-
-<script>
-  const tl = gsap.timeline({ paused: true });
-  tl.to(
-    "#hero",
-    {
-      "--hf-color-grading-blur": 0,
-      duration: 1.2,
-      ease: "power2.out",
-    },
-    0,
-  );
-  window.__timelines = window.__timelines || {};
-  window.__timelines["media-effect-demo"] = tl;
-</script>
+```bash
+npx hyperframes media-treatment \
+  --selector '#product' \
+  --grading '{"preset":"two-ink-print"}' \
+  --apply --json
 ```
 
-Author the initial custom-property value inline. Do not use timers, unseeded
-randomness, frame-zero `set()` calls, or `onUpdate` callbacks. Query an effect's
-focused capability to get its exact animation property and range.
-
-Tape damage, digital glitch, film artifacts, and similar effects may contain
-deterministic internal motion even when their overall strength is not one of
-the keyframeable paths above.
+Use `--dry-run` to inspect the exact mutation without writing, `--analyze` for
+bounded source measurements and a suggested primary correction, or `--clear`
+to remove the selected treatment. The command writes the same
+`data-color-grading` contract that Studio uses.
 
-## Important Effect Behavior
+## Keep the treatment useful
 
-- **Tape Damage** is the primary analog-tape amount. Tracking controls moving
-  tears, Noise controls row jitter/noise, and Speed controls their deterministic
-  motion. Those subordinate controls do not activate tape damage by themselves.
-- **Film Artifacts** adds sparse deterministic dust and scratches. Grain,
-  vignette, color, and optional wrapper motion such as a subtle gate weave are
-  separate choices.
-- **Halftone** uses fixed print-oriented channel angles and edge behavior.
-  Cell size remains adjustable.
-- **Two-Ink Print** is HyperFrames' own fixed two-ink mapping. Do not describe
-  it as a named commercial print process or stack it with Halftone by default.
-- **ASCII** uses procedural glyph cells. Size, style, ink behavior, rotation,
-  and a compatible palette remain configurable.
-- **Ordered Dither** uses a temporally stable 4x4 Bayer matrix. It is not
-  Floyd-Steinberg or another sequential error-diffusion algorithm.
-- **Bloom** extracts bright regions before blurring them; it is different from
-  raising highlights or whites.
-- **Kuwahara Paint** smooths regions while preserving major edges. Radius,
-  sharpness, and saturation shape the result.
+- Use blur or pixelation for a real reveal, focus shift, or privacy need.
+- Use a named stylization strongly enough to read; keep ordinary correction
+  restrained.
+- Compare against the original and inspect representative rendered frames.
+- Remove the treatment when it competes with the story.
 
-## Deterministic Pipeline Order
+## Performance and delivery
 
-HyperFrames evaluates combined treatment stages in one fixed order:
+Several overlapping, full-frame treated layers can slow preview and rendering,
+especially at 4K. Simplify the stack or pre-render a finished layer when
+playback drops frames.
 
-1. Source framing and multipass Blur/Kuwahara preparation
-2. Chromatic and digital-glitch transforms
-3. Primary correction, color grading, and LUT blended by global intensity
-4. Grain and film artifacts
-5. Mono, engraving, crosshatch, halftone, two-ink, dither, and ASCII
-6. Bloom, scanlines, vignette, and CRT display masking
-7. Before/after comparison
+Effects use the SDR/Rec.709 shader pipeline. Native HDR delivery preserves HDR
+source pixels through a separate path, so these SDR effects do not appear on
+native HDR layers. Convert or tone-map to SDR when the effect must appear in
+the final result.
 
-The order cannot currently be rearranged. A fixed order keeps Studio,
-playback, seeking, and final rendering deterministic and prevents agents from
-inventing incompatible effect graphs.
-
-## Performance
-
-Performance follows the number of treated pixels and the selected render lane,
-not only the number of elements.
-
-- Blur, Bloom, and Kuwahara use multipass rendering.
-- Several tiled media elements can be cheaper than several overlapping
-  full-frame elements.
-- When more than two full-frame multipass-treated elements are visible
-  together, verify continuous playback on the target machine.
-- Simplify or pre-render a stack when preview frames drop.
-- Kuwahara uses bounded half-float intermediate targets when supported and
-  otherwise reports itself unavailable.
-
-For 4K delivery, verify the effect at the final composition size. Resolution-
-aware effects preserve their intended scale, but 4K still processes more pixels
-than 1080p.
-
-## Low-Level HTML Contract
-
-Media effects live in the same persisted contract as grading:
-
-```html index.html
-<img
-  id="poster"
-  src="assets/poster.jpg"
-  data-color-grading='{
-    "effects":{
-      "ascii":1,
-      "asciiSize":0.066,
-      "asciiStyle":0,
-      "asciiColor":1,
-      "asciiRotation":0
-    },
-    "palette":["#001100","#00ff00"],
-    "colorSpace":"rec709"
-  }'
-/>
-```
+Project-local media is the reliable default. Remote media must allow browser
+pixel access through compatible CORS headers.
 
-Unknown keys are rejected and values are normalized by the Core contract. The
-CLI should remain the primary authoring surface for agents.
+The [Color Grading guide](/guides/color-grading) covers correction, wheels,
+curves, selective color, finishing, and LUTs. The [HTML
+schema](/reference/html-schema#color-grading-and-media-effects) contains the
+persistence contract.
 
-## Next Steps
+## Related topics
 
-<CardGroup cols={2}>
-  <Card title="Color Grading" icon="palette" href="/guides/color-grading">
-    Correct and grade media with scopes, wheels, curves, selections, and LUTs.
-  </Card>
-  <Card title="Media Overlays" icon="layer-group" href="/guides/media-overlays">
-    Add authored HUD, flash, light-leak, and freeze-frame layers.
-  </Card>
-  <Card title="Keyframes" icon="diamond" href="/guides/keyframes">
-    Edit and verify deterministic GSAP animation in Studio.
-  </Card>
-  <Card title="Performance" icon="gauge-high" href="/guides/performance">
-    Diagnose source resolution, browser, decoder, and composition cost.
-  </Card>
-</CardGroup>
+- [Color grade images and footage](/guides/color-grading)
+- [Use images and video](/guides/video-components)
+- [Browse ready-made visual effects](/catalog)
diff --git a/docs/guides/open-design-hyperframes.md b/docs/guides/open-design-hyperframes.md
index b56bc07a15..2bd57d7e40 100644
--- a/docs/guides/open-design-hyperframes.md
+++ b/docs/guides/open-design-hyperframes.md
@@ -414,7 +414,7 @@ as the canonical reference and follow its patterns verbatim:
 - HDR / wide-gamut color handling
 - Audio-reactive animation (`hf-seek` + `window.__hfAudio`)
 - Captions / TTS integration
-- The `hyperframes add` registry (50+ blocks and components)
+- The `hyperframes add` registry of blocks and components
 
 This skill stays focused on what Open Design needs at emission time — the
 structural rules, the active-`DESIGN.md` binding, and the 5-dim self-critique
diff --git a/docs/guides/performance.mdx b/docs/guides/performance.mdx
index f8f1c4c87a..a2885f83b8 100644
--- a/docs/guides/performance.mdx
+++ b/docs/guides/performance.mdx
@@ -1,139 +1,64 @@
 ---
-title: Performance
-description: "How to keep preview playback smooth and diagnose expensive compositions."
+title: Fix a slow preview or render
+description: Find the expensive part of a composition and make it cheaper.
 ---
 
-Preview plays your composition in real time, so any frame that takes longer than 33ms (at 30fps) shows up as stutter. This page covers the patterns that blow that budget and how to spot them.
+A finished render can be smooth even when preview stutters. Preview must draw each frame in real time; render can take as long as it needs to capture the same frames.
 
-## Preview vs. render
+## Start with the symptom
 
-Render captures frames one at a time and stitches them into a video. Slow frames make the render take longer, but you never see the pauses — you watch the finished mp4.
+| What you see | Check first |
+| --- | --- |
+| Preview stutters in one scene | Large blurs, masks, shadows, or many animated layers in that scene |
+| Preview pauses the first time an image appears | Oversized source images or image decoding |
+| The whole page becomes slow | Script work, layout thrashing, or too many DOM nodes |
+| Render is slow but the result is correct | Source-video extraction, frame capture, or encoding |
+| WebM takes much longer than MP4 | VP9 encoding; transparent WebM is CPU-heavy |
 
-Preview does the same work in real time. If a frame takes 200ms to paint, you see a 200ms freeze.
+## Reduce expensive browser work
 
-This is why "render looks fine, preview stutters" is expected for paint-heavy compositions. It doesn't mean preview is broken — it means individual frames are too expensive for real-time playback.
+- Use fewer large `backdrop-filter` and `filter: blur()` layers.
+- Avoid animating dozens of shadowed elements at once.
+- Replace a static blur or texture stack with a pre-rendered image.
+- Size images near their actual delivery dimensions. A very large JPEG still decodes into a very large bitmap.
+- Keep work inside animation callbacks small. Do not repeatedly read layout and write styles in the same frame.
 
-## Expensive CSS patterns
+For a 1920×1080 composition, a 3840×2160 source already provides enough detail for a 2× display. Larger sources usually add memory and decode work without improving the frame.
 
-These are the patterns that most often cause preview to drop below 30fps.
+## Measure instead of guessing
 
-### backdrop-filter: blur()
+1. Run `npx hyperframes preview`.
+2. Open Chrome DevTools and select **Performance**.
+3. Record the part that stutters.
+4. Inspect the longest tasks:
+   - **Paint** or **Composite Layers** points to filters, shadows, masks, or large layers.
+   - **Layout** or **Recalculate Style** points to layout work.
+   - **Script** points to author code.
 
-Each `backdrop-filter: blur(radius)` sampled over a large area forces the compositor to read pixels from behind the element, run a blur kernel across them, and composite the result. Cost scales with both the blurred area and the radius.
+Change one expensive feature, record again, and keep the version that moves the bottleneck.
 
-Stacked blur layers multiply the cost. Eight layers at progressively larger radii (1, 2, 4, 8, 16, 32, 64, 128px) will happily take 200ms per frame over a 1920x1080 region on mid-tier GPUs.
+## Make a fast review render
 
-**What to do:**
-- Keep stacked layers to 2-3 maximum, with manually tuned radii
-- Avoid `blur(128px)` or `blur(64px)` over large areas — the biggest radii dominate the cost
-- For a static blur, render it once into a PNG and use a regular `<img>` overlay
-
-### filter: blur() and filter: drop-shadow()
-
-Same story as `backdrop-filter` but applied to the element itself rather than behind it. Fine on small elements, expensive on large ones.
-
-### Shadows on many elements
-
-`box-shadow` and `text-shadow` on a few elements are fine. On dozens of elements that also animate, the compositor re-rasterizes each shadowed layer on every frame.
-
-### Large gradients with mask-image
-
-Combined with `backdrop-filter`, `mask-image` can force additional compositor passes. If you have both on the same element, consider whether you need both.
-
-## Image sizing
-
-Image source resolution matters more than file size. Chrome decodes JPEGs and PNGs to raw RGBA bitmaps before displaying them — a decoded bitmap is:
+If the composition is intentionally too heavy for real-time playback, review an encoded file:
 
+```bash
+npx hyperframes render --quality draft --output review.mp4
 ```
-bitmap_bytes = width × height × 4
-```
-
-A 7000×5000 source image is 140MB decoded, regardless of whether the JPEG on disk is 2MB or 5MB.
-
-**Rule of thumb:** resize source images to at most 2x the canvas dimensions. For a 1920x1080 canvas, 3840x2160 source images are already overkill. Anything above that is paying for memory and texture-upload cost that never shows on screen.
-
-```bash Terminal
-# ImageMagick one-liner to downsize a directory of images
-mogrify -path resized -resize 3840x3840\> *.jpg
-```
-
-## Measuring a slow composition
-
-Don't guess — measure. Chrome DevTools has everything you need.
 
-<Steps>
-  <Step title="Run preview">
-    Start the preview server and open it in Chrome:
+Use `standard` or `high` for delivery. Draft changes capture and encoder quality; it does not change the composition's timing.
 
-    ```bash Terminal
-    npx hyperframes preview
-    ```
-  </Step>
-  <Step title="Open DevTools → Performance">
-    `Cmd+Option+I` (macOS) or `Ctrl+Shift+I` (Linux/Windows), then switch to the **Performance** tab.
-  </Step>
-  <Step title="Record during playback">
-    Hit the record button, click play in the preview, let it run 3-5 seconds through the jank-prone scene, then stop recording.
-  </Step>
-  <Step title="Read the main thread track">
-    Look for long tasks (red-flagged in the timeline). Expand the tallest bars and check what Chrome labels them:
+## Tune transparent WebM only when needed
 
-    - **Composite Layers / Paint** with a large duration = compositor cost (backdrop-filter, shadows, large textures)
-    - **Decode Image** = image decode on first paint (rare in Chrome 131+, images decode off-thread by default)
-    - **Layout / Recalculate Style** = layout thrashing from script
-    - **Script** = JS work (rare for compositions, check author scripts)
-  </Step>
-</Steps>
+WebM uses the CPU-heavy VP9 encoder. The default is suitable for most work. To trade more encoding time for compression quality:
 
-Once you know which category dominates, you know what to change.
-
-<Tip>
-  A composition that runs at 60fps in isolation but stutters only during specific scenes is usually a composite-cost problem. Check which layers become visible during those scenes.
-</Tip>
-
-## When preview is unavoidable slow
-
-Some compositions are legitimately too expensive for real-time playback. If you've reduced what you can and preview still stutters, render-to-mp4 and watch the output is a fine workflow — render is still accurate.
-
-```bash Terminal
-npx hyperframes render --quality draft --output preview.mp4
-```
-
-Draft quality renders fast and is visually close to the final render for everything except encoder-level detail.
-
-## WebM encode speed
-
-Transparent WebM output uses FFmpeg's `libvpx-vp9` encoder. VP9 is CPU-heavy, so short overlay renders can spend most of their wall time in the encode stage even when frame capture is fast.
-
-HyperFrames sets `-cpu-used 4` for VP9 by default. On a devbox check using an 8s 1280×720, 15fps VP9-alpha encode, explicit `-cpu-used 4` cut encode time from 6.3s to 2.6s versus libvpx's default, with SSIM 0.9986 and PSNR 50.5dB against the default encode. Your composition and host CPU will move those numbers, but the direction is consistent: higher values trade some compression efficiency for faster WebM encodes.
-
-Tune per deployment with:
-
-```bash Terminal
-PRODUCER_VP9_CPU_USED=2 npx hyperframes render --format webm --output overlay.webm
+```bash
+npx hyperframes render --format webm --vp9-cpu-used 2 --output overlay.webm
 ```
 
-For one-off local renders, pass the same value directly:
+`--vp9-cpu-used` accepts integers from `-8` to `8`; higher values are faster with a larger quality/size tradeoff.
 
-```bash Terminal
-npx hyperframes render --format webm --vp9-cpu-used 2 --output overlay.webm
-```
+## Related topics
 
-Valid values are integers from `-8` to `8`; HyperFrames clamps out-of-range values before passing them to FFmpeg.
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
-    Environment, tooling, and rendering issues
-  </Card>
-  <Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
-    Composition pitfalls that break rendering
-  </Card>
-  <Card title="Rendering" icon="film" href="/guides/rendering">
-    Rendering modes, options, and flags
-  </Card>
-  <Card title="CLI Reference" icon="terminal" href="/packages/cli">
-    Full list of CLI commands
-  </Card>
-</CardGroup>
+- [Diagnose a failed or stalled render](/guides/troubleshooting)
+- [Render from the command line](/guides/rendering)
+- [Render at 4K](/guides/4k-rendering)
diff --git a/docs/guides/remove-background.mdx b/docs/guides/remove-background.mdx
index 3a6f80f579..cc5d2ff49c 100644
--- a/docs/guides/remove-background.mdx
+++ b/docs/guides/remove-background.mdx
@@ -1,424 +1,120 @@
 ---
-title: Remove Background (transparent video)
-description: "Remove the background from a video or image and drop it into any composition as a transparent overlay."
+title: "Remove a background"
+description: "Turn footage of a person or a portrait image into transparent media you can layer over a HyperFrames scene."
 ---
 
-Background removal — also called *matting* in VFX — separates a foreground subject (typically a person) from its background. The output is a video with an alpha channel: fully transparent where the background was, opaque where the subject is. Drop it into any HyperFrames composition as a `<video>` tag and the subject floats over whatever you put behind them.
+Use background removal when a person needs to appear over designed text,
+graphics, or another scene. HyperFrames runs the included human-segmentation
+model locally; it does not upload the source or require an API key.
 
-The CLI ships a built-in `remove-background` command that runs locally — no API keys, no cloud upload, no green screen.
+<Frame caption="The same real frame before and after the local model. The softer hair and hand edges are the model’s actual limit on this source.">
+  <img
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/remove-background-before-after-v1.png"
+    alt="The original presenter frame beside its transparent cutout over a green background"
+  />
+</Frame>
 
-## Quick Start
+## Create the transparent file
 
-<Steps>
-  <Step title="Verify ffmpeg is installed">
-    The pipeline needs `ffmpeg` and `ffprobe` for decode + encode. Most systems already have them; if not:
+Make sure FFmpeg is installed, then run:
 
-    ```bash Terminal
-    # macOS
-    brew install ffmpeg
-
-    # Ubuntu / Debian
-    sudo apt install ffmpeg
-    ```
-
-    Confirm with `npx hyperframes doctor` — both should be green.
-  </Step>
-  <Step title="Remove the background from your video">
-    ```bash Terminal
-    npx hyperframes remove-background subject.mp4 -o transparent.webm
-    ```
-
-    On the first run, the CLI downloads ~168 MB of model weights to `~/.cache/hyperframes/background-removal/models/`. Subsequent runs reuse the cache.
-
-    Output:
-
-    ```
-    ◇  Removed background from 240 frames in 38.4s (6.3 fps, CoreML) → ./transparent.webm
-    ```
-  </Step>
-  <Step title="Drop it into a composition">
-    The output is a standard VP9-with-alpha WebM. Chrome's `<video>` element decodes the alpha plane natively — no special player needed:
-
-    ```html composition.html
-    <div class="scene">
-      <!-- background layer -->
-      <img src="city.jpg" class="bg" />
-
-      <!-- transparent subject floats on top -->
-      <video src="transparent.webm" autoplay muted loop playsinline></video>
-    </div>
-    ```
-
-    Render the composition with the usual `hyperframes render`.
-  </Step>
-</Steps>
-
-## How it works
-
-The pipeline runs four stages, all locally:
-
-```
-ffmpeg decode  →  u²-net_human_seg inference  →  alpha composite  →  ffmpeg encode
-   (raw RGB)         (320×320 mask, then upsampled)                    (VP9-alpha)
+```bash
+npx hyperframes remove-background subject.mp4 -o subject.webm
 ```
 
-The model is **u²-net_human_seg** (MIT license, ~168 MB ONNX). It runs through `onnxruntime-node` with the best-available execution provider on your machine: CoreML on Apple Silicon, CUDA on NVIDIA, CPU otherwise.
-
-The output is encoded with the exact ffmpeg flags Chrome's `<video>` element needs to decode alpha — `-pix_fmt yuva420p` plus the `alpha_mode=1` metadata tag. Get those wrong and the alpha plane is silently discarded by browsers.
+The first run downloads the model. Later runs reuse it.
 
-## Output formats
+Choose the output by destination:
 
-| Extension | Codec | When to use | Size (4s @ 1080p) |
-|-----------|-------|-------------|-------------------|
-| `.webm` (default) | VP9 with alpha | Drop into `<video>` for HTML5-native transparent playback | ~1 MB |
-| `.mov` | ProRes 4444 with alpha | Editing round-trip in Premiere / Resolve / Final Cut | ~50 MB |
-| `.png` | PNG with alpha | Single-image cutout (only when the input is also a single image) | varies |
+| Output              | Use it for                                                       |
+| ------------------- | ---------------------------------------------------------------- |
+| Transparent `.webm` | A subject layered inside a web or HyperFrames composition        |
+| Transparent `.mov`  | A ProRes 4444 round trip through Premiere, Resolve, or Final Cut |
+| Transparent `.png`  | A single portrait image                                          |
 
-```bash Terminal
-npx hyperframes remove-background subject.mp4 -o transparent.webm        # web playback
-npx hyperframes remove-background subject.mp4 -o transparent.mov         # editing
-npx hyperframes remove-background portrait.jpg -o cutout.png       # still image
+```bash
+npx hyperframes remove-background subject.mp4 -o subject.mov
+npx hyperframes remove-background portrait.jpg -o portrait.png
 ```
 
-## Layer separation: emit the cutout and the background plate together
-
-Pass `--background-output` (alias `-b`) to write a *second* transparent video alongside the cutout. Same source RGB, alpha is the *inverse* mask — opaque where the surroundings were, transparent where the subject is. The result is a clean two-layer separation in a single inference pass:
-
-```bash Terminal
-npx hyperframes remove-background subject.mp4 \
-  -o subject.webm \
-  --background-output plate.webm
-```
-
-| Output | Alpha | Use it as |
-| ------ | ----- | --------- |
-| `subject.webm` | Mask — subject opaque | Foreground layer (top of stack) |
-| `plate.webm` | `255 − mask` — subject region transparent | Background layer; place anything you want **under the subject's silhouette** between this and `subject.webm` |
-
-Both encoders share the source W/H/fps and your `--quality` preset, so the layers are pixel-aligned. Encode cost roughly doubles; segmentation cost is unchanged.
-
-<Tip>
-**This is a hole-cut plate, not an inpainted clean plate.** The subject region in `plate.webm` is fully transparent — you have to composite something opaque under it (a graphic, a blurred copy, a different scene) to fill the hole. If you need an actual filled background where the subject was, use a video inpainter (LaMa, ProPainter, RunwayML Inpaint) — `remove-background` is not the right tool for that.
-</Tip>
-
-### Hole-cut vs. clean plate — when does the difference matter?
-
-A **hole-cut plate** keeps the original surroundings and makes the subject region transparent. A **clean plate** fills the subject region with reconstructed background — produced by a separate inpainting model. Display each alone over black:
-
-| | Hole-cut plate (this command) | Clean plate (inpainted) |
-| --- | --- | --- |
-| Subject region | Transparent silhouette | Reconstructed background pixels |
-| What you see alone | A person-shaped hole | An empty room |
-| Cost | One inference pass, one extra ffmpeg encode | A second model (LaMa, ProPainter, E2FGVI) |
-| Tool | `remove-background --background-output` | Outside this CLI |
+## Use the cutout
 
-The line is: **does anything ever need to be visible *through* the subject's silhouette where the subject used to be?**
+Import the transparent file into the project and place it above the
+background, text, or graphic it should cover. Then check the complete clip,
+especially hair, hands, fast movement, and the first and last frames.
 
-| Use case | What you need |
-| --- | --- |
-| Text/graphics live *between* the cutout and the plate (the example above) | **Hole-cut** — the graphics fill the hole. |
-| Composite the subject onto an unrelated scene | Neither. Just use `subject.webm`; the plate is irrelevant. |
-| Show "the room without the person" as a real background | **Clean plate** — a hole-cut plate would show a transparent void. |
-| Replace the person with a different subject (re-target) | **Clean plate** — the new subject needs real pixels under it. |
-| VFX rotoscoping / "remove an extra from this take" | **Clean plate** — the canonical inpainting use case. |
-
-If something opaque always covers the silhouette, hole-cut is sufficient and ~1000× cheaper than running an inpainter.
-
-### The two-layer composition pattern
-
-The two-layer pattern is functionally a drop-in for [text-behind-subject](#text-behind-subject-the-recommended-layout) without needing the original `presenter.mp4` in the project — the plate replaces it as the bottom layer:
-
-```html
-<!-- z=1 inverse-alpha plate fills everything except the subject's silhouette -->
-<video src="plate.webm" data-start="0" data-duration="6" data-track-index="0" muted playsinline></video>
-
-<!-- z=2 anything you want occluded by the subject lives here -->
-<h1 style="z-index:2; position:absolute; top:50%; left:50%; transform:translate(-50%,-50%);">
-  MAKE IT IN HYPERFRAMES
-</h1>
-
-<!-- z=3 the cutout puts the subject back on top -->
-<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
-  <video src="subject.webm" data-start="0" data-duration="6" data-track-index="1" muted playsinline></video>
-</div>
-```
-
-Constraints: the flag requires a video input and `.webm` or `.mov` for both outputs. It's not valid for image inputs (no temporal pairing to do) and won't accept `.png` for the plate.
-
-## Performance
-
-Real-world numbers from the [matting eval](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654), running u²-net_human_seg on a 4-second 1080p clip:
-
-| Platform | Provider | ms/frame | 30-second clip |
-|----------|----------|----------|----------------|
-| Apple Silicon (M2 Pro / M3 / M4) | CoreML | ~263 | ~2 min |
-| NVIDIA GPU (T4, A10, RTX) | CUDA | ~80–150 | ~30–60 s |
-| Linux x86 | CPU | ~1100 | ~16 min |
-| macOS Intel | CPU | ~900 | ~13 min |
-
-Matting is offline preprocessing — you run it once per asset and reuse the output. CPU-only is slow but always works; if you reuse the same subject clip repeatedly, run it once on a faster machine and check the transparent output into your project.
-
-## Picking a device explicitly
-
-`--device auto` is the default and right for almost everyone. The flag exists for two cases:
-
-- **Force CPU on a GPU box** when you want to keep the GPU free for other work, or are debugging an EP-specific issue:
-
-  ```bash Terminal
-  npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
-  ```
-
-- **Opt into CUDA** by setting `HYPERFRAMES_CUDA=1` and providing a GPU-enabled `onnxruntime-node` build (the bundled build is CPU + CoreML only, to keep the install small for the 99% of users who don't have a GPU):
-
-  ```bash Terminal
-  HYPERFRAMES_CUDA=1 npx hyperframes remove-background subject.mp4 -o transparent.webm --device cuda
-  ```
-
-Run `npx hyperframes remove-background --info` to see what providers are detected on your machine and which one `auto` would pick.
-
-## Using the transparent video in a composition
-
-The transparent WebM behaves like any other video element. The two patterns you'll use most:
-
-**Subject over a background image:**
-
-```html
-<div style="position: relative; width: 1920px; height: 1080px;">
-  <img src="background.jpg" style="position: absolute; inset: 0;" />
-  <video
-    src="transparent.webm"
-    autoplay
-    muted
-    loop
-    playsinline
-    style="position: absolute; right: 80px; bottom: 0; height: 90%;"
-  ></video>
-</div>
-```
-
-**Subject over a HyperFrames scene:**
-
-```html
-<!-- scene contents (text, animations, etc.) -->
-<div class="title-card">Welcome</div>
-
-<!-- subject layered on top -->
-<video src="transparent.webm" autoplay muted loop playsinline class="subject"></video>
-```
-
-The cutout inherits the composition's frame rate and timeline — it plays through once during the scene's duration, so match the source clip length to the scene length when possible. If the scene is longer than the clip, `loop` handles it.
-
-<Tip>
-  When rendering a composition that contains a `<video>` element, the renderer reads the source via ffmpeg internally. Transparent WebMs are decoded with the alpha plane preserved.
-</Tip>
+If you animate the subject, animate a wrapper around the video. This keeps the
+transparent media and the composition’s timing behavior together.
 
 ## Compositing patterns and pitfalls
 
-The cutout webm is a **re-encoded copy** of the source mp4's RGB — the matter pipeline decodes the source to raw RGB, runs segmentation, and re-encodes to VP9 with alpha. That choice has consequences depending on what you put behind it.
-
-### The three patterns
-
-| Pattern | Behind the cutout | Result |
-|---|---|---|
-| **Cutout over a different scene** *(most common)* | Static image, gradient, animated bg, or unrelated footage | Clean. The cutout is the only source of the subject — no doubling, no edge halo. Use any `--quality`. |
-| **Cutout over its own source mp4** *(text-behind-subject, talking-head with overlays)* | The same mp4 the cutout was generated from | Two RGB sources for the same person. At default `--quality balanced` (crf 18) the doubling is barely visible; at `--quality fast` (crf 30) you'll see a slight color shift / soft edge on the silhouette. Use `--quality best` (crf 12) for hero shots. |
-| **Cutout over different footage of the same subject** | Another take of the same person | Looks like two overlapping people. Avoid — re-shoot or re-cut the source. |
-
-### Text-behind-subject: the recommended layout
-
-Putting a headline *behind* a presenter so their silhouette occludes the text:
-
-```html
-<!-- z=1 base mp4: full lobby + presenter, plays the whole scene -->
-<video
-  id="cf-base"
-  data-start="0" data-duration="6" data-media-start="0" data-track-index="0"
-  src="presenter.mp4"
-  muted playsinline
-></video>
-
-<!-- z=2 headline -->
-<h1 id="cf-headline" style="position:absolute;top:50%;left:50%;
-     transform:translate(-50%,-50%); z-index:2;
-     color:#fff; text-shadow:0 6px 32px rgba(0,0,0,.55);
-     clip-path:inset(0 0 100% 0); font-size:220px; font-weight:900;">
-  MAKE IT IN HYPERFRAMES
-</h1>
-
-<!-- z=3 cutout: same source, alpha around presenter, hidden until the cut.
-     The wrapper carries the opacity, NOT the <video> itself. -->
-<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
-  <video
-    id="cf-cutout"
-    data-start="0" data-duration="6" data-media-start="0" data-track-index="1"
-    src="presenter.webm"
-    muted playsinline
-  ></video>
-</div>
-```
-
-```js
-const tl = gsap.timeline({ paused: true });
-const CUT = 3.3;
-
-// Reveal the headline early
-tl.to("#cf-headline", { clipPath: "inset(0 0 0% 0)", duration: 0.6, ease: "expo.out" }, 0.25);
-
-// At the cut, flip the cutout wrapper visible — silhouette punches through the headline
-tl.set(".cutout-wrap", { opacity: 1 }, CUT);
-
-// Sentinel: extend timeline to the composition's full duration so the renderer
-// doesn't bail past the last meaningful tween.
-tl.set({}, {}, 6);
-```
-
-### Two non-obvious rules
-
-**1. Wrap the cutout video in a non-timed `<div>` and animate the wrapper, not the video.**
-
-The framework forces `opacity: 1` on any element with `data-start`/`data-duration` while it's "active" — that's how it controls clip visibility. CSS `opacity: 0` on the video element is silently overwritten by the framework's clip lifecycle, so an opacity tween on the video element won't do anything. Wrap the video in a `<div>` that has no `data-*` attributes; the wrapper is owned entirely by your CSS/GSAP.
-
-**2. Both videos start at `data-start="0"` and decode in sync from t=0.**
-
-It's tempting to "late-mount" the cutout (`data-start="3.3"` to match the cut). Don't — Chrome does a seek + decoder warm-up at mount, which can land one frame off the base mp4 at the cut moment. With both videos mounted from t=0 and the cutout's wrapper opacity-animated, both decoders advance the same way and stay frame-accurate.
-
-### Quality preset and color match
-
-When the cutout is overlaid on its own source mp4, the encoder's CRF directly affects how visible the doubling is at edges:
-
-| `--quality` | CRF | File size (12s @ 1080p) | When to use |
-|---|---|---|---|
-| `fast` | 30 | ~2 MB | Cutout sits over an unrelated background and file size matters |
-| `balanced` *(default)* | 18 | ~6 MB | Recommended for text-behind-subject and any pattern that overlays on the source |
-| `best` | 12 | ~12 MB | Hero shots, masters, or anything you'll re-encode downstream |
-
-The encoder also writes BT.709 + limited-range color metadata so Chrome's YUV→RGB pipeline matches the source mp4's. Without those tags, the cutout would render slightly differently from the underlying mp4 even at lossless quality (visible red/skin shift).
-
-## What u²-net_human_seg is and isn't good for
-
-The model is purpose-built for **portrait / human matting**. It excels when:
-
-- ✅ The subject is a person, head-and-shoulders or full-body
-- ✅ The framing is reasonably stable (not a wide handheld shot)
-- ✅ The background contrasts with the subject
+Keep the media element stable and animate a wrapper when the cutout must move,
+resize, or reveal. This avoids mixing media playback with the transform that
+controls the composition.
 
-It struggles or fails on:
+When a cutout and its original background must remain frame-aligned, give both
+media elements the same `data-start` and playback offset. Hide or reveal them
+through wrappers instead of mounting one source later. Then scrub the cut point
+and check the rendered frame, not only normal playback.
 
-- ❌ Non-human subjects (products, animals, objects). The model will return a mostly-empty mask.
-- ❌ Very fine hair detail on a busy background. The 320×320 inference resolution means hair tips get softened — fine for most use cases, but compositors notice.
-- ❌ Frame-to-frame temporal consistency. Each frame is processed independently, so static backgrounds with moving subjects can show subtle edge flicker. For most web playback this is invisible; for high-end VFX it may matter.
-- ❌ Live streams or real-time capture. The pipeline is batch-only.
+## Put something behind the subject
 
-If your use case hits one of these, see the alternatives below.
+For text-behind-subject or another three-layer effect, you can create both the
+foreground cutout and an inverse-alpha background plate in one pass:
 
-## Alternatives — when the built-in command isn't the right tool
-
-The CLI ships **one model on purpose** — the one that's MIT-licensed, runs everywhere, and produces production-quality output for person/portrait video. The list below leads with **free, open-source tools** that pair naturally with HyperFrames. Each entry calls out the actual catch — license, install effort, hardware needs — so you can pick the right one for your situation. Full benchmarks are in the [matting eval](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654).
-
-### Free, open-source CLIs and libraries
-
-These all run locally with no account, no upload, no watermark.
-
-| Tool | When to use it | Catch |
-|------|----------------|-------|
-| [`rembg`](https://github.com/danielgatis/rembg) (Python, MIT) | You need a different subject type — `isnet-general-use` for objects/animals/products, `birefnet-portrait` for a quality ceiling on hair, `silueta` for a tiny ~40 MB footprint. Same family as our default model, more variety. | Requires Python + `pip install rembg`. Some bundled models (`birefnet-*`) need ~4 GB RAM and are CPU-only |
-| [BiRefNet](https://github.com/ZhengPeng7/BiRefNet) (PyTorch, MIT) | Highest-fidelity portrait mattes available — visibly better hair edges than u²-net | Heavy (~4 GB inference RAM), slow on CPU, broken on Apple CoreML at the time of the eval |
-| [Robust Video Matting (RVM)](https://github.com/PeterL1n/RobustVideoMatting) (PyTorch, **GPL-3.0**) | The only widely-available model with **temporal consistency** built in — no edge flicker on moving subjects. Best choice when you're matting a long talking-head clip and frame-to-frame stability matters | GPL-3.0 license is incompatible with most commercial / proprietary codebases. Read your repo's license before using |
-| [Backgroundremover](https://github.com/nadermx/backgroundremover) (Python, MIT) | Simple `pip install` wrapper around u²-net; nice if you want a Python API instead of our Node CLI | Same model family as ours, no quality difference — pick whichever fits your stack |
-| [ComfyUI](https://github.com/comfyanonymous/ComfyUI) (open-source, GPL-3.0 core) | Custom workflows: chain a segmentation model + alpha refinement + temporal smoothing. The right tool for tricky cases (multiple subjects, hair against a similar background, sports footage) | Setup is involved (Python, models, node graph). Worth it for repeat specialty work |
-
-After running any of these externally, encode the output as a HyperFrames-compatible transparent WebM with:
-
-```bash Terminal
-ffmpeg -i frames-%04d.png -c:v libvpx-vp9 \
-  -pix_fmt yuva420p \
-  -metadata:s:v:0 alpha_mode=1 \
-  -auto-alt-ref 0 -cpu-used 4 -b:v 0 -crf 30 \
-  transparent.webm
+```bash
+npx hyperframes remove-background subject.mp4 \
+  -o subject.webm \
+  --background-output plate.webm
 ```
 
-### Free desktop / GUI tools
-
-| Tool | When to use it | Catch |
-|------|----------------|-------|
-| [DaVinci Resolve — Magic Mask](https://www.blackmagicdesign.com/products/davinciresolve) | You're already editing in Resolve, want a brush-based UI with manual refinement, and need to round-trip the alpha into a larger edit | macOS / Windows / Linux desktop install. The free tier covers Magic Mask; paid Studio version unlocks higher resolutions on some features |
-| [Backgroundremover.app](https://backgroundremover.app) (web) | One-off image cutout, no signup, no watermark | Single images only, not video. Free tier is hosted but the underlying tool is the same `rembg` model family |
-| [PhotoRoom Background Remover](https://www.photoroom.com/tools/background-remover) (web) | Quick one-off image, polished UI, no signup | Single images only, e-commerce-tuned model |
-
-### Web SaaS tools (free tiers, with strings)
-
-| Tool | When to use it | Catch |
-|------|----------------|-------|
-| [unscreen.com](https://www.unscreen.com) | Quick one-off video, no install, drag-and-drop | **Free tier is watermarked and capped at short clips** (~10s preview). Paid removes both. Run by the team behind remove.bg |
-| [RunwayML — Green Screen](https://runwayml.com) | Polished UI with brush refinement and time-aware tracking; the closest a SaaS gets to professional roto | Free tier exists but is credit-limited; serious use is a subscription |
-| [Kapwing — Background Remover](https://www.kapwing.com/tools/remove-video-background) | Browser-based, integrates with their video editor | Free tier is watermarked; paid removes it |
+The plate keeps the original surroundings and leaves a transparent
+person-shaped hole. It is not an inpainted empty background. Place an opaque
+graphic or scene beneath the hole, then place `subject.webm` above it.
 
-### How to choose
+## Know when it will work well
 
-- **Person / portrait video, web playback, MIT-clean** → use the built-in `hyperframes remove-background` (this is what it's tuned for).
-- **Non-human subject** (product, animal, object) → `rembg` with `isnet-general-use`.
-- **Maximum portrait quality, especially hair** → `BiRefNet` via Python.
-- **Long video where edge flicker would be visible**, GPL is OK → `RVM`.
-- **One-off marketing clip, no install** → DaVinci Resolve (free) for video, Backgroundremover.app for a still image.
-- **Specialty case the off-the-shelf models can't handle** → ComfyUI with a custom graph.
+The included model is designed for people. It works best with a clear human
+subject, stable framing, and reasonable contrast from the background.
 
-## Troubleshooting
+Use another segmentation or masking tool when:
 
-### Model download fails or hangs
+- the subject is a product, animal, or other object;
+- fine hair crosses a busy background;
+- frame-to-frame edge stability must meet high-end VFX standards;
+- you need the original background reconstructed after removing the person.
 
-The weights live on GitHub Releases (rembg's `v0.0.0` release, ~168 MB). If your network blocks GitHub or the download is interrupted:
+Background removal is preprocessing. Run it once, keep the transparent result
+in the project, and reuse it.
 
-```bash Terminal
-# Manually download and drop into the cache
-mkdir -p ~/.cache/hyperframes/background-removal/models
-curl -L -o ~/.cache/hyperframes/background-removal/models/u2net_human_seg.onnx \
-  https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net_human_seg.onnx
-```
-
-Subsequent `remove-background` runs skip the download and use your local copy.
-
-### "ffmpeg and ffprobe are required"
-
-The pipeline shells out to ffmpeg for decode + encode. Install via `brew install ffmpeg` on macOS or `sudo apt install ffmpeg` on Debian/Ubuntu. Verify with `npx hyperframes doctor`.
-
-### The output WebM looks fully opaque in the browser
-
-Chrome only reads the alpha plane when the WebM is encoded as `yuva420p` with the `alpha_mode=1` metadata tag. The CLI sets both. If you re-encode the output yourself (e.g. with another ffmpeg invocation), preserve those flags:
+## Balance quality and speed
 
-```bash Terminal
-ffmpeg -i in.webm -c:v libvpx-vp9 \
-  -pix_fmt yuva420p \
-  -metadata:s:v:0 alpha_mode=1 \
-  -auto-alt-ref 0 -cpu-used 4 \
-  out.webm
-```
-
-To verify a WebM has alpha, extract the first frame and inspect:
+`--device auto` chooses the best available local provider. Inspect the detected
+provider with:
 
-```bash Terminal
-ffmpeg -y -c:v libvpx-vp9 -i out.webm -frames:v 1 -pix_fmt rgba -update 1 frame0.png
+```bash
+npx hyperframes remove-background --info
 ```
 
-The decoded `frame0.png` should be RGBA and have non-trivial alpha values.
-
-### CoreML is "available" but inference fails to start
-
-The pipeline auto-falls-back to CPU if CoreML fails to bind, with a warning. If you want to skip the CoreML attempt entirely, force CPU:
-
-```bash Terminal
-npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
-```
+For WebM output, `--quality balanced` is the default. Use `best` when the
+cutout sits directly over its original source and edge color must match; use
+`fast` for a smaller file over an unrelated background.
 
-### The alpha mask has rough or jagged edges
+## Common problems
 
-That usually means the source frame is high-contrast against a similar-toned background and the model's 320×320 inference resolution is showing through. Two paths forward:
+| Problem                           | What to check                                                                                   |
+| --------------------------------- | ----------------------------------------------------------------------------------------------- |
+| The background is still opaque    | Confirm the output is transparent WebM, MOV, or PNG and preview it over a colored background.   |
+| Edges flicker                     | Use a cleaner source, reduce fast movement, or use a stronger external matting tool.            |
+| Processing is slow                | Check `--info`; CPU processing works but is much slower than an available accelerated provider. |
+| The subject has a color halo      | Use `--quality best`, especially when layering over the original source.                        |
+| The “background plate” has a hole | Expected: it is inverse alpha, not an inpainted clean plate.                                    |
 
-1. Re-frame or re-shoot to give the subject a more contrasting background.
-2. Try `birefnet-portrait` via `rembg` (see [Other open-source models](#other-open-source-models)) — it's higher quality at hair edges but slower and heavier.
+The [CLI reference](/packages/cli#remove-background) lists every flag and
+supported input.
 
-## Reference
+## Related topics
 
-- CLI: [`hyperframes remove-background`](/packages/cli#remove-background)
-- Eval: [Matting eval — v7](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654)
-- Source model: [danielgatis/rembg](https://github.com/danielgatis/rembg)
-- ONNX runtime: [`onnxruntime-node`](https://www.npmjs.com/package/onnxruntime-node)
+- [Use images and video](/guides/video-components)
+- [Add an avatar presenter](/guides/avatar-presenter)
+- [Apply media effects without changing the source file](/guides/media-effects)
diff --git a/docs/guides/rendering.mdx b/docs/guides/rendering.mdx
index d46deb99e4..a13246162b 100644
--- a/docs/guides/rendering.mdx
+++ b/docs/guides/rendering.mdx
@@ -1,444 +1,159 @@
 ---
-title: Rendering
-description: "Render compositions to MP4, MOV, WebM, GIF, or PNG sequences locally or in Docker."
+title: "Render from the command line"
+description: "Check a project and render MP4, MOV, WebM, GIF, or PNG output."
 ---
 
-Render your Hyperframes [compositions](/concepts/compositions) to MP4, MOV, WebM, GIF, or PNG sequences with the [CLI](/packages/cli). The rendering pipeline is frame-by-frame and seek-driven — see [Deterministic Rendering](/concepts/determinism) for how this works under the hood.
+Studio is the simplest place to export a project. Use the command line when an agent, script, CI job, or advanced delivery workflow needs to control the render.
 
-## Getting Started
-
-<Steps>
-  <Step title="Verify your environment">
-    Run the diagnostics command to check for required dependencies:
-
-    ```bash Terminal
-    npx hyperframes doctor
-    ```
-
-    Expected output:
-
-    ```
-    ✓ Node.js    v22.x
-    ✓ FFmpeg      7.x
-    ✓ FFprobe     7.x
-    ✓ Chrome      (bundled)
-    ✓ Docker      available
-    ```
-  </Step>
-  <Step title="Preview your composition">
-    Before rendering, preview your composition in the browser to verify it looks correct:
-
-    ```bash Terminal
-    npx hyperframes preview
-    ```
-  </Step>
-  <Step title="Render to MP4">
-    Run the render command from your project directory:
-
-    ```bash Terminal
-    npx hyperframes render --output output.mp4
-    ```
-
-    Expected output:
-
-    ```
-    ⠋ Rendering composition "root" (30fps, standard quality)
-    ✓ Captured 240 frames in 8.2s
-    ✓ Encoded to output.mp4 (8.0s, 1920x1080, 4.2MB)
-    ```
-  </Step>
-</Steps>
-
-## Rendering Modes
-
-<Tabs>
-  <Tab title="Local Mode">
-    ### Local Mode (default)
-
-    Uses Puppeteer (bundled Chromium) and your system's FFmpeg. Fast for iteration during development.
-
-    **Requires:** FFmpeg installed on your system. See [Troubleshooting](/guides/troubleshooting) if FFmpeg is not found.
-
-    ```bash Terminal
-    npx hyperframes render --output output.mp4
-    ```
-
-    **Pros:**
-    - Fast startup, no container overhead
-    - Can use your system GPU for Chrome/WebGL capture by default
-    - Can use your system GPU for hardware-accelerated encoding (with `--gpu`)
-    - Best for iterative development
-
-    **Cons:**
-    - Output may vary across platforms due to font and Chrome version differences
-    - Not suitable for CI/CD pipelines that require reproducibility
-  </Tab>
-  <Tab title="Docker Mode">
-    ### Docker Mode
-
-    [Deterministic](/concepts/determinism) output with an exact Chrome version and font set. Use this for production renders and CI pipelines.
-
-    **Requires:** Docker installed and running.
-
-    ```bash Terminal
-    npx hyperframes render --docker --output output.mp4
-    ```
-
-    **Pros:**
-    - Identical output on every platform — same Chrome, same fonts, same FFmpeg
-    - The same pipeline used in production
-    - Ideal for CI/CD and automated workflows
-
-    **Cons:**
-    - Slower startup due to container initialization
-    - Browser capture stays on the deterministic software-GL path
-    - GPU encoding requires Docker host GPU passthrough and is not cross-platform on Docker Desktop
-
-    <Note>
-      Docker mode uses `chrome-headless-shell` with [BeginFrame](/concepts/determinism#how-it-works) control for frame-perfect, deterministic capture.
-    </Note>
-  </Tab>
-</Tabs>
-
-## When to Use Each Mode
-
-| Scenario | Recommended Mode |
-|----------|-----------------|
-| Local development and iteration | Local |
-| CI/CD pipeline | Docker |
-| Sharing renders with a team | Docker |
-| Quick preview export | Local |
-| AI agent-driven rendering | Docker |
-| Benchmarking performance | Local |
-
-## Options
-
-| Flag | Values | Default | Description |
-|------|--------|---------|-------------|
-| `--output` | path | `renders/<name>.mp4` | Output file path |
-| `--format` | mp4, mov, webm, gif, png-sequence | mp4 | Output format (see [Transparent Video](#transparent-video) below) |
-| `--fps` | 1-240 or rational (e.g. `30000/1001`) | 30 | Frames per second |
-| `--gif-loop` | 0-65535 | 0 | GIF loop count. `0` loops forever |
-| `--quality` | draft, standard, high | standard | Encoding quality preset |
-| `--crf` | 0–51 | — | Override CRF (lower = higher quality). Cannot combine with `--video-bitrate` |
-| `--video-bitrate` | e.g. `10M`, `5000k` | — | Target bitrate encoding. Cannot combine with `--crf` |
-| `--video-frame-format` | auto, jpg, png | auto | Source video frame extraction format. Use `png` for UI recordings, screen captures, and color-sensitive source videos |
-| `--workers` | 1-24 or `auto` | auto | Parallel render workers (see [Workers](#workers) below) |
-| `--max-concurrent-renders` | 1-10 | 2 | Max simultaneous renders via the producer server (see [Concurrent Renders](#concurrent-renders) below) |
-| `--batch` | path | — | JSON array of variable rows (or `{ "rows": [...] }`), rendering one output per row |
-| `--batch-concurrency` | integer | 1 | Maximum batch rows to render at once |
-| `--batch-fail-fast` | — | off | Stop launching new batch rows after the first row failure |
-| `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, AMF, VAAPI, QSV) |
-| `--browser-gpu` / `--no-browser-gpu` | — | on locally, off in Docker | Use or opt out of host GPU acceleration for local Chrome/WebGL capture |
-| `--hdr` | — | off | Force HDR output even if no HDR sources are detected (MP4 only). See [HDR Rendering](/guides/hdr) |
-| `--sdr` | — | off | Force SDR output even if HDR sources are detected |
-| `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) |
-| `--quiet` | — | off | Suppress verbose output |
-
-## Quality and Encoding
-
-The `--quality` flag selects a preset that controls the H.264 CRF (Constant Rate Factor) and encoder speed:
-
-| Preset | CRF | x264 Preset | Best For |
-|--------|-----|-------------|----------|
-| `draft` | 28 | ultrafast | Quick previews, iteration |
-| `standard` | 18 | medium | General use — visually lossless at 1080p |
-| `high` | 15 | slow | Final delivery, near-lossless quality |
-
-For finer control, use `--crf` or `--video-bitrate` to override the preset:
+## Render a normal video
 
-```bash
-# Near-lossless quality (CRF 15 = very high quality, large file)
-npx hyperframes render --crf 15 --output pristine.mp4
+From the project folder:
 
-# Target a specific bitrate (useful for size-constrained delivery)
-npx hyperframes render --video-bitrate 10M --output controlled.mp4
+```bash
+npx hyperframes render --output final.mp4
 ```
 
-**Tip**: The default `standard` preset (CRF 18) is visually lossless at 1080p — most people cannot distinguish it from the source. Use `--quality draft` for faster iteration, or `--quality high` / `--crf 10` when file size is no concern.
-
-## Input Video Codecs
-
-Video assets referenced by a composition (a `<video src="...">` clip) are decoded by FFmpeg, not by the browser: the pipeline pre-extracts every input video into frame images and injects them during capture, so the render never depends on what the capture browser can play. Any codec your FFmpeg build decodes works as an input, including:
-
-- H.264 / AVC
-- **HEVC / H.265, 8-bit and 10-bit** (`hvc1` and `hev1`): common for storage-optimized asset libraries; renders identically on macOS and Linux, no hardware decoder required
-- VP8 / VP9 and ProRes 4444 (with alpha; see [Transparent Video](#transparent-video))
-- HDR sources (HLG / PQ) are tone-mapped for SDR renders; see the [HDR guide](/guides/hdr)
-
-The one caveat is **live preview**: `preview`, `play`, Studio, and published player pages play the file in a real browser, so playback there depends on that browser's codec support. Chrome (107+), Edge, and Safari hardware-decode HEVC on most modern machines; Firefox does not. Preview handles this automatically: on first use, it transcodes the asset into a cached H.264 proxy (stored under `.transcode-cache/`, safe to delete) and serves that for playback, while render always uses the original file. `check` and `snapshot` prepare the same proxies before opening their browser phase. Publishing bakes the proxies into the published archive so static player pages work too. Opt out per command with `--no-proxy`, or project-wide by setting `media.autoProxy` to `false` in `hyperframes.json`.
-
-`hyperframes lint` emits an info-level `hevc_preview_codec` note when a composition references an HEVC video, naming the affected asset(s).
-
-## Animated GIF
+If you omit `--output`, HyperFrames writes the result under `renders/`.
 
-Use GIF when the output needs to autoplay inline in GitHub PRs, READMEs, issue reports, and docs pages:
+The normal workflow is:
 
-```bash Terminal
-npx hyperframes render --format gif --fps 15 --gif-loop 0 --output demo.gif
+```bash
+npx hyperframes lint
+npx hyperframes check
+npx hyperframes render --output final.mp4
 ```
 
-GIF output uses a two-pass FFmpeg palette encode (`palettegen` with diff statistics, then `paletteuse` with Sierra dithering) for better gradients and text edges than a single-pass conversion. GIFs are still much larger than MP4/WebM at the same dimensions, so prefer short compositions. GIF renders are capped at 30fps; pass `--fps 15` for smaller files.
-
-GIF does not carry audio and only has 1-bit transparency. For transparent overlays, use `--format webm`, `--format mov`, or `--format png-sequence` instead.
+`lint` checks the project structure. `check` opens the project in a browser and looks for runtime, layout, motion, media, and contrast problems.
 
-For UI recordings, screen captures, or other source videos where saturated interface colors matter, pass `--video-frame-format png` to extract source video layers as PNG before browser capture. The default `auto` mode preserves the historical behavior: alpha-capable sources use PNG, opaque sources use JPG.
+## Choose a format
 
-## GPU Acceleration
+| Format       | Use it for                                                 |
+| ------------ | ---------------------------------------------------------- |
+| MP4          | Normal sharing, publishing, and delivery                   |
+| MOV          | ProRes workflows and transparent editing intermediates     |
+| WebM         | Web delivery and transparent overlays                      |
+| GIF          | Short previews in issues, pull requests, and documentation |
+| PNG sequence | Frame-by-frame handoff to compositing software             |
 
-Hyperframes has two separate GPU acceleration surfaces:
+Examples:
 
-- `--gpu` uses a hardware video encoder in FFmpeg when one is available. Supported backends include VideoToolbox on macOS, NVENC on NVIDIA systems, AMD AMF on Windows, VAAPI on Linux, and Intel QSV on supported Windows/Linux hosts.
-- Browser GPU uses the host GPU for local Chrome/WebGL capture. It is enabled automatically for local renders and disabled in Docker. Use `--no-browser-gpu` to opt out.
+```bash
+# Transparent web overlay
+npx hyperframes render --format webm --output overlay.webm
 
-```bash Terminal
-# Add hardware FFmpeg encoding to the default local browser-GPU render
-npx hyperframes render --gpu --output encoded-fast.mp4
+# ProRes editing file
+npx hyperframes render --format mov --output master.mov
 
-# Opt out of hardware Chrome/WebGL capture
-npx hyperframes render --no-browser-gpu --output software-browser.mp4
+# Short looping preview
+npx hyperframes render --format gif --fps 15 --output preview.gif
 
-# Use browser GPU plus hardware FFmpeg encoding
-npx hyperframes render --gpu --output gpu.mp4
+# RGBA frames in a directory
+npx hyperframes render --format png-sequence --output frames
 ```
 
-Browser GPU capture is local-mode only. It maps to platform-native Chrome GPU backends: Metal on macOS, D3D11 on Windows, and EGL on Linux. Use `--no-browser-gpu` or Docker mode when exact cross-machine reproducibility matters more than local render speed.
-
-## Workers
-
-Each render worker launches a **separate Chrome browser process** to capture frames in parallel. More workers can speed up rendering, but each one consumes ~256 MB of RAM and significant CPU.
-
-### Default behavior
-
-By default, Hyperframes uses **CPU cores minus 2** (reserving headroom for FFmpeg encoding and your other applications):
-
-| Machine | CPU cores | Default workers |
-|---------|-----------|----------------|
-| MacBook Air (M1) | 8 | 6 |
-| MacBook Pro (M3) | 12 | 10 |
-| 4-core laptop | 4 | 2 |
-| 2-core VM | 2 | 1 |
+GIF has no audio and limited transparency. Prefer MP4 or WebM for normal playback.
 
-Each worker spawns its own Chrome process (~256 MB RAM), so the per-worker overhead is significant. The maximum is 24 workers (hard ceiling).
+### Transparent video
 
-### Choosing a worker count
+Use WebM for a transparent web overlay or MOV for a ProRes 4444 editing
+intermediate. Leave the composition background unpainted wherever the output
+must remain transparent; an opaque `html`, `body`, or full-frame background
+will be encoded as visible pixels.
 
-```bash Terminal
-# Explicit worker count
-npx hyperframes render --workers 1 --output output.mp4
-
-# Let Hyperframes pick based on your CPU
-npx hyperframes render --workers auto --output output.mp4
-
-# Maximum parallelism (use with caution on laptops)
-npx hyperframes render --workers 24 --output output.mp4
+```bash
+npx hyperframes render --format webm --output overlay.webm
+npx hyperframes render --format mov --output overlay.mov
 ```
 
-<Tip>
-  Start with the default. If renders feel slow and your system has headroom (check Activity Monitor / `htop`), try increasing `--workers`. If you see high memory pressure or fan noise, reduce it.
-</Tip>
-
-### When to use 1 worker
-
-- Short compositions (under 2 seconds / 60 frames) — parallelism overhead exceeds the benefit
-- Low-memory machines (4 GB or less)
-- Running renders alongside other heavy processes (video editing, large builds)
+MP4 is the normal opaque delivery format. After rendering transparency, inspect
+the file over a contrasting background rather than trusting a player that
+always shows black behind alpha.
 
-### When to increase workers
-
-- Long compositions (30+ seconds) on a machine with 8+ cores and 16+ GB RAM
-- Dedicated render machines or CI runners
-- Docker mode on a well-provisioned host
-
-## Batch Rendering
-
-Batch rendering runs the same composition once per variables row:
-
-```json rows.json
-[
-  { "name": "Alice", "headline": "Welcome, Alice" },
-  { "name": "Bob", "headline": "Welcome, Bob" }
-]
-```
-
-```bash Terminal
-npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
-```
+## Input video codecs
 
-`--output` is a template. Use `{index}` or any scalar key from the row to make each path unique. Hyperframes preflights the full batch before rendering: malformed rows, missing placeholders, duplicate output paths, and strict variable mismatches fail before the first video starts. A `manifest.json` file is written next to the outputs with per-row status, output path, render time, duration when available, and error details.
+Studio, preview, `check`, and published projects normally create cached browser
+proxies for local video that Chrome cannot decode reliably, including common
+HEVC and ProRes inputs. The original file stays in the project and remains the
+render source.
 
-Rows continue after failures by default so a bad data row does not discard the rest of the batch. Add `--batch-fail-fast` to stop launching new rows after the first failure, or `--json` to stream machine-readable progress events while the manifest is updated.
+If a clip is black only in preview, keep automatic proxying enabled, confirm the
+source is local, and run `npx hyperframes check`. Disable proxying only when the
+browser already supports the source or you are diagnosing the proxy itself.
 
-## Concurrent Renders
+## Choose quality and frame rate
 
-When multiple render requests hit the producer server simultaneously (common with AI agents), each render spawns its own set of Chrome worker processes. Too many concurrent renders can exhaust CPU and cause failures.
+The default `standard` quality is the right choice for most finished work.
 
-The producer server uses a **request-level semaphore** to queue renders. Only `maxConcurrentRenders` renders execute at a time — additional requests wait in a FIFO queue until a slot opens.
-
-### Configuration
+```bash
+# Faster review version
+npx hyperframes render --quality draft --output review.mp4
 
-```bash Terminal
-# CLI flag
-npx hyperframes render --max-concurrent-renders 2 --output output.mp4
+# Larger final master
+npx hyperframes render --quality high --output master.mp4
 
-# Environment variable (for the producer server)
-PRODUCER_MAX_CONCURRENT_RENDERS=2
+# Explicit frame rate
+npx hyperframes render --fps 60 --output final-60fps.mp4
 ```
 
-The default is **2** concurrent renders, which works well on 8-core machines where each render uses 2-3 workers.
-
-### Queue status
-
-The producer server exposes a `GET /render/queue` endpoint that returns the current state:
+Use a higher frame rate only when the source or destination needs it. It creates more frames, so rendering takes longer.
 
-```json
-{
-  "maxConcurrentRenders": 2,
-  "activeRenders": 1,
-  "queuedRenders": 3
-}
-```
-
-AI agents can poll this endpoint to decide whether to submit a render or wait.
+The CLI uses the composition’s `data-fps` when present and otherwise defaults to 30 fps.
 
-### SSE queue events
+## Local or Docker
 
-When using the streaming endpoint (`POST /render/stream`), queued requests receive a `queued` event before rendering begins:
+Local rendering is the normal choice:
 
-```json
-{"type": "queued", "requestId": "...", "position": 2}
+```bash
+npx hyperframes render --output final.mp4
 ```
 
-This lets agents report "waiting in queue" to users rather than appearing stuck.
-
-### Choosing a concurrency limit
+It starts quickly and can use the computer’s browser GPU.
 
-| Machine | CPU cores | Recommended limit |
-|---------|-----------|------------------|
-| 4-core VM | 4 | 1 |
-| 8-core workstation | 8 | 2 |
-| 16-core server | 16 | 3-4 |
-| 32-core render box | 32 | 5-6 |
+Use Docker when a controlled Chrome, FFmpeg, and font environment matters:
 
-<Tip>
-  When in doubt, use 1. Renders will queue up and execute sequentially, but each one gets full CPU and finishes as fast as possible. This is better than 3 renders fighting for CPU and all finishing slowly — or failing.
-</Tip>
-
-## Transparent Video
-
-Hyperframes supports rendering with a transparent background — useful for overlays, lower thirds, subscribe cards, and any element you want to composite over other footage in a video editor.
-
-### Recommended format: MOV (ProRes 4444)
-
-```bash Terminal
-npx hyperframes render --format mov --output overlay.mov
+```bash
+npx hyperframes render --docker --output final.mp4
 ```
 
-**MOV with ProRes 4444** is the industry standard for transparent video. It works in all major video editors:
-
-- CapCut
-- Final Cut Pro
-- Adobe Premiere Pro
-- DaVinci Resolve
-- After Effects
-
-<Warning>
-  ProRes MOV files are large (typically 5-40 MB for short clips) because ProRes is a high-quality intermediate codec optimized for editing, not delivery. This is expected — the same tradeoff Remotion and professional pipelines make.
-</Warning>
-
-### Format comparison
+Docker adds startup and infrastructure overhead. It is useful for CI and repeatable production environments, not a requirement for every final render.
 
-| Format | Codec | Transparency | Video editors | Browsers | File size |
-|--------|-------|-------------|---------------|----------|-----------|
-| **MOV** | ProRes 4444 | Yes | CapCut, Final Cut, Premiere, DaVinci, After Effects | No | Large |
-| **WebM** | VP9 | Yes | None (shows black background) | Chrome, Firefox | Small |
-| **PNG sequence** | RGBA PNGs (no encoding) | Yes (lossless) | After Effects, Nuke, Fusion (image-sequence import) | No | Largest |
-| **MP4** | H.264 | No | All | All | Small |
+## Render another composition
 
-<Note>
-  **WebM VP9 alpha** is technically supported but all major video editors ignore the alpha channel and render transparent areas as black. Only Chromium-based browsers (Chrome, Arc, Brave, Edge) decode VP9 alpha correctly. Safari does not support it. Use MOV for editor workflows and WebM only for browser-based playback.
-</Note>
+The root `index.html` is rendered by default. To target another standalone composition:
 
-### PNG sequence (no encoding)
-
-```bash Terminal
-npx hyperframes render --format png-sequence --output frames/
+```bash
+npx hyperframes render \
+  --composition compositions/intro.html \
+  --output intro.mp4
 ```
 
-`--format png-sequence` skips the encoder entirely. The captured RGBA frames are copied to `<output>/frame_NNNNNN.png` (zero-padded) and, if the composition has audio, an `audio.aac` sidecar is written alongside. Use this when you want lossless frames — for compositing in After Effects / Nuke / Fusion, or as the input to a custom encode pipeline. `--output` is treated as a directory and is created if it doesn't exist.
+Nested compositions that use `<template>` wrappers should be rendered through the root composition that includes them.
 
-### How it works
+## Batch and cloud work
 
-When you render with `--format mov`, `--format webm`, or `--format png-sequence`, Hyperframes:
+For several variable-driven versions, use batch rendering. For remote infrastructure, use HyperFrames cloud, AWS Lambda, or Google Cloud Run.
 
-1. Captures each frame as a **PNG with alpha channel** (instead of JPEG for MP4)
-2. Sets Chrome's page background to transparent via `Emulation.setDefaultBackgroundColorOverride`
-3. Encodes with an alpha-capable codec (ProRes 4444 for MOV, VP9 for WebM); `png-sequence` skips encoding and writes the captured frames directly
+Those workflows involve output naming, credentials, concurrency, and infrastructure choices. Start in the [CLI guide](/developers/cli) and use the complete [CLI reference](/packages/cli) when you need every flag.
 
-Your composition's HTML should **not** set a `background` on `html` or `body` — leave it unset so the transparent background comes through.
+## If rendering fails
 
-### Authoring transparent compositions
+Run:
 
-```html
-<style>
-  /* Do NOT set background on html/body — leave them transparent */
-  * { margin: 0; padding: 0; box-sizing: border-box; }
-
-  [data-composition-id="my-overlay"] {
-    position: relative;
-    width: 1920px;
-    height: 1080px;
-    overflow: hidden;
-    /* No background here either */
-  }
-</style>
+```bash
+npx hyperframes doctor
+npx hyperframes lint
+npx hyperframes check
 ```
 
-Only the visible elements (cards, text, images) will appear in the final video. Everything else will be transparent.
-
-### Verifying transparency
-
-- **In a browser:** Open the MOV file — it won't play (ProRes is not a browser codec). Instead, render a WebM copy and open it in Chrome on a checkerboard background page.
-- **In a video editor:** Import the MOV file and place it on a track above other footage. Transparent areas should show the footage below.
-- **Online tool:** Use [rotato.app/tools/transparent-video](https://rotato.app/tools/transparent-video) to verify your MOV or WebM has working transparency.
-
-<Note>
-  **`ffprobe` reports a transparent WebM as `yuv420p`, not `yuva420p`.** This is expected and does not mean the alpha is missing. VP9 stores its alpha plane in a Matroska `BlockAdditional` sidecar, not in the primary stream's pixel format, so `ffprobe` reports the primary stream as `pix_fmt=yuv420p` even when the file genuinely carries alpha. First check that the WebM declares the alpha sidecar, then force the VP9 library decoder to verify per-pixel alpha:
-
-  ```bash
-  ffprobe -v error -show_streams out.webm | grep -i alpha_mode   # ALPHA_MODE=1 or alpha_mode=1
-  ffmpeg -c:v libvpx-vp9 -i out.webm -frames:v 1 -f rawvideo -pix_fmt rgba frame.raw
-  ```
-
-  A fully transparent corner pixel in `frame.raw` reads `00 00 00 00`. MOV (ProRes 4444) and `png-sequence` report their alpha directly, so this caveat is WebM-only.
-</Note>
-
-## Tips
+Keep the first exact error rather than only the final “render failed” message. See [Troubleshooting](/guides/troubleshooting) for the next checks.
 
 <Tip>
-  Use `draft` quality during development for fast previews. Switch to `standard` or `high` for final output.
+  Always watch the exported file itself. Preview proves that the project can play; the output file
+  proves that the delivery is correct.
 </Tip>
 
-- Use `npx hyperframes benchmark` to find optimal settings for your system
-- Docker mode is slower but guarantees [identical output](/concepts/determinism) across platforms
-- For compositions with many frames, `--gpu` can significantly speed up local encoding
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Deterministic Rendering" icon="lock" href="/concepts/determinism">
-    Understand the determinism guarantees
-  </Card>
-  <Card title="HDR Rendering" icon="sun" href="/guides/hdr">
-    Render HDR10 MP4 from HDR video and image sources
-  </Card>
-  <Card title="Cloud Rendering" icon="cloud" href="/deploy/cloud">
-    Render on HeyGen's hosted cloud — no local Chrome or FFmpeg
-  </Card>
-  <Card title="CLI Reference" icon="terminal" href="/packages/cli">
-    Full list of CLI commands and flags
-  </Card>
-  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
-    Fix common rendering issues
-  </Card>
-</CardGroup>
+## Related topics
+
+- [Compare local, hosted, and self-managed rendering](/deploy/overview)
+- [Render and export from Studio](/studio/export)
+- [Diagnose a failed render](/guides/troubleshooting)
diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx
index 8c60644600..b0777b322a 100644
--- a/docs/guides/skills.mdx
+++ b/docs/guides/skills.mdx
@@ -1,131 +1,129 @@
 ---
-title: Skills catalog
-description: "Every HyperFrames skill agents load on demand — what each one is for, and how to install them."
+title: "Install and update agent skills"
+sidebarTitle: "Agent skills"
+description: "Teach a coding agent how to create valid HyperFrames projects and load specialized workflows when needed."
 ---
 
-HyperFrames ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). They teach your agent the framework-specific patterns — `data-*` attributes, GSAP timeline registration, adapter registries, runtime-owned media playback — that generic web docs don't cover. **Install them before writing compositions** and your agent produces valid HyperFrames HTML on the first try.
+HyperFrames skills teach coding agents the project format, animation rules, media workflow, validation loop, and creation workflows that generic web knowledge does not cover.
 
-The skills split into three groups:
+## Install for a person
 
-- **Router** — the entry skill that confirms the brief up front (the intent layer) and picks a workflow for any "make me a…" request — usually a video, but also a navigable deck (`/slideshow`) or a composition port (`/remotion-to-hyperframes`).
-- **Creation workflows** — one per input shape (URL, PR, music track, captions, etc.). Each owns its task end-to-end: project setup, gated steps, and the final deliverable. Read by the router; you can also invoke directly if you already know which one fits.
-- **Domain skills** — atomic capabilities (animation, media, CLI, registry) the workflows compose against; they never own the end-to-end task. Load one when you need that specific layer.
+Run the interactive installer:
 
-## Install
+```bash
+npx skills add heygen-com/hyperframes --full-depth
+```
+
+Select **Core Skills**. The `/hyperframes` router installs a specialized creation workflow when the request needs one, so you do not need the full catalog up front.
+
+Start a fresh agent chat after installation, then ask it to use `/hyperframes`.
+
+## Install or refresh from an agent
+
+For a non-interactive agent or CI environment, use:
+
+```bash
+npx hyperframes skills update
+```
+
+This installs or refreshes the core set and any HyperFrames skills already present in the global install, then links those bundles into compatible installed agents. It does not add every optional workflow.
+
+Check freshness without changing anything:
+
+```bash
+npx hyperframes skills check
+```
+
+Install or refresh one workflow explicitly:
+
+```bash
+npx hyperframes skills update pr-to-video
+```
+
+## Use the skills in Google Antigravity
+
+Install the skills from the root of the project you open in Antigravity:
 
-<Steps>
-  <Step title="Install the core set (default)">
-    ```bash
-    npx hyperframes skills update
-    ```
+```bash
+npx skills add heygen-com/hyperframes --full-depth
+```
+
+Select **Core Skills** and **Antigravity**. This uses Antigravity's supported
+project location, `.agents/skills`, and keeps the skills with the project. Start
+a fresh Antigravity conversation after installation.
+
+Antigravity also supports a global `~/.gemini/config/skills` directory. See
+Google's [current skills guide](https://antigravity.google/docs/skills?app=antigravity-ide)
+before managing that directory by hand.
+
+## Use the skills in GitHub Copilot CLI
+
+Run `npx hyperframes skills update`, open the project, and start Copilot:
+
+```bash
+copilot
+```
+
+If Copilot was already running, use `/skills reload`. Use `/skills list` or
+`/skills info hyperframes` to confirm discovery. GitHub's [current skills
+guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
+lists its project and personal skill locations.
 
-    Installs exactly the core set — the `/hyperframes` router, the `hyperframes-*` domain skills, and `media-use` — and the router installs each creation workflow on demand the first time it routes there. Always installs from the repo's current `main`. Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), [GitHub Copilot CLI](/guides/copilot-cli), and [Google Antigravity](/guides/antigravity).
-  </Step>
-  <Step title="Or pick what to install (interactive picker)">
-    ```bash
-    npx skills add heygen-com/hyperframes --full-depth
-    ```
+Both agents can use the same first request:
 
-    In a terminal this opens a picker — the core set under the "Core Skills" group, the on-demand creation workflows under "Other", nothing pre-selected. Keep `--full-depth`: it installs the current `main`; without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours. The picker is interactive-only: a non-interactive or agent run without `--skill` installs all 19, so agents should use `npx hyperframes skills update` above.
-  </Step>
-  <Step title="Or install everything at once (skip the picker)">
-    ```bash
-    npx skills add heygen-com/hyperframes --all --full-depth
-    ```
+```text
+Using /hyperframes, make a 10-second product intro for https://example.com.
+```
+
+Continue in the same conversation for revisions. For hosted creation instead
+of a local project, use the [HyperFrames MCP guide](/guides/mcp).
+
+## Let the router choose
 
-    Writes every skill to your project in one shot. Use this only when you explicitly want the full set up front — the router installs workflows on demand otherwise.
-  </Step>
-  <Step title="Or install one skill at a time">
-    ```bash
-    npx skills add heygen-com/hyperframes --skill <name> --full-depth
-    ```
+The normal entry point is `/hyperframes`. It confirms the important intent, then selects a workflow from the input:
 
-    Pass the bare skill name (no leading `/`) — e.g. `--skill hyperframes-animation`. Useful when you want a single capability without the full set.
-  </Step>
-  <Step title="Read /hyperframes first">
-    Once installed, invoke `/hyperframes` in your agent. It's the capability map for everything below and routes "make me a…" intent — a video, a deck, or a composition port — to the right creation workflow based on your input.
-  </Step>
-</Steps>
+| You provide | Workflow |
+| --- | --- |
+| A product website or product brief | Product launch video |
+| A topic or script with no website capture | Faceless explainer |
+| A GitHub pull request | PR-to-video |
+| Existing talking-head footage | Captions or a designed recut |
+| A music track | Music-driven video |
+| A short design-led animation | Motion graphic |
+| A presentation | Slideshow |
+| A Figma file or frame | Figma import with assets, brand tokens, components, and reconstructed motion |
+| Anything outside those shapes | General video |
 
-<Tip>
-  **Don't see a slash command after install?** Open a new agent session, or run `/skills` (Copilot CLI) / restart your agent's skill loader. Most agents pick up new skills on the next prompt.
-</Tip>
+You can invoke a workflow directly when you already know it is the right one, but you do not need to memorize the names to start.
 
-## Keeping skills current
+## Install more only when you need it
 
-After the first install, skills stay lean and current on their own — nothing re-pulls the full set behind your back:
+Install the complete set deliberately with:
 
-- **Core set** — the `/hyperframes` router, the `hyperframes-*` domain skills, and `/media-use`. `npx hyperframes init` (which every creation workflow runs when scaffolding) refreshes the core set plus anything else you already have installed. It never _expands_ the install — workflow skills you haven't used are not pulled — and re-running `init` on an up-to-date machine is a no-op. Offline (or rate-limited) it degrades gracefully and never hard-fails.
-- **Workflow skills** (and `/figma`) — install **on demand**, when their workflow is first triggered. The `/hyperframes` router runs `npx hyperframes skills update <workflow>` before entering a workflow, so the one it routes to is guaranteed present.
+```bash
+npx skills add heygen-com/hyperframes --all --full-depth
+```
 
-Check or refresh manually anytime:
+Or install one named skill:
 
 ```bash
-npx hyperframes skills check          # non-zero exit if installed skills are stale or the core set is incomplete
-npx hyperframes skills update         # refresh the core set + everything installed (never expands)
-npx hyperframes skills update <name>  # also install a specific workflow / domain skill on demand
-npx hyperframes skills                # install the full set explicitly
+npx skills add heygen-com/hyperframes --skill hyperframes-animation --full-depth
 ```
 
-`skills check` reports workflow skills you haven't installed as _available on demand_, not as a failure.
-
-## Router
-
-The single entry point. Read `/hyperframes` before invoking anything else — it knows what's available and which workflow fits your request.
-
-| Skill          | Use when                                                                                                                                                                                                  |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/hyperframes` | **Read first** for any request to make / create / edit / animate / render a video, animation, or motion graphic. Capability map for the domain skills, the intent layer that confirms every creation brief up front, and intent router for the creation workflows below. |
-
-## Creation workflows
-
-One workflow per input shape. The router (`/hyperframes`) picks one of these for you — but you can invoke them directly when you already know which fits.
-
-| Skill                      | Use when                                                                                                                                                                                |
-| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/product-launch-video`    | Any **website** — marketing / launching / promoting a product (from its URL, a brief, or a script), or a site tour / showcase / social clip featuring the site's own visuals. Up to ~3 min (sweet spot 30-90s).                                |
-| `/faceless-explainer`      | **Explaining a topic / concept** from arbitrary text — no product, no URL, no website capture; every visual is LLM-invented (typography / abstract / diagram / data-viz).               |
-| `/pr-to-video`             | A **GitHub pull request** (PR URL, `owner/repo#N` ref, or "this PR") → changelog / feature-reveal / fix / refactor explainer, read via the `gh` CLI.                                   |
-| `/embedded-captions`       | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed.                     |
-| `/talking-head-recut`      | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP.          |
-| `/motion-graphics`         | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay.       |
-| `/music-to-video`          | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing.                                        |
-| `/slideshow`               | A **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. |
-| `/general-video`           | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox).                              |
-| `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation.                                                                     |
-
-## Domain skills (loaded on demand)
-
-Atomic capabilities the creation workflows compose against — pull one when you need that specific layer.
-
-| Skill                    | Covers                                                                                                                                                                |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/hyperframes-core`      | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules.        |
-| `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).         |
-| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. |
-| `/hyperframes-creative`  | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.            |
-| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking.          |
-| `/hyperframes-cli`       | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus HeyGen-hosted cloud rendering (`cloud render / list / get / delete`) and AWS Lambda rendering (`lambda deploy / render / progress / destroy / policies`). |
-| `/hyperframes-registry`  | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream.                   |
-| `/figma`                 | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
-
-## Source of truth
-
-The one-line "use when" for each skill comes from its own `SKILL.md` frontmatter `description:` field in the [hyperframes repo](https://github.com/heygen-com/hyperframes/tree/main/skills). The same catalog lives in the [README's `## Skills` section](https://github.com/heygen-com/hyperframes#skills) and the repo `CLAUDE.md`. Two more surfaces compress the same descriptions and drift the same way, so they belong to the same sync set: the setup tables in the [prompting guide](/prompting/overview#one-time-setup) and the [quickstart](/quickstart). All of them are kept in sync when a skill is added, renamed, or has its contract changed.
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Quickstart" icon="rocket" href="/quickstart">
-    Install skills, scaffold a project, and render your first video.
-  </Card>
-  <Card title="Claude Design" icon="palette" href="/guides/claude-design">
-    Produce a valid first draft in Claude Design, then refine in any AI coding agent.
-  </Card>
-  <Card title="GitHub Copilot CLI" icon="terminal" href="/guides/copilot-cli">
-    Install and invoke HyperFrames skills from Copilot CLI in your terminal.
-  </Card>
-  <Card title="Google Antigravity" icon="atom" href="/guides/antigravity">
-    Use HyperFrames skills in Google Antigravity.
-  </Card>
-</CardGroup>
+Use the full set for an environment that must work across many HyperFrames tasks without fetching later. For a normal project, the core set is smaller and easier to keep current.
+
+## If the agent cannot see a skill
+
+1. Start a new agent session.
+2. Confirm that the project or global skill directory belongs to the agent you are using.
+3. Run `npx hyperframes skills check`.
+4. Run `npx hyperframes skills update` when the check reports a missing or stale core skill.
+
+The individual skill definitions remain the source of truth for agents and are
+available in the [HyperFrames repository](https://github.com/heygen-com/hyperframes/tree/main/skills).
+
+## Related topics
+
+- [Make your first video](/quickstart)
+- [Choose a specific creation workflow](/workflows)
+- [Use authentication and hosted services](/guides/authentication)
diff --git a/docs/guides/troubleshooting.mdx b/docs/guides/troubleshooting.mdx
index 8043e64e0b..41de0d82af 100644
--- a/docs/guides/troubleshooting.mdx
+++ b/docs/guides/troubleshooting.mdx
@@ -1,185 +1,229 @@
 ---
-title: Troubleshooting
-description: "Solutions for common Hyperframes issues."
+title: "Troubleshooting"
+description: "Solve common Studio, project, media, animation, preview, and rendering problems."
 ---
 
-If your issue is about a specific coding mistake (animations not working, video cutting off early), see [Common Mistakes](/guides/common-mistakes) first. This page covers environment, tooling, and rendering issues.
+Start with the symptom you can see. Keep the exact error and note whether the problem happens in Studio, validation, or only in the final render.
 
-<AccordionGroup>
-  <Accordion title='"No composition found"'>
-    Your directory needs an `index.html` with a valid [composition](/concepts/compositions). The root element must have a [`data-composition-id`](/concepts/data-attributes#composition-attributes) attribute.
+## Start here
 
-    **Fix:** Run `npx hyperframes init` to create a composition from an [example](/examples), or verify your `index.html` has the correct structure:
-
-    ```html index.html
-    <div id="root" data-composition-id="my-video"
-         data-width="1920" data-height="1080">
-      <!-- elements here -->
-    </div>
+<Steps>
+  <Step title="Check the machine">
+    ```bash
+    npx hyperframes doctor
     ```
-  </Accordion>
-
-  <Accordion title='"FFmpeg not found"'>
-    Local [rendering](/guides/rendering) requires FFmpeg installed on your system. Install it for your platform:
 
-    <CodeGroup>
-    ```bash macOS
-    brew install ffmpeg
+    This checks the runtime, browser, FFmpeg, and other local requirements.
+  </Step>
+  <Step title="Check the project">
+    ```bash
+    npx hyperframes lint
+    npx hyperframes check
     ```
+  </Step>
+  <Step title="Inspect the visible result">
+    Open Studio or capture important frames:
 
-    ```bash Ubuntu/Debian
-    sudo apt install ffmpeg
+    ```bash
+    npx hyperframes snapshot --at 0,3,8
     ```
+  </Step>
+  <Step title="Give the agent useful context">
+    Copy the complete error and add what you did, what you expected, and what must not change.
+  </Step>
+</Steps>
 
-    ```bash Windows
-    # Download from https://ffmpeg.org/download.html
-    # Add the bin directory to your PATH
-    ```
+For selection, canvas, timeline, autosave, and Studio-only failures, use
+[Studio troubleshooting](/studio/troubleshooting).
 
-    ```bash Verify installation
-    ffmpeg -version
-    ```
-    </CodeGroup>
+## Project and environment problems
 
-    After installing, run `npx hyperframes doctor` to verify the CLI can find it.
+### "No composition found"
 
-    <Tip>
-      If you cannot install FFmpeg, use [Docker mode](/guides/rendering) instead — it bundles FFmpeg inside the container: `npx hyperframes render --docker --output output.mp4`
-    </Tip>
-  </Accordion>
+The project needs an `index.html` containing a valid composition root with `data-composition-id`, width, and height.
 
-  <Accordion title="Lint errors">
-    Run `npx hyperframes lint` to check for common structural issues (see [CLI: lint](/packages/cli#lint)):
+Create a new project:
 
-    | Error | Meaning |
-    |-------|---------|
-    | Missing `data-composition-id` | Root element needs this attribute. See [Compositions](/concepts/compositions). |
-    | Missing `class="clip"` | Timed visible elements need this class. See [Data Attributes](/concepts/data-attributes#element-visibility). |
-    | Overlapping timelines | Clips on the same [`data-track-index`](/concepts/data-attributes#timing-attributes) cannot overlap in time. |
-    | Unmuted video elements | Video elements should be `muted` unless `data-has-audio="true"` is set. |
-    | Deprecated attribute names | `data-layer` and `data-end` have been replaced. Check the [HTML Schema Reference](/reference/html-schema). |
-  </Accordion>
+```bash
+npx hyperframes init my-video
+```
 
-  <Accordion title="Preview not updating">
-    Make sure you are editing the `index.html` in the project directory. The [preview server](/packages/cli#preview) watches for file changes and auto-reloads.
+Or compare the current source with [Compositions](/concepts/compositions).
 
-    If changes still do not appear:
+### "FFmpeg not found"
 
-    1. Check the terminal for errors from the preview server
-    2. Stop and restart `npx hyperframes preview`
-    3. Hard-refresh the browser: **Ctrl+Shift+R** (Windows/Linux) or **Cmd+Shift+R** (macOS)
-    4. Clear the browser cache if CSS changes are not reflected
-  </Accordion>
+FFmpeg is required for local video encoding.
 
-  <Accordion title="Preview stutters or plays at a low frame rate">
-    **Symptom:** Preview playback is jerky or skips frames, but the rendered mp4 looks fine.
+<CodeGroup>
+```bash macOS
+brew install ffmpeg
+```
 
-    **Cause:** Individual frames are taking longer than 16-33ms to paint. Render hides this (it captures frames one at a time), preview does not.
+```bash Ubuntu or Debian
+sudo apt install ffmpeg
+```
 
-    **Common culprits, most to least frequent:**
+```powershell Windows
+# Download a 64-bit Windows build from:
+# https://ffmpeg.org/download.html#build-windows
+# Then add its bin directory to PATH.
+```
+</CodeGroup>
 
-    - Stacked `backdrop-filter: blur()` layers, especially at radii above 32px
-    - Source images at very high resolution (above 4K) displayed in small regions
-    - `filter: blur()` or `filter: drop-shadow()` on large elements
-    - Many elements with `box-shadow` or `text-shadow` that also animate
+Verify with `ffmpeg -version`, then rerun `npx hyperframes doctor`.
 
-    **First thing to check:** does the stutter happen only during specific scenes, or throughout? Scene-specific stutter usually points at an element, often a blur overlay, that becomes visible in that scene.
+### Docker render will not start
 
-    **How to diagnose:** open Chrome DevTools, switch to the Performance tab, record a few seconds of playback, and look for long tasks labeled "Composite Layers" or "Paint". See [Performance: Measuring a slow composition](/guides/performance#measuring-a-slow-composition) for the full walkthrough.
+Run `docker info`.
 
-    **Temporary workaround:** render to mp4 and watch the output. Render is accurate regardless of per-frame cost.
+Confirm Docker is installed, its daemon is running, your user has permission, and the first image download can reach the registry.
 
-    ```bash Terminal
-    npx hyperframes render --quality draft --output preview.mp4
-    ```
+## Media problems
 
-    See [Performance](/guides/performance) for the full guide on expensive CSS patterns and how to fix them.
-  </Accordion>
+### Video is black in preview but renders
 
-  <Accordion title="Render looks different from preview">
-    Use `--docker` mode for [deterministic output](/concepts/determinism). Local renders may differ due to:
+The browser may not decode the source codec even though FFmpeg can.
 
-    - **Font availability** — different fonts on different platforms cause text reflow
-    - **Chrome version** — local Chromium vs. Docker's pinned version can render slightly differently
-    - **System-specific rendering** — GPU compositing, subpixel antialiasing, etc.
+HyperFrames normally creates and uses a compatible preview proxy. If the frame remains black:
 
-    ```bash Terminal
-    npx hyperframes render --docker --output output.mp4
-    ```
+1. confirm automatic proxying is not disabled;
+2. run `npx hyperframes doctor`;
+3. run `npx hyperframes lint --verbose` to identify affected files;
+4. confirm the source file exists and can be read.
 
-    See [Rendering: When to Use Each Mode](/guides/rendering#when-to-use-each-mode) for guidance on choosing between local and Docker rendering.
-  </Accordion>
+### Video, image, or audio is missing
 
-  <Accordion title="Docker mode fails to start">
-    Verify Docker is installed and the daemon is running:
+Prefer a local project asset. Confirm its path, filename capitalization, and whether it was moved or renamed.
 
-    ```bash Terminal
-    docker info
-    ```
+Remote media can fail because of permissions, expiring URLs, or cross-origin restrictions.
 
-    Common issues:
-    - **Docker not running:** Start Docker Desktop or the Docker daemon
-    - **Permission denied:** Add your user to the `docker` group (`sudo usermod -aG docker $USER`) and restart your shell
-    - **Image pull fails:** Check your internet connection; the first render downloads the Hyperframes Docker image
-  </Accordion>
+### Preview stutters
 
-  <Accordion title="Render is slow">
-    Try these optimizations:
+Common causes:
 
-    1. Use `--quality draft` during development for faster encoding
-    2. Run `npx hyperframes benchmark` to find the optimal worker count for your system
-    3. Local Chrome/WebGL GPU capture is enabled automatically; compare with `--no-browser-gpu` if troubleshooting
-    4. Use `--gpu` for hardware-accelerated encoding (local mode only)
-    5. Reduce `--fps` to 24 if 30fps is not needed
-    6. Check that your composition does not have unnecessary elements or overly complex animations
+- very large source images;
+- several large `backdrop-filter` blurs;
+- expensive shadows or filters on animated elements;
+- too many large overlapping layers.
 
-    See [Rendering: Options](/guides/rendering#options) for all available flags.
-  </Accordion>
+Check whether the slowdown occurs in one scene. Resize oversized media and simplify the expensive element before reducing the whole project’s quality.
 
-  <Accordion title="Video asset plays black in preview but renders fine (HEVC/H.265)">
-    Rendering decodes video assets with FFmpeg, so HEVC (H.265) inputs render correctly on every platform. Live preview is different: `preview`, `play`, Studio, and published player pages play the file in your browser, and not every browser decodes HEVC (Chrome 107+, Edge, and Safari do on most modern hardware; Firefox does not). This is now self-healing: preview detects an undecodable asset and automatically swaps in a cached H.264 proxy, so this should no longer show as a persistent black frame.
+## Animation and composition mistakes
 
-    If a hostile asset is still stuck black in preview:
+These problems often appear in agent-written or manually edited source.
 
-    1. Confirm auto-proxying is not disabled: no `--no-proxy` flag, and `media.autoProxy` is not `false` in `hyperframes.json`.
-    2. Run `npx hyperframes doctor` to confirm ffmpeg/ffprobe are installed; the proxy transcode needs both.
-    3. Run `npx hyperframes lint --verbose`: the info-level `hevc_preview_codec` finding names every affected asset.
+### A video freezes while its box animates
 
-    See [Rendering: Input Video Codecs](/guides/rendering#input-video-codecs).
-  </Accordion>
-</AccordionGroup>
+Do not animate `width`, `height`, `top`, or `left` directly on a `<video>` element.
 
-## System Diagnostics
+Put the video inside a wrapper and animate the wrapper:
 
-Run `npx hyperframes doctor` to check your environment:
+```html
+<div id="video-wrapper">
+  <video src="./assets/video.mp4" style="width:100%;height:100%"></video>
+</div>
+```
 
-```bash Terminal
-npx hyperframes doctor
+```javascript
+tl.to("#video-wrapper", { width: 500, height: 280, x: 1200 }, 2);
 ```
 
-This checks for Node.js version, FFmpeg availability, Docker status, and other requirements. If `doctor` reports issues, address them before rendering.
+### Media plays out of sync
+
+Do not call `play()`, `pause()`, or set `currentTime` from composition scripts.
+
+HyperFrames owns media playback. Use timing and media attributes to describe when the file should play.
+
+### The composition ends too early
+
+Check the resolved composition duration:
+
+```bash
+npx hyperframes compositions
+```
+
+A short animation timeline can make a project end before the underlying media. Extend the authored root duration or timeline using the correct pattern for that composition.
+
+### A timed element is always visible
+
+Timed visible elements need `class="clip"` as well as their timing attributes.
+
+```html
+<h1 class="clip" data-start="2" data-duration="5" data-track-index="0">
+  Hello
+</h1>
+```
+
+`npx hyperframes lint` normally catches this.
+
+### Animation is static
+
+Check that the animation is paused and registered using the exact composition ID.
+
+```javascript
+const timeline = gsap.timeline({ paused: true });
+window.__timelines = window.__timelines || {};
+window.__timelines["my-video"] = timeline;
+```
+
+`my-video` must match `data-composition-id="my-video"`.
+
+### Changing root duration from a variable does nothing
+
+The root render length is determined before composition scripts run. Author or generate the intended root `data-duration` directly.
+
+Clip durations can still vary. See [Variables](/concepts/variables) for what may be changed safely.
+
+## Render problems
+
+### The render looks different from preview
+
+Check fonts, remote media, browser-specific effects, and the actual exported file.
+
+Use Docker when you need a pinned rendering environment:
+
+```bash
+npx hyperframes render --docker --output output.mp4
+```
+
+### The render is slow
+
+During iteration:
+
+- use draft quality;
+- inspect snapshots before starting another full render;
+- resize large source media;
+- simplify expensive filters;
+- avoid increasing resolution or frame rate before needed.
+
+Run `npx hyperframes benchmark` when tuning worker settings.
+
+### Expected HDR but received SDR
+
+HDR needs a supported output and correct source color metadata. MP4 is the normal HDR output path; WebM and MOV may fall back to SDR.
+
+Use `--hdr` only when the whole source and delivery workflow is intended for HDR. Read [HDR rendering](/guides/hdr) before delivery.
+
+## Still stuck?
+
+Run:
+
+```bash
+npx hyperframes info
+```
 
-## Still Stuck?
+Then search [GitHub issues](https://github.com/heygen-com/hyperframes/issues) or open a report with:
 
-If none of the above resolves your issue:
+- the exact error;
+- steps to reproduce;
+- HyperFrames version and operating system;
+- whether the issue occurs in preview, checks, or render;
+- a small shareable project when possible.
 
-1. Run `npx hyperframes info` to gather system and project details
-2. Check [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for similar reports
-3. Open a new issue with the output of `npx hyperframes info` and steps to reproduce
+Do not include secrets, private media, or access tokens.
 
-## Next Steps
+## Related topics
 
-<CardGroup cols={2}>
-  <Card title="Common Mistakes" icon="triangle-exclamation" href="/guides/common-mistakes">
-    Coding pitfalls that break compositions
-  </Card>
-  <Card title="Rendering" icon="film" href="/guides/rendering">
-    Rendering modes, options, and tips
-  </Card>
-  <Card title="CLI Reference" icon="terminal" href="/packages/cli">
-    Full list of CLI commands
-  </Card>
-  <Card title="Contributing" icon="code-branch" href="/contributing">
-    Report bugs and contribute fixes
-  </Card>
-</CardGroup>
+- [Start with the shortest recovery path](/help)
+- [Recover from a Studio-only problem](/studio/troubleshooting)
+- [Share useful product feedback](/guides/feedback)
diff --git a/docs/guides/video-components.mdx b/docs/guides/video-components.mdx
index 823a607f86..4302e21ad3 100644
--- a/docs/guides/video-components.mdx
+++ b/docs/guides/video-components.mdx
@@ -1,124 +1,79 @@
 ---
-title: Video Components
-description: "Install production-ready video blocks and components from the HyperFrames catalog with one command — or contribute your own."
+title: "Use images and video"
+sidebarTitle: "Images and video"
+description: "Import, place, replace, trim, and review images and footage in a HyperFrames project."
 ---
 
-The HyperFrames **catalog** is a registry of 50+ production-ready video components — captions, code animations, social overlays, shader transitions, data viz, and more. Each one installs into any project with a single command and renders to a deterministic MP4. Don't rebuild a scene from scratch — install the one that already exists.
+Images and footage should enter the project once, remain easy to identify, and
+behave the same in preview and the final render.
 
-```bash Terminal
-npx hyperframes add x-post
+<Frame caption="Current Studio, changing the real project: inspect the source, change Fit and Position, crop on the canvas, then import another local asset.">
+  <video
+    autoPlay
+    loop
+    muted
+    playsInline
+    preload="metadata"
+    poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-media-edit-loop-v1.jpg"
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/studio-media-edit-loop-v1.mp4"
+  />
+</Frame>
+
+## Import a file
+
+In Studio:
+
+1. Open **Assets**.
+2. Choose **Import media**, or drop the file into the panel.
+3. Preview it.
+4. Drag it to the timeline.
+
+Studio accepts common image formats, SVG, MP4, WebM, and MOV. Keep the source
+inside the project before the final render.
+
+## Place it deliberately
+
+- Set the start and duration by watching the surrounding edit.
+- Choose a crop that preserves the important content.
+- Keep source audio only when it belongs in the mix.
+- Avoid stretching low-resolution media beyond what it can support.
+- Use a wrapper when animating the size or position of video; this keeps frame capture reliable.
+
+For a source-level change, ask the agent in terms of the visible result:
+
+```text
+Use assets/product-tour.mp4 from 00:04 to 00:10.
+Crop around the editor canvas, keep the source muted, and place it beneath
+the existing caption layer.
 ```
 
-## Browse the catalog
-
-<CardGroup cols={2}>
-  <Card title="Code Animations" icon="code" href="/catalog/blocks/code-morph">
-    Typing, diff, morph, highlight, scroll, and GPU 3D/particle/shader code reveals
-  </Card>
-  <Card title="Captions" icon="closed-captioning" href="/catalog/components/caption-highlight">
-    15 caption styles — karaoke, kinetic slam, neon, gradient, glitch, emoji pop
-  </Card>
-  <Card title="Social Overlays" icon="share-nodes" href="/catalog/blocks/x-post">
-    X posts, TikTok / Instagram follow cards, Reddit, Spotify, lower thirds
-  </Card>
-  <Card title="Shader Transitions" icon="bolt" href="/catalog/blocks/whip-pan">
-    14 WebGL transitions — whip pan, glitch, light leak, vortex, iris, burn
-  </Card>
-  <Card title="Liquid Glass &amp; VFX" icon="wand-magic-sparkles" href="/catalog/blocks/ios26-liquid-glass">
-    HTML-in-canvas effects — iOS 26 glass, device frames, portals, shatter, magnetic
-  </Card>
-  <Card title="Data" icon="chart-column" href="/catalog/blocks/data-chart">
-    Animated charts and US / world / region maps with bubbles, flows, and hexes
-  </Card>
-  <Card title="CSS Transitions" icon="right-left" href="/catalog/blocks/transitions-3d">
-    13 zero-dependency transitions — 3D, blur, cover, dissolve, push, radial
-  </Card>
-  <Card title="Code Snippets" icon="terminal" href="/catalog/blocks/code-snippet-dark-modern">
-    24 syntax-highlighted code cards and Apple-terminal themes
-  </Card>
-</CardGroup>
-
-Plus **Effects** (grain, vignette, shimmer, parallax), **Text Effects** (morph text, texture mask), and **Showcases** — browse them all under the [Catalog](/catalog/blocks/data-chart) tab.
-
-## Blocks vs components
-
-The catalog ships two kinds of item, installed the same way but wired differently:
-
-| | **Blocks** | **Components** |
-|---|---|---|
-| What it is | A full standalone scene | A reusable snippet / effect |
-| Has its own size & duration | Yes | No — adapts to the host |
-| Installs to | `compositions/<name>.html` | `compositions/components/<name>.html` |
-| Wired by | `data-composition-src` on a host element | Pasting its HTML / CSS / JS into your composition |
-| Examples | `x-post`, `data-chart`, `code-morph` | `grain-overlay`, `caption-highlight`, `shimmer-sweep` |
-
-## Install and wire
-
-<Steps>
-  <Step title="Find it">
-    Browse the [Catalog](/catalog/blocks/data-chart) tab, or have your AI agent consult the registry — every item lists its name, description, tags, dimensions, and duration.
-  </Step>
-  <Step title="Add it">
-    ```bash Terminal
-    npx hyperframes add data-chart
-    ```
-    The CLI writes the files and prints a snippet to paste into your host composition.
-  </Step>
-  <Step title="Wire a block">
-    Blocks are standalone compositions — include them with `data-composition-src` and a timeline position:
-    ```html index.html
-    <div
-      data-composition-id="data-chart"
-      data-composition-src="compositions/data-chart.html"
-      data-start="0"
-      data-duration="15"
-      data-track-index="1"
-      data-width="1920"
-      data-height="1080"
-    ></div>
-    ```
-  </Step>
-  <Step title="Wire a component">
-    Components are snippets — paste their HTML into your composition's markup, their CSS into your styles, and any JS into your script, then hook their timeline calls into yours.
-  </Step>
-</Steps>
-
-<Tip>
-  Using an AI agent? Install the HyperFrames skills with `npx skills add heygen-com/hyperframes` and ask it to "add a chart block" — the `/hyperframes-registry` skill discovers, installs, and wires the catalog item for you.
-</Tip>
-
-## Contribute a video component
-
-Your agent already knows how to build video components — it writes HTML, HyperFrames renders it. The registry is where that work ships to **every** HyperFrames user. Spotted a caption style on TikTok that doesn't exist yet, or built a transition worth sharing? Add it to the catalog.
-
-<Info>
-**Quick version** — Fork the repo. Write one HTML file with a paused GSAP timeline. Add `registry-item.json`. Run `hyperframes lint` + `validate`. Publish with `npx hyperframes publish`. Open a PR.
-</Info>
-
-Every item is a single self-contained HTML file with a paused GSAP timeline — no build step, no framework. It must be deterministic (seeded randomness only, no `Date.now()` / `Math.random()`), register its timeline on `window.__timelines`, and meet the production-quality bar.
-
-<CardGroup cols={2}>
-  <Card title="Contributing to the Catalog" icon="cube" href="/contributing/catalog">
-    The full idea → scaffold → build → validate → preview → ship workflow, the `registry-item.json` schema, the rules, and the quality bar
-  </Card>
-  <Card title="Open a component request" icon="lightbulb" href="https://github.com/heygen-com/hyperframes/issues/new">
-    No code needed — share a visual reference and tag it <code>component-request</code>
-  </Card>
-</CardGroup>
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Compositions" icon="layer-group" href="/concepts/compositions">
-    How blocks nest into a host composition
-  </Card>
-  <Card title="Variables" icon="sliders" href="/concepts/variables">
-    Parameterize an installed block to stay on-brand
-  </Card>
-  <Card title="The Pipeline" icon="diagram-project" href="/guides/pipeline">
-    Design → plan → layout → build → validate → render
-  </Card>
-  <Card title="Contributing to the Catalog" icon="cube" href="/contributing/catalog">
-    Add your own block or component to the registry
-  </Card>
-</CardGroup>
+## Change or replace the source
+
+Studio’s Media section shows the current project path and controls Fit,
+Position, playback, and audio. Assets imports files and adds new layers. It does
+not currently provide a one-click source replacement in that Inspector.
+
+To keep the existing layer, ask the agent to change its `src`, or edit the
+element in Source. Then recheck the crop, clip length, transition, and any
+motion tied to the old dimensions.
+
+Replacing a file should not require rebuilding the whole scene. If the new
+content also changes the story or several scenes, ask the agent to make the
+broader revision.
+
+## Avoid fragile sources
+
+Temporary signed URLs, private browser sessions, and render-time network
+requests can disappear or fail in another environment. Copy required media into
+the project, keep filenames stable, and run `npx hyperframes check` before
+rendering.
+
+Continue to [Use Assets and Catalog](/studio/assets-and-blocks) for the Studio
+controls, or [Media effects](/guides/media-effects) when the source needs a
+non-destructive visual treatment.
+
+## Related topics
+
+- [Use Assets and Catalog in Studio](/studio/assets-and-blocks)
+- [Apply a media effect](/guides/media-effects)
+- [Remove a human background](/guides/remove-background)
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index c10e106874..a057714a8b 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -1,135 +1,56 @@
 ---
-title: Introduction
-description: "Write HTML. Render video. Built for agents."
+title: "What is HyperFrames?"
+sidebarTitle: "What HyperFrames is"
+description: "See what an AI agent can make with ordinary web technology."
 ---
 
-Hyperframes is an open-source framework that turns HTML into deterministic, frame-by-frame rendered video — so you can define a video the same way you build a web page.
+import { DocsVideo, ShowcaseWall } from "/snippets/docs-video.jsx";
+import { LiveReferenceProject } from "/snippets/live-reference-project.jsx";
 
-## See It in Action
+<div className="hf-docs-video-frame">
+  <DocsVideo
+    title="What is HyperFrames?"
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-introduction-v5.mp4"
+    poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-introduction-v5.jpg"
+  />
+</div>
 
-Here is a video defined entirely as HTML:
+HyperFrames is an open-source framework that turns HTML into video. You make the request; an AI agent builds an editable project; HyperFrames plays or renders it.
 
-```html
-<div id="root" data-composition-id="demo"
-     data-start="0" data-width="1920" data-height="1080">
+## What can it make?
 
-  <video id="clip-1" data-start="0" data-duration="5"
-         data-track-index="0" src="intro.mp4" muted playsinline></video>
+Every tile below is a finished HyperFrames film. Open one to watch it with sound.
 
-  <h1 id="title" class="clip"
-      data-start="1" data-duration="4" data-track-index="1"
-      style="font-size: 72px; color: white;">
-    Welcome to Hyperframes
-  </h1>
+<ShowcaseWall />
 
-  <audio id="bg-music" data-start="0" data-duration="5"
-         data-track-index="2" data-volume="0.5" src="music.wav"></audio>
-</div>
-```
-
-Run `npx hyperframes render --output demo.mp4` and this produces an MP4 with deterministic, frame-by-frame capture. Same input, identical output, every time. No timeline editor. No proprietary format. Just HTML.
-
-<CardGroup cols={2}>
-  <Card title="Watch the Showcase" icon="play" href="/showcase">
-    Finished HyperFrames videos you can watch, read, run, and remix — product launches, website-to-video demos, UI reveals, and VFX experiments.
-  </Card>
-  <Card title="Browse the Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
-    50+ ready-to-use blocks and components — social overlays, shader transitions, data visualizations, and cinematic effects. Install any of them with one command.
-  </Card>
-  <Card title="Quick Start" icon="rocket" href="/quickstart">
-    Go from zero to rendered video in under 5 minutes.
-  </Card>
-  <Card title="Skills catalog" icon="sparkles" href="/guides/skills">
-    Every HyperFrames AI agent skill — router, creation workflows, and domain skills. Install with `npx skills add heygen-com/hyperframes`.
-  </Card>
-</CardGroup>
-
-## Why Hyperframes?
-
-<Tabs>
-  <Tab title="For developers">
-    **You already know the stack.** Compositions are HTML files with data attributes. Animations use GSAP, Lottie, CSS, or any runtime that can seek to a given frame. There is no custom DSL, no proprietary component system, and no React requirement. If you can build a web page, you can build a video.
-  </Tab>
-  <Tab title="For AI agents">
-    **Agents already speak HTML.** Most video tools require complex APIs or drag-and-drop interfaces that agents cannot operate. Hyperframes compositions are plain HTML documents — the format LLMs are best at generating. The CLI is non-interactive by default — all inputs via flags, plain text output, fail-fast on errors — so agents can drive every command without prompts or parsing.
-  </Tab>
-  <Tab title="For automated pipelines">
-    **Determinism by design.** The rendering pipeline is seek-driven with no wall-clock dependencies. `frame = floor(time * fps)` — every frame is independently captured via Chrome's `beginFrame` API and encoded with FFmpeg. Same input always produces identical output, making CI testing and batch rendering reliable.
-  </Tab>
-</Tabs>
-
-<Tip>
-  Hyperframes was designed from the ground up for AI agent integration. Compositions are plain HTML that any LLM can generate. The CLI is non-interactive by default — flag-driven with plain text output — so agents can scaffold, render, and lint without interactive prompts. Add `--human-friendly` for the interactive terminal UI. See [CLI](/packages/cli) for details.
-</Tip>
-
-## How It Works
-
-<Steps>
-  <Step title="Write HTML">
-    Define your video as an HTML document. Each element gets data attributes for timing (`data-start`, `data-duration`) and layout (`data-track-index`). Add animations with GSAP, Lottie, CSS transitions, or any seekable runtime via the Frame Adapter pattern.
-  </Step>
-  <Step title="Preview in the browser">
-    Run `npx hyperframes preview` to open a live preview in your browser. Edit your HTML and see changes instantly — no build step, no compilation.
-  </Step>
-  <Step title="Render to MP4">
-    Run `npx hyperframes render --output output.mp4` to produce a final video. The engine seeks each frame in headless Chrome, captures it with `beginFrame`, and pipes the result through FFmpeg. Run locally or in Docker for fully reproducible output.
-  </Step>
-</Steps>
-
-## Packages
-
-<CardGroup cols={2}>
-  <Card title="@hyperframes/core" icon="cube" href="/packages/core">
-    Types, HTML parsing, runtime, and composition linter — the foundation everything else builds on.
-  </Card>
-  <Card title="@hyperframes/sdk" icon="code" href="/packages/sdk">
-    Headless composition editing engine for agents, custom editors, patch events, and persistence.
-  </Card>
-  <Card title="@hyperframes/engine" icon="gear" href="/packages/engine">
-    Seekable page-to-video capture engine. Loads HTML in headless Chrome and captures frame-by-frame.
-  </Card>
-  <Card title="@hyperframes/player" icon="play" href="/packages/player">
-    Embeddable web component for playing HyperFrames compositions in any web page.
-  </Card>
-  <Card title="@hyperframes/producer" icon="video" href="/packages/producer">
-    Full rendering pipeline combining capture and FFmpeg encoding into a single API call.
-  </Card>
-  <Card title="@hyperframes/shader-transitions" icon="sparkles" href="/packages/shader-transitions">
-    WebGL shader transitions for scene-to-scene motion and render-time compositing.
-  </Card>
-  <Card title="@hyperframes/aws-lambda" icon="cloud" href="/packages/aws-lambda">
-    AWS Lambda and Step Functions adapter for distributed rendering.
-  </Card>
-  <Card title="@hyperframes/gcp-cloud-run" icon="cloud" href="/packages/gcp-cloud-run">
-    Google Cloud Run and Workflows adapter for distributed rendering.
-  </Card>
-  <Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
-    Visual composition editor UI for building and previewing timelines interactively.
-  </Card>
-  <Card title="hyperframes (CLI)" icon="terminal" href="/packages/cli">
-    Command-line tool for creating, previewing, and rendering compositions.
-  </Card>
-</CardGroup>
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Showcase" icon="play" href="/showcase">
-    Get inspired by finished videos and production launch projects.
-  </Card>
-  <Card title="Quickstart" icon="rocket" href="/quickstart">
-    Build and render your first video in 60 seconds
-  </Card>
-  <Card title="Skills catalog" icon="sparkles" href="/guides/skills">
-    Every HyperFrames AI agent skill — router, creation workflows, and domain skills
-  </Card>
-  <Card title="Compositions" icon="layer-group" href="/concepts/compositions">
-    Understand the HTML-based data model behind every video
-  </Card>
-  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
-    Add timeline-driven animations with GSAP
-  </Card>
-  <Card title="Rendering" icon="film" href="/guides/rendering">
-    Render locally, in Docker, or in a CI pipeline
-  </Card>
-</CardGroup>
+## Three things to know
+
+**Agent-built.** You describe the video; the agent writes the HTML, CSS, and JavaScript. You do not need to write code for this path.
+
+**Editable.** The result is a project folder, not a flattened black box. An agent, Studio, and your own tools can work on the same files.
+
+**Reliable render.** HyperFrames asks the project for each exact frame instead of
+depending on live playback, so a slow machine does not drop moments from the
+finished video.
+
+## Change the project yourself
+
+This is the same real HTML project used in the first-video walkthrough. Change
+its words or accent, then press Play.
+
+<LiveReferenceProject
+  src="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/index-v2.html"
+  poster="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/poster-v2.jpg"
+/>
+
+## Make one
+
+<Card title="Make your first video" icon="play" href="/quickstart" horizontal arrow>
+  Install the skills, make one short request, and choose how you want to continue.
+</Card>
+
+## Related topics
+
+- [Watch more finished HyperFrames work](/examples)
+- [Go further with an existing project](/go-further)
+- [Build on HyperFrames as a developer](/developers)
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 07f4754300..8b48a8ce21 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -1,273 +1,66 @@
 ---
-title: Quickstart
-description: "Create, preview, and render your first Hyperframes video in under two minutes."
+title: "Make your first video"
+description: "Install the HyperFrames skills, make one short request, and continue with your agent, Studio, or the CLI."
 ---
 
-Go from zero to a rendered MP4 — either by prompting your AI agent or by starting a project manually.
+import { QuickstartContinuationGrid } from "/snippets/quickstart-continuation-grid.jsx";
+import { DocsVideo } from "/snippets/docs-video.jsx";
+import { AgentAction } from "/snippets/agent-action.jsx";
 
-## Option 1: With an AI coding agent (recommended)
-
-Install the HyperFrames skills, then describe the video you want:
-
-```bash
-npx skills add heygen-com/hyperframes --full-depth
-```
-
-Keep `--full-depth`: it installs the current `main`. Without it, `skills add` fetches the skills.sh registry blob, which lags `main` by hours — you'd get stale skills.
-
-The installer shows a picker. Select the **core set** every project needs — these register as slash commands in Claude Code (Cursor, Gemini CLI, Codex, [Google Antigravity](/guides/antigravity), and [GitHub Copilot CLI](/guides/copilot-cli) load them too):
-
-| Core skill (install all) | What it does |
-|--------------------------|--------------|
-| `/hyperframes` | **The entry skill — read it first.** Orients you to the whole surface and routes "make me a video" to the right workflow |
-| `/hyperframes-core` | Composition contract — HTML structure, `data-*` attributes, clips, tracks |
-| `/hyperframes-animation` | All animation + the GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU runtime adapters |
-| `/hyperframes-creative` | Design direction — palettes, typography, narration, beat planning |
-| `/hyperframes-cli` | Dev-loop CLI — init, lint, check, preview, render, doctor |
-| `/media-use` | Asset preprocessing — TTS, transcription, background removal |
-| `/hyperframes-registry` | Install catalog blocks and components |
-| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes, plus `hyperframes keyframes` diagnostics |
-| `/general-video` | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of companion mode; the fallback when no specific workflow fits |
-
-The **workflow skills** are optional — add the ones that match your inputs, and `/hyperframes` routes to whichever you've installed: `/product-launch-video`, `/faceless-explainer`, `/pr-to-video`, `/embedded-captions`, `/talking-head-recut`, `/motion-graphics`, `/music-to-video`, `/slideshow`, `/general-video`, `/remotion-to-hyperframes`, `/figma`. See the [skills catalog](/guides/skills) for the full list with one-line "use when" descriptions.
-
-<Tip>
-  To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all --full-depth`.
-</Tip>
-
-These skills teach your agent how to write correct compositions, GSAP and runtime-adapter animations, Tailwind v4 browser-runtime styles, captions, and voiceovers. Invoking a slash command loads its context explicitly, which produces correct output the first time — and **starting at `/hyperframes` lets it route your request to the right workflow.**
+<div className="hf-docs-video-frame">
+  <DocsVideo
+    title="A beginner creates a first HyperFrames video from one short request, then continues with an agent, Studio, or the CLI."
+    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-quickstart-v5.mp4"
+    poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/journey-quickstart-v5.jpg"
+  />
+</div>
 
 <Note>
-  Claude Design uses a different entry path. Open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub, click the download button (↓) to save it, then attach to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the [Claude Design guide](/guides/claude-design).
+  HyperFrames is free and open-source, and local rendering does not use HeyGen credits. Your coding
+  agent and any optional hosted, voice, avatar, or generated-media services may have their own
+  costs.
 </Note>
 
-### Try it: example prompts
-
-Copy any of these into your agent to get started.
-
-<CardGroup cols={1}>
-  <Card title="Cold start — describe what you want">
-    > Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
-  </Card>
-  <Card title="Warm start — turn existing context into a video">
-    > 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`.
-
-    > Turn this CSV into an animated bar chart race using `/hyperframes`.
-  </Card>
-  <Card title="Format-specific">
-    > Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
-  </Card>
-  <Card title="Iterate — talk to the agent like a video editor">
-    > Make the title 2x bigger, swap to dark mode, and add a fade-out at the end.
-
-    > Add a lower third at 0:03 with my name and title.
-  </Card>
-</CardGroup>
-
-The agent handles scaffolding, animation, and rendering. See the [prompting guide](/prompting/overview) for more patterns, or the [pipeline guide](/guides/pipeline) for the 7-step structure (DESIGN, SCRIPT, STORYBOARD, …) that AI agents follow for multi-beat videos.
-
-<Tip>
-  Skills encode HyperFrames-specific patterns — like required `class="clip"` on timed elements, GSAP timeline registration, adapter registries such as `window.__hfLottie`, and `data-*` attribute semantics — that are not in generic web docs. Using skills produces correct compositions from the start.
-</Tip>
-
-## Option 2: Start a project manually
-
-### Prerequisites
-
-- **Node.js 22+** — runtime for the CLI and dev server
-- **FFmpeg** — video encoding for local renders
-
-<Accordion title="Install instructions">
-  <Steps>
-    <Step title="Install Node.js 22+">
-      Hyperframes requires Node.js 22 or later. Check your version:
-
-      ```bash
-      node --version
-      ```
-
-      ```bash Expected output
-      v22.0.0   # or any version >= 22
-      ```
-    </Step>
-
-    <Step title="Install FFmpeg">
-      FFmpeg is required for local video rendering (encoding captured frames into MP4).
+## 1. Install the skills
 
-      <CodeGroup>
-      ```bash macOS
-      brew install ffmpeg
-      ```
-      ```bash Ubuntu / Debian
-      sudo apt install ffmpeg
-      ```
-      ```bash Windows
-      # Download from https://ffmpeg.org/download.html
-      # or install via winget:
-      winget install ffmpeg
-      ```
-      </CodeGroup>
+Run this in your project folder:
 
-      Verify the installation:
-
-      ```bash
-      ffmpeg -version
-      ```
-
-      ```bash Expected output
-      ffmpeg version 7.x ...
-      ```
-    </Step>
-  </Steps>
-</Accordion>
-
-### Create your first video
-
-<Steps>
-  <Step title="Scaffold the project">
-    ```bash
-    npx hyperframes init my-video
-    cd my-video
-    ```
-
-    This starts an interactive wizard that walks you through example selection and media import. To skip prompts (e.g. in CI or from an agent), use `--non-interactive`:
-
-    ```bash
-    npx hyperframes init my-video --non-interactive --example blank
-    ```
-
-    See [Examples](/examples) for all available examples.
-
-    This generates a project structure like:
-
-    <Tree>
-      <Tree.Folder name="my-video" defaultOpen>
-        <Tree.File name="meta.json" />
-        <Tree.File name="index.html" />
-        <Tree.Folder name="compositions" defaultOpen>
-          <Tree.File name="intro.html" />
-          <Tree.File name="captions.html" />
-        </Tree.Folder>
-        <Tree.Folder name="assets" defaultOpen>
-          <Tree.File name="video.mp4" />
-        </Tree.Folder>
-      </Tree.Folder>
-    </Tree>
-
-    | Path | Purpose |
-    |------|---------|
-    | `meta.json` | Project metadata (name, ID, creation date) |
-    | `index.html` | Root composition — your video's entry point |
-    | `compositions/` | Sub-compositions loaded via `data-composition-src` |
-    | `assets/` | Media files (video, audio, images) |
-
-    If you have a source video, pass it with `--video` for automatic transcription and captions:
-
-    ```bash
-    npx hyperframes init my-video --example warm-grain --video ./intro.mp4
-    ```
-
-    `hyperframes init` installs AI agent skills automatically, so you can hand off to your AI agent at any point.
-  </Step>
-
-  <Step title="Preview in the browser">
-    ```bash
-    npx hyperframes preview
-    ```
-
-    This starts the Hyperframes Studio and opens your composition in the browser. Edits to `index.html` reload automatically.
-
-    <Tip>
-      The dev server supports hot reload — save your HTML file and the preview updates instantly, no manual refresh needed.
-    </Tip>
-  </Step>
-
-  <Step title="Edit the composition">
-    Open the project with your AI coding agent (Claude Code, Cursor, etc.) — skills are installed automatically and your agent knows how to create and edit compositions.
-
-    Or edit `index.html` directly — here's a minimal composition:
-
-    ```html index.html
-    <div id="root" data-composition-id="my-video"
-         data-start="0" data-width="1920" data-height="1080">
-
-      <!-- 1. Define a timed text clip on track 0 -->
-      <h1 id="title" class="clip"
-          data-start="0" data-duration="5" data-track-index="0"
-          style="font-size: 72px; color: white; text-align: center;
-                 position: absolute; top: 50%; left: 50%;
-                 transform: translate(-50%, -50%);">
-        Hello, Hyperframes!
-      </h1>
-
-      <!-- 2. Load GSAP for animation -->
-      <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
-
-      <!-- 3. Create a paused timeline and register it -->
-      <script>
-        const tl = gsap.timeline({ paused: true });
-        tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
-        window.__timelines = window.__timelines || {};
-        window.__timelines["my-video"] = tl;
-      </script>
-    </div>
-    ```
-
-    Three rules to remember:
+```bash
+npx skills add heygen-com/hyperframes --full-depth
+```
 
-    - **Root element** must have `data-composition-id`, `data-width`, and `data-height`
-    - **Timed elements** need `data-start`, `data-duration`, `data-track-index`, and `class="clip"`
-    - **GSAP timeline** must be created with `{ paused: true }` and registered on `window.__timelines`
-  </Step>
+Choose **Core Skills** in the picker. Keep `--full-depth` so the installer uses the current repository version. Then open or restart your coding agent in that folder.
 
-  <Step title="Validate before rendering">
-    ```bash
-    npx hyperframes lint
-    npx hyperframes check
-    ```
+## 2. Ask for the video
 
-    `lint` checks the HTML structure statically; `check` runs the composition in a headless browser and reports what a still frame can't — an element overflowing its region, colliding text, a runtime error that only fires mid-timeline, contrast below WCAG AA. Both must pass before you render: a render that took ten minutes will happily contain a defect `check` names in seconds.
-  </Step>
+```text
+Using /hyperframes, make a 10-second product intro for https://example.com.
+```
 
-  <Step title="Render to MP4">
-    ```bash
-    npx hyperframes render --output output.mp4
-    ```
+Replace `https://example.com` with the real page you want the video to show. The agent will propose
+a direction and ask for anything important that is missing. You do not need to write a production
+specification.
 
-    ```bash Expected output
-    ✔ Capturing frames... 150/150
-    ✔ Encoding MP4...
-    ✔ output.mp4 (1920x1080, 5.0s, 30fps)
-    ```
+## 3. Continue from the first version
 
-    Your video is now at `output.mp4`. Open it with any media player.
-  </Step>
-</Steps>
+The agent leaves you with an editable project folder and opens its local preview.
+To reopen that preview later, run `npx hyperframes preview` inside the project
+folder. Watch the first version once and check the story, facts, readable text,
+and sound; it is not a guaranteed final cut. All three paths below work with
+the same project.
 
-## Requirements summary
+<QuickstartContinuationGrid />
 
-| Dependency | Required | Notes |
-|-----------|----------|-------|
-| **Node.js** 22+ | Yes | Runtime for CLI and dev server |
-| **npm** or bun | Yes | Package manager |
-| **FFmpeg** | Yes | Video encoding for local renders |
-| **Docker** | No | Optional — for deterministic, reproducible renders |
+<AgentAction request="Using /hyperframes, make a 10-second product intro for https://example.com." />
 
-## Next steps
+## Related topics
 
 <CardGroup cols={2}>
-  <Card title="Browse the Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
-    50+ ready-to-use blocks — transitions, overlays, data visualizations, and effects
-  </Card>
-  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
-    Add fade, slide, scale, and custom animations to your videos
-  </Card>
-  <Card title="Examples" icon="rocket" href="/examples">
-    Start from built-in examples like Warm Grain and Swiss Grid
+  <Card title="Choose a specific workflow" icon="route" href="/workflows">
+    Product launch, explainer, captions, recut, pull request, music, motion graphic, or
+    presentation.
   </Card>
-  <Card title="Rendering" icon="film" href="/guides/rendering">
-    Explore render options: quality presets, Docker mode, and GPU acceleration
+  <Card title="Go further" icon="arrow-right" href="/go-further">
+    Direct the agent, edit in Studio, build richer projects, and finish with confidence.
   </Card>
 </CardGroup>
diff --git a/docs/weekly-updates.mdx b/docs/weekly-updates.mdx
index 882d65f93d..fea7cfb4a4 100644
--- a/docs/weekly-updates.mdx
+++ b/docs/weekly-updates.mdx
@@ -4,6 +4,8 @@ description: "Curated weekly highlights for HyperFrames."
 rss: true
 ---
 
+import { DocsVideo } from "/snippets/docs-video.jsx";
+
 Weekly HyperFrames highlights across releases, examples, docs, and community updates.
 
 For exact versioned release notes, see the [Changelog](/changelog).
@@ -17,7 +19,10 @@ For exact versioned release notes, see the [Changelog](/changelog).
 >
 
 <Frame>
-  <video controls muted playsinline src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-27-2026-08-03.mp4"></video>
+  <DocsVideo
+    title="HyperFrames video: Weekly Changelog 2026 07 27 2026 08 03"
+    src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-27-2026-08-03.mp4"
+  />
 </Frame>
 
 The Studio timeline is the headline. Expanding a track now shows one lane per animated property, with keyframe track headers, drag retiming, and virtualization on by default, and a long correctness sweep makes a keyframe edit land on the element you actually clicked. Three themed registry families add 29 catalog items from an outside contributor. Transparent GIF output works, the engine's media probing is hardened end to end, and a clean install now resolves a dependency graph with no advisories.
@@ -76,7 +81,10 @@ For exact versioned release notes, see the [Changelog](/changelog).
 >
 
 <Frame>
-  <video controls muted playsinline src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-20-2026-07-27.mp4"></video>
+  <DocsVideo
+    title="HyperFrames video: Weekly Changelog 2026 07 20 2026 07 27"
+    src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-2026-07-20-2026-07-27.mp4"
+  />
 </Frame>
 
 Professional color grading is the headline. Master and per-channel curves, hue curves, three-way wheels, and HSL secondaries land in core, Studio, and the CLI, so you can shape shadows, midtones, and highlights on any image or video without leaving the composition. The distributed plan gains an explicit protocol version and can publish artifacts straight to S3 and GCS. Studio adds a keyframe ease editor, registry caption components become transcript-driven, and a long run of audio, download, and capture reliability fixes lands underneath.
@@ -128,7 +136,10 @@ For exact versioned release notes, see the [Changelog](/changelog).
   tags={["Weekly update", "Highlights"]}
 >
 <Frame>
-  <video controls muted playsinline src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-jul13-20.mp4"></video>
+  <DocsVideo
+    title="HyperFrames video: Weekly Changelog Jul13 20"
+    src="https://static.heygen.ai/hyperframes/changelog-videos/weekly-changelog-jul13-20.mp4"
+  />
 </Frame>
 
 Automatic media proxying is the headline. Any video codec your FFmpeg can decode now plays on every live surface, from preview and Studio to play and published pages, while render keeps using the originals. Media Use gains a video generator, Studio's flat inspector ships on by default, and the engine's timeout errors now name the fix. A large batch of render, lint, and CLI reliability fixes lands alongside.

From ac9486980d8b0583929d733e8ad046d8c8565595 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 3 Aug 2026 17:43:19 -0700
Subject: [PATCH 2/5] docs: make the Reference Project links read as links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four destinations were a single bordered four-column strip, which reads as
a tab bar — a control that switches the panel below it — when every cell is a
link to GitHub. Replaced with a CardGroup, which is what AGENTS.md prescribes
for choosing between destinations, at the two columns it also prescribes.
---
 docs/examples.mdx | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/docs/examples.mdx b/docs/examples.mdx
index 846262755b..30576a0a0f 100644
--- a/docs/examples.mdx
+++ b/docs/examples.mdx
@@ -66,24 +66,20 @@ source, revision notes, checks, and final render are all public.
 Using /hyperframes, make a 10-second product intro for https://example.com.
 ```
 
-<div className="not-prose my-6 grid overflow-hidden rounded-xl border border-zinc-200 bg-white md:grid-cols-4 dark:border-zinc-800 dark:bg-zinc-950">
-  <a className="border-b border-zinc-200 p-4 text-inherit no-underline md:border-b-0 md:border-r dark:border-zinc-800" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/BRIEF.md">
-    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Brief</span>
-    <strong className="mt-1 block text-sm">What the agent decided</strong>
-  </a>
-  <a className="border-b border-zinc-200 p-4 text-inherit no-underline md:border-b-0 md:border-r dark:border-zinc-800" href="https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project">
-    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Source</span>
-    <strong className="mt-1 block text-sm">Every editable project file</strong>
-  </a>
-  <a className="border-b border-zinc-200 p-4 text-inherit no-underline md:border-b-0 md:border-r dark:border-zinc-800" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md#2-v1--v2">
-    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Revision</span>
-    <strong className="mt-1 block text-sm">What changed after review</strong>
-  </a>
-  <a className="p-4 text-inherit no-underline" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md">
-    <span className="block text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-400">Checks</span>
-    <strong className="mt-1 block text-sm">The real verification report</strong>
-  </a>
-</div>
+<CardGroup cols={2}>
+  <Card title="Brief" icon="clipboard-list" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/BRIEF.md">
+    What the agent decided before building anything.
+  </Card>
+  <Card title="Source" icon="folder-open" href="https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project">
+    Every editable project file, exactly as it renders.
+  </Card>
+  <Card title="Revision" icon="pen-to-square" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md#2-v1--v2">
+    What changed between the first and second cut, and why.
+  </Card>
+  <Card title="Checks" icon="circle-check" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md">
+    The real gate output: lint, check, contrast, and the final render.
+  </Card>
+</CardGroup>
 
 <div style={{ maxWidth: "36rem", margin: "1.5rem auto" }}>
   <DocsVideo

From 3d8db3f44e9406fe342dd2bdd36748ebc2105109 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 3 Aug 2026 21:54:59 -0700
Subject: [PATCH 3/5] docs: drop the Source group to two columns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rames' second item on #2976, fixed here because this is the line that owns it.
It was the only cols={3} in docs/, and all three cards carry body text — the
case docs/AGENTS.md names as hyphenating titles mid-word at this content width.

The rules file is #2976's deliverable, so it should not ship with the tree
beneath it holding the one counter-example.
---
 docs/guides/deploy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/deploy.mdx b/docs/guides/deploy.mdx
index 60f99a4ce7..cbc76099be 100644
--- a/docs/guides/deploy.mdx
+++ b/docs/guides/deploy.mdx
@@ -90,7 +90,7 @@ For infrastructure designed around distributed jobs, use
 
 ## Source
 
-<CardGroup cols={3}>
+<CardGroup cols={2}>
   <Card title="Vercel" icon="github" href="https://github.com/heygen-com/hyperframes-vercel-template">
     Next.js, Sandbox, and Blob
   </Card>

From b36f69a3c0b6d89365d6aa19b8aa76bd7ed8eafe Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 3 Aug 2026 22:14:46 -0700
Subject: [PATCH 4/5] docs: drop the live embed from the introduction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removed on request. The demo let a reader change a headline and an accent on a
ten-second composition, which undersold the thing the page is arguing for — the
Showcase wall above it does more for that in less space.

The component and its build apparatus go with it in #2977; nothing else on the
page referenced them.
---
 docs/introduction.mdx | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index a057714a8b..e05660e4b0 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -5,7 +5,6 @@ description: "See what an AI agent can make with ordinary web technology."
 ---
 
 import { DocsVideo, ShowcaseWall } from "/snippets/docs-video.jsx";
-import { LiveReferenceProject } from "/snippets/live-reference-project.jsx";
 
 <div className="hf-docs-video-frame">
   <DocsVideo
@@ -33,16 +32,6 @@ Every tile below is a finished HyperFrames film. Open one to watch it with sound
 depending on live playback, so a slow machine does not drop moments from the
 finished video.
 
-## Change the project yourself
-
-This is the same real HTML project used in the first-video walkthrough. Change
-its words or accent, then press Play.
-
-<LiveReferenceProject
-  src="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/index-v2.html"
-  poster="https://static.heygen.ai/hyperframes-oss/docs/reference-project/live/poster-v2.jpg"
-/>
-
 ## Make one
 
 <Card title="Make your first video" icon="play" href="/quickstart" horizontal arrow>

From f720eb75bec555e42f3dbcbc8bd9e23997c41681 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Mon, 3 Aug 2026 23:07:52 -0700
Subject: [PATCH 5/5] docs: lead the Quickstart with a paste-to-agent block,
 cut the Examples link wall
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things a non-technical reader hits that the pages did not help with.

**Quickstart made you do it by hand before you could ask.** Install through an
interactive picker, choose the right group, restart the agent, then type a
prompt — four manual terminal steps before anything happens. The copy-to-agent
affordance existed but sat at the bottom of the page, after the step it would
have replaced, and it copied only the prompt.

It leads now, with the whole thing in one visible block: install, make, open the
preview. It uses `hyperframes skills update` rather than the interactive
`skills add`, which is the command the README already says agents should run —
non-interactive, exactly the core set. The manual steps stay below for anyone
who wants to see them.

Plain code fence rather than the AgentAction component, deliberately: that
component renders a Copy button and never shows the request, so a reader copies
something they cannot read. Mintlify fences already carry a copy button and show
the text.

**Examples had four GitHub cards where one belongs.** Brief, Source, Revision,
Checks — two of them pointing into a gate-output report. That is showing
homework, not helping someone who came to see finished work. The render stays,
with one link into the folder.
---
 docs/examples.mdx   | 29 ++++++-----------------------
 docs/quickstart.mdx | 20 +++++++++++++++++---
 2 files changed, 23 insertions(+), 26 deletions(-)

diff --git a/docs/examples.mdx b/docs/examples.mdx
index 30576a0a0f..402972686d 100644
--- a/docs/examples.mdx
+++ b/docs/examples.mdx
@@ -59,27 +59,8 @@ Each preview links to the complete source project.
 
 ## One project, open end to end
 
-This is the same small project used in the Quickstart. Its request, brief,
-source, revision notes, checks, and final render are all public.
-
-```text
-Using /hyperframes, make a 10-second product intro for https://example.com.
-```
-
-<CardGroup cols={2}>
-  <Card title="Brief" icon="clipboard-list" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/BRIEF.md">
-    What the agent decided before building anything.
-  </Card>
-  <Card title="Source" icon="folder-open" href="https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project">
-    Every editable project file, exactly as it renders.
-  </Card>
-  <Card title="Revision" icon="pen-to-square" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md#2-v1--v2">
-    What changed between the first and second cut, and why.
-  </Card>
-  <Card title="Checks" icon="circle-check" href="https://github.com/heygen-com/hyperframes/blob/main/examples/docs-reference-project/VERIFICATION.md">
-    The real gate output: lint, check, contrast, and the final render.
-  </Card>
-</CardGroup>
+The same ten-second project the Quickstart builds. This is its actual render,
+and the folder behind it is public — not a sealed demo.
 
 <div style={{ maxWidth: "36rem", margin: "1.5rem auto" }}>
   <DocsVideo
@@ -89,8 +70,10 @@ Using /hyperframes, make a 10-second product intro for https://example.com.
   />
 </div>
 
-The result is not a sealed demo. Open any stage above and use the same shape for
-your own project: request → brief → source → revision → render.
+<Card title="Open the project on GitHub" icon="folder-open" href="https://github.com/heygen-com/hyperframes/tree/main/examples/docs-reference-project" horizontal arrow>
+  Every file exactly as it renders — the composition, the caption overlay, the
+  measured word timings, and the brief the agent worked from.
+</Card>
 
 ## Start from a template
 
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 8b48a8ce21..d878ddc6d6 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -5,7 +5,6 @@ description: "Install the HyperFrames skills, make one short request, and contin
 
 import { QuickstartContinuationGrid } from "/snippets/quickstart-continuation-grid.jsx";
 import { DocsVideo } from "/snippets/docs-video.jsx";
-import { AgentAction } from "/snippets/agent-action.jsx";
 
 <div className="hf-docs-video-frame">
   <DocsVideo
@@ -21,6 +20,23 @@ import { AgentAction } from "/snippets/agent-action.jsx";
   costs.
 </Note>
 
+## The short way: hand it to your agent
+
+If you already have a coding agent open in a folder, paste this and skip the
+rest of the page. It installs the skills, makes the video, and opens the
+preview — you only change the URL.
+
+```text
+Set this folder up for HyperFrames and make me a video.
+
+1. Run: npx hyperframes skills update
+2. Then, using /hyperframes, make a 10-second product intro for https://example.com
+3. Open the local preview when it is done and tell me the project folder.
+```
+
+Swap `https://example.com` for the page you want the video to show. Everything
+below is the same thing done by hand, if you would rather see each step.
+
 ## 1. Install the skills
 
 Run this in your project folder:
@@ -51,8 +67,6 @@ the same project.
 
 <QuickstartContinuationGrid />
 
-<AgentAction request="Using /hyperframes, make a 10-second product intro for https://example.com." />
-
 ## Related topics
 
 <CardGroup cols={2}>