@corvio/cli 0.1.0-beta.32 → 0.1.0-beta.34

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
@@ -24,15 +26,17 @@ 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. `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
-`corvio collaboration status --provider workbuddy --json --no-input` to inspect WorkBuddy's manual copy at
+incompatible, compatible-but-not-current, or conflicting local Skill, but never mutates host directories. Non-current receipts include one
+compact Agent notice and a source-aware action; current copies stay quiet. For standalone Skill refreshes,
+the command pins the verified installer, selects exactly one provider, preserves project/global scope, and returns a verification command.
+Use `corvio collaboration status --provider workbuddy --json --no-input` to inspect WorkBuddy's manual copy at
 `~/.workbuddy/skills/corvio-operate-workspace/`; this does not prove which bytes a running WorkBuddy conversation loaded. The canonical
 website ZIP is a static local copy and is not update-tracked by `npx skills update`; reinstall from the same source and scope, then start a
 fresh host session. Until a reviewed WorkBuddy marketplace listing is live, a WorkBuddy upload is an unmanaged manual install and cannot
 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,14 +39,15 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.32";
+const VERSION = "0.1.0-beta.34";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 const MAX_SYNC_FILES = 2_000;
 const MAX_MARKDOWN_CHARACTERS = 120_000;
-const CORVIO_SKILL_INSTALL_COMMAND = "npx skills add https://corvio.ai/developers/skills/corvio-operate-workspace/corvio-operate-workspace.zip";
+const CORVIO_SKILL_ARCHIVE = "https://corvio.ai/developers/skills/corvio-operate-workspace/corvio-operate-workspace.zip";
+const AGENT_SKILLS_INSTALLER_VERSION = "1.5.23";
 const GLOBAL_OPTIONS = Object.freeze([
   "api-base",
   "workspace",
@@ -103,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"],
@@ -151,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
@@ -173,14 +179,14 @@ const COMMAND_HELP = Object.freeze({
   auth: `Usage: corvio auth login|status|logout\n\nAuthenticate with a user-level device link, inspect the current principal, or revoke the stored credential.`,
   workspaces: `Usage:\n  corvio workspaces list\n  corvio workspaces use <workspace-id>\n  corvio workspaces current\n  corvio workspaces create --name <name> [--kind personal|team]\n\nWorkspace status and blocked capability reasons are returned with each item.`,
   capabilities: `Usage: corvio capabilities [--json]\n\nShow live API resources, principal scopes, selected Workspace status, and CLI compatibility.`,
-  collaboration: `Usage:\n  corvio collaboration status [--project <path>] [--provider codex|claude_code|copilot|workbuddy]\n\nCheck local Corvio prerequisites and every discoverable Corvio Skill copy. Package freshness, contract compatibility, update ownership, and host loading are separate facts. WorkBuddy inspection is read-only and never changes ~/.workbuddy. The CLI cannot prove that the current host task loaded a particular copy, or whether remote MCP or host memory is active.`,
+  collaboration: `Usage:\n  corvio collaboration status [--project <path>] [--provider codex|claude_code|copilot|workbuddy]\n\nCheck local Corvio prerequisites and every discoverable Corvio Skill copy. Current copies stay quiet; non-current receipts include one compact Agent notice and a source-aware next action. Standalone refresh commands pin the verified installer, select exactly one provider, and preserve project/global scope. WorkBuddy inspection is read-only and never changes ~/.workbuddy. The CLI cannot prove that the current host task loaded a particular copy, or whether remote MCP or host memory is active.`,
   ask: `Usage: corvio ask --prompt <text> [--file <path>] [--asset-ids <id,id>] [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--processing-profile auto|economy|standard|deep] [--max-processing-profile economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off] [--caller-model <host-model>] [--context-file <json>] [--idempotency-key <key>]\n\nPass the user's natural goal, complete decision-relevant context, and explicit constraints. Unless the user chose them, do not invent taxonomy, titles, artifact count, or Corvio's internal plan; Corvio chooses the cognitive structure and carriers. --file retains the selected local file, verifies its hash, and attaches the finalized Asset to this exact question. --asset-ids attaches already-retained Corvio Assets. Use --allow-actions when Corvio should create the Page, Spreadsheet, Presentation, Code, HTML Artifact, Memory, or qualifying Project Skill that best serves the result. A continuation handle is subject evidence, not necessarily the durable write destination: for a reusable pattern or method, resolve the fitting same-scope Memory or Skill owner before admitting or merging it. Read the terminal Question receipt and use artifact.url or links.primary_artifact verbatim; reader_output artifacts are deliverables, structure_container artifacts are hierarchy, and node_id is never a document URL. Upload alone is not evidence of interpretation. Skill extraction mode always requires --allow-actions and an evidence-backed decision, not forced Skill creation; answer-only questions may use auto or off.`,
   agents: `Usage:\n  corvio agents list\n  corvio agents connect [--provider codex|claude_code|copilot] [--project <path>] [--permission-profile read_only|workspace_write|danger_full_access] [--trigger-policy owner_only|workspace_members] [--display-name <name>] [--recover-credential] [--no-listen]\n  corvio agents create --handle <handle> --display-name <name> [--provider codex|claude_code|copilot|custom] [--permissions read,comment,edit]\n  corvio agents update <id> [--display-name <name>] [--status active|paused|revoked] [--permissions <list>]\n  corvio agents rotate <id>\n\n'connect' binds the current Git project (or --project path) to one stable personal Agent. Repeating it is idempotent; another project creates another Agent. It reports provider/CLI, listener, and local Skill prerequisites separately; run corvio collaboration status after installing or refreshing the Skill. The CLI cannot prove that the current host task loaded those surfaces. The default workspace_write profile is limited by the provider's native sandbox. owner_only is the safe trigger default. Secrets and absolute project paths stay local.`,
   agent: `Usage:\n  corvio agent claim [--worker-id <id>] [--wait-seconds <0-30>]\n  corvio agent renew <event-id> --lease-token <token> [--lease-seconds <30-900>]\n  corvio agent complete <event-id> --lease-token <token> [--result-file <json>]\n  corvio agent fail <event-id> --lease-token <token> --error <message>\n  corvio agent mentions --document-id <id> [--query <name>]\n  corvio agent comments --document-id <id>\n  corvio agent comment --document-id <id> --body <text> [--selection-file <json>] [--start-new-chain] [--idempotency-key <key>]\n  corvio agent reply <thread-id> --document-id <id> --body <text> [--source-event-id <id> --source-event-lease-token <token>|--start-new-chain] [--idempotency-key <key>]\n  corvio agent status <thread-id> --document-id <id> --status open|resolved\n  corvio agent closeout --document-id <id> [--thread-id <id>] --body <verified-result> [--status open|resolved] [--idempotency-key <key>]\n  corvio agent run [--provider codex|claude_code|copilot|custom] [--handler <executable>] [--agent <id>] [--once] [--processing-profile auto|economy|standard|deep] [--max-processing-profile economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off] [--caller-model <host-model>]\n\nUse mentions before commenting when the target is uncertain; aliases resolve to stable user or Agent IDs and ambiguity fails closed. Use closeout when a Corvio document or comment owned the task: it returns the verified result to that surface and reads document/comments back. Agent-to-Agent comments require either a claimed source event or explicit --start-new-chain. The runner iteratively exchanges origin-scoped evidence with Corvio Query/Writer, then invokes the bound provider inside its local project. Local code changes use the recorded provider permission profile; complex Corvio document changes belong to Query/Writer. Provider children never receive Corvio credentials.`,
   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.`,
   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>]`,
@@ -237,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",
@@ -813,6 +821,58 @@ function collaborationRevisionAtLeast(actual, minimum) {
   return true;
 }
 
+function skillInstallerAgent(provider) {
+  return {
+    codex: "codex",
+    claude_code: "claude-code",
+    copilot: "github-copilot",
+  }[provider] || null;
+}
+
+function scopedSkillInstallCommand(provider, evaluated) {
+  const agent = skillInstallerAgent(provider);
+  if (!agent) return null;
+  const projectScoped = !evaluated.length || evaluated.some((item) => item.scope.startsWith("project_"));
+  const globalFlag = projectScoped ? "" : " --global";
+  return `npx --yes skills@${AGENT_SKILLS_INSTALLER_VERSION} add ${CORVIO_SKILL_ARCHIVE} --agent ${agent} --skill corvio-operate-workspace --yes${globalFlag}`;
+}
+
+function collaborationAgentNotice(guidance) {
+  const status = guidance.package_status;
+  if (status === "current") return null;
+  if (status === "compatible_update_available") {
+    return {
+      code: "corvio_legacy_compatible",
+      message: `This host is using Corvio ${guidance.discovered_copies[0]?.release_version || guidance.discovered_copies[0]?.contract_revision || "legacy guidance"}; ${guidance.expected_release_version || guidance.expected_contract_version} is current. It may continue, but Beta feedback should identify this session as legacy.`,
+      continue_allowed: true,
+      recommended_action: guidance.install_command || guidance.update_action,
+      show_once_per_session: true,
+    };
+  }
+  if (status === "freshness_unverified") {
+    return {
+      code: "corvio_freshness_unverified",
+      message: `The loaded Corvio copy declares the current contract, but upstream package integrity could not be verified (${guidance.upstream_manifest_status}).`,
+      continue_allowed: true,
+      recommended_action: "Retry the status check before claiming this host is current; do not describe manifest retrieval failure as a stale install.",
+      show_once_per_session: true,
+    };
+  }
+  const messages = {
+    missing: "Corvio guidance is not installed in the effective host scope.",
+    multiple_copies_conflict: "Multiple effective Corvio copies disagree. Resolve the reported scopes before relying on the guidance.",
+    update_required: "The effective Corvio guidance is unsupported or differs from the official package.",
+    contract_unavailable: "The current Corvio collaboration contract could not be loaded.",
+  };
+  return {
+    code: `corvio_${status}`,
+    message: messages[status] || "Corvio host guidance is not ready.",
+    continue_allowed: false,
+    recommended_action: guidance.install_command || guidance.update_action || "Inspect the reported source and retry before continuing.",
+    show_once_per_session: true,
+  };
+}
+
 async function loadOfficialSkillManifest(liveContract) {
   const manifestUrl = String(dictLike(dictLike(liveContract?.distribution).official_skill).manifest || "").trim();
   if (!manifestUrl) return { status: "unavailable", manifest: {} };
@@ -959,6 +1019,23 @@ async function inspectCollaborationGuidance(provider, projectRoot, liveContract,
   const refreshAvailable = new Set([
     "missing", "compatible_update_available", "update_required", "multiple_copies_conflict",
   ]).has(packageStatus);
+  const pluginManaged = evaluated.some((item) => item.source === "plugin_cache");
+  const installCommand = provider !== "workbuddy"
+    && refreshAvailable
+    && packageStatus !== "multiple_copies_conflict"
+    && !pluginManaged
+    ? scopedSkillInstallCommand(provider, evaluated)
+    : null;
+  let updateAction = null;
+  if (provider === "workbuddy" && refreshAvailable) {
+    updateAction = workbuddyAction || "Download the official Skill ZIP, replace it in WorkBuddy, then start a fresh conversation.";
+  } else if (packageStatus === "multiple_copies_conflict") {
+    updateAction = "Resolve the reported effective scopes explicitly; do not overwrite either copy by assumption.";
+  } else if (pluginManaged && refreshAvailable) {
+    const channel = provider === "codex" ? "codex_marketplace" : "claude_code_marketplace";
+    updateAction = dictLike(dictLike(distribution.host_channels)[channel]).action
+      || "Use the host marketplace/plugin update flow, then start a fresh session.";
+  }
   return {
     status,
     package_status: packageStatus,
@@ -979,12 +1056,10 @@ async function inspectCollaborationGuidance(provider, projectRoot, liveContract,
     current_scopes: current.map((item) => item.scope),
     compatible_scopes: compatible.map((item) => item.scope),
     discovered_copies: found,
-    install_command: provider !== "workbuddy" && refreshAvailable
-      ? CORVIO_SKILL_INSTALL_COMMAND
-      : null,
-    update_action: provider === "workbuddy" && refreshAvailable
-      ? workbuddyAction || "Download the official Skill ZIP, replace it in WorkBuddy, then start a fresh conversation."
-      : null,
+    install_command: installCommand,
+    install_scope: installCommand ? (installCommand.endsWith(" --global") ? "global" : "project") : null,
+    update_action: updateAction,
+    verification_command: refreshAvailable ? `corvio collaboration status --provider ${provider} --project . --json --no-input` : null,
   };
 }
 
@@ -1022,9 +1097,13 @@ async function collaborationStatus(options) {
   if (!credential && requiresProjectAgent) nextActions.push(`corvio agents connect --provider ${provider} --project .`);
   if (guidance.install_command) nextActions.push(guidance.install_command);
   if (guidance.update_action) nextActions.push(guidance.update_action);
+  if ((guidance.install_command || guidance.update_action) && guidance.verification_command) {
+    nextActions.push(guidance.verification_command);
+  }
   if (!serverVersion) nextActions.push("corvio update check --json");
   const localPrerequisitesReady = status === "ready";
   const hostIntegration = dictLike(liveContract.host_integration);
+  const agentNotice = collaborationAgentNotice(guidance);
   writeResult({
     status,
     local_prerequisites_ready: localPrerequisitesReady,
@@ -1063,6 +1142,7 @@ async function collaborationStatus(options) {
         ? hostIntegration.decision_points
         : [],
     },
+    ...(agentNotice ? { agent_notice: agentNotice } : {}),
     next_actions: nextActions,
   }, { json: options.json });
 }
@@ -2904,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);
@@ -2980,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 }),
@@ -3008,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",
@@ -3019,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 } : {}),
@@ -3103,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.32",
+  "version": "0.1.0-beta.34",
   "description": "Official Corvio Workspace CLI for questions, knowledge search, documents, and Agent workflows.",
   "type": "module",
   "bin": {