docs(prompting): document the intent interview and align pages with skill contracts

docs/guides/pipeline.mdx

@@ -15,7 +15,7 @@ Each step produces an artifact that feeds the next:
 |---|-------------------------|-----------------------------------------|-------------------------------------------------------------------------|
 | 1 | **Capture**             | `capture/`                              | Extract screenshots, design tokens, fonts, assets, animations from a source |
 | 2 | **Design**              | `DESIGN.md`                             | Brand reference: colors, typography, component stylings, spacing, iteration guide |
-| 3 | **Strategy & Messaging**| —                                       | Align on video type, style, the ONE message, narrative arc, and audience |
+| 3 | **Strategy & Messaging**| `BRIEF.md`                              | Lock video type, style, the ONE message, arc, audience — and the run's shape (automation or companion, storyboard or one-shot) |
 | 4 | **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md`          | Concept-first storyboard and narration script, written together         |
 | 5 | **VO + Timing**         | `narration.wav` + `transcript.json`     | TTS audio with word-level timestamps                                    |
 | 6 | **Build**               | `compositions/*.html`                   | Animated HTML compositions, one per beat                                |
@@ -38,7 +38,8 @@ my-video/
 │   ├── AGENTS.md               # capture summary for AI agents
 │   └── CLAUDE.md
 ├── DESIGN.md                   # Step 2, brand cheat sheet
-├── SCRIPT.md                   # Step 3, narration backbone
+├── BRIEF.md                    # Step 3, confirmed intent: message, audience, run shape
+├── SCRIPT.md                   # Step 4, narration backbone
 ├── STORYBOARD.md               # Step 4, beat-by-beat creative plan
 ├── narration.wav               # Step 5, TTS audio
 ├── narration.txt               # Step 5, exact spoken text (with pronunciation subs)
@@ -92,13 +93,15 @@ A typical `DESIGN.md` has five sections:
 
 ## Step 3: Strategy & Messaging
 
-**Output:** Alignment on video type, duration, style, and — critically — the ONE message and narrative arc
+**Output:** `BRIEF.md` in the project root
 
 Before any creative decisions, align with the user on the story this video must tell. Parse the user's prompt first — they probably already gave you the video type and style. Only ask about things they didn't specify. If the prompt is detailed enough, confirm the direction in one message and move to Step 4.
 
 The questions to resolve: what type of video (social ad, product demo, brand reel, etc.), what style and energy, what's the ONE thing this video must communicate, what narrative arc serves that message, and whether narration is wanted.
 
-**Gate:** Video type, duration, format, and the message and narrative arc are locked. Without those, Step 4 can't write a concept-first storyboard.
+When the project starts from `/hyperframes`, this step is the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first) — and it runs before Step 1, since the answers decide whether there's anything to capture at all. Either way, the confirmed answers land in `BRIEF.md`: frontmatter keys for the deterministic fields (`workflow`, `flow`, `storyboard`, `message`, audience, length), prose sections for the intent and any supplied material. A later session resumes from this file instead of re-asking.
+
+**Gate:** `BRIEF.md` exists — video type, duration, format, message, and narrative arc locked. Without those, Step 4 can't write a concept-first storyboard.
 
 ## Step 4: Storyboard + Script
 
@@ -185,6 +188,7 @@ For personalized or catalog outputs, render the same validated composition with
 
 The pipeline is built around named artifacts on disk so you can re-enter anywhere without re-running everything:
 
+- To change what the video is *for* — the message, the audience, the run's shape — edit `BRIEF.md`; it's the file the agent trusts over chat history.
 - To rework the creative plan, edit `STORYBOARD.md`: change a beat's mood, swap an asset, retime the entrance, then ask the agent to rebuild just that beat.
 - For surgical tweaks, open a composition file directly (e.g. `compositions/beat-3-proof.html`) and adjust animations, colors, or layout. `npx hyperframes preview` shows changes live.
 - To rebuild one beat from scratch, prompt the agent: _"Rebuild beat 2 with more energy. Use the product screenshot as full-bleed background."_ It reads `STORYBOARD.md`, `DESIGN.md`, and the transcript, then regenerates just that file.

docs/prompting/media-and-audio.mdx

@@ -3,7 +3,7 @@ title: Media and audio
 description: "Ask for the voiceover, music, sound, captions, cutouts, and assets a composition needs — with the precise, unambiguous phrasing the media pipeline acts on."
 ---
 
-By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a companion media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say.
+By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a sibling media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say.
 
 ## Voiceover (TTS)
 

docs/prompting/overview.mdx

@@ -48,19 +48,19 @@ The installer shows a picker. Select the **core skills** below — every project
 | `/media-use`            | Media OS — TTS voiceover (`tts`), `transcribe`, `remove-background`, plus BGM / SFX / image resolution |
 | `/hyperframes-registry` | Block and component installation via `hyperframes add`                     |
 | `/hyperframes-keyframes`| Seek-safe keyframe authoring across runtimes, plus `hyperframes keyframes` diagnostics |
-| `/general-video`        | The general authoring workflow — fallback for any video that doesn't match a specific workflow below |
+| `/general-video`        | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of **companion mode**; the fallback when no workflow below fits |
 
 **Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)
 
 | Slash command            | Input → output                                                              |
 | ------------------------ | --------------------------------------------------------------------------- |
 | `/product-launch-video`  | Any website URL / brief / script → launch or promo video, or a site tour / showcase |
-| `/faceless-explainer`    | Arbitrary text (no URL) → faceless explainer with its own TTS narration     |
+| `/faceless-explainer`    | Arbitrary text (no URL, no footage) → faceless explainer — every visual invented (typography, diagrams, data-viz) |
 | `/pr-to-video`           | A GitHub PR → code-change explainer                                         |
 | `/embedded-captions`     | An existing talking-head video → the same footage with captions / subtitles |
-| `/talking-head-recut`      | An existing talking-head video → footage packaged with designed graphic cards |
-| `/motion-graphics`       | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
-| `/music-to-video`        | A music track + your images → beat-synced video (lyric / slideshow / kinetic promo) |
+| `/talking-head-recut`      | An existing talking-head video → footage packaged with transcript-synced graphic overlays (kinetic titles, lower-thirds, PiP) |
+| `/motion-graphics`       | A logo / stat / tweet / brief → a short (~10s) unnarrated motion graphic (kinetic type, count-up, logo sting) — MP4 or transparent overlay |
+| `/music-to-video`        | A music track (or a video's audio) → beat-synced video (lyric / slideshow / kinetic promo); your images optional, cut on the beat |
 | `/slideshow`             | A deck outline or slides → navigable presentation with presenter mode (not a rendered MP4) |
 | `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML         |
 | `/figma`                 | A Figma file / frame / URL → imported assets, brand tokens, and reconstructed motion |
@@ -108,6 +108,25 @@ Warm-start prompts produce richer, more grounded videos because the agent is wri
 
 The four prompts above illustrate shape, not results — every prompt in this guide that ships with an embedded render was run exactly as written, and the gallery of those lives in [Verified examples](/prompting/examples).
 
+## The interview: what the agent asks first
+
+Either shape starts a short interview before anything is built. This isn't the agent stalling — it's the intent layer turning "make me a video" into a confirmed brief, so the build never has to guess the things you'd have corrected afterward. The agent confirms the route, then asks that workflow's must-have questions (recommended answer first, so most are one-word confirmations). When the selected workflow supports both run shapes, it then closes with two questions that shape the run itself:
+
+| Question | Your options |
+| --- | --- |
+| **Storyboard?** | `yes` — review the plan, wireframe sketches, and the build pass by pass on a live board (recommended past a couple of scenes) · `no` — one finished video from the confirmed brief |
+| **Automation or companion?** | `automation` — the matched workflow's pipeline executes the brief end to end · `companion` — build it together in `/general-video` with every HyperFrames capability on the table |
+
+The two are independent — all four combinations are valid, and a companion run reviews on the live board too when you said yes to the storyboard. Four routes skip both questions because neither has anything to add: `/motion-graphics` (the piece is seconds long), `/slideshow` (the deliverable is a navigable deck, not a rendered video), and `/embedded-captions` and `/talking-head-recut` (the footage is untouched, so there's no storyboard to review).
+
+In a hurry, skip the whole conversation by saying so:
+
+> Just build it — don't ask me anything.
+
+That locks `automation` with no storyboard wherever those apply, and every question the agent would have asked becomes a stated default in its heads-up instead.
+
+Everything the interview settles is written to **`BRIEF.md`** in the project root — the brief is the artifact, not the chat. A later session (or a different agent) resumes from that file and asks nothing again; to change an answer, edit `BRIEF.md` rather than re-explaining yourself in the prompt.
+
 ## Recommended workflow
 
 1. `npx hyperframes init my-video` — scaffold a project (skills install automatically)

docs/prompting/storyboards.mdx

@@ -7,6 +7,10 @@ description: "For multi-scene work, don't prompt the scenes one by one — promp
 
 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.
 
+<Note>
+"Storyboard" is also a question the agent asks in the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first) — answering yes there means the plan, the sketches, and the build get reviewed with you pass by pass on a live board. That answer changes the review process, not the route, and either way the plan this page teaches is what the build works from.
+</Note>
+
 ## 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.
@@ -97,7 +101,7 @@ Without stating the return explicitly, a rebuild is free to treat the early moti
     The two-color discipline and brand tokens a storyboard's direction block draws from.
   </Card>
   <Card title="The HyperFrames pipeline" icon="route" href="/guides/pipeline">
-    `STORYBOARD.md` as a production artifact — the file format this chapter's prompts turn into.
+    `STORYBOARD.md` as a production artifact — where this chapter's plans land, downstream of `BRIEF.md`.
   </Card>
 </CardGroup>