@cueframe/skills 0.1.0

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

@@ -0,0 +1,293 @@
+---
+name: cueframe-product-video
+description: Use when turning a screen recording (with cursor/click events) into a polished, auto-zooming product video or demo reel via CueFrame — e.g. "make a product demo from this Browserbase capture", "auto-zoom this screen recording to where the user clicked", "turn this walkthrough into a social demo". This is a USE-CASE recipe over the CueFrame primitives in the `cueframe-cli` skill.
+---
+
+# CueFrame — Product Video recipe
+
+A **use-case recipe**, not new framework surface. CueFrame's engine only knows
+primitives (`upload` → `composition put` → `render`, the `reframe` viewport, the
+overlay/effect primitives). This skill is the *judgment* on top: how to turn a
+captured walkthrough into a product video that looks good. This tells you *what*
+to author, not how to transport it.
+
+**Drive the primitives over MCP if you can call tools** (`new_composition` /
+`apply_composition` / `validate_composition` / `create_render` — see the
+`cueframe-connect` skill for the one-line setup). The `npx -y cueframe@0.5 …` commands
+written out below are the same operations for a terminal or CI job with no MCP
+host; see the `cueframe-cli` skill.
+
+## The pipeline
+
+```
+capture (video + cursor/click points)  →  auto-zoom (points → reframe)
+   →  compose (video track + per-clip reframe)  →  polish (overlay primitives)
+   →  render
+```
+
+## 1. Capture → timed focus points
+
+Get a screen recording **plus** the cursor/click events with viewport
+coordinates and timestamps (e.g. from a browser-automation capture). Normalize
+every point to `{ t: seconds, x: 0..1, y: 0..1 }` against the **real captured
+viewport** — these are the *focus points* the zoom follows. Measure the rendered
+video's true duration (ffprobe) and map point times onto it.
+
+## 2. Points → reframe (auto-zoom)
+
+The framework owns the tuning. Canonical implementation:
+`autoZoom(points, style)` in `@cueframe/composition` (timed focus points →
+gapless `reframe` segments; never re-derive this with an LLM — it drifts). Pick a
+**style**, never raw numbers:
+
+| style | zoom (`<1` punches in) | feel |
+|---|---|---|
+| `subtle`   | 0.80 | gentle, corporate |
+| `standard` | 0.67 | default |
+| `punchy`   | 0.55 | snappy, social |
+
+The tiling rule (what `autoZoom` does — use this until it's exposed as
+`cueframe compose from-points`): sort points by `t`; group points within
+`mergeGap`s; pad each group `prePad` before / `postPad` after; drop groups
+shorter than `minZoom`; merge overlapping windows; emit `frame-center` zoom 1
+in the gaps and a `point` punch-in (`focus:{mode:"point",x,y}`, `zoom` = the
+style's) over each window. Result → `source.reframe.segments` on the clip.
+
+## 3. Compose
+
+One video track, the screen recording as a media clip carrying the reframe.
+`npx -y cueframe@0.5 composition put <projectId> -b @composition.json` (see `cueframe-cli`).
+Choose `-a 16:9` for landscape product video, `9:16` for social.
+
+## 4. Polish — layer overlay primitives (this is what makes it look "produced")
+
+A bare auto-zoom reads as a raw screen-grab. Add overlay/effect clips referencing
+registered primitives (`registry/params-required.json` lists each one's params;
+`$brand:` tokens bind brand colors/fonts at render). Tasteful default set for a
+product demo:
+
+| Goal | primitiveId | kind |
+|---|---|---|
+| animated cursor tracing the click path | `cursor-flow` / `simulated-cursor` | overlay |
+| title / context | `lower-third` or `heroText` | overlay |
+| highlight a clicked element | `marker-highlight` / `pulsing-indicator` | overlay |
+| device/browser frame | `device-mockup-zoom` / `browser-flow` | overlay |
+| captions (if narrated) | the top-level `captions` field | — |
+| finish/look | `color-grade` + `vignette` | effect |
+| several cells sharing space that should reflow (feature grid, rail + fluid content) | author a component on `FlexLayout` from `@cueframe/animate` (see `cueframe-component-authoring`) | overlay (authored) |
+
+Static PiP / split-screen is `region` + `fit` on the clips (EX3 / EX4). Cells that must
+**reflow together** or hold mixed content are one authored component built on `FlexLayout`;
+the catalog `flex-layout` primitive is that same layout, but a bare composition overlay has
+no children, so on its own it draws only the rig outlines.
+
+A primitive is the `source` of a clip; the clip wraps it with `id`/`startTime`/`duration`:
+- Overlay clip (on a `kind:"overlay"` track): `{ "id":"t1", "startTime":1, "duration":3, "source":{ "kind":"overlay", "primitiveId":"lower-third", "params":{…}, "zPlane":"front" } }`.
+- Effect clip (on a `kind:"effect"` track): `{ "id":"e1", "startTime":0, "duration":9, "source":{ "kind":"effect", "primitiveId":"color-grade", "params":{…} } }`.
+Simultaneous overlays go on **separate tracks** — clips on one track can't overlap in time.
+**Don't over-decorate** — 2–4 primitives. Cursor + title + grade is usually enough.
+
+## 5. Render
+
+First use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md):
+check framing with `preview_frame` and click/zoom timing with an affected-window `preview_clip`.
+For a small revision, verify that change and relevant regressions without exporting the whole film.
+When delivering the finished video:
+
+`npx -y cueframe@0.5 render <projectId> -o out.mp4 --json`. Verify the output (ffprobe +
+sample frames) before declaring done.
+
+## Worked examples — composition JSON
+
+These are **orientation, not the contract.** The live wire schema is
+`npx -y cueframe@0.5 schema composition`, and the way to know a draft is correct is
+`npx -y cueframe@0.5 composition validate -b @composition.json` — it runs the same
+validator the server enforces, with no save and no render. Discover + validate
+before you render; never spend a render to find a schema mistake.
+
+Each block below is a complete `@composition.json` (the bare object `composition put`
+accepts: top-level `v`, `format`, `tracks`, optional `captions`). All five validate
+against the real wire schema + save invariants (swap the `<…MediaId>` placeholders for
+real `npx -y cueframe@0.5 upload` ids). Conventions that keep them valid:
+
+- Tracks hold **`contents`** (not `clips`); each clip wraps a `source`.
+- A clip's `source.kind` must match the track `kind`: `media` → `video`/`image`/`audio`
+  tracks, `overlay` → `overlay` tracks, `effect` → `effect` tracks.
+- Clip/segment times are **seconds** (`startTime`, `duration`, `startSec`, `endSec`,
+  `trim`); caption word times are **milliseconds** (`startMs`/`endMs`).
+- `region`/`fit` are **clip-level** (siblings of `source`); `reframe` lives on the media `source`.
+- Clips on one track can't overlap — put simultaneous layers on **separate tracks**.
+- `zoom < 1` punches in (range `[0.1, 1]`, default `1`). Durations are illustrative — match your source.
+
+### EX1 · Auto-zoom screen demo (16:9)
+One screen recording with `reframe` punch-ins (the `autoZoom` output: `frame-center` in the gaps, `point` over each click) + a cinematic grade.
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "16:9", "fps": 30 },
+  "tracks": [
+    {
+      "id": "v-screen", "kind": "video", "contents": [
+        {
+          "id": "rec", "startTime": 0, "duration": 12,
+          "source": {
+            "kind": "media", "mediaId": "<mediaId>",
+            "reframe": { "segments": [
+              { "startSec": 0,  "endSec": 2,  "focus": { "mode": "frame-center" }, "zoom": 1 },
+              { "startSec": 2,  "endSec": 5,  "focus": { "mode": "point", "x": 0.28, "y": 0.42 }, "zoom": 0.6,  "ease": { "in": 0.4, "out": 0.4 } },
+              { "startSec": 5,  "endSec": 7,  "focus": { "mode": "frame-center" }, "zoom": 1, "ease": { "in": 0.4, "out": 0.4 } },
+              { "startSec": 7,  "endSec": 10, "focus": { "mode": "point", "x": 0.72, "y": 0.66 }, "zoom": 0.55, "ease": { "in": 0.4, "out": 0.4 } },
+              { "startSec": 10, "endSec": 12, "focus": { "mode": "frame-center" }, "zoom": 1, "ease": { "in": 0.4, "out": 0.4 } }
+            ] }
+          }
+        }
+      ]
+    },
+    {
+      "id": "fx", "kind": "effect", "contents": [
+        { "id": "grade", "startTime": 0, "duration": 12, "source": { "kind": "effect", "primitiveId": "color-grade", "params": { "preset": "cinematic" } } }
+      ]
+    }
+  ]
+}
+```
+
+### EX2 · Social vertical with captions (9:16)
+Reframe + a `lower-third` title, then a `cursor-flow` overlay (non-overlapping on one overlay track), transcript `captions` (ms timing), warm grade. `$brand:` refs bind brand colors/fonts at render.
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "9:16", "fps": 30, "platform": "tiktok" },
+  "tracks": [
+    {
+      "id": "v", "kind": "video", "contents": [
+        {
+          "id": "rec", "startTime": 0, "duration": 10,
+          "source": {
+            "kind": "media", "mediaId": "<mediaId>",
+            "reframe": { "segments": [
+              { "startSec": 0, "endSec": 4,  "focus": { "mode": "point", "x": 0.3,  "y": 0.4 },  "zoom": 0.7,  "ease": { "in": 0.4, "out": 0.4 } },
+              { "startSec": 4, "endSec": 10, "focus": { "mode": "point", "x": 0.62, "y": 0.55 }, "zoom": 0.62, "ease": { "in": 0.4, "out": 0.4 } }
+            ] }
+          }
+        }
+      ]
+    },
+    {
+      "id": "ov", "kind": "overlay", "contents": [
+        {
+          "id": "title", "startTime": 0, "duration": 3.5,
+          "source": {
+            "kind": "overlay", "primitiveId": "lower-third",
+            "params": {
+              "text": "AI video, one command", "subtitle": "cueframe", "variant": "modern",
+              "tokens": { "textColor": "$brand:colors.textOnMedia", "accentColor": "$brand:colors.accent", "fontFamily": "$brand:fonts.heading.family" }
+            }
+          }
+        },
+        {
+          "id": "cursor", "startTime": 3.5, "duration": 6,
+          "source": {
+            "kind": "overlay", "primitiveId": "cursor-flow",
+            "params": {
+              "waypoints": [ { "x": 200, "y": 180 }, { "x": 540, "y": 240, "click": true, "label": "Generate" }, { "x": 1040, "y": 520, "click": true, "label": "Publish" } ],
+              "cursorColor": "$brand:colors.text", "showTargets": true
+            }
+          }
+        }
+      ]
+    },
+    {
+      "id": "fx", "kind": "effect", "contents": [
+        { "id": "grade", "startTime": 0, "duration": 10, "source": { "kind": "effect", "primitiveId": "color-grade", "params": { "preset": "warm" } } }
+      ]
+    }
+  ],
+  "captions": {
+    "segments": [
+      { "words": [
+        { "text": "Watch",   "startMs": 0,    "endMs": 320 },
+        { "text": "this",    "startMs": 320,  "endMs": 560, "emphasis": true },
+        { "text": "render",  "startMs": 560,  "endMs": 980 },
+        { "text": "in",      "startMs": 980,  "endMs": 1120 },
+        { "text": "one",     "startMs": 1120, "endMs": 1360, "emphasis": true },
+        { "text": "command", "startMs": 1360, "endMs": 1900 }
+      ] }
+    ],
+    "style": { "fontFamily": "Inter", "fontSize": 6.5, "fontWeight": 900, "color": "#ffffff", "highlightColor": "#10B981", "position": "bottom", "textTransform": "uppercase" }
+  }
+}
+```
+
+### EX3 · Picture-in-picture (16:9)
+Full-frame screen recording + a webcam **inset** placed with `region`/`fit` on a second video track (composites on top by track order). Two uploads → two `mediaId`s.
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "16:9", "fps": 30 },
+  "tracks": [
+    { "id": "v-screen", "kind": "video", "contents": [
+      { "id": "screen", "startTime": 0, "duration": 10, "source": { "kind": "media", "mediaId": "<screenMediaId>" } }
+    ] },
+    { "id": "v-cam", "kind": "video", "contents": [
+      { "id": "cam", "startTime": 0, "duration": 10, "source": { "kind": "media", "mediaId": "<webcamMediaId>" }, "region": { "x": 0.68, "y": 0.04, "w": 0.3, "h": 0.3 }, "fit": "cover" }
+    ] }
+  ]
+}
+```
+
+### EX4 · Split-screen (16:9)
+Two sources side-by-side, each with a half-frame `region` on its own video track.
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "16:9", "fps": 30 },
+  "tracks": [
+    { "id": "v-left", "kind": "video", "contents": [
+      { "id": "left", "startTime": 0, "duration": 8, "source": { "kind": "media", "mediaId": "<leftMediaId>" }, "region": { "x": 0, "y": 0, "w": 0.5, "h": 1 }, "fit": "cover" }
+    ] },
+    { "id": "v-right", "kind": "video", "contents": [
+      { "id": "right", "startTime": 0, "duration": 8, "source": { "kind": "media", "mediaId": "<rightMediaId>" }, "region": { "x": 0.5, "y": 0, "w": 0.5, "h": 1 }, "fit": "cover" }
+    ] }
+  ]
+}
+```
+
+### EX5 · Presenter intro — title behind the speaker (9:16)
+Talking-head with an `active-speaker` reframe and a `heroText` title at `zPlane:"behind-subject"`. The speaker **detection** and the person **matte** are both resolved automatically at render (see the `cueframe-cli` skill's "Render resolves expensive intents" section) — author the intent, render, done.
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "9:16", "fps": 30 },
+  "tracks": [
+    { "id": "v", "kind": "video", "contents": [
+      { "id": "cam", "startTime": 0, "duration": 6, "source": { "kind": "media", "mediaId": "<mediaId>", "reframe": { "segments": [ { "startSec": 0, "endSec": 6, "focus": { "mode": "active-speaker" }, "zoom": 0.8 } ] } } }
+    ] },
+    { "id": "ov", "kind": "overlay", "contents": [
+      { "id": "hero", "startTime": 0.5, "duration": 5, "source": {
+        "kind": "overlay", "primitiveId": "heroText",
+        "params": { "text": "SHIP IN MINUTES", "fontSizePct": 14, "textColor": "$brand:colors.textOnMedia", "fontFamily": "$brand:fonts.heading.family" },
+        "zPlane": "behind-subject", "anchor": { "space": "scene", "x": 0.5, "y": 0.42 }
+      } }
+    ] }
+  ]
+}
+```
+
+## Notes / honesty
+
+- **Picture-in-picture / inset cards render** — per-clip output-space placement
+  (`region:{x,y,w,h}` in `[0,1]` + `fit`) is wired for PiP / inset / split-screen,
+  for video, image, and overlay clips. Set `region`/`fit` on the **clip** (siblings
+  of `source`, not inside it — as an agent, patch them with an `apply_composition`
+  `clip.update` op: `{ type: 'clip.update', clipId, patch: { region, fit } }`); two
+  clips with different placement composite by track order instead of occluding the
+  background. See EX3 / EX4 below.
+- This recipe lives in a skill on purpose: the engine stays use-case-free; the
+  product opinions (style, which primitives, layout) live here and ship via
+  `npx -y cueframe@0.5 install`. Add sibling recipes (`cueframe-podcast-clip`, …) the same way.

package/skills/cueframe-product-video/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame — Product Video recipe"
+  short_description: "Use when turning a screen recording (with cursor/click events) into a…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-product-video when turning a screen recording (with cursor/click events) into a polished, auto-zooming product video or demo reel via CueFrame — e.g. \"make a product demo from this Browserbase capture\", \"auto-zoom this screen recording to where the user clicked\", \"turn this walkthrough into a social demo\"."

package/skills/cueframe-product-video/assets/icon.svg

@@ -0,0 +1,16 @@
+<svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg">
+  <clipPath id="cf-favicon-clip"><circle cx="128" cy="128" r="118"/></clipPath>
+  <circle cx="128" cy="128" r="118" fill="#f7c948"/>
+  <g clip-path="url(#cf-favicon-clip)">
+    <path d="M88 128Q160 40 300-40" fill="none" stroke="#160f08" stroke-width="5"/>
+    <path d="M88 128Q170 60 310 20" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q180 80 316 70" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q186 110 320 110" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q186 146 320 146" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q180 176 316 186" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q170 196 310 236" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q160 216 300 296" fill="none" stroke="#160f08" stroke-width="5"/>
+  </g>
+  <circle cx="88" cy="128" r="20" fill="#160f08"/>
+  <circle cx="88" cy="128" r="8" fill="#f7c948"/>
+</svg>

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

@@ -0,0 +1,68 @@
+---
+name: cueframe-scene-shot
+description: Author a CueFrame 3D world-object shot as canonical SceneShotSpecV2 JSON. Use for slabs, pages, phones, laptops, captured component or video surfaces, world text, camera motion, studio lighting, focus, and product-shot recipes.
+---
+
+# CueFrame scene shots
+
+Use `scene.add` and `scene.update` through `apply_composition`. Author the scene JSON; CueFrame owns the generated wrapper, preparation, resource admission, previews, and export.
+
+Before authoring, read `cueframe://scene-shot`. It serves the canonical generated `SceneShotSpecV2` schema, exact operation contracts, supported brand tokens, refusal rules, and a copyable nested slab-and-page recipe. Do not infer fields from an older example.
+
+On the CueFrame desktop app that resource is unreachable — its MCP surface is tools-only and no `cueframe://` URI resolves there. Call the `get_scene_contract` tool instead: same document, served in sections (`essentials` by default, then `rules` and `schema`).
+
+## Workflow
+
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+for the available hosted/local lane. Inspect affected camera/focus/entrance windows in motion,
+not only keyframes. A scene tweak can finish with preview evidence; export for final delivery.
+
+1. Create or open a composition at the target aspect and FPS.
+2. Register every image or video source. Capture-backed component surfaces use an exact component id, source version id, capture frame, layout, and optional bake scale.
+3. Read `cueframe://scene-shot` (desktop: `get_scene_contract`), copy its `world-objects` recipe, and replace placeholder ids and copy.
+4. Send `apply_composition` with `dry_run: true`. Fix the exact reported field path.
+5. Apply the same batch for real. Preview the first frame, object entrances, focus transitions, and the last frame.
+6. Revise with `scene.update`; do not hand-edit a generated wrapper.
+7. Render only after surfaces report ready and the previews show the intended pixels.
+
+## Ownership boundaries
+
+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.
+
+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.
+
+## Objects and surfaces
+
+V2 supports nested `group` layers and canonical `slab`, `page`, `phone`, `laptop`, and `text` layers. Use each object's declared surface slot:
+
+- `source: "image"` binds an admitted PNG, JPEG, or WebP through the outer `assets` map.
+- `source: "component"` captures an immutable component source at the declared frame and layout. Omitted `bakeScale` lets preparation select 2× or 3×; an explicit insufficient scale refuses.
+- `source: "video"` binds an admitted media id with frame-addressed start/end facts. Video decoding and committed-frame readiness are sealed before drawing.
+- `source: "color"` supplies an unlit solid surface.
+
+Never insert a URL, raw HTML, shader source, or placeholder art into a surface. Every required slot must resolve before capture. UI surfaces and world text are unlit and color-managed; bodies use declared physical material roles. Invisible objects do not write depth.
+
+World text participates in camera, depth, occlusion, and focus. Screen text stays fixed above the world result. Both are line-authored with no automatic reflow. Every exact font family, weight, and style used by base or emphasized runs must be admitted.
+
+## Lighting and post
+
+Choose the generated studio environment for named studio profiles or `{kind:"photographic-studio-v1"}` for the fixed photographic recipe. Arbitrary HDR fields are refused. Backdrops may be transparent, solid, linear, or radial. Focus is per-pixel world depth; sample the actual object face rather than its layer origin when choosing distance and range.
+
+Brand tokens are allowed only in schema-declared color and font-family fields. Read the token enums from the resource. A font token resolves the family only; authored weight and style still require exact admitted bytes.
+
+## Limits and refusals
+
+The contract admits at most 32 layers, 4 devices, 16 distinct image slots, 256 keyframes per channel, and 2048 keyframes per shot. Raw HTML, custom shader properties, imported GLB models, arbitrary external HDR environments, skeletal animation, and physics are unsupported. Unknown keys, duplicate ids, missing bindings, non-finite values, aspect mismatch, budget overflow, and unsupported capabilities fail with a named code and exact path.
+
+Composition-level global wrap effects do not reach front-overlay scene clips. Author grain, vignette, focus, backdrop, and environment inside the scene.
+
+## Delivery checks
+
+- The rendered subject is a real object with a real admitted surface.
+- Every key entrance, reflection sweep, screen update, and focus transition was previewed.
+- Device and slab bodies receive the intended light while UI colors remain unchanged.
+- Text uses the intended admitted face and remains legible.
+- The output aspect matches the authored reference aspect.
+- The final response identifies the composition, render, source provenance, and any intentional unsupported boundary.

package/skills/cueframe-scene-shot/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame scene shots"
+  short_description: "Author a CueFrame 3D world-object shot as canonical SceneShotSpecV2 JSON. Use…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-scene-shot to author a CueFrame 3D world-object shot as canonical SceneShotSpecV2 JSON."

package/skills/cueframe-scene-shot/assets/icon.svg

@@ -0,0 +1,16 @@
+<svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg">
+  <clipPath id="cf-favicon-clip"><circle cx="128" cy="128" r="118"/></clipPath>
+  <circle cx="128" cy="128" r="118" fill="#f7c948"/>
+  <g clip-path="url(#cf-favicon-clip)">
+    <path d="M88 128Q160 40 300-40" fill="none" stroke="#160f08" stroke-width="5"/>
+    <path d="M88 128Q170 60 310 20" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q180 80 316 70" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q186 110 320 110" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q186 146 320 146" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q180 176 316 186" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q170 196 310 236" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q160 216 300 296" fill="none" stroke="#160f08" stroke-width="5"/>
+  </g>
+  <circle cx="88" cy="128" r="20" fill="#160f08"/>
+  <circle cx="88" cy="128" r="8" fill="#f7c948"/>
+</svg>

package/skills/cueframe-storyboard/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: cueframe-storyboard
+description: >-
+  Use BEFORE composing when starting a NEW video from scratch and you need to plan its structure — turning a rough ask ("make a launch video", "30s promo", "an explainer for our API") into a concrete beat flow. Owns the intake + storyboard step: interview the user for the brief, resolve the format from the platform, and lay out the hook→body→cta beats that drive the compose workflow. Triggers on "plan a video", "storyboard", "structure this video", "outline the video", "where do I start", or any new-video ask that has no structure yet. Hand off to composing-video for per-beat craft.
+---
+
+# CueFrame Storyboard: brief → flow
+
+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)
+to verify the requested change; do not restart intake, Director authoring, or final export by default.
+
+> **The bar:** the `video-craft-standards` skill (GET /v1/skills/video-craft-standards) defines DONE for every artifact class — per-class MUST checklists and kill criteria. Read it before composing and score against it before rendering. When this skill and that document disagree, the standards win.
+
+
+## The one idea
+
+**You are the planner.** You have the user, the whole conversation, the brand, and the judgment — you are
+the smartest thing in this loop. CueFrame is the hands. This skill is the **intake + structure** step:
+turn intent into a concrete **beat flow** *before* you seed a composition, so the curated workflow (media →
+components → seed) executes a plan instead of a guess. Craft — grounded-vs-slop, the verify loop — belongs
+to the sibling **composing-video** skill; this skill gets you a flow, then hands off to it.
+
+Do not offload the *thinking* to CueFrame. There is no server that plans the video for you, and you would
+not want one — it would be a blind model with none of your context. Plan here, in the open, with the user.
+
+## 1. Interview for the brief — ask only what you can't infer
+
+Fill the brief from the conversation first; ask the user **only for the 1–2 things you genuinely cannot
+infer**, and STATE what you assume for the rest. Never wall them with a form.
+
+- **Goal / intent** *(required)* — what is this video FOR? launch, promo, explainer, demo, teaser, recap.
+- **Platform** *(sets the format)* — reels / tiktok / shorts → **9:16, ~20s** · youtube → **16:9, ~45s** ·
+  linkedin / x → **1:1, ~20s** · web → **16:9, ~30s**. (Or an explicit aspect ratio + duration.)
+- **Audience**, **tone** (punchy / premium-calm / playful / authoritative), **CTA**, **must-includes**
+  (a number, a name, a screen), **references** (a style to echo), **brand kit**.
+
+If the ask is "make a launch video for our API," you already have goal + a hint of audience — ask "Reels,
+YouTube, or your site?" and infer the rest: *"I'll assume a developer audience and a punchy tone — say if
+you'd rather it feel calm/premium."* One or two questions, not seven.
+
+## 2. Structure the flow — the storyboard
+
+Lay the duration into **beats** using the fixed editorial vocabulary
+**hook → context → body → proof → cta → outro** (use what the piece needs — most short-form is
+hook → body → cta). For each beat decide:
+
+- a one-line **intent** (what this beat does for the viewer),
+- a **duration** (they sum to the target; the hook earns attention in ~3s),
+- a **media need** — real footage is the strongest grounding and CueFrame's home turf, so reach for it
+  first; otherwise `generate` a *purposeful* clip (a diagram of the real mechanism, the real UI) or `find`
+  stock. Animated text over a gradient is not grounding — it's the slop default,
+- an optional **graphic** (a lower-third, title, CTA card),
+- a **caption** and/or a **VO/script** line.
+
+**Ground it, don't invent it.** Pick every graphic/scene from `list_catalog` (filter by `useCase`/`tier`)
+— never hardcode hex or positions or name a component that doesn't exist. Theme from the brand kit. If
+you're planning over real footage, read `get_media_context` (detected faces + transcript) so beat timing,
+crops, and captions land on what's actually there.
+
+## 3. Show the flow, then persist it as a Brief
+
+Show the user the beat list **first** — a five-line outline. It is cheap to change here and expensive to
+change after a render, so this is where you converge on structure. On their go, **persist the plan with
+`create_brief`** — the beats/goal/format/gates you just elicited map 1:1 onto its fields, and the plan stops
+being chat-ephemeral (it survives the session, carries a cost quote, and is honored field-by-field):
+
+1. `import_media` / `generate_media` for each beat's media need,
+2. `create_brief` — goal, audience, platform/format, durationSec, tone, cta, locale, and the beats
+   (each with its editorial intent and, when you're cutting real footage, MOMENT PINNING
+   `source: {mediaId, startSec, endSec}` from the transcript — honored to-the-frame or refused).
+   Relay the response's **quote** (compose + estimated render) BEFORE composing.
+3. `compose { briefId }` — the Director authors FROM your brief; every field is honored or the
+   compose is refused loudly naming the field. Gates: put `holdAt: ["layout"]` in the brief's `gates` when
+   the user wants to approve the storyboard mid-flight; `autoApprove: true` for hands-off.
+4. `score_composition` / `consult` to fix the weakest beat,
+5. `create_render` for the MP4.
+
+**Two graphic media — pick per beat, and review accordingly:** a `card` (verbatim HTML in
+`seededGraphics`) is a STATIC graphic — cheap, approve it from a still; a **component**
+(`create_component`, `useCurrentFrame`) is MOTION — a still is one frame, so preview it before trusting it.
+Seeded graphics you author into the brief are carried VERBATIM as locked clips — the Director never
+re-authors them; `exclusions` bans graphic kinds you never want it to author.
+
+Then load **composing-video** and apply its craft to make each beat good.
+
+## Related skills & positioning
+
+This skill owns **structure/intake**; its siblings own execution and craft — defer to them:
+
+- **composing-video** — the craft/quality layer (grounded specificity vs. slop, the vision → rubric →
+  verify loop). Load it *after* you have a flow; it makes each beat good.
+- **cueframe-compose-loop** — the author → render → verify → fix convergence loop + the ship bar.
+- **cueframe-product-video** — click-points → auto-zoom tiling + PiP for screen demos.
+- **cueframe-brand-demo** — brand-token vocabulary + auto intro/outro/logo for branded launches.
+- **cueframe-component-authoring** — fork → preview → push for a custom graphic a beat needs.
+- **cueframe-cli** — the `cueframe` binary + wire mechanics.
+
+## The boundary
+
+You own the **vision** (the one idea and the flow for *this* video) and **data correctness** (a wrong
+number you supply is rendered faithfully — the mistake is yours). CueFrame owns being faithful, legible,
+and giving you real footage + real components to plan against. Reason from this; skip the whole flow only
+for a re-render of an approved composition or a single trivial one-off.

package/skills/cueframe-storyboard/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame Storyboard: brief → flow"
+  short_description: "Use BEFORE composing when starting a NEW video from scratch and you need to…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-storyboard before composing when starting a NEW video from scratch and you need to plan its structure — turning a rough ask (\"make a launch video\", \"30s promo\", \"an explainer for our API\") into a concrete beat flow."

package/skills/cueframe-storyboard/assets/icon.svg

@@ -0,0 +1,16 @@
+<svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg">
+  <clipPath id="cf-favicon-clip"><circle cx="128" cy="128" r="118"/></clipPath>
+  <circle cx="128" cy="128" r="118" fill="#f7c948"/>
+  <g clip-path="url(#cf-favicon-clip)">
+    <path d="M88 128Q160 40 300-40" fill="none" stroke="#160f08" stroke-width="5"/>
+    <path d="M88 128Q170 60 310 20" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q180 80 316 70" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q186 110 320 110" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q186 146 320 146" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q180 176 316 186" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q170 196 310 236" fill="none" stroke="#160f08" stroke-width="4.5"/>
+    <path d="M88 128Q160 216 300 296" fill="none" stroke="#160f08" stroke-width="5"/>
+  </g>
+  <circle cx="88" cy="128" r="20" fill="#160f08"/>
+  <circle cx="88" cy="128" r="8" fill="#f7c948"/>
+</svg>

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

@@ -0,0 +1,87 @@
+---
+name: every-format-from-one-edit
+description: Derives content-aware 9:16, 1:1, and 4:5 siblings from one finished composition — same edit, every platform, no re-editing. Triggers on "make this vertical too", "I need this for TikTok and LinkedIn", "every aspect ratio", "square version of this", "resize for Reels", "one video, all platforms", "port this edit to Shorts".
+---
+
+# Every format from one edit
+
+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,
+subject-tracked rather than letterboxed, each judged and rendered on its own. The edit decisions
+are made once; the formats are a job, not a re-edit.
+
+## Before you start
+
+Confirm which master and which target platforms before setup. When the first tool call
+approaches and CueFrame isn't connected, load **`cueframe-connect`** and follow it once.
+
+Then straight to deriving — this whole job is minutes when the master is good.
+
+## Inputs
+
+- **The master composition** (required): a finished, approved edit — find it via
+  `list_compositions` if the user doesn't have the id. If the master isn't done, finish it first
+  (this skill multiplies quality AND flaws).
+- **Target aspects**: default all three siblings — 9:16, 1:1, 4:5. The documented derive lane
+  starts from a 16:9 master.
+- **Per-platform tweaks**: default none — determinism is the point. Take an explicit ask (e.g.
+  "shorter for TikTok") as a separate edit on the derived sibling.
+
+## Workflow
+
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+for each affected sibling. Check motion as well as layout where the new crop changes visibility.
+A correction to one sibling does not require rendering the master or the other unchanged siblings.
+
+1. **Verify the master is actually done.** It passed its class checklist, its audio was
+   decided, its render was approved. Deriving from a draft ships the draft's flaws four times.
+2. **Derive each sibling.** `derive_composition` per target aspect — the reframe is
+   content-aware: it tracks the subject into the new frame instead of letterboxing. Each
+   sibling is a real composition you can edit independently afterward; the master is never
+   touched.
+3. **Audit every sibling on real pixels — required, not optional.** `preview_frame` each
+   sibling at t=0, hook-end, and each card's midpoint; describe each still. What to look for
+   per aspect: the subject's head fully in the vertical frame; cards and captions inside the
+   safe area (no critical copy in the outer ~8%); no beat where the tighter crop lost the thing
+   the beat exists to show.
+4. **Fix per-sibling, surgically.** Where a crop or card misbehaves, `apply_composition` on
+   THAT sibling — nudge a `setCropIntents` segment, resize a card for the narrower frame
+   (re-shell with `applyMotionPreset` in a following call if you replace the card). Don't
+   re-edit the story; the story is the master's.
+5. **Confirm the audio carried.** The master's decided audio — bed, ducking, beat-aligned cuts
+   (`materializeGrid` markers), or its intentional silence — rides into each sibling. Verify
+   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
+   master's vision as `editorialIntent`. A 9:16 sibling is a social reel and answers to that
+   class's checklist — hook inside 2 seconds still applies in the new crop. Fix worst-first to
+   ≥ 7.5.
+7. **Render each approved sibling.** `create_render` → `wait_job (kind:"render")` per
+   composition. One final render per approval; iterate with previews.
+
+## What good looks like
+
+Quoted from `video-craft-standards` (cross-cutting rules — every artifact):
+
+> **MUST** Safe-area respected: no critical copy in the outer ~8% of frame.
+
+> **MUST** One final render per approval; iterate with previews, not renders.
+
+> **MUST** 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: a derived 9:16 answers to §1 (Social reel) —
+*"**MUST (K)** The hook lands inside 2 seconds"* — a derived 16:9 to its own class. Derivation
+changes the frame, never the bar.
+
+## Delivering
+
+The last message is a manifest, never "done":
+
+- Every sibling's render link, labeled by aspect and platform, and where each lives (project +
+  composition id — the master's id too, since it stays the source of truth).
+- The master's attribution list (it covers all siblings — same assets).
+- The intentional-silence note, restated once, if the master chose silence.
+- Any sibling-specific edits you made (which crop nudged, which card resized) so future master
+  edits know what to re-check after re-deriving.