@corvio/cli 0.1.0-beta.4 → 0.1.0-beta.41

package/README.md

@@ -1,17 +1,98 @@
 # 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='cvu_...'
 corvio auth status
-corvio workspaces list
-corvio workspaces use <workspace_id>
+corvio agents connect --provider codex --project . --json
+corvio collaboration status --json --no-input
 corvio ask --prompt 'Summarize recurring launch risks' --json
+corvio ask --background --prompt 'Reconcile the current launch evidence' --json
+corvio questions operation <operation_id> --after-cursor <progress_cursor> --wait-until-terminal --json
+corvio questions cancel <operation_id> --yes --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 --wait-until-terminal --timeout-seconds 1200 --json
+corvio files operation <operation_id> --wait-until-terminal --timeout-seconds 1200 --json
+corvio files resume <operation_id> --yes --wait-until-terminal --timeout-seconds 1200 --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
 corvio update check --json
 ```
 
-When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` credential; it does not freeze the browser's current Workspace. Select each operation's Workspace with `corvio workspaces use`, `--workspace`, or `CORVIO_WORKSPACE_ID`. Legacy Workspace-bound `cvk_` keys remain supported and cannot be widened to another Workspace. The environment key always takes precedence. 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. `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. 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. `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`, keep the user's natural question unchanged, then append the smallest complete decision-relevant context or stable handles
+as a separate clause. A carried Project handle normally bounds a cross-branch question without enumerating all descendants. Handles are
+evidence addresses: do not invent a comparison rubric, prescribe reasoning steps, substitute another user objective, or turn current Tree
+labels into a detailed task plan. Unless the user chose them, do not invent taxonomy, titles, artifact counts, or Corvio's internal plan.
+In a bounded read-only continuation, use `corvio ask --workspace <workspace_id> --prompt "<unchanged question; Context: project handle>"
+--json --no-input` when a trusted current-task or prior receipt already
+proves this authenticated CLI and exact Workspace. Answer-only is
+the default: omit `--allow-actions`; the CLI has no `--mode` option. Start the command once; do not launch an identical Question concurrently
+or retry before terminal exit. The command returns the terminal Question without model-visible
+polling. Transport continuity does not prove a cheaper processing profile; leave profile selection on `auto` unless the unresolved semantic
+bottleneck independently justifies another profile. Do not install, probe, or switch to the CLI only for that optimization, and do not
+extend it to an unbound Workspace.
+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.
+
+For a Question that may outlive one host turn, add `--background`. The command returns one durable `operation_id` immediately. Continue
+that same operation with `corvio questions operation`; `--wait-until-terminal` keeps the status loop inside the CLI, while
+`--after-cursor` returns only later user-visible milestones. A local deadline is not remote cancellation. Use
+`corvio questions cancel <operation_id> --yes` to request a stop, and do not report success until the returned state is actually
+`cancelled`. Progress is a bounded phase summary, never hidden reasoning or a provisional final answer. To correct the objective, finish
+or cancel the current operation and start a successor `corvio ask --conversation-id <conversation_id>` rather than silently replacing it.
+
+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. When this authenticated CLI is already the natural transport, `--wait-until-terminal` keeps deterministic status reads inside one foreground process; `--timeout-seconds` is a bounded local deadline, and expiry returns the latest non-terminal receipt with `transport_wait.status=deadline_reached`. Without that flag, `corvio files operation <operation_id>` remains one immediate read. 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.