@visa/cli 4.1.0-rc.7 → 4.1.0-rc.70

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

@@ -0,0 +1,92 @@
+# Running Visa pairing in OpenClaw and Hermes
+
+`@visa/visa-cli-openclaw` is packaged for OpenClaw, but the pairing v2 skill is
+runtime-agnostic. OpenClaw, Hermes, and any runtime that can execute the `visa` CLI or
+mount its MCP server all use the same identity-only enrollment ceremony.
+
+## Plugins are runtime-specific
+
+| Axis            | OpenClaw                                                  | Hermes                                                                                          |
+| --------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Language        | JavaScript/TypeScript                                     | Python                                                                                          |
+| Plugin manifest | `openclaw.plugin.json` + `definePluginEntry` (`index.ts`) | `~/.hermes/plugins/<name>/plugin.yaml` + `__init__.py`, `ctx.register_tool(...)`                |
+| Config file     | `~/.openclaw/openclaw.json`                               | `~/.hermes/config.yaml`                                                                         |
+| Skills          | Markdown `SKILL.md`                                       | Markdown under `~/.hermes/skills/<name>/`                                                       |
+| MCP             | `mcp.servers.*`                                           | `mcp_servers.*`                                                                                 |
+| Migration       | —                                                         | `hermes claw migrate` imports skills, allowlists, compatible MCP servers, memory, and `SOUL.md` |
+
+The OpenClaw JavaScript tools do not load as a Hermes plugin. Portability comes from the
+Markdown skill, CLI, and MCP protocol instead.
+
+## One ceremony, three surfaces
+
+All supported surfaces share the same local pending record and pairing v2 protocol:
+
+1. OpenClaw: `pair_agent_start` / `pair_agent_poll`.
+2. Visa MCP server: `enroll_agent` with `action: "start"` / `action: "claim"`.
+3. Raw CLI: `visa agent enroll --format json` /
+   `visa agent enroll-claim --format json`.
+
+The start operation returns an authorization URL for the human. The browser receives only
+that URL. The runtime retains its private Ed25519 key and local claim material. Polling
+resumes the same pending identity and safely replays the same signed request after an
+interruption.
+
+On activation, use `agentId` as the stable identity. `identityKeyJkt` identifies the
+currently bound Ed25519 public key and can change after key rotation. Activation means the
+identity is paired only; payment methods, email, and tap bindings are separate future or
+follow-up configuration.
+
+## Install and mount
+
+Install the prerelease CLI, which provides both command names and the MCP server:
+
+```sh
+npm install -g @visa/cli@rc
+```
+
+There is no `visa mcp` subcommand. Run `visa-cli connect <runtime>` when supported, or
+configure `@visa/cli/dist/mcp-server/index.js` directly. Replace `<npm root -g>` below
+with the output of `npm root -g`.
+
+OpenClaw (`~/.openclaw/openclaw.json`):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "visa-cli": {
+        "command": "node",
+        "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
+      }
+    }
+  }
+}
+```
+
+Hermes (`~/.hermes/config.yaml`):
+
+```yaml
+mcp_servers:
+  visa-cli:
+    command: node
+    args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+```
+
+## Runtime setup map
+
+| Runtime       | Setup and pairing surface                                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| OpenClaw      | Install `@visa/visa-cli-openclaw` for the `pair_agent_*` tools and bundled skill. The plugin auto-mounts the Visa MCP server. The MCP or raw CLI surfaces remain valid alternatives. |
+| Hermes        | Run `visa-cli connect hermes`, install `pair-visa-agent/SKILL.md` under `~/.hermes/skills/`, and use `enroll_agent`. `hermes claw migrate` can import an existing OpenClaw setup.    |
+| Other runtime | Put `visa` on `PATH`, mount the same MCP server if supported, or use the raw `visa agent enroll` and `visa agent enroll-claim` commands as the universal fallback.                   |
+
+The skill itself can be installed with `visa agent skill`. Pass `--runtime <name>` or
+`--dir <path>` when auto-detection is not appropriate, then reload the runtime.
+
+## Optional Hermes wrapper
+
+A Hermes Python plugin may expose the same `pair_agent_start` and `pair_agent_poll` names
+by calling the canonical raw CLI commands and registering tools with
+`ctx.register_tool(...)`. It is optional: the MCP server and skill already expose the
+same protocol and persisted pairing state without a second implementation.

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

@@ -0,0 +1,402 @@
+---
+name: pair-visa-agent
+description: Pair a Visa CLI v4 agent identity to this runtime. Present one authorization link 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.6.7'
+  # 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
+  # missing; other runtimes (Hermes, Claude Code, …) self-provision via the
+  # bundled `scripts/setup.mjs` (see compatibility + Getting set up). @rc pinned
+  # until 4.1.0 is promoted to latest.
+  openclaw:
+    user-invocable: true
+    emoji: '🔐'
+    requires:
+      bins:
+        - visa
+    install:
+      - kind: node
+        package: '@visa/cli@rc'
+        bins:
+          - visa
+          - visa-cli
+---
+
+# 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.
+
+## 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.
+
+## Getting this skill
+
+The skill ships inside the public `@visa/cli` npm package. No clone of the private
+monorepo is required:
+
+```sh
+npm install -g @visa/cli@rc
+visa agent skill
+```
+
+`visa agent skill` auto-detects OpenClaw, Hermes, and Claude Code, 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.
+
+Access remains enforced by the Visa service. Installing the public package or skill does
+not authorize an account to pair.
+
+OpenClaw users also receive the skill with the `@visa/visa-cli-openclaw` plugin.
+
+## 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. **Pair.** Follow the core flow below.
+
+## MCP mounting examples
+
+Both runtimes use the same server entrypoint. Replace `<npm root -g>` with the output of
+`npm root -g`.
+
+OpenClaw (`~/.openclaw/openclaw.json`):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "visa-cli": {
+        "command": "node",
+        "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
+      }
+    }
+  }
+}
+```
+
+Hermes (`~/.hermes/config.yaml`):
+
+```yaml
+mcp_servers:
+  visa-cli:
+    command: node
+    args: ['<npm root -g>/@visa/cli/dist/mcp-server/index.js']
+```
+
+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. The activation result
+includes protocol version `2`, `pairingId`, stable `agentId`, the display name, and
+`identityKeyJkt`.
+
+## Fastest path — one shot (`visa agent pair`)
+
+If the `visa` CLI is on PATH, prefer the one-shot command — it does the whole flow
+from a single call, so the user types nothing after their initial request:
+
+```
+visa agent pair --format json
+```
+
+It returns `browserUrl`, `pairingId`, stable `agentId`, and the full public
+`requestKeyFingerprint` **immediately**. It starts a detached activation process only
+after the pending identity and private key are durable. Present the link and fingerprint
+for exact browser comparison. 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.
+
+## 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 — acquiring a wallet to spend
+
+Pairing binds **identity only**. To let this agent pay via the Turnkey x402
+(stablecoin) wallet, the wallet must be **delegated by the human owner** — the runtime
+never self-mints it. On mainnet (production) `wallet_init` throws
+`WalletCredentialRequiredError` until that delegation lands, so do NOT call it as a
+setup step. Follow this sequence:
+
+- [ ] **Pair** the identity (the flow above). Identity only — no wallet yet.
+- [ ] **Sign in the account session FIRST.** Wallet delegation is an account
+      operation, so this runtime needs a live owner session before `grant-wallet`:
+      `agent_login` (MCP) or `visa agent login` (CLI). Without a session the grant has
+      no account to delegate from.
+- [ ] **Initiate the wallet grant from MCP — no shelling.** Call `agent_connect`
+      (`{"rail":"wallet","ceiling":"<usd>","perTransaction":"<usd>"}`); omit `agentId`
+      to target the most recently paired agent. It creates the delegation request and
+      returns `{ url, code, attachId, willGrant, expiresAt }`. Present the bare `url`
+      and `code` to the human exactly as returned — the crypto approval happens in the
+      browser and **cannot** run inline in chat. Prefer this over the raw
+      `visa agent grant-wallet <agentId>` CLI ceremony; `setup_agent` (`{"rail":"wallet"}`)
+      still sequences identity → wallet → policy → ready if you need the next-step map.
+      If `agent_connect` returns `{"code":"session_required"}`, run `agent_login` first.
+- [ ] **Owner approves the wallet.** The human opens the `url` and confirms the wallet
+      grant on the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`), approving with
+      their **sign-in session — no passkey** — and confirming the caps. You cannot approve
+      on their behalf.
+- [ ] **Finish from MCP with `agent_connect_poll`.** Call `agent_connect_poll`
+      (`{"attachId":"<from agent_connect>"}`; or resume by `agentId`) — each call runs one
+      bounded poll. It returns `{"ok":false,"state":"...","blockedByKind":"awaiting_human_approval"}`
+      while pending; call again until it returns `{"ok":true,"state":"grant_activated","fundAddress":...,"caps":...}`.
+      Activation registers the delegated Turnkey signer + caps and writes the delegated
+      Turnkey credential (`turnkey.json`) to this runtime. It never spends.
+- [ ] **Confirm the real wallet** with `wallet_status` (or `visa wallet show`). Only a
+      provisioned/delegated credential — not the served tool list — means the wallet is
+      usable; `agent_capabilities.wallet.available` reflects this.
+- [ ] **Set the spend policy** with `wallet_policy_set` — per-transaction / daily /
+      session USD caps (plus optional network and merchant allow/deny lists) that refuse
+      any x402 payment BEFORE it is signed. This is the `policy` step in the
+      `setup_agent` chain, between a delegated wallet and spending.
+- [ ] **Spend** with `wallet_pay` (x402), enforced by the owner-approved local policy
+      caps. Never raise a human-approved limit yourself.
+
+Once the 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.
+
+Card checkout is a separate upgrade on top of this Turnkey-only base — approve a card on
+the **v4 agent dashboard** (`app.visacli.sh/agent/enroll`) with a **passkey**, then
+`start_card_mandate` / `pay_merchant` draw against it. Neither rail is enabled by pairing.
+
+## Core flow
+
+- [ ] Start the pairing with `pair_agent_start`, `enroll_agent` action `start`, or
+      `visa agent enroll --format json`.
+- [ ] Present the authorization URL, stable agent ID, and full public fingerprint 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.
+
+### 1. Start
+
+Start once. If there is already a pending pairing, poll it before creating another.
+
+The result provides `browserUrl`, stable `agentId`, and `requestKeyFingerprint`. 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 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;
+>
+> Public request-key fingerprint — compare every character in the browser:
+> &lt;requestKeyFingerprint, complete and untruncated&gt;
+>
+> Approve only if the fingerprint matches, then tell me when it is finished. The link
+> expires shortly.
+
+Do not ask the human for a code, secret, private key, token, or signed message. The URL,
+stable agent ID, and public fingerprint are review values, not claim credentials.
+
+### 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, enabled `checkout_agent_access`, and opted the MCP server into submission with
+`CHECKOUT_AGENT_ALLOW_SUBMIT=1`, 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
+
+- `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.

package/dist/skills/pair-visa-agent/scripts/setup.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Portable provisioner for the pair-visa-agent skill.
+//
+// Ensures the `visa` CLI is installed so ANY Agent Skills runtime can pair —
+// not just OpenClaw (whose `metadata.openclaw.install` auto-runs). Hermes,
+// Claude Code, and any other agentskills.io-compatible runtime run this bundled
+// script per the standard's `scripts/` execution stage.
+//
+// Safe to run repeatedly: it no-ops when `visa` already resolves. Pinned to @rc
+// because the v4 agent surface is prerelease (the @latest tag predates the
+// `visa agent` commands); drop the tag once 4.1.0 is promoted to latest.
+
+import { execSync } from 'node:child_process'
+
+function resolves(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+if (resolves('visa') || resolves('visa-cli')) {
+  console.log('✓ visa CLI already installed — nothing to do. Run the pairing flow in SKILL.md.')
+  process.exit(0)
+}
+
+console.log('Installing @visa/cli@rc (the v4 agent surface is prerelease)…')
+try {
+  execSync('npm install -g @visa/cli@rc', { stdio: 'inherit' })
+} catch {
+  console.error(
+    'Global install failed. Try `npm install -g @visa/cli@rc` manually (may need sudo, or set a\n' +
+      'user-writable npm prefix: `npm config set prefix ~/.npm-global` and add its `bin` to PATH).'
+  )
+  process.exit(1)
+}
+
+if (!resolves('visa') && !resolves('visa-cli')) {
+  console.error(
+    'Installed, but `visa` is not on PATH. Ensure your npm global bin dir is on PATH\n' +
+      '(`npm bin -g` shows it), then re-run this script.'
+  )
+  process.exit(1)
+}
+
+console.log('✓ visa CLI ready. Now run the pairing flow in SKILL.md.')

package/install.ps1

@@ -168,7 +168,6 @@ if ($npmExitCode -ne 0) {
 # Verify
 $cliCommandNames = Get-InstalledCliCommands
 $verifiedCommand = $null
-$verifiedCommandPath = $null
 $visaVersion = $null
 
 foreach ($commandName in $cliCommandNames) {
@@ -177,12 +176,9 @@ foreach ($commandName in $cliCommandNames) {
         continue
     }
 
-    # Capture the resolved executable path so the setup hand-off below runs
-    # exactly the binary verified here, not a fresh PATH lookup.
     $versionOutput = (& $commandInfo.Source --version 2>$null | Select-Object -First 1)
     if ($LASTEXITCODE -eq 0 -and $versionOutput) {
         $verifiedCommand = $commandName
-        $verifiedCommandPath = $commandInfo.Source
         $visaVersion = $versionOutput.Trim()
         break
     }
@@ -191,46 +187,12 @@ foreach ($commandName in $cliCommandNames) {
 Write-Host ""
 if ($verifiedCommand) {
     Write-Host "  Visa CLI $visaVersion installed." -ForegroundColor Green
-
-    # Hand off straight into setup so install -> setup -> signed-in is one
-    # uninterrupted flow. Hardening:
-    #  * Auto-launch only on an interactive console with input/output/error
-    #    all attached - setup must prompt and open a browser. Redirected
-    #    streams and CI fall back to printing the next step.
-    #  * Invoke $verifiedCommandPath (the path verified just above), not a
-    #    bare command name re-resolved through PATH.
-    #  * Pass only the literal "setup" argument - nothing caller-controlled.
-    if ($Host.Name -eq 'ConsoleHost' -and -not [Console]::IsInputRedirected -and -not [Console]::IsOutputRedirected -and -not [Console]::IsErrorRedirected -and -not $env:CI) {
-        Write-Host ""
-        Write-Host "  Continuing to setup..." -ForegroundColor Cyan
-        Write-Host ""
-        try {
-            $setupProcess = Start-Process -FilePath $verifiedCommandPath -ArgumentList @('setup') -Wait -NoNewWindow -PassThru -ErrorAction Stop
-        } catch {
-            Write-Host ""
-            Write-Host "  Setup could not start. Visa CLI is installed." -ForegroundColor Yellow
-            Write-Host "  PowerShell error: $($_.Exception.Message)" -ForegroundColor Yellow
-            Write-Host "  run '$verifiedCommand setup' when you're ready to finish." -ForegroundColor Yellow
-            Wait-BeforeExit
-            exit 1
-        }
-        if ($setupProcess.ExitCode -ne 0) {
-            Write-Host ""
-            Write-Host "  Setup exited before completion. Visa CLI is installed." -ForegroundColor Yellow
-            Write-Host "  run '$verifiedCommand setup' when you're ready to finish." -ForegroundColor Yellow
-            Wait-BeforeExit
-            exit 1
-        }
-        exit 0
-    } else {
-        Write-Host "  Run '$verifiedCommand setup' to get started." -ForegroundColor Cyan
-        Write-Host "  After setup, run /mcp inside Claude Code, not PowerShell, if Claude Code was already open." -ForegroundColor Cyan
-    }
+    Write-Host "  Connect an AI client with: $verifiedCommand connect <client>" -ForegroundColor Cyan
+    Write-Host "  Then ask your agent to call enroll_agent." -ForegroundColor Cyan
     Write-Host ""
 } else {
     $primaryCommand = $cliCommandNames | Select-Object -First 1
     Write-Host "  Installed but '$primaryCommand' was not runnable from PATH yet." -ForegroundColor Yellow
-    Write-Host "  Close and reopen PowerShell, then run: $primaryCommand setup" -ForegroundColor Yellow
-    Write-Host "  Run /mcp inside Claude Code after setup if you need to reconnect the MCP server." -ForegroundColor Yellow
+    Write-Host "  Close and reopen PowerShell, then run: $primaryCommand connect <client>" -ForegroundColor Yellow
     Write-Host ""
 }

package/install.sh

@@ -99,9 +99,6 @@ fi
 echo "$NPM_OUTPUT"
 
 # ── verify ────────────────────────────────────────────────────────────────────
-# Capture the absolute path resolved here so the setup hand-off below invokes
-# exactly the binary we just verified, instead of re-resolving "visa-cli"
-# through $PATH a second time.
 VISA_BIN=""
 VISA_VERSION=""
 if VISA_BIN="$(command -v visa-cli 2>/dev/null)"; then
@@ -111,40 +108,11 @@ fi
 echo ""
 if [ -n "$VISA_VERSION" ]; then
   ok "Visa CLI ${VISA_VERSION} installed."
-  # Hand off straight into setup so install -> setup -> signed-in is one
-  # uninterrupted flow. Hardening:
-  #  * Auto-launch only when output streams are real terminals and setup can
-  #    read from either stdin or /dev/tty. That keeps `curl ... | bash` usable:
-  #    the script arrives on stdin, while setup prompts still read from the
-  #    user's terminal. CI and redirected output print the next step instead.
-  #  * Invoke "$VISA_BIN" (the path verified just above), never a bare
-  #    "visa-cli" re-resolved through $PATH at call time.
-  #  * Pass only the literal "setup" argument — "$@" is never forwarded — so
-  #    nothing the script's caller controls reaches the installed binary.
-  if [ -t 1 ] && [ -t 2 ] && { [ -t 0 ] || [ -r /dev/tty ]; }; then
-    echo ""
-    info "Continuing to setup..."
-    echo ""
-    SETUP_EXIT=0
-    if [ -t 0 ]; then
-      "$VISA_BIN" setup || SETUP_EXIT=$?
-    else
-      "$VISA_BIN" setup </dev/tty || SETUP_EXIT=$?
-    fi
-    if [ "$SETUP_EXIT" -ne 0 ]; then
-      echo ""
-      warn "Setup exited before completion. Visa CLI is installed."
-      warn "run 'visa-cli setup' when you're ready to finish."
-      exit 1
-    fi
-    exit 0
-  else
-    info "Run 'visa-cli setup' to get started."
-    info "After setup, run /mcp inside Claude Code, not Terminal, if Claude Code was already open."
-  fi
+  info "Connect an AI client with: visa-cli connect <client>"
+  info "Then ask your agent to call enroll_agent."
 else
   warn "Installed, but 'visa-cli' was not found on PATH."
-  warn "You may need to restart your shell, then run: visa-cli setup"
+  warn "Restart your shell, then run: visa-cli connect <client>"
 fi
 echo ""