@corvio/cli 0.1.0-beta.25 → 0.1.0-beta.27

package/README.md

@@ -15,8 +15,8 @@ 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
 ```
@@ -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.25";
+const VERSION = "0.1.0-beta.27";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -180,8 +180,8 @@ const COMMAND_HELP = Object.freeze({
   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>] [--lifecycle active|archived]\n  corvio docs get <id> [--output <path>]\n  corvio docs table-read <id> [--table-id <id>] [--after-row-id <id>] [--limit <1-100>]\n  corvio docs table-mutate <id> --input <json> --yes [--operation-id <id>] [--change-summary <text>]\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>] [--change-summary <text>]\n  corvio docs move <id> --parent-node-id <id>\n  corvio docs archive <id> --yes\n  corvio docs restore <id> --yes\n  corvio docs share <id> --yes [--display-name <name>]\n  corvio docs open <id>\n\nA selected Markdown file is uploaded once as a provenance-preserving Asset, then its source_asset_id becomes an editable Page without resending the body; inspect the returned document ID, node ID, revision, and URL. Other formats or semantic restructuring belong to \`corvio files organize\` or \`corvio ask --allow-actions\`. \`docs update\` replaces the Page body: use it only when whole-body replacement is the smallest faithful change; delegate large localized semantic edits, reorder, splice, or formatting to \`corvio ask --allow-actions\` with the canonical document handle. Use table-read plus table-mutate for bounded stable-ID cell updates or row appends without round-tripping a whole document. Agent-authenticated document changes require --change-summary and create a visible document-level comment after the guarded update. When a document/comment is the task owner, use \`corvio agent closeout\` to return verified work to that same collaboration surface and read it back.`,
-  projects: `Usage:\n  corvio projects list [--limit <n>]\n  corvio projects create --title <title> [--idempotency-key <key>]\n\nProjects are durable grouping owners in the Corvio Docs tree. Reuse a matching Project instead of creating one ceremonial Project per file. 'corvio folders' is an alias.`,
+  docs: `Usage:\n  corvio docs list [--limit <n>] [--cursor <cursor>] [--lifecycle active|archived]\n  corvio docs get <id> [--output <path>]\n  corvio docs table-read <id> [--table-id <id>] [--after-row-id <id>] [--limit <1-100>]\n  corvio docs table-mutate <id> --input <json> --yes [--operation-id <id>] [--change-summary <text>]\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>] [--change-summary <text>]\n  corvio docs move <id> --parent-node-id <id>\n  corvio docs archive <id> --yes\n  corvio docs restore <id> --yes\n  corvio docs share <id> --yes [--display-name <name>]\n  corvio docs open <id>\n\nA selected Markdown file is uploaded once as a provenance-preserving Asset, then its source_asset_id becomes an editable Page without resending the body; inspect the returned document ID, node ID, revision, and URL. Other formats or semantic restructuring belong to \`corvio files organize\` or \`corvio ask --allow-actions\`. \`docs update\` replaces the Page body: use it only when whole-body replacement is the smallest faithful change; delegate large localized semantic edits, reorder, splice, or formatting to \`corvio ask --allow-actions\` with the canonical document handle. Use table-read plus table-mutate for bounded stable-ID cell updates or row appends without round-tripping a whole document. \`docs move\` accepts a non-Project document and a Project destination; Projects stay at the Workspace root and cannot be nested. Use \`corvio files organize\` or \`corvio ask --allow-actions\` when deeper structure needs semantic branch Pages and leaves. Agent-authenticated document changes require --change-summary and create a visible document-level comment after the guarded update. When a document/comment is the task owner, use \`corvio agent closeout\` to return verified work to that same collaboration surface and read it back.`,
+  projects: `Usage:\n  corvio projects list [--limit <n>]\n  corvio projects create --title <title> [--idempotency-key <key>]\n\nProjects are durable root-level grouping owners in the Corvio Docs tree and cannot be nested under another Project. Reuse a matching Project instead of creating one ceremonial Project per file; use semantic branch Pages and leaves for deeper Work Models. 'corvio folders' is an alias.`,
   files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id> [--content]\n  corvio files download <id> [--output <path>]\n  corvio files upload --file <path> [--mime-type <type>] [--organize --instruction <text> --additional-asset-ids <id,id> --yes]\n  corvio files organize <id> --instruction <text> --yes [--additional-asset-ids <id,id>] [--processing-profile auto|economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off]\n  corvio files operation <operation-id>\n  corvio files resume <operation-id> --yes\n  corvio files cancel <operation-id> --yes\n  corvio files open <id>\n\nUse --content only when source facts are needed. It returns one bounded AI-safe projection with hash, completeness, and truncation receipts; it does not rewrite or materialize the original. Upload alone preserves the exact original, provenance, hash, policy, and stable Asset ID. Organization is a separate asynchronous value step: one coherent source set can produce reader-facing structure, source reconciliation, Memory candidates, and qualifying Project Skills. Pass --instruction a weak natural goal plus explicit user constraints and only authority facts needed to prevent wrong identity or scope. Keep source-derived facts in the source; do not precompute an outline, edit checklist, taxonomy, titles, artifact count, or sole leaf target from current visibility. For a newly finalized Asset that should enter a Work Model or Skill evaluation, use organize directly instead of duplicate ask requests just to await processing. Use 'files operation' to reach terminal and inspect output_document plus skills_evaluation; always requires evaluation but may correctly return evaluated_no_qualifying_skill. Resume reuses the same durable operation after resolving its blocker; cancel is idempotent.`,
   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.`,
@@ -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();
@@ -2821,7 +2871,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 +2880,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 +2904,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 +2914,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 +2992,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 +3066,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 +3079,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 });
 }
 

package/package.json

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