video-editing 1.3.1

package/skills/video-editing/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: video-editing
+description: >-
+  Edit a talking-head video reel into a tight, clean cut using ONLY the local
+  `video-editing` CLI — never the video-use repo, never the clean-cut skill,
+  never raw Python helpers or ffmpeg by hand. Removes bad retakes, false starts,
+  stutters and cut-off words (keep the LAST complete take, but keep the CLEANEST
+  take when an earlier one is clean and a later one stutters), tightens every
+  pause to ~0.13s, cold-opens on the strongest hook, trims outro dead air.
+  Vertical 9:16, clean cuts only (no grade/subtitles/overlays by default). Two
+  mandatory gates: SCREEN before cutting and CONTENT-VERIFY (re-transcribe the
+  rendered preview at every join) after. Use whenever the user drops a
+  talking-head clip / reel / vlog / interview and wants it edited or tightened —
+  phrasings like "edit this reel", "cut the bad retakes", "remove the false
+  starts", "clean up this recording", "tighten this reel", "tighten this", "I
+  flubbed some lines, fix it", "get rid of the dead air", "make a clean cut of
+  this", or just a video path with "make this cleaner". Handles Hebrew/RTL.
+  This is the single source of truth for reel edits; it supersedes and replaces
+  the clean-cut and video-use skills.
+---
+
+# Video Editing (CLI-only)
+
+Turn a raw talking-head recording into a tight, clean vertical cut. The local
+**`video-editing`** CLI is the single source of truth and owns ALL execution
+(probe, transcribe, screen, bake master, render, QC, content-verify). **You**
+read the transcript and author the EDL; the CLI does everything executable.
+
+## Install
+
+Requirements: **Node ≥ 20**, **ffmpeg**/**ffprobe** on PATH, and an **ElevenLabs API key**
+(`ELEVENLABS_API_KEY`) for transcription.
+
+```bash
+npm install -g video-editing                                  # the CLI
+npx skills add ItayElgazar/clipready --skill video-editing    # this skill
+```
+
+## HARD RULE — execution boundary (read first)
+
+- 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.
+- Your only hand-authored artifact is `<job>/edl.json`.
+
+## Prerequisites
+
+- `video-editing` on PATH (`which video-editing`), plus `ffmpeg`/`ffprobe`.
+- ElevenLabs key: the CLI owns it (env `ELEVENLABS_API_KEY` or `~/.config/video-editing/.env`;
+  set once with `video-editing config set-key <key>`). Transcription is cached per source
+  and is a paid call — never force a re-transcribe of an unchanged source.
+
+## Workflow
+
+1. **Init** — `video-editing init-job --source "<video>" --job-dir "/vercel/sandbox/jobs/<job_id>"`
+   → job dir + `source.json`. Always pass `--job-dir` explicitly (there is no `~/Downloads` on
+   the sandbox); use the job dir given in the task prompt.
+2. **Transcribe + screen** — `video-editing transcribe --job-dir "<job>"` → word-level
+   transcript + screening artifacts (`flags.txt`, `takes_packed.md`, `word_dump.txt`, `coverage.json`).
+3. **GATE 1 — SCREEN before cutting** — read `<job>/flags.txt`: resolve every **[A]**
+   over-long/collapsed token (retakes hide here), judge every **[B]** repeated phrase
+   (retake vs intentional), note **[C]** gaps/audio-events. Confirm `<job>/coverage.json`
+   (last word within ~2s of duration). See `references/scribe-collapse.md`.
+4. **Author the EDL** — read `<job>/word_dump.txt` (and `prompts/author-edl.prompt.md` if present),
+   then write `<job>/edl.json` per the brief below. To inspect any moment visually:
+   `video-editing inspect --job-dir "<job>" --video vertical_src --start <a> --end <b>`.
+   (Or let the CLI scaffold the prompt: `video-editing cut-bad-retakes --job-dir "<job>"`.)
+5. **Render preview** — `video-editing render --job-dir "<job>" --mode preview`.
+   Render **auto-runs the amplitude silence-trim pass** (Gate 3) first: it scans the audio
+   with `silencedetect` and excises every sub-floor silence the transcript can't see —
+   pauses baked *inside* a stretched word token, room tone, breaths — then trims silent
+   range edges. Your authored `edl.json` is backed up to `edl.raw.json` and rewritten with
+   the tightened ranges (more ranges, shorter total). It is **transcript-aware**: it never
+   splits inside a single word token (spelled acronyms like "WWX", held vowels, numbers).
+   Tune or disable: `video-editing desilence --job-dir "<job>"` (flags below) /
+   `render … --no-desilence`.
+6. **GATE 2 — CONTENT-VERIFY** — `video-editing verify --job-dir "<job>" --json`.
+   It re-transcribes the preview at every join (healing OFF) and flags duplicated phrases
+   across a join (= a retake left in) and over-long gaps (= dead air). Adjudicate with
+   `video-editing inspect --job-dir "<job>" --join <i>`. See `references/adversarial-review.md`.
+7. **Fix → re-render → re-verify** until `verify` is clean (`references/fix` rules apply).
+8. **Final** — `video-editing render --job-dir "<job>" --mode final`.
+
+## The standing editing brief (apply exactly)
+
+- Output **VERTICAL 9:16**, **CLEAN CUTS ONLY** (`grade:"none"`, no subtitles, no overlays).
+- **CUT** bad retakes / false starts / cut-off / stuttered words — keep the **LAST complete take**,
+  BUT keep the **CLEANEST** take when an earlier take is clean and a later one stutters.
+- **TIGHTEN every pause** to ~0.12–0.14s of air (remove dead air). The render's amplitude
+  pass (Gate 3) enforces this automatically — it cuts **every silence below the dB floor**
+  (default −36 dB, pauses ≥0.14s, leaving ~0.09s air). This catches the silences the
+  transcript misses (dead air baked inside a long word token, room tone, breaths). It runs
+  on every render; you don't hand-tighten silences in the EDL.
+- **CUT ALL SILENCES below the dB floor** — for a more/less aggressive cut, tune the pass:
+  `video-editing desilence --job-dir "<job>" --noise-db -39 --min-silence 0.30` (gentler) or
+  `--noise-db -34 --min-silence 0.12 --lead-pad 0.03 --trail-pad 0.04` (harder). Re-render +
+  re-verify after. To start clean, restore `cp edl.raw.json edl.json` then re-run.
+- **COLD-OPEN** on the strongest hook (trim weak/dead intro).
+- **TRIM outro dead air** (trailing breaths/ambient/silence/device noise).
+- **KEEP intentional rhetorical repeats.**
+- Never cut inside a word — snap every edge to a transcript word boundary; pad cut edges
+  30–200ms (lead ~0.05s, trail ~0.08s; ~0.03–0.05s at retake joins, staying inside the silence).
+  The renderer adds 30ms audio fades, so tight pads are safe.
+- Hebrew/RTL: read the transcript word-by-word with explicit timestamps to avoid reorder confusion.
+
+## The gates
+
+1. **SCREEN before cutting** — Scribe hides retakes in over-long/dropped tokens; always read `flags.txt` first.
+2. **DESILENCE on render** (automatic) — the amplitude pass cuts every sub-dB-floor silence the
+   transcript can't see and trims silent edges. Transcript-aware (won't split spelled acronyms).
+3. **CONTENT-VERIFY after preview** — `video-editing verify` re-transcribes joins; a waveform/visual check
+   alone does NOT catch a retake left in (abandoned take + keeper render as one continuous clean span).
+   A **≥3-word** duplicate across a join = a real retake left in → **error**, fix it. A bare **2-word**
+   repeat = **warning**: adjudicate with `inspect` — it is usually a spelled acronym / number / emphasis
+   (e.g. "WW" → "דבל יו דבל יו"), not a retake, and is safe to keep.
+
+## EDL format
+
+```json
+{
+  "version": 1,
+  "sources": {"SRC": "<job>/vertical_src.mp4"},
+  "grade": "none",
+  "ranges": [
+    {"source": "SRC", "start": 11.35, "end": 14.12, "beat": "HOOK", "quote": "…", "reason": "cleanest take; stops before the slip at 38.46"}
+  ],
+  "overlays": [],
+  "total_duration_s": 51.33
+}
+```
+
+Ranges are KEEP segments in source seconds; the gaps between them are the cuts. A retake range
+must END at the **last clean word before the abandoned attempt**. `total_duration_s` = Σ(end−start).
+
+## Timeline v2 (preferred when present)
+
+When the CLI exposes a `timeline compile` verb (run `video-editing timeline --help`),
+**author `<job>/timeline.json` instead of hand-writing `edl.json`.** timeline.json is the
+single authored artifact: cuts (keep-ranges) plus optional **captions, zooms, overlays, and
+audio blocks**. The compiler is compiler-grade — it validates, resolves phrase anchors to exact
+source seconds, and emits `resolved/plan.json`, `resolved/diagnostics.json`, and a legacy
+`edl.json`.
+
+**Prerequisite — bake the vertical master first.** `timeline compile` probes
+`<job>/vertical_src.mp4`, and `transcribe` alone does NOT create it: after transcribing, run
+`video-editing cut-bad-retakes --job-dir "<job>" --render none` once (it bakes the vertical
+master AND writes the screening artifacts the SCREEN gate needs anyway). Skipping this makes
+`timeline compile` fail with a raw ffprobe "No such file or directory" — that error means run
+the bake, not that your timeline is wrong.
+
+Loop until clean:
+
+1. Author/patch `<job>/timeline.json`.
+2. `video-editing timeline compile --job-dir "<job>" --json` — read the diagnostics and iterate
+   until it exits **0**:
+   - **exit 2 = validation failed** (schema / semantic / capability) — fix the reported `path`s.
+   - **exit 3 = ambiguous anchor** — disambiguate with
+     `video-editing timeline resolve --phrase "…" --near <t>` (or `--occurrence <n>`), then bake the
+     resolved seconds / occurrence into the anchor and re-compile.
+3. **Never hand-edit anything under `resolved/`** — it is generated; re-compile instead.
+4. compile emits the legacy `edl.json`, so the **render → desilence → verify → final** steps are
+   **unchanged** — run them exactly as in the workflow above.
+
+**Phrase → seconds ONLY via `timeline resolve`.** Never eyeball `word_dump.txt` for anchor
+times — `resolve` returns word-accurate `start`/`end` and flags ambiguity so you disambiguate
+deliberately (`--near <srcSeconds>` or `--occurrence <n>`).
+
+Captions: enable with `video-editing timeline captions generate --job-dir "<job>" [--preset grouped]`
+— cues are **derived at compile**, you don't hand-write cue timings. The default preset `grouped`
+puts up to 4 words in each cue, starting a new cue on long word gaps (>0.6s), cut joins (a cue
+never spans a join), and sentence-ending `.` `?` `!` (same characters in Hebrew); `opus-karaoke`
+is the word-by-word opt-in. Timing/grouping knobs live in `captions.style` in timeline.json:
+`maxWords` (default 4), `leadS` (default 0.08 — each cue appears that many seconds early, clamped
+to the previous cue / segment start), `holdS` (default 0.9 — each cue holds on screen up to that
+long past its last word to bridge the gap to the next cue, killing blink). **Word styling**: an
+`op:"style"` caption override colors and/or emphasizes the anchored words — e.g. "make word X red"
+is `{"op":"style","anchor":{"type":"words","source":"SRC","phrase":"X"},"color":"#ff5c5c"}`;
+`emphasis:"pop"|"highlight"` animates the word at its onset. `captions.style.karaoke: true`
+adds a per-word highlight sweep inside grouped cues (staged). Validate anytime with
+`video-editing timeline validate --job-dir "<job>" --json`.
+
+### Authoring zooms
+
+A zoom is a punch-in on `rect` (unit-canvas crop, `x+w<=1`, `y+h<=1`) at `scale`
+(`1 < scale <= 3`), anchored to a phrase or source span. Static by default (hard in/out).
+For a **ramp**, add `to: {scale?, rect?}` — the zoom animates from the base rect/scale to
+`to` over the zoom window, shaped by `ease: {in, out}` (both > 0 → smooth in-out). Zooms
+resolve onCut like everything else (`clip` default). Full examples:
+`references/timeline-v2-vocabulary.md`.
+
+### Authoring overlays & assets
+
+- Text: `kind:"text"` (positioned) / `kind:"title-card"` (full-frame card) + `text`.
+- **Image/sticker**: `kind:"sticker"` (or `"image"`) + `asset: {ref: "assets/logo.png"}` —
+  `ref` is a **job-dir-relative path**; keep files under `<job>/assets/`. Position with
+  `layout.x/y` (center), size with `size.w/h` (canvas fractions; sticker default ~0.25 of
+  width), stack with `z` (0–50). Animate with `enter`/`exit`
+  (`{preset: fade|pop|slide-up|slide-down|scale-in, durationS ≤ 2}`).
+- A referenced file that does not exist fails `timeline compile` with `asset-missing` —
+  put the file in place first.
+- On `review push --timeline` / `--complete`, referenced assets are **uploaded to
+  clipready automatically** (sha256-cached in `<job>/review/assets.json`, so unchanged
+  files are never re-uploaded); the push payload carries the `{ref: asset_id}` manifest.
+- `compose` copies referenced assets into `<job>/composition/media/` and renders them.
+
+### Delivering captions/zooms
+
+The ffmpeg `render --mode final` path is **CUT-ONLY** — it never draws the compiled
+captions/zooms/overlays from `resolved/plan.json`. Deliver those visual layers with either:
+
+- **`video-editing compose --job-dir "<job>" --render`** — local and free. Builds a declarative
+  HyperFrames composition in `<job>/composition/` (compressed proxy of `vertical_src.mp4`,
+  the CONTINUOUS cut audio extracted from `preview.mp4`, and `index.html`) and renders it with
+  the `hyperframes` CLI (needs it on PATH: `npm install -g hyperframes`). Prerequisites:
+  `resolved/plan.json` (run `timeline compile`) and `preview.mp4` (run `render --mode preview`).
+  Without `--render` it only builds the composition and prints the exact `hyperframes render`
+  command to run. Output defaults to `<job>/composed.mp4`.
+- **The ClipReady cloud render** (`cloud render`), which renders the same plan server-side
+  (requires a ClipReady account + API key — see the review-round section below).
+
+Do **NOT** fall back to the legacy `render --build-subtitles` ASS burn for timeline-v2 jobs —
+it requires a libass ffmpeg and renders the old 2-word subtitle style, not the compiled cues.
+
+### Working a ClipReady review round
+
+> Cloud features require a ClipReady account + API key (`CLIPREADY_API_BASE`, `CLIPREADY_API_KEY`).
+
+When the job is a clipready review round (you have an API base + credential + video id), the
+CLI syncs the round for you — no hand-rolled curl:
+
+1. `video-editing review pull --job-dir "<job>"` — writes `<job>/review/round.json` (run id,
+   requested changes) and `<job>/review/instruction.md`, and hydrates `<job>/timeline.json`
+   from the server when you don't already have one (it never overwrites a local timeline).
+   Add `--source` if the source video isn't local yet.
+2. `video-editing review push --stage edl --job-dir "<job>"` when you start working the round.
+3. Edit `timeline.json` per the instruction, then
+   `video-editing review push --timeline --job-dir "<job>"` after each meaningful change — it
+   compiles locally (diagnostics + exit 2 if not clean) and the review page updates live.
+4. Preview/verify locally exactly as in the workflow above (render preview, CONTENT-VERIFY, QC).
+5. `video-editing review push --complete --duration <s> --outcomes outcomes.json --job-dir "<job>"`
+   — compiles fresh (must be clean) and delivers the terminal payload (edl + timeline + plan).
+   `outcomes.json` is `[{"change_id": "chg_…", "ok": true, "note": "…"}]`, one entry per
+   `[chg_…]` marker in the instruction; omit `--outcomes` when there are no markers.
+
+## References
+
+- `references/cli-reference.md` — every subcommand + flag (incl. `verify`, `inspect`).
+- `references/timeline-v2-vocabulary.md` — the full timeline.json v2 vocabulary, one JSON
+  example per feature (word styling, karaoke, zoom ramps, stickers, enter/exit, grade).
+- `references/editing-brief.md` — the full EDL-authoring procedure.
+- `references/hard-rules.md` — production-correctness rules + anti-patterns.
+- `references/scribe-collapse.md` — why retakes hide in the transcript (Gate 1).
+- `references/adversarial-review.md` — the content-verify pass (Gate 2).

package/skills/video-editing/references/adversarial-review.md

@@ -0,0 +1,44 @@
+# Gate 2 — content-verify after preview
+
+A single editing pass leaves retakes in. The reliable failure mode: the abandoned
+first attempt and the keeper render as **one continuous clean-audio span**, so a
+waveform / visual self-eval looks perfect while the *content* is duplicated across
+the join. The fix is to **re-transcribe the rendered preview at each join** — which
+is exactly what `video-editing verify` does. Run it for every real cut.
+
+## Run it
+
+```
+video-editing verify --job-dir "<job>" --json
+```
+
+- Default (per-join): re-transcribes a ~6s window centered on each cut boundary
+  (from `cut_boundaries.json`), **healing OFF**.
+- `--full`: re-transcribes the whole preview and also checks head/tail dead air.
+
+It reports, per join:
+- **duplicated phrase across the join** → a retake left in (severity `error`). It only
+  flags **near-adjacent** duplication (the retake fingerprint), not legitimate topical
+  repeats spaced apart.
+- **over-long gap straddling the join** → dead air not tightened (warning, or error if large).
+
+Writes `verify.json` (same shape family as `review.json`); exit code 2 on `needs-fixes`.
+
+## Adjudicate + fix
+
+For any finding, eyeball it: `video-editing inspect --job-dir "<job>" --join <i>` and read
+the PNG (clipped word, leftover false-start syllable, audio pop, broken frame?).
+
+Then FIX the EDL and re-render + re-verify:
+- **Retake still present** → set that range's END at the **last clean word BEFORE the
+  abandoned attempt**.
+- **Intentional repeat wrongly cut** → restore it.
+- **Clipped boundary** → re-snap to the transcript word boundary.
+- **Leading / trailing dead air** → trim it.
+
+Re-snap every edge to a word boundary; keep pads tight (30–200ms); keep `grade:"none"`,
+`overlays:[]`; update `total_duration_s`. Re-render `--mode preview`, re-run `verify`.
+Cap at ~3 fix passes; if findings persist, surface them rather than looping forever.
+
+A real retake left in / an intentional repeat wrongly cut / a clipped word at a join /
+leading-or-trailing dead air ⇒ not clean. Minor taste calls are not defects.

package/skills/video-editing/references/cli-reference.md

@@ -0,0 +1,181 @@
+# `video-editing` CLI reference
+
+All execution goes through this CLI. Quote paths (they contain spaces).
+
+## Pipeline commands
+
+- **`init-job --source <video> [--job-dir <dir>] [--force]`**
+  Probe the source and create the job dir + `source.json`. Always pass `--job-dir`
+  explicitly on the sandbox (e.g. `/vercel/sandbox/jobs/<job_id>`) — there is no
+  `~/Downloads` to default into. Prints the job dir.
+
+- **`transcribe (--source <video> | --job-dir <dir>) [--language <iso>] [--num-speakers <n>] [--no-heal] [--force] [--api-key <key>]`**
+  Word-level ElevenLabs Scribe transcription (auto-heals collapsed/dropped spans)
+  + screening artifacts: `flags.txt`, `takes_packed.md`, `word_dump.txt`, `coverage.json`.
+  Cached per source — `--force` re-transcribes (paid). `--no-heal` disables healing.
+
+- **`cut-silences (--source|--job-dir) [--min-gap 0.30] [--target-gap 0.13] [--lead-pad 0.05] [--trail-pad 0.08] [--render preview|none] [--force-transcribe]`**
+  Prepare a silence-only EDL-authoring prompt (`prompts/cut-silences.prompt.md`);
+  renders a preview if `edl.json` already exists.
+
+- **`cut-bad-retakes (--source|--job-dir) [--with-sound-waves] [--quality-review] [--render preview|none] [--language] [--num-speakers] [--force-transcribe]`**
+  Prepare the full author-edl prompt (`prompts/author-edl.prompt.md`). `--with-sound-waves`
+  writes join QC PNGs (needs `edl.json` + `preview.mp4`). `--quality-review` writes the review prompt.
+
+- **`desilence --job-dir <dir> [--noise-db -36] [--min-silence 0.14] [--lead-pad 0.04] [--trail-pad 0.05] [--render preview|none] [--force]`**  ← Gate 3
+  Amplitude silence-trim. Runs `silencedetect=noise=<db>dB` over each EDL source, then for every
+  keep-range **excises internal silences ≥ `--min-silence`** (leaving `lead-pad + trail-pad` of air)
+  and **trims silent leading/trailing edges**. Catches silence the transcript can't see (dead air
+  baked inside a stretched word token, room tone, breaths). **Transcript-aware** — never splits inside
+  a single word token (spelled acronyms, held vowels, numbers). Backs the original EDL up to
+  `edl.raw.json`, rewrites `edl.json`, marks it `desilenced`. Idempotent. Higher `--noise-db`
+  (e.g. −34) + lower `--min-silence` = more aggressive.
+  **Runs automatically at the start of every `render`** (skip with `render … --no-desilence`); the
+  standalone command is for tuning + inspecting the result before rendering.
+
+- **`render --job-dir <dir> --mode preview|draft|final [--build-subtitles] [--no-subtitles] [--no-loudnorm] [--no-desilence]`**
+  Render the EDL: **desilence (unless `--no-desilence`)** → per-segment extract → lossless concat →
+  (optional subs) → loudnorm (−14 LUFS / −1 dBTP / LRA 11). preview=CRF22/1080p, draft=CRF28/720p,
+  final=CRF20/1080p. Writes `preview.mp4`/`draft.mp4`/`final.mp4` + `cut_boundaries.json`.
+
+## QC / verification commands
+
+- **`verify --job-dir <dir> [--full] [--window 6] [--gap 0.6] [--json] [--api-key <key>]`**  ← Gate 4 (content)
+  Re-transcribes the rendered preview with healing OFF and reports, per join,
+  **duplicated phrases** and **over-long gaps** (dead air not tightened → warning/error).
+  A duplicate of **≥3 words** = a retake left in → **error**. A bare **2-word** repeat = **warning**
+  (spelled acronym / number / emphasis like "WW" → "דבל יו דבל יו" — adjudicate with `inspect`, usually safe).
+  Default: per-join ~6s windows from `cut_boundaries.json`; `--full` re-transcribes the whole preview and
+  also checks head/tail dead air. Writes `verify.json`; exit code 2 if `needs-fixes`.
+
+- **`inspect --job-dir <dir> (--join <i> | --start <s> --end <s>) [--video preview|vertical_src] [--transcript <path>] [-o <png>] [--n-frames 10]`**
+  Filmstrip + waveform + word-label PNG for a window or a cut-boundary index.
+  `timeline` is an alias. Use it to adjudicate a verify finding or pick a cut edge.
+
+## TimelineV2 commands (`timeline.json` v2 — preferred when present)
+
+Exit codes for this group: `0` ok, `1` error, `2` validation failed, `3` ambiguous anchor.
+
+- **`timeline validate --job-dir <dir> [--json]`**
+  Schema + semantic + capability validation of `<job>/timeline.json`. Prints errors/warnings and
+  the capabilities the doc `uses`. Exit `2` if invalid.
+
+- **`timeline compile --job-dir <dir> [--json]`**
+  Compile `timeline.json` → `resolved/plan.json` + `resolved/diagnostics.json` + **legacy `edl.json`**
+  (so render/verify are unchanged). Iterate until it exits `0`. Exit `2` = validation failed,
+  `3` = an ambiguous phrase anchor (disambiguate with `timeline resolve`). Never hand-edit `resolved/`.
+
+- **`timeline resolve --job-dir <dir> --phrase <text> [--near <srcSeconds>] [--occurrence <n>] [--source <name>] [--json]`**
+  Resolve a transcript phrase to **exact source seconds** (normalized, word-accurate match). The
+  ONLY way to turn a phrase into an anchor time — never eyeball `word_dump.txt`. Multiple hits →
+  exit `3` with per-occurrence context; pick one with `--near` (nearest source time) or
+  `--occurrence` (1-based). Not found → fuzzy suggestions, exit `1`.
+
+- **`timeline captions generate --job-dir <dir> [--preset grouped|opus-karaoke] [--json]`**
+  Enable captions in `timeline.json` (preset only — cues are **derived at compile**, not hand-authored).
+  Default preset `grouped`: up to `captions.style.maxWords` (default 4) words per cue, breaking on
+  word gaps >0.6s, cut joins, and sentence-ending `.` `?` `!`; `opus-karaoke` is the word-by-word
+  opt-in. Style knobs in `captions.style`: `maxWords` (4), `leadS` (0.08 — cues display that early,
+  clamped), `holdS` (0.9 — cues hold to bridge the gap to the next cue). Reports the derived cue
+  count via a dry compile.
+
+- **`compose --job-dir <dir> [--render] [--quality draft|standard|high] [--fps 30] [--out <path>] [--proxy-crf 23] [--json]`**
+  Build a local HyperFrames composition from `resolved/plan.json` (cut + captions/zooms/overlays)
+  in `<job>/composition/`: `media/source.mp4` (compressed proxy of `vertical_src.mp4`, libx264
+  CRF `--proxy-crf`, skipped when up to date), `media/audio.m4a` (the CONTINUOUS cut audio
+  extracted from `preview.mp4` — the QC preview must exist), referenced image/sticker assets
+  copied under `media/` (preserving their job-dir-relative paths), and `index.html` (with a
+  generated GSAP timeline when the plan uses animated vocabulary). Without `--render`,
+  prints the composition dir + the exact `hyperframes render` command. With `--render`, runs
+  `hyperframes render --quality <q> --fps <n> --output <out>` (default `<job>/composed.mp4`)
+  in the composition dir — requires the `hyperframes` CLI on PATH (`npm install -g hyperframes`).
+  `--json` prints `{compositionDir, entry, out?, segments, cues, zooms, overlays}`. This is the
+  LOCAL delivery path for compiled captions/zooms — the ffmpeg `render` is cut-only; never use
+  `--build-subtitles` for timeline-v2 jobs.
+
+## Cloud thin-client commands (clipready render/QA/artifact API)
+
+Every cloud verb resolves credentials the same way and supports `--json` (machine shape;
+exit `0` ok, `1` error). Resolution precedence:
+
+- **base**: `--api-base` → env `CLIPREADY_API_BASE` → env `API_BASE`
+- **credential** (sent as `Authorization: Bearer <credential>`): `--api-key` → env `CLIPREADY_API_KEY` → env `RUN_TOKEN`
+- **video id**: `--video-id` → env `VIDEO_ID`
+
+A missing base / credential / (required) video id is a clear error → exit `1`.
+
+- **`cloud render --job-dir <dir> --mode preview|final [--wait] [--poll-interval 10] [--out <path>] [--json]`**
+  Submit a render. Without `--wait`: prints `render_id` and exits `0`. With `--wait`: polls status
+  (max 30 min) until terminal; on `completed`, downloads the signed `video_url` to `--out`
+  (default `<job>/preview.mp4` or `<job>/final.mp4`). `failed` → exit `1` with the error. Needs a video id.
+
+- **`cloud status <render_id> [--json]`**
+  One status GET: `pending|running|completed|failed` (+ `video_url` when completed). `failed` → exit `1`.
+
+- **`qa frames --start <s> --end <s> [--cols <n>] [--interval <s>] [--job-dir <dir>] [--json]`**
+  Server-render a filmstrip PNG for the window and download it to `<job>/qa/frames_<start>_<end>.png`
+  (`./qa/` when no `--job-dir`). Prints the local path + grid metadata (Read the PNG to inspect). Needs a video id.
+
+- **`qa waveform --start <s> --end <s> [--job-dir <dir>] [--json]`**
+  Same, for a waveform: downloads `<job>/qa/waveform_<start>_<end>.png` and writes the word list to
+  `<job>/qa/waveform_<start>_<end>.words.json`. Prints both paths. Needs a video id.
+
+- **`job pull [--job-dir <dir>] [--only <name,name>] [--json]`**
+  List the video's artifacts and fetch each (or the `--only` subset) into the job dir (default cwd),
+  **preserving relative paths** (`resolved/plan.json` → `<job>/resolved/plan.json`). Prints a summary.
+  `.json` artifacts are written pretty-printed; others verbatim. Needs a video id. Allowlisted names include
+  `word_dump.txt`, `takes_packed.md`, `flags.txt`, `coverage.json`, `edl.json`, `verify.json`,
+  `cut_boundaries.json`, `timeline.json`, `resolved/plan.json`, `resolved/diagnostics.json`.
+
+- **`review pull [--job-dir <dir>] [--source] [--json]`**
+  Fetch the clipready review session for the video into the job dir (default cwd): writes
+  `<job>/review/round.json` (round/run ids, mode, status, requested changes) and
+  `<job>/review/instruction.md` (the round's editorial instruction — or a "no active round" note).
+  Writes `<job>/timeline.json` from the session ONLY when no local timeline.json exists (never
+  overwrites yours). With `--source`, also downloads the source video (to the `source.json`
+  filename, else `<job>/source.mp4`) when absent locally. Needs a video id.
+
+- **`review push (--stage <type> [--message <text>] | --timeline | --complete --duration <s> [--outcomes <file>]) [--job-dir <dir>] [--run-id <id>] [--json]`**
+  Push review-round events (exactly one mode per call; run id defaults to `review/round.json`
+  from `review pull`). `--stage` posts a progress event
+  (`provisioning|transcribing|edl|render_preview|qc|render_final|uploading|log`), optional
+  `{message}` payload. `--timeline` compiles `<job>/timeline.json` locally (same sequence as
+  `timeline compile`, needs ffmpeg) and pushes a `timeline_update` with the raw timeline JSON,
+  the compiled plan, and its hash — 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?}]`, bare array or `{outcomes: [...]}`). Compile failures print
+  diagnostics and exit `2` (nothing is pushed); cloud errors exit `1`. Needs a video id.
+  Both `--timeline` and `--complete` **upload the timeline's referenced assets
+  automatically** (image/sticker overlays, audio beds): each ref is sha256-cached in
+  `<job>/review/assets.json` so unchanged files are never re-uploaded, and the push
+  payload includes an `assets: {ref: asset_id}` manifest. A missing asset file fails the
+  compile (`asset-missing`) before anything is uploaded.
+
+- **`skill install [--target <dir>] [--json]`**
+  Copy the bundled `video-editing` agent skill into `<target|~/.claude/skills>/video-editing`
+  (overwriting). Prints what was installed.
+
+## Utility
+
+- **`--version`** — print the CLI version.
+- **`status --job-dir <dir> [--json]`** — job state + artifact existence.
+- **`review prompt --job-dir <dir> [--write-warnings]`** — write the review prompt;
+  optionally convert `review.json` → `warnings.json`. (`--open-app` is not usable on the
+  sandbox — it launches a local browser; skip it, there is no display.) This was the old
+  top-level `review` verb — `review` is now a group (`prompt` / `pull` / `push`).
+- **`config set-key <key>` / `config path`** — manage the ElevenLabs key
+  (`~/.config/video-editing/.env`; on the sandbox the CLI reads env `ELEVENLABS_API_KEY`,
+  no need to run `config set-key`).
+
+## Typical session
+
+```
+video-editing init-job --source "source.mp4" --job-dir /vercel/sandbox/jobs/<job_id>
+video-editing transcribe --job-dir /vercel/sandbox/jobs/<job_id>
+# read flags.txt (Gate 1), author edl.json
+video-editing render --job-dir /vercel/sandbox/jobs/<job_id> --mode preview
+video-editing verify --job-dir /vercel/sandbox/jobs/<job_id> --json   # Gate 2
+# fix edl.json as needed, re-render, re-verify
+video-editing render --job-dir /vercel/sandbox/jobs/<job_id> --mode final
+```

package/skills/video-editing/references/editing-brief.md

@@ -0,0 +1,44 @@
+# Editing brief — authoring the EDL
+
+The standing style for a single talking-head vertical reel and the exact
+step-by-step for authoring `<job>/edl.json`. All execution is via the
+`video-editing` CLI; you only write the EDL.
+
+## Standing brief (apply exactly)
+
+- **Output VERTICAL 9:16.** The CLI bakes `vertical_src.mp4`; point the EDL at it.
+- **CUT:** bad retakes, false starts, cut-off / stuttered words — keep the **LAST
+  complete take**, EXCEPT keep the **CLEANEST** take when an earlier take is clean
+  and a later one stutters into completion.
+- **TIGHTEN EVERY PAUSE:** trim 0.3–1s inter-phrase gaps down to ~0.12–0.14s of air.
+- **COLD-OPEN** on the strongest hook (trim weak/dead intro).
+- **TRIM outro dead air** (footsteps / ambient / silence / trailing breaths / device noise).
+- **CLEAN CUTS ONLY:** `grade:"none"`, no subtitles, no overlays.
+- **KEEP intentional rhetorical repeats.**
+
+### Retake-vs-intentional discriminator (for a flagged repeated phrase)
+
+- **RETAKE** (cut it, keep the last/cleanest complete pass) if the earlier
+  instance cuts off mid-word (a fragment / trailing "-") OR is immediately restarted.
+- **INTENTIONAL** (keep BOTH) if both instances are complete and serve rhetoric /
+  parallel structure and are separated by other content.
+- Decide every flagged repeat — never blind-cut.
+
+## Steps
+
+1. **Init + transcribe + screen** (CLI does these): `init-job` → `transcribe`.
+   Then read `<job>/flags.txt` (Gate 1) and confirm `<job>/coverage.json`.
+2. **Read the word-level transcript** at `<job>/word_dump.txt` (every word/audio_event
+   as `[start-end] type: text` with `---- gap Xs ----` at gaps ≥0.30s). THINK HARD and
+   list, with exact timestamps: every retake/false-start/stutter (and which take to KEEP),
+   every silence (head/inter-phrase/outro), the cold-open point, the intentional repeats.
+   When text and audio seem to disagree, `video-editing inspect --video vertical_src --start <a> --end <b>` and read the PNG.
+3. **Write `<job>/edl.json`** — KEEP segments in source seconds; gaps between them are
+   the cuts. Snap every in/out to a transcript word boundary (lead ~0.05s, trail ~0.08s;
+   ~0.03–0.05s at retake joins, clamped to stay inside the silence and never include a
+   false-start word). Ranges chronological, non-overlapping. `total_duration_s` = Σ(end−start).
+   **A retake range must END at the LAST CLEAN WORD before the abandoned attempt.**
+4. **Render** `--mode preview`, then **verify** (Gate 2), fix, repeat. Finalize `--mode final`.
+
+See `cli-reference.md` for exact commands, `hard-rules.md` for correctness, and
+`scribe-collapse.md` / `adversarial-review.md` for the two gates.

package/skills/video-editing/references/hard-rules.md

@@ -0,0 +1,38 @@
+# Hard rules (production correctness — non-negotiable)
+
+These produce **silent failures** if violated. The CLI enforces the rendering
+rules internally; the EDL-authoring rules are on you.
+
+## The CLI guarantees (do not try to replicate by hand)
+
+- **Per-segment extract → lossless `-c copy` concat** (no double-encode).
+- **30ms audio fades at every segment boundary** (`afade` in/out) — which is why
+  tight pads (down to ~30ms) at retake joins are safe.
+- **Loudnorm** to −14 LUFS / −1 dBTP / LRA 11 (two-pass for final, one-pass for preview).
+- Subtitles, if ever enabled, are applied LAST in the filter chain.
+- Word-level verbatim ASR with auto-heal; transcripts cached per source.
+
+## EDL-authoring rules (yours to uphold)
+
+- **Never cut inside a word.** Snap every edge to a transcript word boundary.
+- **Pad every cut edge** (30–200ms). Scribe timestamps drift 50–100ms; padding absorbs it.
+  Tightest (~0.03–0.05s) at retake joins, staying inside the silence.
+- A **retake range ends at the last clean word BEFORE the abandoned attempt.**
+- Clipped tokens ending in `-` (`s-`, `re-`, `li-`) are danger zones — leave an 80–150ms
+  guard band before them when there's room.
+- Keep the first token of the chosen take even if it's a connector ("and/so/but").
+- `grade:"none"`, `overlays:[]`, no subtitles (clean-cut pass).
+- Keep `total_duration_s` = Σ(end−start); ranges chronological + non-overlapping.
+
+## The two mandatory gates
+
+1. **SCREEN before cutting** — read `flags.txt`; resolve every [A], judge every [B]. See `scribe-collapse.md`.
+2. **CONTENT-VERIFY after preview** — `video-editing verify`; a visual/waveform check alone
+   misses a retake left in. See `adversarial-review.md`.
+
+## Anti-patterns (consistently fail)
+
+- Trusting the transcript without screening it (Scribe collapses/drops hide retakes).
+- Running ffmpeg or ad-hoc helper scripts by hand — forbidden; use only the `video-editing` CLI.
+- A visual-only check at a retake join (the duplicated content reads as continuous clean audio).
+- Re-transcribing an unchanged source (paid + pointless; it's cached).

package/skills/video-editing/references/scribe-collapse.md

@@ -0,0 +1,37 @@
+# Gate 1 — the Scribe collapse / drop gotcha
+
+The single most important thing before reasoning about cuts: **retakes hide in
+the transcript.** Trust the text without screening and you will leave duplicated
+content in the cut.
+
+## What happens
+
+When Scribe hits a hard-to-segment chunk (fast speech, a stutter, a false start
+immediately followed by the retake), it sometimes:
+
+- **Collapses** the chunk into ONE over-long token (a "word" lasting >~1.2s), or
+- **Drops** a stretch of audio silently — no tokens for that span.
+
+Either way the retake is invisible in the text, a waveform looks fine, and the
+cut "reads" clean — but the abandoned take is still in the render.
+
+## How the CLI + you catch it
+
+1. **`video-editing transcribe` auto-heals** most collapses/drops (re-transcribes the
+   suspect window in isolation and splices the recovered words back). Watch its log.
+2. **`video-editing transcribe` writes `flags.txt`** — read it (Gate 1):
+   - **[A]** over-long / collapsed tokens (>~1.2s) — content is hidden inside one of these.
+   - **[B]** repeated phrases — the retake fingerprint (false starts, reworded restarts).
+   - **[C]** audio events + big gaps.
+   Resolve every [A]; judge every [B] (retake vs intentional).
+3. **Verify coverage** via `coverage.json`: the last word must end within ~2s of the
+   media duration. If it ends well before EOF, a tail was dropped.
+
+## When a span is still suspect
+
+Inspect it: `video-editing inspect --job-dir <job> --video vertical_src --start <a> --end <b>`
+and read the filmstrip+waveform PNG to see what was actually said before choosing the cut.
+
+> Screening + inspecting suspicious windows is what isolates retakes Scribe collapsed
+> into one token. Skipping it is the #1 cause of a "clean-looking" cut that still has a
+> retake in it.