@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvpx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @anvpx/motion-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`mk <command> [flags]` - the motion-kit command line. Workspace dependencies only (`@anvpx/motion-schema`, `@anvpx/motion-build`, `@anvpx/motion-templates` for the built-in template directory); no third-party packages.
+
+Every built-in blueprint ships a contact-sheet preview, and `mk template show <template>/<blueprint>` prints its path — e.g. `explain/concept`: ![explain/concept preview](../templates/templates/explain/previews/concept.png)
+
+## Commands
+
+| Command                                                                                                                                          | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mk doctor [--json]`                                                                                                                             | Tri-state check per tool (ok, usable, missing or unknown): node >= 22, pnpm, ffmpeg >= 6, ffprobe (required); hyperframes, chrome-headless-shell, gpu, python 3.12, skills (installed `skills/motion-kit` + references) (optional, warn only). `--json`: one line `[{id,status,version?,hint?}]`                                                                                                                                                                                     |
+| `mk validate <sb.json> [--json]`                                                                                                                 | Schema + scene props + timing + lint. One line per finding: `E /scenes/1/props/items/0: message -> suggestion` (`W` for warnings)                                                                                                                                                                                                                                                                                                                                                    |
+| `mk build <sb.json> [--out d] [--assets d] [--ledger f] [--incremental] [--clean-cache] [--shared-cache-dir d]`                                  | Validate, then write the HyperFrames project (default `<storyboard dir>/out/project`); prints file count, duration, manifest sha256. `--incremental` (also on draft/render/still) reuses unchanged scenes from `<storyboard dir>/.mk-cache` (byte-identical output; prints `cache: N hit / M miss`; `--no-incremental` is the default); `--clean-cache` wipes it first; `--shared-cache-dir` is opt-in shared cache across storyboards (requires `--incremental`)                    |
+| `mk still <sb.json> (--at 1,5,9 \| --review) [--out d]`                                                                                          | Build, then `hyperframes snapshot` per timestamp; PNGs in `<out>/stills`; `--review` captures the upstream review set instead (scene starts, middles, cut seams plus phone-width beats)                                                                                                                                                                                                                                                                                              |
+| `mk compare <a.json> <b.json> [<c.json> [<d.json>]] --at <s> [--out d] [--assets d] [--ledger f] [--json]`                                       | Build 2-4 storyboards, one still of each at the same `--at` second, then tile them in CLI order into `<out>/compare-<s>.png` (default `<out>` = `<first storyboard dir>/out/compare`, each build in `<out>/<name>`; tiles are 640 px wide, so candidates should share an aspect). One output line; `--json`: `{at,png,items:[{storyboard,still,sha256}]}`. Exit 2 for <2 or >4 storyboards or a bad `--at`, 1 when a build, snapshot or tile fails (the failing storyboard is named) |
+| `mk draft <sb.json> [--out d] [--verify]`                                                                                                        | Build, then 15 fps draft to `<out>/draft.mp4` (960x540); writes `render-manifest.json`; `--verify` re-probes it (exit 5 on FAIL)                                                                                                                                                                                                                                                                                                                                                     |
+| `mk render <sb.json> [--out d] [--fps 30] [--format mp4\|webm\|mov\|gif\|png-sequence] [--resolution 1080p\|4k] [--resume] [--verify] [--gated]` | Build, then final H.264 to `<out>/final.mp4`; non-mp4 formats convert that master with ffmpeg; `--resolution 4k` uses the 4K preset matching the frame; `--verify` re-probes the mp4 master (exit 5 on FAIL); `--gated` renders only when `mk approve` matches the current files, else exit 4                                                                                                                                                                                        |
+| `mk verify <file.mp4> [--storyboard sb.json] [--platform id] [--draft] [--determinism second.mp4] [--events] [--loudness] [--json]`              | Re-probe a rendered file with ffprobe and report findings; see Verify below                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `mk state <sb.json> [--out d] [--render d] [--assets d] [--ledger f] [--json]`                                                                   | Report the highest project state the artifacts prove; read-only, no writes. Pass the same `--assets`/`--ledger`/`--audio`/`--music` flags used with `mk preview`/`mk approve`, else a vendored-asset project is undecidable. `--json`: one line {state, next, missing, problems, evidence}. Exit 1 when a manifest claims more than the evidence; 2 when approval inputs are unreadable                                                                                              |
+| `mk analyze <audio.wav> [--words f] [--tokens text] [--out f] [--python bin]`                                                                    | Analyze voice audio into AudioAnalysis JSON (words, silences, duration); no `--words`/`--tokens` means UNKNOWN exit 2                                                                                                                                                                                                                                                                                                                                                                |
+| `mk qc <manifest.json> [--audio audio.wav] [--words words.json] [--json]`                                                                        | Gate a voice TimingManifest plus its audio: PASS/WARN/FAIL/UNKNOWN; no `--audio` means UNKNOWN exit 2                                                                                                                                                                                                                                                                                                                                                                                |
+| `mk catalog [<scene>] [--json] [--write [--out f]]`                                                                                              | No argument: index, one line per scene (`type \| layer \| purpose \| required`). `<scene>`: fields, types, defaults, minimal example. `--write` regenerates `CATALOG.md` at the repo root                                                                                                                                                                                                                                                                                            |
+| `mk contact <file.mp4> [--cols 4] [--count 12] [--out f.png]`                                                                                    | ffmpeg contact sheet: `--count` evenly spaced frames, 320 px tiles, `--cols` per row; default `<file>-contact.png`. One output line                                                                                                                                                                                                                                                                                                                                                  |
+| `mk template list [--domain d] [--for q] [--tag a,b] [--aspect 16:9] [--sec 45] [--json]`                                                        | One line per template: `id@version \| domains \| blueprints \| source` (<= 15 lines); `--for` ranks blueprints (top 8, NOT-FOR sinks); `--aspect`/`--sec` are hard filters; shadowed templates flagged with `!`. Roots: `./templates`, `$MK_TEMPLATES_PATH`, `~/.motion-kit/templates`, built-in, then opt-in npm roots (built-ins win)                                                                                                                                              |
+| `mk template show <t>[/<bp>] [--json]`                                                                                                           | Template: styles, themes, blueprints with slot signatures, pacing, copy guide (<= 60 lines). Blueprint: slots (`*` required, `?` optional, limits) and an example                                                                                                                                                                                                                                                                                                                    |
+| `mk template validate <dir \| id> [--json]`                                                                                                      | Contracts, themes (AA contrast), styles, blueprint examples; `E path: message -> fix` per finding; exit 2 on errors                                                                                                                                                                                                                                                                                                                                                                  |
+| `mk template fork <t>/<bp> --as <name> [--out sb.json] [--json]`                                                                                 | Fork a blueprint example into a user-owned storyboard (built-ins never modified); records `forkedFrom` provenance                                                                                                                                                                                                                                                                                                                                                                    |
+| `mk new [<t>/<bp>] [--demo] [--with scene[,scene]] [--set k=v ...] [--slots f.json] [--style s] [--length l] [--out sb.json] [--json]`           | Instantiate a blueprint into a validated storyboard; vendors the used theme(s) into `<out dir>/themes/`; writes `<out dir>/.mk/<name>/template.json` (provenance). Bare `--demo` uses `explain/architecture`; `--with` appends a base scene whose props come from `slots["$with"]["<type>"]`. `--set k=a\|b\|c` for lists (backslash-pipe is a literal pipe). At most 5 output lines                                                                                                 |
+| `mk preview <sb.json> [--stills 6 \| --every] [--budget-sec 90] [--out d] [--assets d] [--ledger f] [--json]`                                    | The proposal pack in `<out>/<name>.preview` (default `<out>` = `<storyboard dir>/out`): `preview.json`, `contact.png`, `stills/NN-<scene>-<theme>.png`, `clip.mp4`; one summary line. Scratch builds in `<out>/<name>.preview-work`                                                                                                                                                                                                                                                  |
+| `mk approve <sb.json> [--note t] [--out d] [--assets d] [--ledger f] [--audio m] [--music f]`                                                    | Record the user's approval of the CURRENT visual/audiovisual inputs in `<storyboard dir>/.mk/<name>/approval.json`; the previewed inputs are inferred from `preview.json`, and an explicit flag must match the pack; exit 2 when no preview exists                                                                                                                                                                                                                                   |
+| `mk captions [<manifest>] [--storyboard sb] [--out ops.json] [--srt f] [--vtt f] [--from-srt f\|--from-vtt f]`                                   | One caption overlay per narrated scene as RFC 6902 `add` ops for `mk patch --ops`; words are scene-relative and out-of-bound words are reported; SRT/VTT export and import                                                                                                                                                                                                                                                                                                           |
+| `mk assets import <file...> --dir d --licence id --source-url url [--attribution t] [--ledger f]`                                                | Copy, hash and append a validated ledger row per file; re-running is a no-op, a hash mismatch at an existing path exits 2, remote paths are refused                                                                                                                                                                                                                                                                                                                                  |
+| `mk patch <sb.json> [--ops f.json] [--op <json> ...]`                                                                                            | RFC 6902 subset (`add`, `replace`, `remove`, `move`, `test`) applied to a copy; paths into a missing parent, `__proto__`/`constructor`/`prototype` and command-shaped keys are refused; the result is validated with the full validator and written atomically, never when invalid (pointer errors on stderr, exit 2). At most 3 output lines. Any edit changes the approval hash                                                                                                    |
+| `mk scene add <sb.json> <type> [--id x] [--after id] [--set k=v ...] [--duration s] [--over id] [--offset s]`                                    | Insert a scene built from the catalog's minimal example (`--set` values are JSON when they parse; overlay types need `--over`); one output line                                                                                                                                                                                                                                                                                                                                      |
+| `mk scene remove <sb.json> <id>` / `mk scene move <sb.json> <id> (--after <id> \| --first)`                                                      | Remove or reorder a scene; validated and atomic like `patch`                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `mk fit <sb.json> --seconds N`                                                                                                                   | Scale every base scene by one common factor so the total is N, each scene inside its pacing range (smallest to largest seconds of its type in the template's `pacing.json`, never under reading time or the 2 s hold; without template provenance: floor to 1.5x). Deterministic; refuses (writes nothing) when N is out of reach and says which scene's reading time or which limit                                                                                                 |
+| `mk generate-3d <image> --out <model.glb> [--python bin]`                                                                                        | Generate a validated GLB from a single image via the TripoSR backend; fails closed with a `mk doctor` hint, never a silent fallback                                                                                                                                                                                                                                                                                                                                                  |
+| `mk icon search <q> \| list [--tag group]`                                                                                                       | Icon names only (max 20 lines) for scene `icon` props; `--json` for an array                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `mk plugin install [--out d]`                                                                                                                    | Copy the bundled Claude Code plugin (skill, references, commands, manifest, README) to `<dir>`; verifies `skills/motion-kit/SKILL.md` sha256 match; pinned core version (0.0.0 pre-publish, 404 in isolation)                                                                                                                                                                                                                                                                        |
+| `mk voice <sb.json> --voice <id> [--out f] [--audio-dir d] [--python bin]`                                                                       | Synthesize narration into a voice TimingManifest; `--voice` required, never hardcoded; no venv/tool fails closed with a `mk doctor` hint                                                                                                                                                                                                                                                                                                                                             |
+| `mk optimize-model <model.glb> [--out f]`                                                                                                        | Validate a binary GLB and write an optimized copy (offline passthrough byte validator)                                                                                                                                                                                                                                                                                                                                                                                               |
+| `mk --help`                                                                                                                                      | List every registered command, one line each (<= 40 lines; a test enforces it)                                                                                                                                                                                                                                                                                                                                                                                                       |
+
+`still`, `draft` and `render` also accept `--assets` and `--ledger`. `<out>` is the project directory.
+
+## Exit codes
+
+One module defines them (`src/exit-codes.ts`); every command returns one of these.
+
+| Code | Name              | Meaning                                                                                                                                                                                                                       |
+| ---- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | OK                | Success; warnings allowed. `verify`: PASS or WARN. `doctor`: no required tool missing                                                                                                                                         |
+| 1    | ERROR             | Tool, build or render failure, hyperframes pin mismatch                                                                                                                                                                       |
+| 2    | USAGE             | Bad flags or arguments, unreadable file, **validation errors** (`validate`, `build`, `still`, `draft`, `render`), unknown command; `verify`/`qc`/`analyze`: UNKNOWN (could not decide); `doctor`: a required check is unknown |
+| 4    | AWAITING_APPROVAL | `render --gated` without a current visual approval (ask the user, then `mk preview` + `mk approve`); not an error                                                                                                             |
+| 5    | QA_FAIL           | `verify` found a fatal finding (also `draft`/`render --verify`)                                                                                                                                                               |
+| 127  | MISSING_TOOL      | A required program is missing or cannot run (`doctor`, `verify` without ffprobe, a render step whose program is absent)                                                                                                       |
+
+Change from Phase 1: validation errors used to exit 1; they now exit 2. Unknown command stays 2 (stderr).
+
+## Templates, preview and the approval gate
+
+Templates are data folders discovered in `./templates`, `$MK_TEMPLATES_PATH`, `~/.motion-kit/templates`, the built-in `packages/templates`, then opt-in npm roots (`mk-template-*`, `motion-kit-template-*`, `@*/mk-template-*`, `@anvpx/motion-template-*` in `node_modules`; built-ins win on id clash) (passed in by the CLI; `build` never imports it). A blueprint plus slots becomes a plain storyboard (`mk new`); the storyboard needs no template afterwards (its theme is vendored).
+
+`mk preview` runs validate + lint (exit 2 on errors), then stills (first, last, each scene type, even spread, at 70% of the scene; 3 more in the paired theme when the template has one), `contact.png` (ffmpeg tile of the stills, argv only), then `clip.mp4` through `mk draft` on an in-memory copy where every base scene is capped at 2 s, overlays are clamped inside, narration is stripped and the whole clip is <= 30 s (scenes sampled with the same picker). The clip build skips the authored-work lint rules (reading time, minimum hold), because scenes are cut short on purpose. If `--budget-sec` is used up after the stills, the clip is skipped and recorded (exit 0). `preview.json` records the approval hash, scenes, stills, clip status, lint counts, `estFullRenderSec` (an estimate from draft ms per frame) and an approval checklist. With `--audio`, the exact final wavs are mixed under `clip.mp4` with the same mix args as the final render, and `preview.json` records `audioMix` (`manifestSha`, `wavSha`, `audible: true`); silent packs record `audible: false`.
+
+Approval gate (visual + audiovisual + music bed; AU-01 extends the same gate with opt-in music, no parallel gate): `.mk/<name>/approval.json` = `{ inputManifest, inputManifestSha256, previewManifestSha, approvedAt, note }`, where `inputManifest` is the single resolver output (storyboard + vendored themes + exact referenced assets + asset-ledger bytes + (for audiovisual) the voice TimingManifest, every sibling wav and the mix + (AU-01, opt-in) the music bed `{path,sha256,volume,licenseEvidenceSha256}` with frozen copied bed bytes, project-relative forward-slash paths, code-unit sorted, `scope` visual or audiovisual) and `inputManifestSha256` is its canonical hash (no timestamp or machine path enters it). `mk preview` uses the same normalized `buildMixArgs`/`buildMusicMixArgs` clip/mix params as the final render. A receipt whose shape or inputs do not match the current manifest reads as `stale`, never silently upgraded — re-preview + re-approve. `mk render --gated` exits 4 (stderr names the cause: no approval, or inputs changed since approval) unless the recomputed hash matches; any edit to storyboard, themes, referenced asset bytes, ledger, audio manifest, wavs, mix, bed, volume or license receipt re-arms it, and inputs are rechecked before publication (mutation during preview/build fails before the renderer; ABA restore still mixes the frozen approved copy). A visual-only receipt never authorizes `--audio`, narration-only never authorizes `--music` (exit 4: re-preview audible + re-approve). `mk preview --audio [--music --music-volume --music-license]`, `mk approve --audio [--music ...]` and `mk render --gated --audio [--music ...]` must all use the identical manifests/bed/volume/license; a mismatch exits 2 at approve time, drift exits 4 at render. Silent/missing/skipped clips never qualify; silent/missing wavs fail closed. Without `--gated`, `render` (and ungated `--audio`) behaves as before; `mk draft` stays explicit and ungated.
+
+## Verify
+
+`mk verify <file.mp4>` runs `ffprobe` (found on PATH, as doctor finds ffmpeg) and asserts: a video stream; h264 + yuv420p; frame count = duration x fps within 1 frame. With `--storyboard`: size, fps and duration equal the storyboard's (total = sum of resolved scene durations minus crossfade overlaps; tolerance max(0.1 s, 1 frame)); `--draft` expects 960 px wide at 15 fps. With `--platform <id>` (id or alias from `packages/schema/data/platforms`): aspect, fps cap, duration cap and video codec; a template with `verified: false` adds an info finding `platform-unverified`. The storyboard does not declare audio, so audio is not required (a non-aac audio codec warns). With `--loudness`, audio loudness QC (`verify/audio-loudness.ts`, via `platformAudioReport`) measures integrated LUFS + true peak with installed FFmpeg `loudnorm=print_format=json` (single pass, no gain) and judges only an explicit verified policy (`verified: true`): `|measured-target| > 1.0 LU` is `audio-loudness-mismatch`, peak over ceiling + 0.5 dB is `audio-true-peak-mismatch` (both FAIL); unverified/absent policy is UNKNOWN (`audio-loudness-unverified`/`audio-loudness-no-policy`), unmeasurable audio is UNKNOWN (`audio-loudness-unavailable`/`no-stream`/`unmeasurable`); no universal LUFS is ever applied.
+
+Output is terse: `PASS|WARN|FAIL|UNKNOWN <file>` then findings `level code: message` (fatal first, at most 10, then `(+N more)`). `--json` prints one line `{status,file,findings,more?}`. QC measures and reports; it never decides for you: only FAIL exits 5, UNKNOWN exits 2. Pure assertions live in `@anvpx/motion-build` (`verifyMedia`), the ffprobe spawn here. `--determinism` compares a second render byte-for-byte (same machine/GPU/driver only); a mismatch is FAIL.
+
+With `--events`, one extra ffmpeg pass (`-v info -i IN -vf freezedetect=n=-60dB:d=2,blackdetect=d=0.1:pix_th=0.10 -an -f null -`; fixed argv, no user-supplied filter string, audio not decoded) reports `media-freeze-detected` and `media-black-detected` as WARN, never fatal: a hold is a judgment call on the clip (`docs/CRAFT-RUBRIC.md` §2 allows 3-4 s settled), not an engine verdict. Black that starts within 0.5 s of either end is `media-black-head-tail` info instead of a warn; nothing found is the info line `media-events-clear`. Detection that cannot run is UNKNOWN: `media-events-unavailable` (ffmpeg, freezedetect or blackdetect missing) and `media-events-unreadable` (decode failed). Both flags are opt-in and default off, so stdout without them is unchanged.
+
+Opt-in probes merge through `mergeReports`: FAIL > UNKNOWN > WARN > PASS, findings base first, and the merged status is the one exit-code authority, so WARN still exits 0 and UNKNOWN still exits 2. `--determinism` keeps its own FAIL-only escalation.
+
+## Provenance
+
+`manifest.json` (written by `build`) is byte-deterministic: sorted keys, no timestamps or machine paths; it records `storyboardSha256`, `themeHash`, `ledgerSha256`, `scenePlugins` (type -> providing package version), package versions, `hyperframes` pin, `node` version and a sha256 per file. `draft` and `render` also write `<out>/render-manifest.json`: manifest hash, output file name + sha256, render params, tool versions (ffmpeg, hyperframes, node) and verify status (`PASS|WARN|FAIL|UNKNOWN|not-run`). It describes the latest render (`kind`, `output.file`).
+
+## Output size
+
+Default output is at most 1 KB per command (`doctor`, `verify`); lists are capped with a total; argument errors are one sentence plus the usage line.
+
+## Rendering facts (hyperframes 0.8.212, checked against its real `--help`)
+
+- Run as `pnpm exec hyperframes ...` with cwd = project dir, through the injected runner (Windows: `cmd.exe /d /s /c`, only for the `pnpm`/`npx` .cmd shims; never `shell: true`). cmd.exe re-parses the command line, so on that path any argument containing `& | < > ^ " %`, a line break or NUL is refused (exit 127, message names the argument) rather than escaped. Keep user-provided values (paths, `--at` lists) free of those characters. Refuses to run unless `pnpm exec hyperframes --version` equals `motionKit.pins.hyperframes`.
+- Every build-based command writes `<out>/render-log.txt` (stdout + stderr of each tool); a failure prints the last 15 lines and the log path.
+- `draft`: hyperframes `--resolution` only offers presets from 1080p up, so it renders `--quality draft --fps 15` at the composition size, then ffmpeg downscales (`scale=960:-2:flags=lanczos`, x264 veryfast crf 23) into `draft.mp4` and deletes the intermediate.
+- `render`: `--quality delivery` (x264 preset slow, CRF 15 — the best preset the CLI offers; default `looks` is CRF 16). Size comes from the storyboard `meta`; `--resolution 4k` passes the matching `landscape-4k`/`portrait-4k`/`square-4k` preset. `--format webm|mov|gif|png-sequence` converts the delivered mp4 master with ffmpeg (the mp4 stays the source of truth; `--verify` is mp4-only).
+- `render --resume`: hyperframes supports it only with segmented capture, so `mk` sets `HF_SEGMENTED_CAPTURE=true` and passes `--resume`; finished segments from an interrupted render (`<out>/renders/.hf-segments/`) are reused. Experimental in hyperframes.
+- `<out>` must live inside the workspace so `pnpm exec` finds the pinned binary.
+
+## Pins (`mk doctor` warns when absent or mismatched; render commands refuse)
+
+Add to the repo-root `package.json`:
+
+```json
+"motionKit": { "pins": { "hyperframes": "0.8.212", "chromeHeadlessShell": "152.0.7977.30" } }
+```
+
+<!-- DL-01-START: install/doctor qualification (DL-01 owns these lines; AU-01 owns approval sections above) -->
+
+## Install qualification (DL-01)
+
+Install is the npm package install plus `mk doctor` hints; `mk plugin install --out <dir>` stays a separate explicit step, never part of npm install. Qualify with `node scripts/qualify-pack.mjs --json`: fresh pack records full inventory/SHA (`tarball.members`, `sha256`, bytes, `node`/`pnpm`/`npm`/`tar` versions, packed `hyperframes` pin vs root pin, `unpublishedInternals`), installs in an empty external consumer with no workspace fallback (`pnpm-workspace.yaml`/`packages/` absent), then runs native `doctor`/`catalog`/`template list`/`template validate explain` plus `new`/`validate`/`build`/`preview --stills 1 --budget-sec 20`/`approve` smoke with missing-target negatives; final `gated-render`/`verify` stay `NOT_RUN` without an explicit yes (do not render). Registry/marketplace stay `NOT_RUN`; isolated install is currently `BLOCKED` (`404` on unpublished `0.0.0` internals, `base: BLOCKED`; see DISTRIBUTION MK-080 choices A/B). Missing guide/index/font/icon/bed, source fallback reachable, wrong pin, broken install, missing venv/WAV all fail closed with actionable nonzero diagnostics (`reinstall @anvpx/motion`, `copy-dist-assets`, `mk doctor`, `py -3.12 -m venv .venv-voice`).
+
+## Voice and music delivery (DL-01)
+
+Voice probes (`python`, `python-venv`, `espeak`, `kokoro`, `faster-whisper`) fail closed with manual hints and never auto-install system/pip deps; `mk doctor --fix` leaves voice rows untouched. Supplied/authorized narration needs reviewed pronunciation, intelligibility, pacing, word alignment, no unintended silence plus measured `mk qc` audio QC; a unit test or synthetic silence is not human-quality proof. The 1 s procedural `music/bed.wav` silence is `NOT_RUN` for quality: silence must not pass as music quality. Base workflow `PASS` is distinct from optional voice/music `BLOCKED_ENV`/`NOT_RUN`.
+
+<!-- DL-01-END -->
+
+## Run
+
+```
+node packages/cli/src/main.ts doctor      # Node 24 type stripping; imports use .ts extensions
+pnpm test                                 # from the repo root (fast, fake runner)
+pnpm test:integration                     # in packages/cli: real validate/build/still/draft/render and the template flow new, preview, gated render, approve (~60 s); outputs in dist/.out/smoke and dist/.out/template-flow
+```

package/dist/analyze/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "../types.ts";
+export declare const analyzeCommand: Command;

package/dist/analyze/command.js

@@ -0,0 +1,190 @@
+import { ALIGN_MODEL_ID, alignWords, detectSilence, resolveVenvPython, VOICE_PROVENANCE, } from "@anvpx/motion-audio";
+import { AudioAnalysisSchema } from "@anvpx/motion-schema";
+import { parseFlags, requirePositional, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { probeMedia } from "../verify/probe.js";
+const USAGE = `mk analyze <audio.wav> [--words <words.json>] [--tokens <text>] [--out <file>] [--python <bin>]
+
+Analyze voice audio into AudioAnalysis JSON (words, silences, duration).
+Prints one compact JSON line to stdout, or writes it to --out.
+  <audio.wav>      audio file to analyze (required)
+  --words <file>   known word timings JSON [{w,start,end}]; skips the aligner
+  --tokens <text>  known script text; aligned with the voice venv python
+  --out <file>     write the JSON to <file> (stdout gets one summary line)
+  --python <bin>   explicit venv python (skips the probe; only with --tokens)
+Without --words or --tokens there are no word timings: silence intervals and
+duration are still measured and the analysis is UNKNOWN (exit 2), never failed.
+Exit 0 analysis ok; 2 UNKNOWN (could not decide) or bad arguments; 127 ffprobe or python missing.
+`;
+const FLAGS = {
+    words: { type: "string" },
+    tokens: { type: "string" },
+    out: { type: "string" },
+    python: { type: "string" },
+};
+const FFMPEG_HINT = "mk: ffprobe not found; install ffmpeg and put it on PATH";
+const DOCTOR_HINT = "Run `mk doctor` for the voice setup steps.";
+const isExit = (value) => typeof value === "object" && value !== null && value.kind === "exit";
+/** One ffprobe duration probe; unreadable audio is UNKNOWN, never failed. */
+async function measureDuration(io, audio) {
+    const probed = await probeMedia(io, audio);
+    if (!probed.ok && probed.kind === "missing-tool") {
+        io.stderr(`${FFMPEG_HINT}\n`);
+        return { kind: "exit", code: EXIT.MISSING_TOOL };
+    }
+    if (!probed.ok) {
+        io.stderr(`mk analyze: could not read audio: ${probed.reason}; result is UNKNOWN\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    const format = probed.probe.format;
+    const duration = Number(format?.duration);
+    return Number.isFinite(duration) && duration > 0 ? duration : undefined;
+}
+/** ffprobe silencedetect gate; missing ffprobe is 127, a failed gate is UNKNOWN. */
+async function measureSilence(io, audio) {
+    const silence = await detectSilence(io.run, { audioPath: audio });
+    if (!silence.ok && silence.status === "missing") {
+        io.stderr(`${FFMPEG_HINT}\n`);
+        return { kind: "exit", code: EXIT.MISSING_TOOL };
+    }
+    if (!silence.ok) {
+        io.stderr(`mk analyze: silence gate failed: ${silence.hint}; result is UNKNOWN\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    return silence.intervals;
+}
+/** Known word timings from a JSON file; invalid content is a usage error. */
+async function wordsFromFile(io, path) {
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk analyze: ${loaded.message}\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    if (!Array.isArray(loaded.value)) {
+        return usageError("analyze", USAGE, "words file must be a JSON array", io);
+    }
+    return loaded.value;
+}
+const splitTokens = (text) => text.split(/\s+/).filter((w) => w.length > 0);
+async function pickPython(io, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const probe = await resolveVenvPython(io.run);
+    if (probe.ok)
+        return probe.python;
+    io.stderr(`mk analyze: ${probe.hint}\n${DOCTOR_HINT}\n`);
+    return { kind: "exit", code: EXIT.MISSING_TOOL };
+}
+/** Align known script text with the voice venv python; failures never fake words. */
+async function wordsFromTokens(io, audio, text, explicitPython) {
+    const tokens = splitTokens(text);
+    if (tokens.length === 0) {
+        return usageError("analyze", USAGE, "--tokens needs at least one token", io);
+    }
+    const python = await pickPython(io, explicitPython);
+    if (isExit(python))
+        return python;
+    const aligned = await alignWords(io.run, { audioPath: audio, tokens, python });
+    if (!aligned.ok && aligned.status === "missing") {
+        io.stderr(`mk analyze: ${aligned.hint}\n${DOCTOR_HINT}\n`);
+        return { kind: "exit", code: EXIT.MISSING_TOOL };
+    }
+    if (!aligned.ok) {
+        io.stderr(`mk analyze: align failed: ${aligned.hint}; result is UNKNOWN\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    return {
+        words: aligned.words,
+        model: ALIGN_MODEL_ID,
+        modelRevision: VOICE_PROVENANCE.alignModelRev,
+    };
+}
+/** Words plus optional model provenance from --words or --tokens. */
+async function loadWords(io, audio, wordsPath, tokens, python) {
+    if (wordsPath === undefined && tokens === undefined) {
+        io.stderr("mk analyze: no --words or --tokens; word timings are UNKNOWN\n");
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    if (wordsPath !== undefined) {
+        const words = await wordsFromFile(io, wordsPath);
+        if (isExit(words))
+            return words;
+        return { words };
+    }
+    return wordsFromTokens(io, audio, tokens, python);
+}
+/** Validate against the schema and emit (stdout JSON, or --out file plus a summary). */
+async function emitAnalysis(io, input, out) {
+    const validated = AudioAnalysisSchema.safeParse(input);
+    if (!validated.success) {
+        const problems = validated.error.issues
+            .map((issue) => `${issue.path.join("/")}: ${issue.message}`)
+            .join("; ");
+        io.stderr(`mk analyze: refusing invalid analysis: ${problems}\n`);
+        return EXIT.USAGE;
+    }
+    const json = `${JSON.stringify(validated.data)}\n`;
+    if (out === undefined) {
+        io.stdout(json);
+        return EXIT.OK;
+    }
+    await io.host.writeTextAtomic(out, json);
+    io.stdout(`analyze ok | ${validated.data.words.length} words -> ${out}\n`);
+    return EXIT.OK;
+}
+const silencesOf = (intervals) => intervals.length === 0 ? undefined : intervals.map(([start, end]) => ({ start, end }));
+const analysisOf = (source, intervals, duration) => {
+    const silences = silencesOf(intervals);
+    return {
+        words: source.words,
+        ...(silences === undefined ? {} : { silences }),
+        ...(duration === undefined ? {} : { duration }),
+        ...(source.model === undefined ? {} : { model: source.model }),
+        ...(source.modelRevision === undefined ? {} : { modelRevision: source.modelRevision }),
+    };
+};
+/** Flags plus the positional audio path, or the usage failure to exit with. */
+async function resolveInput(args, io) {
+    const parsed = parseFlags("analyze", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed;
+    const audio = requirePositional("analyze", USAGE, parsed.positionals, "<audio.wav>", io);
+    if (typeof audio !== "string")
+        return audio;
+    if (!(await io.host.exists(audio))) {
+        io.stderr(`mk analyze: cannot read ${audio}; check the path.\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    const wordsPath = textFlag(parsed.flags, "words");
+    const tokens = textFlag(parsed.flags, "tokens");
+    if (wordsPath !== undefined && tokens !== undefined) {
+        return usageError("analyze", USAGE, "use only one of --words or --tokens", io);
+    }
+    return {
+        audio,
+        wordsPath,
+        tokens,
+        python: textFlag(parsed.flags, "python"),
+        out: textFlag(parsed.flags, "out"),
+    };
+}
+export const analyzeCommand = {
+    name: "analyze",
+    summary: "analyze voice audio into AudioAnalysis JSON (words, silences, duration)",
+    async run(args, io) {
+        const input = await resolveInput(args, io);
+        if (isExit(input))
+            return input.code;
+        const duration = await measureDuration(io, input.audio);
+        if (isExit(duration))
+            return duration.code;
+        const intervals = await measureSilence(io, input.audio);
+        if (isExit(intervals))
+            return intervals.code;
+        const source = await loadWords(io, input.audio, input.wordsPath, input.tokens, input.python);
+        if (isExit(source))
+            return source.code;
+        return emitAnalysis(io, analysisOf(source, intervals, duration), input.out);
+    },
+};

package/dist/approval/approval.d.ts

@@ -0,0 +1,32 @@
+import type { Host } from "../types.ts";
+import { type ApprovalBuildOptions, type ApprovalInputManifest } from "./hash.ts";
+export declare const APPROVAL_FILE = "approval.json";
+export declare const approvalPath: (storyboard: string) => string;
+export interface Approval {
+    readonly inputManifest: ApprovalInputManifest;
+    readonly inputManifestSha256: string;
+    readonly previewManifestSha: string;
+    readonly approvedAt: string;
+    readonly note: string;
+}
+export type ApprovalState = {
+    state: "approved";
+    hash: string;
+} | {
+    state: "missing" | "stale";
+    hash: string;
+};
+/** The stored approval, or undefined when absent, malformed or legacy. */
+export declare function readApproval(host: Host, storyboard: string): Promise<Approval | undefined>;
+export declare function writeApproval(host: Host, storyboard: string, approval: Approval): Promise<string>;
+/**
+ * Does an approval match the CURRENT inputs (visual, audiovisual or
+ * audiovisual+music)? Fails
+ * closed: any legacy receipt is `stale` (re-preview + re-approve), missing
+ * file is `missing`. A visual-only receipt never authorizes audio: resolving
+ * with --audio recomputes the audiovisual hash, which cannot match. A
+ * narration-only receipt never authorizes --music: the music
+ * {path,sha256,volume,licenseEvidenceSha256} binding changes the hash.
+ * Rejects when inputs are unreadable (missing asset, ledger, wav…).
+ */
+export declare function approvalState(host: Host, storyboard: string, opts?: ApprovalBuildOptions): Promise<ApprovalState>;

package/dist/approval/approval.js

@@ -0,0 +1,141 @@
+import { join } from "node:path";
+import { buildApprovalInputManifest, hashApprovalInput, mkDir, readSidecar, } from "./hash.js";
+export const APPROVAL_FILE = "approval.json";
+export const approvalPath = (storyboard) => join(mkDir(storyboard), APPROVAL_FILE);
+const HEX64 = /^[a-f0-9]{64}$/;
+const isManifestRef = (value) => {
+    const row = value;
+    return (typeof row === "object" &&
+        row !== null &&
+        typeof row.path === "string" &&
+        typeof row.sha256 === "string" &&
+        row.sha256.length === 64);
+};
+const everyManifestRef = (value) => Array.isArray(value) && value.every(isManifestRef);
+const hasLedger = (value) => value === undefined || (typeof value === "string" && HEX64.test(value));
+const isMixClip = (value) => {
+    const row = value;
+    return (typeof row === "object" &&
+        row !== null &&
+        typeof row.id === "string" &&
+        typeof row.start === "number" &&
+        typeof row.wavSha === "string" &&
+        row.wavSha.length === 64);
+};
+const isMix = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return false;
+    if (row.mode !== "single" && row.mode !== "concat" && row.mode !== "adelay")
+        return false;
+    return Array.isArray(row.clips) && row.clips.every(isMixClip);
+};
+const isMusic = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return false;
+    if (typeof row.path !== "string" || row.path.length === 0)
+        return false;
+    if (typeof row.sha256 !== "string" || !HEX64.test(row.sha256))
+        return false;
+    if (typeof row.volume !== "number" ||
+        !Number.isFinite(row.volume) ||
+        row.volume <= 0 ||
+        row.volume > 1)
+        return false;
+    const lic = row.licenseEvidenceSha256;
+    return lic === null || (typeof lic === "string" && HEX64.test(lic));
+};
+const hasMusic = (value) => value === undefined || isMusic(value);
+const isApprovalManifest = (value) => {
+    const manifest = value;
+    if (typeof manifest !== "object" || manifest === null)
+        return false;
+    if (manifest.scope !== "visual" && manifest.scope !== "audiovisual")
+        return false;
+    if (!isManifestRef(manifest.storyboard))
+        return false;
+    if (!everyManifestRef(manifest.themes))
+        return false;
+    if (!everyManifestRef(manifest.assets))
+        return false;
+    if (!everyManifestRef(manifest.audio))
+        return false;
+    if (!hasLedger(manifest.ledgerSha256))
+        return false;
+    if (manifest.scope === "visual") {
+        if ((manifest.audio ?? []).length !== 0)
+            return false;
+        if (manifest.audioManifest !== undefined || manifest.mix !== undefined)
+            return false;
+        if (manifest.music !== undefined)
+            return false;
+        return true;
+    }
+    if (!isManifestRef(manifest.audioManifest))
+        return false;
+    if (!isMix(manifest.mix))
+        return false;
+    if (!hasMusic(manifest.music))
+        return false;
+    return (manifest.audio ?? []).length > 0;
+};
+const isApprovalReceiptFields = (row) => typeof row.inputManifestSha256 === "string" &&
+    HEX64.test(row.inputManifestSha256) &&
+    typeof row.previewManifestSha === "string" &&
+    typeof row.approvedAt === "string" &&
+    typeof row.note === "string";
+const isApproval = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return false;
+    if (!isApprovalManifest(row.inputManifest))
+        return false;
+    return isApprovalReceiptFields(row);
+};
+/** The stored approval, or undefined when absent, malformed or legacy. */
+export async function readApproval(host, storyboard) {
+    try {
+        const parsed = JSON.parse(await readSidecar(host, storyboard, APPROVAL_FILE));
+        return isApproval(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeApproval(host, storyboard, approval) {
+    const path = approvalPath(storyboard);
+    await host.writeText(path, `${JSON.stringify(approval, null, 2)}\n`);
+    return path;
+}
+/**
+ * Does an approval match the CURRENT inputs (visual, audiovisual or
+ * audiovisual+music)? Fails
+ * closed: any legacy receipt is `stale` (re-preview + re-approve), missing
+ * file is `missing`. A visual-only receipt never authorizes audio: resolving
+ * with --audio recomputes the audiovisual hash, which cannot match. A
+ * narration-only receipt never authorizes --music: the music
+ * {path,sha256,volume,licenseEvidenceSha256} binding changes the hash.
+ * Rejects when inputs are unreadable (missing asset, ledger, wav…).
+ */
+export async function approvalState(host, storyboard, opts = {}) {
+    const manifest = await buildApprovalInputManifest(host, storyboard, opts);
+    const hash = hashApprovalInput(manifest);
+    let raw;
+    try {
+        raw = await readSidecar(host, storyboard, APPROVAL_FILE);
+    }
+    catch {
+        return { state: "missing", hash };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { state: "stale", hash };
+    }
+    if (!isApproval(parsed))
+        return { state: "stale", hash };
+    return { state: parsed.inputManifestSha256 === hash ? "approved" : "stale", hash };
+}

package/dist/approval/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "../types.ts";
+export declare const approveCommand: Command;