dsh-hyperframes 0.9.1 → 0.9.2

package/skills/hyperframes/references/skill-lifecycle.md

@@ -1,19 +1,23 @@
 # Skill installation and freshness
 
-Read this reference when installing or updating skills, diagnosing unexpected workflow behavior, or running HyperFrames setup in CI.
+Read this reference when installing or updating skills, diagnosing unexpected skill behavior, or running HyperFrames setup in CI.
 
-For a plugin installation, follow [plugin execution rules](plugin-installation.md); the plugin manager owns updates and all workflows are bundled. The commands below apply only to standalone skills.
+For a plugin installation, follow [plugin execution rules](plugin-installation.md); the plugin manager owns updates and every skill is bundled. The commands below apply only to standalone skills.
 
-HyperFrames installs the core set eagerly and workflow skills lazily.
-
-- **Core set:** `/hyperframes`, the `hyperframes-*` domain skills, and `/media-use`.
-- **Workflow skills:** installed when routing selects them through `npx hyperframes skills update <workflow-name>`.
+- **Core set, installed eagerly:** `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry` and `/media-use`.
+- **On demand:** `/figma`, `/slideshow` and `/remotion-to-hyperframes`, installed with `npx hyperframes skills update <name>`.
 
 ## What `init` does
 
-`npx hyperframes init` checks GitHub and refreshes the core set plus other skills already installed. It does not install workflows that have never been used. A current install is a no-op. Offline or rate-limited checks degrade gracefully and do not fail project scaffolding.
+`npx hyperframes init` installs the core set when it is missing and leaves every skill that is already installed as it is: it never refreshes, replaces or removes one. Updating is `npx hyperframes skills update`, run by you. Offline or rate-limited checks degrade gracefully and do not fail project scaffolding.
+
+`--skip-skills` makes `init` leave skills alone. `HYPERFRAMES_SKIP_SKILLS=1` does the same for CI and tests.
+
+`HYPERFRAMES_SKIP_SKILLS=1` also makes `skills update` (bare or named) and bare `skills` exit 0 without installing, so an install pinned to one commit stays pinned.
 
-The `--skip-skills` CLI flag is temporarily ignored. CI and tests may opt out with `HYPERFRAMES_SKIP_SKILLS=1`.
+## Stale-skills notice
+
+After `render`, `lint` and `validate`, the CLI prints `N HyperFrames skills out of date or missing` to stderr when the cached check finds stale skills, so an agent run without a terminal sees it too. It is off in CI, in dev, with `HYPERFRAMES_NO_UPDATE_CHECK=1` and with `HYPERFRAMES_SKIP_SKILLS=1`, and runs with `--json` too, since it only writes stderr and leaves `--json` stdout untouched.
 
 ## Diagnose and update
 
@@ -21,15 +25,25 @@ The `--skip-skills` CLI flag is temporarily ignored. CI and tests may opt out wi
 npx hyperframes skills check
 npx hyperframes skills check --json
 npx hyperframes skills update
-npx hyperframes skills update <workflow-name>
+npx hyperframes skills update <name>
 npx hyperframes skills
 ```
 
-- `skills check` exits non-zero when an installed skill is stale or the core set is incomplete. Workflows available on demand but not installed are not failures.
-- Bare `skills update` refreshes the core set and everything already installed, prunes unpublished skills, and does not expand the workflow set.
-- Named `skills update <name...>` also installs those named workflows or domain skills.
+- `skills check` exits non-zero when an installed skill is stale or the core set is incomplete. Skills available on demand but not installed are not failures.
+- Bare `skills update` refreshes the core set and the HyperFrames skills already installed. It never removes a skill, and it leaves a skill the install record attributes to another publisher alone, even when the name matches one of ours.
+- Named `skills update <name...>` also installs those named skills.
 - Bare `skills` installs the full published set explicitly.
 
-If the HyperFrames CLI is unavailable, use `npx skills add heygen-com/hyperframes --skill <workflow-name>` for one workflow or `npx skills add heygen-com/hyperframes --all` for the full published set.
+If the HyperFrames CLI is unavailable, use `npx skills add heygen-com/hyperframes --skill <name>` for one skill or `npx skills add heygen-com/hyperframes --all` for the full published set.
+
+The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Treat a failed update as a visible tool failure; do not continue from a remembered skill.
+
+## Keep the project's CLI current
+
+A scaffolded project pins `hyperframes@<version>` in its `package.json` scripts so renders stay reproducible; the pin never advances on its own, and a pinned run of an older CLI prints no warning about it. When resuming a project whose scripts carry a pin, probe once before the first render-affecting command:
+
+```bash
+npx hyperframes@latest upgrade --project . --check
+```
 
-The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Treat a failed update as a visible tool failure; do not continue from a remembered workflow contract.
+The probe is read-only and reports the pin against the latest release; keep the explicit `.` — on older CLI releases a bare `--project` followed by another flag consumes that flag as its directory value. When it reports the project behind — or any CLI output already shows it (the stderr notice `This project pins hyperframes@… (latest …)`, or `_meta.updateAvailable: true` in a `--json` result from a pinned script) — apply with `npx hyperframes@latest upgrade --project .`, then verify with `npx hyperframes check`. A passing check confirms the project's compositions still validate on the new version — not that rendered output is frame-identical to the old pin — so a successful bump is never silent: name the old and new version in the run's summary. A project with no composition yet needs no verification. If the check fails, revert the `package.json` change, continue on the pinned version, and report which version the project stays on and why. Act on the signal rather than relaying it to the user; never leave a bumped pin unverified.

package/skills/hyperframes/references/sound.md

@@ -0,0 +1,43 @@
+# Sound
+
+Sound is half of how a film feels, and the viewer notices a silent one before any frame. Every judge of frames misses it, so plan it on purpose.
+
+## 1. The default
+
+- **A film over about 15 s that tells something** (launch, explainer, recap, PR video) gets a music bed and sounds on its visible actions, unless the person asked for silence or it is made to play muted (a looping background, a feed that autoplays without sound: then the type and the pictures carry it alone).
+- **A voiceover** only when the request or the source calls for one (`SKILL.md`).
+- **Each storyline says its sound** in one line (`story.md` §2): the bed's feel and tempo, the one moment the music changes, which actions get effects, or silence and why.
+- **Short pieces** (a title card, a sting under 10 s, captions or overlays on footage that has its own sound) follow the request and the footage.
+
+## 2. The clock
+
+- **Narrated**: the voice is the clock. Time each beat's start to its anchor word; text lands on the word that says it.
+- **Music only**: the music is the clock. Land the payoff and the mark on its strong beats (`npx hyperframes beats`, then `film.md` "On music"); cuts follow the motion, not the drums.
+- Let the sound act out the story when it fits: the old way sits near silence, the music opens when the product appears; the music holds back until the payoff.
+
+## 3. Music
+
+The person's own track first, as given. Else search the catalog (`/media-use`, `bgm`) with the film's feel and tempo, not its subject ("tense minimal pulse building to a bright drop, 120 bpm"), and read a few results before keeping one. Enter at the track's strongest bar, not a quiet intro; end on a bar line with a short fade under the end card.
+
+With no music source (no `heygen` sign-in and no local model), deliver silent and say so in one line with how to add one. Do not spend the run building an audio chain or writing music in code: nobody can hear whether it is good.
+
+## 4. Effects
+
+Few and exact: every effect has a cause on screen, and too many read as a template.
+
+| Sound             | Only on                                        |
+| ----------------- | ---------------------------------------------- |
+| click             | a real cursor click on screen                  |
+| whoosh            | a scene cut, or a large card moving fast       |
+| soft key tick     | text arriving letter by letter or line by line |
+| pop               | a badge, chip or number landing                |
+| riser into impact | the payoff or the mark, once in the film       |
+
+- Place a clip so its peak lands one frame after its picture (light arrives before sound; a sound early feels wrong sooner than one late): `npx hyperframes audio <file> --json` reports where it hits, and most files peak after their start.
+- Each hit sits 3-6 dB over the bed; a bed with most of its energy under 150 Hz plays as nothing on a phone speaker.
+- Rotate two or three takes of a repeated sound; the same whoosh on every cut is the most common tell.
+- Over strong music, a typing-heavy film can drop the clicks and keys. No synthesised tones, chimes or dings.
+
+## 5. Levels
+
+Music under a voice sits around 0.14 volume; nothing clips (AI audio often does). Keep each file's true peak at −1 dBTP or lower and the mix around −16 to −14 LUFS for social, `npx hyperframes normalize-audio` to match levels (`/media-use`). Check the rendered file with `npx hyperframes audio <video> --json`: sound present, hits where the picture hits, loudness in range. Say in the delivery note that it was measured, not heard (`review.md` §4).

package/skills/hyperframes/references/spec.md

@@ -0,0 +1,76 @@
+# The spec
+
+Adjectives are where the default look lives. Given "premium, modern, clean", the model fills every gap with its own defaults, and they look the same in every run: a dark void, a glow, small type floating in the middle, everything fading in. Every adjective you turn into a number is a decision taken back from those defaults.
+
+So before any scene, write `SPEC.md` at the project root: the film as a director's brief to yourself, with a number wherever you would have written an adjective. Build from it, check against it, and change it when a review changes the film.
+
+The spec serves the story, never the other way round (`story.md`). A look that turns the story's things into abstract shapes has failed, however striking the frame.
+
+## The template
+
+```text
+GOAL:    what the viewer feels or does at the end, one sentence
+OUTPUT:  HyperFrames, W x H, fps
+TIME:    seconds x fps = frames; BPM and frames per beat when there is music
+LOOK:    ground (hex, texture and its amount), ink, one accent and where it may appear;
+         display face + weight + size in px + tracking, body face the same;
+         the medium (paper and ink, photographs, product UI, glass, clay, 3D studio) with its numbers;
+         light and depth: shadow offset, blur and opacity, grain %, vignette %
+OBJECTS: every thing the story needs the viewer to recognise (a mirror, a clock, a phone, a person),
+         drawn with the material and details that make it read without a label: a mirror is
+         silvered glass with a bright edge and a mount, not a bar
+MOTION:  eases by role as named curves (enter, move, exit, camera); springs as damping ratio;
+         durations and staggers in frames
+SHOTS:   one line per shot: frame range, the one hero move, what the viewer reads (with its window),
+         the sound, and how it hands off to the next shot
+BANNED:  the defaults below, plus anything this film must not become
+QA:      the frames to check, and what each must show
+```
+
+## Turning words into numbers
+
+| The word  | Becomes                                                                                                                                |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| premium   | a material with numbers: satin paper with 2% grain, a product on a seamless sweep with a 0.55 contact shadow, chrome at roughness 0.05 |
+| modern    | a camera and a type system: a 30-frame push on one ease, a display face at 9% of the frame height with -2% tracking                    |
+| clean     | a grid and a ration: 12 columns, 96 px margins, the accent on one word per shot                                                        |
+| dynamic   | cuts on the beat, a layout change on the bar (every 4 beats), one hero move per shot                                                   |
+| playful   | springs at damping 0.45-0.6 on position and scale (never on opacity or colour), 10-30% exaggerated poses                               |
+| cinematic | a lens and a light: a 35 mm framing, a key from upper left, a rim from behind, 6% vignette                                             |
+
+## Composition numbers
+
+- The hero of a shot fills at least 40% of the frame's height or width. A small object in the middle of an empty frame is never a shot; push in, crop, or give it a world.
+- One hero move per shot. Secondary moves travel 50-70% as far, start 100-200 ms after it, and everything else holds still.
+- In a story film every shot moves the story: something happens that causes the next shot. Lines read as cause and effect ("so…", "which means…"), not slogans.
+- An information card (B-roll over a talking head, a data beat, a vertical explainer card) is different: its information is on screen within about 2.5 s, then it holds, so any paused frame reads as a finished poster.
+- Something new every 2-4 s across the film; a new layout every bar when there is music.
+- Text meant to be read: at least 28 px at 1080 (2.6% of the short side), held 0.5 s + 0.3 s a word. Too many words: cut words, never shrink type.
+
+## BANNED by default
+
+These are where generated video lands when nothing else is decided. Each is banned unless the brand's own material or the person's reference uses it, and then only as they use it:
+
+- a black or dark navy void as the ground, with small elements floating in its middle;
+- glow, bloom, neon, lens flares, glowing orbs and rings; floating particles as decoration;
+- purple or blue gradients, mesh gradients, glass cards;
+- a cream or off-white paper ground with a serif display, italic accent words, numbered "01 / 02" labels, small monospace caps labels, pill-shaped chips and buttons;
+- everything centred; everything fading in at once; every element fading and sliding up;
+- text that moves while it is read; titles that keep drifting after they land;
+- corner labels, frame borders, corner brackets, HUD readouts as decoration;
+- three cards in a row, KPI grids, a title over a dimmed screenshot;
+- the logo docked in a corner.
+
+After the first render, name every default it used anyway, from this list or not, add each to the film's BANNED line, and fix them. The list grows with every film.
+
+## A look built from a medium
+
+A look holds together when it is the rules of one medium, not a palette. A risograph look, for example, is five parts and nothing else:
+
+- **paper**: one flat colour with a fibre noise, no gradients;
+- **ink A**: every word that must be read and every structural line;
+- **ink B**: one fluorescent accent, one focus per frame (the number, the bar, the stamp);
+- **overprint**: where the inks overlap a third colour appears, and the B plate sits 3 px off register;
+- **halftone**: every gradient is dots.
+
+Motion comes from the same medium: the frame is printed, plate by plate, not faded in. Write any look this way: its parts, what each may carry, and how the medium itself moves (paper is cut and lifted, ink is printed, glass refracts, clay is pressed).

package/skills/hyperframes/references/story.md

@@ -0,0 +1,103 @@
+# Story
+
+Read before building any video that tells something over about 15 s: a launch or promo, an explainer, a pull-request or changelog video, a recap, a music video with a narrative. Most weak films are good motion around no story: a list of features, three cards in a row, a logo, a URL.
+
+Skip it for an edit to an existing project, captions or overlays on footage, and a short single-idea piece (one kinetic line, a map move, a highlight on an image), where the request is the story. When the person gave a script, a storyboard or a reference film, follow theirs. The shape of each kind of film (launch, explainer, music, data, vertical, 3D, character) is in `types/`.
+
+## 1. The one thing
+
+- **What it is**, in one line: "You can now …" for a launch, the one idea the viewer must understand for an explainer, what changed and why it matters for a pull request. A whole release ("2.0", "what's new") is not one thing: take its headline.
+- **The one thing to remember** after the film ends, in the viewer's words, not the brand slogan.
+- **One viewer doing one real task**, from the moment they need it to the result. That task is the spine, and one real piece of data (a query, a file, a prompt, a number) travels through it from the hook to the payoff. An explainer's spine is one concrete example worked through.
+- Keep facts (what it does, real numbers, real labels) apart from creative choices (angle, tone, look). Every claim on screen traces to the source: the site, the PR, the docs or the person's words. Use the person's own copy verbatim.
+- What the source does not say stays unsaid: never derive a claim it did not make ("40 min to 2 min" is not "20× faster"), mark an example number as illustrative, and show a screen you cannot get as a labelled placeholder, not a drawn one.
+
+## 2. Three storylines, then one
+
+Write three. They are three different films, not three titles on one film: each has its own **world** (where it happens and what it looks like), its own **device** (what the story is) and its own **form** (how the camera and the cuts carry it). Sketch five or more ideas first, a line each pairing a device with a form (tables below); drop those the subject cannot carry well, and of the rest keep the three that differ most. Make one of the three the bold one you would not have picked first. Each says:
+
+- its name, its device and form in a few words, and in two sentences what the viewer sees and feels;
+- the first two seconds, exactly;
+- its beats in one line (`hook → … → end card`);
+- its look in one line: ground, type, the one material or treatment, taken from the subject or the brand (`look.md`);
+- its sound in one line (`sound.md` §1).
+
+The storylines are words: build nothing for any of them before one is picked. Pick a storyline for its story: the one a stranger would follow and remember, with people or a situation they know, ahead of the most striking picture. Picking a storyline picks its look and its sound. Then write the picked one as `SPEC.md`.
+
+Put your recommendation first, with the reason in one clause, and save all three in the project as `STORYLINES.md` so a later turn can switch.
+
+- **The person is there to answer:** show the three and stop once until they pick. A mix ("A's opening with C's middle") is one storyline. Ask nothing else unless only they can answer it (real screens you cannot capture, narrated or music only). State everything else in one assumption line: the length as a range, the aspect, music or voice, and every paid item (a HeyGen voice, an avatar, catalog music) with the free option beside it.
+- **They asked for the file or for no stops:** take your recommendation, build it, and name the other two in one line each in your reply.
+- With a storyboard (`storyboard.md`), the picked storyline becomes the board's frames.
+
+| Device                        | What the viewer sees                                                                    |
+| ----------------------------- | --------------------------------------------------------------------------------------- |
+| A moment in someone's day     | a person, a time stamp, the message that creates the need ("launch is tomorrow")        |
+| A character does the work     | a mascot or a cursor carries, drags, draws and reacts; every cut has a cause            |
+| The feature as the hook       | the feature happening to a recognisable image in the first half second                  |
+| The result first              | the finished output plays, then the camera pulls back to show where it came from        |
+| One object across apps        | the thing being made travels from one app into the product, which keeps working on it   |
+| Life before and after         | the old way as a scene (one person drowning in tabs), then the new way                  |
+| Type carries the argument     | giant kinetic type, colour fields and grids that cut on the beat                        |
+| A number lands                | one real number earned by a scene, then made physical                                   |
+| A question with the input     | "What if you could make a video from your ⟨website⟩?", the blank filled by a real input |
+| The object is the explanation | a machine or model whose working is the idea; the camera tours through it               |
+
+| Form                       | What the viewer sees                                                                         |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| One continuous take        | the camera never cuts; it pushes, pulls and travels from one world into the next             |
+| Object-to-object chain     | every shot ends on the thing that opens the next: a button becomes a card becomes a phone    |
+| An endless zoom            | the camera dives into a detail that turns out to be the next world, again and again          |
+| A flight through one world | a 3D set, a map or a desk the camera travels across; each idea is a stop on the route        |
+| Cut on the beat            | hard cuts on the music, type and colour fields changing every half beat                      |
+| Match cuts                 | one shape holds while everything around it changes: a circle becomes a lens, a wheel, a logo |
+| Split screen to one        | several panes play at once, then collapse into the one that matters                          |
+| One frame that rebuilds    | a single composition keeps rearranging itself and never leaves the frame                     |
+
+A pitch where all three are plain cuts between scenes has not tried the forms. Before and after: the new side moves calmly while the old side churns; never mock a named competitor. A recap asks one question first so each piece answers it.
+
+## 3. The hook
+
+The first two seconds are the densest of the film, and frame 0 is the thumbnail: never black, never a logo alone. Open on the feature working on something recognisable, a real moment that creates the need, a question with the input inside it, a sentence whose last word becomes the picture, or the bug itself. Then let the old way fail on screen (the wait, the wall of text, the wrong result) before the product brings relief; the proof is often the same shot improved in front of the viewer. Typing into a prompt box as the opener, with nothing else on screen, is the tell of a generated film; as a story step a few seconds in, it is fine.
+
+## 4. Beats
+
+A common shape for a launch of about 35 s; scale it, let the device bend it, and take another type's shape from its file in `types/`:
+
+| Beat     | Share | Job                                                                                       |
+| -------- | ----- | ----------------------------------------------------------------------------------------- |
+| Hook     | ~8%   | the world and the need, or the feature already working                                    |
+| Tension  | ~12%  | the old way failing on screen, or a gag                                                   |
+| Reveal   | ~8%   | the product or idea named as a title, about 20–30% in                                     |
+| Proof    | ~40%  | the real task in the real UI as 3–6 verbs (_paste, pick, watch it build, ship_), one each |
+| Payoff   | ~20%  | the output arrives, already moving: the biggest visual moment, once, 60–80% in            |
+| Claim    | ~8%   | the one thing, in one line                                                                |
+| End card | ~8%   | the mark carried in, the name and the call to action land and hold 2–3 s                  |
+
+In each verb beat keep only what the cursor touches and what proves the line; delete the rest of the screen. The process runs fast; the payoff plays at normal speed. Length follows the story (a feature launch is usually 20–45 s); a length in the request is a range, never padded.
+
+## 5. Worlds
+
+A film visits several worlds, each with its own background, light and scale (a desktop, the product on a brand gradient, a white void with a character, live action), never one dark canvas with small UI floating in it. Enter each world through an object already on screen: the thing clicked becomes the next shot. Keep one home stage to return to, one carrier the eye follows, and the palette and type constant across worlds.
+
+## 6. Copy and voice
+
+- Titles take at most 6 words a line, one line on screen at a time, no trailing periods; an explainer's lines may run to about 10. A line holds about 0.3 s a word plus 0.5 s, and the last line at least 2 s.
+- Show, don't list: no bullet slides or three-card rows. When similar things repeat, each gets its own idea and layout.
+- Real numbers only, from the source. The first line is never "Introducing", "Meet" or the logo; after the pain, "Introducing X" is fine. Never "unlock", "seamless", "supercharge", "game-changer", "revolutionize", "effortless", or "in seconds" unless measured.
+- Read the lines alone: a stranger gets the pitch. Watch the pictures alone: they tell the same story.
+- No voiceover unless the request or the source calls for one; then the screen never repeats the spoken sentence word for word. Without a voice, large titles and the product's own text carry the words, over music and effects (`sound.md`).
+
+## 7. The brand
+
+The mark lands once, with weight, usually on the end card; before it the brand shows only inside the product and the story, never docked small in a corner. The end card is built, not a still: the mark is carried in, typed or wiped in. The accent colour is rationed: one highlighted word, the payoff, the end card.
+
+## 8. Tells of a generated film
+
+The defaults a film falls into when nothing is decided are banned by name in `spec.md` ("BANNED by default"): a dark void with small things floating in it, glow and particles, the cream-paper-serif-mono-label look, everything fading and sliding up, three cards in a row, the docked logo. Beyond those, for a story:
+
+- every scene entering the same way, or the same move beat after beat;
+- side-by-side panels and floating cards standing in for a scene;
+- titles that keep sliding or shrinking after they land; breathing or floating loops standing in for motion on titles and UI (a character's idle breath is acting, `types/character.md`).
+
+When a first render shows any of them, name which, take the replacement from the subject, the brand or the medium, and add it to the BANNED line of `SPEC.md`.

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

@@ -1,6 +1,6 @@
 # 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.
+Defines the storyboard's **base data format** only: the `STORYBOARD.md` file shape and the `StoryboardManifest` it parses into. Planning the film itself is in [story.md](story.md); the optional narration/TTS file (`SCRIPT.md`) is a separate concern, not here.
 
 A storyboard is the **plan layer** for a video — an ordered set of **frames** (key moments) in one markdown file. Parser: `@hyperframes/core/storyboard` → `StoryboardManifest`.
 
@@ -8,31 +8,38 @@ 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`                               |
-| `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`                              |
+| Key        | Meaning                                                      | Example                                   |
+| ---------- | ------------------------------------------------------------ | ----------------------------------------- |
+| `format`   | Canvas size                                                  | `1920x1080`                               |
+| `duration` | The length the person asked for (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 (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.
+Set `duration` when the storyboard is first written. It is an expectation, not a gate: compare where the cut actually lands against it — 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 |
+| 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`); a note only, build it yourself (overlap clips for a crossfade) |
+| `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` — carry your own per-frame data (effects, assets, …) here                   |
+
+Two `extra` keys every film plan carries, so the build and the review check the same thing:
+
+| Key     | Meaning                                                                                                                                                                                                                          |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reads` | what the viewer must understand in this frame, in order, each with its window: `the cursor finds the button (0.4-1.2s); "Export" lands (1.2-2.6s)`. Windows never overlap, and each is long enough for its words (`story.md` §6) |
+| `sound` | the bed, the effects on visible actions, or silence: `bed enters strong; click on Export; whoosh on the cut`                                                                                                                     |
 
 ## Parsed manifest
 
@@ -55,7 +62,7 @@ StoryboardManifest {
 
 ## `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.
+Optional, free-form, **not parsed into the manifest** — the locked-narration file that drives TTS, absent for videos with no narration/TTS. The per-frame `voiceover` above is the storyboard's own narration guide.
 
 ## Example
 
@@ -75,6 +82,8 @@ audience: indie devs on X
 - transition_in: cut
 - status: animated
 - voiceover: "Ship a launch video in an afternoon."
+- reads: "Ship a launch video" lands (0.3-1.6s); "in an afternoon" (1.6-3.0s)
+- sound: bed enters on its strongest bar; impact on "afternoon"
 - src: compositions/frames/01-hook.html
 
 Open cold on the promise. This is the thesis — everything after pays it off.
@@ -95,5 +104,4 @@ The old way: prompt, wait, get something that misses. Establish the pain we remo
 
 - 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. Nothing is drawn yet beyond the approved layout.
-- The process that walks these statuses — plan, sketch, build, each pass reviewed in chat and in `storyboard.html` — is `review-loop.md`.
 - Multi-line `voiceover` values collapse to one line on save.

package/skills/hyperframes/references/storyboard.md

@@ -0,0 +1,36 @@
+# Storyboard recipe — plan a video as stills the person approves
+
+Use it whenever a run makes or changes a storyboard: when the person asks for one, or when you want their go on the shots before animating. This file owns **how to make the board**; `storyboard-format.md` owns the `STORYBOARD.md` file the tools parse.
+
+A film's shots are planned in the SHOTS line of `SPEC.md` (`spec.md`); a storyboard turns those shots into stills when the person wants to approve them first, one frame per shot, carrying its `reads` and `sound` (`storyboard-format.md`).
+
+The person sees the plan as stills on the board, comments or draws on a frame, and says go. The board is `boards/storyboard.html`, and tools that show it find its frames by the classes in § 2; boxes marked any other way (`cell` boxes, `id="frame-NN"` markers) are not found.
+
+## 1. The run
+
+1. **Pose each shot** in the composition the project renders, the root `index.html`, at its key moment: real words, real fonts, real colors, the focal point big enough to read on a phone. A shot posed in its own file (`compositions/frames/NN-*.html`) shows only once it is mounted in `index.html` (`data-composition-src`) at its planned start; `snapshot` renders `index.html` and nothing else. Before the first pose, copy `index.html` to `boards/.film.html`: until the go, the preview plays that film, never the stills (step 4).
+2. **Snapshot every still in one run** with your host's snapshot tool when one is offered (each shot's seconds, out `boards/stills`); otherwise `npx hyperframes snapshot --at <every shot's seconds, in film order> --no-end --describe false -o boards/stills`. Each still is named `frame-NN-at-<seconds>s.png`, NN its place in the film. Every `snapshot` run clears its `-o` folder and numbers from `00`, so never snapshot a single moment into `boards/stills/` itself (step 5). Look at every still yourself; fix and snapshot again until each one holds.
+3. **Write `boards/storyboard.html`** (§ 2), styled as a finished board: Inter or the system sans-serif, a light page, each frame a rounded card with its still above its words, even gaps.
+4. **Put the film back.** Copy the posed `index.html` to `boards/.posed.html`, then `boards/.film.html` back over `index.html`. The board stays on its own page: held stills in the preview read as a slideshow.
+5. **Stop.** Hand the person the board and wait for their go. Notes on frames change only those frames. For each one: copy `boards/.posed.html` over `index.html`, re-pose it, snapshot just its moment into `boards/stills/redo/` (`--at <its seconds>`), move that one file over the frame's old still under the old name (its new time in the name if the time changed, and the page's `src` with it), then put the film back (step 4), rewrite the page and stop again. The other stills stay as approved.
+6. **Once they say go**, copy `boards/.posed.html` over `index.html` and animate from the approved stills.
+
+## 2. The page
+
+One `class="frame"` box per still, in film order, holding its image, a `class="title"` line "<two-digit number>: <name>" and a `class="time"` range in seconds. Optional: a `class="words"` line under it, and a `class="act"` heading before the first frame of each act.
+
+```html
+<section class="act">Act 1: The hook</section>
+<div class="frame">
+  <img src="stills/frame-00-at-1.5s.png" alt="" />
+  <div class="title">01: The hook</div>
+  <div class="time">0.0 to 3.0s</div>
+  <p class="words">The cursor drops the photo on the timeline; the title lands on the drop.</p>
+</div>
+```
+
+Stills are written next to the page (`boards/stills/`), so `src` is relative to `boards/` and names the file `snapshot` wrote for that shot. A still written after the page shows by itself; never reopen or rename the page for it.
+
+## 3. The plan beside it
+
+`STORYBOARD.md` at the project root (format: `storyboard-format.md`) names the same frames in the same order, and its words win over the page's: one heading per frame like `## Frame 1: The hook (0-3s)`, a `- act:` bullet for its act, and `- status: outline` until its still is posed.

package/skills/hyperframes/references/types/3d.md

@@ -0,0 +1,25 @@
+# 3D, simulations and generative pieces
+
+Use 3D when the film earns it: an object or a set as the payoff, a product, a simulation that explains. Loading Three.js, WebGPU, p5 or canvas and the seek protocol are in `../runtimes.md`.
+
+## Deterministic by construction
+
+- Draw every frame from timeline time in the `hf-seek` listener; frames render out of order.
+- Simulate once at load (physics, agents, particles) into arrays, then look up the state at `t`: `render(t)` stays a pure function. Heavy setup (meshes, shader compiles, the simulation) registers a `window.__hf.buildReady` promise.
+- Seed every random choice; a seeded hash of the index, never `Math.random()`.
+
+## Camera and story
+
+- One hero object beats a crowd. Fly through or into it rather than orbiting it: one dive is worth ten turns.
+- Cutaways, exploded views and chapters with one caption line each, plus labels with real numbers, turn a simulation into an explanation instead of eye candy.
+- Product UI is never tilted into 3D; only generated content tilts.
+
+## Light and materials
+
+- Light it with a warm key, a cool rim and a dark environment with two or three soft strips; turn the environment, not the object, so highlights sweep across it; a contact shadow under the object.
+- Bloom eats detail: keep it to the brightest points. Glossy metal under a low light gives white streaks: roughness about 0.45 or more, environment intensity about 0.5.
+- One NaN pixel turns a whole frame black through bloom: clamp values that can divide by zero.
+
+## Check it
+
+Snapshot the dive and the payoff (`../review.md`); a frame that takes too long to draw slows every render, so profile the heaviest moment once.

package/skills/hyperframes/references/types/character.md

@@ -0,0 +1,20 @@
+# Characters, mascots and story shorts
+
+A character gives every transition a cause and gives the film its jokes: it carries the result into the player, rejects its own first try, reads the manual. After Effects characters come in through Lottie (`../runtimes.md`).
+
+## Acting
+
+- Mood changes go through a take: anticipation, a squash, the new face, a settle. A face never snaps from one state to the next.
+- Squash and stretch, anticipation, overshoot and follow-through belong to the character. Here an idle breath or blink is life, not a tell; the tells about breathing and bounce in `../motion.md` are about titles and UI.
+- Code moves every part at once, on one curve, by the same amount. Offset the parts (head leads, arms follow), vary the amounts, and never move both arms, both eyes or a crowd in unison.
+- Contact sells it: feet on the ground, props held by the hand, eyes on what they look at.
+
+## Reads
+
+Each action is one read. Lead the eye to where it will happen, play the action fast, and let its meaning land slowly: hold the reaction. A sign or caption that repeats what the action already shows is the classic failure.
+
+## Build
+
+- A rig is a set of parameters over time: position, squash, arm angles, an eye state and a mouth state per moment. Write mood changes as keyed states (`[[t0,"normal"],[t1,"scared"]]`) the rig eases between.
+- Hand-drawn life: redraw the outlines about 12 times a second with a jitter seeded by `Math.floor(t * 12)`, so the line boils while the character holds still, and every render matches.
+- A long piece is one chapter per sub-composition, all drawing from the same rig and helpers.

package/skills/hyperframes/references/types/data.md

@@ -0,0 +1,19 @@
+# Numbers, charts and data stories
+
+## One number at a time
+
+- A number is earned by the scene before it, then made physical: a count that becomes a skyline, a share that becomes a crowd.
+- The number is the biggest thing on screen. Tabular figures (`font-variant-numeric: tabular-nums`) so a count-up does not jitter; a count-up runs 1.2–1.6 s, then holds.
+- Real data only, from the source, rounded the same way everywhere, with a small source line on screen. One data module drives every figure in the film.
+
+## Charts as pictures
+
+- Build a chart in reading order: the frame and axis, a reference line, then the data drawing in, then one annotation on the point that matters. Annotate on the mark; no legends.
+- Highlight one series, grey the rest. A chart with one thing to say says it in its title.
+- The same object carries across beats: a bar becomes the ground of the next scene, a line becomes the road the camera follows.
+- The camera can dive into the one value that matters, then the rest falls away.
+- Registry charts first (`npx hyperframes catalog --query chart --json`); drive any chart library from a GSAP tween's `onUpdate`, never its own transitions (`../runtimes.md`).
+
+## Tells for this type
+
+A grid of KPI cards; a dashboard; a pie chart; every number counting up at once; numbers with no source.

package/skills/hyperframes/references/types/explainer.md

@@ -0,0 +1,34 @@
+# Explainers, tutorials and "how it works"
+
+One idea the viewer understands by the end (`../story.md` §1). The spine is one concrete example worked through, start to finish, not a tour of facts. Usually 30–90 s.
+
+## Ground it first
+
+Start where the viewer already is: a person, a place or a situation they know, and a question they would ask about it ("why does the astronaut come home younger than her twin?"). The abstract device (a light clock, a graph, a field) enters inside that situation, as the thing that answers the question, and the film returns to the person at the end with the answer. A film that opens on the device alone is a diagram, not an explainer.
+
+## Devices that explain
+
+- **The object is the explanation.** Build a thing whose working is the idea: a machine, a model, a map, a light clock, drawn so it reads as what it is (its material, its mount, where it sits in the scene). Every number on screen comes from it, and the camera tours through it: cutaways, an exploded view, a dive into the part that matters.
+- **One diagram that grows.** Start from the simplest true picture and add one part per beat, each appearing when it is named; never a finished diagram dropped on screen at once.
+- **Continuous transformation.** Each step morphs out of the last (a bar becomes an axis, a dot becomes a population), so the viewer never loses the thread to a cut.
+- **The worked example.** One real input (a sentence, a number, a photo) travels through every step to the answer.
+
+## Shapes of information
+
+Most explainable lines are one of a few shapes, and each has its own picture: a number that lands (`data.md`); a myth turned over (the wrong idea struck through, the right one printed over it); before and after; many things converging into a few groups; a network that densifies; one chosen out of many; steps in order; a real screenshot with the detail circled; a quote set as a poster; a chapter card. Pick the shape first, then the picture, so similar lines get different pictures and every line gets the one that shows it.
+
+## Words
+
+- Narrated: the voice is the clock (`../sound.md` §2). Reveal each part when the voice names it, across the back half of the scene; keep a scene to about 19 spoken words (`../film.md` "Script and pacing").
+- Not narrated: large lines carry it, up to about 10 words, each held 0.5 s + 0.3 s a word.
+- Labels sit on the part they name, with a leader line when needed, and appear with it. No legends, no bullet slides.
+
+## Getting it right
+
+- Every claim, value and step traces to the source; a number the source did not give is left out or marked illustrative. One data module drives every figure so the numbers agree with each other.
+- Check the science or the logic of each step before animating it; a beautiful wrong diagram is worse than none.
+- End on the one idea in one line. No brand end card unless asked.
+
+## Tells for this type
+
+A slide of bullets; icons in circles; three cards in a row; the whole diagram at once; a narrator repeating the text on screen word for word.

package/skills/hyperframes/references/types/launch.md

@@ -0,0 +1,41 @@
+# Launch, promo and feature films
+
+The shape is `../story.md` §4 (hook → tension → reveal → proof → payoff → claim → end card), usually 20–45 s. What a viewer shares is real people and real output: in the official films, effects-heavy pieces drew about a tenth of the views of ones built on a real result.
+
+## Real UI, never a mockup
+
+Everything that claims to be the product is the product. One invented button loses everyone who uses it.
+
+1. Where it comes from, best first: the person's recording or screenshots (ask, naming the screen per beat, when the proof needs one you cannot capture); Figma frames, rebuilt as states of one app so the change between two frames is a real click (`/figma`); walking the flow yourself when no sign-in is needed; `npx hyperframes capture` of the feature's own page; the product's code, PR or docs to confirm today's labels.
+2. Missing a screen: a clearly labelled placeholder ("Screenshot: Settings → Motion"), said in the reply. A feature with nothing visible (speed, an API): the real UI that exposes it, a real analogue the viewer knows, real terminal output, or a checklist of real facts. Never a made-up dashboard.
+3. Logo, icons and fonts are the brand's own files (`/media-use` for logos); never redrawn from memory, never a coloured square for an app icon.
+
+## The product on screen
+
+Captured screens establish what is real; they are not a shot list. A launch film can rearrange verified pieces to explain a result. For a launch, do not substitute a sequence of full-page screenshots with titles for showing what the product does.
+
+Plan the relationship between the product and its parts:
+
+1. **Establish the workspace.** Show enough of the real navigation and surrounding interface to locate the task. A whole-product view supplies context; the viewer does not need to read every control.
+2. **Isolate the action.** Bring the relevant chart, field or result forward. Keep its real labels, values and state; rebuild only the piece the beat uses and show it at 1.6–2× its real size. Text stays at least 26 px at 1080p after any push. Never a small window in the middle of an empty canvas, never product UI tilted in 3D. Let a trace draw, a result populate or a panel open before advancing. A camera move over a frozen screenshot is not the product performing an action.
+3. **Return the result.** Carry the same component back into its place in the interface, or pull back to show where the output is used. When the result plays inside the product, pull back to reveal its player or zoom through the player until the result fills the frame. A film made only of floating close-ups loses the system they belong to. Do not imply that a rearranged component is an interaction the product actually supports.
+
+Keep a short explanation where the action needs one: a phrase naming the change, the relevant label or the meaning of a number. "Less text" does not mean removing the context needed to understand the evidence. Reveal supporting elements across the beat instead of showing everything at its start and extending the hold. Review the transition's intermediate frames as well as its endpoints; carried labels and values must not jump or get covered on the way back into the workspace.
+
+For a background or palette revision, update the root, scene surfaces and timeline color tweens together; a later tween can restore the old background. Adjust text, chart strokes and axes for contrast on the new ground, then check frames from every affected scene and transition. Preserve the product's meaningful status colors.
+
+- The camera cycles between the window on its ground, one pane, and a punch-in on one control. Moves take 0.4–0.6 s with motion blur, arrive at the control the cursor needs, then hold while the UI acts.
+- Containers morph instead of cutting: the button becomes the menu, the message becomes the bubble.
+- The cursor is big (4–7% of the frame), enters from off-screen, and its click causes the next thing on the same frame.
+
+## Worlds and transitions
+
+Visit several worlds (`../story.md` §5) and enter each through an object on screen, with 3–5 kinds of transition in a film (`../motion.md` "Transitions with a cause").
+
+## The end card
+
+The mark lands in the last 5–10% of the film, centred, the lockup 15–30% of the frame width, performed rather than faded in: the cursor clicks the mark and a fill rises through it, or a character carries it in, then the wordmark wipes in beside it. Then the call to action (a real button, the command to type), held 1.5–3 s.
+
+## Tells for this type
+
+Typing into a prompt box as the opener; a feature list as three cards; a title over a dimmed screenshot; an invented dashboard; the logo docked in a corner.

package/skills/hyperframes/references/types/music.md

@@ -0,0 +1,24 @@
+# Music videos and films cut to a track
+
+The song is the structure. Timing facts (hits, beat trust, loops) are in `../film.md` "On music"; this file is the shape.
+
+## Song structure becomes edit structure
+
+- Find the sections first: `npx hyperframes audio <track> --only sections,onsets,moments --json`. Each section is a chapter: intro, verse, chorus, bridge, outro.
+- Cut density follows energy: slower shots in verses, one picture per strong beat in the chorus, a held image on a breakdown.
+- The chorus returns to one home stage and escalates each time it comes back; the ending rhymes with the opening.
+- Chapter breaks land on section boundaries, with a transition that belongs to the film's medium (a brush wipe, a paper tear, a match cut).
+
+## Pictures for the words
+
+- Each lyric line or phrase gets its own picture (shots of about 1.4–4 s): show what the line means, not the line itself. Lyrics on screen only when asked; then each line holds at least a beat and is set as type, not subtitles.
+- Something happens in every shot, and every cut has a cause on screen.
+- A song about something real gets real material (footage, photos, places); an abstract track gets one world with a strong medium.
+
+## The look
+
+A physical medium carries a music film further than effects: watercolour with ink outlines, cut paper, risograph print, film grain on footage. Characters, if any, act (`character.md`).
+
+## Tells for this type
+
+The same treatment for more than about 6 s; a spectrum bar or waveform as the main picture; every cut on every beat; words about the music rather than the song's own world.