cueframe 0.4.10 → 0.7.0

package/dist/skills/composing-video/SKILL.md

@@ -5,129 +5,39 @@ description: Use when an agent is asked to make ANY video with CueFrame — a pr
 
 # Composing Video: craft for CueFrame
 
+## Scope and capability policy
+
+User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
+
+Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
+
+For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+
 For preview selection and small revisions, use `cueframe-compose-loop`'s
 [preview workflow](../cueframe-compose-loop/references/preview-workflow.md). Retain the approved
 brief/rubric for a local correction; check the affected behavior and relevant regressions instead
 of restarting the new-film method below. A diagnostic or preview-only request does not require
 a final export or a whole-film judge pass. Explicit user scope takes precedence over craft defaults.
 
-> **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, 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 (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 launch-video case below.
-
-**The loophole to nail shut:** "purposeful graphics" means *specific to this content* — the real mechanism, the real data, a diagram of the actual thing. Animated/kinetic TEXT by itself is not that, no matter how deliberate — it is not grounding. A generic gradient or aurora is NEVER "purposeful"; it is always the slop default. The reframe broadens what counts as good; it does not wave decorative filler through.
-
-**The boundary.** This is craft guidance you can override, not a gate. You own the **vision** (the one idea for this specific video) and you own **data correctness** (if you supply a wrong number, CueFrame renders it faithfully and the mistake is yours). CueFrame owns being faithful, legible, and teaching you the craft below. Reason from these principles; break a rule knowingly when your vision demands it. (Skip this whole flow only for a pure re-render of an already-approved composition, or a single trivial still — don't ceremony a one-liner.) Planning a new video from scratch? Do **`cueframe-storyboard`** first to get the beat flow, then apply this craft to each beat.
-
----
-
-## Related skills & positioning
-
-This skill is the **craft / quality layer** for an agent driving CueFrame over the **MCP tool surface** (`preview_frame` / `apply_composition` / `score_composition` / `create_render`) — *not* the `cueframe` CLI binary. It owns the decision layer: vision → rubric → grounding → iterate → verify. When a mechanic below is owned by a sibling skill, defer to that skill for the deep how-to:
-
-- **`cueframe-storyboard`** — the intake/structure step BEFORE craft: interview the user for the brief and lay out the hook→body→cta beat flow. Start here for a new video from scratch; this skill then makes each beat grounded and good.
-- **`cueframe-cli`** — the `cueframe` binary + wire mechanics (auth, projects, raw request/response shapes).
-- **`cueframe-compose-loop`** — the full author→render→verify→fix **convergence loop**; it owns the loop budget and ship bar (this skill's step 6 mirrors it: 3–5 passes, ship at composite ≥ 7.5).
-- **`cueframe-product-video`** — the click-points → reframe-segment **auto-zoom tiling** + picture-in-picture recipe for screen demos.
-- **`cueframe-brand-demo`** — brand-token vocabulary + auto intro/outro/logo for branded launches.
-- **`cueframe-component-authoring`** — the full fork → preview → push loop for custom components.
-- **`cueframe-scene-shot`** — the 3D product shot authored as JSON (a tilted page screenshot, a lit laptop/phone showing a real app screenshot, camera move, focus). Reach for it *before* hand-writing a WebGL component for a device mockup.
-
-Loading this skill and a sibling together: this one governs *what makes the video good*; the sibling governs *how that mechanic works*.
-
----
-
-## If you read nothing else
-
-Six non-negotiables. Everything below is the reasoning behind them.
-
-1. **HUNT for real footage FIRST** — it's the strongest grounding and CueFrame's edge — before building without it; that failure was never looking.
-2. **Write a harsh, specific rubric BEFORE you render a single frame** — including the three mandatory kill criteria (K1–K3), meaning preserved.
-3. **Grounded, specific content must DOMINATE the runtime** — real footage, real UI/data, or purposeful content-specific graphics — never generic/decorative filler. (For footage-based formats, target real footage ≥60%.)
-4. **Describe every rendered still in words before you score it** — if you can't say what's in the frame, you didn't look.
-5. **Get an independent grade you can't game:** `score_composition` samples its own frames — you cannot cherry-pick flattering timestamps past it.
-6. **Budget 3–5 verify passes, never set your ship bar below 7.5/10, then stop.**
-
----
-
-## The method — run these steps in order, every time
-
-The order is the forcing function. Steps 2, 3, and 5 are where agents cut corners and ship slop, so they are not optional.
-
-### 1 — Decide the VISION, then the FORMAT
-Write the controlling idea as one sentence with a value and a cause — "X wins *because* Y" (McKee, *Story*: a story is a charged value-shift, not a topic). Not "product launch" — a claim: "Two founders tell you, to your face, why their product kills the pipeline step you dread — and you watch it be faster." Then pick the format floor: product-launch / social-clip / explainer / demo / talking-head (playbooks below). The vision is the filter for what belongs; anything that doesn't express it gets cut.
-
-### 2 — Write a HARSH, SPECIFIC rubric — BEFORE you render anything
-Authored against the vision, before pixels exist, so it can't be rationalized after the fact. Use the template below: must-haves anchored to named frame timestamps, measurable thresholds, and kill criteria that fail the render outright.
-
-**Hard gate:** do not call `preview_frame` until the rubric text exists in your context. No rubric → no pixels.
-
-**These three kill criteria are MANDATORY — preserve the MEANING of K1–K3 in every rubric, adapting the phrasing to your video. You may add more; you may not remove or weaken these:**
-- **K1.** Any sampled frame is a gradient/solid background with only text and NO grounded subject — no real footage, no real UI/data, no purposeful content-specific graphic, just decorative filler. Animated/kinetic TEXT over any background does NOT count as a grounded subject — only a visual of the real mechanism or real data does.
-- **K2.** Any on-screen number you cannot trace to a written source, or any faked/mocked UI standing in for a real capture.
-- **K3.** Generic/decorative filler dominates the runtime — grounded, specific content (real footage, real UI/data, or purposeful content-specific graphics) does not.
-
-### 3 — Ground the video (hunt for footage first, then a grounding ladder — never straight to generic filler)
-
-Real footage is the strongest grounding and CueFrame's edge, so hunt for it FIRST — but grounding is the goal, and purposeful, specific graphics are a legitimate way to reach it.
-
-**3a. Hunt for footage FIRST, before building without it.** Before you build without footage, actively look, in order:
-1. Did the user attach or name footage?
-2. Does the subject (company/person/product) already have a launch video, founder clips, demo recordings, or a conference talk you can `import_media` from a public https URL?
-3. Ask the user directly: *"Do you have a founder clip, screen capture, or event recording? CueFrame is built to compose real footage — it's the difference between a launch film and a slideshow."*
-
-In the launch-video 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 / an authored diagram of the actual mechanism]. Want to proceed as generic motion-graphics, or ground it first?"*
+## Plan and author to the request
 
-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.
+Use `cueframe-storyboard` only when new work lacks structure. For an existing title correction, retain the approved brief and edit the title directly; no whole-film rubric, paid judge or final export is required.
 
-**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 needs an external screen-capture client — e.g. a headed Playwright walkthrough recorded to MP4 — or the user's own recording).
-3. **Real product screenshots / photos** as held stills with **motivated** motion.
-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.
+Choose content that serves the requested idea. Real footage, actual product captures, sourced data, diagrams, abstract motion and typography are all valid. Do not fabricate facts or present simulated UI as a real product capture. Search for footage when the request needs it; an explicit typography-only request needs no footage hunt or permission to remain typography-only.
 
-Do not fake the missing footage, and do not dress up generic filler as grounding.
+For new work, state concise acceptance criteria from the brief before authoring. For broader review, reuse the approved criteria. Preview affected frames, inspect motion in the relevant window and listen when sound changes. Validate contracts and source/media bindings independently of aesthetic review. For face/active-speaker framing or behind-subject graphics, prepare the required subjectTrack/matte for the exact source trim window and wait for ready evidence; unresolved perception is not acceptable preview proof.
 
-### 4 — Author against `get_media_context`
-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.
+Use `score_composition` only when its broader editorial critique is useful, available and within budget. The hosted judge has editorial, spatial, brand and caption criteria; `editorialIntent` does not remove fixed criteria. A caption penalty for intentionally uncaptioned or silent work is a judge limitation, not a reason to add captions or declare user intent failed. Skill text does not repair the judge. Stop after two no-improvement passes and report gaps.
 
-If `faces.status` is `not_detected` and the edit uses `active-speaker`/`face` framing, call `prepare_media` with `kind:"subjectTrack"` and the clip's exact SOURCE trim window, then poll `get_media_facts` with that same kind/window until `exact.state:"ready"`. Do the same with `kind:"matte"` before sighting a `zPlane:"behind-subject"` graphic. `preview_frame` and `score_composition` fail loud when required perception is unresolved; never treat a flattened title or a static wide crop as acceptable preview evidence.
+## Choose the film spine from the leading material
 
-### 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**. It queues durable capture and returns a `jobId`; call `wait_job(kind:"preview_frame")` until the evidence is terminal.
+- Narrated explainer: draft the script, align visuals to its phrases, verify intelligibility and any requested captions against actual word timings.
+- Recorded interview: preserve meaning and source order where required; cut and frame from the transcript and actual speaker evidence, with no invented narration.
+- Product action: plan around real captured interactions and results; add voice or music only when requested or appropriate.
+- Silent brand study or typography: plan visual rhythm, reading time and transitions directly. Silence is already decided by the request; no audio generation or footage requirement.
+- Visual/music motion or observational sequence: use the chosen motion, music, activity or deliberate holds as the timing authority. No universal beat count, cut interval or CTA.
 
-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.
-
-`validate_composition` only checks shape (membership, params, track-family, reframe coverage) — a pass there means nothing about quality. Judge the pixels, not the JSON.
-
-### 6 — Get an independent second opinion, then stop
-You grading your own render is the weak link. Call `score_composition` with your VISION line as `editorialIntent` and brand facts as `brandContext`, then call `wait_job(kind:"verify")`. It renders and grades **four fixed server-side criteria** — editorial, spatial, brand, caption (0–10 each) — plus a weighted composite and a worst-first critique, **on frames it samples itself.** Your `editorialIntent` steers *what "good" means for this video*; it does **not** replace the criteria, and you cannot feed it your own rubric or pick its frames — that un-gameable sampling *is* the independence. Treat a low score on a frame you didn't choose as ground truth, not noise.
-
-Fix the worst thing via `apply_composition`, preview the affected frames and motion, and re-score when useful. For a whole-film review, budget up to 3–5 verify passes; two no-improvement passes are a reason to stop spending and report remaining gaps (`cueframe-compose-loop` owns the convergence loop). The rubric's acceptance criteria still apply; a score around 7.5 is guidance, not permission to ship a known mismatch. Hosted preview and scoring are stateless durable jobs; there is no hosted session to close.
-
----
-
-## 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.
+Use `cueframe-component-authoring` for custom 2D motion. Load `cueframe-scene-shot` for supported device, camera or 3D tasks. `cueframe-compose-loop` owns scoped preview and optional review; `video-craft-standards` supplies aesthetic defaults under the scope policy above.
 
 ### The card token contract — `tokens` key `x` is read as `var(--cf-x)`
 
@@ -163,7 +73,7 @@ Chromium captures; the clock never advances). Use these instead:
    `--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
+   an exit slide via `--cf-exit`. This supports entrance/exit choreography within 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.
@@ -191,11 +101,10 @@ 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
+**Optional audio review:** the `sfx-same-sound-reuse` craft floor can report
 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
+to support a varied palette. This is reported judge behavior, not a universal creative requirement: preserve intentional repetition or silence and assess it against the brief. Browse the full palette structurally on
 `list_catalog` (the `sfx` array — `soundId`, `family`, `envelopeClass`,
 `description`, `durationSec`).
 
@@ -255,7 +164,7 @@ soundtrack is a measurable share of whether anyone keeps watching.
    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
+   *voice* (author the script first for a narrated piece, 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`),
@@ -342,8 +251,8 @@ soundtrack is a measurable share of whether anyone keeps watching.
    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).
+   from 3 sounds. At 6+ hits optional audio review may report `sfx-same-sound-reuse`
+   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
@@ -364,56 +273,15 @@ soundtrack is a measurable share of whether anyone keeps watching.
 
 ---
 
-## 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:
+## Craft defaults
 
-- **No juxtaposition, no meaning.** Meaning in video is manufactured by adjacency — the same neutral shot reads as grief or desire depending only on the shot next to it (Kuleshov effect; Eisenstein's montage of collision). A gradient next to a gradient creates nothing. Grounded, specific shots in sequence (problem-shot → product-shot → relief-shot) make a claim the individual shots never state. Compose in **pairs and triads**, ordered so adjacency does the arguing.
-- **No specificity, no belief.** Images are encoded more deeply than abstract words (picture-superiority effect, Paivio), and — a separate, stronger mechanism — a real human face is among the most attention-binding things a screen can show. "10x faster" on a card is an abstraction the viewer can't feel; real people talking in a real room, or a diagram of the *actual* mechanism, is embodied and credible — it *shows*.
-- **No subject, no eye-trace, no peak.** With nothing specific on screen there's no focus of interest to cut on (Murch's eye-trace) and no candidate for the one emotional peak the viewer remembers (Kahneman's Peak-End Rule). A flat decorated slideshow has no peak and a whimper ending.
+Make deliberate choices about hierarchy, type, framing, juxtaposition and motion. For a product demonstration, use real captures and sourced claims; never present a mock UI as documentary evidence or invent a performance number. For an explicit abstract or typography study, judge its reading time, rhythm and visual intent directly: text and gradients are valid material, not automatic failures.
 
-So grounding the video (step 3) is load-bearing, not a preference. Missing it guarantees the rest.
+Platform conventions can suggest hooks, captions, short cuts and clear closing actions. Apply them only when they serve the requested format. An observational long hold, slow logo-first opening, silent piece or no-CTA ending is not a failure merely because another format prefers something else. Caption speech when requested or appropriate; verify actual word timing. Use audio or visual rhythm as the timing authority selected in the brief.
 
-### Slop tells — you are making slop if a frame has any of these
-1. **Gradient/aurora background under centered kinetic text**, no grounded subject. The literal default of every text-to-video toy. Zero information per frame — animating the text, or calling it "purposeful kinetic typography," does NOT ground it; only a visual of the real mechanism or real data does.
-2. **Generic AI b-roll** — glowing brains, blue circuit boards, particle networks, rotating server racks, holographic dashboards. "Technology" as a vibe; interchangeable across a thousand companies.
-3. **Faked or mocked UI/terminals** — a styled `<div>` pretending to be the product. The cursor doesn't blink, nothing scrolls, the output is too clean. A real 4-second capture beats it every time.
-4. **On-screen numbers with no real source** — "10x", "5x", "99.9%" over a gradient. Unsourced is the content-farm tell; *wrong* is a credibility bomb.
-5. **All generic filler, nothing grounded** — 100% decorative generated backgrounds and kinetic text, with no real footage, no real UI/data, and no purposeful content-specific graphic. The master failure that produces all the others. (A *purposeful* animated explainer — one built on diagrams of the real mechanism or animations of the real data, NOT animated copy — is grounded and does NOT count as this tell.)
-6. **Unmotivated motion** — everything drifts, floats, Ken-Burns-pans, swoosh-transitions for no reason. The screensaver aesthetic: soft, well-oiled, no harsh edges, regardless of content.
-7. **Template rhythm** — title card → 3 bullet slides → CTA, every beat the same length and entrance. The eye recognizes the mold.
-8. **Metronomic pacing** — every clip the same length, every caption the same duration, no held beat before the payoff. The tell of an algorithm chunking on a timer.
-9. **Off-brand default type / over-captioning** — Inter/Arial where a brand typeface exists; karaoke captions on a slideshow with no speech to caption.
-10. **Dead-center symmetry, one z-plane** — subject and text fighting for the same pixels, throwing away the depth CueFrame gives you (an overlay title at `zPlane:"behind-subject"`).
+## Format playbooks (examples, not fixed structures)
 
-### The positive inverse — author toward these
-One controlling idea every clip serves · grounded content of the real thing (real footage, real UI/data, or a purposeful diagram of the actual mechanism) · motivated motion (the frame moves because the subject moved or the idea turned) · restraint (fewer elements, held longer) · typographic discipline (brand type, ≤2 weights, one hierarchy) · honest data with visible provenance ("8.5%, with the source on screen" beats "10x") · varied pace that builds to one memorable beat · real depth (a title behind the head, layered z-planes).
-
-### The launch-video case — the exact contrast to burn in
-**Brief:** a product-launch video for a developer-tools product. (Composite example.)
-**What the agent shipped (slop):** ~37s of purple-gradient slides with centered kinetic text; a static mocked terminal card pretending to be the product running; a fabricated "10x faster" where the sourced result was **8.5%**; zero grounded content. A clean sweep of tells #1, #3, #4, #5, #7, #10.
-**What was sitting right there, ignored:** the team's own launch footage — people talking to camera in a nice office. *Precisely* CueFrame's home turf: `all-faces` on a two-shot / `active-speaker` on the singles, transcript-timed captions, a lower-third per speaker, a color grade, a 4K render.
-**Craft looks like (same tool, same 37s):** `import_media` the interview 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 speaker → the team's real brand type → if a benchmark appears, the real **8.5%** with its source visible, ideally over a real capture of the product running. One idea, grounded content, motivated cuts, honest data, a payoff. (Even the no-footage version was fixable: an authored diagram of the product's *actual* pipeline step beats a gradient — that's grounded too.)
-
----
-
-## Operating floors (fold into every format)
-
-Directional, not laws — reason above them:
-
-- **Hook = first 3 seconds.** Viewers decide to stay or scroll almost immediately; the first frame is the highest-leverage frame in the piece. Budget craft disproportionately to 0–3s. Put a real face or real motion there — never a logo fade.
-- **Caption speech, always.** Most social video is watched sound-off, and captions lift retention and completion — treat them as mandatory, not decoration. Attach `captions` with word-level timing from `get_media_context`; set legibility via `setCaptionStyle` (`position` + `emphasisPlate`). Caption **speech** — do not karaoke a slideshow.
-- **Length: earn it.** Engagement decays with length; short pieces complete far better than long. A sub-1-min teaser is watched to the end at rates a 5-min film never sees; instructional pieces are the exception *only* when they genuinely teach. Never pad — every second must carry the idea forward.
-- **Cut cadence (motivated, never for its own sake):** a visual change every ~1.5–2s for sub-60s pieces; B-roll shots ~1.5–3s (>3s stalls); cinematic ~4–6s. For talking-head/demo the two operations differ: **reframe/punch-in every ~3–4s *within* a held speaker shot**, and insert a B-roll **cutaway every ~5–8s** of continuous talking. Drive with clip `trim`/`duration` and overlay entrance timing — but every change of state must be *motivated* (a reframe to the speaker, a lower-third entrance, a caption emphasis).
-- **Word budget:** ~130–150 wpm; 60s ≈ ~130 words; a 12–15-word hook ≈ 5–6s of speech. Past ~160 wpm reads rushed.
-- **Sound sets perceived pace.** CueFrame composes to an existing audio bed — use it: land caption entrances and cut points on stressed words / beats via the transcript's word timing (a cut on the beat reads as craft, off it reads as accident — synchresis, Chion); duck music under speech; hold one beat of silence before the payoff line. Silence before the peak is a tool, not an absence.
-- **The saturated default.** Gradient-text-over-music synced to a beat is the *standard* software-launch look, not a differentiator. When you reach for that generic default instead of grounding the piece, you land in exactly that interchangeable tier — which is the whole reason step 3 exists.
-
----
-
-## Format playbooks
-
-Each playbook is a **floor**, not a template — reason above it. Every beat maps to a real CueFrame capability. Default to **16:9 landscape** for product/demo/explainer/founder-web; **9:16 vertical** only for social cutdowns (a wide source crammed vertical crops the subject wrong and wastes the frame).
+Each playbook is an illustrative format default; explicit intent and scope govern. Every beat maps to a real CueFrame capability. Default to **16:9 landscape** for product/demo/explainer/founder-web; **9:16 vertical** for social cutdowns or other explicitly vertical work (a wide source crammed vertical crops the subject wrong and wastes the frame).
 
 ### 1 — Product launch / announcement
 **When:** launching or announcing a product; teaser or full launch film.
@@ -427,7 +295,7 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | CTA + date | 40–45s | Exact action + launch date. Logo last. | ≤12 |
 
 **Frameworks:** 3-act teaser (Tease → Reveal → CTA) or StoryBrand SB7 (customer is hero, you are guide). One pain or one wow — not five diluted features.
-**Reach for:** `import_media` a real demo capture or founder clip · `list_catalog` → the `product-launch-trailer` and `cinematic-title` scenes (use `cinematic-title` for the *closing* wordmark, never the open) · `color-grade` for the hero look · date + CTA on the final held frame.
+**Reach for:** `import_media` a real demo capture or founder clip · `list_catalog` → the `product-launch-trailer` and `cinematic-title` scenes (use `cinematic-title` for a wordmark where the brief calls for it) · `color-grade` for the hero look · date + CTA on the final held frame.
 **Anti-patterns:** opening on a logo animation; stacking five features; narrating specs; a fabricated/rounded stat; a mocked terminal standing in for a real screen.
 **Quality bar:** the first frame survives with zero text on it. If your open is a gradient with the product name, you've already lost.
 
@@ -513,8 +381,8 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | 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 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 |
+| Discover what to build with | `list_catalog` — pass filters such as `category`/`kind`/`tier`/`useCase`/`mood`/`intent`, plus `limit` and the returned pagination cursor. For builtin packages, request `projection:"component-library"` and `origin:"builtin"`, then resolve the selected exact identity before insertion. 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` (exact scoped v3 pin for builtins) / `create_component` / `update_component` (preserve the complete source snapshot) — **see `cueframe-component-authoring`** for the full fork→preview→push loop |
 | Several cells that share space and must reflow together (feature grid, rail + fluid content, cast + type) | An authored component on `FlexLayout` from `@cueframe/animate` — tracks are **weights** (`{ weight: 0, basis: px }` = content-sized, pushes neighbours), `tracksEnd` animates the reflow per frame, `fits` per cell (`stretch`/`contain`/`cover`/`position`/`scale`/`matte`). Static PiP / split is clip `region` + `fit` instead. Never CSS-scale the layout. **See `cueframe-component-authoring`** |
 | 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. |
@@ -526,11 +394,11 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | Independent grade (steered, un-gameable) | `score_composition` (sessionless; `editorialIntent`=your vision, `brandContext`=brand facts) → four fixed criteria + composite + worst-first critique, on frames it samples itself |
 | Director ensemble compose | `compose` — set EXACTLY ONE of `fromComposition:true` (author from the seeded composition) or `suggestionId` (clipping path) → `wait_job(kind:"compose")` |
 | Final MP4 | `create_render` → `wait_job(kind:"render")` or `create_webhook` on `render.completed`; `retry_render` (transient only) / `cancel_render` |
-| Orient before spending | `get_account` FIRST — read `balance`, NOT `included`. Rendering / generation / previews / judge / Director share ONE credit wallet (`fundedBy`); each `balance` restates that same wallet in that feature's unit. Balance > 0 = proceed — never tell the user a capability is missing, never send them to checkout. New orgs get a free credit grant, so an empty usage history is not a blocker. 402 `billing_required` fires once the balance is spent; `generate_media` also 402s over its USD ceiling |
+| Orient before spending | `get_account` FIRST — read `balance`, NOT `included`. Rendering / generation / previews / judge / Director share ONE credit wallet (`fundedBy`); each `balance` restates that same wallet in that feature's unit. Positive balance is not proof of capability or entitlement: check the exposed contract, entitlements and quote before proceeding. New orgs get a free credit grant, so an empty usage history is not a blocker. 402 `billing_required` fires once the balance is spent; `generate_media` also 402s over its USD ceiling |
 
 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 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 needs an external screen-capture client (e.g. a headed Playwright walkthrough recorded to MP4). 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); use generated visuals where their actual capabilities fit the brief, and do not present synthetic footage as documentary evidence. No screen capture: that needs an external screen-capture client (e.g. a headed Playwright walkthrough recorded to MP4). 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`.
 
@@ -538,165 +406,42 @@ Everything needs a `projectId` — `create_project` is step 0.
 
 ---
 
-## Craft principles (reason FROM these — the rules above are their consequences)
+## Craft principles (aesthetic defaults) (reason FROM these — the rules above are their consequences)
 
-- **Curiosity is an information gap** (Loewenstein, 1994). A slide that *states* a fact satiates before it primes; a cold open that *poses* ("…and that's the number that made us kill the old pipeline") opens a gap the viewer must watch to close. Order clips to pose, not answer. Never lead with a definitional title card.
+- **Curiosity is an information gap** (Loewenstein, 1994). A slide that *states* a fact satiates before it primes; a cold open that *poses* ("…and that's the number that made us kill the old pipeline") opens a gap the viewer must watch to close. Order clips to pose, not answer. A definitional title card is appropriate when requested or useful for this format.
 - **Emotion outweighs everything** (Murch's Rule of Six: emotion ~51%, then story, rhythm, eye-trace, planarity, spatial continuity). The slop instinct optimizes the bottom of the list — aligned text, smooth easing — while ignoring the top. When choosing where to cut, ask "does this land the emotion / advance the point?" first, "is it geometrically neat?" last.
-- **Attention habituates; pattern interrupts reset it** (orienting response). Constant motion is itself a flat pattern the brain adapts to. Plan a *motivated* change of state every few seconds; vary shot scale between clips.
+- **Attention and rhythm.** Consider motivated changes of state or shot scale when attention is the goal. Deliberate repetition, continuous motion and long holds can serve other requested formats.
 - **Sound is half the picture** (Chion, *Audio-Vision*; synchresis). Cut on stressed words / beats via transcript word-timing; hold a silence beat before the peak line. On-beat reads as craft, off-beat as accident.
-- **Story is a value-shift** (McKee). Even a 30s piece must move from pain (real) → product (real) → win. A launch with no reversal is a list, not a story. (Ira Glass's storytelling model says it well another way: build a *sequence of raised-and-answered questions* — which is exactly "pose, don't answer.")
-- **Premium = legible intent, not polish.** Audiences forgive imperfect video with a point of view; they don't forgive adequate video with no soul. Restraint, typographic discipline, and one consistent color/type/motion system across the whole piece are the premium signal. If you can't say *why* something moves, it shouldn't.
+- **Story can use a value-shift** (McKee). Pain → product → win is one launch structure; a sequence of raised-and-answered questions is another. Neither is required for a brand study, observation or a different requested arc.
+- **Premium = legible intent, not polish.** Audiences forgive imperfect video with a point of view; they don't forgive adequate video with no soul. Restraint, typographic discipline, and one consistent color/type/motion system across the whole piece are the premium signal. Consider why motion serves the requested visual experience.
 
 ### Deconstructed grammars (steal the structure, map to the tools)
 These are *archetypes*, not documented cuts of specific films — reason from the grammar, don't cargo-cult a company.
 
-- **The hardware-reveal grammar → "the product is the opening shot."** Open on black; the product materializes — no logo splash, no title card. One capability per shot. Numbers rationed, each on its own held frame. Negative space around one object = confidence. *CueFrame:* `import_media` real product footage → `preview_frame` the opening frame and ask "would this survive with zero text?" · `cinematic-title` for the *closing* wordmark only · `color-grade` for the hero look.
-- **The founder-to-camera grammar → CueFrame's home field (the shape that agent walked past).** Founder, medium shot, direct address: "Hey, I want to show you something." No sting, just a face and eye contact. Screen-share woven in as real capture under the continuing VO. Captions burned in, plated. Lower-third names the founder once. Imperfect on purpose — that's the credibility. *CueFrame:* `get_media_context` → `active-speaker`/`all-faces` reframe → transcript-timed captions with an `emphasisPlate` → a `zPlane:"behind-subject"` title → `lower-third` → `color-grade`. Zero generation.
-- **The dark-kinetic-product grammar → "a gradient is a stage, not a subject."** Hard cut in on the UI in motion. Feature montage ~2–4s each, every beat a *real* UI interaction, cut on the music. The UI floats on a near-black stage with a subtle gradient — but the gradient is the *stage*; the real UI is always on top. One hero feature gets 8–10s to breathe. *CueFrame:* `import_media` UI captures → tight per-clip `trim`, cut on beat via clip durations → a dark `color-grade` + a `backgrounds` primitive as the *stage*, real footage on top. `preview_frame` a mid-montage frame: if there's no product on it, it's slop.
-
-*The compressed lessons:* the product/human is the opening shot, not a title card · a real screen recording beats a beautiful fake · a gradient is a stage, not a subject · open on your single most satisfying real moment in the first 5s · founder-to-camera + real footage is home field · a purposeful diagram of the real mechanism is grounded too · show one task completed end-to-end, not a feature grid.
-
----
-
-## The rubric template (write your video-specific version BEFORE rendering)
-
-```
-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. 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."
-
-MUST-HAVES (each scoreable YES/NO on a NAMED frame, or 0–10):
-  H1. [t=…] …
-  ... (5–8 lines; anchor every one to a timestamp a PNG can answer)
-
-KILL CRITERIA (any TRUE on any sampled frame = FAIL, regardless of score):
-  K1. [MANDATORY — preserve the meaning] Any sampled frame is a gradient/solid background with only
-      text and NO grounded subject — no real footage, no real UI/data, no purposeful
-      content-specific graphic, just decorative filler.
-  K2. [MANDATORY — preserve the meaning] Any on-screen number you cannot trace to a written
-      source, or any faked/mocked UI standing in for a real capture.
-  K3. [MANDATORY — preserve the meaning] Generic/decorative filler dominates the runtime — grounded,
-      specific content (real footage, real UI/data, or purposeful content-specific
-      graphics) does not.
-  K4+. … (add your own; encode this video's specific slop modes as disqualifiers)
-
-PROVENANCE: for every on-screen number, write the source next to it here
-  (e.g. "8.5% — benchmark table, <link to the writeup>"). No written source → it does not go on screen.
-
-PER-BEAT CHECKS: B1 (0:00–0:0X) … B2 … (each beat exists and lands, with a duration)
-
-MEASURABLE THRESHOLDS:
-  T1. First grounded frame (real footage / real UI/data / purposeful graphic) at t ≤ __s.
-  T2. Grounded, content-specific visuals (real footage, real UI/data, or a visual of the
-      real mechanism/data) ≥ 60% of runtime; a beat whose only visual is animated text
-      over a background counts as filler, not grounded. (Footage-based formats: real
-      footage ≥ 60%.)
-  T3. ≤ __ on-screen stats, each held ≥ __s, each source-traceable.
-  T4. No single frame > __% empty decorative background.
-  T5. Caption legible (contrast/size, plate) on named frames.
-  T6. Cut/beat count in range __–__ (not a static hold, not a strobe).
-
-SCORING: (a) your own frame-by-frame descriptions pass every MUST-HAVE with ZERO kill
-  criteria; AND (b) score_composition (editorialIntent = the VISION line;
-  brandContext = brand facts) composite ≥ 7.5/10 on its OWN sampled frames
-  (never set your bar below 7.5). Sample frames at [list incl t=0]. Budget 3–5 passes.
-```
+- **Hardware reveal example:** a product materializing against negative space can carry a reveal, with one capability per shot and sourced numbers held long enough to read. This is one option; a requested logo or title opening is equally valid. Use actual product footage when claiming to show the real hardware.
 
-### Filled example — product launch (the anti-slop rubric)
-```
-VISION: "Two founders who clearly believe in the product tell you, to your face, why it's
-  faster — and you watch it BE faster."
-FORMAT: talking-head + real demo (NOT slides).
-SOURCE REALITY CHECK: HUNT (3a) → the team's real launch footage = people to camera → import
-  it. If no footage: a real capture of the product running, or a first-class authored diagram of
-  its actual pipeline (grounded, not a consolation) — NOT a gradient deck. Generic
-  filler = fail.
-
-MUST-HAVES:
-  H1. [t=0–3s] A human FACE on screen within 3s (subject present, headroom).
-  H2. [t=0–3s] NO title card / logo splash before the face.
-  H3. [any speaking frame] The person framed is the person talking (reframe to
-      get_media_context faces; all-faces on the two-shot, active-speaker on singles).
-  H4. [speaking frames] Legible transcript captions, plated, never over the face.
-  H5. [one frame] Speaker name in a lower-third, shown once, spelled correctly.
-  H6. [demo beat] The real product running (captured pixels), not a re-created UI card.
-  H7. [stat beat] Any number matches the source exactly (source says 8.5% → the frame
-      says 8.5%, not 10x).
-  H8. [final] Wordmark + one line lands LAST, held ≥1.5s.
-
-KILL CRITERIA:
-  K1. [mandatory] Gradient/solid + only text, no grounded subject (no real footage,
-      real UI/data, or purposeful content-specific graphic).
-  K2. [mandatory] Untraceable number (e.g. "10x") or a fake/static terminal.
-  K3. [mandatory] Generic/decorative filler dominates; grounded content does not.
-  K4. On >2 consecutive sampled beats, the frame's largest element is text on a
-      flat/gradient field with no grounded subject behind or beside it.
-
-PROVENANCE: "8.5%" — the benchmark table in the sourced writeup. (No other on-screen numbers.)
-
-PER-BEAT: B1(0:00–0:05) cold open on a speaker, direct address, caption running ·
-  B2(0:05–0:20) the "why," problem in one sentence, on the face · B3(0:20–0:35) real
-  product demo, the one satisfying moment, captioned · B4(0:35–0:45) the honest 8.5% on a
-  clean held frame · B5(0:45–0:50) face again + CTA + wordmark.
-
-THRESHOLDS: T1 first grounded frame ≤ 3s · T2 real footage ≥ 60% of runtime · T3 ≤ 2
-  stats, each held ≥ 1.5s, source-traceable · T4 no frame > 30% empty background ·
-  T5 caption plate legible on B1,B3 · T6 ≥ 1 active-speaker/all-faces reframe.
-
-SCORING: own descriptions pass H1–H8, zero kills; score_composition (editorialIntent
-  = VISION) composite ≥ 7.5/10 on its sampled frames. Sample at 0,3,10,20,35,45s.
-  Budget 3–5 passes.
-```
+- **Human testimony example:** founder-to-camera footage can give a launch specificity. Reframe from actual speaker facts and use transcript timing for requested captions. Do not add a person or voice to a piece that calls for another medium.
 
-### Filled example (compact) — social clip (9:16 from long-form)
-```
-VISION: "In 20s, one surprising claim from the talk makes you stop scrolling."
-FORMAT: social-clip (9:16, sound-off).
-SOURCE: a real talking-head/podcast clip (the whole point of the clipping path).
-MUST-HAVES: H1[0–1.5s] the single most surprising sentence is the FIRST thing said
-  (align to transcript) · H2[every frame] face in the vertical safe area, top of head
-  in-frame · H3[speaking] word-level animated captions, high-contrast, plated · H4
-  captions never cover mouth/eyes · H5[last 2s] soft loop or one-line handle.
-KILL: K1[mandatory] gradient+text, no grounded subject · K2[mandatory] untraceable
-  number/fake UI · K3[mandatory] generic filler dominates, grounded content doesn't ·
-  K4 face cropped at forehead/chin OR vertical frame mostly empty · K5 opens on filler
-  ("um, so…") not the hook.
-THRESHOLDS: 15–30s · hook ≤ 1.5s · caption height ≥ ~6% of frame · face box ≥ 25% of
-  frame area · real footage ≥ 60% · nothing critical in bottom ~12% or top ~10%.
-SCORING: own descriptions pass, zero kills; score_composition (editorialIntent =
-  VISION) composite ≥ 7.5/10 on its sampled frames. Sample 0,1.5,5,10,18s. Budget 3–5 passes.
-```
+- **Product-action example:** real UI interactions on a restrained stage can make a software demo readable. Choose holds, cuts, music and graphic-only intervals from the brief; a frame without the product is not an automatic failure. A typography or gradient study can use those elements as its subject.
 
-Every line names a frame and asks a question a PNG can answer — is a grounded subject present, is text legible, is the background mostly empty decoration, does the number match its written source, is the hook first. None require reading the composition JSON. The kill criteria *are* the enforcement: K1–K3 encode that trial's failure modes as automatic disqualifiers a render can't be rationalized past.
+These examples suggest choices, not a required opening shot, visual medium or film structure. Real captures matter when presented as product evidence; authored diagrams and typography are valid requested media.
 
 ---
 
-## Red flags — stop and fix if any is true
+## Acceptance template
 
-- **You concluded "no footage" without hunting** → run step 3a (user-attached? subject's existing footage? ask). That agent's whole failure was skipping this — footage is the strongest grounding.
-- **Generic/decorative filler dominates the runtime** → grounded, specific content (real footage, real UI/data, or a purposeful content-specific graphic) doesn't. K3 trips. (For footage-based formats, real footage under ~60% is the usual symptom.)
-- **An on-screen number the user didn't give you** → you fabricated it. CueFrame renders your number faithfully, so a wrong one is on you — write every stat's source in the rubric; no written source → it doesn't go on screen.
-- **A terminal/UI that's a styled component, not a real capture** → it's a mock. Import the real capture or drop it.
-- **A gradient/aurora you're calling "purposeful"** → it isn't. Purposeful means specific to THIS content (the real mechanism, the real data). A decorative gradient is always the slop default, never grounding.
-- **You rendered before writing the rubric** → stop, write the rubric (step 2), then look at pixels.
-- **You scored without describing the pixels** → you didn't look. Write one line of what's visible per still, then score.
-- **You're the sole judge** → run `score_composition` (editorialIntent = vision); it samples its own frames — treat a low score on a frame you didn't pick as ground truth.
+Use only what the request needs:
 
----
+```
+INTENT: the requested outcome or visual experience.
+SCOPE: new work | affected revision | broader review | final delivery.
+PROJECT/LANE: current project and capabilities actually exposed.
+ACCEPTANCE: observable requirements at relevant timestamps/windows.
+PRESERVE: unrelated timing, media, audio, source identity and shared kit state.
+FACTS: sources for factual claims; identify simulated UI honestly.
+EVIDENCE: matching frames plus motion/audio checks where relevant; source revision and job identity.
+REVIEW: optional judge critique within budget; acceptance failures take precedence over scores.
+DELIVERY: preview evidence or verified final export as requested; report remaining gaps.
+```
 
-## Pre-render checklist (before `create_render`)
-
-0. `create_project` done; `get_account` shows enough `balance` on the wallet funding render/compose/generate (and the generate cost ceiling clears). Judge inclusion by balance, not by `included`.
-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. 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.
-6. `validate_composition` is `{ valid: [] }` — shape sound, no `reframe_coverage_gap` (shape ≠ quality).
-7. `preview_frame` stills taken at every rubric timestamp incl t=0, each **described in words** then scored against the rubric.
-8. `score_composition` run with `editorialIntent`=vision, `brandContext`=brand; worst-first critique addressed; composite ≥ 7.5 on its own sampled frames.
-9. Every kill criterion false on every sampled frame; every on-screen number traces to its written source and matches it.
-10. Verify passes budgeted (3–5) and the rubric genuinely passes — then `create_render` → `wait_job(kind:"render")`.
+Before final export, verify the requested acceptance criteria, current source revision and media bindings, valid composition shape, relevant motion/audio, and applicable hosted account/quote safeguards. Return the artifact location and distinguish preview proof from final-export proof.

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

@@ -5,8 +5,15 @@ 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`.
+## Scope and capability policy
+
+User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
+
+Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
 
+For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+
+> **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
@@ -254,4 +261,4 @@ frames) before declaring done.
   which is the engine's job now.
 - This recipe lives in a skill on purpose: the engine stays use-case-free; the
   product opinions (what to extract, which overlays, how to brand) live here and
-  ship via `npx -y cueframe install`.
+  ship via `npx -y cueframe@0.7 install`.