frameyard 0.0.0-stage → 0.2.0

package/examples/demo/props/demo.json

@@ -0,0 +1,5 @@
+{
+  "title": "Frameyard",
+  "subtitle": "Deterministic video, authored with the web platform.",
+  "accent": "#b8f36b"
+}

package/examples/demo/video.config.js

@@ -0,0 +1,5 @@
+export default {
+  compositions: {
+    demo: "./compositions/demo.js",
+  },
+};

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "frameyard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vladiantio/frameyard.git"
+  },
+  "homepage": "https://github.com/vladiantio/frameyard#readme",
+  "bugs": {
+    "url": "https://github.com/vladiantio/frameyard/issues"
+  },
+  "keywords": [
+    "video",
+    "video-rendering",
+    "html",
+    "css",
+    "javascript",
+    "deterministic",
+    "ffmpeg",
+    "playwright",
+    "agent-skill"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "frameyard": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "docs",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "GLOSSARY.md"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "playwright": "1.64.1"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "oxfmt": "0.75.0",
+    "oxlint": "1.90.0",
+    "typescript": "5.9.3",
+    "vitest": "5.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json",
+    "lint": "oxlint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "test": "pnpm build && vitest run",
+    "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/random.test.ts test/scaffold.test.ts test/transcript.test.ts",
+    "bench": "pnpm build && node scripts/bench-render.mjs",
+    "set-version": "node scripts/set-version.mjs"
+  }
 }

package/skills/frameyard/README.md

@@ -0,0 +1,35 @@
+# Frameyard agent skill
+
+This directory is the optional, host-neutral Frameyard agent skill. Its API version matches the npm package version. The npm package includes this directory.
+
+## Install or reference
+
+Install from the repository with the open agent-skills CLI:
+
+```sh
+npx skills add vladiantio/frameyard
+```
+
+The skill lives at `skills/frameyard` in the repository and npm package. Alternatively, copy or symlink the whole `skills/frameyard/` directory into the skill location your agent host uses. Examples:
+
+- Claude Code project skills: `.claude/skills/frameyard`
+- Agent hosts that read `.agents/skills`: `.agents/skills/frameyard`
+- Global installations: place it under your host's documented personal skills directory
+
+The skill is host-neutral: it uses only the normal `frameyard` project format and CLI. There is no agent-only runtime.
+
+Run the CLI with `npx frameyard`. It resolves the latest published version; pin it with `npx frameyard@<version>` or install the package locally when the CLI version must match the skill. When the skill is copied outside the npm package, `scripts/frameyard.mjs` falls back to the `frameyard` command on `PATH`; if that command is unavailable, set `FRAMEYARD_CLI` to an installed CLI path.
+
+## Contents
+
+- `SKILL.md`: trigger description and operating workflow
+- `references/deterministic-authoring.md`
+- `references/audio-assets.md`
+- `references/subtitles-karaoke.md`
+- `references/json-results.md`
+- `references/failure-recovery.md`
+- `scripts/frameyard.mjs`: thin fallback wrapper for the installed CLI
+
+## Version matching
+
+`SKILL.md` records `frameyard-api-version`. If `npx frameyard --version` reports a different version, pin the CLI (`npx frameyard@<version>`) to the skill version, or use the skill files shipped inside the installed package. Contract changes are documented in the repository README and design baseline.

package/skills/frameyard/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: frameyard
+description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML, CSS, and native JavaScript. Use when a user asks to build or operate a Frameyard project, produce parameterized video, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
+frameyard-api-version: 0.2.0
+---
+
+# Frameyard
+
+Use Frameyard's public project format and CLI. Do not introduce an agent-only runtime, a hosted service, or direct calls to `qwen-tts` or `whisper-cli`.
+
+## First decisions
+
+1. Find the project: look for `video.config.js` from the working directory upward, or run `npx frameyard init <directory>` to scaffold one.
+2. Read the composition entry points listed in `video.config.js`. There is no directory scanning.
+3. Read the existing props file and composition source before changing behavior.
+4. If the task needs speech or transcription, confirm that inference is requested or explicitly approved before producing assets.
+
+## Workflow
+
+1. **Author** the composition with HTML, CSS, SVG, Canvas 2D, and native JavaScript ES modules. Keep `width`, `height`, `fps`, and `durationInFrames` fixed. Read [deterministic authoring](references/deterministic-authoring.md).
+2. **Provide props** as JSON. Validate domain-specific requirements with `validateProps()`.
+3. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
+4. **Validate** with `npx frameyard check <id> --json`. It evaluates every frame, checks audio and declared transcripts, and does not encode.
+5. **Inspect** representative frames with `npx frameyard still <id> --frame <n> --out <file.png> --json`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
+6. **Render** with `npx frameyard render <id> --out <file.mp4> [--props <file>] --json`.
+7. **Report** the project path, composition entry, props, generated assets, provenance manifest, validation results, still paths and inspection status, final video path, and any failures.
+
+Never claim success when `check` fails, a still is missing, a render exits nonzero, or visual inspection was skipped. A partial or unpublished render is not a successful result.
+
+## Command rules
+
+- Use `--json` for every non-interactive command. Parse stdout as the structured result; treat stderr as progress and diagnostics.
+- Keep the current output files unless the user explicitly approves replacement. Use `--force` only with that approval.
+- Use `--project <dir>` when not running from the project root.
+- Use `npx frameyard doctor --json` before reporting an environment problem. It inspects without repairing or downloading.
+- Read [JSON results](references/json-results.md) for result and error shapes, and [failure recovery](references/failure-recovery.md) for actionable error codes.
+
+## Determinism guardrails
+
+- A frame may depend only on its integer `frame`, immutable `props`, and assets loaded before frame production.
+- Use `random("stable:key")` from `frameyard/runtime`; never use `Math.random()`.
+- Never use `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions as animation inputs.
+- Finish remote data, fonts, and image loading during `mount()` or before the first frame. Network requests are blocked during frame capture.
+- Keep `update({ frame, props })` synchronous and seek-safe. Do not carry state between frames.
+- Do not run model inference inside `mount()`, `update()`, or frame production.
+
+## Subtitle and karaoke rule
+
+Use canonical transcripts produced by `npx frameyard transcribe`. Convert integer source-relative milliseconds to composition frames with the audio clip's `startFrame`, `trimStart`, and the composition `fps`. Karaoke highlighting requires actual `words` timings; never interpolate segment timings. Read [subtitles and karaoke](references/subtitles-karaoke.md).
+
+## CLI invocation
+
+Use `npx frameyard` (or an installed `frameyard` binary) directly. `scripts/frameyard.mjs` is a fallback for hosts that cannot resolve package binaries: it prefers the package-local `dist/cli.js`, then the `frameyard` command on `PATH`. When the skill is copied out of the package, set `FRAMEYARD_CLI` to an installed CLI path if that command is unavailable.
+
+```sh
+npx frameyard check <id> --json
+node scripts/frameyard.mjs check <id> --json   # fallback
+```
+
+When the CLI version differs from `frameyard-api-version`, pin it with `npx frameyard@<version>`.

package/skills/frameyard/references/audio-assets.md

@@ -0,0 +1,86 @@
+# Audio and generated assets
+
+Audio clips are a declarative timeline. Generated speech and transcripts are frozen local inputs produced before composition loading.
+
+## Audio timeline
+
+```js
+audio: [
+  {
+    src: "assets/voice.wav", // project-relative local file
+    startFrame: 30,          // composition timeline position
+    trimStart: 0.25,         // seconds trimmed from the source
+    trimDuration: 4.2,       // optional seconds to use
+    volume: 0.8,             // 0..1
+  },
+];
+```
+
+- Placement is in composition frames.
+- Trimming is in seconds from the source.
+- Frameyard never time-stretches audio or changes composition duration to fit it.
+- `check` reports clip durations and overrun warnings.
+
+## Local speech synthesis
+
+Use Frameyard, not `qwen-tts` directly:
+
+```sh
+npx frameyard tts \
+  --speaker vivian \
+  --talker-model models/qwen-talker-1.7b-customvoice-Q8_0.gguf \
+  --codec-model models/qwen-tokenizer-12hz-Q8_0.gguf \
+  --language English \
+  --text-file script.txt \
+  --out assets/voice.wav \
+  --json
+```
+
+- CustomVoice only: `--speaker` is required.
+- Text comes from `--text-file` or stdin.
+- `--style` maps to the upstream style instruction.
+- `--language` maps to `--lang`.
+- `--device CPU` forces qwentts.cpp onto the CPU when the GPU does not have enough VRAM.
+- Output is one frozen 24 kHz mono WAV.
+- Talker and codec GGUF paths are required.
+- `--force` is required to replace an existing asset. Do not pass it without user approval.
+- Executable resolution: `--executable`, then `FRAMEYARD_QWEN_TTS`, then `PATH`.
+- Frameyard does not build qwentts.cpp, download models, or redistribute weights.
+
+## Local transcription
+
+```sh
+npx frameyard transcribe assets/voice.wav \
+  --model models/ggml-base.en.bin \
+  --out assets/voice.transcript.json \
+  --words \
+  --export srt,vtt \
+  --json
+```
+
+- The source is normalized with FFmpeg to 16 kHz mono PCM WAV before `whisper-cli` runs.
+- The canonical output is Frameyard transcript JSON.
+- `--words` requests actual word timings. It fails rather than fabricate them.
+- `--export srt,vtt` writes derived subtitle files next to the transcript.
+- `--force` is required to replace existing transcript or export files.
+- Executable resolution: `--executable`, then `FRAMEYARD_WHISPER_CLI`, then `PATH`.
+- Frameyard does not download Whisper models or execute Whisper's generated karaoke shell script.
+
+## Provenance manifest
+
+Both commands update `frameyard.assets.json` in the project root unless `--manifest <file>` is supplied. The manifest records:
+
+- artifact path, content hash, and size;
+- generator command, Frameyard version, executable, and integration revision;
+- model identities and sizes;
+- operation parameters and, for transcription, source identity and derived exports.
+
+Commit the manifest with the project. It explains how generated inputs were produced. Do not edit hashes by hand.
+
+## Regeneration rules
+
+- Do not regenerate or overwrite an existing generated asset without permission.
+- Do not silently switch models, speakers, language, or text.
+- Report the manifest path and the exact asset paths after success.
+- `npx frameyard doctor` verifies manifest integrity, including artifact, source, model, and derived-export hashes, and optional integration executables; it does not download or repair anything. Pass `--talker-model`, `--codec-model`, or `--model` to inspect model readability and identity before generation.
+- Once assets are frozen, checking and rendering do not need the model or inference executable.

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

@@ -0,0 +1,107 @@
+# Deterministic authoring
+
+Frameyard compositions are ordinary native JavaScript ES modules. The preview server injects an import map for `frameyard` and `frameyard/runtime`; do not add a bundling step or import from `node_modules` in composition code.
+
+## Project configuration
+
+`video.config.js` lists every composition explicitly:
+
+```js
+export default {
+  compositions: {
+    hello: "./compositions/hello.js",
+  },
+};
+```
+
+There is no directory scanning. A new composition file is invisible until it is listed.
+
+## Composition shape
+
+```js
+import { defineComposition } from "frameyard";
+import { random } from "frameyard/runtime";
+
+let title;
+
+export default defineComposition({
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  durationInFrames: 900,
+  defaultProps: { title: "Hello" },
+  validateProps(props) {
+    return typeof props.title === "string" ? [] : ["title must be a string"];
+  },
+  mount({ container, props }) {
+    container.innerHTML = "<h1 id='title'></h1>";
+    title = container.querySelector("#title");
+    title.textContent = props.title;
+  },
+  update({ frame, props }) {
+    title.textContent = props.title;
+    title.style.transform = `translateX(${random("title:" + frame) * 40}px)`;
+  },
+  dispose() {
+    title = undefined;
+  },
+});
+```
+
+- `mount()` runs once and may await loading work.
+- `update({ frame, props })` is synchronous and seek-safe.
+- `dispose()` releases resources and module-scope references.
+- Props are JSON-serializable, deep-frozen, and merged shallowly over `defaultProps`.
+- Keep mutable state in module-scope variables, never on `this`.
+
+## Forbidden animation inputs
+
+Do not use any of these as animation state:
+
+- `Math.random()`
+- `Date.now()` or `performance.now()`
+- `setTimeout()` or `setInterval()`
+- independent `requestAnimationFrame()` loops
+- CSS transitions
+- state left from a previously visited frame
+
+Use `random("stable:key")` for deterministic randomness. The value depends only on the key, not call order.
+
+```js
+import { random } from "frameyard/runtime";
+
+const x = random("star:17:x") * width;
+```
+
+## CSS and Canvas
+
+CSS `@keyframes` and the Web Animations API are paused and seeked by the runtime inside the composition container. They are valid animation drivers. CSS transitions are diagnosed as non-deterministic and should not be used.
+
+Canvas 2D must be redrawn from the current frame:
+
+```js
+update({ frame }) {
+  context.clearRect(0, 0, canvas.width, canvas.height);
+  context.fillStyle = frame % 2 === 0 ? "#101820" : "#203040";
+  context.fillRect(0, 0, canvas.width, canvas.height);
+}
+```
+
+## Loading assets
+
+Remote data, images, fonts, and other assets must resolve during `mount()` or before the first frame. The production browser blocks network requests after loading begins. A fetch from `update()` is a bug.
+
+Images inserted in `mount()` are awaited by the runtime. Static fonts should be loaded with `document.fonts.ready` or an explicit `FontFace` before frame production.
+
+## Validation and inspection
+
+```sh
+npx frameyard check hello --json
+npx frameyard still hello --frame 42 --out hello-42.png --json
+```
+
+`check` mounts the composition, evaluates every frame, and validates audio and declared transcripts without capturing or encoding. Do not replace it with a single still.
+
+## Metadata is fixed
+
+`width`, `height`, `fps`, and `durationInFrames` cannot be derived from props. Choose a reusable resolution, frame rate, and duration; put variation in props. Frameyard does not change duration to fit audio.

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

@@ -0,0 +1,57 @@
+# Failure recovery
+
+Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and only then render.
+
+## Common codes
+
+| 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, and exist. |
+| `COMPOSITION_NOT_FOUND` | ID is not listed | Add the entry to `video.config.js`. |
+| `COMPOSITION_INVALID` | Invalid metadata or lifecycle shape | Fix metadata and ensure `update()` is synchronous. |
+| `COMPOSITION_ERROR` | Mount, update, or browser page error | Read the frame location in the message; remove forbidden clocks/randomness. |
+| `COMPOSITION_UPDATE_ASYNC` | `update()` returned a promise | Move async work to `mount()`. |
+| `PROPS_INVALID` | Props are not JSON or fail `validateProps()` | Fix the props file or validator. |
+| `FRAME_OUT_OF_RANGE` | Frame is outside `0..durationInFrames - 1` | Choose a valid frame. |
+| `AUDIO_INVALID` | Bad clip or unreadable/unsupported audio | Use a local project-relative file with a decodable audio stream. |
+| `ASSET_NOT_FOUND` | Required file is missing or unreadable | Restore the asset, model, or text file. |
+| `OUTPUT_EXISTS` | Output exists and replacement was not approved | Reuse it, choose another path, or pass `--overwrite`/`--force` with permission. |
+| `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. |
+| `TRANSCRIBE_FAILED` | Normalization or `whisper-cli` failed | Verify FFmpeg, the source media, and the Whisper model. |
+| `TRANSCRIPT_INVALID` | Canonical transcript JSON is malformed | Regenerate it 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: true`. |
+| `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. |
+| `FFPROBE_FAILED` | FFprobe is missing or failed | Install FFmpeg/FFprobe together. |
+| `BROWSER_FAILED` | Chromium could not start | Install the Playwright Chromium build. |
+| `RENDER_FAILED` | Capture or encoding failed | Read stderr; rerun `check` and a representative `still`. |
+| `CANCELLED` | The operation was interrupted | Rerun when ready. Partial outputs are removed. |
+
+## Behavior to rely on
+
+- A failed render writes to a temporary file and does not publish a partial MP4.
+- Failed TTS/transcription operations leave no artifact and no manifest entry.
+- Existing outputs are replaced only with `--overwrite` (renders/stills) or `--force` (generated assets).
+- Cancellation terminates the child inference process and cleans temporary work.
+- `check` validates every frame and declared transcripts without encoding.
+- `doctor` inspects but never repairs, downloads, or modifies the environment.
+
+## When visual inspection is impossible
+
+If the host cannot display images, say explicitly that representative stills could not be visually inspected. Report their paths and the fact that inspection was skipped. Do not describe visual correctness you did not observe.
+
+## Reporting a completed result
+
+Report all of:
+
+- source project path and composition entry;
+- props file or inline props used;
+- generated audio/transcript paths and provenance manifest path;
+- `check` result, including warnings;
+- still paths and whether they were viewed;
+- final video path, frame count, and audio/transcript summary;
+- any skipped step or unresolved warning.

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

@@ -0,0 +1,203 @@
+# JSON command results
+
+Every non-interactive command supports `--json`. Stdout contains one JSON document; progress and human diagnostics go to stderr. Failures exit nonzero.
+
+## Success envelope
+
+```json
+{
+  "ok": true,
+  "command": "check"
+}
+```
+
+Additional fields are command-specific and stable within the 0.1 contract.
+
+## Error envelope
+
+```json
+{
+  "ok": false,
+  "command": "render",
+  "error": {
+    "code": "OUTPUT_EXISTS",
+    "message": "Output already exists: ..."
+  }
+}
+```
+
+Use the error `code` for decisions, not message text. `command` is `null` only for usage failures that occur before a command is known. Exit code `2` means usage; `130` means cancellation; other failures exit `1`.
+
+## check
+
+```json
+{
+  "ok": true,
+  "command": "check",
+  "composition": "hello",
+  "metadata": { "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 900 },
+  "framesChecked": 900,
+  "audio": {
+    "clips": 1,
+    "warnings": [],
+    "details": [
+      {
+        "src": "assets/voice.wav",
+        "startFrame": 30,
+        "startSeconds": 1,
+        "endSeconds": 5.2,
+        "sourceDurationSeconds": 4.95,
+        "trimStart": 0.25,
+        "volume": 0.8
+      }
+    ]
+  },
+  "transcripts": {
+    "clips": 1,
+    "warnings": [],
+    "details": [
+      { "src": "assets/voice.transcript.json", "language": "en", "segments": 3, "words": 17, "durationMs": 5200, "bytes": 2048 }
+    ]
+  },
+  "elapsedMs": 1200
+}
+```
+
+## still
+
+```json
+{
+  "ok": true,
+  "command": "still",
+  "composition": "hello",
+  "frame": 42,
+  "path": "/absolute/path/hello-42.png",
+  "width": 1920,
+  "height": 1080,
+  "elapsedMs": 700
+}
+```
+
+## render
+
+```json
+{
+  "ok": true,
+  "command": "render",
+  "composition": "hello",
+  "path": "/absolute/path/hello.mp4",
+  "width": 1920,
+  "height": 1080,
+  "fps": 30,
+  "durationInFrames": 900,
+  "durationSeconds": 30,
+  "framesRendered": 900,
+  "bytes": 1234567,
+  "audio": { "clips": 1, "warnings": [] },
+  "transcripts": { "clips": 1, "warnings": [] },
+  "elapsedMs": 99000
+}
+```
+
+A successful render means the final path exists and was published atomically. A nonzero exit means no new partial video was published.
+
+## tts
+
+```json
+{
+  "ok": true,
+  "command": "tts",
+  "path": "/absolute/path/assets/voice.wav",
+  "bytes": 480000,
+  "sha256": "64-character hex digest",
+  "sampleRate": 24000,
+  "channels": 1,
+  "speaker": "vivian",
+  "language": "English",
+  "manifest": "/absolute/path/frameyard.assets.json",
+  "elapsedMs": 12000
+}
+```
+
+`language` is omitted when it was not supplied.
+
+## transcribe
+
+```json
+{
+  "ok": true,
+  "command": "transcribe",
+  "path": "/absolute/path/assets/voice.transcript.json",
+  "bytes": 2048,
+  "sha256": "64-character hex digest",
+  "source": {
+    "path": "assets/voice.wav",
+    "sha256": "64-character hex digest",
+    "bytes": 480000
+  },
+  "language": "en",
+  "segments": 3,
+  "words": 17,
+  "exports": [
+    {
+      "format": "srt",
+      "path": "/absolute/path/assets/voice.transcript.srt",
+      "bytes": 220,
+      "sha256": "64-character hex digest"
+    }
+  ],
+  "manifest": "/absolute/path/frameyard.assets.json",
+  "elapsedMs": 30000
+}
+```
+
+`words` is `0` when word timings were not requested. `language` is omitted when it could not be determined.
+
+## doctor
+
+Doctor reports findings rather than throwing for environment problems. `ok: true` means the inspection completed; `healthy` says whether required checks, manifest integrity, explicitly supplied models, and integration compatibility passed.
+
+```json
+{
+  "ok": true,
+  "command": "doctor",
+  "healthy": true,
+  "checks": [
+    { "name": "node", "required": true, "status": "ok", "detail": "v22.12.0" },
+    { "name": "ffmpeg", "required": true, "status": "ok", "detail": "ffmpeg version ..." },
+    { "name": "ffmpeg-encoders", "required": true, "status": "ok", "detail": "libx264 and aac are available." },
+    { "name": "ffprobe", "required": true, "status": "ok", "detail": "ffprobe version ..." },
+    { "name": "chromium", "required": true, "status": "ok", "detail": "/path/to/chrome" },
+    { "name": "manifest", "required": false, "status": "ok", "detail": "2 artifacts verified." }
+  ],
+  "integrations": {
+    "tts": {
+      "name": "qwen-tts",
+      "status": "ok",
+      "requested": false,
+      "executable": "/path/to/qwen-tts",
+      "capabilities": ["--model", "--codec", "--speaker", "--lang", "--device", "-o"],
+      "version": "5916bf7c79dbb4e66fc059cdc507a79a23a28bb4 (2026-10-28)",
+      "referenceRevision": "..."
+    },
+    "transcribe": {
+      "name": "whisper-cli",
+      "status": "missing",
+      "requested": false,
+      "referenceRevision": "..."
+    }
+  },
+  "models": [
+    {
+      "role": "talker",
+      "path": "/absolute/path/models/talker.gguf",
+      "status": "ok",
+      "bytes": 1234567,
+      "sha256": "64-character hex digest"
+    }
+  ],
+  "manifest": { "path": "/absolute/path/frameyard.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.