@corvio/cli 0.1.0-beta.26 → 0.1.0-beta.28

package/README.md

@@ -15,13 +15,13 @@ corvio files get <asset_id> --content --json
 corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --json
 corvio files operation <operation_id> --json
 corvio files resume <operation_id> --yes --json
-corvio docs table-read <document_id> --limit 25 --json
-corvio docs table-mutate <document_id> --input ./table-change.json --change-summary 'Updated owner and due date' --yes --json
+corvio docs table-read <workspace_id/document_id> --limit 25 --json
+corvio docs table-mutate <workspace_id/document_id> --input ./table-change.json --change-summary 'Updated owner and due date' --yes --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`. Login creates one user-level `cvu_` control-plane credential; it does not freeze the browser's current Workspace. Run `corvio agents connect --project .` from the project you want to expose. The command verifies the selected Codex, Claude Code, or Copilot host before server mutation, then idempotently creates or restores the Agent for that provider/device/project binding, grants current/future Workspace coverage under live membership/role and ACL limits, saves the one-time `cvg_` in a `0600` multi-binding registry, and starts that project's listener. `corvio collaboration status` then checks local foreground prerequisites and reports package freshness, contract compatibility, installation ownership, every discoverable copy, and the fact that host loading is not observable. A listener receives inbound `@Agent` work; it does not make an unrelated foreground coding session collaborate automatically. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory, then a locally confirmed selection, the account selection, the personal default, or one authorized candidate. They ask only on real ambiguity. Use `corvio workspaces use`, `--workspace`, and `--agent` as explicit routing/reproducibility controls. Legacy Workspace-bound `cvk_`, `cvg_`, and version-1 credential files remain compatible and are never widened. 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.
+When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` control-plane credential; it does not freeze the browser's current Workspace. Run `corvio agents connect --project .` from the project you want to expose. The command verifies the selected Codex, Claude Code, or Copilot host before server mutation, then idempotently creates or restores the Agent for that provider/device/project binding, grants current/future Workspace coverage under live membership/role and ACL limits, saves the one-time `cvg_` in a `0600` multi-binding registry, and starts that project's listener. `corvio collaboration status` then checks local foreground prerequisites and reports package freshness, contract compatibility, installation ownership, every discoverable copy, and the fact that host loading is not observable. A listener receives inbound `@Agent` work; it does not make an unrelated foreground coding session collaborate automatically. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory, then a locally confirmed selection, the account selection, the personal default, or one authorized candidate. They ask only on real ambiguity. Use `corvio workspaces use`, `--workspace`, and `--agent` as explicit routing/reproducibility controls. Legacy Workspace-bound `cvk_`, `cvg_`, and version-1 credential files remain compatible and are never widened. 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. `corvio capabilities` reads only Corvio API capability and compatibility facts, so discovery remains usable in hosts that deny npm registry access. `corvio update check` is the explicit registry-backed version check; it never self-installs. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the full command and receipt contract.
 
 CLI and Skill updates are independent. `corvio update check` checks the CLI package only. `corvio collaboration status` detects a missing,
 incompatible, compatible-but-not-current, or conflicting local Skill, but never mutates host directories. Use
@@ -32,7 +32,7 @@ fresh host session. Until a reviewed WorkBuddy marketplace listing is live, a Wo
 auto-update from Corvio. Remote MCP changes are server-delivered and normally need only a refreshed host session unless new OAuth scopes
 require reauthorization.
 
-The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document updates preflight the current revision when `--expected-revision` is omitted. `docs table-read` returns a bounded stable-ID projection; `docs table-mutate` accepts a JSON payload for at most 50 cell updates or row appends and requires the fetched revision, while formulas, styles, structure, sorting, and semantic transformations remain `corvio ask --allow-actions` work. When the executing principal is a connected Agent, document and table mutations also require `--change-summary`, create a visible document-level comment after the guarded update, and return its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use `corvio agent closeout` to return the verified outcome, optionally resolve the thread, and read both document and thread back. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
+The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document commands accept both bare document IDs and canonical `workspace_id/document_id` handles; a canonical handle that disagrees with the selected Workspace fails before remote access, and successful reads return `canonical_id` for direct reuse. Document updates preflight the current revision when `--expected-revision` is omitted. `docs table-read` returns a bounded stable-ID projection; `docs table-mutate` accepts a JSON payload for at most 50 cell updates or row appends and requires the fetched revision, while formulas, styles, structure, sorting, and semantic transformations remain `corvio ask --allow-actions` work. When the executing principal is a connected Agent, document and table mutations also require `--change-summary`, create a visible document-level comment after the guarded update, and return its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use `corvio agent closeout` to return the verified outcome, optionally resolve the thread, and read both document and thread back. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
 
 For `corvio ask`, pass the user's natural goal, complete decision-relevant context, and explicit constraints. Unless the user chose them,
 do not invent taxonomy, titles, artifact counts, or Corvio's internal plan. Read the terminal Question receipt and use `artifact.url` or

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.26";
+const VERSION = "0.1.0-beta.28";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -189,8 +189,11 @@ const COMMAND_HELP = Object.freeze({
 
 function contextualHelp(command, action) {
   const normalizedCommand = command === "workspace" ? "workspaces" : command === "folders" ? "projects" : command;
-  const commandHelp = COMMAND_HELP[normalizedCommand];
-  if (!commandHelp) return HELP.trimEnd();
+  const baseCommandHelp = COMMAND_HELP[normalizedCommand];
+  if (!baseCommandHelp) return HELP.trimEnd();
+  const commandHelp = normalizedCommand === "docs"
+    ? `${baseCommandHelp}\n\nDocument commands accept either a bare document ID or the canonical workspace_id/document_id handle returned by Corvio. A canonical handle that disagrees with the selected Workspace fails before any remote request. Document reads return canonical_id for direct reuse.`
+    : baseCommandHelp;
   if (!action) return commandHelp;
   const matchingLine = commandHelp
     .split("\n")
@@ -277,6 +280,53 @@ function resourcePath(value) {
   return encodeURIComponent(String(value));
 }
 
+function resolveDocumentId(value, selection) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    throw new CliError("Provide a document ID or canonical workspace/document handle.", {
+      code: "document_id_required",
+    });
+  }
+  const handle = raw.startsWith("document:") ? raw.slice("document:".length) : raw;
+  if (!handle.includes("/")) return handle;
+  const parts = handle.split("/");
+  if (parts.length !== 2 || parts.some((part) => !part.trim())) {
+    throw new CliError(
+      "Document handles must be a document ID or canonical workspace_id/document_id pair.",
+      { code: "document_handle_invalid" },
+    );
+  }
+  const [workspaceId, documentId] = parts.map((part) => part.trim());
+  if (!selection?.workspaceId) {
+    throw new CliError(
+      "A canonical document handle requires an explicit or resolved Workspace route.",
+      { code: "document_workspace_route_unavailable", exitCode: EXIT.AUTH },
+    );
+  }
+  if (selection?.workspaceId && workspaceId !== selection.workspaceId) {
+    throw new CliError(
+      `The document handle belongs to Workspace ${workspaceId}, but the current route is ${selection.workspaceId}.`,
+      {
+        code: "document_workspace_mismatch",
+        exitCode: EXIT.AUTH,
+        details: {
+          handle_workspace_id: workspaceId,
+          selected_workspace_id: selection.workspaceId,
+        },
+      },
+    );
+  }
+  return documentId;
+}
+
+function withCanonicalDocumentId(value, selection, fallbackDocumentId = null) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const workspaceId = String(selection?.workspaceId || "").trim();
+  const documentId = String(fallbackDocumentId || value.id || "").trim();
+  if (!workspaceId || !documentId) return value;
+  return { ...value, canonical_id: `${workspaceId}/${documentId}` };
+}
+
 function safeRemoteFileName(value, fallback) {
   const normalized = String(value || "").replaceAll("\\", "/");
   const name = basename(normalized).trim();
@@ -699,7 +749,10 @@ async function capabilities(options) {
     workspace_selection: selection,
     api: index,
     principal: identity,
-    update: await buildUpdateStatus(index, { allowRegistryFailure: true }),
+    update: await buildUpdateStatus(index, {
+      allowRegistryFailure: true,
+      checkRegistry: false,
+    }),
   }, { json: options.json });
 }
 
@@ -2821,7 +2874,7 @@ async function search(options, positionals) {
 }
 
 async function docs(options, action, id) {
-  const { api, executionIdentity } = await executionClient(options);
+  const { api, executionIdentity, selection } = await executionClient(options);
   const documentId = id || options.id;
   let result;
   if (action === "list") {
@@ -2830,8 +2883,19 @@ async function docs(options, action, id) {
       throw new CliError("--lifecycle must be active or archived.", { code: "document_lifecycle_invalid" });
     }
     result = await api.request("/documents", { query: { ...pageQuery(options), lifecycle } });
+    if (Array.isArray(result?.data)) {
+      result = {
+        ...result,
+        data: result.data.map((item) => withCanonicalDocumentId(item, selection)),
+      };
+    }
   } else if (action === "get") {
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`);
+    const targetId = resolveDocumentId(documentId, selection);
+    result = withCanonicalDocumentId(
+      await api.request(`/documents/${resourcePath(targetId)}`),
+      selection,
+      targetId,
+    );
     if (executionIdentity === "agent") {
       result = {
         ...result,
@@ -2843,7 +2907,7 @@ async function docs(options, action, id) {
       result = { ...result, output: options.output };
     }
   } else if (action === "table-read") {
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     result = await api.request(`/documents/${resourcePath(targetId)}/table`, {
       query: {
         table_id: options["table-id"] || undefined,
@@ -2853,7 +2917,7 @@ async function docs(options, action, id) {
     });
   } else if (action === "table-mutate") {
     requireConfirmation(options, "Mutating a document table");
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     const payload = await readJsonObject(option(options, "input", { required: true }), "--input");
     const changeSummary = String(options["change-summary"] || "").trim();
     if (executionIdentity === "agent" && !changeSummary) {
@@ -2931,7 +2995,7 @@ async function docs(options, action, id) {
         code: "document_update_empty",
       });
     }
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     const changeSummary = String(options["change-summary"] || "").trim();
     if (executionIdentity === "agent" && !changeSummary) {
       throw new CliError(
@@ -3005,7 +3069,8 @@ async function docs(options, action, id) {
     }
   } 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 }))}`);
+    const targetId = resolveDocumentId(documentId, selection);
+    const current = await api.request(`/documents/${resourcePath(targetId)}`);
     result = await api.request(`/nodes/${resourcePath(current.node_id)}:move`, {
       method: "POST",
       headers: { "idempotency-key": idempotencyKey(options) },
@@ -3017,25 +3082,31 @@ async function docs(options, action, id) {
     });
   } else if (action === "archive") {
     requireConfirmation(options, "Archiving a document");
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}`, { method: "DELETE" });
+    const targetId = resolveDocumentId(documentId, selection);
+    result = await api.request(`/documents/${resourcePath(targetId)}`, { method: "DELETE" });
   } else if (action === "restore") {
     requireConfirmation(options, "Restoring an archived document");
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}/restore`, { method: "POST", retrySafe: true });
+    const targetId = resolveDocumentId(documentId, selection);
+    result = await api.request(`/documents/${resourcePath(targetId)}/restore`, { method: "POST", retrySafe: true });
   } else if (action === "share") {
     requireConfirmation(options, "Creating a document share link");
-    result = await api.request(`/documents/${resourcePath(documentId || option(options, "id", { required: true }))}/shares`, {
+    const targetId = resolveDocumentId(documentId, selection);
+    result = await api.request(`/documents/${resourcePath(targetId)}/shares`, {
       method: "POST",
       retrySafe: true,
       body: { public_display_name: options["display-name"] || null },
     });
   } else if (action === "open") {
-    const targetId = documentId || option(options, "id", { required: true });
+    const targetId = resolveDocumentId(documentId, selection);
     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: targetId, url: target, opened };
   } else {
     throw new CliError("docs action must be list, get, table-read, table-mutate, create, update, move, archive, restore, share, or open.");
   }
+  if (!new Set(["list", "create"]).has(action)) {
+    result = withCanonicalDocumentId(result, selection, resolveDocumentId(documentId, selection));
+  }
   writeResult(result, { json: options.json });
 }
 
@@ -3056,7 +3127,10 @@ async function projects(options, action) {
   writeResult(result, { json: options.json });
 }
 
-async function buildUpdateStatus(index, { allowRegistryFailure = false } = {}) {
+async function buildUpdateStatus(
+  index,
+  { allowRegistryFailure = false, checkRegistry = true } = {},
+) {
   return resolveNpmUpdateStatus({
     currentVersion: VERSION,
     policy: index?.distribution?.workspace_cli || {
@@ -3065,6 +3139,7 @@ async function buildUpdateStatus(index, { allowRegistryFailure = false } = {}) {
     },
     userAgent: USER_AGENT,
     allowRegistryFailure,
+    checkRegistry,
   });
 }
 

package/dist/core.js

@@ -244,6 +244,7 @@ export async function resolveNpmUpdateStatus({
   policy,
   userAgent,
   allowRegistryFailure = false,
+  checkRegistry = true,
   fetchImpl = globalThis.fetch,
   registryBase = process.env.CORVIO_NPM_REGISTRY_BASE || "https://registry.npmjs.org",
 }) {
@@ -253,22 +254,24 @@ export async function resolveNpmUpdateStatus({
   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,
+  if (checkRegistry) {
+    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;
@@ -278,6 +281,7 @@ export async function resolveNpmUpdateStatus({
     dist_tag: distTag,
     current_version: currentVersion,
     latest_published_version: latestVersion,
+    registry_checked: checkRegistry,
     reviewed_version: String(policy.reviewed_version || "").trim() || null,
     minimum_supported_version: minimum,
     update_available: Boolean(latestVersion && compareVersions(latestVersion, currentVersion) > 0),

package/package.json

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