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

# HyperFrames documentation refactor notes

This is the working notebook for facts, judgments, questions, and progress. Keep raw observations here; keep durable decisions in `PLAN.md`.

## 2026-07-31 — content correction and consolidation pass

- `guides/video-components.mdx` was labeled and linked as “Images and video”
  but contained a Catalog-components guide. It now performs the actual image
  and footage task.
- `guides/media-overlays.mdx` duplicated treatment-overlay blocks already owned
  by the Registry and implied a separate Studio insertion surface. The page and
  nav entry were removed; the old URL redirects to the real Catalog.
- `concepts/compositions.mdx` incorrectly said declarative `data-var-*`
  bindings do not exist. Runtime code, tests, the HTML schema, and the Variables
  page prove `data-var-text`, `data-var-src`, and scalar CSS bindings are
  supported. The contradiction is corrected.
- General authentication no longer claims that everything works without a key.
  Local creation/media have fallbacks; managed cloud and hosted MCP require
  authentication. First-time `publish` works anonymously and returns a claim
  URL; sign-in is needed for immediate ownership, in-place updates, and shared
  spaces.
- Studio source and visual edits autosave. Troubleshooting now asks users to
  save only files changed in an external editor or by an agent.
- Project Tour duplicated Concepts and Pipeline; its useful file map moved into
  `/concepts` and the old route redirects there.
- Common Questions repeated the journey, Studio, media, export, and support
  pages; it was removed from navigation and redirected to `/help`.
- The 3,339-word background-removal page, 1,757-word color-grading page, and
  1,509-word media-effects page were reduced to task guides. Exact flags and
  persistence contracts already live in CLI and schema reference.
- Current official host documentation was checked before updating the MCP
  setup: Claude custom connectors, ChatGPT MCP apps/developer mode, and Grok
  custom connectors have different plan and workspace requirements.
- The Studio front-door film passed its planning gate and is now in production
  under `scratchpad/studio-front-door-v2`. It uses a new real `Field Notes`
  project, River narration, the TT Norms media identity from the changelog
  workflow, the shared caption rail, music, sound, and real Studio capture. Do
  not integrate or upload it until the render, contact sheet, lint/check logs,
  media probe, and docs-width review pass.
- Source verification corrected several inherited absolutes and stale details:
  - seek-driven rendering does not promise identical pixels across machines;
  - HTML-in-Canvas is experimental and falls back to normal capture;
  - the current variable contract has seven types, including `font` and
    `image`;
  - the exported `FrameAdapter` utility is an experimental v0 API rather than
    the complete internal renderer contract;
  - current Remotion Studio supports direct visual editing and saves back to
    React code;
  - Figma storyboard reconstruction can use REST frame exports and does not
    require an MCP connector.
  - `hyperframes media-treatment` is a current, tested CLI command. It
    discovers the capability surface, analyzes local media, and applies,
    previews, or clears the same `data-color-grading` contract Studio uses.
  - Studio's current Effects surface is broader than Blur and Pixelate:
    Essentials, Retro & Glitch, Print, and Art groups are implemented in source.
  - The source-of-truth pass now targets a clean snapshot of current
    `origin/main`, not the older merge base of the docs branch. Final review
    requires rebasing/merging current main before sign-off.

## Baseline audit

- Public navigation contains 213 pages.
- 133 are catalog entries.
- 80 are non-catalog documentation pages.
- Current top tabs are Documentation, Catalog, Packages, SDK, and Reference.
- Product capability matrix: 82 capabilities.
  - Covered: 21
  - Partial: 29
  - Misplaced: 2
  - Wrong: 5
  - Missing: 25
- Studio capability matrix: 35 capabilities.
  - Covered: 1
  - Partial: 15
  - Misplaced: 1
  - Wrong: 2
  - Missing: 16
- Non-catalog docs contain about 130,000 words.
- The CLI package page alone contains more than 10,000 words.
- `mint validate` and `mint broken-links` passed before the refactor.
- Mintlify CLI currently needs Node 20 locally. Default Node 26 is unsupported.

## Confirmed content problems

- `introduction.mdx` says there is no timeline editor. This is false.
- `guides/timeline-editing.mdx` says split is unsupported. Studio ships split at playhead, a razor tool, and split-all behavior.
- Several guides use incomplete or outdated skills installation guidance.
- `packages/studio.mdx` documents the Studio package and embedding surface, not how to use the Studio product.
- `contributing/studio-manual-dom-editing.mdx` contains important user-facing Studio behavior in the wrong section.
- `weekly-updates.mdx` has almost no content.
- `guides/mcp.mdx` exists but is not in public navigation.
- `guides/website-to-video.mdx` describes a workflow now handled by Product Launch Video.
- Showcase and Launch Videos overlap.
- Claude Design and Open Design overlap.
- Common Mistakes and Troubleshooting overlap.

## Current Studio facts verified in source

- Storyboard and Preview modes.
- Storyboard board/source views, frame statuses, focus, comments, direction, voiceover iteration, and agent handoff.
- Canvas selection and direct manipulation: move, resize, rotate, crop, nudge, snapping, marquee, groups, and stacking order.
- Layers panel.
- Timeline move, trim, split, razor, split-all, snapping, beats, zoom, auto-keyframe, keyframe diamonds, nested composition expansion, breadcrumbs, and multi-drag.
- GSAP animation editing, speed curves, per-keyframe easing, keyframe CRUD and retiming, motion paths, gesture recording, and computed-tween unrolling.
- Property controls for text, layout, style, media, 3D, and color grading.
- Assets import, preview, cross-project assets, and timeline drag/drop.
- Blocks browsing, search, insertion, and drag/drop.
- Source editor and file tree.
- Variables creation, binding, and live preview.
- Captions timeline, properties, and animation.
- Slideshow slides, notes, fragment holds, branches, and hotspots.
- Lint modal and copy-issues-to-agent.
- Render queue with MP4, WebM, MOV, quality, resolution, FPS, cancel, download, delete, and hide-finished controls.
- Undo/redo, capture current frame, and Ask Agent.

## Navigation judgment

The existing navigation is repository-shaped:

- Packages, SDK, and Reference are separate top-level destinations.
- Studio has no top-level human manual.
- General workflows are mixed with implementation concepts and deployment.
- Important pages compete with changelog and empty weekly updates in Getting Started.

New navigation should be task-shaped:

- Guides
- Studio
- Catalog
- Developers

## Header judgment

- Use the native Mintlify Aspen theme.
- Aspen was tested with the real refactored docs at desktop and 390px mobile widths.
- It provides a genuine full-width top header with logo, search, GitHub, primary action, and theme toggle.
- It places the four section tabs in a second full-width row.
- Maple was rejected because its header began after the left sidebar and kept the logo and theme toggle inside the sidebar column.
- Current logo is already configured for light and dark modes.
- The default appearance now follows the user’s system setting.
- Add GitHub and a primary action.
- Confirm the canonical Studio URL before adding the primary action.
- The temporary primary action is **Get started** and points to Quickstart.
- Keep Aspen's full-width header. A desktop-only layout override is intentional so the logo, tabs, search, actions, and theme toggle fit on one row.

## Questions to verify during implementation

- What is the canonical public Studio URL?
- Is Studio always used locally, hosted publicly, or both?
- Which screenshots can be generated from stable fixture projects?
- Which product workflows deserve separate pages based on actual user questions?
- Should old release URLs remain public but hidden, or redirect to a release archive?
- Is there an existing analytics baseline for searches and failed searches?

## Work log

### 2026-07-28

- Completed repository and public-doc audit.
- Built validated interactive report in `research/docs-audit/report.html`.
- Selected four-tab architecture.
- Created persistent docs rules, plan, and notes.
- Rebuilt navigation as Guides, Studio, Catalog, and Developers.
- Added collapsible nested groups and folded all Catalog categories by default.
- Switched from Maple to Aspen after desktop and mobile visual comparison.
- Rewrote Introduction and Quickstart.
- Added Guides, Catalog, Developers, concepts, media, export, help, product-launch, and path-selection landing pages.
- Added a 17-page Studio user section.
- Retired the empty Weekly Updates page.
- Replaced the stale Website to Video and incorrect Timeline Editing pages with redirects.
- Added MCP to public navigation.
- Corrected the main outdated skills installation commands.
- Mintlify build validation and broken-link checks passed after the first implementation pass.

### 2026-07-28 — second pass

- Added sendable, task-first pages for project structure, faceless explainers, PR videos, captions and recuts, motion graphics, music-driven videos, general video, voice and audio, transcription, quality review, and publishing.
- Merged Claude Design and Open Design into one maintained Design tools page.
- Merged Common Mistakes into a symptom-first Troubleshooting hub and redirected the old URL.
- Merged Showcase and Launch Videos into one Examples page with real finished work, source links, and starter templates.
- Added a human-readable Product updates page while keeping Changelog as the complete release archive.
- Added a task-based CLI guide before the full command reference.
- Removed the buried Studio manual-editing page and redirected it to the current user-facing Canvas guide.
- Retired the overlapping video-editor cheatsheet in favor of the current Studio shortcuts and task guides.
- Added Authentication and the orphaned Motion Blur component to public navigation. Every remaining MDX page is now reachable from navigation.
- Captured the current Studio from the included storyboard fixture and added the real workspace image to the Studio tour.
- Added freshness and ownership rules to `docs/AGENTS.md`.
- Mintlify build validation and broken-link checks passed after the second pass.

### 2026-07-28 — Studio and Catalog verification pass

- Verified the Studio manual against current UI source, tests, and a running Studio fixture.
- Corrected conceptual or outdated panel names to the visible controls people actually see:
  - top bar: Storyboard, Preview, Capture, Inspector, Export;
  - left sidebar: Code, Comps, Assets, Catalog;
  - inspector: Design, Layers, Renders, Slideshow when applicable, Variables;
  - lower-left action: Lint.
- Verified Code autosave, Assets project scopes, Catalog insertion behavior, render formats and controls, lint handoff, storyboard status meanings, and current keyboard shortcuts.
- Added real 1280×720 Studio images for the workspace, Storyboard, Inspector, and Renders panel.
- Added a narrow `.gitignore` exception for `docs/images/studio/*.jpg` so these authored screenshots are included while generated Catalog media remains ignored.
- Corrected the Storyboard feedback loop to **Save & copy message** followed by pasting into agent chat.
- Documented that `SCRIPT.md`, when present, is the final narration source and that **Open in Preview** applies to built frames.
- Reworked the Catalog page generator for all 134 items:
  - removed duplicate body titles;
  - added a plain-language agent request;
  - kept the terminal command as an alternative;
  - moved files, dimensions, and embed markup into labeled technical accordions.
- Added a short Common questions page with sendable answers for the most likely first-use and support questions.
- Replaced the oversized Feedback Collection telemetry specification with a task-focused Share feedback guide. Kept the public-project warning and essential privacy explanation.
- Reviewed the new Common questions, Storyboard, and Catalog item pages in a local Mintlify preview.
- Mintlify local search results cannot be tested: the local preview explicitly reports “Not available on local preview.” Search-result quality must be checked after deployment or through Mintlify analytics.
- Mintlify validation and broken-link checks passed after this pass.

### 2026-07-28 — final editorial and structural pass

- Resolved the header destination:
  - Studio remains project-local through `npx hyperframes preview`;
  - the global header action is **Playground**, linking to the official `https://www.hyperframes.dev/` browser experience.
- Rewrote the remaining general-audience outliers:
  - Prompt Guide → a concise human brief and feedback guide;
  - The Pipeline → a flexible idea-to-export explanation rather than a mandatory internal process;
  - HyperFrames vs Remotion → a shorter, balanced decision guide with current Studio and licensing language;
  - Rendering → a task-first CLI render guide, leaving exhaustive flags in the CLI reference;
  - Video Components → a human guide for choosing and adapting Catalog visuals;
  - HyperFrames MCP → current host-aware setup with honest plan, workspace, and beta caveats.
- Corrected stale public documentation:
  - removed hard-coded skill counts that had already drifted from the repository;
  - replaced obsolete `validate` composition guidance with `npx hyperframes check`;
  - removed old Website to Video labels;
  - standardized the HyperFrames brand spelling;
  - removed the remaining duplicate body H1;
  - guaranteed a description for every generated Catalog page.
- Added Playground as a no-local-setup path in Introduction and Choose your path.
- Added `research/docs-audit/current-state.html`, a visual after-state dashboard alongside the baseline audit.
- Final structural inventory:
  - 253 public documentation pages after syncing the latest `main` branch;
  - 253 pages represented in navigation;
  - zero orphan pages;
  - zero missing navigation targets;
  - every MDX page has frontmatter, a title, and a description.
- Final visual review confirmed the full-width Aspen header, Playground action, rewritten guide rendering, Studio images, default Mintlify navigation behavior, and after-state dashboard.
- Final checks:
  - `mint validate` passed;
  - `mint broken-links` passed;
  - `oxlint` passed for changed scripts;
  - `git diff --check` passed.

### 2026-07-28 — navigation polish after preview review

- Restored the navigation behavior used on `origin/main`: ordinary top-level groups in every tab, with no nested root, directory, expanded, or drilldown behavior.
- Kept the refactored page inventory and the new Guides, Studio, Catalog, and Developers information architecture.
- Removed all custom sidebar hierarchy and **On this page** CSS so both surfaces use Mintlify's unchanged default rendering.
- Confirmed the result in a local Mintlify preview; validation and broken-link checks still pass.

### 2026-07-28 — final navigation visual correction

- Kept the Aspen theme, four refactored tabs, and current page groupings.
- Matched the deployed main docs' sidebar treatment: 14px medium group headings, square links, no horizontal dividers, and one border segment per page so the active segment tracks the current page. Groups remain open and non-collapsible.
- Kept Mintlify's right-side **On this page** surface completely unchanged.
- Fit the Aspen desktop header into one row, with the GitHub destination shown as a compact icon.
- Corrected Aspen's stale 96px sticky-sidebar offset to the actual 56px header height and removed its early scroll-fade mask.
- Restored the GitHub star count while keeping the repository name hidden, and normalized Aspen's darker surface borders to main's quieter border color.
- Verified that the documentation font did not change: both main and the refactor use the same TT Norms Pro files and the same body and heading typography.
- Explicitly forced Mintlify's live GitHub star span to remain visible and gave the floating agent input a distinct surface, stronger border, and restrained shadow.
- Prevented the GitHub control from blinking during client-side navigation: Mintlify removes the live count for about 49ms while remounting, so the control now keeps a fixed width and shows the last verified count as a transient CSS fallback.

### 2026-07-29 — journey-led documentation proposal

- Leadership feedback requires the documentation strategy to begin with realistic end-to-end user journeys rather than the inherited page inventory.
- Created `USER-JOURNEYS-PROPOSAL.md` as an approval document. It defines seven journeys, recommends five as P0, assigns one canonical starting link to each, and specifies the sequence, success state, visual formats, current gaps, and validation method.
- Public docs should not be restructured again until the journeys are approved.

### 2026-07-29 — journey implementation approved

- The product owner approved the proposed journey model.
- Added `JOURNEY-IMPLEMENTATION-MAP.md` as the implementation contract.
- Began consolidating the P0 entrances around `/introduction`, `/quickstart`, `/workflows`, `/studio`, and `/help`.
- The established Aspen header, sidebar behavior, right-side table of contents, borders, typography, GitHub control, and agent input treatment remain unchanged.

### 2026-07-29 — journey implementation pass

- Rebuilt the five P0 entrances:
  - `/introduction` now provides immediate proof, the product loop, human-control guidance, and focused next steps;
  - `/quickstart` now starts from source material and ends at a played or exported result;
  - `/workflows` is the canonical outcome-led creation chooser with useful requests;
  - `/studio` now follows the real review → direct edit or agent revision → check → export journey;
  - `/help` now starts from visible symptoms and produces a fix or useful diagnostic.
- Removed the duplicate Choose your path, Create with an agent, and old Help pages. Added redirects for every old route.
- Added the missing human-facing slideshow workflow, including the current live-deck output and honest MP4 limitation.
- Standardized the seven existing creation workflow pages with direction approval, review guidance, common problems, and a return to Studio or the workflow chooser.
- Reworked Catalog around the visual job and Developers around the smallest technical surface.
- Removed large machine-facing Claude Design and Open Design authoring specifications from the human navigation while preserving their source URLs.
- Added `VISUAL-PRODUCTION-BRIEFS.md` for the three P0 videos and eight Studio task loops.
- Updated the visual current-state dashboard around the five approved journeys.
- Browser-reviewed Introduction, Quickstart, Workflows, Help, Studio, Catalog, and Developers in the local Mintlify preview.
- `mint validate`, `mint broken-links`, and `git diff --check` pass.

### 2026-07-29 — composition-led front-door rebuild

- The product owner approved the new `/workflows` page composition.
- The page is a visual router, not an explainer:
  - route choices begin in the first viewport;
  - people choose from the source they already have, not internal workflow names;
  - each tile names what to bring and links directly to the working guide;
  - repetitive setup, “after you choose,” and large first-project callouts are removed.
- Every route tile must show a short, real output from that exact workflow. These
  previews may be muted loops because they are compact chooser media; the full
  films on important destination pages retain narration, music, and purposeful
  sound.
- Existing truthful previews cover product launch, faceless explainer, captions
  and recuts, pull requests, motion graphics, music-driven video, and general
  video.
- Produced the missing interactive-presentation preview from a real
  `hyperframes present` deck:
  - real fragment reveals;
  - real slide navigation;
  - real hotspot branch navigation and return;
  - 1280×720 H.264, 60 fps, 8.3 seconds, 419 KB;
  - first and final states match for a clean loop;
  - the deck passes HyperFrames lint and check with zero errors and warnings.
- The shipped `registry/examples/slideshow-demo` does not currently resolve its
  scene-only slide references under `hyperframes present`; the preview therefore
  uses a purpose-built deck with explicit slide bounds. This appears to be a
  real example/runtime gap worth fixing separately.
- The approved composition sketch is
  `/Users/ularkimsanov/.codex/visualizations/2026/07/29/019fab3f-b40d-7682-b7c6-d8b65ff7f710/workflows-page-composition.html`.

### 2026-07-30 — Studio front-door composition

- The product owner approved the new `/studio` page direction.
- Its one job is to take someone who already has a project through human
  control: watch the result, change something visible, and export a version.
- The page no longer begins by teaching the interface or presenting every
  panel. It leads with one real project and routes by the visible task:
  - text or layout;
  - timing or order;
  - animation or media;
  - export.
- The Studio-versus-agent decision is reduced to one rule:
  - if you can point at the exact thing, start in Studio;
  - if the story, several scenes, or source material must change, ask the agent.
- The first implementation uses verified Studio captures. Replace them with
  short real task loops as those production assets are approved.
- The top capture is a temporary truthful first paint. Replace it with the
  complete narrated Studio film before treating the front door as finished.
- The approved composition sketch is
  `/Users/ularkimsanov/.codex/visualizations/2026/07/29/019fab3f-b40d-7682-b7c6-d8b65ff7f710/studio-page-composition.html`.

### 2026-07-30 — Quickstart front-door composition

- The product owner approved the new `/quickstart` page rhythm:
  - show the finished result first;
  - recognize the source material;
  - make one useful request;
  - approve the creative direction;
  - make one visible change in Studio;
  - export the file.
- Rewrote the actual page around those six beats and removed the inherited
  installation-first framing, long prompt checklist, five-question review
  checklist, repeated completion explanation, and oversized workflow card.
- Installation is now a subordinate, first-time-only disclosure. It no longer
  interrupts the main journey.
- The full hero film is one continuous, self-demonstrating project. Unlike small
  chooser previews, it must ship with narration, music, purposeful sound, and
  captions.
- The finished hero film is now embedded with its real closing frame as the
  poster:
  - 43.7 seconds, 1920×1080, H.264 + stereo AAC, 30 fps;
  - full narration, music arc, purposeful SFX, and burned-in captions;
  - one real project throughout, including a real Studio before/after edit;
  - HyperFrames lint has zero errors; the full browser check passes;
  - five scene seams pass with zero failures or warnings;
  - integrated loudness is −16.0 LUFS and true peak is −0.5 dBTP with no clipping.
- The film's one accepted delivery compromise is the −0.5 dBTP peak. It is safe
  but slightly hotter than the preferred approximately −1 dBTP delivery
  headroom. Lowering the whole master would weaken an otherwise verified
  narration/music balance.
- Browser review confirmed the approved hierarchy, unchanged Mintlify chrome,
  and no horizontal overflow. Mintlify validation and broken-link checks pass.
- The approved composition sketch is
  `/Users/ularkimsanov/.codex/visualizations/2026/07/29/019fab3f-b40d-7682-b7c6-d8b65ff7f710/quickstart-page-composition.html`.

### 2026-07-30 — Workflow destination media audit

- Audited the eight destination guides linked from `/workflows`.
- Their existing top media was uniformly a 6–8 second, video-only loop. That is
  appropriate on the chooser, where motion is a compact preview, but insufficient
  as the only proof on a destination guide.
- Replaced five destination loops with the matching complete controllable films
  with sound:
  - captions and recuts → 43.6-second variables film;
  - pull request → 32.1-second PR film;
  - motion graphic → 26.5-second Hypecard film;
  - music-driven video → 90-second music film;
  - custom video → 33.5-second timeline film.
- Added the real 8.3-second interactive-deck proof to the slideshow guide. It
  remains a silent loop because it demonstrates interaction rather than pretending
  to be a complete narrated film.
- Product launch and faceless explainer still have only short silent previews on
  their destination pages. Honest full sound masters are the remaining media gap;
  do not label the existing loops as complete films.
- The content pattern across all eight guides is too mechanical: intro prose →
  approval checklist → review checklist → common-problems table → two standard
  cards. The next editorial pass should compose each page around its distinct
  decision and review moment instead of preserving this repeated template.

### 2026-07-30 — Pull request destination

- Traced the complete PR workflow before editing the page: GitHub data access,
  diff and commit inspection, story archetypes, audience choice, evidence
  requirements, storyboard, authoring, browser validation, and rendering.
- Rebuilt the page around the decision that materially changes the story:
  whether the video is for users, contributors, or a social audience.
- Added a small interactive audience chooser that produces a useful request for
  each audience instead of teaching an abstract prompt formula.
- Removed the inherited common-problems table and generic approval language.
  The remaining checks are specific to PR truth: branch, release state,
  before-and-after behavior, migrations, readable code excerpts, and claims
  supported by the diff.
- Browser testing confirmed that all three audience choices update the request
  and expose the selected state correctly.

### 2026-07-30 — Captions and talking-head destination

- Traced both complete workflows before editing:
  - embedded captions preserve the source clip and use a clean verbatim rail
    with scarce expressive emphasis;
  - talking-head repackaging preserves the source clip and audio while adding
    transcript-led titles, quotes, statistics, side panels, or picture-in-picture;
  - neither workflow removes pauses, reorders speech, or changes the source edit.
- Rebuilt the page around the real three-way decision:
  - add readable captions;
  - add designed overlays;
  - change the footage through General Video.
- Avoided presenting internal caption backend modes as user-facing choices.
  HyperFrames recommends a treatment after inspecting the clip.
- Kept only source-specific gates and review checks: suitable single-subject
  footage, transcript-sensitive names and terms, safe regions around the
  speaker, synchronization, muted playback, and the final graphic clearing.
- Live Mintlify review found that the selected pill label disappeared in dark
  mode. Fixed the active state in both this chooser and the PR audience chooser
  with a consistent high-contrast HyperFrames accent.
- Formatting, linting, Mintlify validation, broken-link checking, interaction
  testing, and visual review all pass.

### 2026-07-30 — Product and website destination

- Traced the complete product-launch workflow before editing: intent interview,
  website capture, brand extraction, story and script, audio, rough-layout
  review, frame build, Studio review, seam checks, and render.
- The decisive user choice is not a list of video formats. It is what the video
  must do with the source:
  - sell it through a persuasive launch story;
  - show it as an honest product tour;
  - prove one point in a short social video.
- Rebuilt the page around an interactive chooser and editable URL. Each purpose
  produces a distinct brief from the same source.
- Reduced the capture explanation to the three human-facing ingredients that
  matter: real screens, product language, and the brand system. The detailed
  extraction inventory remains developer/agent implementation detail.
- Made the real review sequence explicit: story → rough layouts → Studio →
  export. Removed the generic approval list, goal table, “keep it narrow”
  lecture, and common-problems table.
- The existing silent Huly loop is labeled honestly as a preview. A dedicated
  complete product film with narration, BGM, SFX, and captions is now in
  production through Claude Code using `ANTHROPIC_API_KEY`.
- Browser testing confirmed all purpose choices, URL editing, selected states,
  and prompt updates. A second visual check found Mintlify's code style forcing
  horizontal prompt scrolling; all three interactive brief builders now wrap
  their complete requests.

### 2026-07-30 — Faceless explainer destination

- Traced the complete faceless-explainer workflow before editing. It has no
  website capture or asset inventory: source text supplies information; every
  visual is invented later to teach the selected story.
- The workflow's core editorial rule is that paragraph order is not scene
  order. It extracts the teaching spine, omits asides, and builds toward one
  retained idea.
- Rebuilt the page around two connected decisions:
  - the teaching shape: concept, process, three parallel points, or story;
  - the one sentence the viewer should be able to say afterward.
- The interactive chooser produces a different brief for each teaching shape
  and lets the reader edit the intended landing line.
- Removed the duplicated “approve the explanation” and “review the explanation”
  checklists plus the generic common-problems table. The remaining review gate
  tests whether the piece actually creates and resolves understanding.
- Audited the complete 39.5-second SpaceX/Grok production master. It has 1080p60
  H.264 video and stereo AAC audio, but too much of its runtime demonstrates the
  Grok chat flow before the explanation. Rejected it as the destination hero
  rather than closing the media gap with a weaker fit.
- Live browser testing confirmed all four teaching shapes, landing-line edits,
  selected states, prompt wrapping, and zero page-level horizontal overflow.

### 2026-07-30 — Motion Graphics destination

- Traced the complete autonomous motion-graphics flow: classify, decide whether
  real-source search is required, resolve assets, design around those assets,
  reuse catalog building blocks, verify opening/signature/final proof frames,
  then render after approval.
- Verified the real public boundary: usually under ten seconds, up to roughly
  thirty seconds; one dominant visual idea; normally no narration; MP4 or a
  transparent WebM/MOV overlay. Longer, narrated, or multi-scene work belongs
  in General Video.
- The workflow spans six useful human-facing source types: words, one number,
  data, a logo, an overlay, or a real page/post/map. The underlying category
  system also covers articles, tweets, captured UI, and image-to-data fusion.
- Rebuilt the page around an interactive “what are you animating?” chooser with
  six concrete requests. Removed the generic approval checklist and repeated
  common-problems table.
- Kept the workflow's intentional audio exception honest: the complete
  year-in-review graphic uses music and sound but no narration because motion
  carries the message.
- Live browser testing confirmed every selection pattern, readable prompt
  wrapping, selected-state contrast, and zero page-level horizontal overflow.

### 2026-07-30 — Music-to-Video destination

- Traced the complete music-grounded flow: stage the track and optional media,
  run the single canonical audio analysis, map meaningful musical sections,
  decide beat-grid versus phrase-flow pacing, plan treatments, build frames,
  assemble the track once, review proof moments, and render.
- Corrected the public mental model: “beat-synced” does not mean cutting on
  every measured beat. A genuinely rhythmic track may use its beat grid; calm
  or loose music should flow by phrase and energy.
- Rebuilt the page around the three real source modes:
  - supplied photos or video;
  - synchronized lyrics;
  - completely invented typography and graphics.
- Added an editable energy-direction field so the request names where the
  visual arc changes and how it should end.
- Removed the repeated approval checklist and common-problems table. The
  remaining review checks focus on the chosen track section, required media,
  lyric truth, meaningful musical changes, readability, and the landing/loop.
- Live browser testing confirmed every mode, energy-direction edits, selected
  states, readable prompt wrapping, and zero page-level horizontal overflow.

### 2026-07-30 — Interactive presentation destination

- Traced the complete slideshow contract, player/controller behavior, fragments,
  branches, hotspots, presenter/audience split, media cleanup, screen-sharing
  constraints, handoff, and validation.
- Preserved the essential output truth near the top: a HyperFrames slideshow is
  a live navigable deck. Normal video rendering can resolve only the first
  slide, so a complete linear MP4 is not currently a supported slideshow output.
- Rebuilt the page around the type of control the presenter needs:
  - a direct main story;
  - progressive reveals;
  - optional detail branches;
  - conversion of an existing interactive page.
- Kept the real 8.3-second deck recording because it demonstrates actual
  fragment navigation, slide navigation, hotspot branching, and return to the
  main line.
- Removed the oversized warning, “use it when” list, long approval checklist,
  duplicated supported-output section, and troubleshooting section. Kept the
  minimum presenter handoff and Meet/Zoom sharing guidance because those
  behaviors affect whether the audience view works.
- Live browser testing confirmed all four deck paths, selected states, prompt
  wrapping, visible output limitation, and zero page-level horizontal overflow.

### 2026-07-30 — General Video destination

- Traced the complete custom-video flow, including source adapters, state
  resumption, automation versus storyboard review, companion mode, design and
  media dependencies, scene build strategy, assembly, validation, Studio
  approval, and render.
- Tightened the route boundary: custom work means mixed source types, editable
  underlying footage, longer or unusual multi-scene structure, deliberately
  redesigned formats, or close creative collaboration. A focused input should
  stay in its focused workflow.
- Made the page's unique decision the collaboration shape:
  - build autonomously;
  - review the story and layouts;
  - co-direct through companion mode.
- Explained companion mode as a complete ceiling treatment proposed up front:
  story, visual system, scene motion, transitions, audio identity, opening, and
  ending. The person trims or redirects it instead of assembling quality through
  many small approvals.
- Removed the generic approval checklist, generic five-step review loop, and
  common-problems table. Kept only route-specific source, audio, format, opening,
  ending, and validation checks.
- Live browser testing confirmed all collaboration modes, selected states,
  prompt wrapping, route-boundary visibility, and zero page-level horizontal
  overflow.

### 2026-07-30 — Cross-workflow editorial pass

- Compared all eight destination pages after their individual rewrites:
  headings, word counts, route statements, repeated phrases, common filler, and
  ending actions.
- Pages now remain compact at roughly 225–338 words of body content before
  component-rendered prompt text.
- Removed the last inherited template residue: the identical “Choose another
  workflow” card that ended every page. The sidebar and adjacent navigation
  already provide that route; each guide now ends on its own useful action in
  Studio, Storyboard, Timeline, Catalog, or Slideshow controls.
- No destination page retains the old “Common problems,” “Approve the…,” or
  generic workflow-ending copy.
- Reformatted and linted only the new/changed interactive snippets after
  restoring two unrelated tracked snippets that a broad formatter glob touched.
- Full Mintlify validation, broken-link checking, snippet linting, and diff
  whitespace checks pass after the cross-page cleanup.

## Maintenance issue

- The repo instructions refer to `.agents/skills/hyperframes/SKILL.md`, but that repo-local path is absent in this checkout. The installed current router at `/Users/ularkimsanov/.agents/skills/hyperframes/SKILL.md` was used as the workflow source of truth for this pass.

### 2026-07-30 — Four maturity journeys replace the earlier front doors

- The product owner clarified that the docs need four levels of intent:
  understand HyperFrames, create a first video, go further as an experienced
  user, and build on top of HyperFrames as a developer.
- Canonical routes are now `/introduction`, `/quickstart`, `/go-further`, and
  `/developers`.
- `/workflows` remains the beginner's source-material router. `/studio` becomes
  a major destination inside “Go further.” Neither is a separate maturity
  journey.
- Added a visual `/go-further` hub that changes its proof media and destination
  around four kinds of control: direct editing, stronger agent direction,
  richer media/motion, and project internals.

### 2026-07-30 — Journey-film rebuild begins

- Replaced the Introduction's repeated four-step explanation and workflow-card
  wall with one definition, the existing proof wall, three product truths, and
  one dominant first-video action.
- Rebuilt Quickstart around the README's human-facing installation command:
  `npx skills add heygen-com/hyperframes --full-depth`, followed by selection of
  the Core Skills group.
- Reduced the first request to:
  `Using /hyperframes, make a 10-second product intro for https://example.com.`
- Removed Quickstart's source tabs, long pricing prompt, scattered links,
  unrelated Studio image, required-Studio framing, and required-Renders-panel
  export.
- Made agent revision/render, Studio, and CLI preview/render equal continuations
  from the same first playable project.
- Replaced Go further's hidden tab chooser with four always-visible, linked
  preview tiles.
- Reduced the Developer hub to five smallest useful surfaces. Each card now
  states its first useful result; packages, deployment, and contributing remain
  deeper reference.
- Wrote the shared four-film series bible and exact producer briefs.
- Launched Introduction and Quickstart as Wave 1 using isolated Claude Code
  sessions authenticated only through `ANTHROPIC_API_KEY`.
- Mintlify build validation, broken-link checks, snippet formatting/linting,
  desktop review, and 390px mobile review pass for the current page compositions.
- The separate Studio producer delivered a verified 68-second narrated film and
  four real-UI preview loops for design, timing, motion, and export. Its report
  confirms 1080p H.264, AAC on the full film, muted video-only loops, passing
  browser checks, no blank frames, and readable framing at the actual docs width.
- The Studio capture proved there is no user-editable version-name field in the
  current export panel. Removed the inaccurate “useful name” instruction; Studio
  dates rendered files and keeps them in the queue.
- AWS SSO was refreshed. The Studio film, all four Studio loops, and the Huly
  product-launch film are published under versioned immutable CDN filenames and
  integrated into their pages.
- Wave 2 production for Go further and Developers began once the Wave 1 scripts
  and storyboards were locked.
- Wave 1 acceptance watch items:
  - Introduction must use the exact ElevenLabs River voice
    (`SAz9YHcvj6GT2YYXdXww`), not a substitute labelled as River.
  - Quickstart's three continuation paths must remain visually equal. Its final
    transition must enter the shared project/result, not make the center Studio
    panel look like the required path.

### 2026-07-30 — Four journey films completed

- Published and integrated complete narrated films for `/introduction`,
  `/quickstart`, `/go-further`, and `/developers`.
- Every film uses the exact ElevenLabs River voice
  (`SAz9YHcvj6GT2YYXdXww`), burned phrase captions, music, purposeful SFX, real
  product behavior, controls, and no autoplay or loop.
- The Go-further film uses one real Studio project from opening through final
  result. It proves a story-level agent revision, a direct `168px → 148px`
  Studio edit, Catalog and variable use, and real CLI checks and rendering.
- The exact variable render command shown in that film was executed and
  inspected. A current mounted-block limitation is documented in its production
  report: host variables work, while standalone block lint reports two
  `unknown_variable_binding` warnings.
- Final Go-further delivery: H.264 High 1920×1080 at 30 fps, AAC-LC 48 kHz
  stereo, exactly 58 seconds, −16.8 LUFS, −1.3 dBFS peak, and zero blank frames.
- All journey media uses versioned immutable CDN filenames. The media manifest
  records every published source and destination.

### 2026-07-31 — Full Guides, Studio, and Developers audit reopened

- The owner explicitly rejected treating the four journey pages as the end of
  the refactor. Guides, Studio, and Developers must work as complete reading
  systems, not collections of routers and reference fragments.
- Current in-scope inventory:
  - Guides: 49 routes
  - Studio: 17 routes
  - Developers: 49 routes
  - Total: 115 routes
- Studio is the clearest visual gap. Fourteen of its seventeen pages are mostly
  text-only even when the subject is inherently visual: Canvas, Layers,
  Timeline, Design, Animation, Assets, Variables, and related editing tasks.
- The existing Studio front-door film is a separate older production:
  `bm_george` from local Kokoro, Inter captions, a 68-second Airbnb project, and
  a captured lint panel with 16 errors and 20 warnings. It does not share the
  four journey films' River narrator or their current caption/visual system.
- The Studio film must be re-authored around the current page job and current
  product. Real captures may be reused only when the UI and behavior still
  match. Do not reuse its old voice or error-heavy lint sequence.
- The changelog-video kit was only partially adopted. Some journey revisions
  use TT Norms Pro, but Studio still uses Inter. The useful shared assets are:
  ABC Solar Display for rare editorial display moments, TT Norms Pro for
  narration captions/body, TT Norms Mono for machine truth, the darkened house
  pattern as connective tissue, and the restrained house sound family. Do not
  inherit weekly labels, dates, scene counters, progress dots, or filenames.
- The prior series bible instruction to move phrase captions around the frame
  conflicts with direct owner feedback. New and revised docs films use a
  consistent lower caption rail unless a real product control occupies that
  space; captions do not jump to arbitrary positions.
- Guides currently mix human and engineering material. Frame adapters,
  deterministic-render internals, 4K/HDR implementation details, performance
  engineering, and much of the background-removal implementation do not belong
  in the primary general-user reading path.
- Concrete content defects found:
  - `concepts/compositions.mdx` denies automatic `data-var-*` binding while
    `concepts/variables.mdx` documents the supported declarative bindings.
  - Help and Studio troubleshooting say to save manually while the Studio Source
    page says source edits autosave. The wording must distinguish Studio edits
    from files edited in another application.
  - `guides/performance.mdx` ends with duplicate Troubleshooting cards.
  - Product Updates, Weekly Updates, and the roughly 24,000-word raw Changelog
    overlap and compete for the same job.
- Developers is technically stronger than Guides and Studio, but its front doors
  still create avoidable hops:
  - the CLI reference is roughly 7,900 words;
  - the SDK overview is a fourteen-card directory before the quickstart;
  - skill installation is repeated across setup pages;
  - there is no neutral deployment chooser comparing local CLI, Producer,
    Engine, managed cloud, AWS Lambda, Google Cloud Run, and hosted templates.
- Desktop browser testing on the current local preview confirms the Developers
  header tab currently resolves to `/developers/overview`, including from the
  `/developers` journey page. Keep the journey in Guides and the technical
  overview in the Developers tab, but continue testing the tab after navigation
  edits because the two neighboring routes are easy to confuse.
- Do not change the approved Mintlify chrome or its Inter site font as part of
  film branding. Changelog typography reuse applies to authored docs media, not
  to the Mintlify shell.

### 2026-07-31 — Source verification continues

- The current Studio store initializes auto-keyframing as enabled. The Canvas
  and Animation pages now tell readers to check the highlighted toolbar state
  and turn it off before a constant layout edit instead of assuming it starts
  disabled.
- Save behavior is surface-specific. Preview's Code editor and direct visual
  controls autosave. Storyboard narration, source, and feedback drafts expose
  their own explicit Save actions. Help and Studio troubleshooting now state
  that distinction.
- Studio's Lint endpoint scans every HTML file independently, while the
  project-level CLI linter recognizes mounted sub-compositions. The Studio
  troubleshooting path now makes `npx hyperframes lint` and
  `npx hyperframes check` the final verdict for nested projects.
- The Player documentation was stale: the unsupported “3KB gzipped” claim was
  removed, `timeupdate` was corrected from roughly 30 fps to the package
  README's roughly 10 fps, and current audio, volume, source-document, and
  shader-preview attributes were documented from source.
- The four existing Studio stills are not one coherent set. The Storyboard
  still is neutral and current; Overview, Design, and Export use the older
  Airbnb production. Replace those three from the clean project created for
  the Studio front-door rebuild, then reuse the same capture set across the
  highest-value Studio task pages.
- Studio film v2 is in production after owner approval. Its job is narrow:
  show how a person understands and makes precise edits to the exact project
  an agent created while Studio, agent, and terminal remain equal
  continuations. It uses River, the shared media fonts, one stable caption
  rail, real current UI, and no weekly-show chrome.
- The first pass inspected an older CLI surface and incorrectly treated
  `hyperframes media-treatment` and several Studio effect groups as absent.
  Current `origin/main` source and generated CLI help supersede that finding;
  the corrected contract is recorded in the rendering and deployment audit
  below.
- The current `hyperframes skills` command no longer takes the old
  `--claude`/`--cursor`/`--gemini` flags. The reference now documents the real
  bare install plus `skills check` and `skills update [workflow]`.
- The render reference now follows the current CLI help and worker resolver:
  root `data-fps` precedes the 30 fps fallback; automatic worker sizing considers
  CPU, memory, frame count, composition cost, and concurrency limits; local
  browser GPU mode probes before falling back to software; and every shipped
  render flag is represented.
- `hyperframes skills update` installs into the global Claude/shared agent
  stores and mirrors bundles to compatible installed agents; it does not write
  a project-local `.agents/skills` tree. Corrected the host-specific setup pages
  and the skills overview to state the real scope.
- The hosted MCP endpoint was checked directly. The canonical trailing-slash
  route is live and returns the expected authorization challenge; host
  availability and setup wording were checked against the current official
  Claude, ChatGPT, Grok, Copilot CLI, and Antigravity documentation.
- Authentication now distinguishes account-free local work from managed cloud,
  hosted MCP, and authenticated publishing. Local Kokoro and MusicGen fallbacks
  can require a first-use model download before they operate offline.

### 2026-07-31 — Rendering, deployment, and maintainer audit

- The earlier note that `hyperframes media-treatment` did not exist is
  superseded. The command is present in current source and CLI help. Its real
  surface is capability discovery, bounded local-media analysis, validated
  `data-color-grading` mutation, dry-run, and clear. The Media Effects, Color
  Grading, and CLI pages now document that actual contract.
- Verified the managed cloud, AWS Lambda, and Google Cloud Run commands against
  current source and generated CLI help. Removed nonexistent Lambda
  `--bitrate` / `--crf` flags from migration instructions and replaced the
  old manual-first Cloud Run page with the shipped `cloudrun` CLI flow.
- Verified the current Vercel, Cloudflare, and Modal template repositories.
  Replaced stale template names and Cloudflare architecture, then removed
  volatile timing, price, and cold-start promises.
- Reduced the 4K, HDR, and performance pages from 507 to 186 lines. The pages
  now lead with the actual task, constraints, and verification instead of
  internal pipeline detail and one-machine benchmarks.
- Rewrote the main contributing and Catalog-contribution pages against current
  workspace scripts, registry schema, and generated Catalog workflow. Removed
  the stale “52 blocks” count rather than replacing it with another volatile
  number.
- Synced the public adopters page with `ADOPTERS.md`, including Typeframe.
- Deleted the retired Weekly Updates page and redirected its old route to the
  concise Product Updates page.
- Replaced fictional local-testing fixture archives with a reproducible
  maintainer workflow against any real external project. The named archives in
  the old page are not present in the repository.
- Reduced the managed-cloud guide from 232 to 117 lines while preserving the
  verified sign-in, render, archive, format, variable, webhook, retry, and
  render-management behavior.
- The Mintlify shell stays on Inter. TT Norms Pro, TT Norms Mono, ABC Solar,
  and the changelog sound/visual kit are for authored docs films, not a shell
  typography change. Removing the cross-origin TT Norms declarations also
  removes four repeatable browser console errors while preserving the approved
  effective site font.

### 2026-07-31 — Studio delivery and current-main sync

- The replacement Studio film uses the current `field-notes` project and real
  Studio 0.7.86 captures. It runs 56 seconds with River narration, BGM, SFX,
  and one stable caption rail. Film lint, browser check, and all five seam
  checks pass; all 1,680 frames were measured with zero blank, white, or flat
  frames. Integrated loudness is -16.6 LUFS and the worst narration-to-bed
  separation is 12.3 dB.
- Replaced the Studio overview, Storyboard, Design, and Export stills with one
  coherent capture set. The four muted loops now show direct editing, a real
  persisted timeline trim, the real Ask agent handoff, and a real Studio render.
- Published the film, poster, four loops, and four loop posters under first-use
  `*-v2` keys in `s3://heygen-public/hyperframes-oss/docs/images/showcase/` with
  immutable one-year cache headers. S3 metadata and CDN content types were
  verified after upload.
- Merged `origin/main` at `a3c8f897f` before final QA. Preserved the approved
  Guides / Studio / Catalog / Developers chrome, added the new Prompt Guide as
  progressive disclosure inside Guides, redirected the retired
  `/guides/prompting` route, and kept the beginner Quickstart intentionally
  short.