docs: address remaining prompt guide feedback

2026-09-03 23:03:09 +00:00 · 2026-07-30 05:01:12 -07:00
parent 73ebc7c621
commit fdf3ad8fdd
7 changed files with 6 additions and 874 deletions
@@ -6,6 +6,8 @@ description: "One prompt, one continuous camera move, every technique in this gu
 <video controls muted loop playsinline preload="metadata" src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/capstone-timeline-default.mp4#t=0.1" style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}></video>
 *"The Timeline" — 1920x1080, ~62 seconds, one prompt, one unbroken camera move, unedited.*
 The prompt targeted roughly 60 seconds; the delivered render runs 1:02 because the final lockup holds for a two-second breath.
 If you read the guide in order, you have already seen every piece of this film. Each region was cut out and embedded in the chapter that teaches its technique — the typed opening in [Code animations](/prompting/code-blocks), the chart and map in [Data and maps](/prompting/data-and-maps), the footage pipeline in [Media and audio](/prompting/media-and-audio), the glass and mural in [VFX](/prompting/vfx-and-liquid-glass) and [Generated artwork](/prompting/generated-artwork), the beat grid in [Music](/prompting/music-and-slideshows), the 3D coil in [Runtimes and 3D](/prompting/runtimes-and-3d), the continuous camera in [Motion](/prompting/motion), the seeded finale in [Rendering and output](/prompting/rendering-and-output). This page is where the pieces become one composition, and the prompt below is the glue: every paragraph of it is a chapter of this guide restated as a binding clause.
 The concept is the product: the viewer travels along one literal timeline — the thing HyperFrames is built on — from the first typed character to the finished MP4. Everything in it is true: real catalog counts, real cloud regions, real product surfaces, footage staged as the material the tool processes. And the film has no scenes in the slideshow sense — it is one continuous camera journey through one wide world, which is the chapter's biggest lesson.
@@ -1,6 +1,6 @@
 ---
 title: Motion that reads premium
-description: "Seven motion-grammar rules from frame-by-frame study of professional work — nothing stops, the camera acts, action overlaps, imperfection stays reproducible."
+description: "Eight motion-grammar rules from frame-by-frame study of professional work — nothing stops, the camera acts, action overlaps, imperfection stays reproducible."
 ---
 By now you can specify a frame precisely — exact copy, exact colors, exact layout, exact timing. This level makes it move. But "make it move" is the wrong instruction, and it is worth understanding why before you write a single motion clause.
@@ -5,6 +5,8 @@ description: "For multi-scene work, don't prompt the scenes one by one — promp
 [Variables and templating](/prompting/variables-and-templating) was about reusing one composition across many renders. This page is the other axis of scale: one film with many scenes. Past a handful of beats, describing each scene from a blank page — "then frame 2 shows X, then frame 3 shows Y" — is the slow way and the way that drifts, because nothing ties the frames to each other. The fast way is to prompt the **plan** once — the throughline, the job each frame does, the rule that paces reveals — and let the build put frames against it.
 This narrative vocabulary is a writing discipline, not additional `STORYBOARD.md` schema: the workflow translates the plan into the smaller machine-readable shape the build consumes.
 ## Prompt the plan, not the scenes
 A storyboard is a short, structured document that sits above the individual frames: one arc, one direction block that every frame inherits, and a light per-frame spec (not a full description) for each key moment. The workflow reads the plan and builds each frame's HTML sub-composition against it — so a plan that's precise about the *shape* of the film produces frames that already agree with each other on pacing, palette, and payoff, without you re-stating any of that per frame.
@@ -1,508 +0,0 @@
 # Prompt Guide Arc Restructure — Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Restructure the 29-page Prompt Guide from a reference manual into a novice→advanced arc (spec: `plans/prompt-guide-arc.md`) where each level builds on the prior one and ends in a validated capstone film.
 **Architecture:** Pages keep their slugs (`docs/prompting/*.mdx`) — only `docs.json` grouping, page content framing, and two new pages (`storyboards`, `capstone`) change. Content rewrites are per-level editorial passes with a fixed bridge template. New prompts follow the standing validation protocol (built as written → lint/check → render → embed).
 **Tech Stack:** Mintlify docs (`docs/`), oxfmt/oxlint, HyperFrames CLI validation builds, S3 render hosting via `scripts/upload-docs-images.sh`.
 ## Global Constraints
 - All work in worktree `~/src/wt/hyperframes/prompt-guide` on branch `fix/prompt-guide-validation-bugs` (PR #2109). Commit with `/usr/bin/git` (the `rtk` proxy silently no-ops commits). Conventional commits; header ≤ 100 chars.
 - **No prompt ships unverified.** Every NEW prompt printed in the guide must pass the Validation Protocol below before its page is committed. Existing prompts keep their existing 64 embedded renders; do not rewrite a validated prompt's text (rewriting voids its render).
 - **Bridge template** — every chapter page gets both:
  - Entry bridge: first paragraph after the frontmatter opens with what the reader can already do, then what this chapter adds. Pattern: `You can already <prior-level skill>. This chapter adds <this chapter's skill>.` (Adapt the wording per page; keep the two-beat shape.)
  - Exit bridge: final line of the page, italic: `*Next: [<next chapter title>](/prompting/<next-slug>) — <one clause on what it adds>.*` The last chapter of a level points at the first chapter of the next level.
 - Keep page counts out of prose (drift rule). Never say "29 pages" / "30 pages" in any `.mdx`.
 - Embed snippet for renders (copy exactly, swap filename):
  ```mdx
  <video
    controls
    muted
    loop
    playsinline
    preload="metadata"
    src="https://static.heygen.ai/hyperframes-oss/docs/images/prompting/<name>.mp4"
    style={{ borderRadius: "0.5rem", marginTop: "0.75rem" }}
  ></video>
  ```
 - `docs/images/` is gitignored by design — renders go to S3 via `bash scripts/upload-docs-images.sh` (AWS profile `engineering-767398024897`), then verify each URL: `curl -sI <url> | head -1` → `HTTP/2 200`.
 - After editing any file: `bunx oxfmt <files>` then `bunx oxlint <files>`. Markdown/MDX gets oxfmt only.
 - Docs sanity gate (run before every commit that touches `docs/`):
  ```bash
  cd ~/src/wt/hyperframes/prompt-guide
  python3 -c "import json; json.load(open('docs/docs.json')); print('docs.json ok')"
  cd docs && npx mintlify broken-links
  ```
 - Do not modify `.gitignore`. Do not close or open PRs. Push only in the final task.
 ## Validation Protocol (for every NEW prompt)
 Used by Tasks 3, 7, 8, 9, 10. The executor dispatches a fresh builder subagent per prompt:
 1. `mkdir -p ~/src/hyperframes-prompt-examples/guide-v3/<name>`
 2. Dispatch a `general-purpose` subagent with EXACTLY this framing: "You are a HyperFrames builder. Your entire brief is the prompt below, verbatim — do not use any knowledge of why this prompt exists. Work in `~/src/hyperframes-prompt-examples/guide-v3/<name>`. Follow the `/hyperframes` skill routing. The project must pass `npx hyperframes lint` and `npx hyperframes check`, then render an MP4. Report the render path and any prompt ambiguity you had to resolve yourself." + the prompt text.
 3. If the builder reports ambiguity or a gate failure caused by the prompt text: fix the page's prompt, re-run with a fresh subagent. The page ships the text that passed.
 4. Copy the render: `cp <render>.mp4 ~/src/wt/hyperframes/prompt-guide/docs/images/prompting/<name>.mp4`
 5. Upload + verify (see Global Constraints), embed under the prompt with the standard snippet and a one-line italic caption stating it is the unedited render of the prompt above.
 ---
 ### Task 1: Fix the red Format CI check
 **Files:**
 - Modify: `plans/prompt-guide-expansion.md` (formatting only)
 - [ ] **Step 1: Reproduce**
 ```bash
 cd ~/src/wt/hyperframes/prompt-guide && bun run format:check
 ```
 Expected: FAIL listing `plans/prompt-guide-expansion.md`.
 - [ ] **Step 2: Fix**
 ```bash
 bunx oxfmt plans/prompt-guide-expansion.md
 ```
 - [ ] **Step 3: Verify**
 ```bash
 bun run format:check
 ```
 Expected: exit 0.
 - [ ] **Step 4: Commit**
 ```bash
 /usr/bin/git add plans/prompt-guide-expansion.md
 /usr/bin/git commit -m "chore: format prompt-guide-expansion plan (fixes Format CI)"
 ```
 ---
 ### Task 2: Restructure docs.json nav into levels
 **Files:**
 - Modify: `docs/docs.json` (the `Prompt Guide` group only)
 **Interfaces:**
 - Produces: the level grouping every later task's pages live in. Slugs unchanged; no new redirects needed (the existing `/guides/prompting` → `/prompting/overview` redirect stays untouched).
 - [ ] **Step 1: Replace the Prompt Guide group's subgroups**
 In `docs/docs.json`, find the group `"Prompt Guide"` and replace its `pages` array with:
 ```json
 [
  "prompting/overview",
  {
    "group": "Level 1 — Your first video",
    "pages": [
      "prompting/product-launch",
      "prompting/explainers",
      "prompting/code-and-prs",
      "prompting/captions-and-talking-heads",
      "prompting/music-and-slideshows",
      "prompting/motion-graphics"
    ]
  },
  {
    "group": "Level 2 — Control",
    "pages": [
      "prompting/anatomy",
      "prompting/specification-dial",
      "prompting/vocabulary",
      "prompting/visual-specs",
      "prompting/examples"
    ]
  },
  {
    "group": "Level 3 — Life",
    "pages": ["prompting/motion", "prompting/transitions"]
  },
  {
    "group": "Level 4 — Substance",
    "pages": [
      "prompting/code-blocks",
      "prompting/data-and-maps",
      "prompting/overlays-and-lower-thirds",
      "prompting/captions-catalog",
      "prompting/generated-artwork",
      "prompting/vfx-and-liquid-glass",
      "prompting/runtimes-and-3d"
    ]
  },
  {
    "group": "Level 5 — Voice and sound",
    "pages": ["prompting/media-and-audio"]
  },
  {
    "group": "Level 6 — Scale",
    "pages": [
      "prompting/design-systems",
      "prompting/variables-and-templating",
      "prompting/editing-existing-videos",
      "prompting/iterating",
      "prompting/recreating-references",
      "prompting/rendering-and-output",
      "prompting/remotion-migration"
    ]
  },
  {
    "group": "Appendix",
    "pages": ["prompting/rules-and-anti-patterns"]
  }
 ]
 ```
 Notes: `prompting/storyboards` is added to Level 6 (before `editing-existing-videos`) in Task 9 when the file exists; `prompting/capstone` is added as a `"Level 7 — Capstone"` group between Level 6 and Appendix in Task 11. Mintlify fails on nav entries whose files don't exist yet — that's why they're deferred.
 - [ ] **Step 2: Verify**
 Run the docs sanity gate (Global Constraints). Expected: `docs.json ok`, no broken links.
 - [ ] **Step 3: Commit**
 ```bash
 /usr/bin/git add docs/docs.json
 /usr/bin/git commit -m "docs(prompting): regroup Prompt Guide nav into novice-to-advanced levels"
 ```
 ---
 ### Task 3: Level 1 — workflow-ride rewrites (6 pages)
 **Files:**
 - Modify: `docs/prompting/product-launch.mdx`, `docs/prompting/explainers.mdx`, `docs/prompting/code-and-prs.mdx`, `docs/prompting/captions-and-talking-heads.mdx`, `docs/prompting/music-and-slideshows.mdx`, `docs/prompting/motion-graphics.mdx`
 **Interfaces:**
 - Consumes: nav order from Task 2 (bridge targets follow that order: product-launch → explainers → code-and-prs → captions-and-talking-heads → music-and-slideshows → motion-graphics → anatomy).
 - Produces: L1 framing later levels refer back to ("you rode a workflow; now open the hood").
 **Editorial contract (each page):**
 1. Reframe the page intro as a _first win_: one prompt to the workflow gets a finished video; the page's first validated prompt + its existing render move to the top.
 2. Keep every existing validated prompt and embed verbatim (moving them on the page is fine; editing their text is not).
 3. Existing "knobs that matter" material stays but moves after the first-win section, introduced as "what you can steer from the prompt before you've learned any technique."
 4. Apply the bridge template. Entry bridge for `product-launch` (the arc's first chapter) instead states the level premise: you need zero technique to get a first video — one sentence describing your product is enough.
 5. `motion-graphics` exit bridge points to `anatomy` and names the turn: "you've been riding workflows; Level 2 opens the prompt itself."
 **`code-and-prs` additionally** gains a short "Changelog videos" section: the `changelog-video` skill (landed after the original guide) turns a repo's recent merges into a changelog video. Write one prompt for it and run the Validation Protocol with name `changelog-video` — the builder runs against the public `heygen-com/hyperframes` repo history so the render is publishable.
 - [ ] **Step 1: Rewrite the 6 pages per the contract**
 - [ ] **Step 2: Validate the new changelog-video prompt** (Validation Protocol, name `changelog-video`; embed render in `code-and-prs.mdx`)
 - [ ] **Step 3: Format + docs sanity gate**
 ```bash
 bunx oxfmt docs/prompting/product-launch.mdx docs/prompting/explainers.mdx docs/prompting/code-and-prs.mdx docs/prompting/captions-and-talking-heads.mdx docs/prompting/music-and-slideshows.mdx docs/prompting/motion-graphics.mdx
 ```
 Then the docs sanity gate.
 - [ ] **Step 4: Commit**
 ```bash
 /usr/bin/git add docs/prompting/
 /usr/bin/git commit -m "docs(prompting): Level 1 — reframe workflow pages as first-win rides + changelog-video"
 ```
 ---
 ### Task 4: Level 2 — Control rewrites (5 pages)
 **Files:**
 - Modify: `docs/prompting/anatomy.mdx`, `docs/prompting/specification-dial.mdx`, `docs/prompting/vocabulary.mdx`, `docs/prompting/visual-specs.mdx`, `docs/prompting/examples.mdx`
 **Editorial contract:**
 1. `anatomy` entry bridge: "your Level 1 prompts worked because the workflow filled the gaps; the skeleton is how you take that control yourself." Add one short paragraph noting the composition-structure mandate now enforced by the framework (main commit `0aaac7aa3` / PR #2599): compositions follow a required structural shape, so the skeleton isn't style advice — the framework soft-warns when structure drifts. No new prompt needed.
 2. `examples` reframed as the level-end gallery: entry bridge frames the 18 dissections as "read these with your new vocabulary — spot the skeleton parts in each."
 3. Chapter order for bridges: anatomy → specification-dial → vocabulary → visual-specs → examples → motion.
 4. All existing prompts/renders/tables stay verbatim.
 - [ ] **Step 1: Rewrite the 5 pages per the contract**
 - [ ] **Step 2: Format + docs sanity gate** (`bunx oxfmt` the five files, then the gate)
 - [ ] **Step 3: Commit**
 ```bash
 /usr/bin/git add docs/prompting/
 /usr/bin/git commit -m "docs(prompting): Level 2 — control chapters with bridges + structure mandate note"
 ```
 ---
 ### Task 5: Level 3 — Life rewrites (2 pages)
 **Files:**
 - Modify: `docs/prompting/motion.mdx`, `docs/prompting/transitions.mdx`
 **Editorial contract:**
 1. `motion` entry bridge: "you can specify a frame precisely; this level makes it feel alive." Content (grammar, measured A/B, rule 7 seeded motion) already complete — bridges only.
 2. `transitions` moves from feature-reference framing to "motion between scenes": entry bridge builds on the grammar ("rule 2's camera and rule 3's overlap apply _between_ scenes too"). Existing prompts/renders stay.
 3. Bridge order: motion → transitions → code-blocks.
 - [ ] **Step 1: Rewrite the 2 pages per the contract**
 - [ ] **Step 2: Format + docs sanity gate**
 - [ ] **Step 3: Commit**
 ```bash
 /usr/bin/git add docs/prompting/
 /usr/bin/git commit -m "docs(prompting): Level 3 — life chapters with bridges"
 ```
 ---
 ### Task 6: Level 4 — Substance rewrites (7 pages)
 **Files:**
 - Modify: `docs/prompting/code-blocks.mdx`, `docs/prompting/data-and-maps.mdx`, `docs/prompting/overlays-and-lower-thirds.mdx`, `docs/prompting/captions-catalog.mdx`, `docs/prompting/generated-artwork.mdx`, `docs/prompting/vfx-and-liquid-glass.mdx`, `docs/prompting/runtimes-and-3d.mdx`
 **Editorial contract:**
 1. Every page reframes from "the X feature" to "add X to what you already have": the entry bridge names a Level 1-3 artifact the capability slots into (e.g. code-blocks → "your PR video from Level 1, now with a diff that types itself").
 2. All existing prompts/renders stay verbatim.
 3. Bridge order: code-blocks → data-and-maps → overlays-and-lower-thirds → captions-catalog → generated-artwork → vfx-and-liquid-glass → runtimes-and-3d → media-and-audio.
 - [ ] **Step 1: Rewrite the 7 pages per the contract**
 - [ ] **Step 2: Format + docs sanity gate**
 - [ ] **Step 3: Commit**
 ```bash
 /usr/bin/git add docs/prompting/
 /usr/bin/git commit -m "docs(prompting): Level 4 — capability chapters framed as additive"
 ```
 ---
 ### Task 7: Level 5 — media-and-audio + the proxy subsystem
 **Files:**
 - Modify: `docs/prompting/media-and-audio.mdx`
 - Read for grounding: `git log main --oneline` commits `9ca1e1710`, `9d148d288`, `645880706`, `39b588cbd`, `74b4f1e8c`, `35eff5038`, `e8371a7ac`, `664c39db9`, and `docs/` pages touched by `5f2819b1e`, `8c1b6c515` (the existing proxy docs — link to them rather than duplicating mechanics).
 **Editorial contract:**
 1. Entry bridge: "your video moves and reads right; this level gives it a voice" — narration/TTS/BGM material stays.
 2. New section "Bring any footage" covering the proxy subsystem _from the prompter's perspective_: you can now hand the workflow HEVC/HDR/odd-codec footage and preview/play/publish keep working — the framework probes codecs and builds bounded H.264 (and alpha-capable) proxies automatically; renders still use the original; `hyperframes lint` flags hostile codecs at info level; projects can opt out. Link to the concepts/media docs added by `8c1b6c515` for mechanics.
 3. One new validated prompt exercising it: a prompt that builds a short picture-in-picture piece from a provided HEVC clip. Validation Protocol name `proxy-footage`; the builder gets a real HEVC test clip (generate one first: `ffmpeg -f lavfi -i testsrc2=size=1280x720:rate=30 -t 6 -c:v libx265 -tag:v hvc1 ~/src/hyperframes-prompt-examples/guide-v3/proxy-footage/source-hevc.mp4`) and the prompt references `source-hevc.mp4` by relative path.
 - [ ] **Step 1: Ground against the proxy commits, then rewrite the page**
 - [ ] **Step 2: Validate the proxy-footage prompt** (Validation Protocol; embed render)
 - [ ] **Step 3: Format + docs sanity gate**
 - [ ] **Step 4: Commit**
 ```bash
 /usr/bin/git add docs/prompting/media-and-audio.mdx
 /usr/bin/git commit -m "docs(prompting): Level 5 — voice, sound, and automatic media proxies"
 ```
 ---
 ### Task 8: Level 6 — Scale rewrites (7 pages)
 **Files:**
 - Modify: `docs/prompting/design-systems.mdx`, `docs/prompting/variables-and-templating.mdx`, `docs/prompting/editing-existing-videos.mdx`, `docs/prompting/iterating.mdx`, `docs/prompting/recreating-references.mdx`, `docs/prompting/rendering-and-output.mdx`, `docs/prompting/remotion-migration.mdx`
 **Editorial contract:**
 1. Level premise (design-systems entry bridge): "everything so far was one scene at a time; this level is about videos as systems — design that persists across scenes, edits that don't regress, output that ships."
 2. `variables-and-templating`: add a correction note — composition variables no longer shadow authored CSS custom properties (main commit `406894061`); verify the page's existing wording against that commit's behavior and fix any sentence it invalidates. Existing default-vs-overridden render pair stays.
 3. `remotion-migration` framed as "bringing an existing Remotion project into everything you now know," last chapter before the capstone level.
 4. Bridge order: design-systems → variables-and-templating → storyboards (added in Task 9) → editing-existing-videos → iterating → recreating-references → rendering-and-output → remotion-migration → capstone (added in Task 11; until then point remotion-migration's exit bridge at rules-and-anti-patterns and fix it in Task 11).
 - [ ] **Step 1: Verify the variables claim against `git show 406894061`, then rewrite the 7 pages**
 - [ ] **Step 2: Format + docs sanity gate**
 - [ ] **Step 3: Commit**
 ```bash
 /usr/bin/git add docs/prompting/
 /usr/bin/git commit -m "docs(prompting): Level 6 — scale chapters + variables CSS-shadow correction"
 ```
 ---
 ### Task 9: New chapter — storyboards
 **Files:**
 - Create: `docs/prompting/storyboards.mdx`
 - Modify: `docs/docs.json` (insert `prompting/storyboards` into Level 6 before `editing-existing-videos`), `docs/prompting/variables-and-templating.mdx` (exit bridge now points to storyboards)
 - Source material: `videos/team-vault-explained/STORYBOARD.md` (in-repo), `~/src/videos/hyperframes-infra-proposals/STORYBOARD.md` — mine structure, not content.
 **Editorial contract:**
 1. Teach prompting _into_ a storyboard: for multi-scene work you don't prompt scenes, you prompt the plan — arc, per-frame beats, VO pacing — and the workflow builds frames against it.
 2. Document the storyboard vocabulary the internal films prove, as prompt language: narrative arc line, VO-paced reveals ("at t=0 only what the narrator is saying is on screen; each element lands on its spoken cue"), persuasion/beat per frame, a callback (an early motif returning denser late), exactly one breather frame, a per-frame negative list. Do NOT reproduce internal film content — invent neutral examples.
 3. One new validated prompt: a 3-frame mini storyboard piece (hook → substance → landing with callback), ~15s, no narration (keeps the build cheap). Validation Protocol name `storyboard-mini`; embed render.
 4. Bridges: entry from variables-and-templating; exit to editing-existing-videos.
 - [ ] **Step 1: Write the chapter per the contract**
 - [ ] **Step 2: Validate the storyboard-mini prompt** (Validation Protocol; embed render)
 - [ ] **Step 3: Add to nav, fix neighboring bridges, format + docs sanity gate**
 - [ ] **Step 4: Commit**
 ```bash
 /usr/bin/git add docs/prompting/storyboards.mdx docs/prompting/variables-and-templating.mdx docs/prompting/editing-existing-videos.mdx docs/docs.json
 /usr/bin/git commit -m "docs(prompting): add storyboards chapter — prompting the plan, not the scenes"
 ```
 ---
 ### Task 10: Appendix — rules cheat sheet + new lint rules
 **Files:**
 - Modify: `docs/prompting/rules-and-anti-patterns.mdx`; plus one-sentence in-context mentions on `docs/prompting/motion.mdx` (seek-safety) and `docs/prompting/runtimes-and-3d.mdx` (SVG draw-on) where the gotchas bite.
 **Editorial contract:**
 1. Reframe as the consolidated cheat sheet: entry bridge says every rule here was taught in context — this page is the lookup table; each rule row links its teaching chapter.
 2. Add the post-guide lint rules, phrased as prompt guidance (what to write / avoid so the build passes first try), each verified against its lint source before writing:
   - `gsap_cold_seek_hidden_fromto_missing_reveal` (#2503) — elements hidden at t=0 need an explicit reveal tween.
   - `gsap_callback_dom_measurement`, `gsap_function_value_hazard`, `gsap_repeat_refresh_relative_value`, `svg_drawon_css_dasharray_conflict`, `svg_measure_before_path_d` (#2611 / `f3d210066`) — seek-order safety and SVG draw-on.
   - `gsap_relative_value_second_writer`, `gsap_timeline_set_initial_hide` (#2612 / `4ad582606`).
     Ground each row: `git show <commit> -- packages/lint/src/rules/gsap.ts` and read the rule's message string; the guide row must match what the linter actually says.
 3. Rows are prompt guidance, not prompts — but any row that prints a runnable example prompt must pass the Validation Protocol (name `lint-<rule>`); rows with phrasing-only guidance need no build.
 - [ ] **Step 1: Ground each rule against lint source, write the rows + in-context mentions**
 - [ ] **Step 2: Format + docs sanity gate**
 - [ ] **Step 3: Commit**
 ```bash
 /usr/bin/git add docs/prompting/
 /usr/bin/git commit -m "docs(prompting): appendix cheat sheet + post-guide lint rules as prompt guidance"
 ```
 ---
 ### Task 11: Capstone film — build, validate, render
 **Files:**
 - Create (outside repo): `~/src/hyperframes-prompt-examples/capstone/` (brief, `frame.md`, `STORYBOARD.md`, compositions, audio, renders)
 - Create (repo, this task): nothing yet — the chapter is Task 12; this task produces the artifacts.
 **The film (from the spec):** public promo for HyperFrames itself ("write HTML, render video"), ~45-60s, 7 frames, 1920×1080. Required technique checklist and its frame mapping:
 | Frame | Content                                                                                                                             | Techniques it must carry                                |
 | ----- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
 | F1    | Hook — kinetic type on the one-line pitch                                                                                           | L2 skeleton, L3 grammar (staggered overshoot entrances) |
 | F2    | "Write HTML" — a composition types itself                                                                                           | L4 code-blocks (per-character typing beat)              |
 | F3    | "It becomes video" — pipeline diagram; **matched-motion transition into F4** (a diagram line becomes the F4 chart axis)             | L3 transitions                                          |
 | F4    | Proof — data-viz beat (e.g. render-speed or catalog count-up)                                                                       | L4 data-and-maps                                        |
 | F5    | Generated-artwork hybrid — one illustration-led beat (generated raster on contrasting solid bg, keyed, code-layer animation on top) | L4 generated-artwork                                    |
 | F6    | Capability montage — quick cuts, continuous camera push across them                                                                 | L3 camera-as-actor, L1 callbacks to workflows           |
 | F7    | Landing lockup — F1 motif returns denser (callback), the film's one breather, CTA `npx skills add heygen-com/hyperframes`           | L6 storyboard craft                                     |
 Production constraints:
 - `frame.md`: strict two-color system + negative list, per the internal-promo pattern — but pick a palette that is NOT cream/cobalt (do not read as a reuse of the internal films).
 - `STORYBOARD.md` uses the same frontmatter + per-frame field shape as `videos/team-vault-explained/STORYBOARD.md` (format/message/arc/audience/music; per-frame scene/voiceover/duration/transition_in/type/persuasion/beat/blueprint/focal). VO-paced reveals throughout.
 - Narration: TTS via `/media-use` (pick a voice explicitly — pass `--voice`); BGM resolved via `/media-use` at the default bed level (post-#2110 `bgmDefaultVolume`, do not override).
 - Variables: expose the two palette colors + product name as composition variables; render twice — default, and one `--variables` re-skin.
 - The film is built BY a builder subagent from a single long-form prompt (the "capstone prompt") that the guide will print in full — this is the point: the prompt IS the most advanced artifact. Author the capstone prompt first (brief + design system + storyboard direction + technique requirements in prose, per the guide's own anatomy), then run the Validation Protocol with name `capstone`. Iterate the prompt (fresh builder each time) until the render passes review; the shipped chapter prints the exact prompt that produced the shipped render.
 - [ ] **Step 1: Author the capstone prompt** (long-form; follows the guide's own 6-part anatomy; encodes the table above without naming levels)
 - [ ] **Step 2: Run the Validation Protocol, name `capstone`** — builder must produce: `frame.md`, `STORYBOARD.md`, frames, passing `lint`/`check`, `capstone.mp4`
 - [ ] **Step 3: Re-skin render** — `npx hyperframes render` with `--variables` overriding the palette colors → `capstone-reskin.mp4`
 - [ ] **Step 4: Review gate** — watch both renders; check every row of the technique table is visibly present; if not, revise the prompt and re-run Step 2 with a fresh builder
 - [ ] **Step 5: Upload** — copy `capstone.mp4` + `capstone-reskin.mp4` to `docs/images/prompting/`, run `bash scripts/upload-docs-images.sh`, `curl -sI` both URLs → 200
 No repo commit in this task (artifacts live outside the repo + on S3).
 ---
 ### Task 12: Capstone chapter + overview rewrite
 **Files:**
 - Create: `docs/prompting/capstone.mdx`
 - Modify: `docs/prompting/overview.mdx` (full rewrite), `docs/docs.json` (add `"Level 7 — Capstone"` group with `["prompting/capstone"]` between Level 6 and Appendix), `docs/prompting/remotion-migration.mdx` (exit bridge → capstone)
 **Editorial contract — `capstone.mdx`:**
 1. Opens with the embedded `capstone.mp4` render, then: "every technique in this film has a chapter in this guide."
 2. Prints the full capstone prompt verbatim (the one that produced the render), then dissects it: walk brief → design system → storyboard → frames → validation → render, each step linking the chapter that taught it (anatomy, visual-specs, motion, transitions, code-blocks, data-and-maps, generated-artwork, media-and-audio, design-systems, variables-and-templating, storyboards, rendering-and-output).
 3. Shows the `capstone-reskin.mp4` pair with the exact `--variables` invocation used.
 4. Exit bridge points at the Appendix cheat sheet: "keep this open while you build."
 **Editorial contract — `overview.mdx`:**
 1. Rewrite as the arc's map: open with the capstone embed and the promise "by the end of this guide you can build this with a prompt"; then the level ladder (one line per level: what you can do after it); then the existing one-time skill setup; then the two prompt shapes + workflow loop condensed.
 2. Existing "best of" example embeds may stay at the bottom.
 - [ ] **Step 1: Write `capstone.mdx` per the contract**
 - [ ] **Step 2: Rewrite `overview.mdx` per the contract**
 - [ ] **Step 3: Nav + bridges, format + docs sanity gate**
 - [ ] **Step 4: Commit**
 ```bash
 /usr/bin/git add docs/prompting/capstone.mdx docs/prompting/overview.mdx docs/prompting/remotion-migration.mdx docs/docs.json
 /usr/bin/git commit -m "docs(prompting): capstone chapter + overview rewritten as the arc's map"
 ```
 ---
 ### Task 13: Final QA + PR update
 **Files:**
 - Modify: PR #2109 description (via `gh`), spec `plans/prompt-guide-arc.md` status line.
 - [ ] **Step 1: Full-guide QA sweep**
 ```bash
 cd ~/src/wt/hyperframes/prompt-guide
 bun run format:check                    # expect exit 0
 python3 -c "import json; json.load(open('docs/docs.json')); print('ok')"
 cd docs && npx mintlify broken-links    # expect none
 # every S3 embed resolves:
 grep -rhoE 'https://static\.heygen\.ai/[^" ]+\.mp4' docs/prompting/ | sort -u | while read u; do
  code=$(curl -s -o /dev/null -w '%{http_code}' -I "$u"); [ "$code" = 200 ] || echo "BROKEN $code $u"
 done
 ```
 Also start `npx mintlify dev --port 3333` in `docs/` and click through the level nav once.
 - [ ] **Step 2: Bridge-chain check** — read only entry/exit bridges of all chapters in nav order; every exit target matches the next chapter; fix any mismatch.
 - [ ] **Step 3: Update spec status** — change `plans/prompt-guide-arc.md` line 3 `Status:` to `implemented <today's date>`; commit with the bridge fixes if any:
 ```bash
 /usr/bin/git add -A plans/prompt-guide-arc.md docs/
 /usr/bin/git commit -m "docs(prompting): final QA pass for the guide arc"
 ```
 - [ ] **Step 4: Push + update PR #2109**
 ```bash
 /usr/bin/git push origin fix/prompt-guide-validation-bugs
 gh pr edit 2109 --title "docs: Prompt Guide as a novice-to-capstone arc + text corrections from validation"
 ```
 Rewrite the PR body (via `gh pr edit 2109 --body-file`) to describe: the arc restructure (levels, full dissolve, bridges), the capstone film + its validated prompt, new topics covered (proxies, new lint rules, changelog-video, structure mandate, variables/CSS fix), the new validation builds, and keep the existing "text corrections" section. Keep the existing footer convention.
 - [ ] **Step 5: Verify CI green**
 ```bash
 gh pr checks 2109 --watch
 ```
 Expected: Format passes (Task 1); docs-only lanes skip as before.
@@ -1,98 +0,0 @@
 # Prompt Guide arc restructure — novice → capstone
 Status: implemented 2026-07-22. Owner: Vance. Supersedes the _structure_ of
 `plans/prompt-guide-expansion.md` (its content and validation rule carry over unchanged).
 Lands on `fix/prompt-guide-validation-bugs`, amending PR #2109.
 ## Why
 Reviewer feedback on the 29-page guide: it reads as a reference manual — "how to do
 specific things with prompts" — with no story in the hierarchy. The fix: restructure as a
 progression from novice to advanced where each section builds on techniques learned in the
 prior one, culminating in the most advanced artifact a reader can build with everything
 the guide teaches.
 Structure model ("full dissolve"): no standalone by-video-type / by-feature reference
 sections survive. Every page becomes a chapter at the level where the reader is ready for
 it, with an entry bridge ("you can now X") and an exit bridge ("next you'll Y").
 ## The capstone (design target — everything builds to this)
 A new, public, promo-style film about HyperFrames itself ("write HTML, render video"),
 ~45–60s, 6–8 frames. It is the "final form": the artifact only a reader who has absorbed
 every level can prompt into existence. Modeled on the internal promo compositions
 (`videos/team-vault-explained`, `~/src/videos/hyperframes-infra-proposals`) — the proven
 advanced stack:
 - `frame.md` design system: strict two-color palette discipline, negative list,
  permanent grid/chrome that rides every frame
 - Storyboard with narrative arc, VO-paced reveals (each element lands on its spoken cue),
  persuasion/beat columns, a callback (early motif returns denser late), one breather frame
 - TTS narration + BGM at the fixed bed level (post-#2110 default)
 - One generated-artwork hybrid frame (illustration-led → generated raster + code-layer
  animation), one data-viz frame, one code frame
 - Matched-motion transition between at least one frame pair
 - Variables re-skin: default vs overridden render pair
 - Full `lint` / `check` / render validation; built for real in
  `~/src/hyperframes-prompt-examples/capstone/`; renders hosted on static.heygen.ai
 The capstone chapter walks brief → design system → storyboard → per-frame build →
 validate → render, and each step links back to the level that taught it. The finished
 MP4 is also embedded in the overview intro as the guide's promise ("by the end you can
 build this").
 ## Level structure and page mapping
 Nav: the `Prompt Guide` top-level group's subgroups become levels.
 | Level | Title            | Chapters (existing page → new role)                                                                                                                                                                                                                   |
 | ----- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | —     | Start here       | `overview` — rewritten: the arc's map, skill setup, capstone teaser embed                                                                                                                                                                             |
 | L1    | Your first video | Workflow rides, one prompt + embedded render each: `product-launch`, `explainers`, `code-and-prs` (gains changelog-video), `captions-and-talking-heads`, `music-and-slideshows`, `motion-graphics`                                                    |
 | L2    | Control          | `anatomy`, `specification-dial`, `vocabulary`, `visual-specs`; `examples` becomes the level-end gallery (18 dissections)                                                                                                                              |
 | L3    | Life             | `motion` (grammar + measured A/B), `transitions`, seeded-motion rule 7 material                                                                                                                                                                       |
 | L4    | Substance        | Capability chapters framed as "add this to what you have": `code-blocks`, `data-and-maps`, `overlays-and-lower-thirds`, `captions-catalog`, `generated-artwork`, `vfx-and-liquid-glass`, `runtimes-and-3d`                                            |
 | L5    | Voice & sound    | `media-and-audio` expanded with the media-proxy subsystem (see New topics)                                                                                                                                                                            |
 | L6    | Scale            | `design-systems`, `variables-and-templating` (+ CSS-shadow fix), **storyboards** (new chapter, extracted from internal-promo practice), `editing-existing-videos`, `iterating`, `recreating-references`, `rendering-and-output`, `remotion-migration` |
 | L7    | Capstone         | New chapter as specified above                                                                                                                                                                                                                        |
 | —     | Appendix         | `rules-and-anti-patterns` kept as the consolidated cheat sheet; each rule is _also_ taught in-context at its level                                                                                                                                    |
 Page count: ~30 (29 existing, minus none, plus storyboards + capstone; overview rewritten).
 Keep page counts out of prose (standing drift rule).
 ## New topics (landed on main after the guide was written, Jul 9–22)
 1. **Media proxy subsystem** → L5 chapter section: HEVC/hostile-codec probe, automatic
   bounded H.264 and alpha-capable authoring proxies, serving from preview/play/static
   server, baking into published archives, project opt-out, runtime swap of undecodable
   video (#2585–#2598 range).
 2. **New lint rules** → taught at the level where each gotcha becomes relevant AND listed
   in the appendix: seek-order safety, SVG draw-on rules, relative-value second writers,
   `tl.set` initial hides, cold-seek opacity reveals (#2503, #2612, f3d210066).
 3. **Composition-structure mandate block** (#2599, 0aaac7aa3) → L2 anatomy context.
 4. **changelog-video skill** (e96ebd74d) → L1 code-and-prs chapter.
 5. **Variables no longer shadow authored CSS custom properties** (406894061) → L6
   variables chapter correction.
 ## Validation
 Standing rule unchanged: no prompt ships unverified. Existing 64 renders are reused
 wherever the prompt text survives the move verbatim. New validation builds required for:
 the capstone film (full pipeline), the proxy-chapter prompt, new-lint-gotcha examples,
 and the storyboard-chapter example. Same bar: built exactly as written by a builder
 agent, lint/check pass, render embedded.
 ## Mechanics
 - All work on `fix/prompt-guide-validation-bugs` in worktree
  `~/src/wt/hyperframes/prompt-guide`; PR #2109 description updated to describe the arc.
 - `docs.json` nav rewritten to the level groups; Mintlify redirects for any `prompting/*`
  slug that moves; the existing `guides/prompting` → `prompting/overview` redirect stays.
 - Renders synced via `scripts/upload-docs-images.sh` (S3, `docs/images/` stays gitignored).
 - Fix the currently red Format CI check on the branch while in there.
 ## Out of scope
 - Tier 3 registry-block overhauls (issue #2107) — unchanged.
 - HeyGenVerse article resync / llms.txt check — post-deploy follow-ups as before.
 - No behavior changes to skills or pipeline (that was PR #2110, merged).
@@ -1,266 +0,0 @@
 # Prompt Guide expansion plan
 Status: draft 2026-07-08. Owner: Vance. Source of validated content: the 2026-07-07/08
 prompting-guide work (18 verified example prompts, showreel recreation, motion grammar,
 asset-gen hybrid, recreation protocol; renders in ~/src/hyperframes-prompt-examples,
 preview page https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe).
 ## Goal
 Promote `guides/prompting` from a single page to a top-level **Prompt Guide** nav group:
 the current page splits into focused sub-pages, each expanded, and every documented
 feature that _implies_ a promptable action gets actual prompting guidance. Standing
 rule carried over from the original guide: **no prompt ships unverified** — every
 example is built, rendered, and (where feasible) embedded next to its prompt.
 ## Navigation (docs.json)
 New top-level group between **Concepts** and **Guides**:
 ```
 [Prompt Guide]
  prompting/overview
  [Fundamentals]
    prompting/anatomy
    prompting/specification-dial
    prompting/vocabulary
    prompting/iterating
    prompting/rules-and-anti-patterns
  [Making it look good]
    prompting/visual-specs
    prompting/motion
    prompting/generated-artwork
    prompting/recreating-references
  [By video type]
    prompting/product-launch
    prompting/explainers
    prompting/code-and-prs
    prompting/music-and-slideshows
    prompting/captions-and-talking-heads
    prompting/motion-graphics
  [By feature]
    prompting/transitions
    prompting/captions-catalog
    prompting/overlays-and-lower-thirds
    prompting/code-blocks
    prompting/data-and-maps
    prompting/vfx-and-liquid-glass
    prompting/rendering-and-output
    prompting/editing-existing-videos
    prompting/media-and-audio
    prompting/variables-and-templating
    prompting/runtimes-and-3d
    prompting/design-systems
 ```
 `guides/prompting` becomes a redirect to `prompting/overview`. Keep the page count out
 of prose (drift rule, same as skills.mdx).
 ## Page-by-page
 ### prompting/overview
 Landing: what prompting a video means, one-time skill setup (moved from current page),
 the two prompt shapes (cold/warm), the recommended workflow loop, and a map of the
 section. Ends with 3 "best of" example prompts w/ embedded renders.
 ### Fundamentals (split + expand current content — all already validated)
 - **anatomy** — the 6-part skeleton, per-part rationale, assembled terminal example,
  plus 3 dissections: take a weak prompt, show the fixed version, diff annotated.
 - **specification-dial** — mood → style tokens → full spec; cross-model validation
  result; the two always-pins (Three.js, sequencing). Expand: when looseness is a
  feature (creative exploration) vs when density is mandatory.
 - **vocabulary** — existing mapping tables (easing, caption tones, transition energy,
  audio-reactive, marker highlights, TTS voices, render quality) + new validated ones:
  camera language ("push in 6%", "drone orbit"), depth language ("near-lens bokeh"),
  pacing language ("punchy 2s cuts" vs "cinematic holds").
 - **iterating** — talk-like-an-editor edits (existing) + the calibration rules from the
  recreation work: absolute targets not relative nudges, one axis at a time, freeze
  what works.
 - **rules-and-anti-patterns** — the 7 technical rules, anti-patterns, plus the newly
  validated ones: never "holds motionless", don't create simultaneity conflicts,
  don't override skill-mandated styles, "~60s" with verbatim scripts.
 ### Making it look good (current sections promoted to pages, each gains examples)
 - **visual-specs** — density ladder + mountain-title worked example + 2 more specs
  (one UI piece, one typographic piece) with renders.
 - **motion** — the six-rule premium-motion grammar; before/after render pair
  (frozen-hold build vs motion-pass build of the same piece — we have both).
 - **generated-artwork** — hybrid pattern, 3 keying/restraint rules, before/after
  (hand-drawn SVG team vs asset-gen team — we have both renders).
 - **recreating-references** — the transcribe → iterate → distill protocol, fidelity
  table, globe worked example + its one-shot render; honest-ceiling callout.
 ### By video type (one page per workflow; the 8 current examples seed them)
 Each page: what the workflow does, 3-5 verified prompts (the existing one + variants:
 different durations, aspect ratios, tones), the knobs that matter for that workflow
 (e.g. explainer: verbatim vs summarized script, caption style, scene density), and
 common failure modes. NEW VALIDATION NEEDED: ~2-4 variant builds per page.
 Pages: product-launch (also covers website-to-video), explainers, code-and-prs
 (pr-to-video + code blocks context), music-and-slideshows, captions-and-talking-heads
 (embedded-captions + talking-head-recut), motion-graphics (also logo stings, stats).
 ### By feature — the "implied but unguided" gap pages
 Sourced from existing docs that document a capability without prompting guidance:
 - **transitions** (sources: 14 shader + 13 CSS catalog groups, transitions skill) —
  energy/mood → named block mapping, when shader vs CSS, per-seam prompting
  ("whip-pan on phrase changes"), full block name table. Validation: montage build
  exercising ~6 transitions.
 - **captions-catalog** (sources: 15 caption components + embedded-captions skill) —
  tone → component mapping ("karaoke pill", "kinetic slam", "matrix decode"), per-word
  styling asks, safe-area/vertical notes. Validation: one clip rendered with 4 styles.
 - **overlays-and-lower-thirds** (sources: social overlays, lower-thirds, news-ticker
  catalog groups) — "add a lower third at 0:03 with name/title" class of prompts,
  picking styles by brand tone, transparent-overlay output for NLEs.
 - **code-blocks** (sources: code animations + 24 code-snippet themes) — prompting
  code walkthroughs: typing, diff, highlight, scroll; theme selection language.
 - **data-and-maps** (sources: data-chart, 5 US-map variants, world/spain maps) — chart
  prompts from CSV/inline data, map highlight/flow/bubble asks, the animated-map
  motion-graphics pattern.
 - **vfx-and-liquid-glass** (sources: HTML-in-Canvas group, html-in-canvas guide) —
  device mockups, liquid glass, shatter/portal/magnetic effects; when these need the
  canvas pipeline and what to say.
 - **rendering-and-output** (sources: rendering, 4k-rendering, hdr, deploy/lambda) —
  quality/format/framerate asks, transparent WebM (and when it's incoherent — full-frame
  designs), 4K/HDR guidance incl. cost warnings, "render this on Lambda" cloud prompts.
 - **editing-existing-videos** (sources: timeline-editing, keyframes,
  video-editor-cheatsheet, studio docs) — NLE-verb prompts: trim/split/move/retime
  scenes, keyframe nudges, "make scene 2 snappier", swap assets; maps the cheatsheet's
  editor verbs to prompt phrasings. Likely the highest-traffic page of the group.
 - **media-and-audio** (sources: video-components, remove-background, media-use skill)
  — TTS voice/tone/speed asks, BGM mood + loudness targets ("under -18dB"), SFX cues,
  transcription/captions from audio, background removal, video-in-video/PiP, and the
  supplied-assets rule (explicit paths).
 - **variables-and-templating** (sources: concepts/variables, sdk) — parameterized
  compositions ("make name/logo/color variables"), batch/personalization prompts,
  template-then-instantiate pattern.
 - **runtimes-and-3d** (sources: concepts/frame-adapters, gsap-animation) — the
  Three.js-via-adapter pin with worked language, when Lottie/CSS/WAAPI make sense to
  request, shader transition requests, canvas/WebGL determinism caveats in prompt form.
 - **design-systems** (sources: claude-design, open-design, figma skill) — design.md /
  brand-token driven prompting, "use the site's own palette", Figma import asks.
 ## Validation & build plan
 Reuse the proven pipeline: Opus builder subagents, one-shot from the page's prompts,
 lint+validate+render gates, frame verification; embed finished MP4s next to prompts
 (Mintlify supports video embeds; assets go wherever docs media lives today — confirm
 hosting path, else link the HeyGenVerse gallery).
 Phasing (each phase shippable):
 1. **Restructure** — split current page into overview + Fundamentals + Making-it-look-good
   (no new validation needed; content exists). Add nav group + redirect. ~1 PR.
 2. **High-traffic gaps** — editing-existing-videos, rendering-and-output,
   media-and-audio, transitions, captions-catalog. Each needs a validation build day.
 3. **By video type** — 6 pages, variant builds per workflow.
 4. **Long tail** — remaining feature pages (data-and-maps, vfx, variables, runtimes,
   design-systems, overlays, code-blocks).
 ## Competitive research findings (2026-07-08, adversarially verified)
 Deep-research survey of first-party prompt guides — Sora 2 (OpenAI Cookbook), Runway
 Gen-3/Gen-4, Veo (DeepMind + Cloud Veo 3.1), Luma, Anthropic prompt-engineering docs.
 (Pika/Kling/Midjourney/Gemini/Copilot claims failed verification — resurvey later.)
 What the best guides converge on, and what we adopt:
 1. **Named content-slot anatomy.** Every major guide teaches a slot formula
   (camera + subject + action + context + style [+ audio]); Veo 3.1 and Runway Gen-3
   make it a literal bracket template. We already have a _process_ skeleton
   (route/spec/beats/copy/technique/negatives) — ADD a named _content_ formula whose
   slots map to HyperFrames concepts (beat + element + motion + layout + style/brand
   - audio), demonstrated in one worked example. Lives on the anatomy page.
 2. **Keyword→Output tables.** Runway Gen-3's gold standard: six categorized keyword
   tables where every row pairs the keyword with the actual generated output. Our
   vocabulary tables get the same treatment: motion verbs → GSAP behavior, camera
   terms → transform/Three.js choreography, style terms → CSS treatment — each row
   with a small rendered clip. (Borrow the format, not their legacy keywords.)
 3. **Output pairing is the differentiator.** Even the best guides skip outputs on
   their most complex examples (Sora's longest templates ship without any; both Veo
   guides mostly unpaired — refuted 0-3). Our article standard (every prompt +
   unedited render) beats the field; keep it absolute.
 4. **❌/✅ paired rewrites under named rules with engine rationale** — Runway's
   dominant device (e.g. ❌ "no clouds in the sky" → ✅ "a clear blue sky", because
   negative prompts backfire). Adopt across anatomy + rules pages using our own
   validated pairs: ❌ "holds motionless" → ✅ "settles into ambient idle";
   ❌ "both at 4s" → ✅ "fades out by 4.2s; at 4.2s..."; ❌ "make dots 2x finer" →
   ✅ "dot radius = 25% of row spacing".
 5. **Iteration as single-variable science.** Sora: "editing is for nudging, not
   gambling" — one change per edit; Runway Gen-4: minimal motion-only prompt first,
   then add ONE element type at a time; strip-then-relayer when a shot misfires.
   Expand the iterating page with these three moves + our absolute-targets rule.
 6. **Timestamped/beat-segmented prompting as a signature device.** Veo 3.1's
   [00:00-00:02] per-segment prompting is the survey's most distinctive device — and
   it maps one-to-one onto HyperFrames' native data-\* timing. Our "Beat N (x-ys)"
   convention is this; promote it explicitly ("more native here than in any
   diffusion model") on anatomy + by-video-type pages.
 7. **Anthropic's IA moves**: thin-router overview, one consolidated living
   best-practices reference (legacy URLs 301 into anchors), prerequisite gate
   ("before prompting, have X"). Adopt: keep overview thin; add a short
   prerequisites block (skills installed, preview running, project scaffolded);
   plan redirects when pages consolidate later.
 8. **Efficacy evidence as differentiation** (research open question): no surveyed
   guide shows its advice measurably works. Ours can — renders are deterministic and
   cheap; we already hold before/after pairs (frozen vs motion-passed, hand-drawn vs
   generated, loose vs dense builds). Add "before/after" render pairs as a standard
   device on making-it-look-good pages.
 Full cited report: deep-research run wf_c81199b6-b15 (22 confirmed claims, 3 refuted;
 sources incl. cookbook.openai.com, help.runwayml.com, deepmind.google, cloud.google.com,
 lumalabs.ai, platform.claude.com).
 ## Incorporate the article's drafted guidance
 The HeyGenVerse article (https://www.heygenverse.com/a/5db0a33b-97e3-4fdb-8747-823a73ad9bbe)
 drafted guidance and presentation patterns beyond the current mdx — these become the
 template for every expanded page:
 - **Proof pairing**: every example prompt is immediately followed by its unedited
  render with the label "Rendered from the prompt above, unedited." This is the
  guide's core credibility device — pages without renders don't ship.
 - **Provenance line**: each page states how its claims were validated (built,
  rendered, frame-verified) and when. The article's footer wording is the model.
 - **Example tags**: prompts carry a visible registry-block / workflow / freeform tag
  so readers learn which layer of the system they're exercising.
 - **Drafted section prose to carry over into the split pages** (the article's phrasing
  is tighter than the mdx in places — reconcile toward the article):
  - Specification dial: "controls how far the result drifts from what you imagined,
    not whether it works" + the two-pins callout as a distinct highlighted element.
  - Generated artwork: the wins/loses two-column comparison (code-drawn wins /
    code-drawn loses) rather than prose paragraphs.
  - Motion: six numbered rules with the "frozen final second is the biggest
    cheap-motion tell" line.
  - Recreation: the 3-row fidelity table (transcribe ~75% / iterate ~90% /
    distill ~80-90%) + honest-ceiling callout, with the one-shot render embedded
    under the distilled spec (not the hand-tuned version — the honest artifact).
 - **Article lifecycle**: the HV page stays the shareable preview/marketing surface;
  it gets regenerated from the docs content at the end of each phase so the two never
  fork. Renders already uploaded as HV assets (19 MP4s) are reusable by URL in the
  docs if we choose the link-out hosting option (open question 2).
 ## Consistency obligations
 - CLAUDE.md "skill catalog maintenance" applies: skills' SKILL.md descriptions stay the
  source of truth for one-line blurbs; the by-video-type pages must link the matching
  skill and not fork its routing language.
 - llms.txt regenerates from docs — verify the new group lands there.
 - Vocabulary tables must match what skills actually implement (easing map, caption
  tones) — audit against skills/hyperframes-animation + embedded-captions at write time.
 - Catalog pages already demo each block; feature pages link to them rather than
  duplicating block docs. Prompting pages own only the "what to say" layer.
 ## Open questions
 1. Group vs tab in docs.json (Mintlify): group keeps single-sidebar; tab gives the
   guide its own sidebar. Current nav is single-tab groups — start as group, promote to
   tab if it crowds.
 2. Where do example MP4s live for docs embeds — repo (heavy), CDN bucket, or link out
   to the HeyGenVerse gallery page? Decide before Phase 1 ships renders.
 3. Do by-video-type pages absorb the existing standalone guides (website-to-video) or
   link them? Proposal: link, don't absorb — those guides cover mechanics, prompting
   pages cover phrasing.
@@ -22,7 +22,7 @@
      "files": 17
    },
    "hyperframes-animation": {
-      "hash": "07ca0a5ce9d127ac",
+      "hash": "6c13cdce4f3a23c2",
      "files": 121
    },
    "hyperframes-cli": {