cueframe 0.9.4 → 0.11.3

package/dist/skills/cueframe-component-authoring/references/native-component-workflows.md

@@ -0,0 +1,98 @@
+# Native component workflows
+
+Choose the path exposed by the current host. Request schemas and the Component Contract own exact fields; these examples explain source and placement identity.
+
+## Path A — MCP agent (no filesystem; source lives server-side)
+
+Use the live tool schema for request envelopes; hosted write fields are normally under `body`. When `get_composition` advertises `clipIds` and `response`, use selected clip IDs with `response:"full"` to retrieve the complete sources you need without pulling every large HTML body. Treat a projection as a partial read, never a replacement composition. Compact apply receipts retain the saved revision and warnings; reread relevant state before a dependent edit. Desktop surfaces may expose different fields.
+
+1. **Discover and read a built-in:** call `list_catalog` with
+   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
+   Select the intended card and preserve its complete scoped source reference. Call
+   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
+   `builtinCollection` (its scope collection).
+   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
+   retry another scope or an unpinned head.
+2. **Author/own it:** edit the complete native `sourceSnapshot`; use your chosen owned ID
+   consistently in its `componentId` and the request. Send it as `body.source` to
+   `create_component`, with required metadata. Preserve its definition, capability
+   declarations, manifest and source format. For an existing component, keep its ID and
+   use `update_component` with the complete source. Do not send an old pin as the identity
+   of changed source: saving produces a new immutable source version.
+3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` queues a durable
+   preview and returns a `jobId`; call `wait_job(kind:"preview")`. The typed terminal result is a
+   verified artifact produced by the same bundle contract used by final render. A failed
+   `component_does_not_compile` job carries the compiler error — read it, fix via `update_component`
+   (same id, in place), and preview again.
+   **Adopt the source in the requested scope:** publication leaves existing placements pinned
+   to their previous versions; `placementsPinnedToPrevious` reports those uses. Source publication
+   plus placement adoption is not an atomic source-write operation. Read the current composition
+   and `describe_composition_ops`, then use the admitted `component.repin-v3` operation with complete
+   before/after execution references and the observed exact composition revision. Its historical
+   name also covers supported version-4 execution references. Preserve unrelated placements and
+   parameters. An unavailable placement capability is a refusal, not permission to bypass source
+   admission or substitute an unpinned head. Reinspect the adopted source in the saved timeline.
+   Set preview duration deliberately: `durationInFrames` is not a trim window and can retime
+   duration-dependent motion. Preserve production timing; inspect the live tool's request shape.
+4. **Check integration:** add it as a `{kind:'component', componentId, props:{},
+   execution:{version:4,componentId,sourceVersionId,params,seed,assets}, placement:{version:3,kind:'clip'}}` clip
+   (`apply_composition`), then inspect saved-composition stills or a scoped `preview_clip` for
+   placement and motion. Use `create_render` → `wait_job kind:"render"` when delivering a
+   finished MP4, not per tweak.
+
+## Path B — CLI / coding agent (customer-owned source under git)
+
+Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit the native
+template locally, push to render.
+
+```bash
+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.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.11 render <projectId> -o ./out.mp4 --json
+```
+
+The CLI writes `template.html` and `definition.json` (input schema, defaults, timing and
+capabilities). `cueframe.json` → `components.<id>` holds the version-4 `manifest` and the catalog
+`name` and `category`, which `push` requires; it refuses a component missing either.
+`push`/`sync` send these as one native `source`, checked against the contract's source schema;
+the server's admission (template lint, determinism, declarations) refuses with a named rule.
+For a builtin fork, copy **all three parts** from the selected `sourceSnapshot`: template,
+definition and manifest. A workspace component that still has a version-3 `index.tsx` is
+refused as `component_source_retired` before any API call; author it again as a native template. To preview before
+a full render, push it and use the appropriate component preview loop.
+
+## Path C — Director editing a local desktop project (project-embedded source)
+
+When `get_context` reports the project lane as local, motion does not need an account or an org
+component. Components here are native (source version 4) too:
+- **New component:** open a draft with `open_component_preview`, passing `template`,
+  `component_manifest` (`{version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets,
+  graphics, alphaPolicy}`) and `component_definition`.
+- **Existing component:** pass `component_id` instead, to start from the clip's pinned version or
+  the library version.
+
+The draft is admitted in full: template lint, determinism and the variable declaration.
+`data-composition-variables` must equal the definition's projection (its scalar inputSchema
+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, 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
+`streams: { hero: { asset: assets.hero } }`. Declare `alphaPolicy` explicitly:
+`requires-transparency` for overlays, `allows-opaque` for full-frame plates.
+
+Every frame must be a pure function of `render.frame`, params and `render.seed`. Timers, `Date`,
+network, imports, other globals and CSS animation are refused at admission. The timeline and final
+export render the exact committed version. Use `create_component` only for a reusable org-catalog
+component on a reachable cloud lane.
+

package/dist/skills/cueframe-component-authoring/references/native-source-contract.md

@@ -0,0 +1,54 @@
+# Native version-4 source contract
+
+Read this when authoring or changing a custom native component. Scene-shot JSON is a different contract served by `cueframe://scene-shot` or desktop `get_scene_contract`; it does not describe a custom component source. Live schemas and named admission errors govern supported fields.
+
+Create and update components with a complete `source` object: `{version:4, componentId, template, manifest, definition}`. TSX (version 3) sources are retired: writing one is refused as `component_source_retired`. The definition declares input schema, defaults, timing, brand/media bindings and placement capabilities. The manifest is `{version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets, graphics, alphaPolicy}`: `assets` declares the media slots (only `image` and `video` slots), `graphics.api` is `webgl2` (or `webgl`), and `alphaPolicy` is `requires-transparency` or `allows-opaque`.
+
+The `template` is one sub-composition. Every source is admitted before it is stored or rendered, and a refusal names the broken rule:
+- `<template>` holds one root `<div id="root" data-composition-id="<componentId>" data-width="1920" data-height="1080" data-no-timeline data-composition-variables='…'>` containing one empty `<div data-cf-scene></div>` (and any static DOM of your own beside it), and one classic inline `<script>`.
+- The script finds its root with `document.getElementById('root')`. The runtime scopes that lookup to each placed instance; a global `[data-composition-id]` selector is refused, because a component placed twice would find no root.
+- `data-composition-variables` is the definition's projection: each scalar `inputSchema` property in schema order, then each manifest slot. `number`/`integer` → `{"id","type":"number","label","default","min","max"}` (min/max from minimum/maximum, omitted when absent); a property with `enum` → `{"type":"enum","default":"<as string>","options":[{"value","label"}]}`; `boolean` → `"boolean"`; a string whose `pattern` admits exactly `#RRGGBB` → `"color"`; any other string → `"string"`; an image slot → `{"id","type":"image","label":"<id>","default":""}`; a video slot → the same with `"type":"string"`. `label` is the property's `title`, else its id; `default` is `definition.defaults[id]`, else the schema default. Any difference is refused as `component_api_mismatch`.
+- The script ends with exactly one `__cfScene.mount({ root: document.getElementById('root'), component: Name, variables: __hyperframes.getVariables() })`. `Name({ params, assets, render, durationInFrames })` returns `h(MediaTileScene, { streams, tiles, camera, fog, background })`, taken from `const { h, MediaTileScene, three } = __cfScene`: a description, not React. `render` is `{ frame, fps, width, height, seed }`. `params` holds only the keys the placement's `execution.params` sets, so read every param with its default as a fallback.
+- Pass a declared slot as `streams: { hero: { asset: assets.hero } }` and place it with `tiles: [{ stream: 'hero', x, y, width, height }]` (pixels; x/y are the tile centre's offset from the frame centre, y down). Tiles also take `z`, `rotation`, `rotationX`, `rotationY` (degrees), `opacity`, `crop` and `renderOrder`; the camera takes `x`, `y`, `z`, `zoom` and `perspective`. Video streams take `trimBeforeFrames`, `trimAfterFrames`, `playbackRate` and `loop`. Audio belongs on composition audio tracks.
+- The template lays out at its declared `data-width` × `data-height`, and the host scales that whole box to the rendered size: DOM beside the scene keeps its place and proportion at every size. The scene draws at the rendered size (`render.width` × `render.height`). A component without media passes `streams: {}` and no tiles; its scene presents its `background`.
+- Every frame is a pure function of `render.frame`, `params` and `render.seed`. The script reads only its own declarations, `__cfScene`, `__hyperframes`, `document` and JavaScript built-ins such as `Math` and `JSON`. Timers, `Date`, `requestAnimationFrame`, `fetch`, `eval`, imports, `window` and other globals are refused (`component_v4_nondeterministic`, `component_import_denied`). The template has no `<img>`, `<video>`, `<link>` or `<iframe>`, no external or `data:` URL, and no CSS `transition`, `animation` or `@keyframes`. The template linter runs in sub-composition mode, and its errors refuse the source (`component_v4_lint_failed`).
+
+Example: one image swinging flat over the clip. Its definition and manifest:
+
+```json
+{
+  "definition": {
+    "inputSchema": { "type": "object", "additionalProperties": false, "properties": {
+      "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#101014" },
+      "tilt": { "type": "number", "minimum": 0, "maximum": 60, "default": 35 }
+    } },
+    "defaults": {}, "brandBindings": [], "timing": { "defaultDuration": { "frames": 90, "fps": 30 } }, "capabilities": [{ "kind": "clip" }]
+  },
+  "manifest": { "version": 4, "runtime": "hyperframes", "hfContract": 1, "kind": "scene",
+    "assets": { "hero": { "kind": "image", "required": true } },
+    "graphics": { "api": "webgl2", "required": true, "accelerationPreference": "hardware-preferred" }, "alphaPolicy": "allows-opaque" }
+}
+```
+
+Its template, with `componentId` `swing-hero`:
+
+```html
+<template><div id="root" data-composition-id="swing-hero" data-width="1920" data-height="1080" data-no-timeline data-composition-variables='[{"id":"background","type":"color","label":"background","default":"#101014"},{"id":"tilt","type":"number","label":"tilt","default":35,"min":0,"max":60},{"id":"hero","type":"image","label":"hero","default":""}]'><div data-cf-scene></div></div><script>
+const { h, MediaTileScene } = __cfScene;
+function SwingHero({ params, assets, render, durationInFrames }) {
+  const t = Math.min(1, render.frame / Math.max(1, durationInFrames - 1));
+  const ease = 1 - Math.pow(1 - t, 3);
+  const tilt = Number.isFinite(params.tilt) ? params.tilt : 35;
+  return h(MediaTileScene, {
+    streams: { hero: { asset: assets.hero } },
+    tiles: [{ stream: 'hero', x: 0, y: 0, width: 1280, height: 720, rotationY: tilt * (1 - ease) }],
+    camera: { x: 0, y: 0, z: 0, zoom: 1, perspective: 1200 },
+    background: params.background ?? '#101014',
+  });
+}
+__cfScene.mount({ root: document.getElementById('root'), component: SwingHero, variables: __hyperframes.getVariables() });
+</script></template>
+```
+
+Place a component as a `{kind:'component', componentId, props:{}, execution:{version:4, componentId, sourceVersionId, params, seed, assets:{hero:'<mediaId>'}}, placement:{version:3, kind:'clip'}}` clip. Bind each slot to a project media id in `execution.assets`; a slot never travels in `params`.
+

package/dist/skills/cueframe-component-authoring/references/parented-device-card.json

@@ -0,0 +1,13 @@
+{
+  "kind": "card",
+  "html": "<style>\n.cf-mounted-demo{position:relative;width:100%;height:100%;overflow:hidden;background:#e9edf5;font-family:Arial,sans-serif;color:#162033;--settle:clamp(0,calc(var(--cf-t)/var(--cf-settleSec)),1);--pose:calc(1 - (1 - var(--settle))*(1 - var(--settle))*(1 - var(--settle)));--approach:clamp(0,calc((var(--cf-t) - var(--cf-contactSec) + var(--cf-approachSec))/var(--cf-approachSec)),1);--response:clamp(0,calc((var(--cf-t) - var(--cf-contactSec))/var(--cf-responseSec)),1)}\n.cf-mounted-demo .stage{position:absolute;left:50%;top:50%;width:380px;height:720px;transform:translate(-50%,-50%);perspective:1400px}\n.cf-mounted-demo .phone{position:absolute;inset:0;border:10px solid #172032;border-radius:52px;background:#172032;box-sizing:border-box;box-shadow:18px 30px 45px #15263a30;transform:translateY(calc((1 - var(--pose))*120px)) rotateY(calc((1 - var(--pose))*var(--cf-tiltDeg)*1deg)) rotateZ(calc((1 - var(--pose))*-5deg))}\n.cf-mounted-demo .screen{position:absolute;inset:0;border-radius:40px;overflow:hidden;background:#fbfcff}\n.cf-mounted-demo .top{position:absolute;left:28px;right:28px;top:38px;font-size:24px;font-weight:700}\n.cf-mounted-demo .card{position:absolute;left:28px;right:28px;top:110px;height:182px;border-radius:18px;background:var(--cf-accent);color:white;box-shadow:0 9px 18px #16203328}\n.cf-mounted-demo .card:before{content:\"NORTH\";position:absolute;left:22px;top:24px;font-size:21px;font-weight:700;letter-spacing:3px}\n.cf-mounted-demo .holder:after{content:var(--cf-holder)}\n.cf-mounted-demo .holder{position:absolute;left:22px;bottom:24px;font-size:18px;letter-spacing:2px}\n.cf-mounted-demo .label{position:absolute;top:330px;left:28px;font-size:20px}\n.cf-mounted-demo .control{position:absolute;left:100px;top:400px;width:160px;height:70px;border:2px solid #b5bfd1;border-radius:18px;box-sizing:border-box;background:#eef2f9;display:grid;place-items:center;font-size:22px;font-weight:700}\n.cf-mounted-demo .frozen{position:absolute;inset:0;border-radius:16px;background:var(--cf-accent);color:white;display:grid;place-items:center;opacity:var(--response)}\n.cf-mounted-demo .pointer{position:absolute;left:180px;top:435px;width:36px;height:48px;background:#162033;clip-path:polygon(0 0,100% 65%,58% 68%,43% 100%);filter:drop-shadow(1px 3px 2px #15263a99);transform:translate(calc((1 - var(--approach))*95px),calc((1 - var(--approach))*80px));transform-origin:0 0}\n.cf-mounted-demo .status{position:absolute;left:28px;right:28px;top:530px;font-size:20px;line-height:1.4;opacity:var(--response)}\n</style><div class=\"cf-mounted-demo\"><div class=\"stage\"><div class=\"phone\"><div class=\"screen\"><div class=\"top\">Your card</div><div class=\"card\"><div class=\"holder\"></div></div><div class=\"label\">Card controls</div><div class=\"control\">Freeze<div class=\"frozen\">Frozen</div></div><div class=\"pointer\"></div><div class=\"status\">Payments are paused.<br>Your card is still here.</div></div></div></div></div>",
+  "tokens": {
+    "accent": "#4265d5",
+    "holder": "\"MAYA\"",
+    "settleSec": "1.0",
+    "tiltDeg": "28",
+    "contactSec": "2.0",
+    "approachSec": "0.65",
+    "responseSec": "0.2"
+  }
+}

package/dist/skills/cueframe-component-authoring/references/parented-motion.md

@@ -0,0 +1,25 @@
+# Parented motion with an editable event clock
+
+Use this example to keep mounted UI on one projected plane and make a cursor action retimeable. It is original CueFrame sample artwork under this repository's Apache-2.0 license, with no external assets. It is not a Cardly reproduction or a real app capture. For physical lighting, depth intersections or a moving 3D camera, use the scene-shot contract instead.
+
+[Complete card source](parented-device-card.json) is a `kind:"card"` source object. Put it on an overlay clip at full-frame 1920×1080, 30 fps, duration 4 seconds; use the live `clip.add` schema for the surrounding operation. It includes an opaque full-duration background, so it is a complete scene plate. When using it over other content, remove that background intentionally rather than hoping it is transparent.
+
+The `.phone` applies the pose once. Its `.screen` clips the card, text, control and pointer as mounted children. Their coordinates stay in phone space. No child independently counter-rotates to approximate the parent's pose. The pointer's top-left tip arrives at the control center `(180,435)` in screen coordinates.
+
+The host supplies `--cf-t` in clip-local seconds. Tokens `settleSec`, `contactSec`, `approachSec` and `responseSec` determine arrival, pointer contact and response; the status and control use the same response phase. The sample keeps its readable state after settling and after contact. Changing `contactSec` shifts the approach and response together. Positive travel/response durations are required by its CSS divisions; keep contact after the approach and allow a readable hold before the clip ends.
+
+`holder` is a CSS string token, so its value includes quote characters. Preserve it when editing the pose or timing. `accent` and `tiltDeg` control visible style and geometry. They are ordinary card tokens; built-in clock keys are not authored tokens.
+
+For the initial proof, inspect the pose in travel, the settled plane, the frame before contact, the contact frame, the response and the last frame. Also inspect a motion preview across arrival and contact. After changing `contactSec`, check that the cursor and response move together, the holder remains, and the full scene still covers its duration. These are tests of this recipe's mechanism; use the reference's actual landmarks for a real film.
+
+This CSS uses a fixed design-space phone inside a full-size card. Recompose for a different aspect/size instead of assuming this sample is responsive. Static layout fidelity, sampled motion and actual playback are distinct evidence. The validation record belongs with the produced preview artifact, not inside this reusable skill.
+
+## Fit and reuse the same object
+
+For a reference-led device, compare the outer silhouette, screen corners and inset, then the mounted card and its typography. A correct bounding width can still hide the wrong perspective. Parenting keeps transforms together, but a child rendered on a different apparent plane can still contradict the device. Inspect a moving pose as well as the settled one before reusing the object across scenes.
+
+Use a small set of editable properties for likely corrections: screen inset, card size, text scale, internal gap, pose and event times. A CSS font-size is not a measurement of visible cap height or text width. Calibrate those relationships from the rendered glyphs and preserve intentional copy adaptations. Do not turn every measured pixel into a global design token.
+
+Publish a reusable native source once, then pass its exact version and relevant parameters to coauthors. Editing its source creates a new version; placed clips remain pinned to the old version. Explicitly adopt the fitted version in the intended placements through the available admitted composition operation, and inspect those uses. Source publication and placement adoption are separate operations; an isolated preview alone does not prove the timeline changed.
+
+When several authors work on one project, existing clip guards cover the whole clip and its structural dependencies, not independent CSS fields. A shared source adoption or dependent timing revision needs current composition state. If another author or the user changed the target, reread and reconcile the intended edit; preserve their copy, timing and unrelated placements rather than replacing a stale document with a fresh token.

package/dist/skills/cueframe-component-authoring/references/retired-projects.md

@@ -0,0 +1,26 @@
+# Retired project sources
+
+## Upgrading an old project
+
+`get_composition` returns `needsUpgrade` only when clips from before the native cutover remain:
+`[{clipId, kind, componentId?, sourceVersionId?, primitiveId?, successorComponentId?,
+successorSourceVersionId?}]`. Saves and renders refuse those clips. A retired component is
+refused with `component_source_retired`, and a retired
+primitive with `render_unknown_primitive`. Upgrade only the listed clips. Keep every other clip,
+timing, track and brand-kit binding as it is.
+
+- **Any entry with a `successorSourceVersionId`:** call `repin_component` with its clip ids. It
+  moves them to the native successor and keeps their saved inputs.
+- **`v3-component` with no successor** (a custom pre-cutover component): read its source, params,
+  timing and placement, and author a native replacement with `create_component` as a version-4
+  template following the server instructions' Component Contract.
+- **`unpinned-component`:** the clip carries a `retired` record (what was stored before the cutover), with its
+  props preserved. Re-author it from those props the same way.
+- **`retired-primitive`:** rebuild what `primitiveId` drew from the clip's params, as a card or
+  a native component.
+
+For each replacement, use `apply_composition` to replace only that clip at the same start,
+duration, track and placement, pinned to the new exact `sourceVersionId`. Map the old params
+onto the new inputs; do not invent new content. Verify each clip with `preview_frame` at a time
+inside its window and confirm `needsUpgrade` is gone. Only then render (`create_render`).
+

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

@@ -1,128 +1,30 @@
 ---
 name: cueframe-compose-loop
-description: Use when an AI agent should DRIVE CueFrame to a high-quality clip itself — author a composition, look at rendered frames, score it with CueFrame's judge, fix the weakest thing, and repeat until it's good — e.g. "turn this source into a polished 9:16 clip", "compose and self-correct until it scores well". This is the agent-driven convergence loop over the CueFrame primitives in the `cueframe-cli` skill.
+description: "Use when previewing, reviewing or revising a CueFrame composition, including a scoped correction, reference comparison or final-delivery check. Also use when an agent should drive CueFrame to a high-quality clip itself: author, look at rendered frames, score with the judge, fix the weakest thing and repeat, over the primitives in the `cueframe-cli` skill. Triggers on \"turn this source into a polished 9:16 clip\" or \"compose and self-correct until it scores well\"."
 ---
 
-# CueFrame — Compose convergence loop
+# CueFrame preview and revision
 
-## Scope and capability policy
+Use the [project and capability policy](../composing-video/references/project-policy.md). This skill owns evidence, revision scope and delivery; craft and format skills describe what to look for.
 
-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 the current saved composition and relevant source before changing it. Reuse the approved brief or supplied reference. A local correction does not restart planning. For exact builtin preset/recipe insertion, use [builtin insertion](references/builtin-insertion.md).
 
-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.
+## Inspect the behavior that matters
 
-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).
+Read [preview workflow](references/preview-workflow.md) to choose the supported hosted or local surface. Match evidence to the question: stills for typography/geometry, motion for paths and handoffs, audio inspection for the mix. Requested timestamps, artifact URLs and successful jobs are not proof that their content was observed.
 
-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
-the primitives with the `cueframe-cli` skill; this tells you *how to converge*.
+Locate a finding in the film: when it happens, what is visible or audible, what the brief/reference requires, and which relationship needs to change. For reconstruction, compare matching source/output landmarks and the interval between them. If a requested revision deliberately changed timing, compare corresponding events rather than pretending they still share timestamps.
 
-Before choosing a preview or export, read [preview-workflow.md](references/preview-workflow.md).
-It owns hosted/local routing, bounded motion evidence, and the distinction between a small edit
-and final delivery. For a minor revision, keep the approved brief and inspect the changed behavior
-plus relevant regressions; do not restart the full planning/judging loop below.
+Fix the highest-impact cause you can explain. A layout failure may need a grid change, a position adjustment, a different parent transform or a new shot choice. Do not force every correction into one technique. Use targeted atomic operations against the observed revision and retain concurrent edits. Every committing batch needs the required `if_match` from the current read. After a conflict, reread the changed state and rebuild the intended change; never resend old operations with the error's `currentEtag`.
 
-## The loop
+## Recheck the affected scene
 
-```
-get_context  →  author  →  scoped preview (look)  →  judge if useful
-                   ↑                                      │
-                   └──────── fix the WORST criterion ──────┘  → stop → render
-```
+A timing change can affect more than the edited clip: backing plates, screen masks, linked controls, captions, sound and neighboring handoffs. Inspect the changed window with its entrance/exit context. If the ending must be preserved, verify the complete final scene through its last frame, not just an unchanged logo object. Check saved values as well as actual output.
 
-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.
+`score_composition` can supply broader editorial, spatial, brand and caption critique when useful and within budget. Its fixed caption criterion can penalize intentionally uncaptioned work; do not add captions solely to improve a score. These instructions do not change judge behavior. A failed brief requirement remains a failure regardless of a numerical score.
 
-## 0. Context — relevant project and source first
+Continue while evidence suggests a useful correction within the task's time/cost scope. If progress stalls, change the diagnosed cause or report the remaining gap; repeated scores alone are not progress. A scoped edit can finish with verified previews. For a finished-video request, export the saved revision and inspect the resulting artifact. Report the output, what was actually reviewed, and unresolved limitations.
 
-`GET /v1/media/:id/context` (`cueframe_api_getMediaContext`) returns what you need
-to author well for a source:
+## Detailed guidance
 
-- **faces** — the subject roster per source window: `faceId` (face-0 = largest/
-  primary speaker), normalized `bbox`, `speakingShare` (0–1). Use these to aim
-  reframe/crop intents at the right subject. `faces.status: "not_detected"` means
-  no detection has run yet — author without face-targeted reframe, or trigger a
-  pass first; never invent face ids.
-- **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 —
-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.
-
-## 2. Preview — look at it
-
-Use the curated `preview_frame` MCP tool, or
-`POST /v1/projects/:id/preview-frame-jobs`, with the composition target and the
-timestamps you need to inspect. The operation returns `{ jobId }` immediately.
-Call `wait_job({ kind: "preview_frame", id: jobId })`, then view the image artifact
-URLs in the successful result. Look at the beats you're unsure about: a cut, an
-overlay entrance, or the hook. The stills are real render evidence, not continuous-motion proof.
-Use `preview_clip` for the affected composition window to judge cuts, entrances, camera movement,
-and audio timing; use `preview_component` or `preview_card` for isolated authoring checks.
-
-## 3. Score it
-
-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", id: jobId })`. CueFrame's judge samples
-the meaningful beats, renders them, and returns:
-
-```
-{ perCriterion: { editorial, spatial, brand, caption } each { score 0–10, critique },
-  composite,        // weighted overall
-  critique,         // worst-first, leads with the criterion to fix
-  beats }
-```
-
-The four criteria:
-
-| criterion | what it grades |
-|---|---|
-| **editorial** | does the framing/cut serve the stated intent (the hook, the point)? |
-| **spatial**   | subject framing — centered/tight enough, not lost in dead space, not occluded by captions |
-| **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.
-
-## 4. Fix the worst — then re-score
-
-Read `critique` — it names the lowest criterion first and says why. Fix **that one
-thing** (re-author the relevant ops), then score again. One criterion per pass:
-chasing all four at once thrashes. Example: editorial 4 "two subjects off-center
-vs centered intent" → tighten the reframe onto face-0 → re-score. A layout critique
-("cramped", "unbalanced", "text crowds the art") on a laid-out card or component is a
-change to its CSS grid tracks or flex basis. Re-author those; never nudge pixels (see
-`cueframe-component-authoring`).
-
-## 5. Stop — then render
-
-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.
-
-## Notes
-
-- **Whose tokens:** you run this loop on your own model/tokens; CueFrame bills the
-  infra (capture/render) + the judge. That's the point — you keep the orchestration.
-- **Don't re-derive the judge or beat sampling** — verify owns both. Your job is
-  author → read scores → fix worst → repeat.
-- **Budget the loop:** 3–5 scoring passes is plenty for most clips. If composite
-  won't climb, the limiter is usually the source or the intent, not more passes.
+[The convergence loop](references/convergence-loop.md) has the step-by-step author, preview, score, fix and stop procedure for an agent driving a clip to quality.

package/dist/skills/cueframe-compose-loop/references/convergence-loop.md

@@ -0,0 +1,128 @@
+# The convergence loop
+
+Defaults, examples and detail for this topic. The [skill](../SKILL.md) and the [project and capability policy](../../composing-video/references/project-policy.md) take precedence where they differ, and the current tool schemas are authoritative.
+
+## 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
+the primitives with the `cueframe-cli` skill; this tells you *how to converge*.
+
+Before choosing a preview or export, read [preview-workflow.md](preview-workflow.md).
+It owns hosted/local routing, bounded motion evidence, and the distinction between a small edit
+and final delivery. For a minor revision, keep the approved brief and inspect the changed behavior
+plus relevant regressions; do not restart the full planning/judging loop below.
+
+## The loop
+
+```
+get_media_context  →  author  →  scoped preview (look)  →  judge if useful
+                   ↑                                      │
+                   └──────── fix the WORST criterion ──────┘  → stop → render
+```
+
+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 — relevant project and source first
+
+`GET /v1/media/:id/context` (`get_media_context`) returns what you need
+to author well for a source:
+
+- **faces** — the subject roster per source window: `faceId` (face-0 = largest/
+  primary speaker), normalized `bbox`, `speakingShare` (0–1). Use these to aim
+  reframe/crop intents at the right subject. `faces.status: "not_detected"` means
+  no detection has run yet — author without face-targeted reframe, or trigger a
+  pass first; never invent face ids.
+- **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](builtin-insertion.md)
+before authoring custom source.
+
+## 1. Author
+
+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. 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_media_context in your reframe segments;
+time captions/overlays from the transcript word timings.
+
+## 2. Preview — look at it
+
+Use the curated `preview_frame` MCP tool, or
+`POST /v1/projects/:id/preview-frame-jobs`, with the composition target and the
+timestamps you need to inspect. The operation returns `{ jobId }` immediately.
+Call `wait_job({ kind: "preview_frame", id: jobId })`, then view the image artifact
+URLs in the successful result. Look at the beats you're unsure about: a cut, an
+overlay entrance, or the hook. The stills are real render evidence, not continuous-motion proof.
+Use `preview_clip` for the affected composition window to judge cuts, entrances, camera movement,
+and audio timing; use `preview_component` or `preview_card` for isolated authoring checks.
+
+## 3. Score it
+
+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", id: jobId })`. CueFrame's judge samples
+the meaningful beats, renders them, and returns:
+
+```
+{ perCriterion: { editorial, spatial, brand, caption } each { score 0–10, critique },
+  composite,        // weighted overall
+  critique,         // worst-first, leads with the criterion to fix
+  beats }
+```
+
+The four criteria:
+
+| criterion | what it grades |
+|---|---|
+| **editorial** | does the framing/cut serve the stated intent (the hook, the point)? |
+| **spatial**   | subject framing — centered/tight enough, not lost in dead space, not occluded by captions |
+| **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.
+
+## 4. Fix the worst — then re-score
+
+Read `critique` — it names the lowest criterion first and says why. Fix **that one
+thing** (re-author the relevant ops), then score again. One criterion per pass:
+chasing all four at once thrashes. Example: editorial 4 "two subjects off-center
+vs centered intent" → tighten the reframe onto face-0 → re-score. A layout critique
+("cramped", "unbalanced", "text crowds the art") on a laid-out card or component is a
+change to its CSS grid tracks or flex basis. Re-author those; never nudge pixels (see
+`cueframe-component-authoring`).
+
+## 5. Stop — then render
+
+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.
+
+## Notes
+
+- **Whose tokens:** you run this loop on your own model/tokens; CueFrame bills the
+  infra (capture/render) + the judge. That's the point — you keep the orchestration.
+- **Don't re-derive the judge or beat sampling** — verify owns both. Your job is
+  author → read scores → fix worst → repeat.
+- **Budget the loop:** 3–5 scoring passes is plenty for most clips. If composite
+  won't climb, the limiter is usually the source or the intent, not more passes.

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

@@ -16,21 +16,25 @@ 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
 
 - Use a component's existing params for supported changes; update its source in place only when necessary. Do not create a new component ID for each tweak.
 - `durationInFrames` sets the component's render duration; it is **not a generic trim window**. Shortening it can retime animations normalized over duration. Preserve production timing. Use a documented component-specific offset only if it preserves that timing, or use the saved composition's `preview_clip` window. `startFrame` is not a universal preview API parameter.
 - Preserve FPS when judging motion. Choose resolution for the question: a low-resolution motion preview may establish timing but not typography, glass edges, or final-resolution shader quality. Use appropriate stills for those details.
-- Batch related still timestamps. Build contact sheets from returned images for inspection; a grid is a presentation of sampled frames, not proof of continuous motion. Watch the critical window as well. Listen when the change affects sound.
+- Batch related still timestamps within the tool's delivery bounds. Check which image blocks actually arrived and their timestamp/identity; metadata for more frames does not establish their delivery. Request missing frames through the supported selector or another bounded preview. Repeating an unchanged completed job is not evidence of additional frames. A contact sheet shows sampled frames, not continuous playback. Inspect the critical motion window and listen when the change affects sound.
 - Scope output and compute are different: a short composition preview can still trigger preparation or an alpha bake on a cache miss. Inspect progress/receipts before diagnosing cost. Do not promise instant previews, cross-job cache hits, or that every requested still requires a full bake.
 
 ## Evidence and stopping
 
 Keep component source revision/hash, params, asset bindings, dimensions, FPS, requested frames/window, and returned artifact/job identity together. For hosted composition parity, inspect `previewed.source`, composition ID, and ETag where provided. Source can change without changing the composition ETag. Unchanged pixels outside an edit's visible frame range do not by themselves prove a stale cache.
 
-Compare affected frames and motion with the reference at matching timestamps. Keep isolated-component proof distinct from saved-composition proof and final-export proof. For a minor edit, stop once the requested behavior and relevant regressions are checked; report the preview and explicitly say if no new final export was made.
+Compare affected frames and motion with the reference at matching timestamps, or corresponding named events when a requested revision intentionally retimed them. For structural changes, inspect connected layers and the intervals on both sides of each affected boundary; preserve a complete ending, including its background and audio tail. Keep isolated-component proof distinct from saved-composition proof and final-export proof. For a minor edit, stop once the requested behavior and relevant regressions are checked; report the preview and explicitly say if no new final export was made.
+
+For precise reference matching, `compare_frames` can place a certified source frame beside an existing saved preview and return an unaligned overlay. Use full-resolution images for glyph bounds and spacing; request a common-coordinate crop for details. Read actual frame/source identities, color/display transforms and delivery status from the result. Derived comparison images are diagnostic evidence, not authored reconstruction layers. Reuse the candidate preview; comparing a different view does not require rendering it again.
+
+After a correction, capture the affected saved version and compare it with the same reference moment. Inspect the adjacent movement separately: doubled edges in an overlay can identify a displaced object, but they cannot explain its acceleration or establish that sound is synchronized. A former comparison remains evidence of the former source; it does not update when a component or composition changes.
 
 Use `score_composition` for broader editorial/brand review when useful and within budget. Do not require repeated whole-film judging to verify a known local correction. A judge score does not override a failed acceptance criterion or the user's visual feedback.
 

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

@@ -5,13 +5,7 @@ description: Use when CueFrame is not connected yet, the user asks how to connec
 
 # 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).
+Use the [project and capability policy](../composing-video/references/project-policy.md) for scope, current state and metered work.
 
 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`.
 
@@ -23,7 +17,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 +36,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,