editorbrain 0.5.0 → 0.7.0

package/README.md

@@ -5,30 +5,29 @@ Editorial references, brand context and portable video projects for Claude Code
 Inspect the CLI without configuring your agent:
 
 ```sh
-npx editorbrain@0.5.0 help
+npx editorbrain@0.7.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.5.0
+npm install -g editorbrain@0.7.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
 ```
 
-Both `editorbrain` and the compatible `editorharness` command run the same CLI. Existing folders and skills remain named `editorharness`. Do not install both distributions globally at the same time; choose one rather than forcing binary conflicts.
-
-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
 
 - No install/postinstall hooks, runtime package dependencies, native binaries or background services. Installing the package does not register MCP servers or modify agent instructions.
 - Configuration happens only when you run a command. `skill install` writes the selected project's skill files and instruction pointers; existing customizations are preserved and conflicts reported.
-- `login` uses browser consent and stores the CLI credential in `~/.config/editorharness/config.json` (owner-only permissions on POSIX systems). This is a local credential file, not an OS keychain. Never share it or commit it.
+- `login` uses browser consent and stores the CLI credential in `~/.config/editorbrain/config.json` (owner-only permissions on POSIX systems). This is a local credential file, not an OS keychain. Never share it or commit it.
 - Remote commands contact the selected API endpoint. Use the official `https://api.editorbrain.com` endpoint. Commands such as push and media upload transfer the selected documents or assets; npm installation and help do not upload your projects.
-- MCP credentials are separate and must be provided locally through the documented environment variable. Do not paste secrets into chats or project files.
+- MCP uses separate OAuth consent in the browser. Do not paste secrets into chats or project files.
 - Updates are explicit. Pin a version for reproducibility; do not bypass agent permission prompts or use sudo/--force to resolve installation conflicts.
 
 Distribution is proprietary (UNLICENSED); publication on npm does not make the private service or library open source.

package/bin/{editorharness.mjs → editorbrain.mjs}

@@ -1,11 +1,5 @@
 #!/usr/bin/env node
 
-// packages/cli/src/index.ts
-import { chmod, lstat as lstat3, mkdir as mkdir2, open as open4 } from "node:fs/promises";
-import { constants as constants4 } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname as dirname2, extname, join as join2, resolve as resolve3 } from "node:path";
-
 // packages/core/src/index.ts
 var SCHEMA_VERSION = 1;
 var MAX_DOCUMENT_BYTES = 128 * 1024;
@@ -30,9 +24,9 @@ function assertIdentifier(value) {
 }
 function safeDocumentPath(path) {
   if (typeof path !== "string" || path.length > 400 || /[\\\x00-\x1f\x7f%:]/.test(path) || path.startsWith("/") || path.endsWith("/")) throw new Error("Unsafe document path");
-  const parts = path.split("/");
+  const parts = canonicalDocumentPath(path).split("/");
   if (parts.some((part) => !part || part === "." || part === ".." || part.length > 100 || !/^[a-zA-Z0-9_.-]+$/.test(part) || ["__proto__", "prototype", "constructor"].includes(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) || /[. ]$/.test(part))) throw new Error("Unsafe or nonportable path segment");
-  if (![".editorharness", "videos"].includes(parts[0]) || parts.length < 3 || !/\.(json|md)$/.test(parts.at(-1))) throw new Error("Documents must be .md/.json beneath .editorharness/ or videos/");
+  if (![".editorbrain", ".editorharness", "videos"].includes(parts[0]) || parts.length < 3 || !/\.(json|md)$/.test(parts.at(-1))) throw new Error("Documents must be .md/.json beneath .editorbrain/ or videos/");
   if (parts.some((part) => /^\.env(?:\.|$)/i.test(part) || [".sync.json", ".credentials.json", "credentials.json"].includes(part.toLowerCase()))) throw new Error("Credential and local state files cannot be synced");
   return path;
 }
@@ -86,10 +80,10 @@ function validateDocument(path, content) {
     return { valid: false, issues };
   }
   if (doc.schemaVersion !== SCHEMA_VERSION) add("schemaVersion must be 1");
-  const parts = path.split("/");
-  const isBrand = parts[0] === ".editorharness" && parts[1] === "brands" && parts.length === 4;
-  const isStyle = parts[0] === ".editorharness" && parts[1] === "styles" && parts.length === 4;
-  const isOutput = parts[0] === ".editorharness" && parts[1] === "output-profiles" && parts.length === 3;
+  const parts = canonicalDocumentPath(path).split("/");
+  const isBrand = parts[0] === ".editorbrain" && parts[1] === "brands" && parts.length === 4;
+  const isStyle = parts[0] === ".editorbrain" && parts[1] === "styles" && parts.length === 4;
+  const isOutput = parts[0] === ".editorbrain" && parts[1] === "output-profiles" && parts.length === 3;
   const isProject = parts[0] === "videos" && parts.length === 3 && parts[2] === "project.json";
   const isMedia = parts[0] === "videos" && parts.length === 3 && parts[2] === "media.json";
   if (isBrand || isStyle || isProject || isOutput) {
@@ -145,23 +139,24 @@ function validateDocument(path, content) {
 }
 function projectSources(project) {
   return [
-    `.editorharness/brands/${project.brand}/brand.md`,
-    `.editorharness/brands/${project.brand}/tokens.json`,
-    `.editorharness/brands/${project.brand}/language.json`,
-    `.editorharness/brands/${project.brand}/assets.json`,
-    `.editorharness/styles/${project.style}/style.md`,
-    `.editorharness/styles/${project.style}/style.json`,
-    `.editorharness/styles/${project.style}/examples.json`,
-    `.editorharness/output-profiles/${project.outputProfile}.json`,
+    `.editorbrain/brands/${project.brand}/brand.md`,
+    `.editorbrain/brands/${project.brand}/tokens.json`,
+    `.editorbrain/brands/${project.brand}/language.json`,
+    `.editorbrain/brands/${project.brand}/assets.json`,
+    `.editorbrain/styles/${project.style}/style.md`,
+    `.editorbrain/styles/${project.style}/style.json`,
+    `.editorbrain/styles/${project.style}/examples.json`,
+    `.editorbrain/output-profiles/${project.outputProfile}.json`,
     `videos/${project.id}/project.json`,
     `videos/${project.id}/brief.md`,
     `videos/${project.id}/direction.md`
   ];
 }
 function optionalProjectSources(project) {
-  return [`.editorharness/brands/${project.brand}/design.md`, `.editorharness/styles/${project.style}/effects.md`, `.editorharness/styles/${project.style}/music.md`, `videos/${project.id}/media.json`];
+  return [`.editorbrain/brands/${project.brand}/design.md`, `.editorbrain/styles/${project.style}/effects.md`, `.editorbrain/styles/${project.style}/music.md`, `videos/${project.id}/media.json`];
 }
 function validateWorkspace(files) {
+  files = canonicalFiles(files);
   const issues = [];
   for (const [path, content] of Object.entries(files)) issues.push(...validateDocument(path, content).issues);
   for (const [path, content] of Object.entries(files)) {
@@ -181,6 +176,7 @@ async function sha256(content) {
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
 }
 async function resolveProject(files, projectId) {
+  files = canonicalFiles(files);
   assertIdentifier(projectId);
   const path = `videos/${projectId}/project.json`;
   if (!own(files, path)) throw new ValidationError([{ path, message: "Project does not exist" }]);
@@ -312,31 +308,39 @@ function createWorkspace(options = {}) {
   const project = assertIdentifier(options.project ?? "first-video");
   const json = (value) => stableJson({ schemaVersion: 1, ...value });
   return {
-    [`.editorharness/brands/${brand}/brand.md`]: `# ${options.name ?? brand}
+    [`.editorbrain/brands/${brand}/brand.md`]: `# ${options.name ?? brand}
 
 Describe identity, audience, non-negotiables and preferred visual/audio treatment. Exact colors and fonts belong in tokens.json. Do not inherit reference colors automatically.
 `,
-    [`.editorharness/brands/${brand}/design.md`]: "# Visual direction\n\nDescribe how the brand should look in context: hierarchy, readable typography, composition, photographic or illustration treatment, and use of negative space. Exact colors and fonts stay in tokens.json; refer to semantic roles instead of duplicating values here. Adapt positions and scale to the subject, material and output format. Separate graphic brand accents from natural skin tones and photographic grading. Prefer coherence and legibility over copying a reference frame literally.\n",
-    [`.editorharness/brands/${brand}/tokens.json`]: json({ id: brand, tokens: {} }),
-    [`.editorharness/brands/${brand}/language.json`]: json({ id: brand, defaultLanguage: "es", glossary: [], pronunciations: [], doNotTranslate: [] }),
-    [`.editorharness/brands/${brand}/assets.json`]: json({ id: brand, assets: [] }),
-    [`.editorharness/styles/${style}/style.md`]: "# Adaptive editorial style\n\nBuild a coherent edit around the script, audience and available material. Use B-roll to explain this topic, with a consistent photographic direction. Timing, typography, imagery and sound should support each narrative beat. Omit a technique if it weakens clarity. SFX require listening; do not infer their existence from images.\n",
-    [`.editorharness/styles/${style}/effects.md`]: "# Effects and motion\n\nChoose each effect for an editorial function: reveal information, direct attention, explain a relationship or support a transition. Time motion to the actual speech, action and reading time. Adapt intensity, easing, scale and placement to the scene; omit effects when a hold or cut works better. Do not require a zoom, transition, animation or SFX in every beat. Keep observed reference effects separate from proposed effects and verified implementations.\n",
-    [`.editorharness/styles/${style}/music.md`]: "# Music and sound\n\nChoose energy and instrumentation from the story and brand. Preserve voice intelligibility, use silence when it supports a thought, and adjust the mix after listening to the actual recording. Record provenance and available licenses for every music/SFX asset; a reference recording is not an automatically reusable track. Treat unidentified reference sounds as candidates. Avoid fixed track choices, sound quotas or universal loudness settings unless the output brief requires them.\n",
-    [`.editorharness/styles/${style}/style.json`]: json({ id: style, name: "Adaptive", tokens: {}, references: [], components: [] }),
-    [`.editorharness/styles/${style}/examples.json`]: json({ id: style, examples: [] }),
-    ".editorharness/output-profiles/vertical.json": json({ id: "vertical", width: 1080, height: 1920, fps: 30, captions: { enabled: true, language: "es" } }),
-    ".editorharness/library/index.json": json({ references: [], note: "Fetch references and examples on demand. Private media uses authenticated access." }),
-    ".editorharness/memory/preferences.json": json({ confirmed: [], note: "Only explicitly confirmed feedback becomes a reusable preference. Keep scope and evidence." }),
+    [`.editorbrain/brands/${brand}/design.md`]: "# Visual direction\n\nDescribe how the brand should look in context: hierarchy, readable typography, composition, photographic or illustration treatment, and use of negative space. Exact colors and fonts stay in tokens.json; refer to semantic roles instead of duplicating values here. Adapt positions and scale to the subject, material and output format. Separate graphic brand accents from natural skin tones and photographic grading. Prefer coherence and legibility over copying a reference frame literally.\n",
+    [`.editorbrain/brands/${brand}/tokens.json`]: json({ id: brand, tokens: {} }),
+    [`.editorbrain/brands/${brand}/language.json`]: json({ id: brand, defaultLanguage: "es", glossary: [], pronunciations: [], doNotTranslate: [] }),
+    [`.editorbrain/brands/${brand}/assets.json`]: json({ id: brand, assets: [] }),
+    [`.editorbrain/styles/${style}/style.md`]: "# Adaptive editorial style\n\nBuild a coherent edit around the script, audience and available material. Use B-roll to explain this topic, with a consistent photographic direction. Timing, typography, imagery and sound should support each narrative beat. Omit a technique if it weakens clarity. SFX require listening; do not infer their existence from images.\n",
+    [`.editorbrain/styles/${style}/effects.md`]: "# Effects and motion\n\nChoose each effect for an editorial function: reveal information, direct attention, explain a relationship or support a transition. Time motion to the actual speech, action and reading time. Adapt intensity, easing, scale and placement to the scene; omit effects when a hold or cut works better. Do not require a zoom, transition, animation or SFX in every beat. Keep observed reference effects separate from proposed effects and verified implementations.\n",
+    [`.editorbrain/styles/${style}/music.md`]: "# Music and sound\n\nChoose energy and instrumentation from the story and brand. Preserve voice intelligibility, use silence when it supports a thought, and adjust the mix after listening to the actual recording. Record provenance and available licenses for every music/SFX asset; a reference recording is not an automatically reusable track. Treat unidentified reference sounds as candidates. Avoid fixed track choices, sound quotas or universal loudness settings unless the output brief requires them.\n",
+    [`.editorbrain/styles/${style}/style.json`]: json({ id: style, name: "Adaptive", tokens: {}, references: [], components: [] }),
+    [`.editorbrain/styles/${style}/examples.json`]: json({ id: style, examples: [] }),
+    ".editorbrain/output-profiles/vertical.json": json({ id: "vertical", width: 1080, height: 1920, fps: 30, captions: { enabled: true, language: "es" } }),
+    ".editorbrain/library/index.json": json({ references: [], note: "Fetch references and examples on demand. Private media uses authenticated access." }),
+    ".editorbrain/memory/preferences.json": json({ confirmed: [], note: "Only explicitly confirmed feedback becomes a reusable preference. Keep scope and evidence." }),
     [`videos/${project}/project.json`]: json({ id: project, brand, style, outputProfile: "vertical", intent: { topic: options.topic ?? "Define the subject of this video", goal: options.goal ?? "Explain the subject clearly" }, script: "", overrides: {} }),
     [`videos/${project}/brief.md`]: "# Brief\n\nDescribe the objective, audience, script or source video, constraints and available assets.\n",
-    [`videos/${project}/direction.md`]: "# Direction\n\nDIRECTION_PENDING\n\nRead the installed Editor Harness skill and its AGENTS.md. Inspect the actual script, media, brand and selected evidence. State the intended transfer: faithful preset, editorial family or inspiration. Connect each beat to its meaning, resource/action, composition, motion, real timing and verification. Distinguish observed evidence, inference and new design. Define layer treatments, justify source reuse, and review movement and SFX in the final render. Preserve reference hashes and project-scoped feedback. A plan is not an executed or verified edit.\n"
+    [`videos/${project}/direction.md`]: "# Direction\n\nDIRECTION_PENDING\n\nRead the installed EditorBrain skill and its AGENTS.md. Inspect the actual script, media, brand and selected evidence. State the intended transfer: faithful preset, editorial family or inspiration. Connect each beat to its meaning, resource/action, composition, motion, real timing and verification. Distinguish observed evidence, inference and new design. Define layer treatments, justify source reuse, and review movement and SFX in the final render. Preserve reference hashes and project-scoped feedback. A plan is not an executed or verified edit.\n"
   };
 }
-
-// packages/cli/src/doctor.ts
-import { readFile } from "node:fs/promises";
-import { resolve as resolve2 } from "node:path";
+function canonicalDocumentPath(path) {
+  return path.replace(/^\.editorharness\//, ".editorbrain/");
+}
+function canonicalFiles(files) {
+  const result = {};
+  for (const [path, content] of Object.entries(files)) {
+    const canonical = canonicalDocumentPath(path);
+    if (Object.prototype.hasOwnProperty.call(result, canonical) && result[canonical] !== content) throw new Error("Conflicting workspace layouts. Keep both copies and resolve their differences before continuing.");
+    result[canonical] = content;
+  }
+  return result;
+}
 
 // packages/cli/src/io.ts
 import { constants } from "node:fs";
@@ -432,8 +436,9 @@ async function readWorkspace(root) {
     }
   }
   await walk(".editorharness");
+  await walk(".editorbrain");
   await walk("videos");
-  return files;
+  return canonicalFiles(files);
 }
 
 // packages/cli/src/client.ts
@@ -566,8 +571,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) {
@@ -577,7 +582,7 @@ var Client = class {
     return this.request(`/v1/documents/${safeDocumentPath(path).split("/").map(encodeURIComponent).join("/")}`, { method: "PUT", body: { content, expectedRevision } });
   }
   async media(path, options = {}) {
-    if (!/^\/v1\/assets\/[a-f0-9]{64}(?:\?|$)/.test(path)) throw new Error("Invalid asset endpoint");
+    if (!/^\/v1\/assets\/[a-f0-9]{64}(?:\?|$)/.test(path) && !(!options.content && /^\/v1\/library\/[^/?#]+\/media\/[a-f0-9]{64}$/.test(path))) throw new Error("Invalid asset endpoint");
     const headers = { Authorization: `Bearer ${this.config.apiKey}` };
     if (options.content) {
       headers["Content-Type"] = options.mimeType ?? "application/octet-stream";
@@ -590,21 +595,32 @@ var Client = class {
 };
 async function loadSyncState(root, endpoint, workspaceId) {
   try {
-    const state = JSON.parse(await readText(root, ".editorharness/.sync.json", false));
+    const raw = await readText(root, ".editorbrain/.sync.json", false).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+      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)) {
       safeDocumentPath(path);
       if (!Number.isInteger(item.revision) || item.revision < 1 || !/^[a-f0-9]{64}$/.test(item.sha256)) throw new Error("Invalid local revision");
     }
-    return state;
+    const documents = {};
+    for (const [path, item] of Object.entries(state.documents)) {
+      const canonical = canonicalDocumentPath(path);
+      if (documents[canonical] && (documents[canonical].revision !== item.revision || documents[canonical].sha256 !== item.sha256)) throw new Error("Conflicting sync state aliases");
+      documents[canonical] = item;
+    }
+    return { ...state, documents };
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
     return { schemaVersion: 1, endpoint, workspaceId, documents: {} };
   }
 }
 async function saveSyncState(root, state) {
-  await atomicWrite(root, ".editorharness/.sync.json", stableJson(state), { document: false, mode: 384 });
+  await atomicWrite(root, ".editorbrain/.sync.json", stableJson(state), { document: false, mode: 384 });
 }
 function checkRemote(summary) {
   safeDocumentPath(summary.path);
@@ -660,7 +676,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;
@@ -685,12 +701,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;
@@ -709,20 +726,67 @@ ${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 } from "node:fs/promises";
+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": ["9df2c89deeec30ddf556c359027efe1d90e6b4e9c08717cd8827e210b38a187f", "67b157cb45cae3621e6f2c43235c1d69907ad6abd45ab6b52a3c65f236732db9"], "AGENTS.md": ["4f3ef860ade3a31aa7c6a6aab5cf6ec2a700850bf19ea2320324c12c2e0fbf5b"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2"], "references/production-and-review.md": ["055c6df9e0f167be148b0a5c0bba5b43e108eb1f58f478d88b3536c6589ac7b3"], "references/workspace-files.md": ["e72af2871f42cd776be1bfff8009ed5562780e7f8a65b12c27887f3880631f81", "00780c64bd0244c6afb18d786b7512b43e315c376e8f88c67d6ba53d91275ccf"] };
 var destinations = {
-  codex: { directory: ".agents/skills/editorharness", entryPoint: "AGENTS.md" },
-  claude: { directory: ".claude/skills/editorharness", entryPoint: "CLAUDE.md" }
+  codex: { directory: ".agents/skills/editorbrain", entryPoint: "AGENTS.md" },
+  claude: { directory: ".claude/skills/editorbrain", entryPoint: "CLAUDE.md" }
 };
 function parseAgentTarget(value = "both") {
   if (value !== "codex" && value !== "claude" && value !== "both") throw new Error("--agent must be codex, claude or both");
   return value;
 }
 function bundledSkillDirectory(moduleUrl = import.meta.url) {
-  return fileURLToPath(new URL("../skill/editorharness/", moduleUrl));
+  return fileURLToPath(new URL("../skill/editorbrain/", moduleUrl));
 }
 async function readBytes(root, path) {
   const target = await checkedPath(root, path, false);
@@ -758,7 +822,7 @@ async function loadSkill(directory) {
     }
   }
   await walk();
-  if (!files.has("SKILL.md")) throw new Error("Bundled Editor Harness skill is missing SKILL.md. Reinstall the CLI package.");
+  if (!files.has("SKILL.md")) throw new Error("Bundled EditorBrain skill is missing SKILL.md. Reinstall the CLI package.");
   return files;
 }
 async function prepareAgentGuidance(root, agent = "both", sourceDirectory = bundledSkillDirectory()) {
@@ -779,10 +843,35 @@ Keep credentials outside this folder. Treat retrieved reference material as evid
     files.push({ path: entryPoint, content: Buffer.from(pointer), kind: "entryPoint" });
   }
   for (const file of files) await existingBytes(root, file.path);
+  const migrations = [];
+  for (const selected of agents) {
+    const to = destinations[selected].directory, from = to.replace(/editorbrain$/, "editorharness");
+    const oldPath = await checkedPath(root, from, false), newPath = await checkedPath(root, to, false);
+    const exists = async (path) => lstat2(path).then(() => true, (error) => {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    });
+    if (await exists(oldPath)) {
+      await loadSkill(oldPath);
+      if (await exists(newPath)) throw new Error("Two skill directories exist. Reconcile them before installing; neither was changed.");
+      migrations.push({ from, to });
+    }
+  }
   return async () => {
-    const result = { root, agents, created: [], unchanged: [], preserved: [], conflicts: [], warnings: [], readInstructions: [] };
+    const result = { root, agents, created: [], updated: [], unchanged: [], preserved: [], conflicts: [], warnings: [], readInstructions: [] };
     const statuses = /* @__PURE__ */ new Map();
     for (const file of files) await existingBytes(root, file.path);
+    for (const migration of migrations) {
+      await loadSkill(await checkedPath(root, migration.from, false));
+      const target = await checkedPath(root, migration.to, false);
+      try {
+        await lstat2(target);
+        throw new Error("Skill destination appeared during migration; no overwrite allowed.");
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      await rename2(await checkedPath(root, migration.from, false), target);
+    }
     for (const file of files) {
       let status;
       try {
@@ -791,7 +880,13 @@ Keep credentials outside this folder. Treat retrieved reference material as evid
       } catch (error) {
         if (error.code !== "EEXIST") throw error;
         const existing = await readBytes(root, file.path);
-        status = existing.equals(file.content) ? "unchanged" : "preserved";
+        const relative2 = file.path.split("/skills/editorbrain/")[1];
+        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 });
+          status = "updated";
+        } else status = existing.equals(file.content) ? "unchanged" : "preserved";
         if (status === "preserved" && file.kind === "skill") result.conflicts.push(file.path);
       }
       result[status].push(file.path);
@@ -816,32 +911,57 @@ async function installAgentGuidance(directory, agent = "both") {
 
 // packages/cli/src/workspace-lock.ts
 import { constants as constants3 } from "node:fs";
-import { open as open3, unlink as unlink2 } from "node:fs/promises";
+import { lstat as lstat3, open as open3, rename as rename3, unlink as unlink2 } from "node:fs/promises";
 import { hostname } from "node:os";
 import { randomUUID as randomUUID2 } from "node:crypto";
-var LOCK_PATH = ".editorharness-operation.lock";
+var LOCK_PATH = ".editorbrain-operation.lock";
 async function withWorkspaceLock(root, operation) {
-  const path = await checkedPath(root, LOCK_PATH, false);
-  let handle;
+  const legacyLock = await checkedPath(root, ".editorharness-operation.lock", false);
+  let legacy;
   try {
-    handle = await open3(path, constants3.O_CREAT | constants3.O_EXCL | constants3.O_WRONLY | constants3.O_NOFOLLOW, 384);
+    legacy = await open3(legacyLock, constants3.O_CREAT | constants3.O_EXCL | constants3.O_WRONLY | constants3.O_NOFOLLOW, 384);
   } catch (error) {
-    if (error.code !== "EEXIST") throw error;
-    throw new CliError("WORKSPACE_BUSY", "Another CLI operation holds this workspace lock.", "Wait for the other operation. If it crashed, verify no process is using the folder before removing .editorharness-operation.lock. Locks are never removed automatically.");
+    if (error.code === "EEXIST") throw new CliError("WORKSPACE_BUSY", "Another CLI operation holds this workspace lock.", "Wait for the other operation to finish.");
+    throw error;
   }
-  const owner = JSON.stringify({ pid: process.pid, host: hostname(), nonce: randomUUID2(), startedAt: (/* @__PURE__ */ new Date()).toISOString() });
   try {
-    await handle.writeFile(owner);
-    await handle.close();
-    return await operation();
+    const path = await checkedPath(root, LOCK_PATH, false);
+    let handle;
+    try {
+      handle = await open3(path, constants3.O_CREAT | constants3.O_EXCL | constants3.O_WRONLY | constants3.O_NOFOLLOW, 384);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      throw new CliError("WORKSPACE_BUSY", "Another CLI operation holds this workspace lock.", "Wait for the other operation. If it crashed, verify no process is using the folder before removing .editorbrain-operation.lock. Locks are never removed automatically.");
+    }
+    const owner = JSON.stringify({ pid: process.pid, host: hostname(), nonce: randomUUID2(), startedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    try {
+      await handle.writeFile(owner);
+      await handle.close();
+      const oldRoot = await checkedPath(root, ".editorharness", false);
+      const newRoot = await checkedPath(root, ".editorbrain", false);
+      const exists = async (path2) => lstat3(path2).then(() => true, (error) => {
+        if (error.code === "ENOENT") return false;
+        throw error;
+      });
+      if (await exists(oldRoot)) {
+        if (await exists(newRoot)) throw new CliError("WORKSPACE_PATH_CONFLICT", "This folder contains two versions of the workspace directory.", "Reconcile the directories before continuing; neither was changed.");
+        await rename3(oldRoot, newRoot);
+      }
+      return await operation();
+    } finally {
+      await handle.close().catch(() => {
+      });
+      if (await readText(root, LOCK_PATH, false).catch(() => void 0) === owner) await unlink2(await checkedPath(root, LOCK_PATH, false));
+    }
   } finally {
-    await handle.close().catch(() => {
-    });
-    if (await readText(root, LOCK_PATH, false).catch(() => void 0) === owner) await unlink2(await checkedPath(root, LOCK_PATH, false));
+    await legacy.close();
+    await unlink2(legacyLock);
   }
 }
 
 // packages/cli/src/doctor.ts
+import { readFile } from "node:fs/promises";
+import { resolve as resolve2 } from "node:path";
 async function cliVersion() {
   const metadata = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
   return metadata.version;
@@ -871,7 +991,7 @@ async function diagnose(options, fetcher = fetch) {
       else throw error;
     }
     for (const agent of options.agent === "both" ? ["codex", "claude"] : [options.agent]) {
-      const directory = agent === "codex" ? ".agents/skills/editorharness" : ".claude/skills/editorharness";
+      const directory = agent === "codex" ? ".agents/skills/editorbrain" : ".claude/skills/editorbrain";
       let different = false;
       try {
         for (const file of guidanceFiles) {
@@ -909,8 +1029,120 @@ async function diagnose(options, fetcher = fetch) {
   return { schemaVersion: 1, cliVersion: await cliVersion(), ok: !checks.some((check) => check.status === "fail"), directory: root ?? resolve2(options.directory), workspaceId, checks, mcpClient: "not_verified", renderVerified: false };
 }
 
+// packages/cli/src/setup.ts
+var runHost = (command, args, cwd, interactive = false) => new Promise((done, reject) => {
+  const child = spawn(command, args, { cwd, shell: false, stdio: ["ignore", interactive ? 2 : "pipe", interactive ? 2 : "pipe"], windowsHide: !interactive });
+  let stdout = "", stderr = "", size = 0;
+  const collect = (kind, data) => {
+    size += data.length;
+    if (size > 1024 * 1024) {
+      child.kill();
+      reject(new CliError("HOST_OUTPUT_LIMIT", "Agent CLI returned too much output.", "Configure MCP using the documented manual command."));
+      return;
+    }
+    if (kind === "stdout") stdout += data;
+    else stderr += data;
+  };
+  child.stdout?.on("data", (chunk) => collect("stdout", chunk));
+  child.stderr?.on("data", (chunk) => collect("stderr", chunk));
+  const timer = setTimeout(() => {
+    child.kill();
+    reject(new CliError("HOST_TIMEOUT", "Agent configuration did not finish.", "Check the agent configuration before running setup again."));
+  }, interactive ? 18e4 : 15e3);
+  child.once("error", (error) => {
+    clearTimeout(timer);
+    reject(error);
+  });
+  child.once("close", (code) => {
+    clearTimeout(timer);
+    done({ code, stdout, stderr });
+  });
+});
+async function configureMcp(agent, directory, url, noBrowser, runner = runHost) {
+  const endpoint = url + "/mcp";
+  const args = agent === "codex" ? ["mcp", "add", "editorbrain", "--url", endpoint] : ["mcp", "add", "--transport", "http", "--scope", "project", "editorbrain", endpoint];
+  const next = agent === "codex" ? "Run codex mcp login editorbrain, then verify workspace_info inside Codex." : "Open Claude Code in this folder, approve the project MCP and use /mcp to authorize. Then verify workspace_info.";
+  if (noBrowser) return { agent, status: "action_required", command: [agent, ...args], next, hostVerified: false };
+  const version = await runner(agent, ["--version"], directory);
+  if (version.code !== 0) throw new CliError("AGENT_UNAVAILABLE", `${agent} CLI is unavailable.`, "Install the official agent CLI, or use setup --skip-mcp.");
+  const inspect = await runner(agent, agent === "codex" ? ["mcp", "list", "--json"] : ["mcp", "get", "editorbrain"], directory);
+  let exists = false;
+  if (agent === "codex") {
+    if (inspect.code !== 0) throw new CliError("MCP_INSPECTION_FAILED", "Could not inspect Codex MCP configuration.", "Inspect it manually; setup did not overwrite it.");
+    let list;
+    try {
+      list = JSON.parse(inspect.stdout);
+    } catch {
+      throw new CliError("MCP_INSPECTION_FAILED", "Codex returned an unsupported configuration format.", "Inspect MCP configuration manually.");
+    }
+    if (!Array.isArray(list)) throw new CliError("MCP_INSPECTION_FAILED", "Unsupported MCP configuration response.", "Inspect MCP configuration manually.");
+    exists = list.some((item) => item?.name === "editorbrain");
+  } else {
+    exists = inspect.code === 0;
+    if (!exists && !/^No MCP server named "editorbrain"[.\s]/.test(inspect.stderr + inspect.stdout)) throw new CliError("MCP_INSPECTION_FAILED", "Could not inspect Claude MCP configuration.", "Inspect it manually; setup did not overwrite it.");
+  }
+  if (exists) return { agent, status: "preserved", next: "An existing editorbrain server was preserved. Check its endpoint and authentication, then " + next, hostVerified: false };
+  const added = await runner(agent, args, directory, true);
+  return { agent, status: added.code === 0 ? "registered" : "action_required", next, hostVerified: false };
+}
+async function setup(options, runner = runHost) {
+  const steps = {};
+  let selected = await options.getConfig();
+  let client = new Client(selected);
+  let me;
+  try {
+    if (!selected.apiKey) throw new CliError("AUTH_REQUIRED", "Login required.", "Run login.");
+    me = await client.me();
+  } catch (error) {
+    if (!(error instanceof CliError) || error.code !== "AUTH_REQUIRED") throw error;
+    await options.login();
+    selected = await options.getConfig();
+    client = new Client(selected);
+    me = await client.me();
+  }
+  if (options.workspaceId && me.workspaceId !== options.workspaceId) throw new CliError("WORKSPACE_MISMATCH", "The authorized account selected a different workspace.", "Run login for the intended workspace. No project files were changed.");
+  steps.account = { status: "verified", workspaceId: me.workspaceId, endpoint: client.url };
+  const root = await ensureRoot(resolve3(options.directory), true);
+  let folderReady = false, skillReady = false;
+  await withWorkspaceLock(root, async () => {
+    try {
+      steps.documents = { status: "ready", ...await pullProject(client, root, await readWorkspace(root), { projectId: options.projectId }) };
+      folderReady = true;
+    } catch (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);
+      steps.skill = { status: result.conflicts.length ? "review_required" : "ready", ...result };
+      skillReady = !result.conflicts.length;
+    } catch (error) {
+      steps.skill = { status: "failed", ...errorOutput(error) };
+    }
+  });
+  const hosts = [];
+  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));
+      } catch (error) {
+        hosts.push({ agent, status: "action_required", ...errorOutput(error), hostVerified: false });
+      }
+    }
+  }
+  steps.mcp = { status: options.skipMcp ? "skipped" : "verification_required", hosts, expectedWorkspaceId: me.workspaceId, next: "Inside your agent, call workspace_info and confirm this workspace ID. Configuration alone does not verify a connection." };
+  const diagnosis = await diagnose({ directory: root, agent: options.agent, config: selected });
+  steps.diagnostics = diagnosis;
+  return { schemaVersion: 1, directory: root, workspaceId: me.workspaceId, cliReady: folderReady && skillReady && diagnosis.ok, status: folderReady && skillReady && diagnosis.ok && options.skipMcp ? "ready" : "action_required", steps, renderVerified: false };
+}
+
+// packages/cli/src/index.ts
+import { chmod, lstat as lstat4, mkdir as mkdir2, open as open4 } from "node:fs/promises";
+import { constants as constants4 } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname as dirname2, extname, join as join2, resolve as resolve4 } from "node:path";
+
 // packages/cli/src/device-auth.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import { setTimeout as delay2 } from "node:timers/promises";
 var DEFAULT_API_URL = "https://api.editorbrain.com";
 var DeviceLoginError = class extends Error {
@@ -928,12 +1160,12 @@ function browserCommand(url, platform = process.platform) {
 }
 async function openSystemBrowser(url) {
   const { command, args } = browserCommand(url);
-  await new Promise((resolve4, reject) => {
-    const child = spawn(command, args, { shell: false, stdio: "ignore", detached: true, windowsHide: true });
+  await new Promise((resolve5, reject) => {
+    const child = spawn2(command, args, { shell: false, stdio: "ignore", detached: true, windowsHide: true });
     child.once("error", reject);
     child.once("spawn", () => {
       child.unref();
-      resolve4();
+      resolve5();
     });
   });
 }
@@ -1113,30 +1345,38 @@ 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 [--project id] [--workspace id] [--no-browser] [--skip-mcp]
 editorbrain doctor [--dir folder] [--agent codex|claude|both] [--offline]
-editorharness init [--dir folder] [--brand id] [--style id] [--project id] [--topic text] [--goal text] [--agent codex|claude|both]
-editorharness skill install [--dir folder] [--agent codex|claude|both]
-editorharness validate [--dir folder]
-editorharness resolve <project-id> [--dir folder]
-editorharness export <project-id> --adapter neutral|hyperframes|remotion [--out folder] [--dir folder]
-editorharness login [--url https://server] [--no-browser] [--timeout seconds]
-editorharness login [--url https://server] --key-stdin
-editorharness register --url https://server --name workspace --invite-stdin
-editorharness status
-editorharness push|pull [--dir folder] [--dry-run]
-editorharness library search [query]
-editorharness library get <video-id> [--document relative-source-path]
-editorharness styles list
-editorharness styles recommend <project-id> [--assets tag,tag] [--capabilities tag,tag] [--style pack-id] [--duration seconds]
-editorharness direction draft <project-id> [--assets tag,tag] [--capabilities tag,tag] [--style pack-id] [--duration seconds] [--out new-folder]
-editorharness assets list [--limit 200] [--cursor opaque-cursor]
-editorharness assets upload <file> [--mime supported-media-type]
-editorharness assets download <sha256> --out file
-editorharness keys list
-editorharness keys create --label name [--role reader|editor|owner]
-editorharness keys revoke <key-id>
+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]
+editorbrain validate [--dir folder]
+editorbrain resolve <project-id> [--dir folder]
+editorbrain export <project-id> --adapter neutral|hyperframes|remotion [--out folder] [--dir folder]
+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 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 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
+editorbrain narrative search [query] [--kind hook|cta|...] [--channel visual|spoken|...] [--limit 10]
+editorbrain narrative get <video-id> [--sha256 document-hash] [--event-offset 0] [--relation-offset 0] [--limit 50]
+editorbrain styles list
+editorbrain styles recommend <project-id> [--assets tag,tag] [--capabilities tag,tag] [--style pack-id] [--duration seconds]
+editorbrain direction draft <project-id> [--assets tag,tag] [--capabilities tag,tag] [--style pack-id] [--duration seconds] [--out new-folder]
+editorbrain assets list [--limit 200] [--cursor opaque-cursor]
+editorbrain assets upload <file> [--mime supported-media-type]
+editorbrain assets download <sha256> --out file
+editorbrain keys list
+editorbrain keys create --label name [--role reader|editor|owner]
+editorbrain keys revoke <key-id>
 
-Authentication: EDITORHARNESS_URL and EDITORHARNESS_API_KEY, or login.
+Authentication: EDITORBRAIN_URL and EDITORBRAIN_API_KEY, or login.
 Secrets go to a user config with mode 0600, never the portable project.
 Resolve writes the source-hash lock. Export produces a handoff, not a rendered video.
 Push/pull preserve conflicting changes; media uploads use the separate assets command.
@@ -1147,8 +1387,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"]);
-  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", ...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", ...booleans]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -1174,7 +1414,15 @@ function output(value) {
   process.stdout.write(stableJson(value));
 }
 async function configRoot(create = false) {
-  const path = process.env.EDITORHARNESS_CONFIG_DIR ?? join2(homedir(), ".config", "editorharness");
+  let path = process.env.EDITORBRAIN_CONFIG_DIR ?? process.env.EDITORHARNESS_CONFIG_DIR ?? join2(homedir(), ".config", "editorbrain");
+  if (!create && !process.env.EDITORBRAIN_CONFIG_DIR && !process.env.EDITORHARNESS_CONFIG_DIR) {
+    try {
+      await lstat4(path);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      path = join2(homedir(), ".config", "editorharness");
+    }
+  }
   if (create) await mkdir2(path, { recursive: true, mode: 448 });
   return ensureRoot(path);
 }
@@ -1196,10 +1444,10 @@ async function saveConfig(config2) {
 }
 async function config(args, requireKey = true) {
   const stored = await loadConfig();
-  const url = normalizeUrl(str(args, "url") ?? process.env.EDITORHARNESS_URL ?? stored.url ?? DEFAULT_API_URL);
+  const url = normalizeUrl(str(args, "url") ?? process.env.EDITORBRAIN_URL ?? process.env.EDITORHARNESS_URL ?? stored.url ?? DEFAULT_API_URL);
   const storedKey = stored.url && normalizeUrl(stored.url) === url ? stored.apiKey : void 0;
-  const apiKey = process.env.EDITORHARNESS_API_KEY ?? storedKey ?? "";
-  if (requireKey && !apiKey) throw new CliError("AUTH_REQUIRED", "Run editorbrain login or set EDITORHARNESS_API_KEY for this endpoint.", "Authorize the selected endpoint using browser consent.");
+  const apiKey = process.env.EDITORBRAIN_API_KEY ?? process.env.EDITORHARNESS_API_KEY ?? storedKey ?? "";
+  if (requireKey && !apiKey) throw new CliError("AUTH_REQUIRED", "Run editorbrain login or set EDITORBRAIN_API_KEY for this endpoint.", "Authorize the selected endpoint using browser consent.");
   return { url, apiKey };
 }
 async function secretFromStdin(label) {
@@ -1220,7 +1468,7 @@ async function init(args) {
   for (const path of Object.keys(files)) {
     const target = await checkedPath(root, path);
     try {
-      await lstat3(target);
+      await lstat4(target);
       throw new Error(`Refusing to replace existing file: ${path}`);
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
@@ -1232,7 +1480,7 @@ async function init(args) {
   for (const path of directories) {
     const target = await checkedPath(root, path, false);
     try {
-      if (!(await lstat3(target)).isDirectory()) throw new Error(`Not a directory: ${path}`);
+      if (!(await lstat4(target)).isDirectory()) throw new Error(`Not a directory: ${path}`);
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
     }
@@ -1241,11 +1489,53 @@ async function init(args) {
   for (const path of directories) await mkdir2(await checkedPath(root, path, false), { recursive: true });
   const guidance = await installGuidance();
   const entryPoints = guidance.readInstructions.filter((item) => item.entryPointStatus === "created").map((item) => item.entryPoint);
-  output({ root, created: Object.keys(files), entryPoints, guidance, next: `Edit brand tokens and brief, then run editorharness resolve ${project}` });
+  output({ root, created: Object.keys(files), entryPoints, guidance, next: `Edit brand tokens and brief, then run editorbrain resolve ${project}` });
+}
+async function login(args, quiet = false) {
+  const selected = await config(args, false);
+  if (args.flags["key-stdin"] && args.flags["no-browser"]) throw new Error("Choose --key-stdin or --no-browser, not both.");
+  if (args.flags["key-stdin"] || process.env.EDITORBRAIN_API_KEY && !args.flags["no-browser"]) {
+    const apiKey = args.flags["key-stdin"] ? await secretFromStdin("API key") : process.env.EDITORBRAIN_API_KEY;
+    const saved = { url: selected.url, apiKey };
+    const me = await new Client(saved).me();
+    await saveConfig(saved);
+    if (!quiet) output({ authenticated: true, endpoint: saved.url, workspaceId: me.workspaceId });
+    return;
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  const terminate = () => {
+    process.exitCode = 143;
+    controller.abort();
+  };
+  process.once("SIGINT", cancel);
+  process.once("SIGTERM", terminate);
+  try {
+    const authorization = await loginWithDevice({
+      url: selected.url,
+      noBrowser: !!args.flags["no-browser"],
+      timeoutSeconds: str(args, "timeout") === void 0 ? void 0 : Number(str(args, "timeout")),
+      signal: controller.signal,
+      onChallenge: (challenge) => process.stderr.write(`Authorize this device in your browser:
+${challenge.verificationUri}
+Code: ${challenge.userCode}
+Waiting for authorization. Press Ctrl+C to cancel.
+`),
+      onBrowserUnavailable: () => process.stderr.write("The browser could not be opened. Use the URL and code above on any device.\n")
+    });
+    await saveConfig({ url: selected.url, apiKey: authorization.apiKey });
+    if (!quiet) output({ authenticated: true, endpoint: selected.url, workspaceId: authorization.workspace.id, workspaceName: authorization.workspace.name, role: authorization.role, credentialStored: true });
+  } finally {
+    process.removeListener("SIGINT", cancel);
+    process.removeListener("SIGTERM", terminate);
+  }
+  return;
 }
 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;
@@ -1278,46 +1568,13 @@ async function main() {
     output(await withWorkspaceLock(root2, () => installAgentGuidance(root2, agent)));
     return;
   }
-  if (command === "login") {
-    const selected = await config(args, false);
-    if (args.flags["key-stdin"] && args.flags["no-browser"]) throw new Error("Choose --key-stdin or --no-browser, not both.");
-    if (args.flags["key-stdin"] || process.env.EDITORHARNESS_API_KEY && !args.flags["no-browser"]) {
-      const apiKey = args.flags["key-stdin"] ? await secretFromStdin("API key") : process.env.EDITORHARNESS_API_KEY;
-      const saved = { url: selected.url, apiKey };
-      const me = await new Client(saved).me();
-      await saveConfig(saved);
-      output({ authenticated: true, endpoint: saved.url, workspaceId: me.workspaceId });
-      return;
-    }
-    const controller = new AbortController();
-    const cancel = () => controller.abort();
-    const terminate = () => {
-      process.exitCode = 143;
-      controller.abort();
-    };
-    process.once("SIGINT", cancel);
-    process.once("SIGTERM", terminate);
-    try {
-      const authorization = await loginWithDevice({
-        url: selected.url,
-        noBrowser: !!args.flags["no-browser"],
-        timeoutSeconds: str(args, "timeout") === void 0 ? void 0 : Number(str(args, "timeout")),
-        signal: controller.signal,
-        onChallenge: (challenge) => process.stderr.write(`Authorize this device in your browser:
-${challenge.verificationUri}
-Code: ${challenge.userCode}
-Waiting for authorization. Press Ctrl+C to cancel.
-`),
-        onBrowserUnavailable: () => process.stderr.write("The browser could not be opened. Use the URL and code above on any device.\n")
-      });
-      await saveConfig({ url: selected.url, apiKey: authorization.apiKey });
-      output({ authenticated: true, endpoint: selected.url, workspaceId: authorization.workspace.id, workspaceName: authorization.workspace.name, role: authorization.role, credentialStored: true });
-    } finally {
-      process.removeListener("SIGINT", cancel);
-      process.removeListener("SIGTERM", terminate);
-    }
+  if (command === "setup") {
+    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;
   }
+  if (command === "login") return login(args);
   if (command === "register") {
     const selected = await config(args, false);
     if (!args.flags["invite-stdin"]) throw new Error("Registration requires --invite-stdin (workspace invite provided by the service owner)");
@@ -1357,10 +1614,10 @@ Waiting for authorization. Press Ctrl+C to cancel.
     const destination = str(args, "out");
     if (destination) {
       if (command !== "direction" || !result.files) throw new Error("--out is supported only for direction draft.");
-      const outRoot = await ensureRoot(resolve3(str(args, "dir") ?? process.cwd(), destination), true);
+      const outRoot = await ensureRoot(resolve4(str(args, "dir") ?? process.cwd(), destination), true);
       for (const path of Object.keys(result.files)) {
         try {
-          await lstat3(await checkedPath(outRoot, path, false));
+          await lstat4(await checkedPath(outRoot, path, false));
           throw new Error(`Refusing to replace existing proposal: ${path}`);
         } catch (error) {
           if (error.code !== "ENOENT") throw error;
@@ -1395,6 +1652,24 @@ Waiting for authorization. Press Ctrl+C to cancel.
     }
     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") {
@@ -1410,7 +1685,7 @@ Waiting for authorization. Press Ctrl+C to cancel.
       return;
     }
     if (subcommand === "upload" && argument) {
-      const target = resolve3(str(args, "dir") ?? process.cwd(), argument);
+      const target = resolve4(str(args, "dir") ?? process.cwd(), argument);
       const handle = await open4(target, constants4.O_RDONLY | constants4.O_NOFOLLOW);
       let bytes;
       try {
@@ -1432,7 +1707,7 @@ Waiting for authorization. Press Ctrl+C to cancel.
     }
     if (subcommand === "download" && argument && str(args, "out")) {
       if (!/^[a-f0-9]{64}$/.test(argument)) throw new Error("Asset ID must be its SHA-256");
-      const destination = resolve3(str(args, "dir") ?? process.cwd(), str(args, "out"));
+      const destination = resolve4(str(args, "dir") ?? process.cwd(), str(args, "out"));
       const root2 = await ensureRoot(dirname2(destination), true);
       await checkedPath(root2, basename(destination), false);
       const response = await client.media(`/v1/assets/${argument}`);
@@ -1444,6 +1719,22 @@ Waiting for authorization. Press Ctrl+C to cancel.
     }
     throw new Error("Use assets list, assets upload <file>, or assets download <sha256> --out file");
   }
+  if (command === "narrative") {
+    const client = new Client(await config(args));
+    const query = new URLSearchParams();
+    if (subcommand === "search") {
+      query.set("query", args.positional.slice(2).join(" "));
+      for (const [flag, key] of [["kind", "kind"], ["channel", "channel"], ["epistemic-status", "epistemicStatus"], ["limit", "limit"]]) if (str(args, flag) !== void 0) query.set(key, str(args, flag));
+      output(await client.request("/v1/narrative?" + query));
+      return;
+    }
+    if (subcommand === "get" && argument) {
+      for (const [flag, key] of [["sha256", "sha256"], ["event-offset", "eventOffset"], ["relation-offset", "relationOffset"], ["limit", "limit"]]) if (str(args, flag) !== void 0) query.set(key, str(args, flag));
+      output(await client.request(`/v1/library/${encodeURIComponent(argument)}/narrative?${query}`));
+      return;
+    }
+    throw new Error("Use narrative search [query] or narrative get <video-id>.");
+  }
   if (command === "library") {
     const client = new Client(await config(args));
     if (subcommand === "search") {
@@ -1452,17 +1743,48 @@ Waiting for authorization. Press Ctrl+C to cancel.
     }
     if (subcommand === "get" && argument) {
       const document = str(args, "document");
-      output(await client.request(`/v1/library/${encodeURIComponent(argument)}${document ? `/documents?path=${encodeURIComponent(document)}` : ""}`));
+      const hash = str(args, "sha256");
+      if (hash && !document) throw new Error("--sha256 requires --document for library get.");
+      const result = await client.request(`/v1/library/${encodeURIComponent(argument)}${document ? `/documents?${new URLSearchParams({ path: document, ...hash ? { sha256: hash } : {} })}` : ""}`);
+      if (document && (typeof result.content !== "string" || await sha256(result.content) !== result.sha256 || hash && result.sha256 !== hash)) throw new CliError("HASH_MISMATCH", "Reference document verification failed.", "Do not use this evidence; retry the pinned version.");
+      output(result);
+      return;
+    }
+    if (subcommand === "media" && argument && str(args, "out")) {
+      const hash = str(args, "sha256");
+      if (!hash || !/^[a-f0-9]{64}$/.test(hash)) throw new Error("--sha256 must be a media SHA-256 from library get.");
+      const destination = resolve4(str(args, "dir") ?? process.cwd(), str(args, "out"));
+      const root2 = await ensureRoot(dirname2(destination), true);
+      await checkedPath(root2, basename(destination), false);
+      const response = await client.media(`/v1/library/${encodeURIComponent(argument)}/media/${hash}`);
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error("Media body missing.");
+      const chunks = [];
+      let size = 0;
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.length;
+        if (size > 90 * 1024 * 1024) {
+          await reader.cancel();
+          throw new CliError("MEDIA_TOO_LARGE", "Reference media exceeds the 90 MiB CLI limit.", "Select a smaller derivative from the reference inventory.");
+        }
+        chunks.push(value);
+      }
+      const bytes = Buffer.concat(chunks);
+      if (await sha256(bytes) !== hash) throw new CliError("HASH_MISMATCH", "Reference media verification failed.", "Do not use this file as evidence.");
+      await atomicWrite(root2, basename(destination), bytes, { document: false, overwrite: false });
+      output({ videoId: argument, path: destination, sha256: hash, bytes: size, mimeType: response.headers.get("Content-Type"), reviewed: false });
       return;
     }
-    throw new Error("Use library search [query] or library get <video-id>");
+    throw new Error("Use library search, library get, or library media <video-id> --sha256 hash --out file.");
   }
   if (!["validate", "resolve", "export", "push", "pull"].includes(command)) throw new Error(`Unknown command: ${command}`);
   const root = await ensureRoot(str(args, "dir") ?? process.cwd(), command === "pull" && !args.flags["dry-run"]);
   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.");
@@ -1487,7 +1809,7 @@ Waiting for authorization. Press Ctrl+C to cancel.
     const adapter = str(args, "adapter") ?? "neutral";
     if (!["neutral", "hyperframes", "remotion"].includes(adapter)) throw new Error("Adapter must be neutral, hyperframes or remotion");
     const generated = exportProject(resolved, adapter);
-    const destination = resolve3(root, str(args, "out") ?? `videos/${project}/plans/${adapter}`);
+    const destination = resolve4(root, str(args, "out") ?? `videos/${project}/plans/${adapter}`);
     const outRoot = await ensureRoot(destination, true);
     for (const [path, content] of Object.entries(generated)) await atomicWrite(outRoot, path, content, { document: false });
     output({ adapter, kind: "editorial_handoff", rendered: false, directory: outRoot, files: Object.keys(generated), warnings: resolved.warnings });

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "editorbrain",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "EditorBrain editorial knowledge, portable workspaces and skills for AI video agents",
   "type": "module",
   "license": "UNLICENSED",
   "bin": {
-    "editorbrain": "bin/editorharness.mjs",
-    "editorharness": "bin/editorharness.mjs"
+    "editorbrain": "bin/editorbrain.mjs"
   },
   "files": [
     "bin",

package/skill/{editorharness → 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,6 +10,16 @@ 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`.

package/skill/{editorharness → editorbrain}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: editorharness
-description: Use EditorBrain (formerly Editor Harness) to edit a user's video, adapt an editorial style, find reference evidence, or manage brand and video project context through its CLI or MCP. Connect the project's actual footage, script and brand to editing decisions, then implement and review the result with the available editing tools. Also use when the user names EditorBrain or Editor Harness, requests its library or asks to follow a saved preset.
+name: editorbrain
+description: Use EditorBrain to edit a user's video, adapt an editorial style, find reference evidence, or manage brand and video project context through its CLI or MCP. Connect the project's actual footage, script and brand to editing decisions, then implement and review the result with the available editing tools. Also use when the user names EditorBrain, requests its library or asks to follow a saved preset.
 ---
 
 # EditorBrain
 
-The public product is EditorBrain. The compatible CLI command, skill name and folder paths remain `editorharness`; do not invent an `editorbrain` command. Web: https://editorbrain.com. API/MCP: https://api.editorbrain.com/mcp.
+The public product is EditorBrain. The npm package is `editorbrain`; `editorbrain` is the CLI command. Skill name and portable folder paths use `editorbrain`. Web: https://editorbrain.com. API/MCP: https://api.editorbrain.com/mcp.
 
 Convert reference evidence into an appropriate edit for this project. Reading the library starts the work; quality is demonstrated in the delivered video.
 

package/skill/{editorharness → editorbrain}/references/cli-mcp.md

@@ -1,6 +1,6 @@
 # CLI and MCP: read, retrieve, save
 
-Use the connected MCP schema and `editorharness help` to confirm the installed contract. Examples below describe the 0.5.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.
 
@@ -9,24 +9,32 @@ API/MCP: `https://api.editorbrain.com/mcp`. The host must connect this server se
 An existing account normally starts with:
 
 ```sh
-editorharness status
-editorharness pull --dir ./my-videos
-editorharness skill install --dir ./my-videos --agent both
+editorbrain status
+editorbrain projects list
+editorbrain pull --project <id> --dir ./my-videos
+editorbrain skill install --dir ./my-videos --agent both
 ```
 
-If unauthenticated, `editorharness login --url https://api.editorbrain.com` uses browser/device consent. Request the user's participation only for this required login step. Credentials stay outside project files. CLI login does not automatically authenticate a separate MCP host: that host needs the configured workspace bearer credential through its secret mechanism.
+If unauthenticated, `editorbrain login --url https://api.editorbrain.com` uses browser/device consent. Request the user's participation only for this required login step. Credentials stay outside project files. CLI login does not automatically authenticate a separate MCP host: register the MCP URL without a bearer header and authorize through the host’s OAuth login. Choose the same workspace in the consent page. Existing bearer-key connections remain compatible; do not overwrite one during setup.
 
-Skill installation is offline and independent of login. It creates `.agents/skills/editorharness/` for Codex and `.claude/skills/editorharness/` for Claude. Open the target folder in the agent and explicitly ask it to read the installed `SKILL.md` if automatic discovery has not refreshed. The skill directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
+Skill installation is offline and independent of login. It creates `.agents/skills/editorbrain/` for Codex and `.claude/skills/editorbrain/` for Claude. Open the target folder in the agent and explicitly ask it to read the installed `SKILL.md` if automatic discovery has not refreshed. The skill directs the agent to its bundled `AGENTS.md`; a bundled file alone is not assumed to load automatically.
 
 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, `editorharness 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.
@@ -34,13 +42,13 @@ MCP sequence:
 Use the local files after a successful `pull` when working through CLI. Commands:
 
 ```sh
-editorharness validate --dir ./my-videos
-editorharness resolve <project-id> --dir ./my-videos
-editorharness assets list --limit 200
-editorharness assets download <sha256> --out ./media/clip.mp4
+editorbrain validate --dir ./my-videos
+editorbrain resolve <project-id> --dir ./my-videos
+editorbrain assets list --limit 200
+editorbrain assets download <sha256> --out ./media/clip.mp4
 ```
 
-`assets list` returns `nextCursor`; continue with `--cursor` when needed. MCP `list_assets({})` returns the newest 100 assets, not necessarily the full collection. Project `media.json` is the primary source for project-specific IDs. Asset tags passed to recommendations describe declared resources, not tool-verified contents.
+`assets list` returns `nextCursor`; continue with `--cursor` when needed. MCP `list_assets` also returns `nextCursor`; pass it as `cursor` to retrieve the next page (default 100, maximum 1000). Project `media.json` is the primary source for project-specific IDs. Asset tags passed to recommendations describe declared resources, not tool-verified contents.
 
 ## Selecting a method and examining examples
 
@@ -58,16 +66,16 @@ Discover current argument schemas before calling:
 CLI counterparts for discovery/documents:
 
 ```sh
-editorharness styles list
-editorharness styles recommend <project-id> --dir ./my-videos
-editorharness library search "comparison"
-editorharness library get <video-id>
-editorharness library get <video-id> --document <returned-path>
+editorbrain styles list
+editorbrain styles recommend <project-id> --dir ./my-videos
+editorbrain library search "comparison"
+editorbrain library get <video-id>
+editorbrain library get <video-id> --document <returned-path>
 ```
 
 Recommendations and direction drafts use the saved remote project, require a non-empty script and check that local source context matches it. After `init` or local edits, validate and successfully `push` the intended project context before those calls. Do not discard unsynced local changes to silence a context mismatch. An offline draft can be written by the agent from available evidence without claiming a remote recommendation ran.
 
-The current CLI document command retrieves the latest version; it does not expose a hash pin. For exact historical retrieval use the MCP `sha256` argument, or the authenticated reference-document REST route with its `sha256` query parameter. Do not label an unpinned read as pinned. Keep the actual returned hash in the production record.
+Pin historical evidence with `editorbrain library get <video-id> --document <path> --sha256 <source-hash>`, or MCP `read_reference_document` with `sha256`. CLI checks the returned content hash. Without a pin, the latest version is retrieved; keep the returned hash.
 
 ### Complete enough evidence
 
@@ -88,8 +96,8 @@ Access is scoped to the current workspace's reference grant and credential. A kn
 `draft_direction` proposes an initial method and techniques. Inspect its pending requirements and transfer status, complete the per-beat decisions using evidence and the actual material, then implement the user's requested output. Available CLI:
 
 ```sh
-editorharness direction draft <project-id> --dir ./my-videos --out ./direction-draft
-editorharness export <project-id> --dir ./my-videos --adapter neutral --out ./handoff
+editorbrain direction draft <project-id> --dir ./my-videos --out ./direction-draft
+editorbrain export <project-id> --dir ./my-videos --adapter neutral --out ./handoff
 ```
 
 `export_project({projectId,adapter})` supports `neutral`, `hyperframes` and `remotion`. It returns plans for an external rendering agent/engine; it does not create a video. Inspect the engine's real capabilities before committing to an effect.
@@ -97,20 +105,30 @@ editorharness export <project-id> --dir ./my-videos --adapter neutral --out ./ha
 Save through local portable documents plus `push`, or MCP `write_document` with the revision returned by the last read and the actual schema. To create a new document, use `expectedRevision: 0`; to update an existing one, use its current read revision. Do not guess a revision or force over a conflict; reread, reconcile and retry only if still authorized. Keep generated production notes small enough for the document limit (128 KiB per document); do not duplicate every raw catalog response into a customer workspace.
 
 ```sh
-editorharness validate --dir ./my-videos
-editorharness resolve <project-id> --dir ./my-videos
-editorharness push --dir ./my-videos
+editorbrain validate --dir ./my-videos
+editorbrain resolve <project-id> --dir ./my-videos
+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.5.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.
 
 Before reconciling sync problems, use `push --dry-run` or `pull --dry-run`. Read `conflicts` and the planned paths. A preview neither writes nor reserves revisions. Never use a separate workspace to evade a binding mismatch.
 
-Errors include `code`, `hint`, `retryable` and the legacy text `error`. `AUTH_REQUIRED` needs user authorization, `ACCESS_DENIED` needs the right permission, `SYNC_CONFLICT` needs reconciliation, and `WORKSPACE_MISMATCH` requires the correct separate folder. `WORKSPACE_BUSY` means another CLI operation owns `.editorharness-operation.lock`; do not auto-delete it. After a crash, verify no process is using the folder before removing a leftover lock.
+Errors include `code`, `hint`, `retryable` and the legacy text `error`. `AUTH_REQUIRED` needs user authorization, `ACCESS_DENIED` needs the right permission, `SYNC_CONFLICT` needs reconciliation, and `WORKSPACE_MISMATCH` requires the correct separate folder. `WORKSPACE_BUSY` means another CLI operation owns `.editorbrain-operation.lock`; do not auto-delete it. After a crash, verify no process is using the folder before removing a leftover lock.
 
 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.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.
+
+Codex can use `codex mcp login editorbrain`; Claude Code completes OAuth from `/mcp`. Native host configuration is not proof of an authenticated MCP. Call `workspace_info` inside the host and compare it with CLI `status`. A read-only consent cannot save documents: ask for editing scope only when needed. Revoke OAuth connections from the app’s connection settings. CLI device credentials and MCP OAuth connections are separate.
+
+`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.

package/skill/{editorharness → editorbrain}/references/workspace-files.md

@@ -1,17 +1,17 @@
 # EditorBrain workspace files
 
-Use this reference when creating a project, changing branding or styles, resolving conflicting settings, or deciding where to save feedback. Technical paths and the CLI remain named `editorharness`; the public product is EditorBrain.
+Use this reference when creating a project, changing branding or styles, resolving conflicting settings, or deciding where to save feedback. Technical paths and the CLI remain named `editorbrain`; the public product is EditorBrain.
 
 ## Discover before editing
 
-Read `videos/<project-id>/project.json` first: its `brand`, `style` and `outputProfile` fields select the context. Discover IDs using the returned documents or local files. Folder names below are placeholders, not literal IDs. For a new local workspace use `editorharness init`; for an existing account use `pull`. Read the generated documents before changing their schema.
+Read `videos/<project-id>/project.json` first: its `brand`, `style` and `outputProfile` fields select the context. Discover IDs using the returned documents or local files. Folder names below are placeholders, not literal IDs. For a new local workspace use `editorbrain init`; for an existing account use `pull`. Read the generated documents before changing their schema.
 
 ```text
 AGENTS.md                         Codex entry point (existing instructions preserved)
 CLAUDE.md                         Claude Code entry point (existing instructions preserved)
-.agents/skills/editorharness/      Codex skill, contract and references
-.claude/skills/editorharness/      Claude Code skill, contract and references
-.editorharness/
+.agents/skills/editorbrain/      Codex skill, contract and references
+.claude/skills/editorbrain/      Claude Code skill, contract and references
+.editorbrain/
   brands/<brand-id>/
     brand.md                      Identity, audience, constraints
     design.md                     Composition and visual treatment (optional)
@@ -38,7 +38,7 @@ videos/<project-id>/
   reviews/                        Reviews tied to a particular delivered version
 ```
 
-The native skill folders are local instructions, not portable documents synchronized by `push`. Local media/render folders are not media uploads. `.editorharness/.sync.json` is CLI-managed sync state; do not edit it to bypass conflicts. An older valid workspace may omit the optional files and local production directories.
+The native skill folders are local instructions, not portable documents synchronized by `push`. Local media/render folders are not media uploads. `.editorbrain/.sync.json` is CLI-managed sync state; do not edit it to bypass conflicts. An older valid workspace may omit the optional files and local production directories.
 
 The resolver requires the selected brand's `brand.md`, `tokens.json`, `language.json`, `assets.json`; the selected style's `style.md`, `style.json`, `examples.json`; the selected output profile; and the project's `project.json`, `brief.md`, `direction.md`. Preserve them even when a declaration is empty. Additional guidance such as `adaptation-rules.json`, library indexes or memory may be present: read it explicitly when relevant. It is not automatically included in `resolve` merely because it exists.
 
@@ -76,6 +76,6 @@ Save reusable feedback at its stated scope: project-only changes in the project,
 
 ## Updating the installed skill
 
-Updating the global CLI does not replace skills already copied into a project. Run `editorharness skill install --dir <workspace> --agent both` and inspect `conflicts`, `preserved`, `warnings` and `readInstructions`.
+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.