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

package/README.md

@@ -4,9 +4,14 @@ Official CLI for a user's Corvio Workspace. It supports an existing `CORVIO_API_
 
 ```bash
 npm install --global @corvio/cli@beta
-export CORVIO_API_KEY='cvk_...'
+export CORVIO_API_KEY='cvu_...'
 corvio auth status
+corvio workspaces list
+corvio workspaces use <workspace_id>
 corvio ask --prompt 'Summarize recurring launch risks' --json
+corvio files upload --file ./research.pdf --json
+corvio sync init --dir ./knowledge --root-node-id <node_id> --json
+corvio update check --json
 ```
 
-When no environment key is configured, run `corvio auth login`. The environment key always takes precedence. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the supported command and receipt contract.
+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.

package/dist/cli.js

@@ -1,9 +1,15 @@
 #!/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,
+  clearWorkspaceContext,
   clearWorkspaceCredential,
   idempotencyKey,
   listOption,
@@ -12,16 +18,20 @@ 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.4";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -30,18 +40,24 @@ const HELP = `Corvio Workspace CLI ${VERSION}
 
 Usage:
   corvio auth login|status|logout
+  corvio workspaces list|use|current [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 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.
 `;
 
@@ -49,7 +65,23 @@ function baseUrl(options) {
   return normalizeApiBase(options["api-base"] || process.env.CORVIO_API_BASE, DEFAULT_API_BASE);
 }
 
-async function client(options, { auth = true } = {}) {
+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 +89,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 +132,10 @@ async function authLogin(options) {
         "documents:read",
         "documents:write",
         "documents:share",
+        "assets:read",
+        "assets:write",
+        "sync:read",
+        "sync:write",
       ],
     },
   });
@@ -127,7 +178,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 +191,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 +204,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 +225,80 @@ 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 });
+  }
+  throw new CliError("workspaces action must be list, use, or current.");
+}
+
 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.");
@@ -295,28 +411,530 @@ async function docs(options, action, id) {
   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) } });
+  } else if (action === "get") {
+    result = await api.request(`/files/${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 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" });
+    const bytes = await readFile(input);
+    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 || {} });
+    result = await api.request("/files/uploads:finalize", {
+      method: "POST",
+      body: {
+        upload_id: initialized.upload_id,
+        blob_name: initialized.blob_name,
+        file_name: fileName,
+        mime_type: mimeType,
+        size_bytes: bytes.length,
+      },
+    });
+  } else if (action === "organize") {
+    requireConfirmation(options, "Starting a file organization run");
+    result = await api.request(`/files/${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/${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.");
+  }
+  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) {
+  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 scanMarkdown(root) {
+  const mirror = join(root, "corvio_docs");
+  await mkdir(mirror, { recursive: true });
+  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),
+        });
+      }
+    }
+  }
+  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",
+    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/${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);
+      const previous = mappings[item.page_id];
+      if (previous?.relative_path && previous.relative_path !== item.relative_path) {
+        const oldTarget = localSyncPath(root, previous.relative_path);
+        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, item.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,
+        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);
+      const bytes = await readFile(path);
+      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: bytes.toString("utf8"),
+          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);
+    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/${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 || "");
+      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: item.content_sha256,
+            mtime_ms: Math.trunc(info.mtimeMs),
+          }],
+        },
+      });
+      const result = await api.request(`/sync/conflicts/${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);
+      const bytes = await readFile(target);
+      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"),
+          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 (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 === "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}`);
 }
 

package/dist/core.js

@@ -105,10 +105,92 @@ export function normalizeApiBase(value, fallback) {
   return raw.endsWith("/v1") ? raw : `${raw}/v1`;
 }
 
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map((item) => Number.parseInt(item, 10)),
+    pre: match[4] ? match[4].split(".") : [],
+  };
+}
+
+export function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1;
+  }
+  if (a.pre.length === 0 && b.pre.length > 0) return 1;
+  if (b.pre.length === 0 && a.pre.length > 0) return -1;
+  for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+    if (a.pre[index] === undefined) return -1;
+    if (b.pre[index] === undefined) return 1;
+    if (a.pre[index] === b.pre[index]) continue;
+    const aNumber = /^\d+$/.test(a.pre[index]) ? Number.parseInt(a.pre[index], 10) : null;
+    const bNumber = /^\d+$/.test(b.pre[index]) ? Number.parseInt(b.pre[index], 10) : null;
+    if (aNumber !== null && bNumber !== null) return aNumber > bNumber ? 1 : -1;
+    if (aNumber !== null) return -1;
+    if (bNumber !== null) return 1;
+    return a.pre[index] > b.pre[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+export async function resolveNpmUpdateStatus({
+  currentVersion,
+  policy,
+  userAgent,
+  allowRegistryFailure = false,
+  fetchImpl = globalThis.fetch,
+  registryBase = process.env.CORVIO_NPM_REGISTRY_BASE || "https://registry.npmjs.org",
+}) {
+  const packageName = String(policy?.package || "").trim();
+  const distTag = String(policy?.dist_tag || "beta").trim();
+  if (!packageName) throw new CliError("The API did not advertise an npm package.", { code: "update_policy_invalid" });
+  const encoded = encodeURIComponent(packageName).replace("%40", "@");
+  let latestVersion = null;
+  let registryError = null;
+  try {
+    const registry = String(registryBase).replace(/\/+$/, "");
+    const response = await fetchImpl(`${registry}/${encoded}`, {
+      headers: { accept: "application/json", "user-agent": userAgent },
+      signal: AbortSignal.timeout(2500),
+    });
+    if (!response.ok) throw new Error(`npm registry returned ${response.status}`);
+    const metadata = await response.json();
+    latestVersion = String(metadata?.["dist-tags"]?.[distTag] || "").trim() || null;
+  } catch (error) {
+    registryError = error instanceof Error ? error.message : String(error);
+    if (!allowRegistryFailure) {
+      throw new CliError(`Unable to check npm for updates: ${registryError}`, {
+        code: "update_check_failed",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+  }
+  const minimum = String(policy.minimum_supported_version || "").trim() || null;
+  return {
+    package: packageName,
+    channel: String(policy.channel || distTag),
+    dist_tag: distTag,
+    current_version: currentVersion,
+    latest_published_version: latestVersion,
+    reviewed_version: String(policy.reviewed_version || "").trim() || null,
+    minimum_supported_version: minimum,
+    update_available: Boolean(latestVersion && compareVersions(latestVersion, currentVersion) > 0),
+    supported: minimum ? compareVersions(currentVersion, minimum) >= 0 : true,
+    install_command: String(policy.install_command || `npm install --global ${packageName}@${distTag}`),
+    automatic_install: false,
+    ...(registryError ? { registry_error: registryError } : {}),
+  };
+}
+
 export class ApiClient {
-  constructor({ baseUrl, credential = null, userAgent, fetchImpl = globalThis.fetch }) {
+  constructor({ baseUrl, credential = null, workspaceId = null, userAgent, fetchImpl = globalThis.fetch }) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.credential = credential;
+    this.workspaceId = String(workspaceId || "").trim() || null;
     this.userAgent = userAgent;
     this.fetchImpl = fetchImpl;
   }
@@ -129,6 +211,10 @@ export class ApiClient {
         throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
       }
       requestHeaders.authorization = `Bearer ${this.credential}`;
+      if (this.workspaceId) {
+        requestHeaders["X-Corvio-Workspace-Id"] = this.workspaceId;
+        requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
+      }
     }
     let response;
     try {
@@ -179,6 +265,10 @@ export class ApiClient {
         throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
       }
       requestHeaders.authorization = `Bearer ${this.credential}`;
+      if (this.workspaceId) {
+        requestHeaders["X-Corvio-Workspace-Id"] = this.workspaceId;
+        requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
+      }
     }
     let response;
     try {
@@ -208,6 +298,31 @@ export class ApiClient {
     }
     return bytes;
   }
+
+  async putUrl(url, content, { headers = {} } = {}) {
+    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,
+      });
+    }
+    if (!response.ok) {
+      const message = (await response.text()).slice(0, 500);
+      throw new CliError(message || `File upload failed (${response.status}).`, {
+        code: "upload_failed",
+        status: response.status,
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    return { ok: true, status: response.status };
+  }
 }
 
 function configRoot(env = process.env) {
@@ -220,6 +335,10 @@ export function workspaceCredentialPath(env = process.env) {
   return join(configRoot(env), "credentials.json");
 }
 
+export function workspaceContextPath(env = process.env) {
+  return join(configRoot(env), "workspace-context.json");
+}
+
 export function adminCredentialPath(env = process.env) {
   return join(configRoot(env), "admin-credentials.json");
 }
@@ -227,8 +346,8 @@ export function adminCredentialPath(env = process.env) {
 export async function readWorkspaceCredential(env = process.env) {
   const environmentKey = String(env.CORVIO_API_KEY || "").trim();
   if (environmentKey) {
-    if (!environmentKey.startsWith("cvk_")) {
-      throw new CliError("CORVIO_API_KEY must be a Workspace cvk_ key.", {
+    if (!environmentKey.startsWith("cvu_") && !environmentKey.startsWith("cvk_")) {
+      throw new CliError("CORVIO_API_KEY must be a user cvu_ key or legacy Workspace cvk_ key.", {
         code: "invalid_workspace_key",
         exitCode: EXIT.AUTH,
       });
@@ -245,14 +364,15 @@ export async function readWorkspaceCredential(env = process.env) {
   }
   const profileName = String(parsed.active_profile || "default");
   const profile = parsed.profiles?.[profileName];
-  const key = String(profile?.api_key || "").trim();
-  if (!key.startsWith("cvk_")) {
+  const metadata = String(parsed.api_key || "").trim() ? parsed : profile;
+  const key = String(metadata?.api_key || "").trim();
+  if (!key.startsWith("cvu_") && !key.startsWith("cvk_")) {
     throw new CliError("Stored Corvio credentials are invalid; run `corvio auth login` again.", {
       code: "credential_store_invalid",
       exitCode: EXIT.AUTH,
     });
   }
-  return { key, source: "device_link", profile: profileName, metadata: profile };
+  return { key, source: "device_link", profile: profileName, metadata };
 }
 
 export async function storeWorkspaceCredential(payload, env = process.env) {
@@ -260,28 +380,73 @@ export async function storeWorkspaceCredential(payload, env = process.env) {
   const root = dirname(path);
   await mkdir(root, { recursive: true, mode: 0o700 });
   await chmod(root, 0o700).catch(() => {});
-  const profileName = String(payload.workspace_id || "default");
+  const document = {
+    version: 2,
+    api_key: payload.secret,
+    key_id: payload.key_id,
+    audience: payload.audience || "user",
+    scopes: payload.scopes || [],
+    expires_at: payload.expires_at || null,
+    created_at: payload.created_at || new Date().toISOString(),
+    source: "device_link",
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path, profile: "default" };
+}
+
+export async function readWorkspaceContext(env = process.env) {
+  const environmentWorkspaceId = String(env.CORVIO_WORKSPACE_ID || "").trim();
+  if (environmentWorkspaceId) {
+    return { workspaceId: environmentWorkspaceId, workspaceName: null, source: "environment" };
+  }
+  const path = workspaceContextPath(env);
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const workspaceId = String(parsed.active_workspace_id || "").trim();
+    if (!workspaceId) return null;
+    return {
+      workspaceId,
+      workspaceName: String(parsed.active_workspace_name || "").trim() || null,
+      source: "stored",
+    };
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio Workspace selection is unreadable.", {
+      code: "workspace_context_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+}
+
+export async function storeWorkspaceContext({ workspaceId, workspaceName = null }, env = process.env) {
+  const normalizedId = String(workspaceId || "").trim();
+  if (!normalizedId) throw new CliError("Workspace ID is required.", { code: "workspace_selection_required" });
+  const path = workspaceContextPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
   const document = {
     version: 1,
-    active_profile: profileName,
-    profiles: {
-      [profileName]: {
-        api_key: payload.secret,
-        key_id: payload.key_id,
-        workspace_id: payload.workspace_id,
-        workspace_name: payload.workspace_name,
-        scopes: payload.scopes || [],
-        created_at: payload.created_at || new Date().toISOString(),
-        source: "device_link",
-      },
-    },
+    active_workspace_id: normalizedId,
+    active_workspace_name: String(workspaceName || "").trim() || null,
+    updated_at: new Date().toISOString(),
   };
   const temporary = `${path}.${randomUUID()}.tmp`;
   await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
   await chmod(temporary, 0o600);
   await rename(temporary, path);
   await chmod(path, 0o600);
-  return { path, profile: profileName };
+  return { path, workspaceId: normalizedId };
+}
+
+export async function clearWorkspaceContext(env = process.env) {
+  const path = workspaceContextPath(env);
+  await rm(path, { force: true });
+  return path;
 }
 
 export async function clearWorkspaceCredential(env = process.env) {
@@ -388,13 +553,24 @@ 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];
-  try {
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
-    child.unref();
-    return true;
-  } catch {
-    return false;
-  }
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (settled) return;
+      settled = true;
+      resolvePromise(opened);
+    };
+    try {
+      const child = spawn(command, args, { detached: true, stdio: "ignore" });
+      child.once("error", () => finish(false));
+      child.once("spawn", () => {
+        child.unref();
+        finish(true);
+      });
+    } catch {
+      finish(false);
+    }
+  });
 }
 
 export async function sleep(milliseconds) {

package/package.json

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