@corvio/cli 0.1.0-beta.10

package/README.md

@@ -0,0 +1,45 @@
+# Corvio Workspace CLI
+
+Official CLI for a user's Corvio Workspace. It supports an existing `CORVIO_API_KEY` and a browser device-link login.
+
+```bash
+npm install --global @corvio/cli@beta
+export CORVIO_API_KEY='cvu_...'
+corvio auth status
+corvio agents connect --provider codex --project . --json
+corvio ask --prompt 'Summarize recurring launch risks' --json
+corvio files upload --file ./research.pdf --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_` 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. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory. 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.
+
+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. 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.
+
+## 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`, and `Offline`, and includes the stable Agent, opaque project binding, Workspace scope, host permission/trigger policy, 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.