video-editing 2.0.0 → 3.0.0

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.0.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,105 @@ 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>"`.
 
 ## 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 +159,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 +180,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/cli-reference.md

@@ -1,71 +1,86 @@
-# `video-editing` CLI reference (v2 — cloud-only)
+# `video-editing` CLI reference (v3 — pure API client)
 
-All execution goes through this CLI. Quote paths (they contain spaces).
+All execution goes through this CLI, and the CLI runs NOTHING locally: every
+verb is HTTP against the ClipReady cloud plus small artifact pulls. Quote
+paths (they contain spaces).
 
 **Every verb requires ClipReady credentials.** Resolution:
 
-- **base**: `--api-base` → env `CLIPREADY_API_BASE`
-- **key** (sent as `Authorization: Bearer <key>`): `--api-key` → env `CLIPREADY_API_KEY`
+- **base**: `--api-base` → env `CLIPREADY_API_BASE` → the hosted cloud (default)
+- **key** (sent as `Authorization: Bearer <key>`): `--api-key` → env `CLIPREADY_API_KEY` → the config file written by `video-editing auth api-key`
 - **video id**: `--video-id` → `<job>/job.json` (written by `init`) → env `VIDEO_ID`
 
 A missing base or key is a clear error → non-zero exit, nothing runs. There is
-**no ElevenLabs configuration** — transcription is server-side in the ClipReady
-cloud.
+**no ffmpeg/ffprobe/hyperframes requirement and no ElevenLabs
+configuration** — media work is server-side in the ClipReady cloud.
 
 Most verbs support `--json` for a machine-readable result. Exit codes: `0` ok,
 `1` error (incl. missing credentials), `2` validation failed, `3` ambiguous
 anchor (timeline group).
 
-## Pipeline commands
+**Large uploads are chunked automatically** (no flag needed): the init source
+streams up in 8MB parts with per-part retry — a 2GB file is never buffered in
+memory — and on networks where direct storage PUTs keep dying, parts fall back
+to an authenticated relay through the API. Servers without chunked-upload
+support transparently fall back to a single retried upload.
 
-- **`init --video <path> [--job-dir <dir>] [--master] [--force]`**
-  Upload the source and create the cloud job. Writes the job dir (default: a
-  new dir named for the clip) with `job.json` (`video_id`, api base) and
-  `source.json`. `--master` bakes the vertical 9:16 master locally (ffmpeg)
-  before upload, for non-vertical sources destined for a vertical deliverable.
+## Pipeline commands
 
-- **`transcribe --job-dir <dir> [--language <iso>] [--num-speakers <n>] [--force]`**
-  Upload the audio; the **cloud** transcribes and screens it, then the CLI
-  pulls the results into the job dir: `transcripts/*.json`, `word_dump.txt`,
-  `takes_packed.md`, `flags.txt`, `coverage.json`, and the editorial brief
-  `prompts/author-edl.prompt.md` (plus any other `prompts/*.md` the server sends).
-  Cached server-side per source; `--force` re-transcribes.
+- **`init --source <path> [--job-dir <dir>] [--title <t>] [--poll-interval 5]`**
+  ONE command covers what init+transcribe used to do. Streams the source up,
+  creates the cloud job, runs server-side **ingest** (probe + audio
+  extraction + transcription + editorial screening), polls with progress
+  lines, then pulls into the job dir: `transcripts/*.json`, `word_dump.txt`,
+  `takes_packed.md`, `flags.txt`, `coverage.json`, `probe.json`, and the
+  editorial brief `prompts/author-edl.prompt.md` (plus any other
+  `prompts/*.md`). Writes `job.json` (`video_id`, api base, stem,
+  `duration_s` from the server probe, `source_path`) and prints the video's
+  web page link (`web_url` in `--json`). The internal stem is sanitized to a
+  filename-safe charset, so apostrophe/space/unicode filenames work end to
+  end with no rename.
+
+- **`transcribe --job-dir <dir> [--poll-interval 5]`**
+  Re-run/pull only (init already transcribed): when the transcript artifacts
+  exist server-side it just pulls them; otherwise it starts a fresh
+  server-side ingest, polls, and pulls. No media flags — there is no local
+  extraction.
 
 ## Timeline commands (`timeline.json` v2)
 
 - **`timeline validate --job-dir <dir> [--json]`**
-  Local schema + semantic + capability validation of `<job>/timeline.json`.
-  Exit `2` if invalid.
+  Local schema + semantic + capability validation of `<job>/timeline.json`
+  (the one purely local verb — it touches no media). Exit `2` if invalid.
 
-- **`timeline resolve --job-dir <dir> --phrase <text> [--near <srcSeconds>] [--occurrence <n>] [--source <name>] [--json]`**
-  Resolve a transcript phrase to **exact source seconds** (word-accurate).
-  The ONLY way to turn a phrase into an anchor time. Multiple hits → exit `3`
-  with per-occurrence context; pick one with `--near` or `--occurrence`
+- **`timeline resolve --job-dir <dir> --phrase <text> [--occurrence <n>] [--source <name>] [--json]`**
+  Resolve a transcript phrase to **exact source seconds** (word-accurate,
+  server-side). The ONLY way to turn a phrase into an anchor time. Multiple
+  hits → exit `3` with per-occurrence context; pick one with `--occurrence`
   (1-based). Not found → fuzzy suggestions, exit `1`.
 
 - **`timeline compile --job-dir <dir> [--json]`**
   **Cloud compile**: uploads `timeline.json`, the server validates, resolves
-  anchors, derives caption cues, and returns `resolved/plan.json` +
-  `resolved/diagnostics.json` (written into the job dir). Iterate until exit
-  `0`. Exit `2` = validation failed (fix the reported `path`s), `3` =
+  anchors, sources silences from the job's cloud files, derives caption
+  cues, and returns `resolved/plan.json` + `resolved/diagnostics.json`
+  (written into the job dir). On success prints the `View & comment` watch
+  link — the compiled cut is already watchable in the web app. Iterate until
+  exit `0`. Exit `2` = validation failed (fix the reported `path`s), `3` =
   ambiguous anchor (disambiguate with `timeline resolve`). Never hand-edit
   anything under `resolved/`.
 
-## Preview / render commands
+- **`timeline captions generate --job-dir <dir> [--preset grouped|opus-karaoke] [--json]`**
+  Enable captions in `timeline.json` (preset only), then server-compile to
+  derive/report cues.
+
+## Render commands
 
-- **`compose --job-dir <dir> [--render] [--quality draft|standard|high] [--fps 30] [--out <path>] [--json]`**
-  Build the local HyperFrames composition from `resolved/plan.json` (cut +
-  captions/zooms/overlays) in `<job>/composition/` — media proxies, referenced
-  assets, and `index.html`. Without `--render`, prints the composition dir +
-  the exact `hyperframes render` command to run. With `--render`, runs it
-  (requires the `hyperframes` CLI on PATH: `npm install -g hyperframes`);
-  default output `<job>/preview.mp4` (the render IS the preview in the cloud-first flow). This is the LOCAL delivery path.
+- **`render [--mode preview|final] --job-dir <dir> [--no-wait] [--poll-interval 10] [--out <path>] [--json]`**
+  THE render verb: submits a cloud render of the compiled plan (works right
+  after `timeline compile`), **waits by default**, and downloads the result
+  to `<job>/preview.mp4` / `<job>/final.mp4`. Mode defaults to `preview`.
+  `--no-wait` submits and prints `render_id` only.
 
-- **`cloud render --job-dir <dir> --mode preview|final [--wait] [--poll-interval 10] [--out <path>] [--json]`**
-  Submit a server-side render of the compiled plan. Without `--wait`: prints
-  `render_id` and exits `0`. With `--wait`: polls until terminal; on
-  `completed`, downloads the video to `--out` (default `<job>/preview.mp4` or
-  `<job>/final.mp4`). `failed` → exit `1` with the error.
+- **`cloud render --mode preview|final --job-dir <dir> [--wait] [--poll-interval 10] [--out <path>] [--json]`**
+  Same implementation, legacy spelling (`--wait` is opt-in here).
 
 - **`cloud status <render_id> [--json]`**
   One status GET: `pending|running|completed|failed` (+ `video_url` when
@@ -73,36 +88,56 @@ anchor (timeline group).
 
 ## Verification / QA commands
 
-- **`verify --job-dir <dir> [--json]`**
-  **Cloud verification** of the rendered preview: uploads/points at the
-  preview and the server re-checks every join for duplicated phrases (a
-  retake left in → error) and over-long gaps (dead air → warning/error).
-  Writes `verify.json`; exit `2` on needs-fixes. Requires a rendered preview
-  (`compose` + hyperframes render, or `cloud render --mode preview`).
-
-- **`qa frames --range <start>-<end> [--cols <n>] [--interval <s>] --job-dir <dir> [--json]`**
-  **Local ffmpeg** filmstrip PNG for the window →
-  `<job>/qa/frames_<start>_<end>.png`. Read the PNG to inspect frames.
-
-- **`qa waveform --range <start>-<end> --job-dir <dir> [--json]`**
-  **Local ffmpeg** waveform PNG + word-timing sidecar →
+- **`verify --job-dir <dir> [--full] [--window <s>] [--json]`**
+  **Fully server-side verification** of the rendered preview: the server
+  re-checks every join for duplicated phrases (a retake left in → error) and
+  over-long gaps (dead air → warning/error) against its own copy of the
+  preview — nothing is uploaded. Writes `verify.json`; exit `2` on
+  needs-fixes. Caveat: the duplicated-phrase check over-triggers on
+  thematically narrow monologues — if every join is flagged (including plain
+  pause-tightening joins), adjudicate against `flags.txt` instead of blindly
+  recutting.
+
+- **`qa frames (--start <s> --end <s> | --join <i> [--span 2] | --out-start <s> --out-end <s>) [--cols <n>] [--interval <s>] --job-dir <dir> [--json]`**
+  **Server-rendered** filmstrip PNG(s) → `<job>/qa/frames_<start>_<end>.png`.
+  Three addressing modes (exactly one): `--start/--end` in SOURCE seconds;
+  `--join <i>` renders the two sides of compiled-plan join `i` (1-based —
+  the last/first `--span` seconds of the segments meeting there) as
+  `…-a.png` (tail) + `…-b.png` (head); `--out-start/--out-end` in OUTPUT
+  seconds, mapped through `resolved/plan.json` (windows crossing a join
+  split into `-a`/`-b`/… PNGs). Read the PNGs to inspect frames.
+
+- **`qa waveform --start <s> --end <s> --job-dir <dir> [--json]`**
+  **Server-rendered** waveform PNG + word-timing sidecar →
   `<job>/qa/waveform_<start>_<end>.png` and
   `<job>/qa/waveform_<start>_<end>.words.json` (word list with timings for
-  the window). Free and fast — use for cut-edge adjudication.
+  the window, SOURCE seconds). Use for cut-edge adjudication.
+
+- **`qa inspect (--start <s> --end <s> | --join <i> [--span 2] | --out-start <s> --out-end <s>) [--n-frames <n>] --job-dir <dir> [--json]`**
+  **THE close-look tool** — a **server-rendered** combined composite PNG →
+  `<job>/qa/inspect_<start>_<end>.png`: filmstrip + waveform + word labels
+  in one image, with the compiled plan's cut regions shaded translucent
+  red (labeled "cut") over the waveform. Same three addressing modes as
+  `qa frames` (exactly one): `--start/--end` in SOURCE seconds; `--join <i>`
+  renders the two sides of compiled-plan join `i` as `…-a.png` (tail) +
+  `…-b.png` (head) — the sides are discontiguous in source time, hence two
+  PNGs; `--out-start/--out-end` in OUTPUT seconds mapped through
+  `resolved/plan.json`. `--n-frames` sets the filmstrip frame count
+  (default 10). Prefer this over separate frames + waveform calls when
+  adjudicating a cut.
 
 ## File sync commands
 
 - **`files pull --job-dir <dir> [--only <name,name>] [--json]`**
-  List the cloud job's artifacts and fetch each (or the `--only` subset) into
+  List the cloud job's files and fetch each (or the `--only` subset) into
   the job dir, **preserving relative paths** (`resolved/plan.json` →
   `<job>/resolved/plan.json`, `prompts/author-edl.prompt.md` →
-  `<job>/prompts/author-edl.prompt.md`). `.json` artifacts pretty-printed. Use to
+  `<job>/prompts/author-edl.prompt.md`). Byte-exact, sha256-skipped. Use to
   recover job state on a fresh machine.
 
-- **`files push --job-dir <dir> [--only <name,name>] [--json]`**
-  Upload local job artifacts (e.g. `timeline.json`, referenced assets under
-  `assets/`) to the cloud job. Content-hash-cached — unchanged files are not
-  re-uploaded.
+- **`files push --job-dir <dir> <paths…> [--json]`**
+  Upload local job files (e.g. `timeline.json`, referenced assets) to the
+  cloud job. Content-hash-cached — unchanged files are not re-uploaded.
 
 ## Review round commands (ClipReady review sessions)
 
@@ -116,31 +151,36 @@ anchor (timeline group).
   Push review-round events (one mode per call; run id defaults to
   `review/round.json`). `--stage` posts a progress event
   (`provisioning|transcribing|edl|render_preview|qc|render_final|uploading|log`).
-  `--timeline` compiles `<job>/timeline.json` (same as `timeline compile`,
-  exit `2` if not clean) and pushes a `timeline_update` — the review page
-  updates live. `--complete` compiles fresh (must be clean) and pushes the
-  terminal `completed` event (`{edl, timeline, plan, duration_s, outcomes?}`;
+  `--timeline` compiles `<job>/timeline.json` in the cloud (exit `2` if not
+  clean) and pushes a `timeline_update` — the review page updates live.
+  `--complete` compiles fresh (must be clean) and pushes the terminal
+  `completed` event (`{edl, timeline, plan, duration_s, outcomes?}`;
   `--outcomes` is a JSON file of `[{change_id, ok, note?}]`). Both
   `--timeline` and `--complete` upload the timeline's referenced assets
   automatically (sha256-cached in `<job>/review/assets.json`).
 
+- **`review prompt --job-dir <dir> [--json]`** — print the pulled round
+  instruction.
+
 ## Utility
 
 - **`--version`** — print the CLI version.
 - **`status --job-dir <dir> [--json]`** — cloud job state + local artifact existence.
 - **`skill install [--target <dir>] [--json]`** — copy the bundled
   `video-editing` agent skill into `<target|~/.claude/skills>/video-editing`.
+- **`config set-key <key> | set-base <url> | path`** — store credentials in
+  `~/.config/video-editing/.env` (the only verb that runs without one).
 
 ## Typical session
 
 ```
-export CLIPREADY_API_BASE=https://…  CLIPREADY_API_KEY=…
-video-editing init --video "clip.mp4" --job-dir jobs/clip
-video-editing transcribe --job-dir jobs/clip
+video-editing auth api-key            # once per machine (skip if already logged in)
+video-editing init --source "clip.mp4" --job-dir jobs/clip   # upload + ingest + pull (transcribe included)
 # READ jobs/clip/prompts/author-edl.prompt.md — it is the editorial brief. Author timeline.json.
-video-editing timeline compile --job-dir jobs/clip --json     # fix until exit 0
-video-editing compose --job-dir jobs/clip --render            # local preview render
-video-editing verify --job-dir jobs/clip --json               # fix → recompile → re-render → re-verify
-video-editing qa frames --range 0-5 --job-dir jobs/clip       # spot-check looks
-video-editing cloud render --job-dir jobs/clip --mode final --wait
+video-editing timeline validate --job-dir jobs/clip --json
+video-editing timeline compile --job-dir jobs/clip --json    # fix until exit 0; prints the watch link
+video-editing render --job-dir jobs/clip                     # cloud preview render (waits + downloads)
+video-editing verify --job-dir jobs/clip --json              # fix → recompile → re-render → re-verify
+video-editing qa inspect --join 1 --job-dir jobs/clip        # close-look at the first join's two sides (filmstrip+waveform+cuts)
+video-editing render --mode final --job-dir jobs/clip
 ```