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

package/dist/cli.js

@@ -1,9 +1,17 @@
 #!/usr/bin/env node
 
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+
 import {
   ApiClient,
   CliError,
   EXIT,
+  assertKnownOptions,
+  assertPositionalCount,
+  clearWorkspaceContext,
   clearWorkspaceCredential,
   idempotencyKey,
   listOption,
@@ -12,44 +20,214 @@ import {
   openBrowser,
   option,
   readTextFile,
+  readWorkspaceContext,
   readWorkspaceCredential,
   requireConfirmation,
+  resolveNpmUpdateStatus,
   runMain,
   sleep,
+  storeWorkspaceContext,
   storeWorkspaceCredential,
   writeResult,
+  writeBinaryFile,
   writeTextFile,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.3";
+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|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
 
 Global options:
-  --api-base <url>  --json  --no-input  --yes  --help  --version
+  --api-base <url>  --workspace <id>  --json  --no-input  --yes  --help  --version
 
 Authentication:
-  CORVIO_API_KEY=cvk_... takes precedence over the stored device-link login.
+  CORVIO_API_KEY=cvu_... takes precedence over the stored device-link login.
+  Legacy Workspace-bound cvk_ keys remain supported.
+  Select the target with 'corvio workspaces use <id>', --workspace, or CORVIO_WORKSPACE_ID.
   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);
 }
 
-async function client(options, { auth = true } = {}) {
+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" };
+  const legacyWorkspaceId = String(credential?.metadata?.workspace_id || "").trim();
+  if (legacyWorkspaceId) {
+    return {
+      workspaceId: legacyWorkspaceId,
+      workspaceName: String(credential?.metadata?.workspace_name || "").trim() || null,
+      source: "legacy_credential",
+    };
+  }
+  const context = await readWorkspaceContext();
+  if (context?.workspaceId) return context;
+  return null;
+}
+
+async function client(options, { auth = true, workspace = "required" } = {}) {
   const credential = auth ? await readWorkspaceCredential() : null;
   if (auth && !credential) {
     throw new CliError("No Corvio credential found. Set CORVIO_API_KEY or run `corvio auth login`.", {
@@ -57,16 +235,31 @@ async function client(options, { auth = true } = {}) {
       exitCode: EXIT.AUTH,
     });
   }
+  const selection = auth && workspace !== "none"
+    ? await resolveWorkspaceSelection(options, credential)
+    : null;
+  if (auth && workspace === "required" && credential?.key?.startsWith("cvu_") && !selection?.workspaceId) {
+    throw new CliError(
+      "No Corvio Workspace selected. Run `corvio workspaces list` then `corvio workspaces use <id>`.",
+      { code: "workspace_selection_required", exitCode: EXIT.AUTH },
+    );
+  }
   return {
-    api: new ApiClient({ baseUrl: baseUrl(options), credential: credential?.key, userAgent: USER_AGENT }),
+    api: new ApiClient({
+      baseUrl: baseUrl(options),
+      credential: credential?.key,
+      workspaceId: selection?.workspaceId,
+      userAgent: USER_AGENT,
+    }),
     credential,
+    selection,
   };
 }
 
 async function authLogin(options) {
   const current = await readWorkspaceCredential();
   if (current?.source === "environment" && !options.force) {
-    const { api } = await client(options);
+    const api = new ApiClient({ baseUrl: baseUrl(options), credential: current.key, userAgent: USER_AGENT });
     const identity = await api.request("/me");
     writeResult({ authenticated: true, source: "environment", identity }, { json: options.json });
     return;
@@ -85,6 +278,11 @@ async function authLogin(options) {
         "documents:read",
         "documents:write",
         "documents:share",
+        "assets:read",
+        "assets:write",
+        "sync:read",
+        "sync:write",
+        "workspaces:write",
       ],
     },
   });
@@ -127,7 +325,9 @@ async function authLogin(options) {
     authenticated: true,
     source: "device_link",
     profile: stored.profile,
+    user: identity.user,
     workspace: identity.workspace,
+    workspaces: identity.workspaces || [],
     scopes: identity.api_key?.scopes || [],
   }, { json: options.json });
 }
@@ -138,7 +338,12 @@ async function authStatus(options) {
     writeResult({ authenticated: false, sources: ["CORVIO_API_KEY", "device_link"] }, { json: options.json });
     return;
   }
-  const api = new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
+  const selection = await resolveWorkspaceSelection(options, credential);
+  const api = new ApiClient({
+    baseUrl: baseUrl(options),
+    credential: credential.key,
+    userAgent: USER_AGENT,
+  });
   const identity = await api.request("/me");
   writeResult({
     authenticated: true,
@@ -146,6 +351,8 @@ async function authStatus(options) {
     profile: credential.profile,
     user: identity.user,
     workspace: identity.workspace,
+    workspaces: identity.workspaces || [],
+    selection,
     api_key: identity.api_key,
   }, { json: options.json });
 }
@@ -165,24 +372,104 @@ async function authLogout(options) {
   const api = new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
   await api.request("/auth/credentials/current:revoke", { method: "POST" });
   await clearWorkspaceCredential();
+  await clearWorkspaceContext();
   writeResult({ authenticated: false, revoked: true, profile: credential.profile }, { json: options.json });
 }
 
 async function capabilities(options) {
-  const { api, credential } = await client(options);
+  const { api, credential, selection } = await client(options, { workspace: "optional" });
   const [index, identity] = await Promise.all([api.request("", { auth: false }), api.request("/me")]);
   writeResult({
     cli_version: VERSION,
     auth_source: credential.source,
+    workspace_selection: selection,
     api: index,
     principal: identity,
-    unavailable: {
-      files: "Public Workspace Asset upload/organization is not advertised by /v1 yet.",
-      sync: "Public Local Sync adapters are not advertised by /v1 yet.",
-    },
+    update: await buildUpdateStatus(index, { allowRegistryFailure: true }),
   }, { json: options.json });
 }
 
+async function workspaces(options, action, id) {
+  const credential = await readWorkspaceCredential();
+  if (!credential) {
+    throw new CliError("No Corvio credential found. Run `corvio auth login`.", {
+      code: "auth_required",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  if (action === "list") {
+    const api = new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
+    if (credential.key.startsWith("cvk_")) {
+      const identity = await api.request("/me");
+      return writeResult({ data: identity.workspace ? [identity.workspace] : [], legacy_bound: true }, { json: options.json });
+    }
+    return writeResult(await api.request("/workspaces"), { json: options.json });
+  }
+  const selection = await resolveWorkspaceSelection(options, credential);
+  if (action === "current") {
+    if (!selection?.workspaceId) {
+      if (credential.key.startsWith("cvk_")) {
+        const api = new ApiClient({ baseUrl: baseUrl(options), credential: credential.key, userAgent: USER_AGENT });
+        const identity = await api.request("/me");
+        return writeResult(
+          { selected: Boolean(identity.workspace), workspace: identity.workspace, source: "legacy_credential" },
+          { json: options.json },
+        );
+      }
+      return writeResult({ selected: false, workspace: null }, { json: options.json });
+    }
+    const api = new ApiClient({
+      baseUrl: baseUrl(options),
+      credential: credential.key,
+      workspaceId: selection.workspaceId,
+      userAgent: USER_AGENT,
+    });
+    const identity = await api.request("/me");
+    return writeResult({ selected: true, workspace: identity.workspace, source: selection.source }, { json: options.json });
+  }
+  if (action === "use") {
+    const workspaceId = String(id || options.id || options.workspace || options["workspace-id"] || "").trim();
+    if (!workspaceId) throw new CliError("Provide a Workspace ID.", { code: "workspace_selection_required" });
+    const api = new ApiClient({
+      baseUrl: baseUrl(options),
+      credential: credential.key,
+      workspaceId,
+      userAgent: USER_AGENT,
+    });
+    const identity = await api.request("/me");
+    if (!identity.workspace?.id) {
+      throw new CliError("Corvio did not resolve the selected Workspace.", { code: "workspace_selection_failed" });
+    }
+    await storeWorkspaceContext({ workspaceId: identity.workspace.id, workspaceName: identity.workspace.name });
+    return writeResult({ selected: true, workspace: identity.workspace }, { json: options.json });
+  }
+  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) {
   const prompt = String(options.prompt || positionals.join(" ")).trim();
   if (!prompt) throw new CliError("Provide --prompt <text> or a positional prompt.");
@@ -196,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"],
   };
@@ -212,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 });
 }
 
@@ -220,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 });
 }
 
@@ -230,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,
     },
@@ -247,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",
@@ -265,58 +555,715 @@ 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, 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 });
+}
+
+async function buildUpdateStatus(index, { allowRegistryFailure = false } = {}) {
+  return resolveNpmUpdateStatus({
+    currentVersion: VERSION,
+    policy: index?.distribution?.workspace_cli || {
+      package: "@corvio/cli",
+      dist_tag: "beta",
+    },
+    userAgent: USER_AGENT,
+    allowRegistryFailure,
+  });
+}
+
+function updateCachePath() {
+  const root = process.env.CORVIO_CONFIG_DIR
+    ? resolve(process.env.CORVIO_CONFIG_DIR)
+    : process.env.XDG_CACHE_HOME
+      ? join(resolve(process.env.XDG_CACHE_HOME), "corvio")
+      : join(homedir(), ".cache", "corvio");
+  return join(root, "update-check.json");
+}
+
+async function readUpdateCache() {
+  try {
+    return JSON.parse(await readFile(updateCachePath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeUpdateCache(payload) {
+  const target = updateCachePath();
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, target);
+}
+
+async function updateCheck(options) {
+  const { api } = await client(options, { auth: false });
+  const index = await api.request("", { auth: false });
+  const result = await buildUpdateStatus(index);
+  await writeUpdateCache({ checked_at: new Date().toISOString(), result }).catch(() => {});
+  writeResult(result, { json: options.json });
+}
+
+async function maybeNotifyUpdate(options) {
+  if (
+    options.json
+    || options["no-input"]
+    || process.env.CI
+    || process.env.CORVIO_DISABLE_UPDATE_CHECK === "1"
+  ) return;
+  const cache = await readUpdateCache();
+  const checkedAt = Date.parse(String(cache?.checked_at || ""));
+  let result = cache?.result;
+  if (!Number.isFinite(checkedAt) || Date.now() - checkedAt > 24 * 60 * 60 * 1000) {
+    try {
+      const { api } = await client(options, { auth: false });
+      const index = await api.request("", { auth: false });
+      result = await buildUpdateStatus(index, { allowRegistryFailure: true });
+      await writeUpdateCache({ checked_at: new Date().toISOString(), result }).catch(() => {});
+    } catch {
+      return;
+    }
+  }
+  if (result?.update_available) {
+    process.stderr.write(
+      `Update available: @corvio/cli ${result.current_version} → ${result.latest_published_version}. `
+      + `Run: ${result.install_command}\n`,
+    );
+  } else if (result?.supported === false) {
+    process.stderr.write(
+      `This Corvio CLI (${VERSION}) is no longer supported. Run: ${result.install_command}\n`,
+    );
+  }
+}
+
+function mimeTypeFor(path) {
+  const extension = extname(String(path)).toLowerCase();
+  return ({
+    ".md": "text/markdown",
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  })[extension] || "application/octet-stream";
+}
+
+async function files(options, action, id) {
+  const { api } = await client(options);
+  const assetId = id || options.id;
+  let result;
+  if (action === "list") {
+    result = await api.request("/files", { query: { limit: numberOption(options, "limit", 50, { maximum: 100 }) } });
+  } else if (action === "get") {
+    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/${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 || {},
+      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,
+        file_name: fileName,
+        mime_type: mimeType,
+        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/${resourcePath(assetId || option(options, "id", { required: true }))}:organize`, {
+      method: "POST",
+      body: {
+        instruction: option(options, "instruction", { required: true }),
+        target_root_node_id: options["target-root-node-id"] || null,
+      },
+    });
+  } 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/${resourcePath(targetId)}`;
+    result = { file_id: targetId, url: target, opened: options["no-input"] ? false : await openBrowser(target) };
   } else {
-    throw new CliError("docs action must be list, get, create, update, archive, share, or open.");
+    throw new CliError("files action must be list, get, download, upload, organize, or open.");
   }
   writeResult(result, { json: options.json });
 }
 
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function syncRoot(options) {
+  return resolve(String(options.dir || process.cwd()));
+}
+
+function syncStatePath(root) {
+  return join(root, ".corvio", "state.json");
+}
+
+async function readSyncState(options) {
+  const root = syncRoot(options);
+  let state;
+  try {
+    state = JSON.parse(await readFile(syncStatePath(root), "utf8"));
+  } catch (cause) {
+    if (cause?.code === "ENOENT") {
+      throw new CliError("This directory is not initialized. Run `corvio sync init --root-node-id <id>`.", {
+        code: "sync_not_initialized",
+      });
+    }
+    throw new CliError(".corvio/state.json is invalid.", { code: "sync_state_invalid" });
+  }
+  if (state.version !== 1 || !state.source_id) {
+    throw new CliError(".corvio/state.json has an unsupported format.", { code: "sync_state_invalid" });
+  }
+  const requestedBase = baseUrl(options);
+  if (state.api_base && state.api_base !== requestedBase) {
+    throw new CliError(
+      `This directory belongs to ${state.api_base}; use the matching --api-base or reinitialize it.`,
+      { code: "sync_api_base_mismatch" },
+    );
+  }
+  return { root, state };
+}
+
+async function writeSyncState(root, state) {
+  const target = syncStatePath(root);
+  await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, target);
+}
+
+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" });
+  }
+  const target = resolve(root, ...parts);
+  if (target !== root && !target.startsWith(`${root}${sep}`)) {
+    throw new CliError(`Unsafe sync path returned by Corvio: ${relativePath}`, { code: "sync_path_unsafe" });
+  }
+  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 })) {
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        await walk(path);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+        const bytes = await readFile(path);
+        const info = await lstat(path);
+        manifest.push({
+          relative_path: relative(root, path).split(sep).join("/"),
+          content_sha256: sha256(bytes),
+          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",
+          });
+        }
+      }
+    }
+  }
+  await walk(mirror);
+  manifest.sort((left, right) => left.relative_path.localeCompare(right.relative_path));
+  return manifest;
+}
+
+async function syncManifest(root, state) {
+  const manifest = await scanMarkdown(root);
+  const mappings = Object.entries(state.mappings || {}).map(([pageId, mapping]) => ({ pageId, ...mapping }));
+  const pageByPath = new Map(mappings.map((mapping) => [mapping.relative_path, mapping.pageId]));
+  const presentPaths = new Set(manifest.map((item) => item.relative_path));
+  for (const item of manifest) {
+    const pageId = pageByPath.get(item.relative_path);
+    if (pageId) item.page_id = pageId;
+  }
+
+  // Treat a local move as the same Page only when the last-common hash gives
+  // one unambiguous missing-old-path -> new-path match. Duplicate content
+  // stays unbound and the server reports separate missing/new actions.
+  const unboundByHash = new Map();
+  for (const item of manifest.filter((candidate) => !candidate.page_id)) {
+    const values = unboundByHash.get(item.content_sha256) || [];
+    values.push(item);
+    unboundByHash.set(item.content_sha256, values);
+  }
+  const missingByHash = new Map();
+  for (const mapping of mappings.filter((candidate) => !presentPaths.has(candidate.relative_path))) {
+    const values = missingByHash.get(mapping.content_sha256) || [];
+    values.push(mapping);
+    missingByHash.set(mapping.content_sha256, values);
+  }
+  for (const [hash, items] of unboundByHash.entries()) {
+    const candidates = missingByHash.get(hash) || [];
+    if (items.length === 1 && candidates.length === 1) items[0].page_id = candidates[0].pageId;
+  }
+  return manifest;
+}
+
+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) },
+  });
+}
+
+async function syncCommand(options, action) {
+  const { api, selection } = await client(options);
+  if (action === "init") {
+    const root = syncRoot(options);
+    await mkdir(root, { recursive: true });
+    if (!options.force) {
+      try {
+        await readFile(syncStatePath(root), "utf8");
+        throw new CliError("This directory is already initialized; pass --force to bind it again.", {
+          code: "sync_already_initialized",
+        });
+      } catch (cause) {
+        if (cause instanceof CliError) throw cause;
+        if (cause?.code !== "ENOENT") throw cause;
+      }
+    }
+    const clientId = `corvio-cli-${randomUUID()}`;
+    const source = await api.request("/sync/sources", {
+      method: "POST",
+      body: {
+        root_node_id: option(options, "root-node-id", { required: true }),
+        folder_name: String(options.name || basename(root)),
+        client_id: clientId,
+      },
+    });
+    const state = {
+      version: 1,
+      source_id: source.id,
+      root_node_id: source.root_node_id,
+      workspace_id: source.workspace_id || selection?.workspaceId || null,
+      client_id: clientId,
+      api_base: baseUrl(options),
+      mirror_root_dir: source.mirror_root_dir || "corvio_docs",
+      mappings: {},
+      initialized_at: new Date().toISOString(),
+    };
+    await mkdir(join(root, state.mirror_root_dir), { recursive: true });
+    await writeSyncState(root, state);
+    return writeResult({ source, directory: root, state_file: syncStatePath(root) }, { json: options.json });
+  }
+
+  const { root, state } = await readSyncState(options);
+  if (state.workspace_id && selection?.workspaceId && state.workspace_id !== selection.workspaceId) {
+    throw new CliError(
+      `This sync directory belongs to Workspace ${state.workspace_id}; select it before syncing.`,
+      { code: "sync_workspace_mismatch" },
+    );
+  }
+  if (action === "status") {
+    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") {
+    return writeResult(await syncPlan(api, state, root), { json: options.json });
+  }
+  if (action === "pull") {
+    const plan = await syncPlan(api, state, root);
+    const conflicts = plan.actions.filter((item) => item.action === "conflict");
+    if (conflicts.length) {
+      throw new CliError("Sync has conflicts. Run `corvio sync plan --json` and resolve each conflict.", {
+        code: "sync_conflict",
+        exitCode: EXIT.CONFLICT,
+        details: { conflicts },
+      });
+    }
+    const committed = [];
+    const mappings = { ...(state.mappings || {}) };
+    for (const actionItem of plan.actions.filter((item) => item.action === "pull")) {
+      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);
+        } catch (cause) {
+          if (cause?.code !== "ENOENT") throw cause;
+        }
+      }
+      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: verified.contentHash,
+        mtime_ms: Math.trunc(info.mtimeMs),
+      });
+      mappings[item.page_id] = {
+        node_id: item.node_id,
+        relative_path: item.relative_path,
+        content_sha256: item.content_sha256,
+        content_revision: item.content_revision,
+      };
+    }
+    if (committed.length) {
+      await api.request("/sync/commit", {
+        method: "POST",
+        body: { source_id: state.source_id, items: committed },
+      });
+    }
+    state.mappings = mappings;
+    state.last_pull_at = new Date().toISOString();
+    await writeSyncState(root, state);
+    return writeResult({
+      pulled: committed.length,
+      unresolved_local_missing: plan.actions.filter((item) => item.action === "local_missing"),
+      directory: root,
+    }, { json: options.json });
+  }
+  if (action === "push") {
+    requireConfirmation(options, "Pushing local Markdown changes to Corvio");
+    const plan = await syncPlan(api, state, root);
+    const conflicts = plan.actions.filter((item) => item.action === "conflict");
+    if (conflicts.length) {
+      throw new CliError("Sync has conflicts. Resolve them before pushing.", {
+        code: "sync_conflict",
+        exitCode: EXIT.CONFLICT,
+        details: { conflicts },
+      });
+    }
+    const results = [];
+    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", {
+        method: "POST",
+        body: {
+          source_id: state.source_id,
+          relative_path: actionItem.relative_path,
+          markdown,
+          content_sha256: sha256(bytes),
+          mtime_ms: Math.trunc(info.mtimeMs),
+          page_id: actionItem.page_id || null,
+          expected_content_revision: previous?.content_revision ?? null,
+        },
+      });
+      results.push(result);
+      mappings[result.item.page_id] = {
+        node_id: result.item.node_id,
+        relative_path: result.item.relative_path,
+        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();
+    await writeSyncState(root, state);
+    return writeResult({
+      pushed: results.length,
+      results,
+      unresolved_local_missing: plan.actions.filter((item) => item.action === "local_missing"),
+    }, { json: options.json });
+  }
+  if (action === "resolve") {
+    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/${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 assertNoSyncSymlink(root, target);
+      const verified = verifiedRemoteMarkdown(item);
+      await writeTextFile(target, verified.markdown);
+      const info = await stat(target);
+      await api.request("/sync/commit", {
+        method: "POST",
+        body: {
+          source_id: state.source_id,
+          items: [{
+            page_id: item.page_id,
+            node_id: item.node_id,
+            relative_path: item.relative_path,
+            content_sha256: verified.contentHash,
+            mtime_ms: Math.trunc(info.mtimeMs),
+          }],
+        },
+      });
+      const result = await api.request(`/sync/conflicts/${resourcePath(conflictId)}:resolve`, {
+        method: "POST",
+        body: { strategy: "use_remote" },
+      });
+      state.mappings[item.page_id] = {
+        node_id: item.node_id,
+        relative_path: item.relative_path,
+        content_sha256: item.content_sha256,
+        content_revision: item.content_revision,
+      };
+      await writeSyncState(root, state);
+      return writeResult(result, { json: options.json });
+    }
+    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,
+          content_sha256: sha256(bytes),
+          mtime_ms: Math.trunc(info.mtimeMs),
+          page_id: conflict.remote?.page_id || null,
+          conflict_id: conflictId,
+        },
+      });
+      state.mappings[result.item.page_id] = {
+        node_id: result.item.node_id,
+        relative_path: result.item.relative_path,
+        content_sha256: result.item.content_sha256,
+        content_revision: result.item.content_revision,
+      };
+      await writeSyncState(root, state);
+      return writeResult(result, { json: options.json });
+    }
+    throw new CliError("--strategy must be use-remote or keep-local.", { code: "sync_strategy_invalid" });
+  }
+  throw new CliError("sync action must be init, status, plan, pull, push, or resolve.");
+}
+
 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);
     if (action === "status") return authStatus(options);
     if (action === "logout") return authLogout(options);
     throw new CliError("auth action must be login, status, or logout.");
   }
+  if (command === "workspaces" || command === "workspace") {
+    return workspaces(options, action || "list", id);
+  }
   if (command === "capabilities") return capabilities(options);
   if (command === "ask") return ask(options, [action, id, ...rest].filter(Boolean));
   if (command === "questions") return questions(options, action || "list", id);
   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 === "files" || command === "sync") {
-    throw new CliError(`${command} is not available until the public /v1 capability is released.`, {
-      code: `${command}_capability_unavailable`,
-      exitCode: EXIT.UNAVAILABLE,
-    });
-  }
+  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);
   throw new CliError(`Unknown command: ${command}`);
 }