cueframe 0.4.3 → 0.4.5

package/{skills → dist/skills}/add-music-bed/SKILL.md

@@ -20,22 +20,8 @@ cuts moved onto its beat grid. Attribution included, levels disciplined, one re-
 ## Before you start
 
 Listen first — identify what audio the composition already has before proposing anything. When
-the first tool call approaches and CueFrame isn't connected:
-
-<!-- cueframe:connect -->
-- **Claude Code:** offer to run
-  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — a browser
-  opens and the user clicks **Allow**. No API key.
-- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
-  `https://api.cueframe.ai/v1/mcp`.
-- **Other agents (Cursor, Codex, VS Code, Windsurf, Zed, Gemini CLI, Copilot CLI, …):**
-  run `npx -y cueframe install` — it detects what is on the machine and wires each one.
-- **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
-  `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
-- **No account at all (pay-per-call):** connect
-  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
-  settle per-call in USDC over x402 from the agent's wallet.
-<!-- /cueframe:connect -->
+the first tool call approaches and CueFrame isn't connected, load **`cueframe-connect`** and
+follow it once.
 
 Then back to the soundtrack — this is usually a one-sitting job.
 
@@ -51,6 +37,10 @@ Then back to the soundtrack — this is usually a one-sitting job.
 
 ## Workflow
 
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Listen to a scoped `preview_clip` across speech, ducking, fades, and beat changes before final
+delivery; stills and a visual judge cannot establish the mix. Recheck visuals where cuts moved.
+
 1. **Read the composition and its speech.** `list_compositions` / the composition body for
    what's on the timeline; `get_media_context` for transcripts. Speech present → the voice is
    the rhythm authority and the bed serves it. No speech → the bed IS the rhythm authority and

package/{skills → dist/skills}/brand-reel/SKILL.md

@@ -12,22 +12,8 @@ beat, tagline lockup — where every graphic could belong to this brand and no o
 ## Before you start
 
 Talk brand first — palette, type, the one line they'd put on a poster — before any setup. When
-the first tool call approaches and CueFrame isn't connected:
-
-<!-- cueframe:connect -->
-- **Claude Code:** offer to run
-  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — a browser
-  opens and the user clicks **Allow**. No API key.
-- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
-  `https://api.cueframe.ai/v1/mcp`.
-- **Other agents (Cursor, Codex, VS Code, Windsurf, Zed, Gemini CLI, Copilot CLI, …):**
-  run `npx -y cueframe install` — it detects what is on the machine and wires each one.
-- **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
-  `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
-- **No account at all (pay-per-call):** connect
-  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
-  settle per-call in USDC over x402 from the agent's wallet.
-<!-- /cueframe:connect -->
+the first tool call approaches and CueFrame isn't connected, load **`cueframe-connect`** and
+follow it once.
 
 Then pick the brand conversation back up where it paused — connection is the smallest step in
 this job.
@@ -43,6 +29,10 @@ this job.
 
 ## Workflow
 
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+for stills and motion windows. For a small revision, preserve the approved arc and inspect the
+affected behavior and regressions; reserve full-film judging and export for the relevant review/delivery.
+
 
 0. **Find the claim (before anything else).** Interrogate the brand/material
    for its tension — what it believes that its category doesn't — and write

package/{skills → dist/skills}/clip-a-talking-head/SKILL.md

@@ -12,22 +12,8 @@ dead air, and caption every word from the real transcript.
 ## Before you start
 
 Get the source URL and what "best moment" means to the user before any setup ceremony. When the
-first tool call is close and CueFrame isn't connected:
-
-<!-- cueframe:connect -->
-- **Claude Code:** offer to run
-  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — a browser
-  opens and the user clicks **Allow**. No API key.
-- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
-  `https://api.cueframe.ai/v1/mcp`.
-- **Other agents (Cursor, Codex, VS Code, Windsurf, Zed, Gemini CLI, Copilot CLI, …):**
-  run `npx -y cueframe install` — it detects what is on the machine and wires each one.
-- **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
-  `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
-- **No account at all (pay-per-call):** connect
-  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
-  settle per-call in USDC over x402 from the agent's wallet.
-<!-- /cueframe:connect -->
+first tool call is close and CueFrame isn't connected, load **`cueframe-connect`** and follow it
+once.
 
 Then straight back to hunting the moment — setup is a footnote, not a phase.
 
@@ -43,6 +29,10 @@ Then straight back to hunting the moment — setup is a footnote, not a phase.
 
 ## Workflow
 
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Watch/listen across changed cuts and caption/subject motion with `preview_clip`. For a small
+correction, retain the approved edit and check relevant regressions without automatically exporting.
+
 1. **Import and read.** `import_media` the recording, wait for ready, then `get_media_context`
    — the transcript with word timings and the face roster (with `faceId`s and speaking share)
    are your whole map. For an assisted hunt, `suggest_briefs` proposes clip candidates from the
@@ -70,7 +60,12 @@ Then straight back to hunting the moment — setup is a footnote, not a phase.
    from `search_resources` honoring the brand kit's `musicMood`, ducked under the voice — or
    intentional speech-only, recorded with its reason in the delivery note. Either is fine;
    defaulted silence is not.
-8. **Preview, judge, render once per clip.** `preview_frame` at t=0 and each cut; describe each
+8. **Prepare the subject evidence.** If `get_media_context.faces.status` is `not_detected`, call
+   `prepare_media` with `kind:"subjectTrack"` and the clip's exact SOURCE trim window; if the
+   edit has `zPlane:"behind-subject"`, prepare `kind:"matte"` for that same window. Poll
+   `get_media_facts` with kind + startSec + endSec until `exact.state:"ready"`. A flattened
+   depth title or ignored speaker crop is not preview evidence.
+9. **Preview, judge, render once per clip.** `preview_frame` at t=0 and each cut; describe each
    still (is the framed person the one talking? is the top of the head in frame?).
    `score_composition` with the clip's claim as `editorialIntent`; fix worst-first to ≥ 7.5,
    then `create_render` → `wait_job (kind:"render")`.

package/{skills → dist/skills}/composing-video/SKILL.md

@@ -5,6 +5,12 @@ description: Use when an agent is asked to make ANY video with CueFrame — a pr
 
 # Composing Video: craft for CueFrame
 
+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
@@ -31,6 +37,7 @@ This skill is the **craft / quality layer** for an agent driving CueFrame over t
 - **`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*.
 
@@ -95,17 +102,19 @@ Do not fake the missing footage, and do not dress up generic filler as grounding
 ### 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.
 
+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.
+
 ### 5 — Iterate on REAL PIXELS (and prove you looked)
-`preview_frame` PNG stills at your rubric's named timestamps — **always including t=0 and hook-end** — and **look at them**. (Sessionless; if a cold first call returns 409 box_warming, retry in a few seconds.)
+`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.
 
 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` (sessionless — the warm box is a server detail) with your VISION line as `editorialIntent` and brand facts as `brandContext`. 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.
+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`, re-render the affected frames, re-score. **Budget 3–5 verify passes** (two no-improvement passes = diminishing returns — `cueframe-compose-loop` owns the full convergence loop). Ship only when your own rubric passes with zero kill criteria tripped AND the `score_composition` composite ≥ 7.5 — not when you get bored. (No session to close — the warm box is a server detail that reaps itself.)
+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.
 
 ---
 
@@ -159,10 +168,10 @@ Chromium captures; the clock never advances). Use these instead:
 2. **`transitionIn` on any overlay clip** — `{ transitionIn: { type: "fade", duration: 0.4 } }`
    now applies to overlay-family clips (cards, components, primitives), not just video.
    Use it for entrances; author exits in-card via `--cf-exit`.
-3. **`applyMotionPreset` op** — shell a static card into a live motion component in one op:
+3. **`applyMotionPreset` op** — shell a static card into a frame-driven component in one op:
    `{ type: "applyMotionPreset", clipId, preset }` (unknown presets are rejected with the
    full preset list). The layout stays verbatim; the preset adds entrance/idle/exit
-   choreography. The result is a live component you can `get_component_source` and refine.
+   choreography. The result is a component you can `get_component_source` and refine.
 
 ---
 
@@ -494,10 +503,10 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | Craft goal | Do this in CueFrame |
 |---|---|
 | Bring in the real thing | `import_media` — requires `url` (public https) + `filename` + `contentType` (from the fixed enum: `video/mp4`, `video/quicktime`, `image/png`, `audio/mpeg`, …). Poll `list_media` or `create_webhook` on `media.completed` (status inside: complete|failed). |
-| Know where subject + speech are | `get_media_context` → face boxes per frame (with `faceId`) + transcript |
+| Know where subject + speech are | `get_media_context` → face boxes per frame (with `faceId`) + transcript. If faces are not detected, `prepare_media(kind:"subjectTrack", intent:{startSec,endSec})` → poll `get_media_facts` for the same SOURCE window until ready. |
 | Keep the speaker framed / punch-in | `setCropIntents` op (the PREFERRED authoring path) or inline `reframe.segments` on a `clip.add` source. Each segment needs `startSec`/`endSec`/`focus`/`zoom`; **segments must TILE the clip** (an uncovered span → `reframe_coverage_gap` at validate). `focus.mode`: `frame-center` \| `point{x,y}` \| `face{faceId, shotScale?: close\|standard\|wide}` \| `all-faces` \| `active-speaker`. `zoom<1` punches in, `=1` full frame, `>1` rejected (min 0.1). Times in **seconds**. |
 | Captions that track real speech | `composition.captions.segments[].words[]` = `{text, startMs, endMs, emphasis?, annotate?: circle\|underline}` — word times in **milliseconds**. Author the words directly with the `setCaptions` op (segments wholesale — how a generated-VO film gets its word-synced spine without a source transcript); style via `setCaptionStyle`: `position` (top\|center\|bottom), `entrance` (fade\|word-pop\|stagger-up), `emphasisPlate` + plate colors for legibility. Captions default to front; set top-level `composition.captions.zPlane:"behind-subject"` only when the user wants the whole caption layer behind the speaker. It resolves person cutouts for every overlapping source window and degrades visibly to front where the legibility gate refuses the effect. |
-| Text behind the speaker's head | An `overlay` clip (a title/label primitive) with `zPlane:"behind-subject"`. This is the focused hero treatment; caption-layer depth is a separate whole-layer choice. Render resolves the person cutout + handles occlusion. |
+| Text behind the speaker's head | An `overlay` clip (a title/label primitive) with `zPlane:"behind-subject"`. This is the focused hero treatment; caption-layer depth is a separate whole-layer choice. Before preview/judgment, `prepare_media(kind:"matte", intent:{startSec,endSec})` for the overlapping clip's SOURCE trim and poll `get_media_facts` until ready. Render also resolves the person cutout on miss. |
 | Name someone / label a step | `lower-third` scene from `list_catalog` |
 | Title / closing wordmark | `cinematic-title` scene (closing, not opening) |
 | Grade the look | `color-grade` scene/effect |
@@ -506,11 +515,14 @@ Each playbook is a **floor**, not a template — reason above it. Every beat map
 | 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 |
+| 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. |
 | Shape-check (NOT quality) | `validate_composition` → `{ valid, errors[] }` (`unknown_primitive`, `invalid_primitive_params`, `clip_source_track_mismatch`, `reframe_coverage_gap`, …); does **not** check trim bounds or image-on-video-track (those fail at save/render) |
 | Look at real pixels | `preview_frame` at timestamps → PNG stills → LOOK |
-| Preview one graphic | `preview_component` (async motion clip: 202 + jobId → `wait_job(kind:"preview")`; compile errors land on the job's failed terminal with the author-fixable message) |
+| Judge motion or audio timing | `preview_clip` for the affected `[fromSec, toSec)` window → `wait_job(kind:"render")` → watch/listen; use matching reference timestamps |
+| Check an isolated card | `preview_card` with its HTML and tokens; no scratch composition needed |
+| Preview one graphic | `preview_component` (202 + jobId → `wait_job(kind:"preview")`; returns the verified artifact from the same immutable bundle used by production; compile/runtime/capability errors land on the job's failed terminal with the author-fixable message) |
 | 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` |

package/{skills → dist/skills}/cueframe-brand-demo/SKILL.md

@@ -31,6 +31,11 @@ Two things make this different from `cueframe-product-video`:
 Drive the primitives with the `cueframe-cli` skill and converge with
 `cueframe-compose-loop`; this tells you *what brand-demo to author*.
 
+Use the compose-loop [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+for iteration. Check brand/layout with stills and motion with `preview_clip`; a small revision
+does not require rerunning the Director or exporting the whole film. The pipeline below is for
+a new finished demo; choose the self-driven loop when the user has not asked for Director authoring.
+
 ## The pipeline
 
 ```

package/{skills → dist/skills}/cueframe-cli/SKILL.md

@@ -5,6 +5,23 @@ description: Use when editing, clipping, or rendering video via the CueFrame CLI
 
 # CueFrame CLI
 
+## MCP is the primary surface — read this before using the CLI
+
+**If you are an agent that can call tools, connect to CueFrame's MCP server instead of shelling
+out to this CLI.** MCP is the supported, maintained integration surface: it hides transport and
+contract details, its tools are generated from the same OpenAPI SSOT the CLI is, and it is where
+new capability lands first. The `cueframe-connect` skill owns the setup for every host
+(Claude Code, Claude/ChatGPT connectors, Cursor/Codex/VS Code/Windsurf/Zed, and the
+no-account pay-per-call path) — load it rather than copying a connection command from here.
+
+**Use this CLI when MCP is not available to you:** a terminal or CI job with no MCP host, a
+scripted batch, or a human at a shell. It is a first-class path, not a deprecated one — but it is
+the *second* thing to reach for.
+
+**Do not hand-roll `curl` against `/v1`.** Raw REST is the fallback beneath the fallback: it is
+where undocumented contract edges bite (components' runtime params were discovered that way), and
+both MCP and this CLI exist so you do not have to.
+
 ## Overview
 
 The `cueframe` CLI drives the CueFrame platform from the terminal. Optimized for agents — every command supports `--json` (NDJSON event stream) and the binary self-describes via `npx -y cueframe describe --json`.
@@ -28,13 +45,19 @@ the real wire schema the server enforces); confirm any draft with
 free and instant; a render is neither. The examples here are orientation — the
 schema is the source of truth.
 
-**Core principle:** Drive everything through `cueframe`. Never `curl` the v1 API around it — that invalidates the work and hides CLI bugs.
+**Core principle:** once you are ON this path, drive everything through `cueframe` — never `curl` the v1 API around it, which invalidates the work and hides CLI bugs. (Choosing MCP over the CLI in the first place is not "going around it"; see the banner above.)
 
 ## Framework workflow (upload → compose → render)
 
 The general path for any agent. Author the timeline yourself and render it — no
 clip suggestion required.
 
+For iteration, use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Validate first, then use `preview_card` / `preview_component` for isolated graphics,
+`preview_frame` for composition stills, or `preview_clip` for a motion window. Use the available
+MCP tools or the CLI's `api` escape hatch with the live request contract. Full `render` is for
+delivery, not checking each edit. CLI validation does not replace visual evidence.
+
 ```bash
 # 0. Always use --json for agent-driven runs (NDJSON to stdout, no spinners).
 #    Commands run against production; auth is stored in ~/.cueframe/auth.json.
@@ -174,7 +197,7 @@ npx -y cueframe new component my-badge --json
 #     cueframe/components/my-badge/index.tsx as your starting point.
 
 # 3. Edit cueframe/components/<id>/ — it's standard Remotion. The component is mounted
-#    ({ durationInFrames, params }) at render; params are your composition's clip params.
+#    ({ durationInFrames, params, assets, render }) at render; declare its v2 manifest.
 
 # 4. Publish to CueFrame so it can render (uploads index.tsx as the component's tsxSource).
 npx -y cueframe push my-badge --json            # one component
@@ -190,7 +213,7 @@ npx -y cueframe render <projectId> -o ./out.mp4 --json
 | Need to… | Command |
 |---|---|
 | See every command + flags | `npx -y cueframe describe --json` |
-| (Re)install/update this skill | `npx -y cueframe install` (→ `~/.claude/skills/cueframe-cli`) |
+| Install/refresh managed skills | `npx -y cueframe install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
 | List projects | `npx -y cueframe list -n 50` |
 | List your media | `npx -y cueframe clips` (no mediaId arg) |
 | Discover the live composition schema | `npx -y cueframe schema composition` |

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

@@ -0,0 +1,167 @@
+---
+name: cueframe-component-authoring
+description: Use when authoring, forking, or customizing a CueFrame motion-graphics component/primitive/graphic — e.g. "customize the cinematic-title primitive", "make my own animated lower-third", "fork a CueFrame template and edit it", "author a custom graphic and render it". Covers cloud MCP, local desktop, and CLI project paths through the same component-v2 contract. Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
+---
+
+# CueFrame component authoring (fork / customize / own)
+
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+to select hosted or local evidence and separate iteration from final delivery.
+
+CueFrame ships 87 built-in motion-graphics **primitives** (titles, lower-thirds, captions,
+effects, transitions, scenes). You can **fork any of them as editable source**, customize it,
+and render it on CueFrame — or author a brand-new component. This is shadcn-for-video: own the
+component code; CueFrame is the reliable engine that renders it.
+
+**Before you hand-write 3D:** a device mockup or a screenshot floating in a lit 3D scene is a
+**scene shot** — validated JSON with `scene.add` / `scene.update`, not a component you author.
+See the `cueframe-scene-shot` skill and `cueframe://scene-shot`. Author a component here when
+you need behaviour the scene contract does not express.
+
+**The two facts that shape everything:**
+- A component is mounted through contract v2 as
+  **`({ durationInFrames, params, assets, render }) => JSX`**. `render` contains frame, fps,
+  dimensions, deterministic seed, and color space. A from-scratch component must default-export
+  this shape; older components may ignore the added properties.
+- Neither renderer runs authored component source in the editor process. Hosted org components are
+  baked in an isolated box. A local project compiles source in a separate headless-Chromium child
+  process, pins the immutable source version in the project, and uses that version for the editor and export.
+
+## Path A — MCP agent (no filesystem; source lives server-side)
+
+Single self-contained module per component (`create_component` takes one `tsxSource`).
+
+1. **Fork a built-in:** `get_component_source(componentId: "cinematic-title")` → returns the
+   primitive's editable single-module `tsxSource` (the named component + the adapter). Discover
+   ids from the catalog (`/v1/components`). *(Or author from scratch — skip to step 2.)*
+2. **Author/own it:** edit the `tsxSource`, declare its v2 `manifest`, then call
+   `create_component({ componentId, tsxSource, manifest, … })` to store your customer-owned copy.
+   If forked, `ejectedFrom` is stamped.
+3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` queues a durable
+   preview and returns a `jobId`; call `wait_job(kind:"preview")`. The typed terminal result is a
+   verified artifact produced by the same bundle contract used by final render. A failed
+   `component_does_not_compile` job carries the compiler error — read it, fix via `update_component`
+   (same id, in place), and preview again.
+   Set preview duration deliberately: `durationInFrames` is not a trim window and can retime
+   duration-dependent motion. Preserve production timing; inspect the live tool's request shape.
+4. **Check integration:** add it as an `alpha-layer` clip (`apply_composition`), then inspect
+   saved-composition stills or a scoped `preview_clip` for placement and motion. Use
+   `create_render` → `wait_job kind:"render"` when delivering a finished MP4, not per tweak.
+
+## Path B — CLI / coding agent (customer-owned source under git)
+
+Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit locally as
+standard Remotion, push to render.
+
+```bash
+npx -y cueframe init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe new component my-badge --json     # scaffold a component in the workspace
+#   to start from a built-in instead of a blank file: fetch its source with the
+#   `get_component_source` tool and paste it into cueframe/components/my-badge/index.tsx
+# …edit cueframe/components/<id>/ in your editor (standard Remotion)…
+npx -y cueframe push my-badge --json              # upload index.tsx as the component tsxSource
+#   or: npx -y cueframe sync --json               # push every component in the workspace
+# reference the component id in your composition, then render:
+npx -y cueframe render <projectId> -o ./out.mp4 --json
+```
+
+The CLI writes a 3-file layout (`index.tsx` = renderable module + adapter; `_config.ts` + `config.ts`
+= local workspace metadata). `push` sends `index.tsx` as the single `tsxSource` — the same shape the
+MCP path stores. To preview before a full render, push it and use the MCP `preview_component` loop.
+
+## Path C — Director editing a local desktop project (project-embedded source)
+
+When `get_context` reports the project lane as local, motion does not require an account or an org
+component. When exposed, use `open_component_preview` to compile an isolated preview,
+`update_component_preview` to replace its source, and `render_component_preview_frame` for exact
+frame evidence. Inspect playback for motion; `commit_component_preview` commits the checked revision
+with a fresh ETag. Close the preview when finished. This loop does not bake a timeline video and
+does not imply HMR: source updates still compile.
+
+If those tools are unavailable, add/update through `apply_composition` and inspect the local
+timeline. An inline custom overlay has this shape:
+
+```json
+{
+  "type": "clip.add",
+  "clip": {
+    "id": "local-motion",
+    "kind": "overlay",
+    "startTime": 0,
+    "duration": 3,
+    "source": {
+      "kind": "overlay",
+      "primitiveId": "custom",
+      "params": {
+        "jsxSource": "export default function Graphic({ durationInFrames, params, assets, render }) { ... }",
+        "componentManifest": { "version": 2, "assets": {}, "graphics": { "api": "canvas2d", "required": true, "accelerationPreference": "software-allowed" }, "alphaPolicy": "requires-transparency" },
+        "componentAssets": {}
+      }
+    }
+  },
+  "newTrack": true
+}
+```
+
+The desktop compiles the module in an isolated child process and persists its immutable source version.
+The timeline and final export render that exact version; no preview media is baked. A compile failure
+refuses the whole batch and leaves the composition untouched. Use `create_component` only for a reusable
+org-catalog component on a reachable cloud lane.
+
+For media-backed graphics, declare each slot in `componentManifest.assets`, bind the slot to a
+project media id in `componentAssets`, and read its request-scoped handle from `assets`. The renderer
+localizes and hashes the file before execution. Remote URLs, undeclared assets, arbitrary filesystem
+paths, WebGL substitution, and static/card substitution are not fallback paths.
+
+Declare `componentManifest.alphaPolicy` explicitly: `requires-transparency` for overlays and
+`allows-opaque` for intentional full-frame plates. Both adapters verify the same field.
+
+Normal static imports are supported only from the runtime allowlist: React, Remotion, Three.js
+WebGPU/TSL, React Three Fiber/Drei, Remotion Three, and CueFrame animation helpers. Use ordinary hooks,
+loops, refs, constructors, typed arrays, canvas, and WebGPU when needed. Drive visible animation from
+`render.frame`/`render.fps` and seed variation from `render.seed`; ambient time/randomness is refused.
+
+## Choosing what to fork
+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+`preview_frame` to see it.)
+
+## Layout inside a component — `FlexLayout` / `solveFlex`
+When a graphic has several cells that must share space — a feature grid, a fixed rail beside
+fluid content, a cast of objects next to type — don't hand-place pixels. The layout helpers
+are in `@cueframe/animate` (on the import allowlist):
+
+```tsx
+import { FlexLayout } from '@cueframe/animate';
+const R = params.region ?? { x: 0, y: 0, w: 1, h: 1 };
+<FlexLayout
+  tracks={[{ weight: 0, basis: 520 }, 1, { weight: 3, split: [1, 1] }]}
+  tracksEnd={[{ weight: 0, basis: 520 }, 1, { weight: 1, split: [2, 1] }]}
+  fits={[{ mode: 'stretch' }, { mode: 'position' }, { mode: 'matte', aspect: 1 }, { mode: 'stretch' }]}
+  gap={16} width={R.w * width} height={R.h * height}>
+  <Rail /> <Type /> <Art /> <Block />
+</FlexLayout>
+```
+
+- Tracks are **weights, not pixels**; `{ weight: 0, basis: 520 }` is content-sized and pushes its
+  neighbours. Children fill the leaves depth-first (a `split` nests cells on the other axis).
+- `tracksEnd` animates: weights ease across the clip and **every cell re-solves per frame**. A cell
+  present on only one side enters from / exits to zero. Layout is the motion — no keyframed positions.
+- `fits`, one per leaf: `stretch | contain | cover | position | scale | matte`. `position` keeps type at
+  its natural size; `matte` clips a window instead of resizing the art.
+- Inside a `params.region` container pass `width`/`height` = the region's pixel size so nested splits and
+  aspect fits solve against the region, not the frame. **Never CSS-`scale()` the layout** — it resamples;
+  size the container instead.
+- 3D in the same rig: `solveFlex(tree, size, weights)` returns the boxes; `flexBoxToThree(box, size)`
+  centres a mesh under `<ThreeCanvas orthographic>` (frustum pinned 1:1 to pixels), so one canvas holds
+  every object exactly on its cell.
+- Same inputs, same boxes everywhere: the solve is pure and yoga-backed; nothing is measured from the DOM.
+  Text is placed, not measured — declare sizes with `basis` when a cell must fit its content.
+
+## Don't
+- Don't expect a forked primitive to use rich named props — read `params` inside and use the explicit
+  `assets` and `render` bags for media and frame state.
+- Don't hand-roll a graphic from zero when a built-in is close — fork it (fetch the source with
+  `get_component_source`, paste it into a `npx -y cueframe new component` scaffold) and edit.
+- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.

package/{skills → dist/skills}/cueframe-compose-loop/SKILL.md

@@ -5,23 +5,27 @@ 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
 the primitives with the `cueframe-cli` skill; this tells you *how to converge*.
 
+Before choosing a preview or export, read [preview-workflow.md](references/preview-workflow.md).
+It owns hosted/local routing, bounded motion evidence, and the distinction between a small edit
+and final delivery. For a minor revision, keep the approved brief and inspect the changed behavior
+plus relevant regressions; do not restart the full planning/judging loop below.
+
 ## The loop
 
 ```
-get_context  →  author  →  capture (look)  →  verify (score)
-                   ↑                               │
-                   └──── fix the WORST criterion ──┘   →  stop  →  render
+get_context  →  author  →  scoped preview (look)  →  judge if useful
+                   ↑                                      │
+                   └──────── fix the WORST criterion ──────┘  → stop → render
 ```
 
-Run it on a warm **session** (one boot, many fast renders), not one-shot renders.
+Hosted preview and scoring are durable, stateless jobs. Keep their job IDs and
+wait for each terminal result; there is no hosted render box to open, warm, or close.
+Use the local live-preview tools when working in a desktop project that exposes them.
 
 ## 0. Context — always first
 
@@ -44,24 +48,23 @@ are `.strict()`: a typo'd key is rejected, not silently dropped, so read the
 error and fix the key. Reference faces from get_context in your reframe segments;
 time captions/overlays from the transcript word timings.
 
-## 2. Open a session
-
-`POST /v1/projects/:id/compose-session` → `{ sessionId }`. Boots a warm render box
-(~60–120s the first time). Reuse it for every capture/verify in the loop; close
-it (`DELETE …/:sessionId`) when done — it also self-reaps at its TTL.
-
-## 3. Capture — look at it
+## 2. Preview — look at it
 
-`POST /v1/projects/:id/compose-session/:sessionId/render` with `{ composition,
-timestamps }` → stills, each with a presigned `url` you can actually view. Look at
-the beats you're unsure about (a cut, an overlay entrance, the hook). Stills are
-real render output — what you see is what ships.
+Use the curated `preview_frame` MCP tool, or
+`POST /v1/projects/:id/preview-frame-jobs`, with the composition target and the
+timestamps you need to inspect. The operation returns `{ jobId }` immediately.
+Call `wait_job({ kind: "preview_frame", id: jobId })`, then view the image artifact
+URLs in the successful result. Look at the beats you're unsure about: a cut, an
+overlay entrance, or the hook. The stills are real render evidence, not continuous-motion proof.
+Use `preview_clip` for the affected composition window to judge cuts, entrances, camera movement,
+and audio timing; use `preview_component` or `preview_card` for isolated authoring checks.
 
-## 4. Verify — score it
+## 3. Score it
 
-`POST /v1/projects/:id/compose-session/:sessionId/verify` with `{ composition,
-editorialIntent?, brandContext? }`. CueFrame's judge samples the meaningful beats,
-renders them, and returns:
+Use `score_composition`, or `POST /v1/projects/:id/score-composition`, with the
+composition target plus optional `editorialIntent` and `brandContext`. It returns
+`{ jobId }`; call `wait_job({ kind: "verify", jobId })`. CueFrame's judge samples
+the meaningful beats, renders them, and returns:
 
 ```
 { perCriterion: { editorial, spatial, brand, caption } each { score 0–10, critique },
@@ -83,18 +86,23 @@ You get **scores and the critique, never the rubric** — the taste is CueFrame'
 Pass `editorialIntent` (your brief/hook) so editorial is graded against what you
 meant.
 
-## 5. Fix the worst — then re-verify
+## 4. Fix the worst — then re-score
 
 Read `critique` — it names the lowest criterion first and says why. Fix **that one
-thing** (re-author the relevant ops), then verify again. One criterion per pass:
+thing** (re-author the relevant ops), then score again. One criterion per pass:
 chasing all four at once thrashes. Example: editorial 4 "two subjects off-center
-vs centered intent" → tighten the reframe onto face-0 → re-verify.
+vs centered intent" → tighten the reframe onto face-0 → re-score. A layout critique
+("cramped", "unbalanced", "text crowds the art") on a component built with
+`FlexLayout` is a `tracks` weight or `fits` change — re-author those and re-solve; never
+nudge pixels (see `cueframe-component-authoring`).
 
-## 6. Stop — then render
+## 5. Stop — then render
 
-Stop when **composite ≥ ~7.5** OR a pass doesn't improve the composite (two
-no-improvement passes = diminishing returns; ship the best so far). Then render
-the final: `createRender` (see `cueframe-cli`) → MP4.
+For a whole-film review, use **composite ≥ ~7.5** as a guide alongside the brief's actual
+acceptance criteria. Two no-improvement passes are a reason to stop spending and report what
+remains, not to declare a rejected result approved. Render with `create_render` only when a
+finished video is requested or the work reaches final delivery. A scoped revision can end with
+verified preview evidence and an explicit note that no new final export was made.
 
 ## Notes
 
@@ -102,5 +110,5 @@ the final: `createRender` (see `cueframe-cli`) → MP4.
   infra (capture/render) + the judge. That's the point — you keep the orchestration.
 - **Don't re-derive the judge or beat sampling** — verify owns both. Your job is
   author → read scores → fix worst → repeat.
-- **Budget the loop:** 3–5 verify passes is plenty for most clips. If composite
+- **Budget the loop:** 3–5 scoring passes is plenty for most clips. If composite
   won't climb, the limiter is usually the source or the intent, not more passes.

package/dist/skills/cueframe-compose-loop/references/preview-workflow.md

@@ -0,0 +1,37 @@
+# Preview, iteration, and delivery
+
+Choose the evidence for the current request. A small revision is not a new-film workflow. Preserve the approved brief, timeline, and unaffected source; inspect the affected behavior and relevant regressions. Export when the user requests a finished video or the work reaches final delivery, not after every preview or parameter edit.
+
+## Select the available lane
+
+Read the current tool contracts and project context. Do not infer a hosted session from a local desktop tool, or require cloud registration for a local project.
+
+| Need | Hosted evidence | Local desktop evidence, when exposed |
+|---|---|---|
+| Isolated HTML card layout | `preview_card` with the card's HTML and tokens | Inspect the card in the local project |
+| Authored component layout or motion | `preview_component`, with explicit dimensions, FPS, params, assets, and appropriate duration | `open_component_preview` → `update_component_preview`; inspect playback and `render_component_preview_frame` at exact frames |
+| Saved composition layout and overlap | `preview_frame`, batching the needed timestamps | The local composition preview/capture tools |
+| Cuts, entrances, camera motion, or audio timing | `preview_clip` for the affected `[fromSec, toSec)` window, including its lead-in and settle | Play/seek the affected window; capture matching frames when needed |
+| Finished deliverable | `create_render` and verify the resulting file | The project's export path and verification of its resulting file |
+
+Hosted calls use `projectId` and the request shape declared by the live tool. `preview_component` returns a job ID: wait with `kind:"preview"`. `preview_frame` uses `kind:"preview_frame"`. `preview_clip` returns a render job: wait with `kind:"render"`, even though it is a preview. Reuse the returned job ID; do not submit duplicate jobs while waiting. Hosted evidence jobs do not require opening or warming a compose session.
+
+The local component preview compiles replacement source revisions; it is not a promise of browser HMR or zero compilation work. `commit_component_preview` commits the inspected revision with a fresh project ETag. An isolated preview does not itself edit the saved timeline. Close the preview when finished if that tool is available.
+
+## Bound the work without changing the animation
+
+- Use a component's existing params for supported changes; update its source in place only when necessary. Do not create a new component ID for each tweak.
+- `durationInFrames` sets the component's render duration; it is **not a generic trim window**. Shortening it can retime animations normalized over duration. Preserve production timing. Use a documented component-specific offset only if it preserves that timing, or use the saved composition's `preview_clip` window. `startFrame` is not a universal preview API parameter.
+- Preserve FPS when judging motion. Choose resolution for the question: a low-resolution motion preview may establish timing but not typography, glass edges, or final-resolution shader quality. Use appropriate stills for those details.
+- Batch related still timestamps. Build contact sheets from returned images for inspection; a grid is a presentation of sampled frames, not proof of continuous motion. Watch the critical window as well. Listen when the change affects sound.
+- Scope output and compute are different: a short composition preview can still trigger preparation or an alpha bake on a cache miss. Inspect progress/receipts before diagnosing cost. Do not promise instant previews, cross-job cache hits, or that every requested still requires a full bake.
+
+## Evidence and stopping
+
+Keep component source revision/hash, params, asset bindings, dimensions, FPS, requested frames/window, and returned artifact/job identity together. For hosted composition parity, inspect `previewed.source`, composition ID, and ETag where provided. Source can change without changing the composition ETag. Unchanged pixels outside an edit's visible frame range do not by themselves prove a stale cache.
+
+Compare affected frames and motion with the reference at matching timestamps. Keep isolated-component proof distinct from saved-composition proof and final-export proof. For a minor edit, stop once the requested behavior and relevant regressions are checked; report the preview and explicitly say if no new final export was made.
+
+Use `score_composition` for broader editorial/brand review when useful and within budget. Do not require repeated whole-film judging to verify a known local correction. A judge score does not override a failed acceptance criterion or the user's visual feedback.
+
+Check account balance and current quotes before metered hosted work. Record actual job charges separately for preview, judging, and final export; separate those from agent time/token cost and from infrastructure estimates. Compare workflows only after testing equivalent changes and evidence requirements. Existing previews should be exercised before proposing new infrastructure.