@visa/cli 4.1.0-rc.17 → 4.1.0-rc.170

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

@@ -1,12 +1,12 @@
 ---
 name: pair-visa-agent
-description: Pair a Visa CLI v4 agent identity to this device so the agent can pay on the user's behalf. You paste a link, the user enrolls on mobile web, and the credential auto-pairs back to this device — no code is ever typed back. Use when the user says "pair my agent", "enroll my Visa CLI", "connect my Visa wallet", "set up my agent identity", "get me set up to pay", "log in to Visa", or asks to connect/sign up their .visa account.
-compatibility: Needs the `visa` CLI (`npm i -g @visa/cli@rc`) — run `node scripts/setup.mjs` to auto-install it if missing — plus network access to the Visa verify-web origin. Works in OpenClaw, Hermes, or any Agent Skills runtime.
+description: Pair a Visa CLI v4 agent identity to this runtime. Sign the owner in first (agent_login), then present one authorization link, the returned public confirmation code, and the full public request-key fingerprint to the human, then poll until the runtime's local Ed25519 identity is activated. Use when the user says "pair my agent", "enroll my Visa CLI", "connect my Visa agent", or "set up my agent identity".
+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, or any Agent Skills runtime.
 allowed-tools: Bash(visa:*) Bash(visa-cli:*) Bash(node:*) Bash(npm:*) Bash(npx:*)
 metadata:
   author: visa
   homepage: https://visacli.sh/agents
-  version: '0.5.0'
+  version: '0.7.1'
   # OpenClaw-namespaced extension (agentskills.io keeps `metadata` free-form, so
   # non-standard runtime config lives here — `user-invocable` is not a standard
   # top-level field). OpenClaw auto-installs `install[]` when `requires.bins` are
@@ -15,7 +15,7 @@ metadata:
   # until 4.1.0 is promoted to latest.
   openclaw:
     user-invocable: true
-    emoji: '💳'
+    emoji: '🔐'
     requires:
       bins:
         - visa
@@ -27,80 +27,89 @@ metadata:
           - visa-cli
 ---
 
-# Pair a Visa CLI v4 Agent Identity
+# Pair a Visa CLI v4 agent identity
+
+Pair this runtime's locally generated identity with a human-approved Visa agent. Pairing
+protocol v2 has one ceremony and three equivalent ways to drive it:
+
+- **`pair_agent_start` / `pair_agent_poll`** — OpenClaw plugin tools.
+- **`enroll_agent` with `action: "start"` / `action: "claim"`** — the `visa` MCP server tool.
+- **`visa agent enroll --format json` / `visa agent enroll-claim --format json`** — the raw
+  CLI and universal fallback.
+
+Use the first surface available. Do not mix this flow with older pairing or login flows;
+all three surfaces above wrap the same v2 enrollment ceremony and local pending state.
+
+**Console handoff codes are a separate, compound ceremony.** When the human brings a
+one-time code minted by the Console's Create-agent flow, claim it instead of pairing:
+the code carries server-held, pre-approved terms and resolves identity + spending in one
+run (card auto-activates from the mint consent; wallet still needs one browser approval).
+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.
+
+## What pairing establishes
+
+Pairing activates an agent identity on this runtime:
+
+- `agentId` is the server-assigned, stable identifier for the agent.
+- The runtime creates and retains the private Ed25519 identity key. It sends only the
+  public JWK to the service.
+- `identityKeyJkt` is the thumbprint of the currently bound Ed25519 public key. It can
+  change when that key rotates, so it must never be presented or stored as the stable
+  agent identifier.
+- The human receives the authorization URL, stable agent ID, and full public request-key
+  fingerprint for exact comparison. Private key material, the local claim token, and signed
+  protocol messages stay with the runtime.
+- An `activated` result means **identity paired only**. Payment methods, an email address,
+  and tap bindings are separate configuration that may be added later. Do not infer any
+  of those capabilities from pairing success.
 
-Connects a Visa v4 identity (`.visa` name + delegated wallet + card) to THIS device
-through a mobile-web enrollment link. This is the device-link flow: the credential
-pairs back **automatically** to the terminal that started it. **No confirmation code is
-ever typed back into you** — the code is an out-of-band check the human reads to confirm
-the page they are on is the flow you started.
+## Getting this skill
 
-Driven through the local `visa` binary. **This skill is runtime-agnostic** — it works in
-OpenClaw, Hermes, or any agent runtime that can run the `visa` CLI or mount its MCP
-server (see Runtimes). Use whichever pairing surface your runtime exposes; they all wrap
-the same two `visa` commands:
+The skill ships inside the public `@visa/cli` npm package. No clone of the private
+monorepo is required:
 
-- **`pair_agent_start` / `pair_agent_poll`** — the OpenClaw plugin tools (parse JSON for you). Use these if present.
-- **`enroll_agent`** — the `visa` MCP server tool, if the runtime has the server mounted.
-- **`visa agent enroll` / `visa agent enroll-claim`** — the raw CLI, always available if `visa` is on PATH. The universal fallback.
+```sh
+npm install -g @visa/cli@rc
+visa agent skill
+```
 
-Pick the first one available; if unsure, shell out to the raw CLI commands — every path
-hits the same hand-off on this device.
+`visa agent skill` auto-detects OpenClaw, Hermes, Claude Code, and Codex, falling back to
+the project-local `./.agents/skills`. Pass `--runtime <name>` or `--dir <path>` to choose a
+target, `--force` to overwrite, or `--print` to read without writing. Reload or restart
+the agent runtime after installation so it registers the skill.
 
-## Getting this skill
+Access remains enforced by the Visa service. Installing the public package or skill does
+not authorize an account to pair.
 
-The skill ships **inside the public `@visa/cli` npm package** — no git clone of the
-(private) monorepo is required, so any agent box that can reach npm can install it:
+OpenClaw users also receive the skill with the `@visa/visa-cli-openclaw` plugin.
 
-```
-npm install -g @visa/cli@rc      # public npm — puts `visa` on PATH
-visa agent skill                 # plants this skill into your runtime's skills dir
-```
+## Getting set up
+
+1. **Install the prerelease CLI.** Run `npm install -g @visa/cli@rc`, or run the bundled
+   idempotent provisioner `node scripts/setup.mjs`. The `@latest` tag may not yet expose
+   the v4 agent commands. Installation puts `visa` and `visa-cli` on `PATH` and includes
+   `@visa/cli/dist/mcp-server/index.js`.
+2. **Mount the MCP server when the runtime supports MCP.**
+   - **OpenClaw:** installing `@visa/visa-cli-openclaw` auto-mounts the server by writing
+     `mcp.servers["visa-cli"]` in `~/.openclaw/openclaw.json`.
+   - **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 agent …` commands.
+3. **Sign the owner in.** Pairing starts are owner-bound — see "Sign in first" below. On a
+   fresh runtime this step is required before any pairing command will succeed.
+4. **Pair.** Follow the core flow below.
+
+## MCP mounting examples
 
-`visa agent skill` auto-detects OpenClaw / Hermes / Claude Code (falling back to the
-project-local `./.agents/skills`); pass `--runtime <name>` or `--dir <path>` to target
-one explicitly, `--force` to overwrite, or `--print` to read it without writing. After
-it lands, **reload/restart your agent** so the runtime registers the skill, then prompt
-the agent — "set up my Visa agent to pay" — to run the pairing flow below. (Installing a
-skill does not run it; the agent activates it on a matching prompt.)
-
-Access is gated server-side by the employee allowlist + Turnkey, so shipping the playbook
-over public npm exposes no capability — only allowlisted accounts can actually pair.
-
-(OpenClaw users also get it auto-bundled with the `@visa/visa-cli-openclaw` plugin. The
-`npx skills add` open-standard path applies once the skill is published to a public repo.)
-
-## Getting set up (install → mount → pair → transact)
-
-The whole flow, top to bottom:
-
-1. **Install the CLI (prerelease)** — `npm install -g @visa/cli@rc`, **or** run the bundled
-   provisioner `node scripts/setup.mjs` (idempotent — installs `@visa/cli@rc` only if `visa`
-   is missing; this is how **Hermes / Claude Code / any runtime** self-provisions, and what
-   OpenClaw runs automatically via the manifest). You **must** use the `@rc` tag: the
-   `@latest` tag (4.0.x) predates the `visa agent` commands and reports "does not expose
-   agent enroll". This puts both `visa` and `visa-cli` on PATH and ships the bundled MCP
-   server (`@visa/cli/dist/mcp-server/index.js`). (Once 4.1.0 is promoted to `latest`, bare
-   `@visa/cli` will work.)
-2. **Mount the MCP server** — one mount gives this agent the _entire_ v4 toolset:
-   - **OpenClaw:** installing the `@visa/visa-cli-openclaw` plugin **auto-mounts** the server
-     (its postinstall writes `mcp.servers["visa-cli"]` into `~/.openclaw/openclaw.json`).
-     Nothing to do by hand.
-   - **Hermes / anything else:** run `visa-cli install hermes` (or `visa-cli install <runtime>`).
-     This writes the server entry idempotently into the runtime's config (Hermes →
-     `~/.hermes/config.yaml` under `mcp_servers`). See Runtimes below for the exact shape.
-   - **No runtime integration?** The raw `visa agent …` CLI still works — the universal fallback.
-3. **Pair** — run the Core flow below. This binds a `.visa` identity + delegated wallet + card
-   to this device.
-4. **Transact** — once paired, use the mounted tools (see "What you can do once paired").
-
-## Runtimes
-
-One artifact, both runtimes. The `visa` CLI is the portable substrate; mount its MCP
-server so the runtime exposes the tools (both use the same server entrypoint — replace
-`<npm root -g>` with the output of `npm root -g`):
-
-**OpenClaw** (`~/.openclaw/openclaw.json`):
+Both runtimes use the same server entrypoint. Replace `<npm root -g>` with the output of
+`npm root -g`.
+
+OpenClaw (`~/.openclaw/openclaw.json`):
 
 ```json
 {
@@ -115,185 +124,420 @@ server so the runtime exposes the tools (both use the same server entrypoint —
 }
 ```
 
-**Hermes** (`~/.hermes/config.yaml`):
+Hermes (`~/.hermes/config.yaml`). **Hermes passes ONLY this `env:` map to the MCP
+subprocess — it does NOT inherit the gateway environment.** Omitting a required variable
+(an RC access code, the right `HOME`, `PATH`) makes the server exit on every start while
+`agent_capabilities` — which reads on-disk grant state, not live tool registration — can
+still report rails as available. Always set the map explicitly:
 
 ```yaml
 mcp_servers:
   visa-cli:
     command: node
     args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+    # Hermes does NOT inherit the gateway env. This map is the entire
+    # subprocess environment; omit VISA_RC_CODE and the server exits on boot.
+    env:
+      HOME: /home/<user> # the home that holds this runtime's .visa-cli state
+      VISA_RC_CODE: <access code>
+      PATH: /usr/local/bin:/usr/bin:/bin
 ```
 
-No MCP server configured? The raw `visa agent …` CLI commands below work as long as `visa`
-is on PATH. (In Hermes, `hermes claw migrate` also imports this skill from an existing
-OpenClaw install into `~/.hermes/skills/`.) See `RUNTIMES.md` for the full plugin/config map.
+Hermes also loads skills **per profile** from `~/.hermes/profiles/<profile>/skills/`, not
+from `~/.hermes/skills/`. `visa agent skill --runtime hermes` resolves this automatically:
+it targets the single profile when exactly one exists (or the one named by
+`HERMES_PROFILE`), and **fails loudly** on a multi-profile box instead of planting into
+the flat dir nothing reads — pass `--dir ~/.hermes/profiles/<profile>/skills` to choose.
+
+**Hermes sanitizes MCP server names when registering tools.** A server declared
+`visa-cli` in `mcp_servers:` registers its tools as `mcp__visa_cli__<tool>` — with an
+UNDERSCORE, not the declared hyphen. Anything that hardcodes `mcp__visa-cli__<tool>` gets
+`unknown tool` on every call while looking correct in review. Read tool names off the
+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.
+
+## JSON and exit-code contract
+
+Prefer structured output and parse it; never scrape prose.
+
+- The OpenClaw and MCP tools return structured objects directly.
+- Raw CLI commands support `--format json`.
+- `visa agent enroll-claim` exits `0` when activated, `3` when the human has not finished,
+  and `1` on a terminal failure.
+
+The start result includes protocol version `2`, `pairingId`, stable `agentId`, full
+`requestKeyFingerprint`, `browserUrl`, and expiry information. Newer builds also return
+`confirmationCode`, a short public code the browser review page displays for comparison.
+Present it when the field is present and skip it when it is absent; an older server or CLI
+simply omits it, which is not an error. The activation result includes protocol version
+`2`, `pairingId`, stable `agentId`, the display name, and `identityKeyJkt`.
+
+## Sign in first — pairing is owner-bound
+
+Pairing starts are authenticated as the owner: the service pins the owner account at
+initiation, and the browser review page rejects any other signed-in account
+(`owner_profile_mismatch`). So on a fresh runtime the ceremony has a mandatory first leg —
+establish the owner session **before** any pairing command:
+
+- [ ] Call `agent_login` (MCP, default action `"start"`) or run
+      `visa agent login --format json` (CLI). The result carries a sign-in `browserUrl`
+      and a short 6-character confirmation code.
+- [ ] Relay **both** to the human in your reply — the bare URL on its own line, and the
+      code. You are very often not in a terminal they can see; the chat message is the
+      only place these values reach them.
+- [ ] The human opens the link, signs in (Google or email), and **types the confirmation
+      code into the sign-in page** — into the browser, never back to you in chat.
+- [ ] Claim the session: `agent_login {"action":"claim"}` (the CLI command polls on its
+      own). Once claimed, the session token is stored locally and pairing can start.
+
+If a pairing command returns "An owner profile is required before pairing" or
+`{"code":"session_required"}`, that is this ordering rule — not a fault. Run `agent_login`,
+drive the sign-in above to a claimed session, then retry the same pairing command once.
+
+The account that signs in here is the owner the pairing binds to. The same person must
+approve the pairing link in the next step from that same signed-in browser session;
+a different account on the review page fails closed.
+
+## Fastest path — one shot (`visa agent pair`)
+
+If the `visa` CLI is on PATH, prefer the one-shot command — after the owner session above
+exists, it does the whole flow from a single call, so the user types nothing after their
+initial request:
 
-## Running commands
+```
+visa agent pair --format json
+```
 
-- Every command supports `--format json`; the tools use it. On success JSON goes to
-  stdout; on failure a JSON object with `error` (and, for claim, a `status`) goes to
-  stdout with a non-zero exit code. **Always parse the JSON — never scrape prose.**
-- `enroll-claim` exit codes are load-bearing: `0` = claimed (done), `3` = not ready yet
-  (poll again), `1` = terminal failure (stop, recover).
+On a runtime with no owner session it fails with "An owner profile is required before
+pairing" — run the sign-in leg above first, then re-run it.
+
+It returns `browserUrl`, `pairingId`, stable `agentId`, the full public
+`requestKeyFingerprint`, and — on newer builds — `confirmationCode` **immediately**. It
+starts a detached activation process only after the pending identity and private key are
+durable. Present the link, returned confirmation code, and fingerprint for browser
+comparison; omit only a confirmation code the result did not provide. When `claiming` is `background`,
+activation completes after approval without another command; if it is `manual`, run the
+returned `recoveryCommand` after approval. Use the step-by-step flow
+below when `pair` is unavailable or when driving the plugin/MCP tools — `enroll_agent`
+action `start` reports the same `claiming` / `recoveryCommand` fields and starts the same
+detached poller.
+
+## Returning & already-connected — do NOT re-pair
+
+If `pair`/`enroll` returns **`already_connected`** (or `alreadyConnected: true`), this
+device is **already set up** as an agent — a fresh pairing is neither needed nor
+possible (re-pairing an existing identity silently dead-ends). Do this instead:
+
+1. **Tell the user plainly:** "This device is already connected as `<name>.visa`."
+   Read the name from the response. Do **not** start another hand-off. `--new` /
+   `force:true` exists only if they explicitly want a _second, separate_ agent.
+2. **Report status honestly — "connected" is five separate things**, not one. Never
+   imply the agent can spend just because it's connected. Don't guess from prose —
+   read it live from tools: `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 session that spending grants require.
+   - **Identity** — connected (`.visa` name bound to _this user's_ account). ✓ once `already_connected`.
+   - **Spending** — a _separate human approval_, and there are two rails, each
+     approved on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`) — not any
+     account-settings page (that legacy surface is retired). The Turnkey
+     **wallet:x402** rail (stablecoin) is approved with the owner's **sign-in session**
+     (the Google/email auth-proxy) — **no passkey**. The **card:vic** rail is approved
+     with a **passkey**. You **cannot** self-grant either; there is no
+     `visa agent add-rail` command, and never self-mint a wallet with `wallet_init` on
+     mainnet — it throws until the owner's delegation lands.
+   - **Mesh (`.visa` messaging)** — with `SUBWAY_MESH=visa`, a returning device now
+     registers on `pair`; if `meshRegistered` is false, `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 the user
+   signed in with (their email); the wallet + spend limits are theirs. Speak in terms
+   of "your agent / your account / the limits you approved," never a shared identity.
+
+Missing **spend** blocks _checkout mandates_, not a delegated x402 wallet — but that
+wallet must first be acquired by owner approval (below); it is never self-minted.
+
+## What you can do once paired — granting spend authority (card or wallet)
+
+Pairing binds **identity only**. To let this agent pay, the human owner must **delegate**
+a spend rail — the runtime never self-mints one. There are two rails, and **one** ceremony
+drives both:
+
+- **`wallet:x402`** (Turnkey stablecoin) — owner approves with their **sign-in session, no
+  passkey**. On mainnet `wallet_init` throws `WalletCredentialRequiredError` until this
+  delegation lands, so never call it as a setup step.
+- **`card:vic`** (Visa card checkout) — owner approves with a **passkey**.
+
+The contract is identical for both rails, and it is **one command from you, one approval
+from the owner**. You never hand a command, code, or URL back to the human after they
+approve — you poll to completion yourself:
+
+1. **You run one command** naming the rail and caps.
+2. **The owner opens the returned link and approves once** (they may adjust the amount).
+3. **You poll to activation** — the owner does nothing further.
+
+- [ ] **Pair** the identity (the flow above). Identity only — no rail yet.
+- [ ] **Establish the owner session once.** Grant creation is an account operation, so this
+      runtime needs a live owner session: `agent_login` (MCP) or `visa agent login` (CLI).
+      If you just paired, the session from the sign-in-first leg is usually still live —
+      no re-login needed. This is a short-lived session established once — **not** a
+      re-pair, and **not** something the owner repeats per payment. If `agent_connect`
+      later returns `{"code":"session_required"}`, the session lapsed — run `agent_login`
+      again.
+- [ ] **Initiate the grant from MCP — no shelling, no invented URLs.** Call `agent_connect`
+      with the rail and caps: `{"rail":"card","ceiling":"<usd>","perTransaction":"<usd>"}`
+      (or `"rail":"wallet"`); omit `agentId` to target the most recently paired agent. 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 crypto approval happens in the owner's browser and cannot run
+      inline in chat. (`setup_agent {"rail":"card"|"wallet"}` returns the same next-step map
+      if you need it.)
+- [ ] **Owner approves once** on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`),
+      confirming the caps — **card with a passkey, wallet with their sign-in session**. You
+      cannot approve on their behalf.
+- [ ] **Poll to activation from MCP.** Call `agent_connect_poll` (`{"attachId":"<from
+      agent_connect>"}`; or resume by `agentId`) — one bounded poll per call. It returns
+      `{"ok":false,"state":"...","blockedByKind":"awaiting_human_approval"}` while pending;
+      call again until `{"ok":true,"state":"grant_activated","caps":...}` (wallet also
+      returns `fundAddress`). Activation registers the delegated signer + caps: wallet writes
+      the Turnkey credential (`turnkey.json`); card writes the card pointer. It never spends.
+- [ ] **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.
+- [ ] **Then spend against the owner-approved caps.** Wallet: set the policy with
+      `wallet_policy_set` (per-transaction / daily / session USD caps + optional network and
+      merchant allow/deny lists that refuse an x402 payment BEFORE it is signed), then
+      `wallet_pay`. Card: `start_card_mandate` then `pay_merchant`. Never raise a
+      human-approved limit yourself.
+
+**Raw CLI equivalent (one shot).** If you cannot drive MCP, the same ceremony runs from the
+CLI and `--wait` polls to activation in a single call. Present the URL it prints — don't
+invent one:
 
-## Core flow
+```
+visa agent grant-card   <agentId> --ceiling <usd> --per-transaction <usd> --wait
+visa agent grant-wallet <agentId> --ceiling <usd> --per-transaction <usd> --wait
+```
 
-Copy this checklist and track progress:
+Rail selection is the owner's call — wallet only, card only, or both. Newer builds also
+accept one compound command that runs the same ceremony per rail in sequence
+(`both` = card, then wallet, under the same caps — expect one extra approval trip):
 
-- [ ] Step 1 — Start the hand-off (`pair_agent_start` / `enroll_agent` / `visa agent enroll --format json`)
-- [ ] Step 2 — Present the link AND the confirmation code to the user
-- [ ] Step 3 — Poll until paired (`pair_agent_poll` / `visa agent enroll-claim --format json`) — auto-pairs, no code entry
-- [ ] Step 4 — Confirm the identity is bound to this device
+```
+visa agent connect --authority <card|wallet|both> --ceiling <usd> --per-transaction <usd> --wait
+```
 
-Below, "start" and "poll" mean whichever surface your runtime exposes (see the top of
-this skill). The returned fields and the poll semantics are identical across all of them.
+Use the stable `agentId` from pairing or `visa agent list` — never invent or alter the id.
+A policy refusal or timeout means **nothing was signed**: report it and stop; do not retry
+with a different command or a reconstructed URL.
 
-### Step 1 — Start the hand-off
+Once a wallet is delegated and a policy is set, these are the served wallet tools this agent
+can actually call: `wallet_discover` (search the public x402 Bazaar), `wallet_probe` (read a
+challenge without paying), `wallet_pay` / `wallet_directory_pay` (pay, policy-enforced),
+`wallet_history` / `wallet_reconcile` (local ledger + resolve `reconciling` holds),
+`wallet_fund` (funding address + faucet), and `wallet_export` (export key material —
+dangerous). All spending is gated by the owner-approved local policy caps.
+
+## Core flow
 
-**CRITICAL:** Only ONE hand-off can be in flight per device; starting a new one replaces
-any prior. If the user says they already started enrolling, go to Step 3 first.
+- [ ] Establish the owner session ("Sign in first" above) if this runtime does not have
+      one yet.
+- [ ] Start the pairing with `pair_agent_start`, `enroll_agent` action `start`, or
+      `visa agent enroll --format json`.
+- [ ] Present the authorization URL, stable agent ID, full public fingerprint, and the
+      `confirmationCode` when the start result carries one, to the human.
+- [ ] Poll with `pair_agent_poll`, `enroll_agent` action `claim`, or
+      `visa agent enroll-claim --format json`.
+- [ ] Report the stable `agentId` and that the identity is paired on this runtime.
 
-Start the hand-off (`pair_agent_start`, or `visa agent enroll --format json`). It returns
-`browserUrl`, `confirmCode`, `expiresAt`.
+### Completion is `activated` — nothing else
 
-If it returns an error containing `verify-web URL not available in stable builds`, this is
-a stable CLI build with the surface not yet public. **Do NOT proceed** — tell the user to
-set `VISA_VERIFY_WEB_URL` (or use a preview/RC build), then stop.
+Only a poll result of `activated` means this runtime is paired. Until you have one, do not
+tell the human the agent is connected, paired, enrolled, set up, ready, or good to go, and
+do not move on to spending, mail, or mesh steps that assume an identity.
 
-If it returns an error containing `RC build requires access` (often suffixed `Run: visa-cli
-setup`), this is an **older RC build** whose employee gate still fires on the pairing
-bootstrap. **Do NOT run `visa-cli setup`** — that is the legacy v3 GitHub-OAuth path, it is
-NOT how v4 pairing authenticates, and it dead-ends on the same gate. Recover by either
-upgrading to a current RC (`npm install -g @visa/cli@rc` — recent RCs exempt `agent enroll`
-/ `agent enroll-claim` from this gate) or, if the operator has the code, setting the
-`VISA_RC_CODE` env var on the host. Then retry the hand-off. Never substitute `setup` for
-pairing.
+`start` returning successfully is not completion. It returns a stable `agentId` and a
+`requestKeyFingerprint` **before any human has approved anything** — those are review
+values for the browser comparison, not evidence of pairing. Reporting an `agentId` as
+though it were a finished pairing is the most likely way to mislead the human here, because
+the number looks like a result.
 
-### Step 2 — Present the link AND the confirmation code
+If you cannot reach `activated`, say plainly what state you did reach and what the human
+should do next. An honest "approved but not yet activated — I'm still polling" is correct;
+"you're all set" without an `activated` result is not.
 
-Show BOTH clearly. The user opens the link on their phone.
+### 1. Start
 
-**Formatting rules — make it clean AND tappable in chat clients like Telegram:**
+Start once. If there is already a pending pairing, poll it before creating another.
 
-- **Bare, tappable link.** Put `browserUrl` on its own line as a plain URL — no backticks, no
-  code span, and do **not** wrap it as a Markdown `[label](url)` link. Telegram auto-linkifies
-  a bare URL (one tap opens the phone's browser); a code span is unclickable, and the long
-  pairing query string (`?cli=…&cliPk=…`, with underscores) breaks Telegram MarkdownV2 link
-  parsing. Add a short "👉 Tap to open on your phone" cue so it reads as an action.
-- **Emphasize the confirm code.** Show `confirmCode` in **bold** or `monospace` — both are
-  Telegram-safe (mono needs no escaping). It's read/compared, never clicked.
-- **Relative expiry.** "expires in about 15 minutes" — never the raw `expiresAt` ISO/UTC
-  timestamp (e.g. `2026-07-21T21:22:57Z`); a UTC time reads as noise.
-- **Scannable layout.** Short lines, a blank line between blocks, one leading emoji per block.
-- **Don't over-Markdown.** Telegram MarkdownV2 requires escaping `_ * [ ] ( ) ~ > # + - = | { } . !`,
-  so heavy formatting risks a broken render. A bold/mono code + a bare link + emojis is plenty —
-  keep the rest plain prose.
+The result provides `browserUrl`, stable `agentId`, `requestKeyFingerprint`, and — on newer
+builds — `confirmationCode`. 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. Show the complete fingerprint without truncation and tell the human to approve
+only when every character matches the browser review page.
 
-Use this shape:
+You are very often **not** in a terminal the human can see. Nothing you print to stdout
+reaches them. Every value the browser asks them to compare has to appear in your reply, or
+the comparison silently becomes "click approve and hope" — which is the whole failure this
+step exists to prevent.
 
-> 💳 **Pair your Visa agent** — open this on your phone:
+Use this concise shape:
+
+> 🔐 Pair your Visa agent — open this authorization page:
+>
+> 👉 &lt;browserUrl, bare and on its own line&gt;
+>
+> Stable agent ID: &lt;agentId&gt;
 >
-> 👉 &lt;browserUrl — bare, on its own line&gt;
+> Confirmation code — this exact code should appear on the page:
+> &lt;confirmationCode&gt;
 >
-> 🔐 Confirmation code: **&lt;confirmCode&gt;**
+> Public request-key fingerprint — compare every character in the browser:
+> &lt;requestKeyFingerprint, complete and untruncated&gt;
 >
-> On the final screen, check the code matches before you finish — only finish if it does. Never
-> type this code back to me or share it with anyone; it pairs back here automatically once you
-> finish. Expires in about 15 minutes.
-
-**Do NOT** ask the user to read the code back. **Do NOT** accept a code as input. Pairing
-is proven by a secret held on this device, not by anything the user types.
-
-### Step 3 — Poll until paired (auto-pair)
-
-Poll (`pair_agent_poll`, or `visa agent enroll-claim --format json`). With the raw CLI,
-read the **exit code** (`0` claimed / `3` not-ready / `1` terminal); the plugin tool
-returns the same as a `done`/`status` object. Then, based on the result:
-
-- `done: true` / exit 0, `status: "claimed"` → paired. Go to Step 4.
-- `done: false` / exit 3, `status: "not_ready"` → the user hasn't finished. Tell them
-  you're still waiting, then poll again. **Do not loop forever** — each poll already
-  waits ~9s; after a handful of polls, ask the user whether they've finished on their phone.
-- `done: true`, `status: "not_ready"`, `likelyExpired: true` → the 15-minute window
-  expired. Go back to Step 1.
-- `done: true`, `status: "confirm_mismatch"` → **STOP.** See Errors.
-- `done: true`, `status: "no_pending"` → no hand-off in flight. Go back to Step 1.
-
-### Step 4 — Confirm the identity is bound
-
-On `claimed`, tell the user their `name` (e.g. `alec.visa`) is paired to this device. Read
-`keyBound`:
-
-- `keyBound: true` → the agent key was generated on THIS device; its private half never
-  left it. Highest assurance.
-- `keyBound: false` → an existing agent was connected from a returning sign-in; no agent
-  key is held locally. Normal and expected for returning users — the credential is fully
-  valid.
-
-## What you can do once paired
-
-Pairing is the on-ramp. v4 is **non-custodial** — a Turnkey-delegated wallet bounded by
-on-device keys and policies, **not** a stored credit line or a server-custodied card.
-Describe it that way to the user. The mounted MCP server exposes:
-
-- **x402 wallet spend (the core rail)** — `wallet_discover` (find payable x402 services by
-  outcome; free) → `wallet_probe` (preview a fresh x402 challenge; free) → `wallet_pay` /
-  `wallet_directory_pay` (a bounded payment settled directly from the delegated wallet over
-  x402, wallet→endpoint — never touching credits, cards, or server-side spend controls).
-  These `wallet_*` tools are **default-on in the supported build** (the v4 wallet runtime is
-  bundled); spend stays bounded by the on-device wallet policy. The same rail is on the CLI
-  as `visa find` / `inspect` / `pay`.
-- **Visa catalog (curated tools)** — `discover_tools` → `execute_tool` (or `visa tools` /
-  `visa run`): enumerate the curated catalog and run a tool; paid ones show a preview and
-  settle inline. Distinct from the open x402 directory above.
-- **Subway mesh** — `subway_*` route calls across the agent mesh. **Gated:** present but only
-  reach the mesh once the `.visa` relay is wired (`SUBWAY_MESH` / `SUBWAY_RELAY_MULTIADDR`);
-  until then they no-op against an unreachable relay.
-- **Real-merchant card checkout (experimental, opt-in)** — `pay_merchant` fills and pays an
-  ordinary merchant web checkout with a **Verified Agent card credential**: a one-shot
-  network-token cryptogram minted **on this device** (non-custodial) — not a stored card,
-  not x402, not server-side spend controls. Two steps: `review` (free; returns merchant +
-  exact amount as a `reviewId`) then `pay` (requires `confirm: "PAY <reviewId>"` + a passkey,
-  and CHARGES). **Tester-gated** (`checkout_agent_access`) and **RC/preview builds only** —
-  opt-in, never paired-and-go.
-
-If a tool you expect isn't visible, the MCP server isn't mounted (or the v4 wallet runtime
-isn't bundled in this build) — go back to "Getting set up".
-
-## Important
-
-- **The confirmation code is display-only.** Show it; never ask for it; never accept it as
-  input. It lets the human verify the page matches the flow you started.
-- **Never read, print, log, or echo** the credential file or the enrollment pending file,
-  or the `browserUrl` query values beyond the single presentation to the user. The link
-  carries only a hash + a public key — safe in history — but treat it as one-time.
-- Do not run API-key setup, card enrollment, or a balance top-up as a substitute for
-  pairing. Once paired, use the `visa-cli` skill's Rail 1 commands to pay.
-
-## Limits
-
-| Limit                          | Value                                                        |
-| ------------------------------ | ------------------------------------------------------------ |
-| Hand-off validity              | 15 minutes from `pair_agent_start`                           |
-| In-flight hand-offs per device | 1 (a new start replaces the prior)                           |
-| Claim                          | single-shot server-side; once claimed the entry is destroyed |
-| Confirmation code              | 6 chars, no ambiguous glyphs; display-only                   |
-
-## Errors
-
-All errors are JSON with a non-zero exit code; `enroll-claim` tags them with `status`.
-
-| status / symptom                                                  | Cause                                                             | Recovery                                                                                                                                                                                  |
-| ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `error: verify-web URL not available in stable builds`            | Stable CLI build, surface not public                              | Set `VISA_VERIFY_WEB_URL` or use a preview build. Do not proceed otherwise.                                                                                                               |
-| `error: RC build requires access` (may say `Run: visa-cli setup`) | Older RC build whose employee gate still fires on the bootstrap   | **Do NOT run `visa-cli setup`** (legacy v3 GitHub-OAuth path; dead-ends on the same gate). Upgrade the RC (`npm install -g @visa/cli@rc`) or set `VISA_RC_CODE`, then retry the hand-off. |
-| `no_pending`                                                      | No hand-off in flight (never started, or already claimed/expired) | Start fresh with `pair_agent_start`.                                                                                                                                                      |
-| `not_ready`, `likelyExpired: false`                               | User hasn't finished the mobile flow                              | Wait, tell the user, poll again. Bounded polling only.                                                                                                                                    |
-| `not_ready`, `likelyExpired: true`                                | 15-minute window elapsed                                          | Start over with `pair_agent_start`.                                                                                                                                                       |
-| `confirm_mismatch`                                                | The claim didn't match THIS device's secret                       | STOP. Show the re-derived `confirmCode`. If the user did not just finish the flow, someone else may hold their link — start over. Never retry blindly.                                    |
-| `error` (network / malformed)                                     | Transport or server error                                         | Surface the message. Poll once more; if it persists, start over.                                                                                                                          |
+> Approve only if the code and fingerprint both match. The link expires shortly — I'll keep
+> watching and confirm here the moment it activates.
+
+Omit the confirmation-code line entirely when the start result has no `confirmationCode`;
+never invent, derive, abbreviate, or reformat one.
+
+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 URL, stable agent ID, confirmation code, and public
+fingerprint are review values the human checks against their own authenticated browser
+session. They are not claim credentials, they cannot approve a pairing, and they cannot
+spend. Approval happens only in that browser session, and the only evidence of it is a poll
+result of `activated`.
+
+**Do not end your turn here waiting to be told the human is done.** Presenting the link is
+not the end of the ceremony; go straight to the poll in §2 and drive it to a terminal
+state. Asking the human to report back is what strands a pairing: they approve in the
+browser, the server records it, and nothing ever writes the local record — so the ceremony
+expires while both sides believe the other is acting.
+
+When the start result reports `claiming: "background"`, a detached poller is already
+finishing activation and it will complete even if this turn ends; poll anyway so you can
+confirm the outcome. When it reports `claiming: "manual"`, that poller could NOT start and
+polling in this turn is the ONLY thing that will complete the pairing.
+
+### 2. Poll
+
+Poll the same pending pairing. Interpret results as follows:
+
+- `activated` — pairing is complete. Continue to the completion report.
+- `not_ready` with `likelyExpired: false` — the human has not finished. Wait and poll
+  again, using bounded retries rather than an endless loop.
+- `not_ready` with `likelyExpired: true` — the authorization window probably expired.
+  Start a fresh pairing.
+- `no_pending` — this runtime has no resumable pairing. Start a fresh pairing.
+- `error` — surface the error without exposing local pending data. Retry once if it is a
+  transient network failure; otherwise stop and ask the human to start again.
+
+### 3. Report completion
+
+On `activated`, report the display name when present and the stable `agentId`. You may
+also report `identityKeyJkt` as the current key fingerprint, but label it clearly as a
+rotatable key identifier.
+
+Use precise completion language:
+
+> Visa agent &lt;displayName&gt; is paired to this runtime. Stable agent ID: &lt;agentId&gt;.
+
+Do not claim that activation configured payments, email, tap bindings, or any other
+product capability. Those are separate follow-up configuration flows.
+
+## Interruption and replay safety
+
+The runtime persists its v2 pending record before sending the signed claim. If a request
+or response is interrupted, the next poll resumes the exact same `pairingId`, `agentId`,
+Ed25519 identity, and claim material. This makes an identical retry safe and avoids
+creating a second identity because a response was lost.
+
+The pending record remains until the activated agent record has been written durably.
+Therefore:
+
+- Poll before starting over.
+- Do not delete or edit pending files to fix a transient failure.
+- Do not regenerate keys for an existing pairing.
+- Do not copy pending state between runtimes.
+
+## Optional `.visa` mesh binding (separate from pairing)
+
+Pairing does not register a `.visa` name, TAP key, or Subway peer. If the operator has
+separately enabled and registered those channel bindings, the mounted `visa-cli` MCP server
+may expose `subway_register`, `subway_send`, `subway_inbox`, and `subway_find`.
+
+Mesh messaging is available only on a compatible RC/dev build with `SUBWAY_MESH=visa` and
+a reachable `SUBWAY_RELAY_MULTIADDR`. If those tools or the relay are unavailable, report
+that clearly and stop. Do not imply that identity pairing alone granted directory or
+messaging authority, and do not improvise another transport.
+
+## Optional agent mailbox (separate from pairing)
+
+Pairing does not provision an email address or inbox. If the agent needs a
+mailbox — e.g. to receive a merchant's account-signup or one-time-code email —
+connect one explicitly, from the paired runtime, with the raw CLI:
+
+```
+visa agent mail-connect <agentId>
+```
+
+This is CLI-only; no pairing step or MCP tool connects a mailbox. It requires an
+already-paired stable-agent identity on this runtime — it reads the local agent
+record and proves the Ed25519 identity to the service. It issues the stable
+agent mailbox if one does not exist, then stores an inbox-scoped credential in an
+owner-only `0600` runtime file so this runtime can read that one inbox.
+
+Be honest about scope. A mailbox grants an email address and the ability to read
+that inbox — nothing more. It is **not** identity, a wallet, spend authority, a
+card, or a `.visa` name, and it never authorizes a payment. Do not claim pairing
+set up mail. Once connected, the MCP `wallet_mail_status`, `wallet_mail_read`,
+and `wallet_mail_await_otp` tools read the inbox (e.g. to await a sender-checked
+one-time code); without the scoped credential those reads fail closed. Keep the
+org-wide AgentMail key off the runtime — provisioning happens only through
+`mail-connect` under operator control.
+
+## Optional checkout profile (separate from pairing)
+
+Pairing does not enable card checkout. If the operator has separately provisioned card
+authority and enabled `checkout_agent_access`, the experimental `pay_merchant` flow also needs a local
+`~/.visa-mcp/contact.json` file. Collect every value from the human before the first review;
+never infer or invent identity or address data. Write the file with mode `0600`.
+
+```jsonc
+{
+  "fullName": "Ada Lovelace",
+  "email": "ada@example.com",
+  "addressLine1": "1 Analytical Way",
+  "addressLine2": "",
+  "city": "San Francisco",
+  "state": "CA",
+  "postalCode": "94105",
+  "country": "US",
+}
+```
+
+`fullName` must be non-blank; `firstName` plus `lastName` is also accepted. The engine reads
+the exact keys `fullName`, `firstName`, `lastName`, `email`, `addressLine1`, `addressLine2`,
+`city`, `state`, `postalCode`, and `country`. The profile supplies checkout/cardholder and
+billing data only. Its `email` value is not the account's verified owner email, an agent
+mailbox, key proof, recovery factor, or permission to spend.
+
+## Security rules
+
+- Never read, print, log, paste, or transmit the private Ed25519 JWK or local claim token.
+- Never read or echo the pending pairing file. Present only the authorization URL returned
+  by the supported command or tool.
+- Never treat `identityKeyJkt` as the stable identity. Use `agentId` for references and
+  persistence.
+- Never fetch the authorization URL on the human's behalf. The human reviews and approves
+  it in their browser.
+- Never invent a secondary pairing path when polling fails. Preserve the pending state,
+  surface the error, and retry or restart through the same canonical enrollment flow.
 
 ## Further docs
 
-- `docs/agents/ARCHITECTURE.md` — where the enroll hand-off sits in the v4 request paths.
-- `visacli.sh/agents` — product-facing agent docs.
+- `RUNTIMES.md` — OpenClaw, Hermes, and raw CLI setup.
+- `docs/agents/ARCHITECTURE.md` — where enrollment sits in the v4 request paths.
+- `visacli.sh/agents` — product-facing agent documentation.