docs: rebuild the site structure — add sections, retire superseded pages

.github/workflows/docs.yml

@@ -49,4 +49,6 @@ jobs:
 
       - name: Check broken links
         working-directory: docs
-        run: npx mint broken-links
+        # --check-redirects also resolves every redirect destination, so a
+        # restructure cannot leave a redirect pointing at a page it removed.
+        run: npx mint broken-links --check-redirects

docs/catalog/index.mdx

@@ -0,0 +1,62 @@
+---
+title: "Catalog"
+description: "Browse reusable HyperFrames scenes, transitions, captions, overlays, effects, and components."
+---
+
+The Catalog is a library of visuals you can add to a project instead of building each one from scratch.
+
+Use a **block** when you want a larger scene or self-contained visual. Use a **component** when you want a smaller effect or behavior inside an existing scene.
+
+## Start with the job
+
+<CardGroup cols={2}>
+  <Card title="Code animations" icon="code" href="/catalog/blocks/code-typing">
+    Show code being typed, changed, highlighted, scrolled, or transformed.
+  </Card>
+  <Card title="Captions" icon="closed-captioning" href="/catalog/components/caption-highlight">
+    Keep speech readable or emphasize selected words without designing a caption system from zero.
+  </Card>
+  <Card title="Transitions" icon="arrows-left-right" href="/catalog/blocks/cinematic-zoom">
+    Move between scenes with a quiet cut treatment or a more expressive transition.
+  </Card>
+  <Card title="Social overlays" icon="share-nodes" href="/catalog/blocks/x-post">
+    Show posts, follow prompts, notifications, names, roles, and platform-inspired cards.
+  </Card>
+  <Card title="Data and diagrams" icon="chart-column" href="/catalog/blocks/data-chart">
+    Explain a number, comparison, trend, location, or geographic movement.
+  </Card>
+  <Card title="Complete scenes" icon="play" href="/catalog/blocks/app-showcase">
+    Start from a larger scene that already combines design, media, and animation.
+  </Card>
+</CardGroup>
+
+## Use an item in a real project
+
+1. Open an item and watch the motion preview.
+2. Check that its communication job matches the scene.
+3. Copy the plain-language request from the item page into your agent chat.
+4. Replace the example content with real project content.
+5. Match the project's type, color, spacing, and motion language.
+6. Review the item inside the complete video, not only in isolation.
+
+The terminal command and source details remain available on each item page for people who need them.
+
+## Before you keep it
+
+<Note>
+  A Catalog item is a starting point, not a finished design decision. Keep it only when it makes the scene clearer or faster to understand. Remove decorative motion that competes with the story.
+</Note>
+
+Check:
+
+- Can the viewer understand why the visual is present?
+- Is the real content readable at the final size?
+- Does its timing fit the scenes around it?
+- Does it feel like part of this project rather than a pasted demo?
+- Is a quieter alternative more effective?
+
+## Related topics
+
+- [Add Catalog items in Studio](/studio/assets-and-blocks)
+- [Build richer compositions](/go-further)
+- [Contribute a Catalog item](/contributing/catalog)

docs/concepts/index.mdx

@@ -0,0 +1,163 @@
+---
+title: "How a HyperFrames project works"
+sidebarTitle: "Project model"
+description: "Understand the editable files, compositions, timing, and tools behind a HyperFrames video."
+---
+
+A HyperFrames project is a folder your agent can create and you can keep
+editing. Its HTML is the video: it describes the scenes, timing, motion, media,
+and reusable parts that HyperFrames plays or renders.
+
+## The source is the project
+
+The agent, Studio, CLI, SDK, and Player do not create separate versions of the
+video. They work with the same project files.
+
+| What you want to change                              | Best place to start |
+| ---------------------------------------------------- | ------------------- |
+| Story, structure, or several scenes                  | Ask the agent       |
+| Text, layout, timing, or animation you can see       | Studio              |
+| Preview, checks, snapshots, rendering, or automation | CLI                 |
+| A composition inside your own product                | SDK or Player       |
+
+<div style={{ maxWidth: "42rem", margin: "1.5rem auto" }}>
+  <Frame caption="The same editable project open in Studio, with its source, canvas, controls, and timeline.">
+    <img
+      src="https://static.heygen.ai/hyperframes-oss/docs/images/studio/overview-v1.jpg"
+      alt="A HyperFrames project open in Studio with the source tree, canvas, controls, and timeline"
+    />
+  </Frame>
+</div>
+
+Studio writes supported edits back into the source. An agent can continue from
+those files, Git can track them, and the renderer sees the same result.
+
+## What the agent creates
+
+A larger project often looks like this:
+
+```text
+project/
+├── BRIEF.md              what the video must communicate
+├── STORYBOARD.md         the planned sequence and review state
+├── SCRIPT.md             locked narration, when the video has it
+├── frame.md              visual direction, when the project needs one
+├── index.html            the main composition
+├── hyperframes.json      project settings
+├── compositions/         scenes and reusable visual parts
+├── assets/               images, video, audio, and fonts
+└── renders/              finished files
+```
+
+Only the project source is essential. Planning files exist to preserve decisions
+across reviews and agent sessions. A simple title card may need only
+`index.html` and an asset; a narrated launch film benefits from a brief,
+storyboard, script, and separate scenes.
+
+## Compositions hold the video together
+
+A **composition** is a finite, seekable piece of the project. The main
+composition is the complete sequence. Other compositions can be scenes,
+captions, title systems, or visuals reused more than once.
+
+```text
+Main video
+├── Opening
+├── Product demo
+├── Customer proof
+└── Closing
+```
+
+Each part is still HTML. A larger project stays manageable because a scene can
+be built and checked on its own, then placed on the main timeline.
+
+```html
+<div
+  data-composition-id="product-demo"
+  data-composition-src="compositions/product-demo.html"
+  data-start="4"
+  data-duration="6"
+  data-track-index="1"
+></div>
+```
+
+Edit the nested composition when the scene itself should change everywhere it
+is used. Edit its placement in the main composition when only this appearance
+should start earlier, run longer, or move to another layer.
+
+## Time is part of the source
+
+Timed elements carry their start, duration, and track in HTML:
+
+```html
+<img
+  id="product-shot"
+  class="clip"
+  data-start="2"
+  data-duration="3"
+  data-track-index="1"
+  src="./assets/product.png"
+/>
+```
+
+This image starts at two seconds, remains for three seconds, and appears on
+track one. Animation timelines are paused and seekable, so Studio, the Player,
+and the renderer can request an exact moment without playing from the
+beginning.
+
+## Variables keep approved parts changeable
+
+A variable exposes something that is meant to change—such as a title, logo,
+color, price, or customer name—without rebuilding the layout. One composition
+can produce several approved versions while preserving its design and motion.
+
+Use a variable when the structure should stay fixed. Use a normal edit when the
+structure itself needs to change.
+
+## How a project moves forward
+
+There is no required seven-step ceremony. The project records only the
+decisions its size and review process need.
+
+| Decision                       | Where it usually lives                                      |
+| ------------------------------ | ----------------------------------------------------------- |
+| What the video is for          | Your request and, for a fuller project, `BRIEF.md`          |
+| What happens and in what order | `STORYBOARD.md` and optional `SCRIPT.md`                    |
+| How it looks                   | `frame.md`, project assets, and the compositions themselves |
+| The editable result            | `index.html`, `compositions/`, and `assets/`                |
+| The approved delivery          | checks plus the file in `renders/`                          |
+
+Review the message and sequence before polishing individual frames. Once the
+project looks right, run the checks, render it, and watch the exported file.
+
+## Why rendering can repeat the same moment
+
+HyperFrames seeks the composition to an exact time, captures the frame, and
+advances. Media and audio follow the same timeline.
+
+For the same source, media, and settings, an exact timestamp should resolve to
+the same project state. Compositions therefore avoid the current clock,
+unseeded randomness, and render-time network requests.
+
+## Go deeper when you need it
+
+<CardGroup cols={2}>
+  <Card title="Reuse a design with variables" icon="sliders" href="/concepts/variables">
+    Expose approved content without opening the layout.
+  </Card>
+  <Card title="Finish and share a video" icon="circle-check" href="/guides/export-and-share">
+    Review, check, render, watch, and deliver the same project.
+  </Card>
+  <Card title="Composition structure" icon="layer-group" href="/concepts/compositions">
+    Use nested compositions and exact source attributes.
+  </Card>
+  <Card title="HTML schema" icon="code" href="/reference/html-schema">
+    Look up the complete technical composition contract.
+  </Card>
+</CardGroup>
+
+## Related topics
+
+- [Take more control of an existing project](/go-further)
+- [Look up the complete HTML schema](/reference/html-schema)
+- [Choose a developer integration surface](/developers/overview)

docs/deploy/overview.mdx

@@ -0,0 +1,99 @@
+---
+title: "Choose a rendering path"
+sidebarTitle: "Rendering overview"
+description: "Choose the smallest HyperFrames rendering surface for local work, an application backend, managed cloud, or infrastructure you operate."
+---
+
+Every rendering path starts with the same HyperFrames project. The difference is
+who operates Chrome and FFmpeg, how the request is submitted, and how much of the
+pipeline your application needs to control.
+
+| Need | Start with | You operate |
+| --- | --- | --- |
+| Render while creating or in CI | **CLI** | The machine running the command |
+| Render from a Node application | **Producer** | The Node service and its runtime |
+| Control exact frame capture | **Engine** | Capture, encoding, and orchestration |
+| Submit a render without managing infrastructure | **HyperFrames Cloud** | Nothing beyond the request and result |
+| Run distributed renders in your AWS account | **AWS Lambda** | The deployed AWS stack |
+| Run distributed renders in your Google Cloud account | **Cloud Run** | The deployed GCP resources |
+| Deploy a preview and render API from a template | **Hosted templates** | The selected hosting account |
+
+## Local or CI: use the CLI
+
+The CLI owns the complete normal pipeline: project loading, checks, browser
+capture, audio mixing, and encoding.
+
+```bash
+npx hyperframes check
+npx hyperframes render --output video.mp4
+```
+
+Start here unless an application—not a person or CI job—must initiate the
+render. See [Rendering](/guides/rendering) for the normal workflow and the
+[complete CLI reference](/packages/cli) for automation flags.
+
+## A Node application: use Producer
+
+`@hyperframes/producer` is the complete programmable render pipeline. It is the
+right layer for a backend that needs to provide project input, receive progress,
+cancel work, or control encoding without spawning the CLI.
+
+```ts
+import { createRenderJob, executeRenderJob } from "@hyperframes/producer";
+
+const job = createRenderJob({ fps: 30, quality: "standard" });
+await executeRenderJob(job, "./project", "./video.mp4");
+```
+
+Use [Producer](/packages/producer) for its current configuration and exported
+API. Use Engine only when Producer performs work your application must replace.
+
+## Exact frame capture: use Engine
+
+`@hyperframes/engine` opens a seekable composition and captures exact frames.
+It does not replace the complete Producer pipeline.
+
+Use it when building specialized capture, inspection, or rendering
+infrastructure. For an ordinary encoded video, stay with CLI or Producer. See
+[Engine](/packages/engine).
+
+## No infrastructure: use HyperFrames Cloud
+
+Managed cloud rendering accepts a project, runs the render, and returns the
+finished file without requiring local Chrome or FFmpeg.
+
+```bash
+npx hyperframes cloud render ./project --output video.mp4
+```
+
+Authentication, variables, webhooks, and job management are covered in
+[Cloud rendering](/deploy/cloud).
+
+## Infrastructure you control
+
+Use [AWS Lambda](/deploy/aws-lambda) or [Google Cloud Run](/deploy/gcp-cloud-run)
+when renders must run inside your own cloud account. Both paths distribute work
+across workers and store intermediate and final media in the corresponding
+cloud storage.
+
+Use the [hosted templates](/guides/deploy) when the desired result is a small
+preview application plus a render API on Vercel, Cloudflare, or Modal—not a
+general distributed-rendering platform.
+
+## The decision
+
+Choose the highest-level surface that completes the job:
+
+```text
+CLI → Producer → Engine
+```
+
+Moving right gives an application more control and more pipeline responsibility.
+Managed Cloud, AWS Lambda, Cloud Run, and hosted templates decide where that
+pipeline runs.
+
+## Related topics
+
+- [Render with the CLI](/guides/rendering)
+- [Render with HyperFrames Cloud](/deploy/cloud)
+- [Use Producer from a Node application](/packages/producer)

docs/developers/cli.mdx

@@ -0,0 +1,62 @@
+---
+title: "CLI guide"
+description: "Find the HyperFrames command for creating, checking, rendering, publishing, and automating projects."
+---
+
+Use this page to choose a command. The [CLI reference](/packages/cli) contains
+detailed flags, examples, and environment settings. The installed version
+remains authoritative: run `npx hyperframes <command> --help`.
+
+## Everyday project loop
+
+| Task | Command |
+| --- | --- |
+| Create a project | `npx hyperframes init my-video` |
+| Open Studio | `npx hyperframes preview` |
+| Check HTML structure | `npx hyperframes lint` |
+| Run browser, layout, motion, and contrast checks | `npx hyperframes check` |
+| Capture review frames | `npx hyperframes snapshot --at 0,2,5` |
+| Render a video | `npx hyperframes render --output output.mp4` |
+| Publish a browser link | `npx hyperframes publish` |
+| Diagnose the machine | `npx hyperframes doctor` |
+
+## Work with media
+
+| Task | Command |
+| --- | --- |
+| Inspect project metadata | `npx hyperframes info` |
+| Transcribe speech | `npx hyperframes transcribe <file>` |
+| Generate narration | `npx hyperframes tts <script>` |
+| Capture a website | `npx hyperframes capture <url>` |
+
+## Reuse and inspect
+
+| Task | Command |
+| --- | --- |
+| Add a Catalog item | `npx hyperframes add <name>` |
+| List compositions | `npx hyperframes compositions` |
+| Inspect keyframe behavior | `npx hyperframes keyframes` |
+| Compare outputs | `npx hyperframes compare` |
+
+## Rendering and automation
+
+The CLI also supports:
+
+- batch and variable-driven output;
+- image sequences and several video formats;
+- managed cloud rendering;
+- AWS Lambda and Google Cloud Run workflows;
+- machine-readable JSON output;
+- publishing and shared spaces.
+
+Start with the simple command, then open the [full reference](/packages/cli) for the exact options needed by automation or infrastructure.
+
+<Tip>
+  Run `npx hyperframes <command> --help` for the installed version’s exact syntax.
+</Tip>
+
+## Related topics
+
+- [Open the complete CLI reference](/packages/cli)
+- [Choose a rendering path](/deploy/overview)
+- [Diagnose a CLI or project problem](/guides/troubleshooting)