hyperframes/plans/prompt-guide-arc-plan.md

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):

  <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/):

  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

cd ~/src/wt/hyperframes/prompt-guide && bun run format:check

Expected: FAIL listing plans/prompt-guide-expansion.md.

• Step 2: Fix

bunx oxfmt plans/prompt-guide-expansion.md

• Step 3: Verify

bun run format:check

Expected: exit 0.

• Step 4: Commit

/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:

[
  "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

/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

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

/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

/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

/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

/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

/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

/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

/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

/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

/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

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:

/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

/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

gh pr checks 2109 --watch

Expected: Format passes (Task 1); docs-only lanes skip as before.