Merge pull request #2109 from heygen-com/fix/prompt-guide-validation-bugs

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

Author: vanceingalls

docs/concepts/compositions.mdx

@@ -37,6 +37,8 @@ You can embed one composition inside another in two ways: loading from an extern
   <Tab title="External file">
     Reference another HTML file with `data-composition-src`. The framework automatically fetches the file, extracts the `<template>` content, mounts it, executes scripts, and registers the timeline.
 
+    `data-composition-src` paths resolve relative to the **project root**, not the referencing file — a nested composition one level deep still writes `compositions/foo.html`, never `../compositions/foo.html`.
+
     ```html index.html
     <div
       id="el-5"

docs/docs.json

@@ -71,6 +71,83 @@
               "concepts/determinism"
             ]
           },
+          {
+            "group": "Prompt Guide",
+            "pages": [
+              "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/storyboards",
+                  "prompting/editing-existing-videos",
+                  "prompting/iterating",
+                  "prompting/recreating-references",
+                  "prompting/rendering-and-output",
+                  "prompting/remotion-migration"
+                ]
+              },
+              {
+                "group": "Level 7 — Capstone",
+                "pages": [
+                  "prompting/capstone"
+                ]
+              },
+              {
+                "group": "Appendix",
+                "pages": [
+                  "prompting/rules-and-anti-patterns"
+                ]
+              }
+            ]
+          },
           {
             "group": "Guides",
             "pages": [
@@ -89,7 +166,6 @@
               "guides/claude-design",
               "guides/claude-design-send-to-hyperframes",
               "guides/open-design",
-              "guides/prompting",
               "guides/hyperframes-vs-remotion",
               "guides/gsap-animation",
               "guides/keyframes",
@@ -413,5 +489,12 @@
     "socials": {
       "github": "https://github.com/heygen-com/hyperframes"
     }
-  }
+  },
+  "redirects": [
+    {
+      "source": "/guides/prompting",
+      "destination": "/prompting/overview",
+      "permanent": true
+    }
+  ]
 }

docs/guides/antigravity.mdx

@@ -135,7 +135,7 @@ HyperFrames projects created with `npx hyperframes init` scaffold both `CLAUDE.m
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Prompting guide" icon="message" href="/guides/prompting">
+  <Card title="Prompting guide" icon="message" href="/prompting/overview">
     Vocabulary and patterns that produce better compositions.
   </Card>
   <Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">

docs/guides/claude-design.mdx

@@ -143,7 +143,7 @@ Then iterate:
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Prompt Guide" icon="message" href="/guides/prompting">
+  <Card title="Prompt Guide" icon="message" href="/prompting/overview">
     More prompt patterns for HyperFrames across Claude Code, Claude Design, and other agents.
   </Card>
   <Card title="@hyperframes/player" icon="play" href="/packages/player">

docs/guides/copilot-cli.mdx

@@ -175,7 +175,7 @@ Authorize via OAuth when prompted. See the [MCP guide](/guides/mcp) for full det
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Prompting guide" icon="message" href="/guides/prompting">
+  <Card title="Prompting guide" icon="message" href="/prompting/overview">
     Vocabulary and patterns that produce better compositions.
   </Card>
   <Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">

docs/guides/mcp.mdx

@@ -320,7 +320,7 @@ The MCP is a HeyGen-hosted product that wraps:
   <Card title="Quickstart" href="/quickstart">
     Try HyperFrames locally with the open-source CLI.
   </Card>
-  <Card title="Prompting guide" href="/guides/prompting">
+  <Card title="Prompting guide" href="/prompting/overview">
     Tips for getting the best results when working with AI agents.
   </Card>
   <Card title="Catalog" href="/catalog/blocks/data-chart">

docs/guides/open-design.mdx

@@ -169,7 +169,7 @@ Then iterate the same way as the Claude Design path:
   <Card title="Claude Design Guide" icon="message" href="/guides/claude-design">
     The closed-source flavor of the same workflow — useful when you don't have a CLI on your laptop.
   </Card>
-  <Card title="Prompt Guide" icon="message" href="/guides/prompting">
+  <Card title="Prompt Guide" icon="message" href="/prompting/overview">
     More prompt patterns for HyperFrames across Claude Code, Claude Design, Open Design, and other agents.
   </Card>
 </CardGroup>

docs/guides/pipeline.mdx

@@ -141,7 +141,7 @@ npx hyperframes transcribe narration.wav
 | `narration.txt`  | The exact spoken text with pronunciation substitutions applied (`API` → `A P I`, `$2T` → `two trillion`). Distinct from `SCRIPT.md` so you can regenerate the audio later with a different voice without redoing the substitutions. |
 | `transcript.json`| `[{ text, start, end }]` for every word. Every later step reads this for timing. |
 
-Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/media-use`](/guides/prompting) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`.
+Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/media-use`](/guides/skills#domain-skills-loaded-on-demand) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`.
 
 **Gate:** `narration.wav`, `narration.txt`, and `transcript.json` exist. `STORYBOARD.md` beat timings reference real timestamps, not estimates.
 
@@ -153,7 +153,7 @@ This is where the storyboard becomes runnable HTML. Each composition is a self-c
 
 For multi-beat videos, spawn a focused sub-agent per beat. Each one gets fresh context, the storyboard section for its beat, the asset paths it needs, and the relevant technique references. That produces noticeably better output than building every beat in one long-running context.
 
-After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes-core`](/guides/prompting) skill encodes the composition rules — required `class="clip"` attributes, `data-*` attribute semantics — and [`/hyperframes-animation`](/guides/prompting) covers GSAP timeline registration and adapter registries.
+After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes-core`](/guides/skills#domain-skills-loaded-on-demand) skill encodes the composition rules — required `class="clip"` attributes, `data-*` attribute semantics — and [`/hyperframes-animation`](/guides/skills#domain-skills-loaded-on-demand) covers GSAP timeline registration and adapter registries.
 
 **Gate:** Every composition is self-reviewed. No overlapping elements, no misplaced assets, no static images sitting unanimated.
 
@@ -209,7 +209,7 @@ For a 5-second one-shot animation, a single hand-authored composition is fine; t
   <Card title="Website to Video" icon="globe" href="/guides/website-to-video">
     The full website-to-video guide built on this pipeline.
   </Card>
-  <Card title="Prompting" icon="comment" href="/guides/prompting">
+  <Card title="Prompting" icon="comment" href="/prompting/overview">
     How to invoke the pipeline through your AI agent.
   </Card>
   <Card title="Launch Videos" icon="rocket" href="/launch-videos">