From 73ebc7c62145e084c8b2565d2c5c0c76ef5385de Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 30 Jul 2026 04:54:27 -0700 Subject: [PATCH] docs: address prompt guide review findings --- docs/docs.json | 5 +-- docs/guides/antigravity.mdx | 2 +- docs/guides/claude-design.mdx | 2 +- docs/guides/copilot-cli.mdx | 2 +- docs/guides/mcp.mdx | 2 +- docs/guides/open-design.mdx | 2 +- docs/guides/pipeline.mdx | 6 ++-- docs/guides/video-editor-cheatsheet.mdx | 5 ++- docs/prompting/anatomy.mdx | 6 ++-- docs/prompting/capstone.mdx | 4 +-- docs/prompting/captions-and-talking-heads.mdx | 2 +- docs/prompting/captions-catalog.mdx | 8 ++--- docs/prompting/code-and-prs.mdx | 4 +-- docs/prompting/code-blocks.mdx | 12 +++---- docs/prompting/data-and-maps.mdx | 12 +++---- docs/prompting/design-systems.mdx | 4 +-- docs/prompting/editing-existing-videos.mdx | 8 ++--- docs/prompting/examples.mdx | 36 +++++++++---------- docs/prompting/explainers.mdx | 4 +-- docs/prompting/generated-artwork.mdx | 6 ++-- docs/prompting/media-and-audio.mdx | 4 +-- docs/prompting/motion-graphics.mdx | 2 +- docs/prompting/motion.mdx | 24 ++++++------- docs/prompting/music-and-slideshows.mdx | 4 +-- docs/prompting/overlays-and-lower-thirds.mdx | 8 ++--- docs/prompting/overview.mdx | 8 ++--- docs/prompting/product-launch.mdx | 4 +-- docs/prompting/recreating-references.mdx | 2 +- docs/prompting/rendering-and-output.mdx | 4 +-- docs/prompting/rules-and-anti-patterns.mdx | 4 +-- docs/prompting/runtimes-and-3d.mdx | 6 ++-- docs/prompting/storyboards.mdx | 4 +-- docs/prompting/transitions.mdx | 4 +-- docs/prompting/variables-and-templating.mdx | 10 +++--- docs/prompting/vfx-and-liquid-glass.mdx | 12 +++---- docs/prompting/visual-specs.mdx | 6 ++-- docs/prompting/vocabulary.mdx | 10 +++--- docs/quickstart.mdx | 2 +- packages/cli/src/commands/init.ts | 2 +- .../adapters/gsap-transforms-and-perf.md | 2 +- 40 files changed, 127 insertions(+), 127 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index cd586a642..8bb5f0e6d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -493,7 +493,8 @@ "redirects": [ { "source": "/guides/prompting", - "destination": "/prompting/overview" + "destination": "/prompting/overview", + "permanent": true } ] -} \ No newline at end of file +} diff --git a/docs/guides/antigravity.mdx b/docs/guides/antigravity.mdx index 292b58876..8836b1d13 100644 --- a/docs/guides/antigravity.mdx +++ b/docs/guides/antigravity.mdx @@ -135,7 +135,7 @@ HyperFrames projects created with `npx hyperframes init` scaffold both `CLAUDE.m ## Next steps - + Vocabulary and patterns that produce better compositions. diff --git a/docs/guides/claude-design.mdx b/docs/guides/claude-design.mdx index 66494e87d..da3239415 100644 --- a/docs/guides/claude-design.mdx +++ b/docs/guides/claude-design.mdx @@ -143,7 +143,7 @@ Then iterate: ## Next steps - + More prompt patterns for HyperFrames across Claude Code, Claude Design, and other agents. diff --git a/docs/guides/copilot-cli.mdx b/docs/guides/copilot-cli.mdx index d24aac28c..72e99deea 100644 --- a/docs/guides/copilot-cli.mdx +++ b/docs/guides/copilot-cli.mdx @@ -175,7 +175,7 @@ Authorize via OAuth when prompted. See the [MCP guide](/guides/mcp) for full det ## Next steps - + Vocabulary and patterns that produce better compositions. diff --git a/docs/guides/mcp.mdx b/docs/guides/mcp.mdx index fc3a17180..703063e9b 100644 --- a/docs/guides/mcp.mdx +++ b/docs/guides/mcp.mdx @@ -320,7 +320,7 @@ The MCP is a HeyGen-hosted product that wraps: Try HyperFrames locally with the open-source CLI. - + Tips for getting the best results when working with AI agents. diff --git a/docs/guides/open-design.mdx b/docs/guides/open-design.mdx index d79acf514..433aee577 100644 --- a/docs/guides/open-design.mdx +++ b/docs/guides/open-design.mdx @@ -169,7 +169,7 @@ Then iterate the same way as the Claude Design path: The closed-source flavor of the same workflow — useful when you don't have a CLI on your laptop. - + More prompt patterns for HyperFrames across Claude Code, Claude Design, Open Design, and other agents. diff --git a/docs/guides/pipeline.mdx b/docs/guides/pipeline.mdx index 71b273ccd..909293eb0 100644 --- a/docs/guides/pipeline.mdx +++ b/docs/guides/pipeline.mdx @@ -141,7 +141,7 @@ npx hyperframes transcribe narration.wav | `narration.txt` | The exact spoken text with pronunciation substitutions applied (`API` → `A P I`, `$2T` → `two trillion`). Distinct from `SCRIPT.md` so you can regenerate the audio later with a different voice without redoing the substitutions. | | `transcript.json`| `[{ text, start, end }]` for every word. Every later step reads this for timing. | -Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/media-use`](/guides/prompting) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`. +Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/media-use`](/guides/skills#domain-skills-loaded-on-demand) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`. **Gate:** `narration.wav`, `narration.txt`, and `transcript.json` exist. `STORYBOARD.md` beat timings reference real timestamps, not estimates. @@ -153,7 +153,7 @@ This is where the storyboard becomes runnable HTML. Each composition is a self-c For multi-beat videos, spawn a focused sub-agent per beat. Each one gets fresh context, the storyboard section for its beat, the asset paths it needs, and the relevant technique references. That produces noticeably better output than building every beat in one long-running context. -After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes-core`](/guides/prompting) skill encodes the composition rules — required `class="clip"` attributes, `data-*` attribute semantics — and [`/hyperframes-animation`](/guides/prompting) covers GSAP timeline registration and adapter registries. +After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes-core`](/guides/skills#domain-skills-loaded-on-demand) skill encodes the composition rules — required `class="clip"` attributes, `data-*` attribute semantics — and [`/hyperframes-animation`](/guides/skills#domain-skills-loaded-on-demand) covers GSAP timeline registration and adapter registries. **Gate:** Every composition is self-reviewed. No overlapping elements, no misplaced assets, no static images sitting unanimated. @@ -209,7 +209,7 @@ For a 5-second one-shot animation, a single hand-authored composition is fine; t The full website-to-video guide built on this pipeline. - + How to invoke the pipeline through your AI agent. diff --git a/docs/guides/video-editor-cheatsheet.mdx b/docs/guides/video-editor-cheatsheet.mdx index 16e3431ab..70266404b 100644 --- a/docs/guides/video-editor-cheatsheet.mdx +++ b/docs/guides/video-editor-cheatsheet.mdx @@ -217,14 +217,13 @@ For GSAP animation, register one paused timeline per composition: const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.6 }); - tl.set({}, {}, 5); // keeps the timeline at least 5 seconds long window.__timelines["main"] = tl; ``` - If a video cuts off early, check that the GSAP timeline is at least as long as the intended edit. The final `tl.set({}, {}, 5)` pattern is the fix. + Render duration comes from `data-duration` on the composition and clips, not from GSAP timeline length. If a video cuts off early, check those timing attributes. Do not pad the timeline with an empty `tl.set()` sentinel. ## Render Presets @@ -285,7 +284,7 @@ For editor-facing changes, keep `npx hyperframes preview` running, then have the | Need to share editable project | `npx hyperframes publish` | - + How to direct AI agents to build better videos diff --git a/docs/prompting/anatomy.mdx b/docs/prompting/anatomy.mdx index 451e4ee3a..743a6a6c1 100644 --- a/docs/prompting/anatomy.mdx +++ b/docs/prompting/anatomy.mdx @@ -27,7 +27,7 @@ Assembled: > /motion-graphics Make an 8-second 1920x1080 video. Beat 1 (0-4s): dark macOS terminal types "npx skills add heygen-com/hyperframes" character by character, then hold on the blinking cursor. Beat 2 (4-5s): the terminal shatters into fragments. Beat 3 (5-8s): bold white kinetic text on black slams in word by word, snappy: "YOU JUST MADE THIS / WITH HYPERFRAMES." Adapt the `code-typing` and `vfx-shatter` registry blocks; hand-author the kinetic text. No narration, no image or media files. - + *Rendered from the prompt above, unedited.* @@ -88,7 +88,7 @@ The skeleton above is how you ask. This is what the agent writes, and it's worth | --- | --- | | `class="clip"` | Marks a timed section. The framework owns its visibility — never animate a clip's own opacity or `display` to hide it. | | `data-start` / `data-duration` / `data-track-index` | When the clip begins, how long it runs, and which track it sits on. Two clips on the same track index must not overlap in time. | -| `window.__timelines[""]` | Every composition registers exactly one paused GSAP timeline here, built synchronously at load. The renderer seeks that timeline frame by frame — which is why nothing may depend on wall-clock time or unseeded randomness. | +| `window.__timelines[""]` | Every GSAP-driven composition registers exactly one paused timeline here, built synchronously at load. The renderer seeks that timeline frame by frame — which is why nothing may depend on wall-clock time or unseeded randomness. Other adapters, including Lottie, CSS animations, and WAAPI, register through their own seekable runtime contracts. | | `