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

package/README.md

@@ -15,3 +15,37 @@ 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.
+
+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.
+
+## External Agent collaboration
+
+Create and manage an Agent with the user credential, then run it with the one-time `cvg_` secret. User and Agent credentials are deliberately separate:
+
+```bash
+corvio agents create \
+  --handle reviewer-a \
+  --display-name "Reviewer A" \
+  --provider codex \
+  --permissions read,comment,edit \
+  --json
+
+export CORVIO_AGENT_API_KEY='cvg_...'
+corvio agent claim --wait-seconds 30 --json
+corvio agent run --handler ./my-agent-handler --once --json
+```
+
+The handler reads one Agent event JSON object from stdin and prints one JSON object:
+
+```json
+{"instruction":"Inspect the mentioned section and correct unsupported claims.","reply":"Reviewed and updated the section."}
+```
+
+The Runner renews the mailbox lease, sends the instruction and structured event context to Corvio Query, posts the reply under the Agent's own name/avatar, and completes only with durable Query/comment/artifact receipts. Query owns detailed document edits; the handler should decide intent, not implement a second line editor. `CORVIO_API_KEY` is not passed to the handler and Agent runtime commands never fall back to it.
+
+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. Use a process supervisor for an always-on Runner; pause or revoke the Agent when it should stop receiving new mentions.