From f5201aa97c399e84197d2fe30e497ae074c05a1d Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Tue, 28 Jul 2026 19:16:15 -0700 Subject: [PATCH 01/46] docs: refactor documentation around user workflows --- .gitignore | 4 + README.md | 6 +- docs/AGENTS.md | 60 + docs/catalog/blocks/app-showcase.mdx | 29 +- docs/catalog/blocks/apple-money-count.mdx | 29 +- .../blocks/blue-sweater-intro-video.mdx | 29 +- .../catalog/blocks/chromatic-radial-split.mdx | 29 +- docs/catalog/blocks/cinematic-zoom.mdx | 29 +- docs/catalog/blocks/code-3d-extrude.mdx | 29 +- docs/catalog/blocks/code-diff.mdx | 29 +- docs/catalog/blocks/code-highlight.mdx | 29 +- docs/catalog/blocks/code-morph.mdx | 29 +- .../catalog/blocks/code-particle-assemble.mdx | 29 +- docs/catalog/blocks/code-scroll.mdx | 29 +- docs/catalog/blocks/code-shader-dissolve.mdx | 29 +- .../code-snippet-apple-terminal-basic.mdx | 60 +- ...code-snippet-apple-terminal-clear-dark.mdx | 59 +- ...ode-snippet-apple-terminal-clear-light.mdx | 60 +- .../code-snippet-apple-terminal-grass.mdx | 60 +- .../code-snippet-apple-terminal-homebrew.mdx | 59 +- .../code-snippet-apple-terminal-man-page.mdx | 60 +- .../code-snippet-apple-terminal-novel.mdx | 59 +- .../code-snippet-apple-terminal-ocean.mdx | 59 +- .../code-snippet-apple-terminal-pro.mdx | 59 +- .../code-snippet-apple-terminal-red-sands.mdx | 59 +- ...-snippet-apple-terminal-silver-aerogel.mdx | 59 +- ...de-snippet-apple-terminal-solid-colors.mdx | 59 +- .../catalog/blocks/code-snippet-dark-2026.mdx | 55 +- .../blocks/code-snippet-dark-modern.mdx | 55 +- .../catalog/blocks/code-snippet-dark-plus.mdx | 55 +- docs/catalog/blocks/code-snippet-flight.mdx | 29 +- .../code-snippet-high-contrast-light.mdx | 55 +- .../blocks/code-snippet-high-contrast.mdx | 55 +- .../blocks/code-snippet-light-2026.mdx | 55 +- .../blocks/code-snippet-light-modern.mdx | 55 +- .../blocks/code-snippet-light-plus.mdx | 55 +- docs/catalog/blocks/code-snippet-monokai.mdx | 55 +- .../blocks/code-snippet-solarized-light.mdx | 55 +- .../code-snippet-visual-studio-dark.mdx | 55 +- .../code-snippet-visual-studio-light.mdx | 55 +- docs/catalog/blocks/code-typing.mdx | 29 +- docs/catalog/blocks/cross-warp-morph.mdx | 29 +- docs/catalog/blocks/data-chart.mdx | 29 +- docs/catalog/blocks/domain-warp-dissolve.mdx | 29 +- docs/catalog/blocks/flash-through-white.mdx | 29 +- docs/catalog/blocks/flowchart-vertical.mdx | 29 +- docs/catalog/blocks/flowchart.mdx | 29 +- docs/catalog/blocks/glitch.mdx | 29 +- docs/catalog/blocks/gravitational-lens.mdx | 29 +- docs/catalog/blocks/instagram-follow.mdx | 29 +- docs/catalog/blocks/ios26-liquid-glass.mdx | 59 +- docs/catalog/blocks/light-leak.mdx | 29 +- .../blocks/liquid-glass-context-menu.mdx | 30 +- .../blocks/liquid-glass-media-controls.mdx | 30 +- .../blocks/liquid-glass-notification.mdx | 31 +- docs/catalog/blocks/liquid-glass-widgets.mdx | 31 +- docs/catalog/blocks/logo-outro.mdx | 29 +- docs/catalog/blocks/lower-third-bild.mdx | 29 +- docs/catalog/blocks/lt-accent-underline.mdx | 29 +- docs/catalog/blocks/lt-bold-block.mdx | 29 +- docs/catalog/blocks/lt-clean-bar.mdx | 29 +- docs/catalog/blocks/lt-color-block.mdx | 29 +- docs/catalog/blocks/lt-dark-card.mdx | 29 +- docs/catalog/blocks/lt-kicker-name.mdx | 29 +- docs/catalog/blocks/lt-mask-reveal.mdx | 29 +- docs/catalog/blocks/lt-side-rule.mdx | 29 +- docs/catalog/blocks/lt-soft-pill.mdx | 29 +- docs/catalog/blocks/lt-stack-bars.mdx | 29 +- docs/catalog/blocks/macos-notification.mdx | 29 +- .../blocks/macos-tahoe-liquid-glass.mdx | 51 +- docs/catalog/blocks/news-ticker.mdx | 29 +- .../blocks/north-korea-locked-down.mdx | 29 +- docs/catalog/blocks/nyc-paris-flight.mdx | 29 +- docs/catalog/blocks/reddit-post.mdx | 29 +- docs/catalog/blocks/ridged-burn.mdx | 29 +- docs/catalog/blocks/ripple-waves.mdx | 29 +- docs/catalog/blocks/sdf-iris.mdx | 29 +- docs/catalog/blocks/spain-map.mdx | 29 +- docs/catalog/blocks/spotify-card.mdx | 29 +- docs/catalog/blocks/swirl-vortex.mdx | 29 +- docs/catalog/blocks/thermal-distortion.mdx | 29 +- docs/catalog/blocks/tiktok-follow.mdx | 29 +- docs/catalog/blocks/transitions-3d.mdx | 29 +- docs/catalog/blocks/transitions-blur.mdx | 29 +- docs/catalog/blocks/transitions-cover.mdx | 29 +- .../blocks/transitions-destruction.mdx | 29 +- docs/catalog/blocks/transitions-dissolve.mdx | 29 +- .../catalog/blocks/transitions-distortion.mdx | 29 +- docs/catalog/blocks/transitions-grid.mdx | 29 +- docs/catalog/blocks/transitions-light.mdx | 29 +- .../catalog/blocks/transitions-mechanical.mdx | 29 +- docs/catalog/blocks/transitions-other.mdx | 29 +- docs/catalog/blocks/transitions-push.mdx | 29 +- docs/catalog/blocks/transitions-radial.mdx | 29 +- docs/catalog/blocks/transitions-scale.mdx | 29 +- docs/catalog/blocks/ui-3d-reveal.mdx | 29 +- docs/catalog/blocks/us-map-bubble.mdx | 29 +- docs/catalog/blocks/us-map-flow.mdx | 29 +- docs/catalog/blocks/us-map-hex.mdx | 29 +- docs/catalog/blocks/us-map.mdx | 29 +- docs/catalog/blocks/vfx-iphone-device.mdx | 29 +- docs/catalog/blocks/vfx-liquid-background.mdx | 29 +- docs/catalog/blocks/vfx-liquid-glass.mdx | 29 +- docs/catalog/blocks/vfx-magnetic.mdx | 29 +- docs/catalog/blocks/vfx-portal.mdx | 29 +- docs/catalog/blocks/vfx-shatter.mdx | 29 +- docs/catalog/blocks/vfx-text-cursor.mdx | 29 +- docs/catalog/blocks/vpn-youtube-spot.mdx | 29 +- docs/catalog/blocks/whip-pan.mdx | 29 +- docs/catalog/blocks/world-map.mdx | 29 +- docs/catalog/blocks/x-post.mdx | 29 +- docs/catalog/blocks/yt-lower-third.mdx | 29 +- .../components/caption-blend-difference.mdx | 31 +- docs/catalog/components/caption-clip-wipe.mdx | 29 +- .../components/caption-editorial-emphasis.mdx | 29 +- docs/catalog/components/caption-emoji-pop.mdx | 29 +- .../catalog/components/caption-glitch-rgb.mdx | 29 +- .../components/caption-gradient-fill.mdx | 29 +- docs/catalog/components/caption-highlight.mdx | 29 +- .../components/caption-kinetic-slam.mdx | 29 +- .../components/caption-matrix-decode.mdx | 29 +- .../components/caption-neon-accent.mdx | 29 +- docs/catalog/components/caption-neon-glow.mdx | 29 +- .../components/caption-parallax-layers.mdx | 29 +- .../components/caption-particle-burst.mdx | 29 +- .../components/caption-pill-karaoke.mdx | 29 +- docs/catalog/components/caption-texture.mdx | 29 +- .../components/caption-weight-shift.mdx | 29 +- docs/catalog/components/grain-overlay.mdx | 29 +- .../catalog/components/grid-pixelate-wipe.mdx | 29 +- docs/catalog/components/morph-text.mdx | 31 +- docs/catalog/components/motion-blur.mdx | 57 +- docs/catalog/components/parallax-unzoom.mdx | 29 +- docs/catalog/components/parallax-zoom.mdx | 29 +- docs/catalog/components/shimmer-sweep.mdx | 29 +- docs/catalog/components/texture-mask-text.mdx | 22 +- docs/catalog/components/vignette.mdx | 29 +- docs/catalog/index.mdx | 46 + docs/community/adopters.mdx | 2 +- docs/concepts/compositions.mdx | 4 +- docs/concepts/data-attributes.mdx | 4 +- docs/concepts/determinism.mdx | 6 +- docs/concepts/frame-adapters.mdx | 10 +- docs/concepts/index.mdx | 25 + docs/concepts/variables.mdx | 2 +- docs/contributing.mdx | 20 +- docs/contributing/catalog.mdx | 2 +- docs/contributing/changelog-process.mdx | 6 +- .../studio-manual-dom-editing.mdx | 315 -- .../migrating-to-hyperframes-lambda.mdx | 2 +- docs/developers/cli.mdx | 54 + docs/developers/index.mdx | 39 + docs/docs.json | 834 +++-- docs/examples.mdx | 401 +- docs/guides/4k-rendering.mdx | 6 +- docs/guides/antigravity.mdx | 4 +- docs/guides/authentication.mdx | 2 +- docs/guides/captions-and-recuts.mdx | 42 + docs/guides/choose-your-path.mdx | 39 + docs/guides/claude-design.mdx | 152 - docs/guides/common-mistakes.mdx | 289 -- docs/guides/common-questions.mdx | 79 + docs/guides/copilot-cli.mdx | 4 +- docs/guides/create-with-agent.mdx | 104 + docs/guides/deploy.mdx | 6 +- docs/guides/design-tools.mdx | 57 + docs/guides/export-and-share.mdx | 31 + docs/guides/faceless-explainer.mdx | 38 + docs/guides/feedback.mdx | 250 +- docs/guides/general-video.mdx | 35 + docs/guides/gsap-animation.mdx | 10 +- docs/guides/hdr.mdx | 18 +- docs/guides/help.mdx | 33 + docs/guides/html-in-canvas.mdx | 2 - docs/guides/hyperframes-vs-remotion.mdx | 183 +- docs/guides/index.mdx | 27 + docs/guides/mcp.mdx | 363 +- docs/guides/media.mdx | 31 + docs/guides/motion-graphics.mdx | 30 + docs/guides/music-to-video.mdx | 39 + docs/guides/open-design.mdx | 175 - docs/guides/performance.mdx | 2 +- docs/guides/pipeline.mdx | 245 +- docs/guides/pr-to-video.mdx | 35 + docs/guides/product-launch-video.mdx | 62 + docs/guides/project-tour.mdx | 69 + docs/guides/prompting.mdx | 329 +- docs/guides/publish-and-share.mdx | 52 + docs/guides/quality-checklist.mdx | 59 + docs/guides/rendering.mdx | 461 +-- docs/guides/skills.mdx | 4 +- docs/guides/timeline-editing.mdx | 110 - docs/guides/transcribe-and-caption.mdx | 41 + docs/guides/troubleshooting.mdx | 304 +- docs/guides/video-components.mdx | 173 +- docs/guides/video-editor-cheatsheet.mdx | 300 -- docs/guides/voice-and-audio.mdx | 38 + docs/guides/website-to-video.mdx | 238 -- docs/images/studio/export.jpg | Bin 0 -> 84259 bytes docs/images/studio/inspector.jpg | Bin 0 -> 85528 bytes docs/images/studio/overview.jpg | Bin 0 -> 75899 bytes docs/images/studio/storyboard.jpg | Bin 0 -> 67207 bytes docs/introduction.mdx | 167 +- docs/launch-videos.mdx | 73 - docs/packages/cli.mdx | 24 +- docs/packages/core.mdx | 10 +- docs/packages/engine.mdx | 10 +- docs/packages/lint.mdx | 2 +- docs/packages/producer.mdx | 4 +- docs/packages/studio.mdx | 10 +- docs/product-updates.mdx | 47 + docs/public/catalog-index.json | 3248 ++++++++++------- docs/quickstart.mdx | 320 +- docs/reference/html-schema.mdx | 10 +- docs/showcase.mdx | 262 -- docs/studio/animation.mdx | 52 + docs/studio/assets-and-blocks.mdx | 38 + docs/studio/canvas.mdx | 54 + docs/studio/captions.mdx | 32 + docs/studio/design.mdx | 44 + docs/studio/export.mdx | 44 + docs/studio/index.mdx | 70 + docs/studio/layers.mdx | 30 + docs/studio/lint-and-agent.mdx | 48 + docs/studio/shortcuts.mdx | 40 + docs/studio/slideshows.mdx | 33 + docs/studio/source.mdx | 30 + docs/studio/storyboard.mdx | 54 + docs/studio/timeline.mdx | 59 + docs/studio/tour.mdx | 84 + docs/studio/troubleshooting.mdx | 52 + docs/studio/variables.mdx | 32 + docs/weekly-updates.mdx | 11 - research/docs-audit/current-state.html | 255 ++ research/docs-refactor/NOTES.md | 195 + research/docs-refactor/PLAN.md | 247 ++ research/docs-refactor/rebuild-navigation.mjs | 362 ++ scripts/generate-catalog-pages.ts | 77 +- 238 files changed, 9592 insertions(+), 7596 deletions(-) create mode 100644 docs/AGENTS.md create mode 100644 docs/catalog/index.mdx create mode 100644 docs/concepts/index.mdx delete mode 100644 docs/contributing/studio-manual-dom-editing.mdx create mode 100644 docs/developers/cli.mdx create mode 100644 docs/developers/index.mdx create mode 100644 docs/guides/captions-and-recuts.mdx create mode 100644 docs/guides/choose-your-path.mdx delete mode 100644 docs/guides/claude-design.mdx delete mode 100644 docs/guides/common-mistakes.mdx create mode 100644 docs/guides/common-questions.mdx create mode 100644 docs/guides/create-with-agent.mdx create mode 100644 docs/guides/design-tools.mdx create mode 100644 docs/guides/export-and-share.mdx create mode 100644 docs/guides/faceless-explainer.mdx create mode 100644 docs/guides/general-video.mdx create mode 100644 docs/guides/help.mdx create mode 100644 docs/guides/index.mdx create mode 100644 docs/guides/media.mdx create mode 100644 docs/guides/motion-graphics.mdx create mode 100644 docs/guides/music-to-video.mdx delete mode 100644 docs/guides/open-design.mdx create mode 100644 docs/guides/pr-to-video.mdx create mode 100644 docs/guides/product-launch-video.mdx create mode 100644 docs/guides/project-tour.mdx create mode 100644 docs/guides/publish-and-share.mdx create mode 100644 docs/guides/quality-checklist.mdx delete mode 100644 docs/guides/timeline-editing.mdx create mode 100644 docs/guides/transcribe-and-caption.mdx delete mode 100644 docs/guides/video-editor-cheatsheet.mdx create mode 100644 docs/guides/voice-and-audio.mdx delete mode 100644 docs/guides/website-to-video.mdx create mode 100644 docs/images/studio/export.jpg create mode 100644 docs/images/studio/inspector.jpg create mode 100644 docs/images/studio/overview.jpg create mode 100644 docs/images/studio/storyboard.jpg delete mode 100644 docs/launch-videos.mdx create mode 100644 docs/product-updates.mdx delete mode 100644 docs/showcase.mdx create mode 100644 docs/studio/animation.mdx create mode 100644 docs/studio/assets-and-blocks.mdx create mode 100644 docs/studio/canvas.mdx create mode 100644 docs/studio/captions.mdx create mode 100644 docs/studio/design.mdx create mode 100644 docs/studio/export.mdx create mode 100644 docs/studio/index.mdx create mode 100644 docs/studio/layers.mdx create mode 100644 docs/studio/lint-and-agent.mdx create mode 100644 docs/studio/shortcuts.mdx create mode 100644 docs/studio/slideshows.mdx create mode 100644 docs/studio/source.mdx create mode 100644 docs/studio/storyboard.mdx create mode 100644 docs/studio/timeline.mdx create mode 100644 docs/studio/tour.mdx create mode 100644 docs/studio/troubleshooting.mdx create mode 100644 docs/studio/variables.mdx delete mode 100644 docs/weekly-updates.mdx create mode 100644 research/docs-audit/current-state.html create mode 100644 research/docs-refactor/NOTES.md create mode 100644 research/docs-refactor/PLAN.md create mode 100644 research/docs-refactor/rebuild-navigation.mjs diff --git a/.gitignore b/.gitignore index 52719ff212..0f14be0d7a 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,10 @@ 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 videos/ diff --git a/README.md b/README.md index a94b9cd123..cab728d92d 100644 --- a/README.md +++ b/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 --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 --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 ` before entering one. Nothing re-pulls the full set behind your back. diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000000..4c323cb76b --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,60 @@ +# 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 navigation shallow. Use clickable overview pages and collapsed nested groups. +- 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. + +## 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. diff --git a/docs/catalog/blocks/app-showcase.mdx b/docs/catalog/blocks/app-showcase.mdx index 640804ad77..c338cfc02b 100644 --- a/docs/catalog/blocks/app-showcase.mdx +++ b/docs/catalog/blocks/app-showcase.mdx @@ -3,15 +3,22 @@ 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`