From 3cbfeae3fa08914692a828faef72285095504290 Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Tue, 7 Jul 2026 21:15:57 +0800
Subject: [PATCH 1/6] =?UTF-8?q?feat(skills):=20add=20brief=20contract=20?=
 =?UTF-8?q?=E2=80=94=20interaction=20modes=20+=20shared=20intake=20fields?=
 =?UTF-8?q?=20across=20workflows?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New hyperframes-core/references/brief-contract.md, the shared intake
contract every creation workflow now runs its brief against:

- §1 interaction mode: collaborative (default) vs autonomous, ongoing
  vs one-time signals, mode set once and carried forward, and a gate
  taxonomy (preference / checkpoint / quality / routing) — autonomous
  skips waiting, never verification
- §2 field registry: destination→aspect derivation (feed → 1:1,
  Shorts/TikTok → 9:16, else 16:9), message, angle, length, audience,
  language, narration — each workflow binds fields as ask or state
- §3 question rules: one round with one question per asked field
  (native question UI mandatory when available, recommended option
  first with a receipt), never drop a question as inferable, and a
  mode legend advertised in the intro text instead of asked

Wired into the surfaces:

- hyperframes router: detect mode at entry, derive aspect from
  destination instead of stating 16:9
- product-launch-video / pr-to-video / faceless-explainer: ask/state
  binding tables at Step 0; Step 3/6 checkpoint-gate branches
  (autonomous posts a heads-up with a preview hint before render)
- website-to-video: local mode definition now defers to the contract
- music-to-video, general-video, embedded-captions, talking-head-recut,
  slideshow, motion-graphics: mode semantics wired per gate type
- storyboard-format: new optional 'mode' frontmatter key
- pr-to-video: length tier is a ceiling, not a floor — a one-headline
  PR recommends inside the 30–90s sweet spot regardless of diff size
---
 skills-manifest.json                          | 26 +++++-----
 skills/embedded-captions/SKILL.md             |  4 ++
 skills/faceless-explainer/SKILL.md            | 29 +++++++----
 skills/general-video/SKILL.md                 |  2 +-
 skills/hyperframes-core/SKILL.md              | 29 +++++------
 .../references/brief-contract.md              | 48 +++++++++++++++++++
 .../references/storyboard-format.md           | 13 ++---
 skills/hyperframes/SKILL.md                   |  4 +-
 skills/motion-graphics/SKILL.md               |  2 +
 skills/music-to-video/SKILL.md                | 10 ++--
 skills/pr-to-video/SKILL.md                   | 32 +++++++++----
 skills/product-launch-video/SKILL.md          | 29 +++++++----
 skills/slideshow/SKILL.md                     |  2 +-
 skills/talking-head-recut/SKILL.md            |  4 +-
 skills/website-to-video/SKILL.md              |  4 +-
 15 files changed, 168 insertions(+), 70 deletions(-)
 create mode 100644 skills/hyperframes-core/references/brief-contract.md

diff --git a/skills-manifest.json b/skills-manifest.json
index 5bb238f236..86a31dc1b6 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -2,11 +2,11 @@
   "source": "heygen-com/hyperframes",
   "skills": {
     "embedded-captions": {
-      "hash": "d870992d206c9ddc",
+      "hash": "169f74d84d52860c",
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "80882d8135b2aeac",
+      "hash": "82987c3d87648710",
       "files": 18
     },
     "figma": {
@@ -14,11 +14,11 @@
       "files": 1
     },
     "general-video": {
-      "hash": "6cb3fbdf9b860ba6",
+      "hash": "c0beee735bee14ac",
       "files": 1
     },
     "hyperframes": {
-      "hash": "4e0795ead8c8bfa3",
+      "hash": "14e7ce906fab5923",
       "files": 1
     },
     "hyperframes-animation": {
@@ -30,8 +30,8 @@
       "files": 7
     },
     "hyperframes-core": {
-      "hash": "6683808c1c4beebd",
-      "files": 13
+      "hash": "cb4b275446b8de6b",
+      "files": 14
     },
     "hyperframes-creative": {
       "hash": "18a14a79da6cbc06",
@@ -50,19 +50,19 @@
       "files": 97
     },
     "motion-graphics": {
-      "hash": "f5a432862116b39a",
+      "hash": "2f7d2bd5a7576141",
       "files": 23
     },
     "music-to-video": {
-      "hash": "42aba6b650599962",
+      "hash": "920107da254d8fc1",
       "files": 132
     },
     "pr-to-video": {
-      "hash": "71dce61cff0233f2",
+      "hash": "d7caab8e0aac7191",
       "files": 22
     },
     "product-launch-video": {
-      "hash": "ac4e1e4aa671fe27",
+      "hash": "38114c90d19cbab2",
       "files": 20
     },
     "remotion-to-hyperframes": {
@@ -70,15 +70,15 @@
       "files": 70
     },
     "slideshow": {
-      "hash": "764746e9199213b6",
+      "hash": "2b93ef9099bb1c9a",
       "files": 2
     },
     "talking-head-recut": {
-      "hash": "fbb95a4c6062c41a",
+      "hash": "e954e659a81cb937",
       "files": 27
     },
     "website-to-video": {
-      "hash": "d81ede8e9cabd09b",
+      "hash": "db7cfa04c6939cc9",
       "files": 32
     }
   }
diff --git a/skills/embedded-captions/SKILL.md b/skills/embedded-captions/SKILL.md
index b128a83933..463a8c4ccf 100644
--- a/skills/embedded-captions/SKILL.md
+++ b/skills/embedded-captions/SKILL.md
@@ -59,6 +59,10 @@ encodes everything routing needs: reading surface, voice, recommend-for, scene
 needs, adjacency notes for the genuinely-close pairs (loud↔ordnance,
 neon↔neonsign, cream↔stardust).
 
+The identity pick is a **preference gate** (`../hyperframes-core/references/brief-contract.md` § 1):
+in autonomous mode ("surprise me" / "decide for me"), pick from your shortlist
+yourself and state the one-line why instead of asking.
+
 Procedure: probe the clip → shortlist 2–3 identities from the catalog →
 recommend ONE with a one-line why → **the user picks** → author that identity's
 file. Identities are engine-locked (no cross combos; opening one is a
diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md
index 895f57592b..d818af0c47 100644
--- a/skills/faceless-explainer/SKILL.md
+++ b/skills/faceless-explainer/SKILL.md
@@ -11,7 +11,7 @@ Use this skill to turn a body of text into an explainer video: pick a design sys
 
 > **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for **explaining a topic from text, with no product and no website to capture**. Route other intents elsewhere: a product launch/promo → `/product-launch-video`; a tour of a real site → `/website-to-video`; a GitHub PR → `/pr-to-video`; captions on existing footage → `/embedded-captions`; a short unnarrated motion graphic → `/motion-graphics`. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the interaction mode (collaborative vs autonomous), the shared brief fields, and how to ask; the mode governs how the Step 0/3/6 gates behave. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup → `hyperframes.json`; Step 1 brief → `capture/extracted/`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.
 
@@ -27,7 +27,19 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the topi
 
 **Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
 
-**Gate:** `hyperframes.json` exists, and angle, length, aspect ratio, and language are locked; sign-in status was shown (signed in, or continuing offline).
+**Confirm the brief in one round** per the brief contract — every asked field gets its own question with a recommended default plus a one-line receipt; "go" accepts all.
+
+**Ask** (each its own question, every run — never drop one as "inferable"):
+
+- **angle** — how the topic is taught (concept / how-to / listicle / narrative); default: infer from the text's own shape (state the basis).
+- **length** — default inside the 30–90s sweet spot, scaled to how much the text actually teaches (state the basis).
+- **destination → aspect** — per the contract's derivation (social feed → 1:1; Shorts / TikTok → 9:16; else 16:9).
+
+**State in the intro text** (don't ask): **message** (the explainer's thesis, echoed back in one sentence), **language** (the user's). (`VO_MODE` is asked in Step 1 only when a script was pasted.)
+
+In autonomous mode, state the locked brief as a heads-up and proceed.
+
+**Gate:** `hyperframes.json` exists, and the brief fields (angle, length, destination → aspect, message, language) are locked; sign-in status was shown (signed in, or continuing offline).
 
 ---
 
@@ -74,9 +86,9 @@ Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md
 
 Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. Use the exact required fields from the storyboard and script references.
 
-After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6.
+After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed without waiting — skip the preview question and carry "not asked" to Step 6.
 
-**Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan.
+**Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
 ---
 
@@ -168,23 +180,23 @@ If a command fails, surface stderr and stop — don't pile on recovery commands.
 
 **Known false-positive — do not chase it.** `inspect` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
 
-After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode the review pause is a checkpoint gate: post a one-line heads-up (checks passed, render starting — `npx hyperframes preview` if they want to look first), proceed to render without waiting, then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview`
 
-Render only after user approval:
+Render only after user approval (autonomous mode: after the checks pass):
 
 `npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4`
 
 Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless the user asks.
 
-**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause; `renders/video.mp4` exists. Final reply states MP4 path and final duration.
+**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists. Final reply states MP4 path and final duration.
 
 ---
 
 ## Quick Reference
 
-**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the format once in the storyboard frontmatter.
+**Formats:** landscape `1920x1080`; portrait `1080x1920`; square `1080x1080` — derived from the destination (brief contract § 2). Set the format once in the storyboard frontmatter.
 
 **Faceless deltas vs a captured-asset workflow:** no Step 1 capture (synthetic `tokens.json` + `visible-text.txt`); no `asset-descriptions.md` and no `capture/assets/`; no asset-staging in Step 4; `asset_candidates` empty by default; every visual is invented by the Step 5 workers (typography / abstract graphics / diagrams / data-viz). A user-supplied `public/<basename>` image is the only real asset path.
 
@@ -194,6 +206,7 @@ The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blue
 
 | Read                                                                                                                                                        | When                                                           |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.    |
 | `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                       |
 | `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                          |
 | `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the explainer story.                              |
diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md
index 7fde74fb39..97917d6383 100644
--- a/skills/general-video/SKILL.md
+++ b/skills/general-video/SKILL.md
@@ -27,7 +27,7 @@ For vague, exploratory requests ("make something for our brand", "a cool intro")
 - **Priority** — what matters most? motion quality / content accuracy / brand fidelity / speed?
 - **Variations** — one best shot, or 2-3 meaningfully different options (different pacing, energy, or structure — not just color swaps)?
 
-For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery.
+For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery. If the request carries an ongoing autonomous signal ("surprise me", "just build it" — `hyperframes-core/references/brief-contract.md` § 1), skip discovery too: default to one best shot and state your calls with one-line receipts as you make them.
 
 ### Step 1 — Design system → `hyperframes-creative`
 
diff --git a/skills/hyperframes-core/SKILL.md b/skills/hyperframes-core/SKILL.md
index 9b2fc009f5..26375214ae 100644
--- a/skills/hyperframes-core/SKILL.md
+++ b/skills/hyperframes-core/SKILL.md
@@ -11,20 +11,21 @@ This skill is the **technical contract** — how to build one hyperframes projec
 
 ## References
 
-| File                                 | Read it to…                                                                                       |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------- |
-| `references/minimal-composition.md`  | start from the smallest renderable composition skeleton                                           |
-| `references/composition-patterns.md` | choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype         |
-| `references/data-attributes.md`      | look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"`           |
-| `references/tracks-and-clips.md`     | pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another     |
-| `references/sub-compositions.md`     | wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it        |
-| `references/variables-and-media.md`  | declare variables; place `<video>`/`<audio>`, set volume, trim                                    |
-| `references/determinism-rules.md`    | build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit |
-| `references/full-screen-motion.md`   | author full-frame motion with shared backgrounds                                                  |
-| `references/storyboard-format.md`    | author a `STORYBOARD.md` plan (+ the parsed manifest)                                             |
-| `references/script-format.md`        | author the optional `SCRIPT.md` locked narration                                                  |
-| `references/subagent-dispatch.md`    | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness                |
-| `references/tailwind.md`             | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3)      |
+| File                                 | Read it to…                                                                                                             |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `references/minimal-composition.md`  | start from the smallest renderable composition skeleton                                                                 |
+| `references/composition-patterns.md` | choose monolithic vs modular; structure a modular `index.html`; pick a sub-comp archetype                               |
+| `references/data-attributes.md`      | look up any `data-*` (root / clip / sub-comp host / legacy aliases); use `class="clip"`                                 |
+| `references/tracks-and-clips.md`     | pick `data-track-index`, handle same-track overlap / z-index, time a clip relative to another                           |
+| `references/sub-compositions.md`     | wire a sub-composition (host attrs, `<template>`, per-instance vars) and animate inside it                              |
+| `references/variables-and-media.md`  | declare variables; place `<video>`/`<audio>`, set volume, trim                                                          |
+| `references/determinism-rules.md`    | build a seekable timeline; determinism bans; the animatable-property allowlist; layout / text fit                       |
+| `references/full-screen-motion.md`   | author full-frame motion with shared backgrounds                                                                        |
+| `references/storyboard-format.md`    | author a `STORYBOARD.md` plan (+ the parsed manifest)                                                                   |
+| `references/brief-contract.md`       | conduct a creation workflow's intake — interaction mode (collaborative / autonomous), shared brief fields, asking rules |
+| `references/script-format.md`        | author the optional `SCRIPT.md` locked narration                                                                        |
+| `references/subagent-dispatch.md`    | map subagent dispatch verbs (parallel fan-out / background / wait) to your harness                                      |
+| `references/tailwind.md`             | work in a Tailwind v4 project (`init --tailwind`; runtime contract differs from Studio's v3)                            |
 
 For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) go to `hyperframes-animation` → `adapters/<runtime>.md`.
 
diff --git a/skills/hyperframes-core/references/brief-contract.md b/skills/hyperframes-core/references/brief-contract.md
new file mode 100644
index 0000000000..ec489db617
--- /dev/null
+++ b/skills/hyperframes-core/references/brief-contract.md
@@ -0,0 +1,48 @@
+# Brief contract — interaction mode, shared brief fields, and question rules
+
+Every creation workflow runs its intake step (Step 0 / brief) against this contract. It defines three things: the **interaction mode** (which controls all later gates, not just the brief), the **shared brief fields**, and the **question rules**. Each workflow maps these fields to its own values in its SKILL.md — including its enums, recommendation logic, and extra inputs. This file never includes workflow-specific content. Workflows without a real brief, such as `/motion-graphics`, use only § 1.
+
+## 1. Interaction mode
+
+There are two modes. Default: **collaborative**.
+
+**Signals.**
+
+- **Ongoing autonomous signals** — "autonomous", "surprise me", "decide for me", "just build it", "don't ask, just go", "LFG": the whole flow switches to autonomous from this point on.
+- **One-time acceptance** — a bare "go" / "looks good" at a gate accepts only that gate's defaults; the mode does not change.
+- The mode is set **once** — during routing (`/hyperframes`) or during the workflow brief — and **carries forward. No later step asks again.** Once a storyboard exists, record it in `STORYBOARD.md` frontmatter (`mode: autonomous`) so resumed sessions inherit it.
+- **Mid-run switch**: "stop asking / just finish it" → autonomous for the rest of the run. Clear feedback on a heads-up → collaborative resumes at the next gate.
+
+**Gate types.** Autonomous mode changes only the first two types:
+
+1. **Preference gates** (which preset, voice, caption identity, want a preview?) — autonomous: decide yourself and state the decision with a one-line reason. Never stay silent.
+2. **Checkpoint gates** (storyboard approval, pre-render review) — autonomous: post the same summary you would have asked about as an inline heads-up, then continue without waiting.
+3. **Quality gates** (`lint` / `validate` / `inspect`, capture completeness, fetch failures, workflow-specific verification checklists) — never skip these in any mode. Errors still stop the run. Reasoning like "autonomous means bias toward action, so I'll skip verification" misuses the mode — bias toward action applies to deciding _what to build_, not _whether to verify_.
+4. **Routing and sign-in decisions** — wrong routing is a quality problem: an ambiguous-intent confirmation, such as `/slideshow`'s "is this a deck?", still happens in autonomous mode. Auth sign-in follows `/media-use` → Preflight: show the status as-is; collaborative waits for the user's choice, while autonomous notes it and continues offline.
+
+**Autonomous is not silent.** Every question absorbed by the mode becomes a decision with a receipt — state the choice and its one-line reason inline as you go. Final delivery always includes the contact sheet, so review happens after the fact instead of not happening at all.
+
+## 2. Field registry
+
+The shared brief fields. Each workflow's SKILL.md declares which fields it uses, its own value set, how it derives recommendations, and — decisively — marks each field **ask** (always gets its own question) or **state** (stated in the intro text, never asked). The binding table's ask/state marking is authoritative; the default policies below apply only when a binding doesn't say otherwise. If a workflow does not use a field, such as `/music-to-video` having no narration, that field is simply absent from its binding — don't ask about it.
+
+| Field         | Meaning                                                               | Default policy                                                                                                                                                                                                                   |
+| ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | collaborative / autonomous (§ 1)                                      | detect signals; never ask again                                                                                                                                                                                                  |
+| `destination` | where the video will play (X / LinkedIn feed, YouTube, TikTok, embed) | infer from the request; if unknown **and** it would change aspect or type scale, include ONE question in the brief                                                                                                               |
+| `aspect`      | canvas                                                                | derive from destination — social **feed** (X / LinkedIn / Instagram) → square `1080x1080`; TikTok / Reels / Shorts → `1080x1920`; YouTube / website embed / unknown-desktop → `1920x1080`. State the derivation; never ask twice |
+| `length`      | target duration                                                       | the workflow derives its own recommendation and states the reason                                                                                                                                                                |
+| `language`    | narration + captions                                                  | use the user's language — state it, don't ask                                                                                                                                                                                    |
+| `audience`    | who will watch                                                        | infer from the input; confirm only when it would change the beats                                                                                                                                                                |
+| `message`     | the ONE thing the video must communicate                              | derive it and echo it in the brief — if the message cannot be stated in one sentence, the video is not ready for storyboarding                                                                                                   |
+| `angle`       | what kind of story (workflow enum)                                    | workflow-specific values; recommend one with a receipt                                                                                                                                                                           |
+| `narration`   | yes / minimal / no (+ workflow slots such as `VO_MODE`)               | workflow-specific                                                                                                                                                                                                                |
+
+## 3. Question rules
+
+- **Parse the prompt first.** Only ask for what the user has not already specified, and never ask them to confirm what they already said. Pre-fill anything `/hyperframes` or an earlier step has locked.
+- **One round, one question per asked field.** Bundle the brief into a single round: every field the workflow's binding marks **ask** gets its own question (native UI: one multi-question call — e.g. angle / length / destination as separate questions), leading with the recommended default plus its receipt; every **state** field goes in the intro text. The ask/state split is fixed by the binding table — **never drop a question because its answer looks inferable**; confidence sharpens the recommended default, it doesn't remove the question. "go" accepts all defaults.
+- **Advertise the mode, don't ask it.** Every brief carries a one-line legend: `"go" accepts all defaults · "surprise me" / "just build it" hands me every later decision (autonomous — no more questions, each call comes with its reason)`. In plain text, end the brief message with it; with a native question UI (`AskUserQuestion` or equivalent), put it in the short intro text you send **before** the question call — the UI has no message tail. The mode never gets its own question or option; the legend text is the only place it appears.
+- **Receipts.** A recommendation without a reason is a guess — every default states where it came from, for example: "~40s — small change, +44/−13 across 12 files".
+- **Channel.** When the environment has a native question UI (`AskUserQuestion` or equivalent), using it for the **ask** fields is **mandatory** in collaborative mode — one multi-question call, each question offering 2–4 options with the recommended one first. A plain-text "here's the brief, reply 'go'" statement is NOT a substitute; that shape is reserved for autonomous mode's heads-up. Only in an environment with no native UI, ask in plain text as one numbered list. Use 2–5 questions max per round.
+- **Autonomous brief.** Don't ask at all — state the locked brief, including all fields and receipts, as a heads-up and proceed.
diff --git a/skills/hyperframes-core/references/storyboard-format.md b/skills/hyperframes-core/references/storyboard-format.md
index c46bda11de..b69d50f920 100644
--- a/skills/hyperframes-core/references/storyboard-format.md
+++ b/skills/hyperframes-core/references/storyboard-format.md
@@ -8,12 +8,13 @@ A storyboard is the **plan layer** for a video — an ordered set of **frames**
 
 YAML block at the top. Unknown keys are kept under `globals.extra`.
 
-| Key        | Meaning         | Example                                   |
-| ---------- | --------------- | ----------------------------------------- |
-| `format`   | Canvas size     | `1920x1080`                               |
-| `message`  | One-line thesis | `Ship a launch video in an afternoon`     |
-| `arc`      | Narrative arc   | `Hook → Problem → Solution → Proof → CTA` |
-| `audience` | Who it's for    | `indie devs on X`                         |
+| Key        | Meaning                                                           | Example                                   |
+| ---------- | ----------------------------------------------------------------- | ----------------------------------------- |
+| `format`   | Canvas size                                                       | `1920x1080`                               |
+| `message`  | One-line thesis                                                   | `Ship a launch video in an afternoon`     |
+| `arc`      | Narrative arc                                                     | `Hook → Problem → Solution → Proof → CTA` |
+| `audience` | Who it's for                                                      | `indie devs on X`                         |
+| `mode`     | Interaction mode (see `brief-contract.md`; default collaborative) | `autonomous`                              |
 
 ## Per-frame sections
 
diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md
index 0995faeb99..7cd05cfb87 100644
--- a/skills/hyperframes/SKILL.md
+++ b/skills/hyperframes/SKILL.md
@@ -48,7 +48,9 @@ Routing needs to know **what the video is about** — its input and subject. If
 
 - **Input** — a product (URL / brief), a general website, a GitHub PR, a topic to explain, or an existing talking-head video?
 
-**Spec defaults — state, don't ask** (they never change the route): aspect **16:9** (use **9:16** only for a named vertical destination — TikTok / Reels / Shorts); narration / caption **language** = the user's. The chosen workflow re-confirms its own specifics at its first step.
+**Mode** — if the request carries an ongoing autonomous signal ("surprise me", "decide for me", "just build it"), note it and pass it into the workflow: the whole run goes autonomous and no later step re-asks. Default is collaborative. (`/motion-graphics` is autonomous by design.) Semantics: `hyperframes-core` → `references/brief-contract.md`.
+
+**Spec defaults — state, don't ask** (they never change the route): **aspect** derives from the destination — social feed (X / LinkedIn / Instagram) → square **1:1**, TikTok / Reels / Shorts → **9:16**, YouTube / embed / unknown → **16:9**; narration / caption **language** = the user's. The chosen workflow re-confirms its own specifics at its first step (field semantics: `hyperframes-core` → `references/brief-contract.md`).
 
 ## Workflow cheat-sheet
 
diff --git a/skills/motion-graphics/SKILL.md b/skills/motion-graphics/SKILL.md
index 402619d6d6..e272c29a9e 100644
--- a/skills/motion-graphics/SKILL.md
+++ b/skills/motion-graphics/SKILL.md
@@ -19,6 +19,8 @@ metadata:
 
 > **Confirm the route before Step 0.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). A **longer, multi-scene, or narrated** treatment → `/general-video`; a **narrated video of a website** → `/website-to-video`; a **topic explainer** → `/faceless-explainer`; a **product promo** → `/product-launch-video`; **captions on existing footage** → `/embedded-captions`. **Out of scope**: live / at-render-time data, or footage it can't capture. Unsure motion-first-vs-narrated? **Read `/hyperframes` first.**
 
+This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then straight through to render; the collaborative/autonomous distinction in `../hyperframes-core/references/brief-contract.md` adds no gates here.
+
 A short design-led motion graphic. **Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities. All artifacts go to `PROJECT_DIR = videos/<project-name>/` (created in Step 0); all paths below are relative to it.
 
 | Phase    | Execution                                                             | Primary artifact                                                 | Detailed flow                 |
diff --git a/skills/music-to-video/SKILL.md b/skills/music-to-video/SKILL.md
index 32a538825c..978b146bc9 100644
--- a/skills/music-to-video/SKILL.md
+++ b/skills/music-to-video/SKILL.md
@@ -7,7 +7,7 @@ description: "Turn a music track (an audio file, a video to pull audio from, or
 
 Use this skill to turn a **music track** into a beat-synced HyperFrames video. You analyze the track once, lay out the frames, fill in a per-frame plan, and build each frame as a composition. The input is a music track plus optional user images or videos — there is **no narration and no website capture**. Typography and templates are the floor (a complete video needs zero assets); any media the user supplies is cut in on the same beat grid.
 
-You are the **orchestrator**. Work in `videos/<project>/`. Run the steps in order and pass each **Gate** before moving on. Two steps need the user: **Step 3** (plan approval) and **Step 6** (render approval). Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**. Keep design and motion rules out of this file — they live in `references/` and the `frame-worker` sub-agent.
+You are the **orchestrator**. Work in `videos/<project>/`. Run the steps in order and pass each **Gate** before moving on. Two steps need the user: **Step 3** (plan approval) and **Step 6** (render approval) — both are checkpoint gates per `../hyperframes-core/references/brief-contract.md` (read it before Step 0): in autonomous mode, post the summary as a heads-up and proceed instead of waiting. Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**. Keep design and motion rules out of this file — they live in `references/` and the `frame-worker` sub-agent.
 
 `SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos/<project-name>/`.
 
@@ -89,9 +89,9 @@ node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD
   --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
 ```
 
-Fix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then show the user a frame-by-frame summary and iterate until they approve.
+Fix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then show the user a frame-by-frame summary and iterate until they approve. In autonomous mode this is a checkpoint gate: post the summary as a heads-up and proceed (the `validate-plan.mjs` pass is a quality gate and still blocks).
 
-**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan.
+**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan (autonomous: the summary was posted as a heads-up).
 
 ---
 
@@ -147,13 +147,13 @@ Run the CLI on the **assembled project** — that's the correct unit (the per-fr
 ( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
 ```
 
-Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval:
+Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval (autonomous mode: post a one-line heads-up — checks passed, render starting, `npx hyperframes preview` to look first — then render without waiting and deliver the MP4 with the contact sheet):
 
 ```bash
 ( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
 ```
 
-**Gate:** `lint` / `validate` / `inspect` passed; the user approved; `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.
+**Gate:** `lint` / `validate` / `inspect` passed; the user approved (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.
 
 ---
 
diff --git a/skills/pr-to-video/SKILL.md b/skills/pr-to-video/SKILL.md
index 38d25dcf79..8f72d908bf 100644
--- a/skills/pr-to-video/SKILL.md
+++ b/skills/pr-to-video/SKILL.md
@@ -11,7 +11,7 @@ Use this skill to ingest a GitHub pull request, understand the change, plan a co
 
 > **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for a **GitHub pull request** (a code change). Route other intents elsewhere: a product launch/promo → `/product-launch-video`; a general website tour → `/website-to-video`; a topic explainer with no PR → `/faceless-explainer`; captions on existing footage → `/embedded-captions`; a short unnarrated motion graphic → `/motion-graphics`; a whole-repo or multi-PR release walkthrough → `/general-video`. **Out of scope:** live / at-render-time data — PR facts are read once at author time and baked in. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the interaction mode (collaborative vs autonomous), the shared brief fields, and how to ask; the mode governs how the Step 0/3/6 gates behave. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup → `hyperframes.json`; Step 1 ingest → `capture/extracted/` + `assets/<login>.png`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.
 
@@ -21,7 +21,18 @@ Workflow: Step 0 setup → `hyperframes.json`; Step 1 ingest → `capture/extrac
 
 Goal: Lock the PR reference and the core video brief, and create the HyperFrames project if needed.
 
-Get the **PR reference** (a full URL, an `<owner>/<repo>#<N>` ref, or "this PR" in a checked-out repo) and, in one message, confirm the brief — lead with a recommended default for each and pre-fill anything `/hyperframes` already set: **angle** (changelog / feature-reveal / fix-explainer / refactor-walkthrough — default: infer from the PR), **audience** (default: developers), **length** (default: **scale to the PR's change size** — see below), **aspect** (default 16:9), **language**. The style is always **claude**. Proceed only after the user replies; a "go" accepts the defaults.
+Get the **PR reference** (a full URL, an `<owner>/<repo>#<N>` ref, or "this PR" in a checked-out repo) and, in one round, confirm the brief per the brief contract — every asked field gets its own question with a recommended default **plus its receipt**; pre-fill anything `/hyperframes` already set.
+
+**Ask** (each its own question, every run — never drop one as "inferable"):
+
+- **angle** — changelog / feature-reveal / fix-explainer / refactor-walkthrough; default: infer from the PR.
+- **audience** — default: developers.
+- **length** — default: **scale to the PR's change size** (see below).
+- **destination → aspect** — per the contract's derivation; a code explainer defaults to 16:9 unless a feed destination is named → then 1:1.
+
+**State in the intro text** (don't ask): **message** (the ONE thing the video must say about this change, echoed in one sentence), **language**, and the style (always **claude**).
+
+Proceed only after the user replies; a "go" accepts the defaults. In autonomous mode, state the locked brief as a heads-up and proceed.
 
 **Recommend the length from the PR's change size**, not a fixed guess. Before confirming the brief, peek at the PR once — a read-only call that also grounds the angle (Step 1 still does the full deterministic fetch):
 
@@ -38,7 +49,7 @@ Pick the tier from `additions + deletions` (nudged up by `changedFiles`) and lea
 | substantial (~200–600 lines)      | ~70–110s           |
 | large (≳ 600 lines, or 25+ files) | ~110–180s          |
 
-State the basis in one phrase when you propose it (e.g. "~40s — small change, +44/−13 across 12 files"). A huge PR doesn't mean a long video — if the story is one headline change, keep it tight and say so.
+State the basis in one phrase when you propose it (e.g. "~40s — small change, +44/−13 across 12 files"). A huge PR doesn't mean a long video — the tier is a **ceiling** on how much story the diff can support, never a floor to fill. When the story is **one headline change**, recommend inside the 30–90s sweet spot regardless of the size tier, and say so (the tier's range can still appear as a non-recommended option for a fuller walkthrough).
 
 Initialize only if `hyperframes.json` is missing. Name `<project>` from the PR in kebab-case, such as `acme-sdk-pr-1842`; never use the workspace name or a timestamp.
 
@@ -46,7 +57,7 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the PR i
 
 **Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
 
-**Gate:** `hyperframes.json` exists; the PR ref is captured; angle, length, aspect ratio, and language are locked; sign-in status was shown (signed in, or continuing offline).
+**Gate:** `hyperframes.json` exists; the PR ref is captured; angle, audience, length, destination → aspect, message, and language are locked; sign-in status was shown (signed in, or continuing offline).
 
 ---
 
@@ -103,9 +114,9 @@ Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md
 
 Use `story-design.md` for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the optional credits close. The sequence comes from **narrative design, not the diff's file order** — explain the change, don't read the diff aloud. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits (story truth still decides which beats exist — never force a beat to fit a shape). Feature 2–4 real diff hunks (from `capture/diff.patch`), each a small legible snippet; name the `code-*` block each wants in the frame's `scene`. Frames carry no `asset_candidates` except an optional `credits` close (2–6 `assets/<login>.png` avatars). Use the exact required fields from the storyboard and script references.
 
-After drafting, show a frame-by-frame summary. In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6.
+After drafting, show a frame-by-frame summary. In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed without waiting — skip the preview question and carry "not asked" to Step 6.
 
-**Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the plan.
+**Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the plan (autonomous: the summary was posted as a heads-up).
 
 ---
 
@@ -199,23 +210,23 @@ If a command fails, surface stderr and stop — don't pile on recovery commands.
 
 **Known false-positive — do not chase it.** `inspect` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
 
-After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, do not ask again if they are already reviewing in Studio.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, do not ask again if they are already reviewing in Studio. In autonomous mode the review pause is a checkpoint gate: post a one-line heads-up (checks passed, render starting — `npx hyperframes preview` if they want to look first), proceed to render without waiting, then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview`
 
-Render only after user approval:
+Render only after user approval (autonomous mode: after the checks pass):
 
 `npx hyperframes render --skill=pr-to-video --quality high --output renders/video.mp4`
 
 Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless the user asks.
 
-**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause; `renders/video.mp4` exists. Final reply states the MP4 path and final duration.
+**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists. Final reply states the MP4 path and final duration.
 
 ---
 
 ## Quick Reference
 
-**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the format once in the storyboard frontmatter.
+**Formats:** landscape `1920x1080`; portrait `1080x1920`; square `1080x1080` — derived from the destination (brief contract § 2). Set the format once in the storyboard frontmatter.
 
 **PR deltas vs a captured-asset workflow:** no Step 1 capture (the `gh` CLI ingests the PR into a synthetic `capture/extracted/` package — `tokens.json` + `visible-text.txt` + `people.json`); the only real assets are the contributors' `assets/<login>.png` avatars (an optional credits close); no `asset-descriptions.md`, no asset-staging step. Code beats are rendered by the `code-*` registry blocks on claude's navy Code Surface; the style is always **claude**.
 
@@ -225,6 +236,7 @@ The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blue
 
 | Read                                                                                                                                                        | When                                                           |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.    |
 | `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the PR explanation.                               |
 | `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.      |
 | `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                 |
diff --git a/skills/product-launch-video/SKILL.md b/skills/product-launch-video/SKILL.md
index f8bda08b7b..f35f98ecc1 100644
--- a/skills/product-launch-video/SKILL.md
+++ b/skills/product-launch-video/SKILL.md
@@ -11,7 +11,7 @@ Use this skill to capture a product, understand its brand, plan a launch video,
 
 > **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue to the next step. This skill is for a **product being marketed, launched, promoted, or revealed**, including requests such as "promo for our site" when the purpose is promotional. Route other intents elsewhere: a general non-launch website tour -> `/website-to-video`; a topic explainer with no product -> `/faceless-explainer`; a GitHub PR -> `/pr-to-video`; captions on existing footage -> `/embedded-captions`; a short unnarrated motion graphic -> `/motion-graphics`. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the interaction mode (collaborative vs autonomous), the shared brief fields, and how to ask; the mode governs how the Step 0/3/6 gates behave. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup -> `hyperframes.json`; Step 1 capture -> `capture/`; Step 2 design system -> `frame.md`; Step 3 storyboard/script -> `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio -> `audio_meta.json`; Step 4 visual design -> enriched `STORYBOARD.md`; Step 5 frames -> `compositions/frames/NN-*.html` and `index.html`; Step 6 final render -> `renders/video.mp4`.
 
@@ -27,7 +27,19 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the bran
 
 **Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
 
-**Gate:** `hyperframes.json` exists, and angle, length, aspect ratio, and language are locked; sign-in status was shown (signed in, or continuing offline).
+**Confirm the brief in one round** per the brief contract — every asked field gets its own question with a recommended default plus a one-line receipt; "go" accepts all.
+
+**Ask** (each its own question, every run — never drop one as "inferable"):
+
+- **angle** — the promo's story shape; default: infer from the site's / brief's own positioning (state the basis).
+- **length** — default inside the 30–90s sweet spot, scaled to how much material the input gives you (state the basis).
+- **destination → aspect** — per the contract's derivation (social feed → 1:1; Shorts / TikTok → 9:16; else 16:9).
+
+**State in the intro text** (don't ask): **message** (the ONE thing the promo must communicate, echoed back in one sentence), **language** (the user's). (`VO_MODE` is asked in Step 1 only when a script was pasted.)
+
+In autonomous mode, state the locked brief as a heads-up and proceed.
+
+**Gate:** `hyperframes.json` exists, and the brief fields (angle, length, destination → aspect, message, language) are locked; sign-in status was shown (signed in, or continuing offline).
 
 ---
 
@@ -73,9 +85,9 @@ Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md
 
 Use `story-design.md` for story blueprint, hook, persuasion logic, beats, `VO_MODE`, and asset choices. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, note a candidate blueprint id when one fits. Story truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Choose each visual frame's `asset_candidates` from `capture/extracted/asset-descriptions.md` (the canonical inventory) — don't browse raw `capture/assets/`. Do not ask the user to pick assets unless that inventory is missing or unusable. Use the exact required fields from the storyboard and script references.
 
-After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6.
+After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed without waiting — skip the preview question and carry "not asked" to Step 6.
 
-**Gate:** `STORYBOARD.md` exists, every visual frame has `asset_candidates`, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan.
+**Gate:** `STORYBOARD.md` exists, every visual frame has `asset_candidates`, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
 ---
 
@@ -169,23 +181,23 @@ Inject transitions, run checks, pause for review, then render.
 
 If a command fails, surface stderr and stop — don't pile on recovery commands. Fix it yourself: the cheapest safe edit to `compositions/frames/NN-*.html`, then rerun the failed check.
 
-After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode the review pause is a checkpoint gate: post a one-line heads-up (checks passed, render starting — `npx hyperframes preview` if they want to look first), proceed to render without waiting, then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview`
 
-Render only after user approval:
+Render only after user approval (autonomous mode: after the checks pass):
 
 `npx hyperframes render --skill=product-launch-video --quality high --output renders/video.mp4`
 
 Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless the user asks.
 
-**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause; `renders/video.mp4` exists. Final reply states MP4 path and final duration.
+**Gate:** `lint`, `validate`, and `inspect` passed before render; user approved at the review pause (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists. Final reply states MP4 path and final duration.
 
 ---
 
 ## Quick Reference
 
-**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the format once in the storyboard frontmatter.
+**Formats:** landscape `1920x1080`; portrait `1080x1920`; square `1080x1080` — derived from the destination (brief contract § 2). Set the format once in the storyboard frontmatter.
 
 **Background scripts:** the workflow ships only these scripts under `scripts/`: `build-frame` for adopting + brand-remixing a frame preset into `frame.md` (+ caption skin); `audio` for TTS, transcription, BGM, SFX, and duration syncing; `captions`; `transitions` for inject and verify; `stage-assets` for copying frame-named assets into `assets/`; and `assemble-index`. Everything else is handled by the `hyperframes` CLI.
 
@@ -193,6 +205,7 @@ The reusable, product-agnostic shot shapes live in `../hyperframes-animation/blu
 
 | Read                                                                                                                                                        | When                                                           |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.    |
 | `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                       |
 | `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                          |
 | `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the product-launch story.                         |
diff --git a/skills/slideshow/SKILL.md b/skills/slideshow/SKILL.md
index cc0f0bb171..68ef3de5d4 100644
--- a/skills/slideshow/SKILL.md
+++ b/skills/slideshow/SKILL.md
@@ -33,7 +33,7 @@ Then ask a short confirmation question:
 
 Use a yes/no choice UI when the environment provides one; otherwise ask the question in plain text.
 
-Do not implement the slideshow until the user says yes. If they say no, stop using this skill and switch to the appropriate non-slideshow workflow.
+Do not implement the slideshow until the user says yes. If they say no, stop using this skill and switch to the appropriate non-slideshow workflow. This confirmation is a **routing decision**, not a preference gate — per `../hyperframes-core/references/brief-contract.md` § 1 it survives autonomous mode ("surprise me" does not skip it): building the wrong deliverable type is a quality failure, not a creative call.
 
 ---
 
diff --git a/skills/talking-head-recut/SKILL.md b/skills/talking-head-recut/SKILL.md
index 01b82f5c67..30906184c8 100644
--- a/skills/talking-head-recut/SKILL.md
+++ b/skills/talking-head-recut/SKILL.md
@@ -293,7 +293,9 @@ Rules that apply to every channel:
   the parameters that materially affect the final output** (ratio,
   layout, style, cardCount).
 - If the user has already pre-approved defaults ("just use defaults",
-  "no need to ask", "auto-pick everything") or asked you not to ask — **skip
+  "no need to ask", "auto-pick everything"), asked you not to ask, or the
+  run carries an ongoing autonomous signal ("surprise me" / "decide for me" —
+  `../hyperframes-core/references/brief-contract.md` § 1) — **skip
   the question entirely** and use: `recommendedRatio`, `layout="stack"`
   (safest cross-ratio default), `style` chosen from transcript tone in
   the most neutral group (editorial/data), `autoCount`. Tell the user
diff --git a/skills/website-to-video/SKILL.md b/skills/website-to-video/SKILL.md
index d7231b13cd..1d8792aa36 100644
--- a/skills/website-to-video/SKILL.md
+++ b/skills/website-to-video/SKILL.md
@@ -17,9 +17,9 @@ Users say things like:
 - "Make a 30-second site tour / showcase from https://..."
 - "Capture our homepage and build a video from its own visuals"
 
-The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped; see step-2-brief.md for how that propagates.
+The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. Mode semantics (signals, propagation, gate taxonomy) are canonical in `../hyperframes-core/references/brief-contract.md`; when the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped — see step-2-brief.md for how that propagates through this workflow.
 
-**Autonomous mode is NOT "skip all gates."** Auto mode covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:
+**Autonomous mode is NOT "skip all gates"** (brief contract § 1). It covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:
 
 - Asset Audit (Step 3) — viewing contact sheets and justifying USE/SKIP for each asset
 - Per-beat HTML read (Step 5) — structured evidence block per beat

From b24fb617c85cc1f4103e4a438f5670bd59939837 Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Tue, 7 Jul 2026 22:14:49 +0800
Subject: [PATCH 2/6] feat(skills): story spine + mode-first brief across
 creation workflows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Story — the reverse-iceberg feedback:

- New hyperframes-creative/references/story-spine.md, three rules for
  the narrated workflows: the hook speaks the viewer's outcome
  language, the value claim lands by beat 2 (implementation is the
  footnote of the story, not the spine), and the storyboard is
  presented as a proposal — 'This video tells [audience] that
  [message]' plus a per-frame why: drawn from narrativeRole
- pr-to-video: feature-reveal reordered promise-first (impact leads,
  diff/mechanism follow as evidence); hooks ban file/function names;
  fix-explainer, refactor-walkthrough, changelog unchanged
- product-launch-video / faceless-explainer hook rules aligned to the
  spine; website-to-video's beat summary gains the echo line + why:;
  general-video points at the spine from its plan step

Brief — hardened after live-test drift:

- Mode is now the first question (Collaborative recommended vs
  Autonomous), its own round, skipped when the request carries a
  signal; autonomous asks nothing further until one final
  preview-or-render question before render
- Step 0 rewritten as a literal two-round question script in each
  shot-sequence workflow (website-to-video's editorial register,
  channel-agnostic); brief-contract.md §3 reduced to invariants so the
  procedure lives in exactly one place
---
 skills-manifest.json                          | 20 +++---
 skills/faceless-explainer/SKILL.md            | 62 ++++++++++--------
 .../references/story-design.md                |  2 +-
 skills/general-video/SKILL.md                 |  2 +-
 .../references/brief-contract.md              | 16 ++---
 skills/hyperframes-creative/SKILL.md          | 33 +++++-----
 .../references/story-spine.md                 | 30 +++++++++
 skills/hyperframes/SKILL.md                   |  2 +-
 skills/music-to-video/SKILL.md                |  2 +-
 skills/pr-to-video/SKILL.md                   | 64 ++++++++++---------
 skills/pr-to-video/references/story-design.md | 51 ++++++++-------
 skills/product-launch-video/SKILL.md          | 62 ++++++++++--------
 .../references/story-design.md                |  2 +-
 .../references/step-3-storyboard.md           | 10 +--
 14 files changed, 205 insertions(+), 153 deletions(-)
 create mode 100644 skills/hyperframes-creative/references/story-spine.md

diff --git a/skills-manifest.json b/skills-manifest.json
index 86a31dc1b6..f1fc3b7cab 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -6,7 +6,7 @@
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "82987c3d87648710",
+      "hash": "e3e985bb49f54b06",
       "files": 18
     },
     "figma": {
@@ -14,11 +14,11 @@
       "files": 1
     },
     "general-video": {
-      "hash": "c0beee735bee14ac",
+      "hash": "708f11b9e61a9efc",
       "files": 1
     },
     "hyperframes": {
-      "hash": "14e7ce906fab5923",
+      "hash": "779b42e75005d1e8",
       "files": 1
     },
     "hyperframes-animation": {
@@ -30,12 +30,12 @@
       "files": 7
     },
     "hyperframes-core": {
-      "hash": "cb4b275446b8de6b",
+      "hash": "c1a1f45d57d65019",
       "files": 14
     },
     "hyperframes-creative": {
-      "hash": "18a14a79da6cbc06",
-      "files": 68
+      "hash": "6767eb16fd7ef98a",
+      "files": 69
     },
     "hyperframes-keyframes": {
       "hash": "555c0cd491c40cea",
@@ -54,15 +54,15 @@
       "files": 23
     },
     "music-to-video": {
-      "hash": "920107da254d8fc1",
+      "hash": "889cc05c8aa968ec",
       "files": 132
     },
     "pr-to-video": {
-      "hash": "d7caab8e0aac7191",
+      "hash": "8b3eb48b8e594533",
       "files": 22
     },
     "product-launch-video": {
-      "hash": "38114c90d19cbab2",
+      "hash": "f6e05101f9245172",
       "files": 20
     },
     "remotion-to-hyperframes": {
@@ -78,7 +78,7 @@
       "files": 27
     },
     "website-to-video": {
-      "hash": "db7cfa04c6939cc9",
+      "hash": "72cef2ad592b65b9",
       "files": 32
     }
   }
diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md
index d818af0c47..d151364b94 100644
--- a/skills/faceless-explainer/SKILL.md
+++ b/skills/faceless-explainer/SKILL.md
@@ -11,7 +11,7 @@ Use this skill to turn a body of text into an explainer video: pick a design sys
 
 > **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for **explaining a topic from text, with no product and no website to capture**. Route other intents elsewhere: a product launch/promo → `/product-launch-video`; a tour of a real site → `/website-to-video`; a GitHub PR → `/pr-to-video`; captions on existing footage → `/embedded-captions`; a short unnarrated motion graphic → `/motion-graphics`. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the interaction mode (collaborative vs autonomous), the shared brief fields, and how to ask; the mode governs how the Step 0/3/6 gates behave. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the two modes, the gate types, and the brief fields; the mode governs the Step 0/3/6 gates. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup → `hyperframes.json`; Step 1 brief → `capture/extracted/`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.
 
@@ -27,17 +27,22 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the topi
 
 **Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
 
-**Confirm the brief in one round** per the brief contract — every asked field gets its own question with a recommended default plus a one-line receipt; "go" accepts all.
+**Confirm the brief** in two rounds — through the question UI when the environment has one, conversationally otherwise. The intro text states **message** (the explainer's thesis, in one sentence) and **language**. Skip a question only when the user's request already answered it. (`VO_MODE` is asked in Step 1 only when a script was pasted.)
 
-**Ask** (each its own question, every run — never drop one as "inferable"):
+**Round 1 — mode.** One question, asked first. Skip it when the request already carried a signal ("surprise me" / "just build it"):
 
-- **angle** — how the topic is taught (concept / how-to / listicle / narrative); default: infer from the text's own shape (state the basis).
-- **length** — default inside the 30–90s sweet spot, scaled to how much the text actually teaches (state the basis).
-- **destination → aspect** — per the contract's derivation (social feed → 1:1; Shorts / TikTok → 9:16; else 16:9).
+- **Collaborative (recommended)** — confirm the key choices together before building.
+- **Autonomous** — every decision is made for the user, each stated with its reason; the only remaining question is preview-before-render.
 
-**State in the intro text** (don't ask): **message** (the explainer's thesis, echoed back in one sentence), **language** (the user's). (`VO_MODE` is asked in Step 1 only when a script was pasted.)
+Autonomous → ask nothing more. State the locked brief (all fields + receipts) as a heads-up and proceed straight through; the preview question waits at Step 6.
 
-In autonomous mode, state the locked brief as a heads-up and proceed.
+**Round 2 — the brief (collaborative).** One round, these three questions, recommended option first with its receipt:
+
+- **Angle — how should the topic be taught?** concept / how-to / listicle / narrative; recommend the one the text's own shape suggests, with its basis.
+- **Length — how long?** Recommend inside the 30–90s sweet spot, scaled to how much the text actually teaches, with its basis.
+- **Destination — where will it play?** YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
+
+A "go" accepts all recommended defaults.
 
 **Gate:** `hyperframes.json` exists, and the brief fields (angle, length, destination → aspect, message, language) are locked; sign-in status was shown (signed in, or continuing offline).
 
@@ -82,11 +87,11 @@ A faceless explainer usually has **no brand colors/fonts** (`tokens.json` colors
 
 Goal: Turn the text into an approved frame-by-frame teaching plan.
 
-Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
+Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
 
 Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. Use the exact required fields from the storyboard and script references.
 
-After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed without waiting — skip the preview question and carry "not asked" to Step 6.
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then a frame-by-frame summary where every frame carries a one-line `why:` (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
@@ -180,11 +185,11 @@ If a command fails, surface stderr and stop — don't pile on recovery commands.
 
 **Known false-positive — do not chase it.** `inspect` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
 
-After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode the review pause is a checkpoint gate: post a one-line heads-up (checks passed, render starting — `npx hyperframes preview` if they want to look first), proceed to render without waiting, then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode this is the one question the mode keeps: ask "preview first, or render?" — open the preview on yes, render on no — then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview`
 
-Render only after user approval (autonomous mode: after the checks pass):
+Render only after user approval (autonomous mode: after the preview-or-render question):
 
 `npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4`
 
@@ -204,19 +209,20 @@ Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless
 
 The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blueprints/` (indexed by `../hyperframes-animation/blueprints-index.md`).
 
-| Read                                                                                                                                                        | When                                                           |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.    |
-| `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                       |
-| `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                          |
-| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the explainer story.                              |
-| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.      |
-| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                 |
-| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                     |
-| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers and voices.       |
-| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary). |
-| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.           |
-| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).  |
-| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.        |
-| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                            |
-| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                            |
+| Read                                                                                                                                                        | When                                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.                    |
+| `[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)`                                                    | Step 3: story doctrine — hook language, value-before-evidence, proposal shape. |
+| `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                                       |
+| `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                                          |
+| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the explainer story.                                              |
+| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.                      |
+| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                                 |
+| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                                     |
+| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers and voices.                       |
+| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary).                 |
+| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.                           |
+| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).                  |
+| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.                        |
+| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                                            |
+| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                                            |
diff --git a/skills/faceless-explainer/references/story-design.md b/skills/faceless-explainer/references/story-design.md
index b22a97e862..79c39f41ae 100644
--- a/skills/faceless-explainer/references/story-design.md
+++ b/skills/faceless-explainer/references/story-design.md
@@ -125,7 +125,7 @@ Pick one opening strategy for the first 3-5 seconds. For explainers the hook ope
 | Imagine / scenario     | A thought experiment frames the whole piece.       | "Imagine money that loses value if you don't spend it."          |
 | Stakes / consequence   | The "why care now" is a real cost or risk.         | "Get this one step wrong and the whole batch is ruined."         |
 
-The hook must create curiosity, tension, or stakes. Do not open with a generic definition.
+The hook must create curiosity, tension, or stakes. Do not open with a generic definition. Per `../hyperframes-creative/references/story-spine.md`: the hook speaks the viewer's language (the payoff of understanding, never the source text's section headings), and the thesis (`message`) lands by beat 2 — the explanation after that is its evidence.
 
 ## Clarity / rhetoric technique catalog
 
diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md
index 97917d6383..7c1df663ae 100644
--- a/skills/general-video/SKILL.md
+++ b/skills/general-video/SKILL.md
@@ -53,7 +53,7 @@ Run for every multi-scene composition (skip for single-scene pieces and trivial
 
 Before writing HTML, think at a high level:
 
-1. **What** — the viewer experience: narrative arc, key moments, emotional beats.
+1. **What** — the viewer experience: narrative arc, key moments, emotional beats. For a narrated story piece, follow `hyperframes-creative/references/story-spine.md` — hook in viewer-outcome language, the message landing by beat 2, evidence after.
 2. **Structure** — how many compositions, sub-comp vs inline, which tracks carry video / audio / overlays / captions. For the monolithic-single-file vs modular-sub-comp call, see `hyperframes-core/references/composition-patterns.md` § Two Architectures (rule of thumb: ≥3 hard scene cuts, or any reused scene → modularize; a short single-scene piece stays one file).
 3. **Rhythm** — name the pattern before implementing (e.g. `fast-fast-SLOW-SHADER-hold`); see `hyperframes-creative/references/beat-direction.md`.
 4. **Timing** — which clips drive duration, where transitions land, the pacing.
diff --git a/skills/hyperframes-core/references/brief-contract.md b/skills/hyperframes-core/references/brief-contract.md
index ec489db617..ca38df3794 100644
--- a/skills/hyperframes-core/references/brief-contract.md
+++ b/skills/hyperframes-core/references/brief-contract.md
@@ -10,13 +10,13 @@ There are two modes. Default: **collaborative**.
 
 - **Ongoing autonomous signals** — "autonomous", "surprise me", "decide for me", "just build it", "don't ask, just go", "LFG": the whole flow switches to autonomous from this point on.
 - **One-time acceptance** — a bare "go" / "looks good" at a gate accepts only that gate's defaults; the mode does not change.
-- The mode is set **once** — during routing (`/hyperframes`) or during the workflow brief — and **carries forward. No later step asks again.** Once a storyboard exists, record it in `STORYBOARD.md` frontmatter (`mode: autonomous`) so resumed sessions inherit it.
+- The mode is set **once** — by a signal in the request, or by the brief's first question (§ 3) — and **carries forward. No later step asks again.** Once a storyboard exists, record it in `STORYBOARD.md` frontmatter (`mode: autonomous`) so resumed sessions inherit it.
 - **Mid-run switch**: "stop asking / just finish it" → autonomous for the rest of the run. Clear feedback on a heads-up → collaborative resumes at the next gate.
 
 **Gate types.** Autonomous mode changes only the first two types:
 
 1. **Preference gates** (which preset, voice, caption identity, want a preview?) — autonomous: decide yourself and state the decision with a one-line reason. Never stay silent.
-2. **Checkpoint gates** (storyboard approval, pre-render review) — autonomous: post the same summary you would have asked about as an inline heads-up, then continue without waiting.
+2. **Checkpoint gates** (storyboard approval, pre-render review) — autonomous: post the same summary you would have asked about as an inline heads-up, then continue. One exception: before rendering, ask once — preview first, or render (§ 3).
 3. **Quality gates** (`lint` / `validate` / `inspect`, capture completeness, fetch failures, workflow-specific verification checklists) — never skip these in any mode. Errors still stop the run. Reasoning like "autonomous means bias toward action, so I'll skip verification" misuses the mode — bias toward action applies to deciding _what to build_, not _whether to verify_.
 4. **Routing and sign-in decisions** — wrong routing is a quality problem: an ambiguous-intent confirmation, such as `/slideshow`'s "is this a deck?", still happens in autonomous mode. Auth sign-in follows `/media-use` → Preflight: show the status as-is; collaborative waits for the user's choice, while autonomous notes it and continues offline.
 
@@ -40,9 +40,9 @@ The shared brief fields. Each workflow's SKILL.md declares which fields it uses,
 
 ## 3. Question rules
 
-- **Parse the prompt first.** Only ask for what the user has not already specified, and never ask them to confirm what they already said. Pre-fill anything `/hyperframes` or an earlier step has locked.
-- **One round, one question per asked field.** Bundle the brief into a single round: every field the workflow's binding marks **ask** gets its own question (native UI: one multi-question call — e.g. angle / length / destination as separate questions), leading with the recommended default plus its receipt; every **state** field goes in the intro text. The ask/state split is fixed by the binding table — **never drop a question because its answer looks inferable**; confidence sharpens the recommended default, it doesn't remove the question. "go" accepts all defaults.
-- **Advertise the mode, don't ask it.** Every brief carries a one-line legend: `"go" accepts all defaults · "surprise me" / "just build it" hands me every later decision (autonomous — no more questions, each call comes with its reason)`. In plain text, end the brief message with it; with a native question UI (`AskUserQuestion` or equivalent), put it in the short intro text you send **before** the question call — the UI has no message tail. The mode never gets its own question or option; the legend text is the only place it appears.
-- **Receipts.** A recommendation without a reason is a guess — every default states where it came from, for example: "~40s — small change, +44/−13 across 12 files".
-- **Channel.** When the environment has a native question UI (`AskUserQuestion` or equivalent), using it for the **ask** fields is **mandatory** in collaborative mode — one multi-question call, each question offering 2–4 options with the recommended one first. A plain-text "here's the brief, reply 'go'" statement is NOT a substitute; that shape is reserved for autonomous mode's heads-up. Only in an environment with no native UI, ask in plain text as one numbered list. Use 2–5 questions max per round.
-- **Autonomous brief.** Don't ask at all — state the locked brief, including all fields and receipts, as a heads-up and proceed.
+The executable question script lives in each workflow's Step 0 as a literal two-round template. This section defines only the invariants that script satisfies:
+
+- **Round 1 asks the mode** — one question, skipped when the request already carried a signal. Autonomous → no further questions: state the locked brief (all fields + receipts) as a heads-up and build straight through; the one remaining question, before render, is "preview first, or render?". Collaborative → Round 2.
+- **Round 2 asks the workflow's ask-marked fields** — one question per field, recommended option first, each with its receipt. Skip a question only when the user already answered that field in their request; inference is not an answer.
+- **Receipts.** Every recommended option states its basis: "~40s — small change, +44/−13 across 12 files".
+- **Channel.** Native question UI when the environment has one; otherwise plain text as one numbered list. "go" accepts all defaults.
diff --git a/skills/hyperframes-creative/SKILL.md b/skills/hyperframes-creative/SKILL.md
index e76ff5e78d..62ebfd5abc 100644
--- a/skills/hyperframes-creative/SKILL.md
+++ b/skills/hyperframes-creative/SKILL.md
@@ -29,22 +29,23 @@ For motion patterns, scene blueprints, transitions, and CSS marker effects, use
 
 ## Routing
 
-| Topic                                                                    | Read                                           |
-| ------------------------------------------------------------------------ | ---------------------------------------------- |
-| Adopt a ready-made frame-preset as `frame.md` (optional)                 | `frame-presets/` · `references/design-spec.md` |
-| Default palettes, motion, typography, lazy defaults to question          | `references/house-style.md`                    |
-| Named style presets, mood-to-style routing                               | `references/visual-styles.md`                  |
-| Palette-specific color tokens                                            | `palettes/*.md`                                |
-| Composition patterns — PiP, text-behind-subject, title card, slide show  | `references/composition-patterns.md`           |
-| Stats / infographic presentation                                         | `references/data-in-motion.md`                 |
-| Structured expansion for open-ended prompts                              | `references/prompt-expansion.md`               |
-| Video-medium density, scale, color, frame composition                    | `references/video-composition.md`              |
-| Per-beat direction, rhythm planning, transition timing                   | `references/beat-direction.md`                 |
-| Post-authoring spec verification (colors, type, corners, spacing, depth) | `references/design-adherence.md`               |
-| High-level motion guardrails and GSAP-quality rules                      | `references/motion-principles.md`              |
-| Font selection, pairings, rendered-video type guardrails                 | `references/typography.md`                     |
-| Script pacing, tone, openings, number pronunciation                      | `references/narration.md`                      |
-| Precomputed audio bands mapped to motion                                 | `references/audio-reactive.md`                 |
+| Topic                                                                         | Read                                           |
+| ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| Adopt a ready-made frame-preset as `frame.md` (optional)                      | `frame-presets/` · `references/design-spec.md` |
+| Default palettes, motion, typography, lazy defaults to question               | `references/house-style.md`                    |
+| Named style presets, mood-to-style routing                                    | `references/visual-styles.md`                  |
+| Palette-specific color tokens                                                 | `palettes/*.md`                                |
+| Composition patterns — PiP, text-behind-subject, title card, slide show       | `references/composition-patterns.md`           |
+| Stats / infographic presentation                                              | `references/data-in-motion.md`                 |
+| Structured expansion for open-ended prompts                                   | `references/prompt-expansion.md`               |
+| Video-medium density, scale, color, frame composition                         | `references/video-composition.md`              |
+| Per-beat direction, rhythm planning, transition timing                        | `references/beat-direction.md`                 |
+| Post-authoring spec verification (colors, type, corners, spacing, depth)      | `references/design-adherence.md`               |
+| High-level motion guardrails and GSAP-quality rules                           | `references/motion-principles.md`              |
+| Font selection, pairings, rendered-video type guardrails                      | `references/typography.md`                     |
+| Story doctrine — hook language, value-before-evidence, storyboard-as-proposal | `references/story-spine.md`                    |
+| Script pacing, tone, openings, number pronunciation                           | `references/narration.md`                      |
+| Precomputed audio bands mapped to motion                                      | `references/audio-reactive.md`                 |
 
 ## Scripts
 
diff --git a/skills/hyperframes-creative/references/story-spine.md b/skills/hyperframes-creative/references/story-spine.md
new file mode 100644
index 0000000000..1b219b067a
--- /dev/null
+++ b/skills/hyperframes-creative/references/story-spine.md
@@ -0,0 +1,30 @@
+# Story spine — value-first narrative doctrine
+
+Applies to the narrated, story-driven creation workflows — `/product-launch-video`, `/pr-to-video`, `/faceless-explainer`, `/website-to-video`, and `/general-video` when the piece tells a story. It does **not** apply to `/music-to-video` (the track drives the arc), `/motion-graphics` (no narration — motion is the message), `/embedded-captions` and `/talking-head-recut` (the footage's story is already fixed), or `/slideshow` (the presenter owns the story). Do not force these rules onto an exempt workflow.
+
+Each workflow's own story-design reference owns its archetypes, beat sequences, and frame vocabulary. This file owns three cross-workflow rules about **order** and **justification** — the reverse iceberg: lead with why it's valuable, not with what it is or how it was made.
+
+## 1. The hook speaks the viewer's language
+
+The first beat answers "why should I care" in **outcome language** — what the viewer gains, avoids, or finally understands. Subject-internal vocabulary is banned in the hook: file / function / API names for a code change; a feature list for a product; the source article's section headings for an explainer. Numbers are welcome only when they carry stakes ("40% faster cold starts"), never inventory ("23 files changed").
+
+## 2. Reverse iceberg — value before evidence
+
+The value claim (the brief's `message`) lands **by the second beat**. Everything after it is evidence in service of that claim — the diff, the mechanism, the feature demo, the site's screenshots. Implementation is the footnote of the story, not the spine.
+
+Self-check on the finished beat list:
+
+- Delete every evidence beat — the remaining beats must still state the value on their own.
+- Delete the value beats — if the video still seems to work, it was a feature tour / diff readout, not a story.
+
+Structure is value-first; the **voice** stays whatever the workflow prescribes (a PR video keeps its plain, no-hype developer voice — leading with value is an ordering decision, not a marketing register).
+
+## 3. The storyboard is a proposal, not a listing
+
+When Step 3 presents the plan (a checkpoint gate — `hyperframes-core/references/brief-contract.md` § 1):
+
+- Open by echoing the strategy line: **"This video tells [audience] that [message]."**
+- Every frame line carries a one-line `why:` — the frame's job in the story (from its `narrativeRole`), traced back to the message. A frame whose `why` cannot be traced to the message is a frame to cut, not to decorate.
+- Recommendations keep their receipts (brief-contract § 3): the archetype choice, the beat count, and any beat the user might question each state their basis.
+
+The proposal shape — echo line → per-frame lines with `why:` → style / duration footer → "approve or adjust" — is the cheapest place to iterate: a beat change here costs 30 seconds; the same change after build costs minutes.
diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md
index 7cd05cfb87..43dfe6015c 100644
--- a/skills/hyperframes/SKILL.md
+++ b/skills/hyperframes/SKILL.md
@@ -48,7 +48,7 @@ Routing needs to know **what the video is about** — its input and subject. If
 
 - **Input** — a product (URL / brief), a general website, a GitHub PR, a topic to explain, or an existing talking-head video?
 
-**Mode** — if the request carries an ongoing autonomous signal ("surprise me", "decide for me", "just build it"), note it and pass it into the workflow: the whole run goes autonomous and no later step re-asks. Default is collaborative. (`/motion-graphics` is autonomous by design.) Semantics: `hyperframes-core` → `references/brief-contract.md`.
+**Mode** — if the request carries an ongoing autonomous signal ("surprise me", "decide for me", "just build it"), note it and pass it into the workflow: the whole run goes autonomous and no later step re-asks. With no signal, the workflow asks the mode as its first brief question. Default is collaborative. (`/motion-graphics` is autonomous by design.) Semantics: `hyperframes-core` → `references/brief-contract.md`.
 
 **Spec defaults — state, don't ask** (they never change the route): **aspect** derives from the destination — social feed (X / LinkedIn / Instagram) → square **1:1**, TikTok / Reels / Shorts → **9:16**, YouTube / embed / unknown → **16:9**; narration / caption **language** = the user's. The chosen workflow re-confirms its own specifics at its first step (field semantics: `hyperframes-core` → `references/brief-contract.md`).
 
diff --git a/skills/music-to-video/SKILL.md b/skills/music-to-video/SKILL.md
index 978b146bc9..70b7868e63 100644
--- a/skills/music-to-video/SKILL.md
+++ b/skills/music-to-video/SKILL.md
@@ -147,7 +147,7 @@ Run the CLI on the **assembled project** — that's the correct unit (the per-fr
 ( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
 ```
 
-Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval (autonomous mode: post a one-line heads-up — checks passed, render starting, `npx hyperframes preview` to look first — then render without waiting and deliver the MP4 with the contact sheet):
+Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval (autonomous mode: ask the one kept question — "preview first, or render?" — then deliver the MP4 with the contact sheet):
 
 ```bash
 ( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
diff --git a/skills/pr-to-video/SKILL.md b/skills/pr-to-video/SKILL.md
index 8f72d908bf..c892f092ea 100644
--- a/skills/pr-to-video/SKILL.md
+++ b/skills/pr-to-video/SKILL.md
@@ -11,7 +11,7 @@ Use this skill to ingest a GitHub pull request, understand the change, plan a co
 
 > **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for a **GitHub pull request** (a code change). Route other intents elsewhere: a product launch/promo → `/product-launch-video`; a general website tour → `/website-to-video`; a topic explainer with no PR → `/faceless-explainer`; captions on existing footage → `/embedded-captions`; a short unnarrated motion graphic → `/motion-graphics`; a whole-repo or multi-PR release walkthrough → `/general-video`. **Out of scope:** live / at-render-time data — PR facts are read once at author time and baked in. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the interaction mode (collaborative vs autonomous), the shared brief fields, and how to ask; the mode governs how the Step 0/3/6 gates behave. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the two modes, the gate types, and the brief fields; the mode governs the Step 0/3/6 gates. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup → `hyperframes.json`; Step 1 ingest → `capture/extracted/` + `assets/<login>.png`; Step 2 design system → `frame.md`; Step 3 storyboard/script → `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio → `audio_meta.json`; Step 4 visual design → enriched `STORYBOARD.md`; Step 5 frames → `compositions/frames/NN-*.html` and `index.html`; Step 6 final render → `renders/video.mp4`.
 
@@ -21,18 +21,23 @@ Workflow: Step 0 setup → `hyperframes.json`; Step 1 ingest → `capture/extrac
 
 Goal: Lock the PR reference and the core video brief, and create the HyperFrames project if needed.
 
-Get the **PR reference** (a full URL, an `<owner>/<repo>#<N>` ref, or "this PR" in a checked-out repo) and, in one round, confirm the brief per the brief contract — every asked field gets its own question with a recommended default **plus its receipt**; pre-fill anything `/hyperframes` already set.
+Get the **PR reference** (a full URL, an `<owner>/<repo>#<N>` ref, or "this PR" in a checked-out repo), then confirm the brief in two rounds — through the question UI when the environment has one, conversationally otherwise. The intro text states **message** (the ONE thing the video must say about this change, in one sentence), **language**, and the style (always **claude**). Skip a question only when the user's request already answered it.
 
-**Ask** (each its own question, every run — never drop one as "inferable"):
+**Round 1 — mode.** One question, asked first. Skip it when the request already carried a signal ("surprise me" / "just build it"):
 
-- **angle** — changelog / feature-reveal / fix-explainer / refactor-walkthrough; default: infer from the PR.
-- **audience** — default: developers.
-- **length** — default: **scale to the PR's change size** (see below).
-- **destination → aspect** — per the contract's derivation; a code explainer defaults to 16:9 unless a feed destination is named → then 1:1.
+- **Collaborative (recommended)** — confirm the key choices together before building.
+- **Autonomous** — every decision is made for the user, each stated with its reason; the only remaining question is preview-before-render.
 
-**State in the intro text** (don't ask): **message** (the ONE thing the video must say about this change, echoed in one sentence), **language**, and the style (always **claude**).
+Autonomous → ask nothing more. State the locked brief (all fields + receipts) as a heads-up and proceed straight through; the preview question waits at Step 6.
 
-Proceed only after the user replies; a "go" accepts the defaults. In autonomous mode, state the locked brief as a heads-up and proceed.
+**Round 2 — the brief (collaborative).** One round, these four questions, recommended option first with its receipt:
+
+- **Angle — what story does this PR tell?** changelog / feature-reveal / fix-explainer / refactor-walkthrough; recommend the one the PR itself suggests, with its basis.
+- **Audience — who is it for?** developers (default) · mixed technical · non-technical stakeholders.
+- **Length — how long?** From the size table below; the tier is a ceiling, and a one-headline story recommends inside 30–90s ("+A/−D across F files" is the receipt).
+- **Destination — where will it play?** YouTube / embed → 16:9 (default for a code explainer) · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
+
+A "go" accepts all recommended defaults.
 
 **Recommend the length from the PR's change size**, not a fixed guess. Before confirming the brief, peek at the PR once — a read-only call that also grounds the angle (Step 1 still does the full deterministic fetch):
 
@@ -110,11 +115,11 @@ The script copies the claude preset's `FRAME.md` → `frame.md`, remixes it onto
 
 Goal: Turn the PR into an approved frame-by-frame explanation plan.
 
-Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
+Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
 
 Use `story-design.md` for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the optional credits close. The sequence comes from **narrative design, not the diff's file order** — explain the change, don't read the diff aloud. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits (story truth still decides which beats exist — never force a beat to fit a shape). Feature 2–4 real diff hunks (from `capture/diff.patch`), each a small legible snippet; name the `code-*` block each wants in the frame's `scene`. Frames carry no `asset_candidates` except an optional `credits` close (2–6 `assets/<login>.png` avatars). Use the exact required fields from the storyboard and script references.
 
-After drafting, show a frame-by-frame summary. In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed without waiting — skip the preview question and carry "not asked" to Step 6.
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then a frame-by-frame summary where every frame carries a one-line `why:` (its `narrativeRole`, traced to the message). In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the plan (autonomous: the summary was posted as a heads-up).
 
@@ -210,11 +215,11 @@ If a command fails, surface stderr and stop — don't pile on recovery commands.
 
 **Known false-positive — do not chase it.** `inspect` may report a handful of `text_box_overflow` errors of ~1–4px on the **caption** highlight words (selector `#caption-word-*` / `.caption-line`). The caption pill uses a deliberately snug `line-height` (set once in `scripts/captions.mjs`) and has **no `overflow:hidden`**, so a heavy display glyph's ink spills a few px into the pill's own padding — nothing is actually clipped. Treat these as expected and proceed. Do **not** inflate the caption `line-height` (it balloons the pill, which is worse). Only act on a `text_box_overflow` when it names a **frame** element (`#el-NN-*`), not a caption word.
 
-After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, do not ask again if they are already reviewing in Studio. In autonomous mode the review pause is a checkpoint gate: post a one-line heads-up (checks passed, render starting — `npx hyperframes preview` if they want to look first), proceed to render without waiting, then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, do not ask again if they are already reviewing in Studio. In autonomous mode this is the one question the mode keeps: ask "preview first, or render?" — open the preview on yes, render on no — then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview`
 
-Render only after user approval (autonomous mode: after the checks pass):
+Render only after user approval (autonomous mode: after the preview-or-render question):
 
 `npx hyperframes render --skill=pr-to-video --quality high --output renders/video.mp4`
 
@@ -234,19 +239,20 @@ Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless
 
 The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blueprints/` (indexed by `../hyperframes-animation/blueprints-index.md`); the `code-*` registry blocks are the code-beat vocabulary (`references/code-vocabulary.md`).
 
-| Read                                                                                                                                                        | When                                                           |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.    |
-| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the PR explanation.                               |
-| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.      |
-| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                 |
-| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                     |
-| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers.                  |
-| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary). |
-| `[references/code-vocabulary.md](references/code-vocabulary.md)`                                                                                            | Step 4 + 5: pick + fill the `code-*` block for a code beat.    |
-| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.           |
-| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).  |
-| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.        |
-| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                            |
-| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                            |
-| `[../hyperframes-creative/frame-presets/claude/FRAME.md](../hyperframes-creative/frame-presets/claude/FRAME.md)`                                            | Step 2: the claude preset (fixed style).                       |
+| Read                                                                                                                                                        | When                                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.                    |
+| `[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)`                                                    | Step 3: story doctrine — hook language, value-before-evidence, proposal shape. |
+| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the PR explanation.                                               |
+| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.                      |
+| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                                 |
+| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                                     |
+| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers.                                  |
+| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary).                 |
+| `[references/code-vocabulary.md](references/code-vocabulary.md)`                                                                                            | Step 4 + 5: pick + fill the `code-*` block for a code beat.                    |
+| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.                           |
+| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).                  |
+| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.                        |
+| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                                            |
+| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                                            |
+| `[../hyperframes-creative/frame-presets/claude/FRAME.md](../hyperframes-creative/frame-presets/claude/FRAME.md)`                                            | Step 2: the claude preset (fixed style).                                       |
diff --git a/skills/pr-to-video/references/story-design.md b/skills/pr-to-video/references/story-design.md
index 4704b1714f..0293935cf7 100644
--- a/skills/pr-to-video/references/story-design.md
+++ b/skills/pr-to-video/references/story-design.md
@@ -25,6 +25,8 @@ A diff is a list of edits. A video is a guided act of understanding.
 
 Do **not** narrate the diff file-by-file or read the PR description aloud — that is the single most common failure. **Explain the change** — and where the change has a runtime behavior, **show that behavior in motion** (a `mechanism` beat — see "Show the behavior" below), don't just display the lines that changed. Reorder, merge, omit, compress: surface the one change that matters and drop the incidental churn (lockfile bumps, formatting, generated files) unless it _is_ the story. Scene order comes from narrative design, not from the diff's file order or the commit list.
 
+**Value before evidence** (`../hyperframes-creative/references/story-spine.md`): the viewer-facing payoff — what the change unlocks, fixes, or speeds up — lands by the second beat; the diff and the mechanism are the **evidence** for that claim, never the opening. Implementation is the footnote of the story, not the spine.
+
 Default to a **plain, technical, unhurried developer voice** — accurate, specific, no hype, no marketing gloss. You are explaining a real change to engineers; respect their time and intelligence. `frame.md` (claude) tunes the voice toward considered and literary; it does not change the structure.
 
 ## PR archetypes
@@ -32,7 +34,7 @@ Default to a **plain, technical, unhurried developer voice** — accurate, speci
 Choose **one** archetype (or name a compound). Each is a complete path through understanding a change — do not splice phases from different archetypes.
 
 - **Changelog** — "here's what shipped." Hook naming the headline → **2–4 roughly co-equal change items** → ship/wrap. Best for release PRs, multi-change PRs, "what's new in vN." Items are parallel → `cut` / `push-slide` between them. Rule-of-three is strongest when changes compress. An item with a visible behavior can be a `mechanism` mini-demo instead of a bare `diff`.
-- **Feature-reveal** — "we built X; here's what it does." Hook (the new capability) → name it (`change`) → the new code typing on (`diff`) → **animate what it does (`mechanism`)** → why it matters (`impact`) → close. Best for a PR that adds **one notable feature**. The new code is the protagonist, but the `mechanism` beat is where the viewer _sees_ the feature work — not just reads its diff.
+- **Feature-reveal** — "here's what you can do now." Hook (the outcome the feature unlocks, in user language) → the payoff made concrete (`impact` — what now works) → name it (`change`) → the new code typing on (`diff`) → **animate what it does (`mechanism`)** → close (a callback to the promise). Best for a PR that adds **one notable feature**. The promise leads and the code proves it: `diff` and `mechanism` are the evidence for the opening claim — the viewer should already care before the first line of code appears.
 - **Fix-explainer** — "this was broken; here's the fix." Symptom/bug (`problem`) → **animate the broken behavior (`mechanism`)** → the fix as a before→after (`diff`) → **the behavior now working (`mechanism`)** or the result (`impact`). Best for bugfix PRs. Seeing the bug _happen_ and then _not_ happen is the turn — a stronger shape (tension → turn → relief) than the diff alone.
 - **Refactor-walkthrough** — "same behavior, better shape." Hook (the smell / the why) → old shape vs new shape (`before_after`) → **the structure untangling, same inputs → same outputs (`mechanism`)** → payoff (`evidence` — lines removed, perf delta, files touched). Best for refactors, perf, cleanups, migrations. A `mechanism` animation _proves_ "same behavior, better shape" far better than asserting it.
 
@@ -42,18 +44,18 @@ Choose **one** archetype (or name a compound). Each is a complete path through u
 
 Set each frame's `type` to one of these PR-native values. (The storyboard parser keeps `type` verbatim; it is a narrative + pacing label, not a hard enum.) Each maps to a claude frame treatment and a typical visual — so the type, the design, and the visual stay aligned end to end. Note `mechanism` is the **show-the-behavior** beat (an invented animated diagram), distinct from `diff` (show the code).
 
-| `type`         | The frame's job                                                                                                        | claude treatment (frame.md)                                        | typical visual (see code-vocabulary.md)                                                 |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `hook`         | The high-leverage opening 3–5s                                                                                         | Cover                                                              | — (or `code-3d-extrude` for a hero code moment)                                         |
-| `problem`      | The bug / smell / pain / why-care the PR resolves                                                                      | Statement or Pull-quote                                            | `code-highlight` (spotlight the offending line)                                         |
-| `change`       | Name the change / the feature / the PR itself                                                                          | Statement or Cover                                                 | —                                                                                       |
-| `diff`         | The change body — a before→after, a hunk, new code typed on                                                            | **Code Surface** (navy)                                            | `code-diff` / `code-morph` / `code-typing`                                              |
-| `before_after` | Explicit old-shape vs new-shape comparison (refactor/fix)                                                              | Code Surface (split / morph)                                       | `code-morph` / `code-diff`                                                              |
-| `mechanism`    | **Show what the change DOES at runtime** — the request retrying, the cache filling, serial→parallel, the race resolved | invented diagram on cream (hairline ink + one coral active marker) | **invented SVG/GSAP**; `flowchart` / `flowchart-vertical` / `data-chart` where they fit |
-| `impact`       | The payoff — what now works, what's now possible                                                                       | Number / Impact                                                    | `number-lockup` (no code block needed)                                                  |
-| `evidence`     | Concrete grounding — `+N/−M`, a passing test, a benchmark                                                              | Number / Impact                                                    | `code-diff` red→green / `number-lockup`                                                 |
-| `credits`      | Shipped-by close — the humans behind the change                                                                        | Closing                                                            | — (avatar row from `assets/<login>.png`)                                                |
-| `cta`          | The closing ask — pull it, upgrade, read the PR                                                                        | Closing                                                            | — (coral-callout)                                                                       |
+| `type`         | The frame's job                                                                                                             | claude treatment (frame.md)                                        | typical visual (see code-vocabulary.md)                                                 |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `hook`         | The high-leverage opening 3–5s                                                                                              | Cover                                                              | — (or `code-3d-extrude` for a hero code moment)                                         |
+| `problem`      | The bug / smell / pain / why-care the PR resolves                                                                           | Statement or Pull-quote                                            | `code-highlight` (spotlight the offending line)                                         |
+| `change`       | Name the change / the feature / the PR itself                                                                               | Statement or Cover                                                 | —                                                                                       |
+| `diff`         | The change body — a before→after, a hunk, new code typed on                                                                 | **Code Surface** (navy)                                            | `code-diff` / `code-morph` / `code-typing`                                              |
+| `before_after` | Explicit old-shape vs new-shape comparison (refactor/fix)                                                                   | Code Surface (split / morph)                                       | `code-morph` / `code-diff`                                                              |
+| `mechanism`    | **Show what the change DOES at runtime** — the request retrying, the cache filling, serial→parallel, the race resolved      | invented diagram on cream (hairline ink + one coral active marker) | **invented SVG/GSAP**; `flowchart` / `flowchart-vertical` / `data-chart` where they fit |
+| `impact`       | The payoff — what now works, what's now possible; opens the video as the promise (feature-reveal) or lands it as the result | Number / Impact                                                    | `number-lockup` (no code block needed)                                                  |
+| `evidence`     | Concrete grounding — `+N/−M`, a passing test, a benchmark                                                                   | Number / Impact                                                    | `code-diff` red→green / `number-lockup`                                                 |
+| `credits`      | Shipped-by close — the humans behind the change                                                                             | Closing                                                            | — (avatar row from `assets/<login>.png`)                                                |
+| `cta`          | The closing ask — pull it, upgrade, read the PR                                                                             | Closing                                                            | — (coral-callout)                                                                       |
 
 The body of a PR video **alternates `diff` (show the code that changed) with `mechanism` (show what it does at runtime)**, landing on `impact` / `evidence` (the result). A body that is all `diff` reads as code show-and-tell — the `mechanism` beat is what makes the change _legible_ and is the usual cure for a video that feels flat. Every PR has a change, so at least one `diff` (or `change`) frame always exists; most PRs also have a behavior worth animating.
 
@@ -61,17 +63,17 @@ The body of a PR video **alternates `diff` (show the code that changed) with `me
 
 The hook is the highest-leverage 3–5 seconds. Pick one:
 
-| Strategy               | When                                | Example                                                    |
-| ---------------------- | ----------------------------------- | ---------------------------------------------------------- |
-| Shocking statistic     | The change quantifies the stakes    | "This PR deletes 1,200 lines." / "40% faster cold starts." |
-| Counterintuitive claim | The change contradicts intuition    | "We made the client slower — and that fixed it."           |
-| Pain validation        | The audience already feels the bug  | "Every deploy, the same flaky timeout."                    |
-| Concept announcement   | The change has a name worth landing | "Meet retry-with-backoff."                                 |
-| Before/after teaser    | The diff is the whole story         | "One line threw. Now it recovers."                         |
-| Stakes / consequence   | The "why care now" is a real cost   | "This crash hit every user on a flaky network."            |
-| Direct address         | The audience is clearly defined     | "If you've ever waited on a 5-minute CI run…"              |
+| Strategy               | When                                | Example                                                                |
+| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| Shocking statistic     | The change quantifies the stakes    | "This PR deletes 1,200 lines." / "40% faster cold starts."             |
+| Counterintuitive claim | The change contradicts intuition    | "We made the client slower — and that fixed it."                       |
+| Pain validation        | The audience already feels the bug  | "Every deploy, the same flaky timeout."                                |
+| Concept announcement   | The change has a name worth landing | "Meet retry-with-backoff — flaky networks stop killing your requests." |
+| Before/after teaser    | The diff is the whole story         | "One line threw. Now it recovers."                                     |
+| Stakes / consequence   | The "why care now" is a real cost   | "This crash hit every user on a flaky network."                        |
+| Direct address         | The audience is clearly defined     | "If you've ever waited on a 5-minute CI run…"                          |
 
-Do not open with a generic repo/company description.
+Do not open with a generic repo/company description. Whatever the strategy, the hook speaks the **viewer's outcome language** (story-spine rule 1) — never file / function / identifier names; numbers only when they carry stakes ("40% faster"), not inventory ("23 files changed").
 
 ## Clarity / rhetoric technique catalog
 
@@ -100,7 +102,7 @@ Compound beats are often strongest: "Recognition _and_ relief" (a fix), "Curiosi
 A PR video's core is **2–5 body frames**, each advancing one change / one before→after / one item, building cumulatively. **Alternate `diff` (the code) with `mechanism` (the behavior)** — don't stack code surfaces:
 
 - **changelog:** a `diff` (or a `mechanism` mini-demo) per change item; parallel → default `cut` / `push-slide`.
-- **feature-reveal:** `change` (name it) → `diff` (the code, often typing/morphing on) → `mechanism` (animate it working) → `impact`.
+- **feature-reveal:** `impact` (the promise, concrete) → `change` (name it) → `diff` (the code, often typing/morphing on) → `mechanism` (animate it working) → a closing callback to the promise.
 - **fix-explainer:** `problem` (symptom) → `mechanism` (the bug happening) → `diff` (cause + fix, before→after) → `impact` (result, or a `mechanism` of it working).
 - **refactor-walkthrough:** `before_after` structure → `mechanism` (the structure untangling, behavior preserved) → an `evidence` numbers beat.
 
@@ -200,6 +202,7 @@ The `credits` frame additionally carries an `asset_candidates:` line (see the cr
 
 - One archetype is named (compound only when explicit); the sequence is narrative-driven, not diff-order-driven.
 - The opening uses a named hook strategy; you do not read the PR description aloud.
+- The hook is in viewer-outcome language (no file / function / identifier names), and the video's `message` lands by beat 2 (story-spine).
 - Each frame has one job; the body builds cumulatively, **alternating `diff` (the code) with `mechanism` (the behavior)** + `impact` / `evidence` — not a single isolated body frame, and not an unbroken stack of code surfaces.
 - Every frame has `type` (PR-native), `persuasion` (a named technique), and `beat` (specific). The emotional arc matches the archetype (fix = frustration → relief; feature = curiosity → confidence).
 - Each `voiceover` is phrase-segmented into cues (each a piece Step 5 can reveal on), not one run-on clause; a candidate `blueprint:` is tagged from the role→blueprint menu where a proven shape fits (a code beat usually omits it — the `code-*` block is the shape).
diff --git a/skills/product-launch-video/SKILL.md b/skills/product-launch-video/SKILL.md
index f35f98ecc1..748e3bf442 100644
--- a/skills/product-launch-video/SKILL.md
+++ b/skills/product-launch-video/SKILL.md
@@ -11,7 +11,7 @@ Use this skill to capture a product, understand its brand, plan a launch video,
 
 > **Confirm the route before Step 0.** You are the orchestrator. Run each step, verify its gate, and only then continue to the next step. This skill is for a **product being marketed, launched, promoted, or revealed**, including requests such as "promo for our site" when the purpose is promotional. Route other intents elsewhere: a general non-launch website tour -> `/website-to-video`; a topic explainer with no product -> `/faceless-explainer`; a GitHub PR -> `/pr-to-video`; captions on existing footage -> `/embedded-captions`; a short unnarrated motion graphic -> `/motion-graphics`. If the user says only "make a video" or the route is uncertain, read `/hyperframes` first.
 
-You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the interaction mode (collaborative vs autonomous), the shared brief fields, and how to ask; the mode governs how the Step 0/3/6 gates behave. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
+You are the orchestrator. Work in `videos/<project>/`. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Read `../hyperframes-core/references/brief-contract.md` before Step 0 — it defines the two modes, the gate types, and the brief fields; the mode governs the Step 0/3/6 gates. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, this skill's local `../hyperframes-animation/rules/` + `../hyperframes-animation/blueprints/`, and `hyperframes-creative`.
 
 Workflow: Step 0 setup -> `hyperframes.json`; Step 1 capture -> `capture/`; Step 2 design system -> `frame.md`; Step 3 storyboard/script -> `STORYBOARD.md` and `SCRIPT.md`; Step 3.1 audio -> `audio_meta.json`; Step 4 visual design -> enriched `STORYBOARD.md`; Step 5 frames -> `compositions/frames/NN-*.html` and `index.html`; Step 6 final render -> `renders/video.mp4`.
 
@@ -27,17 +27,22 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the bran
 
 **Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
 
-**Confirm the brief in one round** per the brief contract — every asked field gets its own question with a recommended default plus a one-line receipt; "go" accepts all.
+**Confirm the brief** in two rounds — through the question UI when the environment has one, conversationally otherwise. The intro text states **message** (the ONE thing the promo must communicate, in one sentence) and **language**. Skip a question only when the user's request already answered it. (`VO_MODE` is asked in Step 1 only when a script was pasted.)
 
-**Ask** (each its own question, every run — never drop one as "inferable"):
+**Round 1 — mode.** One question, asked first. Skip it when the request already carried a signal ("surprise me" / "just build it"):
 
-- **angle** — the promo's story shape; default: infer from the site's / brief's own positioning (state the basis).
-- **length** — default inside the 30–90s sweet spot, scaled to how much material the input gives you (state the basis).
-- **destination → aspect** — per the contract's derivation (social feed → 1:1; Shorts / TikTok → 9:16; else 16:9).
+- **Collaborative (recommended)** — confirm the key choices together before building.
+- **Autonomous** — every decision is made for the user, each stated with its reason; the only remaining question is preview-before-render.
 
-**State in the intro text** (don't ask): **message** (the ONE thing the promo must communicate, echoed back in one sentence), **language** (the user's). (`VO_MODE` is asked in Step 1 only when a script was pasted.)
+Autonomous → ask nothing more. State the locked brief (all fields + receipts) as a heads-up and proceed straight through; the preview question waits at Step 6.
 
-In autonomous mode, state the locked brief as a heads-up and proceed.
+**Round 2 — the brief (collaborative).** One round, these three questions, recommended option first with its receipt:
+
+- **Angle — what story shape should the promo take?** Options from the site's / brief's own positioning; recommend one, with its basis.
+- **Length — how long?** Recommend inside the 30–90s sweet spot, scaled to how much material the input gives you, with its basis.
+- **Destination — where will it play?** YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
+
+A "go" accepts all recommended defaults.
 
 **Gate:** `hyperframes.json` exists, and the brief fields (angle, length, destination → aspect, message, language) are locked; sign-in status was shown (signed in, or continuing offline).
 
@@ -81,11 +86,11 @@ The script does the rest deterministically: copies the preset's `FRAME.md` → `
 
 Goal: Turn the brief and captured material into an approved frame-by-frame story plan.
 
-Read `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
+Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
 
 Use `story-design.md` for story blueprint, hook, persuasion logic, beats, `VO_MODE`, and asset choices. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, note a candidate blueprint id when one fits. Story truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Choose each visual frame's `asset_candidates` from `capture/extracted/asset-descriptions.md` (the canonical inventory) — don't browse raw `capture/assets/`. Do not ask the user to pick assets unless that inventory is missing or unusable. Use the exact required fields from the storyboard and script references.
 
-After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed without waiting — skip the preview question and carry "not asked" to Step 6.
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then a frame-by-frame summary where every frame carries a one-line `why:` (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every visual frame has `asset_candidates`, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
@@ -181,11 +186,11 @@ Inject transitions, run checks, pause for review, then render.
 
 If a command fails, surface stderr and stop — don't pile on recovery commands. Fix it yourself: the cheapest safe edit to `compositions/frames/NN-*.html`, then rerun the failed check.
 
-After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode the review pause is a checkpoint gate: post a one-line heads-up (checks passed, render starting — `npx hyperframes preview` if they want to look first), proceed to render without waiting, then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
+After checks pass, pause for user review. The video is assembled, viewable, and editable in Studio. Manage preview only once across Step 3 and Step 6: open it if the user asked earlier, offer it if they declined earlier, and do not ask again if they are already reviewing in Studio. In autonomous mode this is the one question the mode keeps: ask "preview first, or render?" — open the preview on yes, render on no — then deliver the MP4 with the contact sheet and the frame ids so revisions can target a single frame.
 
 Preview: `npx hyperframes preview`
 
-Render only after user approval (autonomous mode: after the checks pass):
+Render only after user approval (autonomous mode: after the preview-or-render question):
 
 `npx hyperframes render --skill=product-launch-video --quality high --output renders/video.mp4`
 
@@ -203,19 +208,20 @@ Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless
 
 The reusable, product-agnostic shot shapes live in `../hyperframes-animation/blueprints/` (indexed by `../hyperframes-animation/blueprints-index.md`).
 
-| Read                                                                                                                                                        | When                                                           |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.    |
-| `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                       |
-| `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                          |
-| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the product-launch story.                         |
-| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.      |
-| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                 |
-| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                     |
-| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers and voices.       |
-| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary). |
-| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.           |
-| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).  |
-| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.        |
-| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                            |
-| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                            |
+| Read                                                                                                                                                        | When                                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `[../hyperframes-core/references/brief-contract.md](../hyperframes-core/references/brief-contract.md)`                                                      | Step 0: the interaction mode, brief fields, and how to ask.                    |
+| `[../hyperframes-creative/references/story-spine.md](../hyperframes-creative/references/story-spine.md)`                                                    | Step 3: story doctrine — hook language, value-before-evidence, proposal shape. |
+| `[../hyperframes-creative/frame-presets/](../hyperframes-creative/frame-presets/)`                                                                          | Step 2: choose and adopt a frame preset.                                       |
+| `[../hyperframes-creative/references/design-spec.md](../hyperframes-creative/references/design-spec.md)`                                                    | Step 2: apply brand tokens correctly.                                          |
+| `[references/story-design.md](references/story-design.md)`                                                                                                  | Step 3: plan the product-launch story.                                         |
+| `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)`                                                              | Step 3: role→blueprint menu. Step 4: pick the shot shape.                      |
+| `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)`                                                | Step 3: write `STORYBOARD.md`.                                                 |
+| `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)`                                                        | Step 3: write `SCRIPT.md`.                                                     |
+| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)`                                                                              | Step 3.1: choose or understand TTS providers and voices.                       |
+| `[references/visual-design.md](references/visual-design.md)`                                                                                                | Step 4: write the frame's shot sequence (+ Layout vocabulary).                 |
+| `[references/motion-language.md](references/motion-language.md)`                                                                                            | Step 4: the motion vocabulary + the motion doctrine.                           |
+| `[references/cut-catalog.md](references/cut-catalog.md)`                                                                                                    | Step 4-5: the cut catalog (worker builds within-frame seams).                  |
+| `[../hyperframes-animation/rules-index.md](../hyperframes-animation/rules-index.md)` + `[../hyperframes-animation/rules/](../hyperframes-animation/rules/)` | Step 5: local rule recipe bodies for the cited motions.                        |
+| `[sub-agents/frame-worker.md](sub-agents/frame-worker.md)`                                                                                                  | Step 5: dispatch per-frame workers.                                            |
+| `[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)`                                                | Step 5: dispatch sub-agents safely.                                            |
diff --git a/skills/product-launch-video/references/story-design.md b/skills/product-launch-video/references/story-design.md
index 8180025ef7..125372f4dd 100644
--- a/skills/product-launch-video/references/story-design.md
+++ b/skills/product-launch-video/references/story-design.md
@@ -64,7 +64,7 @@ One clear job per beat — never "more benefits" or "another feature." Beat `typ
 
 `hook | pain_point | product_intro | feature_showcase | benefit_highlight | social_proof | branding | cta`
 
-The opening 3–5s needs ONE hook that creates tension, curiosity, or desire — a shocking stat, pain validation, a rhetorical question, direct address, an imagine/future-pace, a category announcement, or visual spectacle. Never open with generic company description.
+The opening 3–5s needs ONE hook that creates tension, curiosity, or desire — a shocking stat, pain validation, a rhetorical question, direct address, an imagine/future-pace, a category announcement, or visual spectacle. Never open with generic company description. Per `../hyperframes-creative/references/story-spine.md`: the hook speaks the viewer's outcome language (what they gain, never a feature list), and the promise (`message`) lands by beat 2 — features after that are its evidence.
 
 A UI demo is usually a SEQUENCE of 3+ consecutive `feature_showcase` / `benefit_highlight` beats on the same surface (input → response → result → benefit), not one isolated frame.
 
diff --git a/skills/website-to-video/references/step-3-storyboard.md b/skills/website-to-video/references/step-3-storyboard.md
index 8c2bf9c811..7ad08d97b0 100644
--- a/skills/website-to-video/references/step-3-storyboard.md
+++ b/skills/website-to-video/references/step-3-storyboard.md
@@ -542,13 +542,13 @@ After writing the storyboard AND the script, present BOTH to the user for review
 
 ### How to Present
 
-Summarize the plan clearly. Don't dump the full STORYBOARD.md — give the user a beat-by-beat overview they can scan in 30 seconds:
+Summarize the plan clearly. Don't dump the full STORYBOARD.md — give the user a beat-by-beat overview they can scan in 30 seconds. Per `../../hyperframes-creative/references/story-spine.md` § 3, the summary is a proposal: open by echoing the strategy line, and give every beat a `why:` traced to the message:
 
-> **Here's what I've planned for your [duration] [type]:**
+> **This video tells [audience] that [message].** Here's the plan for your [duration] [type]:
 >
-> **Beat 1 (0:00–0:04):** [one sentence — what happens visually + what the narration says]
-> **Beat 2 (0:04–0:10):** [one sentence]
-> **Beat 3 (0:10–0:18):** [one sentence] _(hero beat — 3D MacBook reveal with bloom effect)_
+> **Beat 1 (0:00–0:04):** [one sentence — what happens visually + what the narration says] — _why: [the beat's job, traced to the message]_
+> **Beat 2 (0:04–0:10):** [one sentence] — _why: […]_
+> **Beat 3 (0:10–0:18):** [one sentence] _(hero beat — 3D MacBook reveal with bloom effect)_ — _why: […]_
 > ...
 > **Beat N (closing):** [one sentence — CTA/logo]
 >

From cf8614e65ad6e154df9f91b6f63d35528c7eeb09 Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Tue, 7 Jul 2026 22:15:28 +0800
Subject: [PATCH 3/6] feat(skills): split type minimums by viewing context
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

typography.md: full-screen viewing keeps body 20px / headline 60px;
in-feed destinations (X / LinkedIn / Instagram — brief-contract's
destination field) scale to body >=32px, headline >=90px, data labels
>=24px. First-pass values, to be calibrated against real renders.
---
 skills-manifest.json                                 | 8 ++++----
 skills/hyperframes-creative/references/typography.md | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index f1fc3b7cab..96cefe0453 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -6,7 +6,7 @@
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "e3e985bb49f54b06",
+      "hash": "49f7541cfcab07c8",
       "files": 18
     },
     "figma": {
@@ -34,7 +34,7 @@
       "files": 14
     },
     "hyperframes-creative": {
-      "hash": "6767eb16fd7ef98a",
+      "hash": "904a42525511f835",
       "files": 69
     },
     "hyperframes-keyframes": {
@@ -58,11 +58,11 @@
       "files": 132
     },
     "pr-to-video": {
-      "hash": "8b3eb48b8e594533",
+      "hash": "b637106a1e5b1984",
       "files": 22
     },
     "product-launch-video": {
-      "hash": "f6e05101f9245172",
+      "hash": "4768fdb4b759d999",
       "files": 20
     },
     "remotion-to-hyperframes": {
diff --git a/skills/hyperframes-creative/references/typography.md b/skills/hyperframes-creative/references/typography.md
index 30ba3d76a7..2e5713d632 100644
--- a/skills/hyperframes-creative/references/typography.md
+++ b/skills/hyperframes-creative/references/typography.md
@@ -60,7 +60,7 @@ You know these rules but you violate them. Stop.
 - **Don't pair two sans-serifs.** You do this constantly — one for headlines, one for body. Cross the boundary: serif + sans, or sans + mono.
 - **One expressive font per scene.** You pick two interesting fonts trying to make it "better." One performs, one recedes.
 - **Weight contrast must be extreme.** You default to 400 vs 700. Video needs 300 vs 900. The difference must be visible in motion at a glance.
-- **Video sizes, not web sizes.** Body: 20px minimum. Headlines: 60px+. Data labels: 16px. You will try to use 14px. Don't.
+- **Video sizes, not web sizes.** Full-screen viewing (YouTube / website embed): body 20px minimum, headlines 60px+, data labels 16px. **In-feed viewing** (destination = X / LinkedIn / Instagram feed — `hyperframes-core/references/brief-contract.md` § 2): the video plays small inside a scrolling feed, so scale up — body ≥32px, headlines ≥90px, data labels ≥24px (first-pass values; calibrate against real renders). You will try to use 14px. Don't.
 
 ## What You Don't Do Without Being Told
 

From c548953def9730545d886b3060cfd63c60a2d134 Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Wed, 8 Jul 2026 14:56:16 +0800
Subject: [PATCH 4/6] feat(skills): storyboard proposal as a table + credits
 close by default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- story-spine § 3: the proposal presents frames as a markdown table
  (frame · beat · on screen · why) instead of dense paragraphs; the
  three shot-sequence workflows and website-to-video's beat summary
  reference the same shape
- pr-to-video: the credits close is now the default ending — every PR
  video ends on a contributors frame (committers by commit count, 1-6
  avatars), with no taste judgment; the only skip is when no avatar
  was fetched, and the user can cut the frame in the proposal
---
 skills-manifest.json                                 | 10 +++++-----
 skills/faceless-explainer/SKILL.md                   |  2 +-
 .../hyperframes-creative/references/story-spine.md   | 11 +++++++++--
 skills/pr-to-video/SKILL.md                          |  8 ++++----
 skills/pr-to-video/references/story-design.md        | 10 +++++-----
 skills/product-launch-video/SKILL.md                 |  2 +-
 .../website-to-video/references/step-3-storyboard.md | 12 +++++++-----
 7 files changed, 32 insertions(+), 23 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index 96cefe0453..9a48129e78 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -6,7 +6,7 @@
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "49f7541cfcab07c8",
+      "hash": "eefc92e38ebc3c64",
       "files": 18
     },
     "figma": {
@@ -34,7 +34,7 @@
       "files": 14
     },
     "hyperframes-creative": {
-      "hash": "904a42525511f835",
+      "hash": "1aabfdbfeb06fe45",
       "files": 69
     },
     "hyperframes-keyframes": {
@@ -58,11 +58,11 @@
       "files": 132
     },
     "pr-to-video": {
-      "hash": "b637106a1e5b1984",
+      "hash": "2b55d661d6522270",
       "files": 22
     },
     "product-launch-video": {
-      "hash": "4768fdb4b759d999",
+      "hash": "6597395eb2aecedc",
       "files": 20
     },
     "remotion-to-hyperframes": {
@@ -78,7 +78,7 @@
       "files": 27
     },
     "website-to-video": {
-      "hash": "72cef2ad592b65b9",
+      "hash": "e227830484883145",
       "files": 32
     }
   }
diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md
index d151364b94..293b2fd5b8 100644
--- a/skills/faceless-explainer/SKILL.md
+++ b/skills/faceless-explainer/SKILL.md
@@ -91,7 +91,7 @@ Read `../hyperframes-creative/references/story-spine.md` (hook language, value-b
 
 Use `story-design.md` for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and `VO_MODE`. The video's sequence comes from **narrative design, not the input text's paragraph order** — reorder, merge, omit, compress. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits. Teaching truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Faceless visuals are invented downstream, so frames do **not** carry an asset inventory: leave `asset_candidates` empty unless the user supplied a real `public/<basename>` image. Use the exact required fields from the storyboard and script references.
 
-After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then a frame-by-frame summary where every frame carries a one-line `why:` (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
diff --git a/skills/hyperframes-creative/references/story-spine.md b/skills/hyperframes-creative/references/story-spine.md
index 1b219b067a..faf47a1c74 100644
--- a/skills/hyperframes-creative/references/story-spine.md
+++ b/skills/hyperframes-creative/references/story-spine.md
@@ -24,7 +24,14 @@ Structure is value-first; the **voice** stays whatever the workflow prescribes (
 When Step 3 presents the plan (a checkpoint gate — `hyperframes-core/references/brief-contract.md` § 1):
 
 - Open by echoing the strategy line: **"This video tells [audience] that [message]."**
-- Every frame line carries a one-line `why:` — the frame's job in the story (from its `narrativeRole`), traced back to the message. A frame whose `why` cannot be traced to the message is a frame to cut, not to decorate.
+- Present the frames as a markdown table, one row per frame:
+
+  | Frame            | Beat      | On screen                                               | Why                             |
+  | ---------------- | --------- | ------------------------------------------------------- | ------------------------------- |
+  | 01 — Not anymore | hook · 9s | States the old pain and resolves it in the same breath. | Lands the value claim in beat 1 |
+
+  **Why** is the frame's job in the story (from its `narrativeRole`), traced back to the message — a frame whose why cannot be traced to the message is a frame to cut, not to decorate.
+
 - Recommendations keep their receipts (brief-contract § 3): the archetype choice, the beat count, and any beat the user might question each state their basis.
 
-The proposal shape — echo line → per-frame lines with `why:` → style / duration footer → "approve or adjust" — is the cheapest place to iterate: a beat change here costs 30 seconds; the same change after build costs minutes.
+The proposal shape — echo line → frame table → style / duration footer → "approve or adjust" — is the cheapest place to iterate: a frame change here costs 30 seconds; the same change after build costs minutes.
diff --git a/skills/pr-to-video/SKILL.md b/skills/pr-to-video/SKILL.md
index c892f092ea..720c0faeae 100644
--- a/skills/pr-to-video/SKILL.md
+++ b/skills/pr-to-video/SKILL.md
@@ -84,7 +84,7 @@ PR="<url | owner/repo#N | N>"
   --pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
 
 # The people front's one network step — download each contributor's GitHub avatar to
-# assets/<login>.png for an optional credits close. Best-effort; always exits 0.
+# assets/<login>.png for the credits close. Best-effort; always exits 0.
 (cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
   --people ./capture/extracted/people.json)
 ```
@@ -117,9 +117,9 @@ Goal: Turn the PR into an approved frame-by-frame explanation plan.
 
 Read `../hyperframes-creative/references/story-spine.md` (hook language, value-before-evidence, storyboard-as-proposal), `references/story-design.md`, `../hyperframes-animation/blueprints-index.md`, `../hyperframes-core/references/storyboard-format.md`, and `../hyperframes-core/references/script-format.md`. Use them to write `STORYBOARD.md` and, when narration is needed, `SCRIPT.md`.
 
-Use `story-design.md` for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the optional credits close. The sequence comes from **narrative design, not the diff's file order** — explain the change, don't read the diff aloud. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits (story truth still decides which beats exist — never force a beat to fit a shape). Feature 2–4 real diff hunks (from `capture/diff.patch`), each a small legible snippet; name the `code-*` block each wants in the frame's `scene`. Frames carry no `asset_candidates` except an optional `credits` close (2–6 `assets/<login>.png` avatars). Use the exact required fields from the storyboard and script references.
+Use `story-design.md` for the PR archetype (changelog / feature-reveal / fix-explainer / refactor-walkthrough), the PR-native frame types, hook, persuasion, beats, the per-frame word budget, and the credits close. The sequence comes from **narrative design, not the diff's file order** — explain the change, don't read the diff aloud. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, write the voiceover in the shape its candidate blueprint implies and tag that candidate `blueprint:` id when one fits (story truth still decides which beats exist — never force a beat to fit a shape). Feature 2–4 real diff hunks (from `capture/diff.patch`), each a small legible snippet; name the `code-*` block each wants in the frame's `scene`. Frames carry no `asset_candidates` except the `credits` close (1–6 `assets/<login>.png` avatars). Use the exact required fields from the storyboard and script references.
 
-After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then a frame-by-frame summary where every frame carries a one-line `why:` (its `narrativeRole`, traced to the message). In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). In that same message ask the user (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (`npx hyperframes preview`) — open it only on a yes. Iterate until approved; carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every frame has the required narrative fields, `SCRIPT.md` exists when narration is needed, and the user approved the plan (autonomous: the summary was posted as a heads-up).
 
@@ -233,7 +233,7 @@ Do not rerun `lint`, `validate`, `inspect`, or `snapshot` after rendering unless
 
 **Formats:** landscape `1920x1080`; portrait `1080x1920`; square `1080x1080` — derived from the destination (brief contract § 2). Set the format once in the storyboard frontmatter.
 
-**PR deltas vs a captured-asset workflow:** no Step 1 capture (the `gh` CLI ingests the PR into a synthetic `capture/extracted/` package — `tokens.json` + `visible-text.txt` + `people.json`); the only real assets are the contributors' `assets/<login>.png` avatars (an optional credits close); no `asset-descriptions.md`, no asset-staging step. Code beats are rendered by the `code-*` registry blocks on claude's navy Code Surface; the style is always **claude**.
+**PR deltas vs a captured-asset workflow:** no Step 1 capture (the `gh` CLI ingests the PR into a synthetic `capture/extracted/` package — `tokens.json` + `visible-text.txt` + `people.json`); the only real assets are the contributors' `assets/<login>.png` avatars (the credits close); no `asset-descriptions.md`, no asset-staging step. Code beats are rendered by the `code-*` registry blocks on claude's navy Code Surface; the style is always **claude**.
 
 **Background scripts:** the workflow ships these under `scripts/`: `fetch-pr` (PR → `capture/pr.json` + `diff.patch` via `gh`; large-PR-safe, no scratch), `ingest` (→ synthetic capture package; offline), and `fetch-people-avatars` (contributor avatars → `assets/`); plus the shared engine — `build-frame` (adopt + brand-remix a preset into `frame.md` + caption skin), `audio` (TTS, BGM, SFX, duration sync), `captions`, `transitions` (inject + verify), and `assemble-index`. Everything else is the `hyperframes` CLI. Code blocks install via `npx hyperframes add <name>`.
 
diff --git a/skills/pr-to-video/references/story-design.md b/skills/pr-to-video/references/story-design.md
index 0293935cf7..ea92a0e68c 100644
--- a/skills/pr-to-video/references/story-design.md
+++ b/skills/pr-to-video/references/story-design.md
@@ -10,7 +10,7 @@ This file defines the story: what the video explains, in what order, and why eac
 2. `frame.md` — tone, type, design system (the shipped preset is **claude**: warm editorial, a serif that thinks, scarce coral, a navy code surface).
 3. `capture/extracted/visible-text.txt` — the assembled PR brief: title, meta (`base ← head · +N/−M across F files`), people, body, commits, changed files, and a budget-bounded set of **representative diff hunks**. This is your source of **information**.
 4. `capture/diff.patch` — the full unified diff, for deeper hunk selection than the brief's excerpt.
-5. `capture/extracted/people.json` — contributors (author / committers / reviewers / commenters), bot-filtered, each with an avatar in `assets/<login>.png` (for an optional credits close).
+5. `capture/extracted/people.json` — contributors (author / committers / reviewers / commenters), bot-filtered, each with an avatar in `assets/<login>.png` (for the credits close).
 
 ## Output
 
@@ -151,13 +151,13 @@ Plan **at least one `mechanism` beat** for any PR with a visible runtime behavio
 
 Name the mechanism in the frame's `scene` ("animate the request retrying: fire → 500 → backoff → 200, invented SVG flow") so Step 4 and the worker build it. The `diff` frame and the `mechanism` frame are **complementary** — the diff is the proof in code, the mechanism is the proof in motion; alternate them rather than stacking code surfaces.
 
-## Optional close: a credits / shipped-by scene
+## The close: a credits / shipped-by scene
 
-A PR is shipped by people. `capture/extracted/people.json` lists real contributors (bot-filtered), and Step 1 downloaded each avatar to `assets/<login>.png` (the `avatarFetched: true` entries — confirm with `ls assets/`). `reviewDecision` (e.g. `APPROVED`) is honest grounding.
+A PR is shipped by people, and every PR video closes with a `credits` frame naming them. `capture/extracted/people.json` lists real contributors (bot-filtered), and Step 1 downloaded each avatar to `assets/<login>.png` (the `avatarFetched: true` entries — confirm with `ls assets/`). `reviewDecision` (e.g. `APPROVED`) is honest grounding.
 
 > **The PR `author` only opened the PR — not necessarily who wrote the code.** A teammate often authors most commits. Lead the credits with `committer`s by `commitCount`, not the opener.
 
-You **may** add one closing `credits` frame naming the humans — an avatar row with names + roles + an "approved" check. On that frame only, set `asset_candidates` to 2–6 entries of `assets/<login>.png — <login>, <role>` (commit authors by `commitCount` first, then reviewers; only `avatarFetched: true` logins). The body stays code-only — avatars appear **only** on this close, never decorating a diff frame. This is **optional and tasteful**: a one-line hotfix or a solo PR with no reviews doesn't need a credits roll; a feature or release the team rallied around earns one.
+The `credits` frame is an avatar row with names + roles + an "approved" check. On that frame only, set `asset_candidates` to 1–6 entries of `assets/<login>.png — <login>, <role>` (commit authors by `commitCount` first, then reviewers; only `avatarFetched: true` logins). The body stays code-only — avatars appear **only** on this close, never decorating a diff frame. The frame sits in the Step 3 proposal like any other, so the user can cut it there; skip it yourself only when no avatar was fetched.
 
 Every other frame has **no** `asset_candidates` (the visuals are invented downstream from `scene` + the diff).
 
@@ -209,6 +209,6 @@ The `credits` frame additionally carries an `asset_candidates:` line (see the cr
 - **2–4 real diff hunks** featured, each a small legible snippet (not a whole file), each naming its `code-*` block in `scene`.
 - **At least one `mechanism` beat** animates what the change _does_ at runtime (an invented diagram, or a `flowchart` / `data-chart`), named in its `scene` — unless the PR genuinely has no visible behavior (a pure docs / config bump). The body is not an unbroken run of code surfaces.
 - Transitions use only registry names and repeat 2–3 types; frame 1 is `cut`.
-- `asset_candidates` is absent on every frame except an optional `credits` close (2–6 `assets/<login>.png` entries, `avatarFetched: true` only).
+- The video closes with a `credits` frame (skipped only when no avatar was fetched); `asset_candidates` is absent on every other frame (1–6 `assets/<login>.png` entries on the close, `avatarFetched: true` only).
 - Each `script` fits the budget — ≤ 19 words / ≤ 9 s default, ≤ 2 frames at the ≤ 26 / ≤ 12 s exception; `duration = ceil(word_count / 2.2)`, not a guess.
 - `SCRIPT.md` contains only locked spoken narration; silent frames are intentional and omitted from it.
diff --git a/skills/product-launch-video/SKILL.md b/skills/product-launch-video/SKILL.md
index 748e3bf442..c52b39aa79 100644
--- a/skills/product-launch-video/SKILL.md
+++ b/skills/product-launch-video/SKILL.md
@@ -90,7 +90,7 @@ Read `../hyperframes-creative/references/story-spine.md` (hook language, value-b
 
 Use `story-design.md` for story blueprint, hook, persuasion logic, beats, `VO_MODE`, and asset choices. As a **soft guide**, consult the role→blueprint menu in `../hyperframes-animation/blueprints-index.md`: for each beat, note a candidate blueprint id when one fits. Story truth still decides which beats exist — never force a beat to fit a blueprint, and never invent a beat just because a proven shape is available. Choose each visual frame's `asset_candidates` from `capture/extracted/asset-descriptions.md` (the canonical inventory) — don't browse raw `capture/assets/`. Do not ask the user to pick assets unless that inventory is missing or unusable. Use the exact required fields from the storyboard and script references.
 
-After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then a frame-by-frame summary where every frame carries a one-line `why:` (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
+After drafting, present the plan as a proposal per story-spine § 3: open by echoing **"This video tells [audience] that [message]"**, then the frame table — one row per frame: frame · beat (type, duration) · on screen · why (its `narrativeRole`, traced to the message). In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6. This is a **checkpoint gate** (brief contract § 1): in autonomous mode, post the same summary as a heads-up and proceed — the preview question is asked once, at Step 6.
 
 **Gate:** `STORYBOARD.md` exists, every visual frame has `asset_candidates`, `SCRIPT.md` exists when narration is needed, and the user approved the frame-by-frame plan (autonomous: the summary was posted as a heads-up).
 
diff --git a/skills/website-to-video/references/step-3-storyboard.md b/skills/website-to-video/references/step-3-storyboard.md
index 7ad08d97b0..7837b7729b 100644
--- a/skills/website-to-video/references/step-3-storyboard.md
+++ b/skills/website-to-video/references/step-3-storyboard.md
@@ -546,11 +546,13 @@ Summarize the plan clearly. Don't dump the full STORYBOARD.md — give the user
 
 > **This video tells [audience] that [message].** Here's the plan for your [duration] [type]:
 >
-> **Beat 1 (0:00–0:04):** [one sentence — what happens visually + what the narration says] — _why: [the beat's job, traced to the message]_
-> **Beat 2 (0:04–0:10):** [one sentence] — _why: […]_
-> **Beat 3 (0:10–0:18):** [one sentence] _(hero beat — 3D MacBook reveal with bloom effect)_ — _why: […]_
-> ...
-> **Beat N (closing):** [one sentence — CTA/logo]
+> | Beat          | On screen + narration                                              | Why                                     |
+> | ------------- | ------------------------------------------------------------------ | --------------------------------------- |
+> | 1 (0:00–0:04) | [one sentence — what happens visually + what the narration says]   | [the beat's job, traced to the message] |
+> | 2 (0:04–0:10) | [one sentence]                                                     | […]                                     |
+> | 3 (0:10–0:18) | [one sentence] _(hero beat — 3D MacBook reveal with bloom effect)_ | […]                                     |
+> | …             | …                                                                  | …                                       |
+> | N (closing)   | [one sentence — CTA/logo]                                          | […]                                     |
 >
 > **Style:** [dimension summary — e.g., "Cinematic pacing, dark mood, dramatic transitions for hero, clean for the rest"]
 > **Narration:** [first and last line of the script]

From e39b954694ae0ff456c9e5589a0ab1f0b18c84dd Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Wed, 8 Jul 2026 18:36:44 +0800
Subject: [PATCH 5/6] fix(skills): address review nits on the brief/story
 contracts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- embedded-captions: the identity procedure now states both sides of the
  preference gate inline (user picks; autonomous picks with a stated why)
- website-to-video step-2-brief: note that its mode section is the
  workflow's application of brief-contract.md, not a second definition
- brief-contract: resuming a project reads mode from STORYBOARD.md
  frontmatter — a recorded mode counts as set, closing the write-only gap
---
 skills-manifest.json                                 | 6 +++---
 skills/embedded-captions/SKILL.md                    | 3 ++-
 skills/hyperframes-core/references/brief-contract.md | 2 +-
 skills/website-to-video/references/step-2-brief.md   | 2 +-
 4 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index 94e093ecb5..a81965f83b 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -2,7 +2,7 @@
   "source": "heygen-com/hyperframes",
   "skills": {
     "embedded-captions": {
-      "hash": "169f74d84d52860c",
+      "hash": "5859f7129550b798",
       "files": 144
     },
     "faceless-explainer": {
@@ -30,7 +30,7 @@
       "files": 7
     },
     "hyperframes-core": {
-      "hash": "5b3a61fad4106c76",
+      "hash": "440b82a23415750b",
       "files": 14
     },
     "hyperframes-creative": {
@@ -78,7 +78,7 @@
       "files": 27
     },
     "website-to-video": {
-      "hash": "886d3f32388a22db",
+      "hash": "f41dee71998bb6d1",
       "files": 32
     }
   }
diff --git a/skills/embedded-captions/SKILL.md b/skills/embedded-captions/SKILL.md
index 463a8c4ccf..2c7bea83af 100644
--- a/skills/embedded-captions/SKILL.md
+++ b/skills/embedded-captions/SKILL.md
@@ -64,7 +64,8 @@ in autonomous mode ("surprise me" / "decide for me"), pick from your shortlist
 yourself and state the one-line why instead of asking.
 
 Procedure: probe the clip → shortlist 2–3 identities from the catalog →
-recommend ONE with a one-line why → **the user picks** → author that identity's
+recommend ONE with a one-line why → **the user picks** (autonomous mode: you
+pick, stating the why) → author that identity's
 file. Identities are engine-locked (no cross combos; opening one is a
 validation event — see dna/README.md).
 
diff --git a/skills/hyperframes-core/references/brief-contract.md b/skills/hyperframes-core/references/brief-contract.md
index ca38df3794..38e38d0a89 100644
--- a/skills/hyperframes-core/references/brief-contract.md
+++ b/skills/hyperframes-core/references/brief-contract.md
@@ -10,7 +10,7 @@ There are two modes. Default: **collaborative**.
 
 - **Ongoing autonomous signals** — "autonomous", "surprise me", "decide for me", "just build it", "don't ask, just go", "LFG": the whole flow switches to autonomous from this point on.
 - **One-time acceptance** — a bare "go" / "looks good" at a gate accepts only that gate's defaults; the mode does not change.
-- The mode is set **once** — by a signal in the request, or by the brief's first question (§ 3) — and **carries forward. No later step asks again.** Once a storyboard exists, record it in `STORYBOARD.md` frontmatter (`mode: autonomous`) so resumed sessions inherit it.
+- The mode is set **once** — by a signal in the request, or by the brief's first question (§ 3) — and **carries forward. No later step asks again.** Once a storyboard exists, record it in `STORYBOARD.md` frontmatter (`mode: autonomous`). When resuming an existing project, read `mode` from that frontmatter first — a recorded mode counts as already set, so don't ask again.
 - **Mid-run switch**: "stop asking / just finish it" → autonomous for the rest of the run. Clear feedback on a heads-up → collaborative resumes at the next gate.
 
 **Gate types.** Autonomous mode changes only the first two types:
diff --git a/skills/website-to-video/references/step-2-brief.md b/skills/website-to-video/references/step-2-brief.md
index 52f71901d4..6484dcd7b7 100644
--- a/skills/website-to-video/references/step-2-brief.md
+++ b/skills/website-to-video/references/step-2-brief.md
@@ -118,7 +118,7 @@ When the user gives no creative direction, default to what the brand's visual id
 
 With that minimum in hand, still write an ambitious storyboard. "Surprise me" means "impress me," not "play it safe." Go bold.
 
-**Autonomous mode propagates — for user-preference gates only.** When the user signals "surprise me" / "decide for me" / "just build it" here at Step 2, that signal kills downstream user-preference 💬 gates: Step 3's storyboard approval, Step 4's TTS provider choice, music yes/no, captions yes/no. Make those creative decisions yourself and present the finished video at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.
+**Autonomous mode propagates — for user-preference gates only.** (Mode semantics — signals, propagation, gate types — are canonical in `../../hyperframes-core/references/brief-contract.md`; this section is this workflow's application of them, not a second definition.) When the user signals "surprise me" / "decide for me" / "just build it" here at Step 2, that signal kills downstream user-preference 💬 gates: Step 3's storyboard approval, Step 4's TTS provider choice, music yes/no, captions yes/no. Make those creative decisions yourself and present the finished video at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.
 
 **Auto mode does NOT skip quality-verification gates.** These run regardless and must produce evidence in your final summary:
 

From 451699db260b8f644e271b042f797e09a7939af2 Mon Sep 17 00:00:00 2001
From: Miao Yang <miao.yang@heygen.com>
Date: Wed, 8 Jul 2026 23:39:04 +0800
Subject: [PATCH 6/6] docs(skills): add a non-code receipts example to the
 brief contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review nit (jrusso1020, #2058): the receipts example in § 3 was
PR-video-shaped only. A destination-shaped example joins it so the rule
reads as workflow-neutral.
---
 skills-manifest.json                                 | 2 +-
 skills/hyperframes-core/references/brief-contract.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/skills-manifest.json b/skills-manifest.json
index a81965f83b..74cb825995 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -30,7 +30,7 @@
       "files": 7
     },
     "hyperframes-core": {
-      "hash": "440b82a23415750b",
+      "hash": "2b1fb57fc6964e76",
       "files": 14
     },
     "hyperframes-creative": {
diff --git a/skills/hyperframes-core/references/brief-contract.md b/skills/hyperframes-core/references/brief-contract.md
index 38e38d0a89..5707bc2421 100644
--- a/skills/hyperframes-core/references/brief-contract.md
+++ b/skills/hyperframes-core/references/brief-contract.md
@@ -44,5 +44,5 @@ The executable question script lives in each workflow's Step 0 as a literal two-
 
 - **Round 1 asks the mode** — one question, skipped when the request already carried a signal. Autonomous → no further questions: state the locked brief (all fields + receipts) as a heads-up and build straight through; the one remaining question, before render, is "preview first, or render?". Collaborative → Round 2.
 - **Round 2 asks the workflow's ask-marked fields** — one question per field, recommended option first, each with its receipt. Skip a question only when the user already answered that field in their request; inference is not an answer.
-- **Receipts.** Every recommended option states its basis: "~40s — small change, +44/−13 across 12 files".
+- **Receipts.** Every recommended option states its basis — "~40s — small change, +44/−13 across 12 files"; "square 1:1 — you named the X/LinkedIn feed as the destination".
 - **Channel.** Native question UI when the environment has one; otherwise plain text as one numbered list. "go" accepts all defaults.