video-editing 1.3.1 → 3.0.0

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

@@ -1,181 +1,186 @@
-# `video-editing` CLI reference
+# `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` → 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 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).
+
+**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.
 
 ## 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.
+- **`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]`**
-  Schema + semantic + capability validation of `<job>/timeline.json`. Prints errors/warnings and
-  the capabilities the doc `uses`. 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 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> [--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 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 compile --job-dir <dir> [--json]`**
+  **Cloud compile**: uploads `timeline.json`, the server validates, resolves
+  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/`.
 
 - **`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.
+  Enable captions in `timeline.json` (preset only), then server-compile to
+  derive/report cues.
+
+## Render commands
+
+- **`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 --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 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.
+  One status GET: `pending|running|completed|failed` (+ `video_url` when
+  completed). `failed` → exit `1`.
+
+## Verification / QA commands
+
+- **`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, 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 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`). Byte-exact, sha256-skipped. Use to
+  recover job state on a fresh machine.
+
+- **`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)
+
+- **`review pull --job-dir <dir> [--source] [--json]`**
+  Fetch the review session: writes `<job>/review/round.json` (round/run ids,
+  mode, status, requested changes) and `<job>/review/instruction.md`. Writes
+  `<job>/timeline.json` from the session ONLY when no local one exists (never
+  overwrites yours). `--source` also downloads the source video when absent.
+
+- **`review push (--stage <type> [--message <text>] | --timeline | --complete --duration <s> [--outcomes <file>]) --job-dir <dir> [--run-id <id>] [--json]`**
+  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` 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]`** — 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`).
+- **`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
 
 ```
-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
+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 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
 ```

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

@@ -1,44 +1,4 @@
-# Editing brief — authoring the EDL
+# Editing brief (moved server-side)
 
-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.
+The full editorial brief now arrives from the ClipReady cloud as `<job>/prompts/author-edl.prompt.md`
+(pulled by `video-editing transcribe` / `files pull`). Read and follow the pulled prompts — this file is a stub.

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

@@ -1,38 +1,4 @@
-# Hard rules (production correctness — non-negotiable)
+# Hard rules (moved server-side)
 
-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).
+The production-correctness rules now arrive from the ClipReady cloud inside `<job>/prompts/*.md`
+(pulled by `video-editing transcribe` / `files pull`). Read and follow the pulled prompts — this file is a stub.

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

@@ -1,37 +1,4 @@
-# Gate 1 — the Scribe collapse / drop gotcha
+# Screening gate (moved server-side)
 
-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.
+The transcript-screening procedure (Gate 1) now arrives from the ClipReady cloud inside `<job>/prompts/*.md`
+(pulled by `video-editing transcribe` / `files pull`). Read and follow the pulled prompts — this file is a stub.

package/skills/video-editing/references/timeline-v2-vocabulary.md

@@ -2,8 +2,8 @@
 
 Every feature of the authored `<job>/timeline.json` (version 2), with one minimal JSON
 example each. Validate with `video-editing timeline validate`; compile with
-`timeline compile` (it resolves phrase anchors, derives caption cues and emits
-`resolved/plan.json` + legacy `edl.json`). Items all carry a unique `id`; word anchors
+`timeline compile` (cloud compile — it resolves phrase anchors, derives caption cues
+and emits `resolved/plan.json`). Items all carry a unique `id`; word anchors
 (`{type:"words", source, phrase}`) resolve via the transcript — use `timeline resolve`
 to disambiguate. Capability status per feature: run `timeline validate` — `staged`
 features compile but warn (render path not yet proven); `ready` features render via