docs: refactor documentation around user workflows

.gitignore

@@ -22,6 +22,17 @@ Thumbs.db
 # with `bun run upload:docs-images`. Add explicit negations below for any
 # non-generated assets (logos, svgs) that should stay in the repo.
 docs/images/
+!docs/images/
+docs/images/*
+!docs/images/studio/
+!docs/images/studio/*.jpg
+# The introduction's explainer film. Not a generated preview: it is authored, it
+# is the page's whole argument, and at 332KB silent it costs less than one
+# catalog preview. Committed so the page cannot break when a CDN credential
+# expires. The version with its music bed lives on the CDN instead.
+!docs/images/showcase/
+!docs/images/showcase/*.mp4
+!docs/images/showcase/*.jpg
 
 videos/
 

README.md

@@ -41,7 +41,7 @@ Install the HyperFrames skills, then describe the video you want:
 npx skills add heygen-com/hyperframes --full-depth
 ```
 
-> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas a non-interactive `skills add` without `--skill` installs all 19.
+> The picker opens with nothing pre-selected — the **Core Skills** group is all you need: the `/hyperframes` router installs each creation workflow on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas a non-interactive `skills add` without `--skill` installs the full set.
 >
 > `--full-depth` does a full clone of the repo's current `main`. Without it, `skills add` fetches the skills.sh registry blob, which lags `main` by hours — you'd get an older copy of a skill. (`hyperframes skills update` already installs full-depth.)
 
@@ -53,9 +53,9 @@ The skills teach agents the HyperFrames production loop: plan the video, write v
 
 ## Skills
 
-HyperFrames ships 19 skills agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below.
+HyperFrames ships skills that agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below.
 
-Default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes --full-depth`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs all 19. Use `npx skills add heygen-com/hyperframes --all --full-depth` to install all 19 deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill <name> --full-depth` for just one (bare name, no leading `/`). Keep `--full-depth` — it installs the current `main`; without it `skills add` fetches the skills.sh blob, which lags by hours.
+Default to the **core set** — the router installs each creation workflow on demand. `npx hyperframes skills update` installs exactly that from anywhere; the interactive picker (`npx skills add heygen-com/hyperframes --full-depth`) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without `--skill` installs the full set. Use `npx skills add heygen-com/hyperframes --all --full-depth` to install everything deliberately (skips the picker), or `npx skills add heygen-com/hyperframes --skill <name> --full-depth` for just one (bare name, no leading `/`). Keep `--full-depth` — it installs the current `main`; without it `skills add` fetches the skills.sh blob, which lags by hours.
 
 Installs stay lean after that: `npx hyperframes init` keeps the **core set** fresh (the router, the `hyperframes-*` domain skills, and `media-use` — plus whatever is already installed; `/figma` stays on demand) and never expands a partial install; the creation workflows install **on demand** — the router runs `npx hyperframes skills update <workflow>` before entering one. Nothing re-pulls the full set behind your back.
 

docs/AGENTS.md

@@ -0,0 +1,124 @@
+# HyperFrames documentation rules
+
+Before changing anything in `docs/`, read:
+
+1. `../research/docs-refactor/PLAN.md`
+2. `../research/docs-refactor/NOTES.md`
+3. The complete body of every page you plan to change
+4. The product source or tests that prove the behavior being documented
+
+These rules are persistent and apply to every documentation session:
+
+- Write for a smart general user first. Do not assume they are a developer.
+- Explain what a person can accomplish before explaining implementation details.
+- Prefer plain words, short examples, screenshots, and visible outcomes.
+- Keep agent instructions copyable and specific.
+- Put CLI, SDK, package, schema, deployment, and internals under **Developers**.
+- Never infer product behavior from page titles or old docs. Verify it in current code.
+- Do not preserve a page merely because it already exists. Merge, rewrite, redirect, or remove it when that improves the user journey.
+- Do not publish empty, duplicated, outdated, or aspirational content as fact.
+- A page should answer a real question or help complete a real task.
+- Keep ordinary top-level groups inside each tab, with no nested `root`, `directory`, `expanded`, or drilldown behavior.
+- Match the deployed main docs' sidebar rhythm: 14px medium group headings, square links, no horizontal group dividers, and a segmented vertical rail whose active segment follows the current page. Groups remain open and non-collapsible.
+- Keep the Aspen sidebar aligned to the 56px header and disable its early scroll-fade mask.
+- Keep Mintlify's right-side **On this page** behavior and styling unchanged.
+- Keep Aspen's desktop header on one row: logo, tabs, search, compact GitHub link with its star count, Playground action, and theme toggle. Preserve the fixed-width star-count fallback so client-side navigation does not make the control blink or collapse.
+- Keep the bottom-center agent input visually distinct from the page with its own surface, stronger border, and restrained shadow.
+- Record important findings, uncertainties, and decisions in `../research/docs-refactor/NOTES.md`.
+- Update progress and changed decisions in `../research/docs-refactor/PLAN.md`.
+
+## Page standard
+
+Most human-facing pages should contain:
+
+1. What this lets you do
+2. When to use it
+3. A visual or concrete example
+4. The shortest successful path
+5. What should happen
+6. Common problems
+7. Useful next steps
+
+Do not force this structure where it makes a page worse. Reference pages may stay reference-shaped.
+
+## Component doctrine
+
+One component per job. If two components on a page render the same list, delete one.
+
+| The job | Use | Never use |
+| --- | --- | --- |
+| Choose between destinations | `CardGroup` + `Card`, max 2 columns, linking to the real page | An accordion, or cards pointing at anchors on the same page |
+| Ordered instructions | `Steps` | A flow diagram that repeats the same steps |
+| Parallel variants of one instruction (source type, OS, language) | `Tabs` | Repeating the whole block per variant |
+| Compare attributes across items | A table | Prose paragraphs per item |
+| Any media | `Frame` with a caption that says what it is | A bare `img` with no context |
+| Genuinely out-of-band aside | One `Note`, `Tip`, or `Warning` per page | Stacked callouts, or a callout for ordinary prose |
+
+**Accordions are not used.** They hide the thing the reader is choosing between, cost a click, break `Cmd+F` and printing, and render as grey bars. Long symptom or reference lists become visible `##` sections instead — they get anchors the support team can link directly, and they appear in the page contents.
+
+**No diagram that restates adjacent prose.** A four-node flow beside a four-step list is the same content twice. Keep whichever is more useful and delete the other.
+
+**Cards link to pages, never to anchors on the current page.** A card that scrolls the reader a short distance to the same words is the worst pattern in these docs; it has been removed twice.
+
+**Two columns is the practical maximum** for anything containing text. Three columns in this content width hyphenates titles mid-word.
+
+### Custom React components
+
+Mintlify compiles `.jsx` / `.tsx` from `docs/snippets/`. Use one when a native component genuinely cannot express the idea — a scrubber, a comparison slider, a live player — not for styling.
+
+- Named exports only: `export const Thing = () => ...`. Default exports do not work.
+- `useState`, `useEffect`, `useRef`, `useCallback`, `useMemo`, `useContext`, `useReducer` are pre-injected; do not import React.
+- **No third-party packages and no CDN scripts.** Browser built-ins only (`fetch`, `IntersectionObserver`, Canvas, `<video>`). This rules out importing `@hyperframes/player` as a package — embed a hosted composition in an `iframe` instead.
+- A snippet cannot import another snippet. Keep each self-contained.
+- **Declare everything inside the component.** Only the exported component survives
+  compilation; module-level `const`s above it are dropped, so a constant defined
+  outside arrives `undefined` at render. The component then throws inside React,
+  the error boundary swallows it, and the page renders nothing at that position —
+  with no console error to point at it. If a snippet renders blank, check this first.
+- Client-side only: guard anything touching `window` and give every component a sensible first paint.
+- Respect `prefers-reduced-motion`, give interactive elements a visible focus state, and never make a component the only route to information.
+
+### Raw HTML gotchas
+
+**Utility classes are rewritten, and unknown ones are dropped.** Mintlify moves
+Tailwind classes into its own `mint-*` namespace during the build. Write utilities
+for layout that the theme already uses (`flex`, `rounded-xl`, `border`) and do not
+rely on anything exotic surviving. Anything load-bearing belongs in `custom.css`
+under an `hf-` class — those pass through untouched.
+
+**Every `<img>` is wrapped in the image-zoom component.** The real markup is
+`span[data-rmiz] > span[data-rmiz-content] > picture.contents > img`, so a width
+set on a surrounding `div` is absorbed and the image renders full width — which
+silently pushes a side-by-side card's text out of view. Use the `.hf-peek` class,
+which collapses that wrapper, or use a `<video>`: videos are not wrapped, which is
+why the same card layout works with one.
+
+Prose styles also add a 2em margin to media, which shows as a band inside any
+wrapper with its own background. Zero it when the wrapper is the frame.
+
+### Width and media
+
+The content column is widened in `custom.css` — a measured 888px at a 1600px viewport, 1048px at 1920px, where it used to be stuck at 664px. There is no paragraph measure cap: these pages are built from lists, tables, cards, and code, so a whole guide contains roughly three `<p>` elements and capping them changed nothing. Add `className="hf-wide"` when a visual should escape any inherited measure.
+
+## Verification
+
+After navigation or MDX changes:
+
+```bash
+PATH=/opt/homebrew/opt/node@20/bin:$PATH mint validate
+PATH=/opt/homebrew/opt/node@20/bin:$PATH mint broken-links
+```
+
+Use Bun for repository work. Do not create a `pnpm-lock.yaml`.
+
+## Freshness and ownership
+
+- A product behavior page is owned by the team that owns the matching product surface.
+- A package or API reference is owned by the package maintainer.
+- Workflow pages are owned by the maintainer of the matching agent skill.
+- When a feature changes, update its task guide, related troubleshooting entry, and screenshot in the same pull request.
+- Treat screenshots as product claims. Replace them when labels, layout, or the demonstrated workflow changes materially.
+- Review **Start here**, **Studio**, **Export**, and **Troubleshooting** at least once per release cycle.
+- Review lower-traffic reference pages at least quarterly.
+- Remove an unowned update feed instead of letting it become stale.
+- Use search analytics and support questions to decide which missing task pages to add next.

docs/catalog/blocks/app-showcase.mdx

@@ -3,23 +3,34 @@ title: "App Showcase"
 description: "Fitness app product showcase with three floating smartphone screens"
 ---
 
-# App Showcase
-
 Fitness app product showcase with three floating smartphone screens
 
 `showcase` `app` `3d`
 
 <video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/app-showcase.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/app-showcase.png" autoPlay muted loop playsInline />
 
-## Install
+## Add it to a project
+
+<Tabs>
+
+<Tab title="Ask your agent">
+
+```text
+Add the App Showcase block from the HyperFrames Catalog to this project.
+Replace the demo content with mine and match the existing design and timing.
+```
+
+</Tab>
 
-<CodeGroup>
+<Tab title="Terminal">
 
-```bash Terminal
+```bash
 npx hyperframes add app-showcase
 ```
 
-</CodeGroup>
+</Tab>
+
+</Tabs>
 
 ## Details
 
@@ -29,15 +40,17 @@ npx hyperframes add app-showcase
 | Dimensions | 1920×1080 |
 | Duration | 5.5s |
 
-## Files
+**Installed files**
 
 | File | Target | Type |
 | --- | --- | --- |
 | `app-showcase.html` | `compositions/app-showcase.html` | hyperframes:composition |
 
-## Usage
+## Use it
+
+Ask your agent to replace the example content, match the project style, and place the block at the right moment in the video.
 
-After installing, add the block to your host composition:
+**Wiring it by hand.** The installed block can be added to a host composition with:
 
 ```html
 <div data-composition-id="app-showcase" data-composition-src="compositions/app-showcase.html" data-start="0" data-duration="5.5" data-track-index="1" data-width="1920" data-height="1080"></div>

docs/catalog/blocks/apple-money-count.mdx

@@ -3,8 +3,6 @@ title: "Apple Money Count"
 description: "Apple-style finance counter that counts from $0 to $10,000, flashes green, and bursts money icons with sound."
 ---
 
-# Apple Money Count
-
 Apple-style finance counter that counts from $0 to $10,000, flashes green, and bursts money icons with sound.
 
 `showcase` `finance` `kinetic` `youtube` `sfx`
@@ -19,15 +17,28 @@ Created by [Stronkter](https://x.com/Stronkter).
 
 <video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/apple-money-count.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/apple-money-count.png" autoPlay muted loop playsInline />
 
-## Install
+## Add it to a project
+
+<Tabs>
+
+<Tab title="Ask your agent">
 
-<CodeGroup>
+```text
+Add the Apple Money Count block from the HyperFrames Catalog to this project.
+Replace the demo content with mine and match the existing design and timing.
+```
 
-```bash Terminal
+</Tab>
+
+<Tab title="Terminal">
+
+```bash
 npx hyperframes add apple-money-count
 ```
 
-</CodeGroup>
+</Tab>
+
+</Tabs>
 
 ## Details
 
@@ -37,16 +48,18 @@ npx hyperframes add apple-money-count
 | Dimensions | 1920×1080 |
 | Duration | 5s |
 
-## Files
+**Installed files**
 
 | File | Target | Type |
 | --- | --- | --- |
 | `apple-money-count.html` | `compositions/apple-money-count.html` | hyperframes:composition |
 | `assets/sfx-production.wav` | `assets/sfx-production.wav` | hyperframes:asset |
 
-## Usage
+## Use it
+
+Ask your agent to replace the example content, match the project style, and place the block at the right moment in the video.
 
-After installing, add the block to your host composition:
+**Wiring it by hand.** The installed block can be added to a host composition with:
 
 ```html
 <div data-composition-id="apple-money-count" data-composition-src="compositions/apple-money-count.html" data-start="0" data-duration="5" data-track-index="1" data-width="1920" data-height="1080"></div>

docs/catalog/blocks/blue-sweater-intro-video.mdx

@@ -3,8 +3,6 @@ title: "Blue Sweater Intro Video"
 description: "Warm AI creator intro sequence that resolves into an X follow card for @_blue_sweater_."
 ---
 
-# Blue Sweater Intro Video
-
 Warm AI creator intro sequence that resolves into an X follow card for @_blue_sweater_.
 
 `showcase` `ai` `creator` `sfx`
@@ -13,15 +11,28 @@ Created by [Joe Sai](https://x.com/_blue_sweater_).
 
 <video className="w-full aspect-video rounded-xl object-cover bg-zinc-100 dark:bg-zinc-800" src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/blue-sweater-intro-video.mp4" poster="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/blue-sweater-intro-video.png" autoPlay muted loop playsInline />
 
-## Install
+## Add it to a project
+
+<Tabs>
+
+<Tab title="Ask your agent">
+
+```text
+Add the Blue Sweater Intro Video block from the HyperFrames Catalog to this project.
+Replace the demo content with mine and match the existing design and timing.
+```
+
+</Tab>
 
-<CodeGroup>
+<Tab title="Terminal">
 
-```bash Terminal
+```bash
 npx hyperframes add blue-sweater-intro-video
 ```
 
-</CodeGroup>
+</Tab>
+
+</Tabs>
 
 ## Details
 
@@ -31,17 +42,19 @@ npx hyperframes add blue-sweater-intro-video
 | Dimensions | 1920×1080 |
 | Duration | 12s |
 
-## Files
+**Installed files**
 
 | File | Target | Type |
 | --- | --- | --- |
 | `blue-sweater-intro-video.html` | `compositions/blue-sweater-intro-video.html` | hyperframes:composition |
 | `assets/joe-sai-avatar.png` | `assets/joe-sai-avatar.png` | hyperframes:asset |
 | `assets/sfx/integrated-melodic-tech-mix.wav` | `assets/sfx/integrated-melodic-tech-mix.wav` | hyperframes:asset |
 
-## Usage
+## Use it
+
+Ask your agent to replace the example content, match the project style, and place the block at the right moment in the video.
 
-After installing, add the block to your host composition:
+**Wiring it by hand.** The installed block can be added to a host composition with:
 
 ```html
 <div data-composition-id="blue-sweater-intro-video" data-composition-src="compositions/blue-sweater-intro-video.html" data-start="0" data-duration="12" data-track-index="1" data-width="1920" data-height="1080"></div>