docs: Prompt Guide as a novice-to-capstone arc + text corrections from validation

[vanceingalls]

Summary

Two bodies of documentation work from the prompt-guide campaign:

1. Prompt Guide restructured as a novice-to-capstone arc

The 29-page reference manual (by-video-type / by-feature sections) is now a single novice-to-advanced
arc — no standalone reference sections survive ("full dissolve"). Every page becomes a chapter at the
level where the reader is ready for it, with an entry bridge ("you can already X — this adds Y") and
a literal exit bridge (*Next: [Title](/slug) — clause.*) chaining straight into the next chapter.
Bridge-chain integrity was verified end to end: all 30 chapters' exit bridges point at the actual next
page in nav order, zero mismatches.

• Level 1 — Your first video: workflow rides (product-launch, explainers, code & PRs, captions &
  talking-heads, music & slideshows, motion graphics), reframed as one-prompt first wins; adds a validated changelog-angle variant for /pr-to-video, built against this repository’s own last-two-weeks digest.
• Level 2 — Control: anatomy, specification dial, vocabulary, visual specs; examples becomes the
  level-end gallery. Anatomy gains a note on the composition-structure mandate (feat(skills): add COMPOSITION_STRUCTURE to feedback repro packet + soft-warn lint #2599).
• Level 3 — Life: motion grammar, transitions.
• Level 4 — Substance: code blocks, data & maps, overlays, captions catalog, generated artwork,
  VFX, runtimes & 3D — reframed as additive capabilities layered onto earlier chapters.
• Level 5 — Voice and sound: media & audio, plus a new Bring any footage section documenting
  the automatic HEVC/hostile-codec proxy subsystem (refactor(parsers): single shared FFmpeg/FFprobe binary resolver #2585–feat(media): alpha-capable authoring proxies #2598), validated with a real HEVC test
  clip built into a picture-in-picture piece.
• Level 6 — Scale: design systems, variables & templating (with a correction for the
  variables-no-longer-shadow-authored-CSS fix, fix(core): stop composition variables from shadowing authored CSS custom properties #2553), a brand-new Storyboards chapter (prompting
  the plan instead of the scenes — arc, direction block, one breather, one callback, per-frame
  negative list — validated with a real silent 3-frame build), editing, iterating, recreating
  references, rendering & output, Remotion migration.
• Level 7 — Capstone: a new chapter built around a real public promo film for HyperFrames itself
  ("Write HTML. Render video.") — nine regions, 62s, one long-form prompt that composes nearly every
  technique the guide teaches (kinetic type, per-character code typing, a matched-motion transition,
  real data-viz, a generated-artwork hybrid, a continuous camera-push montage, and a callback +
  breather landing). The prompt is printed in full and dissected chapter-by-chapter. Exposes ground/
  ink/productName as composition variables and ships both the default render and a --variables
  re-skin — including an honest note that one frame (a generated illustration) bakes its palette at
  generation time and doesn't follow the CSS-driven override the other six frames do.
• Appendix: rules-and-anti-patterns becomes the consolidated cheat sheet (existing rules link
  back to where they're taught) plus 8 new lint-rule rows — seek-order safety, cold-seek visibility,
  SVG draw-on — each grounded against the actual linter source (packages/lint/src/rules/gsap.ts),
  phrased as prompt guidance.

New validation builds beyond the existing 64 embedded renders: the /pr-to-video changelog variant, proxy-footage,
storyboard-mini, and the capstone film (default + re-skin) — each built exactly as written by a
fresh builder agent, passing lint/check, rendered, and frame-verified before its page shipped.

2. Text corrections from the validation campaign

• hyperframes-core SKILL.md — "First-pass lint gotchas": root element needs data-start="0"; initial states via gsap.fromTo, never CSS transform + tween on the same property.
• docs/concepts/compositions.mdx — data-composition-src resolves relative to the project root, not the referencing file.
• gsap-transforms-and-perf.md — createElementNS SVG can use measured origins once attached and sized; use an explicit svgOrigin or local (0,0) geometry when measurement is unavailable.

Behavior fixes from the same campaign are in #2110; Tier 3 block bugs tracked in #2107.

Test plan

• All new validation builds (the /pr-to-video changelog variant, proxy-footage, storyboard-mini, capstone
  default + re-skin) pass lint/check/render exactly as written by a fresh builder agent
• Every embedded S3 URL across the guide (96 total) verified serving (200, video/mp4)
• docs.json parses; full nav walked and every exit bridge verified against the actual next
  chapter in order (0 mismatches across all 30 chapters)
• bun run format:check and mintlify broken-links both clean
• Capstone film's technique-table coverage independently verified frame-by-frame (ffprobe +
  visual frame extraction) against the render, not just the builder's own report

🤖 Generated with Claude Code

[miga-heygen]

PR #2109 Review: Prompt Guide as a novice-to-capstone arc + text corrections

Overview

A massive documentation restructure: 4423 additions, 302 deletions across 41 files. The old single-page guides/prompting.mdx (297 lines) is replaced by a 30-chapter novice-to-capstone arc under docs/prompting/ spanning 7 levels, plus text corrections from a validation campaign against the actual codebase.

This is the best documentation work I've reviewed in this repo. The motion chapter alone is a masterclass — eight rules taught through concrete before/after A/B comparisons with rendered video proofs, each rule demonstrated on a subject where the rule is unavoidable given the content ("a live feed that freezes reads as a broken connection"). The capstone film dissection traces every region back to the chapter that teaches its technique, and the vocabulary page ships rendered clips for every easing word, camera word, and marker mode. The whole arc is structurally verified: bridge chains, nav ordering, and validation builds all checked.

---

1. plans/ directory should not ship

Three plan files (872 lines) are internal agent-execution artifacts:

• plans/prompt-guide-arc-plan.md opens with "For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development" and contains worktree paths, branch names, and step-by-step checkbox lists.
• plans/prompt-guide-arc.md and plans/prompt-guide-expansion.md are the design specs these plans execute.

Direct precedent: commit 71e67e2f0 (same author) explicitly deleted a near-identical file (plans/hdr-followups.md) plus two notes/ files, with the message "notes/ and plans/ are working documents, not project docs." This PR reintroduces exactly the pattern that commit walked back.

Recommendation: drop these three files from the PR before merge.

2. Structural integrity — clean

Verified end-to-end:

• Nav structure: all 32 .mdx files have exactly one docs.json entry, and vice versa. Nav ordering is strictly Level 1 → 7 → Appendix.
• Redirect: old /guides/prompting → /prompting/overview via docs.json redirects array. Old file deleted, old nav entry removed.
• Bridge chain: all 31 exit bridges form a complete, unbroken sequence across all 32 pages — no breaks, no loops, no orphans. The chain matches docs.json nav order line-for-line. rules-and-anti-patterns (terminal appendix) correctly has no exit bridge.
• Entry bridges: every chapter except overview and capstone (both open with a video hook, correct for their role as front door and grand finale) explicitly calls back to the immediately preceding chapter's concept.

Three exit-bridge title mismatches (non-blocking — plausibly deliberate shortenings for narrative flow):

From page	Bridge text	Target's actual title:
overview	"Your first video"	"Product launch videos"
motion-graphics	"Prompt anatomy"	"Anatomy of a one-shot prompt"
remotion-migration	"Capstone"	"Capstone — every technique, one journey"

3. Code-touching corrections — all verified accurate

• root_composition_missing_data_start — exists at packages/core/src/lint/rules/composition.ts:313-331, fires exactly as described. Sub-compositions correctly excluded.
• gsap_css_transform_conflict — exists at packages/core/src/lint/rules/gsap.ts:458-545, correctly exempts .fromTo()/.from() calls. The doc's suggested fix matches the actual fixHint.
• data-composition-src path resolution — confirmed in both build paths (htmlBundler.ts and htmlCompiler.ts): resolves against projectDir, not the referencing file.
• SVG createElementNS pivot — mechanism is real (verified in GSAP's getBBox() codepath), fix advice is sound. One wording note: "has no reliable center pivot" is stated as universal but the failure is conditional on zero/misreported getBBox() — consider softening to "may not resolve a center pivot reliably."

4. Stale rule count in motion.mdx

Frontmatter description says "Seven motion-grammar rules" but the content lists 8 rules and the body text says "The second applies the eight rules." The description should say "Eight." Same stale-reference pattern a prior commit (fix stale six-rules references to match the seven-rule grammar) already fixed once.

5. Stale /guides/prompting links in other docs

9 occurrences across 8 files still hardcode /guides/prompting (quickstart.mdx, copilot-cli.mdx, pipeline.mdx ×2, mcp.mdx, open-design.mdx, antigravity.mdx, claude-design.mdx, video-editor-cheatsheet.mdx). The redirect keeps them functional, but they should point directly to /prompting/overview (or the more specific new sub-page) rather than relying on a permanent redirect. Not blocking.

6. Missing trailing newline in docs.json

Minor formatting nit — the new version ends without \n.

---

Verdict

Approve — with the plans/ directory removed. The content quality is outstanding. Structural integrity verified end-to-end: bridge chain complete, nav ordering correct, redirect in place, all code-referencing claims verified against source. 40 CI checks pass.

— Miga

[james-russo-rames-d-jusso]

Reviewed at 8fb1482e7. Substantial doc restructure — 30 new prompting chapters, 3 skill/doc corrections, bridge-chain intact end-to-end (I re-verified: 31 exit bridges, every target = the next nav page, zero mismatches). Factual claims against the code hold up across the ~12 primitives / lint codes / runtime globals / PR-fix references I spot-checked (all 8 new lint rule codes in rules-and-anti-patterns.mdx map cleanly to packages/lint/src/rules/gsap.ts; the data-var-src/data-var-text allowlist matches packages/core/src/runtime/applyVariableBindings.ts; the HEVC-proxy toggles, data-composition-src resolution rule, and the #2553/#2599 fix-PR citations all reconcile with the actual code and PR history).

What I did find, mostly in the "does the guide agree with itself and with what's outside the diff" space:

Concerns

In-diff — please reconcile before merge

• docs/prompting/motion.mdx:3 — the frontmatter description still reads "Seven motion-grammar rules", but the body defines eight numbered rules (1-8, line 42 for the last title) and the "eight rules" phrase appears three separate times in the body (lines 162 / 168 / 174). Confirmed still present at 8fb1482e7; today's Rule 2 rewrite didn't touch it. Flip "Seven" → "Eight" in the frontmatter.

• docs/prompting/capstone.mdx — internal timing drift inside a chapter that explicitly asserts "nothing paraphrased or trimmed" about the prompt block:

  • line 7 says "~62 seconds"
  • line 27 (inside the "verbatim" prompt) says "~60-second"
  • line 68 (inside the "verbatim" prompt) says "Render (56-60s)" — final region ends at 60s
  • line 96 (the walking-the-prompt table) says "Render (0:56-1:02)" — same region, 6 seconds long
  • line 104 says "all 62 seconds"

  Either the prompt is 60s (drop the extra 2s from the summary line and the table) or it's 62s (extend the "Render" region to 56-62s in the prompt itself). Also flags the PR body's own "7 frames, ~48s" summary vs what the chapter actually documents: nine regions, ~60-62s. Recommend updating the PR body once the timeline resolves.

• plans/prompt-guide-arc-plan.md (+508 lines) — reads as an actionable task-list, not a design record. No Status: implemented header at the top; the tasks are still - [ ] unchecked; it references paths that only exist on Vance's box (~/src/wt/hyperframes/prompt-guide, lines 13/35/48/62/472) and contains commands aimed at this PR's coordinator (gh pr edit 2109 steps under Task 13). Aligned with [[feedback_aspirational_planning_doc_drift]] — a future contributor stumbling into plans/ will treat this as a live plan and either try to execute it or edit it. Suggest either (a) drop from this PR, or (b) add a Status: implemented 2026-07-22 — historical only, do not follow header at line 1 and strip the ~/src/* local paths + the gh pr edit 2109 block.

• plans/prompt-guide-expansion.md (+266 lines) — same class of concern, worse in one respect: the nav proposal inside it (Fundamentals / Making it look good / By video type / By feature, lines 20-54) directly contradicts what shipped (Level 1 - Your first video ... Level 7 - Capstone). It also names rules ("never 'holds motionless'", line 82) that don't appear in rules-and-anti-patterns.mdx. Only prompt-guide-arc.md (line 3) mentions this doc's structure is superseded, and that supersession is invisible if a reader opens this file directly. Either add a leading Status: superseded by prompt-guide-arc.md and by the shipped nav in docs/docs.json header, or drop.

  plans/prompt-guide-arc.md (+98 lines) is the exception — it has Status: implemented 2026-07-22 at line 3, so it's the closest of the three to an actual design record. Could stay; the other two are the risky ones.

Out-of-diff — orphaned references to the old prompt guide

The PR deletes docs/guides/prompting.mdx and adds a /guides/prompting → /prompting/overview redirect (docs/docs.json:493-498). The redirect prevents 404s, but eleven callers still point at the old slug and get sent to the generic overview instead of the topical new chapter their anchor text implies:

• packages/cli/src/commands/init.ts:963 — user-visible: after scaffolding a new project, the CLI prints More patterns: hyperframes.heygen.com/guides/prompting. Every fresh install advertises the deleted path.
• docs/quickstart.mdx:66
• docs/guides/pipeline.mdx:144 (/media-use → should point at /prompting/media-and-audio)
• docs/guides/pipeline.mdx:156 (two skill mentions conflating /hyperframes-core and /hyperframes-animation at one landing page)
• docs/guides/pipeline.mdx:212 — Card href
• docs/guides/{open-design,claude-design,mcp,copilot-cli,antigravity,video-editor-cheatsheet}.mdx — Card hrefs (six more)

The init.ts one is the highest-impact — it's the terminal string every new user hits. Suggest fixing at least that one in this PR; the seven Card hrefs can roll into a follow-up sweep.

Coverage gaps worth surfacing

The guide reads authoritative — a reader who works through it and then hits an author-facing feature that isn't covered will assume the guide has told them everything they need. The three biggest missing surfaces:

• Color grading (packages/parsers/src/colorGradingContract.ts — 13 top-level keys: wheels, curves, hueCurves, up-to-four secondaries, LUT, effects like asciiStyle/bloom/monoScreenShape, plus adjust keys exposure/contrast/temperature/tint/vibrance/saturation). Also has a dedicated skills/media-use/references/grading.md. The guide's only "grade" mentions are two prose lines telling users not to grade footage. An author asking for "cinematic film grade" or "add a LUT" has zero vocabulary for this pipeline. This is the largest hole.
• hyperframes doctor / browser / env-setup (packages/cli/src/commands/{doctor,browser}.ts, skills/hyperframes-cli/references/doctor-browser.md). Zero mentions across all 32 chapters. Authors hitting the WebGPU caveat in vfx-and-liquid-glass.mdx:42-46 are given no diagnostic path.
• Introspection commands (snapshot / inspect / info / catalog under packages/cli/src/commands/). Author debugging "why is my sub-composition blank" has no mapped verb — the CLI skill treats hyperframes snapshot --at <t> as required for sub-composition smoke tests but the guide never mentions any of these.

Also thin but real: hyperframes publish/present (missing terminal step; overview.mdx teaches render as terminal), --docker / --strict reproducible-render semantics (rendering-and-output.mdx doesn't touch them), Studio-directed selection edits (preview --context --json → paste hfId into prompt — invisible in editing-existing-videos.mdx), and audio-reactive animation (thin four-row table in vocabulary.mdx:122-138 for a feature that has its own lint rule + hyperframes beats command).

Storyboards vocabulary framing

docs/prompting/storyboards.mdx:16 says the chapter teaches "the vocabulary that turns 'storyboard' from a loose word into a plan the build can execute in one pass", and lines 40-64 name "One breather" and "The callback" as parts of the plan, with a per-frame template using type / persuasion / beat / focal / roles at lines 49-54. The real StoryboardFrame / StoryboardGlobals schema in packages/core/src/storyboard/types.ts:36-80 has message / arc / audience / format at the global level and scene / voiceover / transition_in / duration per frame — no beat, persuasion, breather, or callback fields. So the chapter is teaching a narrative-writing discipline, not documenting the parser's schema — that's fine as pedagogy, but the framing reads as though a lint rule might check for a breather. One clarifier sentence at the top ("These are the words we use when writing the plan; the parser's schema is a smaller machine-readable subset — see packages/core/src/storyboard/types.ts for the fields the build actually reads.") would close the gap.

Nits

• docs/prompting/rules-and-anti-patterns.mdx:6 — "the same eight rules" / line 26 "the linter added eight more rules". The mdx table has 8 new lint codes across 7 coded rows (one seek-order rule is cross-tagged with two codes), plus one uncoded row. Reader-facing "eight" is fine if it means "coded rules"; may want to clarify since the table shows nine rows.
• docs/prompting/specification-dial.mdx (19 lines) — this is the keystone Level 2 chapter that visual-specs.mdx:6 refers back to as "the dial's third setting". Three bullets + a "Next" pointer feels light for the axis the arc is built around; no side-by-side of the three settings (mood vs tokens vs full spec) on the same prompt.
• docs/prompting/generated-artwork.mdx (39 lines) — light on how the generated image asset lands in the composition (path handling, <img> vs texture) and on iterating the image prompt.
• docs/prompting/iterating.mdx (56 lines) — no mention of hyperframes compare (real command at packages/cli/src/commands/compare.ts), which is the obvious "compare against previous render" hook.
• docs/prompting/capstone.mdx — the chapter is linked from eleven sibling chapters as "Level 7 film" but the chapter itself (title / description at lines 2-3) never introduces itself as "Level 7". Minor coordination gap.
• docs/docs.json — final hunk in the diff shows \ No newline at end of file; every prior version ended with a newline. Mechanical.
• No changelog / release-notes marker in the PR. docs/changelog.mdx has a ## Docs & Examples section per release (e.g. v0.7.78 line 30 credits 1a2c30a79 for docs work). Convention appears to be "roll into next release cut," so this may resolve at release time — worth a follow-up line so the next bun run changelog:draft remembers it.

Questions

• Are plans/prompt-guide-arc-plan.md and plans/prompt-guide-expansion.md intended as historical artifacts or is the plan to keep one/both live? If historical, could you add the Status: headers noted above or drop them from this PR?
• The 11 stale /guides/prompting references — planned follow-up sweep in a separate PR, or would you rather fold at least the packages/cli/src/commands/init.ts:963 fix into this one so no shipped CLI advertises a redirected path?
• Color-grading absence — is that a scoped-out gap (already handled by the media-use skill and intentionally not surfaced in the prompt arc), or worth a Level 4 or Level 5 chapter in a follow-up?
• Storyboards vocabulary framing — is the "narrative discipline as vocabulary" framing intentional, or would a one-sentence clarifier that these are prompt-plan words (not STORYBOARD.md schema fields) fit the pedagogy you had in mind?

What I didn't verify

• The 68 embedded S3 URLs (PR body says all 200 / video/mp4; trusting that).
• Each of the 14 HEVC-proxy PRs #2585-#2598 individually — spot-checked #2585 (shared FFmpeg resolver) and the aggregate hevc_preview_codec lint code + --no-proxy CLI flags + .transcode-cache/ behavior, all consistent with the chapter.
• The four fresh-builder-agent renders (changelog-video, proxy-footage, storyboard-mini, capstone default + re-skin). Trusting Vance's e2e testing here.
• enum variable options shape (docs show {"value":..,"label":..}; parser at packages/parsers/src/compositionVariables.ts:54 only validates Array.isArray(options) — Studio's picker may or may not support the object form, worth a spot-check).
• The Lambda-HDR unavailability claim at docs/prompting/rendering-and-output.mdx:80 — I couldn't find a corresponding guard in packages/aws-lambda/.

— Review by Rames D Jusso

[vanceingalls]

Addressed the actionable review feedback from @miga-heygen and @james-russo-rames-d-jusso in 73ebc7c6 and fdf3ad8f. Thank you both for the detailed passes.

Resolved

• Removed the three internal plans/ working documents from the PR.
• Fixed the stale motion-rule count (Seven → Eight) and the contradictory seven/eight-rule framing in rules-and-anti-patterns.mdx; also clarified that two documented render hazards are not coded lint findings.
• Reconciled the capstone timing: the prompt targets roughly 60 seconds, while both published renders probe at exactly 62 seconds because the final lockup extends to 1:02. Updated the PR description from “7 frames, ~48s” to “nine regions, 62s.”
• Added the storyboard clarification that its narrative vocabulary is writing discipline, not extra STORYBOARD.md parser schema, while retaining the pedagogical vocabulary.
• Softened the conditional SVG pivot wording and corrected the other implementation-facing inaccuracies found in the adversarial pass (GSAP timing/default-duration guidance, variable behavior, frame.md terminology, VFX/runtime phrasing, and the overly broad GSAP claim).
• Made /guides/prompting → /prompting/overview permanent and repointed all owned inbound links, including the CLI output string; the redirect remains for old external and published-CLI links.
• Corrected the PR body’s changelog wording to describe the /pr-to-video changelog variant rather than a nonexistent public /changelog-video chapter, and corrected the embedded-video count to 96 distinct URLs.
• Added #t=0.1 to the new video sources so galleries paint a first frame without switching the guide to autoplay or generating/re-uploading 96 poster assets.
• Restored the trailing newline/format cleanliness in docs.json.
• Regenerated skills-manifest.json after the skill-reference accuracy fix; Skills: manifest in sync now passes.

I also checked the review’s two explicitly unverified implementation claims: enum option objects are supported by the declared parser type, Studio form, and runtime validation; distributed/Lambda HDR is explicitly rejected by the producer path and covered by tests. No additional correction was needed for either.

Deliberately not expanded here

The broader coverage ideas (color grading, doctor/browser setup, introspection commands, publish/present, Docker/strict rendering, Studio-directed edits, and deeper audio-reactive guidance) are useful follow-up topics, but they are additions rather than defects in this PR. Likewise, the 28 longer chapter introductions were explicitly left alone: changing that entry-bridge approach requires a guide-wide editorial decision, not a drive-by rewrite in this fix pass.

Local verification passed: bun --bun run format:check, Mint broken-links from docs/, jq empty docs/docs.json, git diff --check, and bun packages/cli/scripts/gen-skills-manifest.ts --check. The live PR currently has no failed checks; the remaining Windows/render-regression jobs are still running.