video-editing 1.3.1

package/dist/cli.js

@@ -0,0 +1,1594 @@
+#!/usr/bin/env node
+import {
+  COMPOSE_ENTRY,
+  DEFAULT_DESILENCE,
+  artifactPaths,
+  checkCapabilities,
+  compileTimeline,
+  composeCounts,
+  composeHtml,
+  configDir,
+  configEnvPath,
+  cutBoundaries,
+  desilenceEdl,
+  edlPath,
+  ensureTranscribed,
+  ensureVerticalMaster,
+  formatDiagnostics,
+  gatherCompileCtx,
+  generateQcImages,
+  loadTimeline,
+  planPath,
+  readEdl,
+  render,
+  resolvePhrase,
+  statusPayload,
+  timelineJsonPath,
+  timelineView,
+  transcriptFileForSource,
+  updateCaptionsBlock,
+  usesFromDoc,
+  validateTimeline,
+  verify,
+  wordStream,
+  writeAgentManifest,
+  writeBoundaries,
+  writeCompileArtifacts,
+  writeSilencePrompt,
+  writeVideoEditingPrompt,
+  writeWarningsFromReview
+} from "./chunk-63HIQBDT.js";
+import {
+  initJob,
+  loadJob,
+  mediaDuration,
+  requireFfmpeg,
+  resolveJob,
+  run,
+  runSync,
+  shown
+} from "./chunk-CU3NBKB4.js";
+
+// src/cli.ts
+import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync2, statSync as statSync3, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname4, join as join5, resolve as resolvePath } from "path";
+import { Command } from "commander";
+
+// src/cloud/client.ts
+import { createWriteStream, mkdirSync, statSync, writeFileSync } from "fs";
+import { dirname, join as pathJoin } from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_DOWNLOAD_TIMEOUT_MS = 3e5;
+function firstNonEmpty(...vals) {
+  for (const v of vals) {
+    if (typeof v === "string" && v.trim() !== "") return v.trim();
+  }
+  return void 0;
+}
+function resolveApiBase(flag, env = process.env) {
+  return firstNonEmpty(flag, env.CLIPREADY_API_BASE, env.API_BASE);
+}
+function resolveApiKey(flag, env = process.env) {
+  return firstNonEmpty(flag, env.CLIPREADY_API_KEY, env.RUN_TOKEN);
+}
+function resolveVideoId(flag, env = process.env) {
+  return firstNonEmpty(flag, env.VIDEO_ID);
+}
+function stripTrailingSlash(base) {
+  return base.replace(/\/+$/, "");
+}
+function resolveConfig(flags, opts = {}, env = process.env) {
+  const base = resolveApiBase(flags.apiBase, env);
+  if (!base) {
+    throw new Error("missing API base URL \u2014 pass --api-base or set CLIPREADY_API_BASE (or API_BASE)");
+  }
+  const credential = resolveApiKey(flags.apiKey, env);
+  if (!credential) {
+    throw new Error("missing API credential \u2014 pass --api-key or set CLIPREADY_API_KEY (or RUN_TOKEN)");
+  }
+  const videoId = resolveVideoId(flags.videoId, env);
+  if (opts.requireVideoId && !videoId) {
+    throw new Error("missing video id \u2014 pass --video-id or set VIDEO_ID");
+  }
+  return { base: stripTrailingSlash(base), credential, videoId };
+}
+function rendersUrl(base) {
+  return `${stripTrailingSlash(base)}/api/v1/renders`;
+}
+function renderUrl(base, renderId) {
+  return `${stripTrailingSlash(base)}/api/v1/renders/${encodeURIComponent(renderId)}`;
+}
+function qaUrl(base, videoId) {
+  return `${stripTrailingSlash(base)}/api/v1/videos/${encodeURIComponent(videoId)}/qa`;
+}
+function reviewUrl(base, videoId) {
+  return `${stripTrailingSlash(base)}/api/v1/videos/${encodeURIComponent(videoId)}/review`;
+}
+function artifactsUrl(base, videoId, name) {
+  const root = `${stripTrailingSlash(base)}/api/v1/videos/${encodeURIComponent(videoId)}/artifacts`;
+  return name ? `${root}?name=${encodeURIComponent(name)}` : root;
+}
+function assetsUrl(base) {
+  return `${stripTrailingSlash(base)}/api/v1/assets`;
+}
+function artifactLocalPath(jobDir, name) {
+  const parts = name.split("/").filter((p) => p !== "" && p !== "." && p !== "..");
+  return pathJoin(jobDir, ...parts);
+}
+function asRecord(data, ctx) {
+  if (data === null || typeof data !== "object") throw new Error(`unexpected ${ctx} response: ${JSON.stringify(data)}`);
+  return data;
+}
+function parseRenderCreate(data) {
+  const o = asRecord(data, "render-create");
+  const renderId = o.render_id;
+  if (typeof renderId !== "string" || renderId === "") throw new Error(`render response missing render_id: ${JSON.stringify(data)}`);
+  return { renderId, status: o.status ?? "pending" };
+}
+function parseRenderState(data) {
+  const o = asRecord(data, "render-status");
+  const status = o.status;
+  if (typeof status !== "string") throw new Error(`render status response missing status: ${JSON.stringify(data)}`);
+  return {
+    status,
+    videoUrl: typeof o.video_url === "string" ? o.video_url : void 0,
+    error: o.error
+  };
+}
+function isTerminalStatus(s) {
+  return s === "completed" || s === "failed";
+}
+function parseArtifactList(data) {
+  const o = asRecord(data, "artifact-list");
+  const arr = o.artifacts;
+  if (!Array.isArray(arr)) throw new Error(`artifact list response missing artifacts[]: ${JSON.stringify(data)}`);
+  return arr.filter((n) => typeof n === "string");
+}
+function parseArtifactContent(data) {
+  const o = asRecord(data, "artifact");
+  const name = o.name;
+  if (typeof name !== "string") throw new Error(`artifact response missing name: ${JSON.stringify(data)}`);
+  return { name, content: o.content };
+}
+function parseAssetCreate(data) {
+  const o = asRecord(data, "asset-create");
+  const assetId = o.asset_id;
+  const uploadUrl = o.upload_url;
+  if (typeof assetId !== "string" || assetId === "") {
+    throw new Error(`asset create response missing asset_id: ${JSON.stringify(data)}`);
+  }
+  if (typeof uploadUrl !== "string" || uploadUrl === "") {
+    throw new Error(`asset create response missing upload_url: ${JSON.stringify(data)}`);
+  }
+  return { assetId, uploadUrl };
+}
+function parseQaFrames(data) {
+  const o = asRecord(data, "qa-frames");
+  if (typeof o.url !== "string") throw new Error(`qa frames response missing url: ${JSON.stringify(data)}`);
+  return {
+    url: o.url,
+    width: Number(o.width ?? 0),
+    height: Number(o.height ?? 0),
+    frames: Number(o.frames ?? 0),
+    tStart: Number(o.tStart ?? 0),
+    tEnd: Number(o.tEnd ?? 0)
+  };
+}
+function parseQaWaveform(data) {
+  const o = asRecord(data, "qa-waveform");
+  if (typeof o.url !== "string") throw new Error(`qa waveform response missing url: ${JSON.stringify(data)}`);
+  const words = Array.isArray(o.words) ? o.words.map((w) => {
+    const r = w;
+    return { t: Number(r.t ?? 0), end: Number(r.end ?? 0), text: String(r.text ?? "") };
+  }) : [];
+  return { url: o.url, words };
+}
+function numOrNull(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function strOrNull(v) {
+  return typeof v === "string" ? v : null;
+}
+function parseReviewSession(data) {
+  const o = asRecord(data, "review-session");
+  const videoId = o.video_id;
+  if (typeof videoId !== "string" || videoId === "") {
+    throw new Error(`review session response missing video_id: ${JSON.stringify(data)}`);
+  }
+  let activeRound = null;
+  if (o.active_round !== null && o.active_round !== void 0) {
+    const r = asRecord(o.active_round, "review-session active_round");
+    const roundId = r.round_id;
+    const runId = r.run_id;
+    if (typeof roundId !== "string" || typeof runId !== "string") {
+      throw new Error(`review session active_round missing round_id/run_id: ${JSON.stringify(o.active_round)}`);
+    }
+    const changes = Array.isArray(r.changes) ? r.changes.filter((c) => c !== null && typeof c === "object").map((c) => ({
+      id: String(c.id ?? ""),
+      idx: Number(c.idx ?? 0),
+      kind: String(c.kind ?? ""),
+      t: numOrNull(c.t),
+      t2: numOrNull(c.t2),
+      x: numOrNull(c.x),
+      y: numOrNull(c.y),
+      text: strOrNull(c.text),
+      outcome: strOrNull(c.outcome)
+    })) : [];
+    activeRound = {
+      roundId,
+      runId,
+      seq: Number(r.seq ?? 0),
+      mode: String(r.mode ?? ""),
+      status: String(r.status ?? ""),
+      instruction: typeof r.instruction === "string" ? r.instruction : "",
+      changes
+    };
+  }
+  return {
+    videoId,
+    title: strOrNull(o.title),
+    latestVersionSeq: numOrNull(o.latest_version_seq),
+    activeRound,
+    timeline: o.timeline ?? null,
+    sourceUrl: strOrNull(o.source_url)
+  };
+}
+var CloudHttpError = class extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "CloudHttpError";
+  }
+  status;
+  body;
+};
+function extractErrorMessage(data) {
+  if (typeof data === "string" && data.trim() !== "") return data;
+  if (data && typeof data === "object") {
+    const o = data;
+    if (typeof o.error === "string") return o.error;
+    if (typeof o.message === "string") return o.message;
+    if (o.error) return JSON.stringify(o.error);
+  }
+  return void 0;
+}
+var CloudClient = class {
+  constructor(cfg, opts = {}) {
+    this.cfg = cfg;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!this.fetchImpl) throw new Error("global fetch is unavailable \u2014 Node 18+ required, or inject fetchImpl");
+  }
+  cfg;
+  fetchImpl;
+  timeoutMs;
+  requireVideoId() {
+    if (!this.cfg.videoId) throw new Error("missing video id \u2014 pass --video-id or set VIDEO_ID");
+    return this.cfg.videoId;
+  }
+  async request(method, url, body) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.cfg.credential}`,
+          Accept: "application/json",
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: ac.signal
+      });
+      const text = await res.text();
+      let data = void 0;
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+      if (!res.ok) {
+        const detail = extractErrorMessage(data) ?? `${res.status} ${res.statusText}`;
+        throw new CloudHttpError(res.status, `${method} ${url} failed: ${detail}`, data);
+      }
+      return data;
+    } catch (err) {
+      if (err instanceof CloudHttpError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`request timed out after ${this.timeoutMs}ms: ${method} ${url}`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ---- render -------------------------------------------------------------
+  async createRender(mode) {
+    const data = await this.request("POST", rendersUrl(this.cfg.base), {
+      video_id: this.requireVideoId(),
+      mode
+    });
+    return parseRenderCreate(data);
+  }
+  async getRender(renderId) {
+    const data = await this.request("GET", renderUrl(this.cfg.base, renderId));
+    return parseRenderState(data);
+  }
+  // ---- qa -----------------------------------------------------------------
+  async qaFrames(args) {
+    const body = { kind: "frames", start: args.start, end: args.end };
+    if (args.cols !== void 0) body.cols = args.cols;
+    if (args.interval !== void 0) body.interval = args.interval;
+    const data = await this.request("POST", qaUrl(this.cfg.base, this.requireVideoId()), body);
+    return parseQaFrames(data);
+  }
+  async qaWaveform(args) {
+    const data = await this.request("POST", qaUrl(this.cfg.base, this.requireVideoId()), {
+      kind: "waveform",
+      start: args.start,
+      end: args.end
+    });
+    return parseQaWaveform(data);
+  }
+  // ---- artifacts ----------------------------------------------------------
+  async listArtifacts() {
+    const data = await this.request("GET", artifactsUrl(this.cfg.base, this.requireVideoId()));
+    return parseArtifactList(data);
+  }
+  async getArtifact(name) {
+    const data = await this.request("GET", artifactsUrl(this.cfg.base, this.requireVideoId(), name));
+    return parseArtifactContent(data);
+  }
+  // ---- assets -------------------------------------------------------------
+  /** POST /api/v1/assets: request an asset row + presigned upload URL
+   *  (clipready assets route: {kind, content_type?, video_id?, filename?} →
+   *  {asset_id, upload_url, upload_token, expires_at}). */
+  async createAsset(args) {
+    const body = { kind: args.kind, video_id: this.requireVideoId() };
+    if (args.contentType !== void 0) body.content_type = args.contentType;
+    if (args.filename !== void 0) body.filename = args.filename;
+    const data = await this.request("POST", assetsUrl(this.cfg.base), body);
+    return parseAssetCreate(data);
+  }
+  /** PUT raw bytes to a presigned upload URL. No Authorization header — the
+   *  signed URL carries its own credentials and may be a different host. */
+  async upload(url, bytes, contentType, timeoutMs = DEFAULT_DOWNLOAD_TIMEOUT_MS) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: bytes,
+        signal: ac.signal
+      });
+      if (!res.ok) {
+        throw new Error(`asset upload failed: HTTP ${res.status} ${res.statusText} for ${url}`);
+      }
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`asset upload timed out after ${timeoutMs}ms: ${url}`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ---- review session -----------------------------------------------------
+  async getReview() {
+    const data = await this.request("GET", reviewUrl(this.cfg.base, this.requireVideoId()));
+    return parseReviewSession(data);
+  }
+  /** POST a review-round event ({run_id, type, payload?}); expects {ok:true}. */
+  async pushReview(body) {
+    const data = await this.request("POST", reviewUrl(this.cfg.base, this.requireVideoId()), body);
+    const o = data;
+    if (!o || o.ok !== true) {
+      throw new Error(`review push (${body.type}) did not return {ok:true}: ${JSON.stringify(data)}`);
+    }
+  }
+  // ---- download (signed URLs; no auth header) -----------------------------
+  async download(url, dest, timeoutMs = DEFAULT_DOWNLOAD_TIMEOUT_MS) {
+    return downloadTo(url, dest, { fetchImpl: this.fetchImpl, timeoutMs });
+  }
+};
+async function downloadTo(url, dest, opts = {}) {
+  const f = opts.fetchImpl ?? globalThis.fetch;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), opts.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS);
+  try {
+    const res = await f(url, { signal: ac.signal });
+    if (!res.ok) throw new Error(`download failed: HTTP ${res.status} ${res.statusText} for ${url}`);
+    mkdirSync(dirname(dest), { recursive: true });
+    const body = res.body;
+    if (!body) {
+      const buf = Buffer.from(await res.arrayBuffer());
+      writeFileSync(dest, buf);
+      return { path: dest, bytes: buf.length };
+    }
+    await pipeline(Readable.fromWeb(body), createWriteStream(dest));
+    return { path: dest, bytes: statSync(dest).size };
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`download timed out after ${opts.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS}ms: ${url}`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/cloud/review.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { basename, isAbsolute, join } from "path";
+function reviewDir(jobDir) {
+  return join(jobDir, "review");
+}
+function roundJsonPath(jobDir) {
+  return join(reviewDir(jobDir), "round.json");
+}
+function instructionPath(jobDir) {
+  return join(reviewDir(jobDir), "instruction.md");
+}
+function assetsCachePath(jobDir) {
+  return join(reviewDir(jobDir), "assets.json");
+}
+function sourceDownloadPath(jobDir) {
+  const manifest = join(jobDir, "source.json");
+  if (existsSync(manifest)) {
+    try {
+      const src = JSON.parse(readFileSync(manifest, "utf8")).source;
+      if (typeof src === "string" && src !== "") return join(jobDir, basename(src));
+    } catch {
+    }
+  }
+  return join(jobDir, "source.mp4");
+}
+async function pullReview(client, jobDir, opts = {}) {
+  const session = await client.getReview();
+  mkdirSync2(reviewDir(jobDir), { recursive: true });
+  const round = session.activeRound;
+  if (round) {
+    const roundFile = {
+      video_id: session.videoId,
+      round_id: round.roundId,
+      run_id: round.runId,
+      seq: round.seq,
+      mode: round.mode,
+      status: round.status,
+      pulled_at: (/* @__PURE__ */ new Date()).toISOString(),
+      changes: round.changes
+    };
+    writeFileSync2(roundJsonPath(jobDir), JSON.stringify(roundFile, null, 2) + "\n", "utf8");
+    writeFileSync2(instructionPath(jobDir), round.instruction + "\n", "utf8");
+  } else {
+    writeFileSync2(instructionPath(jobDir), "No active review round for this video.\n", "utf8");
+  }
+  let wroteTimeline = false;
+  const tlPath = timelineJsonPath(jobDir);
+  if (session.timeline !== null && session.timeline !== void 0 && !existsSync(tlPath)) {
+    writeFileSync2(tlPath, JSON.stringify(session.timeline, null, 2) + "\n", "utf8");
+    wroteTimeline = true;
+  }
+  let downloadedSource = null;
+  if (opts.withSource && session.sourceUrl) {
+    const dest = sourceDownloadPath(jobDir);
+    if (!existsSync(dest)) {
+      const dl = await client.download(session.sourceUrl, dest);
+      downloadedSource = dl.path;
+    }
+  }
+  return { jobDir, round, wroteTimeline, downloadedSource };
+}
+function resolveRunId(jobDir, flagOverride) {
+  if (typeof flagOverride === "string" && flagOverride.trim() !== "") return flagOverride.trim();
+  const path = roundJsonPath(jobDir);
+  if (existsSync(path)) {
+    try {
+      const runId = JSON.parse(readFileSync(path, "utf8")).run_id;
+      if (typeof runId === "string" && runId !== "") return runId;
+    } catch {
+    }
+  }
+  throw new Error(`missing run id \u2014 pass --run-id, or run \`review pull\` first (no run_id in ${path})`);
+}
+var REVIEW_STAGES = [
+  "provisioning",
+  "transcribing",
+  "edl",
+  "render_preview",
+  "qc",
+  "render_final",
+  "uploading",
+  "log"
+];
+function isReviewStage(s) {
+  return REVIEW_STAGES.includes(s);
+}
+async function pushStage(client, runId, stage, message) {
+  if (!isReviewStage(stage)) {
+    throw new Error(`invalid --stage "${stage}" \u2014 expected one of: ${REVIEW_STAGES.join(", ")}`);
+  }
+  await client.pushReview({
+    run_id: runId,
+    type: stage,
+    ...message !== void 0 ? { payload: { message } } : {}
+  });
+}
+function collectPlanAssetRefs(plan) {
+  const refs = [];
+  for (const ev of plan.events) {
+    const ref = ev.kind === "overlay" ? ev.overlay.asset?.ref : ev.kind === "audio" ? ev.audio.asset.ref : void 0;
+    if (typeof ref === "string" && ref !== "" && !refs.includes(ref)) refs.push(ref);
+  }
+  return refs;
+}
+var ASSET_CONTENT_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".mp3": "audio/mpeg",
+  ".m4a": "audio/mp4",
+  ".wav": "audio/wav"
+};
+function assetContentType(ref) {
+  const m = /\.[^./\\]+$/.exec(ref.toLowerCase());
+  return (m !== null ? ASSET_CONTENT_TYPES[m[0]] : void 0) ?? "application/octet-stream";
+}
+function readAssetCache(jobDir) {
+  const path = assetsCachePath(jobDir);
+  if (!existsSync(path)) return {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const out = {};
+    for (const [ref, v] of Object.entries(raw ?? {})) {
+      const e = v;
+      if (e && typeof e.sha256 === "string" && typeof e.asset_id === "string") {
+        out[ref] = { sha256: e.sha256, asset_id: e.asset_id };
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+async function syncAssets(client, jobDir, plan) {
+  const refs = collectPlanAssetRefs(plan);
+  if (refs.length === 0) return {};
+  const paths = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    const abs = isAbsolute(ref) ? ref : join(jobDir, ref);
+    if (!existsSync(abs)) {
+      throw new Error(
+        `asset not found: ${ref} (expected at ${abs}) \u2014 asset refs are job-dir-relative paths; place the file before pushing`
+      );
+    }
+    paths.set(ref, abs);
+  }
+  const cache = readAssetCache(jobDir);
+  const manifest = {};
+  let dirty = false;
+  for (const ref of refs) {
+    const bytes = readFileSync(paths.get(ref));
+    const sha256 = "sha256:" + createHash("sha256").update(bytes).digest("hex");
+    const hit = cache[ref];
+    if (hit !== void 0 && hit.sha256 === sha256) {
+      manifest[ref] = hit.asset_id;
+      continue;
+    }
+    const contentType = assetContentType(ref);
+    const created = await client.createAsset({
+      kind: "timeline",
+      contentType,
+      filename: basename(ref)
+    });
+    await client.upload(created.uploadUrl, bytes, contentType);
+    cache[ref] = { sha256, asset_id: created.assetId };
+    manifest[ref] = created.assetId;
+    dirty = true;
+  }
+  if (dirty) {
+    mkdirSync2(reviewDir(jobDir), { recursive: true });
+    writeFileSync2(assetsCachePath(jobDir), JSON.stringify(cache, null, 2) + "\n", "utf8");
+  }
+  return manifest;
+}
+async function compileJob(jobDir, opts) {
+  const loaded = loadTimeline(jobDir);
+  if (!loaded.doc) return { ok: false, errors: loaded.errors, diagnostics: null };
+  const ctx = await gatherCompileCtx(jobDir, loaded.doc, opts.gather ?? {});
+  const result = compileTimeline(loaded.doc, ctx);
+  writeCompileArtifacts(jobDir, result);
+  if (!result.ok || !result.plan) {
+    return { ok: false, errors: result.diagnostics.errors, diagnostics: result.diagnostics };
+  }
+  return { ok: true, raw: loaded.raw, plan: result.plan, legacyEdl: result.legacyEdl };
+}
+async function pushTimeline(client, jobDir, runId, opts = {}) {
+  const compiled = await compileJob(jobDir, opts);
+  if (!compiled.ok) return compiled;
+  const assets = await syncAssets(client, jobDir, compiled.plan);
+  await client.pushReview({
+    run_id: runId,
+    type: "timeline_update",
+    payload: {
+      timeline: compiled.raw,
+      plan: compiled.plan,
+      timeline_hash: compiled.plan.timelineHash,
+      ...Object.keys(assets).length > 0 ? { assets } : {}
+    }
+  });
+  return { ok: true, plan: compiled.plan, timelineHash: compiled.plan.timelineHash, assets };
+}
+function readOutcomesFile(path) {
+  if (!existsSync(path)) throw new Error(`outcomes file not found: ${path}`);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(`outcomes file is not valid JSON: ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const arr = Array.isArray(raw) ? raw : raw?.outcomes;
+  if (!Array.isArray(arr)) {
+    throw new Error(`outcomes file must be an array (or {outcomes: [...]}) of {change_id, ok, note?}: ${path}`);
+  }
+  return arr.map((o, i) => {
+    const r = o ?? {};
+    if (typeof r.change_id !== "string" || typeof r.ok !== "boolean" || r.note !== void 0 && typeof r.note !== "string") {
+      throw new Error(`outcomes[${i}] must be {change_id: string, ok: boolean, note?: string}: ${JSON.stringify(o)}`);
+    }
+    return { change_id: r.change_id, ok: r.ok, ...r.note !== void 0 ? { note: r.note } : {} };
+  });
+}
+async function pushComplete(client, jobDir, runId, opts) {
+  const outcomes = opts.outcomesPath ? readOutcomesFile(opts.outcomesPath) : void 0;
+  const compiled = await compileJob(jobDir, opts);
+  if (!compiled.ok) return compiled;
+  const assets = await syncAssets(client, jobDir, compiled.plan);
+  await client.pushReview({
+    run_id: runId,
+    type: "completed",
+    payload: {
+      edl: compiled.legacyEdl,
+      timeline: compiled.raw,
+      plan: compiled.plan,
+      duration_s: opts.durationS,
+      ...outcomes !== void 0 ? { outcomes } : {},
+      ...Object.keys(assets).length > 0 ? { assets } : {}
+    }
+  });
+  return { ok: true, plan: compiled.plan, durationS: opts.durationS, outcomes, assets };
+}
+
+// src/cloud/render.ts
+import { join as join2 } from "path";
+var MAX_POLL_MS = 30 * 60 * 1e3;
+function defaultRenderOut(jobDir, mode) {
+  return join2(jobDir, mode === "final" ? "final.mp4" : "preview.mp4");
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function pollRender(client, renderId, opts = {}) {
+  const intervalMs = opts.intervalMs ?? 1e4;
+  const maxMs = opts.maxMs ?? MAX_POLL_MS;
+  const nap = opts.sleepImpl ?? sleep;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  for (; ; ) {
+    const state = await client.getRender(renderId);
+    const elapsed = now() - start;
+    opts.onTick?.(state, elapsed);
+    if (isTerminalStatus(state.status)) return state;
+    if (elapsed + intervalMs >= maxMs) {
+      throw new Error(`render ${renderId} did not finish within ${Math.round(maxMs / 6e4)} min (last status: ${state.status})`);
+    }
+    await nap(intervalMs);
+  }
+}
+
+// src/cloud/qa.ts
+import { join as join3 } from "path";
+function qaDir(jobDir) {
+  return jobDir ? join3(jobDir, "qa") : join3(process.cwd(), "qa");
+}
+function tag(start, end) {
+  return `${start}_${end}`;
+}
+function framesPngPath(dir, start, end) {
+  return join3(dir, `frames_${tag(start, end)}.png`);
+}
+function waveformPngPath(dir, start, end) {
+  return join3(dir, `waveform_${tag(start, end)}.png`);
+}
+function waveformWordsPath(dir, start, end) {
+  return join3(dir, `waveform_${tag(start, end)}.words.json`);
+}
+
+// src/cloud/pull.ts
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2 } from "path";
+function selectArtifacts(available, only) {
+  if (!only || only.length === 0) return available;
+  const want = new Set(only.map((n) => n.trim()).filter((n) => n !== ""));
+  return available.filter((n) => want.has(n));
+}
+function parseOnly(value) {
+  if (!value) return void 0;
+  const names = value.split(",").map((n) => n.trim()).filter((n) => n !== "");
+  return names.length > 0 ? names : void 0;
+}
+function serializeArtifact(name, content) {
+  if (typeof content === "string") return content;
+  return JSON.stringify(content, null, 2) + "\n";
+}
+async function pullArtifacts(client, jobDir, only) {
+  const available = await client.listArtifacts();
+  const requested = only && only.length > 0 ? only : available;
+  const selected = selectArtifacts(available, only);
+  const missing = requested.filter((n) => !available.includes(n));
+  const pulled = [];
+  for (const name of selected) {
+    const art = await client.getArtifact(name);
+    const body = serializeArtifact(art.name, art.content);
+    const dest = artifactLocalPath(jobDir, art.name);
+    mkdirSync3(dirname2(dest), { recursive: true });
+    writeFileSync3(dest, body, "utf8");
+    pulled.push({ name: art.name, path: dest, bytes: Buffer.byteLength(body) });
+  }
+  return { jobDir, pulled, missing };
+}
+
+// src/cloud/skill.ts
+import { cpSync, existsSync as existsSync2, readdirSync, rmSync, statSync as statSync2 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname3, join as join4, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+function bundledSkillDir() {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join4(here, "skills", "video-editing"),
+    join4(here, "..", "skills", "video-editing"),
+    join4(here, "..", "..", "skills", "video-editing")
+  ];
+  for (const c of candidates) {
+    if (existsSync2(join4(c, "SKILL.md"))) return resolve(c);
+  }
+  throw new Error(`bundled skill not found (looked in: ${candidates.map((c) => resolve(c)).join(", ")})`);
+}
+function defaultSkillTarget() {
+  return join4(homedir(), ".claude", "skills");
+}
+function listFilesRecursive(root) {
+  const out = [];
+  for (const entry of readdirSync(root)) {
+    const full = join4(root, entry);
+    if (statSync2(full).isDirectory()) out.push(...listFilesRecursive(full));
+    else out.push(full);
+  }
+  return out;
+}
+function installSkill(opts = {}) {
+  const source = bundledSkillDir();
+  const targetRoot = opts.target ? resolve(opts.target) : defaultSkillTarget();
+  const dest = join4(targetRoot, "video-editing");
+  rmSync(dest, { recursive: true, force: true });
+  cpSync(source, dest, { recursive: true });
+  const files = listFilesRecursive(dest).map((f) => relative(dest, f)).sort();
+  return { source, dest, files };
+}
+
+// src/cli.ts
+function num(v) {
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : void 0;
+}
+async function maybeDesilence(jobDir, opts = {}) {
+  const edl = readEdl(jobDir);
+  if (!edl) return;
+  if (edl.desilenced && !opts.force) return;
+  const { edl: tight, stats } = await desilenceEdl(edl, jobDir, opts.options ?? DEFAULT_DESILENCE);
+  const rawBackup = join5(jobDir, "edl.raw.json");
+  if (!existsSync3(rawBackup)) writeFileSync4(rawBackup, JSON.stringify(edl, null, 2) + "\n", "utf8");
+  writeFileSync4(edlPath(jobDir), JSON.stringify(tight, null, 2) + "\n", "utf8");
+  const db = (opts.options ?? DEFAULT_DESILENCE).noiseDb;
+  process.stderr.write(
+    `  desilence(${db}dB): ${stats.rangesBefore} \u2192 ${stats.rangesAfter} ranges, removed ${stats.removedS.toFixed(2)}s of silence (${stats.durationBefore.toFixed(2)}s \u2192 ${stats.durationAfter.toFixed(2)}s)
+`
+  );
+}
+async function renderJob(jobDir, mode, opts = {}) {
+  if (mode === "none") return null;
+  if (!existsSync3(edlPath(jobDir))) return null;
+  if (!opts.noDesilence) await maybeDesilence(jobDir);
+  const name = { preview: "preview.mp4", draft: "draft.mp4", final: "final.mp4" }[mode];
+  const output = join5(jobDir, name);
+  await render(edlPath(jobDir), output, {
+    preview: mode === "preview",
+    draft: mode === "draft",
+    buildSubtitles: opts.buildSubtitles,
+    noSubtitles: opts.noSubtitles,
+    noLoudnorm: opts.noLoudnorm
+  });
+  return output;
+}
+function printPrepared(jobDir, prompt, edlRequired) {
+  console.log(`job: ${jobDir}`);
+  console.log(`prompt: ${prompt}`);
+  console.log(`manifest: ${join5(jobDir, "agent_manifest.json")}`);
+  console.log(`transcript: ${join5(jobDir, "transcripts")}`);
+  console.log(`flags: ${join5(jobDir, "flags.txt")}`);
+  console.log(`word_dump: ${join5(jobDir, "word_dump.txt")}`);
+  console.log(`vertical_src: ${join5(jobDir, "vertical_src.mp4")}`);
+  if (edlRequired) console.log(`edl missing: ${join5(jobDir, "edl.json")}`);
+}
+var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+var program = new Command();
+program.name("video-editing").description("Standalone TypeScript CLI for editing talking-head reels: transcribe, screen, cut (EDL), render vertical 9:16, QC, content-verify.").version(pkg.version);
+program.command("init-job").description("Create a job directory and source.json").requiredOption("--source <path>", "Source video path").option("--job-dir <path>", "Job directory (default: ~/Downloads/edit/job_<source-stem>)").option("--force", "Overwrite source.json metadata").action(async (o) => {
+  const jobDir = await initJob(o.source, o.jobDir ?? null, { force: !!o.force });
+  console.log(jobDir);
+});
+program.command("transcribe").description("Run ElevenLabs Scribe transcription and screening artifacts").option("--source <path>", "Source video path").option("--job-dir <path>", "Existing job directory").option("--language <code>", "Optional ISO language code").option("--num-speakers <n>", "Optional speaker count").option("--no-heal", "Disable transcript healing").option("--force", "Re-transcribe even if cached").option("--api-key <key>", "ElevenLabs API key override").action(async (o) => {
+  const { jobDir, source, stem } = await resolveJob(o, { forceJob: !!o.force });
+  const tpath = await ensureTranscribed(jobDir, source, stem, {
+    language: o.language,
+    numSpeakers: num(o.numSpeakers),
+    noHeal: o.heal === false,
+    force: !!o.force,
+    apiKey: o.apiKey
+  });
+  writeAgentManifest(jobDir, source, stem, "transcribe");
+  console.log(`transcript: ${tpath}`);
+  console.log(`packed: ${join5(jobDir, "takes_packed.md")}`);
+  console.log(`flags: ${join5(jobDir, "flags.txt")}`);
+});
+program.command("cut-silences").description("Prepare a silence-cut prompt; render/QC if edl.json exists").option("--source <path>", "Source video path").option("--job-dir <path>", "Existing job directory").option("--min-gap <s>", "Document gaps at or above this many seconds", "0.30").option("--target-gap <s>", "Prompt target for remaining air", "0.13").option("--lead-pad <s>", "Prompt lead pad", "0.05").option("--trail-pad <s>", "Prompt trail pad", "0.08").option("--render <mode>", "Render if edl.json exists (preview|none)", "none").option("--force-transcribe", "Regenerate transcript before preparing").option("--api-key <key>", "ElevenLabs API key override").action(async (o) => {
+  const { jobDir, source, stem } = await resolveJob(o);
+  await ensureTranscribed(jobDir, source, stem, { force: !!o.forceTranscribe, apiKey: o.apiKey });
+  await ensureVerticalMaster(jobDir, source);
+  const prompt = writeSilencePrompt(jobDir, stem, {
+    minGap: num(o.minGap),
+    targetGap: num(o.targetGap),
+    leadPad: num(o.leadPad),
+    trailPad: num(o.trailPad)
+  });
+  writeAgentManifest(jobDir, source, stem, "cut-silences");
+  const preview = await renderJob(jobDir, o.render === "preview" ? "preview" : "none");
+  if (preview) {
+    writeBoundaries(jobDir);
+    console.log(`preview: ${preview}`);
+  }
+  printPrepared(jobDir, prompt, !existsSync3(edlPath(jobDir)));
+});
+program.command("cut-bad-retakes").description("Prepare the bad-retake (author-edl) prompt; render/QC if edl.json exists").option("--source <path>", "Source video path").option("--job-dir <path>", "Existing job directory").option("--with-sound-waves", "Write preview join QC PNGs if preview.mp4 exists").option("--quality-review", "Write review prompt; convert review.json to warnings if present").option("--render <mode>", "Render if edl.json exists (preview|none)", "none").option("--language <code>", "Optional ISO language code").option("--num-speakers <n>", "Optional speaker count").option("--force-transcribe", "Regenerate transcript before preparing").option("--api-key <key>", "ElevenLabs API key override").action(async (o) => {
+  const { jobDir, source, stem } = await resolveJob(o);
+  await ensureTranscribed(jobDir, source, stem, {
+    language: o.language,
+    numSpeakers: num(o.numSpeakers),
+    force: !!o.forceTranscribe,
+    apiKey: o.apiKey
+  });
+  await ensureVerticalMaster(jobDir, source);
+  const prompt = writeVideoEditingPrompt(jobDir, stem, "author-edl.prompt.md", "author-edl.prompt.md");
+  writeAgentManifest(jobDir, source, stem, "cut-bad-retakes");
+  const preview = await renderJob(jobDir, o.render === "preview" ? "preview" : "none");
+  if (preview) console.log(`preview: ${preview}`);
+  else if (o.render !== "none") process.stderr.write(`edl not found yet; write ${edlPath(jobDir)} from ${prompt}
+`);
+  if (o.withSoundWaves) {
+    const qc = await generateQcImages(jobDir, preview ? { preview } : {});
+    if (qc) console.log(`qc: ${qc}`);
+    else process.stderr.write("qc not generated yet; it requires edl.json and preview.mp4\n");
+  }
+  if (o.qualityReview) {
+    const reviewPrompt = writeVideoEditingPrompt(jobDir, stem, "review.prompt.md", "review.prompt.md");
+    console.log(`review_prompt: ${reviewPrompt}`);
+    if (existsSync3(join5(jobDir, "review.json"))) {
+      console.log(`warnings: ${writeWarningsFromReview(jobDir)}`);
+    }
+  }
+  printPrepared(jobDir, prompt, !existsSync3(edlPath(jobDir)));
+});
+program.command("render").description("Render the EDL to a preview/draft/final video").requiredOption("--job-dir <path>", "Job directory containing edl.json").requiredOption("--mode <mode>", "preview|draft|final").option("--build-subtitles", "Burn 2-word subtitles from the transcript").option("--no-subtitles", "Do not burn subtitles").option("--no-loudnorm", "Skip loudness normalization").option("--no-desilence", "Skip the amplitude (-39dB) silence-trim pass").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const mode = o.mode;
+  if (!["preview", "draft", "final"].includes(mode)) throw new Error("--mode must be preview|draft|final");
+  const output = await renderJob(jobDir, mode, {
+    buildSubtitles: !!o.buildSubtitles,
+    noSubtitles: o.subtitles === false,
+    noLoudnorm: o.loudnorm === false,
+    noDesilence: o.desilence === false
+  });
+  if (!output) throw new Error(`edl not found: ${edlPath(jobDir)}`);
+  writeBoundaries(jobDir);
+  console.log(output);
+});
+program.command("desilence").description("Excise sub-threshold (-39dB) silences inside EDL ranges and trim silent range edges; rewrites edl.json (original \u2192 edl.raw.json). Runs automatically before render.").requiredOption("--job-dir <path>", "Job directory containing edl.json").option("--noise-db <db>", "Silence threshold in dB (silencedetect noise)", String(DEFAULT_DESILENCE.noiseDb)).option("--min-silence <s>", "Minimum silence length to cut", String(DEFAULT_DESILENCE.minSilence)).option("--target-gap <s>", "Air to leave where a silence is cut", String(DEFAULT_DESILENCE.targetGap)).option("--lead-pad <s>", "Air kept before speech resumes", String(DEFAULT_DESILENCE.leadKeep)).option("--trail-pad <s>", "Air kept after speech ends", String(DEFAULT_DESILENCE.trailKeep)).option("--render <mode>", "Render after rewriting (preview|none)", "none").option("--force", "Re-run even if the EDL is already marked desilenced").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  if (!existsSync3(edlPath(jobDir))) throw new Error(`edl not found: ${edlPath(jobDir)}`);
+  const options = {
+    ...DEFAULT_DESILENCE,
+    noiseDb: num(o.noiseDb) ?? DEFAULT_DESILENCE.noiseDb,
+    minSilence: num(o.minSilence) ?? DEFAULT_DESILENCE.minSilence,
+    targetGap: num(o.targetGap) ?? DEFAULT_DESILENCE.targetGap,
+    leadKeep: num(o.leadPad) ?? DEFAULT_DESILENCE.leadKeep,
+    trailKeep: num(o.trailPad) ?? DEFAULT_DESILENCE.trailKeep
+  };
+  await maybeDesilence(jobDir, { force: true, options });
+  writeBoundaries(jobDir);
+  const preview = await renderJob(jobDir, o.render === "preview" ? "preview" : "none", { noDesilence: true });
+  if (preview) {
+    writeBoundaries(jobDir);
+    console.log(`preview: ${preview}`);
+  }
+  console.log(`edl: ${edlPath(jobDir)}`);
+  console.log(`raw: ${join5(jobDir, "edl.raw.json")}`);
+});
+program.command("verify").description("Content-verify the rendered preview: re-transcribe joins, flag duplicated phrases + dead air").requiredOption("--job-dir <path>", "Job directory").option("--full", "Re-transcribe the whole preview instead of per-join windows").option("--window <s>", "Per-join window length in seconds", "6").option("--gap <s>", "Dead-air threshold in seconds", "0.6").option("--json", "Print the JSON verdict to stdout").option("--api-key <key>", "ElevenLabs API key override").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const result = await verify(jobDir, {
+    full: !!o.full,
+    windowS: num(o.window),
+    gapThresholdS: num(o.gap),
+    apiKey: o.apiKey
+  });
+  writeFileSync4(join5(jobDir, "verify.json"), JSON.stringify(result, null, 2) + "\n", "utf8");
+  if (o.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`verify: ${result.verdict} (${result.joins.length} finding(s), mode ${result.mode})`);
+    for (const f of result.joins) console.log(`  [${f.severity}] ${f.detail}`);
+  }
+  if (result.verdict === "needs-fixes") process.exitCode = 2;
+});
+program.command("inspect").description("Render a filmstrip+waveform PNG for a job window or join").requiredOption("--job-dir <path>", "Job directory").option("--join <i>", "Center on cut-boundary index i (uses cut_boundaries)").option("--start <s>", "Window start (seconds)").option("--end <s>", "Window end (seconds)").option("--video <which>", "preview|vertical_src", "preview").option("--transcript <path>", "Transcript JSON for word labels").option("-o, --output <path>", "Output PNG path").option("--n-frames <n>", "Number of filmstrip frames", "10").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const video = o.video === "vertical_src" ? join5(jobDir, "vertical_src.mp4") : join5(jobDir, "preview.mp4");
+  if (!existsSync3(video)) throw new Error(`video not found: ${video}`);
+  let start = num(o.start);
+  let end = num(o.end);
+  let label = "win";
+  if (o.join !== void 0) {
+    const edl = readEdl(jobDir);
+    if (!edl) throw new Error("edl.json required for --join");
+    const b = cutBoundaries(edl.ranges ?? [])[Number(o.join)];
+    if (!b) throw new Error(`no join index ${o.join}`);
+    const dur = await mediaDuration(video);
+    start = Math.max(0, b.output_time_s - 1.25);
+    end = Math.min(Math.max(0.05, dur - 0.2), b.output_time_s + 1.25);
+    label = `join_${String(Number(o.join)).padStart(2, "0")}`;
+  }
+  if (start === void 0 || end === void 0) throw new Error("provide --join or --start/--end");
+  const qc = join5(jobDir, "qc");
+  mkdirSync4(qc, { recursive: true });
+  const output = o.output ?? join5(qc, `inspect_${label}_${start.toFixed(2)}-${end.toFixed(2)}.png`);
+  const transcript = o.transcript ?? (o.video === "vertical_src" ? join5(jobDir, "transcripts", `${loadJob(jobDir).stem}.json`) : void 0);
+  await timelineView(video, start, end, output, {
+    nFrames: num(o.nFrames),
+    transcript: transcript && existsSync3(transcript) ? transcript : void 0
+  });
+  console.log(output);
+});
+var timelineCmd = program.command("timeline").description("TimelineV2 authoring: validate / compile / resolve phrases / captions");
+function printTimelineErrors(errors, json) {
+  if (json) {
+    console.log(JSON.stringify({ ok: false, errors, warnings: [] }, null, 2));
+  } else {
+    for (const e of errors) console.log(`  [error] ${e.path}: ${e.message}`);
+  }
+}
+timelineCmd.command("validate").description("Schema + semantic + capability validation of <job>/timeline.json").requiredOption("--job-dir <path>", "Job directory containing timeline.json").option("--json", "Print the JSON verdict").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const loaded = loadTimeline(jobDir);
+  if (!loaded.doc) {
+    printTimelineErrors(loaded.errors, !!o.json);
+    process.exitCode = 2;
+    return;
+  }
+  const sem = validateTimeline(loaded.doc);
+  const uses = usesFromDoc(loaded.doc);
+  const cap = checkCapabilities(uses);
+  const errors = [...sem.errors, ...cap.errors];
+  const warnings = [...sem.warnings, ...cap.warnings];
+  const ok = errors.length === 0;
+  if (o.json) {
+    console.log(JSON.stringify({ ok, uses, errors, warnings }, null, 2));
+  } else {
+    console.log(`timeline: ${timelineJsonPath(jobDir)}`);
+    console.log(`valid: ${ok ? "yes" : "NO"} (${errors.length} error(s), ${warnings.length} warning(s))`);
+    console.log(`uses: ${uses.join(", ") || "(none)"}`);
+    for (const e of errors) console.log(`  [error] ${e.path}: ${e.message}`);
+    for (const w of warnings) console.log(`  [warn]  ${w.path}: ${w.message}`);
+  }
+  if (!ok) process.exitCode = 2;
+});
+timelineCmd.command("compile").description("Compile timeline.json -> resolved/plan.json + diagnostics + legacy edl.json").requiredOption("--job-dir <path>", "Job directory containing timeline.json").option("--json", "Print the JSON result").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const loaded = loadTimeline(jobDir);
+  if (!loaded.doc) {
+    printTimelineErrors(loaded.errors, !!o.json);
+    process.exitCode = 2;
+    return;
+  }
+  const ctx = await gatherCompileCtx(jobDir, loaded.doc);
+  const result = compileTimeline(loaded.doc, ctx);
+  const written = writeCompileArtifacts(jobDir, result);
+  if (o.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: result.ok,
+          plan: written.plan ?? null,
+          edl: written.edl ?? null,
+          diagnostics: result.diagnostics,
+          uses: result.uses,
+          outputDurationS: result.plan?.outputDurationS ?? null,
+          segments: result.plan?.segments.length ?? 0,
+          events: result.plan?.events.length ?? 0
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    if (result.ok && result.plan) {
+      console.log(`plan: ${written.plan}`);
+      console.log(`edl: ${written.edl}`);
+      console.log(
+        `output: ${result.plan.outputDurationS.toFixed(2)}s, ${result.plan.segments.length} segment(s), ${result.plan.events.length} event(s)`
+      );
+      console.log(`uses: ${result.uses.join(", ") || "(none)"}`);
+    }
+    console.log(`diagnostics: ${written.diagnostics}`);
+    for (const line of formatDiagnostics(result.diagnostics)) console.log(line);
+  }
+  if (!result.ok) {
+    const ambiguous = result.diagnostics.errors.some((e) => e.code === "anchor-ambiguous");
+    process.exitCode = ambiguous ? 3 : 2;
+  }
+});
+timelineCmd.command("resolve").description("Resolve a transcript phrase to source seconds (exact, normalized match)").requiredOption("--job-dir <path>", "Job directory").requiredOption("--phrase <text>", "Phrase to locate in the word-level transcript").option("--near <srcSeconds>", "Disambiguate: pick the occurrence nearest this source time").option("--occurrence <n>", "Pick the n-th occurrence (1-based)").option("--source <name>", "Source name (default: the timeline's single source, or the job stem)").option("--json", "Print JSON").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  let sourceName = o.source;
+  if (!sourceName) {
+    const loaded = loadTimeline(jobDir);
+    if (loaded.doc) {
+      const names = Object.keys(loaded.doc.sources);
+      if (names.length !== 1) throw new Error(`timeline has ${names.length} sources (${names.join(", ")}); pass --source`);
+      sourceName = names[0];
+    } else {
+      sourceName = loadJob(jobDir).stem;
+    }
+  }
+  const tfile = transcriptFileForSource(jobDir, sourceName);
+  if (!tfile) throw new Error(`no transcript found for source "${sourceName}" in ${join5(jobDir, "transcripts")}`);
+  const transcript = JSON.parse(readFileSync2(tfile, "utf8"));
+  const stream = wordStream(transcript);
+  const outcome = resolvePhrase(stream, o.phrase, { occurrence: num(o.occurrence), nearS: num(o.near) });
+  if (outcome.status === "ok") {
+    const m = outcome.match;
+    const payload2 = { start: m.start, end: m.end, words: m.words, occurrence: m.occurrence };
+    if (o.json) console.log(JSON.stringify(payload2, null, 2));
+    else {
+      console.log(`resolved: ${m.start}s - ${m.end}s (occurrence ${m.occurrence} of ${outcome.matches.length})`);
+      console.log(`context: ${m.context}`);
+    }
+    return;
+  }
+  if (outcome.status === "ambiguous") {
+    const payload2 = {
+      candidates: outcome.candidates.map((c) => ({
+        occurrence: c.occurrence,
+        start: c.start,
+        end: c.end,
+        context: c.context
+      }))
+    };
+    if (o.json) console.log(JSON.stringify(payload2, null, 2));
+    else {
+      console.log(`ambiguous: ${outcome.candidates.length} occurrence(s); pass --occurrence or --near`);
+      for (const c of payload2.candidates) console.log(`  #${c.occurrence} ${c.start}s - ${c.end}s: ${c.context}`);
+    }
+    process.exitCode = 3;
+    return;
+  }
+  const payload = { error: `phrase not found: ${o.phrase}`, suggestions: outcome.suggestions };
+  if (o.json) console.log(JSON.stringify(payload, null, 2));
+  else {
+    console.log(`not found: "${o.phrase}"`);
+    for (const s of outcome.suggestions) console.log(`  did you mean "${s.text}" @${s.start}s (similarity ${s.similarity})`);
+  }
+  process.exitCode = 1;
+});
+var captionsCmd = timelineCmd.command("captions").description("Caption authoring helpers");
+captionsCmd.command("generate").description("Enable captions in timeline.json (preset only \u2014 cues are derived at compile)").requiredOption("--job-dir <path>", "Job directory containing timeline.json").option("--preset <name>", "Caption preset: grouped (default, ~4 words/cue) | opus-karaoke (word-by-word)", "grouped").option("--json", "Print JSON").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  updateCaptionsBlock(jobDir, o.preset);
+  const loaded = loadTimeline(jobDir);
+  if (!loaded.doc) {
+    printTimelineErrors(loaded.errors, !!o.json);
+    process.exitCode = 2;
+    return;
+  }
+  const ctx = await gatherCompileCtx(jobDir, loaded.doc, { noDetect: true });
+  const result = compileTimeline(loaded.doc, ctx);
+  const cueCount = result.plan?.events.filter((e) => e.kind === "caption-cue").length ?? 0;
+  if (o.json) {
+    console.log(
+      JSON.stringify(
+        { ok: result.ok, timeline: timelineJsonPath(jobDir), preset: o.preset, cueCount, diagnostics: result.diagnostics },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(`captions: enabled (preset ${o.preset}) in ${timelineJsonPath(jobDir)}`);
+    console.log(`derived cues (dry compile): ${cueCount}`);
+    for (const line of formatDiagnostics(result.diagnostics)) console.log(line);
+  }
+  if (!result.ok) process.exitCode = 2;
+});
+program.command("compose").description(
+  "Build a local HyperFrames composition from resolved/plan.json (cut + captions/zooms/overlays); with --render, render it via the `hyperframes` CLI"
+).requiredOption("--job-dir <path>", "Job directory containing resolved/plan.json").option("--render", "Render the composition locally (requires the `hyperframes` CLI on PATH)").option("--quality <q>", "Render quality: draft|standard|high", "standard").option("--fps <n>", "Render frame rate", "30").option("--out <path>", "Rendered output path (default <job>/composed.mp4)").option("--proxy-crf <crf>", "libx264 CRF for the compressed video proxy", "23").option("--json", "Print JSON").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const planFile = planPath(jobDir);
+  if (!existsSync3(planFile)) {
+    throw new Error(
+      `plan not found: ${planFile} \u2014 run \`video-editing timeline compile --job-dir "${jobDir}"\` first`
+    );
+  }
+  const plan = JSON.parse(readFileSync2(planFile, "utf8"));
+  const quality = String(o.quality);
+  if (!["draft", "standard", "high"].includes(quality)) throw new Error("--quality must be draft|standard|high");
+  const fps = num(o.fps) ?? 30;
+  const proxyCrf = num(o.proxyCrf) ?? 23;
+  const verticalSrc = join5(jobDir, "vertical_src.mp4");
+  if (!existsSync3(verticalSrc)) {
+    throw new Error(
+      `vertical master not found: ${verticalSrc} \u2014 bake it first (e.g. \`video-editing cut-bad-retakes --job-dir "${jobDir}" --render none\`)`
+    );
+  }
+  const preview = join5(jobDir, "preview.mp4");
+  if (!existsSync3(preview)) {
+    throw new Error(
+      `preview not found: ${preview} \u2014 render the QC preview first (\`video-editing render --job-dir "${jobDir}" --mode preview\`)`
+    );
+  }
+  const compDir = join5(jobDir, "composition");
+  const mediaDir = join5(compDir, "media");
+  mkdirSync4(mediaDir, { recursive: true });
+  const stale = (out2, src) => !existsSync3(out2) || statSync3(out2).mtimeMs < statSync3(src).mtimeMs;
+  const proxy = join5(mediaDir, "source.mp4");
+  if (stale(proxy, verticalSrc)) {
+    await run([
+      "ffmpeg",
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-stats",
+      "-i",
+      verticalSrc,
+      "-c:v",
+      "libx264",
+      "-preset",
+      "veryfast",
+      "-crf",
+      String(proxyCrf),
+      "-maxrate",
+      "6M",
+      "-bufsize",
+      "12M",
+      "-c:a",
+      "aac",
+      "-b:a",
+      "160k",
+      "-movflags",
+      "+faststart",
+      proxy
+    ]);
+  } else {
+    process.stderr.write("  proxy up to date; skipping re-encode\n");
+  }
+  const audio = join5(mediaDir, "audio.m4a");
+  if (stale(audio, preview)) {
+    await run([
+      "ffmpeg",
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-stats",
+      "-i",
+      preview,
+      "-vn",
+      "-c:a",
+      "aac",
+      "-b:a",
+      "160k",
+      audio
+    ]);
+  } else {
+    process.stderr.write("  cut audio up to date; skipping re-extract\n");
+  }
+  const assetRefs = /* @__PURE__ */ new Set();
+  for (const ev of plan.events ?? []) {
+    if (ev.kind === "overlay" && (ev.overlay.kind === "image" || ev.overlay.kind === "sticker") && typeof ev.overlay.asset?.ref === "string") {
+      assetRefs.add(ev.overlay.asset.ref);
+    }
+  }
+  for (const ref of assetRefs) {
+    const srcPath = resolvePath(jobDir, ref);
+    if (!existsSync3(srcPath)) {
+      throw new Error(
+        `asset not found: ${ref} (expected at ${srcPath}) \u2014 asset refs are job-dir-relative paths`
+      );
+    }
+    const dest = join5(mediaDir, ref);
+    mkdirSync4(dirname4(dest), { recursive: true });
+    copyFileSync(srcPath, dest);
+  }
+  const tlForGrade = loadTimeline(jobDir);
+  const grade = tlForGrade.doc && typeof tlForGrade.doc.settings.grade === "object" ? tlForGrade.doc.settings.grade : void 0;
+  const entry = join5(compDir, COMPOSE_ENTRY);
+  writeFileSync4(entry, composeHtml(plan, grade !== void 0 ? { grade } : {}), "utf8");
+  const counts = composeCounts(plan);
+  const out = resolvePath(o.out ?? join5(jobDir, "composed.mp4"));
+  const renderCmd = ["hyperframes", "render", "--quality", quality, "--fps", String(fps), "--output", out];
+  if (!o.render) {
+    if (o.json) {
+      console.log(JSON.stringify({ compositionDir: compDir, entry, ...counts }, null, 2));
+    } else {
+      console.log(`composition: ${compDir}`);
+      console.log(`entry: ${entry}`);
+      console.log(`segments: ${counts.segments}, cues: ${counts.cues}, zooms: ${counts.zooms}, overlays: ${counts.overlays}`);
+      console.log(`render locally: cd ${shown([compDir])} && ${shown(renderCmd)}`);
+    }
+    return;
+  }
+  const probe = runSync(["hyperframes", "--version"], { check: false, echo: false });
+  if (probe.code !== 0) {
+    throw new Error("`hyperframes` CLI not found on PATH \u2014 install it with `npm install -g hyperframes`");
+  }
+  const res = await run(renderCmd, { cwd: compDir, check: false });
+  if (res.code !== 0) {
+    process.exitCode = res.code;
+    process.stderr.write(`hyperframes render failed with exit ${res.code}
+`);
+    return;
+  }
+  if (o.json) {
+    console.log(JSON.stringify({ compositionDir: compDir, entry, out, ...counts }, null, 2));
+  } else {
+    console.log(`composition: ${compDir}`);
+    console.log(`out: ${out}`);
+  }
+});
+function cloudFlags(o) {
+  return { apiBase: o.apiBase, apiKey: o.apiKey, videoId: o.videoId };
+}
+function addCloudOptions(cmd) {
+  return cmd.option("--api-base <url>", "API base URL (else CLIPREADY_API_BASE / API_BASE)").option("--api-key <key>", "API credential (else CLIPREADY_API_KEY / RUN_TOKEN)").option("--video-id <id>", "Video id (else VIDEO_ID)");
+}
+async function withCloudErrors(json, fn) {
+  try {
+    await fn();
+  } catch (err) {
+    if (json) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+}
+var cloudCmd = program.command("cloud").description("Cloud render + status (clipready render API)");
+addCloudOptions(
+  cloudCmd.command("render").description("Submit a render; with --wait, poll to completion and download the result").requiredOption("--job-dir <path>", "Job directory (download target)").requiredOption("--mode <mode>", "preview|final").option("--wait", "Poll until the render is terminal, then download").option("--poll-interval <s>", "Poll interval in seconds", "10").option("--out <path>", "Output path (default <job>/preview.mp4 or final.mp4)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const mode = o.mode;
+    if (mode !== "preview" && mode !== "final") throw new Error("--mode must be preview|final");
+    const jobDir = resolvePath(o.jobDir);
+    const client = new CloudClient(resolveConfig(cloudFlags(o), { requireVideoId: true }));
+    const created = await client.createRender(mode);
+    if (!o.wait) {
+      if (o.json) console.log(JSON.stringify({ ok: true, render_id: created.renderId, status: created.status }, null, 2));
+      else {
+        console.log(`render_id: ${created.renderId}`);
+        console.log(`status: ${created.status}`);
+      }
+      return;
+    }
+    const intervalMs = (num(o.pollInterval) ?? 10) * 1e3;
+    const state = await pollRender(client, created.renderId, {
+      intervalMs,
+      onTick: (s, elapsed) => {
+        if (!o.json) process.stderr.write(`  [${Math.round(elapsed / 1e3)}s] ${s.status}
+`);
+      }
+    });
+    if (state.status === "failed") {
+      const detail = state.error !== void 0 ? typeof state.error === "string" ? state.error : JSON.stringify(state.error) : "unknown error";
+      throw new Error(`render ${created.renderId} failed: ${detail}`);
+    }
+    if (!state.videoUrl) throw new Error(`render ${created.renderId} completed without a video_url`);
+    const out = o.out ? resolvePath(o.out) : defaultRenderOut(jobDir, mode);
+    const dl = await client.download(state.videoUrl, out);
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, render_id: created.renderId, status: state.status, video_url: state.videoUrl, out: dl.path, bytes: dl.bytes }, null, 2));
+    } else {
+      console.log(`render_id: ${created.renderId}`);
+      console.log(`status: ${state.status}`);
+      console.log(`out: ${dl.path} (${dl.bytes} bytes)`);
+    }
+  });
+});
+addCloudOptions(
+  cloudCmd.command("status").description("Fetch the current status of a render").argument("<render_id>", "Render id").option("--json", "Print JSON")
+).action(async (renderId, o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const client = new CloudClient(resolveConfig(cloudFlags(o)));
+    const state = await client.getRender(renderId);
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, render_id: renderId, status: state.status, video_url: state.videoUrl ?? null, error: state.error ?? null }, null, 2));
+    } else {
+      console.log(`render_id: ${renderId}`);
+      console.log(`status: ${state.status}`);
+      if (state.videoUrl) console.log(`video_url: ${state.videoUrl}`);
+      if (state.error !== void 0) console.log(`error: ${typeof state.error === "string" ? state.error : JSON.stringify(state.error)}`);
+    }
+    if (state.status === "failed") process.exitCode = 1;
+  });
+});
+var qaCmd = program.command("qa").description("Cloud QA: server-rendered filmstrip frames + waveform");
+addCloudOptions(
+  qaCmd.command("frames").description("Render a filmstrip PNG for a window and download it locally").requiredOption("--start <s>", "Window start (seconds)").requiredOption("--end <s>", "Window end (seconds)").option("--cols <n>", "Grid columns").option("--interval <s>", "Seconds between frames").option("--job-dir <path>", "Job directory (QA files go under <job>/qa)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const start = num(o.start);
+    const end = num(o.end);
+    if (start === void 0 || end === void 0) throw new Error("--start and --end are required numbers");
+    const client = new CloudClient(resolveConfig(cloudFlags(o), { requireVideoId: true }));
+    const res = await client.qaFrames({ start, end, cols: num(o.cols), interval: num(o.interval) });
+    const dir = qaDir(o.jobDir ? resolvePath(o.jobDir) : void 0);
+    const png = framesPngPath(dir, start, end);
+    const dl = await client.download(res.url, png);
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, path: dl.path, width: res.width, height: res.height, frames: res.frames, tStart: res.tStart, tEnd: res.tEnd }, null, 2));
+    } else {
+      console.log(`frames: ${dl.path}`);
+      console.log(`grid: ${res.frames} frame(s), ${res.width}x${res.height}, t ${res.tStart}s\u2013${res.tEnd}s`);
+    }
+  });
+});
+addCloudOptions(
+  qaCmd.command("waveform").description("Render a waveform PNG + word list for a window and download both").requiredOption("--start <s>", "Window start (seconds)").requiredOption("--end <s>", "Window end (seconds)").option("--job-dir <path>", "Job directory (QA files go under <job>/qa)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const start = num(o.start);
+    const end = num(o.end);
+    if (start === void 0 || end === void 0) throw new Error("--start and --end are required numbers");
+    const client = new CloudClient(resolveConfig(cloudFlags(o), { requireVideoId: true }));
+    const res = await client.qaWaveform({ start, end });
+    const dir = qaDir(o.jobDir ? resolvePath(o.jobDir) : void 0);
+    const png = waveformPngPath(dir, start, end);
+    const wordsPath = waveformWordsPath(dir, start, end);
+    const dl = await client.download(res.url, png);
+    mkdirSync4(dir, { recursive: true });
+    writeFileSync4(wordsPath, JSON.stringify(res.words, null, 2) + "\n", "utf8");
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, png: dl.path, words_path: wordsPath, words: res.words.length }, null, 2));
+    } else {
+      console.log(`waveform: ${dl.path}`);
+      console.log(`words: ${wordsPath} (${res.words.length} word(s))`);
+    }
+  });
+});
+var jobCmd = program.command("job").description("Job artifact sync from the cloud");
+addCloudOptions(
+  jobCmd.command("pull").description("Fetch cloud artifacts into the job dir, preserving relative paths").option("--job-dir <path>", "Job directory (default: cwd)").option("--only <names>", "Comma-separated subset of artifact names").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = o.jobDir ? resolvePath(o.jobDir) : process.cwd();
+    const client = new CloudClient(resolveConfig(cloudFlags(o), { requireVideoId: true }));
+    const result = await pullArtifacts(client, jobDir, parseOnly(o.only));
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, job_dir: jobDir, pulled: result.pulled, missing: result.missing }, null, 2));
+    } else {
+      console.log(`job: ${jobDir}`);
+      for (const a of result.pulled) console.log(`  ${a.name} \u2192 ${a.path} (${a.bytes} bytes)`);
+      if (result.pulled.length === 0) console.log("  (no artifacts pulled)");
+      if (result.missing.length > 0) console.log(`  missing (requested, not on server): ${result.missing.join(", ")}`);
+    }
+  });
+});
+program.command("skill").command("install").description("Install the bundled video-editing agent skill").option("--target <dir>", "Skills dir (default ~/.claude/skills)").option("--json", "Print JSON").action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const res = installSkill({ target: o.target });
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, source: res.source, dest: res.dest, files: res.files }, null, 2));
+    } else {
+      console.log(`installed skill: ${res.dest}`);
+      console.log(`source: ${res.source}`);
+      for (const f of res.files) console.log(`  ${f}`);
+    }
+  });
+});
+var reviewCmd = program.command("review").description("Review rounds: local prompt tooling + clipready review-session sync");
+reviewCmd.command("prompt").description("Write the review prompt, warnings, and/or open the review app").requiredOption("--job-dir <path>", "Job directory").option("--write-warnings", "Convert review.json to warnings.json").option("--open-app", "Open the review app at localhost:5180").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const job = loadJob(jobDir);
+  const reviewPrompt = writeVideoEditingPrompt(jobDir, job.stem, "review.prompt.md", "review.prompt.md");
+  console.log(`review_prompt: ${reviewPrompt}`);
+  if (o.writeWarnings) console.log(`warnings: ${writeWarningsFromReview(jobDir)}`);
+  if (o.openApp) {
+    const url = `http://localhost:5180/?job=${join5(jobDir).split("/").pop()}`;
+    await run(["open", url], { check: false, echo: false });
+    console.log(url);
+  }
+});
+function printPushCompileFailure(res, json) {
+  if (json) {
+    console.log(JSON.stringify({ ok: false, errors: res.errors, diagnostics: res.diagnostics }, null, 2));
+  } else if (res.diagnostics) {
+    for (const line of formatDiagnostics(res.diagnostics)) console.log(line);
+  } else {
+    for (const e of res.errors) console.log(`  [error] ${e.path}: ${e.message}`);
+  }
+  process.exitCode = 2;
+}
+addCloudOptions(
+  reviewCmd.command("pull").description("Pull the review session: round + instruction into <job>/review, timeline.json when absent").option("--job-dir <path>", "Job directory (default: cwd)").option("--source", "Also download the source video when absent locally").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = o.jobDir ? resolvePath(o.jobDir) : process.cwd();
+    const client = new CloudClient(resolveConfig(cloudFlags(o), { requireVideoId: true }));
+    const res = await pullReview(client, jobDir, { withSource: !!o.source });
+    if (o.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            job_dir: jobDir,
+            round: res.round ? {
+              round_id: res.round.roundId,
+              run_id: res.round.runId,
+              seq: res.round.seq,
+              mode: res.round.mode,
+              status: res.round.status,
+              changes: res.round.changes.length
+            } : null,
+            wrote_timeline: res.wroteTimeline,
+            downloaded_source: res.downloadedSource
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(`job: ${jobDir}`);
+      if (res.round) {
+        console.log(`round: ${res.round.roundId} (run ${res.round.runId}, seq ${res.round.seq}, ${res.round.mode}, ${res.round.status})`);
+        console.log(`instruction: ${instructionPath(jobDir)}`);
+        console.log(`changes: ${res.round.changes.length}`);
+      } else {
+        console.log("no active review round");
+      }
+      console.log(`timeline.json: ${res.wroteTimeline ? "written" : existsSync3(timelineJsonPath(jobDir)) ? "kept (already present locally)" : "not provided"}`);
+      if (res.downloadedSource) console.log(`source: ${res.downloadedSource}`);
+    }
+  });
+});
+addCloudOptions(
+  reviewCmd.command("push").description("Push review-round progress: a --stage event, a live --timeline update, or terminal --complete").option("--job-dir <path>", "Job directory (default: cwd)").option("--run-id <id>", "Run id (default: run_id from <job>/review/round.json)").option("--stage <type>", `Progress event type: ${REVIEW_STAGES.join("|")}`).option("--message <text>", "Optional message payload for --stage").option("--timeline", "Compile timeline.json and push a timeline_update (review page updates live)").option("--complete", "Compile fresh and push the terminal completed event").option("--duration <seconds>", "Total kept duration for --complete (required with --complete)").option("--outcomes <file>", "Per-change outcomes JSON for --complete ([{change_id, ok, note?}])").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = o.jobDir ? resolvePath(o.jobDir) : process.cwd();
+    const modeCount = [o.stage !== void 0, !!o.timeline, !!o.complete].filter(Boolean).length;
+    if (modeCount !== 1) {
+      throw new Error("pass exactly one of --stage <type>, --timeline, or --complete");
+    }
+    const client = new CloudClient(resolveConfig(cloudFlags(o), { requireVideoId: true }));
+    const runId = resolveRunId(jobDir, o.runId);
+    if (o.stage !== void 0) {
+      await pushStage(client, runId, o.stage, o.message);
+      if (o.json) console.log(JSON.stringify({ ok: true, run_id: runId, type: o.stage }, null, 2));
+      else console.log(`pushed: ${o.stage} (run ${runId})`);
+      return;
+    }
+    if (o.timeline) {
+      const res2 = await pushTimeline(client, jobDir, runId);
+      if (!res2.ok) {
+        printPushCompileFailure(res2, !!o.json);
+        return;
+      }
+      if (o.json) {
+        console.log(JSON.stringify({ ok: true, run_id: runId, type: "timeline_update", timeline_hash: res2.timelineHash, output_duration_s: res2.plan.outputDurationS, segments: res2.plan.segments.length, assets: res2.assets }, null, 2));
+      } else {
+        console.log(`pushed: timeline_update (run ${runId})`);
+        console.log(`output: ${res2.plan.outputDurationS.toFixed(2)}s, ${res2.plan.segments.length} segment(s)`);
+        console.log(`timeline_hash: ${res2.timelineHash}`);
+        if (Object.keys(res2.assets).length > 0) console.log(`assets: ${Object.keys(res2.assets).length} synced`);
+      }
+      return;
+    }
+    const durationS = num(o.duration);
+    if (durationS === void 0) throw new Error("--complete requires --duration <seconds>");
+    const res = await pushComplete(client, jobDir, runId, {
+      durationS,
+      outcomesPath: o.outcomes ? resolvePath(o.outcomes) : void 0
+    });
+    if (!res.ok) {
+      printPushCompileFailure(res, !!o.json);
+      return;
+    }
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, run_id: runId, type: "completed", duration_s: res.durationS, outcomes: res.outcomes?.length ?? 0, assets: res.assets }, null, 2));
+    } else {
+      console.log(`pushed: completed (run ${runId})`);
+      console.log(`duration_s: ${res.durationS}`);
+      if (res.outcomes) console.log(`outcomes: ${res.outcomes.length} change(s)`);
+      if (Object.keys(res.assets).length > 0) console.log(`assets: ${Object.keys(res.assets).length} synced`);
+    }
+  });
+});
+program.command("status").description("Print job status and artifact paths").requiredOption("--job-dir <path>", "Job directory").option("--json", "Print JSON").action(async (o) => {
+  const jobDir = resolvePath(o.jobDir);
+  const payload = await statusPayload(jobDir);
+  if (o.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(`job: ${payload.job_dir}`);
+  console.log(`source: ${payload.source}`);
+  const tr = payload.transcript;
+  if (tr) console.log(`transcript: ${tr.word_count} words, coverage gap ${tr.coverage_gap_s.toFixed(2)}s`);
+  const edl = payload.edl;
+  if (edl) console.log(`edl: ${edl.range_count} ranges, ${edl.total_duration_s}s`);
+  const prev = payload.preview;
+  if (prev) console.log(`preview: ${prev.width}x${prev.height}, ${prev.duration_s.toFixed(2)}s`);
+  const rev = payload.review;
+  if (rev) console.log(`review: ${rev.verdict} (${rev.issue_count} issues)`);
+  const ver = payload.verify;
+  if (ver) console.log(`verify: ${ver.verdict} (${ver.finding_count} findings)`);
+  console.log(`qc pngs: ${payload.qc_png_count}`);
+  console.log("artifacts:");
+  for (const [name, path] of Object.entries(artifactPaths(jobDir, loadJob(jobDir).stem))) {
+    console.log(`  ${name}: ${existsSync3(path) ? "ok" : "missing"} ${path}`);
+  }
+});
+program.command("config").description("Manage CLI config (ElevenLabs API key)").argument("<action>", "set-key | path").argument("[value]", "key value for set-key").action((action, value) => {
+  if (action === "path") {
+    console.log(configEnvPath());
+    return;
+  }
+  if (action === "set-key") {
+    if (!value) throw new Error("usage: video-editing config set-key <key>");
+    mkdirSync4(configDir(), { recursive: true });
+    writeFileSync4(configEnvPath(), `ELEVENLABS_API_KEY=${value}
+`, { mode: 384 });
+    console.log(`wrote ${configEnvPath()}`);
+    return;
+  }
+  throw new Error(`unknown config action: ${action}`);
+});
+async function main() {
+  requireFfmpeg();
+  await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});