cueframe 0.4.10 → 0.7.0

package/dist/skills/cueframe-cli/SKILL.md

@@ -5,10 +5,17 @@ description: Use when editing, clipping, or rendering video via the CueFrame CLI
 
 # CueFrame CLI
 
+## 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).
+
 ## 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
+**For a tool-driven workflow, prefer an existing supported MCP connection. For an explicitly requested terminal or CI workflow, use the 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
@@ -24,11 +31,11 @@ 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`.
+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@0.7 describe --json`.
 
-**Run it as `npx -y cueframe …` — every command in this skill is written that way, and
+**Run it as `npx -y cueframe@0.7 …` — every command in this skill is written that way, and
 that form is executable verbatim.** There is no `cueframe` on your PATH unless you put it
-there: `npx -y cueframe install` wires the MCP server and drops these skills, but npx
+there: `npx -y cueframe@0.7 install` wires the MCP server and drops these skills, but npx
 unpacks to an ephemeral cache, so it installs no binary. `npx` re-resolves the current
 version on each call (~0.5s warm, ~5s cold), which also means these commands never go
 stale. If you are running many in a row and want to skip that, `npm i -g cueframe` once
@@ -39,9 +46,9 @@ the documented path.
 **The framework is three verbs:** `upload` (register media) → `composition put` (author the timeline) → `render` (→ MP4). The `Composition` is the contract — render takes the saved composition, nothing else. Everything domain-specific (AI clip suggestions, FCPXML/Premiere export) is a **use-case on-ramp** layered on top, not part of the core.
 
 **Core principle — discover, don't guess.** Never author a composition from the
-examples below alone. The live contract is `npx -y cueframe schema composition` (prints
+examples below alone. The live contract is `npx -y cueframe@0.7 schema composition` (prints
 the real wire schema the server enforces); confirm any draft with
-`npx -y cueframe composition validate -b @file.json` BEFORE you render. Validation is
+`npx -y cueframe@0.7 composition validate -b @file.json` BEFORE you render. Validation is
 free and instant; a render is neither. The examples here are orientation — the
 schema is the source of truth.
 
@@ -63,20 +70,20 @@ delivery, not checking each edit. CLI validation does not replace visual evidenc
 #    Commands run against production; auth is stored in ~/.cueframe/auth.json.
 
 # 1. Register media (one or many — mixed video / image / audio).
-npx -y cueframe upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
+npx -y cueframe@0.7 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
 
 # 2. Create a project (sets aspect/format).
-npx -y cueframe project create -n "promo" -a 9:16 --json   # → projectId
+npx -y cueframe@0.7 project create -n "promo" -a 9:16 --json   # → projectId
 
 # 3. Author the composition: tracks of clips (per-clip reframe/trim), optional
 #    captions (captions.segments), brandKitId. The composition is the SSOT.
 #    Discover the live schema, then validate the draft BEFORE saving/rendering:
-npx -y cueframe schema composition                                 # → live wire schema
-npx -y cueframe composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
-npx -y cueframe composition put <projectId> -b @composition.json   # ETag auto
+npx -y cueframe@0.7 schema composition                                 # → live wire schema
+npx -y cueframe@0.7 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
+npx -y cueframe@0.7 composition put <projectId> -b @composition.json   # ETag auto
 
 # 4. Render the saved composition to MP4. SSE-watches + downloads when done.
-npx -y cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.7 render <projectId> -o ./out.mp4 --json
 # → render_queued → render_progress* → render_complete
 #
 # `render` takes ONLY a projectId and renders the SAVED composition (tracks +
@@ -85,14 +92,14 @@ npx -y cueframe render <projectId> -o ./out.mp4 --json
 # a hand-authored composition; if absent, the clip is rendered without captions.
 
 # Reattach to an in-flight render later (e.g. after disconnect):
-npx -y cueframe render watch <renderId> -p <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.7 render watch <renderId> -p <projectId> -o ./out.mp4 --json
 ```
 
 ## Anatomy of a composition.json
 
 This section orients you to the shape; the authoritative contract is
-`npx -y cueframe schema composition` (the live wire schema) — run it when a field is
-unclear, and `npx -y cueframe composition validate -b @file.json` to check a draft.
+`npx -y cueframe@0.7 schema composition` (the live wire schema) — run it when a field is
+unclear, and `npx -y cueframe@0.7 composition validate -b @file.json` to check a draft.
 
 `composition put` takes the **bare** `Composition` object (no wrapper; the CLI POSTs
 the `@file` verbatim and handles the ETag). Minimal valid shape:
@@ -159,18 +166,18 @@ the composition yourself (above).
 
 ```bash
 # 1. Upload + chain the AI clip pass.
-npx -y cueframe upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
-# (or run it explicitly: npx -y cueframe analyze <mediaItemId> --wait --json)
+npx -y cueframe@0.7 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
+# (or run it explicitly: npx -y cueframe@0.7 analyze <mediaItemId> --wait --json)
 
 # 2. List clip suggestions (publicId sug_…, title, startMs/endMs, score).
-npx -y cueframe clips <mediaItemId> --json
+npx -y cueframe@0.7 clips <mediaItemId> --json
 
 # 3. Create a project AND author its composition from the chosen suggestion.
-npx -y cueframe project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
-#   (or, on an existing project: npx -y cueframe composition from-suggestion <projectId> -s <sug_…>)
+npx -y cueframe@0.7 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
+#   (or, on an existing project: npx -y cueframe@0.7 composition from-suggestion <projectId> -s <sug_…>)
 
 # 4. Render — same framework verb as above.
-npx -y cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.7 render <projectId> -o ./out.mp4 --json
 ```
 
 Both flows converge on `composition put` → `render`; the on-ramp just authors the
@@ -187,51 +194,51 @@ video and composites it (the shared renderer never runs your code).
 
 ```bash
 # 1. Scaffold a workspace (writes cueframe.json + cueframe/components/). Idempotent.
-npx -y cueframe init --json
+npx -y cueframe@0.7 init --json
 
 # 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
-npx -y cueframe new component my-badge --json
+npx -y cueframe@0.7 new component my-badge --json
 
-# 2b. …or FORK a built-in: discover ids from the catalog (npx -y cueframe api GET /v1/components),
-#     fetch that primitive's source with the `get_component_source` tool, and paste it into
-#     cueframe/components/my-badge/index.tsx as your starting point.
+# Built-in forks require an exact v3 sourceSnapshot; retain its TSX, definition and manifest.
+# The CLI sends index.tsx + definition.json + the workspace asset manifest as one v3 source.
 
 # 3. Edit cueframe/components/<id>/ — it's standard Remotion. The component is mounted
-#    ({ durationInFrames, params, assets, render }) at render; declare its v2 manifest.
+#    with params/assets/render; definition.json declares its source-v3 capabilities and timing.
+#    The nested asset manifest remains version 2.
 
 # 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
-npx -y cueframe sync --json                      # every component in the workspace
+npx -y cueframe@0.7 push my-badge --json            # one component
+npx -y cueframe@0.7 sync --json                      # every component in the workspace
 
 # 5. Reference the component id in your composition as a {kind:'component', componentId, props}
 #    clip, then render with the same verb. Preview a single component first via the MCP
 #    preview_component loop.
-npx -y cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.7 render <projectId> -o ./out.mp4 --json
 ```
 
 ## Quick reference
 
 | Need to… | Command |
 |---|---|
-| See every command + flags | `npx -y cueframe describe --json` |
-| 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` |
-| Validate a draft (no save, no render) | `npx -y cueframe composition validate -b @plan.json` |
-| Read composition + ETag | `npx -y cueframe composition get <projectId> --json` |
-| Write composition | `npx -y cueframe composition put <projectId> -b @plan.json` (ETag auto) |
-| Export to Final Cut | `npx -y cueframe export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
-| Export to Premiere | `npx -y cueframe export premiere <projectId> -s <sug> --wait -o cut.zip` |
-| Anything not wrapped | `npx -y cueframe api GET /v1/...  -i` (escape hatch, like `gh api`) |
-| Validate a composition without mutating | `npx -y cueframe composition validate -b @plan.json` |
+| See every command + flags | `npx -y cueframe@0.7 describe --json` |
+| Install/refresh managed skills | `npx -y cueframe@0.7 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
+| List projects | `npx -y cueframe@0.7 list -n 50` |
+| List your media | `npx -y cueframe@0.7 clips` (no mediaId arg) |
+| Discover the live composition schema | `npx -y cueframe@0.7 schema composition` |
+| Validate a draft (no save, no render) | `npx -y cueframe@0.7 composition validate -b @plan.json` |
+| Read composition + ETag | `npx -y cueframe@0.7 composition get <projectId> --json` |
+| Write composition | `npx -y cueframe@0.7 composition put <projectId> -b @plan.json` (ETag auto) |
+| Export to Final Cut | `npx -y cueframe@0.7 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
+| Export to Premiere | `npx -y cueframe@0.7 export premiere <projectId> -s <sug> --wait -o cut.zip` |
+| Anything not wrapped | `npx -y cueframe@0.7 api GET /v1/...  -i` (escape hatch, like `gh api`) |
+| Validate a composition without mutating | `npx -y cueframe@0.7 composition validate -b @plan.json` |
 
 ## Auth
 
 Commands run against production. Authenticate once:
 
-- `npx -y cueframe login` — OAuth device flow (laptops).
-- `npx -y cueframe auth <cf_live_… key>` — save a static API key (CI / headless).
+- `npx -y cueframe@0.7 login` — OAuth device flow (laptops).
+- `npx -y cueframe@0.7 auth <cf_live_… key>` — save a static API key (CI / headless).
 
 Creds are stored in `~/.cueframe/auth.json`; the key can also come from the `CUEFRAME_API_KEY` env var.
 
@@ -249,17 +256,15 @@ Errors come as `{"event":"error", "phase":"<step>", "message":"...", "code":"...
 
 | Mistake | Reality |
 |---|---|
-| Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `npx -y cueframe api METHOD /v1/...` — same auth, same JSON pipeline. |
-| Polling for render completion with a sleep loop | `npx -y cueframe render` already SSE-watches and exits when done. Use `render watch <id>` to reattach. |
+| Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `npx -y cueframe@0.7 api METHOD /v1/...` — same auth, same JSON pipeline. |
+| Polling for render completion with a sleep loop | `npx -y cueframe@0.7 render` already SSE-watches and exits when done. Use `render watch <id>` to reattach. |
 | Skipping `--json` and trying to parse human output | Human output is for humans. Agents always use `--json`. |
 | Hand-editing the composition without an ETag | `composition put` GETs the ETag for you; `from-suggestion` rebuilds from a clip. Don't hand-craft unless you have to. |
-| Calling `npx -y cueframe render <projectId> <suggestionId>` (old two-positional shape) | `render` takes ONLY a projectId; commander rejects the extra arg. It renders the SAVED composition — author it first via `composition put` (hand-author) or `project create --from-suggestion <sug>` (clip-finder on-ramp). |
+| Calling `npx -y cueframe@0.7 render <projectId> <suggestionId>` (old two-positional shape) | `render` takes ONLY a projectId; commander rejects the extra arg. It renders the SAVED composition — author it first via `composition put` (hand-author) or `project create --from-suggestion <sug>` (clip-finder on-ramp). |
 | Assuming `render` needs a clip suggestion / that captions only come from a suggestion | No — `render` renders the saved composition directly; a suggestion is optional. Captions come from `composition.captions` (author them in the `put` JSON). The clip-suggestion on-ramp just fills those captions for you by slicing the transcript at author time. |
 
 ## When this skill applies (routing)
 
-Route on **intent, not operation**. This is the path whenever the task is *creating a video* — captioning, reframing or keeping a subject framed, finding the best moment, composing or branding clips, rendering to a target aspect/format. A mechanical verb ("trim", "concat") *inside* a creative goal ("…into a captioned 9:16 short") is still this skill — CueFrame does the trim too. If a task is part mechanical and part creative, it's this skill. When unsure whether a video task needs CueFrame, it does — author it here; validate cost-free with `--dry-run` first.
-
-Drop to raw `ffmpeg` only for a **single mechanical operation with zero creative or perceptual intent** — losslessly concatenating two finished files, transcoding a codec, extracting an audio track. That one carve-out aside, reach for `cueframe`.
+Use this skill for a requested terminal/CI workflow or when the available CLI is the supported path for the task. If supported MCP tools are already connected, use their narrow edit/preview guidance instead. A mechanical operation inside a creative task does not require a different project or new installation. If a required capability is absent, report the limitation and a supported alternative; do not invent a command or silently change lanes.
 
-Not this skill at all: inspecting internal backend state (that has its own operator tooling); changing the CLI's own source (that's CLI development, not usage).
+CLI development and internal backend inspection are outside this usage skill.

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

@@ -1,15 +1,23 @@
 ---
 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.
+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 using complete versioned source snapshots. Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
 ---
 
 # CueFrame component authoring (fork / customize / own)
 
+## 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).
+
 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,
+CueFrame ships built-in motion-graphics definitions (titles, lower-thirds, captions,
+effects, transitions and layouts). Discover the current catalog; fork an exact definition, 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.
 
@@ -18,32 +26,41 @@ component code; CueFrame is the reliable engine that renders it.
 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.
+**Source format matters:**
+- Built-ins use source v3: keep the complete `sourceSnapshot`, including `definition`,
+  `manifest`, and `tsxSource`. Its definition declares input schema, defaults, timing,
+  brand/media bindings and capabilities. Do not infer these from the source code or flatten
+  a v3 source into a v2 module. The nested asset manifest can still have `version: 2`.
+- Existing user-authored v2 sources use
+  `({ durationInFrames, params, assets, render }) => JSX`. Preserve their format when editing.
+- Neither renderer runs authored source in the editor process. Local and hosted execution
+  use isolated render processes and exact immutable source revisions.
 
 ## 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.
+Use the live tool schema for request envelopes; hosted write fields are normally under `body`.
+
+1. **Discover and read a built-in:** call `list_components` with
+   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
+   Select the intended card and preserve its complete scoped source reference. Call
+   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
+   `builtinCollection` (its scope collection), and `supportedSourceVersions: "3"`.
+   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
+   retry another scope or an unpinned head.
+2. **Author/own it:** edit the complete v3 `sourceSnapshot`; use your chosen owned ID
+   consistently in its `componentId` and the request. Send it as `body.source` to
+   `create_component`, with required metadata. Preserve its definition, capability
+   declarations, manifest and source format. For an existing component, keep its ID and
+   use `update_component` with the complete source. Do not send an old pin as the identity
+   of changed source: saving produces a new immutable source version.
 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.
    **Once the component is placed in a project, pass that project on every update:**
-   `update_component({ componentId, body: { tsxSource, projectId, compositionId? } })`. A placed clip
+   `update_component({ componentId, body: { source: editedSnapshot, projectId, compositionId? } })`
+   for v3; an existing v2 component uses its supported v2 edit fields. A placed clip
    renders the exact version it pins; only the composition you name moves to the new version in the
    same write (`repinned` says what moved). Without `projectId` your clips keep rendering the old
    version, and `placementsPinnedToPrevious` counts them.
@@ -60,26 +77,32 @@ Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edi
 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
+npx -y cueframe@0.7 init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe@0.7 new component my-badge --json     # scaffold a component in the workspace
+#   New scaffolds contain index.tsx, config.ts and definition.json (source v3).
+#   For a builtin fork, retain its TSX, complete definition and asset manifest together.
 # …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
+npx -y cueframe@0.7 push my-badge --json              # upload index.tsx as the component tsxSource
+#   or: npx -y cueframe@0.7 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
+npx -y cueframe@0.7 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.
+The CLI writes `index.tsx` (module), `config.ts` (metadata) and `definition.json` (complete v3
+input schema, defaults, timing and capabilities). Its asset manifest lives at
+`cueframe.json` → `components.<id>.manifest`; that nested manifest retains version 2.
+`push`/`sync` send these as one v3 `source` snapshot. For a builtin fork, copy **all three source
+parts** from the selected `sourceSnapshot`: TSX, definition and manifest; choose the owned ID
+consistently. Never replace a definition with the blank scaffold's defaults.
+Older workspaces without `definition.json` are refused before API calls: review and declare
+their real behavior instead of running `new --force` over existing source. To preview before
+a full render, push it and use the appropriate component preview 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 (new source,
-or `component_id` for a component already in the desktop's library), `update_component_preview`
+with an explicit `component_definition`, or `component_id` to preserve an existing library source), `update_component_preview`
 with exact-text edits (`{oldText, newText, replaceAll?}`, each `oldText` matching once), and
 `render_component_preview_frame` for exact frame evidence. Inspect playback for motion;
 `commit_component_preview` publishes the checked source to the library and pins the clip, with a
@@ -103,6 +126,7 @@ timeline. An inline custom overlay has this shape:
       "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" },
+        "componentDefinition": { "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }, "defaults": {}, "timing": { "defaultDuration": { "frames": 90, "fps": 30 } }, "brandBindings": [], "capabilities": [{ "kind": "clip" }] },
         "componentAssets": {}
       }
     }
@@ -112,7 +136,9 @@ timeline. An inline custom overlay has this shape:
 ```
 
 The desktop compiles the module in an isolated child process and creates it in the desktop's component
-library. Inline source creates a component only: a clip whose component already exists with other
+library as a complete v3 source. Declare the actual parameter schema and defaults in
+`componentDefinition`; the empty schema above is for a graphic with no custom parameters.
+Keep a fork's existing definition and nested manifest together with its source. Inline source creates a component only: a clip whose component already exists with other
 source is refused as `component_exists`, and that component changes through edits.
 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
@@ -132,10 +158,10 @@ loops, refs, constructors, typed arrays, canvas, and WebGPU when needed. Drive v
 `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.)
+Use the `component-library` projection to choose a definition, inspect its input schema and
+capabilities, then fetch its exact scoped source as described in Path A. Presets and recipes
+are different card kinds: follow their exact definition/document references rather than treating
+those IDs as source IDs. Inspect appropriate previews before judging visual behavior.
 
 ## Layout inside a component — `FlexLayout` / `solveFlex`
 When a graphic has several cells that must share space — a feature grid, a fixed rail beside
@@ -172,8 +198,8 @@ const R = params.region ?? { x: 0, y: 0, w: 1, h: 1 };
 ## 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.
+- When a built-in fits the request, fork its exact v3 snapshot using Path A. Never discard its
+  definition by copying only its TSX; preserve the definition and manifest too.
 - Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.
 - Don't update a placed component without its `projectId` in the body — the placed clips keep the
   version they pin, so the next preview or render shows the old graphic.

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

@@ -5,6 +5,14 @@ description: Use when an AI agent should DRIVE CueFrame to a high-quality clip i
 
 # CueFrame — Compose convergence loop
 
+## 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).
+
 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
@@ -27,7 +35,7 @@ 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
+## 0. Context — relevant project and source first
 
 `GET /v1/media/:id/context` (`cueframe_api_getMediaContext`) returns what you need
 to author well for a source:
@@ -40,10 +48,15 @@ to author well for a source:
 - **transcript** — utterances with per-word `start`/`end` (seconds). Use for
   caption timing and for placing overlays on the right beat.
 
+For a maintained builtin package, follow [exact builtin insertion](references/builtin-insertion.md)
+before authoring custom source.
+
 ## 1. Author
 
 Build/modify the working composition with the op vocabulary —
-`cueframe_api_applyCompositionOp` (one op) or `putComposition` (whole). Op keys
+the curated `apply_composition({ projectId, body: { ops: [...] } })`. Read
+`describe_composition_ops` for supported operations and `get_composition` for
+current revision and brand witnesses before editing. Op keys
 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.
@@ -61,9 +74,9 @@ and audio timing; use `preview_component` or `preview_card` for isolated authori
 
 ## 3. Score it
 
-Use `score_composition`, or `POST /v1/projects/:id/score-composition`, with the
+When broader review is useful and within budget, 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
+`{ jobId }`; call `wait_job({ kind: "verify", id: jobId })`. CueFrame's judge samples
 the meaningful beats, renders them, and returns:
 
 ```
@@ -82,6 +95,8 @@ The four criteria:
 | **brand**     | on-brand color/typography/voice; cohesive look |
 | **caption**   | caption legibility, timing, placement (or `no_captions` when absent) |
 
+The hosted caption criterion can penalize intentionally uncaptioned work; do not add captions solely for a score. These instructions do not change judge behavior.
+
 You get **scores and the critique, never the rubric** — the taste is CueFrame's.
 Pass `editorialIntent` (your brief/hook) so editorial is graded against what you
 meant.
@@ -98,8 +113,7 @@ nudge pixels (see `cueframe-component-authoring`).
 
 ## 5. Stop — then render
 
-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
+For a whole-film review, check the brief's actual acceptance criteria; no fixed score threshold applies. 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.

package/dist/skills/cueframe-compose-loop/references/builtin-insertion.md

@@ -0,0 +1,49 @@
+# Discover and insert an exact builtin
+
+Use the hosted MCP tools in this order. The CLI reaches the same REST operations
+through `cueframe api ... --json`; read `cueframe describe --json` for its current
+request options. Use the selected environment consistently.
+
+1. Call `list_catalog` with `projection: "component-library"`, `origin: "builtin"`,
+   `limit: 10` and a search term. Follow the returned cursor for more results.
+2. Preserve the selected card's complete identity, including collection, id and
+   revision. Call `resolve_builtin_component` with that exact identity. For a
+   preset or recipe, retain the returned `documentSha256` and canonical document.
+   A definition is source material, not a whole insertable package.
+3. Read the target with `get_composition`, negotiating component execution 3 and
+   dependencies. Keep its revision and brand identity. Do not recreate the project.
+4. Call `apply_template` with `template` equal to the selected builtin id. Put
+   projectId, documentSha256, insert, values, media and concurrency witnesses
+   inside `body`, following the live tool schema. Use an explicit nonnegative
+   `insert.startTime` and a unique `insert.idPrefix`; the package keeps its
+   authored placement offsets. Select pinned samples explicitly for every media slot you intend to use:
+   `media: { image1: { sample: true }, image2: { sample: true } }` (continue
+   for all declared slots), or bind real media IDs. Missing required bindings
+   are refused; samples are never selected implicitly.
+5. Read back the composition. Check that existing clips remain, every package
+   placement exists at its intended offset, and exact source pins are retained.
+6. Preview the affected interval, then use `create_render` and wait for the actual
+   artifact. Inspect the produced video; a successful request alone is not render
+   evidence.
+
+Never replace a selected revision with the latest, switch its scope, refresh a
+stale concurrency witness silently, synthesize replacement wrapper source, or
+use a thumbnail as the package. A pinned sample failure identifies the slot;
+report it or bind an explicit replacement instead of accepting changed bytes.
+
+The executable request examples beside this guide are validated against the
+MCP introspection snapshot generated from the server package.
+
+CLI discovery uses the same contract:
+
+```sh
+cueframe api GET '/v1/components?projection=component-library&origin=builtin&q=wheel&limit=10' --target dev --json
+cueframe api GET '/v1/components/builtin/resolve?collection=curated-looks&id=builtin%3Areference-component-wheel-full&revision=OBSERVED_REVISION' --target dev --json
+cueframe api POST '/v1/templates/builtin%3Areference-component-wheel-full/apply' --body @insertion.json --target dev --json
+```
+
+Replace `OBSERVED_REVISION` with the returned card revision. `insertion.json`
+contains the `body` object from the MCP example with real observed identifiers
+and witnesses. The fixture digest identifies the reviewed Wheel document; use the live resolved
+digest and observed brand identity instead of copying example witnesses. A 202 means pinned media preparation is pending: repeat the same
+insertion command after the response's retry delay, retaining `commandId`.