video-editing 1.3.1 → 3.0.0

package/dist/cli.js

@@ -1,1541 +1,507 @@
 #!/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";
+  CloudClient,
+  REVIEW_STAGES2,
+  compileRemote,
+  defaultRenderOut,
+  framesPngPath,
+  initCloudJob,
+  inspectPngPath,
+  installSkill,
+  instructionPath2,
+  jobJsonPath,
+  joinSourceWindows,
+  joinSpanWindow,
+  loadPublicConfigEnv,
+  loadTimeline2,
+  outWindowToSourceWindows,
+  pollRender,
+  publicConfigEnvPath,
+  pullFiles,
+  pullReview2,
+  pushComplete2,
+  pushFiles,
+  pushStage2,
+  pushTimeline2,
+  qaDir,
+  readJobFile,
+  readPlanSegments,
+  removePublicConfigKey,
+  resolveApiBase,
+  resolveApiKey,
+  resolveConfig,
+  resolveRunId2,
+  savePublicConfigKey,
+  stripTrailingSlash,
+  timelineJsonPath2,
+  transcribeCloud,
+  validateLocal,
+  verifyCloud,
+  videoIdFromJob,
+  waveformPngPath,
+  waveformWordsPath,
+  webVideoUrl
+} from "./chunk-W4IIL2T2.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";
+// src/public/cli.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, 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;
+loadPublicConfigEnv();
+function num(v) {
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : void 0;
 }
-function strOrNull(v) {
-  return typeof v === "string" ? v : null;
+function cloudFlags(o) {
+  return { apiBase: o.apiBase, apiKey: o.apiKey, videoId: o.videoId };
 }
-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)
-  };
+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, else <job>/job.json)");
 }
-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);
+function jobConfig(o, jobDir, opts = { requireVideoId: true }) {
+  const flags = cloudFlags(o);
+  const job = readJobFile(jobDir);
+  if (!flags.apiBase && !process.env.CLIPREADY_API_BASE && !process.env.API_BASE && job?.api_base) {
+    flags.apiBase = job.api_base;
   }
-  return void 0;
+  const cfg = resolveConfig(flags, { requireVideoId: false });
+  const videoId = opts.requireVideoId ? videoIdFromJob(jobDir, cfg.videoId) : cfg.videoId;
+  return { ...cfg, videoId };
 }
-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);
+async function withCloudErrors(json, fn) {
   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 };
+    await fn();
   } catch (err) {
-    if (err instanceof Error && err.name === "AbortError") {
-      throw new Error(`download timed out after ${opts.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS}ms: ${url}`);
+    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;
-  } 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 jobDirOf(o) {
+  return o.jobDir ? resolvePath(String(o.jobDir)) : process.cwd();
 }
-function roundJsonPath(jobDir) {
-  return join(reviewDir(jobDir), "round.json");
+var pkg;
+try {
+  pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+} catch {
+  pkg = { version: "3.0.0" };
 }
-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)) {
+var program = new Command();
+program.name("video-editing").description("Pure-API cloud CLI for editing talking-head reels with clipready: init (upload + server ingest/transcribe), timeline authoring, cloud compile/render/verify/QA, file sync, review rounds. No local media tools needed \u2014 just Node \u2265 20 and CLIPREADY_API_KEY.").version(pkg.version);
+addCloudOptions(
+  program.command("init").description("Create the cloud job end-to-end: stream the source up, run server-side ingest (probe + transcription + screening), pull the transcript/brief artifacts, write <job>/job.json. Covers what init+transcribe used to do \u2014 no separate transcribe needed.").requiredOption("--source <path>", "Source video path").option("--job-dir <path>", "Job directory (default ./job_<stem>)").option("--title <title>", "Project title (default: source stem)").option("--poll-interval <s>", "Ingest-run poll interval in seconds", "5").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const cfg = resolveConfig(cloudFlags(o), { requireVideoId: false });
+    const client = new CloudClient(cfg);
+    let res;
     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 };
+      res = await initCloudJob(client, {
+        source: o.source,
+        jobDir: o.jobDir,
+        title: o.title,
+        pollIntervalMs: (num(o.pollInterval) ?? 5) * 1e3,
+        verbose: !o.json
+      });
+    } catch (err) {
+      if (err instanceof Error && /\/v1\/me|401|403|invalid.*(key|token)|unauthorized/i.test(err.message)) {
+        throw new Error(`${err.message}
+Your credential was rejected \u2014 get your API key at ${cfg.base}/settings and run \`video-editing config set-key <key>\`.`);
       }
+      throw err;
     }
-    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 } : {}
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, job_dir: res.jobDir, job_json: res.jobJson, video_id: res.videoId, project_id: res.projectId, stem: res.stem, duration_s: res.durationS, uploaded: res.uploaded, uploaded_bytes: res.uploadedBytes, run_id: res.runId, pulled: res.pulled.pulled.map((p) => p.path), missing: res.pulled.missing, web_url: res.webUrl }, null, 2));
+    } else {
+      console.log(`job: ${res.jobDir}`);
+      console.log(`video_id: ${res.videoId}`);
+      console.log(`project_id: ${res.projectId}`);
+      console.log(`job.json: ${res.jobJson}`);
+      for (const p of res.pulled.pulled) console.log(`  ${p.path} \u2192 ${p.localPath}${p.skipped ? " (unchanged)" : ""}`);
+      if (res.pulled.missing.length > 0) console.log(`  missing on server: ${res.pulled.missing.join(", ")}`);
+      console.log(`web: ${res.webUrl}`);
     }
   });
-  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)}`);
+});
+addCloudOptions(
+  program.command("transcribe").description("Re-run/pull transcription: pull the transcript artifacts when they already exist server-side, else run server-side ingest and pull (init already did this once)").option("--job-dir <path>", "Job directory (default: cwd)").option("--poll-interval <s>", "Run poll interval in seconds", "5").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    const cfg = jobConfig(o, jobDir);
+    const client = new CloudClient(cfg);
+    const job = readJobFile(jobDir);
+    const res = await transcribeCloud(client, jobDir, {
+      stem: job?.stem ?? "source",
+      pollIntervalMs: (num(o.pollInterval) ?? 5) * 1e3,
+      verbose: !o.json
+    });
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, run_id: res.runId, pulled: res.pulled.pulled.map((p) => p.path), missing: res.pulled.missing }, null, 2));
+    } else {
+      if (res.runId) console.log(`run: ${res.runId}`);
+      for (const p of res.pulled.pulled) console.log(`  ${p.path} \u2192 ${p.localPath}${p.skipped ? " (unchanged)" : ""}`);
+      if (res.pulled.missing.length > 0) console.log(`  missing on server: ${res.pulled.missing.join(", ")}`);
     }
-    return { change_id: r.change_id, ok: r.ok, ...r.note !== void 0 ? { note: r.note } : {} };
   });
+});
+var timelineCmd = program.command("timeline").description("TimelineV2 authoring: validate locally, resolve/compile on the server");
+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}`);
 }
-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 } : {}
+addCloudOptions(
+  timelineCmd.command("validate").description("Schema + semantic + capability validation of <job>/timeline.json (local)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print the JSON verdict")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    jobConfig(o, jobDir, { requireVideoId: false });
+    const loaded = loadTimeline2(jobDir);
+    if (!loaded.doc) {
+      printTimelineErrors(loaded.errors, !!o.json);
+      process.exitCode = 2;
+      return;
     }
-  });
-  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})`);
+    const v = validateLocal(loaded.doc);
+    if (o.json) {
+      console.log(JSON.stringify({ ok: v.ok, uses: v.uses, errors: v.errors, warnings: v.warnings }, null, 2));
+    } else {
+      console.log(`timeline: ${timelineJsonPath2(jobDir)}`);
+      console.log(`valid: ${v.ok ? "yes" : "NO"} (${v.errors.length} error(s), ${v.warnings.length} warning(s))`);
+      console.log(`uses: ${v.uses.join(", ") || "(none)"}`);
+      for (const e of v.errors) console.log(`  [error] ${e.path}: ${e.message}`);
+      for (const w of v.warnings) console.log(`  [warn]  ${w.path}: ${w.message}`);
     }
-    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
+    if (!v.ok) process.exitCode = 2;
   });
-  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)}`);
+addCloudOptions(
+  timelineCmd.command("resolve").description("Resolve a transcript phrase to source seconds (server-side)").requiredOption("--phrase <text>", "Phrase to locate in the word-level transcript").option("--source <name>", "Source name (multi-source timelines)").option("--occurrence <n>", "Pick the n-th occurrence (1-based)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const res = await client.resolveRemote({
+      phrase: o.phrase,
+      ...o.source !== void 0 ? { source: o.source } : {},
+      ...num(o.occurrence) !== void 0 ? { occurrence: num(o.occurrence) } : {}
+    });
+    if (o.json) {
+      console.log(JSON.stringify(res, null, 2));
+    } else if (res.start !== void 0 && res.end !== void 0) {
+      console.log(`resolved: ${res.start}s - ${res.end}s${res.occurrence !== void 0 ? ` (occurrence ${res.occurrence})` : ""}`);
+      if (typeof res.context === "string") console.log(`context: ${res.context}`);
+    } else if (Array.isArray(res.candidates)) {
+      console.log(`ambiguous: ${res.candidates.length} occurrence(s); pass --occurrence`);
+      for (const c of res.candidates) {
+        console.log(`  #${c.occurrence} ${c.start}s - ${c.end}s: ${c.context ?? ""}`);
+      }
+      process.exitCode = 3;
+    } else if (Array.isArray(res.suggestions)) {
+      console.log(`not found: "${o.phrase}"`);
+      for (const s of res.suggestions) {
+        console.log(`  did you mean "${s.text}" @${s.start}s (similarity ${s.similarity})`);
+      }
+      process.exitCode = 1;
+    } else {
+      console.log(JSON.stringify(res, null, 2));
     }
-  }
-  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);
+async function runRemoteCompile(o) {
+  const jobDir = jobDirOf(o);
+  const client = new CloudClient(jobConfig(o, jobDir));
+  const loaded = loadTimeline2(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);
+  const v = validateLocal(loaded.doc);
+  if (!v.ok) {
+    printTimelineErrors(v.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);
+  const res = await compileRemote(client, jobDir, loaded);
+  const diagnostics = res.response.diagnostics;
+  const job = readJobFile(jobDir);
+  const webUrl = res.ok && job && job.project_id !== "" ? webVideoUrl(client.cfg.base, job.project_id, job.video_id) : null;
   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
-      )
-    );
+    console.log(JSON.stringify({ ok: res.ok, plan: res.planPath ?? null, edl: res.edlPath ?? null, diagnostics: res.response.diagnostics ?? null, uses: res.response.uses ?? null, web_url: webUrl }, 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;
+    if (res.ok && res.planPath) {
+      console.log(`plan: ${res.planPath}`);
+      if (res.edlPath) console.log(`edl: ${res.edlPath}`);
+      if (Array.isArray(res.response.uses)) console.log(`uses: ${res.response.uses.join(", ") || "(none)"}`);
     }
-  }
-  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}`);
+    console.log(`diagnostics: ${res.diagnosticsPath}`);
+    for (const e of diagnostics?.errors ?? []) {
+      const d = e;
+      console.log(`  [error] ${d.path ?? ""}: ${d.message ?? ""}`);
     }
-    return;
+    if (webUrl) console.log(`View & comment: ${webUrl}`);
   }
-  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})`);
+  if (!res.ok) {
+    const ambiguous = (diagnostics?.errors ?? []).some((e) => e.code === "anchor-ambiguous");
+    process.exitCode = ambiguous ? 3 : 2;
   }
-  process.exitCode = 1;
+}
+addCloudOptions(
+  timelineCmd.command("compile").description("Compile timeline.json on the server \u2192 resolved/plan.json + diagnostics + legacy edl.json (written verbatim)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, () => runRemoteCompile(o));
 });
 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}`);
-  }
+addCloudOptions(
+  captionsCmd.command("generate").description("Enable captions in timeline.json (preset only), then server-compile to derive/report cues").option("--job-dir <path>", "Job directory (default: cwd)").option("--preset <name>", "Caption preset: grouped (default) | opus-karaoke", "grouped").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    const tlPath = timelineJsonPath2(jobDir);
+    if (!existsSync(tlPath)) throw new Error(`timeline not found: ${tlPath}`);
+    const raw = JSON.parse(readFileSync(tlPath, "utf8"));
+    const captions = raw.captions !== null && typeof raw.captions === "object" ? raw.captions : {};
+    captions.enabled = true;
+    captions.preset = o.preset;
+    raw.captions = captions;
+    writeFileSync(tlPath, JSON.stringify(raw, null, 2) + "\n", "utf8");
+    if (!o.json) console.log(`captions: enabled (preset ${o.preset}) in ${tlPath}`);
+    await runRemoteCompile(o);
+  });
 });
-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")
+  program.command("verify").description("Content-verify the rendered preview fully server-side (no upload): start the run, poll, pull verify.json").option("--job-dir <path>", "Job directory (default: cwd)").option("--full", "Verify the whole preview instead of per-join windows").option("--window <s>", "Per-join window length in seconds").option("--poll-interval <s>", "Run poll interval in seconds", "5").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}
-`);
-      }
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const res = await verifyCloud(client, jobDir, {
+      full: !!o.full,
+      windowS: num(o.window),
+      pollIntervalMs: (num(o.pollInterval) ?? 5) * 1e3,
+      verbose: !o.json
     });
-    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));
+      console.log(JSON.stringify({ ok: true, run_id: res.runId, verify: res.verifyPath, verdict: res.verdict, findings: res.findings }, null, 2));
     } else {
-      console.log(`render_id: ${created.renderId}`);
-      console.log(`status: ${state.status}`);
-      console.log(`out: ${dl.path} (${dl.bytes} bytes)`);
+      console.log(`verify: ${res.verdict ?? "(no verdict)"}${res.findings !== null ? ` (${res.findings} finding(s))` : ""}`);
+      console.log(`verify.json: ${res.verifyPath}`);
     }
+    if (res.verdict === "needs-fixes") process.exitCode = 2;
   });
 });
+var qaCmd = program.command("qa").description("Cloud QC: server-rendered filmstrip frames, waveform (word-timing sidecar) + the combined inspect composite; windows in source seconds, or plan-addressed via --join / --out-start");
+function framesWindows(jobDir, o, joinMode = "split") {
+  const start = num(o.start);
+  const end = num(o.end);
+  const joinIdx = num(o.join);
+  const outStart = num(o.outStart);
+  const outEnd = num(o.outEnd);
+  const modes = [start !== void 0 || end !== void 0, joinIdx !== void 0, outStart !== void 0 || outEnd !== void 0];
+  if (modes.filter(Boolean).length !== 1) {
+    throw new Error("pass exactly one addressing mode: --start/--end (source s), --join <i>, or --out-start/--out-end (output s)");
+  }
+  if (joinIdx !== void 0) {
+    const segs = readPlanSegments(jobDir);
+    const span = num(o.span) ?? 2;
+    return joinMode === "span" ? [joinSpanWindow(segs, joinIdx, span)] : joinSourceWindows(segs, joinIdx, span);
+  }
+  if (outStart !== void 0 || outEnd !== void 0) {
+    if (outStart === void 0 || outEnd === void 0) throw new Error("--out-start and --out-end are both required");
+    return outWindowToSourceWindows(readPlanSegments(jobDir), outStart, outEnd);
+  }
+  if (start === void 0 || end === void 0 || end <= start) throw new Error("--start and --end must be numbers with end > start");
+  return [{ start, end, suffix: "" }];
+}
 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) => {
+  qaCmd.command("frames").description("Server-render a filmstrip PNG per window and download it under <job>/qa").option("--start <s>", "Window start (SOURCE seconds)").option("--end <s>", "Window end (SOURCE seconds)").option("--join <i>", "Plan join index (1-based): filmstrips for the last/first --span seconds of the two segments meeting there (-a tail, -b head)").option("--span <s>", "Seconds per side for --join", "2").option("--out-start <s>", "Window start in OUTPUT seconds (mapped through resolved/plan.json)").option("--out-end <s>", "Window end in OUTPUT seconds").option("--cols <n>", "Grid columns").option("--interval <s>", "Seconds between frames").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
-    const client = new CloudClient(resolveConfig(cloudFlags(o)));
-    const state = await client.getRender(renderId);
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const windows = framesWindows(jobDir, o);
+    const dir = qaDir(jobDir);
+    const outputs = [];
+    for (const w of windows) {
+      const res = await client.qaFrames({ start: w.start, end: w.end, cols: num(o.cols), interval: num(o.interval) });
+      const png = framesPngPath(dir, w.start, w.end, w.suffix);
+      const dl = await client.download(res.url, png);
+      outputs.push({ png: dl.path, width: res.width, height: res.height, frames: res.frames, tStart: res.tStart, tEnd: res.tEnd });
+    }
     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));
+      console.log(JSON.stringify({ ok: true, frames: outputs.map((r) => ({ png: r.png, width: r.width, height: r.height, frames: r.frames, t_start: r.tStart, t_end: r.tEnd })) }, 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)}`);
+      for (const r of outputs) {
+        console.log(`frames: ${r.png}`);
+        console.log(`grid: ${r.frames} frame(s), ${r.width}x${r.height}, t ${r.tStart}s\u2013${r.tEnd}s`);
+      }
     }
-    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")
+  qaCmd.command("inspect").description("Server-render the combined close-look composite (filmstrip + waveform + word labels + red cut shading from the compiled plan) per window and download it under <job>/qa").option("--start <s>", "Window start (SOURCE seconds)").option("--end <s>", "Window end (SOURCE seconds)").option("--join <i>", "Plan join index (1-based): ONE continuous composite spanning the cut \u2014 --span s of kept tail, the red-shaded cut region, --span s of kept head").option("--span <s>", "Seconds per side for --join", "2").option("--out-start <s>", "Window start in OUTPUT seconds (mapped through resolved/plan.json)").option("--out-end <s>", "Window end in OUTPUT seconds").option("--n-frames <n>", "Filmstrip frame count", "10").option("--job-dir <path>", "Job directory (default: cwd)").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);
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const windows = framesWindows(jobDir, o, "span");
+    const dir = qaDir(jobDir);
+    const outputs = [];
+    for (const w of windows) {
+      const res = await client.qaInspect({ start: w.start, end: w.end, nFrames: num(o.nFrames) });
+      const png = inspectPngPath(dir, w.start, w.end, w.suffix);
+      const dl = await client.download(res.url, png);
+      outputs.push({ png: dl.path, tStart: res.tStart, tEnd: res.tEnd, cuts: res.cuts, cached: res.cached });
+    }
     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));
+      console.log(JSON.stringify({ ok: true, inspect: outputs.map((r) => ({ png: r.png, t_start: r.tStart, t_end: r.tEnd, cuts: r.cuts, cached: r.cached })) }, 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`);
+      for (const r of outputs) {
+        console.log(`inspect: ${r.png}`);
+        console.log(`window: t ${r.tStart}s\u2013${r.tEnd}s, ${r.cuts.length} cut(s) shaded${r.cached ? " (cached)" : ""}`);
+      }
     }
   });
 });
 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")
+  qaCmd.command("waveform").description("Server-render a waveform PNG + word-timing sidecar for a source-time window").requiredOption("--start <s>", "Window start (SOURCE seconds)").requiredOption("--end <s>", "Window end (SOURCE seconds)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
 ).action(async (o) => {
   await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
     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 }));
+    if (start === void 0 || end === void 0 || end <= start) throw new Error("--start and --end must be numbers with end > start");
     const res = await client.qaWaveform({ start, end });
-    const dir = qaDir(o.jobDir ? resolvePath(o.jobDir) : void 0);
+    const dir = qaDir(jobDir);
     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 {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(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(", ")}`);
-    }
+var filesCmd = program.command("files").description("Sync the video's virtual file system with the job dir (byte-exact, sha256-skipped)");
+function registerFilesPull(cmd, deprecated) {
+  addCloudOptions(
+    cmd.description(
+      deprecated ? "[deprecated: use `files pull`] Fetch cloud files into the job dir" : "Fetch cloud files into the job dir, preserving relative paths (writes exactly the served bytes)"
+    ).option("--job-dir <path>", "Job directory (default: cwd)").option("--only <paths>", "Comma-separated subset of file paths").option("--json", "Print JSON")
+  ).action(async (o) => {
+    await withCloudErrors(!!o.json, async () => {
+      if (deprecated) process.stderr.write("warning: `job pull` is deprecated; use `files pull`\n");
+      const jobDir = jobDirOf(o);
+      const client = new CloudClient(jobConfig(o, jobDir));
+      const only = typeof o.only === "string" && o.only.trim() !== "" ? o.only.split(",").map((s) => s.trim()).filter((s) => s !== "") : void 0;
+      const res = await pullFiles(client, jobDir, { only });
+      if (o.json) {
+        console.log(JSON.stringify({ ok: true, job_dir: jobDir, pulled: res.pulled.map((p) => ({ path: p.path, local: p.localPath, bytes: p.bytes, skipped: p.skipped })), missing: res.missing }, null, 2));
+      } else {
+        console.log(`job: ${jobDir}`);
+        for (const p of res.pulled) console.log(`  ${p.path} \u2192 ${p.localPath} (${p.bytes} bytes${p.skipped ? ", unchanged" : ""})`);
+        if (res.pulled.length === 0) console.log("  (no files pulled)");
+        if (res.missing.length > 0) console.log(`  missing (requested, not on server): ${res.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) => {
+}
+registerFilesPull(filesCmd.command("pull"), false);
+registerFilesPull(program.command("job", { hidden: true }).command("pull"), true);
+addCloudOptions(
+  filesCmd.command("push").description("Push local files (jobDir-relative paths) into the VFS; unchanged files are skipped by sha256").argument("<paths...>", "jobDir-relative file paths to push").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (paths, o) => {
   await withCloudErrors(!!o.json, async () => {
-    const res = installSkill({ target: o.target });
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const res = await pushFiles(client, jobDir, paths);
     if (o.json) {
-      console.log(JSON.stringify({ ok: true, source: res.source, dest: res.dest, files: res.files }, null, 2));
+      console.log(JSON.stringify({ ok: true, pushed: res.map((p) => ({ path: p.path, bytes: p.bytes, mode: p.mode, skipped: p.skipped })) }, null, 2));
     } else {
-      console.log(`installed skill: ${res.dest}`);
-      console.log(`source: ${res.source}`);
-      for (const f of res.files) console.log(`  ${f}`);
+      for (const p of res) console.log(`  ${p.path} (${p.bytes} bytes, ${p.mode})`);
     }
   });
 });
-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;
-}
+var reviewCmd = program.command("review").description("Review rounds: session sync + progress/terminal pushes (plans compiled server-side)");
 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 });
+    const jobDir = jobDirOf(o);
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const res = await pullReview2(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
-        )
-      );
+      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(`instruction: ${instructionPath2(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"}`);
+      console.log(`timeline.json: ${res.wroteTimeline ? "written" : existsSync(timelineJsonPath2(jobDir)) ? "kept (already present locally)" : "not provided"}`);
       if (res.downloadedSource) console.log(`source: ${res.downloadedSource}`);
     }
   });
 });
+function printPush2Failure(res, json) {
+  if (json) console.log(JSON.stringify({ ok: false, errors: res.errors, diagnostics: res.diagnostics }, null, 2));
+  else for (const e of res.errors) console.log(`  [error] ${e.path}: ${e.message}`);
+  process.exitCode = 2;
+}
 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")
+  reviewCmd.command("push").description("Push review-round progress: a --stage event, a live --timeline update, or terminal --complete (compiles on the server)").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_STAGES2.join("|")}`).option("--message <text>", "Optional message payload for --stage").option("--timeline", "Server-compile timeline.json and push a timeline_update").option("--complete", "Server-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 jobDir = jobDirOf(o);
     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 (modeCount !== 1) throw new Error("pass exactly one of --stage <type>, --timeline, or --complete");
+    const client = new CloudClient(jobConfig(o, jobDir));
+    const runId = resolveRunId2(jobDir, o.runId);
     if (o.stage !== void 0) {
-      await pushStage(client, runId, o.stage, o.message);
+      await pushStage2(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 {
+      const res2 = await pushTimeline2(client, jobDir, runId);
+      if (!res2.ok) return printPush2Failure(res2, !!o.json);
+      if (o.json) console.log(JSON.stringify({ ok: true, run_id: runId, type: "timeline_update", timeline_hash: res2.timelineHash, 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 (res2.timelineHash) 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, {
+    const res = await pushComplete2(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 {
+    if (!res.ok) return printPush2Failure(res, !!o.json);
+    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)`);
@@ -1543,48 +509,237 @@ addCloudOptions(
     }
   });
 });
-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));
+addCloudOptions(
+  reviewCmd.command("prompt").description("Print the pulled review-round instruction (run `review pull` first)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    jobConfig(o, jobDir, { requireVideoId: false });
+    const path = instructionPath2(jobDir);
+    if (!existsSync(path)) throw new Error(`no instruction found at ${path} \u2014 run \`video-editing review pull\` first`);
+    if (o.json) console.log(JSON.stringify({ ok: true, instruction: path, content: readFileSync(path, "utf8") }, null, 2));
+    else {
+      console.log(`instruction: ${path}`);
+      process.stdout.write(readFileSync(path, "utf8"));
+    }
+  });
+});
+async function runCloudRender(o, wait) {
+  const mode = o.mode;
+  if (mode !== "preview" && mode !== "final") throw new Error("--mode must be preview|final");
+  const jobDir = jobDirOf(o);
+  const client = new CloudClient(jobConfig(o, jobDir));
+  const created = await client.createRender(mode);
+  if (!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(String(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(
+  program.command("render").description("Cloud-render the compiled plan (works right after `timeline compile`); waits and downloads by default").option("--mode <mode>", "preview|final", "preview").option("--job-dir <path>", "Job directory (download target; default: cwd)").option("--no-wait", "Submit only; do not poll/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, () => runCloudRender(o, o.wait !== false));
+});
+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("--mode <mode>", "preview|final").option("--job-dir <path>", "Job directory (download target; default: cwd)").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, () => runCloudRender(o, !!o.wait));
+});
+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;
+  });
+});
+addCloudOptions(
+  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 () => {
+    resolveConfig(cloudFlags(o), { requireVideoId: false });
+    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 STATUS_FILES = [
+  "timeline.json",
+  "resolved/plan.json",
+  "resolved/diagnostics.json",
+  "edl.json",
+  "preview.mp4",
+  "final.mp4",
+  "takes_packed.md",
+  "flags.txt",
+  "word_dump.txt",
+  "coverage.json",
+  "probe.json",
+  "verify.json",
+  "review/round.json",
+  "review/instruction.md"
+];
+addCloudOptions(
+  program.command("status").description("Print the cloud job's local state (job.json + which artifacts are present)").option("--job-dir <path>", "Job directory (default: cwd)").option("--json", "Print JSON")
+).action(async (o) => {
+  await withCloudErrors(!!o.json, async () => {
+    const jobDir = jobDirOf(o);
+    jobConfig(o, jobDir, { requireVideoId: false });
+    const job = readJobFile(jobDir);
+    const artifacts = {};
+    if (job) artifacts[`transcripts/${job.stem}.json`] = existsSync(join(jobDir, "transcripts", `${job.stem}.json`));
+    for (const f of STATUS_FILES) artifacts[f] = existsSync(join(jobDir, f));
+    if (o.json) {
+      console.log(JSON.stringify({ ok: true, job_dir: jobDir, job: job ?? null, artifacts }, null, 2));
+    } else {
+      console.log(`job: ${jobDir}`);
+      if (job) {
+        console.log(`video_id: ${job.video_id}`);
+        console.log(`project_id: ${job.project_id}`);
+        console.log(`stem: ${job.stem} (${job.duration_s}s)`);
+      } else {
+        console.log(`job.json: missing (${jobJsonPath(jobDir)}) \u2014 run \`video-editing init\``);
+      }
+      console.log("artifacts:");
+      for (const [name, ok] of Object.entries(artifacts)) console.log(`  ${name}: ${ok ? "ok" : "missing"}`);
+    }
+  });
+});
+function promptSecret(promptText) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    process.stderr.write(promptText);
+    if (!stdin.isTTY) {
+      let data = "";
+      stdin.setEncoding("utf8");
+      stdin.on("data", (d) => data += d);
+      stdin.on("end", () => resolve(data.trim()));
+      stdin.resume();
+      return;
+    }
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    let value = "";
+    const done = (fn) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      process.stderr.write("\n");
+      fn();
+    };
+    const onData = (chunk) => {
+      for (const c of chunk) {
+        if (c === "\r" || c === "\n" || c === "") return done(() => resolve(value.trim()));
+        if (c === "") return done(() => reject(new Error("cancelled")));
+        if (c === "\x7F" || c === "\b") value = value.slice(0, -1);
+        else value += c;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+var authCmd = program.command("auth").description("Log in to ClipReady (stores the API key in the config file)");
+authCmd.command("api-key").description("Paste your ClipReady API key once \u2014 verified against the cloud, then saved").argument("[key]", "API key (omit to be prompted; input is hidden)").option("--api-base <url>", "API base URL (default: the hosted ClipReady cloud)").action(async (keyArg, o) => {
+  const base = stripTrailingSlash(resolveApiBase(o.apiBase));
+  const key = (keyArg ?? await promptSecret(`Paste your ClipReady API key (from ${base}/settings): `)).trim();
+  if (!key) throw new Error("no API key provided");
+  let keyName = null;
+  try {
+    const me = await new CloudClient({ base, credential: key }).me();
+    const k = me.key;
+    keyName = typeof k?.name === "string" ? k.name : null;
+  } catch (err) {
+    throw new Error(
+      `that key was rejected by ${base} \u2014 check it at ${base}/settings and try again` + (err instanceof Error ? `
+(${err.message})` : "")
+    );
+  }
+  savePublicConfigKey("CLIPREADY_API_KEY", key);
+  if (o.apiBase) savePublicConfigKey("CLIPREADY_API_BASE", base);
+  console.log(`Logged in${keyName ? ` with key "${keyName}"` : ""} (\u2026${key.slice(-4)}) \u2014 saved to ${publicConfigEnvPath()}`);
+  console.log(`Cloud: ${base}`);
+});
+authCmd.command("status").description("Show the active credential/base and verify them against the cloud").action(async () => {
+  loadPublicConfigEnv();
+  const base = stripTrailingSlash(resolveApiBase(void 0));
+  const key = resolveApiKey(void 0);
+  console.log(`config: ${publicConfigEnvPath()}`);
+  console.log(`cloud:  ${base}`);
+  if (!key) {
+    console.log("key:    (none) \u2014 run `video-editing auth api-key`");
+    process.exitCode = 1;
     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}`);
+  try {
+    const me = await new CloudClient({ base, credential: key }).me();
+    const k = me.key;
+    const keyName = typeof k?.name === "string" ? k.name : null;
+    console.log(`key:    \u2026${key.slice(-4)}${keyName ? ` ("${keyName}")` : ""} \u2014 valid`);
+  } catch {
+    console.log(`key:    \u2026${key.slice(-4)} \u2014 REJECTED by ${base}`);
+    process.exitCode = 1;
   }
 });
-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) => {
+authCmd.command("logout").description("Remove the stored API key").action(() => {
+  console.log(`removed key from ${removePublicConfigKey("CLIPREADY_API_KEY")}`);
+});
+program.command("config").description("Manage CLI config (clipready API key/base)").argument("<action>", "set-key | set-base | path").argument("[value]", "value for set-key / set-base").action((action, value) => {
   if (action === "path") {
-    console.log(configEnvPath());
+    console.log(publicConfigEnvPath());
     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()}`);
+    console.log(`wrote ${savePublicConfigKey("CLIPREADY_API_KEY", value)}`);
+    return;
+  }
+  if (action === "set-base") {
+    if (!value) throw new Error("usage: video-editing config set-base <url>");
+    console.log(`wrote ${savePublicConfigKey("CLIPREADY_API_BASE", value)}`);
     return;
   }
   throw new Error(`unknown config action: ${action}`);
 });
 async function main() {
-  requireFfmpeg();
   await program.parseAsync(process.argv);
 }
 main().catch((err) => {