cueframe 0.3.2 → 0.4.3

package/skills/cueframe-cli/SKILL.md

@@ -7,14 +7,24 @@ description: Use when editing, clipping, or rendering video via the CueFrame CLI
 
 ## 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 `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 describe --json`.
+
+**Run it as `npx -y cueframe …` — 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
+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
+and drop the `npx -y ` prefix — but it needs a user-writable npm prefix (a default Linux
+install fails `EACCES` on `/usr/local/lib/node_modules`), so it is an optimization, not
+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 `cueframe schema composition` (prints
+examples below alone. The live contract is `npx -y cueframe schema composition` (prints
 the real wire schema the server enforces); confirm any draft with
-`cueframe composition validate -b @file.json` BEFORE you render. Validation is
+`npx -y cueframe 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.
 
@@ -30,20 +40,20 @@ clip suggestion required.
 #    Commands run against production; auth is stored in ~/.cueframe/auth.json.
 
 # 1. Register media (one or many — mixed video / image / audio).
-cueframe upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
+npx -y cueframe upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
 
 # 2. Create a project (sets aspect/format).
-cueframe project create -n "promo" -a 9:16 --json   # → projectId
+npx -y cueframe 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:
-cueframe schema composition                                 # → live wire schema
-cueframe composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
-cueframe composition put <projectId> -b @composition.json   # ETag auto
+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
 
 # 4. Render the saved composition to MP4. SSE-watches + downloads when done.
-cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe render <projectId> -o ./out.mp4 --json
 # → render_queued → render_progress* → render_complete
 #
 # `render` takes ONLY a projectId and renders the SAVED composition (tracks +
@@ -52,14 +62,14 @@ 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):
-cueframe render watch <renderId> -p <projectId> -o ./out.mp4 --json
+npx -y cueframe 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
-`cueframe schema composition` (the live wire schema) — run it when a field is
-unclear, and `cueframe composition validate -b @file.json` to check a draft.
+`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.
 
 `composition put` takes the **bare** `Composition` object (no wrapper; the CLI POSTs
 the `@file` verbatim and handles the ETag). Minimal valid shape:
@@ -126,18 +136,18 @@ the composition yourself (above).
 
 ```bash
 # 1. Upload + chain the AI clip pass.
-cueframe upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
-# (or run it explicitly: cueframe analyze <mediaItemId> --wait --json)
+npx -y cueframe upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
+# (or run it explicitly: npx -y cueframe analyze <mediaItemId> --wait --json)
 
 # 2. List clip suggestions (publicId sug_…, title, startMs/endMs, score).
-cueframe clips <mediaItemId> --json
+npx -y cueframe clips <mediaItemId> --json
 
 # 3. Create a project AND author its composition from the chosen suggestion.
-cueframe project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
-#   (or, on an existing project: cueframe composition from-suggestion <projectId> -s <sug_…>)
+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_…>)
 
 # 4. Render — same framework verb as above.
-cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe render <projectId> -o ./out.mp4 --json
 ```
 
 Both flows converge on `composition put` → `render`; the on-ramp just authors the
@@ -154,50 +164,50 @@ video and composites it (the shared renderer never runs your code).
 
 ```bash
 # 1. Scaffold a workspace (writes cueframe.json + cueframe/components/). Idempotent.
-cueframe init --json
+npx -y cueframe init --json
 
-# 2a. FORK a built-in primitive into cueframe/components/<id>/ as owned, editable source.
-#     Discover ids from the catalog: cueframe api GET /v1/components   (the live primitive catalog).
-cueframe eject cinematic-title --json
+# 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
+npx -y cueframe new component my-badge --json
 
-# 2b. …or scaffold a blank custom component.
-cueframe 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.
 
 # 3. Edit cueframe/components/<id>/ — it's standard Remotion. The component is mounted
 #    ({ durationInFrames, params }) at render; params are your composition's clip params.
 
 # 4. Publish to CueFrame so it can render (uploads index.tsx as the component's tsxSource).
-cueframe push cinematic-title --json     # one component
-cueframe sync --json                      # every component in the workspace
+npx -y cueframe push my-badge --json            # one component
+npx -y cueframe sync --json                      # every component in the workspace
 
 # 5. Reference the component id in your composition (as an alpha-layer clip), then render
 #    with the same verb. Preview a single component first via the MCP preview_component loop.
-cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe render <projectId> -o ./out.mp4 --json
 ```
 
 ## Quick reference
 
 | Need to… | Command |
 |---|---|
-| See every command + flags | `cueframe describe --json` |
-| (Re)install/update this skill | `cueframe install` (→ `~/.claude/skills/cueframe-cli`) |
-| List projects | `cueframe list -n 50` |
-| List your media | `cueframe clips` (no mediaId arg) |
-| Discover the live composition schema | `cueframe schema composition` |
-| Validate a draft (no save, no render) | `cueframe composition validate -b @plan.json` |
-| Read composition + ETag | `cueframe composition get <projectId> --json` |
-| Write composition | `cueframe composition put <projectId> -b @plan.json` (ETag auto) |
-| Export to Final Cut | `cueframe export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
-| Export to Premiere | `cueframe export premiere <projectId> -s <sug> --wait -o cut.zip` |
-| Anything not wrapped | `cueframe api GET /v1/...  -i` (escape hatch, like `gh api`) |
-| Validate a composition without mutating | `cueframe composition validate -b @plan.json` |
+| See every command + flags | `npx -y cueframe describe --json` |
+| (Re)install/update this skill | `npx -y cueframe install` (→ `~/.claude/skills/cueframe-cli`) |
+| 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` |
 
 ## Auth
 
 Commands run against production. Authenticate once:
 
-- `cueframe login` — OAuth device flow (laptops).
-- `cueframe auth <cf_live_… key>` — save a static API key (CI / headless).
+- `npx -y cueframe login` — OAuth device flow (laptops).
+- `npx -y cueframe 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.
 
@@ -215,11 +225,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 `cueframe api METHOD /v1/...` — same auth, same JSON pipeline. |
-| Polling for render completion with a sleep loop | `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 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. |
 | 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 `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 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/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 both the MCP agent path (get_component_source → create_component) and the CLI repo path (cueframe eject/new → push). 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 both the MCP agent path (get_component_source → create_component) and the CLI repo path (get_component_source → npx -y cueframe new component → push). Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
 ---
 
 # CueFrame component authoring (fork / customize / own)
@@ -39,14 +39,15 @@ Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edi
 standard Remotion, push to render.
 
 ```bash
-cueframe init --json                       # scaffold cueframe.json + cueframe/components/
-cueframe eject cinematic-title --json       # fork a built-in primitive as owned source
-#   or: cueframe new component my-badge --json     # scaffold a blank one
+npx -y cueframe init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe new component my-badge --json     # scaffold a component in the workspace
+#   to start from a built-in instead of a blank file: fetch its source with the
+#   `get_component_source` tool and paste it into cueframe/components/my-badge/index.tsx
 # …edit cueframe/components/<id>/ in your editor (standard Remotion)…
-cueframe push cinematic-title --json        # upload index.tsx as the component tsxSource
-#   or: cueframe sync --json                # push every component in the workspace
+npx -y cueframe push my-badge --json              # upload index.tsx as the component tsxSource
+#   or: npx -y cueframe sync --json               # push every component in the workspace
 # reference the component id in your composition, then render:
-cueframe render <projectId> -o ./out.mp4 --json
+npx -y cueframe render <projectId> -o ./out.mp4 --json
 ```
 
 The CLI writes a 3-file layout (`index.tsx` = renderable module + adapter; `_config.ts` + `config.ts`
@@ -62,6 +63,6 @@ follow-up — today you choose from prose + params + source, or compose+`preview
 ## Don't
 - Don't expect a forked primitive to use rich named props — it's adapted to `({durationInFrames,
   params})`; read `params` inside.
-- Don't hand-roll a graphic from zero when a built-in is close — fork it (`get_component_source` /
-  `cueframe eject`) and edit.
+- Don't hand-roll a graphic from zero when a built-in is close — fork it (fetch the source with
+  `get_component_source`, paste it into a `npx -y cueframe new component` scaffold) and edit.
 - Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.

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

@@ -50,7 +50,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.
-`cueframe composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+`npx -y cueframe 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")
@@ -77,21 +77,21 @@ Simultaneous overlays go on **separate tracks** — clips on one track can't ove
 
 ## 5. Render
 
-`cueframe render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+`npx -y cueframe 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
-`cueframe schema composition`, and the way to know a draft is correct is
-`cueframe composition validate -b @composition.json` — it runs the same
+`npx -y cueframe schema composition`, and the way to know a draft is correct is
+`npx -y cueframe 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 `cueframe upload` ids). Conventions that keep them valid:
+real `npx -y cueframe 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`
@@ -267,9 +267,10 @@ Talking-head with an `active-speaker` reframe and a `heroText` title at `zPlane:
 - **Picture-in-picture / inset cards render** — per-clip output-space placement
   (`region:{x,y,w,h}` in `[0,1]` + `fit`) is wired for PiP / inset / split-screen,
   for video, image, and overlay clips. Set `region`/`fit` on the **clip** (siblings
-  of `source`, not inside it — or author via the `set_clip_region` agent tool); two
+  of `source`, not inside it — as an agent, patch them with an `apply_composition`
+  `clip.update` op: `{ type: 'clip.update', clipId, patch: { region, fit } }`); two
   clips with different placement composite by track order instead of occluding the
   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
-  `cueframe install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.
+  `npx -y cueframe install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.

package/skills/every-format-from-one-edit/SKILL.md

@@ -25,6 +25,9 @@ approaches and CueFrame isn't connected:
   run `npx -y cueframe install` — it detects what is on the machine and wires each one.
 - **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
   `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
+- **No account at all (pay-per-call):** connect
+  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
+  settle per-call in USDC over x402 from the agent's wallet.
 <!-- /cueframe:connect -->
 
 Then straight to deriving — this whole job is minutes when the master is good.

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

@@ -22,7 +22,7 @@ they go straight to storage via presigned PUTs.
 
 ## 0. Prereqs
 
-- An API key with `projects:write` (create_brand_kit gates on the `brand_kits` plan feature — check `get_account` first; 402 names the feature).
+- An API key with `projects:write`. `create_brand_kit` gates on the `brand_kits` entitlement, which EVERY plan grants including free, and it costs no credits — so brand kits are not a paywall to route around. (`get_account` confirms it; a 402 names the feature.)
 - `ffmpeg` locally, and the reference video file (download it first if it's a URL).
 - Know the org's IDENTITY kit if one exists (`get_profile` → brandKits). Inspiration NEVER overwrites identity: logo, brand fonts, and identity color slots come from the existing kit (or stay for the user to fill) — extraction contributes the LANGUAGE only.
 

package/skills/launch-video/SKILL.md

@@ -24,6 +24,9 @@ approaches and CueFrame isn't connected:
   run `npx -y cueframe install` — it detects what is on the machine and wires each one.
 - **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
   `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
+- **No account at all (pay-per-call):** connect
+  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
+  settle per-call in USDC over x402 from the agent's wallet.
 <!-- /cueframe:connect -->
 
 Keep the momentum — the video plan is the hard part, the connection is not.

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

@@ -24,6 +24,9 @@ When the first real tool call is imminent and CueFrame isn't connected:
   run `npx -y cueframe install` — it detects what is on the machine and wires each one.
 - **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
   `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
+- **No account at all (pay-per-call):** connect
+  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
+  settle per-call in USDC over x402 from the agent's wallet.
 <!-- /cueframe:connect -->
 
 Thirty seconds, then straight back to the reel — treat it as a detour, never a gate.

package/skills/rebrand-a-video/SKILL.md

@@ -25,6 +25,9 @@ approaches and CueFrame isn't connected:
   run `npx -y cueframe install` — it detects what is on the machine and wires each one.
 - **ChatGPT:** the CLI cannot wire it (there is no local config to write) — add
   `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
+- **No account at all (pay-per-call):** connect
+  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up, no API key; priced calls
+  settle per-call in USDC over x402 from the agent's wallet.
 <!-- /cueframe:connect -->
 
 Then back to the brand — most of this job is a kit definition and an audit.

package/skills/video-craft-standards/SKILL.md

@@ -103,9 +103,10 @@ Everything in §1, plus:
 - **MUST** Active-speaker reframe (`focus: active-speaker` / `face`) — a
   moving camera, not a static center crop.
 - **MUST** Captions timed to the real transcript (`captions.fromTranscript`).
-  The behind-the-speaker LOOK is an overlay text layer at
-  `zPlane:"behind-subject"` where the footage allows — the caption layer
-  itself always renders in front.
+  The focused behind-the-speaker LOOK is an overlay text layer at
+  `zPlane:"behind-subject"` where the footage allows. Use caption-layer
+  `zPlane:"behind-subject"` only when the user explicitly wants every running
+  caption behind the speaker and the legibility gate accepts it.
 - **MUST** Dead air and false starts cut (`addExcludedRange` /
   `cutAndRipple`).
 

package/dist/analyze-4EZTZEAG.js

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