@cueframe/skills 0.1.0

package/skills/composing-video/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Composing Video: craft for CueFrame"
+  short_description: "Use when an agent is asked to make ANY video with CueFrame — a product launch…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $composing-video when an agent is asked to make ANY video with CueFrame — a product launch, announcement, promo, teaser, social clip, reel, short, explainer, animated explainer, concept video, product/dev-tool demo, walkthrough, or founder/talking-head piece."

package/skills/composing-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-brand-demo/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: cueframe-brand-demo
+description: Use when turning a local app into a brand-consistent product demo with CueFrame — extract the brand straight from the repo (colors/fonts/logo/motion), capture a Playwright walkthrough of the running app, and author a branded, auto-zoomed demo whose intro/outro/logo/colors/fonts/motion are frozen by CueFrame's engine — e.g. "make an on-brand demo of my app", "record my localhost and produce a branded launch video". This is the end-to-end brand pipeline over the CueFrame curated tools.
+---
+
+# CueFrame — Brand demo recipe
+
+> **Kit truth over MCP (current limits):** kit CONTENTS are not yet inspectable over MCP (`get_profile` lists names only), so `$brand:` tokens resolve blind — verify resolved fonts/colors with a `preview_frame` still, and when the kit conflicts with an explicit client spec, the spec wins (hardcode it and note the conflict). Bind kits by the SERVER id from `get_profile` (slug binding is unreliable — it can silently bind nothing); always confirm via the project response `brandKitId`.
+
+
+A **use-case recipe** that runs end-to-end from inside the user's own project
+folder. You (Claude) already see their code and their running app — that's the
+unfair advantage. This skill turns that context into a brand-consistent product
+video: pull the brand from the repo, capture the app, and author a demo whose
+**brand identity is enforced by the engine**, not re-typed per clip.
+
+Two things make this different from `cueframe-product-video`:
+
+1. **The brand is real engine state.** A `brandKit` (created with
+   `create_brand_kit`) carries colors / fonts / spacing / sizing / motion / logo
+   / intro / outro / watermark. A composition references it by `brandKitId`;
+   **render freezes it** — intro/outro bumpers are auto-prepended/appended, and
+   every overlay that binds a `$brand:` token resolves against the kit. Edit the
+   kit, re-render, the whole video re-themes. You don't hand-paint brand colors
+   onto each clip.
+2. **Drive CueFrame directly.** Brand consistency is a first-class CueFrame
+   capability now. Don't reach for an external generator to "make it look
+   branded"; author the intent against the brand kit and let render
+   materialize it.
+
+Drive the primitives with the `cueframe-cli` skill and converge with
+`cueframe-compose-loop`; this tells you *what brand-demo to author*.
+
+Use the compose-loop [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+for iteration. Check brand/layout with stills and motion with `preview_clip`; a small revision
+does not require rerunning the Director or exporting the whole film. The pipeline below is for
+a new finished demo; choose the self-driven loop when the user has not asked for Director authoring.
+
+## The pipeline
+
+```
+extract brand (repo + live UI)  →  create_brand_kit
+   →  capture (screen-capture client: Playwright walkthrough of localhost → MP4)  →  import_media
+   →  get_media_context (faces + transcript)
+   →  apply_composition (edit plan + brand template, refs brandKitId + $brand:)
+   →  compose { fromComposition:true }  →  wait_job kind:compose
+   →  create_render  →  wait_job kind:render  →  branded MP4
+```
+
+## 1. Extract the brand → `create_brand_kit`
+
+You are running in the user's project. Read the brand out of the codebase
+instead of asking for it:
+
+- **Colors** — `tailwind.config.*` `theme.extend.colors`, CSS custom properties
+  (`:root { --primary … }`), a `design.md` / tokens file, or the rendered UI.
+- **Fonts** — `@font-face` / `next/font` / `<link>` declarations, the Tailwind
+  `fontFamily` map, and which family is headings vs body.
+- **Logo** — `public/`/`assets/` SVG/PNG; host it at a public https URL (or
+  `import_media` it and use the resulting URL) so render can fetch it.
+- **Spacing / sizing / radius** — the Tailwind scale, `--radius`, base font sizes.
+- **Voice** — README / landing copy → a one-paragraph `voiceGuidelines`.
+
+Synthesize and call `create_brand_kit`. The accepted shape (Phase 1 — the kit now
+carries full brand identity, not just colors/fonts):
+
+```jsonc
+{
+  "kitId": "acme",                 // caller-chosen stable id (re-POST upserts in place)
+  "name": "Acme",
+  "tagline": "Ship faster",
+  "colors": {                       // REQUIRED — all five
+    "primary": "#4F46E5", "secondary": "#0EA5E9", "accent": "#22C55E",
+    "background": "#0B0B0F", "text": "#FAFAFA"
+  },
+  "headingFont": { "fontFamily": "Geist", "fontWeight": 700 },
+  "bodyFont":    { "fontFamily": "Inter", "fontWeight": 400 },
+  "voiceGuidelines": "Confident, plain-spoken, no hype.",
+  "motion":    { "duration": 0.4, "easing": "ease-out", "entrance": "stagger-up", "staggerMs": 60 },
+  "logo":      { "src": "https://…/logo.svg", "placement": "br", "sizePct": 8 },
+  "intro":     { "kind": "card", "title": "Acme", "subtitle": "Ship faster", "durationMs": 1500 },
+  "outro":     { "kind": "card", "title": "acme.dev", "durationMs": 2000 },
+  "watermark": { "src": "https://…/mark.svg", "opacity": 0.6, "placement": "br" },
+  "spacing":   { "base": 16, "lg": 32, "sm": 8 },
+  "sizing":    { "fontSizeHeading": 64, "fontSizeBody": 28, "borderRadius": 12 }
+}
+```
+
+`colors{primary,secondary,accent,background,text}`, `headingFont`, `bodyFont`,
+`name`, `kitId` are required; everything else is optional. The response returns the
+kit `id` — that's the `brandKitId` you'll reference. **Show the founder the
+synthesized kit and let them override** before composing; the kit is the brand
+contract for every clip.
+
+## 2. Capture → one clean MP4
+
+Record a walkthrough of the **running local app** with an external screen-capture
+client: a headed Playwright script drives `localhost` while a native screen
+recorder captures it, and you get one
+CFR / faststart MP4 plus the cursor/click events (timed viewport coordinates —
+the focus points the auto-zoom follows; see `cueframe-product-video` §1–2). Use
+your codebase knowledge to script the walkthrough: open the real flows that
+matter, click the features worth showing, pause on results.
+
+Get the recording into CueFrame with `import_media` (public https URL) — it's
+async; poll `list_media` for `processingStatus:"ready"` (or register
+`create_webhook` on `media.completed`). Keep the click points; you'll map them onto
+the rendered duration for the zoom.
+
+## 3. Context → `get_media_context`
+
+`get_media_context` returns **faces** (subject roster + `speakingShare`, for any
+talking-head/presenter beat) and the **transcript** (per-word `start`/`end` for
+caption timing). Combine it with what you already know from the code — you can
+script and interpret the demo better than transcript-alone, because you know what
+each screen *is*.
+
+## 4. Author the seed composition → `apply_composition`
+
+Author the edit plan **and** the brand template in one composition, then reference
+the kit by `brandKitId`. Two layers:
+
+**a. The edit plan** (same craft as `cueframe-product-video`): the screen
+recording on a video track carrying `reframe` punch-ins from the click points
+(`autoZoom` output — `frame-center` in the gaps, `point` over each click),
+optional speed, and transcript-timed `captions`.
+
+**b. The brand template** — overlays that bind `$brand:` tokens so they resolve
+against the kit at render:
+
+| Goal | how |
+|---|---|
+| intro / outro card | **automatic** — the kit's `intro`/`outro` are prepended/appended at render. Don't author bumper clips. |
+| logo bug | **automatic** — the kit's `logo` is painted as a corner mark at render (placement/size from the kit; it lifts above the caption band). Don't author a logo overlay. |
+| lower-third / title | `lower-third` or `heroText` overlay, colors/fonts bound to `$brand:` tokens |
+| captions | top-level `captions` — themed by the kit's `captionProfile` + `syncCaptions` (don't bind `$brand:` in `captions.style`; captions resolve through the profile, not token refs) |
+| motion identity | overlays inherit `$brand:motion.*`; the kit's entrance/timing drive the feel |
+
+The `$brand:` vocabulary (the frozen token paths render resolves) — bind these,
+never hardcode brand hexes/fonts:
+
+- **colors** — `$brand:colors.{background,surface,card,text,textMuted,textOnMedia,border,accent,accentMuted,textOnAccent,textOnSurface}`.
+  Text **over footage** → `$brand:colors.textOnMedia` (the legible-over-video slot).
+- **fonts** — `$brand:fonts.heading.family`, `$brand:fonts.body.family`, `$brand:fonts.caption.family`.
+- **motion** — `$brand:motion.{duration,easing,entrance,staggerMs,exitMs}`.
+- **spacing / sizing** — `$brand:spacing.{base,lg,sm}`, `$brand:sizing.{fontSizeHeading,fontSizeBody,fontSizeLabel,borderRadius}`.
+
+An unset brand-driven slot on a text overlay auto-binds to its token (you don't
+have to spell out every one); spell out the ones you care about. A `$brand:` ref
+that doesn't resolve is **loud** in render logs and a contrast-critical text color
+falls to a legible neutral — it never silently ships an off-brand frame.
+
+Set `brandKitId` at the top of the composition. `apply_composition` with
+`dry_run:true` validates the batch without persisting — validate before you
+compose.
+
+### Worked example — branded seed composition (16:9)
+
+`brandKitId` ties the kit in; the intro/outro/logo come from the kit
+automatically (NOT authored here); the `lower-third` binds `$brand:` tokens and
+the `captions` are themed by the kit's `captionProfile`. Swap `<…>` for real ids;
+durations are illustrative — match your source.
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "16:9", "fps": 30 },
+  "brandKitId": "<brandKitId>",
+  "tracks": [
+    {
+      "id": "v-screen", "kind": "video", "contents": [
+        {
+          "id": "rec", "startTime": 0, "duration": 12,
+          "source": {
+            "kind": "media", "mediaId": "<screenMediaId>",
+            "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": "ov", "kind": "overlay", "contents": [
+        {
+          "id": "title", "startTime": 1, "duration": 3.5,
+          "source": {
+            "kind": "overlay", "primitiveId": "lower-third",
+            "params": {
+              "text": "One-command deploys", "subtitle": "Acme", "variant": "modern",
+              "tokens": {
+                "textColor": "$brand:colors.textOnMedia",
+                "accentColor": "$brand:colors.accent",
+                "fontFamily": "$brand:fonts.heading.family"
+              }
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "captions": {
+    "segments": [
+      { "words": [
+        { "text": "Ship",    "startMs": 0,    "endMs": 360 },
+        { "text": "in",      "startMs": 360,  "endMs": 520 },
+        { "text": "one",     "startMs": 520,  "endMs": 760, "emphasis": true },
+        { "text": "command", "startMs": 760,  "endMs": 1300 }
+      ] }
+    ]
+  }
+}
+```
+
+## 5. Refine + judge → `compose { fromComposition: true }`
+
+Hand the seed to the Director: `compose` with `{ fromComposition: true }`
+authors an ensemble of candidates from your seed, runs the **server-side judge —
+including the brand axis** (on-brand color/type/voice cohesion), and saves the
+winner. Returns a `composeJobId`; `wait_job` `kind:"compose"` (or a webhook on
+`compose.completed`). The result carries the winner's composite score — verification
+is built in. Pass your brief as `editorialIntent` so editorial is graded against
+what you meant. (To self-drive the loop instead, see `cueframe-compose-loop`.)
+
+## 6. Render → branded MP4
+
+`create_render` → `wait_job` `kind:"render"` (or a webhook on `render.completed`)
+for the download URL. The output is brand-frozen: the kit's **intro/outro** bumper
+the video, the **logo** bug sits in its corner, **motion** drives the overlay
+entrances, and every `$brand:` color/font is resolved. Verify the output (sample
+frames) before declaring done.
+
+## Notes / honesty
+
+- **The brand kit is the source of truth — edit it, re-render, re-theme.** Brand
+  values are resolved at render from the `brandKitId`-referenced kit, so a
+  `create_brand_kit` upsert (same `kitId`) re-themes every existing composition
+  that points at it. Don't bake brand hexes/fonts into clips.
+- **Intro / outro / logo are NOT clips you author** — they live on the kit and
+  the engine places them at render (intro prepended, outro appended, logo painted
+  as a corner mark). A srcless/absent bumper or logo reserves/draws nothing (soft)
+  — it's just skipped, never an error.
+- **`watermark` is accepted by `create_brand_kit` and persisted, but render does
+  NOT yet auto-composite the kit's watermark asset** (the only watermark painted
+  today is CueFrame's product mark). Set it for forward-compat, but custom
+  watermarks are not composited into the output yet — don't promise one.
+- **Drive CueFrame directly.** Everything downstream of the capture — the brand,
+  the compose, the render — is CueFrame. Reach for an external generator only for
+  footage CueFrame genuinely can't produce — not to "make it look branded,"
+  which is the engine's job now.
+- This recipe lives in a skill on purpose: the engine stays use-case-free; the
+  product opinions (what to extract, which overlays, how to brand) live here and
+  ship via `npx -y cueframe@0.5 install`.

package/skills/cueframe-brand-demo/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame — Brand demo recipe"
+  short_description: "Use when turning a local app into a brand-consistent product demo with…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-brand-demo when turning a local app into a brand-consistent product demo with CueFrame — extract the brand straight from the repo (colors/fonts/logo/motion), capture a Playwright walkthrough of the running app, and author a branded, auto-zoomed demo whose intro/outro/logo/colors/fonts/motion are frozen by CueFrame's engine — e.g. \"make an on-brand demo of my app\", \"record my localhost and produce a branded launch video\"."

package/skills/cueframe-brand-demo/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-cli/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: cueframe-cli
+description: Use when editing, clipping, or rendering video via the CueFrame CLI — e.g. "make a 9:16 short from this podcast", "pull the best moments out of this MP4", "render a clip", or any task that calls the `cueframe` binary. Also use when comparing CueFrame against direct-ffmpeg approaches.
+---
+
+# CueFrame CLI
+
+## MCP is the primary surface — read this before using the CLI
+
+**If you are an agent that can call tools, connect to CueFrame's MCP server instead of shelling
+out to this CLI.** MCP is the supported, maintained integration surface: it hides transport and
+contract details, its tools are generated from the same OpenAPI SSOT the CLI is, and it is where
+new capability lands first. The `cueframe-connect` skill owns the setup for every host
+(Claude Code, Claude/ChatGPT connectors, Cursor/Codex/VS Code/Windsurf/Zed, and the
+no-account pay-per-call path) — load it rather than copying a connection command from here.
+
+**Use this CLI when MCP is not available to you:** a terminal or CI job with no MCP host, a
+scripted batch, or a human at a shell. It is a first-class path, not a deprecated one — but it is
+the *second* thing to reach for.
+
+**Do not hand-roll `curl` against `/v1`.** Raw REST is the fallback beneath the fallback: it is
+where undocumented contract edges bite (components' runtime params were discovered that way), and
+both MCP and this CLI exist so you do not have to.
+
+## Overview
+
+The `cueframe` CLI drives the CueFrame platform from the terminal. Optimized for agents — every command supports `--json` (NDJSON event stream) and the binary self-describes via `npx -y cueframe@0.5 describe --json`.
+
+**Run it as `npx -y cueframe@0.5 …` — every command in this skill is written that way, and
+that form is executable verbatim.** There is no `cueframe` on your PATH unless you put it
+there: `npx -y cueframe@0.5 install` wires the MCP server and drops these skills, but npx
+unpacks to an ephemeral cache, so it installs no binary. `npx` re-resolves the current
+version on each call (~0.5s warm, ~5s cold), which also means these commands never go
+stale. If you are running many in a row and want to skip that, `npm i -g cueframe` once
+and drop the `npx -y ` prefix — but it needs a user-writable npm prefix (a default Linux
+install fails `EACCES` on `/usr/local/lib/node_modules`), so it is an optimization, not
+the documented path.
+
+**The framework is three verbs:** `upload` (register media) → `composition put` (author the timeline) → `render` (→ MP4). The `Composition` is the contract — render takes the saved composition, nothing else. Everything domain-specific (AI clip suggestions, FCPXML/Premiere export) is a **use-case on-ramp** layered on top, not part of the core.
+
+**Core principle — discover, don't guess.** Never author a composition from the
+examples below alone. The live contract is `npx -y cueframe@0.5 schema composition` (prints
+the real wire schema the server enforces); confirm any draft with
+`npx -y cueframe@0.5 composition validate -b @file.json` BEFORE you render. Validation is
+free and instant; a render is neither. The examples here are orientation — the
+schema is the source of truth.
+
+**Core principle:** once you are ON this path, drive everything through `cueframe` — never `curl` the v1 API around it, which invalidates the work and hides CLI bugs. (Choosing MCP over the CLI in the first place is not "going around it"; see the banner above.)
+
+## Framework workflow (upload → compose → render)
+
+The general path for any agent. Author the timeline yourself and render it — no
+clip suggestion required.
+
+For iteration, use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Validate first, then use `preview_card` / `preview_component` for isolated graphics,
+`preview_frame` for composition stills, or `preview_clip` for a motion window. Use the available
+MCP tools or the CLI's `api` escape hatch with the live request contract. Full `render` is for
+delivery, not checking each edit. CLI validation does not replace visual evidence.
+
+```bash
+# 0. Always use --json for agent-driven runs (NDJSON to stdout, no spinners).
+#    Commands run against production; auth is stored in ~/.cueframe/auth.json.
+
+# 1. Register media (one or many — mixed video / image / audio).
+npx -y cueframe@0.5 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
+
+# 2. Create a project (sets aspect/format).
+npx -y cueframe@0.5 project create -n "promo" -a 9:16 --json   # → projectId
+
+# 3. Author the composition: tracks of clips (per-clip reframe/trim), optional
+#    captions (captions.segments), brandKitId. The composition is the SSOT.
+#    Discover the live schema, then validate the draft BEFORE saving/rendering:
+npx -y cueframe@0.5 schema composition                                 # → live wire schema
+npx -y cueframe@0.5 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
+npx -y cueframe@0.5 composition put <projectId> -b @composition.json   # ETag auto
+
+# 4. Render the saved composition to MP4. SSE-watches + downloads when done.
+npx -y cueframe@0.5 render <projectId> -o ./out.mp4 --json
+# → render_queued → render_progress* → render_complete
+#
+# `render` takes ONLY a projectId and renders the SAVED composition (tracks +
+# captions). A clip suggestion is NOT required. Same project → same MP4 (idempotent).
+# Captions: render reads composition.captions — put caption words there to caption
+# a hand-authored composition; if absent, the clip is rendered without captions.
+
+# Reattach to an in-flight render later (e.g. after disconnect):
+npx -y cueframe@0.5 render watch <renderId> -p <projectId> -o ./out.mp4 --json
+```
+
+## Anatomy of a composition.json
+
+This section orients you to the shape; the authoritative contract is
+`npx -y cueframe@0.5 schema composition` (the live wire schema) — run it when a field is
+unclear, and `npx -y cueframe@0.5 composition validate -b @file.json` to check a draft.
+
+`composition put` takes the **bare** `Composition` object (no wrapper; the CLI POSTs
+the `@file` verbatim and handles the ETag). Minimal valid shape:
+
+```json
+{
+  "v": 1,
+  "format": { "aspectRatio": "9:16", "fps": 30 },
+  "tracks": [
+    { "id": "v1", "kind": "video", "contents": [
+      { "id": "c1", "startTime": 0, "duration": 10, "source": { "kind": "media", "mediaId": "<mediaId>" } }
+    ] }
+  ]
+}
+```
+
+- **Required**: `v: 1`, `format.aspectRatio` (`16:9` | `9:16` | `1:1` | `4:5`), `tracks`.
+- Tracks hold **`contents`** (not `clips`); each clip wraps a `source`. A clip's
+  `source.kind` must match the track `kind`: `media` → `video`/`image`/`audio`,
+  `overlay` → `overlay`, `effect` → `effect`.
+- `source.kind`s: `media` (`mediaId` + optional `trim`/`reframe`/`volume`), `overlay`
+  (`primitiveId` + `params` + optional `zPlane`), `effect` (`primitiveId` + `params`).
+- Times are **seconds** (`startTime`/`duration`/`trim`, and `reframe` `startSec`/`endSec`);
+  caption word times are **milliseconds**. `region`/`fit` (PiP/inset) are clip-level.
+- Clips on one track can't overlap — simultaneous layers go on separate tracks.
+- Optional top-level: `captions` (`segments[].words[]`), `brandKitId`, `markers`.
+
+For full per-video-type examples (auto-zoom demo, PiP, split-screen, captions,
+behind-subject title), see the `cueframe-product-video` skill.
+
+## Render resolves expensive intents automatically — author, don't pre-bake
+
+You author *intent* on the composition; `render` materializes the expensive
+artifacts it implies. Nothing to pre-bake, no compose step required:
+
+- An overlay with `"zPlane":"behind-subject"` → the person **matte** is baked
+  on-miss and the text is placed behind the speaker (shoulder-band anchor +
+  occlusion handled). Author it and render — it just works.
+- A clip whose `reframe.focus` is `{mode:"face",faceId}` / `{mode:"active-speaker"}`
+  / `{mode:"all-faces"}` → **subject detection** runs on-miss so the crop tracks the
+  real person. (`{mode:"point"}` / `{mode:"frame-center"}` need no detection.)
+
+During this the SSE `render_progress` phases read
+`resolving → baking-matte | detecting → rendering → complete` — the first behind/face
+render of a source pays a one-time bake (cached after; re-renders are fast).
+
+### Render error codes (fail-loud — render never ships a wrong frame silently)
+
+| `code` | meaning | fix |
+|---|---|---|
+| `media_not_found` | a referenced `mediaId` doesn't exist or isn't your org's | reference media you uploaded |
+| `media_not_ready` | the media has no file yet (still uploading/generating) | wait for `upload`'s `process_complete` |
+| `source_dims_unknown` | a `reframe` clip's source has no width/height/fps yet | let the source finish processing before authoring a reframe |
+| `content_anchor` | a clip's trim frames *different* footage than its captions show (wrong-footage) | align the trim window to the captioned moment |
+| `behind_split_unsupported` | one media used under two *different* behind-subject windows | one behind window per media (split into separate clips/media) |
+| `BehindMatteUnresolved` / `TrajectoryUnresolved` | the matte/detection bake produced no result for a behind/face clip | the source may have no detectable person; retry, or drop the behind/face intent |
+
+## Clip-suggestion on-ramp ("podcast → short clip")
+
+ONE use-case layered on the framework: the AI clip-finder picks a moment and
+**authors a composition for you** (trim + speaker framing + captions sliced from
+the transcript). Use it when you want CueFrame to choose the clip; otherwise author
+the composition yourself (above).
+
+```bash
+# 1. Upload + chain the AI clip pass.
+npx -y cueframe@0.5 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
+# (or run it explicitly: npx -y cueframe@0.5 analyze <mediaItemId> --wait --json)
+
+# 2. List clip suggestions (publicId sug_…, title, startMs/endMs, score).
+npx -y cueframe@0.5 clips <mediaItemId> --json
+
+# 3. Create a project AND author its composition from the chosen suggestion.
+npx -y cueframe@0.5 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
+#   (or, on an existing project: npx -y cueframe@0.5 composition from-suggestion <projectId> -s <sug_…>)
+
+# 4. Render — same framework verb as above.
+npx -y cueframe@0.5 render <projectId> -o ./out.mp4 --json
+```
+
+Both flows converge on `composition put` → `render`; the on-ramp just authors the
+composition from a suggestion instead of you hand-writing it.
+
+Pipe `--json` output through `jq -c 'select(.event=="…")'` to grab specific lifecycle events.
+
+## Component authoring — fork a built-in primitive or scaffold your own
+
+Own the motion-graphics components you render (shadcn-style): fork a built-in CueFrame
+primitive as editable source, customize it, and render it on CueFrame — or scaffold a blank
+one. The source lives in your repo under version control; CueFrame bakes it to a transparent
+video and composites it (the shared renderer never runs your code).
+
+```bash
+# 1. Scaffold a workspace (writes cueframe.json + cueframe/components/). Idempotent.
+npx -y cueframe@0.5 init --json
+
+# 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
+npx -y cueframe@0.5 new component my-badge --json
+
+# 2b. …or FORK a built-in: discover ids from the catalog (npx -y cueframe@0.5 api GET /v1/components),
+#     fetch that primitive's source with the `get_component_source` tool, and paste it into
+#     cueframe/components/my-badge/index.tsx as your starting point.
+
+# 3. Edit cueframe/components/<id>/ — it's standard Remotion. The component is mounted
+#    ({ durationInFrames, params, assets, render }) at render; declare its v2 manifest.
+
+# 4. Publish to CueFrame so it can render (uploads index.tsx as the component's tsxSource).
+npx -y cueframe@0.5 push my-badge --json            # one component
+npx -y cueframe@0.5 sync --json                      # every component in the workspace
+
+# 5. Reference the component id in your composition as a {kind:'component', componentId, props}
+#    clip, then render with the same verb. Preview a single component first via the MCP
+#    preview_component loop.
+npx -y cueframe@0.5 render <projectId> -o ./out.mp4 --json
+```
+
+## Quick reference
+
+| Need to… | Command |
+|---|---|
+| See every command + flags | `npx -y cueframe@0.5 describe --json` |
+| Install/refresh managed skills | `npx -y cueframe@0.5 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
+| List projects | `npx -y cueframe@0.5 list -n 50` |
+| List your media | `npx -y cueframe@0.5 clips` (no mediaId arg) |
+| Discover the live composition schema | `npx -y cueframe@0.5 schema composition` |
+| Validate a draft (no save, no render) | `npx -y cueframe@0.5 composition validate -b @plan.json` |
+| Read composition + ETag | `npx -y cueframe@0.5 composition get <projectId> --json` |
+| Write composition | `npx -y cueframe@0.5 composition put <projectId> -b @plan.json` (ETag auto) |
+| Export to Final Cut | `npx -y cueframe@0.5 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
+| Export to Premiere | `npx -y cueframe@0.5 export premiere <projectId> -s <sug> --wait -o cut.zip` |
+| Anything not wrapped | `npx -y cueframe@0.5 api GET /v1/...  -i` (escape hatch, like `gh api`) |
+| Validate a composition without mutating | `npx -y cueframe@0.5 composition validate -b @plan.json` |
+
+## Auth
+
+Commands run against production. Authenticate once:
+
+- `npx -y cueframe@0.5 login` — OAuth device flow (laptops).
+- `npx -y cueframe@0.5 auth <cf_live_… key>` — save a static API key (CI / headless).
+
+Creds are stored in `~/.cueframe/auth.json`; the key can also come from the `CUEFRAME_API_KEY` env var.
+
+## NDJSON event shape
+
+Every `--json` line:
+```json
+{"_":0,"schemaVersion":"v1","ts":1779250551614,"event":"<verb>_<phase>", ...payload}
+```
+Phase lifecycle: `<verb>_prepare` → `<verb>_ready` → `<verb>_progress` (0+) → `<verb>_complete` | `error`. The `_:0` field is a pino formatter placeholder — ignore it.
+
+Errors come as `{"event":"error", "phase":"<step>", "message":"...", "code":"...", "exitCode":N}` *and* a non-zero process exit. Read both.
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `npx -y cueframe@0.5 api METHOD /v1/...` — same auth, same JSON pipeline. |
+| Polling for render completion with a sleep loop | `npx -y cueframe@0.5 render` already SSE-watches and exits when done. Use `render watch <id>` to reattach. |
+| Skipping `--json` and trying to parse human output | Human output is for humans. Agents always use `--json`. |
+| Hand-editing the composition without an ETag | `composition put` GETs the ETag for you; `from-suggestion` rebuilds from a clip. Don't hand-craft unless you have to. |
+| Calling `npx -y cueframe@0.5 render <projectId> <suggestionId>` (old two-positional shape) | `render` takes ONLY a projectId; commander rejects the extra arg. It renders the SAVED composition — author it first via `composition put` (hand-author) or `project create --from-suggestion <sug>` (clip-finder on-ramp). |
+| Assuming `render` needs a clip suggestion / that captions only come from a suggestion | No — `render` renders the saved composition directly; a suggestion is optional. Captions come from `composition.captions` (author them in the `put` JSON). The clip-suggestion on-ramp just fills those captions for you by slicing the transcript at author time. |
+
+## When this skill applies (routing)
+
+Route on **intent, not operation**. This is the path whenever the task is *creating a video* — captioning, reframing or keeping a subject framed, finding the best moment, composing or branding clips, rendering to a target aspect/format. A mechanical verb ("trim", "concat") *inside* a creative goal ("…into a captioned 9:16 short") is still this skill — CueFrame does the trim too. If a task is part mechanical and part creative, it's this skill. When unsure whether a video task needs CueFrame, it does — author it here; validate cost-free with `--dry-run` first.
+
+Drop to raw `ffmpeg` only for a **single mechanical operation with zero creative or perceptual intent** — losslessly concatenating two finished files, transcoding a codec, extracting an audio track. That one carve-out aside, reach for `cueframe`.
+
+Not this skill at all: inspecting internal backend state (that has its own operator tooling); changing the CLI's own source (that's CLI development, not usage).

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame CLI"
+  short_description: "Use when editing, clipping, or rendering video via the CueFrame CLI — e.g.…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-cli when editing, clipping, or rendering video via the CueFrame CLI — e.g. \"make a 9:16 short from this podcast\", \"pull the best moments out of this MP4\", \"render a clip\", or any task that calls the `cueframe` binary."

package/skills/cueframe-cli/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>