cueframe 0.1.0 → 0.1.2

package/skills/cueframe-brand-demo/SKILL.md

@@ -0,0 +1,248 @@
+---
+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
+
+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 — Vaaya-free.** 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*.
+
+## The pipeline
+
+```
+extract brand (repo + live UI)  →  create_brand_kit
+   →  capture (Kishu: Playwright walkthrough of localhost → MP4)  →  import_media
+   →  get_media_context (faces + transcript)
+   →  apply_composition (edit plan + brand template, refs brandKitId + $brand:)
+   →  create_composition { 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 Kishu: a headed Playwright
+script drives `localhost`, native screen-record 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.ready`). 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 → `create_composition { fromComposition: true }`
+
+Hand the seed to the Director: `create_composition` 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.complete`). 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.complete`)
+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 don't promise
+  the founder a custom watermark in the output yet.
+- **Drive CueFrame directly.** This whole recipe is Vaaya-free: the brand, the
+  capture, the compose, the render are all 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 `cueframe install`.

package/skills/cueframe-cli/SKILL.md

@@ -27,7 +27,7 @@ clip suggestion required.
 
 ```bash
 # 0. Always use --json for agent-driven runs (NDJSON to stdout, no spinners).
-#    This build connects to a fixed environment — no target flag needed.
+#    Commands run against production; auth is stored in ~/.cueframe/auth.json.
 
 # 1. Register media (one or many — mixed video / image / audio).
 cueframe upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
@@ -145,6 +145,36 @@ 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.
+cueframe init --json
+
+# 2a. FORK a built-in primitive into cueframe/components/<id>/ as owned, editable source.
+#     Discover ids from the catalog: cueframe api GET /v1/components   (87 primitives).
+cueframe eject cinematic-title --json
+
+# 2b. …or scaffold a blank custom component.
+cueframe new component my-badge --json
+
+# 3. Edit cueframe/components/<id>/ — it's standard Remotion. The component is mounted
+#    ({ durationInFrames, params }) at render; params are your composition's clip params.
+
+# 4. Publish to CueFrame so it can render (uploads index.tsx as the component's tsxSource).
+cueframe push cinematic-title --json     # one component
+cueframe sync --json                      # every component in the workspace
+
+# 5. Reference the component id in your composition (as an alpha-layer clip), then render
+#    with the same verb. Preview a single component first via the MCP preview_component loop.
+cueframe render <projectId> -o ./out.mp4 --json
+```
+
 ## Quick reference
 
 | Need to… | Command |
@@ -162,12 +192,12 @@ Pipe `--json` output through `jq -c 'select(.event=="…")'` to grab specific li
 | Anything not wrapped | `cueframe api GET /v1/...  -i` (escape hatch, like `gh api`) |
 | Validate a composition without mutating | `cueframe composition validate -b @plan.json` |
 
-## Targets and auth
+## Auth
 
-**This build connects to a fixed CueFrame environment.** The `-t` / `--target`, `--url`, and `CUEFRAME_API_URL` inputs are accepted but **ignored** — there is no environment to select. Authenticate once:
+Commands run against production. Authenticate once:
 
-- `cueframe auth <cf_test_… key>` — save a static API key (CI / headless).
 - `cueframe login` — OAuth device flow (laptops).
+- `cueframe 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.
 
@@ -186,15 +216,16 @@ Errors come as `{"event":"error", "phase":"<step>", "message":"...", "code":"...
 | Mistake | Reality |
 |---|---|
 | Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `cueframe api METHOD /v1/...` — same auth, same JSON pipeline. |
-| Passing `-t` / `--url` to switch environment | No-op. The target is fixed for this release; those inputs are ignored. |
 | Polling for render completion with a sleep loop | `cueframe 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 `cueframe 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 NOT to use this skill
+## 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`.
 
-- Pure local video manipulation (concatenate, trim, transcode) where AI clip selection adds no value → use `ffmpeg` directly.
-- Inspecting internal backend state → that has its own operator tooling, not this CLI.
-- Building the CLI itself (changes to the CLI source) → that's CLI development, not CLI usage.
+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-component-authoring/SKILL.md

@@ -0,0 +1,67 @@
+---
+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 both the MCP agent path (get_component_source → create_component) and the CLI repo path (cueframe eject/new → push). Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
+---
+
+# CueFrame component authoring (fork / customize / own)
+
+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.
+
+**The two facts that shape everything:**
+- A component is mounted **`({ durationInFrames, params }) => JSX`** at render — `params` is the
+  single props bag (your composition clip's params). A forked primitive is auto-wrapped in this
+  adapter; a from-scratch component must default-export this shape.
+- The shared renderer **never runs your code**: a component is baked to a transparent (alpha)
+  video in an isolated box first, then composited as trusted pixels. So owning/editing source is
+  safe, and rendering stays on CueFrame.
+
+## 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`, then `create_component({ componentId, tsxSource, … })`
+   to store your customized copy (origin `server-native`; if forked, `ejectedFrom` is stamped).
+3. **Iterate (author→preview→fix):** `open_session` → `preview_component({ componentId, params })`
+   renders ONE still. A 422 `component_does_not_compile` returns the compiler error — read it, fix
+   via `update_component` (same id, in place), preview again. `close_session` when done.
+4. **Render:** add it to a composition as an `alpha-layer` clip (`apply_composition`), then
+   `create_render` → `wait_job kind:"render"` for the MP4.
+
+## Path B — CLI / coding agent (repo-owned source under git)
+
+Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit locally as
+standard Remotion, push to render.
+
+```bash
+cueframe init --json                       # scaffold cueframe.json + cueframe/components/
+cueframe eject cinematic-title --json       # fork a built-in primitive as owned source
+#   or: cueframe new component my-badge --json     # scaffold a blank one
+# …edit cueframe/components/<id>/ in your editor (standard Remotion)…
+cueframe push cinematic-title --json        # upload index.tsx as the component tsxSource
+#   or: cueframe sync --json                # push every component in the workspace
+# reference the component id in your composition, then render:
+cueframe 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.
+
+## 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+`render_frame` to see it.)
+
+## Don't
+- Don't expect a forked primitive to use rich named props — it's adapted to `({durationInFrames,
+  params})`; read `params` inside.
+- Don't hand-roll a graphic from zero when a built-in is close — fork it (`get_component_source` /
+  `cueframe eject`) and edit.
+- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.

package/dist/analyze-JQBFZK57.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{A as a}from"./chunk-KEYFXLX4.js";export{a as analyzeCommand};