frameyard 0.8.0 → 0.9.0

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

@@ -2,7 +2,7 @@
 
 ## Using the old authoring model
 
-- **JavaScript composition modules / `defineComposition`** were removed in 0.4. A composition is a `.html` fragment listed in `video.config.js`.
+- **JavaScript composition modules / `defineComposition`** were removed in 0.4. A composition is a `.html` fragment listed in `fy.config.js`.
 - **`data-frameyard-*`** media attributes were removed in 0.4. Use `data-fy-*`.
 
 ## Document structure
@@ -47,8 +47,18 @@
 - Importing libraries from executable `<script>` tags; import them from the controller instead.
 - Using `Math.random()`, `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions.
 
-## Media and transcripts
+## Fonts
+
+- Using a remote Google Fonts `<link>` in a composition that must render reproducibly. Search Fontsource with `font search` and vendor the file; remote fonts produce `FONT_REMOTE`.
+- Installing a Fontsource variable family and then expecting static weights from the same record. Use `--static --weight 400,700` for static files, or `--force` to replace the family.
+- Passing `--license` with a Fontsource id; the provider supplies the license and the flag is rejected. Use `--license` only with `--file`/`--url`.
+- Importing a font by URL without a license. It records `unknown`, warns, and requires `full`; add `--license` and `--license-file` when the license allows redistribution.
+- Adding a `.woff2` file but forgetting the license or `--family`; `font add` needs the family name and warns when the license is unknown.
+- Hand-editing a path or hash in `fy.fonts.json`. Reinstall the face; `check`, `still`, and `render` verify hashes before Chromium.
+- Installing only weight 400 and using `font-weight: 700`, which asks the browser to synthesize a bold face. Add the weight or a variable range.
+- Moving or renaming a vendored font file without updating the manifest; `font verify` reports `FONT_FILE_MISSING`.
 
+## Media and transcripts
 - Using remote, live, or unseekable media sources.
 - Using `<source>` or `<track>` children; use a local `src` and `<fy-transcript>`.
 - Adding or changing media in `update()`; prepare it in the fragment or in `mount()`.
@@ -56,6 +66,15 @@
 - Assuming media/transcript `src` is document-relative. It is project-root-relative.
 - Assuming the controller `src` is project-root-relative. It is relative to the composition URL.
 
+## Generated audio
+
+- Passing `--talker-model` or `--codec-model` with `--engine supertonic`, or `--model-dir` with `--engine qwen`. Flags are engine-specific.
+- Using a speaker name with `--engine supertonic`; `--speaker` is the numeric `--sid`.
+- Omitting `--language` with Supertonic or using a code outside its 31-language list.
+- Expecting `--style` or `--device` to work with Supertonic; both are qwen-only. Put expression tags in the text.
+- Pointing `--model-dir` at individual files instead of the extracted seven-file archive.
+- Regenerating an existing speech asset without `--force` and user approval (`OUTPUT_EXISTS`).
+
 ## Timelines
 
 - Putting `blend` on an audio clip. It is only valid on visual clips.
@@ -66,6 +85,18 @@
 - Omitting `duration` on a static composition clip, or setting `sourceIn` above 0. A static source has no intrinsic duration or frames.
 - Expecting a static composition clip to contribute audio or transcripts. It is visual-only.
 
+## Timeline keyframes
+
+- Treating `frame` as a timeline frame or a source frame. Keyframe frames are clip-local; `0` is the clip start boundary and `duration` is the end boundary.
+- Expecting keyframes to extend a clip. A key past `duration` is a `TIMELINE_CLIP_OUT_OF_RANGE` error; declare a longer clip instead.
+- Declaring the same channel as a scalar in `transform` and as a keyframe track. Keyed channels and static channels are separate; defaults do not conflict.
+- Combining `keyframes.scale` with a `transform.width`/`height` box. Use a keyed scale without a box, or keep the box and animate `x`, `y`, `rotation`, and `opacity`.
+- Putting keyframes on an audio clip. Only visual clips have presentation channels.
+- Using seconds instead of integer clip-local frames, or putting keys out of order.
+- Expecting the final key’s `easing` to do anything. Easing belongs to the interval after a key; the last key has no following interval.
+- Expecting preview and encoded keyframe motion to match exactly. Preview uses the exact CSS curve; production approximates it in FFmpeg and may differ by a subpixel.
+- Expecting an animated `blend` mode. Blend remains static; only `opacity` can animate the layer’s contribution to a blend.
+
 ## Static compositions
 
 - Expecting `update()` or `--fy-*` frame-state variables to run. A static composition only runs `mount()` and prop validation; use CSS, markup, or mount-time canvas drawing.
@@ -74,6 +105,26 @@
 - Passing `--container`, `--codec`, `--encoder`, or `--concurrency` to `render` for a static composition. Use a timeline image clip if the deliverable must be video.
 - Requesting a still frame other than 0 from a static composition.
 
+## Context, inspection, and templates
+
+- Reading the whole repository before a small edit. Run `npx frameyard context --json` first; it returns the format, props, timelines, assets, policy, and next commands.
+- Treating `inspect`/`compare` as a vision model. They return facts such as blank, alpha coverage, bbox, and changed pixels; they do not judge whether a design looks right.
+- Expecting `compare` to exit 0 when the images differ. It exits 1 and still returns `ok: true` with `identical: false`.
+- Forgetting that `add` does not edit `fy.config.js`. Merge the returned `register` object yourself, then run `lint`.
+- Adding a composition template to a project without `format`. Composition templates inherit the project format; add `format { width, height, fps }` first.
+- Adding the slideshow timeline before `assets/slide-1.png` through `assets/slide-3.png` exist. `check` will report the missing assets.
+
+## Resource policy and lint
+
+- Using `check` as the edit loop. Use `lint`; it resolves the timeline, projects every scene and keyframe channel, and scans the controller without Chromium.
+- Treating a clean `lint` as a successful `check`. Lint does not run `validateProps` or composition runtime.
+- Running `tts`, `transcribe`, or `render` while the workspace policy is `authoring` or `light`. Use `--dry-run` and hand off the command.
+- Editing `fy.policy.json`, `.opencode/`, `.pi/`, or `skills/frameyard/` to bypass the policy. Those files are protected by host permissions and are not part of the authoring task.
+- Passing `--force` or `--overwrite` outside `full`. Ask the user before replacing an output; the CLI will fail with `RESOURCE_POLICY_BLOCKED`.
+- Requesting more still frames than the tier allows. The caps are 1 for `light`, 4 for `authoring`, and 32 for `full`; split larger ranges.
+- Passing `--workers 8` with `--profile shared-cpu`. The profile caps workers at 2 and fails with `RESOURCE_PROFILE_CONFLICT` instead of clamping.
+- Forgetting that the policy is discovered from the working directory upward, independent of `fy.config.js`. Running from a nested directory still finds the workspace file.
+
 ## Validation
 
 - Replacing `check` with a single `still`.

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

@@ -4,7 +4,7 @@ Frameyard compositions are partial HTML fragments. The preview server wraps them
 
 ## Project configuration
 
-`video.config.js` lists every composition explicitly:
+`fy.config.js` lists every composition explicitly:
 
 ```js
 export default {
@@ -99,6 +99,12 @@ CSS `@keyframes` and the Web Animations API are paused and seeked by the runtime
 - The root exposes `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames`. Use them in `calc()` for simple computed motion and progress bars.
 - Do not use CSS transitions. They are diagnosed as non-deterministic.
 
+## Timeline clip keyframes
+
+CSS `@keyframes` animate elements *inside* a composition. A timeline clip's `keyframes` animate the clip's placement in the edit: `x`, `y`, `scale`, `rotation`, and `opacity`. The two mechanisms compose: a composition may animate internally while its timeline clip also fades or moves.
+
+Timeline keyframes use clip-local integer frames, not composition frames or seconds. Keyframe values are derived only from the integer frame and the declared easing, so they are seek-safe. Preview evaluates the exact CSS timing function; production generates per-frame FFmpeg expressions and approximates the curve. See [timelines](timelines.md) for the contract.
+
 ## Controllers
 
 An optional controller handles Canvas 2D, WebGL, karaoke, and per-frame computation CSS cannot express.
@@ -215,17 +221,18 @@ Declare canonical transcript requirements with:
 
 Remote data, images, fonts, and other assets must resolve during the loading phase before frame production. The production browser blocks network requests after loading begins. A fetch from `update()` is a bug.
 
-Images declared in the fragment are awaited by the host. Static fonts should be loaded with `document.fonts.ready` or an explicit `FontFace` before frame production.
+Images declared in the fragment are awaited by the host. Fonts should be vendored into the project with `npx frameyard font search`/`font add <id>` or `font add --file`; the server injects the generated `@font-face` sheet and the host awaits `document.fonts.ready`. A used face that fails to load fails the capture with `FONT_LOAD_FAILED`. A remote font URL produces a `FONT_REMOTE` warning and is not reproducible. See [fonts](fonts.md).
 
 ## Validation and inspection
 
 ```sh
+npx frameyard lint hello --json
 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 animated frame and validates audio and declared transcripts without capturing or encoding. A static composition is inspected once. 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. A static composition exposes only frame 0.
+`lint` runs static validation, timeline resolution, scene and keyframe projection for every timeline frame, and a controller determinism scan without Chromium. Use it while editing; it does not run `validateProps` or composition runtime. `check` runs static validation before Chromium, then evaluates every animated frame and validates audio and declared transcripts without capturing or encoding. A static composition is inspected once. 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 in `full` (4 in `authoring`, 1 in `light`). A static composition exposes only frame 0.
 
 ## Metadata is fixed
 

package/skills/frameyard/references/diagnostics.md

@@ -35,7 +35,7 @@ Static validation covers:
 }
 ```
 
-`details` may include `path`, `line`, `column`, `endLine`, `endColumn`, `element`, `attribute`, `value`, `suggestion`, `frame`, and `controller`.
+`details` may include `path`, `line`, `column`, `endLine`, `endColumn`, `element`, `attribute`, `value`, `suggestion`, `frame`, and `controller`. Timeline diagnostics may also include `timeline`, `clip`, `track`, `channel`, `keyframe`, `jsonPath`, `timelineFrame`, `sourceFrame`, `from`, `to`, and `nesting`; keyframe errors use `channel`, the zero-based `keyframe` index, and the clip-local `frame`, and transition errors use `from`/`to`.
 
 ## Common codes
 
@@ -66,14 +66,38 @@ Static validation covers:
 | `ELEMENT_NOT_SUPPORTED` | error | `iframe`, `object`, `embed`, `base`, refresh/CSP meta, `source`, `track`, or declarative shadow DOM |
 | `ELEMENT_UNKNOWN` | warning | Unknown `fy-*` element |
 | `CONTENT_OUTSIDE_ROOT` | warning | Visual content outside `<fy-composition>` |
+| `TIMELINE_TRANSITION_INVALID` | error | Unknown transition field, invalid clip id, or unsupported easing |
+| `TIMELINE_TRANSITION_UNKNOWN_CLIP` | error | Transition names a missing or self clip |
+| `TIMELINE_TRANSITION_WRONG_TRACK` | error | Transition clips are on different tracks |
+| `TIMELINE_TRANSITION_AUDIO_TRACK` | error | A `dissolve` is declared on an audio track; use `crossfade` |
+| `TIMELINE_TRANSITION_VIDEO_TRACK` | error | A `crossfade` is declared on a video track; use `dissolve` |
+| `TIMELINE_TRANSITION_NOT_OVERLAPPING` | error | Declared transition has no overlap |
+| `TIMELINE_TRANSITION_GEOMETRY` | error | Reversed order or the incoming clip ends before the outgoing clip |
+| `TIMELINE_TRANSITION_DUPLICATE` | error | Repeated pair or a clip used twice on one side |
+| `TIMELINE_TRANSITION_KIND` | error | Unsupported or missing transition `kind` |
 | `MEDIA_INVALID` | error | Invalid or missing audio/video source or attributes |
 | `TRANSCRIPT_INVALID` | error | Invalid or missing transcript source |
 | `ASSET_NOT_FOUND` | error | Missing image, stylesheet, media, or transcript file |
+| `FONT_MANIFEST_INVALID` | error | Invalid font manifest schema, path, face, weight, or duplicate family |
+| `FONT_FILE_MISSING` | error | A manifest font file is missing |
+| `FONT_FILE_INVALID` | error | Wrong extension, signature, or non-file font path |
+| `FONT_HASH_MISMATCH` | error | A vendored font file changed size or SHA-256 |
+| `FONT_LICENSE_MISSING` | warning | Font license type or file is unknown or absent |
+| `FONT_LOAD_FAILED` | error | Chromium failed to load a used `@font-face` |
+| `FONT_PROVIDER_UNAVAILABLE` | error | Fontsource API/CDN unreachable or invalid response |
+| `FONT_DOWNLOAD_FAILED` | error | A Fontsource or URL response was not a valid font file |
+| `FONT_REMOTE` | warning | CSS references a remote font or stylesheet |
+| `FONT_NOT_FOUND` | error | Fontsource id or `font remove` id is not installed |
 | `AUDIO_WARNING` | warning | Audio timeline overrun or silent embedded media |
 | `TRANSCRIPT_WARNING` | warning | Empty transcript text or no timed segments |
 | `DETERMINISM_WARNING` | warning | Forbidden clock/randomness, CSS transition, or runtime diagnostic |
 | `COMPOSITION_NOT_READY` | error | `seek`/`settle` before a successful load |
 | `COMPOSITION_DISPOSED` | error | Operation after the host was disposed |
+| `IMAGE_INVALID` | error | An inspect/compare input is missing, unreadable, not an image, or has different dimensions in a comparison |
+| `POLICY_INVALID` | error | `fy.policy.json` or `FRAMEYARD_POLICY` is missing a required field, has an unknown field, or uses an invalid value |
+| `RESOURCE_POLICY_BLOCKED` | error | The active tier blocks the operation, `--force`, or `--overwrite`; use `--dry-run` or ask the user for a `full` run |
+| `RESOURCE_POLICY_LIMIT` | error | A still request exceeds the active tier's frame cap |
+| `RESOURCE_PROFILE_CONFLICT` | error | `--workers` or `--concurrency` exceeds the `shared-cpu` profile cap |
 
 ## Results
 
@@ -87,6 +111,12 @@ Static validation covers:
 
 Failures use the same envelope with `error.code`, `error.message`, optional `error.details`, and top-level `diagnostics`.
 
+## Lint and resource policy
+
+`lint` returns the same diagnostic shape as `check` but does not launch Chromium. It reports static composition and timeline errors, scene and keyframe projection errors for every timeline frame, media metadata errors, and `DETERMINISM_WARNING` for controller source that calls wall-clock or randomness APIs. It does not run `validateProps` or composition runtime.
+
+Policy failures use the normal error envelope. `RESOURCE_POLICY_BLOCKED` details include `policy`, `operation`, `allowed`, and a `suggestion`; `RESOURCE_POLICY_LIMIT` includes `limit` and `requested`; `RESOURCE_PROFILE_CONFLICT` includes `profile`, `option`, `limit`, and `requested`. Run the blocked `tts`, `transcribe`, or `render` command with `--dry-run` to get the handoff plan instead of treating the block as a render failure. `font add` requires `authoring` or `full`; `font remove` and `font add --force` require `full`.
+
 ## Working with diagnostics
 
 1. Run `npx frameyard check <id> --json`.

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

@@ -7,13 +7,13 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | Code | Meaning | Action |
 | --- | --- | --- |
 | `USAGE` | Invalid flags or missing required arguments | Read `npx frameyard <command> --help`. |
-| `CONFIG_NOT_FOUND` | No `video.config.js` found | Run from the project root or pass `--project`. |
-| `CONFIG_INVALID` | Invalid config or composition entry | Fix `video.config.js`; entries must be explicit, local, `.html`, and exist. |
-| `COMPOSITION_NOT_FOUND` | ID is not listed | Add the entry to `video.config.js`. |
+| `CONFIG_NOT_FOUND` | No `fy.config.js` found | Run from the project root or pass `--project`. |
+| `CONFIG_INVALID` | Invalid config or composition entry | Fix `fy.config.js`; entries must be explicit, local, `.html`, and exist. |
+| `COMPOSITION_NOT_FOUND` | ID is not listed | Add the entry to `fy.config.js`. |
 | `COMPOSITION_INVALID` | Invalid root, metadata, fragment structure, or reserved attribute | Fix the composition fragment; check `details.line` and `details.attribute`. |
 | `COMPOSITION_DOCUMENT_SHELL` | A full document shell is present | Remove `<!doctype>`, `<html>`, `<head>`, and `<body>`; keep the fragment body and top-level metadata. See the 0.8 migration guide. |
 | `IMPORT_MAP_INVALID` | Invalid import map placement, JSON, attributes, or reserved specifier | Keep one or more top-level import maps; remove `frameyard`/`frameyard/` keys and forbidden attributes. |
-| `COMPOSITION_FORMAT_UNRESOLVED` | The composition omits `width`/`height` and the project has no `format` | Declare `width`/`height` on `<fy-composition>`, add `format { width, height, fps }` to `video.config.js`, or render through a timeline. |
+| `COMPOSITION_FORMAT_UNRESOLVED` | The composition omits `width`/`height` and the project has no `format` | Declare `width`/`height` on `<fy-composition>`, add `format { width, height, fps }` to `fy.config.js`, or render through a timeline. |
 | `COMPOSITION_ERROR` | Mount, update, or browser page error | Read the frame location; remove forbidden clocks/randomness or fix the controller. |
 | `COMPOSITION_UPDATE_ASYNC` | `update()` returned a promise | Move async work to `mount()`. |
 | `COMPOSITION_NOT_READY` | `seek`/`settle` before a successful load | Await `load`/`ready`. |
@@ -42,17 +42,41 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | `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. |
+| `TIMELINE_TRANSITION_UNKNOWN_CLIP` | A transition names a missing or self clip | Use two distinct resolved clip IDs in this timeline. |
+| `TIMELINE_TRANSITION_WRONG_TRACK` | The pair is on different tracks | Keep both clips on one video track. |
+| `TIMELINE_TRANSITION_AUDIO_TRACK` | A `dissolve` is on an audio track | Use `"kind": "crossfade"`. |
+| `TIMELINE_TRANSITION_VIDEO_TRACK` | A `crossfade` is on a video track | Use `"kind": "dissolve"`. |
+| `TIMELINE_TRANSITION_NOT_OVERLAPPING` | The incoming clip starts at or after the outgoing clip ends | Move `to.start` earlier; touching endpoints are not a transition. |
+| `TIMELINE_TRANSITION_GEOMETRY` | Reversed order or the incoming clip ends before the outgoing clip | Use `from.start < to.start < from.end < to.end`. |
+| `TIMELINE_TRANSITION_DUPLICATE` | Repeated pair or a clip used twice on one side | Declare each pair once; a clip may chain `from → to → from`. |
+| `TIMELINE_TRANSITION_KIND` | Unsupported or missing `kind` | Use `"kind": "dissolve"` on a video track or `"kind": "crossfade"` on an audio track. |
+| `TIMELINE_TRANSITION_INVALID` | Unknown transition field, invalid id, or unsupported easing | Fix the entry; easing uses the keyframe timing-function vocabulary. |
 | `MEDIA_INVALID` | Invalid media source or attributes | Use local, seekable files and valid `data-fy-*` values. |
 | `MEDIA_SEEK_FAILED` | Embedded video did not reach the requested time | Re-encode with a regular keyframe interval or replace the source. |
 | `TRANSCRIPT_INVALID` | Invalid/missing transcript declaration or JSON | Regenerate with `npx frameyard transcribe`; do not hand-edit timestamps. |
 | `TRANSCRIPT_WORDS_UNAVAILABLE` | Karaoke requested without measured word timings | Re-run transcription with `--words` or remove `words`. |
 | `TRANSCRIPT_WARNING` | Empty transcript text or no timed segments | Regenerate the transcript. |
 | `ASSET_NOT_FOUND` | Required file is missing or unreadable | Restore the asset, model, or text file. |
+| `FONT_MANIFEST_INVALID` | Invalid or unknown manifest field, version, id, family, path, face, or weight | Fix `fy.fonts.json`; reinstall with `npx frameyard font add --file` instead of hand-editing paths. |
+| `FONT_FILE_MISSING` | A font file in the manifest does not exist | Restore the file or remove the face/family. |
+| `FONT_FILE_INVALID` | Wrong extension, signature, or non-file path | Reinstall the font from a valid WOFF2/WOFF/TTF/OTF source. |
+| `FONT_HASH_MISMATCH` | A vendored font file changed size or hash | Restore the file, or reinstall with `npx frameyard font add --force` after approval. |
+| `FONT_LICENSE_MISSING` | License type/file is unknown or absent | Add `--license`/`--license-file`; do not redistribute the project until resolved. |
+| `FONT_LOAD_FAILED` | Chromium could not load a used `@font-face` | Run `npx frameyard font verify`; fix the manifest or file. |
+| `FONT_PROVIDER_UNAVAILABLE` | Fontsource API/CDN is unreachable or returned an invalid response | Retry, check the network, or install the file with `font add --file`/`--url`. |
+| `FONT_DOWNLOAD_FAILED` | A Fontsource or URL response was not a valid font file | Retry the install; verify the URL and family metadata. |
+| `FONT_REMOTE` | CSS still references a remote font/stylesheet | Vendor the font with `font add`; remote fonts are not reproducible. |
+| `FONT_NOT_FOUND` | Fontsource id or `font remove` id is not installed | Search with `npx frameyard font search --json`, or list installed ids. |
 | `DETERMINISM_WARNING` | Forbidden clock/randomness, CSS transition, or runtime warning | Derive state from `frame`/`props`; use `random("stable:key")`. |
 | `OUTPUT_EXISTS` | Output exists and replacement was not approved | Reuse it, choose another path, or pass `--overwrite`/`--force` with permission. |
+| `IMAGE_INVALID` | An inspected or compared image is missing, unreadable, or has different dimensions | Check the paths; for `compare`, use images with the same width and height. |
+| `POLICY_INVALID` | The workspace policy file or `FRAMEYARD_POLICY` is malformed | Read the `details.path`/`jsonPath`, fix the field, or ask the user to remove the override. |
+| `RESOURCE_POLICY_BLOCKED` | The active tier blocks the operation, `--force`, or `--overwrite` | Use `--dry-run` for a handoff plan, or ask the user to run the heavy command with `FRAMEYARD_POLICY=full`. |
+| `RESOURCE_POLICY_LIMIT` | The still request exceeds the tier frame cap | Split the frames into smaller calls; do not assume the 32-frame library cap is available. |
+| `RESOURCE_PROFILE_CONFLICT` | `--workers` or `--concurrency` exceeds the `shared-cpu` cap | Lower the value or omit `--profile`; the CLI does not clamp it. |
 | `OUTPUT_FAILED` | An output or manifest could not be written atomically | Check directory permissions and free space; rerun. |
-| `EXECUTABLE_NOT_FOUND` | `qwen-tts` or `whisper-cli` could not be resolved | Pass `--executable`, set the environment variable, or fix `PATH`. |
-| `TTS_FAILED` | Speech synthesis failed or produced an invalid WAV | Read stderr; verify the talker/codec models and CLI compatibility. |
+| `EXECUTABLE_NOT_FOUND` | `qwen-tts`, `sherpa-onnx-offline-tts`, or `whisper-cli` could not be resolved | Pass `--executable`, set `FRAMEYARD_QWEN_TTS`, `FRAMEYARD_SHERPA_ONNX_TTS`, or `FRAMEYARD_WHISPER_CLI`, or fix `PATH`. |
+| `TTS_FAILED` | Speech synthesis failed or produced an invalid WAV | Read stderr; verify the engine-specific models (`--talker-model`/`--codec-model` for qwen, `--model-dir` for Supertonic) and CLI compatibility. |
 | `TRANSCRIBE_FAILED` | Normalization or `whisper-cli` failed | Verify FFmpeg, the source media, and the Whisper model. |
 | `MANIFEST_INVALID` | Provenance manifest is corrupt or unsupported | Restore or regenerate the manifest; do not invent hashes. |
 | `FFMPEG_FAILED` | FFmpeg is missing, lacks encoders, or failed | Run `npx frameyard doctor --json`; install FFmpeg with libx264 and AAC. |
@@ -62,6 +86,8 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | `CANCELLED` | The operation was interrupted | Rerun when ready. Partial outputs are removed. |
 | `INTERNAL` | Unexpected internal failure | Rerun with `FRAMEYARD_DEBUG=1` and report the stack. |
 
+When a heavy command is blocked, run it once with `--dry-run`. The result contains `commandLine`, `prerequisites`, and `blockers`; report `deferred: true` and the command instead of claiming the render or asset exists. The command line already includes `FRAMEYARD_POLICY=full` when the active tier is not `full`.
+
 ## Behavior to rely on
 
 - A failed render writes to a temporary file and does not publish a partial output.

package/skills/frameyard/references/fonts.md

@@ -0,0 +1,132 @@
+# Fonts
+
+Frameyard vendors font files into the project. A composition uses a font by its
+CSS family name; the preview server injects the generated `@font-face` sheet
+into every composition before author styles. There is no runtime font CDN
+dependency.
+
+## Search Fontsource
+
+```sh
+npx frameyard font search "space grotesk" --subset latin --json
+npx frameyard font search --category sans-serif --variable --limit 10 --json
+```
+
+Filters are `--category`, `--subset`, `--style`, `--variable`, and `--limit`
+(1–100). Search returns `id`, `family`, `category`, `variable`, `weights`,
+`styles`, `subsets`, `license`, and `type`. Fontsource is the default catalog;
+Google Fonts is covered through Fontsource and does not need a separate API key.
+
+## Install a Fontsource family
+
+```sh
+npx frameyard font add space-grotesk --subset latin
+```
+
+The command fetches the family metadata, pins the Fontsource `npmVersion`,
+downloads only the requested WOFF2 files, downloads the package `LICENSE`, and
+records the exact CDN URL and SHA-256 in `fy.fonts.json`.
+
+- A variable family installs the `wght` axis by default. Use multiple
+  `--subset` and `--style` values, for example
+  `--subset latin,latin-ext --style normal,italic`.
+- `--static` installs static files. `--weight` accepts a comma-separated list,
+  for example `--static --weight 400,700`.
+- `--family` overrides the CSS family name when a project needs an alias.
+- Fontsource supplies the license; do not pass `--license` for a Fontsource id.
+- A variable family and a static install of the same family cannot be mixed
+  without `--force`, which replaces the family record.
+
+`FONT_PROVIDER_UNAVAILABLE` means the Fontsource API or CDN was unreachable.
+`FONT_DOWNLOAD_FAILED` means a response was not a valid WOFF2 file.
+
+## Install a local or URL font
+
+```sh
+npx frameyard font add --file ./fonts/SpaceGrotesk.woff2 \
+  --family "Space Grotesk" --weight 300-700 --subset latin \
+  --license OFL-1.1 --license-file ./fonts/OFL.txt
+```
+
+`--weight` is a number (`400`) or a variable range (`300-700`). `--style` is
+`normal` or `italic`. `--subset`, `--unicode-range`, `--license`, and
+`--license-file` are optional; a missing license is a warning. The command
+copies the font and license under `assets/fonts/<id>/`, records the SHA-256 and
+byte size, and prints the CSS family to use.
+
+```sh
+npx frameyard font add --url https://example.com/Inter.woff2 \
+  --family "Inter" --license OFL-1.1 --license-file ./fonts/OFL.txt \
+  --sha256 <hash>
+```
+
+`--url` requires HTTPS; loopback HTTP is allowed for local tests. `--sha256` is
+optional but recommended: the computed hash is always recorded. A URL import
+without `--license`/`--license-file` records `license: { "type": "unknown" }`,
+warns in
+`list`/`verify`/`doctor`, requires the `full` policy, and does not use a shared
+cache. Do not point `--url` at a font whose license you cannot redistribute.
+
+Fontsource is the primary catalog. Google Fonts is covered by Fontsource.
+Bunny Fonts is not a vendoring source: its catalog is undocumented, it exposes
+no license metadata, and its files are not frozen. Fontshare is not a provider:
+its Free Font License prohibits redistribution, subsetting, and format
+conversion for most of its catalog. Only OFL-licensed Fontshare files may be
+vendored, through `font add --url`, with their license text and an explicit
+decision by the user.
+
+## Manage the manifest
+
+```sh
+npx frameyard font list --json
+npx frameyard font verify --json
+npx frameyard font remove space-grotesk --json
+```
+
+`font list` reports installed families, subset/style labels, license, file
+count, bytes, and status. `font verify` checks paths, formats, byte sizes,
+SHA-256 values, license files, and orphaned font directories. `font remove`
+deletes the manifest entry and `assets/fonts/<id>/`; add `--keep-files` to leave
+the binaries in place. `font remove`, `font add --force`, and an unlicensed
+`--url` import require the `full` policy.
+
+Adding another subset, style, or weight to the same family merges into the
+existing entry. Adding the same face again fails with `OUTPUT_EXISTS`; pass
+`--force` to replace it. `fy.fonts.json` has `version: 1` and one entry
+per family. Commit it with `assets/fonts/` and the license files.
+
+## Use the font
+
+```css
+.title {
+  font-family: "Space Grotesk", system-ui, sans-serif;
+  font-weight: 700;
+}
+```
+
+The generated sheet uses `font-display: block`. The host waits for
+`document.fonts.ready` after `mount()`, then fails with `FONT_LOAD_FAILED` if a
+used face reports an error instead of silently capturing fallback text.
+`check`, `still`, and `render` verify sizes and hashes before launching
+Chromium; `lint` verifies existence and size. A changed file fails with
+`FONT_HASH_MISMATCH`.
+
+## Legacy fonts and remote URLs
+
+Existing local `@font-face` rules and `<link rel="stylesheet">` elements keep
+working. A remote font URL in inline CSS, linked local CSS, or a remote
+stylesheet link produces a `FONT_REMOTE` warning. It may work during the loading
+phase, but it is not reproducible and is not covered by the manifest.
+
+## Agent workflow
+
+1. Search Fontsource with `font search` or choose a local/URL source and verify
+   its license.
+2. Install with `font add`, preferring the variable face or the exact static
+   weights the composition uses.
+3. Use the returned family name in the composition CSS.
+4. Run `font verify`, `context --json`, `lint`, and `still`.
+5. Inspect the still when typography or line breaks change.
+
+Do not download fonts from `update()` or `mount()`. Font acquisition is an
+authoring operation, not frame production.

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

@@ -51,7 +51,107 @@ Additional fields are command-specific and stable within the 0.8 contract. `chec
 }
 ```
 
-Static validation diagnostics include source locations. Runtime diagnostics may include a `frame`. Audio and transcript warnings use `AUDIO_WARNING` and `TRANSCRIPT_WARNING`; controller clock/randomness and CSS transition warnings use `DETERMINISM_WARNING`. See [diagnostics](diagnostics.md) for the code table.
+Static validation diagnostics include source locations. Runtime diagnostics may include a `frame`. Timeline diagnostics add `timeline`, `clip`, `track`, `jsonPath`, and, for keyframe errors, `channel` and the zero-based `keyframe` index; transition diagnostics add `from` and `to`. Audio and transcript warnings use `AUDIO_WARNING` and `TRANSCRIPT_WARNING`; controller clock/randomness and CSS transition warnings use `DETERMINISM_WARNING`. See [diagnostics](diagnostics.md) for the code table.
+
+## lint
+
+`lint` reports `kind: "composition"` or `kind: "timeline"` and the same diagnostic shape. A timeline result includes `framesProjected`, `segments`, `tracks`, `clips`, and `transitions`; a composition result includes `metadata` and reports `framesProjected: 0` because lint does not seek frames. The result also includes the active `policy` details.
+
+```json
+{
+  "ok": true,
+  "command": "lint",
+  "policy": { "policy": "authoring", "maxStillFrames": 4, "allowOverwrite": false, "source": "env" },
+  "kind": "timeline",
+  "timeline": "main",
+  "entry": "timelines/main.timeline.json",
+  "format": { "width": 1920, "height": 1080, "fps": 30 },
+  "durationInFrames": 900,
+  "framesProjected": 900,
+  "segments": 3,
+  "diagnostics": [],
+  "elapsedMs": 2
+}
+```
+
+`lint` does not run `validateProps` or composition runtime. A clean lint is not a successful `check`.
+
+## context
+
+`context` returns a read-only project digest. It includes `root`, `format`, `policy`, `compositions`, `timelines`, `assets`, `fonts`, `next`, and `truncated`. Each composition carries its resolved `metadata`, prop `path`/`type` pairs, controller, and diagnostic counts; each timeline carries duration, tracks, clip summaries, transitions, audio/transcript counts, and diagnostic counts. Each font carries `id`, `family`, `provider`, optional `version`, `variable`, `subsets`, `styles`, `license`, `files`, `bytes`, and `status`. `truncated.fonts` reports a clipped font list.
+
+```json
+{
+  "ok": true,
+  "command": "context",
+  "root": "/path/to/project",
+  "format": { "width": 1920, "height": 1080, "fps": 30 },
+  "policy": { "policy": "authoring", "profile": "shared-cpu", "maxStillFrames": 4, "allowOverwrite": false, "source": "file" },
+  "compositions": [
+    { "id": "main", "entry": "compositions/main.html", "kind": "animated", "metadata": { "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 900 }, "controller": { "kind": "external", "src": "compositions/main.controller.js" }, "props": [{ "path": "title", "type": "string" }], "diagnostics": { "errors": 0, "warnings": 0, "codes": [] } }
+  ],
+  "timelines": [],
+  "assets": [],
+  "next": ["npx frameyard lint main --json"],
+  "truncated": { "clips": false, "assets": false, "props": false }
+}
+```
+
+## inspect
+
+`inspect` decodes the first frame and reports `width`, `height`, `bytes`, `alpha`, `blank`, `background`, `content`, `colors`, `luminanceGrid`, and `edgeDensity`. `alpha.coverage` is the opaque fraction; `content.bbox` is `null` when no pixels differ from the background. It never launches Chromium.
+
+## compare
+
+`compare` reports `identical`, `differingPixels`, `totalPixels`, `percent`, `maxChannelDelta`, `meanChannelDelta`, `bbox`, and 3×3 `regions`. It exits 1 when the images differ; the JSON body still has `ok: true` and `identical: false`. Different dimensions fail with `IMAGE_INVALID`.
+
+## add
+
+`add --list` returns `templates` with `name`, `kind`, `description`, and optional `prerequisites`. Adding an entry returns `kind`, `id`, `template`, `entry`, `path`, `register`, `prerequisites`, and `next`. `register` is the exact object to merge into `fy.config.js`; `add` does not edit the config itself.
+
+## font
+
+`font search` returns `provider: "fontsource"`, the `query`, applied `filters`, `results`, and `truncated`. Each result has `id`, `family`, `category`, `variable`, `weights`, `styles`, `subsets`, `license`, optional `version`, and `type`.
+
+`font add` (Fontsource id, `--file`, or `--url`) returns `action: "add"`, a `font` summary (`id`, `family`, `provider`, optional `version`, `variable`, `subsets`, `styles`, `license`, `files`, `bytes`, `status`), the `manifest` path, installed `files`, `warnings`, and `next` commands. Fontsource results identify `provider: "fontsource"` and the pinned `version`; URL results identify `provider: "url"`. `font list` returns `manifest` and a `fonts` array of the same summaries. `font verify` returns `manifest`, `fonts`, `files`, `bytes`, `valid`, and `diagnostics`; errors exit 1, warnings exit 0. `font remove` returns `id`, `family`, `manifest`, `files`, and `keptFiles`.
+
+```json
+{
+  "ok": true,
+  "command": "font",
+  "action": "verify",
+  "manifest": "/project/fy.fonts.json",
+  "fonts": 1,
+  "files": 1,
+  "bytes": 22288,
+  "valid": true,
+  "diagnostics": []
+}
+```
+
+A present-but-invalid manifest fails with `FONT_MANIFEST_INVALID`; missing files use `FONT_FILE_MISSING`, changed content uses `FONT_HASH_MISMATCH`, and a failed browser load uses `FONT_LOAD_FAILED`. Remote font CSS is a `FONT_REMOTE` warning. Fontsource network or API failures use `FONT_PROVIDER_UNAVAILABLE`; invalid downloaded WOFF2 content uses `FONT_DOWNLOAD_FAILED`; a missing Fontsource family or `font remove` id uses `FONT_NOT_FOUND`.
+
+## dry run
+
+`tts`, `transcribe`, and `render` accept `--dry-run`. The result has `dryRun: true`, the active `policy`, a command-specific `plan`, a shell-ready `commandLine`, `prerequisites`, `blockers`, and the output path. It does not create the output directory, write the manifest, load a model, launch Chromium, or encode.
+
+```json
+{
+  "ok": true,
+  "command": "render",
+  "dryRun": true,
+  "deferred": true,
+  "policy": { "policy": "authoring", "maxStillFrames": 4, "allowOverwrite": false, "source": "env" },
+  "plan": { "kind": "video", "frames": 900, "segments": 3, "workers": 2, "encoder": "auto", "codec": "h264", "container": "mp4", "probed": false },
+  "commandLine": "FRAMEYARD_POLICY=full npx frameyard render main --workers 2 --codec h264 --container mp4",
+  "prerequisites": ["assets/voice.wav"],
+  "blockers": [],
+  "diagnostics": [],
+  "output": { "path": "out/main.mp4", "exists": false }
+}
+```
+
+An existing output appears in `blockers` with `OUTPUT_EXISTS`; the dry run still exits 0. The handoff command includes `FRAMEYARD_POLICY=full` when the active tier is not `full`. A dry run is not a render; `deferred: true` means the heavy operation was not executed and the `commandLine` is the handoff.
 
 ## check
 
@@ -111,6 +211,10 @@ A static composition result reports `kind: "static"`, dimensions only, `framesCh
 }
 ```
 
+### Timeline check
+
+A timeline check reports `timeline`, `entry`, `format`, `durationInFrames`, `framesChecked`, `tracks`, `clips`, `transitions`, `audio`, `transcripts`, `diagnostics`, and `elapsedMs`. `framesChecked` equals the timeline duration; `transitions` is the resolved count, and transition diagnostics carry `from`/`to` and `jsonPath` in `details`.
+
 ## still
 
 ```json
@@ -191,6 +295,7 @@ A successful render means the final path exists and was published atomically. A
 {
   "ok": true,
   "command": "tts",
+  "engine": "qwen",
   "path": "/absolute/path/assets/voice.wav",
   "bytes": 480000,
   "sha256": "64-character hex digest",
@@ -198,12 +303,12 @@ A successful render means the final path exists and was published atomically. A
   "channels": 1,
   "speaker": "vivian",
   "language": "English",
-  "manifest": "/absolute/path/frameyard.assets.json",
+  "manifest": "/absolute/path/fy.assets.json",
   "elapsedMs": 12000
 }
 ```
 
-`language` is omitted when it was not supplied.
+`engine` is `qwen` or `supertonic`. `language` is omitted when it was not supplied; Supertonic always supplies it. `device` is present only for qwen.
 
 ## transcribe
 
@@ -230,7 +335,7 @@ A successful render means the final path exists and was published atomically. A
       "sha256": "64-character hex digest"
     }
   ],
-  "manifest": "/absolute/path/frameyard.assets.json",
+  "manifest": "/absolute/path/fy.assets.json",
   "elapsedMs": 30000
 }
 ```
@@ -239,6 +344,8 @@ A successful render means the final path exists and was published atomically. A
 
 ## doctor
 
+The doctor result adds `policy` and `resources` fields. `policy.status` is `ok` or `error`; an invalid policy is reported as a finding without preventing the environment checks. `resources` reports platform, architecture, CPU count, load average, and total/free memory. `fonts` reports the project font manifest path, whether it exists, `valid`, installed `fonts`/`files`/`bytes`, and an optional `detail` for the first integrity problem.
+
 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
@@ -271,6 +378,12 @@ Doctor reports findings rather than throwing for environment problems. `ok: true
       "status": "missing",
       "requested": false,
       "referenceRevision": "..."
+    },
+    "sherpaOnnxTts": {
+      "name": "sherpa-onnx-offline-tts",
+      "status": "missing",
+      "requested": false,
+      "referenceRevision": "..."
     }
   },
   "models": [
@@ -282,8 +395,8 @@ Doctor reports findings rather than throwing for environment problems. `ok: true
       "sha256": "64-character hex digest"
     }
   ],
-  "manifest": { "path": "/absolute/path/frameyard.assets.json", "exists": true, "valid": true, "artifacts": 2 }
+  "manifest": { "path": "/absolute/path/fy.assets.json", "exists": true, "valid": true, "artifacts": 2 }
 }
 ```
 
-`models` is populated only for model paths passed explicitly with `--talker-model`, `--codec-model`, or `--model`. `healthy: false` exits `1`. Missing optional integrations do not fail, but a found executable with incompatible capabilities does.
+`models` is populated only for model paths passed explicitly with `--talker-model`, `--codec-model`, `--model-dir`, or `--model`. A Supertonic `--model-dir` reports one entry with role `supertonic`; `tts` provenance records the seven individual model files. `healthy: false` exits `1`. Missing optional integrations do not fail, but a found executable with incompatible capabilities does.