@visa/cli 4.1.0-rc.289 → 4.1.0-rc.290

package/README.md

@@ -387,6 +387,29 @@ The ceremony timed out — restart with `visa setup start "Name"`, then follow
 **Tools don't appear in the AI client**
 Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconnect in Claude Code). Re-run `visa-cli connect <client>` to rewrite the config.
 
+**Branching on failures from `--format json`**
+Every failure envelope carries `code`, `kind`, `fix`, and `nextAction`. Branch on
+`code` (stable, append-only) and `kind` (`caller` = fix it yourself and retry;
+`platform` = stop and escalate to a human), never on the English `error` text.
+Deterministic preconditions always resolve to a specific code:
+
+| Condition | `code` | `kind` |
+|-----------|--------|--------|
+| Not logged in (`find`, `activity`, `receipt`) | `session_required` | `caller` |
+| No wallet grant on this runtime (`wallet show\|fund\|limits`, `pay`, `--local` reads) | `wallet_credential_required` | `platform` |
+| Wallet grant approved but not fully delivered (`pay`) | `wallet_delivery_required` | `platform` |
+| Local identity record missing for the selected agent (`pay`) | `identity_required` | `caller` |
+| Identity root migrated; direct signing retired (`pay`) | `universal_required_managed_only` | `platform` |
+| Managed wallet limits are owner-set (`wallet limits` with caps) | `managed_limits_owner_controlled` | `platform` |
+| Listing is not x402 (`pay <listing-id>`) | `invalid_argument` | `caller` |
+| Activity id not found or not attributable (`receipt`) | `activity_entry_not_found` | `caller` |
+
+`unspecified_error` (`platform`) is reserved for failures the CLI cannot
+classify and is intentionally kept on two guards: a wallet binding that does not
+match the signed-in owner profile (an integrity refusal, not a caller state),
+and a `wallet limits` change that would broaden policy without the operator's
+`VISA_V4_WALLET_ALLOW_POLICY_RAISE=1`. Both need a human; escalate rather than retry.
+
 ## Monorepo context
 
 Request routing (MCP vs MPP vs web): [docs/agents/ARCHITECTURE.md](../../docs/agents/ARCHITECTURE.md). Branches and deploy: [docs/agents/PIPELINE.md](../../docs/agents/PIPELINE.md). Contributor workflow: [AGENTS.md](../../AGENTS.md), doc index: [docs/agents/README.md](../../docs/agents/README.md).