@corvio/cli 0.1.0-beta.20 → 0.1.0-beta.22

package/README.md

@@ -20,17 +20,22 @@ 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: the official Skill is installed at the live server contract version. A listener receives inbound `@Agent` work; it does not make an unrelated foreground coding session collaborate automatically, and the CLI cannot prove that the current host task loaded the Skill or remote MCP. 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. 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.
 
-CLI and Skill updates are independent. `corvio update check` checks the CLI package only. `corvio collaboration status` detects a missing
-official Skill or a shared-contract mismatch, but not every content-only package revision. The canonical website zip is a static local
-copy and is not currently update-tracked by `npx skills update`; rerun its official `npx skills add` command in the same project/global
-scope for exact freshness, start a new host session, then rerun `corvio collaboration status`. Remote MCP changes are server-delivered and
-normally need only a refreshed host session unless new OAuth scopes require reauthorization.
+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
+`~/.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 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.
 
-File organization is asynchronous. A queued organization receipt is progress, not completion: continue from its stable operation ID with `corvio files operation <operation_id>`. Blocked operations expose their typed error and can be continued with `corvio files resume <operation_id> --yes`; queued/running/blocked operations can be stopped with `corvio files cancel <operation_id> --yes`. Report completion only after the terminal receipt exposes the resulting artifacts, Skill evaluation, and durable links.
+Treat files as a value ladder, not one upload event. Upload/finalize preserves the exact original, provenance, hash, policy, and stable Asset ID. A selected Markdown file can become an editable Page through `corvio docs create --file`; for other formats or a coherent source set, use `corvio files organize` or `corvio ask --allow-actions` to produce the reader-facing Page, Spreadsheet, Presentation, Code, HTML Artifact, or reading layer that fits the task. Stable facts/preferences may enter Memory; only an evidence-backed reusable method, configuration, constraint, or quality bar should become a Project Skill.
+
+File organization is asynchronous. A queued organization receipt is progress, not completion: continue from its stable operation ID with `corvio files operation <operation_id>`. Blocked operations expose their typed error and can be continued with `corvio files resume <operation_id> --yes`; queued/running/blocked operations can be stopped with `corvio files cancel <operation_id> --yes`. Report completion only after the terminal receipt exposes the output document, source reconciliation, Skill evaluation, and durable links. `skills_extraction_mode=always` requires the evaluation; `evaluated_no_qualifying_skill` is a valid terminal result and is preferable to a fabricated Skill.
 
 ## Project Agent collaboration
 

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.20";
+const VERSION = "0.1.0-beta.22";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -173,16 +173,16 @@ 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]\n\nCheck local Corvio prerequisites: project-Agent binding, installed collaboration Skill version, and inbound listener state. The CLI cannot prove that the current host task loaded the Skill, remote MCP, or host memory.`,
-  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\n--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. Skill extraction mode always requires --allow-actions; answer-only questions may use auto or off.`,
+  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.`,
+  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\n--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. Poll/read the returned Question artifacts and operations; 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\nUse table-read plus table-mutate for bounded stable-ID cell updates or row appends without round-tripping a whole document. Use \`corvio ask --allow-actions\` for formulas, styles, table structure, Spreadsheet, Presentation, Code, HTML Artifact, or semantic organization. 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 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\`. 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.`,
-  files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id>\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\nUpload alone preserves the original file. Organization is asynchronous: use 'files operation' to read its terminal result, typed blocker and recovery links before claiming completion. 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>\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\nUpload 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. 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.`,
 });
@@ -724,6 +724,7 @@ async function codexPluginGuidanceCandidates(codexHome) {
       for (const version of await listDirectories(pluginRoot)) {
         candidates.push({
           scope: "codex_plugin_cache",
+          priority: 100,
           path: join(pluginRoot, version, "skills", "corvio-operate-workspace", "SKILL.md"),
         });
       }
@@ -732,24 +733,103 @@ async function codexPluginGuidanceCandidates(codexHome) {
   return candidates;
 }
 
-async function inspectCollaborationGuidance(provider, projectRoot, expectedContractVersion) {
-  const candidates = [
-    { scope: "project_agents", path: join(projectRoot, ".agents", "skills", "corvio-operate-workspace", "SKILL.md") },
-    { scope: "user_agents", path: join(homedir(), ".agents", "skills", "corvio-operate-workspace", "SKILL.md") },
-  ];
+function collaborationRevision(source) {
+  return source.match(/contract (?:version|revision) `([0-9]{4}-[0-9]{2}-[0-9]{2}\.[0-9]+)`/)?.[1] || null;
+}
+
+function collaborationRelease(source) {
+  return source.match(/Skill release `([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)`/)?.[1] || null;
+}
+
+function collaborationCompatibilityFamily(source) {
+  return source.match(/compatibility family\s+`([^`]+)`/)?.[1] || null;
+}
+
+function collaborationRevisionAtLeast(actual, minimum) {
+  const parse = (value) => {
+    const match = String(value || "").match(/^(\d{4})-(\d{2})-(\d{2})\.(\d+)$/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3]), Number(match[4])] : null;
+  };
+  const left = parse(actual);
+  const right = parse(minimum);
+  if (!left || !right) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return true;
+}
+
+async function loadOfficialSkillManifest(liveContract) {
+  const manifestUrl = String(dictLike(dictLike(liveContract?.distribution).official_skill).manifest || "").trim();
+  if (!manifestUrl) return { status: "unavailable", manifest: {} };
+  let url;
+  try {
+    url = new URL(manifestUrl);
+  } catch {
+    return { status: "invalid_url", manifest: {} };
+  }
+  if (!new Set(["https:", "http:"]).has(url.protocol)) return { status: "invalid_url", manifest: {} };
+  try {
+    const response = await fetch(url, {
+      headers: { accept: "application/json", "user-agent": USER_AGENT },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) return { status: `http_${response.status}`, manifest: {} };
+    return { status: "available", manifest: dictLike(await response.json()) };
+  } catch {
+    return { status: "unavailable", manifest: {} };
+  }
+}
+
+async function inspectCollaborationGuidance(provider, projectRoot, liveContract, manifestReceipt = {}) {
+  const distribution = dictLike(liveContract?.distribution);
+  const requiresContentHash = Number(distribution.schema_version || 0) >= 2;
+  const compatibility = dictLike(distribution.compatibility);
+  const officialSkill = dictLike(distribution.official_skill);
+  const expectedContractVersion = String(liveContract?.version || compatibility.current_revision || "").trim() || null;
+  const expectedReleaseVersion = String(officialSkill.current_release || "").trim() || null;
+  const manifest = dictLike(manifestReceipt.manifest);
+  const expectedSkillSha256 = Array.isArray(manifest.files)
+    ? String(manifest.files.find((file) => file?.path === "SKILL.md")?.sha256 || "").trim() || null
+    : null;
+  const expectedFamily = String(compatibility.family || "").trim() || null;
+  const minimumRevision = String(compatibility.minimum_supported_skill_revision || "").trim()
+    || expectedContractVersion;
+  const legacyFamilylessRevisions = Array.isArray(compatibility.legacy_familyless_revisions)
+    ? compatibility.legacy_familyless_revisions.map((value) => String(value || "").trim()).filter(Boolean)
+    : [];
+  const candidates = [];
+  if (provider === "workbuddy") {
+    const workbuddyHome = String(process.env.WORKBUDDY_HOME || join(homedir(), ".workbuddy"));
+    candidates.push({
+      scope: "user_workbuddy",
+      source: "manual_host_copy",
+      priority: 200,
+      path: join(workbuddyHome, "skills", "corvio-operate-workspace", "SKILL.md"),
+    });
+  } else {
+    candidates.push(
+      { scope: "project_agents", source: "project_skill", priority: 300, path: join(projectRoot, ".agents", "skills", "corvio-operate-workspace", "SKILL.md") },
+      { scope: "user_agents", source: "user_skill", priority: 200, path: join(homedir(), ".agents", "skills", "corvio-operate-workspace", "SKILL.md") },
+    );
+  }
   if (provider === "codex") {
     const codexHome = String(process.env.CODEX_HOME || join(homedir(), ".codex"));
     candidates.push({
       scope: "user_codex",
+      source: "user_skill",
+      priority: 200,
       path: join(codexHome, "skills", "corvio-operate-workspace", "SKILL.md"),
     });
     candidates.push(...await codexPluginGuidanceCandidates(codexHome));
   }
   if (provider === "claude_code") {
     candidates.push(
-      { scope: "project_claude", path: join(projectRoot, ".claude", "skills", "corvio-operate-workspace", "SKILL.md") },
+      { scope: "project_claude", source: "project_skill", priority: 300, path: join(projectRoot, ".claude", "skills", "corvio-operate-workspace", "SKILL.md") },
       {
         scope: "user_claude",
+        source: "user_skill",
+        priority: 200,
         path: join(String(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")), "skills", "corvio-operate-workspace", "SKILL.md"),
       },
     );
@@ -759,29 +839,98 @@ async function inspectCollaborationGuidance(provider, projectRoot, expectedContr
     try {
       const source = await readFile(candidate.path, "utf8");
       if (!/^name:\s*corvio-operate-workspace\s*$/m.test(source)) continue;
+      const contractRevision = collaborationRevision(source);
+      const releaseVersion = collaborationRelease(source);
+      const family = collaborationCompatibilityFamily(source);
+      const contentSha256 = createHash("sha256").update(source).digest("hex");
+      const exactRevision = Boolean(expectedContractVersion) && contractRevision === expectedContractVersion;
+      const exactRelease = Boolean(expectedReleaseVersion) && releaseVersion === expectedReleaseVersion;
+      const exactContent = Boolean(expectedSkillSha256) && contentSha256 === expectedSkillSha256;
+      const familyMatches = family === expectedFamily
+        || (!family && legacyFamilylessRevisions.includes(contractRevision));
+      const compatible = expectedFamily
+        ? familyMatches && collaborationRevisionAtLeast(contractRevision, minimumRevision)
+        : exactRevision;
+      const declaredCurrent = compatible && (
+        expectedReleaseVersion ? exactRelease : exactRevision
+      );
       found.push({
         scope: candidate.scope,
-        current: Boolean(expectedContractVersion)
-          && source.includes(`contract version \`${expectedContractVersion}\``),
+        source: candidate.source || "plugin_cache",
+        priority: candidate.priority || 100,
+        path: candidate.path,
+        release_version: releaseVersion,
+        contract_revision: contractRevision,
+        compatibility_family: family,
+        content_sha256: contentSha256,
+        current: expectedSkillSha256
+          ? exactContent && compatible
+          : !requiresContentHash && declaredCurrent,
+        declared_current: declaredCurrent,
+        integrity_match: expectedSkillSha256 ? exactContent : null,
+        compatible,
       });
     } catch (error) {
       if (error?.code !== "ENOENT") throw error;
     }
   }
-  const current = found.filter((item) => item.current);
-  const status = !expectedContractVersion
+  const effectivePriority = found.length ? Math.max(...found.map((item) => item.priority)) : null;
+  const evaluated = effectivePriority === null ? [] : found.filter((item) => item.priority === effectivePriority);
+  const current = evaluated.filter((item) => item.current);
+  const compatible = evaluated.filter((item) => item.compatible);
+  const distinctCopies = new Set(evaluated.map((item) => item.content_sha256));
+  const integrityMismatch = Boolean(expectedSkillSha256) && evaluated.some(
+    (item) => item.release_version === expectedReleaseVersion && item.content_sha256 !== expectedSkillSha256,
+  );
+  let packageStatus = "update_required";
+  if (!expectedContractVersion) packageStatus = "contract_unavailable";
+  else if (!evaluated.length) packageStatus = "missing";
+  else if (distinctCopies.size > 1) packageStatus = "multiple_copies_conflict";
+  else if (integrityMismatch) packageStatus = "update_required";
+  else if (current.length) packageStatus = "current";
+  else if (compatible.length && !expectedSkillSha256 && evaluated.some((item) => item.declared_current)) {
+    packageStatus = "freshness_unverified";
+  } else if (compatible.length) packageStatus = "compatible_update_available";
+  const status = packageStatus === "contract_unavailable"
     ? "contract_unavailable"
-    : current.length
-      ? "ready"
-      : found.length
-        ? "stale"
-        : "missing";
+    : packageStatus === "missing"
+      ? "missing"
+      : ["current", "compatible_update_available", "freshness_unverified"].includes(packageStatus)
+        ? "ready"
+        : "stale";
+  const managementStatus = provider === "workbuddy" && found.length
+    ? "unmanaged_manual_install"
+    : "host_or_installer_managed_unknown";
+  const workbuddyAction = dictLike(dictLike(distribution.host_channels).workbuddy_manual_skill).action;
+  const refreshAvailable = new Set([
+    "missing", "compatible_update_available", "update_required", "multiple_copies_conflict",
+  ]).has(packageStatus);
   return {
     status,
+    package_status: packageStatus,
+    management_status: managementStatus,
+    host_loading_status: "host_loading_unverified",
     expected_contract_version: expectedContractVersion || null,
+    expected_release_version: expectedReleaseVersion,
+    expected_skill_md_sha256: expectedSkillSha256,
+    upstream_manifest_status: manifestReceipt.status || "unavailable",
+    compatibility: {
+      family: expectedFamily,
+      minimum_supported_revision: minimumRevision,
+      legacy_familyless_revisions: legacyFamilylessRevisions,
+    },
     discovered_scopes: found.map((item) => item.scope),
+    effective_scopes: evaluated.map((item) => item.scope),
+    shadowed_scopes: found.filter((item) => item.priority !== effectivePriority).map((item) => item.scope),
     current_scopes: current.map((item) => item.scope),
-    install_command: status === "missing" || status === "stale" ? CORVIO_SKILL_INSTALL_COMMAND : null,
+    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,
   };
 }
 
@@ -794,23 +943,31 @@ async function collaborationStatus(options) {
     fallbackToActive: false,
   });
   const provider = String(options.provider || credential?.metadata?.provider || "codex");
+  if (!["codex", "claude_code", "copilot", "workbuddy"].includes(provider)) {
+    throw new CliError("--provider must be codex, claude_code, copilot, or workbuddy.", {
+      code: "invalid_provider",
+    });
+  }
   const api = new ApiClient({ baseUrl: baseUrl(options), userAgent: USER_AGENT });
   const index = await api.request("", { auth: false });
   const liveContract = dictLike(index?.coding_agent_collaboration);
   const serverVersion = String(liveContract.version || "").trim() || null;
-  const guidance = await inspectCollaborationGuidance(provider, projectRoot, serverVersion);
+  const manifestReceipt = await loadOfficialSkillManifest(liveContract);
+  const guidance = await inspectCollaborationGuidance(provider, projectRoot, liveContract, manifestReceipt);
   const bindingId = String(credential?.metadata?.binding_id || "").trim();
   const runnerState = await readAgentRunnerState();
   const listener = bindingId ? dictLike(runnerState?.listeners?.[bindingId]) : {};
   const listenerStatus = processIsRunning(Number(listener.pid)) ? "listening" : "offline";
+  const requiresProjectAgent = provider !== "workbuddy";
   let status = "ready";
-  if (!credential) status = "needs_connection";
+  if (!credential && requiresProjectAgent) status = "needs_connection";
   else if (!serverVersion) status = "contract_unavailable";
   else if (guidance.status === "missing") status = "needs_skill";
   else if (guidance.status === "stale") status = "stale_skill";
   const nextActions = [];
-  if (!credential) nextActions.push(`corvio agents connect --provider ${provider} --project .`);
+  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 (!serverVersion) nextActions.push("corvio update check --json");
   const localPrerequisitesReady = status === "ready";
   const hostIntegration = dictLike(liveContract.host_integration);
@@ -1509,7 +1666,7 @@ async function agents(options, action, id) {
     const hostGuidance = await inspectCollaborationGuidance(
       provider,
       binding.project_root,
-      collaborationVersion,
+      { version: collaborationVersion },
     );
     result = {
       connected: true,

package/package.json

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