heygen-com__hyperframes/research/docs-refactor/PLAN.md

HyperFrames documentation refactor

Current approval gate

Approved by the product owner on 2026-07-29. The four journey pages exist, but the complete documentation is still in an accuracy, consolidation, visual-proof, and verification pass. Do not describe the refactor as finished until every gate at the end of this plan passes.

The product owner refined the information model on 2026-07-30. Four maturity journeys are now the canonical front doors:

1. Understand HyperFrames — /introduction
2. Create a first video — /quickstart
3. Go further — /go-further
4. Build on HyperFrames — /developers

Workflows, Studio, Catalog, export, and troubleshooting are destinations inside these journeys rather than competing front doors.

The approved journeys become the source of truth for:

• canonical starting links;
• page priority and order;
• required videos and diagrams;
• navigation;
• consolidation and removal decisions;
• analytics and usability tests.

The route-to-journey contract is maintained in JOURNEY-IMPLEMENTATION-MAP.md.

Status: full content rebuild in progress Started: 2026-07-28 Primary audience: people who want to make, edit, and share videos with HyperFrames Secondary audience: developers integrating or extending HyperFrames

This is the durable plan for the documentation refactor. Read it before doing docs work, including after a chat compaction or in a future session.

Goal

Turn the docs from a repository-shaped collection of pages into a useful product guide.

A visitor should quickly understand:

• what HyperFrames does;
• whether they should use an agent, Studio, or both;
• how to complete a real video task;
• where to find a feature they saw in the product;
• what to send someone who asks “how do I do this?”;
• where technical reference lives when they actually need it.

The docs should feel clear, capable, visual, and human. They should not read like an API dump, marketing filler, or instructions written only for framework contributors.

Current journey rebuild

The four canonical journey pages are being rebuilt as complete front doors:

1. /introduction — understand HyperFrames;
2. /quickstart — create a first video;
3. /go-further — gain more control;
4. /developers — build on HyperFrames.

Each page begins with one complete narrated film and continues with a concise written expansion. The shared film series uses River narration, burned phrase captions, an intentional music arc, purposeful SFX, real product behavior, and real HyperFrames source. Long films use controls and do not autoplay or loop.

The approved Mintlify header, left sidebar, right table of contents, theme, and page-width behavior remain unchanged.

Current execution order — 2026-07-31

1. Correct factual contradictions, fake or missing product surfaces, duplicate routes, and Guides/Developers information architecture.
2. Replace route-only hubs with pages that teach a useful mental model or first result before linking deeper.
3. Add current, truthful visual proof to the highest-use Studio pages.
4. Replace the Studio front-door film with a current project, River narration, the shared media typography, and the approved caption rail.
5. Verify commands and claims against current source, tests, CLI help, skills, and official host documentation.
6. Run Mintlify validation, broken links, desktop/mobile review, media checks, accessibility checks, and final source diff review before pushing.

Completed in the current pass:

• exhaustive action audit for all 115 Guides, Studio, and Developers routes;
• corrected authentication, variable-binding, and Studio autosave contradictions;
• rebuilt Guides and Developers navigation around human tasks and the smallest technical surface;
• added a neutral rendering/deployment chooser;
• rewrote the main Media, SDK, Go further, Skills, Design import, Variables, and support routes so they perform a task rather than act as directories;
• removed a nonexistent Media Overlays product surface and redirected its old route;
• merged duplicate Project Tour and Common Questions routes into their actual destinations;
• reduced three oversized media guides from implementation memos to task guides.
• corrected the Player page against the current package, including supported attributes, controls, and event cadence;
• corrected Studio auto-keyframe and save semantics against current source: auto-keyframing starts enabled, Preview edits autosave, and Storyboard drafts keep explicit Save actions;
• verified the current hyperframes media-treatment command and aligned the grading/effects guides with its capability-discovery, local-analysis, apply, preview, clear, and data-color-grading behavior;
• corrected the CLI skills lifecycle against the current implementation: complete bare install, freshness check, and targeted update.
• verified and rebuilt the deployment chooser, hosted templates, AWS Lambda, and Google Cloud Run guides against current source, CLI help, and live template repositories;
• reduced the advanced 4K, HDR, and performance pages to task-focused references and removed volatile benchmark claims;
• rewrote the contributor and Catalog-contribution entry pages against current scripts and schemas;
• retired the duplicate Weekly Updates route in favor of Product Updates and the release archive;
• removed broken cross-origin TT Norms loading from the Mintlify shell while keeping the approved Inter UI and the changelog fonts inside authored films.

Still required:

• current visual proof across the Studio manual;
• final Studio film production and approval;
• source-by-source verification of the remaining developer/reference examples;
• final Mintlify, responsive, media, accessibility, and link gates.

Navigation decision

Use four top-level header tabs:

1. Guides — start here, create with an agent, workflows, core ideas, media, export, troubleshooting, and product updates.
2. Studio — the complete visual editor manual.
3. Catalog — browsable blocks and components.
4. Developers — CLI, SDK, packages, schemas, deployment, integrations, and contributing.

Global header:

• Use Mintlify’s Aspen theme. A desktop and mobile preview confirmed that it provides the desired full-width header without custom CSS.
• HyperFrames logo on the left.
• Search remains prominent.
• GitHub link on the right.
• Light/dark theme toggle remains available.
• Primary Playground action to the official hyperframes.dev browser experience. Studio itself remains project-local through npx hyperframes preview.
• Keep Aspen’s full-width top navigation. Use the small desktop-only layout override needed to fit the logo, tabs, search, actions, and theme toggle on one row.
• Keep every left-sidebar group open and non-collapsible. Match the deployed main docs' spacing, group-heading scale, square link treatment, and segmented active-page rail.
• Keep Mintlify’s default right-side On this page behavior and styling.
• Align Aspen's sticky sidebar to the actual 56px header, remove its premature scroll fade, keep the GitHub star count, and use main's quieter structural border color.
• Keep the floating agent input easy to notice without making it visually dominant.

Navigation behavior:

• Every tab uses ordinary top-level groups, matching origin/main.
• Group labels are static section headings; only actual pages navigate.
• Do not add root, directory, expanded, or drilldown behavior.
• Keep Mintlify's default sidebar and On this page rendering unchanged.
• Human-facing labels describe tasks, not repository packages.
• Updates is not a top-level tab.

Target information architecture

Guides

• Start here
  • What HyperFrames is
  • Make your first video
  • Go further
  • Build on HyperFrames
• Create with an agent
  • Choose a workflow
  • Give the agent a useful brief
  • Review and improve a result
  • Product and website videos
  • Explainers
  • PR and changelog videos
  • Captions and talking-head recuts
  • Motion graphics
  • Music-driven videos
  • Slideshows
• Learn
  • Composition basics
  • Timing and tracks
  • Animation basics
  • Reusable variables
  • Nested compositions
  • Deterministic rendering
• Media
  • Images and video
  • Voice and audio
  • Captions and transcription
  • Background removal
  • Color grading
• Export and share
  • Choose a format
  • Export from Studio
  • Render from the CLI
  • 4K and HDR
  • Publish and share
• Help
  • Troubleshooting
  • Common questions
  • Give feedback
• What’s new
  • Product updates
  • Detailed release archive

Studio

• Studio overview and tour
• Storyboard
• Canvas editing
• Layers and groups
• Timeline editing
• Animation and keyframes
• Assets and reusable blocks
• Text, layout, style, media, 3D, and color controls
• Captions
• Variables and templates
• Slideshows
• Source editor
• Lint and fixing issues
• Export queue
• Keyboard shortcuts
• Troubleshooting

Catalog

• Visual catalog home
• Blocks
• Components
• Categories and search
• Add an item
• Customize an item
• Build and contribute an item

Individual item pages stay concise and visual. Their shared generator owns the agent prompt, install path, and progressive disclosure of technical details.

Developers

• Developer overview
• CLI
• SDK
• Player
• Packages
• HTML schema
• Advanced rendering
• Deployment
• MCP and integrations
• Contributing
• Release process

Content decisions

• Rewrite Introduction and Quickstart around outcomes and user paths.
• Create real Studio documentation from current product behavior.
• Move user-facing Studio material out of Contributing.
• Merge Packages, SDK, and Reference into Developers.
• Remove Weekly updates until it has real content and an owner.
• Keep one human-readable product updates page and one detailed release archive.
• Merge Showcase and Launch Videos into one examples area.
• Merge overlapping Claude Design and Open Design guidance.
• Replace the stale Website to Video workflow with the current Product Launch workflow.
• Merge Common Mistakes into a useful troubleshooting hub.
• Replace the giant CLI wall with task guides plus a searchable command reference.
• Add the MCP guide to navigation.
• Correct installation guidance:
  • Agent/non-interactive default: npx hyperframes skills update
  • Interactive picker: npx skills add heygen-com/hyperframes --full-depth

Writing principles

• Lead with the result, not setup.
• Use “you” and name visible controls exactly as they appear.
• One page, one main job.
• Prefer short sentences and meaningful headings.
• Show a successful path before edge cases.
• Explain technical vocabulary the first time it appears.
• Do not make humans learn internal architecture unless it helps them act.
• Do not hide important caveats.
• No filler introductions, fake enthusiasm, or repetitive summaries.
• Use screenshots, short clips, diagrams, and examples when they reduce uncertainty.
• Technical detail belongs in a Developer section or a clearly labeled advanced section.

Evidence standard

Every feature claim must come from at least one current source:

• shipped product code;
• tests;
• CLI help/output;
• schemas and public types;
• current agent skills;
• a confirmed live product flow.

Old docs and changelogs are leads, not proof.

Execution phases

Phase 1 — Foundation

• Audit public pages and product capabilities.
• Produce a visual coverage report.
• Agree on four top-level tabs.
• Create persistent plan, notes, and docs rules.
• Implement the header/navigation shell.
• Add overview pages required by the new hierarchy.

Phase 2 — Critical truth fixes

• Remove the “no timeline editor” claim.
• Correct timeline splitting guidance.
• Correct skills installation commands in the main user paths.
• Add MCP to navigation.
• Remove or redirect the empty Weekly Updates page and stale Website to Video and Timeline Editing pages.

Phase 3 — Human starting experience

• Rewrite Introduction.
• Rewrite Quickstart.
• Add Choose your path.
• Add workflow chooser.
• Rebuild examples around real outcomes.

Phase 4 — Studio

• Create the first complete Studio section.
• Verify each control and workflow in current code.
• Add the first real Studio workspace visual.
• Add focused visuals for difficult interactions.
• Move or redirect the buried manual-editing page.
• Replace the Studio front-door film with a current narrated product walkthrough.
• Recapture the Studio stills and four task loops from the same real project.
• Publish the final Studio media under immutable versioned CDN URLs.

Phase 5 — Consolidation

• Consolidate the highest-impact overlapping guides.
• Reorganize developer material under one top-level section.
• Add a task-based CLI guide in front of the complete command reference.
• Separate product updates from raw release history.
• Improve catalog browsing and repeated item content.

Phase 6 — Quality and maintenance

• Run Mintlify validation and broken-link checks.
• Review desktop and mobile navigation.
• Add and visually review sendable routes for common user questions.
• Add page ownership and freshness rules.
• Merge the current main prompting guide and product changes before final QA.
• After release, use Mintlify analytics to inspect real searches, no-result queries, and weak result ranking.

Deliverables

• Visual audit: ../docs-audit/report.html
• Audit data: ../docs-audit/audit-data.json
• Working notes: NOTES.md
• Documentation rules: ../../docs/AGENTS.md
• Refactored Mintlify site: ../../docs/