ffmpeg-skill 3.8.7 → 3.8.8

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 (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.7`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.8`) | 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`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.7", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.8", "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.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -726,7 +726,8 @@ Per-tool keys added in 1.17, all additive:
 | `filler`, `removed_seconds_total` | `silence.py --filler` | `{lang, source, engine, words, removed, removed_count, removed_seconds, removed_words, word_timings, list, warnings}`. The existing `removed_seconds` is unchanged in name and meaning — the seconds of *silence* removed, which is what it has always held — and `removed_seconds_total` is the additive sibling covering silence plus filler |
 | `jobs`, `jobs_requested`, `wall_seconds`, `item_seconds_total`, `timed_out` | `batch.py` | the parallelism actually applied and the number asked for, the batch's wall clock, the sum of the per-item times (so the speed-up can be quoted), and whether the shared timeout budget ran out. A timed-out item carries `"skipped": "timeout"` in its result row |
 | `timeline` | `render.py --export-timeline FILE` | `{format, rate, duration, frames, clips, transition, transition_frames, music, markers, notes, not_exported}`: the written timeline's own numbers (`rate` is exact, `"30000/1001"` for 29.97) and what the project asked for that an editor timeline cannot carry. Nothing is encoded (`commands: []`); `verified` means the file was written and reads back as its format (`verification` step `parse`) -- not that an editor opened it |
-| `cache` | `render.py --cache` | `{dir, ffmpeg, hits, misses, miss_reasons, saved_seconds, entries}`, plus `would_hit` under `--dry-run`. `miss_reasons` (unreleased, additive): `[{stage, reason, ...}]`, `reason` one of `not_cached`, `sidecar_missing`, `artifact_missing`, `sidecar_corrupt`, `artifact_truncated`, `no_output_path`. The ffmpeg build banner, the skill version, the contract version, the forwarded flags (`--fast`, `--codec`, …), the GPU setting (`FFMPEG_SKILL_HW` and whether `--hw`/`--no-hw` made it explicit) and the output's extension are all part of every key, so a cache is never reused across any of them — a `--fast` draft is never served to a run that did not ask for one |
+| `templates` | `render.py --list-templates --json` | one row per shipped template: `{template, destination, frame: {width, height} or null for an audio destination, fit, max_duration, lufs, safe: {top, bottom, left, right}}` (unreleased: before, the table was printed under `--json` too). `render.py --init FILE --json` prints the plain success document with `output` the file it wrote |
+| `cache` | `render.py --cache` | `{dir, ffmpeg, hits, misses, miss_reasons, saved_seconds, entries}`, plus `would_hit` under `--dry-run`. `miss_reasons` (unreleased, additive): `[{stage, reason, ...}]`, `reason` one of `not_cached`, `sidecar_missing`, `artifact_missing`, `sidecar_corrupt`, `artifact_truncated`, `no_output_path`, `destination_not_owned` (a file already at the stage's path in `--work` is not one this render wrote). The ffmpeg build banner, the skill version, the contract version, the forwarded flags (`--fast`, `--codec`, …), the GPU setting (`FFMPEG_SKILL_HW` and whether `--hw`/`--no-hw` made it explicit) and the output's extension are all part of every key, so a cache is never reused across any of them — a `--fast` draft is never served to a run that did not ask for one |
 | `intermediate_preset` | `render.py` | The x264/x265 preset the stages before an encoding export ran at: `--intermediate-preset`, default `superfast` since 2.16 (`veryfast` in 2.15). `null` when no stage received it: no encoding export was reached, `--fast`, `--stop-after` before the export, a `copy` export, or nothing but the export encoded. Present on every render result, early stops included |
 
 Per-tool keys added in 1.17.1, all additive:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.7",
+  "version": "3.8.8",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "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": [

package/references/scripts.md

@@ -977,8 +977,9 @@ rows, youtube's spec assumed, as `check.py --content` without `--platform`); und
 
 `"export": {"preset": "reels", "normalize": true}` forwards `export.py --normalize`
 so the rendered file meets the platform's loudness without a separate pass. Since
-1.9.0 it is on by default when the preset is a platform (`youtube|youtube4k|reels|x`)
-and the project has no `loudness` stage; `"normalize": false` opts out.
+1.9.0 it is on by default when the preset is a platform's (`youtube`, `youtube4k`,
+`youtube-hdr`, `youtube-av1`, `reels`, `tiktok`, `shorts`, `x`, `linkedin`, `facebook`:
+`export.PLATFORM_OF`) and the project has no `loudness` stage; `"normalize": false` opts out.
 
 `"audio": {"stems": {"dialogue": -2, "music": -18, "effects": -24}}` names one
 level per element of the mix: `dialogue` is the main track's gain, `music` the
@@ -1015,7 +1016,29 @@ relative to the project file; `--export-timeline` lists the layer under
 before `check`, so the markers are in the file that ships (streams copied). The
 entries and the file path are validated before the first stage runs, and the
 stage plans its `metadata.py` command under `--dry-run`/`--plan` like every
-other stage, so the plan lists `chapters` and the run does the same work.
+other stage, so the plan lists `chapters` and the run does the same work. An
+inline title is one line: a line feed, carriage return or NUL in it is refused
+(`kind: input`), since the chapters file holds one `TIME TITLE` line per chapter
+and FFmpeg ends a title at NUL. Under `--dry-run` the list is written to a
+temporary file, not into the work directory.
+
+**`--stop-after export`** stops once the delivery is written: the chapters and
+check stages do not run (and their sections are not read). **Without an export
+stage** the delivery is the last stage's file copied as it is (`.mp4`, or the
+audio container of an audio-only output), so an output named for another
+container (`.webm`, `.mkv`) is refused, `kind: input`, before the first stage
+when the copy is certainly an intermediate and at the copy otherwise (a single
+uncut clip that no stage touches is its source, copied as it is); `.mov`,
+`.m4v`, `.m4a` and `.3gp` are the MP4 family and are accepted.
+
+**The work directory.** Without `--work`, each run makes a new
+`<output>_work_<pid>_<random>/` beside the output and removes it at exit (kept
+with `--keep`, or by a `--stop-after` preview whose output is in it). `--work
+DIR` is used as given and never emptied; a stage file an earlier render wrote
+there, still unchanged (size, mtime, inode: `DIR/.ffskill-render-stages.json`
+records them), is replaced without `--overwrite`, while any other existing file
+is refused as before. A `--dry-run` writes nothing there and removes a `--work`
+directory it had to create.
 
 **`--cache DIR` (1.17)** reuses the artifact of a stage that already ran with
 exactly the same arguments and the same inputs. Opt-in only: **there is no
@@ -1023,7 +1046,8 @@ default cache directory** — one appearing on someone's disk unasked would
 contradict this tool's "a plan leaves nothing behind" posture. The key is a
 sha1 over the stage name, the tool, its arguments (every existing path replaced
 by its content hash), the input hashes, the **forwarded** flags (`--fast`,
-`--overwrite`, `--timeout`, `--codec`), the output's extension, and **the ffmpeg
+`--overwrite`, `--timeout`; render.py has no `--codec`), the GPU setting (`--hw`/`--no-hw`,
+`FFMPEG_SKILL_HW`), the output's extension, and **the ffmpeg
 build banner, the skill version and the contract version**. `--fast` matters as
 much as any of them: it rewrites every child's preset to `veryfast`, so without
 it in the key a `--cache --fast` draft would be served back to a later run that
@@ -1037,8 +1061,10 @@ hardlinks the artifact into the work directory, or copies it where the
 filesystem will not link — never moves it, since the cache has to outlive the
 run's own cleanup. A miss is work to do, not an error, but never a silent one:
 `cache.miss_reasons` says why each stage missed (`not_cached`, `sidecar_missing`,
-`artifact_missing`, `sidecar_corrupt`, `artifact_truncated`, `no_output_path`), and a
-damaged entry (the last two of those that name a file this tool wrote) is also a
+`artifact_missing`, `sidecar_corrupt`, `artifact_truncated`, `no_output_path`, and
+`destination_not_owned` when the file already at a stage's path in `--work` is not one this
+render wrote: the stage runs and refuses it by its own overwrite rule), and a
+damaged entry (`sidecar_corrupt`, `artifact_truncated`) is also a
 `cache_entry_damaged` warning and a line in `DIR/.ffskill-audit.jsonl`. A sidecar keeps
 the stage's `verified`, `verification`, `notes` and `diagnostics`, and a hit replays
 them, so a cached stage counts toward the render's `verified` as a live one does. A
@@ -1046,7 +1072,14 @@ store that fails is a `cache_store_failed` warning (the run is unaffected).
 
 A stage whose flags changed misses the cache, so editing the captions block (for
 example to `"fit_size": "off"`) re-runs captions and everything after it and
-serves the earlier stages from the cache.
+serves the earlier stages from the cache. A file is keyed by its name, size,
+modification time (in nanoseconds; in whole seconds up to 3.8.4) and
+first and last MiB, the batch cache's key (`batch.file_key()`); a file whose
+mtime was set back to the old value keeps its key. The chapters file an inline
+`chapters` list is written to is new every run, so it is keyed by its content
+instead, and the chapters stage hits when the delivery under it is the cached
+one (an export served from the cache; a delivery copied without an export stage
+is a new file, and misses).
 
 `stages_done` is unchanged: a cached stage is still a stage that happened.
 Nothing is written under `--dry-run`, which instead reports `cache.would_hit`.
@@ -1086,7 +1119,10 @@ no overlay stage at all, not an overlay of nothing. The filled project then rend
 normal stages, so `--dry-run --json`, `--stop-after` and the work directory behave as always. An
 unknown name is refused (`kind: input`) with the list. Output defaults to
 `<input>_<template>.mp4` **next to the input** (`.m4a` for an audio-only destination such as
-`podcast`) — the same rule for one template and for a pack, whose `-o` names the directory.
+`podcast`) — the same rule for one template and for a pack. A pack writes each destination as
+`<input>_<template>.<ext>` and the table as `<input>_pack.md` in the **directory of** `-o`:
+`-o packs/talk.mp4` writes into `packs/`, and `-o packs` into the folder that holds `packs`
+(the file name in `-o` is not used).
 Alias spellings are accepted everywhere one name is: `youtube-shorts`/`yt-shorts` = `shorts`,
 `yt` = `youtube`, `instagram`/`ig` = `reels`, `twitter` = `x`, `fb` = `facebook`
 (`check.py --platform`, `export.py --preset`, `caption.py`/`graphics.py`/`overlay.py
@@ -1137,7 +1173,8 @@ whose destinations did not all pass exits non-zero with the per-destination rows
 
 `audiogram` (1.16) is the one-call form of the podcast-to-video job: an `audiogram` stage runs
 **first** (it makes the picture the rest of the chain works on, through `waveform.py --image`),
-then captions, loudness, export and check. It needs `--image` (a local file) or a `background`
+then captions, a `--title` lower third (graphics, as the youtube template draws it), loudness,
+export and check, with `--brand` reaching the audiogram, caption and graphics stages. It needs `--image` (a local file) or a `background`
 colour in the project — this skill fetches nothing and invents no cover art; `--template
 audiogram` without `--image` is refused before anything runs, and a project with an `audiogram`
 and more than one clip is refused (it is drawn from one audio source) — and it is
@@ -1331,8 +1368,18 @@ batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--jobs N|auto]
 ```
 `batch.json` holds either `steps` (a list of script argv with `{in}`/`{out}`
 placeholders, chained) or `project` (a render project applied per file).
-Outputs land in `output_dir` with `suffix`; a content-hash cache skips files
-already done with the same recipe. Use `--dry-run` to preview the plan. The recipe's
+Outputs land in `output_dir` with `suffix`, named with the source's extension
+unless the recipe sets `ext` -- except a `.webm` source, whose output is `.mp4`
+(the steps re-encode to H.264/AAC, which WebM cannot hold; a recipe that keeps
+WebM sets `"ext": "webm"`). `glob` matches names without regard to case on every
+platform (`"*.mp4"` finds `GOPR0001.MP4`; the letters inside a `[...]` class keep
+theirs), and a glob that matches nothing is a note. A cache skips files already
+done with the same recipe: an item's key is its source's `file_key()` (name,
+size, mtime in nanoseconds, first and last MiB), the recipe, the GPU setting,
+the files the steps name and, for a project recipe, the project file and every
+file it names (music, cues, brand and its logo and font, overlays, chapters,
+the clips other than the one each item replaces), read again on every
+`--watch` pass. Use `--dry-run` to preview the plan. The recipe's
 keys are `glob`, `steps`, `project`, `clip_key`, `output_dir`, `suffix` and `ext`; any
 other key is refused before an item runs, with the nearest valid name when one is close, else
 with the list of valid keys.

package/scripts/_common/runner.py

@@ -2692,10 +2692,23 @@ def parse_json(text: str) -> Any:
         if isinstance(value, (dict, list)):
             if depth > JSON_MAX_DEPTH:
                 raise JsonTooDeep(f"nested more than {JSON_MAX_DEPTH} levels deep")
+            if isinstance(value, dict):
+                stack.extend((k, depth) for k in value)
             stack.extend((v, depth + 1) for v in (value.values() if isinstance(value, dict) else value))
+        elif isinstance(value, str) and _SURROGATE.search(value):
+            # A264: "\ud83d" alone is valid JSON and no text: json reads it as a lone surrogate,
+            # which no UTF-8 file, argument or stdout can encode -- the run died on the first write
+            # with a UnicodeEncodeError traceback and nothing on stdout
+            bad = _SURROGATE.search(value).group(0)
+            raise ValueError(f"the string \"{value[:60].encode('ascii', 'backslashreplace').decode()}\" holds \\u{ord(bad):04x}, "
+                             "half of a UTF-16 surrogate pair with no other half: it is no character, so no file can "
+                             "hold it -- write the character itself, or both halves of its \\u escape")
     return data
 
 
+_SURROGATE = re.compile("[\ud800-\udfff]")
+
+
 def read_json(path: "os.PathLike[str] | str") -> Any:
     """parse_json() of a UTF-8 file. Raises OSError for a file that cannot be read and ValueError
     (UnicodeDecodeError is one) for anything else, so `except (OSError, ValueError)` covers it."""

package/scripts/_common/timeline.py

@@ -142,11 +142,15 @@ def start_tc_frames(tc: Dict[str, Any], rate: Fraction) -> int:
 
 def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
     """`frames` as hh:mm:ss:ff at the nominal integer rate; drop-frame (`;`) for an NTSC source
-    whose own timecode is drop-frame, so the label is the one the media itself shows."""
+    whose own timecode is drop-frame, so the label is the one the media itself shows. Timecode
+    wraps at 24 hours as the media's own does (output_timecode_args() counts the same day): a
+    source starting at 23:59:50:00 is labelled 00:00:00:00 ten seconds in, not 24:00:00:00, which
+    no editor reads (A266)."""
     nominal = int(round(float(rate)))
     if not _drop_frame(drop, rate):
-        return _tc(frames, nominal)
+        return _tc(frames % (nominal * 86400), nominal) if nominal >= 1 else _tc(frames, nominal)
     d = nominal // 15
+    frames %= (nominal * 600 - d * 9) * 144
     per_10, per_min = nominal * 600 - d * 9, nominal * 60 - d
     tens, rem = divmod(frames, per_10)
     frames += d * 9 * tens + (d * ((rem - d) // per_min) if rem > d else 0)
@@ -376,6 +380,19 @@ def _tc(frames: int, fps_int: int) -> str:
     return f"{h:02d}:{m:02d}:{s:02d}:{f:02d}"
 
 
+# CMX 3600 numbers events in a three-digit field, and record timecode runs from 01:00:00:00 within
+# one 24-hour day.
+EDL_MAX_EVENTS = 999
+
+
+def _edl_text(value: Any) -> str:
+    """Caller text (a file name, a clip or chapter name, the title) on one EDL line. The format is
+    one statement per line with no escape, so a line break -- any str.splitlines() boundary -- or
+    another control character in a name added lines, or whole events, that parse_error() then
+    accepted (A261). Each becomes a space."""
+    return "".join(" " if (ch in "\x85\u2028\u2029" or ord(ch) < 32 or ord(ch) == 127) else ch for ch in str(value))
+
+
 def to_edl(tl: Dict[str, Any]) -> str:
     """CMX 3600, non-drop timecode at the nominal integer rate, record starting at 01:00:00:00.
     Every event is reel AX (the convention for file-based media) with the file named in
@@ -386,16 +403,24 @@ def to_edl(tl: Dict[str, Any]) -> str:
     from where the previous one stopped to where the next dissolve begins."""
     fps_int = int(round(float(tl["rate"])))
     hour = fps_int * 3600
+    rate = tl["rate"]
     clips = tl["clips"]
     d = tl["transition_frames"]
     # record range of each event: starts `trim_head` before its visible start (the dissolve
     # window), ends where the next event starts
     starts = [c["record_in"] - c["trim_head"] for c in clips]
     ends = starts[1:] + [tl["total"]]
-    lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
+    events = len(clips) + (1 if tl["music"] else 0)
+    if events > EDL_MAX_EVENTS:
+        # A265: f"{n:03d}" wrote event 1000 as four digits, outside the field
+        raise TimelineError(f"an EDL numbers its events in three digits (at most {EDL_MAX_EVENTS}); this timeline has "
+                            f"{events} -- export .fcpxml or .otio, or split the project")
+    if hour + tl["total"] > fps_int * 86400:
+        raise TimelineError(f"the timeline ({float(Fraction(tl['total']) / rate):.0f}s) runs past 24:00:00:00 when the "
+                            "EDL's record starts at 01:00:00:00 -- export .fcpxml or .otio, or split the project")
+    lines = [f"TITLE: {_edl_text(tl['name'])}", "FCM: NON-DROP FRAME", ""]
     n = 0
     prev_src_end = ""
-    rate = tl["rate"]
 
     def src_tc(c: Dict[str, Any], seq_frames: int) -> str:
         """The source timecode `seq_frames` (sequence frames of source media) after the clip's in
@@ -415,13 +440,13 @@ def to_edl(tl: Dict[str, Any]) -> str:
                          f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
             lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
-            lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
-            lines.append(f"* TO CLIP NAME: {c['name']}")
+            lines.append(f"* FROM CLIP NAME: {_edl_text(clips[i - 1]['name'])}")
+            lines.append(f"* TO CLIP NAME: {_edl_text(c['name'])}")
         else:
             lines.append(f"{n:03d}  AX       {chan:<5} C        {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
-            lines.append(f"* FROM CLIP NAME: {c['name']}")
-        lines.append(f"* SOURCE FILE: {c['src']}")
+            lines.append(f"* FROM CLIP NAME: {_edl_text(c['name'])}")
+        lines.append(f"* SOURCE FILE: {_edl_text(c['src'])}")
         if abs(c["speed"] - 1.0) > 1e-6:
             # the speed in source frames per second, at the rate the source labels are counted in
             own_fps = int(round(float(c.get("rate") or rate)))
@@ -433,11 +458,11 @@ def to_edl(tl: Dict[str, Any]) -> str:
         m = tl["music"]
         lines.append(f"{n:03d}  AX       A2    C        {_tc(0, fps_int)} {_tc(m['length'], fps_int)} "
                      f"{_tc(hour, fps_int)} {_tc(hour + m['length'], fps_int)}")
-        lines.append(f"* FROM CLIP NAME: {m['name']}")
-        lines.append(f"* SOURCE FILE: {m['src']}")
+        lines.append(f"* FROM CLIP NAME: {_edl_text(m['name'])}")
+        lines.append(f"* SOURCE FILE: {_edl_text(m['src'])}")
         lines.append("")
     for mk in tl["markers"]:
-        lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE   {mk['title']}")
+        lines.append(f"* LOC: {_tc(hour + mk['at'], fps_int)} WHITE   {_edl_text(mk['title'])}")
     return "\n".join(lines).rstrip("\n") + "\n"
 
 
@@ -459,6 +484,14 @@ def _url(path: str) -> str:
     return Path(os.path.abspath(path)).as_uri()
 
 
+def _xml_text(value: Any) -> str:
+    """Caller text as XML 1.0 can hold it: a control character other than tab, line feed and
+    carriage return (and U+FFFE/U+FFFF) has no representation at all, not even escaped, so a clip
+    or chapter name carrying one made the FCPXML not well-formed (the sibling of A261). Each
+    becomes a space."""
+    return "".join(" " if ((ord(ch) < 32 and ch not in "\t\n\r") or ch in "\ufffe\uffff") else ch for ch in str(value))
+
+
 def to_fcpxml(tl: Dict[str, Any]) -> str:
     """FCPXML 1.10 (Final Cut Pro 10.6+, DaVinci Resolve): one library/event/project, a spine of
     asset-clips with cross dissolves between them, the music bed as a connected clip on lane -1
@@ -466,7 +499,7 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
     sequence has its own format (r1); each video asset has its source's, and a clip of another
     aspect states its spatial conform (adjust-conform) for frame.fit."""
     rate = tl["rate"]
-    q = lambda s: _xml_escape(str(s), {'"': "&quot;"})  # noqa: E731
+    q = lambda s: _xml_escape(_xml_text(s), {'"': "&quot;"})  # noqa: E731
     fd = _t(1, rate)
     res: List[str] = []
     ids: Dict[Any, str] = {}  # a format's (width, height, frameDuration) or an asset's path -> its id

package/scripts/_contract.py

@@ -751,7 +751,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "guides": {"type": "array", "description": "--guides only: each outline drawn on the PNG, {guide: action|title, fraction (0.93 / 0.90 of the frame, SMPTE ST 2046-1), of: frame} or {guide: 4:3, window, action: 0.90, title: 0.80}; drawn on the preview only"}}
     elif name == "render":
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"], "description": "check.py's document for a \"check\" stage with a platform, \"content\": true, or both; when check.py printed none, a failure document with error.reason check_output_unparsed"},
-                 "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
+                 "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path|destination_not_owned, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
                  "caption": {"type": ["object", "null"], "description": "the caption stage's own block, forwarded verbatim from caption.py (cue-layout counts and fit-size keys); null without a caption stage"},
                  "snap": {"type": ["object", "null"], "description": "a project's \"snap\": cut.py's snap block for the first snapped clip, with every clip's in clips; null when nothing was snapped"},
                  "intermediate_preset": {"type": ["string", "null"], "description": "2.15: the x264/x265 preset the stages before an encoding export ran at (--intermediate-preset, default superfast since 2.16); null when no stage received it (no encoding export reached, --fast, --stop-after before the export, a copy export, or nothing but the export encoded)"},
@@ -763,7 +763,10 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"},
                  "timeline": {"type": "object", "description": "--export-timeline: format, rate, duration, frames, clips, transition, "
                               "transition_frames, music, markers, notes, and not_exported (what the project asks for that an "
-                              "editor timeline cannot carry)"}}
+                              "editor timeline cannot carry)"},
+                 "templates": {"type": "array", "description": "--list-templates --json: one row per shipped template, {template, "
+                               "destination, frame: {width, height} or null (audio), fit, max_duration, lufs, safe: {top, bottom, "
+                               "left, right}}; without --json the same rows are a table"}}
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]},
                  "files": {"type": "array", "description": "one entry per file: {file, probe, steps, skipped}. A step is {step, ok, seconds, error (one line, for the table)}, plus the tool's verified when it completed, and on a failure its own kind, reason, message, details and exit_code (reason step_timeout or step_output_unparsed when the tool printed no failure document); skipped lists the steps that do not apply as {step, reason: quick|no_video|no_audio|not_hdr|not_multichannel|input_unreadable, message}"},

package/scripts/batch.py

@@ -37,7 +37,8 @@ from _common import STATE, add_common, apply_common, child_args, die, emit, info
 from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
                             owned_identity, stop_children)
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
-from _common.decision import rebase_project_paths
+from _common.decision import NO_DEFAULT_ENCODE_EXT, rebase_project_paths
+from _common.runner import parse_json
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}  # one list (_common); a batch walks media, not stills
@@ -51,9 +52,16 @@ ALLOWED_STEP_SCRIPTS = {p.name for p in HERE.glob("*.py") if not p.name.startswi
 
 
 def file_key(path: Path) -> str:
+    """A cheap change detector: the name, the size, the modification time in nanoseconds and the
+    first and last MiB. A rewrite of the middle of a file keeps its size and its ends, so the
+    modification time is what tells it apart: in whole seconds (up to 3.8.4) two writes within
+    one second shared a key, and the old output was served as cached. A file whose mtime is reset
+    to the earlier value (``touch -r``, a copy that preserves it) or a filesystem that keeps
+    whole seconds (FAT keeps two) still shares one; hashing every byte would cost a read of the
+    whole file per item per run (docs/design-decisions.md, "After 3.8.4")."""
     st = path.stat()
     h = hashlib.sha1(usedforsecurity=False)  # a change detector, not a secret
-    h.update(f"{path.name}|{st.st_size}|{int(st.st_mtime)}".encode())
+    h.update(f"{path.name}|{st.st_size}|{st.st_mtime_ns}".encode())
     with open(path, "rb") as fh:  # first and last MB: cheap and good enough to detect changes
         h.update(fh.read(1 << 20))
         if st.st_size > 2 << 20:
@@ -86,6 +94,30 @@ def side_inputs_key(recipe: Dict[str, Any]) -> str:
     return h.hexdigest()[:8]
 
 
+def caseless_glob(pattern: str) -> str:
+    """`pattern` with every letter outside a [...] class matched in either case: "*.mp4" finds
+    GOPR0001.MP4, as it already did on macOS's and Windows' default filesystems, so a recipe means
+    the same files on every platform (A82: on Linux a camera folder was an empty batch). pathlib's
+    case_sensitive= needs Python 3.12; 3.10 is the floor."""
+    out: List[str] = []
+    in_class = False
+    first = -1  # index of the class's first member: a "]" there is a member, not the end ("[]a]", "[!]a]")
+    for i, ch in enumerate(pattern):
+        if in_class:
+            out.append(ch)
+            if ch == "]" and i > first:
+                in_class = False
+        elif ch == "[":
+            first = i + 2 if pattern[i + 1:i + 2] == "!" else i + 1
+            in_class = "]" in pattern[first + 1:]  # an unclosed [ ("[!]x") is a literal character to fnmatch
+            out.append(ch if in_class else "[[]")
+        elif ch.isalpha() and ch.lower() != ch.upper():
+            out.append(f"[{ch.lower()}{ch.upper()}]")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
 def recipe_key(recipe: Dict[str, Any]) -> str:
     # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
     # (export preset, captions, everything) live in the file at that path, not in this dict.
@@ -93,18 +125,57 @@ def recipe_key(recipe: Dict[str, Any]) -> str:
     # itself) left the key, and so every cache hit, unchanged: a preset swapped from "copy" to
     # "x" (a real re-encode) still served the old cached output. Fold the referenced file's own
     # content into the key so a content change invalidates the cache like any other edit would.
+    # main() calls this on every pass, so a --watch loop sees an edit made while it runs (A81).
     project_content = ""
     if recipe.get("project"):
         try:
             project_content = Path(recipe["project"]).read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError) as exc:
             # keyed on the recipe alone: an unreadable project cannot invalidate the cache by its
-            # content, so say so (each item that needs it then fails on reading it)
-            warn(f"recipe.project {recipe['project']} could not be read ({exc}); the cache key covers the recipe only",
-                 "recipe_project_unreadable", path=str(recipe["project"]), error=str(exc))
+            # content, so say so (each item that needs it then fails on reading it); once per run
+            entry = {"code": "recipe_project_unreadable", "path": str(recipe["project"])}
+            if not any(all(w.get(k) == v for k, v in entry.items()) for w in STATE.warnings if isinstance(w, dict)):
+                warn(f"recipe.project {recipe['project']} could not be read ({exc}); the cache key covers the recipe only",
+                     "recipe_project_unreadable", path=str(recipe["project"]), error=str(exc))
+        else:
+            project_content += "\0" + project_files_key(recipe, project_content)
     return hashlib.sha1((json.dumps(recipe, sort_keys=True) + "\0" + project_content).encode(), usedforsecurity=False).hexdigest()[:12]
 
 
+def project_files_key(recipe: Dict[str, Any], text: str) -> str:
+    """The files a project recipe's project names (music, cues, the brand and its logo and font,
+    overlay images and videos, the chapters file, every clip but the one each item replaces),
+    each keyed by its own content as file_key() keys a source (A80): an edited cue file or music
+    bed changes the output, so it has to change the key. The list is render.py's own
+    project_input_files(), read against the project file's directory as render reads it. A
+    project that does not parse adds nothing: each item then fails reading it."""
+    try:
+        proj = parse_json(text)
+    except ValueError:
+        return ""
+    if not isinstance(proj, dict):
+        return ""
+    from render import project_input_files  # here, not at the top: render.py imports this module
+    base = Path(str(recipe["project"])).resolve().parent
+    clips = proj.get("clips")
+    idx = int(recipe.get("clip_key") or 0)  # check_recipe_types() has refused anything else
+    if isinstance(clips, list) and idx < len(clips) and isinstance(clips[idx], dict):
+        # the clip every item replaces with itself: its placeholder is no input of any item
+        proj = dict(proj, clips=[dict(c, src=None) if i == idx else c for i, c in enumerate(clips)])
+
+    def rel(p: Any) -> str:
+        return str(p) if os.path.isabs(str(p)) else str(base / str(p))
+    h = hashlib.sha1(usedforsecurity=False)
+    for name in sorted(set(project_input_files(proj, rel))):
+        path = Path(name)
+        try:
+            ident = file_key(path) if path.is_file() else "-"
+        except OSError:
+            ident = "-"
+        h.update(f"{name}\0{ident}\0".encode())
+    return h.hexdigest()
+
+
 def gpu_key() -> str:
     """The GPU setting the steps resolve, as a suffix for the item cache key: a VideoToolbox file is
     not the CPU's bytes, so a --hw output is never served to a --no-hw run or the other way round
@@ -222,6 +293,11 @@ def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
     # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
+    if not recipe.get("ext") and src.suffix.lower() in NO_DEFAULT_ENCODE_EXT:
+        # the #415 default-name rule (default_output()): the steps re-encode to x264/AAC, which a
+        # WebM cannot hold, so every .webm item was refused output_container_codecs (A83). A
+        # recipe that keeps WebM (a stream copy, export.py --preset vp9-alpha) sets "ext".
+        final_ext = "mp4"
     steps = recipe.get("steps") or []
     if not recipe.get("ext") and not recipe.get("project") and steps and not step_writes(steps[-1]) and not writes_nothing(recipe):
         # the last step writes nothing, so what is delivered is an intermediate: its name says its
@@ -649,7 +725,6 @@ def main() -> int:
             audit("batch_cache_reset", {"path": str(cache_path), "size": size, "error": str(exc)},
                   default_path=str(outdir / ".ffskill-audit.jsonl"))
             cache = {}
-    rkey = recipe_key(recipe) + gpu_key()
     glob = recipe.get("glob") or "*"
 
     # --jobs: every item is itself an ffmpeg that already threads across cores, so beyond a few
@@ -706,6 +781,7 @@ def main() -> int:
     # first seen, last modified at least one interval ago; until then its row is
     # skipped: "settling", not cached, and the next pass looks again.
     last_seen: Dict[str, "tuple[int, int]"] = {}
+    shown_empty = {"done": False}
 
     def settle_poll(files: List[Path]) -> "set":
         if not args.watch:
@@ -728,7 +804,12 @@ def main() -> int:
         return unsettled
 
     def one_pass() -> List[Dict[str, Any]]:
-        files = sorted(p for p in folder.glob(glob) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        files = sorted(p for p in folder.glob(caseless_glob(glob)) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        if not files and not shown_empty["done"]:
+            # a batch of nothing completed with total 0 and not a word (A82): say what matched nothing
+            shown_empty["done"] = True
+            note(f"no media file in {folder} matches the recipe's glob {glob!r} (matched without regard to case); "
+                 "nothing was processed")
         # Two different sources can compute the same final path (most often a fixed recipe "ext"
         # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
         # processing anything, rather than letting the later one silently overwrite the earlier
@@ -805,7 +886,9 @@ def main() -> int:
         slots: "List[Optional[Dict[str, Any]]]" = [None] * len(files)
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
-        pass_key = rkey + side_inputs_key(recipe)
+        # read on every pass: a --watch loop serves nothing from an edited project.json, cue file or
+        # music bed (computed once before the loop, it did: A81)
+        pass_key = recipe_key(recipe) + gpu_key() + side_inputs_key(recipe)
         polled = settle_poll(files)
         for i, src in enumerate(files):
             if str(src) in polled:

package/scripts/metadata.py

@@ -52,6 +52,10 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
         # chapter files carry no fps, so hh:mm:ss:ff needs its @fps suffix; time_arg() says so
         start = time_arg(parts[0], f"{path}:{n}")
         title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
+        if "\x00" in title:
+            # FFmpeg ends a metadata value at NUL: "A\x00B" was written as "A", verified (the
+            # sibling of A260 in render.py's inline chapters)
+            die(f"{path}:{n}: the chapter title holds a NUL character, which a chapter title cannot carry; remove it")
         if entries and start <= entries[-1]["start"]:
             die(f"{path}:{n}: chapter at {start:g}s does not come after the previous one at {entries[-1]['start']:g}s")
         if duration and start >= duration:

package/scripts/render.py

@@ -75,7 +75,7 @@ from typing import Any, Dict, List, Optional, Sequence
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
 from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
-from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, read_json, remember_written
+from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, owned_identity, read_json, remember_written
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 from _common.decision import rebase_project_paths
 import subprocess
@@ -304,8 +304,11 @@ def template_output(input_path: str, name: str, dest: str) -> Path:
 
 
 def list_templates() -> None:
-    """The templates, the destination each delivers to, and the zones its UI covers."""
-    print("%-15s %-11s %-5s %7s  %-10s %s" % ("template", "frame", "fit", "max", "loudness", "safe zones (fraction of the frame)"))
+    """The templates, the destination each delivers to, and the zones its UI covers: a table, or
+    under --json one row per template in `templates` (A102: the table was printed under --json)."""
+    rows: List[Dict[str, Any]] = []
+    if not STATE.json:
+        print("%-15s %-11s %-5s %7s  %-10s %s" % ("template", "frame", "fit", "max", "loudness", "safe zones (fraction of the frame)"))
     for name in template_names():
         tpl = load_template(name)
         dest = str((tpl.get("check") or {}).get("platform") or name)
@@ -318,7 +321,13 @@ def list_templates() -> None:
         size = "%dx%d" % (frame["w"], frame["h"]) if frame else "audio"
         fit = str((tpl.get("frame") or {}).get("fit") or "-")
         loud = ("%g LUFS" % spec["lufs"]) if spec.get("lufs") is not None else "-"
-        print("%-15s %-11s %-5s %7s  %-10s %s" % (name, size, fit, ("%gs" % dur) if dur else "-", loud, zones or "none"))
+        rows.append({"template": name, "destination": dest, "frame": {"width": frame["w"], "height": frame["h"]} if frame else None,
+                     "fit": None if fit == "-" else fit, "max_duration": dur, "lufs": spec.get("lufs"),
+                     "safe": {edge: safe.get(edge, 0) for edge in ("top", "bottom", "left", "right")}})
+        if not STATE.json:
+            print("%-15s %-11s %-5s %7s  %-10s %s" % (name, size, fit, ("%gs" % dur) if dur else "-", loud, zones or "none"))
+    if STATE.json:
+        emit(None, templates=rows, stages=[], check=None)
 
 
 # `--template all`: every destination a single edit is normally posted to. The podcast template
@@ -346,6 +355,19 @@ def expand_templates(value: str) -> List[str]:
     return seen
 
 
+def md_line(text: Any) -> str:
+    """Caller text on one Markdown line: each line break (any str.splitlines() boundary) and other
+    control character becomes a space, so a file name cannot start a line of its own (A263)."""
+    return "".join(" " if (ch in "\x85\u2028\u2029" or ord(ch) < 32 or ord(ch) == 127) else ch for ch in str(text))
+
+
+def md_cell(text: Any) -> str:
+    """Caller text in one cell of a GFM table row: on one line (md_line()), a backslash doubled
+    and a '|' escaped as '\\|', so `a | b.mp4` stays in its column. report.py --pack reads the
+    escapes back (A263: the columns shifted and passing destinations were reported failed)."""
+    return md_line(text).replace("\\", "\\\\").replace("|", "\\|")
+
+
 def render_pack(names: List[str], args) -> int:
     """The social pack: one edit delivered to every named destination, plus a table of what
     was written. Each destination is a full render (its own frame, captions, loudness, export
@@ -415,14 +437,14 @@ def render_pack(names: List[str], args) -> int:
             if err.get("kind") in ("timeout", "interrupted"):
                 stopped.append({"kind": err["kind"], "exit_code": child_exit_code(doc, proc.returncode)})
     pack = str(outdir / f"{stem}_pack.md")
-    lines = [f"# Social pack — {stem}", "",
+    lines = [f"# Social pack — {md_line(stem)}", "",
              "| platform | file | size | duration | check |", "|---|---|---|---|---|"]
     for r in rows:
         dur = f"{r['duration']:.2f} s" if r.get("duration") else "-"
         mb = f"{r['size_bytes'] / 1024 / 1024:.1f} MB" if r.get("size_bytes") else "-"
         verdict = r["check"] + (f" (upload-limit guidance: {'; '.join(r['guidance'])})" if r.get("guidance") else "")
-        lines.append(f"| {r['platform']} | {r['file']} | {mb} | {dur} | {verdict} |")
-    lines += ["", f"{len(rows)} destinations from one edit ({os.path.basename(args.input)}).",
+        lines.append("| " + " | ".join(md_cell(c) for c in (r["platform"], r["file"], mb, dur, verdict)) + " |")
+    lines += ["", f"{len(rows)} destinations from one edit ({md_line(os.path.basename(args.input))}).",
               "Rendered by ffmpeg-skill; `report.py --pack` turns this table into an HTML report."]
     if not STATE.dry_run:
         if not outdir.is_dir():
@@ -501,7 +523,8 @@ def project_input_files(proj: Dict[str, Any], rel: Any) -> List[str]:
             if not must_exist or os.path.isfile(p):
                 found.append(p)
 
-    for c in proj.get("clips") or []:
+    clips = proj.get("clips")
+    for c in clips if isinstance(clips, list) else []:  # a wrong type is validate_project()'s to refuse
         if isinstance(c, dict):
             add(c.get("src"))
             if isinstance(c.get("snap"), dict):
@@ -604,6 +627,13 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
                 check_keys(item, "chapters[]", f"chapters[{i}]")
             if not isinstance(item, dict) or item.get("at") is None or not str(item.get("title") or "").strip():
                 die(f'chapters[{i}]: needs {{"at": TIME, "title": STR}}')
+            # the chapters stage writes one `TIME TITLE` line per chapter for metadata.py, which
+            # reads a line break as the end of the chapter (a CR too: the file is read as text) and
+            # FFmpeg ends a title at NUL: "Intro\n0:01 Evil" was two chapters, verified (A260)
+            bad = next((ch for ch in str(item["title"]) if ch in "\n\r\x00"), None)
+            if bad is not None:
+                die(f"chapters[{i}].title: holds U+{ord(bad):04X} ({'NUL' if bad == chr(0) else 'a line break'}), which "
+                    "a chapter title cannot carry -- a title is one line of text; remove it", kind="input")
     for name in ("clips", "graphics", "overlays"):
         items = proj.get(name)
         if name == "clips" or (not timeline and _reaches(READ_AT[name], stop_after)):  # the export reads only the clips
@@ -707,6 +737,7 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
             _LAST_DOC["cached"] = True
             if not STATE.dry_run:
                 remember_written(dest)  # placed by this run, as a stage's own write would be (#415)
+                _record_own_stage_file(dest)
             return dest
         CACHE["misses"].append(stage)
         _refuse_uncached_earlier_stage(stage)
@@ -714,7 +745,12 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
         CACHE["misses"].append(stage)
         _cache_miss(stage, "no_output_path")  # nothing names where the artifact goes, so there is nothing to keep
     started = time.time()
-    cmd = [str(HERE / script)] + [str(a) for a in argv] + (extra or []) + child_args() + ["--json"]
+    # an earlier render's own stage file in this --work (A98): replaced as this run's own would be.
+    # After the cache key, which this does not change.
+    own = ["--overwrite"] if not STATE.overwrite and _earlier_own_stage_file(dest) else []
+    if own:
+        info(f"    {os.path.basename(str(dest))} is an earlier render's own stage file in {_OWN_STAGES['dir']}, unchanged since: replaced")
+    cmd = [str(HERE / script)] + [str(a) for a in argv] + (extra or []) + own + child_args() + ["--json"]
     info("→ " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd[:-1])))
     proc = run_tool(cmd)
     for line in proc.stderr.splitlines():
@@ -754,6 +790,7 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
         # places its tagged copy over the export's delivery, which the output guard would
         # otherwise refuse as an existing file without --overwrite (#415).
         remember_written(out_path, dest)
+        _record_own_stage_file(dest)
     if key:
         cache_store(stage, key, out_path or (dest or ""), time.time() - started, doc)
     return out_path
@@ -808,12 +845,20 @@ def _intermediate_used() -> Optional[str]:
     return INTERMEDIATE["preset"] if INTERMEDIATE["applied"] else None
 
 
+# Small files this run writes itself and hands to a stage (the inline chapters list's chapters.txt):
+# keyed by their whole content, not by file_key()'s mtime, since a new run writes them anew and
+# their stage could never hit the cache (A100).
+CONTENT_KEYED: set = set()
+
+
 def _content_hash(path: str) -> str:
     """The same cheap content fingerprint batch.py caches on: name, size, mtime, first and last
     MB. Reused rather than reinvented so one file has one identity across the skill. A file that
     cannot be read keys as "missing" -- recorded (cache_input_unreadable), since two unreadable
-    files then share that part of the key."""
+    files then share that part of the key. A file in CONTENT_KEYED is keyed by its bytes."""
     try:
+        if os.path.abspath(path) in CONTENT_KEYED:
+            return "content:" + hashlib.sha1(Path(path).read_bytes(), usedforsecurity=False).hexdigest()
         return file_key(Path(path))
     except (OSError, ValueError) as exc:
         entry = {"code": "cache_input_unreadable", "path": str(path)}
@@ -923,6 +968,10 @@ def cache_lookup(stage: str, key: str, dest: str, tool: Optional[str] = None) ->
     if STATE.dry_run:
         CACHE["would_hit"].append(stage)
         return True
+    if Path(dest).exists() and not STATE.overwrite and not _earlier_own_stage_file(dest):
+        # a file in --work that is not this render's own (the caller's, or one they edited): a hit
+        # would unlink it without --overwrite. Run the stage instead, which refuses it by its rule
+        return _cache_miss(stage, "destination_not_owned", key=key, destination=str(dest))
     Path(dest).parent.mkdir(parents=True, exist_ok=True)
     try:
         if Path(dest).exists():
@@ -1034,6 +1083,13 @@ def run_check(output: str, platform: Optional[str], content: bool) -> Dict[str,
                       "message": msg, "exit_code": cp.returncode, "stderr_tail": tail}}
 
 
+def _from_plan_cwd(output: Any) -> Any:
+    """A plan's output as an absolute path. execute_plan() has moved into the plan's cwd, so a
+    relative one named a file there, and the result reported it to a caller in another directory
+    as if it were in theirs (A96)."""
+    return os.path.abspath(str(output)) if isinstance(output, str) and output else output
+
+
 def execute_plan(plan: Dict[str, Any], path: str) -> int:
     """Run a plan written by `<tool> --plan FILE`: refuse if any fingerprinted input changed since
     the plan was made (the plan's commands would then describe a different edit), run the tool
@@ -1093,7 +1149,8 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
             if step.get("tool") == "check" and (step.get("platform") or step.get("content") is True):
                 record_skip("[dry-run] the plan's check step is not run: there is no output to check yet",
                             "check_dry_run", platform=step.get("platform"), content=step.get("content") is True)
-        emit(plan.get("output"), plan=path, plan_sha256=digest, tool=tool, stages=[tool], check=None, unbound_inputs=unbound)
+        emit(_from_plan_cwd(plan.get("output")), plan=path, plan_sha256=digest, tool=tool, stages=[tool], check=None,
+             unbound_inputs=unbound)
         return 0
     info(f"executing plan {path}: {tool} " + " ".join(argv))
     proc = run_tool([str(script)] + argv + child_args() + ["--json"])
@@ -1114,7 +1171,7 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
             code=child_exit_code(doc, proc.returncode), kind=err.get("kind", "ffmpeg"), plan=path, tool=tool,
             error_extra=error_extra, **_stage_failure_hw(doc))
     absorb_stage(tool, doc)  # the tool's GPU facts (fell back and why, ran on VideoToolbox) and diagnostics reach this result
-    output = doc.get("output") or plan.get("output")
+    output = _from_plan_cwd(doc.get("output") or plan.get("output"))
     check_result = None
     exit_code = 0
     for step in plan.get("verify") or []:
@@ -1180,6 +1237,8 @@ def export_timeline(proj: Dict[str, Any], rel, dest: str) -> int:
         paths.append(rel(proj["audio"]["music"]))
     probes: Dict[str, Dict[str, Any]] = {}
     for path in paths:
+        if path in probes:
+            continue  # one ffprobe per file: ten clips of one recording are one probe (A267)
         if not os.path.exists(path):
             die(f"timeline source not found: {path}")
         probes[path] = probe(path)  # a timeline needs real durations and rates, dry run or not
@@ -1197,9 +1256,9 @@ def export_timeline(proj: Dict[str, Any], rel, dest: str) -> int:
         del frame["aspect"]
     try:
         tl = tlmod.build(dict(proj, frame=frame), probes, rel)
+        text = tlmod.WRITERS[fmt](tl)  # a writer refuses what its format cannot hold (EDL: 999 events, 24 h)
     except tlmod.TimelineError as exc:
         die(f"--export-timeline: {exc}", kind="input")
-    text = tlmod.WRITERS[fmt](tl)
     report = tlmod.summary(tl, fmt)
     _check_output_path(["ffmpeg", dest])
     _check_existing_output(["ffmpeg", dest])
@@ -1234,6 +1293,89 @@ def _has_sound(current: str, proj: Dict[str, Any], rel: Any) -> bool:
     return False
 
 
+def cache_report(cache_dir: Optional[str]) -> Optional[Dict[str, Any]]:
+    """The result's `cache` object (None without --cache), with its stderr summary line."""
+    if not cache_dir:
+        return None
+    report = {"dir": CACHE["dir"], "ffmpeg": CACHE["ffmpeg"],
+              "hits": CACHE["hits"], "misses": CACHE["misses"], "miss_reasons": CACHE["miss_reasons"],
+              "saved_seconds": round(CACHE["saved_seconds"], 1),
+              "entries": CACHE["entries"]}
+    if STATE.dry_run:
+        report["would_hit"] = CACHE["would_hit"]
+    info(f"cache: {len(CACHE['hits'])} hit(s) ({', '.join(CACHE['hits']) or '-'}), "
+         f"{len(CACHE['misses'])} miss(es) ({', '.join(CACHE['misses']) or '-'})")
+    return report
+
+
+# One container family: a copy of an MP4 file named .mov (or .m4v, .m4a, .3gp) is the bytes that
+# name says. Every other pair of extensions names two different containers.
+ISO_BMFF_EXT = frozenset({".mp4", ".mov", ".m4v", ".m4a", ".3gp"})
+
+
+def refuse_copied_container(have: str, output: str) -> None:
+    """Refuse delivering a file of container `have` (an extension) by copying it to `output`
+    under another container's name: with no export stage nothing converts it (A84)."""
+    want = Path(output).suffix.lower()
+    if have == want or (have in ISO_BMFF_EXT and want in ISO_BMFF_EXT):
+        return
+    die(f"output {output}: this project has no \"export\" stage, so the delivery is the last stage's "
+        f"{have or 'extension-less'} file copied as it is, which the name {want or '(no extension)'} would mislabel -- "
+        f"name the output {have or 'with that extension'}, or add an \"export\" stage, which writes the container "
+        "its preset names", kind="input", hint=f"\"output\": \"{Path(output).with_suffix(have).name}\"" if have else None)
+
+
+# A98: the stage files a render with an explicit --work wrote there, {real path: owned_identity()},
+# kept in <work>/.ffskill-render-stages.json. A later run with the same --work replaces one of them
+# without --overwrite while it is still that file (the overwrite rule's "this run's own file",
+# extended to an earlier render of the same work directory); one edited, replaced or never
+# written by render is refused as before.
+_OWN_STAGES: Dict[str, Any] = {"dir": None, "files": {}, "manifest": None}
+
+
+def own_stage_files(work: Path, load: bool) -> None:
+    """Start this run's record of its stage files in `work`, reading an earlier render's when
+    `load` (an explicit --work; the default directory is new every run)."""
+    _OWN_STAGES.update(dir=os.path.realpath(str(work)), files={}, manifest=str(work / ".ffskill-render-stages.json") if load else None)
+    if load:
+        try:
+            doc = json.loads(Path(_OWN_STAGES["manifest"]).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            doc = {}
+        files = doc.get("files") if isinstance(doc, dict) else None
+        if isinstance(files, dict):
+            _OWN_STAGES["files"] = {k: v for k, v in files.items() if isinstance(k, str) and isinstance(v, dict)}
+
+
+def _earlier_own_stage_file(dest: Optional[str]) -> bool:
+    """Whether `dest`, a stage's output in the work directory, is a file an earlier render with
+    this --work wrote there and nothing has changed since."""
+    if not dest or not _OWN_STAGES["manifest"] or not os.path.isfile(dest):
+        return False
+    real = os.path.realpath(dest)
+    if os.path.dirname(real) != _OWN_STAGES["dir"]:
+        return False
+    expected = _OWN_STAGES["files"].get(real)
+    return isinstance(expected, dict) and owned_identity(real) == expected
+
+
+def _record_own_stage_file(dest: Optional[str]) -> None:
+    """Remember a stage file this run put in the --work directory, as it is now. A manifest that
+    cannot be written only means the next run refuses that file as before."""
+    if STATE.dry_run or not dest or not _OWN_STAGES["manifest"] or not os.path.isfile(dest):
+        return
+    real = os.path.realpath(dest)
+    if os.path.dirname(real) != _OWN_STAGES["dir"]:
+        return
+    ident = owned_identity(real)
+    if ident:
+        _OWN_STAGES["files"][real] = ident
+        try:
+            Path(_OWN_STAGES["manifest"]).write_text(json.dumps({"files": _OWN_STAGES["files"]}, indent=1), encoding="utf-8")
+        except OSError:
+            pass
+
+
 def guidance_warns(check_doc: Optional[Dict[str, Any]]) -> List[str]:
     """The rows of a check result that are over the platform table's upload limit (#485): WARN,
     `basis: guidance`. The check passes with them, so each place that says a check passed names
@@ -1323,7 +1465,8 @@ def main() -> int:
         guard_sidecar(args.init)
         Path(args.init).write_text(json.dumps(TEMPLATE, indent=2) + "\n", encoding="utf-8")
         info(f"wrote {args.init}; edit clips/src and run: render.py {args.init}")
-        print(args.init)
+        # the path alone, or under --json the document every other mode prints (A102)
+        emit(args.init, stages=[], check=None)
         return 0
     if not args.project:
         die("give a project.json (or --init FILE, or --template NAME INPUT)")
@@ -1425,25 +1568,48 @@ def main() -> int:
     # fit.mp4, ...) mid-run. An explicit --work is left as given (the caller asked for that exact,
     # shared path, e.g. to inspect intermediates across runs); only the auto-derived default is
     # made unique per process, since it's the one that's also auto-deleted at the end.
-    work = Path(args.work) if args.work else Path(f"{Path(output).with_suffix('')}_work_{os.getpid()}")
+    # Intermediates keep the delivery's media kind: a .mp4 project is unchanged (every stage file
+    # is still clipNN.mp4 / fit.mp4 / loudnorm.mp4), while an audio-only delivery (the podcast
+    # template) carries its stages through the audio container instead of a video one.
+    mid = Path(output).suffix.lower() if Path(output).suffix.lower() in AUDIO_EXT else ".mp4"
+    ex_cfg = proj.get("export")
+    if (not args.stop_after or args.stop_after == "export") and not (isinstance(ex_cfg, dict) and ex_cfg.get("preset")):
+        # A84: with no export stage the delivery is the last stage's file copied as it is, so a
+        # .webm/.mkv name was MP4 bytes, completed and verified. Refused before the first stage
+        # when the last file is certainly an intermediate; a single uncut clip that no stage
+        # touches is the source itself, and the copy below checks what it really is.
+        c0 = clips[0] if len(clips) == 1 and isinstance(clips[0], dict) else None
+        passthrough = c0 is not None and c0.get("in") is None and c0.get("out") is None
+        if not passthrough:
+            refuse_copied_container(mid, output)
+    # A77: the default work directory is new for every run (mkdtemp), not named by the PID alone and
+    # reused with exist_ok -- a later run that got the same PID deleted an earlier run's kept preview.
+    # An explicit --work is the caller's: created when missing, never emptied.
+    created_work = bool(args.work) and not Path(args.work).exists()
     try:
-        work.mkdir(parents=True, exist_ok=True)
+        if args.work:
+            work = Path(args.work)
+            work.mkdir(parents=True, exist_ok=True)
+        else:
+            import tempfile
+            Path(output).parent.mkdir(parents=True, exist_ok=True)
+            work = Path(tempfile.mkdtemp(prefix=f"{Path(output).with_suffix('').name}_work_{os.getpid()}_",
+                                         dir=str(Path(output).parent)))
+            created_work = True
     except OSError as e:
-        die(f"cannot create the work directory {work}: {e}")
+        die(f"cannot create the work directory {args.work or Path(output).parent}: {e}")
+    own_stage_files(work, load=bool(args.work))
     # --stop-after before the export reports a stage file inside the work directory as its output:
     # removing the directory at exit deleted the file the result named (and its output_identity)
     previewing = bool(args.stop_after) and args.stop_after != "export" and not STATE.dry_run
     if previewing and not args.keep and not args.work:
         info(f"--stop-after {args.stop_after}: keeping the work directory {work}, since the result's output is in it")
-    if not args.keep and not args.work and not previewing:
+    if (not args.keep and not args.work and not previewing) or (STATE.dry_run and created_work):
         # a failed or dry run used to leave <output>_work_<pid>/ behind (sweep F15): the
-        # auto-named directory is ours alone, so remove it on every exit path
+        # auto-named directory is ours alone, so remove it on every exit path; a dry run removes
+        # a --work directory it created too, --keep or not (A99: a plan leaves nothing behind)
         import atexit
         atexit.register(lambda: shutil.rmtree(work, ignore_errors=True))
-    # Intermediates keep the delivery's media kind: a .mp4 project is unchanged (every stage file
-    # is still clipNN.mp4 / fit.mp4 / loudnorm.mp4), while an audio-only delivery (the podcast
-    # template) carries its stages through the audio container instead of a video one.
-    mid = Path(output).suffix.lower() if Path(output).suffix.lower() in AUDIO_EXT else ".mp4"
     frame = dict(proj.get("frame") or {})
     trans = proj.get("transition") or {}
     frame_from_preset(frame, proj.get("export") or {})
@@ -1454,7 +1620,6 @@ def main() -> int:
     # unchanged -- it never gets a --platform it did not ask for.
     dest = str(((proj.get("check") or {}).get("platform") or "")) if proj.get("template") else ""
     platform_args: List[str] = ["--platform", dest] if dest in PLATFORMS and PLATFORMS[dest].get("frame") else []
-    ex_cfg = proj.get("export")
     # a malformed "export" is refused by the export stage with its own message; here it only means
     # "no encoding export", never a traceback before that refusal
     ex_preset = str(ex_cfg.get("preset") or "") if isinstance(ex_cfg, dict) else ""
@@ -1468,6 +1633,7 @@ def main() -> int:
 
     CACHE.clear()
     CACHE.update(_fresh_cache())
+    CONTENT_KEYED.clear()
     if args.cache:
         cdir = Path(args.cache)
         try:
@@ -1826,12 +1992,21 @@ def main() -> int:
         sh("export.py", *argv, stage="export")
         stages_done.append("export")
     else:
+        refuse_copied_container(Path(current).suffix.lower(), output)  # what the copy really is (A84)
         if not STATE.dry_run:
             place_output(current, output)
         info(("[dry-run] would copy" if STATE.dry_run else "copied") + f" final stage to {output}")
     current = output
     if not STATE.dry_run:
         mark_delivered(output)  # the chapters and check stages run on it: a stop from here keeps it, and says so (#415)
+    if args.stop_after == "export":
+        # A87: the chapters and check stages ran after "--stop-after export", and a "check" this
+        # run never reads (validate_project() skips it) was then read with .get(): a traceback
+        if not args.keep and not args.work:
+            shutil.rmtree(work, ignore_errors=True)
+        emit(output, stages=stages_done, check=None, cache=cache_report(args.cache),
+             intermediate_preset=_intermediate_used())
+        return 0
 
     # ---- chapters (metadata.py on the delivered file: streams copied, markers written)
     ch = proj.get("chapters")
@@ -1840,9 +2015,19 @@ def main() -> int:
         # which a dry run has not written either. The plan is the run, so --dry-run shows the
         # command and lists the stage (the child's own --dry-run prints rather than writes).
         if isinstance(ch, list):
-            chapter_file = str(work / "chapters.txt")
+            # a dry run writes nothing into the work directory (A99): its metadata.py --dry-run
+            # still reads the list, from a temporary directory removed at exit
+            if STATE.dry_run:
+                import atexit
+                import tempfile
+                tmp_dir = tempfile.mkdtemp(prefix="ffskill_render_chapters_")
+                atexit.register(lambda: shutil.rmtree(tmp_dir, ignore_errors=True))
+                chapter_file = os.path.join(tmp_dir, "chapters.txt")
+            else:
+                chapter_file = str(work / "chapters.txt")
             lines = [f"{entry['at']} {entry['title']}" for entry in ch]
             Path(chapter_file).write_text("\n".join(lines) + "\n", encoding="utf-8")
+            CONTENT_KEYED.add(os.path.abspath(chapter_file))  # rewritten every run: keyed by what it says (A100)
         else:
             chapter_file = rel(ch)
         tagged = str(work / ("chapters" + Path(output).suffix))
@@ -1903,23 +2088,13 @@ def main() -> int:
             kind="verification", output=output, dry_run=STATE.dry_run, stages=stages_done, check=check_result,
             probe=probe(output, role="output"))
     info(f"rendered {output} via {' → '.join(stages_done)}")
-    cache_report = None
-    if args.cache:
-        cache_report = {"dir": CACHE["dir"], "ffmpeg": CACHE["ffmpeg"],
-                        "hits": CACHE["hits"], "misses": CACHE["misses"], "miss_reasons": CACHE["miss_reasons"],
-                        "saved_seconds": round(CACHE["saved_seconds"], 1),
-                        "entries": CACHE["entries"]}
-        if STATE.dry_run:
-            cache_report["would_hit"] = CACHE["would_hit"]
-        info(f"cache: {len(CACHE['hits'])} hit(s) ({', '.join(CACHE['hits']) or '-'}), "
-             f"{len(CACHE['misses'])} miss(es) ({', '.join(CACHE['misses']) or '-'})")
     # One entry per snapped clip, `clip` naming which. A single-clip project keeps the shape a
     # caller reads today by also carrying the first entry's keys at the top level.
     snap_report: Optional[Dict[str, Any]] = None
     if snap_reports:
         snap_report = dict(snap_reports[0])
         snap_report["clips"] = snap_reports
-    emit(output, stages=stages_done, check=check_result, snap=snap_report, cache=cache_report,
+    emit(output, stages=stages_done, check=check_result, snap=snap_report, cache=cache_report(args.cache),
          caption=caption_report, intermediate_preset=_intermediate_used(),
          verification=[{"step": "check", "ok": True, "platform": ck.get("platform")}] if check_result else [])
     return 0

package/scripts/report.py

@@ -119,6 +119,32 @@ PACK_CSS = """
 """
 
 
+def md_cells(line: str) -> List[str]:
+    """The cells of one GFM table row, as render.py's md_cell() writes them: a '|' preceded by a
+    backslash is part of the cell, and a doubled backslash is one. Splitting on every '|' moved a
+    file name such as `a | b.mp4` into the next column (A263)."""
+    cells: List[str] = []
+    cur: List[str] = []
+    body = line.strip()
+    body = body[1:] if body.startswith("|") else body
+    i = 0
+    while i < len(body):
+        ch = body[i]
+        if ch == "\\" and i + 1 < len(body) and body[i + 1] in "\\|":
+            cur.append(body[i + 1])
+            i += 2
+            continue
+        if ch == "|":
+            cells.append("".join(cur).strip())
+            cur = []
+        else:
+            cur.append(ch)
+        i += 1
+    if "".join(cur).strip():
+        cells.append("".join(cur).strip())
+    return cells
+
+
 def pack_report(args) -> int:
     """render.py --template all writes <stem>_pack.md: one row per destination. This renders the
     same rows as HTML, so a pack can be handed over the way a single delivery report is -- no
@@ -130,7 +156,7 @@ def pack_report(args) -> int:
         line = line.strip()
         if not line.startswith("|"):
             continue
-        cells = [c.strip() for c in line.strip("|").split("|")]
+        cells = md_cells(line)
         if all(set(c) <= set("-: ") for c in cells):
             continue
         if not header:

package/scripts/sequence.py

@@ -156,7 +156,11 @@ def main() -> int:
     else:
         out_w, out_h = even(sw), even(sh)
 
-    output = args.output or default_output(str(directory).rstrip("/\\") or "sequence", "sequence", "mp4")
+    # beside the folder, named after it: `--dir .` (run inside the frames folder) or `--dir ..` has
+    # no name of its own, so the folder's resolved name is used (A108: "." was a ValueError
+    # traceback); the filesystem root, which has none either, still names it sequence_sequence.mp4
+    named = directory if directory.name not in ("", ".", "..") else directory.resolve()
+    output = args.output or default_output(str(named).rstrip("/\\") or "sequence", "sequence", "mp4")
     with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-sequence-") as tmp:
         list_path = Path(tmp) / "frames.txt"
         list_path.write_text(concat_list([f.resolve() for f in frames], rate), encoding="utf-8")

package/templates/audiogram.json

@@ -6,6 +6,7 @@
       "src": "$INPUT"
     }
   ],
+  "brand": "$BRAND",
   "audiogram": {
     "image": "$IMAGE",
     "style": "waveform",
@@ -17,6 +18,14 @@
     "position": "bottom",
     "margin": 14
   },
+  "graphics": [
+    {
+      "template": "lower-third",
+      "name": "$TITLE",
+      "start": 1,
+      "end": 6
+    }
+  ],
   "loudness": {
     "lufs": -14,
     "tp": -1