editorbrain 0.6.0 → 0.7.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.7.0 help
 ```
 
 For a persistent installation:
 
 ```sh
-npm install -g editorbrain@0.6.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
 ```
 
-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;
@@ -575,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) {
@@ -604,6 +600,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 +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;
@@ -704,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;
@@ -728,12 +726,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"], "references/cli-mcp.md": ["5d3a79343fbd76cdae5bdbe12fb9c944d5dff4f489ac6534fd96e0cb8630b988", "8e011c31368cef2117a28ee972b39aab9535eeb0f601a4a0f9d6fc019b22c1c2"], "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 +881,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 +1106,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 +1120,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 +1345,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 +1356,11 @@ 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 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 +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", "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", ...booleans]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -1487,6 +1534,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 +1569,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 +1652,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") {
@@ -1717,7 +1784,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.7.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,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/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.