@cueframe/skills 0.2.0 → 0.2.2

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.7 install`.
+  ship via `npx -y cueframe@0.8 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.7 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.8 describe --json`.
 
-**Run it as `npx -y cueframe@0.7 …` — every command in this skill is written that way, and
+**Run it as `npx -y cueframe@0.8 …` — 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.7 install` wires the MCP server and drops these skills, but npx
+there: `npx -y cueframe@0.8 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.7 schema composition` (prints
+examples below alone. The live contract is `npx -y cueframe@0.8 schema composition` (prints
 the real wire schema the server enforces); confirm any draft with
-`npx -y cueframe@0.7 composition validate -b @file.json` BEFORE you render. Validation is
+`npx -y cueframe@0.8 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.7 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
+npx -y cueframe@0.8 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
 
 # 2. Create a project (sets aspect/format).
-npx -y cueframe@0.7 project create -n "promo" -a 9:16 --json   # → projectId
+npx -y cueframe@0.8 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.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
+npx -y cueframe@0.8 schema composition                                 # → live wire schema
+npx -y cueframe@0.8 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
+npx -y cueframe@0.8 composition put <projectId> -b @composition.json   # ETag auto
 
 # 4. Render the saved composition to MP4. SSE-watches + downloads when done.
-npx -y cueframe@0.7 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.8 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.7 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.7 render watch <renderId> -p <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.8 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.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.
+`npx -y cueframe@0.8 schema composition` (the live wire schema) — run it when a field is
+unclear, and `npx -y cueframe@0.8 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.7 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
-# (or run it explicitly: npx -y cueframe@0.7 analyze <mediaItemId> --wait --json)
+npx -y cueframe@0.8 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
+# (or run it explicitly: npx -y cueframe@0.8 analyze <mediaItemId> --wait --json)
 
 # 2. List clip suggestions (publicId sug_…, title, startMs/endMs, score).
-npx -y cueframe@0.7 clips <mediaItemId> --json
+npx -y cueframe@0.8 clips <mediaItemId> --json
 
 # 3. Create a project AND author its composition from the chosen suggestion.
-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_…>)
+npx -y cueframe@0.8 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
+#   (or, on an existing project: npx -y cueframe@0.8 composition from-suggestion <projectId> -s <sug_…>)
 
 # 4. Render — same framework verb as above.
-npx -y cueframe@0.7 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.8 render <projectId> -o ./out.mp4 --json
 ```
 
 Both flows converge on `composition put` → `render`; the on-ramp just authors the
@@ -194,10 +194,10 @@ 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.7 init --json
+npx -y cueframe@0.8 init --json
 
 # 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
-npx -y cueframe@0.7 new component my-badge --json
+npx -y cueframe@0.8 new component my-badge --json
 
 # 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.
@@ -207,38 +207,38 @@ npx -y cueframe@0.7 new component my-badge --json
 #    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.7 push my-badge --json            # one component
-npx -y cueframe@0.7 sync --json                      # every component in the workspace
+npx -y cueframe@0.8 push my-badge --json            # one component
+npx -y cueframe@0.8 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.7 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.8 render <projectId> -o ./out.mp4 --json
 ```
 
 ## Quick reference
 
 | Need to… | Command |
 |---|---|
-| 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` |
+| See every command + flags | `npx -y cueframe@0.8 describe --json` |
+| Install/refresh managed skills | `npx -y cueframe@0.8 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
+| List projects | `npx -y cueframe@0.8 list -n 50` |
+| List your media | `npx -y cueframe@0.8 clips` (no mediaId arg) |
+| Discover the live composition schema | `npx -y cueframe@0.8 schema composition` |
+| Validate a draft (no save, no render) | `npx -y cueframe@0.8 composition validate -b @plan.json` |
+| Read composition + ETag | `npx -y cueframe@0.8 composition get <projectId> --json` |
+| Write composition | `npx -y cueframe@0.8 composition put <projectId> -b @plan.json` (ETag auto) |
+| Export to Final Cut | `npx -y cueframe@0.8 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
+| Export to Premiere | `npx -y cueframe@0.8 export premiere <projectId> -s <sug> --wait -o cut.zip` |
+| Anything not wrapped | `npx -y cueframe@0.8 api GET /v1/...  -i` (escape hatch, like `gh api`) |
+| Validate a composition without mutating | `npx -y cueframe@0.8 composition validate -b @plan.json` |
 
 ## Auth
 
 Commands run against production. Authenticate once:
 
-- `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).
+- `npx -y cueframe@0.8 login` — OAuth device flow (laptops).
+- `npx -y cueframe@0.8 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.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. |
+| Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `npx -y cueframe@0.8 api METHOD /v1/...` — same auth, same JSON pipeline. |
+| Polling for render completion with a sleep loop | `npx -y cueframe@0.8 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.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). |
+| Calling `npx -y cueframe@0.8 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

@@ -27,12 +27,12 @@ See the `cueframe-scene-shot` skill and `cueframe://scene-shot`. Author a compon
 you need behaviour the scene contract does not express.
 
 **Source format matters:**
-- Built-ins use source v3: keep the complete `sourceSnapshot`, including `definition`,
+- Every executable component uses 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.
+- The mount signature is `({ durationInFrames, params, assets, render }) => JSX`.
+  Source2 inputs require explicit migration; they are not accepted for editing or rendering.
 - Neither renderer runs authored source in the editor process. Local and hosted execution
   use isolated render processes and exact immutable source revisions.
 
@@ -44,7 +44,7 @@ Use the live tool schema for request envelopes; hosted write fields are normally
    `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"`.
+   `builtinCollection` (its scope collection).
    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
@@ -58,15 +58,18 @@ Use the live tool schema for request envelopes; hosted write fields are normally
    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:**
+   **Repin only the requested scope:** for all matching placements in one composition, use
    `update_component({ componentId, body: { source: editedSnapshot, projectId, compositionId? } })`
-   for v3; an existing v2 component uses its supported v2 edit fields. A placed clip
+   with the observed revision and dependency guards. 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.
+   version, and `placementsPinnedToPrevious` counts them. For a single placement, update the
+   source without `projectId`, then change only that clip to the returned exact source pin
+   using the observed concurrency guards.
    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 a `{kind:'component', componentId, props}` clip
+4. **Check integration:** add it as a `{kind:'component', componentId, props:{},
+   execution:{version:3,componentId,sourceVersionId,params,seed}, placement:{version:3,kind:'clip'}}` 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.
@@ -77,15 +80,15 @@ Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edi
 standard Remotion, push to render.
 
 ```bash
-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
+npx -y cueframe@0.8 init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe@0.8 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.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
+npx -y cueframe@0.8 push my-badge --json              # upload index.tsx as the component tsxSource
+#   or: npx -y cueframe@0.8 sync --json               # push every component in the workspace
 # reference the component id in your composition, then render:
-npx -y cueframe@0.7 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.8 render <projectId> -o ./out.mp4 --json
 ```
 
 The CLI writes `index.tsx` (module), `config.ts` (metadata) and `definition.json` (complete v3
@@ -201,5 +204,3 @@ const R = params.region ?? { x: 0, y: 0, w: 1, h: 1 };
 - 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.7 install --help` to select the intended client; preserve existing configuration and avoid duplicate installs.
+  use `npx -y cueframe@0.8 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.7 …` commands
+`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.8 …` 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.7 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+`npx -y cueframe@0.8 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.7 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+`npx -y cueframe@0.8 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.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
+`npx -y cueframe@0.8 schema composition`, and the way to know a draft is correct is
+`npx -y cueframe@0.8 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.7 upload` ids). Conventions that keep them valid:
+real `npx -y cueframe@0.8 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.7 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.
+  `npx -y cueframe@0.8 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueframe/skills",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "CueFrame agent skills: the SKILL.md tree the CueFrame plugin ships, packaged for programs that copy or embed the skills.",
   "license": "Apache-2.0",
   "type": "module",