hyperframes 0.8.37 → 0.8.39

package/dist/skills/hyperframes/references/production-loop.md

@@ -0,0 +1,26 @@
+# Production loop — from an approved plan to a delivered video
+
+The stages between a plan the user has agreed to and a video in their hands, written as **dependencies, not numbered steps**: order between independent stages is free — audio renders in the background while frames build; that is the standard trick — order inside a dependency chain is not. Nothing in this file addresses the user: every user-facing pause lives in `review-loop.md`, and this file only marks where those passes attach. Some routes bring their own spine (a beat grid, existing footage) — the stages compose around it. A stage whose need is absent simply doesn't run: no narration, no audio stage; a single scene, no transitions. An edit request enters at the artifact it touches and re-runs verify.
+
+The shipped narrative workflows implement these stages with their own scripts; a freeform build follows this file directly, borrowing tools where the capability menu says they live (`hyperframes/references/capability-menu.md`).
+
+| Stage               | Needs                                                                                                                    | Produces                                                                                                                                                                                                       | Where the capability lives                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Blocks & assets** | the approved plan                                                                                                        | registry blocks installed **once, before any parallel work** (parallel workers race the registry); user assets staged; logos / images / grades resolved                                                        | `npx hyperframes add <block>` per block the plan names; staging, adoption, and `resolve` via the menu's media rows                            |
+| **Audio**           | narration text (when narrated); the storyboard's `music:` mood                                                           | voice files + **word timings** + BGM + SFX → `audio_meta.json`; **when BGM plays under a voice, the bed is carved** (`hyperframes-audio/scripts/carve.mjs`) before Verify — a duck alone is not a finished mix | the one engine — `media-use/audio/scripts/audio.mjs`, run in the background; `wait-bgm.mjs` before render when BGM generates                  |
+| **Frames**          | design spec + the plan (+ a confirmed sketch when one exists — dress that layout, never redraw it: `review-loop.md` § 3) | each scene at `compositions/frames/NN-*.html`, marked `animated` in the storyboard as it lands                                                                                                                 | `frame.md` + `hyperframes-animation` blueprints / rules (+ the genre lens, menu § Genre lenses); parallel dispatch per `subagent-dispatch.md` |
+| **Duration sync**   | word timings + frames                                                                                                    | scene durations trued to real voice length — real duration wins, silent scenes keep estimates, synced values are never hand-edited                                                                             | a mechanical rule; the narrative workflows' audio scripts apply it, a freeform build applies it by hand                                       |
+| **Assembly**        | frames                                                                                                                   | the index composition — scenes as sub-compositions on tracks                                                                                                                                                   | `sub-compositions.md` + `tracks-and-clips.md`; borrowable `assemble-index.mjs` (menu)                                                         |
+| **Transitions**     | the assembled index                                                                                                      | scene handoffs injected                                                                                                                                                                                        | `hyperframes-animation/transitions/overview.md` → `catalog.md`; borrowable `transitions.mjs` (menu)                                           |
+| **Captions**        | word timings + the index                                                                                                 | the caption track                                                                                                                                                                                              | borrowable `captions.mjs` (menu); no script to time against → `media-use` `scripts/transcribe.mjs` first                                      |
+| **Verify**          | the index (+ captions / transitions when present)                                                                        | `npx hyperframes lint` and `npx hyperframes check` **passing**; a contact-sheet glance (`snapshot --at <frame-midpoints>`)                                                                                     | `hyperframes-cli`                                                                                                                             |
+| **Deliver**         | verify passing                                                                                                           | the final-look pause → on approval `render` → optionally `publish` (a stable hosted link, private by default) → the recipe offer                                                                               | final approval and recipe offer: `review-loop.md` § 4; render / publish: `hyperframes-cli`                                                    |
+
+The Frames stage follows the plan's citations: a scene planned on a blueprint or on named rules is built by reading that recipe's body (`hyperframes-animation/blueprints/<id>.md`, `rules/<id>.md`) before its motion is written — names come from the indexes, never invented, and a scene the plan left uncited gets its citation at build time, not improvised motion.
+
+## Scheduling economics (facts you can't see from inside the session)
+
+- **External generations are independent work.** Image plates, TTS, BGM, video gen: fire every generation whose prompt is already known **concurrently or in the background**, and overlap the wait with reading or building. Three image plates generated one-after-another cost ~3× the wall time of firing them together.
+- **Attaching an image re-prices your whole context.** A mid-session image inspection (especially at original detail) invalidates the prompt cache — the next request re-sends your entire history at full price. Batch visual checks (one contact sheet beats N single-frame views) and schedule them at phase boundaries, not mid-build.
+
+Two attach points carry the user's voice into this loop: the plan that starts it was approved at `review-loop.md` § 1 (collaborative) or posted as a heads-up (autonomous), and nothing renders before the § 4 final look. Everything between those two is yours to schedule.

package/dist/skills/hyperframes/references/review-loop.md

@@ -0,0 +1,41 @@
+# The review loop — plan, sketch, build
+
+How a `storyboard: yes` run earns fidelity one pass at a time: the plan is reviewed as text on a live board, the layouts as wireframe sketches, and the finished piece as the assembled video. Collaborative mode waits at each checkpoint. Autonomous mode posts the same checkpoint summaries and continues, keeping exactly one question before render.
+
+This is the shared process for any workflow that plans on a storyboard. The contracts it leans on live next door: interaction mode, gate types, and the comments channel in `brief-contract.md`; the `STORYBOARD.md` format, the `outline → built → animated` statuses, and the comments sidecar in `storyboard-format.md`. A workflow's SKILL.md says **when** its steps hit each pass and supplies its **sketch stand-ins** (what the plain blocks represent); how the loop runs is defined here, once. The stage mechanics between the passes — audio, frames, assembly, transitions, captions, verify — live in `production-loop.md`; this file owns only the user-facing pauses.
+
+## § 1 — The plan, on a live board
+
+Open the **storyboard board** before presenting the plan: run `npx hyperframes preview --background` from the project directory, confirm it is serving, and open `http://localhost:<port>/?view=storyboard#project/<project-name>`. This is an early planning surface, not the final composition preview; it may open before composition checks. The plan appears as frame cards and refreshes as work lands.
+
+Present the plan as a proposal (shape: `hyperframes-creative/references/story-spine.md` § 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). Hand the board URL with it, noting feedback lands in both places — comment on the board or reply here, one revision loop — and that a board submit still needs one reply here (anything) to get picked up.
+
+In the same message ask two things: **(a)** approve or request changes, and **(b)** **sketches first** (recommended — a quick wireframe look check right after this approval) or skip sketches and build in one go. Iterate until approved — feedback arrives in chat or as the comments file (`brief-contract.md` § 1, the comments channel): revise exactly the frames it names, clear the file, re-present.
+
+This is a **checkpoint gate** (`brief-contract.md` § 1). A run that starts autonomous normally has `storyboard: no` and does not enter this loop. If mode switches to autonomous after a board exists, keep updating the board, post the same summary as a heads-up, and continue without waiting; the one kept question comes at § 4.
+
+## § 2 — The sketch pass (collaborative, unless skipped)
+
+The moment the plan is approved, wireframe every frame yourself — no sub-agents, no waiting on other steps (sketches don't use timings), straight from the approved frame table.
+
+A sketch is a **wireframe with the real words, not a styled frame**: the frame's layout at its key moment — the actual headline / stat / label text placed where it will live, plain blocks for panels, charts, diagrams, and media (the workflow says what its blocks stand in for), `frame.md`'s background and ink plus one accent on the focal, nothing else. No decoration, no full brand treatment, **no motion** — all of that arrives with the build pass.
+
+Keep each sketch a real composition file at `compositions/frames/NN-*.html` (template wrapper, `data-composition-id`, `#root` styling, one paused **empty** timeline registered at `window.__timelines["<frame_id>"]`) so the Studio poster renders — and the poster is the only picture this pass needs: **run no CLI here** — no `snapshot`, no `lint` / `check`, no rendering. A sketch is a few dozen lines of HTML; the whole board lands in minutes.
+
+Mark each frame `built` as its sketch lands — the user's open board fills in blue by itself. When every frame is `built`, pause and ask one thing: does the board look right, or which frames change? This is a **checkpoint gate**; the user reviews in Studio (open since § 1 — restart and re-hand the same URL if the server died), and feedback arrives in chat or as the comments file — check the file first when the reply arrives: revise **only the sketches named**, re-present, and loop until the layout is confirmed. Only then does the workflow's visual design get written onto the confirmed layouts.
+
+A confirmed board is also a valid place to **stop**. When the user asked for a storyboard rather than a finished video — a plan to pitch, review, or hand off — the sketched board is the deliverable: confirm it, hand the board URL, and go no further unless asked to build.
+
+In autonomous mode, or when the user chose to skip sketches at § 1, skip this pass — frames go straight from `outline` to `animated` in the build.
+
+## § 3 — Building on confirmed layouts
+
+However the workflow builds — sub-agent workers per frame, or inline scene by scene — a confirmed sketch's **composition is settled**: placement, hierarchy, and copy were approved on the board, so building means dressing that layout (full design treatment, real assets, motion), never redrawing it. Workflows that dispatch workers put "this frame has a **confirmed sketch** on disk" in the worker's context and carry the keep-the-layout rule in their worker prompt; a landed frame must still read as the approved wireframe, fully dressed.
+
+Mark each frame `animated` as it lands. The build gate carries the loop's condition: in collaborative mode, the sketch board was confirmed at § 2.
+
+## § 4 — The final look
+
+After the workflow's checks pass, use the **final composition preview**. In collaborative mode Studio may already be serving from § 1; hand the timeline URL and ask one thing: render now, or what changes? In autonomous mode this is the one question the mode keeps: ask “preview first, or render?” Open the final preview on yes; render on an explicit render answer. Render only on approval.
+
+**After approval, offer the recipe — once.** An approved run is a proven bundle. At delivery, offer to freeze it: `media-use` → `scripts/recipe.mjs freeze --name <name>` (the workflow comes from BRIEF.md; pass `--workflow` only in a project without one) keeps the design spec, the storyboard skeleton (structure kept, content blanked), the brief skeleton, and the confirmed brief values, and the next run of this type starts from it (the intent layer checks for a matching recipe before its first question). When the freeze lands, teach the recall in the confirmation — "Saved as **<name>** (v<N>). Next time say _make another <name>_, or just _like last time_." — the name is something the system reminds the user of, never something they must remember. In autonomous mode don't ask — name the freeze command in the delivery note instead.

package/dist/skills/hyperframes/references/route-briefs.md

@@ -8,4 +8,4 @@ route's own file, together with its input/output/trigger contract:
 `routes/pr-to-video.md` (including the PR-size → length table).
 
 The interview procedure itself (the eight steps) is `references/intent-interview.md`.
-Field semantics and question rules: `hyperframes-core/references/brief-contract.md` § 2–3.
+Field semantics and question rules: `hyperframes/references/brief-contract.md` § 2–3.

package/dist/skills/hyperframes/references/script-format.md

@@ -0,0 +1,52 @@
+# `SCRIPT.md` — locked narration (optional)
+
+The **locked narration** for a project: the final spoken lines + voice + delivery. It is an _optional_ plan-layer file — a video with no narration (bgm-only, silent overlay) has none. The storyboard's per-frame `voiceover` is the lighter, editable _guide_; `SCRIPT.md` is the _commit_. (Storyboard format → `references/storyboard-format.md`.)
+
+This file defines the SCRIPT.md **shape** only. Synthesizing the spoken lines into audio is a capability owned by `media-use` → `../../media-use/audio/references/tts.md`.
+
+Free-form markdown — there is no strict parser; the Studio renders it read-only beside the Storyboard board, and the TTS step extracts the indented spoken lines.
+
+## Shape
+
+A header block, then one section per spoken line.
+
+| Part                            | Holds                                                                                                                                   |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Header                          | `**Voice:**` (provider + voice), `**Voice settings:**` (e.g. stability / similarity / style), `**Voice direction:**` (overall delivery) |
+| `## Line N — <label> (Frame N)` | one spoken line, tied to its storyboard frame                                                                                           |
+| `**Time:**`                     | the board's rough window — a _guide_, not authoritative (real timing comes from TTS word timestamps)                                    |
+| `**Delivery:**`                 | per-line delivery note                                                                                                                  |
+| indented block                  | the **spoken text** — the only part fed to TTS                                                                                          |
+
+## Example
+
+```markdown
+# SCRIPT — acme-launch
+
+**Voice:** Rachel (ElevenLabs)
+**Voice settings:** stability 0.35 · similarity 0.75 · style 0.20
+**Voice direction:** Confident, warm, a little playful.
+
+---
+
+## Line 1 — Hook (Frame 1)
+
+**Time:** 0.0 – 3.0s
+**Delivery:** Land the promise on the beat.
+
+    Ship a launch video in an afternoon.
+
+## Line 2 — The problem (Frame 2)
+
+**Time:** 3.0 – 7.0s
+**Delivery:** Wry, a touch tired.
+
+    The old way? Prompt, wait twenty minutes, get something that misses.
+```
+
+## To TTS
+
+Feed each line's spoken text to the provider documented in
+`media-use/audio/references/tts.md`. The `hyperframes tts` command is
+Kokoro-only; use its `--voice` flag, or use the bundled HeyGen helper when word
+timestamps are required. Real per-word timing replaces the `**Time:**` guides.

package/dist/skills/hyperframes/references/storyboard-format.md

@@ -0,0 +1,130 @@
+# Storyboard format — `STORYBOARD.md` + parsed manifest
+
+Defines the storyboard's **base data format** only: the `STORYBOARD.md` file shape and the `StoryboardManifest` it parses into. How a workflow _generates_ a storyboard lives in that workflow; the optional narration/TTS file (`SCRIPT.md`) is a separate concern owned by the TTS step, not here.
+
+A storyboard is the **plan layer** for a video — an ordered set of **frames** (key moments) in one markdown file. HyperFrames Studio renders it as a contact sheet (the Storyboard view, available by default in every Studio session). Parser: `@hyperframes/core/storyboard` → `StoryboardManifest`; read API: `GET /api/projects/<id>/storyboard`.
+
+## Frontmatter (global direction)
+
+YAML block at the top. Unknown keys are kept under `globals.extra`.
+
+| Key        | Meaning                                                           | Example                                   |
+| ---------- | ----------------------------------------------------------------- | ----------------------------------------- |
+| `format`   | Canvas size                                                       | `1920x1080`                               |
+| `duration` | The brief's rough length expectation (advisory, not a hard limit) | `22s`                                     |
+| `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`                              |
+
+Set `duration` from the brief's `length` when the storyboard is first written. It is an expectation, not a gate: assembly reports where the cut actually lands against it and flags a large gap — judge whether the drift serves the piece, and update the value when the intended length genuinely changes.
+
+## Per-frame sections
+
+One `## Frame N — Title` heading per frame (`Frame` / `Beat` / `Scene` accepted at H2/H3). Metadata as `- key: value` bullets; everything below them until the next heading is the free-form **narrative**.
+
+| Key             | Meaning                                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------- |
+| `status`        | `outline` → `built` → `animated` (defaults `outline`)                                                         |
+| `src`           | project-relative path to the frame's HTML sub-composition (the tile poster renders from it)                   |
+| `duration`      | e.g. `4s`                                                                                                     |
+| `transition_in` | `crossfade` / `cut` / `wipe` … (alias `transition`)                                                           |
+| `scene`         | one-line contact-sheet caption (aliases `description` / `summary` / `caption`)                                |
+| `voiceover`     | the frame's narration _guide_ (aliases `vo` / `voice_over` / `narration`)                                     |
+| `poster`        | seconds to seek for the tile poster (past the intro animation)                                                |
+| _any other key_ | kept verbatim under the frame's `extra` — a workflow carries its own per-frame data (effects, assets, …) here |
+
+## Parsed manifest
+
+The parser is **lenient**: it never throws and records anything surprising as a `warning`.
+
+```
+StoryboardManifest {
+  globals: { format?, message?, arc?, audience?, extra: {…} }
+  frames: Array<{
+    index, number?, title?,
+    status,                       // "outline" | "built" | "animated"
+    src?, duration? / durationSeconds?, transitionIn?,
+    scene?, voiceover?, poster?,
+    narrative,                    // markdown below the metadata
+    extra: {…}                    // unknown keys, preserved
+  }>
+  warnings: Array<{ message, line?, frameIndex? }>
+}
+```
+
+The read API also adds `srcExists` per frame and attaches the optional `SCRIPT.md` payload when present.
+
+## `SCRIPT.md` (out of scope here)
+
+Optional, free-form, **not parsed into the manifest** — the locked-narration file that drives TTS. Its format is defined in `references/script-format.md`, and it is absent for videos with no narration/TTS. The per-frame `voiceover` above is the storyboard's own narration guide.
+
+## Frame comments — `.hyperframes/frame-comments.json`
+
+The storyboard review's **structured feedback channel** — the file Studio's per-frame comment boxes write on submit (chat feedback follows the same rule — `brief-contract.md` § 1, the comments channel). Like `SCRIPT.md`, it is a sibling of the storyboard, not parsed into the manifest.
+
+```json
+{
+  "version": 1,
+  "pass": "sketch",
+  "submitted_at": "2026-07-09T12:04:00Z",
+  "comments": [
+    {
+      "frame": 3,
+      "src": "compositions/frames/03-mechanism.html",
+      "title": "Mechanism",
+      "text": "Swap the bar chart for a before/after slider."
+    }
+  ]
+}
+```
+
+| Field                    | Meaning                                                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `pass`                   | which review the batch belongs to: `storyboard` (text layer) / `sketch` (static frames) / `final` (assembled video) |
+| `comments[].frame`       | the frame's 1-based `index` in the manifest — the key                                                               |
+| `comments[].src` `title` | copied from the frame at submit time — if frames get reordered after submit, the mismatch shows                     |
+| `comments[].text`        | the feedback, verbatim                                                                                              |
+
+Lifecycle — the whole contract: a workflow finding this file at a checkpoint treats it as the revision feedback — **revise exactly the frames named, delete the file, re-present**. Writers create it only on submit; it never lingers across rounds.
+
+## Example
+
+```markdown
+---
+format: 1920x1080
+message: "Ship a launch video in an afternoon"
+arc: Hook → Problem → Solution → Proof → CTA
+audience: indie devs on X
+---
+
+## Frame 1 — Hook
+
+- scene: Big type punches in on the beat
+- duration: 3s
+- poster: 2s
+- transition_in: cut
+- status: animated
+- voiceover: "Ship a launch video in an afternoon."
+- src: compositions/frames/01-hook.html
+
+Open cold on the promise. This is the thesis — everything after pays it off.
+
+## Frame 2 — The problem
+
+- scene: A 20-minute timer spins on a stack of rejected takes
+- duration: 4s
+- transition_in: crossfade
+- status: built
+- voiceover: "The old way? Prompt, wait twenty minutes, get something that misses."
+- src: compositions/frames/02-problem.html
+
+The old way: prompt, wait, get something that misses. Establish the pain we remove.
+```
+
+## Notes
+
+- A frame with `status: outline` and no built `src` renders as an outline placeholder.
+- `built` is the middle rung: the frame's HTML exists and its **layout is confirmed** (a wireframe sketch or better) — motion not yet added. Studio chips it blue.
+- The process that walks these statuses — plan, sketch, build, each pass reviewed on the board — is `review-loop.md`.
+- Multi-line `voiceover` values collapse to one line on save.

package/dist/skills/hyperframes/references/subagent-dispatch.md

@@ -0,0 +1,35 @@
+# Subagent dispatch — harness adapter
+
+The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video` / `motion-graphics` / `general-video`) describe subagent dispatch in harness-neutral verbs. This file maps those verbs to the primitives of whatever agent harness you are running on. Read it once per run, before the first dispatch; everything else in the workflows (dispatch packets, file artifacts, exit-code gates, Resume tables) is harness-independent and needs no translation.
+
+## The contract (identical on every harness)
+
+- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named role file** (a builder-assembled payload like `.hyperframes/frame-packets/_role.md`, or a workflow's `sub-agents/<role>.md`) followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
+- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
+- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
+
+## Concurrency cap → batching rule (cap never changes scope)
+
+A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
+
+- When the harness queues excess children internally, submit **all N at once** and let the queue drain.
+- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
+
+## Harness mapping
+
+Use the current harness's native delegation and waiting tools when they are available. The workflow contract stays the same:
+
+- **DISPATCH** sends the complete role file and dispatch context to one worker.
+- **Parallel fan-out** starts independent workers concurrently up to the harness limit.
+- **WAIT** verifies the expected artifacts on disk, not only a completion notification.
+- **Re-dispatch** starts a fresh worker with the same context plus the gate failure.
+
+When native delegation is unavailable, use the existing fallback ladder: launch headless CLI workers that share the project filesystem, then fall back to inline serial execution.
+
+On Codex, native delegation requires the user's explicit permission. Fold a one-line request into the workflow's first existing user pause before dispatch; a standing grant in `AGENTS.md` or the kickoff prompt also counts. Without it, use the fallback ladder rather than silently skipping work.
+
+## Vocabulary mapping
+
+- A request to work "in the background" means dispatch concurrently when the harness supports it.
+- Load a named skill through the harness's skill mechanism, or read `<skills-root>/<skill>/SKILL.md` directly.
+- Map generic read, write, edit, and shell verbs to the current harness's equivalent tools.

package/dist/skills/hyperframes/scripts/lib/frame-packets-core.mjs

@@ -0,0 +1,212 @@
+// Shared frame-packet builder — the script half of the frame-worker core/delta split.
+//
+// Each narrative workflow ships a thin `scripts/frame-packets.mjs` wrapper that pins
+// its own paths (animation skill, role delta, design-truth resolution, extra packet
+// sections) and delegates everything else here, exactly as the markdown half already
+// does with `references/frame-worker-core.md` + each workflow's delta. One owner for
+// the packet-building logic; the wrappers own only what genuinely differs per workflow.
+//
+// Packet (<frame_id>.md) = project inputs + the frame's exact `## Frame N` block
+// + the blueprint body + every cited rule recipe, inlined — so a worker never opens
+// the shared STORYBOARD.md or any skill document. Cited motions are found
+// mechanically: the explicit `- rules:` field when present, plus every valid rule id
+// (a filename under the animation skill's rules/) mentioned in the block.
+//
+// _role.md = frame-worker-core.md + the workflow's sub-agents/frame-worker.md,
+// concatenated verbatim — the complete worker role, assembled from the two source
+// documents so nothing is hand-maintained twice.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function field(block, name) {
+  const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
+  return match?.[1]?.trim() ?? null;
+}
+
+export function splitFrames(storyboard) {
+  const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
+  return matches.map((match, index) => {
+    const start = match.index;
+    const end = matches[index + 1]?.index ?? storyboard.length;
+    return {
+      heading: match[1].trim(),
+      block: storyboard.slice(start, end).trim(),
+    };
+  });
+}
+
+export function frameId(frame) {
+  const src = field(frame.block, "src");
+  if (!src) throw new Error(`${frame.heading}: missing src`);
+  return basename(src).replace(/\.html?$/i, "");
+}
+
+export function selectedFile(path, heading) {
+  if (!path || !existsSync(path)) return "";
+  return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
+}
+
+function escapeRegExp(id) {
+  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function knownRuleIds(animationDir) {
+  const rulesDir = join(animationDir, "rules");
+  if (!existsSync(rulesDir)) {
+    console.warn(
+      `frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
+    );
+    return [];
+  }
+  return readdirSync(rulesDir)
+    .filter((name) => name.endsWith(".md"))
+    .map((name) => name.replace(/\.md$/, ""));
+}
+
+export function citedRules(block, ruleIds) {
+  const explicit = (field(block, "rules") ?? "")
+    .split(/[,\s]+/)
+    .map((rule) => rule.trim())
+    .filter(Boolean);
+  const mentioned = ruleIds.filter((id) =>
+    new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
+  );
+  return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
+}
+
+// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
+// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
+// the filename. Parse the field into the id it names (or null for `compose`), so
+// no caller ever resolves a raw field value against the blueprints directory.
+export function blueprintId(block) {
+  const raw = field(block, "blueprint");
+  if (!raw) return null;
+  const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
+  return id && id.toLowerCase() !== "compose" ? id : null;
+}
+
+export function resourceSections(block, { animationDir, ruleIds, frameId }) {
+  let sections = "";
+  const blueprint = blueprintId(block);
+  if (blueprint) {
+    const blueprintsDir = join(animationDir, "blueprints");
+    const path = join(blueprintsDir, `${blueprint}.md`);
+    // A blueprint that resolved to nothing used to inline an empty string, so the
+    // packet shipped without the one document the frame was designed against and
+    // the run still reported success. Name it instead — but only when the library
+    // is actually there to be named against. The animation skill installs on
+    // demand, so an absent blueprints/ is a missing install, not a bad id, and it
+    // degrades with a warning exactly like an absent rules/ (see knownRuleIds).
+    if (!existsSync(blueprintsDir)) {
+      console.warn(
+        `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
+      );
+    } else if (!existsSync(path)) {
+      throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
+    } else {
+      sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
+    }
+  }
+  for (const rule of citedRules(block, ruleIds)) {
+    sections += selectedFile(
+      join(animationDir, "rules", `${rule}.md`),
+      `Selected motion rule: ${rule}`,
+    );
+  }
+  return sections;
+}
+
+export function buildRolePayload({ corePath, deltaPath, outDir }) {
+  const core = readFileSync(corePath, "utf8").trim();
+  const delta = readFileSync(deltaPath, "utf8").trim();
+  const role = `${core}\n\n---\n\n${delta}\n`;
+  mkdirSync(outDir, { recursive: true });
+  const path = join(outDir, "_role.md");
+  writeFileSync(path, role);
+  return { path, bytes: Buffer.byteLength(role) };
+}
+
+export function buildFramePackets({
+  projectDir,
+  storyboardPath = join(projectDir, "STORYBOARD.md"),
+  outDir = join(projectDir, ".hyperframes", "frame-packets"),
+  maxPacketBytes = 48_000,
+  animationDir,
+  corePath,
+  deltaPath,
+  // Per-workflow hooks (all optional):
+  // designTruthLine(projectDir) -> the packet's design-truth input line
+  // validateFrame(frame, id)   -> throw to reject a frame before packing
+  // extraSections(block)       -> extra packet sections appended after the rule recipes
+  designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
+  validateFrame,
+  extraSections,
+}) {
+  const storyboard = readFileSync(storyboardPath, "utf8");
+  const frames = splitFrames(storyboard);
+  if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
+  const ruleIds = knownRuleIds(animationDir);
+
+  const packets = frames.map((frame) => {
+    const id = frameId(frame);
+    if (validateFrame) validateFrame(frame, id);
+    const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
+    const bytes = Buffer.byteLength(packet);
+    if (bytes > maxPacketBytes) {
+      throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
+    }
+    return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
+  });
+
+  mkdirSync(outDir, { recursive: true });
+  for (const { path, packet } of packets) writeFileSync(path, packet);
+  buildRolePayload({ corePath, deltaPath, outDir });
+  return packets.map(({ packet: _packet, ...result }) => result);
+}
+
+export function flag(argv, name, fallback) {
+  const index = argv.indexOf(`--${name}`);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+}
+
+// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
+// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
+// a raw compare silently skips main() when invoked through any symlinked path.
+export function isMainModule(importMetaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+  } catch {
+    return false;
+  }
+}
+
+export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
+  const argv = process.argv.slice(2);
+  const projectDir = resolve(flag(argv, "project", "."));
+  const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
+  try {
+    const packets = build({
+      projectDir,
+      storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
+      outDir,
+    });
+    const role = buildRole({ outDir });
+    console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
+    for (const packet of packets)
+      console.log(`  ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
+    console.log(`  worker role: ${role.bytes} bytes → ${role.path}`);
+  } catch (error) {
+    console.error(`✗ frame packets: ${error.message}`);
+    process.exit(1);
+  }
+}

package/dist/skills/hyperframes-cli/SKILL.md

@@ -15,15 +15,15 @@ Run commands as `npx hyperframes ...` unless project instructions provide a wrap
 
 ## Development loop
 
-1. **Scaffold:** `npx hyperframes init <project>` or capture a site. In non-TTY mode, pass `--non-interactive --example=<name>`.
+1. **Scaffold:** `npx hyperframes init <project>` (centered blank). Or capture a site. Pass `--example=<name>` only to start from a named example.
 2. **Find the move:** before authoring motion by hand, search for a primitive that already does it: `npx hyperframes catalog --query "reveal a headline one line at a time"`. Ask for the effect you want rather than the mechanism you have in mind. Install with `npx hyperframes add <name>` (see `/hyperframes-registry`). Author by hand only once nothing fits.
 3. **Author:** write the composition using `/hyperframes-core`.
 4. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes.
 5. **Run the final gate:** run `npx hyperframes check`; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add `--snapshots` for annotated overview frames and finding crops.
 6. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene.
 7. **Open the final Studio preview:** run `npx hyperframes preview --background`, verify the URL returns HTTP 200, hand the timeline project URL to the user, and ask whether to revise or render. Keep it alive until review ends.
-8. **Render only after approval:** use draft quality for iteration and high quality for delivery.
-9. **Verify the output:** confirm the file exists, is non-empty, and has a plausible duration.
+8. **Render only after approval:** use `--quality draft` while iterating, `--quality looks` for the first real encode (the CLI default), and `--quality delivery` for final delivery.
+9. **Verify the output:** confirm the file exists and is non-empty. Read the render summary's second line (`beginframe` vs `screenshot`, GPU, stage timings). `screenshot` + `software gpu` on Linux is the slow path. `ffprobe -v error -show_format -show_streams` and compare duration (and fps if the brief set it) to the root `data-duration`.
 
 ## Mandatory creator-edit cross-references
 
@@ -46,9 +46,9 @@ npx hyperframes lint
 # Required final gate; includes lint.
 npx hyperframes check
 npx hyperframes preview --background
-npx hyperframes render --quality high --output out.mp4
+npx hyperframes render --quality looks --output out.mp4
 test -s out.mp4
-ffprobe -v error -show_format out.mp4
+ffprobe -v error -show_format -show_streams out.mp4
 ```
 
 `check` runs lint first, then uses one browser session and one seek pass to audit runtime errors, failed requests, layout, `*.motion.json` assertions, and WCAG contrast. Persistent findings gate the exit code; transient entrance or exit findings are informational. Use `--strict` to gate warnings. `validate`, `inspect`, and `layout` remain aliases for compatibility but must not appear in new instructions or scripts.
@@ -62,7 +62,7 @@ Do not confuse these states:
 | Storyboard board          | Before composition checks, only when `storyboard: yes` | Review plan cards and wireframe sketches. Open `?view=storyboard#project/<name>`. |
 | Final composition preview | After `check` passes                                   | Review the assembled timeline before render. Open `#project/<name>`.              |
 
-The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes-core/references/review-loop.md`.
+The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes/references/review-loop.md`.
 
 ## Sub-composition smoke test
 
@@ -90,7 +90,7 @@ Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timel
   npx hyperframes doctor --json | jq -e '.ok' >/dev/null
   ```
 
-- Non-TTY mode is automatic. `init` requires `--example` there; use `--non-interactive` to force deterministic behavior on a TTY.
+- Non-TTY mode is automatic and scaffolds the centered blank. Pass `--example` only to start from a named example. Use `--non-interactive` to force flag-only mode on a TTY.
 - Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop.
 - Use `--strict`, `--strict-all`, and `--strict-variables` when the corresponding warnings, variables, or CI conditions must gate the render.
 - JSON paths redact the home directory as `$HOME`; do not try to reverse the redaction.
@@ -112,7 +112,8 @@ Use `selection.target.hfId` when available, otherwise its selector and source fi
 | Need                                     | Command                                                                       |
 | ---------------------------------------- | ----------------------------------------------------------------------------- |
 | Fast local iteration                     | `npx hyperframes render --quality draft`                                      |
-| Final local delivery                     | `npx hyperframes render --quality high --output out.mp4`                      |
+| First real encode                        | `npx hyperframes render --quality looks --output out.mp4`                     |
+| Final local delivery                     | `npx hyperframes render --quality delivery --output out.mp4`                  |
 | Reproducible container render            | `npx hyperframes render --docker --strict --output out.mp4`                   |
 | Local variable-driven batch render       | `npx hyperframes render --batch rows.json --output "renders/{name}.mp4"`      |
 | HeyGen-hosted zero-infrastructure render | `npx hyperframes cloud render`                                                |

package/dist/skills/hyperframes-cli/references/init-and-scaffold.md

@@ -7,18 +7,18 @@ Scaffolding commands. Use these instead of creating files by hand — they set u
 ## init
 
 ```bash
-npx hyperframes init my-video                                    # TTY: interactive wizard
+npx hyperframes init my-video                                    # centered blank (TTY: wizard)
 npx hyperframes init my-video --example warm-grain               # pick an example
-npx hyperframes init my-video --example blank --resolution portrait
+npx hyperframes init my-video --resolution portrait
 npx hyperframes init my-video --video clip.mp4                   # with video file
 npx hyperframes init my-video --audio track.mp3                  # with audio file
-npx hyperframes init my-video --example blank --tailwind         # Tailwind v4 browser runtime
-npx hyperframes init my-video --non-interactive --example blank  # CI/agents — flag-only
+npx hyperframes init my-video --tailwind                         # Tailwind v4 browser runtime
+npx hyperframes init my-video --non-interactive                  # CI — flag-only, same blank
 ```
 
-**Default depends on TTY**: in a terminal, the CLI prompts for example/options. Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and **requires `--example`** (the CLI errors with a usage example if missing). Pass `--non-interactive` to force flag-only mode even on a TTY.
+**Default depends on TTY**: in a terminal, the CLI prompts for example/options (default: centered blank). Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and scaffolds that blank. Pass `--example` only to start from a named example. Pass `--non-interactive` to force flag-only mode on a TTY.
 
-Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`, `vscode-theme-visualizer`. (The closed set of `hyperframes:example` items in `registry/registry.json`. `hyperframes catalog` does not list examples — its `--type` takes only `block` or `component` — so this list has no live equivalent and is checked by `bun run lint:skills`.)
+Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`, `vscode-theme-visualizer`. (The closed set of `hyperframes:example` items in `registry/registry.json` plus the bundled `blank` template. `hyperframes catalog` does not list examples — its `--type` takes only `block` or `component` — so this list has no live equivalent and is checked by `bun run lint:skills`.)
 
 Other useful flags: