@corvio/cli 0.1.0-beta.4 → 0.1.0-beta.5

package/README.md

@@ -15,3 +15,5 @@ corvio update check --json
 ```
 
 When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` credential; it does not freeze the browser's current Workspace. Select each operation's Workspace with `corvio workspaces use`, `--workspace`, or `CORVIO_WORKSPACE_ID`. Legacy Workspace-bound `cvk_` keys remain supported and cannot be widened to another Workspace. The environment key always takes precedence. Local sync stores only credential-free handles and revision/hash baselines in `.corvio/state.json`; Markdown lives below `corvio_docs/`, and conflicts require explicit resolution. Update checks compare npm's published `beta` tag with the API compatibility policy but never self-install. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the full command and receipt contract.
+
+The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document updates preflight the current revision when `--expected-revision` is omitted. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.

package/dist/cli.js

@@ -9,6 +9,8 @@ import {
   ApiClient,
   CliError,
   EXIT,
+  assertKnownOptions,
+  assertPositionalCount,
   clearWorkspaceContext,
   clearWorkspaceCredential,
   idempotencyKey,
@@ -31,22 +33,75 @@ import {
   writeTextFile,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.4";
+const VERSION = "0.1.0-beta.5";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
+const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+const MAX_SYNC_FILES = 2_000;
+const MAX_MARKDOWN_CHARACTERS = 120_000;
+const GLOBAL_OPTIONS = Object.freeze([
+  "api-base",
+  "workspace",
+  "workspace-id",
+  "json",
+  "no-input",
+  "yes",
+  "help",
+  "version",
+]);
+
+const COMMAND_OPTIONS = Object.freeze({
+  "auth:login": ["force"],
+  "auth:status": [],
+  "auth:logout": [],
+  "workspaces:list": [],
+  "workspaces:current": [],
+  "workspaces:use": ["id"],
+  "workspaces:create": ["name", "kind", "description", "idempotency-key"],
+  "capabilities:": [],
+  "ask:": ["prompt", "conversation-id", "sources", "allow-actions", "idempotency-key"],
+  "questions:list": ["limit", "cursor", "conversation-id"],
+  "questions:get": ["id"],
+  "conversations:list": ["limit", "cursor"],
+  "conversations:get": ["id"],
+  "search:": ["query", "limit", "page-id", "node-id"],
+  "docs:list": ["limit", "cursor"],
+  "docs:get": ["id", "output"],
+  "docs:create": ["title", "file", "markdown", "parent-node-id", "idempotency-key"],
+  "docs:update": ["id", "title", "file", "markdown", "expected-revision"],
+  "docs:move": ["id", "parent-node-id", "before-node-id", "after-node-id", "idempotency-key"],
+  "docs:archive": ["id"],
+  "docs:share": ["id", "display-name"],
+  "docs:open": ["id"],
+  "projects:create": ["title", "idempotency-key"],
+  "files:list": ["limit"],
+  "files:get": ["id"],
+  "files:download": ["id", "output"],
+  "files:upload": ["file", "mime-type"],
+  "files:organize": ["id", "instruction", "target-root-node-id"],
+  "files:open": ["id"],
+  "sync:init": ["root-node-id", "dir", "name", "force"],
+  "sync:status": ["dir"],
+  "sync:plan": ["dir"],
+  "sync:pull": ["dir"],
+  "sync:push": ["dir"],
+  "sync:resolve": ["dir", "conflict-id", "strategy"],
+  "update:check": [],
+});
 
 const HELP = `Corvio Workspace CLI ${VERSION}
 
 Usage:
   corvio auth login|status|logout
-  corvio workspaces list|use|current [id]
+  corvio workspaces list|use|current|create [id]
   corvio capabilities
   corvio ask --prompt <text> [--conversation-id <id>] [--allow-actions]
   corvio questions list|get [id]
   corvio conversations list|get [id]
   corvio search <query>
-  corvio docs list|get|create|update|archive|share|open [id]
+  corvio docs list|get|create|update|move|archive|share|open [id]
+  corvio projects create --title <title>
   corvio files list|get|download|upload|organize|open [id]
   corvio sync init|status|plan|pull|push|resolve
   corvio update check
@@ -61,10 +116,101 @@ Authentication:
   Run 'corvio auth login' when no environment key is configured.
 `;
 
+const COMMAND_HELP = Object.freeze({
+  auth: `Usage: corvio auth login|status|logout\n\nAuthenticate with a user-level device link, inspect the current principal, or revoke the stored credential.`,
+  workspaces: `Usage:\n  corvio workspaces list\n  corvio workspaces use <workspace-id>\n  corvio workspaces current\n  corvio workspaces create --name <name> [--kind personal|team]\n\nWorkspace status and blocked capability reasons are returned with each item.`,
+  capabilities: `Usage: corvio capabilities [--json]\n\nShow live API resources, principal scopes, selected Workspace status, and CLI compatibility.`,
+  ask: `Usage: corvio ask --prompt <text> [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--idempotency-key <key>]`,
+  questions: `Usage:\n  corvio questions list [--limit <n>] [--cursor <cursor>] [--conversation-id <id>]\n  corvio questions get <question-id>`,
+  conversations: `Usage:\n  corvio conversations list [--limit <n>] [--cursor <cursor>]\n  corvio conversations get <conversation-id>`,
+  search: `Usage: corvio search <query> [--limit <n>] [--page-id <id>] [--node-id <id>]`,
+  docs: `Usage:\n  corvio docs list [--limit <n>] [--cursor <cursor>]\n  corvio docs get <id> [--output <path>]\n  corvio docs create --title <title> [--file <path>|--markdown <text>] [--parent-node-id <id>] [--idempotency-key <key>]\n  corvio docs update <id> [--title <title>] [--file <path>|--markdown <text>] [--expected-revision <n>]\n  corvio docs move <id> --parent-node-id <id>\n  corvio docs archive <id> --yes\n  corvio docs share <id> --yes [--display-name <name>]\n  corvio docs open <id>`,
+  projects: `Usage: corvio projects create --title <title> [--idempotency-key <key>]\n\nProjects are the user-visible folder/container owner in the Corvio Docs tree. 'corvio folders' is an alias.`,
+  files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id>\n  corvio files download <id> [--output <path>]\n  corvio files upload --file <path> [--mime-type <type>]\n  corvio files organize <id> --instruction <text> --yes [--target-root-node-id <id>]\n  corvio files open <id>`,
+  sync: `Usage:\n  corvio sync init --root-node-id <id> [--dir <path>] [--name <name>]\n  corvio sync status|plan|pull [--dir <path>]\n  corvio sync push --yes [--dir <path>]\n  corvio sync resolve --conflict-id <id> --strategy use-remote|keep-local --yes [--dir <path>]`,
+  update: `Usage: corvio update check [--json]\n\nCompare this executable with the reviewed API policy and the npm beta dist-tag.`,
+});
+
+function contextualHelp(command, action) {
+  const normalizedCommand = command === "workspace" ? "workspaces" : command === "folders" ? "projects" : command;
+  const commandHelp = COMMAND_HELP[normalizedCommand];
+  if (!commandHelp) return HELP.trimEnd();
+  if (!action) return commandHelp;
+  const matchingLine = commandHelp
+    .split("\n")
+    .find((line) => line.trim().startsWith(`corvio ${normalizedCommand} ${action}`));
+  return matchingLine ? `Usage:\n  ${matchingLine.trim()}\n\n${commandHelp}` : commandHelp;
+}
+
+function normalizeInvocation(command, action) {
+  const normalizedCommand = command === "workspace" ? "workspaces" : command === "folders" ? "projects" : command;
+  const defaultActions = {
+    workspaces: "list",
+    questions: "list",
+    conversations: "list",
+    docs: "list",
+    projects: "create",
+    files: "list",
+    sync: "status",
+    update: "check",
+  };
+  return {
+    command: normalizedCommand,
+    action: ["ask", "search", "capabilities"].includes(normalizedCommand)
+      ? ""
+      : action || defaultActions[normalizedCommand] || "",
+  };
+}
+
+function validateInvocation(options, positionals) {
+  const [rawCommand, rawAction] = positionals;
+  if (!rawCommand || rawCommand === "help" || rawCommand === "version" || options.help || options.version) return;
+  const { command, action } = normalizeInvocation(rawCommand, rawAction);
+  const schema = COMMAND_OPTIONS[`${command}:${action}`];
+  if (!schema) throw new CliError(`Unknown command: ${positionals.join(" ")}`, { code: "unknown_command" });
+  assertKnownOptions(options, [...GLOBAL_OPTIONS, ...schema]);
+  if (command !== "ask" && command !== "search") {
+    const actionsWithId = new Set([
+      "workspaces:use",
+      "questions:get",
+      "conversations:get",
+      "docs:get",
+      "docs:update",
+      "docs:move",
+      "docs:archive",
+      "docs:share",
+      "docs:open",
+      "files:get",
+      "files:download",
+      "files:organize",
+      "files:open",
+    ]);
+    assertPositionalCount(positionals, actionsWithId.has(`${command}:${action}`) ? 3 : command === "capabilities" ? 1 : 2);
+  }
+}
+
+function rejectTogether(options, left, right) {
+  if (options[left] !== undefined && options[right] !== undefined) {
+    throw new CliError(`Options --${left} and --${right} cannot be used together.`, {
+      code: "mutually_exclusive_options",
+    });
+  }
+}
+
 function baseUrl(options) {
   return normalizeApiBase(options["api-base"] || process.env.CORVIO_API_BASE, DEFAULT_API_BASE);
 }
 
+function resourcePath(value) {
+  return encodeURIComponent(String(value));
+}
+
+function safeRemoteFileName(value, fallback) {
+  const normalized = String(value || "").replaceAll("\\", "/");
+  const name = basename(normalized).trim();
+  return name && name !== "." && name !== ".." ? name : fallback;
+}
+
 async function resolveWorkspaceSelection(options, credential) {
   const explicit = String(options.workspace || options["workspace-id"] || "").trim();
   if (explicit) return { workspaceId: explicit, workspaceName: null, source: "option" };
@@ -136,6 +282,7 @@ async function authLogin(options) {
         "assets:write",
         "sync:read",
         "sync:write",
+        "workspaces:write",
       ],
     },
   });
@@ -296,7 +443,31 @@ async function workspaces(options, action, id) {
     await storeWorkspaceContext({ workspaceId: identity.workspace.id, workspaceName: identity.workspace.name });
     return writeResult({ selected: true, workspace: identity.workspace }, { json: options.json });
   }
-  throw new CliError("workspaces action must be list, use, or current.");
+  if (action === "create") {
+    if (!credential.key.startsWith("cvu_")) {
+      throw new CliError("Creating a Workspace requires a user-level cvu_ credential.", {
+        code: "user_api_key_required",
+        exitCode: EXIT.AUTH,
+      });
+    }
+    const api = new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
+    const kind = String(options.kind || "personal");
+    if (!new Set(["personal", "team"]).has(kind)) {
+      throw new CliError("--kind must be personal or team.", { code: "workspace_kind_invalid" });
+    }
+    const result = await api.request("/workspaces", {
+      method: "POST",
+      headers: { "idempotency-key": idempotencyKey(options) },
+      body: {
+        name: option(options, "name", { required: true }),
+        kind,
+        description: options.description || null,
+      },
+    });
+    await storeWorkspaceContext({ workspaceId: result.id, workspaceName: result.name });
+    return writeResult({ created: true, selected: true, workspace: result }, { json: options.json });
+  }
+  throw new CliError("workspaces action must be list, use, current, or create.");
 }
 
 async function ask(options, positionals) {
@@ -312,13 +483,14 @@ async function ask(options, positionals) {
       mode: options["allow-actions"] ? "allow_actions" : "answer_only",
       sources: listOption(options, "sources", ["workspace", "web", "memory"]),
     },
+    timeoutMs: 330_000,
   });
   writeResult(result, { json: options.json });
 }
 
 function pageQuery(options) {
   return {
-    limit: numberOption(options, "limit", 20),
+    limit: numberOption(options, "limit", 20, { maximum: 100 }),
     cursor: options.cursor,
     conversation_id: options["conversation-id"],
   };
@@ -328,7 +500,7 @@ async function questions(options, action, id) {
   const { api } = await client(options);
   const result = action === "list"
     ? await api.request("/questions", { query: pageQuery(options) })
-    : await api.request(`/questions/${id || option(options, "id", { required: true })}`);
+    : await api.request(`/questions/${resourcePath(id || option(options, "id", { required: true }))}`);
   writeResult(result, { json: options.json });
 }
 
@@ -336,7 +508,7 @@ async function conversations(options, action, id) {
   const { api } = await client(options);
   const result = action === "list"
     ? await api.request("/conversations", { query: pageQuery(options) })
-    : await api.request(`/conversations/${id || option(options, "id", { required: true })}`);
+    : await api.request(`/conversations/${resourcePath(id || option(options, "id", { required: true }))}`);
   writeResult(result, { json: options.json });
 }
 
@@ -346,9 +518,10 @@ async function search(options, positionals) {
   const { api } = await client(options);
   const result = await api.request("/search", {
     method: "POST",
+    retrySafe: true,
     body: {
       query,
-      limit: numberOption(options, "limit", 10),
+      limit: numberOption(options, "limit", 10, { maximum: 50 }),
       page_id: options["page-id"] || null,
       node_id: options["node-id"] || null,
     },
@@ -363,12 +536,13 @@ async function docs(options, action, id) {
   if (action === "list") {
     result = await api.request("/documents", { query: pageQuery(options) });
   } else if (action === "get") {
-    result = await api.request(`/documents/${documentId || option(options, "id", { required: true })}`);
+    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`);
     if (options.output) {
       await writeTextFile(options.output, String(result.markdown || ""));
       result = { ...result, output: options.output };
     }
   } else if (action === "create") {
+    rejectTogether(options, "file", "markdown");
     const markdown = options.file ? await readTextFile(options.file) : String(options.markdown || "");
     result = await api.request("/documents", {
       method: "POST",
@@ -381,33 +555,78 @@ async function docs(options, action, id) {
       },
     });
   } else if (action === "update") {
+    rejectTogether(options, "file", "markdown");
     const markdown = options.file ? await readTextFile(options.file) : options.markdown;
-    result = await api.request(`/documents/${documentId || option(options, "id", { required: true })}`, {
+    if (options.title === undefined && markdown === undefined) {
+      throw new CliError("Document update requires --title, --file, or --markdown.", {
+        code: "document_update_empty",
+      });
+    }
+    const targetId = documentId || option(options, "id", { required: true });
+    let expectedRevision;
+    if (options["expected-revision"] !== undefined) {
+      expectedRevision = numberOption(options, "expected-revision", undefined, { minimum: 0 });
+    } else {
+      const current = await api.request(`/documents/${resourcePath(targetId)}`);
+      if (!Number.isSafeInteger(current?.content_revision) || current.content_revision < 0) {
+        throw new CliError("Corvio did not return a valid document content revision.", {
+          code: "document_revision_missing",
+          exitCode: EXIT.REMOTE,
+        });
+      }
+      expectedRevision = current.content_revision;
+    }
+    result = await api.request(`/documents/${resourcePath(targetId)}`, {
       method: "PUT",
       body: {
-        ...(options.title ? { title: options.title } : {}),
+        ...(options.title !== undefined ? { title: options.title } : {}),
         ...(markdown !== undefined ? { markdown } : {}),
-        ...(options["expected-revision"] !== undefined
-          ? { expected_content_revision: Number.parseInt(options["expected-revision"], 10) }
-          : {}),
+        expected_content_revision: expectedRevision,
+      },
+    });
+  } else if (action === "move") {
+    rejectTogether(options, "before-node-id", "after-node-id");
+    const current = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`);
+    result = await api.request(`/nodes/${resourcePath(current.node_id)}:move`, {
+      method: "POST",
+      headers: { "idempotency-key": idempotencyKey(options) },
+      body: {
+        parent_node_id: option(options, "parent-node-id", { required: true }),
+        before_node_id: options["before-node-id"] || null,
+        after_node_id: options["after-node-id"] || null,
       },
     });
   } else if (action === "archive") {
     requireConfirmation(options, "Archiving a document");
-    result = await api.request(`/documents/${documentId || option(options, "id", { required: true })}`, { method: "DELETE" });
+    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`, { method: "DELETE" });
   } else if (action === "share") {
     requireConfirmation(options, "Creating a document share link");
-    result = await api.request(`/documents/${documentId || option(options, "id", { required: true })}/shares`, {
+    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}/shares`, {
       method: "POST",
+      retrySafe: true,
       body: { public_display_name: options["display-name"] || null },
     });
   } else if (action === "open") {
-    const target = `${String(process.env.CORVIO_APP_BASE || DEFAULT_APP_BASE).replace(/\/+$/, "")}/app/d/${documentId || option(options, "id", { required: true })}`;
+    const targetId = documentId || option(options, "id", { required: true });
+    const target = `${String(process.env.CORVIO_APP_BASE || DEFAULT_APP_BASE).replace(/\/+$/, "")}/app/d/${resourcePath(targetId)}`;
     const opened = options["no-input"] ? false : await openBrowser(target);
-    result = { document_id: documentId, url: target, opened };
+    result = { document_id: targetId, url: target, opened };
   } else {
-    throw new CliError("docs action must be list, get, create, update, archive, share, or open.");
+    throw new CliError("docs action must be list, get, create, update, move, archive, share, or open.");
+  }
+  writeResult(result, { json: options.json });
+}
+
+async function projects(options, action) {
+  if (action !== "create") {
+    throw new CliError("projects action must be create.");
   }
+  const { api } = await client(options);
+  const result = await api.request("/projects", {
+    method: "POST",
+    headers: { "idempotency-key": idempotencyKey(options) },
+    body: { title: option(options, "title", { required: true }) },
+  });
   writeResult(result, { json: options.json });
 }
 
@@ -511,30 +730,50 @@ async function files(options, action, id) {
   const assetId = id || options.id;
   let result;
   if (action === "list") {
-    result = await api.request("/files", { query: { limit: numberOption(options, "limit", 50) } });
+    result = await api.request("/files", { query: { limit: numberOption(options, "limit", 50, { maximum: 100 }) } });
   } else if (action === "get") {
-    result = await api.request(`/files/${assetId || option(options, "id", { required: true })}`);
+    result = await api.request(`/files/${resourcePath(assetId || option(options, "id", { required: true }))}`);
   } else if (action === "download") {
     const targetId = assetId || option(options, "id", { required: true });
-    const metadata = await api.request(`/files/${targetId}`);
-    const bytes = await api.requestBytes(`/files/${targetId}/content`);
-    const output = options.output || metadata.original_file_name || `${targetId}.bin`;
+    const metadata = await api.request(`/files/${resourcePath(targetId)}`);
+    const bytes = await api.requestBytes(`/files/${resourcePath(targetId)}/content`);
+    if (metadata.content_sha256 && sha256(bytes) !== metadata.content_sha256) {
+      throw new CliError("Downloaded file content did not match Corvio's SHA-256 receipt.", {
+        code: "download_integrity_mismatch",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    const output = options.output || safeRemoteFileName(metadata.original_file_name, `${targetId}.bin`);
     const written = await writeBinaryFile(output, bytes);
     result = { ...metadata, output: written };
   } else if (action === "upload") {
     const input = resolve(String(option(options, "file", { required: true })));
     const info = await stat(input);
     if (!info.isFile()) throw new CliError("--file must point to a regular file.", { code: "upload_file_invalid" });
+    if (info.size < 1 || info.size > MAX_UPLOAD_BYTES) {
+      throw new CliError(`--file must be between 1 byte and ${MAX_UPLOAD_BYTES} bytes.`, {
+        code: "upload_file_size_invalid",
+      });
+    }
     const bytes = await readFile(input);
+    if (bytes.length < 1 || bytes.length > MAX_UPLOAD_BYTES) {
+      throw new CliError(`--file must be between 1 byte and ${MAX_UPLOAD_BYTES} bytes.`, {
+        code: "upload_file_size_invalid",
+      });
+    }
     const fileName = basename(input);
     const mimeType = String(options["mime-type"] || mimeTypeFor(input));
     const initialized = await api.request("/files/uploads", {
       method: "POST",
       body: { file_name: fileName, mime_type: mimeType, size_bytes: bytes.length },
     });
-    await api.putUrl(initialized.upload_url, bytes, { headers: initialized.upload_headers || {} });
+    await api.putUrl(initialized.upload_url, bytes, {
+      headers: initialized.upload_headers || {},
+      timeoutMs: 5 * 60_000,
+    });
     result = await api.request("/files/uploads:finalize", {
       method: "POST",
+      retrySafe: true,
       body: {
         upload_id: initialized.upload_id,
         blob_name: initialized.blob_name,
@@ -543,9 +782,15 @@ async function files(options, action, id) {
         size_bytes: bytes.length,
       },
     });
+    if (result.content_sha256 && result.content_sha256 !== sha256(bytes)) {
+      throw new CliError("Uploaded file content did not match Corvio's SHA-256 receipt.", {
+        code: "upload_integrity_mismatch",
+        exitCode: EXIT.REMOTE,
+      });
+    }
   } else if (action === "organize") {
     requireConfirmation(options, "Starting a file organization run");
-    result = await api.request(`/files/${assetId || option(options, "id", { required: true })}:organize`, {
+    result = await api.request(`/files/${resourcePath(assetId || option(options, "id", { required: true }))}:organize`, {
       method: "POST",
       body: {
         instruction: option(options, "instruction", { required: true }),
@@ -554,7 +799,7 @@ async function files(options, action, id) {
     });
   } else if (action === "open") {
     const targetId = assetId || option(options, "id", { required: true });
-    const target = `${String(process.env.CORVIO_APP_BASE || DEFAULT_APP_BASE).replace(/\/+$/, "")}/app/a/${targetId}`;
+    const target = `${String(process.env.CORVIO_APP_BASE || DEFAULT_APP_BASE).replace(/\/+$/, "")}/app/a/${resourcePath(targetId)}`;
     result = { file_id: targetId, url: target, opened: options["no-input"] ? false : await openBrowser(target) };
   } else {
     throw new CliError("files action must be list, get, download, upload, organize, or open.");
@@ -609,6 +854,9 @@ async function writeSyncState(root, state) {
 }
 
 function localSyncPath(root, relativePath) {
+  if (String(relativePath).includes("\0")) {
+    throw new CliError("Unsafe sync path returned by Corvio.", { code: "sync_path_unsafe" });
+  }
   const parts = String(relativePath).replaceAll("\\", "/").split("/").filter(Boolean);
   if (parts[0] !== "corvio_docs" || parts.some((part) => part === "." || part === "..")) {
     throw new CliError(`Unsafe sync path returned by Corvio: ${relativePath}`, { code: "sync_path_unsafe" });
@@ -620,9 +868,56 @@ function localSyncPath(root, relativePath) {
   return target;
 }
 
+async function assertNoSyncSymlink(root, target) {
+  const rootInfo = await lstat(root);
+  if (rootInfo.isSymbolicLink()) {
+    throw new CliError(`Sync root must not be a symbolic link: ${root}`, {
+      code: "sync_symlink_unsafe",
+    });
+  }
+  const relativeTarget = relative(root, target);
+  if (relativeTarget === "" || relativeTarget.startsWith(`..${sep}`) || relativeTarget === "..") {
+    throw new CliError(`Unsafe local sync target: ${target}`, { code: "sync_path_unsafe" });
+  }
+  let current = root;
+  for (const part of relativeTarget.split(sep).filter(Boolean)) {
+    current = join(current, part);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) {
+        throw new CliError(`Sync path crosses a symbolic link: ${current}`, {
+          code: "sync_symlink_unsafe",
+        });
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+function verifiedRemoteMarkdown(item) {
+  const markdown = String(item?.markdown || "");
+  if (markdown.length > MAX_MARKDOWN_CHARACTERS) {
+    throw new CliError("Remote Markdown exceeds the supported sync size.", {
+      code: "sync_markdown_too_large",
+      exitCode: EXIT.REMOTE,
+    });
+  }
+  const contentHash = sha256(Buffer.from(markdown, "utf8"));
+  if (contentHash !== item?.content_sha256) {
+    throw new CliError("Remote Markdown did not match Corvio's SHA-256 receipt.", {
+      code: "sync_integrity_mismatch",
+      exitCode: EXIT.REMOTE,
+    });
+  }
+  return { markdown, contentHash };
+}
+
 async function scanMarkdown(root) {
   const mirror = join(root, "corvio_docs");
   await mkdir(mirror, { recursive: true });
+  await assertNoSyncSymlink(root, mirror);
   const manifest = [];
   async function walk(directory) {
     for (const entry of await readdir(directory, { withFileTypes: true })) {
@@ -639,6 +934,11 @@ async function scanMarkdown(root) {
           size_bytes: bytes.length,
           mtime_ms: Math.trunc(info.mtimeMs),
         });
+        if (manifest.length > MAX_SYNC_FILES) {
+          throw new CliError(`Sync supports at most ${MAX_SYNC_FILES} Markdown files per source.`, {
+            code: "sync_file_limit_exceeded",
+          });
+        }
       }
     }
   }
@@ -682,6 +982,7 @@ async function syncManifest(root, state) {
 async function syncPlan(api, state, root) {
   return api.request("/sync/plan", {
     method: "POST",
+    retrySafe: true,
     body: { source_id: state.source_id, local: await syncManifest(root, state) },
   });
 }
@@ -735,7 +1036,7 @@ async function syncCommand(options, action) {
     );
   }
   if (action === "status") {
-    const remote = await api.request(`/sync/sources/${state.source_id}`);
+    const remote = await api.request(`/sync/sources/${resourcePath(state.source_id)}`);
     return writeResult({ ...remote, directory: root, state_file: syncStatePath(root) }, { json: options.json });
   }
   if (action === "plan") {
@@ -757,9 +1058,12 @@ async function syncCommand(options, action) {
       const item = actionItem.remote;
       if (!item) continue;
       const target = localSyncPath(root, item.relative_path);
+      await assertNoSyncSymlink(root, target);
+      const verified = verifiedRemoteMarkdown(item);
       const previous = mappings[item.page_id];
       if (previous?.relative_path && previous.relative_path !== item.relative_path) {
         const oldTarget = localSyncPath(root, previous.relative_path);
+        await assertNoSyncSymlink(root, oldTarget);
         try {
           const oldBytes = await readFile(oldTarget);
           if (sha256(oldBytes) === previous.content_sha256) await unlink(oldTarget);
@@ -767,13 +1071,13 @@ async function syncCommand(options, action) {
           if (cause?.code !== "ENOENT") throw cause;
         }
       }
-      await writeTextFile(target, item.markdown || "");
+      await writeTextFile(target, verified.markdown);
       const info = await stat(target);
       committed.push({
         page_id: item.page_id,
         node_id: item.node_id,
         relative_path: item.relative_path,
-        content_sha256: item.content_sha256,
+        content_sha256: verified.contentHash,
         mtime_ms: Math.trunc(info.mtimeMs),
       });
       mappings[item.page_id] = {
@@ -813,7 +1117,14 @@ async function syncCommand(options, action) {
     const mappings = { ...(state.mappings || {}) };
     for (const actionItem of plan.actions.filter((item) => item.action === "push")) {
       const path = localSyncPath(root, actionItem.relative_path);
+      await assertNoSyncSymlink(root, path);
       const bytes = await readFile(path);
+      const markdown = bytes.toString("utf8");
+      if (markdown.length > MAX_MARKDOWN_CHARACTERS) {
+        throw new CliError(`Markdown exceeds ${MAX_MARKDOWN_CHARACTERS} characters: ${actionItem.relative_path}`, {
+          code: "sync_markdown_too_large",
+        });
+      }
       const info = await stat(path);
       const previous = actionItem.page_id ? mappings[actionItem.page_id] : null;
       const result = await api.request("/sync/push", {
@@ -821,7 +1132,7 @@ async function syncCommand(options, action) {
         body: {
           source_id: state.source_id,
           relative_path: actionItem.relative_path,
-          markdown: bytes.toString("utf8"),
+          markdown,
           content_sha256: sha256(bytes),
           mtime_ms: Math.trunc(info.mtimeMs),
           page_id: actionItem.page_id || null,
@@ -835,6 +1146,9 @@ async function syncCommand(options, action) {
         content_sha256: result.item.content_sha256,
         content_revision: result.item.content_revision,
       };
+      state.mappings = mappings;
+      state.last_push_at = new Date().toISOString();
+      await writeSyncState(root, state);
     }
     state.mappings = mappings;
     state.last_push_at = new Date().toISOString();
@@ -849,12 +1163,14 @@ async function syncCommand(options, action) {
     requireConfirmation(options, "Resolving a sync conflict");
     const conflictId = option(options, "conflict-id", { required: true });
     const strategy = option(options, "strategy", { required: true });
-    const conflict = await api.request(`/sync/conflicts/${conflictId}`);
+    const conflict = await api.request(`/sync/conflicts/${resourcePath(conflictId)}`);
     if (strategy === "use-remote") {
       if (!conflict.remote) throw new CliError("The remote document is no longer available.", { code: "sync_remote_missing" });
       const item = conflict.remote;
       const target = localSyncPath(root, item.relative_path);
-      await writeTextFile(target, item.markdown || "");
+      await assertNoSyncSymlink(root, target);
+      const verified = verifiedRemoteMarkdown(item);
+      await writeTextFile(target, verified.markdown);
       const info = await stat(target);
       await api.request("/sync/commit", {
         method: "POST",
@@ -864,12 +1180,12 @@ async function syncCommand(options, action) {
             page_id: item.page_id,
             node_id: item.node_id,
             relative_path: item.relative_path,
-            content_sha256: item.content_sha256,
+            content_sha256: verified.contentHash,
             mtime_ms: Math.trunc(info.mtimeMs),
           }],
         },
       });
-      const result = await api.request(`/sync/conflicts/${conflictId}:resolve`, {
+      const result = await api.request(`/sync/conflicts/${resourcePath(conflictId)}:resolve`, {
         method: "POST",
         body: { strategy: "use_remote" },
       });
@@ -884,14 +1200,21 @@ async function syncCommand(options, action) {
     }
     if (strategy === "keep-local") {
       const target = localSyncPath(root, conflict.relative_path);
+      await assertNoSyncSymlink(root, target);
       const bytes = await readFile(target);
+      const markdown = bytes.toString("utf8");
+      if (markdown.length > MAX_MARKDOWN_CHARACTERS) {
+        throw new CliError(`Markdown exceeds ${MAX_MARKDOWN_CHARACTERS} characters: ${conflict.relative_path}`, {
+          code: "sync_markdown_too_large",
+        });
+      }
       const info = await stat(target);
       const result = await api.request("/sync/push", {
         method: "POST",
         body: {
           source_id: state.source_id,
           relative_path: conflict.relative_path,
-          markdown: bytes.toString("utf8"),
+          markdown,
           content_sha256: sha256(bytes),
           mtime_ms: Math.trunc(info.mtimeMs),
           page_id: conflict.remote?.page_id || null,
@@ -915,7 +1238,12 @@ async function syncCommand(options, action) {
 async function main({ options, positionals }) {
   const [command, action, id, ...rest] = positionals;
   if (options.version || command === "version") return writeResult(VERSION, { json: options.json });
-  if (options.help || !command || command === "help") return writeResult(HELP.trimEnd(), { json: false });
+  if (options.help || !command || command === "help") {
+    const helpCommand = command === "help" ? action : command;
+    const helpAction = command === "help" ? id : action;
+    return writeResult(contextualHelp(helpCommand, helpAction), { json: false });
+  }
+  validateInvocation(options, positionals);
   if (command !== "update") await maybeNotifyUpdate(options);
   if (command === "auth") {
     if (action === "login") return authLogin(options);
@@ -932,6 +1260,7 @@ async function main({ options, positionals }) {
   if (command === "conversations") return conversations(options, action || "list", id);
   if (command === "search") return search(options, [action, id, ...rest].filter(Boolean));
   if (command === "docs") return docs(options, action || "list", id);
+  if (command === "projects" || command === "folders") return projects(options, action || "create");
   if (command === "files") return files(options, action || "list", id);
   if (command === "sync") return syncCommand(options, action || "status");
   if (command === "update" && (action || "check") === "check") return updateCheck(options);

package/dist/core.js

@@ -32,6 +32,59 @@ function exitCodeForStatus(status) {
   return EXIT.REMOTE;
 }
 
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const MAX_REQUEST_TIMEOUT_MS = 10 * 60_000;
+const RETRYABLE_HTTP_STATUSES = new Set([408, 429, 502, 503, 504]);
+
+function normalizeRequestTimeout(value, fallback = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const raw = value === undefined || value === null || value === "" ? fallback : Number(value);
+  if (!Number.isSafeInteger(raw) || raw < 1 || raw > MAX_REQUEST_TIMEOUT_MS) {
+    throw new CliError(
+      `Request timeout must be an integer between 1 and ${MAX_REQUEST_TIMEOUT_MS} milliseconds.`,
+      { code: "invalid_request_timeout" },
+    );
+  }
+  return raw;
+}
+
+function networkFailureDetails({
+  cause,
+  url,
+  method,
+  requestHeaders = {},
+  body = undefined,
+  retrySafe = false,
+}) {
+  const nested = cause && typeof cause === "object" ? cause.cause : null;
+  const causeCode = String(nested?.code || cause?.code || "").trim() || null;
+  const syscall = String(nested?.syscall || cause?.syscall || "").trim() || null;
+  const normalizedMethod = String(method || "GET").toUpperCase();
+  const operationKey = String(requestHeaders["idempotency-key"] || requestHeaders["Idempotency-Key"] || "").trim();
+  const revision = body?.expected_content_revision;
+  const revisionGuarded = normalizedMethod === "PUT" && Number.isSafeInteger(revision) && revision >= 0;
+  const safeToRetry = retrySafe || ["GET", "HEAD"].includes(normalizedMethod) || Boolean(operationKey) || revisionGuarded;
+  const timedOut = cause?.name === "TimeoutError" || cause?.name === "AbortError";
+  return {
+    method: normalizedMethod,
+    origin: new URL(String(url)).origin,
+    response_received: false,
+    timed_out: timedOut,
+    safe_to_retry: safeToRetry,
+    retry_safety: operationKey
+      ? "idempotency_key"
+      : revisionGuarded
+        ? "revision_guard"
+        : retrySafe
+          ? "operation_contract"
+          : safeToRetry
+            ? "read_only"
+            : "unknown_commit_state",
+    ...(operationKey ? { idempotency_key: operationKey } : {}),
+    ...(causeCode ? { cause_code: causeCode } : {}),
+    ...(syscall ? { syscall } : {}),
+  };
+}
+
 export function parseArgv(argv) {
   const options = Object.create(null);
   const positionals = [];
@@ -47,14 +100,26 @@ export function parseArgv(argv) {
   ]);
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
+    if (value === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
     if (!value.startsWith("--")) {
       positionals.push(value);
       continue;
     }
     const separator = value.indexOf("=");
     const name = value.slice(2, separator === -1 ? undefined : separator);
+    if (!name) throw new CliError("Option name must not be empty.", { code: "invalid_option" });
+    if (Object.hasOwn(options, name)) {
+      throw new CliError(`Option --${name} was provided more than once.`, { code: "duplicate_option" });
+    }
     if (booleanOptions.has(name)) {
-      options[name] = separator === -1 ? true : value.slice(separator + 1) !== "false";
+      const booleanValue = separator === -1 ? "true" : value.slice(separator + 1);
+      if (booleanValue !== "true" && booleanValue !== "false") {
+        throw new CliError(`Option --${name} must be true or false.`, { code: "invalid_boolean_option" });
+      }
+      options[name] = booleanValue === "true";
       continue;
     }
     if (separator !== -1) {
@@ -71,6 +136,21 @@ export function parseArgv(argv) {
   return { options, positionals };
 }
 
+export function assertKnownOptions(options, allowed) {
+  const allowedSet = new Set(allowed);
+  for (const name of Object.keys(options)) {
+    if (!allowedSet.has(name)) {
+      throw new CliError(`Unknown option --${name}.`, { code: "unknown_option" });
+    }
+  }
+}
+
+export function assertPositionalCount(positionals, maximum) {
+  if (positionals.length > maximum) {
+    throw new CliError(`Unexpected argument: ${positionals[maximum]}`, { code: "unexpected_argument" });
+  }
+}
+
 export function option(options, name, { required = false, fallback = undefined } = {}) {
   const value = options[name] ?? fallback;
   if (required && (value === undefined || String(value).trim() === "")) {
@@ -85,28 +165,43 @@ export function listOption(options, name, fallback = []) {
   return String(value).split(",").map((item) => item.trim()).filter(Boolean);
 }
 
-export function numberOption(options, name, fallback) {
+export function numberOption(options, name, fallback, { minimum = 1, maximum = Number.MAX_SAFE_INTEGER } = {}) {
   const value = options[name];
   if (value === undefined) return fallback;
-  const parsed = Number.parseInt(String(value), 10);
-  if (!Number.isFinite(parsed) || parsed < 1) {
-    throw new CliError(`Option --${name} must be a positive integer.`, { code: "invalid_number_option" });
+  const normalized = String(value).trim();
+  const parsed = /^\d+$/.test(normalized) ? Number(normalized) : Number.NaN;
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new CliError(
+      `Option --${name} must be an integer between ${minimum} and ${maximum}.`,
+      { code: "invalid_number_option" },
+    );
   }
   return parsed;
 }
 
 export function normalizeApiBase(value, fallback) {
   const raw = String(value || fallback).trim().replace(/\/+$/, "");
-  if (!/^https:\/\//i.test(raw) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(raw)) {
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new CliError("Corvio API base must be a valid URL.", { code: "invalid_api_base" });
+  }
+  const localhost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+  if (parsed.username || parsed.password || (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && localhost))) {
     throw new CliError("Corvio API base must use HTTPS (localhost is allowed for development).", {
       code: "insecure_api_base",
     });
   }
-  return raw.endsWith("/v1") ? raw : `${raw}/v1`;
+  if (parsed.search || parsed.hash) {
+    throw new CliError("Corvio API base must not include a query string or fragment.", { code: "invalid_api_base" });
+  }
+  const normalized = parsed.toString().replace(/\/+$/, "");
+  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
 }
 
 function parseSemver(value) {
-  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  const match = String(value || "").trim().match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
   if (!match) return null;
   return {
     core: match.slice(1, 4).map((item) => Number.parseInt(item, 10)),
@@ -187,15 +282,31 @@ export async function resolveNpmUpdateStatus({
 }
 
 export class ApiClient {
-  constructor({ baseUrl, credential = null, workspaceId = null, userAgent, fetchImpl = globalThis.fetch }) {
+  constructor({
+    baseUrl,
+    credential = null,
+    workspaceId = null,
+    userAgent,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = process.env.CORVIO_REQUEST_TIMEOUT_MS,
+  }) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.credential = credential;
     this.workspaceId = String(workspaceId || "").trim() || null;
     this.userAgent = userAgent;
     this.fetchImpl = fetchImpl;
+    this.timeoutMs = normalizeRequestTimeout(timeoutMs);
   }
 
-  async request(path, { method = "GET", body, query, headers = {}, auth = true } = {}) {
+  async request(path, {
+    method = "GET",
+    body,
+    query,
+    headers = {},
+    auth = true,
+    retrySafe = false,
+    timeoutMs = this.timeoutMs,
+  } = {}) {
     const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
@@ -216,18 +327,56 @@ export class ApiClient {
         requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
       }
     }
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
     let response;
-    try {
-      response = await this.fetchImpl(url, {
-        method,
-        headers: requestHeaders,
-        body: body === undefined ? undefined : JSON.stringify(body),
-      });
-    } catch (cause) {
-      throw new CliError(`Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        code: "network_error",
-        exitCode: EXIT.REMOTE,
-      });
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers: requestHeaders,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        const safety = networkFailureDetails({
+          cause: null,
+          url,
+          method,
+          requestHeaders,
+          body,
+          retrySafe,
+        });
+        if (attempt === 1 && safety.safe_to_retry && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          const retryAfterValue = response.headers.get("retry-after");
+          const retryAfterSeconds = retryAfterValue === null ? Number.NaN : Number(retryAfterValue);
+          const delayMs = Number.isFinite(retryAfterSeconds)
+            ? Math.min(2_000, Math.max(0, retryAfterSeconds * 1000))
+            : 150;
+          await sleep(delayMs);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({ cause, url, method, requestHeaders, body, retrySafe });
+        if (attempt === 1 && details.safe_to_retry) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `Corvio did not respond within ${normalizedTimeout} ms.`
+            : `Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+          code: details.timed_out ? "request_timeout" : "network_error",
+          exitCode: EXIT.REMOTE,
+          details: {
+            ...details,
+            attempts: attempt,
+            automatic_retry_attempted: attempt > 1,
+          },
+          },
+        );
+      }
     }
     const text = await response.text();
     let payload = null;
@@ -244,13 +393,18 @@ export class ApiClient {
         code: String(envelope.code || `http_${response.status}`),
         status: response.status,
         exitCode: exitCodeForStatus(response.status),
-        details: envelope.details || null,
+        details: {
+          ...(envelope.details || {}),
+          ...(envelope.request_id || response.headers.get("x-request-id")
+            ? { request_id: envelope.request_id || response.headers.get("x-request-id") }
+            : {}),
+        },
       });
     }
     return payload;
   }
 
-  async requestBytes(path, { query, headers = {}, auth = true } = {}) {
+  async requestBytes(path, { query, headers = {}, auth = true, timeoutMs = this.timeoutMs } = {}) {
     const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
     for (const [key, value] of Object.entries(query || {})) {
       if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
@@ -270,14 +424,38 @@ export class ApiClient {
         requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
       }
     }
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
     let response;
-    try {
-      response = await this.fetchImpl(url, { method: "GET", headers: requestHeaders });
-    } catch (cause) {
-      throw new CliError(`Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        code: "network_error",
-        exitCode: EXIT.REMOTE,
-      });
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(url, {
+          method: "GET",
+          headers: requestHeaders,
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        if (attempt === 1 && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          await sleep(150);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({ cause, url, method: "GET", requestHeaders });
+        if (attempt === 1) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `Corvio did not respond within ${normalizedTimeout} ms.`
+            : `Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+            code: details.timed_out ? "request_timeout" : "network_error",
+            exitCode: EXIT.REMOTE,
+            details: { ...details, attempts: attempt, automatic_retry_attempted: true },
+          },
+        );
+      }
     }
     const bytes = new Uint8Array(await response.arrayBuffer());
     if (!response.ok) {
@@ -293,25 +471,57 @@ export class ApiClient {
         code: String(envelope.code || `http_${response.status}`),
         status: response.status,
         exitCode: exitCodeForStatus(response.status),
-        details: envelope.details || null,
+        details: {
+          ...(envelope.details || {}),
+          ...(envelope.request_id || response.headers.get("x-request-id")
+            ? { request_id: envelope.request_id || response.headers.get("x-request-id") }
+            : {}),
+        },
       });
     }
     return bytes;
   }
 
-  async putUrl(url, content, { headers = {} } = {}) {
+  async putUrl(url, content, { headers = {}, timeoutMs = this.timeoutMs } = {}) {
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
     let response;
-    try {
-      response = await this.fetchImpl(String(url), {
-        method: "PUT",
-        headers,
-        body: content,
-      });
-    } catch (cause) {
-      throw new CliError(`Unable to upload the file: ${cause instanceof Error ? cause.message : String(cause)}`, {
-        code: "upload_network_error",
-        exitCode: EXIT.REMOTE,
-      });
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(String(url), {
+          method: "PUT",
+          headers,
+          body: content,
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        if (attempt === 1 && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          await sleep(150);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({
+          cause,
+          url,
+          method: "PUT",
+          requestHeaders: headers,
+          retrySafe: true,
+        });
+        if (attempt === 1) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `The file upload did not respond within ${normalizedTimeout} ms.`
+            : `Unable to upload the file: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+            code: details.timed_out ? "upload_timeout" : "upload_network_error",
+            exitCode: EXIT.REMOTE,
+            details: { ...details, attempts: attempt, automatic_retry_attempted: true },
+          },
+        );
+      }
     }
     if (!response.ok) {
       const message = (await response.text()).slice(0, 500);
@@ -534,7 +744,21 @@ export function writeError(error, { json = false, stderr = process.stderr } = {}
       ...(error instanceof CliError && error.details ? { details: error.details } : {}),
     },
   };
-  stderr.write(json ? `${JSON.stringify(safe)}\n` : `Error: ${safe.error.message}\n`);
+  if (json) {
+    stderr.write(`${JSON.stringify(safe)}\n`);
+    return;
+  }
+  stderr.write(`Error: ${safe.error.message}\n`);
+  if (safe.error.details?.request_id) stderr.write(`Request ID: ${safe.error.details.request_id}\n`);
+  if (safe.error.details?.safe_to_retry && safe.error.details?.idempotency_key) {
+    stderr.write(
+      `Safe retry: rerun the command with --idempotency-key ${safe.error.details.idempotency_key}\n`,
+    );
+  } else if (safe.error.details?.retry_safety === "revision_guard") {
+    stderr.write("Safe retry: rerun with the same --expected-revision; Corvio will reject an already-committed replacement.\n");
+  } else if (safe.error.details?.retry_safety === "unknown_commit_state") {
+    stderr.write("Retry state is unknown; read the remote object before repeating this mutation.\n");
+  }
 }
 
 export async function runMain(main, argv = process.argv.slice(2)) {
@@ -551,8 +775,8 @@ export async function runMain(main, argv = process.argv.slice(2)) {
 
 export async function openBrowser(url) {
   const target = String(url);
-  const command = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
-  const args = platform() === "win32" ? ["/c", "start", "", target] : [target];
+  const command = platform() === "darwin" ? "open" : platform() === "win32" ? "rundll32.exe" : "xdg-open";
+  const args = platform() === "win32" ? ["url.dll,FileProtocolHandler", target] : [target];
   return new Promise((resolvePromise) => {
     let settled = false;
     const finish = (opened) => {
@@ -584,14 +808,28 @@ export async function readTextFile(path) {
 export async function writeTextFile(path, content) {
   const target = resolve(String(path));
   await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, content, "utf8");
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
   return target;
 }
 
 export async function writeBinaryFile(path, content) {
   const target = resolve(String(path));
   await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, content);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
   return target;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corvio/cli",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "description": "Official Corvio Workspace CLI for questions, knowledge search, documents, and Agent workflows.",
   "type": "module",
   "bin": {