@visa/cli 2.0.0-rc.11 → 2.0.0-rc.13

package/README.md

@@ -31,7 +31,7 @@ Add to your MCP client config:
 }
 ```
 
-Once connected, your assistant will have access to all payment tools. The first time you use a paid tool, you'll be prompted to log in and enroll a card.
+Once connected, your assistant will have access to all payment tools. The first time you use a paid tool, you'll be prompted to log in and enroll a card — you'll get $1 in free credits to start.
 
 ---
 
@@ -47,7 +47,8 @@ visa-cli history      # Recent transactions with amounts and any generated media
 visa-cli hud enable   # Explicitly pin the Visa HUD below Claude Code input
 visa-cli hud disable  # Remove the Visa HUD from Claude Code
 visa-cli statusline   # Render the multi-line HUD Claude Code calls automatically
-visa-cli mcp          # Start the MCP server
+# MCP (stdio): run the bundled entrypoint (IDE configs use the same path — see getServerEntry in src/clients.ts)
+#   node "$(npm root -g)/@visa/cli/dist/mcp-server/index.js"
 ```
 
 ---
@@ -65,7 +66,7 @@ visa-cli status   # verify you're logged in
 
 ## Card enrollment
 
-Cards are tokenized via VGS — your raw card number never touches Visa servers. `add_card` opens a hosted VGS Collect form in your browser.
+Cards are tokenized via VGS — your raw card number never touches Visa servers. `add_card` opens a hosted VGS Collect form in your browser. You receive $1 in free credits on your first card enrollment.
 
 ```bash
 visa-cli add-card
@@ -75,6 +76,14 @@ Multiple cards can be enrolled. The first becomes the default; you can switch de
 
 ---
 
+## Credits & referrals
+
+You receive **$1 in free credits** when you enroll your first card — enough for about 16 AI images. Credits are used automatically before your card is charged.
+
+Share your referral link (visible in `get_status`) and you both get **$2 in free credits** when your referral enrolls a card.
+
+---
+
 ## Payments & Authentication
 
 Every paid tool call requires authentication. On macOS, this is Touch ID (or device password); on Windows and Linux, payments are server-verified with restricted spending limits. Your assistant will show you the amount and merchant before prompting. If you cancel, the payment is aborted — nothing is charged.
@@ -113,6 +122,9 @@ The create command prints the raw `vk_...` key once. Store it in your app or age
 | `remove_card` | Remove an enrolled card (authentication required) |
 | `set_default_card` | Change the default card (authentication required) |
 | `get_status` | Auth, card, spend limits, and budget summary |
+| `start_session` | Start a capped approval window for paid tools in this MCP process |
+| `get_session_status` | Show the active session cap, estimated spend, and remaining amount |
+| `close_session` | Close the active session and return to pay-as-you-go approvals |
 | `update_spending_controls` | Set daily and per-transaction limits (authentication required) |
 | `transaction_history` | Recent transactions with amounts and media URLs |
 | `feedback` | Submit feedback on a tool result |
@@ -171,6 +183,16 @@ Max per-transaction — hard cap per single tool call
 
 Both limits are enforced server-side. Authentication is always required per payment regardless of limits — this cannot be disabled. On macOS this means Touch ID; on other platforms, server-side verification with restricted spending limits applies.
 
+## Sessions
+
+Paid tools are pay-as-you-go by default: each paid call requests payment approval. To approve a capped window for the current MCP process, use `start_session`:
+
+```bash
+start_session capUsd=5
+```
+
+Paid calls then spend from that approval window until the cap is used, `close_session` is called, the session expires, or the MCP process restarts. Sessions are not reused across Claude/MCP restarts.
+
 ---
 
 ## Config & data locations
@@ -186,7 +208,7 @@ Both limits are enforced server-side. Authentication is always required per paym
 ## Troubleshooting
 
 **Touch ID prompt doesn't appear (macOS)**
-Make sure `visa-cli mcp` is running as a foreground process that has access to the macOS security framework. Running inside some sandboxed environments may prevent Touch ID. On Windows and Linux, biometric prompts are not used — payments are server-verified.
+Make sure the MCP process (`node …/dist/mcp-server/index.js`) runs in a foreground TTY with access to the macOS security framework. Running inside some sandboxed environments may prevent Touch ID. On Windows and Linux, biometric prompts are not used — payments are server-verified.
 
 **"Not logged in" after `visa-cli login`**
 Restart the MCP server after logging in — your MCP client needs to reconnect to pick up the new session.