frameyard 0.8.0 → 0.9.0

package/examples/nested/timelines/nested-reel.timeline.json

@@ -0,0 +1,52 @@
+{
+  "version": 1,
+  "name": "Nested timelines: A full, B full, A as a group",
+  "durationInFrames": 360,
+  "background": "#05070d",
+  "tracks": [
+    { "id": "v1", "kind": "video", "name": "Chapter A · full frame" },
+    { "id": "v2", "kind": "video", "name": "Chapter B · full frame" },
+    { "id": "v3", "kind": "video", "name": "Chapter A · group transform" },
+    { "id": "v4", "kind": "video", "name": "Overlay" }
+  ],
+  "clips": [
+    {
+      "id": "chapter-a-full",
+      "track": "v1",
+      "source": { "kind": "timeline", "id": "chapter-a" },
+      "start": 0,
+      "duration": 120
+    },
+    {
+      "id": "chapter-b-full",
+      "track": "v2",
+      "source": { "kind": "timeline", "id": "chapter-b" },
+      "start": 120,
+      "duration": 120
+    },
+    {
+      "id": "chapter-a-group",
+      "track": "v3",
+      "source": { "kind": "timeline", "id": "chapter-a" },
+      "start": 240,
+      "duration": 120,
+      "transform": {
+        "fit": "cover",
+        "width": 480,
+        "height": 270,
+        "x": 360,
+        "y": 180,
+        "rotation": 0,
+        "opacity": 1
+      },
+      "audio": { "muted": true }
+    },
+    {
+      "id": "overlay",
+      "track": "v4",
+      "source": { "kind": "composition", "id": "overlay" },
+      "start": 0,
+      "duration": 360
+    }
+  ]
+}

package/examples/static/README.md

@@ -7,9 +7,9 @@ timeline uses the same composition as an image layer for 90 frames.
 
 ```sh
 node dist/cli.js check still --project examples/static
-node dist/cli.js render still --project examples/static --out examples/static/out/still.png
+FRAMEYARD_POLICY=full node dist/cli.js render still --project examples/static --out examples/static/out/still.png
 node dist/cli.js check still-timeline --project examples/static
-node dist/cli.js render still-timeline --project examples/static --out examples/static/out/still-timeline.mp4
+FRAMEYARD_POLICY=full node dist/cli.js render still-timeline --project examples/static --out examples/static/out/still-timeline.mp4
 ```
 
 `render still` defaults to `out/still.png`. Static compositions render to PNG;

package/examples/transitions/README.md

@@ -0,0 +1,128 @@
+# Timeline transitions example
+
+This project has two timelines:
+
+- `transitions` dissolves three timed composition cards on one video track and
+  lets their contributed audio crossfade.
+- `audio-crossfade` mutes the composition audio and places the sound directly on
+  an audio track, with a `crossfade` between two audio clips.
+
+## Visual dissolve with contributed audio
+
+`transitions` is a 4-second, 1280×720, 30 fps timeline:
+
+- **alpha** `0..60` — the A-major card and the outgoing clip. It keeps rendering
+  for the whole overlap, including after `beta` starts.
+- **beta** `45..105` — the C#-major card and the incoming clip. Its first 15
+  frames are the `alpha → beta` dissolve, then it runs alone, then it hands off
+  to `gamma`.
+- **gamma** `90..120` — the E-major card and the second incoming clip.
+
+Each composition is a timed HTML fragment (`duration-in-frames`) with one
+`<audio>` element. The audio belongs to the visual clip, so the dissolve
+crossfades it automatically.
+
+## Audio clips on the timeline
+
+`audio-crossfade` renders the same alpha and beta cards for 3.5 seconds, but
+mutes their composition audio with `audio.muted: true` and puts the sound on
+`a1` instead:
+
+- **chord-alpha** `0..60` — `assets/alpha.wav`, the outgoing chord.
+- **chord-beta** `45..105` — `assets/beta.wav`, the incoming chord.
+
+```json
+"transitions": [
+  { "from": "alpha", "to": "beta", "kind": "dissolve", "easing": "ease-in-out" },
+  { "from": "chord-alpha", "to": "chord-beta", "kind": "crossfade", "easing": "linear" }
+]
+```
+
+The visual dissolve and the audio crossfade share the same 15-frame overlap, so
+the picture and the sound hand off together. `crossfade` is the audio-track
+kind: it applies an equal-power gain ramp and changes no pixels.
+
+## Transition contract
+
+`transitions` is a timeline-level array of `{ "from", "to", "kind", "easing" }`:
+
+- `from` and `to` are clip IDs on the **same track**. A transition never spans
+  tracks.
+- `kind` is `dissolve` on a video track or `crossfade` on an audio track. A
+  dissolve fades the incoming picture in and also crossfades the audio the two
+  clips contribute; a crossfade only ramps audio gain. Using the wrong kind for
+  the track is an error.
+- `easing` defaults to `linear` and accepts the same CSS timing-function
+  vocabulary as clip keyframes.
+- The transition window is the overlap: `to.start .. from.end`. There is no
+  `duration` field; move the incoming clip earlier to make the transition
+  longer.
+- The geometry must be `from.start < to.start < from.end < to.end`. The incoming
+  clip must begin inside the outgoing clip and outlast it.
+- A clip may be the `to` of one transition and the `from` of the next, so
+  transitions chain. A clip cannot participate twice on the same side.
+- Overlap without a declared transition is still an error. Touching endpoints
+  are not a transition.
+
+During a dissolve the incoming clip composites above the outgoing clip with
+alpha `clipOpacity × eased progress`. Clip opacity may be static or keyframed
+and multiplies the transition.
+
+## Audio semantics
+
+Both kinds use an equal-power ramp over the window: the outgoing clip's gain is
+`sqrt(1 - t)` and the incoming clip's is `sqrt(t)`, after easing. For a
+dissolve, the ramp applies to the audio the two visual clips contribute. For a
+crossfade, it applies to the two audio-track clips themselves.
+
+`audio.muted` still zeroes a side, and `audio.gain` plus the track `gain`
+multiply the envelope. A crossfade on an audio track has no visual effect; a
+dissolve on an audio track is rejected.
+
+## What to look at
+
+The first dissolve uses `ease-in-out`, so it starts and ends gently around a
+faster middle. The second uses `linear`, so its progress tracks the frame clock
+exactly. The read-only preview draws a hatched band over each overlap, including
+the audio crossfade; the band is informational, not editable.
+
+Render or preview with sound. In `transitions` the chords hand off at frames 45
+and 90. In `audio-crossfade` the sound is on the timeline, and the A → C#
+crossfade happens at frames 45..60 while the picture dissolves over the same
+window.
+
+## Files
+
+```text
+examples/transitions/
+  assets/alpha.wav                 A-major chord, 2 s
+  assets/beta.wav                  C#-major chord, 2 s
+  assets/gamma.wav                 E-major chord, 1 s
+  compositions/alpha.html          outgoing timed card
+  compositions/beta.html           middle timed card
+  compositions/gamma.html          incoming timed card
+  timelines/transitions.timeline.json
+  timelines/audio-crossfade.timeline.json
+  fy.config.js
+```
+
+## Commands
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check transitions --project examples/transitions
+node dist/cli.js check audio-crossfade --project examples/transitions
+node dist/cli.js still transitions --frame 0,52,60,97 --project examples/transitions --out transitions-stills
+node dist/cli.js still audio-crossfade --frame 52 --project examples/transitions --out audio-crossfade-still.png
+FRAMEYARD_POLICY=full node dist/cli.js render transitions --project examples/transitions
+FRAMEYARD_POLICY=full node dist/cli.js render audio-crossfade --project examples/transitions
+node dist/cli.js dev --project examples/transitions
+```
+
+`render` writes `out/<timeline-id>.mp4` inside the project by default. Frame 52
+sits halfway into the first dissolve, frame 59 is the last frame of that overlap,
+and frame 97 is inside the second dissolve. In `audio-crossfade`, frame 52 is
+also inside the audio crossfade. `still` and `render` share the same composite
+path, so a still taken inside a transition matches the rendered frame.

package/examples/transitions/compositions/alpha.html

@@ -0,0 +1,56 @@
+<style>
+  :root {
+    color-scheme: dark;
+  }
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #0b1220;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-content: center;
+    gap: 20px;
+    text-align: center;
+    color: #e9f1ff;
+    font-family:
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    background:
+      radial-gradient(circle at 50% 42%, rgba(88, 140, 255, 0.55), transparent 58%),
+      linear-gradient(160deg, #0d1c3a, #0b1220 70%);
+  }
+  .eyebrow {
+    font-size: 20px;
+    letter-spacing: 0.42em;
+    text-transform: uppercase;
+    color: #8fb3ff;
+  }
+  h1 {
+    margin: 0;
+    font-size: 148px;
+    line-height: 0.92;
+    letter-spacing: -0.04em;
+    font-weight: 800;
+  }
+  p {
+    margin: 0;
+    font-size: 28px;
+    color: #9fb0c9;
+  }
+</style>
+<fy-composition duration-in-frames="60">
+  <div class="card">
+    <div class="eyebrow">scene one</div>
+    <h1>ALPHA</h1>
+    <p>the outgoing clip keeps rendering</p>
+  </div>
+  <audio src="assets/alpha.wav" data-fy-start="0" data-fy-duration="2"></audio>
+</fy-composition>

package/examples/transitions/compositions/beta.html

@@ -0,0 +1,56 @@
+<style>
+  :root {
+    color-scheme: dark;
+  }
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #1d1206;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-content: center;
+    gap: 20px;
+    text-align: center;
+    color: #fff5e6;
+    font-family:
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    background:
+      radial-gradient(circle at 50% 42%, rgba(255, 168, 66, 0.6), transparent 58%),
+      linear-gradient(160deg, #2a1708, #1d1206 70%);
+  }
+  .eyebrow {
+    font-size: 20px;
+    letter-spacing: 0.42em;
+    text-transform: uppercase;
+    color: #ffc078;
+  }
+  h1 {
+    margin: 0;
+    font-size: 148px;
+    line-height: 0.92;
+    letter-spacing: -0.04em;
+    font-weight: 800;
+  }
+  p {
+    margin: 0;
+    font-size: 28px;
+    color: #d8b892;
+  }
+</style>
+<fy-composition duration-in-frames="60">
+  <div class="card">
+    <div class="eyebrow">scene two</div>
+    <h1>BETA</h1>
+    <p>the incoming clip fades in above it</p>
+  </div>
+  <audio src="assets/beta.wav" data-fy-start="0" data-fy-duration="2"></audio>
+</fy-composition>

package/examples/transitions/compositions/gamma.html

@@ -0,0 +1,56 @@
+<style>
+  :root {
+    color-scheme: dark;
+  }
+  html,
+  body {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    background: #071a18;
+  }
+  .card {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-content: center;
+    gap: 20px;
+    text-align: center;
+    color: #e6fffb;
+    font-family:
+      ui-sans-serif,
+      system-ui,
+      -apple-system,
+      "Segoe UI",
+      sans-serif;
+    background:
+      radial-gradient(circle at 50% 42%, rgba(64, 224, 190, 0.45), transparent 58%),
+      linear-gradient(160deg, #0a2823, #071a18 70%);
+  }
+  .eyebrow {
+    font-size: 20px;
+    letter-spacing: 0.42em;
+    text-transform: uppercase;
+    color: #7cf0d8;
+  }
+  h1 {
+    margin: 0;
+    font-size: 148px;
+    line-height: 0.92;
+    letter-spacing: -0.04em;
+    font-weight: 800;
+  }
+  p {
+    margin: 0;
+    font-size: 28px;
+    color: #9ec9c1;
+  }
+</style>
+<fy-composition duration-in-frames="30">
+  <div class="card">
+    <div class="eyebrow">scene three</div>
+    <h1>GAMMA</h1>
+    <p>one clip can dissolve in and out</p>
+  </div>
+  <audio src="assets/gamma.wav" data-fy-start="0" data-fy-duration="1"></audio>
+</fy-composition>

package/examples/transitions/fy.config.js

@@ -0,0 +1,12 @@
+export default {
+  format: { width: 1280, height: 720, fps: 30 },
+  compositions: {
+    alpha: "./compositions/alpha.html",
+    beta: "./compositions/beta.html",
+    gamma: "./compositions/gamma.html",
+  },
+  timelines: {
+    transitions: "./timelines/transitions.timeline.json",
+    "audio-crossfade": "./timelines/audio-crossfade.timeline.json",
+  },
+};

package/examples/transitions/timelines/audio-crossfade.timeline.json

@@ -0,0 +1,44 @@
+{
+  "version": 1,
+  "name": "Audio crossfade",
+  "tracks": [
+    { "id": "v1", "kind": "video" },
+    { "id": "a1", "kind": "audio", "gain": 1 }
+  ],
+  "clips": [
+    {
+      "id": "alpha",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "alpha" },
+      "start": 0,
+      "duration": 60,
+      "audio": { "muted": true }
+    },
+    {
+      "id": "beta",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "beta" },
+      "start": 45,
+      "duration": 60,
+      "audio": { "muted": true }
+    },
+    {
+      "id": "chord-alpha",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/alpha.wav" },
+      "start": 0,
+      "duration": 60
+    },
+    {
+      "id": "chord-beta",
+      "track": "a1",
+      "source": { "kind": "audio", "src": "assets/beta.wav" },
+      "start": 45,
+      "duration": 60
+    }
+  ],
+  "transitions": [
+    { "from": "alpha", "to": "beta", "kind": "dissolve", "easing": "ease-in-out" },
+    { "from": "chord-alpha", "to": "chord-beta", "kind": "crossfade", "easing": "linear" }
+  ]
+}

package/examples/transitions/timelines/transitions.timeline.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "tracks": [{ "id": "main", "kind": "video" }],
+  "clips": [
+    {
+      "id": "alpha",
+      "track": "main",
+      "source": { "kind": "composition", "id": "alpha" },
+      "start": 0,
+      "duration": 60
+    },
+    {
+      "id": "beta",
+      "track": "main",
+      "source": { "kind": "composition", "id": "beta" },
+      "start": 45,
+      "duration": 60
+    },
+    {
+      "id": "gamma",
+      "track": "main",
+      "source": { "kind": "composition", "id": "gamma" },
+      "start": 90,
+      "duration": 30
+    }
+  ],
+  "transitions": [
+    { "from": "alpha", "to": "beta", "kind": "dissolve", "easing": "ease-in-out" },
+    { "from": "beta", "to": "gamma", "kind": "dissolve", "easing": "linear" }
+  ]
+}

package/examples/video/README.md

@@ -92,10 +92,10 @@ node dist/cli.js still video --frame 210 --project examples/video --out video-st
 node dist/cli.js still video-mp4 --frame 210 --project examples/video --out video-mp4-still.png
 node dist/cli.js still video-timeline --frame 210 --project examples/video --out video-timeline-still.png
 node dist/cli.js still video-timeline-mp4 --frame 210 --project examples/video --out video-timeline-mp4-still.png
-node dist/cli.js render video --project examples/video --props examples/video/props/video.json
-node dist/cli.js render video-mp4 --project examples/video --props examples/video/props/video.json
-node dist/cli.js render video-timeline --project examples/video --props examples/video/props/video-timeline.json
-node dist/cli.js render video-timeline-mp4 --project examples/video --props examples/video/props/video-timeline.json
+FRAMEYARD_POLICY=full node dist/cli.js render video --project examples/video --props examples/video/props/video.json
+FRAMEYARD_POLICY=full node dist/cli.js render video-mp4 --project examples/video --props examples/video/props/video.json
+FRAMEYARD_POLICY=full node dist/cli.js render video-timeline --project examples/video --props examples/video/props/video-timeline.json
+FRAMEYARD_POLICY=full node dist/cli.js render video-timeline-mp4 --project examples/video --props examples/video/props/video-timeline.json
 ```
 
 Start the interactive preview with:

package/examples/webgl/README.md

@@ -20,7 +20,7 @@ From the repository root:
 pnpm build
 node dist/cli.js check webgl --project examples/webgl
 node dist/cli.js still webgl --frame 210 --project examples/webgl --out webgl-still.png
-node dist/cli.js render webgl --project examples/webgl --props examples/webgl/props/webgl.json
+FRAMEYARD_POLICY=full node dist/cli.js render webgl --project examples/webgl --props examples/webgl/props/webgl.json
 ```
 
 Start the interactive preview with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "dist",
     "examples",
     "docs",
+    "scaffolds",
     "skills",
     "README.md",
     "CHANGELOG.md",
@@ -71,17 +72,23 @@
     "lint": "oxlint",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm typecheck:test && pnpm typecheck:browser",
+    "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm build && pnpm typecheck:test && pnpm typecheck:browser",
     "compare-stills": "node scripts/compare-stills.mjs",
-    "check": "pnpm check:static && pnpm test",
-    "check:preview": "pnpm check:static && pnpm test:preview",
+    "check": "pnpm check:static && pnpm test:built && node scripts/check-stamp.mjs record",
+    "check:preview": "pnpm check:static && vitest run test/preview-runtime.test.ts test/timeline-preview.test.ts test/timeline-preview-runtime.test.ts",
+    "check:changelog": "node scripts/check-changelog.mjs",
     "test": "pnpm build && vitest run",
+    "test:built": "vitest run",
+    "test:integration": "pnpm build && vitest run --project integration",
+    "test:examples": "pnpm build && vitest run test/examples.test.ts",
     "test:preview": "pnpm build && vitest run test/preview-runtime.test.ts test/timeline-preview.test.ts test/timeline-preview-runtime.test.ts",
-    "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/encoders.test.ts test/random.test.ts test/release.test.ts test/scaffold.test.ts test/transcript.test.ts",
+    "test:unit": "vitest run --project unit",
     "bench": "pnpm build && node scripts/bench-render.mjs",
     "bench:static": "pnpm build && node bench/static-composition.mjs",
+    "eval:local": "node evals/runner.mjs",
     "set-version": "node scripts/set-version.mjs",
     "verify-release": "node scripts/verify-release.mjs",
+    "verify-package": "node scripts/verify-package.mjs",
     "retag-release": "node scripts/retag-release.mjs"
   }
 }

package/scaffolds/init/AGENTS.md

@@ -0,0 +1,131 @@
+# AGENTS.md
+
+This project produces deterministic, parameterized video with Frameyard. This file is the local summary; the official skill has the full contract.
+
+## Project layout
+
+- `fy.config.js` explicitly maps project IDs to sources. There is no directory scanning. It declares the project `format`, `compositions`, and `timelines`.
+- `compositions/` contains HTML fragments; an optional controller lives beside the fragment as a `.controller.js` module.
+- `timelines/` contains JSON timeline documents that assemble clips into one video.
+- `props/hello.json` contains composition props; `props/main.json` contains timeline overrides keyed by composition clip ID.
+- `out/` contains rendered files and is gitignored. `assets/` contains local media and generated assets.
+- `package.json` pins the CLI in `dev`, `check`, `render`, and `still` scripts.
+
+An animated composition declares `duration-in-frames`. A composition with neither `duration-in-frames` nor `fps` is static: it is captured once, renders to PNG, and cannot use animation, media, or transcripts. `width`, `height`, and `fps` inherit the project `format`; declare `width` and `height` together or not at all.
+
+## Composition skeleton
+
+A composition is a partial HTML fragment, not a full document. Keep one top-level `<fy-composition>`; props, the controller, import maps, and styles are top-level siblings. Do not add `<!doctype>`, `<html>`, `<head>`, `<body>`, `<title>`, or `<meta>`.
+
+```html
+<script type="application/json" data-fy="props">{ "title": "Hello" }</script>
+<style>
+  html, body { margin: 0; width: 100%; height: 100%; }
+</style>
+<fy-composition width="1280" height="720" fps="30" duration-in-frames="150">
+  <h1 data-fy-text="title"></h1>
+</fy-composition>
+```
+
+## Timeline skeleton
+
+`timelines/main.timeline.json` assembles clips in the project format:
+
+```json
+{
+  "version": 1,
+  "tracks": [{ "id": "v1", "kind": "video" }],
+  "clips": [
+    {
+      "id": "hello",
+      "track": "v1",
+      "source": { "kind": "composition", "id": "hello" },
+      "start": 0
+    }
+  ]
+}
+```
+
+- `source.kind` is `composition`, `timeline`, `video`, `image`, or `audio`. `start`, `sourceIn`, and `duration` are timeline frames. Image clips require a duration.
+- A static composition clip needs an explicit `duration` and `sourceIn: 0`. It contributes no audio.
+- Tracks composite bottom-to-top. Same-track overlap requires a timeline `transitions` entry; see the skill for transforms, keyframes, blends, and transitions.
+
+## Bindings and animation
+
+- Bindings: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `<template data-fy-repeat>`. Primitive top-level props are also `--fy-prop-<name>` CSS variables.
+- Bindings apply once, before `mount`; controller-created DOM is not re-bound.
+- CSS/WAAPI animations are seeked from the frame clock. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation in frames.
+- Frame state on `:root`: `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, `--fy-duration-frames`.
+
+## Controller
+
+Exactly one optional controller is allowed, inline or external, as a top-level sibling. It may export `mount`, `update`, `dispose`, and `validateProps`; at least one is required. `mount` may be async; `update` is synchronous and seek-safe. The controller is the only executable code; other scripts and `on*` handlers are rejected. Extract large or reusable controllers to an external module.
+
+```html
+<script type="text/fy-controller">
+export default {
+  mount({ root, props }) {},
+  update({ frame, props }) {},
+};
+</script>
+```
+
+## Determinism
+
+- A frame depends only on its integer `frame`, immutable `props`, and assets loaded before frame production.
+- Use `random("stable:key")` from `frameyard/runtime`; never `Math.random()`, `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions.
+- Load remote data, fonts, and images before frames. Network is blocked during capture; do not `fetch()` from `update()`.
+- Vendor fonts with `npx frameyard font add --file`; do not rely on a remote Google Fonts link for a deterministic render. The server injects `@font-face` rules and the host waits for `document.fonts.ready`.
+- Let the runtime seek embedded video; do not play, pause, or set `currentTime`. Redraw Canvas/WebGL from the current frame.
+- Do not run model inference inside `mount()`, `update()`, or frame production.
+
+## Fonts
+
+- `fy.fonts.json` records installed families, licenses, and SHA-256 values; commit it with `assets/fonts/`.
+- Search Fontsource with `npx frameyard font search "<query>" --json`, then install a family with `npx frameyard font add <fontsource-id> --json`. Variable `wght` is the default; add `--static --weight 400,700` for static files.
+- Use `npx frameyard font add --file <path> --family "<name>" --license <id> --license-file <path>` for a local or brand font. Use `--url` for an explicit HTTPS source with `--sha256`.
+- Run `npx frameyard font list --json` and `npx frameyard font verify --json` after moving files. Do not edit manifest hashes by hand.
+- `font add` requires `authoring` or `full`; `font remove`, `font add --force`, and an unlicensed `--url` import require `full`.
+
+## Media and transcripts
+
+- Composition audio uses `<audio>` with `data-fy-start` (frames), `data-fy-trim` (seconds), optional `data-fy-duration` (seconds), and `data-fy-volume` (0-1). Timeline audio uses frames and audio tracks.
+- Media and transcript `src` values resolve from the project root; controller `src` and ordinary HTML URLs resolve from the composition URL.
+- Declare transcripts with `<fy-transcript src="assets/voice.transcript.json" words>`. `words` requires measured word timings; never interpolate segment timings.
+- Use Frameyard's `tts`/`transcribe` wrappers; never call `qwen-tts`, `sherpa-onnx-offline-tts`, or `whisper-cli` directly. Do not overwrite generated assets without approval. Commit `fy.assets.json` when present; do not edit hashes.
+
+## Resource policy
+
+A workspace can commit `fy.policy.json` to gate expensive operations. The nearest file from the working directory upward applies, independent of `fy.config.js`; `FRAMEYARD_POLICY` overrides it. `light` allows one still frame and blocks `check`, `tts`, `transcribe`, and `render`; `authoring` allows four still frames and `check` at low priority and blocks the three heavy operations; `full` allows everything up to the 32-frame still cap. `--profile shared-cpu` caps timeline workers at 2 and composition concurrency at 1. `tts`, `transcribe`, and `render` accept `--dry-run`; use it and report the handoff when blocked. The policy is a guardrail, not a security boundary.
+
+## Agent workflow
+
+1. Read `fy.config.js`, the timeline, the composition, its controller, and the props. Run `npx frameyard context --json` first.
+2. Author with native HTML, CSS, SVG, Canvas, WebGL, and an optional controller. Use `npx frameyard add --list --json` for templates and merge the returned registration object into `fy.config.js`.
+3. Lint the edit loop with `npx frameyard lint main --json`. It does not run `validateProps` or composition runtime.
+4. Run `npx frameyard check main --json` for the full gate when the policy allows it; read diagnostics and warnings.
+5. Inspect with `npx frameyard still main --frame <spec> --out <dir|file.png> --json`. The policy captures at most 32 unique frames in `full` (4 in `authoring`, 1 in `light`). Use `npx frameyard inspect`/`compare` for text facts; view the PNGs when possible.
+6. Render with `npx frameyard render main --props props/main.json [--workers <n>] [--scratch <dir>] --json`. If the policy blocks it, use `--dry-run` and report the handoff.
+7. Report sources, props, diagnostics, still paths, inspection status, output path, and failures. Never claim success when `check` fails, a still is missing, or a render exits nonzero.
+
+## Commands
+
+```sh
+npx frameyard dev
+npx frameyard context --json
+npx frameyard doctor --json
+npx frameyard add --list --json
+npx frameyard lint main --json
+npx frameyard check main --json
+npx frameyard still main --frame 42 --out main-42.png --json
+npx frameyard inspect main-42.png --json
+npx frameyard render main --props props/main.json --workers 8 --scratch /path/to/scratch --json
+```
+
+- Use `--json` for non-interactive commands. Parse stdout; keep stderr for progress and diagnostics.
+- Use `--project <dir>` outside the project root. Outputs default to `out/<id>.mp4` or `out/<id>.png`.
+- `--concurrency` is for animated compositions; `--workers`/`--scratch` are for timelines. `--container <mp4|mov|mkv|webm>`, `--codec <h264|hevc|vp9>`, and `--encoder <auto|software|nvenc|qsv>` select delivery; the extension must match.
+- `--dry-run` validates and prints a handoff plan. `--profile shared-cpu` caps workers/concurrency and lowers priority.
+- `still`/`render` replace outputs only with `--overwrite`; generated assets only with `--force`, and only with approval. The resource policy denies both outside `full`.
+
+The official `frameyard` agent skill has the full contract. Install it with `npx skills add vladiantio/frameyard`. This project was scaffolded with frameyard {{VERSION}}; `npx frameyard` resolves the latest version, so run `npx frameyard@{{VERSION}}` when you need the scaffolding version.