@cueframe/skills 0.1.0 → 0.1.2

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

@@ -5,6 +5,14 @@ description: Use when authoring, forking, or customizing a CueFrame motion-graph
 
 # 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.
 
@@ -60,15 +68,15 @@ Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edi
 standard Remotion, push to render.
 
 ```bash
-npx -y cueframe@0.5 init --json                       # scaffold cueframe.json + cueframe/components/
-npx -y cueframe@0.5 new component my-badge --json     # scaffold a component in the workspace
+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
 # …edit cueframe/components/<id>/ in your editor (standard Remotion)…
-npx -y cueframe@0.5 push my-badge --json              # upload index.tsx as the component tsxSource
-#   or: npx -y cueframe@0.5 sync --json               # push every component in the workspace
+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
 # reference the component id in your composition, then render:
-npx -y cueframe@0.5 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.6 render <projectId> -o ./out.mp4 --json
 ```
 
 The CLI writes a 3-file layout (`index.tsx` = renderable module + adapter; `_config.ts` + `config.ts`
@@ -173,7 +181,7 @@ const R = params.region ?? { x: 0, y: 0, w: 1, h: 1 };
 - 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.5 new component` scaffold) and edit.
+  `get_component_source`, paste it into a `npx -y cueframe@0.6 new component` scaffold) and edit.
 - 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/{skills → 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`.

package/dist/skills/cueframe-compose-loop/references/builtin-requests.json

@@ -0,0 +1,111 @@
+[
+  {
+    "name": "discover_builtin",
+    "tool": "list_catalog",
+    "arguments": {
+      "projection": "component-library",
+      "origin": "builtin",
+      "limit": 10,
+      "q": "Wheel"
+    }
+  },
+  {
+    "name": "resolve_exact_builtin",
+    "tool": "resolve_builtin_component",
+    "arguments": {
+      "collection": "curated-looks",
+      "id": "builtin:reference-component-wheel-full",
+      "revision": "2577db06c45171396e2f0199b2616877dfa25f3f68be0ec75fefea8e6a54755b"
+    }
+  },
+  {
+    "name": "read_insertion_witnesses",
+    "tool": "get_composition",
+    "arguments": {
+      "projectId": "observed-project",
+      "componentExecutionVersions": "3",
+      "includeDependencies": "true"
+    }
+  },
+  {
+    "name": "insert_exact_builtin",
+    "tool": "apply_template",
+    "arguments": {
+      "template": "builtin:reference-component-wheel-full",
+      "body": {
+        "projectId": "observed-project",
+        "documentSha256": "2577db06c45171396e2f0199b2616877dfa25f3f68be0ec75fefea8e6a54755b",
+        "insert": {
+          "startTime": 3,
+          "idPrefix": "wheel-insertion-1"
+        },
+        "expectedRevision": 1,
+        "commandId": "insert-wheel-1",
+        "values": {},
+        "media": {
+          "image1": {
+            "sample": true
+          },
+          "image2": {
+            "sample": true
+          },
+          "image3": {
+            "sample": true
+          },
+          "image4": {
+            "sample": true
+          },
+          "image5": {
+            "sample": true
+          },
+          "image6": {
+            "sample": true
+          },
+          "image7": {
+            "sample": true
+          },
+          "image8": {
+            "sample": true
+          }
+        },
+        "componentExecutionVersions": [
+          3
+        ],
+        "expectedBrandIdentity": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      }
+    }
+  },
+  {
+    "name": "wait_for_score",
+    "tool": "wait_job",
+    "arguments": {
+      "kind": "verify",
+      "id": "returned-job-id"
+    }
+  },
+  {
+    "name": "render_inserted_wheel",
+    "tool": "create_render",
+    "arguments": {
+      "projectId": "observed-project",
+      "body": {
+        "compositionId": "observed-composition",
+        "format": {
+          "aspectRatio": "16:9",
+          "fps": 30,
+          "resolution": "fhd"
+        },
+        "intent": "final"
+      }
+    }
+  },
+  {
+    "name": "wait_for_render",
+    "tool": "wait_job",
+    "arguments": {
+      "kind": "render",
+      "id": "returned-render-id",
+      "projectId": "observed-project"
+    }
+  }
+]

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

@@ -0,0 +1,53 @@
+---
+name: cueframe-connect
+description: Use when CueFrame is not connected yet, the user asks how to connect or authenticate CueFrame, or another CueFrame skill is about to call a tool and needs the one-time setup path for Claude Code, Claude, ChatGPT, Cursor, Codex, VS Code, Windsurf, Zed, Antigravity CLI, Copilot CLI, or an x402 wallet.
+---
+
+# Connect CueFrame
+
+## 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).
+
+First inspect available CueFrame tools and their current project context. If the requested work is supported by an existing connection, use it without installing again. Preserve the user's chosen local or hosted lane. Local-only desktop work needs no hosted registration; desktop connection instructions are at https://docs.cueframe.ai. This public plugin connects to the hosted product at `https://api.cueframe.ai/v1/mcp`.
+
+When a required capability is missing, explain the limitation and the supported alternative. Setup is warranted only when requested or necessary for an authorized tool action. Do not silently install across clients, launch authentication, switch projects or upload local content. For CLI setup, select the intended client using its supported flags rather than wiring every detected host. Resume the original task after setup.
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — a browser
+  opens and the user clicks **Allow**. No API key.
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
+  `https://api.cueframe.ai/v1/mcp`.
+- **Other agents (Cursor, Codex, VS Code, Windsurf, Zed, Antigravity CLI, Copilot CLI, …):**
+  use `npx -y cueframe@0.6 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
+  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up or API key; priced calls settle
+  per call in USDC over x402 from the agent's wallet.
+
+Do not ask the user to configure a model provider for CueFrame. This connection exposes CueFrame's
+tools; the host agent keeps using its already-selected CueFrame Gateway, BYOK, or local model.
+
+## Confirm the capabilities needed for the task
+
+Connected is not the same as working, and finding out at the first *paid* call is the expensive
+way. Use available read-only discovery for the selected lane:
+
+1. **Discover the surface.** List the tools your host now exposes. You should see the compose loop
+   (`new_composition`, `apply_composition`, `validate_composition`, `create_render`) alongside
+   discovery reads (`list_catalog`, `list_media`, `get_account`). There are also resources
+   (`cueframe://scene-shot` for 3D product shots) and workflow prompts — a flat tool list is not
+   the whole surface.
+2. **For hosted work, smoke-call `get_account` before spending.** It takes no arguments, costs nothing, and answers the questions
+   worth knowing before you spend: which org the key is bound to, the plan, per-feature
+   entitlements and — the one that matters — `balance`, not `included`. CueFrame is credit-funded,
+   so rendering, generation, preview stills, the judge and the Director all draw on ONE shared
+   wallet. A successful `get_account` proves that read is authorized; check the specific capability and current quote separately. Local tools without metered hosted work do not need this hosted call.
+
+If a later call fails on scope, the error names the exact missing permission (for example
+`billing:read`, which `get_usage` needs and a creative-only key will not have). Explain the missing permission and use an authorized setup path; do not broaden credentials automatically.

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

@@ -5,6 +5,14 @@ description: Use when turning a screen recording (with cursor/click events) into
 
 # CueFrame — Product Video recipe
 
+## 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).
+
 A **use-case recipe**, not new framework surface. CueFrame's engine only knows
 primitives (`upload` → `composition put` → `render`, the `reframe` viewport, the
 overlay/effect primitives). This skill is the *judgment* on top: how to turn a
@@ -13,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.5 …` commands
+`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.6 …` commands
 written out below are the same operations for a terminal or CI job with no MCP
 host; see the `cueframe-cli` skill.
 
@@ -56,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.5 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+`npx -y cueframe@0.6 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")
@@ -94,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.5 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+`npx -y cueframe@0.6 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.5 schema composition`, and the way to know a draft is correct is
-`npx -y cueframe@0.5 composition validate -b @composition.json` — it runs the same
+`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
 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.5 upload` ids). Conventions that keep them valid:
+real `npx -y cueframe@0.6 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`
@@ -290,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.5 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.
+  `npx -y cueframe@0.6 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.

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

@@ -5,6 +5,14 @@ description: Author a CueFrame 3D world-object shot as canonical SceneShotSpecV2
 
 # CueFrame scene shots
 
+## 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 `scene.add` and `scene.update` through `apply_composition`. Author the scene JSON; CueFrame owns the generated wrapper, preparation, resource admission, previews, and export.
 
 Before authoring, read `cueframe://scene-shot`. It serves the canonical generated `SceneShotSpecV2` schema, exact operation contracts, supported brand tokens, refusal rules, and a copyable nested slab-and-page recipe. Do not infer fields from an older example.