cueframe 0.9.4 → 0.11.3

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

@@ -5,13 +5,7 @@ description: Use when editing, clipping, or rendering video via the CueFrame CLI
 
 # CueFrame CLI
 
-## Scope and capability policy
-
-User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
-
-Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
-
-For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Use the [project and capability policy](../composing-video/references/project-policy.md) for scope, current state and metered work.
 
 ## MCP is the primary surface — read this before using the CLI
 
@@ -31,11 +25,11 @@ 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.9 describe --json`.
+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.11 describe --json`.
 
-**Run it as `npx -y cueframe@0.9 …` — every command in this skill is written that way, and
+**Run it as `npx -y cueframe@0.11 …` — 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.9 install` wires the MCP server and drops these skills, but npx
+there: `npx -y cueframe@0.11 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
@@ -46,9 +40,9 @@ 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.9 schema composition` (prints
+examples below alone. The live contract is `npx -y cueframe@0.11 schema composition` (prints
 the real wire schema the server enforces); confirm any draft with
-`npx -y cueframe@0.9 composition validate -b @file.json` BEFORE you render. Validation is
+`npx -y cueframe@0.11 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.
 
@@ -65,44 +59,62 @@ Validate first, then use `preview_card` / `preview_component` for isolated graph
 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.
 
+To compare a certified reference frame with an existing saved preview, use `compare`:
+
+```bash
+npx -y cueframe@0.11 compare <projectId> --reference-media <mediaId> --reference-representation <identity> --reference-frame 117 --candidate-job <jobId> --candidate-artifact <artifactId> --out ./comparison --json
+```
+
+The command calls the shared comparison operation; it does not rerender the composition. `--views overlay,difference` selects diagnostics and `--crop x,y,width,height` uses one common-coordinate crop. NDJSON contains source identities and image receipts, never base64 payloads. `--out` saves verified PNGs; without it, image receipts explicitly say `metadata_only`. Inspect those images and relevant motion before judging the film.
+
 ```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.9 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
+npx -y cueframe@0.11 upload "/path/to/source.mp4" --json   # → mediaItemId (process_complete)
 
 # 2. Create a project (sets aspect/format).
-npx -y cueframe@0.9 project create -n "promo" -a 9:16 --json   # → projectId
+npx -y cueframe@0.11 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.9 schema composition                                 # → live wire schema
-npx -y cueframe@0.9 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
-npx -y cueframe@0.9 composition put <projectId> -b @composition.json   # ETag auto
+npx -y cueframe@0.11 schema composition                                 # → live wire schema
+npx -y cueframe@0.11 composition validate -b @composition.json          # → ✓ valid | per-field errors (no render)
+npx -y cueframe@0.11 composition get <projectId> --json                  # → etag (not found = no composition yet)
+npx -y cueframe@0.11 composition put <projectId> -b @composition.json --if-match <etag>
+#    --if-match is required: a save made since your `get` fails with 409 stale_etag
+#    instead of being overwritten. Re-`get`, re-apply your edit, retry. Use --create
+#    only for the first composition of a project (refused 409 if one exists).
 
 # 4. Render the saved composition to MP4. SSE-watches + downloads when done.
-npx -y cueframe@0.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 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). A clip suggestion is NOT required. Re-running the same command on an
+# unchanged composition replays the same render (the Idempotency-Key hashes the
+# project, the composition ETag and the request: --aspect/--fps/--resolution/
+# --priority/--intent); editing the composition or changing a flag starts a new one.
+# Without --aspect it renders the composition's own format. --aspect must match the
+# composition's aspect (a new aspect is a `derive_composition`, not a render flag);
+# pass it with --resolution hd|fhd|4k to change only the output resolution.
 # 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.9 render watch <renderId> -p <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 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.9 schema composition` (the live wire schema) — run it when a field is
-unclear, and `npx -y cueframe@0.9 composition validate -b @file.json` to check a draft.
+`npx -y cueframe@0.11 schema composition` (the live wire schema) — run it when a field is
+unclear, and `npx -y cueframe@0.11 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:
+`composition put` takes the **bare** `Composition` object (no wrapper; the CLI PUTs
+the `@file` verbatim with your `--if-match` ETag). Minimal valid shape:
 
 ```json
 {
@@ -166,18 +178,18 @@ the composition yourself (above).
 
 ```bash
 # 1. Upload + chain the AI clip pass.
-npx -y cueframe@0.9 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
-# (or run it explicitly: npx -y cueframe@0.9 analyze <mediaItemId> --wait --json)
+npx -y cueframe@0.11 upload "/path/to/source.mp4" --analyze --json   # mediaItemId + suggestions
+# (or run it explicitly: npx -y cueframe@0.11 analyze <mediaItemId> --wait --json)
 
 # 2. List clip suggestions (publicId sug_…, title, startMs/endMs, score).
-npx -y cueframe@0.9 clips <mediaItemId> --json
+npx -y cueframe@0.11 clips <mediaItemId> --json
 
 # 3. Create a project AND author its composition from the chosen suggestion.
-npx -y cueframe@0.9 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
-#   (or, on an existing project: npx -y cueframe@0.9 composition from-suggestion <projectId> -s <sug_…>)
+npx -y cueframe@0.11 project create -n "paul-klein-shorts" -a 9:16 --from-suggestion <sug_…> --json
+#   (or, on an existing project: npx -y cueframe@0.11 composition from-suggestion <projectId> -s <sug_…>)
 
 # 4. Render — same framework verb as above.
-npx -y cueframe@0.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
 ```
 
 Both flows converge on `composition put` → `render`; the on-ramp just authors the
@@ -185,59 +197,61 @@ 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
+## Component authoring: 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).
+Own the motion-graphics components you render (shadcn-style): scaffold a native component as
+editable source, customize it, and render it on CueFrame. 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). The CLI does not fork built-ins: the maintained builtin
+presets and recipes are placed as they are (list them with `list_catalog`
+projection `component-library`).
 
 ```bash
 # 1. Scaffold a workspace (writes cueframe.json + cueframe/components/). Idempotent.
-npx -y cueframe@0.9 init --json
+npx -y cueframe@0.11 init --json
 
 # 2a. Scaffold a component in cueframe/components/<id>/ as owned, editable source.
-npx -y cueframe@0.9 new component my-badge --category ui-blocks --json
+npx -y cueframe@0.11 new component my-badge --category ui-blocks --json
 
 # The scaffold is a native (version 4) source: template.html + definition.json, with its
-# manifest in cueframe.json. Built-in forks copy the exact template, definition and manifest.
+# manifest in cueframe.json.
 
 # 3. Edit cueframe/components/<id>/template.html (one HyperFrames sub-composition ending in
 #    __cfScene.mount(...)) and definition.json (inputs, defaults, timing, capabilities).
 
 # 4. Publish to CueFrame so it can render (the server admits the source or names the rule it breaks).
-npx -y cueframe@0.9 push my-badge --json            # one component
-npx -y cueframe@0.9 sync --json                      # every component in the workspace
+npx -y cueframe@0.11 push my-badge --json            # one component
+npx -y cueframe@0.11 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.9 render <projectId> -o ./out.mp4 --json
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
 ```
 
 ## Quick reference
 
 | Need to… | Command |
 |---|---|
-| See every command + flags | `npx -y cueframe@0.9 describe --json` |
-| Install/refresh managed skills | `npx -y cueframe@0.9 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
-| List projects | `npx -y cueframe@0.9 list -n 50` |
-| List your media | `npx -y cueframe@0.9 clips` (no mediaId arg) |
-| Discover the live composition schema | `npx -y cueframe@0.9 schema composition` |
-| Validate a draft (no save, no render) | `npx -y cueframe@0.9 composition validate -b @plan.json` |
-| Read composition + ETag | `npx -y cueframe@0.9 composition get <projectId> --json` |
-| Write composition | `npx -y cueframe@0.9 composition put <projectId> -b @plan.json` (ETag auto) |
-| Export to Final Cut | `npx -y cueframe@0.9 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
-| Export to Premiere | `npx -y cueframe@0.9 export premiere <projectId> -s <sug> --wait -o cut.zip` |
-| Anything not wrapped | `npx -y cueframe@0.9 api GET /v1/...  -i` (escape hatch, like `gh api`) |
-| Validate a composition without mutating | `npx -y cueframe@0.9 composition validate -b @plan.json` |
+| See every command + flags | `npx -y cueframe@0.11 describe --json` |
+| Install/refresh managed skills | `npx -y cueframe@0.11 install` (shared `~/.agents/skills` and Claude `~/.claude/skills`; locally changed or untracked packages are preserved and reported) |
+| List projects | `npx -y cueframe@0.11 list -n 50` |
+| List your media | `npx -y cueframe@0.11 clips` (no mediaId arg) |
+| Discover the live composition schema | `npx -y cueframe@0.11 schema composition` |
+| Validate a draft (no save, no render) | `npx -y cueframe@0.11 composition validate -b @plan.json` |
+| Read composition + ETag | `npx -y cueframe@0.11 composition get <projectId> --json` |
+| Write composition | `npx -y cueframe@0.11 composition put <projectId> -b @plan.json --if-match <etag>` (`--create` for the first composition) |
+| Export to Final Cut | `npx -y cueframe@0.11 export fcpxml <projectId> -s <sug> --wait -o cut.zip` |
+| Export to Premiere | `npx -y cueframe@0.11 export premiere <projectId> -s <sug> --wait -o cut.zip` |
+| Anything not wrapped | `npx -y cueframe@0.11 api GET /v1/...  -i` (escape hatch, like `gh api`) |
+| Validate a composition without mutating | `npx -y cueframe@0.11 composition validate -b @plan.json` |
 
 ## Auth
 
 Commands run against production. Authenticate once:
 
-- `npx -y cueframe@0.9 login` — OAuth device flow (laptops).
-- `npx -y cueframe@0.9 auth <cf_live_… key>` — save a static API key (CI / headless).
+- `npx -y cueframe@0.11 login` — OAuth device flow (laptops).
+- `npx -y cueframe@0.11 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.
 
@@ -255,11 +269,11 @@ Errors come as `{"event":"error", "phase":"<step>", "message":"...", "code":"...
 
 | Mistake | Reality |
 |---|---|
-| Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `npx -y cueframe@0.9 api METHOD /v1/...` — same auth, same JSON pipeline. |
-| Polling for render completion with a sleep loop | `npx -y cueframe@0.9 render` already SSE-watches and exits when done. Use `render watch <id>` to reattach. |
+| Reaching for `curl …/v1/...` because the CLI didn't have a command | Use `npx -y cueframe@0.11 api METHOD /v1/...` — same auth, same JSON pipeline. |
+| Polling for render completion with a sleep loop | `npx -y cueframe@0.11 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.9 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). |
+| Hand-editing the composition without an ETag | `composition put` refuses without `--if-match <etag>` from the `composition get` your edit started from. Don't fetch a fresh ETag right before the put: that overwrites anyone who saved in between. `--create` is only for a project's first composition; there is no unconditional overwrite. |
+| Calling `npx -y cueframe@0.11 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)

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

@@ -1,187 +1,38 @@
 ---
 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 using complete versioned source snapshots. Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
+description: "Use when authoring, forking or customizing CueFrame HTML cards, motion-graphics primitives or reusable native components, including a fork of an exact catalog source. Covers cloud MCP, local desktop and CLI project paths using complete versioned source snapshots. For scene-shot devices and cameras use cueframe-scene-shot. Triggers on \"customize the parallax look\", \"make my own animated lower-third\", \"fork a CueFrame template and edit it\", \"author a custom graphic and render it\". Use before hand-writing a component from scratch: forking a built-in is usually the faster start."
 ---
 
-# CueFrame component authoring (fork / customize / own)
+# CueFrame graphic authoring
 
-## Scope and capability policy
+Use the [project and capability policy](../composing-video/references/project-policy.md). Preserve the current project and source identities; make the intended visual behavior inspectable and editable.
 
-User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
+## Choose the representation
 
-Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
+- **HTML card:** authored typography, UI, diagrams and 2D motion with deterministic CSS. It can depict perspective, but does not provide the scene renderer's physical camera, lighting or occlusion.
+- **Whole-clip keyframes:** position, scale, rotation and opacity when the entire card or layer moves together. Read the current `clip.setKeyframes` schema; times are relative to the clip.
+- **Scene shot:** supported groups, devices, pages, world text, surfaces and cameras. Use `cueframe-scene-shot` and its current schema; author JSON, not the generated wrapper.
+- **Native component:** reusable version-4 media-tile scenes with declared inputs, assets and deterministic rendering. Discover a near-fit definition before writing one. Read the [native source contract](references/native-source-contract.md), then the applicable [MCP, CLI or desktop workflow](references/native-component-workflows.md). This is not an arbitrary browser application runtime.
 
-For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+A definition, preset and recipe are different catalog items. Preserve the selected item's exact scoped identity. A builtin source read needs `componentId`, `sourceVersionId` and `builtinCollection`; unavailable pins do not authorize a different source. Keep the complete template, manifest and definition when forking.
 
-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.
+## Cards: geometry, clock and controls
 
-CueFrame ships built-in motion-graphics definitions (titles, lower-thirds, captions,
-effects, transitions and layouts). Discover the current catalog; fork an exact definition, 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.
+A card source is `{kind:"card", html, tokens}`. Each token key `x` becomes the CSS property `--cf-x`; read `var(--cf-x)`. Keys have no leading dashes. Missing variables silently invalidate CSS, so inspect returned warnings and actual output. Use literal or supported whole-string brand references and do not overwrite reserved motion variables.
 
-**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 host injects a clip-local clock each frame: `--cf-frame`, `--cf-t` (seconds), `--cf-fps`, `--cf-duration` (frames), `--cf-progress`, `--cf-ease`, `--cf-enter` and `--cf-exit`. CSS animations, transitions and timers are not the render clock. The built-in entrance/exit ramps span up to 18 frames; use explicit event times when the brief needs other choreography.
 
-**Source format matters:**
-- New and changed components are native (source version 4): `{version:4, componentId, template,
-  manifest, definition}`. `template` is one HyperFrames sub-composition whose script ends in one
-  `__cfScene.mount(...)`; the manifest is `{version:4, runtime:'hyperframes', hfContract:1,
-  kind:'scene', assets, graphics, alphaPolicy}`. The definition declares input schema, defaults,
-  timing, brand/media bindings and capabilities. The server instructions' Component Contract has
-  the full rules. Version-3 TSX sources are retired and refused as `component_source_retired`.
-- Neither renderer runs authored source in the editor process. Local and hosted execution
-  use isolated render processes and exact immutable source revisions.
+Use flex/grid for text and UI reflow, and coordinate-based nested transforms for spatial animation. Parent mounted contents to their object: a moving phone should carry its bezel, screen mask and controls. Use a separate local transform only when that part really moves relative to the object. The [parented motion recipe](references/parented-motion.md) includes a complete editable card with a shared pose and named pointer-contact/response times.
 
-## Path A — MCP agent (no filesystem; source lives server-side)
+Expose likely revisions as meaningful inputs rather than unrelated constants. A card's text token used by CSS `content` needs a quoted CSS string. Preserve the current token values when changing its HTML. The native component definition declares defaults and input controls; its placement binds media in `execution.assets`, separately from `params`.
 
-Use the live tool schema for request envelopes; hosted write fields are normally under `body`.
+## Iterate on the saved result
 
-1. **Discover and read a built-in:** call `list_catalog` with
-   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
-   Select the intended card and preserve its complete scoped source reference. Call
-   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
-   `builtinCollection` (its scope collection).
-   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
-   retry another scope or an unpinned head.
-2. **Author/own it:** edit the complete native `sourceSnapshot`; use your chosen owned ID
-   consistently in its `componentId` and the request. Send it as `body.source` to
-   `create_component`, with required metadata. Preserve its definition, capability
-   declarations, manifest and source format. For an existing component, keep its ID and
-   use `update_component` with the complete source. Do not send an old pin as the identity
-   of changed source: saving produces a new immutable source version.
-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.
-   **Repin only the requested scope:** for all matching placements in one composition, use
-   `update_component({ componentId, body: { source: editedSnapshot, projectId, compositionId? } })`
-   with the observed revision and dependency guards. 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. For a single placement, update the
-   source without `projectId`, then change only that clip to the returned exact source pin
-   using the observed concurrency guards.
-   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:{},
-   execution:{version:4,componentId,sourceVersionId,params,seed,assets}, placement:{version:3,kind:'clip'}}` 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.
+Keep the same owned component ID while updating its complete source. Saving creates a new immutable source version; existing placements keep their old pins unless explicitly repinned in the intended composition. An isolated preview is not a saved timeline edit. The workflow reference explains scoped repinning and local preview commits.
 
-## Path B — CLI / coding agent (customer-owned source under git)
+Use [cueframe-compose-loop](../cueframe-compose-loop/SKILL.md) for isolated, integrated and final evidence. Preserve production duration when previewing duration-dependent motion. Check the relationship that could fail, including screen corners, overlap, pointer contact and the complete ending, rather than only a pleasing middle still. For `needsUpgrade`, use [retired-source recovery](references/retired-projects.md) and replace only the reported clips.
 
-Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit the native
-template locally, push to render.
+## Detailed guidance
 
-```bash
-npx -y cueframe@0.9 init --json                       # scaffold cueframe.json + cueframe/components/
-npx -y cueframe@0.9 new component my-badge --category ui-blocks --json   # scaffold a component in the workspace
-#   New scaffolds contain template.html and definition.json (native source, version 4).
-# …edit cueframe/components/<id>/template.html and definition.json in your editor…
-npx -y cueframe@0.9 push my-badge --json              # send the native source; the server admits it
-#   or: npx -y cueframe@0.9 sync --json               # push every component in the workspace
-# reference the component id in your composition, then render:
-npx -y cueframe@0.9 render <projectId> -o ./out.mp4 --json
-```
-
-The CLI writes `template.html` and `definition.json` (input schema, defaults, timing and
-capabilities). `cueframe.json` → `components.<id>` holds the version-4 `manifest` and the catalog
-`name` and `category`, which `push` requires; it refuses a component missing either.
-`push`/`sync` send these as one native `source`, checked against the contract's source schema;
-the server's admission (template lint, determinism, declarations) refuses with a named rule.
-For a builtin fork, copy **all three parts** from the selected `sourceSnapshot`: template,
-definition and manifest. A workspace component that still has a version-3 `index.tsx` is
-refused as `component_source_retired` before any API call; author it again as a native template. To preview before
-a full render, push it and use the appropriate component preview loop.
-
-## Path C — Director editing a local desktop project (project-embedded source)
-
-When `get_context` reports the project lane as local, motion does not need an account or an org
-component. Components here are native (source version 4) too:
-- **New component:** open a draft with `open_component_preview`, passing `template`,
-  `component_manifest` (`{version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets,
-  graphics, alphaPolicy}`) and `component_definition`.
-- **Existing component:** pass `component_id` instead, to start from the clip's pinned version or
-  the library version.
-
-The draft is admitted in full: template lint, determinism and the variable declaration.
-`data-composition-variables` must equal the definition's projection (its scalar inputSchema
-properties, then the manifest's slots).
-
-Edit the draft with `update_component_preview` (exact-text `{oldText, newText, replaceAll?}`
-edits). Check exact frames with `render_component_preview_frame`, and 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.
-
-Media slots are image or video, declared in `component_manifest.assets` and bound to project
-media ids in `component_assets`. The template passes them to `MediaTileScene` as
-`streams: { hero: { asset: assets.hero } }`. Declare `alphaPolicy` explicitly:
-`requires-transparency` for overlays, `allows-opaque` for full-frame plates.
-
-Every frame must be a pure function of `render.frame`, params and `render.seed`. Timers, `Date`,
-network, imports, other globals and CSS animation are refused at admission. The timeline and final
-export render the exact committed version. Use `create_component` only for a reusable org-catalog
-component on a reachable cloud lane.
-
-## Upgrading an old project
-
-`get_composition` returns `needsUpgrade` only when clips from before the native cutover remain:
-`[{clipId, kind, componentId?, sourceVersionId?, primitiveId?, successorComponentId?,
-successorSourceVersionId?}]`. Saves and renders refuse those clips. A retired component is
-refused with `component_source_retired`, and a retired
-primitive with `render_unknown_primitive`. Upgrade only the listed clips. Keep every other clip,
-timing, track and brand-kit binding as it is.
-
-- **Any entry with a `successorSourceVersionId`:** call `repin_component` with its clip ids. It
-  moves them to the native successor and keeps their saved inputs.
-- **`v3-component` with no successor** (a custom pre-cutover component): read its source, params,
-  timing and placement, and author a native replacement with `create_component` as a version-4
-  template following the server instructions' Component Contract.
-- **`unpinned-component`:** the clip carries a `retired` record (what was stored before the cutover), with its
-  props preserved. Re-author it from those props the same way.
-- **`retired-primitive`:** rebuild what `primitiveId` drew from the clip's params, as a card or
-  a native component.
-
-For each replacement, use `apply_composition` to replace only that clip at the same start,
-duration, track and placement, pinned to the new exact `sourceVersionId`. Map the old params
-onto the new inputs; do not invent new content. Verify each clip with `preview_frame` at a time
-inside its window and confirm `needsUpgrade` is gone. Only then render (`create_render`).
-
-## Choosing what to fork
-Use the `component-library` projection to choose a definition, inspect its input schema and
-capabilities, then fetch its exact scoped source as described in Path A. Presets and recipes
-are different card kinds: follow their exact definition/document references rather than treating
-those IDs as source IDs. Inspect appropriate previews before judging visual behavior.
-
-## Layout inside a component — CSS flex/grid
-
-When several cells must share space (a feature grid, a fixed rail beside fluid content, a cast of
-objects next to type), lay them out with CSS flex or grid in the HTML, not hand-placed pixels.
-Use the template of a native component, or a `card`:
-
-```html
-<div style="display:grid; grid-template-columns: 520px 1fr 3fr; gap:16px; width:100%; height:100%">
-  <div class="rail"></div><div class="type"></div><div class="art"></div>
-</div>
-```
-
-- Fixed tracks (`520px`) hold content-sized cells. Fractions (`1fr`, `3fr`) share what is left.
-- Animate a reflow from the frame, never from time: in a card, drive `grid-template-columns`
-  or `flex-basis` from `var(--cf-progress)` (or `--cf-enter`/`--cf-exit`); in a native template,
-  derive it from `render.frame`.
-- Size the container to its region instead of CSS-`scale()`-ing the layout, which resamples.
-  Use `object-fit` for media in a cell.
-
-## 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.
-- When a built-in fits the request, fork its exact snapshot using Path A. Never discard its
-  definition by copying only its template; preserve the definition and manifest too.
-- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.
+- [Authoring paths](references/authoring-paths.md): the MCP path step by step, when no filesystem is available.
+- [Forking and layout](references/forking-and-layout.md): what to fork, flex and grid inside a component, and what to avoid.

package/dist/skills/cueframe-component-authoring/references/authoring-paths.md

@@ -0,0 +1,72 @@
+# Authoring paths
+
+Defaults, examples and detail for this topic. The [skill](../SKILL.md) and the [project and capability policy](../../composing-video/references/project-policy.md) take precedence where they differ, and the current tool schemas are authoritative.
+
+## Scope and capability policy
+
+User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
+
+Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
+
+For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../../cueframe-compose-loop/references/preview-workflow.md).
+
+Use `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 built-in motion-graphics definitions (titles, lower-thirds, captions,
+effects, transitions and layouts). Discover the current catalog; fork an exact definition, 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.
+
+**Source format matters:**
+- New and changed components are native (source version 4): `{version:4, componentId, template,
+  manifest, definition}`. `template` is one HyperFrames sub-composition whose script ends in one
+  `__cfScene.mount(...)`; the manifest is `{version:4, runtime:'hyperframes', hfContract:1,
+  kind:'scene', assets, graphics, alphaPolicy}`. The definition declares input schema, defaults,
+  timing, brand/media bindings and capabilities. The server instructions' Component Contract has
+  the full rules. Version-3 TSX sources are retired and refused as `component_source_retired`.
+- Neither renderer runs authored source in the editor process. Local and hosted execution
+  use isolated render processes and exact immutable source revisions.
+
+## Path A — MCP agent (no filesystem; source lives server-side)
+
+Use the live tool schema for request envelopes; hosted write fields are normally under `body`.
+
+1. **Discover and read a built-in:** call `list_catalog` with
+   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
+   Select the intended card and preserve its complete scoped source reference. Call
+   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
+   `builtinCollection` (its scope collection).
+   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
+   retry another scope or an unpinned head.
+2. **Author/own it:** edit the complete native `sourceSnapshot`; use your chosen owned ID
+   consistently in its `componentId` and the request. Send it as `body.source` to
+   `create_component`, with required metadata. Preserve its definition, capability
+   declarations, manifest and source format. For an existing component, keep its ID and
+   use `update_component` with the complete source. Do not send an old pin as the identity
+   of changed source: saving produces a new immutable source version.
+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.
+   **Repin only the requested scope:** for all matching placements in one composition, use
+   `update_component({ componentId, body: { source: editedSnapshot, projectId, compositionId? } })`
+   with the observed revision and dependency guards. 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. For a single placement, update the
+   source without `projectId`, then change only that clip to the returned exact source pin
+   using the observed concurrency guards.
+   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:{},
+   execution:{version:4,componentId,sourceVersionId,params,seed,assets}, placement:{version:3,kind:'clip'}}` 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.

package/dist/skills/cueframe-component-authoring/references/forking-and-layout.md

@@ -0,0 +1,35 @@
+# Forking and layout
+
+Defaults, examples and detail for this topic. The [skill](../SKILL.md) and the [project and capability policy](../../composing-video/references/project-policy.md) take precedence where they differ, and the current tool schemas are authoritative.
+
+## Choosing what to fork
+Use the `component-library` projection to choose a definition, inspect its input schema and
+capabilities, then fetch its exact scoped source as described in Path A. Presets and recipes
+are different card kinds: follow their exact definition/document references rather than treating
+those IDs as source IDs. Inspect appropriate previews before judging visual behavior.
+
+## Layout inside a component — CSS flex/grid
+
+When several cells must share space (a feature grid, a fixed rail beside fluid content, a cast of
+objects next to type), lay them out with CSS flex or grid in the HTML, not hand-placed pixels.
+Use the template of a native component, or a `card`:
+
+```html
+<div style="display:grid; grid-template-columns: 520px 1fr 3fr; gap:16px; width:100%; height:100%">
+  <div class="rail"></div><div class="type"></div><div class="art"></div>
+</div>
+```
+
+- Fixed tracks (`520px`) hold content-sized cells. Fractions (`1fr`, `3fr`) share what is left.
+- Animate a reflow from the frame, never from time: in a card, drive `grid-template-columns`
+  or `flex-basis` from `var(--cf-progress)` (or `--cf-enter`/`--cf-exit`); in a native template,
+  derive it from `render.frame`.
+- Size the container to its region instead of CSS-`scale()`-ing the layout, which resamples.
+  Use `object-fit` for media in a cell.
+
+## 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.
+- When a built-in fits the request, fork its exact snapshot using Path A. Never discard its
+  definition by copying only its template; preserve the definition and manifest too.
+- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.