# Corvio Workspace CLI and API authority

## Authority links

- CLI package target: `https://www.npmjs.com/package/@corvio/cli`
- CLI product guide target: `https://corvio.ai/developers/cli`
- Public discovery: `https://api.corvio.ai/v1`
- Public OpenAPI: `https://api.corvio.ai/v1/openapi.json`
- Human API guide: `https://corvio.ai/developers/api`
- Interactive API reference: `https://corvio.ai/developers/api/reference`

The CLI's `--help` and `capabilities --json` output are the command authority. The live OpenAPI is the HTTP method, path, field, scope, and error authority. Do not copy an endpoint catalog into `SKILL.md`.

## Current owner coverage

The public Developer API already owns:

- an environment-key path plus a separate single-use Developer Platform device authorization that yields a user-level `cvu_` principal;
- explicit Workspace discovery/selection and effective capabilities for that user principal;
- idempotent user-level Workspace creation, Project creation, and Tree-owned document moves;
- durable questions, history, conversations, sources, artifacts, operations, and usage;
- Workspace search;
- Page list/read/create/update/recoverable archive/private-link share;
- immutable Workspace Asset upload/finalize, ACL-filtered list/read/download, and Agentic organization receipts;
- foreground Local Markdown source/status/plan/pull/push/commit/conflict resolution over the shared Sync owner;
- CLI distribution policy in discovery, plus npm `beta` dist-tag comparison through `corvio update check`;
- typed document readback, with Presentation and HTML action settlement available through the Agentic question path when advertised.
- user-managed delegated Agent identities with independent `cvg_` credentials, bounded read/comment/edit permission envelopes,
  document comment identity, and stable `@handle` mentions;
- a durable at-least-once Agent event mailbox with claim/lease/renew/retry/dead-letter receipts, plus Agent comment read/reply/status
  operations and Query-owned document mutation.

The remaining typed-write gap is:

- explicit create/update operations for every typed document family.

Never emulate a missing owner with browser-internal `/api/v1`, cookies, Local Agent tokens, title matching, or client-only state.

## Delegated Agent availability

Use a user `cvu_`/`cvk_` principal only to create, update, pause/revoke, or rotate a Workspace Agent. Run `corvio agent ...` with
`CORVIO_AGENT_API_KEY=cvg_...`; the Agent runtime intentionally has no fallback to `CORVIO_API_KEY`. A mention is durable while the
recipient computer is asleep or offline. Nothing remotely powers on a personal computer: when its foreground runner or service
returns, it claims pending work and resumes through the lease contract. Provider-native session messaging may be an adapter for a
running Codex/Claude process, but it is not the cross-vendor mailbox authority.

Keep handler direction in `instruction`; keep the exact comment, document locator/revision, anchor, actor, and event ID in structured
context/resources. The Runner keeps the lease token out of both handler input and Query context. Use Corvio Query for document
mutation, then complete the event only with its matching question/comment receipt or an explicit no-change reason. The server
rechecks the owner's live document ACL at delivery time.

Mailbox events carry causal chain/parent/hop/route facts. Event-derived replies require the exact source event and live lease and
are one-per-event idempotent. Repeated directed routes and hard hop/chain/fanout budgets leave a visible stopped mention without a
runnable event. Only an explicit `start_new_chain` may create a standalone Agent-to-Agent root; do not use it to evade a stop.

## Error decisions

- Package/version lookup failure: stop rather than substituting another `corvio` binary.
- Update available: report `latest_published_version` and `install_command`; never mutate a running installation implicitly.
- `401`: key is invalid, revoked, or expired; do not request it in chat. An interactive user may run `corvio auth login`; an Agent should repair its injected secret authority.
- `400 workspace_selection_required`: login succeeded but no Workspace context was supplied; list and select an exact Workspace before retrying.
- `403`: scope, Workspace role, ACL, or current authority is insufficient; report the exact required capability.
- A `read_only` Workspace blocks write/run even for a member or owner; use the projected status/restriction reason instead of attributing it to role.
- `404`: resource is absent or deliberately hidden; do not infer it from a title.
- `409`: idempotency, revision, in-progress conflict, or legacy `cvk_` Workspace mismatch; reread the canonical resource before retry and never widen a legacy key.
- `429`: honor `Retry-After`.
- Unknown `5xx` or a transport failure without a response: use the CLI retry-safety receipt. Reuse the exact idempotency key when it is safe; otherwise read the resource before retrying.
- `request_timeout` / `upload_timeout`: the bounded request elapsed; preserve the same retry identity and follow `retry_safety`. Do not increase the timeout past the CLI's ten-minute ceiling or add an unbounded outer retry.
- `download_integrity_mismatch`, `upload_integrity_mismatch`, `sync_integrity_mismatch`, or `admin_skill_integrity_mismatch`: no local success may be claimed; retain the request ID and reread the authoritative receipt/package manifest.

Preserve `X-Request-Id` and the CLI's normalized error code in the final result.

`workspace_context` is aggregate routing provenance (titles/bounded outlines), while `workspace_doc` is a document-level source. Neither should be inferred when absent.