@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/hyperframes-core/references/data-attributes.md

@@ -0,0 +1,70 @@
+# Data Attributes Reference
+
+Every HyperFrames composition uses `data-*` attributes to declare timing and structure to the framework. This is the full attribute table — pair with `tracks-and-clips.md` for the rules behind `data-track-index`.
+
+## Composition Root
+
+Every renderable composition needs one root element:
+
+| Attribute                    | Required      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-composition-id`        | Yes           | Unique ID. Must match the animation registry key on `window.__timelines`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `data-width` / `data-height` | Yes           | Pixel frame size. Common values: `1920x1080`, `1080x1920`, `1080x1080`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `data-duration`              | Conditional\* | Render duration in seconds (total length / frame count), not the GSAP timeline length. **Read once at compile time, like `data-width` / `data-height`**: a static root `data-duration` is locked before scripts run, so a script (`root.setAttribute("data-duration", ...)`) or a `--variables`-driven value cannot change the render length. To vary length per render, author the root `data-duration` directly. (A clip's `data-duration` is different: re-read from the live DOM, so scripts/variables can drive it.) Only when the root omits `data-duration` does the renderer derive total length from the live DOM / timeline after scripts run. |
+| `data-fps`                   | No            | Optional frame rate hint. CLI render flags can override output fps.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `data-composition-variables` | No            | JSON array of variable declarations (on `<html>`). See `variables-and-media.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+\*`data-duration` is optional whenever the runtime can auto-infer duration: a registered GSAP timeline, a finite CSS animation, a finite WAAPI `element.animate()`, or a registered Lottie animation. It is **required** for Three.js (no auto-inference), for infinite/unbounded CSS or WAAPI animations, and for any composition with no GSAP timeline and no animation signal at all. `npx hyperframes lint` enforces this (`root_composition_missing_duration_source`). See `determinism-rules.md` → "Duration Contract For Non-GSAP Runtimes" for the per-runtime breakdown.
+
+The root should be `position: relative`, have explicit pixel dimensions, and hide overflow unless intentionally composing outside the frame.
+
+## Clip Attributes
+
+Timed child elements are clips. **`class="clip"` is required on visible timed elements** (`<div>`, `<img>`, etc.) — without it the runtime keeps the element visible for the whole composition, ignoring `data-start` / `data-duration`. Omit on `<video>` (framework manages visibility directly) and `<audio>` (no visual).
+
+**Clips must be DIRECT children of the composition root.** A clip nested inside a wrapper `<div>` is not registered — most visibly, a `<video>` in a wrapper is never seeked/decoded and renders black. To wrap/transform a clip, put the wrapper _inside_ the clip, or animate the clip element itself; do not wrap the clip. (`<video>`/`<audio>` additionally must be at the **host** root, never in a sub-comp `<template>` — see `variables-and-media.md`.)
+
+| Attribute          | Required                                        | Meaning                                                                                                                           |
+| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | Yes                                             | Stable DOM ID for linting, timeline targets, and debugging.                                                                       |
+| `data-start`       | Yes                                             | Start time in seconds, or a supported clip-time reference.                                                                        |
+| `data-duration`    | Required for `div`, `img`, and sub-compositions | Duration in seconds. Video/audio can default to media duration when known.                                                        |
+| `data-track-index` | Yes                                             | Timeline track. Clips on the same track must not overlap.                                                                         |
+| `data-media-start` | No                                              | Offset into the media source, in seconds.                                                                                         |
+| `data-volume`      | No                                              | Static audio volume, `0` to `1`, default `1`. For fades, animate `volume` on the timeline instead (see `variables-and-media.md`). |
+| `data-has-audio`   | No (`<video>` only)                             | `"true"` to declare the video carries an audio track when auto-detection would miss it.                                           |
+
+**Visibility window is inclusive of both ends.** A clip shows while `start ≤ t ≤ start + duration` — it still renders at exactly `t = start + duration`, so the final frame holds the animation's resolved end state (the runtime does not hide it one frame early). A reveal/entrance that lands on `data-duration` is therefore visible on the last frame; you do not need to finish it _before_ `data-duration` just to guarantee the end state renders. (Climax-dwell guidance in `/hyperframes-animation` is about pacing, not this boundary.)
+
+## Sub-Composition Host Attributes
+
+When a clip is a sub-composition host (loads another composition file):
+
+| Attribute                    | Required | Meaning                                                                |
+| ---------------------------- | -------- | ---------------------------------------------------------------------- |
+| `data-composition-id`        | Yes      | The internal composition ID of the loaded file.                        |
+| `data-composition-src`       | Yes      | Path to the sub-composition HTML file.                                 |
+| `data-width` / `data-height` | Yes      | Render dimensions for the sub-composition instance.                    |
+| `data-variable-values`       | No       | Per-instance variable overrides as JSON. See `variables-and-media.md`. |
+
+See `sub-compositions.md` for the full wiring pattern.
+
+## Authoring Hints
+
+- `id="root"` — template convention used by scaffolds and the transition catalog so CSS can target the composition root with `#root` instead of `[data-composition-id="main"]`. Not required by the runtime, but consistent with the rest of the ecosystem.
+- `class="clip"` — required runtime visibility marker on visible timed elements (`<div>`, `<img>`, …). See Clip Attributes above.
+- `data-layout-allow-overflow` — tells `hyperframes inspect` that overflow on this element (or its descendants) is intentional. Notes:
+  - `inspect` measures `getBoundingClientRect` at sampled timestamps, not rendered pixels — `overflow: hidden` clips the visual but does **not** suppress an `inspect` overflow finding. This attribute is the escape hatch; CSS overflow is not.
+  - Can be set on the composition **root** as well as on any child. When the cited offender is `div.<comp>-root inside div.<comp>-root` (the root reports its own children's union as overflowing), the fix goes on the root, not on individual text descendants — shrinking font sizes will not converge.
+  - In a multi-scene `group_wN.html` (continue runs), every scene-local element stays in the DOM during the other scenes' time windows; the layout-box union almost always overflows the canvas during morph seams. Mark the root and every scene-local primary/supporting element with this attribute **at construction**, not after `inspect` flags it.
+  - **Blast radius — it silences more than `inspect`.** The attribute is inherited down the subtree (the perception probe walks ancestors), so it also suppresses the rendered-perception checks `text-clipping`, `content-cramped-container`, and `foreground-over-panel` for every descendant. Putting it on a persistent panel that also hosts real foreground content disables collision checks on that content for the panel's whole lifetime. Prefer the narrowest opt-out: scope it to the smallest decorative wrapper, or use per-element `data-layout-bleed="true"` for one intentional primary-text crop. The two canvas/edge checks `primary-offscreen` and `foreground-over-panel` deliberately run **even under** allow-overflow, so it cannot hide a wordmark sliced by the frame or text bleeding onto a panel edge.
+- `data-layout-ignore` — exclude this element from layout audits entirely.
+
+## Legacy / Removed Attributes
+
+These names appear in older projects and examples. Use the current names when authoring or editing:
+
+| Legacy name  | Use instead        |
+| ------------ | ------------------ |
+| `data-layer` | `data-track-index` |
+| `data-end`   | `data-duration`    |

package/.agents/skills/hyperframes-core/references/determinism-rules.md

@@ -0,0 +1,68 @@
+# Determinism, Animation Runtime, and Layout
+
+HyperFrames seeks compositions frame-by-frame. Every frame must be reproducible from its time value alone — same input time → same pixels. Three contracts enforce this: the **animation runtime contract**, the **determinism rules**, and the **layout contract**.
+
+## Animation Runtime Contract
+
+GSAP is the primary runtime. The core requirement is generic: animation state must be seekable from HyperFrames time.
+
+For GSAP:
+
+- Create the timeline **synchronously** during page initialization.
+- Use `gsap.timeline({ paused: true })`.
+- Register it on `window.__timelines["<composition-id>"]`.
+- The key must match `data-composition-id` on the composition root.
+- **Do not** call `tl.play()` for render-critical motion.
+- **Do not** build timelines inside `async`, `Promise`, `setTimeout`, or event handlers — the renderer can sample before they finish.
+- **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
+- **Do not** `gsap.set()` clip elements from later scenes — they are not in the DOM at page load. Use `tl.set(selector, vars, time)` inside the timeline at or after the clip's `data-start`.
+
+Use the `hyperframes-animation` skill for tween syntax, position parameters, eases, and performance rules.
+
+### Duration Contract For Non-GSAP Runtimes
+
+The render engine needs a positive total duration before it will capture a single frame — without one, capture fails outright with "Composition has zero duration." A GSAP timeline supplies this automatically. CSS, WAAPI, and Lottie compositions have no timeline object, so the runtime infers duration itself:
+
+- **CSS**: longest `animation-delay` + `animation-duration` × finite `animation-iteration-count` across animated elements (offset by each element's `data-start`). `animation-iteration-count: infinite` cannot be inferred.
+- **WAAPI**: longest `element.animate()` effect's `getComputedTiming().endTime`. Infinite `iterations` cannot be inferred.
+- **Lottie**: the registered animation's native length (`totalFrames / frameRate`, or the dotLottie player's own `duration`) — always finite regardless of `loop`.
+- **Three.js**: **not inferable**. The `three` adapter only forwards time via `hf-seek` — it has no `AnimationClip`/`AnimationMixer` inspection.
+
+`data-duration` on the root `[data-composition-id]` element is therefore optional whenever every non-GSAP animation on the page is finite (CSS/WAAPI with finite iteration counts, or Lottie). It is **required** when: the composition has an infinite/unbounded CSS or WAAPI animation, the composition uses Three.js, or there is no GSAP timeline and no animation signal at all for any adapter to discover. `npx hyperframes lint` enforces exactly this (`root_composition_missing_duration_source`) — see the runtime/adapter-specific docs under `hyperframes-animation/adapters/` for the full contract per runtime.
+
+## Determinism Rules
+
+Rendered frames must be reproducible from the requested time. Do **not** use any of the following for visual state:
+
+- `Date.now()`, `performance.now()`, or any render-time clock.
+- Unseeded `Math.random()`. Use a seeded PRNG if random-looking placement is needed.
+- Render-time network fetches for required assets. Inline or pre-bundle them.
+- Hover, scroll, pointer, or focus state. The renderer has no input events.
+- Infinite loops such as `repeat: -1`. Compute a finite count: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)` — **`floor`, not `ceil`** (`ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint; `max(0, …)` avoids a negative repeat = infinite).
+
+Also avoid:
+
+- Animating anything outside the visual-property allowlist: `opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms. Never animate `display` or `visibility` — use opacity/transforms and timed clip visibility instead.
+- Animating the same property on the same element from multiple timelines at the same time — GSAP's overwrite behavior is order-dependent and can flip between renders.
+
+## Layout Contract
+
+Build the visible end-state in static HTML and CSS first, then animate from/to that state.
+
+- The composition root has fixed pixel frame dimensions.
+- **The root composition's total duration (render length / frame count) is fixed at compile time**, read once from the static root `data-duration` before scripts run, like `data-width` / `data-height`. A script or `--variables` value that rewrites the root `data-duration` afterward is ignored. To vary render length per output, author the root `data-duration` directly. (A _clip's_ own `data-duration` is re-read from the live DOM, so scripts/variables can still drive clip lengths. Only when the root omits `data-duration` does the renderer probe the live DOM / timeline for total length.)
+- Scene containers should fill the scene with `width: 100%; height: 100%; box-sizing: border-box`.
+- Use padding, flex, grid, and `max-width` for layout. Avoid positioning main content with hardcoded `top`/`left` offsets when a layout container can do it.
+- Use `position: absolute` for layers and decorative elements, not as the default content-layout strategy.
+- Prefer transforms and opacity for animation.
+- Keep text inside its intended container. For dynamic text, use `max-width`, wrapping, or `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`.
+- For text measurement without DOM reflow, use `window.__hyperframes.pretext`: `pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)`. Pure arithmetic, ~0.0002 ms per call — safe for per-frame text reflow, shrinkwrap containers, and computing layout before render. `fitTextFontSize` is built on it.
+- **Do not** use `<br>` in body text. Forced breaks ignore the actual rendered font width and produce an extra break when the line already wraps naturally, causing overlap. Let text wrap via `max-width`. Exception: short display titles where each word is deliberately on its own line.
+- **Transformed elements must be block-level + sized.** `transform`/`scaleX`/`scaleY` is a no-op on an inline `<span>`, and scaling an auto-width (0px) element shows nothing → invisible bars/fills. Give them `display: block`/`inline-block`/flex-item **and** a real `width`/`height` (e.g. `width: 100%` inside a sized parent). _(silent — lint/inspect miss it.)_
+- **Absolutely-positioned decoratives that pulse or overshoot** (`yoyo` scale, `back.out`) need clearance at their **peak** size and must not straddle an `overflow: hidden` edge — else they overlap a neighbor or get clipped. Position for the largest frame, not the resting one. _(silent.)_
+
+## Why This Matters
+
+The renderer takes a time value and produces a pixel buffer. There is no notion of "playback" — every frame is a fresh seek. Any state that depends on having reached this frame _through_ a prior frame (timers, accumulated state, event-driven animations) will desync when the renderer samples out of order or in parallel.
+
+If you find yourself reaching for `setTimeout`, `requestAnimationFrame`, or `addEventListener` to drive a visual, rebuild it as a tween on the timeline instead.

package/.agents/skills/hyperframes-core/references/full-screen-motion.md

@@ -0,0 +1,62 @@
+# Full-Screen Motion Pattern
+
+For full-frame motion (continuous backgrounds, color washes, full-bleed visual states that span multiple clips), prefer a **shared background layer + transparent timed content layers** over stacked opaque scene backgrounds.
+
+## Why
+
+Stacking opaque scene divs means every scene change has to repaint the entire frame, every cross-scene visual continuity has to be faked, and every "global" state (a hue shift, a vignette, a film grain) has to be duplicated on every scene. A shared background layer driven by the seekable timeline gives you one continuous visual surface and makes scenes themselves cheap and transparent.
+
+## Pattern
+
+```html
+<div id="root" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
+  <!-- Shared background — NOT a clip. Always visible. Driven by the timeline. -->
+  <div id="bg" class="full-bleed"></div>
+
+  <!-- Timed content layers — transparent backgrounds. -->
+  <section
+    id="scene1"
+    class="clip transparent"
+    data-start="0"
+    data-duration="6"
+    data-track-index="1"
+  >
+    <!-- content -->
+  </section>
+  <section
+    id="scene2"
+    class="clip transparent"
+    data-start="6"
+    data-duration="14"
+    data-track-index="1"
+  >
+    <!-- content -->
+  </section>
+</div>
+
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  // Drive the shared background from the seekable timeline.
+  tl.to("#bg", { backgroundColor: "#0a1530", duration: 6, ease: "sine.inOut" }, 0);
+  tl.to("#bg", { backgroundColor: "#1a0a30", duration: 14, ease: "sine.inOut" }, 6);
+
+  // Scene-local animations stay transparent on top.
+  tl.from("#scene1 h1", { y: 48, opacity: 0, duration: 0.6 }, 0.2);
+
+  window.__timelines["main"] = tl;
+</script>
+```
+
+## Rules
+
+- **The background is not a clip.** No `data-start` / `data-duration` / `data-track-index`. It exists for the whole composition.
+- **Content scenes have transparent backgrounds.** Whatever you put in the shared `#bg` shows through.
+- **Drive global state from the shared layer.** Hue shifts, vignettes, grain, film-look filters — animate them once on the shared layer, not per-scene.
+- **Do not animate visibility on `.clip` elements.** HyperFrames already shows/hides clips based on `data-start` and `data-duration`. Animating `display` / `visibility` on the clip itself races with the framework's own show/hide. Animate a _child wrapper_ inside the clip instead.
+- **Verify intentional overflow with snapshots.** Before adding `data-layout-allow-overflow` to silence an inspect warning, run `npx hyperframes snapshot` and confirm the overflow is what you want.
+
+## When Not to Use This Pattern
+
+If scenes really are visually disjoint — hard cuts between distinct color worlds with no continuity — the stacked-opaque pattern is fine. The shared-background pattern is for compositions where the background **is part of the motion language**, not just backdrop.

package/.agents/skills/hyperframes-core/references/minimal-composition.md

@@ -0,0 +1,66 @@
+# Minimal Composition
+
+The smallest renderable HyperFrames composition — a standalone (top-level) root with one clip and one tween:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Minimal HyperFrames Composition</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        background: #0b0f14;
+        color: white;
+        font-family: Inter, system-ui, sans-serif;
+      }
+      #root {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        overflow: hidden;
+      }
+      .clip {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+      }
+      h1 {
+        margin: 0;
+        font-size: 96px;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-width="1920"
+      data-height="1080"
+      data-duration="5"
+    >
+      <section id="title-card" class="clip" data-start="0" data-duration="5" data-track-index="1">
+        <h1 id="title">Hello HyperFrames</h1>
+      </section>
+    </div>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      tl.from("#title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0.2);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Required elements:
+
+- Root `<div>` with `data-composition-id`, `data-width`, `data-height`, `data-duration`
+- At least one clip (any element with `data-start`, `data-duration`, `data-track-index`)
+- GSAP timeline created paused, registered on `window.__timelines["<composition-id>"]`
+
+This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.

package/.agents/skills/hyperframes-core/references/script-format.md

@@ -0,0 +1,49 @@
+# `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 `hyperframes-media` → `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 `npx hyperframes tts` (pin `--voice` / `--provider` from the header; capture word timestamps for captions). Real per-word timing replaces the `**Time:**` guides. CLI contract → `hyperframes-media/references/tts.md`.

package/.agents/skills/hyperframes-core/references/storyboard-format.md

@@ -0,0 +1,95 @@
+# 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`                               |
+| `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`                         |
+
+## 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.
+
+## 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.
+- Multi-line `voiceover` values collapse to one line on save.