@visa/cli 4.1.0-rc.298 → 4.1.0-rc.299

package/dist/skills/pair-visa-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pair-visa-agent
-description: Connect a Visa CLI v4 agent — identity plus every payment rail it needs — through ONE setup operation the human approves once in their browser. Ask what to call the agent, call setup_start, relay the review link, then poll setup_status until it is ready. Use when the user says "pair my agent", "connect Visa", "enroll my Visa CLI", "set up my agent", or "let this agent pay".
+description: Set up a Visa CLI v4 agent through the single protected enrollment implementation, using the entrance this build advertises, and report its live capabilities honestly. The owner always approves in their browser. Use when the user says "pair my agent", "connect Visa", "enroll my Visa CLI", "set up my agent", or "let this agent pay".
 compatibility: Needs the `visa` CLI (`npm i -g @visa/cli@rc`) — run `node scripts/setup.mjs` to install it if missing — plus network access to the Visa authorization service. Works in OpenClaw, Hermes, Claude Code, Codex, or any Agent Skills runtime.
 allowed-tools: Bash(visa:*) Bash(visa-cli:*) Bash(node:*) Bash(npm:*) Bash(npx:*)
 metadata:
@@ -27,52 +27,71 @@ metadata:
           - visa-cli
 ---
 
-# Connect a Visa agent
+# Set up a Visa agent
 
-One setup operation carries everything: this runtime's identity **and** every payment
-rail the agent needs, behind a **single** owner approval on a single review page. You ask
-once, the human clicks Connect once, and you finish the rest yourself.
+One command carries everything: this runtime's identity, the binding to **this
+device**, and the spending limits — behind a **single** owner approval in their browser.
 
-**The whole flow is two tool calls and, for the human, one or two clicks.**
+**Today, the command is run by the OWNER in their terminal.** On one-door builds that
+advertise it, an agent may instead call `agent_enroll` and hand the owner its returned
+link, or the owner runs `visa agent enroll`. These are two entrances to the exact same
+protected enrollment implementation: the same native signer, Authority routes, owner
+browser approval, and limits. Never invent or mix in a second ceremony.
 
 ```
-setup_start {"name": "<what they call it>", "rails": ["card", "wallet"]}
-   → relay the returned browserUrl to the human
-   → human clicks "Connect agent"        (click 1)
-   → for the wallet rail, one "Approve"  (click 2 — same page, no second budget)
-setup_status                              (repeat at the returned pollAfterMs)
-   → each call drives the agent's own steps; stop when nextAction.kind is "done"
+# the human runs this:
+visa agent enroll-protected \
+  --authority-url <origin> --auth-url <origin> --url <origin> --wait
+
+   → it prints a URL and a short code
+   → the human opens the URL and enters the code at /agent/enroll/protected-agent
+   → the human approves the device and its spending limits        (one approval)
+   → the command finishes; `get_status` now reports pairing.paired: true
 ```
 
-Nothing else. Do **not** walk `enroll_agent` → `agent_connect` → `agent_connect_poll` →
-`start_card_mandate` for a new agent: that legacy sequence spends three extra owner
-approvals reaching the same place, and this skill replaces it.
+All three origins are required today; the operator supplies them. If the human does not
+know them, ask — do not guess an origin, and never construct a Visa URL yourself.
 
-## What "connected" means here
+Running the same command again resumes an interrupted enrolment; `--restart` replaces an
+unclaimed request with a fresh code. `--ceiling <usd>` and `--per-transaction <usd>`
+propose limits the owner confirms on the approval page.
 
-`setup_start` mints a **new** agent: a new server-assigned agent, a new device-held Ed25519
-identity key, and whichever rails you asked for. When the operation reports ready:
+## The older ceremonies were deleted — do not call them
+
+`setup_start`, `setup_status`, `setup_resume`, `setup_cancel`, `setup_agent`,
+`enroll_agent`, `agent_connect`, `agent_connect_poll`, `agent_connect_cancel`,
+`agent_handoff_claim` and `agent_pairing_cancel` are gone, along with the `visa setup`
+group and `visa agent pair|create|verify|enroll|enroll-claim|claim|pairing-resume|connect|grant-card|grant-wallet|grant-activate|grant-claim|handoff-claim`.
+
+Calling any of them returns one refusal:
+
+```json
+{ "code": "legacy_door_removed", "kind": "caller", "fix": "visa agent enroll-protected" }
+```
+
+That code means the door no longer exists. **Relay the replacement and stop.** Do not
+retry it, do not try a variant spelling, and do not report it to the human as an outage:
+nothing was signed, paired, or paid.
+
+## What "set up" means here
+
+Each completed protected enrollment mints a **new** agent: a new server-assigned agent,
+a new device-held Ed25519 identity key, and the wallet limits the owner approved.
 
 - The runtime keeps the private Ed25519 key and sends only the public JWK.
-- The rails in `readiness.rails` are the ones the owner actually approved. A rail you did
-  not request is not configured, and pairing has never implied one.
+- The limits are the ones the owner actually approved on the page. Nothing you asked for
+  is granted until they approve it.
 - An email address, a `.visa` mesh name, and TAP bindings remain separate, later
-  configuration. Do not infer them from a finished setup.
-
-**Where the `agentId` comes from — read this before you quote one.** The setup status body
-carries `operationId`, `state`, `readiness`, `nextAction`, `pollAfterMs`, `correlationId`
-and `agent: {name, runtime?, device?}`. It does **not** carry `agentId`, and it never
-carries `identityKeyJkt` (that is a field of the older pairing flow). `agentId` appears on
-exactly one result: the `setup_status` call that performed the activation, which returns it
-alongside `walked`. If you need the id and that call is not the one in front of you — the
-background watcher often finishes the last rung — read it from `get_status` or
-`agent_capabilities` rather than guessing. **Never substitute the `so_…` operation id or a
-`correlationId` for an `agentId`:** they are different things, and feeding an operation id
-to a grant ceremony fails in a way that looks like a Visa outage.
-
-**`setup_start` cannot add a rail to an agent that already exists** — it always creates a
-new one. To give an already-connected agent another rail, see "Adding a rail to an agent
-that already exists" near the end.
+  configuration. Do not infer them from a finished enrolment.
+
+**Where the `agentId` comes from — read this before you quote one.** Do not invent it and
+do not read it out of the command's terminal output, which you often cannot see. Read it
+from `get_status` or `agent_capabilities` once the enrolment finishes. Never substitute a
+correlation id, a confirmation code, or an origin for an `agentId`.
+
+**Re-running the command does not repair an agent that already exists** — it creates a
+second one. To fix a capability an existing agent is missing, see "Already set up — do NOT
+enrol again" near the end.
 
 ## Getting this skill
 
@@ -107,10 +126,10 @@ OpenClaw users receive the skill via `visa agent skill --runtime openclaw` (or t
    - **Hermes or another supported runtime:** run `visa-cli connect hermes` or
      `visa-cli connect <runtime>`. For Hermes, the entry is written under `mcp_servers`
      in `~/.hermes/config.yaml`.
-   - **No MCP integration:** use the raw `visa setup …` commands.
-3. **Sign the owner in** when the setup includes the wallet rail — see "Sign in first"
-   below.
-4. **Connect.** Follow the core flow below.
+   - **No MCP integration:** everything below still works — the enrolment is a shell
+     command, and `--format json` output is available on the management commands.
+3. **Sign the owner in** — see "Sign in first" below.
+4. **Enrol.** Follow the core flow below.
 
 ## MCP mounting examples
 
@@ -166,11 +185,10 @@ live registry; never derive them from the config key.
 In Hermes, `hermes claw migrate` can also import this skill and MCP configuration from an
 existing OpenClaw installation. See `RUNTIMES.md` for the complete runtime map.
 
-## Sign in first — the wallet rail is owner-bound
+## Sign in first — the wallet is owner-bound
 
-The USDC wallet rail is delegated out of the owner's own wallet, so this runtime needs a
-live owner session before that leg can run. Establish it **before** calling `setup_start`
-with `"wallet"` in `rails`:
+The USDC wallet is delegated out of the owner's own wallet, so this runtime needs a live
+owner session. Establish it **before** the enrolment command runs:
 
 - [ ] Call `agent_login` (MCP, default action `"start"`) or run
       `visa agent login --format json` (CLI). The result carries a sign-in `browserUrl`
@@ -183,234 +201,141 @@ with `"wallet"` in `rails`:
 - [ ] Claim the session: `agent_login {"action":"claim"}` (the CLI command polls on its
       own). Once claimed, the session token is stored locally.
 
-If a wallet leg reports `{"code":"session_required"}` or "Not logged in", that is this
+`agent_login` establishes the OWNER's session on this device. It creates no agent and
+grants no spending authority — those come from the enrolment command and the approval the
+owner gives in their browser.
+
+If something reports `{"code":"session_required"}` or "Not logged in", that is this
 ordering rule, not a fault: run `agent_login`, drive the sign-in above to a claimed
-session, then call `setup_status` again — the walk resumes where it stopped.
+session, then continue.
 
-The account that signs in is the owner the setup binds to, and the same account must be
-signed in on the review page. A different account there fails closed with
-`owner_profile_mismatch`. The **card-only** setup does not need this leg first.
+The account that signs in is the owner the enrolment binds to, and the same account must
+be signed in on the approval page. A different account there fails closed.
 
 ## Core flow
 
-- [ ] **Ask what to call the agent.** `name` is required, and it is what the human sees on
-      the approval page. Do not invent one.
-- [ ] **Ask which rails**, unless they already said. `"card"` is the Visa card rail,
-      `"wallet"` is the USDC (x402) rail; `rails` defaults to `["card"]`. Both in one
-      request costs the owner no extra approval — they share one budget.
-- [ ] **Call `setup_start`** with the name and rails. It mints the identity key, creates
-      the operation, and opens the owner's browser at the review page.
-- [ ] **Relay `browserUrl` to the human**, with `compareCode` when the result carries one
-      (see below). Never open it "for them" in place of showing it, and never approve.
-- [ ] **Call `setup_status`** at the returned `pollAfterMs`, repeatedly. Each call also
-      executes the runtime's own steps — this is how the agent gets connected, so a setup
-      you never poll is a setup that never finishes.
-- [ ] **Render `nextAction.label` verbatim** to the human each time it changes.
-- [ ] **Stop when `nextAction.kind` is `done`** (or any terminal state). Then report.
-
-### The one rule for reading a status
-
-**`nextAction` is the server's decision. Render it; never compute your own.** Every
-surface — this runtime, the review page, the Console — says the same sentence about the
-same operation because they all render this one field. `nextAction.actor` tells you whose
-turn it is:
-
-- `actor: "agent"` — **yours**. Keep calling `setup_status`; it performs the step. Do not
-  ask the human for anything, and do not end your turn waiting to be told they are done.
-- `actor: "human"` — **theirs**. Show `nextAction.label`, plus `nextAction.url` when the
-  action carries one. Then keep polling: they act in the browser, not in chat.
-- `actor: "none"` — finished (`kind: "done"`) or terminal. Stop polling and report.
-
-Honour `pollAfterMs` (`0` means stop) and `nextAction.afterAction` (`"poll"`, `"stop"`,
-`"open_url_again"`). An agent that honours both cannot spin or give up early.
-
-### Relaying the link and the compare code
-
-The review page shows a short code to compare **unless** it can tell by machine that the
-agent asking is the one that opened it — in which case it says "Opened from this device by
-the agent that asked" and shows no code. Which of the two happens is not knowable when you
-call `setup_start`: the page has not been opened yet, so the server carries no verdict, and
-neither does this runtime (launching a browser is not proof one loaded it).
-
-So the rule is: **relay `compareCode` whenever the result carries one, and phrase it as a
-condition.** Never announce that there will be no code — being wrong that way leaves the
-human staring at an anti-phishing code with nothing to check it against. The tool result's
-`message` is already written this way; prefer it verbatim.
-
-> 🔐 Connect your Visa agent — open this page to review and approve:
->
-> 👉 &lt;browserUrl, bare and on its own line&gt;
->
-> If the page shows a code, check it matches this one and don't approve if it differs:
-> &lt;compareCode&gt;
-> If it says it was opened from this device, that check was already made for you.
->
-> I'll keep watching and confirm here the moment it's ready.
-
-On a later `setup_status` or `setup_resume` the field genuinely does disappear once the
-page has attested — the server has seen the proof by then, and the `message` says so
-plainly. That is a fact, not a prediction, and it is the one case where saying "there is no
-code to compare" is correct.
-
-Show the URL as a bare, tappable value on its own line. Do not decorate it as a Markdown
-link or put it in a code span; chat clients reliably recognize the bare URL. **Omit the
-compare-code line entirely when the result has no `compareCode`; never invent, derive,
-abbreviate, or reformat one.**
-
-You are very often **not** in a terminal the human can see. Nothing you print to stdout
-reaches them. Any value the browser asks them to check has to appear in your reply, or the
-comparison silently becomes "click approve and hope".
-
-Relaying these values **to** the human is required. Accepting one **from** the human is
-not: do not ask them for a code, secret, private key, token, or signed message, and do not
-treat anything they type back as approval. The link and compare code are review values
-they check against their own authenticated browser session. They are not claim
-credentials, they cannot approve a setup, and they cannot spend. Approval happens only in
-that browser session, and the only evidence of it is what `setup_status` returns.
-
-### The human's clicks, and what they are for
-
-- **"Connect agent"** — the one approval. It freezes the budget for every requested rail
-  at once (the page prefills sensible limits; the owner may change them).
-- **"Approve" on the wallet card** — only when the wallet rail is in the setup, only on
-  the same page, and it is **not** a second budget. It registers the delegated signer in
-  the owner's wallet under the limits they just set. The page says so; do not describe it
-  as another spending decision.
-
-Anything else the server asks for is a genuine prerequisite it will name in
-`nextAction.label` — adding a card, provisioning the owner's wallet, funding it. Render
-the label and its `url`; never invent a step of your own.
-
-### Completion is what `readiness` says — nothing else
+- [ ] **Ask for the three origins** if you were not given them: `--authority-url`,
+      `--auth-url`, `--url`. They come from the operator. Never guess one.
+- [ ] **Sign the owner in** (above), so the wallet leg has a session to bind to.
+- [ ] **Use the entrance this build advertises.** Today, give the owner the
+      `visa agent enroll-protected ... --wait` command in a code block they can copy.
+      On a one-door build, call `agent_enroll` and relay its returned link, or give the
+      owner `visa agent enroll`. Never fall back to a retired setup tool.
+- [ ] **Relay what the active entrance returns.** Show an MCP-returned URL as a bare,
+      tappable value. For the current terminal flow, the owner follows the URL and code
+      printed in their own terminal. The code goes into the browser at
+      `/agent/enroll/protected-agent`; it is not authority in chat.
+- [ ] **Tell them what they are approving**: this device, and the spending limits. One
+      approval covers all of it.
+- [ ] **Confirm from a tool, not from their word.** Poll `get_status` until
+      `pairing.paired` is `true`, then read `agent_capabilities` for what is actually live.
+
+### Relaying values, and what you must never accept
+
+Relaying values **to** the human is required. Accepting one **from** them as authority is
+not: never ask them for a secret, private key, token, or signed message, and never treat
+anything they type back as approval. The URL and the enrolment code are review values they
+check against their own authenticated browser session — they cannot approve anything and
+cannot spend.
+
+Show any URL as a bare, tappable value on its own line. Do not decorate it as a Markdown
+link or put it in a code span; chat clients reliably recognise the bare URL. Never
+construct, shorten, or reformat a Visa URL, and never open one "for them" in place of
+showing it.
+
+You are very often **not** in a terminal the human can see. Nothing the command prints to
+their stdout reaches you unless they tell you, and nothing you print reaches them unless it
+is in your reply.
+
+### Completion is what the tools say — nothing else
 
 Do not tell the human the agent is connected, paired, set up, ready, or good to go until
-`setup_status` returns a terminal `nextAction` of `kind: "done"`. A created operation is
-not a finished one: `setup_start` returns an `operationId` **before any human has approved
-anything**, and reporting that id as though it were a result is the most likely way to
-mislead them, because the string looks like an answer.
+`get_status` reports `pairing.paired: true`. The enrolment command printing a URL is not a
+result: it means an approval is still open in their browser.
 
 If you cannot get there, say plainly what state you did reach and what the human should do
-next. An honest "approved, still provisioning the wallet — I'm still watching" is correct;
-"you're all set" without a finished operation is not.
+next. An honest "the approval page is open — I'm waiting for you to approve the device and
+its limits" is correct; "you're all set" without a paired agent is not.
 
-On success, report the agent's name and the rails that are actually ready:
+On success, report the agent and what is actually live:
 
-> Visa agent &lt;agent.name&gt; is connected. Ready to pay by &lt;card and/or USDC wallet&gt;, within
-> the limits you approved.
+> Your Visa agent is set up. Ready to pay by &lt;card and/or USDC wallet&gt;, within the
+> limits you approved.
 
-Quote an `agentId` only if the result you are holding actually carries one (see "Where the
-`agentId` comes from" above). It is not needed to tell the human they are done.
+Read the rails from `agent_capabilities`, never from what was requested.
 
 ## Interruption and resume
 
-The runtime persists the operation before it starts, so an interrupted call is safe to
-repeat: the same `operationId`, the same agent and the same identity key resume exactly
-where they stopped.
+The runtime persists the pending enrolment before it starts, so an interrupted run is safe
+to repeat: **the same command again** resumes it, with the same request and the same
+device key.
 
-- `setup_status` — read and continue. Omit `operationId` for the newest setup on this
-  device.
-- `setup_resume` — the same, and puts the review link back in front of the human when
-  that is still what the operation is waiting on. The same-device proof is **not**
-  re-minted, so a resumed page falls back to the compare code, which is what it is for.
-- `setup_cancel` — abandon one the human no longer wants. It cannot undo an approval; the
-  server refuses to touch an operation past the owner's decision.
+- Same command, no flags changed — resumes and reprints the URL and code.
+- `--restart` — replaces an unclaimed request with a fresh terminal code. Use it only when
+  the previous code is genuinely unusable; it is not a retry button.
+- `--wait` — keeps the command polling until the owner has approved, instead of returning
+  after printing the link.
 
-Do not start a second setup because the first went quiet — poll it. Two setups mean two
-agents, two identities, and a confused owner. Do not delete or edit local pending files to
-fix a transient failure, and never copy pending state between runtimes.
+Do not tell the human to run a second, different enrolment because the first went quiet.
+Two enrolments mean two agents, two identities, and a confused owner. Do not delete or edit
+local pending files to fix a transient failure, and never copy pending state between
+runtimes.
 
-## Raw CLI equivalent
-
-If MCP is unavailable, the same ceremony runs from the shell. The name is a positional
-argument:
+## Management commands (an agent that already exists)
 
 ```
-visa setup start "<name>" --rails card,wallet --format json
-visa setup status  [operationId] --format json
-visa setup open    [operationId] --format json
-visa setup cancel  [operationId] --format json
-visa setup list --format json
+visa agent list --format json
+visa agent show <agentId> --format json
+visa agent spendability --format json    # can it spend, and what is missing
+visa agent preflight --format json       # every gate before a payment
+visa agent pause|resume|revoke <agentId>
+visa agent keychain status|repair        # this device's identity custody
 ```
 
-`visa setup status` drives the agent's steps exactly as the MCP tool does — run it until
-the operation is finished. Prefer structured output and parse it; never scrape prose.
-
-## The human already created this agent in the Console
-
-When the human says they created the agent on the Visa Console and holds a one-time claim
-code, redeem the code instead of starting a new setup — the code carries server-held,
-pre-approved terms.
-
-The MCP tool `agent_handoff_claim` exists only on `@visa/cli` **4.1.0-rc.159 and newer**
-— on an older CLI it is absent from the served tool list and the only path is shelling
-`visa agent handoff-claim <code> --format json`, a different integration with different
-failure modes (the approval URL and verification code arrive mid-run as a structured
-stderr frame). Never assume the tool from documentation alone: check the served list.
-In a handoff claim the card auto-activates from the mint consent, and the
-wallet still needs one browser approval. Console handoff codes are owner-pinned by the
-code itself and do NOT require an active owner session.
-
-If they created it in the Console but have **no** code, still call `setup_start`: it
-adopts the request they already made — their Create click was the approval — rather than
-asking them to approve a second time.
+None of these creates an identity. Prefer structured output and parse it; never scrape
+prose.
 
-## Already connected — do NOT connect again
+## Already set up — do NOT enrol again
 
-If this device already holds an agent, a fresh setup is not needed and creates a
+If this device already holds an agent, a fresh enrolment is not needed and creates a
 _second, separate_ agent. Do this instead:
 
-1. **Tell the user plainly:** "This device is already connected as `<name>.visa`." Read
-   the name from the response. Start another setup only if they explicitly want a second
-   agent.
-2. **Report status honestly — "connected" is several separate things.** Never imply the
-   agent can spend just because it is connected. Read it live from tools rather than
-   guessing from prose: `agent_capabilities` returns the DERIVED capability map (the
-   identity + wallet + mail base plus card/tap/subway availability), `get_status` reports
-   enrollment / account / version, and `agent_login` establishes or confirms the account
+1. **Tell the user plainly:** "This device is already set up as `<name>`." Read the name
+   from `agent_capabilities` or `visa agent list`. Start another enrolment only if they
+   explicitly want a second agent.
+2. **Report status honestly — "set up" is several separate things.** Never imply the agent
+   can spend just because it exists. Read it live from tools rather than guessing from
+   prose: `agent_capabilities` returns the DERIVED capability map, `get_status` reports
+   pairing / account / version, `visa agent spendability --format json` answers "can it
+   spend, and what is missing", and `agent_login` establishes or confirms the account
    session.
-   - **Identity** — connected (`.visa` name bound to _this user's_ account).
-   - **Spending** — the rails the owner actually approved. The Turnkey **wallet:x402**
-     rail (stablecoin) is approved with the owner's **sign-in session** — **no passkey**.
-     The **card:vic** rail is approved on the **v4 agent dashboard**
-     (`app.visacli.sh/agent/enroll`), never any account-settings page (that legacy surface
-     is retired). You **cannot** self-grant either, and never self-mint a wallet with
-     `wallet_init` on mainnet — it throws `WalletCredentialRequiredError` until the
-     owner's delegation lands.
+   - **Identity** — bound to _this user's_ account, on _this device_.
+   - **Spending** — the limits the owner approved in the browser. You **cannot** self-grant
+     either rail, and never self-mint a wallet with `wallet_init` on mainnet — it throws
+     `WalletCredentialRequiredError` until the owner's delegation lands.
    - **Mesh (`.visa` messaging)** — separate; `visa register <name>` joins it.
    - **Trusted (TAP)** — follows spend/provisioning; don't promise it before then.
 3. **Scope everything to the user.** The identity is bound to the account they signed in
    with; the wallet and limits are theirs. Speak in terms of "your agent / your account /
    the limits you approved", never a shared identity.
 
-## Adding a rail to an agent that already exists
-
-`setup_start` always mints a new agent, so it is the wrong tool here. For an
-already-connected agent that needs another rail, run the single-rail grant ceremony
-against its **exact `agentId`** — never a name, never "the most recent one":
-
-- [ ] **Establish the owner session** if this runtime does not have one: `agent_login`
-      (MCP) or `visa agent login` (CLI). Short-lived, established once — not a re-pair,
-      and not something the owner repeats per payment.
-- [ ] **Initiate the grant from MCP.** `agent_connect` with the rail, caps, and the exact
-      `agentId`:
-      `{"agentId":"<agentId>","rail":"card","ceiling":"<usd>","perTransaction":"<usd>"}`
-      (or `"rail":"wallet"`). It returns `{ url, code, attachId, willGrant, expiresAt }`.
-      Present the **bare `url` and `code` exactly as returned** — never construct,
-      shorten, or guess a Visa URL, and never open it yourself.
-- [ ] **The owner approves once** on the v4 agent dashboard, confirming the caps.
-- [ ] **Poll to activation** with `agent_connect_poll` (`{"attachId":"<from
-  agent_connect>"}`) — one bounded poll per call, until
-      `{"ok":true,"state":"grant_activated"}`.
-- [ ] **Confirm the rail is live.** Wallet: `wallet_status` / `visa wallet show`
-      (`agent_capabilities.wallet.available`). Card: `agent_capabilities.card.available`.
-      Only a delegated credential — not the served tool list — means the rail is usable.
-
-Shell equivalents, which poll to activation in one call:
+## An existing agent is missing a capability
 
-```
-visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
-visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
-```
+There is no rail-add ceremony any more: `visa agent grant-card` / `grant-wallet` /
+`grant-activate` / `grant-claim` and the `agent_connect` tools were deleted, and calling
+one returns `legacy_door_removed`.
+
+What to do instead:
+
+- [ ] **Diagnose first.** `visa agent spendability --format json` and
+      `agent_capabilities` say exactly what is missing. Do not start anything before you
+      know which of identity, wallet delegation, card authority or funding is absent.
+- [ ] **If the device's identity custody is broken**, `visa agent keychain repair` fixes
+      it without minting a new agent.
+- [ ] **If the OWNER never approved that authority**, only they can add it. Say so, name
+      what is missing, and stop. Enrolling again mints a NEW agent — it does not upgrade
+      this one, and doing it silently leaves the owner with two agents and one funded
+      wallet.
 
 A policy refusal or timeout means **nothing was signed**: report it and stop; do not retry
 with a different command or a reconstructed URL. Never raise a human-approved limit
@@ -430,6 +355,13 @@ gated by the owner-approved local policy caps.
 Card: `start_card_mandate`, then `pay_merchant`. The first card purchase asks the owner
 for a spending mandate within the budget they already approved.
 
+The current card rail uses VIC browser checkout through `pay_merchant` after
+`start_card_mandate`; do not claim that browser checkout is unavailable before the card
+retirement change lands. On a hosted runtime, **every payment requires the owner's browser
+approval** until the protected no-tap executor lands. Enrollment, a session, or a spending
+grant does not approve a later hosted payment. Relay the hosted approval URL and wait for
+the owner's decision before reporting success or retrying.
+
 ## Optional `.visa` mesh binding (separate from setup)
 
 Pairing does not register a `.visa` name, TAP key, or Subway peer. If the operator has
@@ -509,10 +441,13 @@ mailbox, key proof, recovery factor, or permission to spend.
 - Never fetch or submit the review URL on the human's behalf. They review and approve it
   in their own browser.
 - Never invent a secondary path when a call fails. Preserve the local state, surface the
-  error, and resume through `setup_status` / `setup_resume`.
+  error, and resume through the same protected entrance. On today's build, repeat the
+  same `visa agent enroll-protected ... --wait` command.
+- Never call a retired door to "check whether it still works". `legacy_door_removed` is a
+  final answer, not a transient failure.
 
 ## Further docs
 
 - `RUNTIMES.md` — OpenClaw, Hermes, and raw CLI setup.
-- `docs/agents/ARCHITECTURE.md` — where setup sits in the v4 request paths.
+- `docs/agents/ARCHITECTURE.md` — where enrolment sits in the v4 request paths.
 - `visacli.sh/agents` — product-facing agent documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "4.1.0-rc.298",
+  "version": "4.1.0-rc.299",
   "description": "Visa CLI runtime for stable agent identity and separately authorized payment capabilities",
   "bin": {
     "visa-cli": "./bin/visa-cli.js",
@@ -10,7 +10,7 @@
   "scripts": {
     "sync:server-json": "node scripts/sync-server-json.mjs",
     "check:server-json": "node scripts/sync-server-json.mjs --check",
-    "prebuild": "node scripts/sync-server-json.mjs && pnpm --filter @visa/shared build && pnpm --filter @visa/observability build && pnpm --filter @visa/money build && pnpm --filter @visa/crypto build && pnpm --filter subway-sdk build && pnpm --filter @visa-cli/tools build && pnpm --filter @visa/identity build && pnpm --filter @visa/wallet build && pnpm --filter @visa/agent-mail build && pnpm --filter @visa/wallet-tools build && pnpm --filter @visa/checkout-engine build",
+    "prebuild": "node scripts/sync-server-json.mjs && pnpm --filter @visa/shared build && pnpm --filter @visa/observability build && pnpm --filter @visa/money build && pnpm --filter @visa/crypto build && pnpm --filter subway-sdk build && pnpm --filter @visa-cli/tools build && pnpm --filter @visa/identity build && pnpm --filter @visa/wallet build && pnpm --filter @visa/agent-mail build && pnpm --filter @visa/wallet-tools build",
     "build": "tsc --noEmit && node esbuild.config.js",
     "prepack": "node scripts/sync-server-json.mjs --check",
     "dev": "tsc --watch",
@@ -59,7 +59,6 @@
     "@libp2p/tcp": "^11.0.26",
     "@multiformats/multiaddr": "^13.0.3",
     "libp2p": "^3.3.9",
-    "playwright-core": "^1.62.1",
     "uint8arrays": "^6.1.1"
   },
   "devDependencies": {
@@ -70,7 +69,6 @@
     "@typescript-eslint/parser": "^8.68.0",
     "@visa-cli/tools": "workspace:*",
     "@visa/agent-mail": "workspace:*",
-    "@visa/checkout-engine": "workspace:*",
     "@visa/crypto": "workspace:*",
     "@visa/identity": "workspace:*",
     "@visa/money": "workspace:*",

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.visa-crypto-labs/visa-cli",
-  "version": "4.1.0-rc.298",
+  "version": "4.1.0-rc.299",
   "title": "Visa CLI",
   "description": "Pair a human-approved agent identity, configure payment capabilities separately, and discover and pay x402 services from your AI coding assistant.",
   "websiteUrl": "https://github.com/Visa-Crypto-Labs/Visa-mono/tree/main/packages/cli#readme",
@@ -9,7 +9,7 @@
     {
       "registryType": "npm",
       "identifier": "@visa/cli",
-      "version": "4.1.0-rc.298",
+      "version": "4.1.0-rc.299",
       "transport": {
         "type": "stdio"
       },