cueframe 0.1.2 → 0.3.0

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
@@ -35,7 +38,7 @@ extract brand (repo + live UI)  →  create_brand_kit
    →  capture (Kishu: Playwright walkthrough of localhost → MP4)  →  import_media
    →  get_media_context (faces + transcript)
    →  apply_composition (edit plan + brand template, refs brandKitId + $brand:)
-   →  create_composition { fromComposition:true }  →  wait_job kind:compose
+   →  compose { fromComposition:true }  →  wait_job kind:compose
    →  create_render  →  wait_job kind:render  →  branded MP4
 ```
 
@@ -95,7 +98,7 @@ matter, click the features worth showing, pause on results.
 
 Get the recording into CueFrame with `import_media` (public https URL) — it's
 async; poll `list_media` for `processingStatus:"ready"` (or register
-`create_webhook` on `media.ready`). Keep the click points; you'll map them onto
+`create_webhook` on `media.completed`). Keep the click points; you'll map them onto
 the rendered duration for the zoom.
 
 ## 3. Context → `get_media_context`
@@ -207,19 +210,19 @@ durations are illustrative — match your source.
 }
 ```
 
-## 5. Refine + judge → `create_composition { fromComposition: true }`
+## 5. Refine + judge → `compose { fromComposition: true }`
 
-Hand the seed to the Director: `create_composition` with `{ fromComposition: true }`
+Hand the seed to the Director: `compose` with `{ fromComposition: true }`
 authors an ensemble of candidates from your seed, runs the **server-side judge —
 including the brand axis** (on-brand color/type/voice cohesion), and saves the
 winner. Returns a `composeJobId`; `wait_job` `kind:"compose"` (or a webhook on
-`compose.complete`). The result carries the winner's composite score — verification
+`compose.completed`). The result carries the winner's composite score — verification
 is built in. Pass your brief as `editorialIntent` so editorial is graded against
 what you meant. (To self-drive the loop instead, see `cueframe-compose-loop`.)
 
 ## 6. Render → branded MP4
 
-`create_render` → `wait_job` `kind:"render"` (or a webhook on `render.complete`)
+`create_render` → `wait_job` `kind:"render"` (or a webhook on `render.completed`)
 for the download URL. The output is brand-frozen: the kit's **intro/outro** bumper
 the video, the **logo** bug sits in its corner, **motion** drives the overlay
 entrances, and every `$brand:` color/font is resolved. Verify the output (sample

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,9 +27,9 @@ 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):** `open_session` → `preview_component({ componentId, params })`
+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. `close_session` when done.
+   via `update_component` (same id, in place), preview again.
 4. **Render:** add it to a composition as an `alpha-layer` clip (`apply_composition`), then
    `create_render` → `wait_job kind:"render"` for the MP4.
 
@@ -57,7 +57,7 @@ MCP path stores. To preview before a full render, push it and use the MCP `previ
 The catalog (`/v1/components`) gives each primitive's `description` / `useWhen` / `tags` / `mood` /
 `tier` / `useCase` / `examples` (example params) + `propSchema` + its source via `get_component_source`.
 Read the spec + the code to pick a starting point. (Rendered preview thumbnails are a separate
-follow-up — today you choose from prose + params + source, or compose+`render_frame` to see it.)
+follow-up — today you choose from prose + params + source, or compose+`preview_frame` to see it.)
 
 ## Don't
 - Don't expect a forked primitive to use rich named props — it's adapted to `({durationInFrames,

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

@@ -0,0 +1,99 @@
+---
+name: cueframe-storyboard
+description: Use BEFORE composing when starting a NEW video from scratch and you need to plan its structure — turning a rough ask ("make a launch video", "30s promo", "an explainer for our API") into a concrete beat flow. Owns the intake + storyboard step: interview the user for the brief, resolve the format from the platform, and lay out the hook→body→cta beats that drive the compose workflow. Triggers on "plan a video", "storyboard", "structure this video", "outline the video", "where do I start", or any new-video ask that has no structure yet. Hand off to composing-video for per-beat craft.
+---
+
+# 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
+the smartest thing in this loop. CueFrame is the hands. This skill is the **intake + structure** step:
+turn intent into a concrete **beat flow** *before* you seed a composition, so the curated workflow (media →
+components → seed) executes a plan instead of a guess. Craft — grounded-vs-slop, the verify loop — belongs
+to the sibling **composing-video** skill; this skill gets you a flow, then hands off to it.
+
+Do not offload the *thinking* to CueFrame. There is no server that plans the video for you, and you would
+not want one — it would be a blind model with none of your context. Plan here, in the open, with the user.
+
+## 1. Interview for the brief — ask only what you can't infer
+
+Fill the brief from the conversation first; ask the user **only for the 1–2 things you genuinely cannot
+infer**, and STATE what you assume for the rest. Never wall them with a form.
+
+- **Goal / intent** *(required)* — what is this video FOR? launch, promo, explainer, demo, teaser, recap.
+- **Platform** *(sets the format)* — reels / tiktok / shorts → **9:16, ~20s** · youtube → **16:9, ~45s** ·
+  linkedin / x → **1:1, ~20s** · web → **16:9, ~30s**. (Or an explicit aspect ratio + duration.)
+- **Audience**, **tone** (punchy / premium-calm / playful / authoritative), **CTA**, **must-includes**
+  (a number, a name, a screen), **references** (a style to echo), **brand kit**.
+
+If the ask is "make a launch video for our API," you already have goal + a hint of audience — ask "Reels,
+YouTube, or your site?" and infer the rest: *"I'll assume a developer audience and a punchy tone — say if
+you'd rather it feel calm/premium."* One or two questions, not seven.
+
+## 2. Structure the flow — the storyboard
+
+Lay the duration into **beats** using the fixed editorial vocabulary
+**hook → context → body → proof → cta → outro** (use what the piece needs — most short-form is
+hook → body → cta). For each beat decide:
+
+- a one-line **intent** (what this beat does for the viewer),
+- a **duration** (they sum to the target; the hook earns attention in ~3s),
+- a **media need** — real footage is the strongest grounding and CueFrame's home turf, so reach for it
+  first; otherwise `generate` a *purposeful* clip (a diagram of the real mechanism, the real UI) or `find`
+  stock. Animated text over a gradient is not grounding — it's the slop default,
+- an optional **graphic** (a lower-third, title, CTA card),
+- a **caption** and/or a **VO/script** line.
+
+**Ground it, don't invent it.** Pick every graphic/scene from `list_catalog` (filter by `useCase`/`tier`)
+— never hardcode hex or positions or name a component that doesn't exist. Theme from the brand kit. If
+you're planning over real footage, read `get_media_context` (detected faces + transcript) so beat timing,
+crops, and captions land on what's actually there.
+
+## 3. Show the flow, then persist it as a Brief
+
+Show the user the beat list **first** — a five-line outline. It is cheap to change here and expensive to
+change after a render, so this is where you converge on structure. On their go, **persist the plan with
+`create_brief`** — the beats/goal/format/gates you just elicited map 1:1 onto its fields, and the plan stops
+being chat-ephemeral (it survives the session, carries a cost quote, and is honored field-by-field):
+
+1. `import_media` / `generate_media` for each beat's media need,
+2. `create_brief` — goal, audience, platform/format, durationSec, tone, cta, locale, and the beats
+   (each with its editorial intent and, when you're cutting real footage, MOMENT PINNING
+   `source: {mediaId, startSec, endSec}` from the transcript — honored to-the-frame or refused).
+   Relay the response's **quote** (compose + estimated render) BEFORE composing.
+3. `compose { briefId }` — the Director authors FROM your brief; every field is honored or the
+   compose is refused loudly naming the field. Gates: put `holdAt: ["layout"]` in the brief's `gates` when
+   the user wants to approve the storyboard mid-flight; `autoApprove: true` for hands-off.
+4. `score_composition` / `consult` to fix the weakest beat,
+5. `create_render` for the MP4.
+
+**Two graphic media — pick per beat, and review accordingly:** a `card` (verbatim HTML in
+`seededGraphics`) is a STATIC graphic — cheap, approve it from a still; a **component**
+(`create_component`, `useCurrentFrame`) is MOTION — a still is one frame, so preview it before trusting it.
+Seeded graphics you author into the brief are carried VERBATIM as locked clips — the Director never
+re-authors them; `exclusions` bans graphic kinds you never want it to author.
+
+Then load **composing-video** and apply its craft to make each beat good.
+
+## Related skills & positioning
+
+This skill owns **structure/intake**; its siblings own execution and craft — defer to them:
+
+- **composing-video** — the craft/quality layer (grounded specificity vs. slop, the vision → rubric →
+  verify loop). Load it *after* you have a flow; it makes each beat good.
+- **cueframe-compose-loop** — the author → render → verify → fix convergence loop + the ship bar.
+- **cueframe-product-video** — click-points → auto-zoom tiling + PiP for screen demos.
+- **cueframe-brand-demo** — brand-token vocabulary + auto intro/outro/logo for branded launches.
+- **cueframe-component-authoring** — fork → preview → push for a custom graphic a beat needs.
+- **cueframe-cli** — the `cueframe` binary + wire mechanics.
+
+## The boundary
+
+You own the **vision** (the one idea and the flow for *this* video) and **data correctness** (a wrong
+number you supply is rendered faithfully — the mistake is yours). CueFrame owns being faithful, legible,
+and giving you real footage + real components to plan against. Reason from this; skip the whole flow only
+for a re-render of an approved composition or a single trivial one-off.

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.

package/skills/extracting-brand-kits/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: extracting-brand-kits
+description: Use when the user says "make my video look like THIS" with a reference video, screenshots, or a moodboard — build a CueFrame brand kit FROM that inspiration so every subsequent compose speaks its visual language. Owns the extraction step: sample the reference's graphics-bearing frames, upload them as exemplars, reproduce each recurring motif as an authored graphic verified against the reference, and upsert the kit with the full language payload. Triggers on "match this style", "like this reference", "use this video as inspiration", "extract a brand kit", "moodboard". Hand off to cueframe-storyboard/composing-video once the kit is bound.
+---
+
+# Extracting brand kits: reference pixels → a kit the engine honors
+
+## The one idea
+
+**No summarization anywhere in the path.** A reference described in prose converges on house style
+with the reference's palette — the pixels are the ground truth. You (the agent) are the extractor:
+you SEE the reference, curate its frames, and reproduce its motifs as ordinary authored graphics,
+verified against the reference by looking. The kit you produce carries (a) **exemplar frames** the
+compose maker and judge both see, and (b) **motif skins** — card HTML the designer reproduces —
+plus code-checked facts (caption profile, density, palette). Once bound to a project, the engine
+takes over: the planner plans to your density, the designer sees your exemplars
+(`view_style_reference`), the judge grades every candidate against them, and a half-applied kit
+fails the compose loudly instead of shipping house style.
+
+Everything below drives the public `/v1` API with your API key. Frames never pass through chat —
+they go straight to storage via presigned PUTs.
+
+## 0. Prereqs
+
+- An API key with `projects:write` (create_brand_kit gates on the `brand_kits` plan feature — check `get_account` first; 402 names the feature).
+- `ffmpeg` locally, and the reference video file (download it first if it's a URL).
+- Know the org's IDENTITY kit if one exists (`get_profile` → brandKits). Inspiration NEVER overwrites identity: logo, brand fonts, and identity color slots come from the existing kit (or stay for the user to fill) — extraction contributes the LANGUAGE only.
+
+## 1. Sample the reference (local, ffmpeg)
+
+Uniform sampling misses short-lived graphics (1–3s overlays). Sample two ways and union:
+
+```bash
+# scene cuts
+ffmpeg -i ref.mp4 -vf "select='gt(scene,0.22)',showinfo" -vsync vfr scenes/%03d.jpg
+# 2fps sweep (catches overlays that appear without a cut)
+ffmpeg -i ref.mp4 -vf fps=2,scale=720:-1 -q:v 4 sweep/%04d.jpg
+```
+
+Then LOOK at the frames and curate: keep the **graphics-bearing** ones — frames where a card,
+pill, stat, lower-third, caption treatment, or end-card is visible and sharp. Drop near-duplicates.
+**≤24 frames**, each downscaled to ≤720px width, jpeg. For each animated graphic, also note the
+timestamp where it ENTERS (you'll classify its motion in step 5; re-watch that 1s window at
+`ffmpeg -ss <t> -t 1 -i ref.mp4 -vf fps=12 burst/%02d.jpg` if you need to see the entrance).
+
+Optional but recommended: build a contact sheet for the human's "right vibe?" check:
+`ffmpeg -i frames/frame-%02d.jpg -filter_complex tile=6x4 sheet.jpg`.
+
+## 2. Upload the exemplars (the ingest door)
+
+```
+POST /v1/brand-kits/exemplar-uploads  { "count": <n>, "includeContactSheet": true }
+```
+
+Returns presigned PUT slots under the org's `brand-inspiration/…` prefix — the ONLY namespace the
+kit door accepts exemplar keys from. PUT each curated frame (order matters: frame-01 ↔ index 0 —
+motif `evidence` arrays reference these indexes), PUT the sheet, keep the returned `key` list.
+URLs expire in 15 minutes; re-POST for a fresh batch if you run over.
+
+## 3. Inventory the motifs
+
+Look across the exemplars and list every RECURRING graphic treatment (expect ~5–12 for a designed
+reference). For each, write:
+
+- `id` — `m1`, `m2`, …
+- `observed` — one precise sentence ("thin-outline rounded keyword pill, single word, beside subject").
+- `role` — the closed vocabulary the planner/designer speak (exact values):
+  `title-card | stat | lower-third | pull-quote | hero | logo-tag | enumeration | sequence | comparison`.
+  Pick the role each motif best SERVES — the designer's steering matches on it exactly.
+- `evidence` — the exemplar indexes (0-based) it appears in.
+- `zone` — normalized `{x, y, w, h}` where it lives.
+- Behind-the-subject motifs (text the speaker occludes): record them with `coverage: "skipped"` and
+  `skipReason: "behind-subject — card graphics render front-only"`. Do NOT attempt them.
+
+Also read the CAPTION treatment off the frames (step 6 consumes it): plate or plateless? base/
+highlight colors? case? emphasis styling? entrance feel (~ms)?
+
+## 4. Reproduce each motif as a card (author → look → refine, ≤3 iterations)
+
+For each non-skipped motif, author it as a **card** (freeform HTML/CSS — rendered verbatim) and
+verify it against the exemplar BY LOOKING:
+
+1. **Measure first**: read the exemplar — border weight, radius, padding, font size relative to
+   frame, colors. Measurement-seeded CSS gets you ~90% in one shot.
+2. Author `{ "kind": "card", "html": "…", "tokens": { … } }`. Bind every brand-swappable color
+   through `tokens` with `$brand:` refs (e.g. `"line": "$brand:colors.accent"`, referenced in CSS
+   as `var(--cf-line)`) so the kit's identity re-themes it. No `<script>`, no `@keyframes` (inert —
+   motion is step 5).
+3. Render it (`preview_frame` on a scratch session, or `preview_component` if you forked a
+   component) and compare the still against the exemplar side by side. Fix the largest visible
+   difference. Repeat — **cap 3 iterations**, keep the best.
+4. Record `diffScore` (your honest 0–1 same-language judgment) and `coverage`:
+   `"reproduced"` (≥0.8) or `"approximated"`.
+
+Prefer a catalog primitive (`list_catalog`) over a card ONLY if it genuinely matches closer —
+record it as `{ "kind": "overlay", "primitiveId": "…", "params": { … } }`. A custom component
+(`{ "kind": "component", "componentId": "…" }`) only for motifs with internal motion (counters).
+
+## 5. Classify motion (closed vocabulary — never invent animation)
+
+Watch each motif's entrance burst and map it:
+
+- Graphic motion presets (exact values): `fade-up | slide-in-left | slide-in-right | scale-pop | stagger-reveal`,
+  with `enterMs` / `exitMs` / `staggerMs` timings you observed.
+- Caption per-word entrances: `none | fade | word-pop | stagger-up`.
+- Unsure or the reference does something the vocabulary can't say? Pick the NEAREST preset and set
+  `"confidence": "low"` — honesty beats fabrication; the vocabulary grows engine-side, not here.
+
+## 6. Compute the facts
+
+- `captionProfile` — from step 3's caption read. The kit door speaks the full look: `color`,
+  `highlightColor`, `plate` (`"none"` for the clean plateless look), `entrance`, `entranceMs`,
+  `exitMs`, `emphasisColor/Scale/FontWeight/FontStyle`, `emphasisPlate` knobs, `textTransform`.
+- `density` — `{ "graphicsPerMin": <count/duration*60>, "maxSimultaneous": <max overlapping> }`.
+- Palette → `extraColors` entries `{ "hex", "label": "inspiration accent N", "usage": "swappable" }`.
+  NEVER write the identity `colors.*` slots, `headingFont`/`bodyFont`, or `logo` from the
+  reference — copy those from the base identity kit, or leave them for the user.
+- `styleRubric` — 2–4 sentences the JUDGE will grade with: name the motif language, the caption
+  treatment, and what disqualifies a frame ("filled chips or plated captions are off-language").
+
+## 7. Upsert the kit + bind it
+
+One `create_brand_kit` call (it's an upsert — re-POST the same `kitId` to curate):
+
+```jsonc
+{
+  "kitId": "acme-launchfilm",
+  "name": "Acme × Launch Film",
+  // identity: copied from the base kit or neutral — never from the reference
+  "colors": { … }, "headingFont": { … }, "bodyFont": { … },
+  "extraColors": [ { "hex": "#F5B942", "label": "inspiration accent 1", "usage": "swappable" } ],
+  "captionProfile": { "plate": "none", "entrance": "fade", "entranceMs": 220, … },
+  "exemplarKeys": [ "<keys from step 2, in frame order>" ],
+  "contactSheetKey": "<sheet key>",
+  "motifs": [ { "id": "m1", "observed": "…", "body": { "kind": "card", … }, "motion": { "preset": "fade-up", "enterMs": 320 }, "role": "pull-quote", "zone": { … }, "evidence": [0, 2], "diffScore": 0.93, "coverage": "reproduced" } ],
+  "styleRubric": "…",
+  "density": { "graphicsPerMin": 4, "maxSimultaneous": 2 },
+  "inspiration": { "sources": ["<reference URL>"], "extractedAt": <now ms>, "extractionVersion": "skill-1" }
+}
+```
+
+The door validates loudly: exemplar keys must come from step 2's batch, motif roles/presets must be
+in-vocabulary, evidence indexes must be in range. A 422 names exactly what to fix.
+
+Then bind: `update_project { "brandKitId": "acme-launchfilm" }`. Show the human the contact sheet
+("right vibe?") before composing. From here, hand off to **cueframe-storyboard** — every compose
+against the project now plans, designs, and JUDGES in the reference's language, and refuses to
+ship house style if any part of the kit fails to resolve.
+
+## Failure honesty
+
+- Reference has no graphics language (talking head, zero overlays)? Say so — upsert nothing, or a
+  captions-only kit. Don't invent motifs.
+- A motif you can't match in 3 iterations ships as `"approximated"` with its real diffScore — the
+  judge's floor will surface it; don't inflate.
+- Behind-subject motifs stay `"skipped"` with the reason. The engine refuses them loudly anyway.

package/skills/launch-video/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: launch-video
+description: Turns screen recordings and product footage into a 30–90 second 16:9 launch film — payoff-first hook, real product surface punched in, a building bed or narration, one CTA end card. Triggers on "make a launch video", "announcement video for this feature", "turn this screen recording into a demo film", "product video from these captures", "we're shipping Friday and need a video", "feature announcement".
+---
+
+# Launch video
+
+You bring real screen recordings or product footage plus the one outcome the feature delivers;
+you get back a 30–90 second 16:9 announcement that opens on the payoff, shows the actual product
+doing the real thing, builds under a bed or narration, and lands on a single CTA.
+
+## Before you start
+
+Nail the payoff sentence and collect the captures before any 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**.
+- **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`.
+
+Keep the momentum — the video plan is the hard part, the connection is not.
+
+## Inputs
+
+- **Real captures** (required): screen recordings, product footage, real output. CueFrame does
+  not screen-record — the user records (or uses a capture client) and you `import_media` the
+  file. Never mock what's missing; ask for the real capture.
+- **The payoff**: the outcome in the user's words ("close the books two days faster"), plus the
+  CTA (one action) and launch date if any.
+- **Brand kit**: project kit if present; ask for wordmark + accent color otherwise.
+- **Voice**: default a building instrumental bed with captioned key lines; narrated VO if they
+  have a script or want one generated.
+
+## Workflow
+
+1. **Import the real surface.** `import_media` every capture; wait for ready;
+   `get_media_context` for what each recording actually shows (and the transcript, if narrated
+   footage exists). Inventory the strongest 3–5 real moments before writing a beat.
+2. **Open on the payoff, not the name.** The hook is the OUTCOME — the result on screen, the
+   pain disappearing — inside the first seconds. "Introducing X" is throat-clearing; the
+   outcome-first frame is the hook. No logo, no title card first.
+3. **Structure: hook → problem → reveal → proof → CTA.** `new_composition` at 16:9 →
+   `apply_composition` with the beats. Pacing tightens as the payoff approaches — clips get
+   shorter toward the reveal.
+4. **Punch in on the real pixels.** A click target is tiny in a full-frame capture;
+   `setCropIntents` with `point` focus segments zooming to the exact UI region per step,
+   `frame-center` in the gaps, tiling every clip. The single biggest amateur-to-pro delta in
+   product video.
+5. **Cards for the claims and the end card.** Key lines and the closing CTA are `kind:"card"`
+   HTML in the brand's type and palette — persisted first, then shelled with
+   `applyMotionPreset` in a FOLLOWING `apply_composition` call. One CTA on the end card, held
+   long enough to read, plus the date if there is one.
+6. **Audio that builds — required.** `search_resources` for a bed honoring the brand kit's
+   `musicMood`, energy arcing toward the reveal; place it `audioRole:"music"`,
+   `materializeGrid { grid:"beat" }`, and land beat boundaries and the reveal on the grid. If
+   narrated: the VO is the rhythm authority instead — cut to the voice and duck the bed under
+   it. Silence is almost never right for a launch; if chosen anyway, record the decision and
+   reason in the delivery note.
+7. **Caption narration.** If there is a voice, `captions.fromTranscript` (or authored word
+   timings for generated VO), styled legible via `setCaptionStyle`. Captions are mandatory when
+   narrated.
+8. **Preview, judge, one render.** `preview_frame` at t=0, hook-end, the reveal, and the end
+   card; describe each still — is that a REAL capture on screen? Then `score_composition` with
+   the payoff line as `editorialIntent`; fix worst-first to ≥ 7.5; `create_render` →
+   `wait_job (kind:"render")`.
+
+## What good looks like
+
+Quoted from `video-craft-standards` §2 (Launch film / feature announcement) — the full checklist
+wins:
+
+> **MUST (K)** Payoff-first hook: the OUTCOME, not the feature name ("Close the books two days
+> faster" beats "Introducing the reconciliation module"). No throat-clearing.
+
+> **MUST** Narration or a bed that builds toward the reveal; pacing tightens as the payoff
+> approaches. **MUST** Real product surface: actual UI/screens/output — never mocked.
+
+> **MUST** End card with a single CTA. **MUST** Captions present when narrated.
+
+And cross-cutting: *"Footage carries the video: real footage / real UI / real data ≥60% of
+runtime for footage-first classes."*
+
+## Delivering
+
+Close with the handoff, never "done":
+
+- The render link and where it lives (project + composition id).
+- Attribution for the bed and any licensed asset (provider, id, author).
+- The intentional-silence note with its reason, in the rare case silence was chosen.
+- A one-line cutdown offer: the 16:9 master can become 9:16 / 1:1 siblings for social (see
+  `every-format-from-one-edit`).

package/skills/make-a-social-reel/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: make-a-social-reel
+description: Turns footage into a finished 9:16 social reel — hook inside 2 seconds, poster-grade type, a decided music bed, one final render. Triggers on "make me a reel from this", "turn this into a short", "cut a clip for TikTok / Reels / Shorts", "make this vertical", "make a social clip from this video", "the opening is boring", "can you make this pop for Instagram".
+---
+
+# Make a social reel
+
+You hand over footage (a file URL, a talk, a product moment); you get back a 9:16 reel of 8–30
+seconds that opens on its strongest image, cuts on the music, carries brand-grade type, and ends
+on a deliberate beat — with a download link, not a "done".
+
+## Before you start
+
+Don't stall the conversation on setup — get the footage, the hook, and the tone agreed first.
+When the first real tool call is imminent and CueFrame isn't connected:
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — a browser tab
+  opens and the user clicks **Allow**.
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
+  `https://api.cueframe.ai/v1/mcp`.
+- **Any other agent:** paste `set up https://cueframe.ai/skill.md`, or run
+  `npx -y cueframe install`.
+
+Thirty seconds, then straight back to the reel — treat it as a detour, never a gate.
+
+## Inputs
+
+- **Footage** (required): a public https URL, or something already in `list_media`. If they have
+  nothing, ask for the real thing before reaching for stock — real footage is the whole edge.
+- **Brand kit**: use the project's kit if one exists; otherwise ask for a color + font or extract
+  one. Default: proceed with a neutral palette and say so.
+- **Tone / platform**: default punchy, 15–25s, sound-on-with-captions. Ask only if the answer
+  would change the cut.
+
+## Workflow
+
+
+0. **Find the claim (before anything else).** Interrogate the brand/material
+   for its tension — what it believes that its category doesn't — and write
+   the claim in one sentence. Derive the shot list, the bed's mood/tempo, the
+   pacing, and every card's copy FROM that sentence. If you cannot state the
+   claim, you are not ready to compose (video-craft-standards: the
+   controlling idea is kill-level).
+
+1. **Import and read the footage.** `import_media` (public https URL), poll `list_media` until
+   ready, then `get_media_context` — faces, transcript, word timings. The context tells you
+   where the hook lives; don't guess.
+2. **Pick the hook before you touch the timeline.** The strongest image, motion, or claim in the
+   footage — the outcome, not the feature name, is the hook. If the best moment is at 0:47, the
+   reel opens at 0:47. No logo-first cold opens, ever.
+3. **Seed the timeline.** `new_composition` at 9:16, then `apply_composition`: clips trimmed to
+   the beats you chose, a new visual beat at least every ~4 seconds. Cut TO moments; never let a
+   clip run out.
+4. **Reframe for vertical.** `setCropIntents` with segments that tile every clip —
+   `active-speaker` or `face` focus when a person carries it, `point` focus on the action
+   otherwise. A wide shot letterboxed into 9:16 is a fail, not a fallback.
+5. **Author the type as cards.** Brand text is `kind:"card"` HTML — your typography,
+   palette-as-fields, considered alignment — persisted first, then shelled with
+   `applyMotionPreset` in a FOLLOWING `apply_composition` call. Catalog text primitives are
+   utility only.
+6. **Decide the audio — required, never skipped.** Search a bed with `search_resources` honoring
+   the brand kit's `musicMood`, place it as an `audioRole:"music"` clip, then `materializeGrid`
+   `{ grid:"beat" }` and land your cut points and transition midpoints on the markers. If the
+   piece is genuinely better silent, that is a decision — record it and its reason in the
+   delivery note. A reel whose silence nobody chose is not done.
+7. **Caption any speech.** `captions.fromTranscript` with the mediaId, styled via
+   `setCaptionStyle` (plated, bottom, out of the mouth/eyes). Most social viewing is sound-off;
+   don't karaoke a beat with no speech.
+8. **Look, then get judged.** `preview_frame` at t=0, hook-end, and every beat boundary;
+   describe each still in words before scoring it. Then `score_composition` with your one-line
+   vision as `editorialIntent` — fix the worst criterion first. Ship at composite ≥ 7.5, budget
+   3–5 passes.
+9. **One final render.** `create_render` → `wait_job (kind:"render")`. Iterate with previews,
+   not renders.
+
+## What good looks like
+
+Quoted from `video-craft-standards` §1 (Social reel) — the full checklist wins over this skill
+wherever they disagree:
+
+> **MUST (K)** The hook lands inside 2 seconds: the strongest image, motion, or claim opens the
+> piece. No logo-first cold opens, no fade-in-from-black preambles.
+
+> **MUST** Typography is poster-grade: composed plates/fields in the brand palette, considered
+> alignment and scale. **K:** centered white text floating on footage.
+
+> **MUST** Pacing is cut-driven: a new visual beat at least every ~4s […] **MUST** Ends on a
+> deliberate beat: tagline, logo, or CTA lockup — not a clip running out.
+
+And the cross-cutting audio rule:
+
+> **MUST** Audio is decided, never defaulted […] **K:** a render whose silence nobody chose.
+
+## Delivering
+
+Never end with "done". The last message carries:
+
+- The render's download URL and where it lives (the project, by composition id).
+- Attribution for every stock asset used (provider, id, author) — the provenance you recorded at
+  import.
+- The intentional-silence note with its reason, if you chose silence over a bed.
+- One line on what you'd tighten next, so the follow-up edit has a starting point.