cueframe 0.2.0 → 0.3.0

package/skills/composing-video/SKILL.md

@@ -5,11 +5,13 @@ description: Use when an agent is asked to make ANY video with CueFrame — a pr
 
 # Composing Video: craft for CueFrame
 
+> **The bar:** the `video-craft-standards` skill (GET /v1/skills/video-craft-standards) defines DONE for every artifact class — per-class MUST checklists and kill criteria. Read it before composing and score against it before rendering. When this skill and that document disagree, the standards win.
+
 ## The one idea
 
-CueFrame composes **real footage** into finished video, and that is its edge: it detects faces and the active speaker and reframes/punches in on them; it renders titles behind the speaker's head; it times captions to the real transcript; it grades color and renders 4K. Real footage is the strongest grounding you can give a video and CueFrame's home turf — so it is the thing to reach for FIRST and usually your highest-leverage move. But the skill's job is **any good video**, footage or not: an animated explainer, a Manim concept video, a data piece. These are first-class, not a lower tier.
+CueFrame composes **real footage** into finished video, and that is its edge: it detects faces and the active speaker and reframes/punches in on them; it renders titles behind the speaker's head; it times captions to the real transcript; it grades color and renders 4K. Real footage is the strongest grounding you can give a video and CueFrame's home turf — so it is the thing to reach for FIRST and usually your highest-leverage move. But the skill's job is **any good video**, footage or not: an animated explainer, an animated concept video, a data piece. These are first-class, not a lower tier.
 
-What separates good from slop is not "footage vs. no footage" — it is **grounded specificity vs. the generic default**. The enemy is the interchangeable filler that could belong to any video: gradient/aurora backgrounds under kinetic text, stock "AI b-roll," faked UI, unmotivated motion. The antidote is a **controlling idea** plus **grounded, specific content** — real footage, OR real UI/screen captures, OR real data, OR a *purposeful* graphic/animation that DEPICTS THIS content specifically (a Manim diagram of the actual mechanism, a data animation of the real numbers) — a data/mechanism visual, NOT animated copy. Animated/kinetic TEXT by itself is not grounding. A well-crafted animated explainer built on diagrams of the real mechanism is grounded and good; it is not slop.
+What separates good from slop is not "footage vs. no footage" — it is **grounded specificity vs. the generic default**. The enemy is the interchangeable filler that could belong to any video: gradient/aurora backgrounds under kinetic text, stock "AI b-roll," faked UI, unmotivated motion. The antidote is a **controlling idea** plus **grounded, specific content** — real footage, OR real UI/screen captures, OR real data, OR a *purposeful* graphic/animation that DEPICTS THIS content specifically (an authored diagram of the actual mechanism, a data animation of the real numbers) — a data/mechanism visual, NOT animated copy. Animated/kinetic TEXT by itself is not grounding. A well-crafted animated explainer built on diagrams of the real mechanism is grounded and good; it is not slop.
 
 **Generic default ⇒ slop. Grounded specificity ⇒ good.** Real footage is the strongest grounding and CueFrame's home turf — reach for it first — but purposeful, specific graphics count too. This is a mechanical prediction, not a taste call (see *Craft principles*). Your single most expensive mistake is walking past real footage that exists to build generic gradient slides instead — which is precisely what happened in the SIA case below.
 
@@ -76,15 +78,15 @@ Real footage is the strongest grounding and CueFrame's edge, so hunt for it FIRS
 In the SIA case, step 2 alone would have surfaced the founders-to-camera launch video and changed everything. Footage is the highest-leverage grounding; don't walk past it.
 
 **3b. The stop fires only when the plan is GENERIC filler.** If your plan has no grounded content — no footage, no real UI/data, no purposeful content-specific graphic, just a gradient with kinetic text — STOP and say so, verbatim, before rendering anything:
-> *"This has no grounded content — it's a gradient-and-text motion piece, the generic default, not a video composed from the real thing. I recommend we ground it in [a 30-second founder to-camera clip / a real screen capture / a Manim diagram of the actual mechanism]. Want to proceed as generic motion-graphics, or ground it first?"*
+> *"This has no grounded content — it's a gradient-and-text motion piece, the generic default, not a video composed from the real thing. I recommend we ground it in [a 30-second founder to-camera clip / a real screen capture / an authored diagram of the actual mechanism]. Want to proceed as generic motion-graphics, or ground it first?"*
 
-Proceed only on an explicit "proceed." A *purposeful, specific* animation — a Manim diagram of the real mechanism, a data animation of the real numbers — does NOT trip this stop; it is a legitimate grounded choice, not a consolation prize. The stop exists only for decorative, could-be-any-video filler. Silent generic slop is the failure; a stated, chosen tradeoff is fine.
+Proceed only on an explicit "proceed." A *purposeful, specific* animation — an authored diagram of the real mechanism, a data animation of the real numbers — does NOT trip this stop; it is a legitimate grounded choice, not a consolation prize. The stop exists only for decorative, could-be-any-video filler. Silent generic slop is the failure; a stated, chosen tradeoff is fine.
 
 **3c. The grounding ladder** (strongest first; every rung is legitimate except the last — degrade the *promise*, never the craft):
 1. **Real footage** — `import_media` a founder clip, event recording, or demo. The strongest grounding and CueFrame's home turf.
 2. **Real screen capture** — `import_media` (CueFrame cannot screen-record; that's the external Kishu client, or the user's own recording).
 3. **Real product screenshots / photos** as held stills with **motivated** motion.
-4. **Purposeful Manim / crafted graphics OF THE ACTUAL THING** — `generate_media → manim` for a diagram of the real mechanism (process/algorithm/data viz), or a data animation of the real numbers specific to this content. A **first-class grounded path**, not a fallback — a good animated explainer lives here. The grounding is that it depicts THIS thing — the real mechanism, the real data — not a decorative loop; animated/kinetic TEXT by itself does not qualify.
+4. **Crafted graphics OF THE ACTUAL THING** — an authored `{kind:'card', html, tokens}` clip diagramming the real mechanism (process/algorithm/data viz), or a data graphic of the real numbers specific to this content, shelled with `applyMotionPreset`. A **first-class grounded path**, not a fallback — a good explainer lives here. The grounding is that it depicts THIS thing — the real mechanism, the real data — not a decorative loop; animated/kinetic TEXT by itself does not qualify.
 5. **Generic `generate_media` texture** as a *supporting* backdrop only (a stage, a texture) — never a fake-cinematic hero, never a re-created product UI (it hallucinates specifics).
 6. **Generic gradient-with-text** is the **last** resort and is exactly what triggers the 3b stop.
 
@@ -94,7 +96,7 @@ Do not fake the missing footage, and do not dress up generic filler as grounding
 When you have imported media, pull the detected **faces** (subject boxes per frame, with `faceId`s) and **transcript** before composing. Align reframe/punch-in to the faces, caption words to the transcript timing, and cut points to the speech. Discover primitives with `list_catalog` before hand-placing hex and coordinates — a built-in almost always exists.
 
 ### 5 — Iterate on REAL PIXELS (and prove you looked)
-`preview_frame` PNG stills at your rubric's named timestamps — **always including t=0 and hook-end** — and **look at them**. (Sessionless: a cold first call returns 409 box_warming — retry in a few seconds; subsequent calls are fast.)
+`preview_frame` PNG stills at your rubric's named timestamps — **always including t=0 and hook-end** — and **look at them**. (Sessionless; if a cold first call returns 409 box_warming, retry in a few seconds.)
 
 For every still, before you score it, write one literal line of what is visible: *Is there a grounded subject (real footage, real UI/data, or a purposeful content-specific graphic)? Real UI, or a styled div? Is the background mostly empty decoration? Is the text legible over what's behind it? Does any on-screen number match its written source?* If you can't describe the pixels, you did not look — render again. Score only from these descriptions, never from what you intended to author. Grade the first frame hardest: if t=0 is a bare gradient with the product name, K1 trips and you're done.
 
@@ -107,6 +109,228 @@ Fix the worst thing via `apply_composition`, re-render the affected frames, re-s
 
 ---
 
+## The film spine — how graphics-led video coheres (narration first, always)
+
+Benchmarked against a top studio launch film: a scene detector reads theirs as **one continuous 44s shot**, because nothing ever changes the whole frame at once — and its spine is a continuous voiceover whose words run word-synced along the bottom of *every* frame. A film coheres when one thing never stops; visuals are then free to change every 1–2 seconds. Build in this order:
+
+1. **Write the narration script FIRST — it is the film.** 10–14 short sentences, one idea each (~2.2 words/sec). Do not author a single visual before the script exists. Then `generate_media { generator: "text-to-speech" }` for one continuous take, transcribe it (or measure sentence boundaries), and **cut every beat boundary to the voice** — never the reverse. A silent text-driven film forces every card to hold long enough to be *read*; that dead time is the slideshow texture. With a voice carrying the through-line, each visual is a 2–3s illustration of the phrase being spoken.
+2. **Author the caption spine with `setCaptions`** — segments of word timings matching the VO, styled small/bottom/`plate:"none"`. The persistent word-synced line is the strongest continuity device the format has; the `caption-spine` cohesion floor flags a vo-role clip without it.
+3. **One world.** A single background system (color, texture, light) across every beat. Chapters are tiny inline corner labels (`01 — INPUTS`) inside the flowing world — **never full-screen interstitial cards**, which hard-stop the film. No beat gets its own room (a black hook, a dark grid finale): a full-frame background change reads as a scene change, and enough of them make a slide deck.
+4. **One part vocabulary + one recurring actor.** Everything on screen is the same part (one card/chip grammar: same radius, shadow, label style) at different densities. Pick one small element (a dot, a mark) that appears in every beat and *hands off* across cuts — end a beat with it where the next beat starts it (an exit that launches it up off-frame matched by an entrance that drops it in is a match cut).
+5. **Exit phases, no dead holds.** Every beat's elements leave the frame during its last ~0.4s; no component ends at rest, so motion carries across every cut. No visual state holds longer than ~3s (the `static-hold` floor fires on cards/still images past 4s). Cards can carry this motion themselves now — see the motion runtime below; components (`create_component`) remain the medium for choreography beyond it.
+6. **The falsifiable bar:** run scene detection (or imagine it) over your cut — if it finds a hard boundary at every beat, you built a deck, not a film. Sparse frames are a tell too: elements sized for a fraction of the canvas leave dead space the reference never has.
+
+### The motion runtime — three ways anything you author can move
+
+CSS `@keyframes`/`transition` **never animate in a render** (frames are independent
+Chromium captures; the clock never advances). Use these instead:
+
+1. **Card motion vars (`--cf-*`)** — every card's wrapper carries frame-driven, unitless
+   custom properties: `--cf-progress` (0→1 across the clip), `--cf-ease` (eased progress),
+   `--cf-enter` (0→1 over the first ~0.6s), `--cf-exit` (1→0 over the last ~0.6s), plus
+   `--cf-frame` / `--cf-t` / `--cf-fps` / `--cf-duration`. Author motion directly in card
+   CSS: `opacity: var(--cf-enter)`, `transform: translateY(calc((1 - var(--cf-enter)) * 40px))`,
+   an exit slide via `--cf-exit`. This satisfies rule 5's exit phases without leaving the
+   card medium — and a `preview_frame` still at time *t* shows the exact *t*-frozen state.
+2. **`transitionIn` on any overlay clip** — `{ transitionIn: { type: "fade", duration: 0.4 } }`
+   now applies to overlay-family clips (cards, components, primitives), not just video.
+   Use it for entrances; author exits in-card via `--cf-exit`.
+3. **`applyMotionPreset` op** — shell a static card into a live motion component in one op:
+   `{ type: "applyMotionPreset", clipId, preset }` (unknown presets are rejected with the
+   full preset list). The layout stays verbatim; the preset adds entrance/idle/exit
+   choreography. The result is a live component you can `get_component_source` and refine.
+
+---
+
+## SFX pack — the curated CC0 sound palette
+
+CueFrame ships a **closed, versioned pack of CC0 sound effects** (40 sounds, all
+peak-normalized). There are two ways to place them. **Automatically:** the compose
+SFX pass binds them **deterministically** — a hit on every eligible graphic
+entrance (family from the primitive: `impact` for hero/title, `pop` for
+stat/value, `tick` for enumeration items), a `whoosh` on video transitions, and a
+`riser` ending at the hero entrance — timed to the same frames as the overlay,
+ducked under speech. **By hand:** a client author places any pack sound directly —
+`import_resource { kind:"sfx-pack", id:"<soundId>" }` returns the org's media
+receipt (`{ id, status:"ready" }`) for that sound, which you then drop in as a
+normal sfx clip (`mediaId`). Idempotent per (org, soundId); an unknown soundId is
+a loud 422. Same curated bytes either path.
+Restraint (density caps, min spacing, speech collision) comes from the AUDIO_MIX
+SSOT the eval floors grade with, so placement and grading can't disagree.
+
+**Variety is a floor, not a nicety.** The `sfx-same-sound-reuse` craft floor fires
+when a dense mix (≥6 SFX hits) draws from too small a palette — distinct sounds ÷
+hits below **0.4**. The pack carries **≥4 distinct sounds per transient family**
+precisely so a memoir-class film satisfies it from the pack alone; leaning every
+hit on one sound is the tell it guards. Browse the full palette structurally on
+`list_catalog` (the `sfx` array — `soundId`, `family`, `envelopeClass`,
+`description`, `durationSec`).
+
+**One palette, org sounds first.** `list_catalog` also returns an `audio` array —
+the ONE unified sound palette: the curated packs (SFX one-shots **and** CC0 music
+beds) unioned with THIS org's own uploads/imports (`source:"org"`) and generated
+audio (`source:"generated"`), each entry a uniform `{ref, role, envelopeClass,
+description, durationSec, evidence, source, license, provenance}` (music entries
+carry `bpm`). Provenance rides every entry — pack attribution, `org-owned`, or the
+generator + prompt. **Prefer an org sound when one fits the family/envelope class:**
+an org that uploads its product's real UI sounds hears ITS product, not a generic
+pack tick — the compose SFX pass does this automatically (org sound of the matching
+envelope class beats the pack default, exactly like a brand kit overrides the
+default font), and by hand you place an org `ref` (a `mediaId`) directly. **The
+music tier is curated beds + a generate escape hatch:** browse the `source:"pack"`
+`role:"music"` beds (each with `bpm` + mood, spanning slow/mid/fast) and place one
+via `import_resource { kind:"music-pack", id:"<bedId>" }` (FREE, like sfx-pack); for
+a bed the pack lacks, `generate_media { generator:"text-to-music" }`. Buy/curate SFX,
+curate-or-generate music.
+
+**Transient one-shots** (entrance hits, per-element ticks):
+
+| family | soundIds (subtle→strong) |
+|---|---|
+| `tick` | `tick-soft` · `tick-toggle` · `tick-scroll` · `tick-select` · `tick-click` · `tick-mouse` · `tick-shutter` · `tick-switch` |
+| `pop` | `pop-drop` · `pop-glass` · `pop-pluck` · `pop-drop-low` · `pop-bong` · `pop-confirm` |
+| `impact` | `impact-generic` · `impact-soft` · `impact-tin` · `impact-metal` · `impact-wood` · `impact-firm` · `impact-punch` · `impact-bell` |
+| `confirm` | `confirm-soft` · `confirm-chime` · `confirm-question` · `confirm-bright` |
+| `error` | `error-soft` · `error-buzz` · `error-tone` · `error-hard` |
+
+**Sweeps** (transitions + hero lead-in, ~0.15–1.2s):
+
+| family | soundIds |
+|---|---|
+| `whoosh` | `whoosh-air` · `whoosh-whip` · `whoosh-page` · `whoosh-sweep` · `whoosh-phaser` · `whoosh-low` |
+| `riser` | `riser-jump` · `riser-phaser` · `riser-sweep` · `riser-power` |
+
+(The SFX pack is transient/sweep one-shots; a sustained bed is a MUSIC-role clip —
+a curated `music-pack` bed or a `text-to-music` generation, not a pack hit; see the
+`audio` palette above.) For a sound the pack lacks, search
+CC0 stock at curation time via `search_resources { kind:"sfx" }` (Freesound,
+duration-bounded) and `import_resource` it — the pack is the fast default, not the
+ceiling. For a sound that doesn't exist anywhere, generate it:
+`generate_media { generator: "text-to-sfx", prompt: "short bright metallic tick, fast decay, no tail" }`
+(0.5–22s; the delivered file is envelope-checked before it goes ready).
+
+### Audio design — how to USE sounds (canonical doctrine + our calibration)
+
+This is established film/UI sound-design craft — Chion, Murch, Thom, and the
+Material sound guidelines — with the numbers calibrated on our own measured films.
+The stakes are empirical, not aesthetic: films with sound effects measure >3x higher
+perceived immersion than without (Kock & Louven), and audio-aware models consistently
+beat vision-only models at predicting short-video engagement (VQualA 2025) — the
+soundtrack is a measurable share of whether anyone keeps watching.
+
+0. **Who owns time — pick the rhythm authority FIRST.** Before any hit or bed,
+   decide what the cut serves. A film has ONE rhythm authority (word timings, beat
+   maps, and shot boundaries are the same TYPE — a temporal grid; pick which one
+   drives). **VO-driven** (a narration film): cut every beat boundary to the
+   *voice* — the film-spine rule (author the script first, then read the word grid
+   off `get_media_context` — `wordGrid.wordTimesMs`, the word onsets in ms — and
+   land each cut/caption on a word). **Music-driven** (a montage/no-VO piece): cut
+   on the *beat* — read `beatGrid` off `get_media_context` (bpm + `beatTimesMs`),
+   land cut points and transition MIDPOINTS on beats, and resolve risers exactly on
+   a downbeat/strong beat (every 4th beat from the grid start). A grid is EVIDENCE,
+   not autopilot — you choose which beats carry cuts; on-beat reads as craft,
+   off-beat as accident (synchresis, Chion). Trust `beatGrid` for cutting when its
+   `confidence` is high; a beatless bed reports low and carries no reliable grid.
+   Once you have picked the authority, **materialize its grid onto the timeline
+   with the `materializeGrid` op** (`{clipId, grid:"beat"|"word", maxMarkers?}`):
+   the server reads that clip's source grid and lands `kind:"beat"|"word"` markers
+   at the correct TIMELINE times (projected through the clip's trim/playbackRate/
+   excludedRanges — you never do the media→timeline math yourself). Then place cuts
+   and transition **midpoints** on the markers — a transition's midpoint IS the cut
+   point, so start a 0.5s transition 0.25s *before* the marker so its center lands
+   on the beat. Materialize ONCE per authority clip; re-running the op refreshes the
+   markers in place (it replaces the prior set from the same clip+grid), so re-run
+   after you retrim or restretch the clip. (`grid:"shot"` is reserved — not exposed
+   yet.)
+
+0b. **Declare the audio's ROLE at ingest — evidence follows the declaration.**
+   Uploads/imports accept an optional `audioRole: vo|music|sfx|ambience` (finalize
+   and import bodies). Declaring it routes enrichment: `vo` → transcript + word
+   grid; `music` → `beatGrid` (detected, no prompt needed); `sfx`/`ambience` →
+   `envelope` evidence on `get_media_context` (`envelopeClass:
+   transient|sweep|ambient` + attackMs/crest stats — pick pack-style hits by
+   class, not by listening). Undeclared audio is transcribed as before, and a
+   no-speech file still comes back envelope-classed. **`ambience` is the fourth
+   role**: a bed that grounds the SPACE — it loops, sits at the bottom of the mix,
+   and HOLDS under VO (it is never ducked; only `music` ducks under speech). Use
+   ambience for room tone/atmosphere continuity across cuts (the room-changes
+   floor's natural fix), never for anything that must be *noticed*.
+
+0c. **The engine owns the default mix — author levels only to deviate.** A clip
+   tagged with an `audioRole` but no authored `volumeDb`/`volume` is auto-staged
+   to the clarity hierarchy (VO 0 dB, sfx −6, music −16 under VO else −8,
+   ambience −22 — keeping VO ≥6 dB over the bed). An authored level always wins,
+   a role-less clip stays at unity, and authored levels that invert the hierarchy
+   (e.g. music over VO) raise a non-blocking `mix_hierarchy_inverted` warning on
+   `create_render` naming the offending clips. Tag roles and let the engine mix;
+   reach for `volumeDb` only when you intend to break the hierarchy.
+
+0d. **A brand kit can carry a SOUND identity — set it once, it rides every
+   compose.** `create_brand_kit`'s `audio` block (echoed on `get_brand_kit` +
+   `get_profile`) holds the brand's sonic taste; every ref is a palette reference
+   (a pack `soundId` | `bedId` | an org `mediaId` from `list_catalog`'s `audio[]`).
+   Four optional fields, resolution precedence **brand > org > pack** (the audio
+   analog of how a brand FONT sits above org/pack defaults):
+   - **`sonicLogo` `{ ref, placement: intro|outro|both, offsetMs? }`** — the brand
+     signature. When the kit ALSO carries the matching bookend (`intro`/`outro`
+     bumper), compose binds an sfx-role clip at the body edge that bookend abuts
+     (intro → body start; outro → body end − logo length; `offsetMs` shifts
+     within). No matching bumper ⇒ a non-blocking `brand_sonic_logo_no_bookend`
+     advisory and nothing placed (the sonic logo is the AUDIO companion to the
+     VISUAL bookend). A `ref` that no longer resolves fails loud
+     `brand_audio_unresolvable` — re-point it or clear the sonic logo.
+   - **`uiSoundSet` `{ family → ref }`** — per-family SFX overrides (the brand's
+     own tick/pop/impact/…). Consumed by the compose SFX draw as the HIGHEST tier:
+     a family the brand overrides plays the brand's sound, everything else falls to
+     the org palette then the pack default.
+   - **`bedStyle` `{ bedId? | genre?, bpmRange? }`** and **`ambiencePreference`
+     `{ ref } | null`** — SURFACED-ONLY today: compose auto-selects neither a music
+     bed nor ambience, so these carry the brand's preference for a DRIVING agent to
+     honor when it pins/generates a bed (`brief.audio.music`) or places ambience.
+   Extraction can't hear: `extract_brand_kit` (website → colors/fonts) never fills
+   the `audio` block — set the sound identity explicitly on `create_brand_kit`.
+
+1. **Every hit is a SYNC POINT — sound welded to a visible event.** Chion
+   (*Audio-Vision*) calls this **synchresis**: the immediate, involuntary weld the
+   brain makes between a sound and the image it lands on — that weld is where
+   "added value" comes from, and a hit with no visible cause produces none (it's
+   the audio version of unmotivated motion, slop tell #6). Bind hits to their
+   events via `anchor: { clipId, offsetMs }` so the weld survives re-edits. And
+   per Randy Thom (*Designing a Movie for Sound*): sound is a storyteller, not
+   decoration — score the moments that matter, let ordinary cuts breathe.
+2. **Class → moment.** `transient` (tick/pop/impact/confirm/error) = entrances,
+   cuts, UI semantics — Material's sound guidelines are the reference for UI
+   semantics (each sound expresses its place in the hierarchy; decorative sound
+   used sparingly). `sweep`: whoosh = motion carrying ACROSS a cut (pair with the
+   exit→entrance handoff); riser = tension INTO a reveal — resolve exactly on the
+   downbeat, never into nothing (an unresolved riser is a broken promise).
+3. **Density has a perceptual ceiling.** Murch (*Dense Clarity — Clear Density*):
+   the brain tracks only ~two-and-a-half simultaneous sound streams; past that,
+   individual sounds stop reading and merge into texture — his mixes convey
+   complex scenes with a FEW carefully chosen elements. Our calibration: the
+   41.6s film that beat its reference carried 9 hits; the rejected cut carried 15
+   from 3 sounds. At 6+ hits the variety floor applies (`sfx-same-sound-reuse`
+   fires below 0.4 distinct/hits).
+4. **Hierarchy within a family** (Murch's balanced-spectrum principle + Material's
+   sound hierarchy): the pack orders soundIds subtle→strong; the biggest beat gets
+   the strong impact ONCE, everything else sits a tier down. Fifteen strong hits
+   = zero strong hits.
+5. **Gain staging.** SFX under a music bed must READ: target the hit ~≥6 dB above
+   the bed at its transient (our measured failure: ticks 1.5 dB over bed =
+   inaudible mush). Working precedent: sfx `volumeDb: -12`, bed lower still.
+   Author sane levels and STOP — the engine masters to −14 LUFS (the streaming
+   loudness standard); never pre-compress or push peaks to compensate.
+6. **The bed is tempo, not wallpaper.** Match bed BPM/energy to the cut rate (our
+   fast recut earned a 124 BPM driving bed; a calm film wants sparser pulse), arc
+   the energy with the narrative, and always `duck` under VO
+   (`duck: { duckDb, attackMs, releaseMs }`) — dialogue sits atop Murch's
+   encoded–embodied spectrum; sfx punctuate BETWEEN phrases, never fight words.
+7. **Silence is a device** (Thom: quiet is the most underrated tool in the
+   soundtrack). Clean air before the first hit; a dropout before the biggest
+   reveal is worth more than any riser. If the whole film is scored, nothing is.
+
+---
+
 ## Recognizing slop (the mechanism — so you can predict it, not just avoid it)
 
 Slop is the model's most common answer to an under-specified prompt: what the path of least resistance produces once the human decision layers are removed. It has a recognizable signature *because* each missing decision compounds:
@@ -136,7 +360,7 @@ One controlling idea every clip serves · grounded content of the real thing (re
 **Brief:** a product-launch video for Hexo Labs' product "SIA."
 **What the agent shipped (slop):** ~37s of purple-gradient slides with centered kinetic text; a static mocked terminal card pretending to be SIA running; a fabricated "14x faster" (the paper said **12.4%**); zero grounded content. A clean sweep of tells #1, #3, #4, #5, #7, #10.
 **What was sitting right there, ignored:** Hexo's own launch footage — two founders talking to camera in a nice office. *Precisely* CueFrame's home turf: `all-faces` on the two-shot / `active-speaker` on the singles, transcript-timed captions, a lower-third per founder, a color grade, a 4K render.
-**Craft looks like (same tool, same 37s):** `import_media` the founder footage → `get_media_context` for faces + transcript → reframe to whoever is speaking → transcript-tracked captions with a legibility plate → a title behind the head → a `lower-third` naming each founder → SIA's real brand type → if a benchmark appears, the real **12.4%** with source visible, ideally over a real capture of SIA running. One idea, grounded content, motivated cuts, honest data, a payoff. (Even the no-footage version was fixable: a Manim diagram of SIA's *actual* pipeline step beats a gradient — that's grounded too.)
+**Craft looks like (same tool, same 37s):** `import_media` the founder footage → `get_media_context` for faces + transcript → reframe to whoever is speaking → transcript-tracked captions with a legibility plate → a title behind the head → a `lower-third` naming each founder → SIA's real brand type → if a benchmark appears, the real **12.4%** with source visible, ideally over a real capture of SIA running. One idea, grounded content, motivated cuts, honest data, a payoff. (Even the no-footage version was fixable: an authored diagram of SIA's *actual* pipeline step beats a gradient — that's grounded too.)
 
 ---
 
@@ -202,8 +426,8 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | CTA | 62–75s | ~20 | One clear next step. |
 
 **Frameworks:** Hook → Problem → Solution → Proof → CTA. Decide the CTA first, script it last; write for the ear.
-**A fully animated explainer is a FIRST-CLASS grounded format**, not a fallback for missing footage. A Manim explainer built on diagrams of the *actual* mechanism (its real pipeline, the real data) is grounded — the grounding is that each visual depicts THIS thing specifically, not a decorative loop. Reach for it deliberately, not as a consolation for "no footage."
-**Reach for:** `generate_media` (prompt → `manim`) to anchor an abstract mechanism with a real diagram — *this is Manim's actual lane* (process/algorithm/data viz), not cinematic footage · `lower-third` for term labels · one idea per beat · when using real footage, narrate to the detected transcript timing.
+**A fully animated explainer is a FIRST-CLASS grounded format**, not a fallback for missing footage. An explainer built on authored diagrams of the *actual* mechanism (its real pipeline, the real data) is grounded — the grounding is that each visual depicts THIS thing specifically, not a decorative loop. Reach for it deliberately, not as a consolation for "no footage."
+**Reach for:** an authored `card` clip (your own HTML/typography, shelled with `applyMotionPreset`) to anchor an abstract mechanism with a real diagram — process/algorithm/data viz, not cinematic footage · `lower-third` for term labels · one idea per beat · when using real footage, narrate to the detected transcript timing.
 **Anti-patterns:** a wall of narration over stock gradient loops with no visual keyed to the words (the generic-filler tell — a purposeful diagram of the real mechanism is the opposite); explaining features before establishing the problem; using `generate_media` text-to-video to fake a "product" that doesn't match the real UI (it hallucinates specifics).
 **Quality bar:** every beat has a visual keyed to what's being said — grounded and specific to this content, not decoration; the hook lands in 3s.
 
@@ -248,15 +472,15 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | Bring in the real thing | `import_media` — requires `url` (public https) + `filename` + `contentType` (from the fixed enum: `video/mp4`, `video/quicktime`, `image/png`, `audio/mpeg`, …). Poll `list_media` or `create_webhook` on `media.completed` (status inside: complete|failed). |
 | Know where subject + speech are | `get_media_context` → face boxes per frame (with `faceId`) + transcript |
 | Keep the speaker framed / punch-in | `setCropIntents` op (the PREFERRED authoring path) or inline `reframe.segments` on a `clip.add` source. Each segment needs `startSec`/`endSec`/`focus`/`zoom`; **segments must TILE the clip** (an uncovered span → `reframe_coverage_gap` at validate). `focus.mode`: `frame-center` \| `point{x,y}` \| `face{faceId, shotScale?: close\|standard\|wide}` \| `all-faces` \| `active-speaker`. `zoom<1` punches in, `=1` full frame, `>1` rejected (min 0.1). Times in **seconds**. |
-| Captions that track real speech | `composition.captions.segments[].words[]` = `{text, startMs, endMs, emphasis?, annotate?: circle\|underline}` — word times in **milliseconds**. Style via `setCaptionStyle`: `position` (top\|center\|bottom), `entrance` (fade\|word-pop\|stagger-up), `emphasisPlate` + plate colors for legibility. **Captions have NO `zPlane`.** |
+| Captions that track real speech | `composition.captions.segments[].words[]` = `{text, startMs, endMs, emphasis?, annotate?: circle\|underline}` — word times in **milliseconds**. Author the words directly with the `setCaptions` op (segments wholesale — how a generated-VO film gets its word-synced spine without a source transcript); style via `setCaptionStyle`: `position` (top\|center\|bottom), `entrance` (fade\|word-pop\|stagger-up), `emphasisPlate` + plate colors for legibility. **Captions have NO `zPlane`.** |
 | Text behind the speaker's head | An `overlay` clip (a title/label primitive) with `zPlane:"behind-subject"` — NOT the caption layer. Render bakes the person matte + handles occlusion. |
 | Name someone / label a step | `lower-third` scene from `list_catalog` |
 | Title / closing wordmark | `cinematic-title` scene (closing, not opening) |
 | Grade the look | `color-grade` scene/effect |
-| Anchor an abstract mechanism | `generate_media` prompt → `manim` (diagrams of the real mechanism — NOT cinematic; a first-class grounded path) |
+| Anchor an abstract mechanism | An authored `card` clip + `applyMotionPreset` (diagrams of the real mechanism — NOT cinematic; a first-class grounded path) |
 | Long-form → clips | `suggest_briefs` → `wait_job(kind:"suggestions")` → `compose({ suggestionId })` |
 | Auto-reframe to another aspect | `derive_composition` (content-aware 9:16 / 1:1 / 4:5 from a 16:9 master) |
-| Discover what to build with | `list_catalog` — over MCP it takes **NO input params**, so the FULL catalog (87 primitives + 7 scenes) + your installed components returns, and you filter the RESULT **client-side** by `category`/`kind`/`tier`/`useCase`/`mood`/`intent`. Each entry carries `placement` (how to author it), `tier`/`useCase`, and `fixedCopy` (baked text no param changes). Read `cueframe://component/{id}` for the full **prop schema**. |
+| Discover what to build with | `list_catalog` — over MCP it takes **NO input params**, so the FULL live catalog + your installed components returns, and you filter the RESULT **client-side** by `category`/`kind`/`tier`/`useCase`/`mood`/`intent`. Each entry carries `placement` (how to author it), `tier`/`useCase`, and `fixedCopy` (baked text no param changes). Read `cueframe://component/{id}` for the full **prop schema**. |
 | Own / fork a custom graphic | `get_component_source` / `create_component` (self-contained tsxSource) / `update_component` — **see `cueframe-component-authoring`** for the full fork→preview→push loop |
 | Seed + edit the timeline | `apply_composition` (atomic batch ops; `dry_run:true` to check, `if_match` for OCC) — this is where clips, reframe, captions, and format are authored |
 | Set the brand | `create_brand_kit` (402-gated) → set `brandKitId` on the **project** (`create_project` / `update_project`). It lives on the project, NOT on a composition op — trying to set it elsewhere is silently dropped. |
@@ -270,7 +494,7 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 
 Everything needs a `projectId` — `create_project` is step 0.
 
-**Hard limits — respect them, don't fake around them.** No cinematic AI generation: `generate_media` is Manim + limited text-to-video/text-to-image/image-to-video; treat generated assets as *supporting graphics* (a diagram, a texture), never a fake-cinematic hero. No screen capture: that's Kishu (external). When the right move needs footage CueFrame can't generate, `import_media` real footage — do not synthesize a substitute. **Units trap:** `startTime`/`duration`/`trim`/reframe `startSec`/`endSec`/`ease` are **seconds**; caption word times are **milliseconds**. **Render-time fail-loud errors to expect** (render never ships a wrong frame silently): `content_anchor` (a clip's `trim` frames *different* footage than its captions show — align the trim to the captioned moment), `behind_split_unsupported` (one media used under two *different* behind-subject windows — one behind-subject window per MEDIA; to render two different behind windows of one source, import it as two separate MEDIA ITEMS (distinct mediaIds) — duplicating the same mediaId into two clips still throws), `BehindMatteUnresolved`/`TrajectoryUnresolved` (the behind/face bake found no detectable person — drop the intent or fix the source).
+**Hard limits — respect them, don't fake around them.** No cinematic AI generation: `generate_media` is limited text-to-video/text-to-image/image-to-video, plus audio: `text-to-speech` (narration VO) and `text-to-music` (instrumental bed); treat generated *visual* assets as *supporting graphics* (a diagram, a texture), never a fake-cinematic hero. No screen capture: that's Kishu (external). When the right move needs footage CueFrame can't generate, `import_media` real footage — do not synthesize a substitute. **Units trap:** `startTime`/`duration`/`trim`/reframe `startSec`/`endSec`/`ease` are **seconds**; caption word times are **milliseconds**. **Render-time fail-loud errors to expect** (render never ships a wrong frame silently): `content_anchor` (a clip's `trim` frames *different* footage than its captions show — align the trim to the captioned moment), `behind_split_unsupported` (one media used under two *different* behind-subject windows — one behind-subject window per MEDIA; to render two different behind windows of one source, import it as two separate MEDIA ITEMS (distinct mediaIds) — duplicating the same mediaId into two clips still throws), `BehindMatteUnresolved`/`TrajectoryUnresolved` (the behind/face bake found no detectable person — drop the intent or fix the source).
 
 **Worked alignment example (the error-prone mechanic).** You want the caption emphasis to land on the founder's stressed word "faster," and the frame to punch in on the same beat. From `get_media_context`, the transcript word "faster" runs `startMs:8120, endMs:8560` (transcript/source time). **For these round numbers, assume an untrimmed clip placed at timeline 0** — then source time, timeline time, and clip-relative time all coincide. So: put that word in `captions.segments[].words[]` with `emphasis:true` at `startMs:8120`; and author reframe with `setCropIntents` as a **contiguous segment list that tiles the whole clip** — e.g. a wide segment `{startSec:0, endSec:8.12, focus:{mode:"active-speaker"}, zoom:1}` then the punch `{startSec:8.12, endSec:<clipEnd>, focus:{mode:"face",faceId:"…",shotScale:"close"}, zoom:0.8, ease:{in:0.4,out:0}}` (ms → s: 8120ms = 8.12s). A lone mid-clip segment that leaves `[0..8.12]` uncovered fails validation with `reframe_coverage_gap`.
 
@@ -304,7 +528,7 @@ These are *archetypes*, not documented cuts of specific films — reason from th
 VISION (one line): the ONE controlling idea for THIS video — a value + a cause.
 FORMAT: [product-launch | social-clip | explainer | demo | talking-head]
 SOURCE REALITY CHECK: what GROUNDS this video (after HUNTING for footage — 3a)? Real
-  footage, real UI/data, or a purposeful content-specific graphic (e.g. a Manim diagram
+  footage, real UI/data, or a purposeful content-specific graphic (e.g. an authored diagram
   of the actual mechanism). If the only plan is generic filler, the 3b stop fired and
   the user has explicitly said "proceed."
 
@@ -351,7 +575,7 @@ VISION: "Two founders who clearly believe in SIA tell you, to your face, why it'
   faster — and you watch it BE faster."
 FORMAT: talking-head + real demo (NOT slides).
 SOURCE REALITY CHECK: HUNT (3a) → Hexo's real launch = two founders to camera → import
-  it. If no footage: a real capture of SIA running, or a first-class Manim diagram of
+  it. If no footage: a real capture of SIA running, or a first-class authored diagram of
   SIA's actual pipeline (grounded, not a consolation) — NOT a gradient deck. Generic
   filler = fail.
 
@@ -431,7 +655,7 @@ Every line names a frame and asks a question a PNG can answer — is a grounded
 
 0. `create_project` done; `get_account` shows the render/compose/generate calls are within plan entitlements and cost ceilings.
 1. Vision written as one sentence (value + cause); format chosen.
-2. Footage HUNTED (3a); if the plan is generic filler, the 3b tradeoff stated to the user and an explicit "proceed" received (a purposeful, specific graphic — e.g. a Manim diagram of the real mechanism — does NOT require the stop).
+2. Footage HUNTED (3a); if the plan is generic filler, the 3b tradeoff stated to the user and an explicit "proceed" received (a purposeful, specific graphic — e.g. an authored diagram of the real mechanism — does NOT require the stop).
 3. Rubric written *before* any render — named-frame must-haves, measurable thresholds (grounded content dominates the runtime; footage-based formats real-footage ≥60%), the mandatory K1–K3 (meaning preserved, phrasing adapted to your video), and written provenance for every number.
 4. Real source imported (`list_media` shows it ready); `get_media_context` faces + transcript pulled and used for reframe + caption timing (when the piece uses footage).
 5. Components discovered via `list_catalog` (no hand-placed hex where a built-in exists); `fixedCopy` checked so no baked text lies. Brand set via `brandKitId` on the project if a brand kit exists.

package/skills/cueframe-brand-demo/SKILL.md

@@ -5,6 +5,9 @@ description: Use when turning a local app into a brand-consistent product demo w
 
 # CueFrame — Brand demo recipe
 
+> **Kit truth over MCP (current limits):** kit CONTENTS are not yet inspectable over MCP (`get_profile` lists names only), so `$brand:` tokens resolve blind — verify resolved fonts/colors with a `preview_frame` still, and when the kit conflicts with an explicit client spec, the spec wins (hardcode it and note the conflict). Bind kits by the SERVER id from `get_profile` (slug binding is unreliable — it can silently bind nothing); always confirm via the project response `brandKitId`.
+
+
 A **use-case recipe** that runs end-to-end from inside the user's own project
 folder. You (Claude) already see their code and their running app — that's the
 unfair advantage. This skill turns that context into a brand-consistent product

package/skills/cueframe-cli/SKILL.md

@@ -157,7 +157,7 @@ video and composites it (the shared renderer never runs your code).
 cueframe init --json
 
 # 2a. FORK a built-in primitive into cueframe/components/<id>/ as owned, editable source.
-#     Discover ids from the catalog: cueframe api GET /v1/components   (87 primitives).
+#     Discover ids from the catalog: cueframe api GET /v1/components   (the live primitive catalog).
 cueframe eject cinematic-title --json
 
 # 2b. …or scaffold a blank custom component.

package/skills/cueframe-component-authoring/SKILL.md

@@ -27,7 +27,7 @@ Single self-contained module per component (`create_component` takes one `tsxSou
    ids from the catalog (`/v1/components`). *(Or author from scratch — skip to step 2.)*
 2. **Author/own it:** edit the `tsxSource`, then `create_component({ componentId, tsxSource, … })`
    to store your customized copy (origin `server-native`; if forked, `ejectedFrom` is stamped).
-3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` (sessionless — a cold first call returns 409 box_warming; retry in a few seconds)
+3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` (sessionless; if a cold first call returns 409 box_warming, retry in a few seconds)
    renders ONE still. A 422 `component_does_not_compile` returns the compiler error — read it, fix
    via `update_component` (same id, in place), preview again.
 4. **Render:** add it to a composition as an `alpha-layer` clip (`apply_composition`), then

package/skills/cueframe-compose-loop/SKILL.md

@@ -5,6 +5,9 @@ description: Use when an AI agent should DRIVE CueFrame to a high-quality clip i
 
 # CueFrame — Compose convergence loop
 
+> **LANE SCOPE:** this skill is written against the DESKTOP/REST compose-session surface. Over MCP those endpoints do not exist — use the `composing-video` skill (sessionless judge/preview) instead; this document is reference for the REST lane only.
+
+
 You are the director. CueFrame gives you hands (author), eyes (capture), and a
 judge (verify); you supply the taste and the iteration. The engine does NOT
 auto-compose for you here — you drive the loop and decide when it's done. Drive

package/skills/cueframe-storyboard/SKILL.md

@@ -5,6 +5,9 @@ description: Use BEFORE composing when starting a NEW video from scratch and you
 
 # CueFrame Storyboard: brief → flow
 
+> **The bar:** the `video-craft-standards` skill (GET /v1/skills/video-craft-standards) defines DONE for every artifact class — per-class MUST checklists and kill criteria. Read it before composing and score against it before rendering. When this skill and that document disagree, the standards win.
+
+
 ## The one idea
 
 **You are the planner.** You have the user, the whole conversation, the brand, and the judgment — you are

package/skills/every-format-from-one-edit/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: every-format-from-one-edit
+description: Derives content-aware 9:16, 1:1, and 4:5 siblings from one finished composition — same edit, every platform, no re-editing. Triggers on "make this vertical too", "I need this for TikTok and LinkedIn", "every aspect ratio", "square version of this", "resize for Reels", "one video, all platforms", "port this edit to Shorts".
+---
+
+# Every format from one edit
+
+You finish ONE edit; you get back its siblings for every platform — 9:16 for
+Reels/TikTok/Shorts, 1:1 and 4:5 for feeds — derived content-aware from the master,
+subject-tracked rather than letterboxed, each judged and rendered on its own. The edit decisions
+are made once; the formats are a job, not a re-edit.
+
+## Before you start
+
+Confirm which master and which target platforms before setup. When the first tool call
+approaches and CueFrame isn't connected:
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — browser OAuth,
+  one **Allow** click.
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
+  `https://api.cueframe.ai/v1/mcp`.
+- **Other agents:** paste `set up https://cueframe.ai/skill.md`, or run
+  `npx -y cueframe install`.
+
+Then straight to deriving — this whole job is minutes when the master is good.
+
+## Inputs
+
+- **The master composition** (required): a finished, approved edit — find it via
+  `list_compositions` if the user doesn't have the id. If the master isn't done, finish it first
+  (this skill multiplies quality AND flaws).
+- **Target aspects**: default all three siblings — 9:16, 1:1, 4:5. The documented derive lane
+  starts from a 16:9 master.
+- **Per-platform tweaks**: default none — determinism is the point. Take an explicit ask (e.g.
+  "shorter for TikTok") as a separate edit on the derived sibling.
+
+## Workflow
+
+1. **Verify the master is actually done.** It passed its class checklist, its audio was
+   decided, its render was approved. Deriving from a draft ships the draft's flaws four times.
+2. **Derive each sibling.** `derive_composition` per target aspect — the reframe is
+   content-aware: it tracks the subject into the new frame instead of letterboxing. Each
+   sibling is a real composition you can edit independently afterward; the master is never
+   touched.
+3. **Audit every sibling on real pixels — required, not optional.** `preview_frame` each
+   sibling at t=0, hook-end, and each card's midpoint; describe each still. What to look for
+   per aspect: the subject's head fully in the vertical frame; cards and captions inside the
+   safe area (no critical copy in the outer ~8%); no beat where the tighter crop lost the thing
+   the beat exists to show.
+4. **Fix per-sibling, surgically.** Where a crop or card misbehaves, `apply_composition` on
+   THAT sibling — nudge a `setCropIntents` segment, resize a card for the narrower frame
+   (re-shell with `applyMotionPreset` in a following call if you replace the card). Don't
+   re-edit the story; the story is the master's.
+5. **Confirm the audio carried.** The master's decided audio — bed, ducking, beat-aligned cuts
+   (`materializeGrid` markers), or its intentional silence — rides into each sibling. Verify
+   the bed is present and the silence decision, if any, still holds; the sibling's delivery
+   note repeats it. If a sibling needs a different bed, `search_resources` honoring the brand
+   kit's `musicMood` and swap it on that sibling only.
+6. **Judge each sibling as its own artifact.** `score_composition` per sibling with the
+   master's vision as `editorialIntent`. A 9:16 sibling is a social reel and answers to that
+   class's checklist — hook inside 2 seconds still applies in the new crop. Fix worst-first to
+   ≥ 7.5.
+7. **Render each approved sibling.** `create_render` → `wait_job (kind:"render")` per
+   composition. One final render per approval; iterate with previews.
+
+## What good looks like
+
+Quoted from `video-craft-standards` (cross-cutting rules — every artifact):
+
+> **MUST** Safe-area respected: no critical copy in the outer ~8% of frame.
+
+> **MUST** One final render per approval; iterate with previews, not renders.
+
+> **MUST** Delivery never ends with "done": the last message carries the output link and where
+> to find it, plus the intentional-silence note if any.
+
+And the class rule that governs each sibling: a derived 9:16 answers to §1 (Social reel) —
+*"**MUST (K)** The hook lands inside 2 seconds"* — a derived 16:9 to its own class. Derivation
+changes the frame, never the bar.
+
+## Delivering
+
+The last message is a manifest, never "done":
+
+- Every sibling's render link, labeled by aspect and platform, and where each lives (project +
+  composition id — the master's id too, since it stays the source of truth).
+- The master's attribution list (it covers all siblings — same assets).
+- The intentional-silence note, restated once, if the master chose silence.
+- Any sibling-specific edits you made (which crop nudged, which card resized) so future master
+  edits know what to re-check after re-deriving.