editorbrain 0.32.0 → 0.34.0

package/README.md

@@ -5,13 +5,13 @@ Editorial references, brand context and portable video projects for Claude Code
 Inspect the CLI without configuring your agent:
 
 ```sh
-npx editorbrain@0.32.0 help
+npx editorbrain@0.34.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.32.0
+npm install -g editorbrain@0.34.0
 editorbrain login --url https://api.editorbrain.com
 editorbrain status --url https://api.editorbrain.com
 editorbrain projects list

package/bin/editorbrain.mjs

@@ -1,9 +1,5 @@
 #!/usr/bin/env node
 
-// packages/cli/src/sfx.ts
-import { readdir as readdir2, lstat as lstat3 } from "node:fs/promises";
-import { join as join2, extname as extname2, basename } from "node:path";
-
 // packages/core/src/creative-direction.ts
 var creativePreferenceSections = [
   { id: "brand", title: "Marca y tipograf\xEDa", question: "\xBFConservamos tus colores, fuentes e idioma, o quieres ajustarlos?" },
@@ -57125,13 +57121,6 @@ function canonicalFiles(files) {
   return result2;
 }
 
-// packages/cli/src/media-runtime.ts
-import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import { constants } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
-import { dirname, extname, parse, resolve } from "node:path";
-
 // packages/cli/src/errors.ts
 var CliError = class extends Error {
   constructor(code, message, hint, retryable = false, details = {}) {
@@ -57154,7 +57143,346 @@ function errorOutput(error) {
   return { error: safe, code: "COMMAND_FAILED", retryable: false, hint: "Read the command help and run editorbrain doctor. Do not retry writes blindly." };
 }
 
+// packages/cli/src/production-output.ts
+import { constants as constants2 } from "node:fs";
+import { mkdir as mkdir2, open as open2 } from "node:fs/promises";
+import { dirname as dirname2 } from "node:path";
+
+// packages/cli/src/io.ts
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, realpath, rename, unlink, link } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+async function ensureRoot(directory, create = false) {
+  const root = resolve(directory);
+  if (create) await mkdir(root, { recursive: true });
+  const info = await lstat(root);
+  if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("Workspace root must be a real directory, not a symlink");
+  return realpath(root);
+}
+async function checkedPath(root, path, document2 = true) {
+  if (document2) safeDocumentPath(path);
+  const target = resolve(root, path);
+  const rel = relative(root, target);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === ".." || resolve(path) === path) throw new Error("Path escapes workspace");
+  let cursor = root;
+  for (const segment of rel.split(sep)) {
+    cursor = join(cursor, segment);
+    try {
+      const info = await lstat(cursor);
+      if (info.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${path}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return target;
+}
+async function readText(root, path, document2 = true) {
+  const target = await checkedPath(root, path, document2);
+  const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new Error(`Not a regular file: ${path}`);
+    if (document2 && info.size > MAX_DOCUMENT_BYTES) throw new Error(`Document exceeds 128 KiB: ${path}`);
+    return new TextDecoder("utf-8", { fatal: true }).decode(await handle.readFile());
+  } finally {
+    await handle.close();
+  }
+}
+async function atomicWrite(root, path, content, options = {}) {
+  const target = await checkedPath(root, path, options.document ?? true);
+  await mkdir(dirname(target), { recursive: true });
+  await checkedPath(root, path, options.document ?? true);
+  const temporary = join(dirname(target), `.eh-${randomUUID()}.tmp`);
+  const handle = await open(temporary, "wx", options.mode ?? 420);
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.close();
+    await checkedPath(root, path, options.document ?? true);
+    if (options.overwrite === false) {
+      await link(temporary, target);
+      await unlink(temporary);
+    } else await rename(temporary, target);
+  } catch (error) {
+    await handle.close().catch(() => {
+    });
+    await unlink(temporary).catch(() => {
+    });
+    throw error;
+  }
+}
+async function readWorkspace(root) {
+  const files = /* @__PURE__ */ Object.create(null);
+  async function walk(path) {
+    const directory = await checkedPath(root, path, false);
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const child = `${path}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${child}`);
+      if (entry.name.startsWith(".")) continue;
+      if (entry.isDirectory()) {
+        if (path.startsWith("videos/") && ["assets", "renders"].includes(entry.name)) continue;
+        await walk(child);
+      } else if (entry.isFile() && /\.(json|md)$/.test(entry.name)) {
+        safeDocumentPath(child);
+        files[child] = await readText(root, child);
+      }
+    }
+  }
+  await walk(".editorharness");
+  await walk(".editorbrain");
+  await walk("videos");
+  return canonicalFiles(files);
+}
+async function readProjectWorkspace(root, projectId) {
+  assertIdentifier(projectId);
+  const projectPath = `videos/${projectId}/project.json`;
+  const projectContent = await readText(root, projectPath);
+  const checked = validateDocument(projectPath, projectContent);
+  if (!checked.valid) throw new ValidationError(checked.issues);
+  const project = JSON.parse(projectContent);
+  const files = { [projectPath]: projectContent };
+  for (const path of /* @__PURE__ */ new Set([...projectSources(project), ...optionalProjectSources(project)])) {
+    if (path === projectPath) continue;
+    const aliases2 = path.startsWith(".editorbrain/") ? [path, path.replace(/^\.editorbrain\//, ".editorharness/")] : [path];
+    for (const alias of aliases2) {
+      try {
+        files[alias] = await readText(root, alias);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+  }
+  if (await readText(root, projectPath) !== projectContent) throw new Error("The selected project changed while reading its context. Retry before editing.");
+  return canonicalFiles(files);
+}
+
+// packages/cli/src/production-output.ts
+async function productionOutputPath(root, relativePath) {
+  if (!relativePath.startsWith(".editorbrain-local/") || relativePath.split(/[\\/]/).some((p) => !p || p === ".." || p === ".") || /[\\\x00-\x1f\x7f]/.test(relativePath)) {
+    throw new CliError("LOCAL_OUTPUT_REQUIRED", "Production output must be inside .editorbrain-local/.", "Use --out .editorbrain-local/<project>/inventory.json, or omit --out for JSON stdout. These reports are not synced.");
+  }
+  return checkedPath(root, relativePath, false);
+}
+async function prepareSampleDirectory(root, path) {
+  const target = await productionOutputPath(root, path);
+  await mkdir2(dirname2(target), { recursive: true });
+  await productionOutputPath(root, path);
+  return target;
+}
+async function readProductionJson(root, path) {
+  const target = await checkedPath(root, path, false);
+  const handle = await open2(target, constants2.O_RDONLY | constants2.O_NOFOLLOW | constants2.O_NONBLOCK);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > 16 * 1024 * 1024) throw new CliError("INVALID_REPORT", "Expected a regular JSON file of at most 16 MiB.", "Select a local inventory, plan or check profile.");
+    return JSON.parse(await handle.readFile("utf8"));
+  } finally {
+    await handle.close();
+  }
+}
+async function saveProductionReport(root, path, report) {
+  const target = await productionOutputPath(root, path);
+  if (!path.endsWith(".json")) throw new CliError("INVALID_ARGUMENT", "Report output needs a .json extension.", "Use a new path under .editorbrain-local/.");
+  await atomicWrite(root, path, stableJson(report), { document: false, overwrite: false, mode: 384 });
+  return target;
+}
+function summarizeProductionReport(value) {
+  const r = value;
+  const base = { schemaVersion: r.schemaVersion, kind: r.kind, summary: true, mediaUploaded: false, quality: "not_assessed" };
+  if (r.kind === "editorbrain.media-inventory") return {
+    ...base,
+    complete: r.complete,
+    contentReviewed: false,
+    counts: { assets: r.assets.length, failures: r.failures.length, skipped: r.skipped.length },
+    assets: r.assets.slice(0, 8),
+    failures: r.failures.slice(0, 5),
+    omitted: { assets: Math.max(0, r.assets.length - 8), failures: Math.max(0, r.failures.length - 5), skipped: r.skipped.length },
+    next: "Inspect selected source content. Use media sample for specific frames. Read the saved report or rerun with --details for omitted metadata; no content was reviewed automatically."
+  };
+  if (r.kind === "editorbrain.media-samples") return { ...base, sourceSha256: r.source.sha256, frames: r.frames, contentReviewed: false, next: "View these frames to inspect composition. They do not prove motion or sound." };
+  if (r.kind === "editorbrain.production-plan-check") return {
+    ...base,
+    valid: r.valid,
+    inventoryComplete: r.inventoryComplete,
+    observations: r.observations,
+    sourceFilesReverified: false,
+    counts: { sources: r.coverage.length, findings: r.findings.length, repeatedPairs: r.repeatedPairs ?? 0 },
+    findings: [...r.findings].sort((a, b) => ({ error: 0, warning: 1, info: 2 })[a.severity] - { error: 0, warning: 1, info: 2 }[b.severity]).slice(0, 8),
+    omittedFindings: Math.max(0, r.findings.length - 8),
+    next: "Review source reuse and inspection gaps in the saved report. Observations are agent-declared, not independently certified."
+  };
+  if (r.kind === "editorbrain.render-check") return {
+    ...base,
+    complete: r.complete,
+    technicalStatus: r.technicalStatus,
+    file: r.file,
+    checks: r.checks,
+    findings: r.findings.slice(0, 8),
+    findingsSummary: r.findingsSummary,
+    omittedFindings: Math.max(0, r.findings.length - 8),
+    next: "Reconcile technical candidates with the brief; inspect the actual video/audio. Technical checks do not assess narrative, aesthetics or SFX audibility."
+  };
+  if (r.kind === "editorbrain.media-source-search") return {
+    ...base,
+    complete: r.complete,
+    results: r.results.slice(0, 5).map((item) => ({ provider: item.provider, id: item.id.slice(0, 180), title: item.title.slice(0, 180), sourceUrl: item.sourceUrl.length <= 1500 ? item.sourceUrl : null, author: item.author?.slice(0, 120) ?? null, license: { id: item.license.id, reason: item.license.reason, url: item.license.url && item.license.url.length <= 500 ? item.license.url : null }, contentReviewed: false, rightsVerified: false })),
+    metadataAbbreviated: true,
+    failures: r.failures.slice(0, 5),
+    counts: r.counts,
+    omitted: { results: Math.max(0, r.results.length - 5), failures: Math.max(0, r.failures.length - 5) },
+    searchExhaustive: false,
+    rightsVerified: false,
+    next: "Inspect relevant source pages and media. These archives supplement web image/video search; empty results do not prove absence on the internet."
+  };
+  if (r.kind === "editorbrain.evidence-check") return {
+    ...base,
+    valid: r.valid,
+    inventoryComplete: r.inventoryComplete,
+    observations: r.observations,
+    sourceFilesReverified: false,
+    factualTruth: "not_assessed",
+    reuseRights: "not_assessed",
+    findings: r.findings.slice(0, 8),
+    omitted: { findings: Math.max(0, r.findings.length - 8) }
+  };
+  if (r.kind === "editorbrain.audio-check") return {
+    ...base,
+    complete: r.complete,
+    technicalStatus: r.technicalStatus,
+    file: r.file,
+    fileStable: r.fileStable,
+    coverage: r.coverage,
+    measurements: r.measurements.slice(0, 8),
+    errorCode: r.errorCode,
+    creativeQuality: r.creativeQuality,
+    omitted: { measurements: Math.max(0, r.measurements.length - 8) },
+    next: "Measurements describe this exact file. Listen for intelligibility, pronunciation, SFX and sync when the modality is available."
+  };
+  if (r.kind === "editorbrain.motion-review") return {
+    ...base,
+    samples: r.samples ? { frameCount: r.samples.frameCount, fps: r.samples.fps, radiusFrames: r.samples.radiusFrames, samples: r.samples.samples.slice(0, 12), omittedSamples: Math.max(0, r.samples.samples.length - 12) } : null,
+    geometryReviews: r.geometryReviews.slice(0, 3).map((g) => ({ scope: g.scope, status: g.status, candidates: g.candidates.slice(0, 8), omittedCandidates: Math.max(0, g.candidates.length - 8), checks: g.checks })),
+    omittedGeometryReviews: Math.max(0, r.geometryReviews.length - 3),
+    next: "This plans samples and checks declared boxes only. Render/view those frames; read saved details for omitted candidates and intentional overlaps."
+  };
+  throw new CliError("INVALID_REPORT", "Unknown production report kind.", "Use media inventory/sample or production check/plan-check.");
+}
+
+// packages/cli/src/editing-batches.ts
+async function batchCommand(client, root, command, argument, flags) {
+  const fail2 = () => {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      "Use batches list/get/create/pause/resume/cancel/retry/detach/claim/renew/release/attention.",
+      "Create with --file batch.json; updates need --expected-revision; leases need --project and --lease-token UUID."
+    );
+  };
+  const lease = ["claim", "renew", "release", "attention"].includes(command), update = ["pause", "resume", "cancel", "retry", "detach"].includes(command);
+  if (!["list", "get", "create"].includes(command) && !lease && !update) fail2();
+  const allowed = [
+    "dir",
+    "url",
+    ...command === "create" ? ["file"] : command === "list" ? ["after"] : lease ? ["project", "lease-token"] : update ? [
+      "expected-revision",
+      ...["retry", "detach"].includes(command) ? ["project"] : []
+    ] : []
+  ];
+  for (const key of Object.keys(flags)) if (!allowed.includes(key)) fail2();
+  if (command === "list") {
+    if (argument) fail2();
+    return client.request(
+      "/v1/batches" + (typeof flags.after === "string" ? "?after=" + encodeURIComponent(flags.after) : "")
+    );
+  }
+  if (command === "create") {
+    if (argument || typeof flags.file !== "string") fail2();
+    const body = await readProductionJson(root, flags.file);
+    return client.request("/v1/batches", { method: "POST", body });
+  }
+  if (!argument || !/^[a-f0-9-]{36}$/i.test(argument)) fail2();
+  const path = "/v1/batches/" + argument;
+  if (command === "get") return client.request(path);
+  if (update) {
+    const revision = Number(flags["expected-revision"]);
+    if (!Number.isSafeInteger(revision) || revision < 1 || ["retry", "detach"].includes(command) && typeof flags.project !== "string")
+      fail2();
+    return client.request(path, {
+      method: "POST",
+      body: {
+        action: command,
+        expectedRevision: revision,
+        ...["retry", "detach"].includes(command) ? { projectId: flags.project } : {}
+      }
+    });
+  }
+  if (typeof flags.project !== "string" || !/^[a-z0-9][a-z0-9_-]{0,79}$/.test(flags.project) || typeof flags["lease-token"] !== "string" || !/^[a-f0-9-]{36}$/i.test(flags["lease-token"]))
+    fail2();
+  return client.request(path + "/lease", {
+    method: "POST",
+    body: {
+      action: command,
+      projectId: flags.project,
+      leaseToken: flags["lease-token"]
+    }
+  });
+}
+
+// packages/cli/src/project-progress-client.ts
+async function projectProgressCommand(client, command, flags) {
+  const fail2 = (message) => {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      message,
+      "Use projects progress/start/queue/complete --project ID. Read progress first; pass --expected-version HASH for changes."
+    );
+  };
+  if (!["progress", "start", "queue", "complete"].includes(command))
+    fail2("Unknown project command.");
+  const allowed = [
+    "project",
+    "url",
+    "dir",
+    ...command === "progress" ? [] : ["expected-version"],
+    ...command === "complete" ? ["revision", "user-confirmed"] : []
+  ];
+  for (const name of Object.keys(flags))
+    if (!allowed.includes(name)) fail2(`Unsupported flag --${name}.`);
+  if (typeof flags.project !== "string") fail2("--project is required.");
+  const project = assertIdentifier(flags.project), path = `/v1/projects/${encodeURIComponent(project)}/progress`;
+  if (command === "progress") return client.request(path);
+  if (typeof flags["expected-version"] !== "string" || !/^[a-f0-9]{64}$/.test(flags["expected-version"]))
+    fail2("--expected-version must be the current progress version.");
+  if (command === "complete" && (typeof flags.revision !== "string" || !/^[a-f0-9-]{36}$/.test(flags.revision) || flags["user-confirmed"] !== true))
+    fail2(
+      "Completion requires --revision UUID and --user-confirmed after explicit final-video approval."
+    );
+  return client.request(path, {
+    method: "POST",
+    body: {
+      action: command,
+      expectedVersion: flags["expected-version"],
+      ...command === "complete" ? { revisionId: flags.revision, userConfirmed: true } : {}
+    }
+  });
+}
+
+// packages/cli/src/sfx.ts
+import { readdir as readdir2, lstat as lstat3 } from "node:fs/promises";
+import { join as join2, extname as extname2, basename } from "node:path";
+
 // packages/cli/src/media-runtime.ts
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants as constants3 } from "node:fs";
+import { lstat as lstat2, open as open3, realpath as realpath2 } from "node:fs/promises";
+import { dirname as dirname3, extname, parse, resolve as resolve2 } from "node:path";
 var MediaToolError = class extends CliError {
   constructor(code, message) {
     super(code, message, code === "MEDIA_TOOL_NOT_FOUND" ? "Install FFmpeg/FFprobe separately and make them available on PATH; no account or model is needed." : "Review the local input and reported limit. An incomplete check does not validate the media.");
@@ -57206,24 +57534,24 @@ function resolveLocalMediaPath(value) {
   if (!value || value.includes("\0") || /[\r\n]/.test(value) || /^[a-z][a-z\d+.-]*:/i.test(value) && !(process.platform === "win32" && /^[a-z]:[\\/]/i.test(value)) || value.startsWith("\\\\")) {
     throw new MediaToolError("MEDIA_LOCAL_PATH_REQUIRED", "Provide a local filesystem path, not a URL, protocol or network share.");
   }
-  return resolve(value);
+  return resolve2(value);
 }
 async function assertNoMediaSymlinks(value) {
   const path = resolveLocalMediaPath(value);
   let cursor = path;
   while (cursor !== parse(cursor).root) {
-    const info = await lstat(cursor);
+    const info = await lstat2(cursor);
     if (info.isSymbolicLink()) {
-      const systemAlias = process.platform === "darwin" && (cursor === "/tmp" || cursor === "/var") && await realpath(cursor) === `/private${cursor}`;
+      const systemAlias = process.platform === "darwin" && (cursor === "/tmp" || cursor === "/var") && await realpath2(cursor) === `/private${cursor}`;
       if (!systemAlias) throw new MediaToolError("MEDIA_SYMLINK", "Symlink media paths are not followed. Use the original local path.");
     }
-    cursor = dirname(cursor);
+    cursor = dirname3(cursor);
   }
   return path;
 }
 async function assertLocalMediaFile(value) {
   const path = await assertNoMediaSymlinks(value);
-  const info = await lstat(path);
+  const info = await lstat2(path);
   if (!info.isFile()) throw new MediaToolError("MEDIA_NOT_REGULAR", "The media input must be a regular local file.");
   if (!SUPPORTED_MEDIA_EXTENSIONS.has(extname(path).toLowerCase())) throw new MediaToolError("MEDIA_FORMAT_UNSUPPORTED", "This file extension is not supported for local media inspection.");
   return path;
@@ -57308,7 +57636,7 @@ var rate2 = (value) => {
 var sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
 async function probeLocalMedia(value) {
   const path = await assertLocalMediaFile(value);
-  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  const handle = await open3(path, constants3.O_RDONLY | (constants3.O_NOFOLLOW ?? 0));
   try {
     const before = await handle.stat();
     if (!before.isFile()) throw new MediaToolError("MEDIA_NOT_REGULAR", "The media input must be a regular local file.");
@@ -57318,7 +57646,7 @@ async function probeLocalMedia(value) {
     for await (const chunk of handle.createReadStream({ autoClose: false })) hash6.update(chunk);
     const after = await handle.stat();
     await assertNoMediaSymlinks(path);
-    const current2 = await lstat(path);
+    const current2 = await lstat2(path);
     if (!sameFile(before, after) || !sameFile(after, current2)) throw new MediaToolError("MEDIA_FILE_CHANGED", "The media file changed while it was being inspected. Retry with a stable source.");
     let raw;
     try {
@@ -57346,121 +57674,6 @@ async function probeLocalMedia(value) {
   }
 }
 
-// packages/cli/src/io.ts
-import { constants as constants2 } from "node:fs";
-import { lstat as lstat2, mkdir, open as open2, readdir, realpath as realpath2, rename, unlink, link } from "node:fs/promises";
-import { dirname as dirname2, join, relative, resolve as resolve2, sep } from "node:path";
-import { randomUUID } from "node:crypto";
-async function ensureRoot(directory, create = false) {
-  const root = resolve2(directory);
-  if (create) await mkdir(root, { recursive: true });
-  const info = await lstat2(root);
-  if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("Workspace root must be a real directory, not a symlink");
-  return realpath2(root);
-}
-async function checkedPath(root, path, document2 = true) {
-  if (document2) safeDocumentPath(path);
-  const target = resolve2(root, path);
-  const rel = relative(root, target);
-  if (!rel || rel.startsWith(`..${sep}`) || rel === ".." || resolve2(path) === path) throw new Error("Path escapes workspace");
-  let cursor = root;
-  for (const segment of rel.split(sep)) {
-    cursor = join(cursor, segment);
-    try {
-      const info = await lstat2(cursor);
-      if (info.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${path}`);
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-  }
-  return target;
-}
-async function readText(root, path, document2 = true) {
-  const target = await checkedPath(root, path, document2);
-  const handle = await open2(target, constants2.O_RDONLY | constants2.O_NOFOLLOW);
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) throw new Error(`Not a regular file: ${path}`);
-    if (document2 && info.size > MAX_DOCUMENT_BYTES) throw new Error(`Document exceeds 128 KiB: ${path}`);
-    return new TextDecoder("utf-8", { fatal: true }).decode(await handle.readFile());
-  } finally {
-    await handle.close();
-  }
-}
-async function atomicWrite(root, path, content, options = {}) {
-  const target = await checkedPath(root, path, options.document ?? true);
-  await mkdir(dirname2(target), { recursive: true });
-  await checkedPath(root, path, options.document ?? true);
-  const temporary = join(dirname2(target), `.eh-${randomUUID()}.tmp`);
-  const handle = await open2(temporary, "wx", options.mode ?? 420);
-  try {
-    await handle.writeFile(content, "utf8");
-    await handle.close();
-    await checkedPath(root, path, options.document ?? true);
-    if (options.overwrite === false) {
-      await link(temporary, target);
-      await unlink(temporary);
-    } else await rename(temporary, target);
-  } catch (error) {
-    await handle.close().catch(() => {
-    });
-    await unlink(temporary).catch(() => {
-    });
-    throw error;
-  }
-}
-async function readWorkspace(root) {
-  const files = /* @__PURE__ */ Object.create(null);
-  async function walk(path) {
-    const directory = await checkedPath(root, path, false);
-    let entries;
-    try {
-      entries = await readdir(directory, { withFileTypes: true });
-    } catch (error) {
-      if (error.code === "ENOENT") return;
-      throw error;
-    }
-    for (const entry of entries) {
-      const child = `${path}/${entry.name}`;
-      if (entry.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${child}`);
-      if (entry.name.startsWith(".")) continue;
-      if (entry.isDirectory()) {
-        if (path.startsWith("videos/") && ["assets", "renders"].includes(entry.name)) continue;
-        await walk(child);
-      } else if (entry.isFile() && /\.(json|md)$/.test(entry.name)) {
-        safeDocumentPath(child);
-        files[child] = await readText(root, child);
-      }
-    }
-  }
-  await walk(".editorharness");
-  await walk(".editorbrain");
-  await walk("videos");
-  return canonicalFiles(files);
-}
-async function readProjectWorkspace(root, projectId) {
-  assertIdentifier(projectId);
-  const projectPath = `videos/${projectId}/project.json`;
-  const projectContent = await readText(root, projectPath);
-  const checked = validateDocument(projectPath, projectContent);
-  if (!checked.valid) throw new ValidationError(checked.issues);
-  const project = JSON.parse(projectContent);
-  const files = { [projectPath]: projectContent };
-  for (const path of /* @__PURE__ */ new Set([...projectSources(project), ...optionalProjectSources(project)])) {
-    if (path === projectPath) continue;
-    const aliases2 = path.startsWith(".editorbrain/") ? [path, path.replace(/^\.editorbrain\//, ".editorharness/")] : [path];
-    for (const alias of aliases2) {
-      try {
-        files[alias] = await readText(root, alias);
-      } catch (error) {
-        if (error.code !== "ENOENT") throw error;
-      }
-    }
-  }
-  if (await readText(root, projectPath) !== projectContent) throw new Error("The selected project changed while reading its context. Retry before editing.");
-  return canonicalFiles(files);
-}
-
 // packages/cli/src/production-context.ts
 async function prepareProductionContext(root, projectId, client) {
   const resolved = await resolveProject(await readProjectWorkspace(root, projectId), projectId);
@@ -57561,123 +57774,6 @@ async function remoteSfx(client, subcommand, params) {
 // packages/cli/src/media-preview.ts
 import { chmod, link as link2, mkdtemp, rm } from "node:fs/promises";
 import { dirname as dirname4, join as join3 } from "node:path";
-
-// packages/cli/src/production-output.ts
-import { constants as constants3 } from "node:fs";
-import { mkdir as mkdir2, open as open3 } from "node:fs/promises";
-import { dirname as dirname3 } from "node:path";
-async function productionOutputPath(root, relativePath) {
-  if (!relativePath.startsWith(".editorbrain-local/") || relativePath.split(/[\\/]/).some((p) => !p || p === ".." || p === ".") || /[\\\x00-\x1f\x7f]/.test(relativePath)) {
-    throw new CliError("LOCAL_OUTPUT_REQUIRED", "Production output must be inside .editorbrain-local/.", "Use --out .editorbrain-local/<project>/inventory.json, or omit --out for JSON stdout. These reports are not synced.");
-  }
-  return checkedPath(root, relativePath, false);
-}
-async function prepareSampleDirectory(root, path) {
-  const target = await productionOutputPath(root, path);
-  await mkdir2(dirname3(target), { recursive: true });
-  await productionOutputPath(root, path);
-  return target;
-}
-async function readProductionJson(root, path) {
-  const target = await checkedPath(root, path, false);
-  const handle = await open3(target, constants3.O_RDONLY | constants3.O_NOFOLLOW | constants3.O_NONBLOCK);
-  try {
-    const stat = await handle.stat();
-    if (!stat.isFile() || stat.size > 16 * 1024 * 1024) throw new CliError("INVALID_REPORT", "Expected a regular JSON file of at most 16 MiB.", "Select a local inventory, plan or check profile.");
-    return JSON.parse(await handle.readFile("utf8"));
-  } finally {
-    await handle.close();
-  }
-}
-async function saveProductionReport(root, path, report) {
-  const target = await productionOutputPath(root, path);
-  if (!path.endsWith(".json")) throw new CliError("INVALID_ARGUMENT", "Report output needs a .json extension.", "Use a new path under .editorbrain-local/.");
-  await atomicWrite(root, path, stableJson(report), { document: false, overwrite: false, mode: 384 });
-  return target;
-}
-function summarizeProductionReport(value) {
-  const r = value;
-  const base = { schemaVersion: r.schemaVersion, kind: r.kind, summary: true, mediaUploaded: false, quality: "not_assessed" };
-  if (r.kind === "editorbrain.media-inventory") return {
-    ...base,
-    complete: r.complete,
-    contentReviewed: false,
-    counts: { assets: r.assets.length, failures: r.failures.length, skipped: r.skipped.length },
-    assets: r.assets.slice(0, 8),
-    failures: r.failures.slice(0, 5),
-    omitted: { assets: Math.max(0, r.assets.length - 8), failures: Math.max(0, r.failures.length - 5), skipped: r.skipped.length },
-    next: "Inspect selected source content. Use media sample for specific frames. Read the saved report or rerun with --details for omitted metadata; no content was reviewed automatically."
-  };
-  if (r.kind === "editorbrain.media-samples") return { ...base, sourceSha256: r.source.sha256, frames: r.frames, contentReviewed: false, next: "View these frames to inspect composition. They do not prove motion or sound." };
-  if (r.kind === "editorbrain.production-plan-check") return {
-    ...base,
-    valid: r.valid,
-    inventoryComplete: r.inventoryComplete,
-    observations: r.observations,
-    sourceFilesReverified: false,
-    counts: { sources: r.coverage.length, findings: r.findings.length, repeatedPairs: r.repeatedPairs ?? 0 },
-    findings: [...r.findings].sort((a, b) => ({ error: 0, warning: 1, info: 2 })[a.severity] - { error: 0, warning: 1, info: 2 }[b.severity]).slice(0, 8),
-    omittedFindings: Math.max(0, r.findings.length - 8),
-    next: "Review source reuse and inspection gaps in the saved report. Observations are agent-declared, not independently certified."
-  };
-  if (r.kind === "editorbrain.render-check") return {
-    ...base,
-    complete: r.complete,
-    technicalStatus: r.technicalStatus,
-    file: r.file,
-    checks: r.checks,
-    findings: r.findings.slice(0, 8),
-    findingsSummary: r.findingsSummary,
-    omittedFindings: Math.max(0, r.findings.length - 8),
-    next: "Reconcile technical candidates with the brief; inspect the actual video/audio. Technical checks do not assess narrative, aesthetics or SFX audibility."
-  };
-  if (r.kind === "editorbrain.media-source-search") return {
-    ...base,
-    complete: r.complete,
-    results: r.results.slice(0, 5).map((item) => ({ provider: item.provider, id: item.id.slice(0, 180), title: item.title.slice(0, 180), sourceUrl: item.sourceUrl.length <= 1500 ? item.sourceUrl : null, author: item.author?.slice(0, 120) ?? null, license: { id: item.license.id, reason: item.license.reason, url: item.license.url && item.license.url.length <= 500 ? item.license.url : null }, contentReviewed: false, rightsVerified: false })),
-    metadataAbbreviated: true,
-    failures: r.failures.slice(0, 5),
-    counts: r.counts,
-    omitted: { results: Math.max(0, r.results.length - 5), failures: Math.max(0, r.failures.length - 5) },
-    searchExhaustive: false,
-    rightsVerified: false,
-    next: "Inspect relevant source pages and media. These archives supplement web image/video search; empty results do not prove absence on the internet."
-  };
-  if (r.kind === "editorbrain.evidence-check") return {
-    ...base,
-    valid: r.valid,
-    inventoryComplete: r.inventoryComplete,
-    observations: r.observations,
-    sourceFilesReverified: false,
-    factualTruth: "not_assessed",
-    reuseRights: "not_assessed",
-    findings: r.findings.slice(0, 8),
-    omitted: { findings: Math.max(0, r.findings.length - 8) }
-  };
-  if (r.kind === "editorbrain.audio-check") return {
-    ...base,
-    complete: r.complete,
-    technicalStatus: r.technicalStatus,
-    file: r.file,
-    fileStable: r.fileStable,
-    coverage: r.coverage,
-    measurements: r.measurements.slice(0, 8),
-    errorCode: r.errorCode,
-    creativeQuality: r.creativeQuality,
-    omitted: { measurements: Math.max(0, r.measurements.length - 8) },
-    next: "Measurements describe this exact file. Listen for intelligibility, pronunciation, SFX and sync when the modality is available."
-  };
-  if (r.kind === "editorbrain.motion-review") return {
-    ...base,
-    samples: r.samples ? { frameCount: r.samples.frameCount, fps: r.samples.fps, radiusFrames: r.samples.radiusFrames, samples: r.samples.samples.slice(0, 12), omittedSamples: Math.max(0, r.samples.samples.length - 12) } : null,
-    geometryReviews: r.geometryReviews.slice(0, 3).map((g) => ({ scope: g.scope, status: g.status, candidates: g.candidates.slice(0, 8), omittedCandidates: Math.max(0, g.candidates.length - 8), checks: g.checks })),
-    omittedGeometryReviews: Math.max(0, r.geometryReviews.length - 3),
-    next: "This plans samples and checks declared boxes only. Render/view those frames; read saved details for omitted candidates and intentional overlaps."
-  };
-  throw new CliError("INVALID_REPORT", "Unknown production report kind.", "Use media inventory/sample or production check/plan-check.");
-}
-
-// packages/cli/src/media-preview.ts
 async function prepareMediaPreview(root, file, out, quality = 720, audioStream) {
   if (![720, 1080].includes(quality) || !out.endsWith(".mp4")) throw new CliError("INVALID_ARGUMENT", "Use --quality 720 or 1080 and a new .mp4 output.", "Previews belong under .editorbrain-local/.");
   const source = await probeLocalMedia(await assertLocalMediaFile(file));
@@ -57736,6 +57832,16 @@ async function prepareStudioAudio(root, file, out, streamIndex) {
 // packages/cli/src/client.ts
 import { setTimeout as delay } from "node:timers/promises";
 var searchErrors = {
+  batch_changed: { status: 409, code: "BATCH_CHANGED", hint: "Read batches get before retrying; preserve new changes." },
+  batch_claim_blocked: { status: 409, code: "BATCH_CLAIM_BLOCKED", hint: "Read the batch. Wait for an available slot or reconcile an expired turn; do not start work without a claim." },
+  batch_budget_exceeded: { status: 409, code: "BATCH_BUDGET_EXCEEDED", hint: "Stop generation. The batch or video budget was reached. Do not increase the budget yourself." },
+  batch_not_running: { status: 409, code: "BATCH_NOT_RUNNING", hint: "The batch is paused/cancelled or the turn expired. Read the batch before continuing." },
+  batch_retry_blocked: { status: 409, code: "BATCH_RETRY_BLOCKED", hint: "Inspect existing jobs and outputs before retrying. Do not duplicate a paid request." },
+  batch_project_busy: { status: 409, code: "BATCH_PROJECT_BUSY", hint: "Wait for existing Studio jobs before grouping these projects." },
+  batch_project_taken: { status: 409, code: "BATCH_PROJECT_TAKEN", hint: "Use the project existing batch or create a separate video project." },
+  studio_context_or_lease_changed: { status: 409, code: "STUDIO_CONTEXT_OR_LEASE_CHANGED", hint: "Refresh the workflow and batch lease before generating." },
+  progress_changed: { status: 409, code: "PROGRESS_CHANGED", hint: "Read projects progress --project ID again. Preserve the latest state; never force an old progress version." },
+  final_not_approved: { status: 409, code: "FINAL_NOT_APPROVED", hint: "Review and approve the latest complete video, resolve pending changes, then record explicit final-delivery acceptance." },
   invalid_search_brief: { status: 400, code: "INVALID_SEARCH_BRIEF", hint: "Check references/search-brief.md and the service contract. Older services may reject eventQueries objects with channels. Do not silently remove constraints or retry a changed query as if filtering succeeded." },
   source_inspection_required: { status: 422, code: "SOURCE_INSPECTION_REQUIRED", hint: "Inspect the supplied source and declare only modalities actually reviewed. A script requires script inspection; video requires frames, motion or audio." },
   search_index_not_ready: { status: 503, code: "SEARCH_INDEX_NOT_READY", hint: "No current authorized evidence is indexed. Report the gap; literal library lookup is available but is not semantic retrieval or proof of fit." }
@@ -57835,7 +57941,7 @@ var Client = class {
       const retryAfterMs = retryDelay(response.headers.get("Retry-After"), this.runtime.now());
       if (!response.ok) {
         let errorBody;
-        if (path === "/v1/search/brief" && [400, 422, 503].includes(response.status)) {
+        if ((path.startsWith("/v1/batches") || path === "/v1/studio/jobs") && response.status === 409 || path === "/v1/search/brief" && [400, 422, 503].includes(response.status) || /^\/v1\/projects\/[^/]+\/progress$/.test(path) && response.status === 409) {
           try {
             const diagnostic = searchDiagnostic(response.status, await boundedJson(response, 16 * 1024));
             errorBody = diagnostic ? { error: { code: diagnostic.serviceCode } } : void 0;
@@ -58017,7 +58123,7 @@ ${conflicts.join("\n")}`, "Run pull --dry-run and reconcile the reported paths."
 
 // packages/cli/src/studio.ts
 async function studioCommand(client, root, command, argument, flags) {
-  const allowed = /* @__PURE__ */ new Set(["dir", "url", ...command === "quote" ? ["file"] : command === "run" ? ["max-credits", "user-confirmed"] : []]);
+  const allowed = /* @__PURE__ */ new Set(["dir", "url", ...command === "quote" ? ["file"] : command === "run" ? ["max-credits", "user-confirmed", "batch-lease-token"] : []]);
   for (const flag of Object.keys(flags)) if (!allowed.has(flag)) throw new CliError("INVALID_ARGUMENT", `--${flag} is not supported for studio ${command}.`, "Read editorbrain help.");
   try {
     if (command === "catalog" || command === "jobs") {
@@ -58035,7 +58141,7 @@ async function studioCommand(client, root, command, argument, flags) {
     if (command === "run") {
       const maxCredits = Number(flags["max-credits"]);
       if (flags["user-confirmed"] !== true || !Number.isFinite(maxCredits) || maxCredits <= 0 || maxCredits > 1e4) throw new CliError("SPENDING_APPROVAL_REQUIRED", "Supply --user-confirmed and --max-credits only after the user authorized this quote or budget.", "Preferences and direct editing mode do not authorize spending.");
-      return await client.request("/v1/studio/jobs", { method: "POST", body: { quoteId: argument, maxCredits, userConfirmed: true } });
+      return await client.request("/v1/studio/jobs", { method: "POST", body: { quoteId: argument, maxCredits, userConfirmed: true, ...flags["batch-lease-token"] ? { batchLeaseToken: flags["batch-lease-token"] } : {} } });
     }
     throw new CliError("INVALID_ARGUMENT", "Use studio catalog, quote, run, get or jobs.", "Read editorbrain help.");
   } catch (error) {
@@ -58381,6 +58487,41 @@ var VERIFIED_GUIDANCE_RELEASES = [
       "editorbrain/references/style-creator.md": "1b1bc289a5bc308cbbf7f4d699de2933b8934733a2b69b3e98fb1b7420d986f2",
       "editorbrain/references/workspace-files.md": "18462e7b66ba6204770c654e4a2f7e505c343319671a0447aa55c59f0b9096ec"
     }
+  },
+  {
+    "version": "0.32.0",
+    "archiveSha256": "30c6c6d97da7de16bb620c0975c2d3f2a4b7a6ea4a56f2eb3c5b0f5f53914f45",
+    "files": {
+      "editorbrain-formats/SKILL.md": "b8b03266a9b7cde8337846144d3032b63b6d9cfbfc4530ae1b06f3dd43074ff2",
+      "editorbrain-formats/references/numbered-tutorial.md": "95754ae7dbfaa678e11ddf1a2b84710dba83a16e2fa4055051bd4f5f4f868a5f",
+      "editorbrain-motion/SKILL.md": "86617d39341d7325d613b877838258f40f05b4286301dacf8e1ec85ccd502aab",
+      "editorbrain-motion/references/authored-scenes.md": "11109dcd35ab7138fdc18e54605885bb26d9e948f12221e18dea4038987dede2",
+      "editorbrain-motion/references/code-motion.md": "50382a797adc1e1596086e2408e81ee75ceb6730ca409be9c884646db643a7cd",
+      "editorbrain-motion/references/component-library.md": "e4593622ebe371bba1b1c62f698c6709c36a8d01ddce4a07d40534fca44b797e",
+      "editorbrain-motion/references/generated-motion.md": "a8d214b53c15f742658abd84f03b768fa2821f8cde94f50aab82a3759a30b36b",
+      "editorbrain-motion/references/motion-craft.md": "adba1b0cbb3c6327a7665857b0a6d144f97dc843464ccf154d3f76ee3ada905d",
+      "editorbrain/AGENTS.md": "2361aaa3202d3f4ea9e941684fbda1a84d9711389cca89f7f6cd3ae03b7ab6d0",
+      "editorbrain/SKILL.md": "b15eb4e2438c0a3e6ec5c3c3170f11c973676d5c6a850cf5d2e9cb3bc7c44e42",
+      "editorbrain/references/audio-production.md": "038504d738db98939aeed14407b15561e4f82c650aace7eb545e77cdffd8dadb",
+      "editorbrain/references/cli-mcp.md": "9febfcac6c1dc763b79ab26ffb07e53bce703cbe4c2332ddcd250e10f2fa75dd",
+      "editorbrain/references/editorial-evidence.md": "caf72365b3e7492a62d96b39cd17031fa7c961671ce32bc4649420d8a353a026",
+      "editorbrain/references/first-edit.md": "d71271ab32c6432cce01316917b4504f15411ea59511566a1f6169ac6d09723c",
+      "editorbrain/references/integrations.md": "a3500dd79c71ab3ee80a865bb5bf8c94287efb933e07d577738891e276a819a0",
+      "editorbrain/references/local-production.md": "2d170bb217854eda7581f64d8342fffe3b56234bbe56b2715fa93eb3210e6354",
+      "editorbrain/references/media-preferences.md": "d1b92b181fbc226c8d3fda762726dd413944175768651fbfb8200eae44fb2ec8",
+      "editorbrain/references/memory-and-review.md": "2a89d6fc4737b750a380c69630d6fd4f4132aed27656b92e8f0c5748887b70ae",
+      "editorbrain/references/motion-review.md": "0fb09a2d61ecd13114ced5cca5daa4580a922cf7d7b3f8698077ceb0e96da6f0",
+      "editorbrain/references/onboarding.md": "875d1b9049c4663780f993c2843528c531a51d6b51380b08ed77d82f618185fb",
+      "editorbrain/references/production-and-review.md": "50f10a98a4f3709a5a585f58e4154f33d6d883b218cd25f3abd72eccc43b15a7",
+      "editorbrain/references/production-continuity.md": "c4b346c9634f3d1ef63b24a97d178e0253c2e45d53f6934076a5417e66e34d9b",
+      "editorbrain/references/real-media.md": "106bee5a34641d53f021ead5d41630d473c2bfc98e4f7ee5500dae837e2e45bb",
+      "editorbrain/references/search-brief.md": "ea2a9c2d5a5cf685c1e5918366901ef2589c4d79aaa78a0dd31e97d6fed42b7b",
+      "editorbrain/references/sfx-library.md": "fa0b02c8765988257e46e16298ecca9cdb0e338a863915e29f831162e237eac4",
+      "editorbrain/references/storage-and-previews.md": "8a3057f1c1a2a1e1cd32028059dc897a8461da38c36e812fbd24943d3740b4d5",
+      "editorbrain/references/studio.md": "7a84e43bd72f8590d1a91c7d1bc5f6b60678c1c8eba6523b51b99243e22a1322",
+      "editorbrain/references/style-creator.md": "1b1bc289a5bc308cbbf7f4d699de2933b8934733a2b69b3e98fb1b7420d986f2",
+      "editorbrain/references/workspace-files.md": "c16fe08b209c65baf8f57054f7cc01f514292fc073b7072298b86c0054da3e19"
+    }
   }
 ];
 function isVerifiedHistoricalGuidance(skillName, relativePath, sha2562) {
@@ -63531,7 +63672,16 @@ editorbrain register --url https://server --name workspace --invite-stdin
 editorbrain status
 editorbrain pull [--project id | --all] [--dir folder] [--dry-run]
 editorbrain push [--dir folder] [--dry-run]
+editorbrain batches list [--after UUID]
+editorbrain batches create --file batch.json
+editorbrain batches get BATCH_ID
+editorbrain batches pause|resume|cancel BATCH_ID --expected-revision N
+editorbrain batches retry|detach BATCH_ID --project ID --expected-revision N
+editorbrain batches claim|renew|release|attention BATCH_ID --project ID --lease-token UUID
 editorbrain projects list
+editorbrain projects progress --project ID
+editorbrain projects start|queue --project ID --expected-version HASH
+editorbrain projects complete --project ID --expected-version HASH --revision UUID --user-confirmed
 editorbrain documents list [--prefix path]
 editorbrain documents get <path> [--revision N]
 editorbrain documents history <path> [--before N]
@@ -63550,7 +63700,7 @@ editorbrain studio prepare --file source.mp4 --out .editorbrain-local/studio/aud
 editorbrain studio catalog
 editorbrain billing status
 editorbrain studio quote --file request.json [--dir folder]
-editorbrain studio run QUOTE_ID --max-credits N --user-confirmed
+editorbrain studio run QUOTE_ID --max-credits N --user-confirmed [--batch-lease-token UUID]
 editorbrain studio get JOB_ID
 editorbrain studio jobs
 editorbrain integrations catalog
@@ -63636,6 +63786,9 @@ function parseArgs(argv) {
   known.add("preview-kind");
   known.add("preset");
   known.add("context-version");
+  known.add("expected-version");
+  known.add("lease-token");
+  known.add("batch-lease-token");
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -64221,6 +64374,14 @@ async function main() {
     }
     throw new Error("Use keys list, keys create --label name, or keys revoke <key-id>");
   }
+  if (command === "batches") {
+    output(await batchCommand(new Client(await config(args)), await ensureRoot(str(args, "dir") ?? process.cwd()), subcommand, argument, args.flags));
+    return;
+  }
+  if (command === "projects" && ["progress", "start", "queue", "complete"].includes(subcommand)) {
+    output(await projectProgressCommand(new Client(await config(args)), subcommand, args.flags));
+    return;
+  }
   if (command === "projects" && subcommand === "list") {
     output({ projects: await listProjects(new Client(await config(args))) });
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editorbrain",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "EditorBrain editorial knowledge, portable workspaces and skills for AI video agents",
   "type": "module",
   "license": "UNLICENSED",

package/skill/editorbrain/SKILL.md

@@ -24,12 +24,14 @@ For factual subjects or real demonstrations, inspect authentic footage/images fr
 5. Ground each new edit or materially changed direction in the **edited-video reference library**, including when a favorite style is selected. Search with `search_from_brief` (CLI `editorbrain search brief --file <brief.json>`) and the project ID after inspecting the material. Read [search brief](references/search-brief.md) for the schema and [editorial evidence](references/editorial-evidence.md) for selection/adaptation. Search communicative needs, not a guessed template. A scoped revision may reuse still-valid inspected evidence and approval. The optional `search_for_edit` server-analysis path is never an automatic fallback.
 6. Survey candidates across the video's needs, then inspect selected documents and actual frames/intervals, plus audio when sound matters. Build a coherent scene-level palette of techniques: opening, imagery, type, explanation and transitions can come from different references. A shortlist is not a single template for the whole video. Use preferences to retain, adapt or reject mechanisms; save evidence, limitations and beat-level adaptations in `direction.md`. A motion-catalog lookup does not complete this step. If evidence is inaccessible or unsuitable, disclose the gap. For factual beats, compare allowed user footage and authentic web media with authored explanation. The engine does not dictate the imagery or entire layout.
 7. Follow the effective review mode: `direct` → implement and review; `directions` → propose suitable alternatives with labelled reference evidence; `sample` → show a frame/short clip made with customer material before the full edit. Respect existing approval. Check the preference version before proposals, costly generation and full rendering; a web update cannot interrupt an active tool.
-8. Carry the same `editorialSnapshot` into implementation and any specialist handoff. For a sample or localized correction, use [production continuity](references/production-continuity.md): register the exact version, retain unaffected work and retrieve pending feedback. Before delivery, use `production verify --project ID --file <render>` when available, inspect its real samples and review the final motion/audio. An editing request needs the edit, not only a plan. Use [production and review](references/production-and-review.md) to compare editorial quality with the chosen references and any applicable user-approved sample; a technical pass alone cannot satisfy that comparison. Report unverified dimensions separately from technical results.
+8. When available, read `check_workflow.projectProgress` on resuming (or `get_project_progress` / `editorbrain projects progress --project ID`). Register actual work with `update_project_progress` (`action:start`, current `expectedVersion`) / `projects start`. This keeps the web board current; it is not a heartbeat. See [production continuity](references/production-continuity.md) for final delivery and conflict handling. Carry the same `editorialSnapshot` into implementation and any specialist handoff. For a sample or localized correction, use [production continuity](references/production-continuity.md): register the exact version, retain unaffected work and retrieve pending feedback. Before delivery, use `production verify --project ID --file <render>` when available, inspect its real samples and review the final motion/audio. An editing request needs the edit, not only a plan. Use [production and review](references/production-and-review.md) to compare editorial quality with the chosen references and any applicable user-approved sample; a technical pass alone cannot satisfy that comparison. Report unverified dimensions separately from technical results.
 
 ## Specialized work, loaded when needed
 
 Use the decision ownership in [the shared contract](AGENTS.md#decision-ownership): montage, media, motion, sound and review share one direction. For animated scenes, read [editorbrain-motion](../editorbrain-motion/SKILL.md) with the active project and resolved context. Ordinary cuts, static graphics or sync/install tasks need no motion skill. When the edit follows a recognizable format (for example a numbered tutorial, or a reference whose structure the user wants replicated), read [editorbrain-formats](../editorbrain-formats/SKILL.md) for its structure and sync rules; identity still comes from the resolved brand and style. User memory belongs in scoped brand/style/project files; shared guides describe methods and examples supply evidence.
 
+For multiple final videos, read the batch section of [production continuity](references/production-continuity.md): confirm clip grouping, isolate projects, acquire turns and respect batch budgets. `check_workflow.batch` carries coordination; it does not replace project preferences.
+
 For built-in transcription, image generation or narration, read [EditorBrain Studio](references/studio.md) only when needed. Discover availability first; quote and obtain an authorized budget before spending. Local MP4 preparation, durable job recovery and private result retrieval are covered there.
 
 For cloud uploads or storage cleanup, read [storage and previews](references/storage-and-previews.md) only then; keep originals and masters distinct from lightweight review copies.

package/skill/editorbrain/references/production-continuity.md

@@ -100,3 +100,96 @@ allowed lists. `MEDIA_USE_REVIEW` stays pending even after a technical pass: com
 the plan and actual visible resources, including useful omissions, using
 [production review](production-and-review.md). The tool does not inspect or count
 imagery automatically, generate assets or authorize any provider.
+
+
+## Keep the project board current (discover availability)
+
+Web, CLI and MCP use the same server state; do not store an independent status in
+`project.json`. First discover these tools/commands with the installed CLI help or
+MCP tools list. Older clients/services remain usable; report unavailable progress
+tracking without claiming that the board was updated.
+
+- `get_project_progress` / `editorbrain projects progress --project ID` returns
+  `stage`, `version`, latest review and pending count. Read on resume and before writes.
+- `update_project_progress` with `action:start`, `expectedVersion` / `projects start
+  --project ID --expected-version HASH`: mark actual editing, including a correction.
+  It does not run a render, wake an agent or authorize paid tools.
+- New registered samples automatically appear **Para revisar**. Requested changes
+  return to **En edición**. Sample approval alone never finishes a project.
+- When the user accepts the exact complete video as the final delivery, use existing
+  production approval for that revision, read progress again, then `projects complete
+  --project ID --revision UUID --expected-version HASH --user-confirmed` or MCP
+  `update_project_progress` with `action:complete`, `revisionId`, `expectedVersion`,
+  `userConfirmed:true`. Do not request the same approval twice; record an existing
+  explicit final acceptance. A frame, preview, successful render or technical pass
+  is insufficient. Only the latest current, available, approved video with zero
+  pending project feedback can finish. Direct editing mode still skips proposal
+  gates; final acceptance is not inferred from that preference.
+- `action:queue` / `projects queue` returns work to **Por editar** when the user
+  defers it and no corrections are pending. `start` can reopen a completed video.
+- On `progress_changed`, refresh and reconcile; never automatically replay stale
+  intent. If a write response is lost, read progress before retrying. No push/pull
+  is needed for this operational state. No live-agent presence is implied.
+
+Archived samples and approvals remain historical evidence. Context changes,
+new samples, removed media and requested corrections can invalidate completion.
+Report unavailable/unknown state honestly; do not assign a stage from filenames.
+
+## Multiple videos: one batch, isolated projects
+
+Load this section only for multiple deliverables. Discover `batches` / editing-batch
+MCP tools first. One project means one final video, not necessarily one source file.
+Inspect the supplied inventory; if grouping is ambiguous, show a short visual list
+of proposed titles and assigned clips for confirmation. For videos from scratch,
+create one project/brief per idea through the existing project workflow. Never
+silently turn ten clips of one story into ten videos. Keep originals intact.
+
+Create the projects normally, then `batches create --file batch.json` (MCP
+`create_editing_batch`). Retain a UUID batchId for retry-safe creation:
+
+```json
+{"batchId":"UUID","name":"This week","styleMode":"series","maxConcurrency":1,"maxCredits":0,"items":[{"projectId":"first-video","maxCredits":0}],"userConfirmed":true}
+```
+
+Confirm the grouping and ceilings with the user; start paused. Zero forbids paid
+Studio generation, not local editing. `series` means a shared direction, not copied
+scenes. `individual` chooses references for each story. Neither overwrites brand,
+language, exclusions, review preference, project exceptions or integration access.
+Reuse relevant shared context but search edited-video references for each brief;
+carry the evidence into each project. Never copy a previous video's factual assets
+or assume its approval transfers. Keep directories, renders and feedback separate.
+
+Read `batches get ID` / `get_editing_batch`. Resume with `batches resume ID
+--expected-revision N` / `update_editing_batch`. This enables scheduling; it does
+not start a renderer or authorize spending. Work serially by default; use at most
+the configured slots if the host supports independent workers and enough disk,
+RAM and render capacity. Do not load every project's full context into one task.
+
+Before work, claim ONE project using `batches claim ID --project PROJECT
+--lease-token UUID` / `editing_batch_lease`. Keep that UUID for retries; another
+session cannot acquire the same item. Read `check_workflow.batch` and the project's
+snapshot; mark actual editing through project progress. Renew within 20 minutes
+and recheck before each expensive step. Stop scheduling on pause, cancellation,
+expiration or conflict. Local processes already running cannot be remotely killed
+by the queue. On host shutdown work waits for another authorized session.
+
+Studio still needs exact quotes and authorized spending. Pass `--batch-lease-token`
+to `studio run` (MCP `studio_run.batchLeaseToken`). The server enforces the shared
+lot ceiling, per-video ceiling and credit balance atomically. External services
+have separate budgets: these limits cannot control a user's own API/MCP charges.
+Read existing job IDs after unknown outcomes; never replace them with new quotes.
+
+After registering a fresh project sample, `batches release` / lease action release
+frees the turn for the next video. This does NOT approve the sample or finish the
+video. On failure use `attention`, preserve outputs and continue unaffected items.
+Expired turns require inspection of local outputs and paid jobs before explicit
+`batches retry ID --project PROJECT --expected-revision N`. Retry resets only that
+queue item; it does not regenerate, delete files or waive existing approvals.
+A requested correction similarly requeues its project after pending jobs settle.
+Final acceptance remains per exact video; batch completion is derived from those
+individual acceptances, never inferred from all renders finishing.
+
+Pause stops new turns/paid jobs. Cancel also prevents future resumption of that
+batch; in-flight jobs may still finish and be charged. To work separately afterward,
+`batches detach ID --project PROJECT --expected-revision N` removes active membership
+only after the cancelled project's jobs and turn have ended. History/costs remain.

package/skill/editorbrain-formats/SKILL.md

@@ -3,9 +3,9 @@ name: editorbrain-formats
 description: >-
   Replicate a proven video format's structure in an EditorBrain edit, such as a
   numbered tutorial or demonstration (hook promise, numbered steps, a visible result
-  for each step, presenter returns, CTA). Use when the user names a format or
-  editorial family, asks to follow a reference's structure, or the material is a
-  step-by-step list. Formats define structure, sync and pacing only; identity comes
+  for each step, presenter returns, CTA) or an aspirational list that turns personal
+  and ends in a demonstration. Use when the user names a format or editorial family,
+  asks to follow a reference's structure, or the material is a list of steps or items. Formats define structure, sync and pacing only; identity comes
   from the user's resolved brand and style.
 ---
 
@@ -42,6 +42,7 @@ The number of steps, durations, demo mechanisms and the headline's wording come
 | Format | Use when | Guide |
 |---|---|---|
 | Numbered tutorial / demonstration | The voice teaches N discrete steps, tips or instructions and each one can be shown working | [numbered tutorial](references/numbered-tutorial.md) |
+| Aspirational list → personal experience → demonstration | The voice lists N people, tools or habits, each illustrated by strong images, then turns personal and shows how to act on it with real material | [aspirational list](references/aspirational-list-demo.md) |
 
 Read only the guide you will use. For animated beats, also use the sibling [motion skill](../editorbrain-motion/SKILL.md); for authentic results, follow [real media](../editorbrain/references/real-media.md).
 

package/skill/editorbrain-formats/references/aspirational-list-demo.md

@@ -0,0 +1,140 @@
+# Format: aspirational list → personal experience → demonstration
+
+A narrator promises a list ("N things, people or tools that…"). Each item opens its own short block of images carrying one lesson. The list then turns personal, toward the narrator's own practice or the viewer's future self, and lands on a concrete demonstration of how to act on it. The narrator stays present as a small element over full-frame imagery instead of filling the frame.
+
+Evidence status: one implemented, user-approved pilot (talking head, a list of five practices, Spanish, vertical, about 130 s). Its reference was a library profile of an English aspirational list of about 85 s ending in a product demo. Transfer to other niches and to voice-over-only material is untested; record the first adaptation's review.
+
+## Authority and adaptation
+
+Reuse the coordinator's resolved context. This guide offers reference grammar, not a mandatory layout or an override of presenter, media, motion or accessibility preferences. In direct mode, make compatible decisions and record them; ask for a sample approval only when the resolved review mode or an unresolved user requirement calls for one.
+
+Match visual changes to meaning; do not cut the audio to force a picture change onto a timestamp. ASR word starts are candidates to verify against playback. Short phrases may need a shared image and longer explanations may need several states.
+
+## Fit
+
+Use when:
+
+- the script enumerates items that can each be illustrated by strong images: people, tools, places, habits, products;
+- the voice carries continuously (voice-over or talking head), and reducing the presenter to a small element does not lose meaning;
+- the list ends in something actionable that can be shown with real material: the narrator's own practice, a configured tool, a product, a first step.
+
+Niche examples: people to study in any field, tools for a craft, habits for a goal, places to visit, investments to understand, routines of known performers.
+
+Avoid or adapt when:
+
+- the items cannot be illustrated without fabricating evidence (biographical claims, results, quotes);
+- the presenter's face is the content (reaction, emotion, testimony). Keep them full frame instead;
+- the demonstration would promote something that does not deliver what is said. Omit the demo and keep the list.
+
+## Skeleton
+
+| Beat | Function | What must be on screen |
+|---|---|---|
+| Hook | Promise the list and who it is for | A collage of the list's strongest visuals (one per cell), a short headline lockup over it and the presenter small over the collage |
+| Item k (repeat N times) | Name the item and its lesson | Item marker (k of N plus name) and one full-frame image per idea, cut on the word that introduces it |
+| Personal turn | Move from examples to the narrator or the viewer | The narrator's real material: their folders, screens, products, recordings |
+| Demonstration | Show how to act on the list | Real interface or product: page scroll, configured screens, steps; the presenter may shrink, move or leave |
+| CTA | The real ask | The presenter returns (full frame or small), optional recap of the N items, the CTA object |
+
+The personal turn can be a final block or woven into every item, with each item ending on the narrator's own tool or result. The pilot wove it into every item. Choose by the script; do not force a twist the voice does not make.
+
+## Voice and image
+
+- **One idea, one image.** Cut when the voice introduces a new idea, name or example (on that word), not on a timer.
+- **The image answers the sentence:**
+  - a named tool or product: its real mark or interface at the moment it is named;
+  - an abstract claim: an illustrative image, labelled when it could be mistaken for evidence;
+  - a number: the number on screen;
+  - a spoken series in one sentence ("apps, documents, tables, projects"): one demo that advances on each word (scroll steps, highlighted rows).
+- **Authentic material first** for anything factual: the user's own product screens, folders, repositories, dashboards and recordings. Clean captures of public pages for named products are authentic support. Hide consent overlays without accepting them, and use logged-in or private screens only when the user provided or explicitly authorized them. Retain source attribution and exclude private details unnecessary to the edit.
+- **Illustrative stills** (generated or licensed) only within the media preferences and an authorized budget. Keep one coherent look across them (lighting, grade, depth) so the list reads as one piece.
+- **Brand characters:** when generating a brand character or mascot, always attach the real asset as a reference; an off-model character undermines trust.
+- **Do not reuse an image, capture or clip** for a different idea. A deliberate callback is the exception and must read as one.
+- **The hook headline** sits directly on the collage in the reference. Keep it legible with the resolved type treatment (outline, shadow, weight) before adding a backing band; follow accessibility and the user's caption/text preferences.
+
+## Presenter treatment
+
+- **Reference grammar:** the presenter is a small floating cut-out (person matte, no background, no frame) placed over each image and relocated per shot.
+  - Placement keeps faces, headlines, controls and the demo's key interface visible.
+  - Adapt to the user's presenter/layout preferences: a split layout, full-frame return, framed picture-in-picture or no presenter may fit better. A clean matte is not a requirement for using the narrative structure.
+- **Matte:** generate it for the whole cut before designing. The pilot used on-device person segmentation on a static camera; other cameras and motions need verification. Apple Vision is an optional macOS implementation, not a client dependency. On other platforms use an available, authorized masking tool or an agreed layout without a matte. Do not install tools or upload private footage merely because this guide mentions segmentation.
+  - Check hair, hands and anything held near the body.
+  - If edges fail, compare the available alternatives within the user's tools, budget and data permissions; a simpler layout is acceptable.
+- **Size and crop:** head to mid-torso, hands included, at about a third of the frame width in the pilot.
+- **Edge treatment:** a clean crop, fades, outline or shadow is an identity choice; resolve it from preferences or ask. The pilot shipped a clean crop with a soft drop shadow.
+- **Relocation:** when the presenter moves with the cut, a small settle (scale or position) can help the eye find them again; follow the resolved motion intensity.
+
+## Rhythm
+
+- Measured pilot holds ranged from about 0.7 s to 6 s (median about 3 s) per image; item blocks lasted 15–31 s. These are evidence, not targets: holds follow the idea and the copy.
+- A longer hold can use a slow push, page scroll or a later overlay when it helps meaning. A deliberate static hold is valid for reading or calm motion preferences.
+- Cuts can land with a short push-in to give each new image energy, within the resolved motion preferences.
+- Captions stay in one stable band, never under the presenter. Short phrases suit the fast image rhythm.
+
+## Filling the frame
+
+Authored scenes (numbers, code or file windows, badges, logo grids) should use the chosen output frame deliberately, including square and landscape adaptations. Options include:
+
+- a full-bleed image behind them;
+- windows that span the width;
+- overlays sized to be read on a phone.
+
+A small centered element on an empty stage reads as a placeholder next to full-bleed images. Crop real captures to their most legible region (one card, one heading, one logo) instead of shrinking a whole page into a cell.
+
+## Identity roles to resolve
+
+Map these roles to the user's tokens and `design.md`, never to a reference's or pilot's look:
+
+| Role | Notes |
+|---|---|
+| Hook headline lockup | Dominant and accent styles, legibility treatment |
+| Item marker | Numeral and item name; persistent or entering per item |
+| Captions | The brand's caption rules |
+| Tags on real captures | Source or explanation labels |
+| Overlay cards | Numbers, badges, stamps, logo tiles |
+| Grade of illustrative stills | Consistent across the video |
+| Presenter edge treatment and shadow | |
+
+## Failure modes seen in practice
+
+- **A framed picture-in-picture** where the reference floats a cut-out: it changes the format's look. Confirm the presenter treatment before rendering.
+- **Opacity fades or backing bands** added for legibility without being asked for. Prefer type treatment, and confirm visible changes to the presenter or headline.
+- **Authored scenes as small elements on an empty dark stage.**
+- **The same image used in the hook, an item and a recap.**
+- **Collage cells with unreadable page text.**
+- **Generic stand-ins** (an unbranded laptop app) where the voice names a product: show its real mark or interface.
+- **A brand character generated without its reference image**, coming out off-model.
+- **The presenter covering the key element** of a real capture.
+- **Consent banners left visible** on page captures.
+
+## Review checklist
+
+1. **Contact sheet:** one still per shot at its key word.
+2. **Named products:** every named product, person or tool shows its real mark or interface when named.
+3. **Reuse:** list every visual; confirm none repeats except a deliberate callback.
+4. **Presenter:** check placement per shot (nothing important covered) and matte edges on hair and hands in motion.
+5. **Frame use:** authored scenes fill the frame; overlays are readable at phone size.
+6. **Captions:** the band is stable and safe areas are respected for every element.
+7. **Labelling:** report what is authentic, illustrative and generated.
+8. **Audio:** follows the user's choices; report what was not heard.
+
+## Pilot evidence (example values, not defaults)
+
+| Measure | Pilot value |
+|---|---|
+| Total | ≈ 130 s; hook 4.2 s; CTA 10.5 s |
+| Images | 37 shots, none repeated |
+| Public page captures and the narrator's own screen recordings | 14 shots |
+| The narrator's own brand assets (product mascot) | 3 |
+| Authored scenes built from the narrator's real data (folders, files) | 3 |
+| Illustrative generated stills | 15 |
+| Hook collage and full-frame presenter CTA | 2 |
+| Presenter | Floating cut-out, relocated on almost every cut |
+
+What the user approved:
+- the floating cut-out;
+- real product pages and the narrator's own tools as the personal experience;
+- one image per idea;
+- the headline set directly on a collage that shows the real brand marks of the list.
+
+What the user corrected: a framed presenter, an opacity fade on the cut-out, a backing band behind the headline, repeated images, empty authored scenes and generic stand-ins for named products.