frameyard 0.7.0 → 0.9.0

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

@@ -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. `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.
+Additional fields are command-specific and stable within the 0.8 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
 
@@ -51,14 +51,117 @@ Additional fields are command-specific and stable within the 0.4 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
 
+Animated composition results report `kind: "animated"`. `metadata` reports the resolved format, combining declared values with the project `format`.
+
 ```json
 {
   "ok": true,
   "command": "check",
+  "kind": "animated",
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "inline" },
@@ -89,7 +192,28 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 }
 ```
 
-`entry` is the project-relative HTML path. `controller` is `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`.
+`entry` is the project-relative composition fragment path. `controller` is `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`.
+
+A static composition result reports `kind: "static"`, dimensions only, `framesChecked: 1`, and no audio/transcript fields:
+
+```json
+{
+  "ok": true,
+  "command": "check",
+  "kind": "static",
+  "composition": "still",
+  "entry": "compositions/still.html",
+  "controller": null,
+  "metadata": { "width": 1920, "height": 1080, "static": true },
+  "framesChecked": 1,
+  "diagnostics": [],
+  "elapsedMs": 600
+}
+```
+
+### 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
 
@@ -111,14 +235,17 @@ Static validation diagnostics include source locations. Runtime diagnostics may
 }
 ```
 
-`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`.
+`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`. A static composition exposes only frame `0`; other frames fail with `FRAME_OUT_OF_RANGE`.
 
 ## render
 
+Animated composition and timeline results report `kind: "video"`:
+
 ```json
 {
   "ok": true,
   "command": "render",
+  "kind": "video",
   "composition": "hello",
   "entry": "compositions/hello.html",
   "controller": { "kind": "inline" },
@@ -141,7 +268,26 @@ 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>.<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.
+A static composition result reports `kind: "image"` and has no fps, duration, frame count, codec, container, encoder, audio, or transcript fields:
+
+```json
+{
+  "ok": true,
+  "command": "render",
+  "kind": "image",
+  "composition": "still",
+  "entry": "compositions/still.html",
+  "controller": null,
+  "path": "/absolute/path/out/still.png",
+  "width": 1920,
+  "height": 1080,
+  "bytes": 48210,
+  "diagnostics": [],
+  "elapsedMs": 700
+}
+```
+
+A successful render means the final path exists and was published atomically. A nonzero exit means no new partial output was published. Without `--out`, the final path is `out/<composition-id>.<ext>` for video and `out/<composition-id>.png` for a static composition 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, and a static composition rejects it. `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
 
@@ -149,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",
@@ -156,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
 
@@ -188,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
 }
 ```
@@ -197,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
@@ -229,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": [
@@ -240,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.

package/skills/frameyard/references/quick-reference.md

@@ -0,0 +1,222 @@
+# Quick reference
+
+Use this page when context is limited or when you need one canonical skeleton.
+Read a topic reference only when the task needs it; the full contract is in
+`SKILL.md` and the linked references.
+
+## Choose the smallest authoring level
+
+1. **Static composition** for a poster, card, or thumbnail: no `duration-in-frames`, no `fps`, renders to PNG.
+2. **CSS animation** for timed reveals, wipes, and simple motion: `@keyframes` plus `data-fy-anim-*`.
+3. **Bindings** for props-driven text, attributes, classes, conditionals, and repeats.
+4. **Controller** for Canvas 2D, WebGL, karaoke, or per-frame math CSS cannot express.
+5. **Timeline** when several compositions, media clips, or audio tracks must share one deliverable.
+
+Do not use a controller when CSS or bindings are enough.
+
+## Animated composition
+
+A composition is a partial HTML fragment, never a full document. Props, the
+controller, import maps, and styles are top-level siblings of the root.
+
+```html
+<script type="application/json" data-fy="props">{ "title": "Hello" }</script>
+<style>
+  html, body { margin: 0; width: 100%; height: 100%; }
+  @keyframes rise { from { opacity: 0; } to { opacity: 1; } }
+  h1 { animation: rise 1s linear both; font: 8vmin system-ui; color: white; }
+  body { background: #101820; display: grid; place-items: center; }
+</style>
+<fy-composition duration-in-frames="150">
+  <h1 data-fy-text="title" data-fy-anim-start="0" data-fy-anim-duration="30"></h1>
+</fy-composition>
+```
+
+`width`, `height`, and `fps` are optional and inherit the project `format`.
+Declare both `width` and `height` together. Never derive metadata from props.
+
+## Static composition
+
+```html
+<script type="application/json" data-fy="props">{ "title": "Poster" }</script>
+<style>
+  body { margin: 0; background: #0c1220; color: #ff7a45; display: grid; place-items: center; }
+  h1 { font: 8vmin system-ui; }
+</style>
+<fy-composition>
+  <h1 data-fy-text="title"></h1>
+</fy-composition>
+```
+
+A static composition has no frame clock: no `data-fy-anim-*`, no `<video>`,
+`<audio>`, or `<fy-transcript>`. Its controller runs `mount()` only.
+
+## Fonts
+
+Fontsource is the default catalog. Search, then install a pinned family:
+
+```sh
+npx frameyard font search "space grotesk" --subset latin --json
+npx frameyard font add space-grotesk --subset latin
+```
+
+Variable families install the `wght` face by default. Use `--static --weight
+400,700` for static files. A local or brand font uses `font add --file`; an
+explicit HTTPS source uses `font add --url` and may pass `--sha256`. A URL
+import without `--license` or `--license-file` is recorded as unknown and
+requires `full`.
+
+Then use the family name normally:
+
+```css
+h1 { font-family: "Space Grotesk", system-ui, sans-serif; font-weight: 700; }
+```
+
+The server injects `@font-face` before author styles, uses `font-display: block`,
+and the host waits for `document.fonts.ready`. Run `font verify` after moving
+files. Remote font URLs produce `FONT_REMOTE`; a used face that fails to load
+produces `FONT_LOAD_FAILED`. See [fonts](fonts.md).
+
+## Timeline
+
+```json
+{
+  "version": 1,
+  "tracks": [
+    { "id": "v1", "kind": "video" },
+    { "id": "a1", "kind": "audio" }
+  ],
+  "clips": [
+    {
+      "id": "intro",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "intro" },
+      "start": 0
+    },
+    {
+      "id": "music",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/music.wav" },
+      "start": 0,
+      "duration": 150,
+      "audio": { "gain": 0.6 }
+    }
+  ]
+}
+```
+
+`start`, `sourceIn`, and `duration` are timeline frames. Image clips and static
+composition clips require an explicit `duration`; a static composition clip
+needs `sourceIn: 0` and contributes no audio. Source kinds are `composition`,
+`timeline`, `video`, `image`, and `audio`.
+
+## Bindings
+
+- `data-fy-text="path"` sets text.
+- `data-fy-attr-src="path"` sets an attribute.
+- `data-fy-class-active="path"` toggles a class.
+- `data-fy-if="path"` removes the element when false.
+- `<template data-fy-repeat="items">` clones content; use `item` and `index`.
+- Paths are dot-separated; missing paths warn and resolve empty.
+
+Bindings apply once per load, before `mount()`. Controller-created DOM is not
+re-bound.
+
+## Controller
+
+```html
+<script type="text/fy-controller">
+export default {
+  mount({ root, props }) {},
+  update({ frame, props }) {},
+  dispose() {},
+};
+</script>
+```
+
+Exactly one controller is allowed, inline or external. `mount` may be async;
+`update` is synchronous and seek-safe. The controller is the only executable
+code. Use `random("stable:key")` from `frameyard/runtime`, never `Math.random()`.
+
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `npx frameyard context --json` | One compact project digest: format, props, timelines, assets, policy, next commands |
+| `npx frameyard lint <id> --json` | Fast edit loop: static validation, scene/keyframe projection, controller determinism |
+| `npx frameyard check <id> --json` | Full gate: props hooks and every animated frame through Chromium |
+| `npx frameyard still <id> --frame <spec> --json` | Inspect representative frames; policy caps the count |
+| `npx frameyard inspect <image> --json` | Blank, alpha, colors, content bbox, luminance grid, edge density |
+| `npx frameyard compare <a> <b> --json` | Pixel and 3×3 region diff; exits 1 when different |
+| `npx frameyard render <id> --dry-run --json` | Handoff plan without Chromium, FFmpeg, or a model |
+| `npx frameyard render <id> --json` | Produce the video when the policy allows it |
+| `npx frameyard add --list --json` | List project templates |
+| `npx frameyard add composition <id> --template <name> --json` | Write a valid fragment and print the config snippet |
+| `npx frameyard font search <query> --json` | Search Fontsource by name, category, subset, style, or variable |
+| `npx frameyard font add <fontsource-id> --json` | Pin and vendor a Fontsource family; variable `wght` by default |
+| `npx frameyard font add <fontsource-id> --static --weight 400,700 --json` | Install explicit static weights |
+| `npx frameyard font add --file <path> --family <name> --json` | Vendor a local font into `assets/fonts/` and update `fy.fonts.json` |
+| `npx frameyard font add --url <https-url> --family <name> --json` | Download and vendor an HTTPS font, optionally with `--sha256` |
+| `npx frameyard font list --json` | Installed families, subsets, licenses, files, and status |
+| `npx frameyard font verify --json` | Manifest paths, hashes, licenses, and orphaned directories |
+| `npx frameyard font remove <id> --json` | Remove a font and its directory; `--keep-files` keeps the binaries |
+| `npx frameyard doctor --json` | Environment, integrations, policy, fonts, and resources |
+
+Every non-interactive command accepts `--json`. Parse stdout; read stderr for
+progress and diagnostics.
+
+## Resource policy
+
+`fy.policy.json` is discovered from the working directory upward,
+independent of `fy.config.js`.
+
+| Tier | `still` | `check` | `tts`/`transcribe`/`render` | overwrite |
+| --- | --- | --- | --- | --- |
+| `light` | 1 frame | blocked | blocked | denied |
+| `authoring` | 4 frames | low priority | blocked | denied |
+| `full` | 32 frames | allowed | allowed | allowed |
+
+`lint`, `context`, `doctor`, `add`, `inspect`, `compare`, and `--dry-run` are
+available in every tier. `font search`, `font list`, and `font verify` are
+available in every tier; `font add` requires `authoring` or `full`; `font
+remove`, `font add --force`, and `font add --url` without
+`--license`/`--license-file` require `full`. When a heavy command is blocked, run it with `--dry-run`, report `deferred: true`, and give the user
+`commandLine`, `prerequisites`, and `blockers`.
+
+## Ten diagnostics that matter
+
+| Code | Fix |
+| --- | --- |
+| `COMPOSITION_DOCUMENT_SHELL` | Remove `<!doctype>`, `<html>`, `<head>`, and `<body>`; compositions are fragments |
+| `COMPOSITION_FORMAT_UNRESOLVED` | Declare `width`/`height` or add project `format` |
+| `COMPOSITION_INVALID` | Check the single `<fy-composition>` root and metadata |
+| `CONTROLLER_INVALID` | Exactly one controller; inline XOR `src`; at least one export |
+| `SCRIPT_NOT_ALLOWED` | Move executable code into the controller |
+| `BINDING_PATH_MISSING` | Fix the props path; use the diagnostic suggestion |
+| `BINDING_INVALID` | Unknown `data-fy-*` attribute; use a documented binding |
+| `TIMELINE_CLIP_OUT_OF_RANGE` | Keyframes cannot extend a clip; lengthen the clip or move the key |
+| `TIMELINE_CLIP_OVERLAP` | Declare a transition or move the clip |
+| `RESOURCE_POLICY_BLOCKED` | Use `--dry-run`, or ask the user for `FRAMEYARD_POLICY=full` |
+
+Font diagnostics: `FONT_HASH_MISMATCH` means the vendored file changed; restore
+it or reinstall with `font add --force`. `FONT_LOAD_FAILED` means a used face
+did not load; check the manifest and `font verify`. `FONT_REMOTE` is a warning
+that the composition still depends on a remote font URL.
+
+## Do not
+
+- Use `Date.now()`, `performance.now()`, timers, `requestAnimationFrame` loops, or CSS transitions as animation inputs.
+- Call `play()`, `pause()`, or set `currentTime` on embedded media.
+- Fetch remote data from `update()`; load during `mount()`.
+- Put visual content outside `<fy-composition>`.
+- Edit `fy.policy.json`, host configuration, or the skill source.
+- Claim success when `check` fails, a still is missing, or a render did not run.
+
+## Next
+
+- Full authoring rules: [deterministic authoring](deterministic-authoring.md)
+- Fonts: [fonts](fonts.md)
+- Timelines and keyframes: [timelines](timelines.md)
+- Error codes: [diagnostics](diagnostics.md)
+- Result shapes: [JSON results](json-results.md)
+- Recovery loops: [failure recovery](failure-recovery.md)