ffmpeg-skill 1.9.1 → 1.10.1

package/README.md

@@ -153,13 +153,13 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 ## Tools
 
-42 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
+42 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, `--plan FILE` (a dry run written as a plan `render.py` executes later), non-zero exit and a reason on stderr on failure. Every re-encoding tool takes `--codec h264|hevc|av1|prores` and `--quality N` (1.8), and every time flag takes seconds, `mm:ss`, `hh:mm:ss.fff` or SMPTE `hh:mm:ss:ff` with an optional `@fps` suffix (1.9).
 
 **Analysis and inspection**
 
 | Tool | What it does |
 |---|---|
-| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision, colour space, rotation, every audio stream; `--analyze` flags Log footage |
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision (`hdr` for BT.2020 or PQ/HLG, `hdr_signal` for a real PQ/HLG/DV transfer only), colour space, rotation, every audio stream; `--analyze` flags Log footage |
 | `scenes.py` | Scene changes, audio peaks, highlight proposals (`--rank-by audio` loudest, or `--rank-by duration` longest — both proxies, not "best") and a per-scene sheet; cut list for `cut.py --segments` |
 | `look.py` | Contact sheet, single frames, side-by-side comparison as PNG so the agent can see what it made |
 
@@ -213,8 +213,8 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 | Tool | What it does |
 |---|---|
-| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif`, all tagged BT.709 |
-| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--crf`, `--fps`, `--no-audio`; not a delivery preset |
+| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif`, all tagged BT.709; `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) |
+| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--crf` (deprecated alias of `--quality`), `--fps`, `--no-audio`; not a delivery preset |
 | `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, broadcast and podcast specs, with the fix for each failure and a `format` / `judgement` kind per row |
 | `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run |
 
@@ -293,6 +293,8 @@ The contract is generated from the code that runs, not maintained beside it. For
 | `mutates_input` | always `false` |
 | `idempotency_hint` | `bit_exact`, `content_equivalent`, `cached` or `environment_dependent` |
 
+Next to the tool list the document carries a top-level `deprecated` list (1.10): what 2.0.0 removes, since when, the replacement and the surface it lives on. `docs/contract.md` "What 2.0 changes" is written from it.
+
 `contract_version` (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure (`{"status": "failed", "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification | interrupted", "message": …}}`), and that no tool runs a shell or executes anything other than the named script, `ffmpeg` and `ffprobe`. Field-by-field reference: [docs/contract.md](docs/contract.md).
 
 ### MCP
@@ -305,6 +307,8 @@ On Windows, `python3` is only on PATH if Python was installed from the Microsoft
 
 `mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 42 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
 
+`FFMPEG_SKILL_MCP_LEAN=1` in the server's environment drops `json` and `progress` from every `inputSchema`: they are transport flags the server sets itself, not tool arguments, and 2.0 drops them unconditionally. It is opt-in, so the default `tools/list` stays byte-identical to the CLI surface the contract promises.
+
 ### Capability detection
 
 ```bash
@@ -329,6 +333,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 - **Non-Latin captions need a font with the glyphs.** Without one you get boxes, not an error. Name it (`caption.py --font "Noto Sans CJK JP"`) or point at the file (`overlay.py --font-file /path/to/NotoSansCJK-Regular.ttc`).
 - **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.
 - **Sync results carry a confidence.** Below 0.3, or an offset near the edge of the analysis window, is probably wrong: enlarge `--analyze-seconds` or find a clap. Recordings over ten minutes from separate devices need `sync.py --fix-drift`.
+- **Outputs are never overwritten silently.** An existing output path is warned about today and refused from 2.0; set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) to get the refusal now and pass `--overwrite` where a replacement is intended.
 - **Long chains belong in a plan.** Three hand-chained re-encodes lose quality and are hard to change; `render.py` runs the whole edit from one JSON file, and `--dry-run` shows every ffmpeg command before anything is written.
 
 ## FFmpeg compatibility
@@ -355,6 +360,8 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **108 / 108** | 1.10.0 re-run (2026-09-13, three passes per prompt, Sonnet agent, regex grader + focused Opus grader): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, report format 108/108 by both graders (the harness now names the five labels), user's language 105/108 (every Japanese request in Japanese; 3 English requests drifted to Spanish or Portuguese), visual check 21/24, trigger set 22/22; real-device corpus 101/101 steps PASS. Details in `evals/results/iteration-10.json` |
+| **108 / 108** | 1.9.0 re-run (2026-09-13, three passes per prompt, Sonnet agent, regex grader + independent Opus grader): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 23/26, user's language 105/108 (every Japanese request answered in Japanese; 3 English requests drifted to Spanish), report format 108/108 by regex (65/108 by the stricter grader, which now counts any missing label), trigger set 22/22; 12 of 15 platform jobs were one encode and `render.py` rendered once in 3/3 (was 1/3). The 1.9.0 time grammar was not used by any agent. Details in `evals/results/iteration-9.json` |
 | **108 / 108** | 1.8.0 re-run (2026-09-12, three passes per prompt, Sonnet agent, regex grader + independent Opus grader that re-probed 22 outputs): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 22/24, report format 108/108 by regex (91/108 by the stricter grader: 'What/how:' in place of Steps:), user's language 98/108 by the stricter grader (Japanese labels-only reports counted), trigger set 22/22; 13 of 14 platform exports used `--normalize` and platform jobs went from three encodes to one; r04/f01 now answered in the request's language 5/6 (was 0/6). Details in `evals/results/iteration-8.json` |
 | **108 / 108** | 1.7.0 re-run (2026-09-12, three passes per prompt, Sonnet agent, regex grader + independent Opus grader that re-probed 24 outputs): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 25/25, report format 108/108 by regex (104/108 by the stricter grader), user's language 101/108 (six English refusals answered in Spanish or Portuguese, one Japanese request in English); trigger set 22/22. Iteration-6 fixes held (fade-in only, Japanese audio trims, music no longer shortens the video). Details in `evals/results/iteration-7.json` |
 | **36 / 36** | 1.4.15 re-run (2026-09-12, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, report format 25/25, user's language 9/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3, one Japanese report with English labels; trigger set 22/22. Both iteration-5 defects gone (no raw ffmpeg fallback, music no longer shortens the video). Details in `evals/results/iteration-6.json` |
@@ -417,7 +424,7 @@ FFmpeg itself:
 
 ## Stability
 
-1.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 2.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-1x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch.
+1.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 2.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-1x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch. What 2.0 will remove is already announced: `contract --json` lists it under `deprecated`, `--crf` prints a one-line warning where `--quality` exists, and [docs/contract.md](docs/contract.md#what-20-changes) says what a caller does today to be ready.
 
 ## Development
 

package/SKILL.md

@@ -65,9 +65,16 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    failure, and the report says so with the script's error message.
 7. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
+   Set `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment you run these scripts
+   in: an output path that already exists is then refused (`kind: input`)
+   instead of warned about, and `--overwrite` stays the one way to say "yes,
+   replace it". It is the recommended agent setting because an agent picking
+   output names cannot see which files the user already cares about — and it
+   is what 2.0 does by default.
 8. **Look at the picture.** Whenever the picture changed (captions, overlays,
    graphics, crop/pad, resize, colour, transitions, a `join.py` that scaled or
-   padded a clip to the first clip's frame) run `look.py OUTPUT`
+   padded a clip to the first clip's frame, a `color.py --to-sdr` that tone-maps
+   an HDR source) run `look.py OUTPUT`
    (contact sheet) or `look.py OUTPUT --at T`, view the PNG. The job is not
    finished until the report's `Look:` line names that PNG; a probe alone
    cannot see a caption sitting on someone's face. Audio-only jobs (sync,
@@ -123,6 +130,10 @@ If a request needs an FFmpeg feature none of the 42 scripts expose, say so and n
 
 ## Request → script
 
+This table and `doctor --json`'s `tools` list are the source of truth for what exists: name only a script you have seen in one of them, never a plausible-sounding one (there is no `doctor.py`, no `trim.py`, no `subtitle.py`).
+
+Timestamp flags -- `--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`, and the times in cue and chapter files -- take seconds, `mm:ss(.fff)`, `hh:mm:ss(.fff)` or four-part SMPTE `hh:mm:ss:ff`, with `@fps` naming the rate (`00:01:02:15@29.97`); tolerance-style flags that are a length rather than a point in time (`--min-silence`, `--margin`, `--min-keep`, `--fade`) are plain seconds. Use the timecode forms when the user pastes an editor's timecode list or an NLE cue sheet, so nothing is converted by hand on the way in.
+
 | User says | Do |
 |-----------|----|
 | "what's in this file", "how long is it", "is it 4K" | `probe.py input.mp4` |
@@ -243,7 +254,7 @@ commands work with `talk.wav` in place of `talk.mp4`. What changes:
 
 ## Report format
 
-Reply in the language the request itself is written in: the language of the user's own sentences, not a language the request talks about (an English request for Spanish subtitles gets an English report) and not the language of a tool's error text or of the file names. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English, and never drift into another language because the job is short or the report is a failure: a one-line "file does not exist" is written in the request's language too. A mid-conversation language switch follows the user's latest message, not the first one. This holds for a one-command job too: a three-second audio trim answered with English labels, numbers and one Japanese word in `Notes:` is an English report; the `Done:` line's own description (what was cut, from where) and `Steps:` are written in the user's language even when the values are technical.
+Reply in the language the request itself is written in: the language of the user's own sentences, not a language the request talks about (a request asking for subtitles in some other language is still answered in the language it was written in) and not the language of a tool's error text or of the file names. Keep the shape below and the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English (they read like log fields, not prose, and stay recognisable across languages); the sentences around them, any question asked, and any explanation of a judgement call are in the user's language. Never default to English because the tool names and flags happen to be English, and never drift into another language because the job is short or the report is a failure: a one-line "file does not exist" is written in the request's language too. A mid-conversation language switch follows the user's latest message, not the first one. This holds for a one-command job too: a three-second audio trim answered with English labels, numbers and one Japanese word in `Notes:` is an English report; the `Done:` line's own description (what was cut, from where) and `Steps:` are written in the user's language even when the values are technical.
 
 Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory):
 
@@ -319,7 +330,10 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out
   script keeps the output HDR (HEVC Main10, source colour tags) so nothing is
   silently flattened. Decide with the user: keep HDR (fine for YouTube/phones)
   or run `color.py --to-sdr` first for SDR-only destinations, LUT work or
-  H.264 deliverables. `export.py` platform presets are SDR and warn on HDR
+  H.264 deliverables. `hdr: true` counts BT.2020 primaries too, so it is also
+  true for a wide-gamut SDR file; `hdr_signal: true` is the narrower fact —
+  a real PQ / HLG / Dolby Vision transfer — and `hdr_format` names the
+  in-between case (`BT.2020 SDR`). `export.py` platform presets are SDR and warn on HDR
   input. iPhone `.mov` files also carry timecode/metadata tracks; scripts map
   only the first audio track, so extra tracks are dropped on re-encode.
   For Log footage (S-Log, V-Log, C-Log: looks grey and low-contrast but is

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.9.1`) | any release |
+| `skill.version` | the npm / package.json version (`1.10.1`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -78,12 +78,29 @@ A defect fix that changes behaviour is not a deprecation: it ships in a patch wi
 CHANGELOG line, and if the old behaviour was something a caller could reasonably have relied
 on, the line says so.
 
+## What 2.0 changes
+
+`contract --json` carries a top-level `deprecated` list, next to `contract_version`: one entry per
+thing 2.0.0 removes, `{"what", "since", "replacement", "removed_in", "where"}` with `where` naming
+the surface (`cli`, `json`, `mcp`, `behaviour`). It is the machine-readable half of the policy
+above, and this section is written from it. Nothing below changes behaviour in 1.x -- every old
+spelling keeps working until 2.0.
+
+| What 2.0 removes | Since | Replacement | To be ready today |
+|---|---|---|---|
+| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.10.1 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
+| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.10.1 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
+| `json` and `progress` in the MCP `inputSchema` | 1.10.1 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
+| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.10.1 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
+| Overwriting an existing output with only a warning | 1.10.1 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |
+
 ## Skill
 
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.9.1", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.10.1", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.10.1", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -404,6 +421,15 @@ already applied when the ToolSpec is built.
 The `tools/list` document is deterministic (byte-identical across processes and
 identical to the translation of `contract --json`), which the tests check.
 
+`FFMPEG_SKILL_MCP_LEAN=1` (anything but "" or `0`) in the server's environment removes `json` and
+`progress` from every `inputSchema` (from `properties`, and from `required` if a tool ever made
+them required). They are transport flags `mcp/server.py` sets itself -- it appends `--json` for
+every tool but `look` and `probe` -- rather than arguments a caller chooses, and 2.0 drops them
+for good (see "What 2.0 changes"). The flag is opt-in and changes nothing else: without it
+`tools/list` carries the tool names, argument names and `required` lists the frozen 1.x snapshot
+pins -- descriptions may change between releases (the `--crf` deprecation mark did) -- so a lean
+client and a default client see the same tools with the same names.
+
 ## Consuming the contract from an agent
 
 A planning agent (for example video-production-agent's SkillRegistry) can:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.9.1",
+  "version": "1.10.1",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/scripts.md

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--crf` is deprecated since 1.10.0 (it warns on stderr and is removed in 2.0): use `--quality`, except on `export.py`, whose `--crf` is not an alias and stays. With `FFMPEG_SKILL_NO_OVERWRITE=1` in the environment, any tool refuses (`kind: input`) to replace an existing output unless `--overwrite` is given. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Time grammar (every time-taking flag, 1.9)
 
@@ -406,7 +406,9 @@ and the project has no `loudness` stage; `"normalize": false` opts out.
 
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
 captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
-CLI flags of each script (see the docstring). Use it whenever an edit has
+CLI flags of each script (see the docstring); a key `render.py` does not read -- at
+the top level or in any stage/clip object -- is refused (`kind: input`) naming the
+key and the nearest valid one, never silently ignored. Use it whenever an edit has
 more than two steps or the user is likely to ask for changes: edit the JSON,
 re-render, and the result is reproducible. `--dry-run --json` prints the
 complete command plan for review.

package/scripts/_common.py

@@ -166,7 +166,7 @@ def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
     parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
 
 
-def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
+def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None, **extra: Any) -> "None":
     """Exit with a message. Under --json also print a machine-readable failure document
     (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged.
 
@@ -176,9 +176,12 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
     `status: "completed"` next to a non-zero exit code, so a caller keying on the status alone
     read a failed delivery as a success."""
     hint = extra.pop("hint", None)
-    STATE.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
+    ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
+    _set_current_ctx(ctx)  # the atexit hook has no argument: it reads the ctx emit()/die() last used
+    ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
+    STATE.plan = None  # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
     sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
-    if STATE.json:
+    if ctx.json:
         doc: Dict[str, Any] = {
             "status": "failed", "exit_code": code,
             "error": {
@@ -186,7 +189,7 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
                 "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
                 "retryable": ERROR_RETRYABLE,
             },
-            "commands": list(STATE.commands),
+            "commands": list(ctx.commands),
         }
         if hint:
             doc["error"]["hint"] = hint
@@ -195,9 +198,10 @@ def die(msg: str, code: int = 1, kind: str = "input", **extra: Any) -> "None":
     sys.exit(code)
 
 
-def info(msg: str) -> None:
+def info(msg: str, ctx: "Optional[Context]" = None) -> None:
     # under --dry-run nothing is written; do not let scripts claim otherwise
-    if msg.startswith("wrote ") and STATE.dry_run:
+    ctx = ctx or STATE
+    if msg.startswith("wrote ") and ctx.dry_run:
         msg = "[dry-run] would write " + msg[len("wrote "):]
     sys.stderr.write(f"{msg}\n")
 
@@ -257,6 +261,15 @@ class Context:
 
 STATE = Context()
 
+# The atexit plan hook takes no arguments, so emit()/die() record the Context they were given
+# here; nothing passed a ctx = it stays None and the hook falls back to STATE, as before (1.10).
+_CURRENT_CTX: "Optional[Context]" = None
+
+
+def _set_current_ctx(ctx: "Context") -> None:
+    global _CURRENT_CTX
+    _CURRENT_CTX = ctx
+
 
 def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
     """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
@@ -274,6 +287,21 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
     g.add_argument("--plan", metavar="FILE",
                    help="write the dry run as a plan (inputs fingerprinted, commands, expected output, verify steps) that render.py FILE executes later; implies --dry-run")
     if codec and "--crf" in ap._option_string_actions:
+        # --crf became an alias of --quality in 1.8; 1.10 deprecates it (removed in 2.0, see the
+        # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
+        # here, once, rather than in each re-encoding tool's own parser.
+        crf = ap._option_string_actions["--crf"]
+        # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
+        # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
+        # apply_common() puts _CRF_DEFAULT back when the flag was absent.
+        global _CRF_DEFAULT
+        _CRF_DEFAULT = crf.default
+        crf.deprecated_default = crf.default  # the schema still advertises it (_contract._json_type)
+        crf.default = None
+        if "deprecated" not in (crf.help or ""):
+            # the nine tools that declare --crf with no help string used to fall through this and
+            # never show the mark at all (review 9)
+            crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
         # only the tools that re-encode (they declare --crf before add_common): one encoder choice
         # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
         g.add_argument("--codec", choices=CODECS, default=None,
@@ -282,7 +310,18 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
                        help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
 
 
+# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
+_CRF_DEFAULT: Optional[int] = None
+
+
 def apply_common(args: "argparse.Namespace") -> None:
+    # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
+    # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
+    # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
+    # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
+    crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
+    if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
+        args.crf = _CRF_DEFAULT
     STATE.plan = getattr(args, "plan", None) or None
     STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
     if STATE.plan:
@@ -316,6 +355,11 @@ def apply_common(args: "argparse.Namespace") -> None:
             die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
                 hint="give -o NAME.mov")
     crf = getattr(args, "crf", None)
+    # The warning the deprecation policy asks for, only when the caller typed the flag (see
+    # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
+    # --crf is not an alias and is not deprecated: warn only where --quality exists.
+    if crf is not None and crf_explicit:
+        info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
     top = 63 if STATE.codec == "av1" else 51
     if crf is not None and not 0 <= int(crf) <= top:
         die(f"--crf must be between 0 and {top} ({'SVT-AV1' if STATE.codec == 'av1' else 'x264/x265'} scale; 18 is visually lossless), got {crf}")
@@ -381,13 +425,18 @@ def _unwatch(proc: subprocess.Popen) -> None:
     _CHILDREN[:] = [(p, c) for p, c in _CHILDREN if p is not proc]
 
 
-def emit(output: Optional[str], **extra: Any) -> None:
-    """Final stdout line: the output path, or a JSON document with --json."""
+def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
+    """Final stdout line: the output path, or a JSON document with --json.
+
+    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+    omitted, every read falls back to the process-global STATE as before."""
+    ctx = ctx or STATE
+    _set_current_ctx(ctx)  # so the atexit hook writes (or skips) this ctx's plan, not STATE's
     meta: Dict[str, Any] = {}
-    if output and not STATE.dry_run:
+    if output and not ctx.dry_run:
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
-    if STATE.json:
-        doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": STATE.dry_run, "commands": list(STATE.commands)}
+    if ctx.json:
+        doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
         if meta:
             doc["probe"] = meta
         # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
@@ -397,18 +446,18 @@ def emit(output: Optional[str], **extra: Any) -> None:
         # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
         # keep status completed and say verified: false, so a caller keys on one field.
         steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
-        if output and not STATE.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
+        if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
             steps.insert(0, {"step": "exists", "ok": True})
-        doc["verified"] = not STATE.dry_run and bool(steps) and all(s.get("ok") for s in steps)
+        doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
         doc["verification"] = steps
         doc.update(extra)
         if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
             doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
-        if STATE.plan:
-            doc["plan"] = write_plan(STATE.plan, output, extra)
+        if ctx.plan:
+            doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
         print_json(doc)
-    elif STATE.plan:
-        print(write_plan(STATE.plan, output, extra))
+    elif ctx.plan:
+        print(write_plan(ctx.plan, output, extra, ctx=ctx))
     elif output:
         print(output)
 
@@ -418,9 +467,10 @@ _PLAN_STRIP = ("--plan", "--dry-run", "--json")
 
 
 def _plan_at_exit() -> None:
-    if STATE.plan and not STATE.plan_written:
+    ctx = _CURRENT_CTX or STATE
+    if ctx.plan and not ctx.plan_written:
         try:
-            write_plan(STATE.plan, None, {})
+            write_plan(ctx.plan, None, {}, ctx=ctx)
         except SystemExit:
             pass
 
@@ -443,13 +493,13 @@ def fingerprint(path: str) -> Dict[str, Any]:
     return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
 
 
-def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = ()) -> List[str]:
+def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Optional[Context]" = None) -> List[str]:
     """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
     existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
     inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
     import shlex
     seen: List[str] = []
-    for a in list(argv) + list(STATE.plan_inputs):
+    for a in list(argv) + list((ctx or STATE).plan_inputs):
         if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
             seen.append(a)
     for line in commands:
@@ -463,10 +513,14 @@ def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = ()) -> List[str]
     return seen
 
 
-def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
+def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Optional[Context]" = None) -> str:
     """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
-    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C)."""
+    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C).
+
+    `ctx` is the Context whose commands and inputs the plan describes (emit()/die() pass the one
+    they were given); omitted, it is the process-global STATE as before."""
     import datetime
+    ctx = ctx or STATE
     argv = [a for a in sys.argv[1:]]
     cleaned: List[str] = []
     skip = False
@@ -495,8 +549,8 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
         "tool": tool,
         "argv": cleaned,
         "cwd": os.getcwd(),
-        "inputs": [fingerprint(p) for p in _plan_inputs(STATE.commands, cleaned)],
-        "commands": list(STATE.commands),
+        "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
+        "commands": list(ctx.commands),
         "output": os.path.abspath(output) if output else None,
         "verify": verify,
         "notes": list(extra.get("notes") or []),
@@ -509,8 +563,8 @@ def write_plan(path: str, output: Optional[str], extra: Dict[str, Any]) -> str:
         os.replace(tmp, path)
     except OSError as exc:
         die(f"cannot write plan {path}: {exc}", kind="output")
-    STATE.plan_written = True
-    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}")
+    ctx.plan_written = True
+    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}", ctx)
     return path
 
 
@@ -840,7 +894,7 @@ def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str]
     return list(cmd[:-1]) + [tmp], output, tmp
 
 
-def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
+def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Optional[Context]" = None) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
     ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run
@@ -848,16 +902,20 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     with a progress readout under --progress. ffprobe and other tools always run. An output
     path that already exists is written through a temp file and replaced only on success
     (see _stage_existing_output), so a failed run never costs the caller the file that was there.
+
+    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+    omitted, the commands and flags are read from the process-global STATE as before.
     """
+    ctx = ctx or STATE
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
         _check_existing_output(cmd)
-        STATE.commands.append(_cmdline(cmd))
+        ctx.commands.append(_cmdline(cmd))
     if not quiet:
-        info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
-    if STATE.dry_run and is_ffmpeg:
+        info(("[dry-run] $ " if ctx.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd), ctx=ctx)
+    if ctx.dry_run and is_ffmpeg:
         return subprocess.CompletedProcess(list(cmd), 0, "", "")
     with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
         exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
@@ -866,7 +924,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
             retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
             if retry is not None:
                 info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
-                STATE.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
+                ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
                 proc = _execute(retry)
             elif "not divisible by 2" in (proc.stderr or ""):
                 die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "
@@ -1468,7 +1526,11 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
         raise ValueError(f"bad time: {value}")
     total = 0.0
     for part in parts:
-        total = total * 60 + float(part)
+        try:
+            total = total * 60 + float(part)
+        except ValueError:
+            # not the interpreter's "could not convert string to float: 'zz'" (review 9)
+            raise ValueError(f"'{value}': not a time")
     return total
 
 

package/scripts/_contract.py

@@ -342,12 +342,15 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
         if isinstance(action, argparse._HelpAction):
             continue
         prop: Dict[str, Any] = _json_type(action)
+        # add_common() parks a deprecated --crf's default aside (so an explicit flag is
+        # distinguishable from the default); the schema still advertises the real one
+        default = getattr(action, "deprecated_default", action.default)
         if action.help and action.help != argparse.SUPPRESS:
-            prop["description"] = action.help % {"default": action.default} if "%(default)" in action.help else action.help
+            prop["description"] = action.help % {"default": default} if "%(default)" in action.help else action.help
         if action.choices:
             prop["enum"] = list(action.choices)
-        if action.default not in (None, False, argparse.SUPPRESS):
-            prop["default"] = action.default
+        if default not in (None, False, argparse.SUPPRESS):
+            prop["default"] = default
         if action.option_strings:
             prop["cli"] = list(action.option_strings)
             if action.required:
@@ -947,7 +950,35 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
 # ----------------------------------------------------------------------------- MCP derivation
 # tools that print JSON without --json (probe) or whose primary output is a file path (look): the transport
 # does not append --json for them (stated in invocation.structured.argument_mapping.json)
+# ----------------------------------------------------------------------------- deprecations
+# What 2.0.0 removes, announced here per docs/contract.md's three-step deprecation policy:
+# step 1 (this list, --help text and the CHANGELOG) in a minor, step 2 keeps it working, step 3
+# removes it in the major. `where` says which surface a caller sees it on. docs/contract.md's
+# "What 2.0 changes" section is written from this list.
+DEPRECATED: List[Dict[str, str]] = [
+    {"what": "top-level per-tool keys next to result_v2 in a success document (output, probe, commands, verified, verification and each tool's own keys)",
+     "since": "1.10.0", "replacement": "result_v2 (FFMPEG_SKILL_RESULT_V2=1 today; the only shape in 2.0)",
+     "removed_in": "2.0.0", "where": "json"},
+    {"what": "--crf as an alias of --quality on every re-encoding tool that takes --quality (export.py keeps --crf: its preset chooses the encoder)",
+     "since": "1.10.0", "replacement": "--quality N (same CRF scale, codec-neutral)",
+     "removed_in": "2.0.0", "where": "cli"},
+    {"what": "json and progress in the MCP inputSchema (they are CLI transport flags, not tool arguments)",
+     "since": "1.10.0", "replacement": "nothing: the MCP transport sets them itself (FFMPEG_SKILL_MCP_LEAN=1 drops them today)",
+     "removed_in": "2.0.0", "where": "mcp"},
+    {"what": "probe's hdr meaning BT.2020 primaries or a PQ/HLG transfer",
+     "since": "1.10.0", "replacement": "hdr_signal (true only for PQ / HLG / Dolby Vision); in 2.0 hdr takes that meaning and hdr_format keeps naming the BT.2020 SDR case",
+     "removed_in": "2.0.0", "where": "json"},
+    {"what": "overwriting an existing output without --overwrite (warned, not refused)",
+     "since": "1.10.0", "replacement": "--overwrite, or FFMPEG_SKILL_NO_OVERWRITE=1 to refuse today",
+     "removed_in": "2.0.0", "where": "behaviour"},
+]
+
+
 MCP_JSON_EXEMPT = ("look", "probe")
+# opt-in lean MCP schema (roadmap 1.10.0): json/progress are transport flags the server appends
+# itself, not tool arguments. Off by default so tools/list stays byte-identical to the CLI surface
+# the contract promises; 2.0 drops them unconditionally.
+MCP_LEAN_DROP = ("json", "progress")
 MCP_STRUCTURED_NOTE = ("Structured arguments: keys are the input_schema property names (argparse dests), positionals "
                        "are passed by name, output -> -o. Or argv: the raw CLI list (non-canonical; all other keys are then ignored). "
                        "Media paths must be absolute.")
@@ -997,6 +1028,13 @@ def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:
     one_of = [[{"required": [d]} for d in group] for group in src.get("one_of_required", [])]
     if one_of:
         structured["anyOf"] = one_of[0] if len(one_of) == 1 else [{"allOf": [{"anyOf": g} for g in one_of]}]
+    if os.environ.get("FFMPEG_SKILL_MCP_LEAN", "") not in ("", "0"):
+        for dest in MCP_LEAN_DROP:
+            props.pop(dest, None)
+        if structured.get("required"):
+            structured["required"] = [d for d in structured["required"] if d not in MCP_LEAN_DROP]
+            if not structured["required"]:
+                del structured["required"]
     schema: Dict[str, Any] = {"type": "object", "properties": props, "additionalProperties": False}
     if structured:
         schema["anyOf"] = [{"required": ["argv"]}, structured]
@@ -1023,6 +1061,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
                      "unknown": d["unknown"], "detection": d["detection"], "detected_by": "doctor"})
     return {
         "contract_version": CONTRACT_VERSION,
+        "deprecated": [dict(d) for d in DEPRECATED],
         "skill": {
             "id": SKILL_ID,
             "version": version,

package/scripts/batch.py

@@ -83,6 +83,9 @@ def run_step(argv: List[str]) -> bool:
     if proc.returncode != 0:
         info("    " + "\n    ".join(proc.stderr.strip().splitlines()[-4:]))
         return False
+    for line in proc.stderr.splitlines():
+        if line.startswith("warning:"):  # a step's deprecation notice is not swallowed by a success (review 9)
+            info("    " + line)
     return True
 
 

package/scripts/render.py

@@ -49,6 +49,7 @@ Examples:
   python3 render.py project.json --fast          # preview quality
 """
 import argparse
+import difflib
 import re
 import json
 import os
@@ -79,6 +80,58 @@ TEMPLATE = {
 }
 
 
+# Every key render.py reads, per object. Anything else is a refusal rather than a silent no-op:
+# a clip "start"/"end" (the spelling titles, graphics and overlays use) rendered the whole clip
+# untrimmed, and a mistyped stage name dropped the stage -- both reported as a success (review 9).
+OBJECT_KEYS: Dict[str, frozenset] = {
+    "project": frozenset({"output", "frame", "clips", "transition", "silence", "brand", "captions",
+                          "graphics", "overlays", "audio", "loudness", "fit", "export", "check"}),
+    "clips[]": frozenset({"src", "in", "out", "speed"}),
+    "frame": frozenset({"aspect", "width", "height", "fps"}),
+    "transition": frozenset({"type", "duration"}),
+    "silence": frozenset({"threshold", "min_silence", "margin"}),
+    "captions": frozenset({"text", "srt", "ass", "font", "size", "color", "position", "margin",
+                           "animate", "highlight_color", "outline", "karaoke", "bold", "box"}),
+    "graphics[]": frozenset({"template", "name", "title", "subtitle", "start", "end", "position",
+                             "from", "scale", "primary", "text_color"}),
+    "overlays[]": frozenset({"logo", "image", "text", "position", "start", "end", "fade", "opacity",
+                             "scale", "font_size", "font", "font_file", "margin", "box"}),
+    "audio": frozenset({"music", "replace", "music_volume", "fade_in", "fade_out", "music_fade_out",
+                        "gain", "duck_amount", "voice", "denoise", "duck", "music_loop", "stereo",
+                        "mono", "downmix"}),
+    "loudness": frozenset({"lufs", "tp"}),
+    "fit": frozenset({"duration", "method", "aspect", "fit", "width", "height", "fps", "smooth"}),
+    "export": frozenset({"preset", "fit", "crf", "normalize"}),
+    "check": frozenset({"platform"}),
+}
+# Typos difflib cannot see: a clip is trimmed with in/out, not the start/end that time a title.
+NEAR_KEYS: Dict[str, Dict[str, str]] = {"clips[]": {"start": "in", "end": "out", "from": "in", "to": "out"}}
+
+
+def check_keys(obj: Any, schema: str, label: str) -> None:
+    """Refuse an unrecognised key, naming the object, the key and the nearest valid one."""
+    if not isinstance(obj, dict):
+        return
+    valid = OBJECT_KEYS[schema]
+    for key in obj:
+        if key in valid:
+            continue
+        near = NEAR_KEYS.get(schema, {}).get(str(key)) or next(iter(difflib.get_close_matches(str(key), sorted(valid), n=1, cutoff=0.6)), None)
+        die(f"{label}: unknown key {key!r}" + (f" (did you mean {near!r}?)" if near
+            else f" (valid keys: {', '.join(sorted(valid))})"))
+
+
+def validate_project(proj: Dict[str, Any]) -> None:
+    check_keys(proj, "project", "project")
+    for name in ("frame", "transition", "silence", "captions", "audio", "loudness", "fit", "export", "check"):
+        check_keys(proj.get(name), name, name)
+    for name in ("clips", "graphics", "overlays"):
+        items = proj.get(name)
+        if isinstance(items, list):
+            for i, item in enumerate(items):
+                check_keys(item, f"{name}[]", f"{name}[{i}]")
+
+
 def sh(script: str, *argv: Any, extra: List[str] = None) -> str:
     """Run a sibling script, forwarding --fast / --dry-run, returning its printed output path."""
     cmd = [str(HERE / script)] + [str(a) for a in argv] + (extra or []) + child_args() + ["--json"]
@@ -226,6 +279,7 @@ def main() -> int:
         die(f"{args.project}: not a project or plan object (top level is {type(proj).__name__})")
     if "plan_version" in proj:
         return execute_plan(proj, os.path.abspath(args.project))
+    validate_project(proj)
     base = Path(args.project).resolve().parent
 
     def rel(p: Any) -> str: