cueframe 0.9.2 → 0.11.0

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

@@ -19,6 +19,14 @@ brief/rubric for a local correction; check the affected behavior and relevant re
 of restarting the new-film method below. A diagnostic or preview-only request does not require
 a final export or a whole-film judge pass. Explicit user scope takes precedence over craft defaults.
 
+## Learned taste: the org's saved style preferences
+
+Before composing for an org, read its learned taste: `get_profile` returns it as `taste`, and Eve recalls it into every turn. It is advice, never instruction. Precedence, highest first: the current request, the brief, the project, the brand kit, exclusions and registered critics, then learned taste. When learned taste conflicts with any of those, follow the higher one and say which preference you set aside; never resolve a conflict silently.
+
+Save a preference only when the user states a durable one: a revise comment, a correction in chat, or an explicit "remember this". Never save one-off brief content, facts about footage, approval notes or anything secret. Every save names its source (the job, checkpoint or chat, plus the date). Save with your runtime's taste tool (Eve: `taste__remember`; MCP: `remember_taste`; HTTP: `POST /v1/profile/taste`).
+
+Tell the user every time you save or forget: "Added to your profile: <preference>. Say undo to remove it." Undo forgets that entry (`taste__forget`, `forget_taste`, or `DELETE /v1/profile/taste/{id}`). When the user says not to learn from this job, save nothing for the rest of it. A refusal (the entry is too long, the org's taste is full, or the owner turned learned taste off) is final: tell the user, and do not retry or shorten the preference silently.
+
 ## Plan and author to the request
 
 Use `cueframe-storyboard` only when new work lacks structure. For an existing title correction, retain the approved brief and edit the title directly; no whole-film rubric, paid judge or final export is required.
@@ -295,7 +303,7 @@ Each playbook is an illustrative format default; explicit intent and scope gover
 | CTA + date | 40–45s | Exact action + launch date. Logo last. | ≤12 |
 
 **Frameworks:** 3-act teaser (Tease → Reveal → CTA) or StoryBrand SB7 (customer is hero, you are guide). One pain or one wow — not five diluted features.
-**Reach for:** `import_media` a real demo capture or founder clip · `list_catalog` → the `product-launch-trailer` and `cinematic-title` scenes (use `cinematic-title` for a wordmark where the brief calls for it) · `color-grade` for the hero look · date + CTA on the final held frame.
+**Reach for:** `import_media` a real demo capture or founder clip · `list_catalog` with `projection:"component-library", origin:"builtin"` to discover a maintained preset or recipe that fits the footage; resolve its exact scoped identity before `apply_template` · an authored card or native component for the closing wordmark, date and CTA on the final held frame.
 **Anti-patterns:** opening on a logo animation; stacking five features; narrating specs; a fabricated/rounded stat; a mocked terminal standing in for a real screen.
 **Quality bar:** the first frame survives with zero text on it. If your open is a gradient with the product name, you've already lost.
 
@@ -328,7 +336,7 @@ Each playbook is an illustrative format default; explicit intent and scope gover
 
 **Frameworks:** Hook → Problem → Solution → Proof → CTA. Decide the CTA first, script it last; write for the ear.
 **A fully animated explainer is a FIRST-CLASS grounded format**, not a fallback for missing footage. An explainer built on authored diagrams of the *actual* mechanism (its real pipeline, the real data) is grounded — the grounding is that each visual depicts THIS thing specifically, not a decorative loop. Reach for it deliberately, not as a consolation for "no footage."
-**Reach for:** an authored `card` clip (your own HTML/typography, animated in its CSS or with `clip.setKeyframes`) to anchor an abstract mechanism with a real diagram — process/algorithm/data viz, not cinematic footage · `lower-third` for term labels · one idea per beat · when using real footage, narrate to the detected transcript timing.
+**Reach for:** an authored `card` clip (your own HTML/typography, animated in its CSS or with `clip.setKeyframes`) to anchor an abstract mechanism with a real diagram — process/algorithm/data viz, not cinematic footage · an authored card for term labels · one idea per beat · when using real footage, narrate to the detected transcript timing.
 **Anti-patterns:** a wall of narration over stock gradient loops with no visual keyed to the words (the generic-filler tell — a purposeful diagram of the real mechanism is the opposite); explaining features before establishing the problem; using `generate_media` text-to-video to fake a "product" that doesn't match the real UI (it hallucinates specifics).
 **Quality bar:** every beat has a visual keyed to what's being said — grounded and specific to this content, not decoration; the hook lands in 3s.
 
@@ -344,7 +352,7 @@ Each playbook is an illustrative format default; explicit intent and scope gover
 | CTA | 110–120s | One action: start free / book / docs. |
 
 **Frameworks:** Problem → Product-in-action → Outcome, wrapped in one completed task, not a feature tour. ~2 min is a good ceiling; chapter beyond that.
-**Reach for:** `import_media` a REAL screen recording (captured by the user, or by an external screen-capture client such as a headed Playwright walkthrough recorded to MP4 — CueFrame does not screen-record) · reframe punch-in to the active UI element each step (`focus:{mode:"point",x,y}` on the click target, or a `face` focus for a founder inset) — the single biggest amateur→pro delta in demos, because the click target is ~30px in a 3840px 4K frame and nobody sees it unzoomed (**see `cueframe-product-video`** for the full click-point→reframe-segment auto-zoom tiling + PiP recipe) · a `lower-third` label per step.
+**Reach for:** `import_media` a REAL screen recording (captured by the user, or by an external screen-capture client such as a headed Playwright walkthrough recorded to MP4 — CueFrame does not screen-record) · reframe punch-in to the active UI element each step (`focus:{mode:"point",x,y}` on the click target, or a `face` focus for a founder inset) — the single biggest amateur→pro delta in demos, because the click target is ~30px in a 3840px 4K frame and nobody sees it unzoomed (**see `cueframe-product-video`** for the full click-point→reframe-segment auto-zoom tiling + PiP recipe) · an authored step-label card.
 **Anti-patterns:** the cardinal demo sin — a mocked/fake terminal or static UI card instead of the real app; showing the full 4K screen unzoomed; narrating every menu.
 **Quality bar:** every UI/terminal on screen is a real capture; the actual action is visibly punched-in, not lost in a wide frame.
 
@@ -360,7 +368,7 @@ Each playbook is an illustrative format default; explicit intent and scope gover
 | Action | 68–75s | One CTA. |
 
 **Frameworks:** PAS (Problem → Agitate → Solution) or AIDA. Framing: eyes on the upper-third line, small headroom, subject looks into the lens; break every ~5–8s of pure talking head with a cutaway.
-**Reach for:** THE canonical CueFrame job. `get_media_context` for faces + transcript → reframe `focus:{mode:"active-speaker"}` for a solo speaker, `{mode:"all-faces"}` to hold a two-shot, or `{mode:"face",faceId,shotScale:"close"}` to punch in on emphasis → transcript-timed `captions` with a legibility plate (`setCaptionStyle` `emphasisPlate`, `position:"bottom"`) → a text overlay at `zPlane:"behind-subject"` when you want a title/word to sit *behind* the head (the signature look; render bakes the person matte) → a `lower-third` for name/title, shown once → `color-grade`. Zero generation needed.
+**Reach for:** THE canonical CueFrame job. `get_media_context` for faces + transcript → reframe `focus:{mode:"active-speaker"}` for a solo speaker, `{mode:"all-faces"}` to hold a two-shot, or `{mode:"face",faceId,shotScale:"close"}` to punch in on emphasis → transcript-timed `captions` with a legibility plate (`setCaptionStyle` `emphasisPlate`, `position:"bottom"`) → a text overlay at `zPlane:"behind-subject"` when you want a title/word to sit *behind* the head (the signature look; render bakes the person matte) → an authored card or owned native component for name/title, shown once; use the selected component’s documented color inputs. Zero generation needed.
 **Anti-patterns:** a static wide talking head running 30s uncut (reads as a raw webcam upload); captions slapped over the chin with no plate; head dead-center or too much headroom; missing the lower-third identity.
 **Quality bar:** a face is on screen within 3s; the person framed is the person speaking; captions never cover the mouth or eyes.
 
@@ -374,17 +382,17 @@ Each playbook is an illustrative format default; explicit intent and scope gover
 | Know where subject + speech are | `get_media_context` → face boxes per frame (with `faceId`) + transcript. If faces are not detected, `prepare_media(kind:"subjectTrack", intent:{startSec,endSec})` → poll `get_media_facts` for the same SOURCE window until ready. |
 | Keep the speaker framed / punch-in | `setCropIntents` op (the PREFERRED authoring path) or inline `reframe.segments` on a `clip.add` source. Each segment needs `startSec`/`endSec`/`focus`/`zoom`; **segments must TILE the clip** (an uncovered span → `reframe_coverage_gap` at validate). `focus.mode`: `frame-center` \| `point{x,y}` \| `face{faceId, shotScale?: close\|standard\|wide}` \| `all-faces` \| `active-speaker`. `zoom<1` punches in, `=1` full frame, `>1` rejected (min 0.1). Times in **seconds**. |
 | Captions that track real speech | `composition.captions.segments[].words[]` = `{text, startMs, endMs, emphasis?, annotate?: circle\|underline}` — word times in **milliseconds**. Author the words directly with the `setCaptions` op (segments wholesale — how a generated-VO film gets its word-synced spine without a source transcript); style via `setCaptionStyle`: `position` (top\|center\|bottom), `entrance` (fade\|word-pop\|stagger-up), `emphasisPlate` + plate colors for legibility. Captions default to front; set top-level `composition.captions.zPlane:"behind-subject"` only when the user wants the whole caption layer behind the speaker. It resolves person cutouts for every overlapping source window and degrades visibly to front where the legibility gate refuses the effect. |
-| Text behind the speaker's head | An `overlay` clip (a title/label primitive) with `zPlane:"behind-subject"`. This is the focused hero treatment; caption-layer depth is a separate whole-layer choice. Before preview/judgment, `prepare_media(kind:"matte", intent:{startSec,endSec})` for the overlapping clip's SOURCE trim and poll `get_media_facts` until ready. Render also resolves the person cutout on miss. |
-| Name someone / label a step | `lower-third` scene from `list_catalog` |
-| Title / closing wordmark | `cinematic-title` scene (closing, not opening) |
-| Grade the look | `color-grade` scene/effect |
+| Text behind the speaker's head | An `overlay` clip using the built-in `heroText` primitive with `zPlane:"behind-subject"`. This is the focused hero treatment; caption-layer depth is a separate whole-layer choice. Before preview/judgment, `prepare_media(kind:"matte", intent:{startSec,endSec})` for the overlapping clip's SOURCE trim and poll `get_media_facts` until ready. Render also resolves the person cutout on miss. |
+| Name someone / label a step | An authored `card` or owned native component with the intended name, typography and placement. |
+| Title / closing wordmark | An authored `card` or owned native component for the closing wordmark, held long enough to read. |
+| Set a graphic's palette | The selected component's documented color inputs, or an authored treatment in its complete native source. |
 | Anchor an abstract mechanism | An authored `card` clip animated in its CSS or with `clip.setKeyframes` (diagrams of the real mechanism — NOT cinematic; a first-class grounded path) |
 | 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` (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 |
+| Discover what to build with | `list_catalog` with `projection:"component-library", origin:"builtin"` discovers maintained preset/recipe cards. Preserve each card's complete identity and resolve its exact collection, id and revision with `resolve_builtin_component` before `apply_template`; retain the returned `documentSha256` and source pins. Page with `limit` and the returned cursor. The default catalog and `cueframe://component/{id}` describe the one primitive (`heroText`) and org-installed components. |
+| Own / fork a custom graphic | Discover a definition with `list_catalog` projection `component-library`; `get_component_source` with its exact `componentId`, `sourceVersionId` and `builtinCollection`, then `create_component` / `update_component` with the complete native version-4 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 card or native component laid out with CSS flex/grid (fixed tracks for content-sized cells, `fr` for the rest), animated from the frame. 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 |
+| Seed + edit the timeline | `apply_composition` (atomic batch ops; `dry_run:true` to check; every committing batch needs `if_match` from `get_composition`, or it is refused 428; on a 409, read `get_composition` again and rebuild the batch before retrying, never resend it with the 409's `currentEtag`) — 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. |
 | Shape-check (NOT quality) | `validate_composition` → `{ valid, errors[] }` (`unknown_primitive`, `invalid_primitive_params`, `clip_source_track_mismatch`, `reframe_coverage_gap`, …); does **not** check trim bounds or image-on-video-track (those fail at save/render) |
 | Look at real pixels | `preview_frame` at timestamps → PNG stills → LOOK |

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.9 install`.
+  ship via `npx -y cueframe@0.11 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.9 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.11 describe --json`.
 
-**Run it as `npx -y cueframe@0.9 …` — every command in this skill is written that way, and
+**Run it as `npx -y cueframe@0.11 …` — 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.9 install` wires the MCP server and drops these skills, but npx
+there: `npx -y cueframe@0.11 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.9 schema composition` (prints
+examples below alone. The live contract is `npx -y cueframe@0.11 schema composition` (prints
 the real wire schema the server enforces); confirm any draft with
-`npx -y cueframe@0.9 composition validate -b @file.json` BEFORE you render. Validation is
+`npx -y cueframe@0.11 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,39 +70,49 @@ 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.9 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
+npx -y cueframe@0.11 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
 
 # 2. Create a project (sets aspect/format).
-npx -y cueframe@0.9 project create -n "promo" -a 9:16 --json   # → projectId
+npx -y cueframe@0.11 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.9 schema composition                                 # → live wire schema
-npx -y cueframe@0.9 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
-npx -y cueframe@0.9 composition put <projectId> -b @composition.json   # ETag auto
+npx -y cueframe@0.11 schema composition                                 # → live wire schema
+npx -y cueframe@0.11 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
+npx -y cueframe@0.11 composition get <projectId> --json                  # → etag (not found = no composition yet)
+npx -y cueframe@0.11 composition put <projectId> -b @composition.json --if-match <etag>
+#    --if-match is required: a save made since your `get` fails with 409 stale_etag
+#    instead of being overwritten. Re-`get`, re-apply your edit, retry. Use --create
+#    only for the first composition of a project (refused 409 if one exists).
 
 # 4. Render the saved composition to MP4. SSE-watches + downloads when done.
-npx -y cueframe@0.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
 # → render_queued → render_progress* → render_complete
 #
 # `render` takes ONLY a projectId and renders the SAVED composition (tracks +
-# captions). A clip suggestion is NOT required. Same project → same MP4 (idempotent).
+# captions). A clip suggestion is NOT required. Re-running the same command on an
+# unchanged composition replays the same render (the Idempotency-Key hashes the
+# project, the composition ETag and the request: --aspect/--fps/--resolution/
+# --priority/--intent); editing the composition or changing a flag starts a new one.
+# Without --aspect it renders the composition's own format. --aspect must match the
+# composition's aspect (a new aspect is a `derive_composition`, not a render flag);
+# pass it with --resolution hd|fhd|4k to change only the output resolution.
 # Captions: render reads composition.captions — put caption words there to caption
 # 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.9 render watch <renderId> -p <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 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.9 schema composition` (the live wire schema) — run it when a field is
-unclear, and `npx -y cueframe@0.9 composition validate -b @file.json` to check a draft.
+`npx -y cueframe@0.11 schema composition` (the live wire schema) — run it when a field is
+unclear, and `npx -y cueframe@0.11 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:
+`composition put` takes the **bare** `Composition` object (no wrapper; the CLI PUTs
+the `@file` verbatim with your `--if-match` ETag). Minimal valid shape:
 
 ```json
 {
@@ -166,18 +176,18 @@ the composition yourself (above).
 
 ```bash
 # 1. Upload + chain the AI clip pass.
-npx -y cueframe@0.9 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
-# (or run it explicitly: npx -y cueframe@0.9 analyze <mediaItemId> --wait --json)
+npx -y cueframe@0.11 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
+# (or run it explicitly: npx -y cueframe@0.11 analyze <mediaItemId> --wait --json)
 
 # 2. List clip suggestions (publicId sug_…, title, startMs/endMs, score).
-npx -y cueframe@0.9 clips <mediaItemId> --json
+npx -y cueframe@0.11 clips <mediaItemId> --json
 
 # 3. Create a project AND author its composition from the chosen suggestion.
-npx -y cueframe@0.9 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
-#   (or, on an existing project: npx -y cueframe@0.9 composition from-suggestion <projectId> -s <sug_…>)
+npx -y cueframe@0.11 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
+#   (or, on an existing project: npx -y cueframe@0.11 composition from-suggestion <projectId> -s <sug_…>)
 
 # 4. Render — same framework verb as above.
-npx -y cueframe@0.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
 ```
 
 Both flows converge on `composition put` → `render`; the on-ramp just authors the
@@ -185,59 +195,61 @@ composition from a suggestion instead of you hand-writing it.
 
 Pipe `--json` output through `jq -c 'select(.event=="…")'` to grab specific lifecycle events.
 
-## Component authoring — fork a built-in primitive or scaffold your own
+## Component authoring: scaffold your own
 
-Own the motion-graphics components you render (shadcn-style): fork a built-in CueFrame
-primitive as editable source, customize it, and render it on CueFrame — or scaffold a blank
-one. The source lives in your repo under version control; CueFrame bakes it to a transparent
-video and composites it (the shared renderer never runs your code).
+Own the motion-graphics components you render (shadcn-style): scaffold a native component as
+editable source, customize it, and render it on CueFrame. The source lives in your repo under
+version control; CueFrame bakes it to a transparent video and composites it (the shared
+renderer never runs your code). The CLI does not fork built-ins: the maintained builtin
+presets and recipes are placed as they are (list them with `list_catalog`
+projection `component-library`).
 
 ```bash
 # 1. Scaffold a workspace (writes cueframe.json + cueframe/components/). Idempotent.
-npx -y cueframe@0.9 init --json
+npx -y cueframe@0.11 init --json
 
 # 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
-npx -y cueframe@0.9 new component my-badge --category ui-blocks --json
+npx -y cueframe@0.11 new component my-badge --category ui-blocks --json
 
 # The scaffold is a native (version 4) source: template.html + definition.json, with its
-# manifest in cueframe.json. Built-in forks copy the exact template, definition and manifest.
+# manifest in cueframe.json.
 
 # 3. Edit cueframe/components/<id>/template.html (one HyperFrames sub-composition ending in
 #    __cfScene.mount(...)) and definition.json (inputs, defaults, timing, capabilities).
 
 # 4. Publish to CueFrame so it can render (the server admits the source or names the rule it breaks).
-npx -y cueframe@0.9 push my-badge --json            # one component
-npx -y cueframe@0.9 sync --json                      # every component in the workspace
+npx -y cueframe@0.11 push my-badge --json            # one component
+npx -y cueframe@0.11 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.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
 ```
 
 ## Quick reference
 
 | Need to… | Command |
 |---|---|
-| See every command + flags | `npx -y cueframe@0.9 describe --json` |
-| Install/refresh managed skills | `npx -y cueframe@0.9 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
-| List projects | `npx -y cueframe@0.9 list -n 50` |
-| List your media | `npx -y cueframe@0.9 clips` (no mediaId arg) |
-| Discover the live composition schema | `npx -y cueframe@0.9 schema composition` |
-| Validate a draft (no save, no render) | `npx -y cueframe@0.9 composition validate -b @plan.json` |
-| Read composition + ETag | `npx -y cueframe@0.9 composition get <projectId> --json` |
-| Write composition | `npx -y cueframe@0.9 composition put <projectId> -b @plan.json` (ETag auto) |
-| Export to Final Cut | `npx -y cueframe@0.9 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
-| Export to Premiere | `npx -y cueframe@0.9 export premiere <projectId> -s <sug> --wait -o cut.zip` |
-| Anything not wrapped | `npx -y cueframe@0.9 api GET /v1/...  -i` (escape hatch, like `gh api`) |
-| Validate a composition without mutating | `npx -y cueframe@0.9 composition validate -b @plan.json` |
+| See every command + flags | `npx -y cueframe@0.11 describe --json` |
+| Install/refresh managed skills | `npx -y cueframe@0.11 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
+| List projects | `npx -y cueframe@0.11 list -n 50` |
+| List your media | `npx -y cueframe@0.11 clips` (no mediaId arg) |
+| Discover the live composition schema | `npx -y cueframe@0.11 schema composition` |
+| Validate a draft (no save, no render) | `npx -y cueframe@0.11 composition validate -b @plan.json` |
+| Read composition + ETag | `npx -y cueframe@0.11 composition get <projectId> --json` |
+| Write composition | `npx -y cueframe@0.11 composition put <projectId> -b @plan.json --if-match <etag>` (`--create` for the first composition) |
+| Export to Final Cut | `npx -y cueframe@0.11 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
+| Export to Premiere | `npx -y cueframe@0.11 export premiere <projectId> -s <sug> --wait -o cut.zip` |
+| Anything not wrapped | `npx -y cueframe@0.11 api GET /v1/...  -i` (escape hatch, like `gh api`) |
+| Validate a composition without mutating | `npx -y cueframe@0.11 composition validate -b @plan.json` |
 
 ## Auth
 
 Commands run against production. Authenticate once:
 
-- `npx -y cueframe@0.9 login` — OAuth device flow (laptops).
-- `npx -y cueframe@0.9 auth <cf_live_… key>` — save a static API key (CI / headless).
+- `npx -y cueframe@0.11 login` — OAuth device flow (laptops).
+- `npx -y cueframe@0.11 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.
 
@@ -255,11 +267,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.9 api METHOD /v1/...` — same auth, same JSON pipeline. |
-| Polling for render completion with a sleep loop | `npx -y cueframe@0.9 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.11 api METHOD /v1/...` — same auth, same JSON pipeline. |
+| Polling for render completion with a sleep loop | `npx -y cueframe@0.11 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.9 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). |
+| Hand-editing the composition without an ETag | `composition put` refuses without `--if-match <etag>` from the `composition get` your edit started from. Don't fetch a fresh ETag right before the put: that overwrites anyone who saved in between. `--create` is only for a project's first composition; there is no unconditional overwrite. |
+| Calling `npx -y cueframe@0.11 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 using complete versioned source snapshots. 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 parallax look", "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)
@@ -80,14 +80,14 @@ Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edi
 template locally, push to render.
 
 ```bash
-npx -y cueframe@0.9 init --json                       # scaffold cueframe.json + cueframe/components/
-npx -y cueframe@0.9 new component my-badge --category ui-blocks --json   # scaffold a component in the workspace
+npx -y cueframe@0.11 init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe@0.11 new component my-badge --category ui-blocks --json   # scaffold a component in the workspace
 #   New scaffolds contain template.html and definition.json (native source, version 4).
 # …edit cueframe/components/<id>/template.html and definition.json in your editor…
-npx -y cueframe@0.9 push my-badge --json              # send the native source; the server admits it
-#   or: npx -y cueframe@0.9 sync --json               # push every component in the workspace
+npx -y cueframe@0.11 push my-badge --json              # send the native source; the server admits it
+#   or: npx -y cueframe@0.11 sync --json               # push every component in the workspace
 # reference the component id in your composition, then render:
-npx -y cueframe@0.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
 ```
 
 The CLI writes `template.html` and `definition.json` (input schema, defaults, timing and
@@ -116,9 +116,9 @@ properties, then the manifest's slots).
 
 Edit the draft with `update_component_preview` (exact-text `{oldText, newText, replaceAll?}`
 edits). Check exact frames with `render_component_preview_frame`, and inspect playback for motion.
-`commit_component_preview` publishes the checked source to the library and pins the clip, with a
-fresh ETag. `read_component` and `edit_component` read and edit the library directly. Close the
-preview when finished.
+`commit_component_preview` publishes the checked source to the library and pins the clip, and
+returns the project's new ETag. `read_component` and `edit_component` read and edit the library
+directly. Close the preview when finished.
 
 Media slots are image or video, declared in `component_manifest.assets` and bound to project
 media ids in `component_assets`. The template passes them to `MediaTileScene` as

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

@@ -56,7 +56,10 @@ before authoring custom source.
 Build/modify the working composition with the op vocabulary —
 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
+current revision and brand witnesses before editing. Pass that revision as `if_match`
+on every committing call. A 409 means someone saved after your read: call `get_composition`
+again, rebuild your ops against what it returns, and send them with its revision. Never resend
+the same ops with the 409's `currentEtag`; that overwrites a save you have not read. 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.

package/dist/skills/cueframe-compose-loop/references/preview-workflow.md

@@ -16,7 +16,7 @@ Read the current tool contracts and project context. Do not infer a hosted sessi
 
 Hosted calls use `projectId` and the request shape declared by the live tool. `preview_component` returns a job ID: wait with `kind:"preview"`. `preview_frame` uses `kind:"preview_frame"`. `preview_clip` returns a render job: wait with `kind:"render"`, even though it is a preview. Reuse the returned job ID; do not submit duplicate jobs while waiting. Hosted evidence jobs do not require opening or warming a compose session.
 
-The local component preview compiles replacement source revisions; it is not a promise of browser HMR or zero compilation work. `commit_component_preview` commits the inspected revision with a fresh project ETag. An isolated preview does not itself edit the saved timeline. Close the preview when finished if that tool is available.
+The local component preview compiles replacement source revisions; it is not a promise of browser HMR or zero compilation work. `commit_component_preview` commits the inspected revision and returns the project's new ETag. An isolated preview does not itself edit the saved timeline. Close the preview when finished if that tool is available.
 
 ## Bound the work without changing the animation
 

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.9 install --help` to select the intended client; preserve existing configuration and avoid duplicate installs.
+  use `npx -y cueframe@0.11 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
@@ -42,7 +42,8 @@ way. Use available read-only discovery for the selected lane:
    (`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.
+   the whole surface. Every tool, whether it reads or writes, and the surfaces that serve it
+   are in the generated [tool reference](references/tools.md).
 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,

package/dist/skills/cueframe-connect/references/tools.md

@@ -0,0 +1,145 @@
+# CueFrame tool reference
+
+Generated from the @cueframe/mcp 0.11.0 catalog (commit a3fb82e59). Do not edit it by hand.
+
+Every CueFrame tool by its catalog name. A host may show it with a connection prefix (`mcp__cueframe__get_account`, `cueframe-read__get_account`); the name after the last `__` is the catalog name. **read** tools change no state, though some are metered; **write** tools change state, and a composition write takes the revision it edits.
+
+Hosted surfaces: `api` is the MCP server at `https://api.cueframe.ai/v1/mcp`; `editor` and `compose` are the hosted Director's editor and compose sessions. Desktop surfaces: `director` is the desktop app's agent, `plan` its planning mode, `external` an outside MCP client connected to the desktop app, and `cli` the Director running as a CLI agent such as Claude Code. A tool is callable only on the surfaces listed for it; list your host's tools for what this connection serves.
+
+| Tool | Access | Hosted | Desktop |
+| --- | --- | --- | --- |
+| `analyze_transcript` | read | editor, compose | director, plan, external, cli |
+| `apply_composition` | write | api, editor, compose | director, external, cli |
+| `apply_template` | write | api, editor | director, external, cli |
+| `cancel_compose` | write | api | - |
+| `cancel_export` | write | api | - |
+| `cancel_job` | write | api | - |
+| `cancel_render` | write | api | - |
+| `check_template` | write | - | external |
+| `close_component_preview` | write | - | director, plan, external, cli |
+| `close_project` | write | - | external |
+| `commit_component_preview` | write | - | director, external, cli |
+| `compose` | write | api | - |
+| `consult` | write | api | - |
+| `create_brand_kit` | write | api | - |
+| `create_brief` | write | api | - |
+| `create_checkout` | write | api | - |
+| `create_component` | write | api, editor, compose | director, external, cli |
+| `create_project` | write | api | external |
+| `create_render` | write | api, editor, compose | director, external, cli |
+| `create_upload` | write | api | - |
+| `create_webhook` | write | api | - |
+| `delete_brief` | write | api | - |
+| `delete_composition` | write | api | - |
+| `delete_critic` | write | api | - |
+| `delete_media` | write | api | - |
+| `delete_project` | write | api | external |
+| `delete_webhook` | write | api | - |
+| `derive_composition` | write | api, editor, compose | director, external, cli |
+| `describe_composition_ops` | read | api, editor, compose | director, plan, external, cli |
+| `download_media` | read | api | - |
+| `edit_component` | write | - | director, external, cli |
+| `editorial_apply` | write | api, editor, compose | director, cli |
+| `editorial_begin` | write | - | director, cli |
+| `editorial_create_brief` | write | api, editor, compose | - |
+| `editorial_create_run` | write | api, editor, compose | - |
+| `editorial_findings_append` | write | api, editor, compose | director, cli |
+| `editorial_findings_list` | read | api, editor, compose | director, plan, cli |
+| `editorial_get_run` | read | api, editor, compose | director, plan, cli |
+| `editorial_inspect_audio` | write | api, editor, compose | director, cli |
+| `editorial_inspect_source` | write | api, editor, compose | director, cli |
+| `editorial_inspect_transcript` | write | api, editor, compose | director, cli |
+| `editorial_integrate` | write | api, editor, compose | director, cli |
+| `editorial_list_briefs` | read | api, editor, compose | director, plan, cli |
+| `editorial_list_evidence` | read | api, editor, compose | director, plan, cli |
+| `editorial_list_runs` | read | api, editor, compose | director, plan, cli |
+| `editorial_run_source` | read | api, editor, compose | - |
+| `editorial_sample_motion` | write | api, editor, compose | director, cli |
+| `export_project` | write | - | external |
+| `extract_brand_kit` | write | api | - |
+| `finalize_upload` | write | api | - |
+| `forget_taste` | write | api, editor, compose | director, external, cli |
+| `generate_media` | write | api, editor, compose | director, external, cli |
+| `get_account` | read | api, editor, compose | director, plan, external, cli |
+| `get_app_state` | read | - | director, plan, external, cli |
+| `get_brief` | read | api | - |
+| `get_checkpoint` | read | api | - |
+| `get_component_source` | read | api, editor, compose | director, plan, external, cli |
+| `get_composition` | read | api, editor, compose | director, plan, external, cli |
+| `get_context` | read | editor, compose | director, plan, external, cli |
+| `get_director_state` | read | - | external |
+| `get_editor_state` | read | - | director, plan, external, cli |
+| `get_import_status` | read | - | director, plan, external, cli |
+| `get_media_context` | read | api, editor, compose | director, plan, external, cli |
+| `get_media_facts` | read | api | director, plan, external, cli |
+| `get_profile` | read | api, editor, compose | director, plan, external, cli |
+| `get_project_settings` | read | - | external |
+| `get_render` | read | api | - |
+| `get_scene_contract` | read | - | director, plan, external, cli |
+| `get_template` | read | api, editor | director, plan, external, cli |
+| `get_transcript` | read | api, editor, compose | director, plan, external, cli |
+| `get_usage` | read | api, editor, compose | director, plan, external, cli |
+| `import_local_media` | write | - | director, external, cli |
+| `import_media` | write | api, editor, compose | director, external, cli |
+| `import_resource` | write | api, editor, compose | director, external, cli |
+| `install_local_person_runtime` | write | - | director, external, cli |
+| `list_briefs` | read | api | - |
+| `list_catalog` | read | api, editor, compose | director, plan, external, cli |
+| `list_checkpoints` | read | api | - |
+| `list_component_packages` | read | - | external |
+| `list_compositions` | read | api | - |
+| `list_critics` | read | api | - |
+| `list_media` | read | api, editor, compose | director, plan, external, cli |
+| `list_plans` | read | api | - |
+| `list_projects` | read | api | external |
+| `list_render_fonts` | read | api | - |
+| `list_taste` | read | api, editor, compose | director, plan, external, cli |
+| `list_templates` | read | api, editor | - |
+| `new_composition` | write | api, editor, compose | director, external, cli |
+| `open_component_preview` | write | - | director, plan, external, cli |
+| `open_project` | write | - | external |
+| `play_pause` | write | - | director, plan, external, cli |
+| `prepare_component_library_previews` | write | - | external |
+| `prepare_component_media` | read | - | external |
+| `prepare_media` | write | api | director, external, cli |
+| `preview_card` | read | api, editor, compose | - |
+| `preview_clip` | write | api | - |
+| `preview_component` | read | api | - |
+| `preview_frame` | read | api, editor, compose | director, plan, external, cli |
+| `propose_plan` | write | - | director, plan, cli |
+| `publish_component` | write | - | external |
+| `read_component` | read | - | director, plan, external, cli |
+| `redo_edit` | write | - | external |
+| `refresh_render_url` | write | api | - |
+| `register_critic` | write | api | - |
+| `remember_taste` | write | api, editor, compose | director, external, cli |
+| `rename_project` | write | - | external |
+| `render_component_preview_frame` | read | - | director, plan, external, cli |
+| `repin_component` | write | api | director, external, cli |
+| `resolve_builtin_component` | read | api | - |
+| `resume` | write | api | - |
+| `retry_render` | write | api | - |
+| `save_as_template` | write | - | director, external, cli |
+| `score_composition` | write | api, editor, compose | director, external, cli |
+| `search_fonts` | read | api, editor, compose | director, plan, external, cli |
+| `search_library` | read | editor, compose | director, plan, external, cli |
+| `search_resources` | read | api, editor, compose | director, plan, external, cli |
+| `seek` | write | - | director, plan, external, cli |
+| `select_candidate` | write | api | - |
+| `send_director_prompt` | write | - | external |
+| `set_playback_rate` | write | - | director, plan, external, cli |
+| `start_template` | write | api, editor | - |
+| `submit_plan` | write | - | director, plan, cli |
+| `suggest_briefs` | write | api | - |
+| `undo_edit` | write | - | external |
+| `update_brief` | write | api | - |
+| `update_component` | write | api | - |
+| `update_component_preview` | write | - | director, plan, external, cli |
+| `update_project` | write | api | - |
+| `update_project_settings` | write | - | external |
+| `update_webhook` | write | api | - |
+| `validate_composition` | read | api, editor, compose | director, plan, external, cli |
+| `verify_webhook` | write | api | - |
+| `view_asset` | read | - | director, plan, external, cli |
+| `view_style_reference` | read | compose | - |
+| `wait_job` | read | api, editor, compose | director, plan, external, cli |

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.9 …` commands
+`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.11 …` 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,8 @@ 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.9 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+`npx -y cueframe@0.11 composition put <projectId> -b @composition.json --if-match <etag>`, with the
+ETag from `composition get` (`--create` for the project's first composition; 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")
@@ -101,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.9 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+`npx -y cueframe@0.11 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.9 schema composition`, and the way to know a draft is correct is
-`npx -y cueframe@0.9 composition validate -b @composition.json` — it runs the same
+`npx -y cueframe@0.11 schema composition`, and the way to know a draft is correct is
+`npx -y cueframe@0.11 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.9 upload` ids). Conventions that keep them valid:
+real `npx -y cueframe@0.11 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`
@@ -297,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.9 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.
+  `npx -y cueframe@0.11 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.