frameyard 0.5.0 → 0.7.0

package/skills/frameyard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: frameyard
-description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML, CSS, and an optional JavaScript controller. Use when a user asks to build or operate a Frameyard project, produce parameterized video, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
-frameyard-api-version: 0.5.0
+description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML compositions and JSON timelines. Use when a user asks to build or operate a Frameyard project, produce parameterized video, assemble clips into a timeline, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
+frameyard-api-version: 0.7.0
 ---
 
 # Frameyard
@@ -11,19 +11,20 @@ Use Frameyard's public project format and CLI. Do not introduce an agent-only ru
 ## First decisions
 
 1. Find the project: look for `video.config.js` from the working directory upward, or run `npx frameyard init <directory>` to scaffold one.
-2. Read the composition entry points listed in `video.config.js`. They are `.html` documents; there is no directory scanning.
-3. Read the composition HTML, its optional controller, and the props file before changing behavior.
+2. Read the `format`, `compositions`, and `timelines` maps in `video.config.js`. Entries are explicit `.html` and `.json` documents; there is no directory scanning.
+3. Read the timeline JSON, the referenced composition HTML, its optional controller, and the props files before changing behavior.
 4. If the task needs speech or transcription, confirm that inference is requested or explicitly approved before producing assets.
 
 ## Workflow
 
-1. **Author** the composition as a full HTML document with one `<fy-composition>` root. Put metadata, default props, markup, CSS animation, bindings, audio, and transcripts in the document. Use an optional controller for Canvas 2D, WebGL, karaoke, or per-frame computation CSS cannot express. Read [deterministic authoring](references/deterministic-authoring.md), [bindings](references/bindings.md), and [controllers](references/controllers.md).
-2. **Provide props** as JSON. Validate domain-specific requirements with a controller's `validateProps()`.
-3. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
-4. **Validate** with `npx frameyard check <id> --json`. Static validation runs before Chromium; then every frame is evaluated. Read the structured `diagnostics` array. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
-5. **Inspect** representative frames with `npx frameyard still <id> --frame <n> --out <file.png> --json`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
-6. **Render** with `npx frameyard render <id> [--out <file.mp4>] [--props <file>] [--concurrency <n>] --json`. The default output is `out/<id>.mp4` in the project root.
-7. **Report** the project path, composition entry, controller, props, generated assets, provenance manifest, validation results, diagnostics, still paths and inspection status, final video path, and any failures.
+1. **Author compositions** as full HTML documents with one `<fy-composition>` root. Put metadata, default props, markup, CSS animation, bindings, audio, and transcripts in the document. Use an optional controller for Canvas 2D, WebGL, karaoke, or per-frame computation CSS cannot express. Read [deterministic authoring](references/deterministic-authoring.md), [bindings](references/bindings.md), and [controllers](references/controllers.md).
+2. **Assemble the timeline** in JSON: project format, video/audio tracks, composition, media, and nested-timeline clips, source ranges, static transforms, and audio. Read [timelines](references/timelines.md).
+3. **Provide props** as JSON. Composition props merge over defaults; timeline render props are a map keyed by composition clip ID. Validate domain-specific requirements with a controller's `validateProps()`.
+4. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
+5. **Validate** with `npx frameyard check <id> --json`, where `<id>` is a timeline or composition. Static validation runs before Chromium; then every frame is evaluated. Read the structured `diagnostics` array. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
+6. **Inspect** representative frames with `npx frameyard still <id> --frame <spec> --out <path> --json`, where `<spec>` is a frame number, an inclusive range like `2-12`, or a comma-separated list with at most 32 unique frames. With one frame, `--out` is a `.png` file; with multiple frames, it is a directory and the files are `still-<id>-<frame>.png`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
+7. **Render** with `npx frameyard render <id> [--out <file>] [--props <file>] --json`. Composition renders accept `--concurrency <n>`; timeline renders accept `--workers <n>` and `--scratch <dir>`. `--container <mp4|mov|mkv|webm>` and `--codec <h264|hevc|vp9>` select the delivery pair (MP4/H.264 by default, WebM defaults to VP9), and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded, defaulting to `auto`. The output extension must match the container. The default output is `out/<id>.<ext>` in the project root.
+8. **Report** the project path, timeline and composition entries, controller, props, generated assets, provenance manifest, validation results, diagnostics, still paths and inspection status, final video path, and any failures.
 
 Never claim success when `check` fails, a still is missing, a render exits nonzero, or visual inspection was skipped. A partial or unpublished render is not a successful result.
 
@@ -33,13 +34,17 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 - Keep the current output files unless the user explicitly approves replacement. Use `--force` only with that approval.
 - Use `--project <dir>` when not running from the project root.
 - `render` writes to `out/<id>.mp4` in the project root unless `--out` is passed. Explicit `--out` paths are relative to the current working directory.
-- Use `--concurrency <n>` only when faster local rendering is useful; the default is `1` and the maximum is `16`. It changes capture scheduling only, not composition behavior or output frame order.
+- Use `--concurrency <n>` only for composition renders; the default is `1` and the maximum is `16`. Use `--workers <n>` for timeline renders; the default is `8`. Timeline renders also accept `--scratch <dir>` for FFV1 intermediates.
+- `still --frame <spec>` accepts `n`, `n-m`, or a comma-separated list; ranges are inclusive, duplicates are removed preserving the first occurrence, order is preserved, and one call captures at most 32 unique frames. Do not use `still` as an image-sequence exporter. With multiple frames, `--out` is a directory and files are named `still-<id>-<frame>.png`; with one frame, `--out` is a `.png` file.
+- `--encoder` selects the encoder: `auto` (default) probes NVENC, then Quick Sync, then the codec's software encoder; `software` forces `libx264`, `libx265`, or `libvpx-vp9`; `nvenc` and `qsv` force a vendor. `--codec <h264|hevc|vp9>` and `--container <mp4|mov|mkv|webm>` select the delivery pair: MP4 and MOV hold H.264/HEVC with AAC, MKV holds H.264/HEVC/VP9, and WebM holds VP9 with Opus and defaults to VP9. `--out` must use the container's extension. The probe is a real one-frame encode. Encoders, codecs, and containers change encoded bytes and file size, not captured frames; do not switch them to fix a visual difference. With `nvenc`, timeline `--workers` is capped at eight, the consumer driver session limit, and a larger value reports an `ENCODER_WARNING`. HEVC MP4/MOV files use the `hvc1` tag and do not play in browsers without platform HEVC decoding.
+- For a timeline, `--props` is a JSON object keyed by top-level composition clip ID. For a composition, it is the props object.
 - Use `npx frameyard doctor --json` before reporting an environment problem. It inspects without repairing or downloading.
 - Read [JSON results](references/json-results.md) for result and error shapes, and [failure recovery](references/failure-recovery.md) for actionable error codes.
 
 ## Authoring rules
 
 - A composition is a full HTML document with one `<fy-composition width height fps duration-in-frames>` root and a `data-fy="props"` default-props block.
+- A timeline is a versioned JSON document with explicit tracks and clips. Sources are composition IDs, nested timeline IDs, or local video/image/audio paths. Timeline frames, sourceIn, and duration are integer frames. No remote URLs.
 - Bindings are explicit: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat` on `<template>`. Primitive top-level props are also `--fy-prop-<name>` CSS variables.
 - CSS `@keyframes` and the Web Animations API are seeked from the frame clock. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation per element in frames.
 - Frame-state variables on `:root`: `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames`.
@@ -50,7 +55,7 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 
 ## Determinism guardrails
 
-- A frame may depend only on its integer `frame`, immutable `props`, and assets loaded before frame production.
+- A composition frame may depend only on its integer `frame`, immutable `props`, and assets loaded before frame production. A timeline frame derives from its active clips and the same composition rules.
 - Use `random("stable:key")` from `frameyard/runtime`; never use `Math.random()`.
 - Never use `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions as animation inputs.
 - Finish remote data, fonts, and image loading during the loading phase. Network requests are blocked during frame capture.
@@ -80,6 +85,7 @@ When the CLI version differs from `frameyard-api-version`, pin it with `npx fram
 
 ## References
 
+- [Timelines](references/timelines.md)
 - [Deterministic HTML authoring](references/deterministic-authoring.md)
 - [Bindings](references/bindings.md)
 - [Controllers](references/controllers.md)

package/skills/frameyard/references/common-mistakes.md

@@ -54,6 +54,7 @@
 ## Validation
 
 - Replacing `check` with a single `still`.
+- Using `still` as an image-sequence exporter, adding `--step`-style workflows, or requesting more than 32 unique frames in one call.
 - Ignoring warnings or `diagnostics` in `--json` output.
 - Claiming success after a nonzero exit, a missing still, or skipped visual inspection.
 - Using `--overwrite` or `--force` without permission.

package/skills/frameyard/references/deterministic-authoring.md

@@ -217,9 +217,10 @@ Images declared in the document are awaited by the host. Static fonts should be
 ```sh
 npx frameyard check hello --json
 npx frameyard still hello --frame 42 --out hello-42.png --json
+npx frameyard still hello --frame 0,118-126 --out out/stills --json
 ```
 
-`check` runs static validation before Chromium, then evaluates every frame and validates audio and declared transcripts without capturing or encoding. Read the structured `diagnostics` array. Do not replace `check` with a single still.
+`check` runs static validation before Chromium, then evaluates every frame and validates audio and declared transcripts without capturing or encoding. Read the structured `diagnostics` array. Do not replace `check` with a single still. Inspect several representative frames in one `still` call with a range or list; the batch seeks sequentially in one session and is limited to 32 unique frames.
 
 ## Metadata is fixed
 

package/skills/frameyard/references/diagnostics.md

@@ -75,7 +75,7 @@ Static validation covers:
 - `controller`: `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`
 - `diagnostics`: all static and runtime diagnostics, deduplicated
 
-`check` also exposes `metadata`, `framesChecked`, `audio.details`, and `transcripts.details`. `still` exposes `frame`, `path`, `width`, and `height`. `render` exposes the output path, dimensions, frame count, concurrency, bytes, and audio/transcript clip counts.
+`check` also exposes `metadata`, `framesChecked`, `audio.details`, and `transcripts.details`. `still` exposes `frames`, `width`, and `height`, plus `frame` and `path` when exactly one frame was captured. `render` exposes the output path, dimensions, frame count, concurrency, bytes, and audio/transcript clip counts.
 
 Failures use the same envelope with `error.code`, `error.message`, optional `error.details`, and top-level `diagnostics`.
 

package/skills/frameyard/references/failure-recovery.md

@@ -32,7 +32,7 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | `ELEMENT_UNKNOWN` | Unknown `fy-*` element | Use `fy-composition`/`fy-transcript` or a normal element. |
 | `CONTENT_OUTSIDE_ROOT` | Visual content outside `<fy-composition>` | Move it inside the root. |
 | `PROPS_INVALID` | Invalid props JSON or `validateProps()` failure | Fix the props file or validator. |
-| `FRAME_OUT_OF_RANGE` | Frame outside `0..durationInFrames - 1` | Choose a valid frame. |
+| `FRAME_OUT_OF_RANGE` | Frame outside `0..durationInFrames - 1` | Choose valid frames; a batch error lists every invalid frame and the valid range. |
 | `AUDIO_INVALID` | Bad clip or unreadable/unsupported audio | Use a local project-root-relative file with a decodable audio stream. |
 | `AUDIO_WARNING` | Audio timeline overrun or silent embedded media | Adjust timing/trim or remove the silent source. |
 | `MEDIA_INVALID` | Invalid media source or attributes | Use local, seekable files and valid `data-fy-*` values. |
@@ -57,7 +57,8 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 
 ## Behavior to rely on
 
-- A failed render writes to a temporary file and does not publish a partial MP4.
+- A failed render writes to a temporary file and does not publish a partial output.
+- A multi-frame still captures every frame to a temporary file first; a failed capture publishes no stills. `OUTPUT_EXISTS` lists every conflicting output path before capture starts.
 - Failed TTS/transcription operations leave no artifact and no manifest entry.
 - Existing outputs are replaced only with `--overwrite` (renders/stills) or `--force` (generated assets).
 - Cancellation terminates the child inference process and cleans temporary work.

package/skills/frameyard/references/json-results.md

@@ -11,7 +11,7 @@ Every non-interactive command supports `--json`. Stdout contains one JSON docume
 }
 ```
 
-Additional fields are command-specific and stable within the 0.4 contract.
+Additional fields are command-specific and stable within the 0.4 contract. `check`, `still`, and `render` report `elapsedMs`, the wall time of the operation from static validation and preflight through the final frame or publication; CLI argument parsing is excluded.
 
 ## Error envelope
 
@@ -100,15 +100,19 @@ Static validation diagnostics include source locations. Runtime diagnostics may
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "external", "src": "compositions/hello.controller.js" },
-  "frame": 42,
-  "path": "/absolute/path/hello-42.png",
+  "frames": [
+    { "frame": 0, "path": "/absolute/path/out/stills/still-hello-0.png" },
+    { "frame": 42, "path": "/absolute/path/out/stills/still-hello-42.png" }
+  ],
   "width": 1920,
   "height": 1080,
   "diagnostics": [],
-  "elapsedMs": 700
+  "elapsedMs": 1400
 }
 ```
 
+`frames` is always present and follows the expanded `--frame` order. `frame` and `path` are also present only when exactly one frame was captured. `--frame` accepts a number, an inclusive range (`2-12`), or a comma-separated list; at most 32 unique frames are captured per invocation. With multiple frames, `--out` is a directory and the files are named `still-<id>-<frame>.png`.
+
 ## render
 
 ```json
@@ -126,6 +130,9 @@ Static validation diagnostics include source locations. Runtime diagnostics may
   "durationSeconds": 30,
   "framesRendered": 900,
   "concurrency": 1,
+  "codec": "h264",
+  "container": "mp4",
+  "encoder": "libx264",
   "bytes": 1234567,
   "audio": { "clips": 1 },
   "transcripts": { "clips": 1 },
@@ -134,7 +141,7 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 }
 ```
 
-A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published. Without `--out`, the final path is `out/<composition-id>.mp4` inside the project root. `concurrency` is the number of browser sessions actually used; it is capped by `durationInFrames` and by the CLI maximum of 16.
+A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published. Without `--out`, the final path is `out/<composition-id>.<ext>` inside the project root, using the container extension. `concurrency` is the number of browser sessions actually used; it is capped by `durationInFrames` and by the CLI maximum of 16. `container` is `mp4`, `mov`, `mkv`, or `webm`; `codec` is `h264`, `hevc`, or `vp9`; and `encoder` is the resolved encoder (`libx264`, `libx265`, `libvpx-vp9`, `h264_nvenc`, `hevc_nvenc`, `h264_qsv`, or `hevc_qsv`). Timeline results also report the effective `workers` count after the encoder session cap, with an `ENCODER_WARNING` diagnostic when it was reduced.
 
 ## tts
 
@@ -190,7 +197,7 @@ A successful render means the final path exists and was published atomically. A
 
 ## doctor
 
-Doctor reports findings rather than throwing for environment problems. `ok: true` means the inspection completed; `healthy` says whether required checks, manifest integrity, explicitly supplied models, and integration compatibility passed.
+Doctor reports findings rather than throwing for environment problems. `ok: true` means the inspection completed; `healthy` says whether required checks, manifest integrity, explicitly supplied models, and integration compatibility passed. `ffmpeg-opus-encoder` and `ffmpeg-video-encoders` are optional: the video check probes each supported encoder with a one-frame encode and lists any that FFmpeg advertises but cannot open (an old driver, for example), and neither check affects `healthy`.
 
 ```json
 {
@@ -201,6 +208,8 @@ Doctor reports findings rather than throwing for environment problems. `ok: true
     { "name": "node", "required": true, "status": "ok", "detail": "v22.12.0" },
     { "name": "ffmpeg", "required": true, "status": "ok", "detail": "ffmpeg version ..." },
     { "name": "ffmpeg-encoders", "required": true, "status": "ok", "detail": "libx264 and aac are available." },
+    { "name": "ffmpeg-opus-encoder", "required": false, "status": "ok", "detail": "libopus is available for VP9/WebM audio." },
+    { "name": "ffmpeg-video-encoders", "required": false, "status": "error", "detail": "Unavailable: h264_nvenc (Driver does not support the required nvenc API version); hevc_nvenc (Driver does not support the required nvenc API version). Available: libx264, libx265, libvpx-vp9, h264_qsv, hevc_qsv." },
     { "name": "ffprobe", "required": true, "status": "ok", "detail": "ffprobe version ..." },
     { "name": "chromium", "required": true, "status": "ok", "detail": "/path/to/chrome" },
     { "name": "manifest", "required": false, "status": "ok", "detail": "2 artifacts verified." }

package/skills/frameyard/references/subtitles-karaoke.md

@@ -72,10 +72,10 @@ Apply that value to text styling inside the controller's `update({ frame })`. Do
 
 ```sh
 npx frameyard check karaoke --json
-npx frameyard still karaoke --frame 120 --out karaoke-120.png --json
+npx frameyard still karaoke --frame 118-126 --out karaoke-frames --json
 ```
 
-Inspect several frames across a word boundary. A single still cannot prove that highlighting is synchronized.
+Inspect several frames across a word boundary in one batch. A single still cannot prove that highlighting is synchronized.
 
 ## Derived exports
 

package/skills/frameyard/references/timelines.md

@@ -0,0 +1,143 @@
+# Timelines
+
+A timeline is a project-local JSON document that assembles composition and media clips on tracks and renders as one video. Compositions remain reusable HTML sources; a composition clip is one placement of a composition with its own source range and props.
+
+## Project configuration
+
+```js
+export default {
+  format: { width: 1920, height: 1080, fps: 30 },
+  compositions: {
+    intro: "./compositions/intro.html",
+  },
+  timelines: {
+    main: "./timelines/main.timeline.json",
+  },
+};
+```
+
+- `format` fixes width, height, and fps for every timeline. It is required when the project lists timelines.
+- Composition and timeline IDs share one namespace and must be unique.
+- A composition used in a timeline must match the project fps exactly. A different size is fitted by the clip.
+- Composition-only projects remain valid without `format` or `timelines`.
+
+## Timeline document
+
+```json
+{
+  "version": 1,
+  "name": "Main edit",
+  "tracks": [
+    { "id": "v1", "kind": "video" },
+    { "id": "v2", "kind": "video" },
+    { "id": "a1", "kind": "audio", "gain": 1, "muted": false }
+  ],
+  "clips": [
+    {
+      "id": "intro",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "intro" },
+      "start": 0,
+      "duration": 150,
+      "sourceIn": 0,
+      "props": { "title": "Hello" },
+      "transform": { "fit": "contain", "x": 0, "y": 0, "scale": 1, "rotation": 0, "opacity": 1 },
+      "audio": { "muted": false, "gain": 1 }
+    },
+    {
+      "id": "logo",
+      "track": "v2",
+      "source": { "kind": "image", "src": "assets/logo.png" },
+      "start": 30,
+      "duration": 60,
+      "transform": { "fit": "contain", "width": 480, "height": 270, "x": 640, "y": -320, "rotation": 0, "opacity": 0.9 }
+    },
+    {
+      "id": "music",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/music.wav" },
+      "start": 0,
+      "duration": 210,
+      "audio": { "gain": 0.5 }
+    }
+  ]
+}
+```
+
+- `version` is `1`.
+- `tracks` and `clips` are required. Track order is bottom-to-top for video and irrelevant for audio.
+- `background` is an optional color; the final video composites over black.
+- `durationInFrames` is optional. The duration is derived from the latest clip end unless declared; a declared duration may extend but not cut clips.
+- Unknown fields are errors. No transitions, effects, keyframes, or track solo/visibility in 0.6.
+
+## Sources
+
+| `source.kind` | Fields | Notes |
+| --- | --- | --- |
+| `composition` | `id` | Project composition ID. The clip may set `props`. |
+| `timeline` | `id` | Nested timeline ID. Rendered as a group. |
+| `video` | `src` | Local MP4/WebM, project-relative. |
+| `image` | `src` | Local PNG/JPEG/WebP. `duration` is required. |
+| `audio` | `src` | Local WAV/MP3/M4A/AAC or a video file used only for audio. |
+
+Media paths resolve from the project root. No remote URLs.
+
+## Time and trims
+
+- `start` is the timeline frame where the clip begins.
+- `sourceIn` is the first source frame. It defaults to `0` and must be `0` for images.
+- `duration` is the number of timeline frames. It is optional for compositions, nested timelines, video, and audio; it defaults to the rest of the source. Images require it.
+- A clip that exceeds its source is an error.
+- Clips on one track cannot overlap. Touching endpoints are allowed. Use separate tracks for overlays.
+
+## Presentation
+
+Visual clips accept a static transform:
+
+- `fit`: `contain`, `cover`, or `stretch`.
+- `width`, `height`: optional clip box in output pixels. Both are required together and cannot be combined with `scale`. `fit` applies inside the box, and `x`/`y` offset the box center. Without them, the project frame is the box.
+- `x`, `y`: pixel offsets from the centered fitted result.
+- `scale`: multiplier after fitting to the project frame; an alternative to `width`/`height`.
+- `rotation`: degrees around the center.
+- `opacity`: 0–1.
+
+No keyframes or animated transforms in 0.6.
+
+## Audio
+
+- Composition, video, and nested-timeline clips contribute audio automatically unless `audio.muted` is true.
+- Timeline audio clips live on audio tracks. Audio tracks support `gain` and `muted`.
+- `audio.gain` on a clip is 0–1 and multiplies the source audio.
+- There are no linked A/V pairs. For a J/L cut, mute the visual clip and add an audio clip with a different `sourceIn`.
+- Audio is mixed once for the whole timeline and muxed into the final output.
+
+## Nested timelines
+
+A nested timeline clip behaves as one layer: its internal tracks are composited first, then the parent clip's opacity and transform apply to the whole group. Nested audio is included. Cycles are rejected statically. Timeline clips do not override props of compositions inside a nested timeline in 0.6.
+
+## Commands
+
+```sh
+npx frameyard check main --json
+npx frameyard still main --frame 42 --out main-42.png --json
+npx frameyard still main --frame 0,118-126 --out out/stills --json
+npx frameyard render main --props props/main.json --workers 8 --scratch /path/to/scratch --json
+```
+
+- `--props` on a timeline is a JSON object keyed by top-level composition clip ID; values merge over the clip's `props`.
+- `--workers` is 1–16. The default is 8. With `--encoder nvenc` it is capped at 8 concurrent encode sessions and a larger value reports an `ENCODER_WARNING`.
+- `--scratch` selects the FFV1 intermediate directory. Use a disk with enough space; intermediates are cleaned after the render.
+- `--container <mp4|mov|mkv|webm>` selects the delivery container (default `mp4`); `--codec <h264|hevc|vp9>` selects the codec, and `--encoder <auto|software|nvenc|qsv>` selects how it is encoded. MP4 and MOV hold H.264/HEVC with AAC; MKV holds all three; WebM holds VP9 with Opus and defaults to VP9. `auto` is the default and probes NVENC, then Quick Sync, then software; `software` forces `libx264`, `libx265`, or `libvpx-vp9`. FFV1 intermediates stay lossless and software-encoded, HEVC keeps the `hvc1` tag in MP4/MOV, and the output extension must match the container.
+- `--concurrency` is composition-only.
+- `render` defaults to `out/<timeline-id>.mp4`.
+- `check` evaluates every timeline frame and composition frame. `still` captures one or more requested frames through the same clip capture and composite path; a multi-frame still resolves the timeline, starts one server, and reuses one scratch directory. The `--frame` spec and 32-frame cap are the same as for compositions.
+- `npx frameyard dev` lists timelines in the preview; the timeline view has a program monitor, read-only tracks and clips, playhead, playback, audio controls, and diagnostics.
+
+## Determinism and performance
+
+- A timeline frame derives only from its active clips, their composition frames, props, assets, and the render plan.
+- Composition frames are captured with Chromium; transparent compositions preserve alpha.
+- Timeline production captures active composition and nested-timeline clips to lossless FFV1, composites segments with FFmpeg, concatenates the ordered segments, and mixes audio once.
+- Preview composites in Chromium; production composites with FFmpeg. Small scaling, alpha, and video color differences are expected. Parity is guaranteed at clip capture, not at final encoded pixels.
+- Final output bytes are not a reproducibility guarantee.
+- Long timelines are segmented and bounded. The reference target and measured worst cases are documented in `docs/adr/0012-render-timelines-with-segmented-lossless-clip-intermediates.md`.

package/skills/frameyard/scripts/frameyard.mjs

@@ -1,13 +1,30 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const localCli = path.resolve(scriptDir, "../../../dist/cli.js");
+const packageRoot = path.resolve(scriptDir, "../../..");
 const configured = process.env.FRAMEYARD_CLI;
 
+// Only prefer a sibling build inside the frameyard package itself. A copied
+// skill sits three levels below its host directory, which may hold an
+// unrelated dist/cli.js.
+function packageCli() {
+  const manifestPath = path.join(packageRoot, "package.json");
+  const cliPath = path.join(packageRoot, "dist", "cli.js");
+  if (!existsSync(manifestPath) || !existsSync(cliPath)) return undefined;
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return manifest.name === "frameyard" ? cliPath : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const localCli = packageCli();
+
 let command;
 let args;
 if (configured) {
@@ -22,7 +39,7 @@ if (configured) {
     command = configured;
     args = process.argv.slice(2);
   }
-} else if (existsSync(localCli)) {
+} else if (localCli) {
   command = process.execPath;
   args = [localCli, ...process.argv.slice(2)];
 } else {