@cueframe/skills 0.1.0

package/skills/cueframe-component-authoring/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: cueframe-component-authoring
+description: Use when authoring, forking, or customizing a CueFrame motion-graphics component/primitive/graphic — e.g. "customize the cinematic-title primitive", "make my own animated lower-third", "fork a CueFrame template and edit it", "author a custom graphic and render it". Covers cloud MCP, local desktop, and CLI project paths through the same component-v2 contract. Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
+---
+
+# CueFrame component authoring (fork / customize / own)
+
+Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
+to select hosted or local evidence and separate iteration from final delivery.
+
+CueFrame ships 87 built-in motion-graphics **primitives** (titles, lower-thirds, captions,
+effects, transitions, scenes). You can **fork any of them as editable source**, customize it,
+and render it on CueFrame — or author a brand-new component. This is shadcn-for-video: own the
+component code; CueFrame is the reliable engine that renders it.
+
+**Before you hand-write 3D:** a device mockup or a screenshot floating in a lit 3D scene is a
+**scene shot** — validated JSON with `scene.add` / `scene.update`, not a component you author.
+See the `cueframe-scene-shot` skill and `cueframe://scene-shot`. Author a component here when
+you need behaviour the scene contract does not express.
+
+**The two facts that shape everything:**
+- A component is mounted through contract v2 as
+  **`({ durationInFrames, params, assets, render }) => JSX`**. `render` contains frame, fps,
+  dimensions, deterministic seed, and color space. A from-scratch component must default-export
+  this shape; older components may ignore the added properties.
+- Neither renderer runs authored component source in the editor process. Hosted org components are
+  baked in an isolated box. A local project compiles source in a separate headless-Chromium child
+  process, pins the immutable source version in the project, and uses that version for the editor and export.
+
+## Path A — MCP agent (no filesystem; source lives server-side)
+
+Single self-contained module per component (`create_component` takes one `tsxSource`).
+
+1. **Fork a built-in:** `get_component_source(componentId: "cinematic-title")` → returns the
+   primitive's editable single-module `tsxSource` (the named component + the adapter). Discover
+   ids from the catalog (`/v1/components`). *(Or author from scratch — skip to step 2.)*
+2. **Author/own it:** edit the `tsxSource`, declare its v2 `manifest`, then call
+   `create_component({ componentId, tsxSource, manifest, … })` to store your customer-owned copy.
+   If forked, `ejectedFrom` is stamped.
+3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` queues a durable
+   preview and returns a `jobId`; call `wait_job(kind:"preview")`. The typed terminal result is a
+   verified artifact produced by the same bundle contract used by final render. A failed
+   `component_does_not_compile` job carries the compiler error — read it, fix via `update_component`
+   (same id, in place), and preview again.
+   **Once the component is placed in a project, pass that project on every update:**
+   `update_component({ componentId, body: { tsxSource, projectId, compositionId? } })`. A placed clip
+   renders the exact version it pins; only the composition you name moves to the new version in the
+   same write (`repinned` says what moved). Without `projectId` your clips keep rendering the old
+   version, and `placementsPinnedToPrevious` counts them.
+   Set preview duration deliberately: `durationInFrames` is not a trim window and can retime
+   duration-dependent motion. Preserve production timing; inspect the live tool's request shape.
+4. **Check integration:** add it as a `{kind:'component', componentId, props}` clip
+   (`apply_composition`), then inspect saved-composition stills or a scoped `preview_clip` for
+   placement and motion. Use `create_render` → `wait_job kind:"render"` when delivering a
+   finished MP4, not per tweak.
+
+## Path B — CLI / coding agent (customer-owned source under git)
+
+Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit locally as
+standard Remotion, push to render.
+
+```bash
+npx -y cueframe@0.5 init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe@0.5 new component my-badge --json     # scaffold a component in the workspace
+#   to start from a built-in instead of a blank file: fetch its source with the
+#   `get_component_source` tool and paste it into cueframe/components/my-badge/index.tsx
+# …edit cueframe/components/<id>/ in your editor (standard Remotion)…
+npx -y cueframe@0.5 push my-badge --json              # upload index.tsx as the component tsxSource
+#   or: npx -y cueframe@0.5 sync --json               # push every component in the workspace
+# reference the component id in your composition, then render:
+npx -y cueframe@0.5 render <projectId> -o ./out.mp4 --json
+```
+
+The CLI writes a 3-file layout (`index.tsx` = renderable module + adapter; `_config.ts` + `config.ts`
+= local workspace metadata). `push` sends `index.tsx` as the single `tsxSource` — the same shape the
+MCP path stores. To preview before a full render, push it and use the MCP `preview_component` loop.
+
+## Path C — Director editing a local desktop project (project-embedded source)
+
+When `get_context` reports the project lane as local, motion does not require an account or an org
+component. When exposed, use `open_component_preview` to compile an isolated preview (new source,
+or `component_id` for a component already in the desktop's library), `update_component_preview`
+with exact-text edits (`{oldText, newText, replaceAll?}`, each `oldText` matching once), and
+`render_component_preview_frame` for exact frame evidence. Inspect playback for motion;
+`commit_component_preview` publishes the checked source to the library and pins the clip, with a
+fresh ETag. `read_component` and `edit_component` read and edit the library directly. Close the preview when finished. This loop does not bake a timeline video and
+does not imply HMR: source updates still compile.
+
+If those tools are unavailable, add/update through `apply_composition` and inspect the local
+timeline. An inline custom overlay has this shape:
+
+```json
+{
+  "type": "clip.add",
+  "clip": {
+    "id": "local-motion",
+    "kind": "overlay",
+    "startTime": 0,
+    "duration": 3,
+    "source": {
+      "kind": "overlay",
+      "primitiveId": "custom",
+      "params": {
+        "jsxSource": "export default function Graphic({ durationInFrames, params, assets, render }) { ... }",
+        "componentManifest": { "version": 2, "assets": {}, "graphics": { "api": "canvas2d", "required": true, "accelerationPreference": "software-allowed" }, "alphaPolicy": "requires-transparency" },
+        "componentAssets": {}
+      }
+    }
+  },
+  "newTrack": true
+}
+```
+
+The desktop compiles the module in an isolated child process and creates it in the desktop's component
+library. Inline source creates a component only: a clip whose component already exists with other
+source is refused as `component_exists`, and that component changes through edits.
+The timeline and final export render that exact version; no preview media is baked. A compile failure
+refuses the whole batch and leaves the composition untouched. Use `create_component` only for a reusable
+org-catalog component on a reachable cloud lane.
+
+For media-backed graphics, declare each slot in `componentManifest.assets`, bind the slot to a
+project media id in `componentAssets`, and read its request-scoped handle from `assets`. The renderer
+localizes and hashes the file before execution. Remote URLs, undeclared assets, arbitrary filesystem
+paths, WebGL substitution, and static/card substitution are not fallback paths.
+
+Declare `componentManifest.alphaPolicy` explicitly: `requires-transparency` for overlays and
+`allows-opaque` for intentional full-frame plates. Both adapters verify the same field.
+
+Normal static imports are supported only from the runtime allowlist: React, Remotion, Three.js
+WebGPU/TSL, React Three Fiber/Drei, Remotion Three, and CueFrame animation helpers. Use ordinary hooks,
+loops, refs, constructors, typed arrays, canvas, and WebGPU when needed. Drive visible animation from
+`render.frame`/`render.fps` and seed variation from `render.seed`; ambient time/randomness is refused.
+
+## Choosing what to fork
+The catalog (`/v1/components`) gives each primitive's `description` / `useWhen` / `tags` / `mood` /
+`tier` / `useCase` / `examples` (example params) + `propSchema` + its source via `get_component_source`.
+Read the spec + the code to pick a starting point. (Rendered preview thumbnails are a separate
+follow-up — today you choose from prose + params + source, or compose+`preview_frame` to see it.)
+
+## Layout inside a component — `FlexLayout` / `solveFlex`
+When a graphic has several cells that must share space — a feature grid, a fixed rail beside
+fluid content, a cast of objects next to type — don't hand-place pixels. The layout helpers
+are in `@cueframe/animate` (on the import allowlist):
+
+```tsx
+import { FlexLayout } from '@cueframe/animate';
+const R = params.region ?? { x: 0, y: 0, w: 1, h: 1 };
+<FlexLayout
+  tracks={[{ weight: 0, basis: 520 }, 1, { weight: 3, split: [1, 1] }]}
+  tracksEnd={[{ weight: 0, basis: 520 }, 1, { weight: 1, split: [2, 1] }]}
+  fits={[{ mode: 'stretch' }, { mode: 'position' }, { mode: 'matte', aspect: 1 }, { mode: 'stretch' }]}
+  gap={16} width={R.w * width} height={R.h * height}>
+  <Rail /> <Type /> <Art /> <Block />
+</FlexLayout>
+```
+
+- Tracks are **weights, not pixels**; `{ weight: 0, basis: 520 }` is content-sized and pushes its
+  neighbours. Children fill the leaves depth-first (a `split` nests cells on the other axis).
+- `tracksEnd` animates: weights ease across the clip and **every cell re-solves per frame**. A cell
+  present on only one side enters from / exits to zero. Layout is the motion — no keyframed positions.
+- `fits`, one per leaf: `stretch | contain | cover | position | scale | matte`. `position` keeps type at
+  its natural size; `matte` clips a window instead of resizing the art.
+- Inside a `params.region` container pass `width`/`height` = the region's pixel size so nested splits and
+  aspect fits solve against the region, not the frame. **Never CSS-`scale()` the layout** — it resamples;
+  size the container instead.
+- 3D in the same rig: `solveFlex(tree, size, weights)` returns the boxes; `flexBoxToThree(box, size)`
+  centres a mesh under `<ThreeCanvas orthographic>` (frustum pinned 1:1 to pixels), so one canvas holds
+  every object exactly on its cell.
+- Same inputs, same boxes everywhere: the solve is pure and yoga-backed; nothing is measured from the DOM.
+  Text is placed, not measured — declare sizes with `basis` when a cell must fit its content.
+
+## Don't
+- Don't expect a forked primitive to use rich named props — read `params` inside and use the explicit
+  `assets` and `render` bags for media and frame state.
+- Don't hand-roll a graphic from zero when a built-in is close — fork it (fetch the source with
+  `get_component_source`, paste it into a `npx -y cueframe@0.5 new component` scaffold) and edit.
+- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.
+- Don't update a placed component without its `projectId` in the body — the placed clips keep the
+  version they pin, so the next preview or render shows the old graphic.

package/skills/cueframe-component-authoring/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame component authoring (fork / customize / own)"
+  short_description: "Use when authoring, forking, or customizing a CueFrame motion-graphics…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-component-authoring when authoring, forking, or customizing a CueFrame motion-graphics component/primitive/graphic — e.g. \"customize the cinematic-title primitive\", \"make my own animated lower-third\", \"fork a CueFrame template and edit it\", \"author a custom graphic and render it\"."

package/skills/cueframe-component-authoring/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-compose-loop/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: cueframe-compose-loop
+description: Use when an AI agent should DRIVE CueFrame to a high-quality clip itself — author a composition, look at rendered frames, score it with CueFrame's judge, fix the weakest thing, and repeat until it's good — e.g. "turn this source into a polished 9:16 clip", "compose and self-correct until it scores well". This is the agent-driven convergence loop over the CueFrame primitives in the `cueframe-cli` skill.
+---
+
+# CueFrame — Compose convergence loop
+
+You are the director. CueFrame gives you hands (author), eyes (capture), and a
+judge (verify); you supply the taste and the iteration. The engine does NOT
+auto-compose for you here — you drive the loop and decide when it's done. Drive
+the primitives with the `cueframe-cli` skill; this tells you *how to converge*.
+
+Before choosing a preview or export, read [preview-workflow.md](references/preview-workflow.md).
+It owns hosted/local routing, bounded motion evidence, and the distinction between a small edit
+and final delivery. For a minor revision, keep the approved brief and inspect the changed behavior
+plus relevant regressions; do not restart the full planning/judging loop below.
+
+## The loop
+
+```
+get_context  →  author  →  scoped preview (look)  →  judge if useful
+                   ↑                                      │
+                   └──────── fix the WORST criterion ──────┘  → stop → render
+```
+
+Hosted preview and scoring are durable, stateless jobs. Keep their job IDs and
+wait for each terminal result; there is no hosted render box to open, warm, or close.
+Use the local live-preview tools when working in a desktop project that exposes them.
+
+## 0. Context — always first
+
+`GET /v1/media/:id/context` (`cueframe_api_getMediaContext`) returns what you need
+to author well for a source:
+
+- **faces** — the subject roster per source window: `faceId` (face-0 = largest/
+  primary speaker), normalized `bbox`, `speakingShare` (0–1). Use these to aim
+  reframe/crop intents at the right subject. `faces.status: "not_detected"` means
+  no detection has run yet — author without face-targeted reframe, or trigger a
+  pass first; never invent face ids.
+- **transcript** — utterances with per-word `start`/`end` (seconds). Use for
+  caption timing and for placing overlays on the right beat.
+
+## 1. Author
+
+Build/modify the working composition with the op vocabulary —
+`cueframe_api_applyCompositionOp` (one op) or `putComposition` (whole). Op keys
+are `.strict()`: a typo'd key is rejected, not silently dropped, so read the
+error and fix the key. Reference faces from get_context in your reframe segments;
+time captions/overlays from the transcript word timings.
+
+## 2. Preview — look at it
+
+Use the curated `preview_frame` MCP tool, or
+`POST /v1/projects/:id/preview-frame-jobs`, with the composition target and the
+timestamps you need to inspect. The operation returns `{ jobId }` immediately.
+Call `wait_job({ kind: "preview_frame", id: jobId })`, then view the image artifact
+URLs in the successful result. Look at the beats you're unsure about: a cut, an
+overlay entrance, or the hook. The stills are real render evidence, not continuous-motion proof.
+Use `preview_clip` for the affected composition window to judge cuts, entrances, camera movement,
+and audio timing; use `preview_component` or `preview_card` for isolated authoring checks.
+
+## 3. Score it
+
+Use `score_composition`, or `POST /v1/projects/:id/score-composition`, with the
+composition target plus optional `editorialIntent` and `brandContext`. It returns
+`{ jobId }`; call `wait_job({ kind: "verify", jobId })`. CueFrame's judge samples
+the meaningful beats, renders them, and returns:
+
+```
+{ perCriterion: { editorial, spatial, brand, caption } each { score 0–10, critique },
+  composite,        // weighted overall
+  critique,         // worst-first, leads with the criterion to fix
+  beats }
+```
+
+The four criteria:
+
+| criterion | what it grades |
+|---|---|
+| **editorial** | does the framing/cut serve the stated intent (the hook, the point)? |
+| **spatial**   | subject framing — centered/tight enough, not lost in dead space, not occluded by captions |
+| **brand**     | on-brand color/typography/voice; cohesive look |
+| **caption**   | caption legibility, timing, placement (or `no_captions` when absent) |
+
+You get **scores and the critique, never the rubric** — the taste is CueFrame's.
+Pass `editorialIntent` (your brief/hook) so editorial is graded against what you
+meant.
+
+## 4. Fix the worst — then re-score
+
+Read `critique` — it names the lowest criterion first and says why. Fix **that one
+thing** (re-author the relevant ops), then score again. One criterion per pass:
+chasing all four at once thrashes. Example: editorial 4 "two subjects off-center
+vs centered intent" → tighten the reframe onto face-0 → re-score. A layout critique
+("cramped", "unbalanced", "text crowds the art") on a component built with
+`FlexLayout` is a `tracks` weight or `fits` change — re-author those and re-solve; never
+nudge pixels (see `cueframe-component-authoring`).
+
+## 5. Stop — then render
+
+For a whole-film review, use **composite ≥ ~7.5** as a guide alongside the brief's actual
+acceptance criteria. Two no-improvement passes are a reason to stop spending and report what
+remains, not to declare a rejected result approved. Render with `create_render` only when a
+finished video is requested or the work reaches final delivery. A scoped revision can end with
+verified preview evidence and an explicit note that no new final export was made.
+
+## Notes
+
+- **Whose tokens:** you run this loop on your own model/tokens; CueFrame bills the
+  infra (capture/render) + the judge. That's the point — you keep the orchestration.
+- **Don't re-derive the judge or beat sampling** — verify owns both. Your job is
+  author → read scores → fix worst → repeat.
+- **Budget the loop:** 3–5 scoring passes is plenty for most clips. If composite
+  won't climb, the limiter is usually the source or the intent, not more passes.

package/skills/cueframe-compose-loop/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CueFrame — Compose convergence loop"
+  short_description: "Use when an AI agent should DRIVE CueFrame to a high-quality clip itself…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-compose-loop when an AI agent should DRIVE CueFrame to a high-quality clip itself — author a composition, look at rendered frames, score it with CueFrame's judge, fix the weakest thing, and repeat until it's good — e.g. \"turn this source into a polished 9:16 clip\", \"compose and self-correct until it scores well\"."

package/skills/cueframe-compose-loop/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-compose-loop/references/preview-workflow.md

@@ -0,0 +1,37 @@
+# Preview, iteration, and delivery
+
+Choose the evidence for the current request. A small revision is not a new-film workflow. Preserve the approved brief, timeline, and unaffected source; inspect the affected behavior and relevant regressions. Export when the user requests a finished video or the work reaches final delivery, not after every preview or parameter edit.
+
+## Select the available lane
+
+Read the current tool contracts and project context. Do not infer a hosted session from a local desktop tool, or require cloud registration for a local project.
+
+| Need | Hosted evidence | Local desktop evidence, when exposed |
+|---|---|---|
+| Isolated HTML card layout | `preview_card` with the card's HTML and tokens | Inspect the card in the local project |
+| Authored component layout or motion | `preview_component`, with explicit dimensions, FPS, params, assets, and appropriate duration | `open_component_preview` → `update_component_preview` (exact-text edits); inspect playback and `render_component_preview_frame` at exact frames |
+| Saved composition layout and overlap | `preview_frame`, batching the needed timestamps | The local composition preview/capture tools |
+| Cuts, entrances, camera motion, or audio timing | `preview_clip` for the affected `[fromSec, toSec)` window, including its lead-in and settle | Play/seek the affected window; capture matching frames when needed |
+| Finished deliverable | `create_render` and verify the resulting file | The project's export path and verification of its resulting file |
+
+Hosted calls use `projectId` and the request shape declared by the live tool. `preview_component` returns a job ID: wait with `kind:"preview"`. `preview_frame` uses `kind:"preview_frame"`. `preview_clip` returns a render job: wait with `kind:"render"`, even though it is a preview. Reuse the returned job ID; do not submit duplicate jobs while waiting. Hosted evidence jobs do not require opening or warming a compose session.
+
+The local component preview compiles replacement source revisions; it is not a promise of browser HMR or zero compilation work. `commit_component_preview` commits the inspected revision with a fresh project ETag. An isolated preview does not itself edit the saved timeline. Close the preview when finished if that tool is available.
+
+## Bound the work without changing the animation
+
+- Use a component's existing params for supported changes; update its source in place only when necessary. Do not create a new component ID for each tweak.
+- `durationInFrames` sets the component's render duration; it is **not a generic trim window**. Shortening it can retime animations normalized over duration. Preserve production timing. Use a documented component-specific offset only if it preserves that timing, or use the saved composition's `preview_clip` window. `startFrame` is not a universal preview API parameter.
+- Preserve FPS when judging motion. Choose resolution for the question: a low-resolution motion preview may establish timing but not typography, glass edges, or final-resolution shader quality. Use appropriate stills for those details.
+- Batch related still timestamps. Build contact sheets from returned images for inspection; a grid is a presentation of sampled frames, not proof of continuous motion. Watch the critical window as well. Listen when the change affects sound.
+- Scope output and compute are different: a short composition preview can still trigger preparation or an alpha bake on a cache miss. Inspect progress/receipts before diagnosing cost. Do not promise instant previews, cross-job cache hits, or that every requested still requires a full bake.
+
+## Evidence and stopping
+
+Keep component source revision/hash, params, asset bindings, dimensions, FPS, requested frames/window, and returned artifact/job identity together. For hosted composition parity, inspect `previewed.source`, composition ID, and ETag where provided. Source can change without changing the composition ETag. Unchanged pixels outside an edit's visible frame range do not by themselves prove a stale cache.
+
+Compare affected frames and motion with the reference at matching timestamps. Keep isolated-component proof distinct from saved-composition proof and final-export proof. For a minor edit, stop once the requested behavior and relevant regressions are checked; report the preview and explicitly say if no new final export was made.
+
+Use `score_composition` for broader editorial/brand review when useful and within budget. Do not require repeated whole-film judging to verify a known local correction. A judge score does not override a failed acceptance criterion or the user's visual feedback.
+
+Check account balance and current quotes before metered hosted work. Record actual job charges separately for preview, judging, and final export; separate those from agent time/token cost and from infrastructure estimates. Compare workflows only after testing equivalent changes and evidence requirements. Existing previews should be exercised before proposing new infrastructure.

package/skills/cueframe-connect/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: cueframe-connect
+description: Use when CueFrame is not connected yet, the user asks how to connect or authenticate CueFrame, or another CueFrame skill is about to call a tool and needs the one-time setup path for Claude Code, Claude, ChatGPT, Cursor, Codex, VS Code, Windsurf, Zed, Antigravity CLI, Copilot CLI, or an x402 wallet.
+---
+
+# Connect CueFrame
+
+Connect only when the first CueFrame tool call is imminent. Setup is a short detour, not a phase;
+resume the user's original task immediately afterward.
+
+- **Claude Code:** offer to run
+  `claude mcp add --transport http cueframe https://api.cueframe.ai/v1/mcp` — a browser
+  opens and the user clicks **Allow**. No API key.
+- **Claude.ai / Claude Desktop:** Settings → Connectors → add a custom connector with
+  `https://api.cueframe.ai/v1/mcp`.
+- **Other agents (Cursor, Codex, VS Code, Windsurf, Zed, Antigravity CLI, Copilot CLI, …):**
+  run `npx -y cueframe@0.5 install` — it detects what is on the machine and wires each one.
+- **ChatGPT:** the CLI cannot wire it because there is no local config to write; add
+  `https://api.cueframe.ai/v1/mcp` as a custom connector instead.
+- **No account (pay per call):** connect
+  `https://api.cueframe.ai/v1/mcp/x402` — no sign-up or API key; priced calls settle
+  per call in USDC over x402 from the agent's wallet.
+
+Do not ask the user to configure a model provider for CueFrame. This connection exposes CueFrame's
+tools; the host agent keeps using its already-selected CueFrame Gateway, BYOK, or local model.
+
+## Then confirm it works, before you plan anything
+
+Connected is not the same as working, and finding out at the first *paid* call is the expensive
+way. Two free read-only calls prove the whole path:
+
+1. **Discover the surface.** List the tools your host now exposes. You should see the compose loop
+   (`new_composition`, `apply_composition`, `validate_composition`, `create_render`) alongside
+   discovery reads (`list_catalog`, `list_media`, `get_account`). There are also resources
+   (`cueframe://scene-shot` for 3D product shots) and workflow prompts — a flat tool list is not
+   the whole surface.
+2. **Smoke-call `get_account`.** It takes no arguments, costs nothing, and answers the questions
+   worth knowing before you spend: which org the key is bound to, the plan, per-feature
+   entitlements and — the one that matters — `balance`, not `included`. CueFrame is credit-funded,
+   so rendering, generation, preview stills, the judge and the Director all draw on ONE shared
+   wallet. If `get_account` returns, authentication, routing and scope are all proven.
+
+If a later call fails on scope, the error names the exact missing permission (for example
+`billing:read`, which `get_usage` needs and a creative-only key will not have). Mint a key with
+that scope rather than guessing at the surface.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Connect CueFrame"
+  short_description: "Use when CueFrame is not connected yet, the user asks how to connect or…"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  default_prompt: "Use $cueframe-connect when CueFrame is not connected yet, the user asks how to connect or authenticate CueFrame, or another CueFrame skill is about to call a tool and needs the one-time setup path for Claude Code, Claude, ChatGPT, Cursor, Codex, VS Code, Windsurf, Zed, Antigravity CLI, Copilot CLI, or an x402 wallet."

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