heygen-com · WaterrrForever · Jul 8, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/skills-manifest.json b/skills-manifest.json
@@ -2,23 +2,23 @@
   "source": "heygen-com/hyperframes",
   "skills": {
     "embedded-captions": {
-      "hash": "36a43fc349052ab0",
+      "hash": "fe837c08dd47b077",
       "files": 144
     },
     "faceless-explainer": {
-      "hash": "027ae009f5255130",
+      "hash": "7f8f31695723756b",
       "files": 18
     },
     "figma": {
       "hash": "ee1408c58b76db8e",
       "files": 1
     },
     "general-video": {
-      "hash": "c266136f4ffa2157",
+      "hash": "e26710c3537b3a07",
       "files": 1
     },
     "hyperframes": {
-      "hash": "42ba4448d7552099",
+      "hash": "24ec436b52957fcc",
       "files": 1
     },
     "hyperframes-animation": {
@@ -30,12 +30,12 @@
       "files": 7
     },
     "hyperframes-core": {
-      "hash": "788462fc5c3b9ee1",
-      "files": 13
+      "hash": "2b1fb57fc6964e76",
+      "files": 14
     },
     "hyperframes-creative": {
-      "hash": "18a14a79da6cbc06",
-      "files": 68
+      "hash": "a5bccc25d291899d",
+      "files": 69
     },
     "hyperframes-keyframes": {
       "hash": "555c0cd491c40cea",
@@ -50,35 +50,35 @@
       "files": 103
     },
     "motion-graphics": {
-      "hash": "2bd92504783e8a0c",
+      "hash": "96ed2f7d8051b009",
       "files": 23
     },
     "music-to-video": {
-      "hash": "3e1e91e93a7a80d0",
+      "hash": "901a19d0680f8c1b",
       "files": 132
     },
     "pr-to-video": {
-      "hash": "088f89960ecaf0ed",
+      "hash": "800b4c11cda4658b",
       "files": 22
     },
     "product-launch-video": {
-      "hash": "cc8f9e4aeb87aa4b",
+      "hash": "4f858cc4d59324da",
       "files": 20
     },
     "remotion-to-hyperframes": {
       "hash": "aa599f027db4b994",
       "files": 70
     },
     "slideshow": {
-      "hash": "3dd62c326ccf25eb",
+      "hash": "19a0332616bc397b",
       "files": 2
     },
     "talking-head-recut": {
-      "hash": "ff57c239045342a9",
+      "hash": "d5c51342625c9952",
       "files": 27
     },
     "website-to-video": {
-      "hash": "baa2f956f3b7a12d",
+      "hash": "32bdb559f4d18f99",
       "files": 32
     }
   }

diff --git a/skills/embedded-captions/SKILL.md b/skills/embedded-captions/SKILL.md
@@ -61,8 +61,13 @@ 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
+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/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md
diff --git 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
@@ -29,7 +29,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`
 
@@ -55,7 +55,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/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
@@ -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** — 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:
+
+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. 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.
+
+**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
+
+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"; "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.
diff --git 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