cueframe 0.11.0 → 0.11.4

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

@@ -1,131 +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. 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.
-
-## 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

@@ -23,14 +23,18 @@ The local component preview compiles replacement source revisions; it is not a p
 - 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`.
 

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

@@ -1,6 +1,6 @@
 # CueFrame tool reference
 
-Generated from the @cueframe/mcp 0.11.0 catalog (commit a3fb82e59). Do not edit it by hand.
+Generated from the @cueframe/mcp 0.13.0 catalog (commit eb1b03358). 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.
 
@@ -15,10 +15,11 @@ Hosted surfaces: `api` is the MCP server at `https://api.cueframe.ai/v1/mcp`; `e
 | `cancel_export` | write | api | - |
 | `cancel_job` | write | api | - |
 | `cancel_render` | write | api | - |
-| `check_template` | write | - | external |
+| `check_template` | read | - | director, plan, external, cli |
 | `close_component_preview` | write | - | director, plan, external, cli |
 | `close_project` | write | - | external |
 | `commit_component_preview` | write | - | director, external, cli |
+| `compare_frames` | read | api, editor, compose | director, plan, external, cli |
 | `compose` | write | api | - |
 | `consult` | write | api | - |
 | `create_brand_kit` | write | api | - |
@@ -53,7 +54,7 @@ Hosted surfaces: `api` is the MCP server at `https://api.cueframe.ai/v1/mcp`; `e
 | `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_run_source` | read | api, editor, compose | director, plan, external, cli |
 | `editorial_sample_motion` | write | api, editor, compose | director, cli |
 | `export_project` | write | - | external |
 | `extract_brand_kit` | write | api | - |
@@ -92,9 +93,9 @@ Hosted surfaces: `api` is the MCP server at `https://api.cueframe.ai/v1/mcp`; `e
 | `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_render_fonts` | read | api | director, plan, external, cli |
 | `list_taste` | read | api, editor, compose | director, plan, external, cli |
-| `list_templates` | read | api, editor | - |
+| `list_templates` | read | api, editor | director, plan, external, cli |
 | `new_composition` | write | api, editor, compose | director, external, cli |
 | `open_component_preview` | write | - | director, plan, external, cli |
 | `open_project` | write | - | external |

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

@@ -5,13 +5,7 @@ description: Use when turning a screen recording (with cursor/click events) into
 
 # CueFrame — Product Video recipe
 
-## Scope and capability policy
-
-User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
-
-Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
-
-For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Use the [project and capability policy](../composing-video/references/project-policy.md) for scope, current state and metered work.
 
 A **use-case recipe**, not new framework surface. CueFrame's engine only knows
 primitives (`upload` → `composition put` → `render`, the `reframe` viewport, the

package/dist/skills/cueframe-reference-video/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: cueframe-reference-video
+description: Use when recreating a supplied video or matching its motion, camera, typography, transitions, visual identity or audiovisual timing in CueFrame.
+---
+
+# CueFrame reference-video reconstruction
+
+Use the [project and capability policy](../composing-video/references/project-policy.md) for scope, current state and metered work.
+
+For a reconstruction, the reference film and full-frame captures are analysis inputs, not finished reconstruction layers; source excerpts remain valid when the user requests an edit or remix.
+
+Treat the supplied film as the acceptance anchor. Reconstruct what it communicates and how its objects move; matching endpoint stills alone does not match a film. Preserve the requested duration, style and intentional holds. Typography, gradients and reconstructed interface artwork are valid when the reference calls for them; do not present reconstructed UI as a capture of a working product.
+
+## Inspect before choosing the technique
+
+Use the current runtime's advertised source and motion-inspection capabilities. An overview finds the phrases; denser samples around a transformation reveal its path, overlap, masking, occlusion and settling. Increase coverage where adjacent observations do not explain the motion. Distinguish a visible cut from an inferred continuous morph.
+
+Keep a concise [reference ledger](references/measurement-and-comparison.md) linking observed timing, geometry, type, materials and sound events to evidence. Measure relevant landmarks and projected dimensions before guessing easing or camera behavior. Record unknown assets, fonts and audio separately from observations.
+
+Eve may have no shell or local media access. Use delivered source/motion evidence through available tools; do not assume FFmpeg, downloads or local scripts can run. A capable local host can use FFprobe/FFmpeg for analysis, comparisons and decode checks. These are not substitute renderers for CueFrame. Report missing observation capabilities rather than claiming unseen motion or unheard sound.
+
+For a local file, `bash scripts/motion-grid.sh INPUT OUTPUT_DIR` creates overview/dense grids and TSV indices with actual source frame numbers and presentation timestamps. Optional `--start SEC --duration SEC` selects an interval relative to the first presented frame; `--overview-fps N --dense-fps N` controls sampling. Each requested instant selects the first source frame at or after it, without duplicate frames; read the recorded actual time rather than assuming the requested rate landed exactly. Use a fresh output directory. The script requires FFprobe/FFmpeg and is an optional local observation aid.
+
+## Author, compare and deliver
+
+Choose useful fidelity anchors and prove the difficult motion early through supported component or timeline previews. Use CueFrame tools for saved authoring, previews and rendering. Keep related motion and sound tied to the same timing decisions; preserve editable text and meaningful parameters. Native peers can help when separate authored work is useful, but continuity still needs integrated review.
+
+Compare actual output at the reference's timestamps and inspect the intervening motion. When available, use `compare_frames` on an identified source frame and saved preview artifact; its unaligned pair/overlay exposes layout drift without rendering the composition again. Read the [worked comparison](references/measurement-and-comparison.md) for geometry, intentional retiming and evidence limits. Fix located mismatches in scale, pose, direction, timing, readability or material before decorative polish. A score or successful compile cannot approve a failed reference requirement. Separate measured audio properties from listening and reused audio from new sound design.
+
+For a finished-film request, deliver an actual CueFrame-produced MP4, verify its format/decode and identify remaining fidelity gaps. Do not invent the user's verdict. For a narrow revision, retain approved work and use the scoped preview workflow in `cueframe-compose-loop`; a new full export is only needed for requested final delivery.

package/dist/skills/cueframe-reference-video/references/measurement-and-comparison.md

@@ -0,0 +1,45 @@
+# Reference ledger and matched-time comparison
+
+Keep observations, measurements and inferred implementation separate. A ledger can use ordinary shot notes; it does not require a new timeline or rigid production schema.
+
+| Note | Useful evidence |
+|---|---|
+| Purpose and identity | What this phrase communicates; recurring subject, type, palette, artwork and material cues |
+| Time | Source seconds/frames, meaningful arrival/hold/exit windows, source/output time mapping |
+| Geometry | Normalized positions and projected sizes, margins, two corners or edges of a moving subject |
+| Motion | Direction, changing displacement, acceleration/settling, rotation/depth cues, blur and opacity |
+| Handoff | What disappears first, what overlaps, which object carries the eye, actual cut versus inferred morph |
+| Sound | Observed cue/onset, rhythmic change or deliberate silence; whether heard or only measured |
+| Evidence and confidence | Source identity, sampled timestamps, image/motion/audio evidence, observed/measured/inferred/unknown |
+
+Start with broad coverage to find the important windows. Use denser samples for a fast handoff, a long camera move or text with a short reading window. Source-rate inspection is useful near impacts, replacements and direction changes. Sample only valid source times; an encoded audio tail is not extra video. If the tool samples or seeks approximately, retain that uncertainty rather than claiming frame-exact timing.
+
+For each difficult move, compare source and output at identical timestamps. Follow the same landmarks: projected width may match while pose, occlusion or velocity is wrong. Inspect before, during and after the transition, not just its landed state. Do not temporally warp the result to conceal drift. A visible replacement is not evidence of a continuous extraction, and cursor contact does not prove a selected or confirmed UI state.
+
+Use isolated authoring previews to establish technique, then persisted timeline previews to verify placement and interaction with other layers. After changing component source, verify its pinned source version and the output where the change should be visible; a composition ETag alone may not identify a changed referenced source.
+
+Record findings as `time/window · observed mismatch → intended correction · what stays`. Reinspect the affected move and adjacent handoffs. Structural feedback can change the story and require retiming dependent copy, camera, graphics and sound; preserve unrelated user edits against current shared state.
+
+A complete delivery can include a small set of fidelity anchors, critical motion comparisons, actual movie identity, asset/source provenance and unresolved differences. Audio signal measurements establish technical properties, not a listening verdict. Reusing the reference mix can isolate picture timing, but it does not demonstrate an authored score; reordering visuals may require reconsidering that mix.
+
+## Worked correction: title spacing and a list thumbnail
+
+In a 1920×1080, 30 fps reference study, the title at frame 117 had a 34px gap from its left word to a central mark and a 41px gap from that mark to the right word. The saved reproduction measured about 3px and 22px. Its type group was also narrower: 1021px against 1304px. These were visible glyph bounds in the output, not the HTML elements' CSS widths.
+
+Inspect the separate frames, then an unaligned 50% overlay. Establish outer group placement and cap height before adjusting the two internal gaps. Change the actual title/mark source, preserving approved copy and the timeline. The corrected saved preview measured about 35px and 39px, with a 1315px group width. Those measurements had approximately ±2–4px uncertainty. They establish a specific spacing improvement, not a font match or a whole-film fidelity percentage.
+
+At frame 180, a list thumbnail was 190px high against a 154px reference and had about 30px top inset against 48px. Its row pitch was already close. Reducing the thumbnail and recovering its inset corrected that relationship without rebuilding the outer panel or retiming the film. Use the same crop coordinates for both images so a shifted crop cannot hide a shifted object.
+
+The title's settled frame improved, but around frame 99 its moving carrier remained displaced by roughly 90px. The list entrance and exit also remained late. This is the useful counterexample: a well-fitted endpoint does not establish the correct path, rotation, overlap, acceleration or timing. Reinspect the affected entrance, hold and exit; use continuous playback for the final motion verdict.
+
+These observations come from CueFrame's Cardly reconstruction study. They are a worked diagnostic example, not default gaps, a required style or a reusable claim about every film. Keep the source reference separate from authored reconstruction layers.
+
+## Reading comparison evidence
+
+`compare_frames` compares already identified inputs. A source-frame operand may decode the certified representation; a candidate references an existing saved preview. Replaying a comparison or changing its crop does not mean a new composition render occurred. Read the delivered images and receipt rather than inferring delivery from URLs or metadata.
+
+Keep actual frame indices, rational FPS/timebase, requested versus sampled time, dimensions, source hashes and composition/source versions with the observation. Hosted render bookends can make the internal render frame differ from the composition frame. A normalized representation is not necessarily the original file's clock. Unknown color transforms, approximate seeks or missing frames constrain the conclusion.
+
+Use the raw pair and overlay at unchanged coordinates. A difference image can locate change but is easily dominated by backgrounds and materials; it is not an acceptance score. Automatic image registration can conceal displacement. Cropping is a view into the same coordinate space, not permission to independently fit the two images.
+
+For an intentional structural revision, record the source-to-output event correspondence and compare those events. Do not temporally warp the evidence or undo the user's changed timing merely to reduce image differences. After editing, compare a preview from the new saved source, then inspect connected motion and sound.

package/dist/skills/cueframe-reference-video/scripts/motion-grid.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+set -euo pipefail
+export LC_ALL=C
+
+usage() {
+  echo "usage: motion-grid.sh INPUT OUTPUT_DIR [--overview-fps N] [--dense-fps N] [--start SEC] [--duration SEC]" >&2
+  exit 2
+}
+
+[[ $# -ge 2 ]] || usage
+input=$1
+output_dir=$2
+shift 2
+overview_fps=1
+dense_fps=6
+start_sec=0
+duration_sec=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --overview-fps) [[ $# -ge 2 ]] || usage; overview_fps=$2; shift 2 ;;
+    --dense-fps) [[ $# -ge 2 ]] || usage; dense_fps=$2; shift 2 ;;
+    --start) [[ $# -ge 2 ]] || usage; start_sec=$2; shift 2 ;;
+    --duration) [[ $# -ge 2 ]] || usage; duration_sec=$2; shift 2 ;;
+    *) usage ;;
+  esac
+done
+awk -v a="$overview_fps" -v b="$dense_fps" -v s="$start_sec" -v d="$duration_sec" 'BEGIN {
+  number = "^[0-9]+([.][0-9]+)?$"
+  exit !(a ~ number && a > 0 && b ~ number && b > 0 && s ~ number && (d == "" || (d ~ number && d > 0)))
+}' || usage
+command -v ffmpeg >/dev/null || { echo "ffmpeg is required" >&2; exit 1; }
+command -v ffprobe >/dev/null || { echo "ffprobe is required" >&2; exit 1; }
+[[ -f "$input" ]] || { echo "input not found: $input" >&2; exit 1; }
+mkdir -p "$output_dir"
+for label in overview dense; do
+  [[ ! -e "$output_dir/${label}-index.tsv" && ! -e "$output_dir/${label}-001.jpg" ]] || {
+    echo "use a fresh output directory (existing $label grid)" >&2; exit 1;
+  }
+done
+work_dir=$(mktemp -d "${TMPDIR:-/tmp}/cueframe-motion-grid.XXXXXX")
+trap 'rm -rf "$work_dir"' EXIT
+
+ffprobe -v error \
+  -show_entries format=duration,format_name:stream=index,codec_name,codec_type,width,height,r_frame_rate,avg_frame_rate,time_base,start_time,sample_rate,channels \
+  -of json "$input" > "$output_dir/probe.json"
+# ffprobe emits frames in presentation order, matching FFmpeg select's n on
+# the first video stream. Keep their actual timestamps, including VFR timing.
+ffprobe -v error -select_streams v:0 -show_frames \
+  -show_entries frame=best_effort_timestamp,best_effort_timestamp_time \
+  -of compact "$input" > "$work_dir/frames.txt"
+awk -F '|' '
+  $1 == "frame" {
+    pts = ""; seconds = ""
+    for (i = 2; i <= NF; i++) {
+      split($i, field, "=")
+      if (field[1] == "best_effort_timestamp") pts = field[2]
+      if (field[1] == "best_effort_timestamp_time") seconds = field[2]
+    }
+    if (pts !~ /^-?[0-9]+$/ || seconds !~ /^-?[0-9]+([.][0-9]+)?$/) exit 1
+    if (n && seconds + 0 < previous) exit 1
+    printf "%d\t%s\t%s\n", n++, pts, seconds
+    previous = seconds + 0
+  }
+  END { if (!n) exit 1 }
+' "$work_dir/frames.txt" > "$work_dir/frames.tsv" || {
+  echo "source has missing or nonmonotonic presentation timestamps" >&2; exit 1;
+}
+ffmpeg -hide_banner -filters > "$work_dir/filters.txt" 2>/dev/null
+has_drawtext=0
+if grep -q ' drawtext ' "$work_dir/filters.txt"; then has_drawtext=1; fi
+
+make_grid() {
+  local label=$1 rate=$2 filter
+  # Select the first actual source frame at/after each requested instant, once.
+  # Start/duration are relative to the first presented frame; the end is exclusive.
+  awk -F '\t' -v rate="$rate" -v start="$start_sec" -v duration="$duration_sec" '
+    BEGIN { print "page\tcell\ttime_sec\tsource_frame\tsource_pts\tsource_pts_time_sec\ttarget_time_sec"; target = start }
+    NR == 1 { origin = $3 + 0 }
+    {
+      time = $3 - origin
+      if (duration != "" && time >= start + duration - 0.0000005) next
+      if (time + 0.0000005 < target) next
+      printf "%03d\t%02d\t%.6f\t%s\t%s\t%s\t%.6f\n", int(count / 16) + 1, count % 16 + 1, time, $1, $2, $3, target
+      count++
+      target = start + (int((time - start + 0.0000005) * rate) + 1) / rate
+    }
+    END { if (!count) exit 1 }
+  ' "$work_dir/frames.tsv" > "$work_dir/${label}-index.tsv" || {
+    echo "no source frames in the requested interval" >&2; return 1;
+  }
+  # FFmpeg recursively parses sums; balance them so long selections do not
+  # exhaust its expression depth while preserving the exact frame indices.
+  awk -F '\t' '
+    function selection(first, last, middle) {
+      if (first == last) return "eq(n\\," frames[first] ")"
+      middle = int((first + last) / 2)
+      return "(" selection(first, middle) "+" selection(middle + 1, last) ")"
+    }
+    NR > 1 { frames[++count] = $4 }
+    END { print selection(1, count) }
+  ' \
+    "$work_dir/${label}-index.tsv" > "$work_dir/selection.txt"
+  filter="select='$(cat "$work_dir/selection.txt")',scale=384:-2:flags=lanczos"
+  if [[ "$has_drawtext" -eq 1 ]]; then
+    filter="${filter},drawtext=fontcolor=white:fontsize=20:box=1:boxcolor=black@0.72:x=8:y=h-th-8:text='pts=%{pts\\:flt}'"
+  fi
+  filter="${filter},tile=4x4:padding=8:margin=8:color=0x111827"
+  # No seek/fps filter: neither source frame indices nor timestamps are relabeled.
+  ffmpeg -hide_banner -loglevel error -copyts -i "$input" -map 0:v:0 \
+    -vf "$filter" -fps_mode passthrough -q:v 2 \
+    "$output_dir/${label}-%03d.jpg"
+  cp "$work_dir/${label}-index.tsv" "$output_dir/${label}-index.tsv"
+}
+make_grid overview "$overview_fps"
+make_grid dense "$dense_fps"
+echo "wrote probe.json, grids and actual source-frame/PTS indices to $output_dir"

package/dist/skills/cueframe-scene-shot/SKILL.md

@@ -5,13 +5,7 @@ description: Author a CueFrame 3D world-object shot as canonical SceneShotSpecV2
 
 # CueFrame scene shots
 
-## Scope and capability policy
-
-User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
-
-Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
-
-For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Use the [project and capability policy](../composing-video/references/project-policy.md) for scope, current state and metered work.
 
 Use `scene.add` and `scene.update` through `apply_composition`. Author the scene JSON; CueFrame owns the generated wrapper, preparation, resource admission, previews, and export.
 
@@ -37,7 +31,7 @@ not only keyframes. A scene tweak can finish with preview evidence; export for f
 
 The composition owns clip start, duration, ordering, cuts, and transitions. The scene owns objects, camera, environment, backdrop, post effects, constraints, and normalized animation. Scene clips occupy a dedicated full-frame front overlay track. Outer region, position, scale, rotation, fit, clip effects, and internal fades are refused because they would create two transform or timing owners.
 
-`referenceSize` must have the same aspect ratio as the composition. Coordinates are reference pixels with origin at frame center, +X right, +Y down, and +Z toward the viewer. Equal-aspect outputs scale uniformly.
+`referenceSize` must have the same aspect ratio as the composition. World coordinates are reference pixels with origin at frame center, +X right, +Y up, and +Z toward the default viewer. World rotations use radians in Euler XYZ order; laptop `openAngle` uses radians in [0, PI]. Equal-aspect outputs scale uniformly.
 
 Animation keyframe `at` is normalized over clip duration. Easing belongs to the keyframe it arrives at. The first keyframe has no easing; each later keyframe supplies `linear`, `hold`, or cubic `bezier` easing. Topology, bindings, text content, fonts, material roles, and object kind remain static within a shot.