video-editing 2.0.0 → 3.1.0

package/dist/index.js

@@ -4,51 +4,55 @@ import {
   CAPTION_STYLE_DEFAULTS,
   CloudClient,
   CloudHttpError,
-  DEFAULT_DESILENCE,
   DEFAULT_DOWNLOAD_TIMEOUT_MS,
   DEFAULT_TIMEOUT_MS,
   INLINE_MAX_BYTES,
   MAX_POLL_MS,
   MAX_RUN_POLL_MS,
+  MULTIPART_THRESHOLD_BYTES,
+  RELAY_DIRECT_ATTEMPTS,
+  RELAY_SUBCHUNK_BYTES,
   REVIEW_STAGES2,
   assertRunCompleted,
   assetContentType2,
   assetsUrl,
-  buildMediaEntry,
   bundledSkillDir,
+  bytesSource,
   checkCapabilities,
   collectPlanAssetRefs2,
   compileRemote,
   compileUrl,
-  composeCloud,
   composeUrl,
   defaultRenderOut,
   defaultSkillTarget,
-  detectSilences,
-  detectSilencesForDoc,
   diagnosticsPath2,
   downloadTo,
   emptyDiagnostics,
-  extractGuardedWav,
   filesUrl,
-  findLocalTranscript,
   formatRunEvent,
+  framesPngPath,
+  ingestArtifactSet,
+  ingestUrl,
   initCloudJob,
   installSkill,
   instructionPath2,
   isTerminalRunStatus,
   isTerminalStatus,
   jobJsonPath,
+  joinSourceWindows,
   loadPublicConfigEnv,
   loadTimeline2,
   meUrl,
+  multipartRelayUrl,
+  multipartUrl,
+  openFileSource,
+  outWindowToSourceWindows,
   parseFileContent,
   parseFileList,
   parseFilePresign,
   parseRenderCreate,
   parseRenderState,
   parseRunState,
-  parseSilenceDetect,
   parseTimeline,
   planPath2,
   pollRender,
@@ -63,13 +67,11 @@ import {
   pushFiles,
   pushStage2,
   pushTimeline2,
-  qaFramesArgs,
-  qaFramesLocal,
-  qaWaveformArgs,
-  qaWaveformLocal,
-  qaWordsForWindow,
+  qaDir,
   readJobFile,
   readOutcomesFile2,
+  readPlanSegments,
+  readProbeDuration,
   renderUrl,
   rendersUrl,
   resolveApiBase,
@@ -83,9 +85,10 @@ import {
   roundJsonPath2,
   runUrl,
   sameSha,
+  sanitizeStem,
   savePublicConfigKey,
   sha256Hex,
-  silenceDetectArgs,
+  shouldMultipart,
   statAssetsForDoc,
   stripTrailingSlash,
   syncAssets2,
@@ -95,7 +98,9 @@ import {
   transcribeArtifactSet,
   transcribeCloud,
   transcribeUrl,
+  uploadMultipart,
   uploadVfsBytes,
+  uploadVfsPayload,
   usesFromDoc,
   validateLocal,
   validateTimeline,
@@ -104,8 +109,10 @@ import {
   vfsContentType,
   vfsLocalPath,
   videoIdFromJob,
+  waveformPngPath,
+  waveformWordsPath,
   writeJobFile
-} from "./chunk-SSXAUKGV.js";
+} from "./chunk-2OM7WV4W.js";
 
 // src/timeline-v2/anchors.ts
 function normalizeToken(text) {
@@ -227,55 +234,59 @@ export {
   CAPTION_STYLE_DEFAULTS,
   CloudClient,
   CloudHttpError,
-  DEFAULT_DESILENCE,
   DEFAULT_DOWNLOAD_TIMEOUT_MS,
   DEFAULT_TIMEOUT_MS,
   INLINE_MAX_BYTES,
   MAX_POLL_MS,
   MAX_RUN_POLL_MS,
+  MULTIPART_THRESHOLD_BYTES,
+  RELAY_DIRECT_ATTEMPTS,
+  RELAY_SUBCHUNK_BYTES,
   REVIEW_STAGES2,
   assertRunCompleted,
   assetContentType2,
   assetsUrl,
-  buildMediaEntry,
   bundledSkillDir,
+  bytesSource,
   checkCapabilities,
   collectPlanAssetRefs2,
   compileRemote,
   compileUrl,
-  composeCloud,
   composeUrl,
   defaultRenderOut,
   defaultSkillTarget,
-  detectSilences,
-  detectSilencesForDoc,
   diagnosticsPath2,
   downloadTo,
   emptyDiagnostics,
-  extractGuardedWav,
   filesUrl,
-  findLocalTranscript,
   findPhrase,
   formatRunEvent,
+  framesPngPath,
   fuzzySuggestions,
+  ingestArtifactSet,
+  ingestUrl,
   initCloudJob,
   installSkill,
   instructionPath2,
   isTerminalRunStatus,
   isTerminalStatus,
   jobJsonPath,
+  joinSourceWindows,
   loadPublicConfigEnv,
   loadTimeline2,
   meUrl,
+  multipartRelayUrl,
+  multipartUrl,
   normalizePhrase,
   normalizeToken,
+  openFileSource,
+  outWindowToSourceWindows,
   parseFileContent,
   parseFileList,
   parseFilePresign,
   parseRenderCreate,
   parseRenderState,
   parseRunState,
-  parseSilenceDetect,
   parseTimeline,
   planPath2,
   pollRender,
@@ -290,13 +301,11 @@ export {
   pushFiles,
   pushStage2,
   pushTimeline2,
-  qaFramesArgs,
-  qaFramesLocal,
-  qaWaveformArgs,
-  qaWaveformLocal,
-  qaWordsForWindow,
+  qaDir,
   readJobFile,
   readOutcomesFile2,
+  readPlanSegments,
+  readProbeDuration,
   renderUrl,
   rendersUrl,
   resolveApiBase,
@@ -311,9 +320,10 @@ export {
   roundJsonPath2,
   runUrl,
   sameSha,
+  sanitizeStem,
   savePublicConfigKey,
   sha256Hex,
-  silenceDetectArgs,
+  shouldMultipart,
   statAssetsForDoc,
   stripTrailingSlash,
   syncAssets2,
@@ -323,7 +333,9 @@ export {
   transcribeArtifactSet,
   transcribeCloud,
   transcribeUrl,
+  uploadMultipart,
   uploadVfsBytes,
+  uploadVfsPayload,
   usesFromDoc,
   validateLocal,
   validateTimeline,
@@ -332,6 +344,8 @@ export {
   vfsContentType,
   vfsLocalPath,
   videoIdFromJob,
+  waveformPngPath,
+  waveformWordsPath,
   wordStream,
   writeJobFile
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "video-editing",
-  "version": "2.0.0",
-  "description": "Cloud CLI + client for editing talking-head reels with clipready: transcription, timeline authoring, verify, compose, QA and renders — heavy lifting runs in the cloud.",
+  "version": "3.1.0",
+  "description": "Pure-API cloud CLI + client for editing talking-head reels with clipready: upload once, then transcription, timeline authoring, compile, render, verify and QA all run in the cloud. Node ≥ 20 + an API key — no ffmpeg.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Itay Elgazar",

package/skills/video-editing/SKILL.md

@@ -1,44 +1,47 @@
 ---
 name: video-editing
 description: >-
-  Cloud-first agent workflow for editing a talking-head video into a tight,
-  clean cut with the `video-editing` CLI + the ClipReady cloud. Requires a
-  ClipReady API key (`CLIPREADY_API_KEY`) — every command talks to the cloud.
-  Transcription and editorial screening run server-side (no ElevenLabs key
-  needed); the editorial brief arrives from the server as pulled
-  `prompts/*.md`; the timeline compiles in the cloud; rendering and QA
-  visuals run locally on your machine (ffmpeg + hyperframes). Use whenever
-  the user drops a talking-head clip / reel / vlog / interview and wants it
-  edited or tightened — "edit this reel", "cut the bad retakes", "clean up
-  this recording", "tighten this", "add captions", or just a video path with
-  an editing ask — or when working a ClipReady review round. Handles
-  Hebrew/RTL.
+  Cloud agent workflow for editing a talking-head video into a tight, clean
+  cut with the `video-editing` CLI + the ClipReady cloud. The CLI is a PURE
+  API client — requirements are Node ≥ 20 and a ClipReady API key
+  (`CLIPREADY_API_KEY`) only; no ffmpeg, no ffprobe, no local rendering
+  tools. The source uploads once at init; transcription, editorial
+  screening, timeline compilation, rendering, verification, and QA visuals
+  all run server-side; the editorial brief arrives from the server as pulled
+  `prompts/*.md`. Use whenever the user drops a talking-head clip / reel /
+  vlog / interview and wants it edited or tightened — "edit this reel",
+  "cut the bad retakes", "clean up this recording", "tighten this",
+  "add captions", or just a video path with an editing ask — or when
+  working a ClipReady review round. Handles Hebrew/RTL.
 ---
 
-# Video Editing (ClipReady cloud + local render)
+# Video Editing (ClipReady cloud — pure API client)
 
-Turn a raw talking-head recording into a tight, clean cut. The **`video-editing`**
-CLI is a thin client for the ClipReady cloud: the cloud owns transcription,
-screening, editorial prompts, timeline compilation, and verification; your
-machine owns rendering and QA visuals. **You** read the pulled transcript +
-brief and author `timeline.json`; the CLI does everything executable.
+Turn a raw talking-head recording into a tight, clean cut. The
+**`video-editing`** CLI (v3) is a pure API client for the ClipReady cloud: the
+cloud owns EVERYTHING executable — probing, transcription, screening,
+editorial prompts, timeline compilation, rendering, verification, and QA
+visuals. Your machine only streams the source up once and pulls small
+artifacts back. **You** read the pulled transcript + brief and author
+`timeline.json`; the CLI does the rest over HTTP.
 
 ## Install & auth
 
 ```bash
-npm install -g video-editing                                  # the CLI (v2)
+npm install -g video-editing                                  # the CLI (v3)
 npx skills add ItayElgazar/clipready --skill video-editing    # this skill
 ```
 
-Requirements:
+Requirements — this is the FULL list:
 
 - **Node ≥ 20**
-- **ffmpeg**/**ffprobe** on PATH (local render + QA visuals)
-- **`CLIPREADY_API_KEY`** — from the ClipReady settings page
-- **`CLIPREADY_API_BASE`** — the ClipReady API base URL
+- **A ClipReady API key** — one-time login: `video-editing auth api-key` (paste
+  the key from the ClipReady settings page; the base URL defaults to the hosted
+  cloud). Env vars `CLIPREADY_API_KEY`/`CLIPREADY_API_BASE` override when set.
 
-**No ElevenLabs key.** Transcription runs in the ClipReady cloud with
-ClipReady's own transcription — do not set or ask for `ELEVENLABS_API_KEY`.
+**No ffmpeg. No ffprobe. No hyperframes. No ElevenLabs key.** Nothing runs on
+the local machine except the CLI itself — do not install media tools, and do
+not set or ask for `ELEVENLABS_API_KEY`.
 
 **Every command fails without the API key.** If a verb errors with a
 missing-key message, stop and ask the user for their ClipReady API key;
@@ -48,79 +51,111 @@ never work around it.
 
 - Use **only** the `video-editing` CLI (`video-editing <subcommand>`). Run
   `video-editing --help` to see commands.
-- **NEVER** run ffmpeg/ffprobe/transcription by hand — the CLI owns all execution.
-- If a capability seems missing, STOP and report it as a CLI gap. Do not reach around the CLI.
+- **NEVER** run ffmpeg/ffprobe/transcription by hand — there is simply no
+  local media in this workflow at all; every frame lives in the cloud. If you
+  have a memory of local renders, `compose`, `--master`, or "extract the WAV
+  first", that memory is from a retired pipeline — discard it.
+- If a capability seems missing, STOP and report it as a CLI gap. Do not
+  reach around the CLI.
 - Your only hand-authored artifact is `<job>/timeline.json`.
+- **Captions are timeline-authored and rendered by the cloud renderer —
+  NEVER ffmpeg subtitle filters, libass, `.srt` sidecars, or `drawtext`.**
 
 ## The workflow
 
-1. **Init** — `video-editing init --video "<path>"` (add `--job-dir "<dir>"` to
-   choose the working dir). Uploads the source and creates the cloud job;
-   writes `<job>/job.json` with the `video_id` every later verb uses.
-2. **Transcribe** — `video-editing transcribe --job-dir "<job>"`. Uploads the
-   audio; the cloud transcribes **and screens** it, then the CLI pulls the
-   results into the job dir: `transcripts/`, `word_dump.txt`,
-   `takes_packed.md`, `flags.txt`, `coverage.json` — **and
-   `prompts/author-edl.prompt.md`**, your editorial brief.
-3. **READ the pulled `prompts/*.md` and follow them** — they are your
+1. **Init** — `video-editing init --source "<path>"` (add `--job-dir "<dir>"`
+   to choose the working dir). ONE command does everything through
+   transcription: it streams the source up (chunked, retried, 2GB-safe),
+   creates the cloud job, runs server-side ingest (probe + transcription +
+   editorial screening), and pulls the results into the job dir:
+   `transcripts/`, `word_dump.txt`, `takes_packed.md`, `flags.txt`,
+   `coverage.json`, `probe.json` — **and `prompts/author-edl.prompt.md`**,
+   your editorial brief. Writes `<job>/job.json` (the `video_id` every later
+   verb uses) and prints the video's web link. There is no separate
+   transcribe step — `transcribe` exists only to re-pull/re-run later.
+   Filenames with apostrophes, spaces, or unicode are safe — the internal
+   stem is sanitized automatically; never rename the user's file.
+2. **READ the pulled `prompts/*.md` and follow them** — they are your
    editorial brief (what to cut, what to keep, the screening gate, the pad
    and boundary rules). They are authoritative and may change between runs;
    never edit them, never substitute a remembered brief.
-4. **Author `<job>/timeline.json`** per the pulled brief plus
+3. **Author `<job>/timeline.json`** per the pulled brief plus
    `references/timeline-v2-vocabulary.md` (cut ranges, captions, zooms,
-   overlays, audio). Resolve phrase → seconds ONLY with
-   `video-editing timeline resolve --phrase "…" [--near <t> | --occurrence <n>]`
+   overlays, audio). The **sources KEY must equal the transcript stem** (the
+   filename of `transcripts/<stem>.json`) — captions and resolve bind
+   through it. Resolve phrase → seconds ONLY with
+   `video-editing timeline resolve --phrase "…" [--occurrence <n>]`
    — never eyeball `word_dump.txt`. Sanity-check locally anytime with
    `video-editing timeline validate --job-dir "<job>" --json`.
-5. **Compile** — `video-editing timeline compile --job-dir "<job>" --json`.
+4. **Compile** — `video-editing timeline compile --job-dir "<job>" --json`.
    Compiles in the cloud; writes `resolved/plan.json` +
-   `resolved/diagnostics.json`. Read the diagnostics and fix until it exits
-   `0` (`2` = validation failed — fix the reported paths; `3` = ambiguous
-   anchor — disambiguate with `timeline resolve`). Never hand-edit `resolved/`.
-6. **Render the preview** — `video-editing compose --job-dir "<job>"` builds
-   the local HyperFrames composition in `<job>/composition/` (with
-   `index.html`), then render it locally with the `hyperframes` CLI
-   (`npm install -g hyperframes`; `compose` prints the exact command, or pass
-   `--render`). No hyperframes / no local horsepower? Use
-   `video-editing cloud render --job-dir "<job>" --mode preview --wait` instead.
-7. **Verify** — `video-editing verify --job-dir "<job>" --json`. Cloud
-   verification of the rendered preview (catches retakes left in across a
-   join and dead air a visual check misses). Fix `timeline.json`, re-compile,
+   `resolved/diagnostics.json` and prints the `View & comment` watch link —
+   the user can already watch/comment on the compiled cut. Read the
+   diagnostics and fix until it exits `0` (`2` = validation failed — fix the
+   reported paths; `3` = ambiguous anchor — disambiguate with
+   `timeline resolve`). Never hand-edit `resolved/`.
+5. **Render the preview** — `video-editing render --job-dir "<job>"`
+   (cloud render, preview mode, waits and downloads `<job>/preview.mp4` by
+   default; it works right after `timeline compile`). Share the printed
+   watch link with the user.
+6. **Verify** — `video-editing verify --job-dir "<job>" --json`. Fully
+   server-side verification of the rendered preview (catches retakes left in
+   across a join and dead air a visual check misses); nothing is uploaded.
+   Can run while the user reviews. Fix `timeline.json`, re-compile,
    re-render, re-verify until clean; cap at ~3 fix passes and surface
    remaining findings rather than looping.
-8. **QA looks** — spot-check any window locally:
-   `video-editing qa frames --range <a>-<b> --job-dir "<job>"` (filmstrip PNG)
-   and `video-editing qa waveform --range <a>-<b> --job-dir "<job>"`
-   (waveform PNG + word-timing sidecar JSON). Local ffmpeg — free and fast;
-   Read the PNGs to adjudicate.
-9. **Final** — `video-editing cloud render --job-dir "<job>" --mode final --wait`
-   (or render the composition locally at final quality).
+7. **QA looks** — spot-check any window with server-rendered visuals.
+   THE close-look tool is
+   `video-editing qa inspect --start <a> --end <b> --job-dir "<job>"`:
+   one composite PNG with the filmstrip, the waveform, word labels, AND
+   the compiled plan's cut regions shaded red ("cut") — everything needed
+   to adjudicate a moment in a single image. Same addressing as frames:
+   `qa inspect --join <i>` (the two sides of plan join i → `-a`/`-b`
+   PNGs) and `qa inspect --out-start <a> --out-end <b>` (OUTPUT seconds
+   mapped through the compiled plan). The narrower views still exist:
+   `video-editing qa frames …` (filmstrip only, same addressing modes)
+   and `video-editing qa waveform --start <a> --end <b>` (waveform PNG +
+   word-timing sidecar JSON). Read the PNGs to adjudicate.
+8. **Final** — `video-editing render --mode final --job-dir "<job>"`.
+
+**Optional, any time after compile:** if joins sound clicky, chopped, or gappy,
+run `video-editing smooth-joins --job-dir "<job>"` to apply an equal-power
+audio crossfade to every cut, then re-render. It is NOT part of the sequence
+above — renders are unaffected unless you run it, and it must be re-run after
+each recompile you want it applied to. See `references/audio-joins.md`.
 
 ## Your editorial brief arrives from the cloud
 
 The deep editorial brief — retake/keep rules, pause tightening, cold-open,
 screening and verification procedure — is **not in this skill**. It is pulled
-from the server into `<job>/prompts/*.md` by `transcribe` (and refreshed by
+from the server into `<job>/prompts/*.md` by `init` (and refreshed by
 `files pull`). Old references in this skill (`editing-brief.md`,
 `hard-rules.md`, `adversarial-review.md`, `scribe-collapse.md`) are stubs
 pointing there. If `prompts/author-edl.prompt.md` is missing, run
 `video-editing files pull --job-dir "<job>"` — do not improvise a brief.
 
-## Vertical master
+## Known caveats
 
-`init --video` uploads the source as-is. When the deliverable is a vertical
-9:16 reel from a non-vertical source, pass `--master` to `init` so the
-vertical master is baked before upload (needs local ffmpeg). Check
-`video-editing init --help` for the current flag surface.
+- **`verify` over-triggers on thematically narrow monologues.** The
+  duplicated-phrase join check flags legitimately repeated wording as
+  "retake left in". If EVERY join comes back flagged — including plain
+  pause-tightening joins that obviously aren't retakes — adjudicate each
+  finding against `flags.txt` (the screening output) instead of blindly
+  recutting; only recut joins that flags.txt corroborates as real retakes.
+- **Caption mistranscriptions** are fixed with a captions override in
+  `timeline.json` (anchored on the MIS-transcribed text — see
+  `references/timeline-v2-vocabulary.md`), then recompile + re-render.
+  Never with subtitle files or filters.
 
 ## File sync
 
 `video-editing files pull --job-dir "<job>" [--only <name,name>]` fetches the
 cloud job's artifacts into the job dir preserving relative paths (transcripts,
 `prompts/*.md`, `resolved/plan.json`, `timeline.json`, …);
-`video-editing files push --job-dir "<job>"` uploads local artifacts (e.g. a
-hand-authored `timeline.json`, referenced assets) back to the job. Use `pull`
-to recover state on a fresh machine — the cloud job is the source of truth.
+`video-editing files push --job-dir "<job>" <paths…>` uploads local artifacts
+(e.g. a hand-authored `timeline.json`, referenced assets) back to the job. Use
+`pull` to recover state on a fresh machine — the cloud job is the source of
+truth.
 
 ## Working a ClipReady review round
 
@@ -130,13 +165,12 @@ When the job is a clipready review round (the video has an active round):
    `<job>/review/round.json` (round/run ids, requested changes) and
    `<job>/review/instruction.md`; hydrates `<job>/timeline.json` from the
    server only when you don't already have one (never overwrites yours).
-   Add `--source` if the source video isn't local yet.
 2. Edit `timeline.json` per the instruction, then
    `video-editing review push --timeline --job-dir "<job>"` after each
-   meaningful change — it compiles (diagnostics; exit `2` if not clean) and
-   the review page updates live. Referenced assets (stickers, audio beds)
-   upload automatically, sha256-cached.
-3. Preview + verify exactly as in the workflow above.
+   meaningful change — it compiles in the cloud (diagnostics; exit `2` if
+   not clean) and the review page updates live. Referenced assets (stickers,
+   audio beds) upload automatically, sha256-cached.
+3. Render + verify exactly as in the workflow above.
 4. `video-editing review push --complete --duration <s> --outcomes outcomes.json --job-dir "<job>"`
    — compiles fresh (must be clean) and delivers the terminal payload.
    `outcomes.json` is `[{"change_id": "chg_…", "ok": true, "note": "…"}]`,
@@ -152,7 +186,7 @@ caption grouping is the same characters in Hebrew.
 
 ## References
 
-- `references/cli-reference.md` — every v2 subcommand + flag.
+- `references/cli-reference.md` — every v3 subcommand + flag.
 - `references/timeline-v2-vocabulary.md` — the full `timeline.json` v2
   vocabulary, one JSON example per feature (captions + word styling, karaoke,
   zoom ramps, stickers, enter/exit, audio beds, grade).

package/skills/video-editing/references/audio-joins.md

@@ -0,0 +1,94 @@
+# Smoothing the audio at cuts (`smooth-joins`)
+
+**Optional.** Nothing here runs as part of a render. If you never call it,
+renders behave exactly as they always have.
+
+This is the Premiere move of selecting the whole timeline and hitting *Apply
+Audio Transition*: the picture stays a hard cut, and every join gets a short
+**Constant Power** (equal-power) audio crossfade built from the padding the cut
+threw away. One invocation treats every join — you do not opt in per cut.
+
+## Why you would run it
+
+By default each kept range is extracted with a 30 ms fade in *and* out and the
+clips are butt-joined, so every cut has a brief hole down to silence. Depending
+on where the cut landed that reads as a click, a clipped syllable, or a gap of
+dead air. The crossfade turns each one into a quick natural dip instead, and
+because it is centred on the cut the total duration does not change.
+
+Reach for it when a verify pass or a listen flags clicks, popping, or chopped
+word endings at joins — and on any edit with a lot of tight desilence trims,
+where joins are most frequent.
+
+Requires a compiled timeline (run `timeline compile` first) and an ingested
+source. Exits non-zero with `no_edl` if you run it too early.
+
+## Usage
+
+```bash
+video-editing smooth-joins --job-dir "<job>"                  # 130ms everywhere
+video-editing smooth-joins --crossfade-ms 90 --job-dir "<job>"
+video-editing smooth-joins --join 3:40 --join 7:220 --job-dir "<job>"
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--crossfade-ms <ms>` | `130` | Transition length at every join (Premiere's 4 frames). `0` disables. |
+| `--curve equal-power\|linear` | `equal-power` | Fade shape. |
+| `--max-ms <ms>` | `500` | Ceiling on any single join. |
+| `--join <index>:<ms>` | — | Override one boundary. Repeatable. |
+| `--json` | — | Machine-readable output. |
+
+**Join `i` is the boundary between segment `i` and segment `i + 1`**, so an
+N-segment edit has N−1 joins. Same indexing `verify` reports its join findings
+against, so a verify finding at join 5 is `--join 5:<ms>` here.
+
+Keep `--curve equal-power` unless you have a reason: it is the only curve that
+holds loudness flat through the transition (`sin² + cos² = 1`). `linear` dips
+~3 dB in the middle of every join.
+
+Per-join overrides are for shaping, not rescue — `--join 3:40` to keep a hard
+beat change tight, `--join 7:220` to let a take change breathe, `--join 9:0` to
+leave one boundary exactly as it was.
+
+## Reading the result
+
+Writes `audio/joined.m4a` (the rebuilt track) and `audio/joined.json`:
+
+```jsonc
+{
+  "edl_sha256": "…",
+  "params": { "crossfade_ms": 130, "curve": "equal-power", "max_ms": 500 },
+  "total_duration_s": 47.213,
+  "segments": 42,
+  "joins": [
+    { "index": 0, "requested_ms": 130, "applied_ms": 130, "handle_ms": 1840, "clamped": false },
+    { "index": 1, "requested_ms": 130, "applied_ms": 52, "handle_ms": 52, "clamped": true,
+      "reason": "limited by the gap the cut removed" }
+  ]
+}
+```
+
+`applied_ms` is what the join actually got; `handle_ms` is the longest
+crossfade the surrounding material could support. **A crossfade can only borrow
+material the cut removed**, so a tight desilence trim that only took out 50 ms
+can only give you a 50 ms transition — it will come back `clamped` no matter
+what you request. That is expected and still sounds clean; 50 ms of same-speaker
+room tone is plenty. Joins between different takes have seconds of handle and
+always get the full request.
+
+Read the report before re-running: if a join you care about came back clamped
+with `"limited by the gap the cut removed"`, asking for more milliseconds will
+change nothing. Widen the cut range in `timeline.json` and recompile instead.
+
+## How it interacts with rendering
+
+Renders **consume** the artifact, they never trigger it:
+
+- Run `smooth-joins`, then render → the render uses the crossfaded audio.
+- Render without running it → unchanged from today.
+- Recompile the timeline, then render → the artifact no longer matches the
+  edit and is ignored (it is keyed to the EDL). Re-run `smooth-joins`.
+
+So the order is: `timeline compile` → `smooth-joins` → render. Re-running the
+command is cheap; re-run it after every recompile you want it applied to.