editorbrain 0.6.0 → 0.8.0

package/README.md

@@ -5,20 +5,21 @@ Editorial references, brand context and portable video projects for Claude Code
 Inspect the CLI without configuring your agent:
 
 ```sh
-npx editorbrain@0.6.0 help
+npx editorbrain@0.8.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.6.0
+npm install -g editorbrain@0.8.0
 editorbrain login --url https://api.editorbrain.com
 editorbrain status --url https://api.editorbrain.com
-editorbrain pull --dir ./my-videos --url https://api.editorbrain.com
+editorbrain projects list
+editorbrain pull --project YOUR_PROJECT_ID --dir ./my-videos --url https://api.editorbrain.com
 editorbrain skill install --dir ./my-videos --agent both
 ```
 
-Create an account and follow connection instructions at https://editorbrain.com/app/settings. Login requires browser consent. Skills install locally; MCP authentication is configured separately. Preserve existing customized instructions and inspect installation conflicts. The package contains the CLI and skill documentation, not private library content or customer credentials. Editing and rendering use your agent's external tools.
+Create an account and follow connection instructions at https://editorbrain.com/app/settings. Login requires browser consent. Pull downloads only the selected project and its brand/style context, remembers the selection, and leaves reference evidence remote. Use `documents list/get` for additional saved documents; `pull --all` is an explicit full-workspace operation. Skills install locally; MCP authentication is configured separately. Preserve existing customized instructions and inspect installation conflicts. The package contains the CLI and skill documentation, not private library content or customer credentials. Editing and rendering use your agent's external tools.
 
 ## Installation and permissions
 

package/bin/editorbrain.mjs

@@ -1,9 +1,5 @@
 #!/usr/bin/env node
 
-// packages/cli/src/setup.ts
-import { spawn } from "node:child_process";
-import { resolve as resolve3 } from "node:path";
-
 // packages/core/src/index.ts
 var SCHEMA_VERSION = 1;
 var MAX_DOCUMENT_BYTES = 128 * 1024;
@@ -107,6 +103,7 @@ function validateDocument(path, content) {
   if (isProject) {
     for (const key of ["id", "brand", "style", "outputProfile"]) if (typeof doc[key] !== "string" || !identifier.test(doc[key])) add(`${key} must be a valid identifier`);
     if (!object(doc.intent) || !nonempty(doc.intent.topic) || !nonempty(doc.intent.goal)) add("intent requires topic and goal");
+    if (doc.reviewMode !== void 0 && !["direct", "directions", "sample"].includes(doc.reviewMode)) add("reviewMode must be direct, directions or sample");
     if (doc.script !== void 0 && typeof doc.script !== "string") add("script must be text");
     if (doc.overrides !== void 0) {
       if (!object(doc.overrides)) add("overrides must be an object");
@@ -546,7 +543,7 @@ var Client = class {
     for (let attempt = 0; attempt < 3; attempt++) {
       let response;
       try {
-        response = await this.fetcher(`${this.url}${path}`, { method, headers, body: options.body === void 0 ? void 0 : JSON.stringify(options.body), redirect: "error", signal: AbortSignal.timeout(2e4) });
+        response = await this.fetcher(`${this.url}${path}`, { method, headers, body: options.body === void 0 ? void 0 : JSON.stringify(options.body), redirect: "error", signal: AbortSignal.timeout(Math.min(18e4, Math.max(1e3, options.timeoutMs ?? 2e4))) });
       } catch {
         if (readOnly && attempt < 2) {
           await this.runtime.sleep(250 * 2 ** attempt + this.runtime.random() * 100);
@@ -575,8 +572,8 @@ var Client = class {
   async me() {
     return this.request("/v1/me");
   }
-  async list() {
-    const data = await this.request("/v1/documents");
+  async list(prefix = "") {
+    const data = await this.request("/v1/documents" + (prefix ? "?" + new URLSearchParams({ prefix }) : ""));
     return data.documents;
   }
   async get(path) {
@@ -604,6 +601,7 @@ async function loadSyncState(root, endpoint, workspaceId) {
       return readText(root, ".editorharness/.sync.json", false);
     });
     const state = JSON.parse(raw);
+    if (state.projectId !== void 0) assertIdentifier(state.projectId);
     if (state.schemaVersion !== 1 || typeof state.documents !== "object") throw new Error("Invalid local sync state");
     if (state.endpoint !== endpoint || state.workspaceId !== workspaceId) throw new CliError("WORKSPACE_MISMATCH", "This folder is bound to a different endpoint/workspace.", "Use a separate folder; never merge private documents across spaces.");
     for (const [path, item] of Object.entries(state.documents)) {
@@ -679,7 +677,7 @@ ${conflicts.join("\n")}`, "Run push --dry-run and reconcile the reported paths."
 async function pullWorkspace(client, root, local, options = {}) {
   const me = await client.me();
   const state = await loadSyncState(root, client.url, me.workspaceId);
-  const summaries = await client.list();
+  const summaries = options.summaries ?? await client.list();
   const pending = [];
   const conflicts = [];
   let unchanged = 0;
@@ -704,12 +702,13 @@ async function pullWorkspace(client, root, local, options = {}) {
 ${conflicts.join("\n")}`, "Run pull --dry-run and reconcile the reported paths.", false, { conflicts });
   const documents = [];
   for (const summary of pending) {
-    const doc = await client.get(summary.path);
+    const doc = options.prefetched?.get(summary.path) ?? await client.get(summary.path);
     checkRemote(doc);
     const validation = validateDocument(doc.path, doc.content);
     if (!validation.valid || doc.path !== summary.path || doc.revision !== summary.revision || doc.sha256 !== summary.sha256 || await sha256(doc.content) !== doc.sha256) throw new Error(`Document changed during pull or failed integrity: ${summary.path}. Retry.`);
     documents.push(doc);
   }
+  await options.beforeWrite?.();
   const downloaded = [];
   for (const doc of documents) {
     let current;
@@ -728,12 +727,57 @@ ${conflicts.join("\n")}`, "Run pull --dry-run and reconcile the reported paths."
   return { downloaded, unchanged };
 }
 
+// packages/cli/src/project-selection.ts
+async function listProjects(client) {
+  const documents = await client.list("videos/");
+  return documents.filter((row) => /^videos\/[^/]+\/project\.json$/.test(row.path)).map((row) => ({ id: assertIdentifier(row.path.split("/")[1]), revision: row.revision, updatedAt: row.updatedAt }));
+}
+async function pullProject(client, root, local, options = {}) {
+  const me = await client.me(), state = await loadSyncState(root, client.url, me.workspaceId);
+  let projectId = options.projectId ?? state.projectId;
+  if (!projectId) {
+    const localIds = Object.keys(local).filter((path) => /^videos\/[^/]+\/project\.json$/.test(path)).map((path) => path.split("/")[1]);
+    if (localIds.length === 1) projectId = localIds[0];
+  }
+  if (!projectId) {
+    const projects = await listProjects(client);
+    if (projects.length !== 1) throw new CliError("PROJECT_SELECTION_REQUIRED", projects.length ? "Choose the project to prepare." : "No saved projects are available.", "Use editorbrain projects list, then setup or pull --project <id>. Create your first project in the app if needed.", false, { projects });
+    projectId = projects[0].id;
+  }
+  assertIdentifier(projectId);
+  const projectPath = `videos/${projectId}/project.json`, projectDoc = await client.get(projectPath);
+  if (projectDoc.path !== projectPath || !validateDocument(projectPath, projectDoc.content).valid || await sha256(projectDoc.content) !== projectDoc.sha256) throw new CliError("INVALID_PROJECT", "Project content failed validation.", "Check the saved project before retrying.");
+  const project = JSON.parse(projectDoc.content);
+  if (project.id !== projectId) throw new CliError("INVALID_PROJECT", "Project ID does not match its path.", "Correct the project in the app.");
+  const wanted = /* @__PURE__ */ new Set([...projectSources(project), ...optionalProjectSources(project)]);
+  const prefixes = [`.editorbrain/brands/${project.brand}/`, `.editorbrain/styles/${project.style}/`, `.editorbrain/output-profiles/${project.outputProfile}.json`, `videos/${projectId}/`];
+  const documents = [];
+  for (const prefix of prefixes) for (const doc of await client.list(prefix)) if (wanted.has(doc.path) && !documents.some((row) => row.path === doc.path)) documents.push(doc);
+  const initial = documents.find((row) => row.path === projectPath);
+  if (!initial || initial.revision !== projectDoc.revision || initial.sha256 !== projectDoc.sha256) throw new CliError("SYNC_CONFLICT", "Project selection changed during preparation.", "Retry the current project.");
+  const missing = projectSources(project).filter((path) => !documents.some((row) => row.path === path));
+  if (missing.length) throw new CliError("INCOMPLETE_PROJECT", "The project is missing required context.", "Complete these files in the app before preparing the project.", false, { missing });
+  const result = await pullWorkspace(client, root, local, { dryRun: options.dryRun, summaries: documents, prefetched: /* @__PURE__ */ new Map([[projectPath, projectDoc]]), beforeWrite: async () => {
+    const fresh = await client.get(projectPath);
+    if (fresh.sha256 !== projectDoc.sha256 || fresh.revision !== projectDoc.revision) throw new CliError("SYNC_CONFLICT", "Project selection changed during download.", "Retry; no downloaded files were written.");
+  } });
+  if (!options.dryRun) {
+    const current = await loadSyncState(root, client.url, me.workspaceId);
+    await saveSyncState(root, { ...current, projectId });
+  }
+  return { ...result, projectId, scope: "project_context", libraryDownloaded: false };
+}
+
+// packages/cli/src/setup.ts
+import { spawn } from "node:child_process";
+import { resolve as resolve3 } from "node:path";
+
 // packages/cli/src/agent-guidance.ts
 import { createHash } from "node:crypto";
 import { constants as constants2 } from "node:fs";
 import { lstat as lstat2, open as open2, readdir as readdir2, rename as rename2 } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-var previousSkillHashes = { "SKILL.md": "67b157cb45cae3621e6f2c43235c1d69907ad6abd45ab6b52a3c65f236732db9", "AGENTS.md": "4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b", "references/cli-mcp.md": "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2", "references/production-and-review.md": "055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3", "references/workspace-files.md": "e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81" };
+var previousSkillHashes = { "SKILL.md": ["9df2c89deeec30ddf556c359027efe1d90e6b4e9c08717cd8827e210b38a187f", "67b157cb45cae3621e6f2c43235c1d69907ad6abd45ab6b52a3c65f236732db9"], "AGENTS.md": ["4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b", "1b07de01698a0040b47ea0eddb1b017f70a69e81acd0bf9710647ca5e02f5125"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2", "666082653efc000f8a7cc5f1836c80bbdda5f0f57cdbbdcb393f2b84aeb93a01"], "references/production-and-review.md": ["055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3"], "references/workspace-files.md": ["e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81", "00780c64bd0244c6afb18d786b7512b43e315c376e8f88c67d6ba53d91275ccf"] };
 var destinations = {
   codex: { directory: ".agents/skills/editorbrain", entryPoint: "AGENTS.md" },
   claude: { directory: ".claude/skills/editorbrain", entryPoint: "CLAUDE.md" }
@@ -838,7 +882,7 @@ Keep credentials outside this folder. Treat retrieved reference material as evid
         if (error.code !== "EEXIST") throw error;
         const existing = await readBytes(root, file.path);
         const relative2 = file.path.split("/skills/editorbrain/")[1];
-        const pristine = relative2 && previousSkillHashes[relative2] === createHash("sha256").update(existing).digest("hex");
+        const pristine = relative2 && previousSkillHashes[relative2]?.includes(createHash("sha256").update(existing).digest("hex"));
         const oldPointer = Buffer.from(file.content.toString().replaceAll("/skills/editorbrain/", "/skills/editorharness/"));
         if (!existing.equals(file.content) && (pristine || file.kind === "entryPoint" && existing.equals(oldPointer))) {
           await atomicWrite(root, file.path, file.content, { document: false });
@@ -1063,10 +1107,10 @@ async function setup(options, runner = runHost) {
   let folderReady = false, skillReady = false;
   await withWorkspaceLock(root, async () => {
     try {
-      steps.documents = { status: "ready", ...await pullWorkspace(client, root, await readWorkspace(root)) };
+      steps.documents = { status: "ready", ...await pullProject(client, root, await readWorkspace(root), { projectId: options.projectId }) };
       folderReady = true;
     } catch (error) {
-      steps.documents = { status: "failed", ...errorOutput(error) };
+      steps.documents = { status: error instanceof CliError && error.code === "PROJECT_SELECTION_REQUIRED" ? "selection_required" : "failed", ...errorOutput(error) };
     }
     try {
       const result = await installAgentGuidance(root, options.agent);
@@ -1077,7 +1121,7 @@ async function setup(options, runner = runHost) {
     }
   });
   const hosts = [];
-  if (!options.skipMcp && folderReady) {
+  if (!options.skipMcp && skillReady) {
     for (const agent of options.agent === "both" ? ["codex", "claude"] : [options.agent]) {
       try {
         hosts.push(await configureMcp(agent, root, client.url, !!options.noBrowser, runner));
@@ -1302,7 +1346,7 @@ async function prepareDirectionContext(root, client, projectId) {
 var HELP = `EditorBrain \u2014 portable editorial context for AI video agents
 
 editorbrain version
-editorbrain setup --dir folder --agent codex|claude|both [--workspace id] [--no-browser] [--skip-mcp]
+editorbrain setup --dir folder --agent codex|claude|both [--project id] [--workspace id] [--no-browser] [--skip-mcp]
 editorbrain doctor [--dir folder] [--agent codex|claude|both] [--offline]
 editorbrain init [--dir folder] [--brand id] [--style id] [--project id] [--topic text] [--goal text] [--agent codex|claude|both]
 editorbrain skill install [--dir folder] [--agent codex|claude|both]
@@ -1313,7 +1357,13 @@ editorbrain login [--url https://server] [--no-browser] [--timeout seconds]
 editorbrain login [--url https://server] --key-stdin
 editorbrain register --url https://server --name workspace --invite-stdin
 editorbrain status
-editorbrain push|pull [--dir folder] [--dry-run]
+editorbrain pull [--project id | --all] [--dir folder] [--dry-run]
+editorbrain push [--dir folder] [--dry-run]
+editorbrain projects list
+editorbrain documents list [--prefix path]
+editorbrain documents get <path>
+editorbrain workflow check [--project id] [--previous-version hash]
+editorbrain search edit [--script file | --video file | --asset sha256 | --project id] [--requirements text] [--assets tag,tag] [--mode styles|events|both] [--review direct|directions|sample]
 editorbrain library search [query]
 editorbrain library get <video-id> [--document relative-source-path] [--sha256 source-hash]
 editorbrain library media <video-id> --sha256 media-hash --out file
@@ -1340,8 +1390,8 @@ Output is JSON except help; login progress/code goes to stderr. --url overrides
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
-  const booleans = /* @__PURE__ */ new Set(["help", "version", "offline", "dry-run", "key-stdin", "invite-stdin", "no-browser", "skip-mcp"]);
-  const known = /* @__PURE__ */ new Set(["dir", "brand", "style", "project", "topic", "goal", "name", "adapter", "out", "url", "document", "mime", "label", "role", "limit", "cursor", "timeout", "assets", "capabilities", "duration", "agent", "workspace", "sha256", "kind", "channel", "epistemic-status", "event-offset", "relation-offset", ...booleans]);
+  const booleans = /* @__PURE__ */ new Set(["help", "version", "offline", "dry-run", "key-stdin", "invite-stdin", "no-browser", "skip-mcp", "all"]);
+  const known = /* @__PURE__ */ new Set(["dir", "brand", "style", "project", "topic", "goal", "name", "adapter", "out", "url", "document", "mime", "label", "role", "limit", "cursor", "timeout", "assets", "capabilities", "duration", "agent", "workspace", "prefix", "sha256", "kind", "channel", "epistemic-status", "event-offset", "relation-offset", "script", "video", "asset", "requirements", "mode", "review", "previous-version", ...booleans]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -1487,6 +1537,8 @@ Waiting for authorization. Press Ctrl+C to cancel.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const [command, subcommand, argument] = args.positional;
+  if (args.flags.all && command !== "pull") throw new Error("--all is supported only by pull.");
+  if (args.flags.all && str(args, "project")) throw new Error("Choose --project or --all, not both.");
   if (command === "version" || args.flags.version) {
     output({ name: "EditorBrain", version: await cliVersion() });
     return;
@@ -1520,7 +1572,7 @@ async function main() {
     return;
   }
   if (command === "setup") {
-    const result = await setup({ directory: str(args, "dir") ?? "./mis-videos", agent: parseAgentTarget(str(args, "agent")), workspaceId: str(args, "workspace"), skipMcp: !!args.flags["skip-mcp"], noBrowser: !!args.flags["no-browser"], getConfig: () => config(args, false), login: () => login(args, true) });
+    const result = await setup({ directory: str(args, "dir") ?? "./mis-videos", agent: parseAgentTarget(str(args, "agent")), workspaceId: str(args, "workspace"), projectId: str(args, "project"), skipMcp: !!args.flags["skip-mcp"], noBrowser: !!args.flags["no-browser"], getConfig: () => config(args, false), login: () => login(args, true) });
     output(result);
     if (result.status !== "ready") process.exitCode = 2;
     return;
@@ -1603,6 +1655,24 @@ async function main() {
     }
     throw new Error("Use keys list, keys create --label name, or keys revoke <key-id>");
   }
+  if (command === "projects" && subcommand === "list") {
+    output({ projects: await listProjects(new Client(await config(args))) });
+    return;
+  }
+  if (command === "documents") {
+    const client = new Client(await config(args));
+    if (subcommand === "list") {
+      output({ documents: await client.list(str(args, "prefix") ?? "") });
+      return;
+    }
+    if (subcommand === "get" && argument) {
+      const doc = await client.get(argument);
+      if (await sha256(doc.content) !== doc.sha256) throw new Error("Document integrity failed");
+      output(doc);
+      return;
+    }
+    throw new Error("Use documents list --prefix path or documents get <path>.");
+  }
   if (command === "assets") {
     const client = new Client(await config(args));
     if (subcommand === "list") {
@@ -1668,6 +1738,46 @@ async function main() {
     }
     throw new Error("Use narrative search [query] or narrative get <video-id>.");
   }
+  if (command === "workflow" && subcommand === "check") {
+    const client = new Client(await config(args));
+    output(await client.request("/v1/workflow/check", { method: "POST", body: { projectId: str(args, "project"), previousVersion: str(args, "previous-version") } }));
+    return;
+  }
+  if (command === "search" && subcommand === "edit") {
+    const client = new Client(await config(args));
+    const scriptPath = str(args, "script"), videoPath = str(args, "video");
+    let script, assetId = str(args, "asset");
+    const readInput = async (path, max) => {
+      const handle = await open4(resolve4(path), constants4.O_RDONLY | constants4.O_NOFOLLOW);
+      try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > max) throw new Error(`Input must be a regular file of at most ${max} bytes.`);
+        return await handle.readFile();
+      } finally {
+        await handle.close();
+      }
+    };
+    if (videoPath && assetId) throw new Error("Use --video or --asset, not both.");
+    if (scriptPath) {
+      script = new TextDecoder("utf-8", { fatal: true }).decode(await readInput(scriptPath, 64e3));
+      if (script.length > 16e3) throw new Error("Script must contain at most 16000 characters.");
+    }
+    const mode = str(args, "mode") ?? "both", reviewMode = str(args, "review");
+    if (!["styles", "events", "both"].includes(mode)) throw new Error("--mode must be styles, events or both.");
+    if (reviewMode && !["direct", "directions", "sample"].includes(reviewMode)) throw new Error("--review must be direct, directions or sample.");
+    if (assetId && !/^[a-f0-9]{64}$/.test(assetId)) throw new Error("--asset requires an owned production asset SHA-256.");
+    if (videoPath) {
+      const bytes = await readInput(videoPath, 12 * 1024 * 1024);
+      const mimeType = { ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm" }[extname(videoPath).toLowerCase()];
+      if (!mimeType) throw new Error("Use MP4, MOV or WebM.");
+      assetId = await sha256(bytes);
+      const uploaded = await client.media(`/v1/assets/${assetId}?name=${encodeURIComponent(basename(videoPath))}`, { content: bytes, mimeType });
+      if ((await uploaded.json()).sha256 !== assetId) throw new Error("Upload hash mismatch.");
+    }
+    if (!script && !assetId && !str(args, "project")) throw new Error("Provide --script, --video, --asset or --project with a saved script.");
+    output(await client.request("/v1/search/edit", { method: "POST", timeoutMs: 18e4, body: { script, assetId, projectId: str(args, "project"), requirements: str(args, "requirements") ?? "", availableAssets: (str(args, "assets") ?? "").split(",").filter(Boolean), mode, reviewMode } }));
+    return;
+  }
   if (command === "library") {
     const client = new Client(await config(args));
     if (subcommand === "search") {
@@ -1717,7 +1827,7 @@ async function main() {
   const run = async () => {
     const files = await readWorkspace(root);
     if (command === "pull") {
-      output(await pullWorkspace(new Client(await config(args)), root, files, { dryRun: !!args.flags["dry-run"] }));
+      output(await (args.flags.all ? pullWorkspace(new Client(await config(args)), root, files, { dryRun: !!args.flags["dry-run"] }) : pullProject(new Client(await config(args)), root, files, { projectId: str(args, "project"), dryRun: !!args.flags["dry-run"] })));
       return;
     }
     if (Object.keys(files).length === 0) throw new Error("No portable documents found. Run init or pull first.");

package/package.json

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

package/skill/editorbrain/AGENTS.md

@@ -1,6 +1,6 @@
 # Customer agent contract
 
-Your responsibility is to turn Harness evidence into editorial decisions suitable for this project, execute the requested work, and check the result. Do not stop at matching a palette or exporting a plan when the user asked for an edited video.
+Your responsibility is to turn EditorBrain evidence into editorial decisions suitable for this project, execute the requested work, and check the result. Do not stop at matching a palette or exporting a plan when the user asked for an edited video.
 
 ## Understand the project
 
@@ -10,12 +10,23 @@ Your responsibility is to turn Harness evidence into editorial decisions suitabl
 - Separate a faithful preset transfer, an adaptation of an editorial family, and inspiration from selected techniques. Infer the intended degree from the request and record it briefly. Preserve the distinctive features the user asked for; do not silently substitute a generic approximation.
 - If evidence supports only part of a faithful transfer, name that part and the unverified details. A provisional plan can be useful, but missing media or final timing must remain explicit production dependencies rather than a claim that it is fully ready to execute.
 
+## Selective access
+
+Prepare only the active project's immediate context with `editorbrain pull --project <id>`.
+Use `editorbrain projects list` to discover IDs; ask which project if the intent is ambiguous.
+Default pull remembers the successful selection; never use `--all` during normal onboarding.
+Reference-library documents/media remain remote and are retrieved to answer a concrete
+editing question. Existing proposals or other project documents can be discovered through
+`documents list --prefix videos/<id>/` and read with `documents get <path>` or MCP
+`list_documents` / `read_document`. No need to enumerate or read the whole workspace.
+
 ## Read context and evidence
 
 Read [the workspace file map](references/workspace-files.md) for the full structure, required/optional files and token precedence. Start with `videos/<project-id>/project.json` to discover the selected brand, style and output profile. Read their actual files plus the brief and direction; do not assume that all documents under the workspace are included automatically by `resolve`.
 
 - Consult style packs for methods and the reference library for their execution. Search by communicative function as well as topic: comparison, demonstration, reveal, cumulative typography, collage, atmosphere, callback.
-- A literal search is not a quality ranking. Recommendations use explicit rules and declared resources; they do not inspect footage or prove fit. Review their reasons, limitations and required assets against the actual project.
+- Start with `search_for_edit` / `editorbrain search edit`, supplying the actual script or owned video and the project ID for brand constraints. It analyzes new material before semantic retrieval and candidate review; inspect its uncertainty, source hashes, coverage and missing assets. Its model reading is not human verification. Legacy literal search and rule-based recommendations remain lookup tools, not equivalents to this content-first flow.
+- Read `check_workflow` at the start, before proposals, before paid resource generation, and before the full render. Precedence: current explicit user request > project reviewMode > workspace default. Direct means proceed and review; directions means offer 2–3 fitting options with labelled library evidence; sample means show a representative customer-material frame or short clip and obtain approval. Do not require a new approval when the relevant version is already approved. Use a moving sample when rhythm or sound is what needs review. Save the workflow version and any approval with the project direction. A receipt acknowledges reading, not actual compliance.
 - Retrieve evidence to answer a concrete question. Use representative images for composition; intervals and source video for movement; the audio review and accessible audio for sound; narrative events and relations for hooks, development, payoff and CTA.
 - Read source documents using paths actually returned by the reference manifest. Pin hashes where supported. A script summary is not word-level alignment, and a provider candidate is not a verified measurement.
 - Check coverage, truncation and pagination. Retrieve the relevant remaining pages or source document before generalizing to an entire reference. Do not claim complete analysis from a partial tool response.

package/skill/editorbrain/SKILL.md

@@ -9,6 +9,8 @@ The public product is EditorBrain. The npm package is `editorbrain`; `editorbrai
 
 Convert reference evidence into an appropriate edit for this project. Reading the library starts the work; quality is demonstrated in the delivered video.
 
+Before selecting a style, use `check_workflow` (CLI: `editorbrain workflow check`) and `search_for_edit` (CLI: `editorbrain search edit`) with the actual script or owned production video and project ID. Respect the returned review mode: direct editing, a choice of directions, or approval of a customer-material sample. Check the preference version again before costly generation and full rendering; a web change cannot interrupt a running tool. Honor current explicit user instructions and existing approval. If these tools are unavailable, report the version limitation and inspect material and evidence explicitly; literal search is not an equivalent quality ranking.
+
 1. Read the bundled [AGENTS.md](AGENTS.md) before using the workflow. It is this skill's editorial contract; do not assume your host auto-loads it.
 2. Read [CLI and MCP](references/cli-mcp.md) when connecting, locating documents, retrieving reference media or saving work. Discover the installed CLI help and connected MCP tool schemas; they take precedence over examples for version-specific arguments.
 3. Read [Workspace files](references/workspace-files.md) when configuring a brand/style, creating projects, resolving preferences, saving feedback or upgrading an installed skill.

package/skill/editorbrain/references/cli-mcp.md

@@ -1,6 +1,6 @@
 # CLI and MCP: read, retrieve, save
 
-Use the connected MCP schema and `editorbrain help` to confirm the installed contract. Examples below describe the 0.6.0 customer workflow; older installations may lack the skill installer or reference-media tool. Do not invent commands from historical architecture documents.
+Use the connected MCP schema and `editorbrain help` to confirm the installed contract. Examples below describe the 0.7.0 customer workflow; older installations may lack the skill installer or reference-media tool. Do not invent commands from historical architecture documents.
 
 API/MCP: `https://api.editorbrain.com/mcp`. The host must connect this server separately; installing a skill does not register or authorize MCP.
 
@@ -10,7 +10,8 @@ An existing account normally starts with:
 
 ```sh
 editorbrain status
-editorbrain pull --dir ./my-videos
+editorbrain projects list
+editorbrain pull --project <id> --dir ./my-videos
 editorbrain skill install --dir ./my-videos --agent both
 ```
 
@@ -20,13 +21,20 @@ Skill installation is offline and independent of login. It creates `.agents/skil
 
 Existing root `AGENTS.md`/`CLAUDE.md` are preserved. Read the install result's instruction paths and conflict reports. A preserved root guide does not mean the native skill failed; a conflicting existing skill needs a deliberate merge, not an overwrite. Do not replace the user's custom instructions to finish setup.
 
-For a separate local workspace, `editorbrain init --dir ./new-video --brand <id> --style <id> --project <id>` creates portable context and installs guidance. Do not initialize over a pulled workspace to reset it. `pull` and `push` synchronize documents, not the installed native skill folders or local render media.
+For a separate local workspace, `editorbrain init --dir ./new-video --brand <id> --style <id> --project <id>` creates portable context and installs guidance. Do not initialize over a pulled workspace to reset it. `pull` prepares selected project documents. `push` uploads changed documents already present in the local folder, not the entire remote workspace. Keep unrelated projects in separate local folders and inspect `push --dry-run` before uploading. Neither command synchronizes installed native skill folders or local render media.
+
+`setup --project <id>` prepares only that project's immediate brand/style/output
+context. With multiple projects and no remembered selection it reports
+`PROJECT_SELECTION_REQUIRED`, without downloading their contents. Normal `pull`
+remembers the selected project; full-space `pull --all` is an explicit advanced action.
+Use `documents list --prefix videos/<id>/` and `documents get <path>` to consult
+additional saved plans/reviews when needed. These reads do not materialize or sync files.
 
 ## Reading the project
 
 MCP sequence:
 
-1. `workspace_info({})`, `list_documents({})`.
+1. `workspace_info({})`, then `list_documents({prefix:"videos/"})` to discover project IDs only when needed. Prefer a known project ID; use narrower brand/style/project prefixes for additional metadata. Never read every listed document by default.
 2. `read_document({path})` for discovered project, brief, brand, style and optional media manifest.
 3. `get_asset({assetId})` for production media IDs. Download the authorized asset for inspection; preserve its ID/hash, not its temporary URL.
 4. `resolve_project({projectId})` to inspect effective tokens, exceptions, source hashes and pending requirements.
@@ -105,7 +113,7 @@ editorbrain push --dir ./my-videos
 `push` is not a media upload. Use `assets upload <file>` for authorized production files within current limits and then record returned IDs/hashes. Keep large renders/evidence in the appropriate media store, with permanent identifiers in the project. Preserve old revisions and disclose unsynchronized local work if saving fails.
 
 
-## Recovery and diagnostics (CLI 0.6.0)
+## Recovery and diagnostics (CLI 0.7.0)
 
 Use `editorbrain version` to discover the installed release. Run `editorbrain doctor --dir <folder> --agent codex|claude|both` before troubleshooting; `--offline` deliberately skips credentials and remote checks. Doctor is read-only. Its `mcpClient: not_verified` is not a claim that the host is connected. A customized skill is reported as a warning, not replaced automatically.
 
@@ -115,7 +123,7 @@ Errors include `code`, `hint`, `retryable` and the legacy text `error`. `AUTH_RE
 
 GET requests use bounded retries and respect Retry-After. Writes are not retried automatically: after a network error, inspect remote state before repeating them. Do not treat `retryable` as permission for an unbounded loop. HTTP error bodies are not printed. The MCP now provides matching structuredContent and text; consume either without counting them as separate results. Writing a document is declared mutating and may update existing content even though revision history is preserved.
 
-## Guided setup and OAuth (0.6.0)
+## Guided setup and OAuth (0.7.0)
 
 `editorbrain setup --dir ./mis-videos --agent codex --workspace <expected-id>` authorizes the CLI when necessary, pulls documents, installs the complete skill and registers an absent MCP connection. Use `claude` or `both` for other hosts. The expected ID is a check, never authorization. Setup preserves existing MCP entries and customized guidance. Exit 2 means action is still required; inspect each step instead of repeating blindly. `--no-browser` defers MCP registration; `--skip-mcp` prepares only the CLI/skill.
 
@@ -124,3 +132,37 @@ Codex can use `codex mcp login editorbrain`; Claude Code completes OAuth from `/
 `editorbrain narrative search [query] --kind hook --channel visual` finds candidates. `narrative get <video-id> --sha256 <document-hash> --event-offset 0 --relation-offset 0 --limit 50` pages through one pinned narrative document; follow returned offsets. Missing narrative coverage stays explicit.
 
 `editorbrain library media <video-id> --sha256 <media-hash> --out <new-file>` downloads an authorized frame/audio/video and verifies its hash (90 MiB maximum). It will not overwrite an existing file. Downloading is not reviewing: inspect it with available visual/audio tools and record the intervals actually checked. Neither CLI nor MCP ingest customer references.
+
+
+## Content-first search and web preferences (0.8+)
+
+```sh
+editorbrain workflow check --project my-video
+editorbrain search edit --script ./script.txt --project my-video --mode both
+editorbrain search edit --video ./analysis-proxy.mp4 --project my-video
+editorbrain workflow check --project my-video --previous-version <returned-hash>
+```
+
+MCP equivalents: `check_workflow` and `search_for_edit`. Use their current schemas.
+A topic alone is insufficient. A project may supply its saved script; passing a video
+uploads that selected production asset to the workspace, then sends it to the configured
+analysis provider. This is customer material, not a new library reference. No automatic
+scraping, FFmpeg installation, asset generation or rendering occurs.
+
+Video inputs currently accept MP4/MOV/WebM up to 12 MiB and 24,000 analysis input tokens.
+For a larger source, prepare a complete analysis proxy with the available media tools;
+keep the original and record duration/coverage. If using excerpts, disclose omitted
+content. Never treat coarse model timing as frame-accurate or inferred sound as verified.
+Scripts accept up to 16,000 characters. Search may take longer than a literal lookup.
+
+Results include source hashes, observed/inferred limitations, applicable evidence,
+missing resources, current workflow version and per-stage elapsed time/token usage.
+A null token count means the provider did not report it, not zero. Follow pinned
+source paths and retrieve needed example media; do not enumerate the entire library.
+If no fit exists, disclose the gap rather than fabricate a matching style. Source,
+reference access or preference changes during a search invalidate that result.
+
+Web preferences are pulled at checkpoints, not pushed into arbitrary agent chats.
+`check_workflow` records a receipt; it cannot stop a tool already running. After a
+version change, reconcile the next step and relevant approval with the current user
+instruction. Do not repeat approval just because an unrelated preference changed.

package/skill/editorbrain/references/workspace-files.md

@@ -79,3 +79,13 @@ Save reusable feedback at its stated scope: project-only changes in the project,
 Updating the global CLI does not replace skills already copied into a project. Run `editorbrain skill install --dir <workspace> --agent both` and inspect `conflicts`, `preserved`, `warnings` and `readInstructions`.
 
 If skill files differ, the installer keeps them. Prepare the new version in a separate temporary directory, compare it with the project's installed copy, and merge changes while preserving custom instructions. Do not assume a successful exit means all guidance was upgraded. Root `AGENTS.md`/`CLAUDE.md` remain user-owned: if already present, use the returned skill path explicitly, or add a narrowly scoped pointer when the user asks to integrate it. There is no automatic global installation for every future project.
+
+
+## Review preference
+
+`videos/<id>/project.json` optionally stores `reviewMode`: `direct`, `directions`, or
+`sample`. Omit it to inherit the workspace default saved in the web app. The current
+explicit user instruction takes precedence. Read the effective value with
+`check_workflow` / `editorbrain workflow check`; local files alone cannot reveal a
+new web preference. Store received versions and scoped approvals in `direction.md`.
+Brand colors/fonts and editing effects/music remain in their existing files.