@corvio/cli 0.1.0-beta.33 → 0.1.0-beta.35

package/README.md

@@ -15,6 +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 read <workspace_id/document_id> --mode auto --json
+corvio docs patch <workspace_id/document_id> --input ./patch.json --operation-id <id> --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
@@ -34,7 +36,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 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.
+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. `docs read --mode auto` returns a complete small Page or a large-Page overview, then supports exact section, line-range, literal-search, and full projections. `docs patch` applies 1–20 exact non-overlapping L# replacements at the fetched revision and returns a compact readback instead of replaying untouched content. `docs get --output` keeps compatibility full-body download but omits the body from stdout; create/update request compact mutation receipts. Document updates preflight only a bounded overview for 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.33";
+const VERSION = "0.1.0-beta.35";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -104,6 +104,11 @@ const COMMAND_OPTIONS = Object.freeze({
   "search:": ["query", "limit", "page-id", "node-id"],
   "docs:list": ["limit", "cursor", "lifecycle"],
   "docs:get": ["id", "output"],
+  "docs:read": [
+    "id", "mode", "start-line", "end-line", "section-ref", "heading", "query",
+    "max-chars", "max-sections", "context-lines", "max-matches", "case-sensitive",
+  ],
+  "docs:patch": ["id", "input", "operation-id", "change-summary", "yes"],
   "docs:table-read": ["id", "table-id", "after-row-id", "limit"],
   "docs:table-mutate": ["id", "input", "operation-id", "change-summary", "yes"],
   "docs:create": ["title", "file", "markdown", "parent-node-id", "idempotency-key"],
@@ -152,7 +157,7 @@ Usage:
   corvio questions list|get [id]
   corvio conversations list|get [id]
   corvio search <query>
-  corvio docs list|get|table-read|table-mutate|create|update|move|archive|restore|share|open [id]
+  corvio docs list|get|read|patch|table-read|table-mutate|create|update|move|archive|restore|share|open [id]
   corvio projects list|create
   corvio files list|get|download|upload|organize|operation|resume|cancel|open [id]
   corvio sync init|status|plan|pull|push|resolve
@@ -181,9 +186,9 @@ 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 a non-Project Page body: use it only when whole-body replacement is the smallest faithful change. A Project is a structure container, so direct body replacement returns \`project_structure_container_body_write_disabled\`; use \`files organize\` or \`ask --allow-actions\` for Work Model maintenance, or update a child Page. A title-only Project rename remains valid. 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.`,
+  docs: `Usage:\n  corvio docs list [--limit <n>] [--cursor <cursor>] [--lifecycle active|archived]\n  corvio docs get <id> [--output <path>]\n  corvio docs read <id> [--mode auto|overview|line-range|section|search|full] [--start-line <n> --end-line <n>|--section-ref <S#>|--query <text>] [--max-chars <n>]\n  corvio docs patch <id> --input <json> --yes [--operation-id <id>] [--change-summary <text>]\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\nUse \`docs read --mode auto\` first for a small full body or a large-document overview, then read an exact section or line range. Use \`docs patch\` when the host already knows 1-20 exact L# replacements; it preserves untouched lines and returns a compact verified delta. A selected Markdown file can become an editable Page without resending the body through the model. Use \`docs update\` only when whole-body replacement is the smallest faithful change. Delegate document-wide judgment, cross-source synthesis, structure/formatting interpretation, and typed Spreadsheet, Presentation, Code, or HTML work to \`corvio ask --allow-actions\`. A Project is a structure container; body writes fail with project_structure_container_body_write_disabled, while a title-only Project rename remains valid. Projects stay at the Workspace root and cannot be nested; use \`files organize\` or \`ask --allow-actions\` for Work Model maintenance. Use table-read plus table-mutate for bounded stable-ID cell updates or row appends. 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>] [--target-root-node-id <project-node-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 one organize operation as the sole semantic owner; do not open ask before or after it for the same Asset set. --target-root-node-id is optional and accepts only a Project node_id returned by projects list, never a Page/document UUID or leaf node; omit it when the Project is not known. 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.`,
+  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>] [--target-root-node-id <project-node-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. A heterogeneous source may update several real Projects while its provenance carrier stays a standalone document; do not direct Corvio to make the source Page an umbrella Project. For a newly finalized Asset that should enter a Work Model or Skill evaluation, use one organize operation as the sole semantic owner; do not open ask before or after it for the same Asset set. --target-root-node-id is optional and accepts only a Project node_id returned by projects list, never a Page/document UUID or leaf node; omit it when the Project is not known. 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.`,
 });
@@ -238,6 +243,8 @@ function validateInvocation(options, positionals) {
       "questions:get",
       "conversations:get",
       "docs:get",
+      "docs:read",
+      "docs:patch",
       "docs:table-read",
       "docs:table-mutate",
       "docs:update",
@@ -2977,8 +2984,108 @@ async function docs(options, action, id) {
       };
     }
     if (options.output) {
-      await writeTextFile(options.output, String(result.markdown || ""));
-      result = { ...result, output: options.output };
+      const markdown = String(result.markdown || "");
+      await writeTextFile(options.output, markdown);
+      const { markdown: _omittedMarkdown, ...metadata } = result;
+      result = {
+        ...metadata,
+        output: options.output,
+        body_returned: false,
+        written_chars: markdown.length,
+        content_sha256: createHash("sha256").update(markdown).digest("hex"),
+      };
+    }
+  } else if (action === "read") {
+    const targetId = resolveDocumentId(documentId, selection);
+    const mode = String(options.mode || "auto").trim().toLowerCase().replaceAll("-", "_");
+    if (!new Set(["auto", "overview", "line_range", "section", "search", "full"]).has(mode)) {
+      throw new CliError("--mode must be auto, overview, line-range, section, search, or full.", {
+        code: "document_read_mode_invalid",
+      });
+    }
+    result = await api.request(`/documents/${resourcePath(targetId)}/content`, {
+      query: {
+        mode,
+        start_line: options["start-line"] === undefined
+          ? undefined
+          : numberOption(options, "start-line", undefined, { minimum: 1, maximum: 2_000_000 }),
+        end_line: options["end-line"] === undefined
+          ? undefined
+          : numberOption(options, "end-line", undefined, { minimum: 1, maximum: 2_000_000 }),
+        section_ref: options["section-ref"] || undefined,
+        heading: options.heading || undefined,
+        query: options.query || undefined,
+        max_chars: numberOption(options, "max-chars", 6000, { minimum: 200, maximum: 60000 }),
+        max_sections: numberOption(options, "max-sections", 240, { minimum: 1, maximum: 400 }),
+        context_lines: numberOption(options, "context-lines", 2, { minimum: 0, maximum: 12 }),
+        max_matches: numberOption(options, "max-matches", 12, { minimum: 1, maximum: 30 }),
+        case_sensitive: Boolean(options["case-sensitive"]),
+      },
+    });
+    if (executionIdentity === "agent") {
+      result = {
+        ...result,
+        collaboration_follow_up: "If this document or one of its comments owns the task, return verified results to the originating collaboration surface after the work. A read-only citation needs no ceremonial comment.",
+      };
+    }
+  } else if (action === "patch") {
+    requireConfirmation(options, "Patching document line ranges");
+    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) {
+      throw new CliError(
+        "Agent document patches require --change-summary so collaborators can see what changed and why.",
+        { code: "agent_document_change_summary_required" },
+      );
+    }
+    const operationId = String(options["operation-id"] || payload.operation_id || randomUUID());
+    result = await api.request(`/documents/${resourcePath(targetId)}/content`, {
+      method: "PATCH",
+      retrySafe: true,
+      body: { ...payload, operation_id: operationId },
+    });
+    if (executionIdentity === "agent" && result?.status !== "no_op") {
+      const commentIdempotencyKey = `document-patch:${createHash("sha256")
+        .update(JSON.stringify({ document_id: targetId, operation_id: operationId, body: changeSummary }))
+        .digest("hex")}`;
+      try {
+        const comment = await api.request(`/documents/${resourcePath(targetId)}/comments`, {
+          method: "POST",
+          headers: { "idempotency-key": commentIdempotencyKey },
+          body: {
+            body: changeSummary,
+            mention_targets: [],
+            selection: { target_scope: "document" },
+            entry_point: "external_agent_cli_document_line_patch",
+            start_new_chain: true,
+          },
+        });
+        const entry = Array.isArray(comment?.entries) ? comment.entries.at(-1) : null;
+        result = {
+          ...result,
+          change_comment: {
+            thread_id: comment?.id || null,
+            entry_id: entry?.id || null,
+            body: changeSummary,
+          },
+        };
+      } catch (error) {
+        throw new CliError(
+          "The line patch succeeded, but its required change comment could not be created. Add the comment before reporting completion.",
+          {
+            code: "document_patched_comment_failed",
+            exitCode: error instanceof CliError ? error.exitCode : EXIT.REMOTE,
+            status: error instanceof CliError ? error.status : null,
+            details: {
+              document_id: targetId,
+              operation_id: operationId,
+              mutation: result,
+              recovery_command: `corvio agent comment --document-id ${targetId} --body <change-summary> --start-new-chain --idempotency-key ${commentIdempotencyKey}`,
+            },
+          },
+        );
+      }
     }
   } else if (action === "table-read") {
     const targetId = resolveDocumentId(documentId, selection);
@@ -3053,6 +3160,7 @@ async function docs(options, action, id) {
     const markdown = options.file ? await readTextFile(options.file) : String(options.markdown || "");
     result = await api.request("/documents", {
       method: "POST",
+      query: { response_mode: "compact" },
       headers: { "idempotency-key": idempotencyKey(options) },
       body: {
         title: option(options, "title", { required: true }),
@@ -3081,7 +3189,9 @@ async function docs(options, action, id) {
     if (options["expected-revision"] !== undefined) {
       expectedRevision = numberOption(options, "expected-revision", undefined, { minimum: 0 });
     } else {
-      const current = await api.request(`/documents/${resourcePath(targetId)}`);
+      const current = await api.request(`/documents/${resourcePath(targetId)}/content`, {
+        query: { mode: "overview", max_chars: 1000, max_sections: 1 },
+      });
       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",
@@ -3092,6 +3202,7 @@ async function docs(options, action, id) {
     }
     result = await api.request(`/documents/${resourcePath(targetId)}`, {
       method: "PUT",
+      query: { response_mode: "compact" },
       body: {
         ...(options.title !== undefined ? { title: options.title } : {}),
         ...(markdown !== undefined ? { markdown } : {}),
@@ -3176,7 +3287,7 @@ async function docs(options, action, id) {
     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.");
+    throw new CliError("docs action must be list, get, read, patch, 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));

package/package.json

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