@corvio/cli 0.1.0-beta.3 → 0.1.0-beta.31

package/README.md

@@ -1,12 +1,73 @@
 # Corvio Workspace CLI
 
-Official CLI for a user's Corvio Workspace. It supports an existing `CORVIO_API_KEY` and a browser device-link login.
+Official CLI for a user's Corvio Workspace. It supports an existing `CORVIO_API_KEY` and a browser device-link login. In a connected
+host, use the accompanying `corvio-operate-workspace` Skill so every non-trivial task begins with a lightweight Corvio grounding check.
 
 ```bash
 npm install --global @corvio/cli@beta
-export CORVIO_API_KEY='cvk_...'
+export CORVIO_API_KEY='cvu_...'
 corvio auth status
+corvio agents connect --provider codex --project . --json
+corvio collaboration status --json --no-input
 corvio ask --prompt 'Summarize recurring launch risks' --json
+corvio files upload --file ./research.pdf --json
+corvio files get <asset_id> --content --json
+corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --json
+corvio files operation <operation_id> --json
+corvio files resume <operation_id> --yes --json
+corvio docs table-read <workspace_id/document_id> --limit 25 --json
+corvio docs table-mutate <workspace_id/document_id> --input ./table-change.json --change-summary 'Updated owner and due date' --yes --json
+corvio sync init --dir ./knowledge --root-node-id <node_id> --json
+corvio update check --json
 ```
 
-When no environment key is configured, run `corvio auth login`. The environment key always takes precedence. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the supported command and receipt contract.
+When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` control-plane credential; it does not freeze the browser's current Workspace. Run `corvio agents connect --project .` from the project you want to expose. The command verifies the selected Codex, Claude Code, or Copilot host before server mutation, then idempotently creates or restores the Agent for that provider/device/project binding, grants current/future Workspace coverage under live membership/role and ACL limits, saves the one-time `cvg_` in a `0600` multi-binding registry, and starts that project's listener. `corvio collaboration status` then checks local foreground prerequisites and reports package freshness, contract compatibility, installation ownership, every discoverable copy, and the fact that host loading is not observable. A listener receives inbound `@Agent` work; it does not make an unrelated foreground coding session collaborate automatically. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory, then a locally confirmed selection, the account selection, the personal default, or one authorized candidate. They ask only on real ambiguity. Use `corvio workspaces use`, `--workspace`, and `--agent` as explicit routing/reproducibility controls. Legacy Workspace-bound `cvk_`, `cvg_`, and version-1 credential files remain compatible and are never widened. Local sync stores only credential-free handles and revision/hash baselines in `.corvio/state.json`; Markdown lives below `corvio_docs/`, and conflicts require explicit resolution. `corvio capabilities` reads only Corvio API capability and compatibility facts, so discovery remains usable in hosts that deny npm registry access. `corvio update check` is the explicit registry-backed version check; it never self-installs. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the full command and receipt contract.
+
+CLI and Skill updates are independent. `corvio update check` checks the CLI package only. `corvio collaboration status` detects a missing,
+incompatible, compatible-but-not-current, or conflicting local Skill, but never mutates host directories. Use
+`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.
+
+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
+`links.primary_artifact` verbatim; `reader_output` artifacts are deliverables, `structure_container` artifacts are hierarchy, and
+`node_id` is never a document URL.
+
+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.
+
+Use `corvio files get <asset_id> --content` when the task needs only bounded facts from one retained source. The response preserves the immutable original as authority, reports its source hash and whether the projection is complete or truncated, and does not create a Question or materialize another document. Never infer unseen workbook rows/sheets or document sections.
+
+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
+
+Connect the current project with the user credential. User and Agent credentials stay deliberately separate, and the secret is never printed, written into the project, or passed to the provider:
+
+```bash
+corvio agents connect --provider codex --project . --json
+```
+
+Without `--display-name`, connect derives a provider-aware project name from the authenticated user, such as `Ada Codex · billing-service`; Settings remains the rename owner. The receipt distinguishes `Configured`, `CLI Ready`, `Listening`, `Offline`, and `Foreground collaboration ready`, and includes the stable Agent, opaque project binding, Workspace scope, host permission/trigger policy, Skill status, and Settings link. The default `workspace_write` profile uses the provider's native sandbox. `owner_only` is the safe trigger default. Allowing Workspace members to invoke the local project or granting unrestricted host access requires explicit `--yes`.
+
+The listener first runs a read-only provider planning pass, then asks Corvio Query for exact origin-document and collaboration context. `local_project` work runs inside the bound project; online document writes remain Query/Writer-owned. The provider consumes the Query result before replying, and completion records exact event/lease/question/comment lineage plus provider, project fingerprint, claimed files/checks, and observed Git working-tree state. A custom handler remains available for advanced adapters:
+
+The Codex adapter requires an existing saved `codex login` session. It selects Codex's built-in authenticated provider and applies a secret-filtered core shell environment to model-run project commands; it does not forward environment-only custom-provider keys as an unattended fallback. Claude Code and Copilot use their own saved authentication and native permission modes. Provider capability summaries are observable facts, not a claim that all three hosts enforce identical sandboxes.
+
+```json
+{"instruction":"Inspect the mentioned section and correct unsupported claims.","reply":"Reviewed and updated the section."}
+```
+
+The Runner renews the mailbox lease, binds Query to the exact event and source document, posts the only visible reply under the explicitly mentioned Agent's own name/provider avatar, and completes only with durable Query/comment/runtime receipts. Inbound comment runs cannot search another Workspace through the owner's account Agent. Neither `CORVIO_API_KEY` nor `CORVIO_AGENT_API_KEY` is passed to the provider/handler, and runtime commands never fall back across Agent principals. The project path stays only in the local registry; Corvio stores its opaque fingerprint and capability summary.
+
+Runner replies are causally bound to the claimed event and are idempotent across network retries. Corvio stops repeated Agent routes
+and enforces bounded hop, chain-event, and per-comment target budgets; a stopped handoff remains visible as “Needs attention” but is
+not claimable. For a deliberate standalone Agent-to-Agent request, use `corvio agent comment ... --start-new-chain`. Manual replies
+may instead pass `--source-event-id` with `--source-event-lease-token`; source and new-chain modes must not be mixed.
+
+If a laptop sleeps, loses network, or stops the Runner, events remain pending or become reclaimable after lease expiry. Corvio does not claim to power on an offline device. Re-run `agents connect` to restore the same listener, or pause/revoke the Agent in Settings when it should stop receiving new mentions. `--no-listen` is an explicit diagnostic override and returns an honest Offline receipt.