cueframe 0.6.0 → 0.7.0

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

@@ -382,7 +382,7 @@ Each playbook is an illustrative format default; explicit intent and scope gover
 | Long-form → clips | `suggest_briefs` → `wait_job(kind:"suggestions")` → `compose({ suggestionId })` |
 | Auto-reframe to another aspect | `derive_composition` (content-aware 9:16 / 1:1 / 4:5 from a 16:9 master) |
 | Discover what to build with | `list_catalog` — pass filters such as `category`/`kind`/`tier`/`useCase`/`mood`/`intent`, plus `limit` and the returned pagination cursor. For builtin packages, request `projection:"component-library"` and `origin:"builtin"`, then resolve the selected exact identity before insertion. Each entry carries `placement` (how to author it), `tier`/`useCase`, and `fixedCopy` (baked text no param changes). Read `cueframe://component/{id}` for the full **prop schema**. |
-| Own / fork a custom graphic | `get_component_source` / `create_component` (self-contained tsxSource) / `update_component` — **see `cueframe-component-authoring`** for the full fork→preview→push loop |
+| Own / fork a custom graphic | `get_component_source` (exact scoped v3 pin for builtins) / `create_component` / `update_component` (preserve the complete source snapshot) — **see `cueframe-component-authoring`** for the full fork→preview→push loop |
 | Several cells that share space and must reflow together (feature grid, rail + fluid content, cast + type) | An authored component on `FlexLayout` from `@cueframe/animate` — tracks are **weights** (`{ weight: 0, basis: px }` = content-sized, pushes neighbours), `tracksEnd` animates the reflow per frame, `fits` per cell (`stretch`/`contain`/`cover`/`position`/`scale`/`matte`). Static PiP / split is clip `region` + `fit` instead. Never CSS-scale the layout. **See `cueframe-component-authoring`** |
 | Seed + edit the timeline | `apply_composition` (atomic batch ops; `dry_run:true` to check, `if_match` for OCC) — this is where clips, reframe, captions, and format are authored |
 | Set the brand | `create_brand_kit` (402-gated) → set `brandKitId` on the **project** (`create_project` / `update_project`). It lives on the project, NOT on a composition op — trying to set it elsewhere is silently dropped. |

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

@@ -261,4 +261,4 @@ frames) before declaring done.
   which is the engine's job now.
 - This recipe lives in a skill on purpose: the engine stays use-case-free; the
   product opinions (what to extract, which overlays, how to brand) live here and
-  ship via `npx -y cueframe@0.6 install`.
+  ship via `npx -y cueframe@0.7 install`.

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

@@ -31,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@0.6 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@0.6 …` — 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@0.6 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
@@ -46,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@0.6 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@0.6 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.
 
@@ -70,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@0.6 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@0.6 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@0.6 schema composition                                 # → live wire schema
-npx -y cueframe@0.6 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
-npx -y cueframe@0.6 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@0.6 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 +
@@ -92,14 +92,14 @@ npx -y cueframe@0.6 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@0.6 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@0.6 schema composition` (the live wire schema) — run it when a field is
-unclear, and `npx -y cueframe@0.6 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:
@@ -166,18 +166,18 @@ the composition yourself (above).
 
 ```bash
 # 1. Upload + chain the AI clip pass.
-npx -y cueframe@0.6 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
-# (or run it explicitly: npx -y cueframe@0.6 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@0.6 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@0.6 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
-#   (or, on an existing project: npx -y cueframe@0.6 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@0.6 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
@@ -194,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@0.6 init --json
+npx -y cueframe@0.7 init --json
 
 # 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
-npx -y cueframe@0.6 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@0.6 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@0.6 push my-badge --json            # one component
-npx -y cueframe@0.6 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@0.6 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@0.6 describe --json` |
-| Install/refresh managed skills | `npx -y cueframe@0.6 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
-| List projects | `npx -y cueframe@0.6 list -n 50` |
-| List your media | `npx -y cueframe@0.6 clips` (no mediaId arg) |
-| Discover the live composition schema | `npx -y cueframe@0.6 schema composition` |
-| Validate a draft (no save, no render) | `npx -y cueframe@0.6 composition validate -b @plan.json` |
-| Read composition + ETag | `npx -y cueframe@0.6 composition get <projectId> --json` |
-| Write composition | `npx -y cueframe@0.6 composition put <projectId> -b @plan.json` (ETag auto) |
-| Export to Final Cut | `npx -y cueframe@0.6 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
-| Export to Premiere | `npx -y cueframe@0.6 export premiere <projectId> -s <sug> --wait -o cut.zip` |
-| Anything not wrapped | `npx -y cueframe@0.6 api GET /v1/...  -i` (escape hatch, like `gh api`) |
-| Validate a composition without mutating | `npx -y cueframe@0.6 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@0.6 login` — OAuth device flow (laptops).
-- `npx -y cueframe@0.6 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.
 
@@ -256,11 +256,11 @@ 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@0.6 api METHOD /v1/...` — same auth, same JSON pipeline. |
-| Polling for render completion with a sleep loop | `npx -y cueframe@0.6 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@0.6 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)

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

@@ -1,6 +1,6 @@
 ---
 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)
@@ -16,8 +16,8 @@ For scoped revisions, preserve unrelated timing, media, audio and shared brand-k
 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.
 
@@ -26,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.
@@ -68,26 +77,32 @@ Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edi
 standard Remotion, push to render.
 
 ```bash
-npx -y cueframe@0.6 init --json                       # scaffold cueframe.json + cueframe/components/
-npx -y cueframe@0.6 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@0.6 push my-badge --json              # upload index.tsx as the component tsxSource
-#   or: npx -y cueframe@0.6 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@0.6 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
@@ -111,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": {}
       }
     }
@@ -120,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
@@ -140,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
@@ -180,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@0.6 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-connect/SKILL.md

@@ -23,7 +23,7 @@ When a required capability is missing, explain the limitation and the supported
 - **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, Antigravity CLI, Copilot CLI, …):**
-  use `npx -y cueframe@0.6 install --help` to select the intended client; preserve existing configuration and avoid duplicate installs.
+  use `npx -y cueframe@0.7 install --help` to select the intended client; preserve existing configuration and avoid duplicate installs.
 - **ChatGPT:** the CLI cannot wire it because there is no local config to write; add
   `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
 - **No account (pay per call):** connect

package/dist/skills/cueframe-product-video/SKILL.md

@@ -21,7 +21,7 @@ to author, not how to transport it.
 
 **Drive the primitives over MCP if you can call tools** (`new_composition` /
 `apply_composition` / `validate_composition` / `create_render` — see the
-`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.6 …` commands
+`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.7 …` commands
 written out below are the same operations for a terminal or CI job with no MCP
 host; see the `cueframe-cli` skill.
 
@@ -64,7 +64,7 @@ style's) over each window. Result → `source.reframe.segments` on the clip.
 ## 3. Compose
 
 One video track, the screen recording as a media clip carrying the reframe.
-`npx -y cueframe@0.6 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+`npx -y cueframe@0.7 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
 Choose `-a 16:9` for landscape product video, `9:16` for social.
 
 ## 4. Polish — layer overlay primitives (this is what makes it look "produced")
@@ -102,21 +102,21 @@ check framing with `preview_frame` and click/zoom timing with an affected-window
 For a small revision, verify that change and relevant regressions without exporting the whole film.
 When delivering the finished video:
 
-`npx -y cueframe@0.6 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+`npx -y cueframe@0.7 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
 sample frames) before declaring done.
 
 ## Worked examples — composition JSON
 
 These are **orientation, not the contract.** The live wire schema is
-`npx -y cueframe@0.6 schema composition`, and the way to know a draft is correct is
-`npx -y cueframe@0.6 composition validate -b @composition.json` — it runs the same
+`npx -y cueframe@0.7 schema composition`, and the way to know a draft is correct is
+`npx -y cueframe@0.7 composition validate -b @composition.json` — it runs the same
 validator the server enforces, with no save and no render. Discover + validate
 before you render; never spend a render to find a schema mistake.
 
 Each block below is a complete `@composition.json` (the bare object `composition put`
 accepts: top-level `v`, `format`, `tracks`, optional `captions`). All five validate
 against the real wire schema + save invariants (swap the `<…MediaId>` placeholders for
-real `npx -y cueframe@0.6 upload` ids). Conventions that keep them valid:
+real `npx -y cueframe@0.7 upload` ids). Conventions that keep them valid:
 
 - Tracks hold **`contents`** (not `clips`); each clip wraps a `source`.
 - A clip's `source.kind` must match the track `kind`: `media` → `video`/`image`/`audio`
@@ -298,4 +298,4 @@ Talking-head with an `active-speaker` reframe and a `heroText` title at `zPlane:
   background. See EX3 / EX4 below.
 - This recipe lives in a skill on purpose: the engine stays use-case-free; the
   product opinions (style, which primitives, layout) live here and ship via
-  `npx -y cueframe@0.6 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.
+  `npx -y cueframe@0.7 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueframe",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Agent-native CLI for CueFrame — author compositions and render video from the terminal (early-access preview).",
   "keywords": [
     "cueframe",
@@ -47,7 +47,7 @@
     "tsup": "^8.5.1",
     "vitest": "^4.1.2",
     "@cueframe/sdk": "^0.5.0",
-    "@cueframe/skills": "0.1.2"
+    "@cueframe/skills": "0.2.0"
   },
   "repository": {
     "type": "git",

package/dist/analyze-Q6MIQWOJ.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{E as a}from"./chunk-U3YHQOER.js";import"./chunk-3QSA3EBY.js";export{a as analyzeCommand};