@visa/cli 5.0.0-rc.367 → 5.0.0-rc.369

package/README.md

@@ -204,6 +204,13 @@ Two browser approvals remain: the sign-in page, then the protected-agent page
 where the owner approves the device and its limits. Each prints one URL and one
 short code at a time. Never relay the code on the owner's behalf.
 
+`visa connect --restart` starts a fresh approval for this machine: choose
+**Replacing** on the approval page to give the same agent new keys (its budget
+and history stay; the old keys are retired and this machine's old local records
+are kept as `*.replaced-<time>` backups). `--restart` never touches the
+installed `pair-visa-agent` skill; `--force-skill` replaces it, moving a locally
+edited copy to `.visa-cli-managed/backups/` first.
+
 On macOS and Linux the private identity key lives under `~/.visa-cli/` in an
 owner-only directory with file mode `0600`. It is an exportable local file:
 copying it transfers identity proof, and losing it blocks new proofs, because
@@ -245,6 +252,14 @@ Pausing, resuming, renaming and revoking an agent are owner actions in the
 Console. `visa disconnect --revoke` is the one terminal exit: it withdraws
 spending authority without touching identity.
 
+**"Ask me each time".** When the owner's mode for a payment is "Ask me each
+time", `pay` (and `purchase_create` for cards) returns
+`wallet_owner_approval_required` / `card_owner_approval_required` with the
+owner's approval link, and nothing is paid. Call the tool again with the same
+`economicIntentId` (card: the returned `resumeId`): it waits for the owner's
+approval (up to 5 minutes) and then completes that exact payment once. Each
+approval covers one payment.
+
 ## Discover and pay
 
 The rail comes from the target. You never name it:
@@ -403,6 +418,16 @@ service's paid route with `discover { "query": "<what you want>" }`.
 The ceremony timed out — run `visa connect` again. Do not look for a resume
 command; the retired setup doors are removed, and `connect` is idempotent.
 
+**Enrollment or TAP signing returns `update_required` / HTTP 426**
+
+The server requires a newer CLI. The error names the running and minimum
+compatible versions. Run `npm install -g @visa/cli@rc`, then run `visa connect`
+again. For MCP, restart the MCP server so it loads the updated binary before
+calling `agent_enroll` again. Repeating `connect --restart` alone cannot fix a
+version refusal. A TAP-only refusal does not undo completed wallet/card setup;
+the result carries `tapDiagnostic.code: "update_required"` and the upgrade remedy,
+even while device approval is still pending.
+
 **`session` is false with a certificate error, but the website works**
 Codes like `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `SELF_SIGNED_CERT_IN_CHAIN` or
 `DEPTH_ZERO_SELF_SIGNED_CERT` mean this machine would not trust the connection,
@@ -438,6 +463,13 @@ Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconn
 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.
+When a person fixes the failure in the Visa Console (add funds, resume or
+reconnect an agent, change limits, renew an approval, verify a card), the
+envelope also carries `remedyUrl` and `remedyLabel`: one link on this
+deployment's Console to hand the owner, for example
+`"remedyUrl": "https://app.visacli.sh/agent/enroll/payments", "remedyLabel": "Add funds to the wallet"`.
+MCP tool failures carry the same two fields in `structuredContent` and in the
+`io.visa/visa-error` metadata.
 Deterministic preconditions always resolve to a specific code:
 
 | Condition | `code` | `kind` |