cueframe 0.9.4 → 0.11.3

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

@@ -0,0 +1,146 @@
+# CueFrame tool reference
+
+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.
+
+Hosted surfaces: `api` is the MCP server at `https://api.cueframe.ai/v1/mcp`; `editor` and `compose` are the hosted Director's editor and compose sessions. Desktop surfaces: `director` is the desktop app's agent, `plan` its planning mode, `external` an outside MCP client connected to the desktop app, and `cli` the Director running as a CLI agent such as Claude Code. A tool is callable only on the surfaces listed for it; list your host's tools for what this connection serves.
+
+| Tool | Access | Hosted | Desktop |
+| --- | --- | --- | --- |
+| `analyze_transcript` | read | editor, compose | director, plan, external, cli |
+| `apply_composition` | write | api, editor, compose | director, external, cli |
+| `apply_template` | write | api, editor | director, external, cli |
+| `cancel_compose` | write | api | - |
+| `cancel_export` | write | api | - |
+| `cancel_job` | write | api | - |
+| `cancel_render` | write | api | - |
+| `check_template` | 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 | - |
+| `create_brief` | write | api | - |
+| `create_checkout` | write | api | - |
+| `create_component` | write | api, editor, compose | director, external, cli |
+| `create_project` | write | api | external |
+| `create_render` | write | api, editor, compose | director, external, cli |
+| `create_upload` | write | api | - |
+| `create_webhook` | write | api | - |
+| `delete_brief` | write | api | - |
+| `delete_composition` | write | api | - |
+| `delete_critic` | write | api | - |
+| `delete_media` | write | api | - |
+| `delete_project` | write | api | external |
+| `delete_webhook` | write | api | - |
+| `derive_composition` | write | api, editor, compose | director, external, cli |
+| `describe_composition_ops` | read | api, editor, compose | director, plan, external, cli |
+| `download_media` | read | api | - |
+| `edit_component` | write | - | director, external, cli |
+| `editorial_apply` | write | api, editor, compose | director, cli |
+| `editorial_begin` | write | - | director, cli |
+| `editorial_create_brief` | write | api, editor, compose | - |
+| `editorial_create_run` | write | api, editor, compose | - |
+| `editorial_findings_append` | write | api, editor, compose | director, cli |
+| `editorial_findings_list` | read | api, editor, compose | director, plan, cli |
+| `editorial_get_run` | read | api, editor, compose | director, plan, cli |
+| `editorial_inspect_audio` | write | api, editor, compose | director, cli |
+| `editorial_inspect_source` | write | api, editor, compose | director, cli |
+| `editorial_inspect_transcript` | write | api, editor, compose | director, cli |
+| `editorial_integrate` | write | api, editor, compose | director, cli |
+| `editorial_list_briefs` | read | api, editor, compose | director, plan, cli |
+| `editorial_list_evidence` | read | api, editor, compose | director, plan, cli |
+| `editorial_list_runs` | read | api, editor, compose | director, plan, cli |
+| `editorial_run_source` | read | api, editor, compose | director, plan, external, cli |
+| `editorial_sample_motion` | write | api, editor, compose | director, cli |
+| `export_project` | write | - | external |
+| `extract_brand_kit` | write | api | - |
+| `finalize_upload` | write | api | - |
+| `forget_taste` | write | api, editor, compose | director, external, cli |
+| `generate_media` | write | api, editor, compose | director, external, cli |
+| `get_account` | read | api, editor, compose | director, plan, external, cli |
+| `get_app_state` | read | - | director, plan, external, cli |
+| `get_brief` | read | api | - |
+| `get_checkpoint` | read | api | - |
+| `get_component_source` | read | api, editor, compose | director, plan, external, cli |
+| `get_composition` | read | api, editor, compose | director, plan, external, cli |
+| `get_context` | read | editor, compose | director, plan, external, cli |
+| `get_director_state` | read | - | external |
+| `get_editor_state` | read | - | director, plan, external, cli |
+| `get_import_status` | read | - | director, plan, external, cli |
+| `get_media_context` | read | api, editor, compose | director, plan, external, cli |
+| `get_media_facts` | read | api | director, plan, external, cli |
+| `get_profile` | read | api, editor, compose | director, plan, external, cli |
+| `get_project_settings` | read | - | external |
+| `get_render` | read | api | - |
+| `get_scene_contract` | read | - | director, plan, external, cli |
+| `get_template` | read | api, editor | director, plan, external, cli |
+| `get_transcript` | read | api, editor, compose | director, plan, external, cli |
+| `get_usage` | read | api, editor, compose | director, plan, external, cli |
+| `import_local_media` | write | - | director, external, cli |
+| `import_media` | write | api, editor, compose | director, external, cli |
+| `import_resource` | write | api, editor, compose | director, external, cli |
+| `install_local_person_runtime` | write | - | director, external, cli |
+| `list_briefs` | read | api | - |
+| `list_catalog` | read | api, editor, compose | director, plan, external, cli |
+| `list_checkpoints` | read | api | - |
+| `list_component_packages` | read | - | external |
+| `list_compositions` | read | api | - |
+| `list_critics` | read | api | - |
+| `list_media` | read | api, editor, compose | director, plan, external, cli |
+| `list_plans` | read | api | - |
+| `list_projects` | read | api | external |
+| `list_render_fonts` | read | api | director, plan, external, cli |
+| `list_taste` | read | api, editor, compose | director, plan, external, cli |
+| `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 |
+| `play_pause` | write | - | director, plan, external, cli |
+| `prepare_component_library_previews` | write | - | external |
+| `prepare_component_media` | read | - | external |
+| `prepare_media` | write | api | director, external, cli |
+| `preview_card` | read | api, editor, compose | - |
+| `preview_clip` | write | api | - |
+| `preview_component` | read | api | - |
+| `preview_frame` | read | api, editor, compose | director, plan, external, cli |
+| `propose_plan` | write | - | director, plan, cli |
+| `publish_component` | write | - | external |
+| `read_component` | read | - | director, plan, external, cli |
+| `redo_edit` | write | - | external |
+| `refresh_render_url` | write | api | - |
+| `register_critic` | write | api | - |
+| `remember_taste` | write | api, editor, compose | director, external, cli |
+| `rename_project` | write | - | external |
+| `render_component_preview_frame` | read | - | director, plan, external, cli |
+| `repin_component` | write | api | director, external, cli |
+| `resolve_builtin_component` | read | api | - |
+| `resume` | write | api | - |
+| `retry_render` | write | api | - |
+| `save_as_template` | write | - | director, external, cli |
+| `score_composition` | write | api, editor, compose | director, external, cli |
+| `search_fonts` | read | api, editor, compose | director, plan, external, cli |
+| `search_library` | read | editor, compose | director, plan, external, cli |
+| `search_resources` | read | api, editor, compose | director, plan, external, cli |
+| `seek` | write | - | director, plan, external, cli |
+| `select_candidate` | write | api | - |
+| `send_director_prompt` | write | - | external |
+| `set_playback_rate` | write | - | director, plan, external, cli |
+| `start_template` | write | api, editor | - |
+| `submit_plan` | write | - | director, plan, cli |
+| `suggest_briefs` | write | api | - |
+| `undo_edit` | write | - | external |
+| `update_brief` | write | api | - |
+| `update_component` | write | api | - |
+| `update_component_preview` | write | - | director, plan, external, cli |
+| `update_project` | write | api | - |
+| `update_project_settings` | write | - | external |
+| `update_webhook` | write | api | - |
+| `validate_composition` | read | api, editor, compose | director, plan, external, cli |
+| `verify_webhook` | write | api | - |
+| `view_asset` | read | - | director, plan, external, cli |
+| `view_style_reference` | read | compose | - |
+| `wait_job` | read | api, editor, compose | director, plan, external, cli |

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

@@ -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
@@ -21,7 +15,7 @@ to author, not how to transport it.
 
 **Drive the primitives over MCP if you can call tools** (`new_composition` /
 `apply_composition` / `validate_composition` / `create_render` — see the
-`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.9 …` commands
+`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.11 …` commands
 written out below are the same operations for a terminal or CI job with no MCP
 host; see the `cueframe-cli` skill.
 
@@ -64,7 +58,8 @@ style's) over each window. Result → `source.reframe.segments` on the clip.
 ## 3. Compose
 
 One video track, the screen recording as a media clip carrying the reframe.
-`npx -y cueframe@0.9 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+`npx -y cueframe@0.11 composition put <projectId> -b @composition.json --if-match <etag>`, with the
+ETag from `composition get` (`--create` for the project's first composition; see `cueframe-cli`).
 Choose `-a 16:9` for landscape product video, `9:16` for social.
 
 ## 4. Polish — layer overlay primitives (this is what makes it look "produced")
@@ -101,21 +96,21 @@ check framing with `preview_frame` and click/zoom timing with an affected-window
 For a small revision, verify that change and relevant regressions without exporting the whole film.
 When delivering the finished video:
 
-`npx -y cueframe@0.9 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+`npx -y cueframe@0.11 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
 sample frames) before declaring done.
 
 ## Worked examples — composition JSON
 
 These are **orientation, not the contract.** The live wire schema is
-`npx -y cueframe@0.9 schema composition`, and the way to know a draft is correct is
-`npx -y cueframe@0.9 composition validate -b @composition.json` — it runs the same
+`npx -y cueframe@0.11 schema composition`, and the way to know a draft is correct is
+`npx -y cueframe@0.11 composition validate -b @composition.json` — it runs the same
 validator the server enforces, with no save and no render. Discover + validate
 before you render; never spend a render to find a schema mistake.
 
 Each block below is a complete `@composition.json` (the bare object `composition put`
 accepts: top-level `v`, `format`, `tracks`, optional `captions`). All five validate
 against the real wire schema + save invariants (swap the `<…MediaId>` placeholders for
-real `npx -y cueframe@0.9 upload` ids). Conventions that keep them valid:
+real `npx -y cueframe@0.11 upload` ids). Conventions that keep them valid:
 
 - Tracks hold **`contents`** (not `clips`); each clip wraps a `source`.
 - A clip's `source.kind` must match the track `kind`: `media` → `video`/`image`/`audio`
@@ -297,4 +292,4 @@ Talking-head with an `active-speaker` reframe and a `heroText` title at `zPlane:
   background. See EX3 / EX4 below.
 - This recipe lives in a skill on purpose: the engine stays use-case-free; the
   product opinions (style, which primitives, layout) live here and ship via
-  `npx -y cueframe@0.9 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.
+  `npx -y cueframe@0.11 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.

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.
 

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

@@ -6,13 +6,7 @@ description: >-
 
 # CueFrame Storyboard: brief → flow
 
-## 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.
 
 This is a new-video planning workflow. For revisions to an approved plan, preserve its structure
 and use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)

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

@@ -5,13 +5,7 @@ description: Derives content-aware 9:16, 1:1, and 4:5 siblings from one finished
 
 # Every format from one edit
 
-## 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.
 
 You finish ONE edit; you get back its siblings for every platform — 9:16 for
 Reels/TikTok/Shorts, 1:1 and 4:5 for feeds — derived content-aware from the master,
@@ -61,7 +55,7 @@ A correction to one sibling does not require rendering the master or the other u
    the bed is present and the silence decision, if any, still holds; the sibling's delivery
    note repeats it. If a sibling needs a different bed, `search_resources` honoring the brand
    kit's `musicMood` and swap it on that sibling only.
-6. **Judge each sibling as its own artifact.** `score_composition` per sibling with the
+6. **Inspect each sibling as its own artifact.** Use `score_composition` only when useful for broader review and within budget, with the
    master's vision as `editorialIntent`. Changing aspect ratio does not change the approved editorial intent, pacing or acceptance criteria. Fix worst-first to
    meet the applicable acceptance criteria.
 7. **Render each approved sibling.** `create_render` → `wait_job (kind:"render")` per
@@ -69,17 +63,7 @@ A correction to one sibling does not require rendering the master or the other u
 
 ## What good looks like
 
-Quoted from `video-craft-standards` (cross-cutting rules — every artifact):
-
-> **DEFAULT** Safe-area respected: no critical copy in the outer ~8% of frame.
-
-> **DEFAULT** One final render per approval; iterate with previews, not renders.
-
-> **DEFAULT** Delivery never ends with "done": the last message carries the output link and where
-> to find it, plus the intentional-silence note if any.
-
-And the class rule that governs each sibling: apply the original brief at the new dimensions; aspect ratio alone does not impose a social-reel hook or pacing. Derivation
-changes the frame, never the bar.
+Use the relevant [craft review questions](../video-craft-standards/SKILL.md) and the [preview workflow](../cueframe-compose-loop/references/preview-workflow.md). Judge the brief's actual intent, visual relationships, timing and sound; format suggestions do not override the requested treatment. The cross-cutting rules in the [format standards](../video-craft-standards/references/format-standards.md) apply to every sibling. Apply the original brief at the new dimensions: aspect ratio alone does not impose a social-reel hook or pacing, and derivation changes the frame, never the bar.
 
 ## Delivering
 

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

@@ -6,13 +6,7 @@ description: >-
 
 # Extracting brand kits: reference pixels → a kit the engine honors
 
-## 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.
 
 ## The one idea
 

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

@@ -5,13 +5,7 @@ description: Turns screen recordings and product footage into a 30–90 second 1
 
 # Launch video
 
-## 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.
 
 You bring real screen recordings or product footage plus the one outcome the feature delivers;
 you get back a 30–90 second 16:9 announcement that opens on the payoff, shows the actual product
@@ -56,8 +50,7 @@ affected window and regressions without automatically rerunning the full-film ju
    product video.
 5. **Cards for the claims and the end card.** Key lines and the closing CTA are `kind:"card"`
    HTML in the brand's type and palette, animated in its CSS or with
-   `clip.setKeyframes` in a FOLLOWING `apply_composition` call. One CTA on the end card, held
-   long enough to read, plus the date if there is one.
+   `clip.setKeyframes` in a FOLLOWING `apply_composition` call. When the brief calls for a CTA, use one, on the end card, held long enough to read; include a date only when relevant.
 6. **Audio when requested or appropriate.** Preserve explicit silence; otherwise: `search_resources` for a bed honoring the brand kit's
    `musicMood`, energy arcing toward the reveal; place it `audioRole:"music"`,
    `materializeGrid { grid:"beat" }`, and land beat boundaries and the reveal on the grid. If
@@ -68,25 +61,12 @@ affected window and regressions without automatically rerunning the full-film ju
    call. Speech clips must have saved duration matching playable source duration divided by
    playbackRate. Re-run after later edits. Use authored word timings for generated VO without a
    transcript, and style legibly via `setCaptionStyle`. Caption narration when requested or appropriate; preserve an explicit uncaptioned format.
-8. **Preview, judge, one render.** `preview_frame` at t=0, hook-end, the reveal, and the end
-   card; describe each still — is that a REAL capture on screen? Then `score_composition` with
-   the payoff line as `editorialIntent`; fix relevant acceptance failures; `create_render` →
-   `wait_job (kind:"render")`.
+8. **Inspect and deliver.** `preview_frame` at t=0, hook-end, the reveal, and the end
+   card; describe each still and ask whether a real capture is on screen; distinguish actual captures from reconstructed artwork. Inspect motion through the important handoffs and listen to changed audio. Use `score_composition` only when broader critique is useful and within budget, with the payoff line as `editorialIntent`. Fix the observed acceptance failures, then export for requested final delivery.
 
 ## What good looks like
 
-Quoted from `video-craft-standards` §2 (Launch film / feature announcement) — these are format defaults:
-
-> **DEFAULT** Payoff-first hook: the OUTCOME, not the feature name ("Close the books two days
-> faster" beats "Introducing the reconciliation module"). No throat-clearing.
-
-> **DEFAULT** Narration or a bed that builds toward the reveal; pacing tightens as the payoff
-> approaches. **DEFAULT** Real product surface: actual UI/screens/output — never mocked.
-
-> **DEFAULT** End card with a single CTA. **DEFAULT** Captions present when narrated.
-
-And cross-cutting: *"Footage carries the video: real footage / real UI / real data ≥60% of
-runtime for footage-first classes."*
+Use the relevant [craft review questions](../video-craft-standards/SKILL.md) and the [preview workflow](../cueframe-compose-loop/references/preview-workflow.md). Judge the brief's actual intent, visual relationships, timing and sound; format suggestions do not override the requested treatment. For this format's defaults read section 2 (Launch film) of the [format standards](../video-craft-standards/references/format-standards.md).
 
 ## Delivering
 
@@ -94,6 +74,6 @@ Close with the handoff, never "done":
 
 - The render link and where it lives (project + composition id).
 - Attribution for the bed and any licensed asset (provider, id, author).
-- The intentional-silence note with its reason, in the rare case silence was chosen.
+- The intentional-silence note with its reason, when relevant to the requested delivery.
 - A one-line cutdown offer: the 16:9 master can become 9:16 / 1:1 siblings for social (see
   `every-format-from-one-edit`).