lane-sdk 0.1.11 → 0.2.0

package/README.md

@@ -2,295 +2,143 @@
 
 > `npm install lane-sdk` — Add wallets and payments to your AI agents.
 
-Lane is the payment infrastructure for AI agents. It lets agent developers give their agents the ability to discover merchants, manage payment methods, and complete purchases — all through a type-safe SDK, 14 MCP tools, and a CLI.
+Lane is the payment infrastructure for AI agents. It lets agent developers give their agents the ability to discover merchants, manage payment methods, and complete purchases — all through a type-safe SDK, 28 MCP tools, and a CLI.
+
+**Stack:** TypeScript · Express · Supabase (PostgreSQL + RLS) · VGS · Visa Intelligent Commerce
+
+```
+Production:  https://api.getonlane.com/sdk
+Wallet app:  https://agent.getonlane.com
+Auth service: https://auth.getonlane.com
+```
 
 ```ts
 import Lane from 'lane-sdk'
 
-const lane = Lane.fromApiKey(process.env.LANE_KEY!)
+const lane = await Lane.create()
 
 // Discover merchants
 const { data: merchants } = await lane.merchants.list({ query: 'sneakers' })
-const merchant = merchants[0]
 
 // Search products
 const { data: products } = await lane.products.search({ query: 'jordan 4' })
 
 // Execute payment
 const txn = await lane.pay.execute({
-  recipient: merchant.domain,
+  recipient: merchants[0].domain,
   amount: 19999,  // cents
   currency: 'USD',
   description: 'Jordan 4 Retro',
 })
-
-console.log(txn.status)    // 'success'
-console.log(txn.receiptUrl) // 'https://...'
 ```
 
+---
+
 ## Table of Contents
 
-- [How It Works](#how-it-works)
+- [Architecture Overview](#architecture-overview)
+- [Three Ways to Integrate](#three-ways-to-integrate)
 - [Quick Start](#quick-start)
-- [Authentication](#authentication)
+- [Authentication Flows](#authentication-flows)
+  - [CLI Login (Device-Code Flow)](#cli-login-device-code-flow)
+  - [SDK Access Verification](#sdk-access-verification)
+  - [Config Resolution](#config-resolution)
+- [Payment Routing](#payment-routing)
+- [Merchant Discovery](#merchant-discovery)
+- [API Reference](#api-reference)
 - [SDK Resources](#sdk-resources)
 - [MCP Integration](#mcp-integration)
 - [CLI](#cli)
-- [Payment Routing](#payment-routing)
-- [Merchant Directory](#merchant-directory)
-- [Security](#security)
-- [Enterprise Features](#enterprise-features)
-- [Server](#server)
-- [Architecture](#architecture)
+- [Database Schema](#database-schema)
+- [Token Architecture](#token-architecture)
+- [Security & Compliance](#security--compliance)
+- [Middleware & Route Protection](#middleware--route-protection)
+- [Cross-Service Auth: SDK vs Lane-Auth](#cross-service-auth-sdk-vs-lane-auth)
+- [Project Structure](#project-structure)
+- [Environment Variables](#environment-variables)
 - [Development](#development)
 
-## How It Works
-
-### End-to-End Agent Payment Flow
-
-This is the core flow when an AI agent discovers a merchant and makes a purchase:
-
-```
- AI Agent (Claude, Cursor, etc.)
- │
- │  1. "Find me sneakers under $200"
- │
- ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│                           Lane SDK                                      │
-│                                                                          │
-│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────────────┐ │
-│  │  2. DISCOVER     │    │  3. SEARCH       │    │  4. PAY              │ │
-│  │                  │    │                  │    │                      │ │
-│  │  merchants.list  │───▶│  products.search │───▶│  pay.execute         │ │
-│  │  ({ query:       │    │  ({ query:       │    │  ({ recipient,       │ │
-│  │    "sneakers" }) │    │    "jordan 4" }) │    │    amount: 19999 })  │ │
-│  └────────┬─────────┘    └────────┬─────────┘    └──────────┬───────────┘ │
-│           │                       │                          │            │
-└───────────┼───────────────────────┼──────────────────────────┼────────────┘
-            │                       │                          │
-            ▼                       ▼                          ▼
-┌───────────────────┐  ┌───────────────────┐  ┌────────────────────────────┐
-│ Merchant Directory│  │  Product Catalog  │  │     Payment Pipeline       │
-│                   │  │                   │  │                            │
-│ • Legendary       │  │ • Jordan 4 Retro  │  │  Budget ──▶ Route ──▶ PSP │
-│   Sneakers        │  │   $199.99         │  │  Check      Engine    Charge│
-│ • tier: onboarded │  │ • Air Max 90      │  │                            │
-│ • fashion/shoes   │  │   $129.99         │  │  ┌────────────────────┐    │
-│                   │  │                   │  │  │ Routing Decision:  │    │
-│                   │  │                   │  │  │ billing_api (Tier 1)│   │
-│                   │  │                   │  │  └────────────────────┘    │
-└───────────────────┘  └───────────────────┘  └────────────────────────────┘
+---
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph Clients
+        AGENT["AI Agent<br/>(Claude, Cursor, Custom)"]
+        MCP_CLIENT["MCP Client"]
+        APP["Application Code"]
+    end
+
+    subgraph "Lane SDK (TypeScript)"
+        SDK_LIB["SDK Library<br/>Lane.create() · 22 resources"]
+        MCP_SERVER["MCP Server<br/>28 tools · stdio/HTTP"]
+        CLI["CLI<br/>npx lane · 26 commands"]
+    end
+
+    subgraph "HTTP Client"
+        CLIENT["LaneClient<br/>HMAC-SHA256 · Retries<br/>Circuit Breaker · Idempotency"]
+    end
+
+    subgraph "Lane Server (Express)"
+        MW["Middleware<br/>API Key Auth → Rate Limit<br/>→ HMAC Verify → Audit"]
+        ROUTES["Routes<br/>/agent/auth · /agent/admin<br/>/agent/wallet · /agent/pay<br/>/agent/merchant · ..."]
+        SERVICES["Services (23)<br/>Payment · Wallet · Budget<br/>Merchant · VIC · Mandate · ..."]
+    end
+
+    subgraph Infrastructure
+        VGS["VGS Vault<br/>PCI DSS Level 1"]
+        PSP["PSP Registry<br/>Stripe · Worldpay<br/>CyberSource"]
+    end
+
+    subgraph "Supabase"
+        DB["PostgreSQL + RLS<br/>32 migrations"]
+    end
+
+    AGENT --> MCP_CLIENT --> MCP_SERVER
+    APP --> SDK_LIB
+    AGENT --> CLI
+
+    MCP_SERVER --> CLIENT
+    SDK_LIB --> CLIENT
+    CLI --> CLIENT
+
+    CLIENT --> MW --> ROUTES --> SERVICES
+    SERVICES --> DB
+    SERVICES --> VGS --> PSP
 ```
 
-### Three Ways to Integrate
+---
 
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                            Your Application                             │
-├──────────────────┬────────────────────────┬──────────────────────────────┤
-│                  │                        │                              │
-│   MCP Server     │     SDK (TypeScript)   │          CLI                 │
-│                  │                        │                              │
-│  For AI agents   │  For application code  │  For developers & scripts   │
-│  that speak MCP  │  that calls Lane APIs  │  that need quick access     │
-│                  │                        │                              │
-│  14 tools:       │  17 resources:         │  16 commands:               │
-│  • discover_     │  • lane.merchants      │  • lane login               │
-│    merchants     │  • lane.pay            │  • lane pay                 │
-│  • pay           │  • lane.wallets        │  • lane balance             │
-│  • checkout      │  • lane.checkout       │  • lane checkout            │
-│  • check_balance │  • lane.admin          │  • lane set-budget          │
-│  • ...           │  • ...                 │  • ...                      │
-│                  │                        │                              │
-│  ┌────────────┐  │  ┌──────────────────┐  │  ┌────────────────────────┐ │
-│  │ stdio or   │  │  │ Lane.fromApiKey() │  │  │ npx lane <command>    │ │
-│  │ HTTP       │  │  │ Lane.create()     │  │  │ Reads ~/.lane/creds   │ │
-│  │ transport  │  │  │                   │  │  │                       │ │
-│  └─────┬──────┘  │  └────────┬─────────┘  │  └───────────┬───────────┘ │
-│        │         │           │             │              │              │
-├────────┴─────────┴───────────┴─────────────┴──────────────┴──────────────┤
-│                          Lane HTTP Client                                │
-│               HMAC-SHA256 · Retries · Circuit Breaker                    │
-└──────────────────────────────────┬───────────────────────────────────────┘
-                                   │
-                                   ▼
-                          Lane API Server
-```
+## Three Ways to Integrate
 
-### Payment Routing Decision Tree
+```mermaid
+graph LR
+    subgraph "MCP Server"
+        MCP["28 tools<br/>Zod validation<br/>JSON responses<br/><br/>stdio or HTTP transport"]
+    end
 
-```
-                         Incoming Payment
-                              │
-                              ▼
-                    ┌───────────────────┐
-                    │   Budget Check    │
-                    │   within limits?  │
-                    └────────┬──────────┘
-                             │
-                    ┌────────┴────────┐
-                    │ NO              │ YES
-                    ▼                 ▼
-              ┌──────────┐  ┌──────────────────┐
-              │  DENIED  │  │ Lookup Merchant   │
-              │  budget  │  │ in Registry       │
-              │  exceeded│  └────────┬──────────┘
-              └──────────┘           │
-                            ┌────────┴─────────┐
-                            │                  │
-                            ▼                  ▼
-                    Has Billing API?     Supports ACP?
-                            │                  │
-                      ┌─────┴─────┐      ┌─────┴─────┐
-                      │YES        │NO    │YES        │NO
-                      ▼           │      ▼           │
-               ┌─────────────┐   │ ┌──────────┐     │
-               │   TIER 1    │   │ │  TIER 2  │     │
-               │ Billing API │   │ │   ACP    │     │
-               │ (cheapest)  │   │ │(protocol)│     │
-               └─────────────┘   │ └──────────┘     │
-                                 │                   │
-                                 └─────────┬─────────┘
-                                           │
-                                           ▼
-                                  Has VIC Token +
-                                  Visa Card?
-                                           │
-                                     ┌─────┴─────┐
-                                     │YES        │NO
-                                     ▼           ▼
-                              ┌──────────┐ ┌──────────┐
-                              │  TIER 3  │ │  TIER 4  │
-                              │   VIC    │ │ Fallback │
-                              │ (Visa    │ │ (standard│
-                              │  network)│ │  card)   │
-                              └──────────┘ └──────────┘
-```
+    subgraph "SDK (TypeScript)"
+        SDK["22 resource classes<br/>Lazy initialization<br/>Type-safe methods<br/><br/>Lane.create()"]
+    end
 
-### Merchant Discovery Flow
+    subgraph "CLI"
+        CLI_["26 commands<br/>Terse mode (-t)<br/>key=value output<br/><br/>npx lane &lt;cmd&gt;"]
+    end
 
-```
-                    ┌──────────────────────────────────────────┐
-                    │         Merchant Directory Service        │
-                    │                                          │
-                    │   In-Memory Cache (refreshed every 30m)  │
-                    └───────────┬──────────────┬───────────────┘
-                                │              │
-              ┌─────────────────┘              └──────────────────┐
-              │                                                    │
-              ▼                                                    ▼
-   ┌─────────────────────┐                          ┌──────────────────────┐
-   │  Lane-Onboarded     │                          │  Protocol Discovery  │
-   │  (Tier 1)           │                          │  (Tier 2)            │
-   │                     │                          │                      │
-   │  Sync from Lane     │                          │  Probe domain:       │
-   │  backend on startup │                          │                      │
-   │                     │                          │  GET /.well-known/ucp│
-   │  POST /merchants/   │                          │  GET /.well-known/acp│
-   │       sync          │                          │                      │
-   │                     │                          │  POST /merchants/    │
-   │  Full checkout API  │                          │       discover       │
-   │  Product catalog    │                          │                      │
-   │  Payment routing    │                          │  Protocol endpoints  │
-   └─────────┬───────────┘                          │  Cached manifests    │
-             │                                      └──────────┬───────────┘
-             │                                                  │
-             ▼                                                  ▼
-   ┌──────────────────────────────────────────────────────────────────────┐
-   │                        merchant_directory (PostgreSQL)               │
-   │                                                                      │
-   │  ┌─────────────────────────────────────────────────────────────────┐ │
-   │  │ id │ name               │ tier          │ type      │ vertical │ │
-   │  ├────┼────────────────────┼───────────────┼───────────┼──────────┤ │
-   │  │ ...│ Legendary Sneakers │ lane_onboarded│ ecommerce │ fashion  │ │
-   │  │ ...│ shop.example.com   │ protocol      │ ecommerce │ ...      │ │
-   │  └─────────────────────────────────────────────────────────────────┘ │
-   │                                                                      │
-   │  Indexes: slug (unique), domain (unique), subcategories (GIN),      │
-   │           name (trigram), tier, status, merchant_type, vertical      │
-   └──────────────────────────────────────────────────────────────────────┘
+    MCP --> HTTP["Lane HTTP Client<br/>HMAC · Retries · Circuit Breaker"]
+    SDK --> HTTP
+    CLI_ --> HTTP
+    HTTP --> API["Lane API Server"]
 ```
 
-### Security & Card Data Flow
-
-```
-                Agent adds a card
-                       │
-                       ▼
-            ┌────────────────────┐
-            │  VGS Collect Form  │    Card PAN entered in
-            │  (iframe/hosted)   │    VGS-controlled form
-            └─────────┬──────────┘
-                      │
-                      │  PAN goes directly to VGS
-                      │  (never touches Lane servers)
-                      ▼
-            ┌────────────────────┐
-            │  VGS Vault         │    PAN stored as token
-            │                    │    tok_4111...1234
-            │  PCI DSS Level 1   │
-            └─────────┬──────────┘
-                      │
-                      │  Token (alias) returned
-                      ▼
-            ┌────────────────────┐
-            │  Lane Server       │    Stores only: last4,
-            │                    │    brand, token alias
-            │  Never sees PAN    │    (never the full PAN)
-            └─────────┬──────────┘
-                      │
-                      │  Payment request with token
-                      ▼
-            ┌────────────────────┐
-            │  VGS Outbound      │    VGS replaces token
-            │  Proxy             │    with real PAN in-flight
-            └─────────┬──────────┘
-                      │
-                      │  Real PAN sent to PSP
-                      ▼
-            ┌────────────────────┐
-            │  PSP               │    Stripe / Worldpay /
-            │  (Payment          │    CyberSource processes
-            │   Processor)       │    the charge
-            └────────────────────┘
-```
+| | MCP Server | SDK | CLI |
+|---|---|---|---|
+| **Use case** | AI agents that speak MCP | Application code | Developers, scripts, agents via SKILL.md |
+| **Auth** | `LANE_API_KEY` env or `lane_connect` tool | `Lane.create()` or `Lane.fromApiKey()` | `npx lane login` → `~/.lane/credentials.json` |
+| **Output** | JSON tool responses | TypeScript objects | `key=value` pairs (terse mode) |
 
-### Enterprise Budget Enforcement
-
-```
-                         Payment Request ($150)
-                                │
-                                ▼
-              ┌─────────────────────────────────────┐
-              │       Hierarchical Budget Check      │
-              │                                     │
-              │  Org Budget     $10,000/mo  ✓ pass  │
-              │       │                             │
-              │       ▼                             │
-              │  Team Budget    $2,000/mo   ✓ pass  │
-              │       │                             │
-              │       ▼                             │
-              │  Dev Budget     $500/day    ✓ pass  │
-              │       │                             │
-              │       ▼                             │
-              │  Agent Policy   $200/txn    ✓ pass  │
-              │       │                             │
-              │       ▼                             │
-              │  Merchant       allowlist   ✓ pass  │
-              │  Allowlist      check              │
-              │       │                             │
-              │       ▼                             │
-              │  MCC Check      5661 (shoes) ✓ pass │
-              │                                     │
-              │  Effective limit = min(all levels)  │
-              └────────────────┬────────────────────┘
-                               │
-                          All passed
-                               │
-                               ▼
-                     Route to Payment
-```
+---
 
 ## Quick Start
 
@@ -304,8 +152,8 @@ npx lane login
 # Verify
 npx lane whoami
 
-# Check balance
-npx lane balance
+# Search merchants
+npx lane merchant list
 
 # Make a payment
 npx lane pay --recipient replicate.com --amount 20.00
@@ -320,704 +168,861 @@ import Lane from 'lane-sdk'
 const lane = await Lane.create()
 
 // Option 2: Explicit API key
-const lane = Lane.fromApiKey('lane_sk_...')
+const lane = await Lane.fromApiKey('lane_sk_...')
 
-// Option 3: Test mode
-const lane = Lane.fromApiKey('lane_sk_test_...', { testMode: true })
+// Option 3: Test mode (auto-detected from key prefix)
+const lane = await Lane.fromApiKey('lane_sk_test_...')
 ```
 
-## Authentication
+---
+
+## Authentication Flows
+
+### CLI Login (Device-Code Flow)
+
+The primary flow for authenticating via `npx lane login -t`. The SDK server orchestrates the flow; lane-auth is used only as an OTP popup.
+
+```mermaid
+sequenceDiagram
+    box rgb(230,240,255) lane-agent-sdk
+        actor Dev as Developer
+        participant CLI as Lane CLI
+        participant SDK as SDK Server<br/>/agent/auth/*
+        participant Wallet as Wallet App<br/>/authorize
+    end
+    box rgb(255,235,235) lane-auth
+        participant Auth as Auth Service<br/>auth.getonlane.com
+    end
+    participant DB as Supabase
+
+    Note over CLI,SDK: Phase 1 — Initiate
+    CLI->>SDK: POST /agent/auth/login
+    SDK->>DB: INSERT auth_sessions (pending, 10min TTL)
+    SDK-->>CLI: { sessionId, authUrl, deviceCode: "LANE-A3B7" }
+    CLI-->>Dev: "auth_url=... device_code=LANE-A3B7"
+
+    Note over Wallet,Auth: Phase 2 — Browser Auth
+    Dev->>Wallet: Open /authorize?s={sessionId}&redirect_port={port}
+    Wallet->>SDK: GET /agent/auth/device-status?s={sessionId}
+    SDK-->>Wallet: { deviceCode: "LANE-A3B7" }
+    Dev->>Wallet: "Codes match — continue"
+
+    rect rgb(255,235,235)
+        Note over Wallet,Auth: OTP login via lane-auth popup
+        Wallet->>Auth: window.open("/login?embed=true")
+        Auth-->>Dev: OTP email
+        Dev->>Auth: Enter 6-digit code
+        Auth-->>Wallet: postMessage("lane:auth:complete")
+    end
+
+    Note over Wallet,SDK: Phase 3 — Complete Session
+    Wallet->>SDK: POST /agent/auth/complete-session<br/>{ sessionId, userId, email }
+    SDK->>DB: UPSERT developers (sdk_access: true)
+    SDK->>DB: INSERT api_keys (lane_sk_ key)
+    SDK->>DB: UPDATE auth_sessions → completed
+    SDK-->>Wallet: { code }
+    Wallet-->>CLI: http://127.0.0.1:{port}/callback?code=...
+
+    Note over CLI,SDK: Phase 4 — Token Exchange
+    CLI->>SDK: POST /agent/auth/token { code, sessionId }
+    SDK->>DB: Verify + UPDATE auth_sessions → consumed
+    SDK-->>CLI: { apiKey: "lane_sk_...", developerId }
+    CLI->>CLI: Write ~/.lane/credentials.json
+    CLI-->>Dev: "ready=true email=..."
+```
+
+### SDK Access Verification
+
+Every `Lane.create()` call verifies the developer's SDK access before returning an instance.
+
+```mermaid
+sequenceDiagram
+    participant App as Application Code
+    participant SDK as Lane.create()
+    participant Server as SDK Server
+    participant DB as Supabase
+
+    App->>SDK: Lane.create()
+    SDK->>SDK: resolveConfig()<br/>API key from: args → env → credentials file
+
+    SDK->>Server: POST /agent/auth/verify-sdk-access<br/>Authorization: Bearer lane_sk_...
+    Server->>DB: SHA-256(key) → api_keys JOIN developers
+
+    alt sdk_access = true
+        Server-->>SDK: 200 { access: true }
+        SDK-->>App: Lane instance ready
+    else sdk_access = false
+        Server-->>SDK: 403 { code: "waitlist" }
+        SDK-->>App: throw Error("Coming Soon")
+    else Network error / timeout
+        Note over SDK: Fail open (offline dev)
+        SDK-->>App: Lane instance ready
+    end
+```
 
-Config resolution order (first match wins):
+### Config Resolution
 
-1. **Constructor:** `Lane.fromApiKey('lane_sk_...')` or `Lane.create({ apiKey: '...' })`
+API key resolution order (first match wins):
+
+1. **Constructor argument:** `Lane.create({ apiKey: '...' })` or `Lane.fromApiKey('...')`
 2. **Environment variable:** `LANE_API_KEY`
 3. **Credentials file:** `~/.lane/credentials.json` (written by `npx lane login`)
 
-```ts
-// Check who you are
-const profile = await lane.auth.whoami()
-// { id: 'dev_...', email: 'you@company.com', plan: 'pro', memberSince: '2025-01-15' }
+Config is frozen after resolution — no mutation allowed.
 
-// Rotate API key (old key valid for 15 min)
-const { apiKey, expiresOldKeyAt } = await lane.auth.rotateKey()
-```
+---
 
-## SDK Resources
+## Payment Routing
 
-The SDK exposes 17 resource classes, all lazily initialized on first access.
+Lane's routing engine selects the optimal payment path using a 5-tier priority system:
 
-### Core Resources
+```mermaid
+flowchart TD
+    START([Payment Request]) --> BUDGET{Budget check<br/>within limits?}
 
-| Resource | Description | Key Methods |
-|---|---|---|
-| `lane.auth` | Authentication & key management | `whoami()`, `login()`, `rotateKey()` |
-| `lane.wallets` | Wallet lifecycle & cards | `create()`, `list()`, `balance()`, `deposit()`, `listCards()`, `getAddCardLink()` |
-| `lane.pay` | Payment execution | `createToken()`, `execute()`, `listTransactions()`, `refund()` |
-| `lane.products` | Product discovery | `search()`, `get()`, `listMerchants()` |
-| `lane.checkout` | Checkout sessions | `create()`, `complete()`, `get()`, `cancel()` |
-| `lane.merchants` | Merchant directory | `list()`, `get()`, `listByVertical()`, `discover()`, `verticals()` |
-| `lane.sell` | Seller tools (Make-a-SaaS) | `create()`, `list()`, `analytics()`, `createSoftwareProduct()` |
-| `lane.webhooks` | Webhook management | `create()`, `list()`, `verify()`, `constructEvent()` |
-| `lane.admin` | Spending & budgets | `spending()`, `setBudget()`, `listMembers()`, `exportData()` |
-| `lane.subscriptions` | Subscription management | `create()`, `cancel()`, `upgrade()`, `pause()`, `resume()` |
+    BUDGET -->|No| DENIED([DENIED<br/>budget_exceeded])
+    BUDGET -->|Yes| LOOKUP[Lookup merchant<br/>in registry]
 
-### Phase 2 — VIC (Visa Intelligent Commerce)
+    LOOKUP --> T1{Has Billing API?}
+    T1 -->|Yes| TIER1([Tier 1: Billing API<br/>Direct integration — cheapest])
+    T1 -->|No| T2{Supports ACP?}
 
-| Resource | Description | Key Methods |
-|---|---|---|
-| `lane.vic` | Visa network tokens | `issue()`, `getCryptogram()`, `revoke()`, `suspend()` |
+    T2 -->|Yes| TIER2([Tier 2: ACP<br/>Agent Commerce Protocol])
+    T2 -->|No| T3{Supports UCP?}
 
-### Phase 4 — Make-a-SaaS
+    T3 -->|Yes| TIER3([Tier 3: UCP<br/>Universal Checkout Protocol])
+    T3 -->|No| T4{Has VIC token<br/>+ Visa card?}
 
-| Resource | Description | Key Methods |
-|---|---|---|
-| `lane.metering` | Usage tracking for sellers | `record()`, `recordBatch()`, `report()`, `setConfig()` |
-| `lane.payouts` | Seller disbursements | `getConfig()`, `setConfig()`, `list()` |
+    T4 -->|Yes| TIER4([Tier 4: x402<br/>Visa network token])
+    T4 -->|No| TIER5([Tier 5: Fallback<br/>Browser checkout / Rye])
 
-### Phase 5 — Corporate Agent Spend
+    style DENIED fill:#fee,stroke:#c00
+    style TIER1 fill:#efe,stroke:#0a0
+    style TIER2 fill:#efe,stroke:#0a0
+    style TIER3 fill:#efe,stroke:#0a0
+    style TIER4 fill:#efe,stroke:#0a0
+    style TIER5 fill:#ffe,stroke:#aa0
+```
 
-| Resource | Description | Key Methods |
-|---|---|---|
-| `lane.teams` | Team management | `create()`, `addMember()`, `setBudget()`, `getHierarchicalBudget()` |
-| `lane.agents` | Agent fleet management | `register()`, `setPolicy()`, `suspend()`, `assignWallet()` |
-| `lane.audit` | SOC 2 audit trail | `query()`, `export()`, `summary()` |
+### Budget Enforcement (Hierarchical)
+
+```mermaid
+flowchart TD
+    REQ([Payment $150]) --> ORG{Org budget<br/>$10,000/mo}
+    ORG -->|Pass| TEAM{Team budget<br/>$2,000/mo}
+    TEAM -->|Pass| DEV{Developer budget<br/>$500/day}
+    DEV -->|Pass| AGENT{Agent policy<br/>$200/txn}
+    AGENT -->|Pass| MERCHANT{Merchant<br/>allowlist check}
+    MERCHANT -->|Pass| MCC{MCC category<br/>check}
+    MCC -->|Pass| ROUTE([Route to payment<br/>effective limit = min of all])
+
+    ORG -->|Fail| DENY([DENIED])
+    TEAM -->|Fail| DENY
+    DEV -->|Fail| DENY
+    AGENT -->|Fail| DENY
+    MERCHANT -->|Fail| DENY
+    MCC -->|Fail| DENY
+```
 
-### Phase 6 — Agent Identity
+---
 
-| Resource | Description | Key Methods |
-|---|---|---|
-| `lane.identity` | Agent KYC chain | `register()`, `verify()`, `getAttestation()`, `refreshAttestation()` |
+## Merchant Discovery
 
-### Usage Examples
+Two-tier merchant directory with in-memory cache (refreshed every 30 minutes):
 
-```ts
-// Wallets & Cards
-const wallet = await lane.wallets.create({ userId: 'user_123' })
-const cards = await lane.wallets.listCards(wallet.id)
-const balance = await lane.wallets.balance(wallet.id)
-
-// Payments
-const token = await lane.pay.createToken({
-  walletId: wallet.id,
-  amount: 5000,
-  merchant: 'legendarysneakers.com',
-  expiresIn: '1h',
-})
-const txn = await lane.pay.execute({
-  tokenId: token.id,
-  recipient: 'legendarysneakers.com',
-  amount: 4999,
-})
+```mermaid
+graph TB
+    subgraph "Merchant Directory Service"
+        CACHE["In-Memory Cache<br/>(30-min refresh)"]
+    end
 
-// Refunds
-const refund = await lane.pay.refund({
-  transactionId: txn.id,
-  reason: 'Wrong size',
-})
+    subgraph "Tier 1: Lane-Onboarded"
+        T1["Synced from Lane backend<br/>Full checkout API<br/>Product catalog<br/>Payment routing"]
+    end
 
-// Checkout profiles (saved address/email for faster checkout)
-await lane.wallets.setProfile(wallet.id, {
-  email: 'agent@company.com',
-  fullName: 'AI Agent',
-  billingLine1: '123 Main St',
-  billingCity: 'San Francisco',
-  billingState: 'CA',
-  billingPostalCode: '94105',
-  billingCountry: 'US',
-})
+    subgraph "Tier 2: Protocol Discovery"
+        T2["Probe domain:<br/>GET /.well-known/ucp<br/>GET /.well-known/acp<br/><br/>Cached manifests"]
+    end
 
-// Merchant accounts (saved credentials per merchant)
-await lane.wallets.saveMerchantAccount(wallet.id, {
-  merchantDomain: 'legendarysneakers.com',
-  merchantName: 'Legendary Sneakers',
-  authType: 'api_key',
-  apiKeyAlias: 'vgs_tok_...',
-})
+    CACHE --> T1
+    CACHE --> T2
 
-// Budgets
-await lane.admin.setBudget({
-  dailyLimit: 10000,    // $100.00
-  perTaskLimit: 5000,   // $50.00
-  merchantAllowlist: ['legendarysneakers.com'],
-})
+    T1 --> DB[(merchant_directory<br/>PostgreSQL)]
+    T2 --> DB
+```
 
-// Subscriptions
-const sub = await lane.subscriptions.create({
-  productId: 'prod_...',
-  plan: 'pro',
-  paymentSource: 'wallet',
-})
+### Taxonomy
 
-// Agent fleet management
-const agent = await lane.agents.register({
-  name: 'shopping-agent',
-  type: 'autonomous',
-  walletId: wallet.id,
-  policy: {
-    budget: { dailyLimit: 5000 },
-    maxTransactionAmount: 2500,
-    canDiscover: true,
-    canRefund: false,
-  },
-})
+| Type | Verticals | Example Subcategories |
+|---|---|---|
+| `ecommerce` | fashion, electronics, beauty, home, food, sports | shoes, sneakers, laptops, skincare |
+| `software` | developer_tools, productivity, ai_ml, security | hosting, databases, ci_cd, auth |
+| `api` | data, communications, payments, infrastructure | enrichment, sms, processing, cdn |
+| `saas` | business, marketing, finance | crm, analytics, accounting |
+| `skill` | agent_tools | web_scraping, code_gen, research |
+| `service` | travel, delivery, professional | flights, food, legal |
 
-// Webhooks
-await lane.webhooks.create({
-  url: 'https://api.myapp.com/hooks/lane',
-  events: ['transaction.completed', 'budget.exceeded'],
-})
-```
+---
 
-## MCP Integration
+## API Reference
 
-Lane ships with 14 MCP tools that any AI agent (Claude, Cursor, etc.) can use out of the box.
+### Public Endpoints (no auth required)
 
-### Setup
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/agent/auth/login` | POST | Initiate browser auth session |
+| `/agent/auth/token` | POST | Exchange one-time code for API key |
+| `/agent/auth/complete-session` | POST | Complete CLI auth (called by wallet) |
+| `/agent/auth/device-status` | GET | Poll device code status |
+| `/agent/auth/verify-sdk-access` | POST | Check SDK whitelist (Bearer token) |
+| `/agent/discovery` | GET | Agent discovery metadata |
+| `/health` | GET | Health check |
 
-```bash
-# Auto-configure for Claude Desktop / Cursor
-npx lane setup-mcp
-```
+### Protected Endpoints (API key required)
+
+| Prefix | Description |
+|--------|-------------|
+| `/agent/admin` | `whoami`, `rotate-key`, `keys` list |
+| `/agent/wallet` | Wallet CRUD, balance, deposit |
+| `/agent/card` | Card management, VGS collect links |
+| `/agent/pay` | Token creation, payment execution, refunds |
+| `/agent/instruction` | VIC instruction lifecycle, credentials, confirmations |
+| `/agent/token` | Agentic token provisioning |
+| `/agent/transaction` | Transaction history, refunds |
+| `/agent/budget` | Budget get/set |
+| `/agent/merchant` | Merchant list, search, discover, verticals |
+| `/agent/product` | Product search, get |
+| `/agent/checkout` | Checkout sessions |
+| `/agent/subscription` | Subscription management |
+| `/agent/fleet` | Agent fleet management |
+| `/agent/team` | Team management |
+| `/agent/webhook` | Webhook CRUD |
+| `/agent/audit` | Audit trail queries |
+| `/agent/onboarding` | Onboarding key generation |
+
+### Legacy Endpoints (deprecated)
 
-Or add to your `claude_desktop_config.json`:
+| Prefix | Description |
+|--------|-------------|
+| `/api/sdk/auth` | Login, token exchange, key rotation |
+| `/api/sdk/wallets` | Wallet operations |
+| `/api/sdk/pay` | Payment operations |
+| `/api/sdk/admin` | Admin operations |
+| `/api/sdk/merchants` | Merchant directory |
 
+All `/api/sdk/*` responses include `Deprecation` and `Sunset` headers. Migrate to `/agent/*`.
+
+<details>
+<summary><strong>POST /agent/auth/login</strong></summary>
+
+**Response:**
 ```json
 {
-  "mcpServers": {
-    "lane": {
-      "command": "npx",
-      "args": ["lane-mcp-server"],
-      "env": {
-        "LANE_API_KEY": "lane_sk_..."
-      }
-    }
-  }
+  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
+  "authUrl": "https://api.getonlane.com/authorize?s=550e8400...",
+  "deviceCode": "LANE-A3B7"
 }
 ```
+</details>
 
-### Programmatic MCP Server
-
-```ts
-import { Lane, LaneMCPServer } from 'lane-sdk'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+<details>
+<summary><strong>GET /agent/admin/whoami</strong></summary>
 
-const lane = Lane.fromApiKey(process.env.LANE_API_KEY!)
-const server = new LaneMCPServer(lane)
+**Header:** `Authorization: Bearer lane_sk_...`
 
-const transport = new StdioServerTransport()
-await server.mcp.connect(transport)
+**Response:**
+```json
+{
+  "data": {
+    "id": "uuid",
+    "email": "dev@example.com",
+    "plan": "free",
+    "memberSince": "2026-03-20T..."
+  }
+}
 ```
+</details>
 
-### Available Tools (14)
+---
 
-| Tool | Description | Key Inputs |
-|---|---|---|
-| `whoami` | Get authenticated developer profile | — |
-| `check_balance` | Get wallet balance | `walletId?` |
-| `list_cards` | List cards in wallet | `walletId?` |
-| `pay` | Execute a payment | `amount`, `recipient`, `currency?`, `description?` |
-| `list_transactions` | List transaction history | `limit?`, `offset?` |
-| `search_products` | Search product catalog | `query`, `type?`, `limit?` |
-| `search_software` | Search software products | `query`, `type?`, `pricingModel?` |
-| `checkout` | Purchase a product | `productId`, `walletId?`, `quantity?` |
-| `set_budget` | Set spending limits | `daily?`, `weekly?`, `monthly?`, `perTask?` |
-| `request_refund` | Refund a transaction | `transactionId`, `amount?`, `reason?` |
-| `subscribe` | Create a subscription | `productId`, `plan`, `walletId?` |
-| `list_subscriptions` | List active subscriptions | `status?`, `limit?` |
-| `cancel_subscription` | Cancel a subscription | `subscriptionId` |
-| `discover_merchants` | Search merchant directory | `query?`, `merchantType?`, `vertical?`, `subcategory?` |
+## SDK Resources
 
-## CLI
+The SDK exposes 22 resource classes, all lazily initialized on first access.
 
-```
-lane <command>
+### Core Resources
 
-Authentication:
-  lane login           Start OAuth login flow (opens browser)
-  lane logout          Delete stored credentials
-  lane whoami          Display authenticated developer profile
-  lane rotate-key      Rotate API key
-
-Wallet:
-  lane balance         Get wallet balance
-  lane cards           List cards in wallet
-  lane add-card        Get VGS Collect link to securely add a card
-  lane wallet          Wallet management (list, create, deposit)
-  lane transactions    List transaction history
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.auth` | Authentication & key management | `whoami()`, `login()`, `rotateKey()` |
+| `lane.wallets` | Wallet lifecycle & cards | `create()`, `list()`, `balance()`, `deposit()`, `listCards()` |
+| `lane.cards` | Card management | `list()`, `get()`, `remove()` |
+| `lane.pay` | Payment execution | `createToken()`, `execute()`, `refund()` |
+| `lane.products` | Product discovery | `search()`, `get()` |
+| `lane.checkout` | Checkout sessions | `create()`, `complete()`, `get()`, `cancel()` |
+| `lane.merchants` | Merchant directory | `list()`, `get()`, `discover()`, `verticals()` |
+| `lane.admin` | Spending & budgets | `spending()`, `setBudget()`, `getBudget()`, `exportData()` |
+| `lane.budget` | Budget management | `get()`, `set()` |
+| `lane.transactions` | Transaction history | `list()`, `get()`, `refund()` |
+| `lane.tokens` | Agentic token lifecycle | `provision()`, `list()`, `revoke()` |
+| `lane.webhooks` | Webhook management | `create()`, `list()`, `verify()` |
+| `lane.subscriptions` | Subscription management | `create()`, `cancel()`, `upgrade()`, `pause()` |
 
-Payments:
-  lane pay             Execute a payment
-  lane checkout        Purchase a product from catalog
-  lane set-budget      Set spending limits
+### Commerce Protocol Resources
 
-Seller:
-  lane vendor          Seller tools (list products, view analytics)
-  lane schema          Display API schema
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.instructions` | VIC instruction lifecycle | `create()`, `getCredential()`, `confirm()` |
+| `lane.mandates` | Spending mandates | `create()`, `list()`, `evaluate()` |
+| `lane.protocol` | Multi-protocol sessions | `createSession()`, `execute()` |
+| `lane.vic` | Visa network tokens | `issue()`, `getCryptogram()`, `revoke()` |
+| `lane.sell` | Seller tools | `create()`, `list()`, `analytics()` |
 
-Setup:
-  lane setup-mcp       Configure MCP server for Claude/Cursor
-  lane wallet open     Open Lane wallet in browser
-```
+### Enterprise Resources
 
-## Payment Routing
+| Resource | Description | Key Methods |
+|---|---|---|
+| `lane.teams` | Team management | `create()`, `addMember()`, `setBudget()` |
+| `lane.agents` | Agent fleet management | `register()`, `setPolicy()`, `suspend()` |
+| `lane.fleet` | Fleet operations | `list()`, `getPolicy()` |
+| `lane.audit` | SOC 2 audit trail | `query()`, `export()`, `summary()` |
+| `lane.identity` | Agent KYC chain | `register()`, `verify()`, `getAttestation()` |
+| `lane.delegations` | Agent-to-agent delegation | `create()`, `verify()`, `revoke()` |
+| `lane.users` | User management | `list()`, `get()` |
+| `lane.metering` | Usage tracking (sellers) | `record()`, `recordBatch()`, `report()` |
+| `lane.payouts` | Seller disbursements | `getConfig()`, `setConfig()`, `list()` |
 
-Lane's routing engine selects the optimal payment path for each transaction using a 4-tier priority system:
+---
 
-```
-Tier 1: Billing API   — Direct merchant API integration (cheapest, fastest)
-Tier 2: ACP           — Agent Commerce Protocol checkout
-Tier 3: VIC           — Visa Intelligent Commerce token (works at any Visa merchant)
-Tier 4: Fallback      — Standard card payment via PSP
-```
+## MCP Integration
 
-The router considers merchant capabilities, card brand, VIC token availability, and budget constraints:
+Lane ships with 28 MCP tools. 4 work without authentication (discovery mode); 24 require a connected API key.
 
-```ts
-import { PaymentRouter, MerchantRegistry } from 'lane-sdk'
-
-const registry = new MerchantRegistry()
-registry.register({
-  merchantId: 'merch_123',
-  hasBillingAPI: true,
-  supportsACP: true,
-  supportsVIC: false,
-  acceptsVisa: true,
-  acceptsMastercard: true,
-  mccs: ['5661'],
-})
+### Setup
 
-const router = new PaymentRouter(registry)
-const decision = router.route({
-  amount: 4999,
-  currency: 'USD',
-  merchantId: 'merch_123',
-  cardBrand: 'visa',
-  hasVICToken: false,
-})
-// { route: 'billing_api', reason: 'Merchant has direct billing API integration (cheapest path).', fallbacks: ['acp', 'fallback'] }
+```bash
+# Auto-configure for Claude Desktop / Cursor
+npx lane setup-mcp
 ```
 
-The `MerchantRegistry` can be populated directly from the merchant directory:
+Or add to `claude_desktop_config.json`:
 
-```ts
-const capabilities = await container.merchantDirectory.populateRegistry()
-const registry = MerchantRegistry.fromDirectory(capabilities)
+```json
+{
+  "mcpServers": {
+    "lane": {
+      "command": "npx",
+      "args": ["lane-mcp-server"],
+      "env": { "LANE_API_KEY": "lane_sk_..." }
+    }
+  }
+}
 ```
 
-## Merchant Directory
+### Pre-Auth Tools (Discovery Mode)
 
-The merchant directory is a live, queryable registry of AI-shoppable merchants. Two tiers:
+| Tool | Description |
+|---|---|
+| `get_lane_info` | Platform overview and capabilities |
+| `lane_signup` | Start signup flow |
+| `lane_connect` | Connect API key to initialize SDK |
+| `resolve_ucp_merchant` | Resolve UCP merchant by domain |
 
-- **Lane-onboarded** — Full checkout API, synced from Lane backend (e.g., Legendary Sneakers)
-- **Protocol-compatible** — Merchants exposing `/.well-known/acp` or `/.well-known/ucp` endpoints
+### Post-Auth Tools (24)
 
-### Taxonomy
+| Tool | Description |
+|---|---|
+| `whoami` | Get developer profile |
+| `check_balance` | Get wallet balance |
+| `list_cards` | List cards in wallet |
+| `pay` | Execute a payment |
+| `list_transactions` | Transaction history |
+| `search_products` | Search product catalog |
+| `checkout` | Purchase a product |
+| `set_budget` | Set spending limits |
+| `request_refund` | Refund a transaction |
+| `subscribe` | Create a subscription |
+| `list_subscriptions` | List subscriptions |
+| `cancel_subscription` | Cancel a subscription |
+| `discover_merchants` | Search merchant directory |
+| `search_software` | Search software products |
+| `lane_add_card` | Add a payment card |
+| `lane_onboarding_status` | Check onboarding progress |
+| `protocol_pay` | Multi-protocol payment |
+| `create_mandate` | Create spending mandate |
+| `pay_with_mandate` | Pay using mandate authorization |
+| `get_mandate_budget` | Check mandate budget |
+| `get_instruction_budget` | Check instruction budget |
+| `register_agent` | Register agent in fleet |
+| `list_agents` | List fleet agents |
+| `provision_vic_payment` | Provision VIC credentials |
+| `confirm_instruction` | Biometric confirmation |
+
+---
 
-Merchants are classified hierarchically:
+## CLI
 
-| Type | Verticals | Example Subcategories |
-|---|---|---|
-| `ecommerce` | fashion, electronics, beauty, home, food_beverage, sports_outdoor, kids_baby | shoes, sneakers, laptops, skincare |
-| `software` | developer_tools, productivity, ai_ml, security | hosting, databases, ci_cd, auth |
-| `api` | data, communications, payments, infrastructure | enrichment, sms, processing, cdn |
-| `saas` | business, marketing, finance | crm, analytics, accounting |
-| `skill` | agent_tools | web_scraping, code_gen, research |
-| `service` | travel, delivery, professional | flights, food, legal |
+26 commands plus 6 deprecated aliases.
 
-### Vertical-Specific Product Attributes
+```
+lane <command>
 
-Each merchant stores a `productAttributes` schema tailored to its vertical:
+Authentication:
+  login              Authenticate (opens browser)
+  logout             Clear local credentials
+  whoami             Developer profile
+  status             Readiness check (wallet, card, budget)
 
-```ts
-// Fashion/shoes merchant
-{ available_sizes: ['7','8','9'], colors: ['black','white'], brands: ['Nike','Jordan'] }
+Wallet & Cards:
+  wallet             Wallet management (list, create, deposit, balance)
+  card               Card management (list, add, remove, get)
 
-// Electronics merchant
-{ specs: { ram_gb: 16, storage_gb: 512 }, brand: 'Apple', model_year: 2025 }
+Payments:
+  pay                Execute a payment
+  checkout           Purchase from catalog
+  checkout-bridge    Browser checkout with VIC credentials
+  budget             Budget management (get, set)
+  token              Token management (provision, list, revoke)
+  transaction        Transaction history
+
+Commerce:
+  merchant           Merchant discovery (list, discover, verticals)
+  product            Product search (search, get)
+  instruction        VIC instruction lifecycle (create, credential, confirm)
+  session            Shopping session management
+  batch              Parallel merchant discovery
+
+Enterprise:
+  fleet              Agent fleet management
+  team               Team management
+  user               User management
+  webhook            Webhook management
+  audit              Audit trail queries
+  vendor             Seller tools
 
-// Software merchant
-{ runtime: 'node', sdk_package: '@acme/sdk', docs_url: '...' }
+Setup:
+  setup-mcp          Configure MCP for Claude/Cursor
+  install-skill      Register Lane skill for auto-activation
+  schema             Display API schema
 ```
 
-### Usage
+All commands support `-t` / `--terse` flag for machine-readable `key=value` output on stdout.
 
-```ts
-// Search by text
-const { data } = await lane.merchants.list({ query: 'sneakers' })
-
-// Filter by vertical
-const fashion = await lane.merchants.listByVertical('fashion')
-
-// Filter by protocol
-const acpMerchants = await lane.merchants.listByProtocol('acp')
+---
 
-// Lane-onboarded only
-const onboarded = await lane.merchants.listOnboarded()
+## Database Schema
 
-// List all verticals and subcategories
-const verticals = await lane.merchants.verticals()
+32 migrations on Supabase (PostgreSQL) with Row Level Security on all tables.
 
-// Discover a protocol-compatible merchant by domain
-const result = await lane.merchants.discover('shop.example.com')
-```
+```mermaid
+erDiagram
+    developers ||--o{ api_keys : "has"
+    developers ||--o{ wallets : "owns"
+    developers ||--o{ auth_sessions : "authenticates"
 
-### Seeded Merchants
+    wallets ||--o{ cards : "has"
+    wallets ||--o{ agentic_tokens : "issues"
+    wallets ||--o{ transactions : "records"
+    wallets ||--o{ checkout_profiles : "has"
+    wallets ||--o{ merchant_accounts : "stores"
 
-The directory ships with pre-populated merchants including:
+    developers ||--o{ budgets : "sets"
+    developers ||--o{ audit_log : "audited"
+    developers ||--o{ agents : "manages"
+    developers ||--o{ mandates : "creates"
 
-- **Legendary Sneakers** (`legendarysneakers.com`) — Premium sneakers and streetwear. Lane-onboarded, Shopify/Worldpay, billing API + ACP support. Fashion vertical with sizes 7-13, brands (Nike, Jordan, Adidas, New Balance, Yeezy).
+    agents ||--o{ delegations : "delegates"
+    agents ||--o{ agentic_tokens : "uses"
 
-Additional merchants are synced from the Lane backend on startup or via the sync API.
+    mandates ||--o{ agentic_tokens : "authorizes"
 
-## Security
+    developers {
+        uuid id PK
+        uuid auth_user_id FK,UK
+        text email UK
+        text name
+        text plan "free | pro | team | enterprise"
+        text status "active | suspended | closed"
+        boolean sdk_access "whitelist gate"
+    }
 
-### PCI DSS Compliance
+    api_keys {
+        uuid id PK
+        uuid developer_id FK
+        text key_hash UK "SHA-256"
+        text key_prefix "lane_sk_..."
+        text environment "test | live"
+        timestamptz revoked_at
+    }
 
-Card PANs **never** touch Lane servers. All card data is tokenized through [VGS](https://www.verygoodsecurity.com/) (Very Good Security):
+    wallets {
+        uuid id PK
+        uuid developer_id FK
+        text label
+        integer balance_cents
+        text currency "USD"
+    }
 
-```ts
-import { VGSOutboundProxy, detectCardBrand, luhnCheck } from 'lane-sdk'
-
-// Card utilities
-detectCardBrand('4111111111111111')  // 'visa'
-luhnCheck('4111111111111111')        // true
-
-// Generate secure card collection form
-import { generateCollectPage } from 'lane-sdk'
-const html = generateCollectPage({
-  vaultId: 'tnt...',
-  environment: 'sandbox',
-  formId: 'card-form',
-  redirectUrl: 'https://app.example.com/done',
-})
-```
+    cards {
+        uuid id PK
+        uuid wallet_id FK
+        text vgs_alias "VGS token"
+        text last4
+        text brand "visa | mastercard | ..."
+        text status "active | inactive"
+    }
 
-### HMAC Request Signing
+    agentic_tokens {
+        uuid id PK
+        uuid wallet_id FK
+        integer amount_cents
+        text status "active | consumed | expired | revoked"
+        text merchant
+        timestamptz expires_at
+    }
 
-Every SDK request is signed with HMAC-SHA256:
+    transactions {
+        uuid id PK
+        uuid wallet_id FK
+        integer amount_cents
+        text status "success | failed | refunded"
+        text recipient
+        text psp_reference
+    }
 
-```ts
-import { HMACSignature, verifyWebhookSignature } from 'lane-sdk'
-
-// Verify incoming webhook
-const isValid = verifyWebhookSignature(
-  rawBody,
-  req.headers['x-lane-signature'],
-  webhookSecret,
-  parseInt(req.headers['x-lane-timestamp']),
-)
-```
+    budgets {
+        uuid id PK
+        uuid developer_id FK
+        integer daily_limit
+        integer weekly_limit
+        integer monthly_limit
+        integer per_task_limit
+    }
 
-### Credential Storage
+    auth_sessions {
+        uuid id PK
+        text device_code
+        text status "pending | completed | consumed | expired"
+        text auth_code
+        text api_key
+        timestamptz expires_at
+    }
 
-Credentials are stored at `~/.lane/credentials.json` with `0600` file permissions (owner read/write only). Directory permissions are set to `0700`.
+    merchant_directory {
+        uuid id PK
+        text name
+        text domain UK
+        text slug UK
+        text tier "lane_onboarded | protocol"
+        text vertical
+        jsonb product_attributes
+    }
 
-### HTTP Client Resilience
+    audit_log {
+        uuid id PK
+        uuid developer_id FK
+        text action
+        text resource_type
+        text resource_id
+        jsonb metadata
+    }
+```
 
-- **Automatic retries** with exponential backoff (1s, 3s, max 5s jitter) on 5xx and 429
-- **Circuit breaker** pattern (3 consecutive failures opens circuit for 30s)
-- **Idempotency keys** to prevent duplicate charges on retry
-- **Rate limit awareness** with `Retry-After` header support
+---
 
-## Enterprise Features
+## Token Architecture
 
-### Hierarchical Budgets
+### Prefixes
 
-Budget limits cascade: Organization > Team > Developer > Agent. The effective limit is the minimum across all levels.
+| Prefix | Type | TTL | Storage |
+|--------|------|-----|---------|
+| `lane_sk_` | API key (live) | None | SHA-256 hash in `api_keys.key_hash` |
+| `lane_sk_test_` | API key (test) | None | SHA-256 hash in `api_keys.key_hash` |
 
-```ts
-// Set team budget
-await lane.teams.setBudget('team_123', {
-  dailyLimit: 100000,     // $1,000
-  monthlyLimit: 1000000,  // $10,000
-  perTaskLimit: 10000,    // $100
-})
+### Key Lifecycle
 
-// View effective limits
-const budget = await lane.teams.getHierarchicalBudget('team_123')
-// { orgBudget, teamBudget, developerBudget, agentBudget, effectiveLimits }
-```
+```mermaid
+flowchart LR
+    subgraph Issuance
+        LOGIN["CLI login<br/>complete-session"]
+        ROTATE["Key rotation<br/>/admin/rotate-key"]
+        ONBOARD["Onboarding<br/>/generate-key"]
+    end
 
-### Agent Policies
+    LOGIN --> KEY["API Key<br/>lane_sk_...<br/>stored as SHA-256"]
+    ROTATE --> KEY
+    ONBOARD --> KEY
 
-Per-agent spending constraints:
+    KEY --> USE["Used for API calls<br/>Authorization: Bearer"]
+    KEY --> REVOKE["Revoked<br/>(15-min grace on rotation)"]
 
-```ts
-await lane.agents.setPolicy('agent_123', {
-  budget: { dailyLimit: 5000 },
-  allowedMCCs: ['5661', '5699'],     // Shoe stores only
-  maxTransactionAmount: 25000,        // $250 max per transaction
-  canRefund: false,
-  canDiscover: true,
-  approvalThreshold: 10000,           // Human approval above $100
-})
+    style REVOKE fill:#fee,stroke:#c00
 ```
 
-### Agent Identity & KYC Chain
-
-Lane-issued identity credentials with a 4-step verification chain: Human (developer KYC) > Lane (platform verification) > Agent (registration + policy binding) > Transaction (cryptographic attestation).
-
-```ts
-const identity = await lane.identity.register({
-  agentId: 'agent_123',
-  capabilities: ['payments', 'product_discovery'],
-  purpose: 'Autonomous shopping assistant',
-})
+### Credential Storage
 
-const attestation = await lane.identity.getAttestation(identity.id)
+- Stored at `~/.lane/credentials.json` with `0600` file permissions
+- Directory `~/.lane/` has `0700` permissions
+- Contains: `apiKey`, `developerId`, `environment`
+- Plaintext key only available at creation time; server stores SHA-256 hash
+
+---
+
+## Security & Compliance
+
+### Card Data Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent as AI Agent
+    participant VGS_C as VGS Collect<br/>(iframe)
+    participant VGS_V as VGS Vault<br/>(PCI DSS L1)
+    participant Lane as Lane Server
+    participant VGS_P as VGS Outbound<br/>Proxy
+    participant PSP as PSP<br/>(Stripe/Worldpay)
+
+    Agent->>Lane: GET /card/add-link
+    Lane-->>Agent: VGS Collect URL
+    Agent->>VGS_C: User enters card PAN
+    Note over VGS_C: PAN never touches Lane
+    VGS_C->>VGS_V: Store PAN → token
+    VGS_V-->>Lane: tok_4111...1234 + last4 + brand
+
+    Note over Lane,PSP: At payment time
+    Lane->>VGS_P: Charge with token
+    VGS_P->>VGS_V: Detokenize
+    VGS_P->>PSP: Real PAN
+    PSP-->>Lane: Authorization
 ```
 
-### Audit Trail
+### Security Controls
 
-Immutable audit log for SOC 2 compliance:
+| Control | Implementation |
+|---------|---------------|
+| **PCI DSS** | Card PANs never touch Lane — VGS vault tokenization |
+| **HMAC signing** | Every SDK request signed with HMAC-SHA256 |
+| **Idempotency** | All mutations accept `idempotencyKey` to prevent duplicate charges |
+| **API key hashing** | Keys stored as SHA-256; plaintext returned only at creation |
+| **Key rotation** | Old key valid for 15-minute grace period |
+| **Rate limiting** | Per-developer RPM limits enforced server-side |
+| **Circuit breaker** | 3 consecutive failures opens circuit for 30 seconds |
+| **Retries** | Exponential backoff (1s, 3s) on 5xx and 429 |
+| **Credential storage** | `~/.lane/credentials.json` with `0600` permissions |
+| **Budget enforcement** | Hierarchical: org > team > developer > agent > merchant > MCC |
+| **Audit trail** | Append-only `audit_log` table for SOC 2 |
+| **Biometric confirmation** | Touch ID / passkey for high-value instructions |
 
-```ts
-const { data: entries } = await lane.audit.query({
-  startDate: '2025-01-01',
-  actorType: 'agent',
-  action: 'payment.execute',
-  limit: 50,
-})
+---
 
-const summary = await lane.audit.summary({ period: '30d' })
-// { totalEntries, byAction, byActorType, topActors }
-```
+## Middleware & Route Protection
 
-### GDPR
+```mermaid
+flowchart TD
+    REQ([Incoming Request]) --> PATH{Route path?}
 
-```ts
-const data = await lane.admin.exportData()
-const { deletionCompletesAt } = await lane.admin.deleteAccount()
-```
+    PATH -->|"/health<br/>/agent/auth/*<br/>/agent/discovery"| PUBLIC([No auth — public])
 
-## Server
+    PATH -->|"/agent/*"| CHAIN["API Key Auth<br/>↓<br/>Rate Limit<br/>↓<br/>HMAC Verify<br/>↓<br/>Audit Logger<br/>↓<br/>Route Handler"]
 
-The SDK includes a full Express backend with OOP service architecture.
+    PATH -->|"/api/sdk/*"| LEGACY["Deprecation Header<br/>↓<br/>Same middleware chain"]
 
-### Environment Variables
+    PATH -->|"Unknown"| E404([404 Not Found])
 
-```bash
-SUPABASE_URL=https://...supabase.co     # Required
-SUPABASE_SERVICE_KEY=eyJ0eXAi...        # Required
-PORT=3001                                # Default: 3001
-LOG_LEVEL=INFO                           # DEBUG | INFO | WARN | ERROR
-
-# Merchant directory sync (optional)
-LANE_BACKEND_URL=https://app.getonlane.com
-LANE_BACKEND_TOKEN=...
+    CHAIN --> HANDLER([Route Handler])
+    LEGACY --> HANDLER
 ```
 
-### API Routes
-
-All routes are under `/api/sdk/` and require API key authentication.
-
-| Prefix | Description |
-|---|---|
-| `/api/sdk/auth` | Login, token exchange, key rotation |
-| `/api/sdk/wallets` | Wallet CRUD, cards, profiles, merchant accounts |
-| `/api/sdk/pay` | Token creation, payment execution, refunds |
-| `/api/sdk/admin` | Spending reports, budgets, team members |
-| `/api/sdk/merchants` | Merchant directory (list, get, capabilities, sync, discover) |
-
-### Middleware Stack
+### Request Lifecycle
 
+```mermaid
+sequenceDiagram
+    participant Client as SDK Client
+    participant Auth as API Key Auth
+    participant RL as Rate Limit
+    participant HMAC as HMAC Verify
+    participant Audit as Audit Logger
+    participant Service as Service Layer
+    participant DB as Supabase
+    participant VGS as VGS / PSP
+
+    Client->>Auth: Bearer lane_sk_...<br/>X-Lane-Signature: sha256<br/>Idempotency-Key: ...
+    Auth->>DB: SHA-256(key) → api_keys
+    Auth->>Auth: Check not revoked
+
+    Auth->>RL: req.developer set
+    RL->>RL: Check RPM limit
+
+    RL->>HMAC: Pass
+    HMAC->>HMAC: Verify signature
+
+    HMAC->>Audit: Pass
+    Audit->>DB: Log request
+
+    Audit->>Service: Route handler
+    Service->>DB: Business logic
+    Service->>VGS: Card operations (if payment)
+    Service-->>Client: JSON response
 ```
-Request → JSON Parser → CORS → API Key Auth → Rate Limit → HMAC Verify → Audit → Route → Error Handler
-```
-
-### Services (9)
 
-| Service | Description |
-|---|---|
-| `WalletService` | Wallet lifecycle, balance tracking |
-| `CardService` | Card management, VGS tokenization |
-| `TokenService` | Agentic token lifecycle (create, validate, consume, expire) |
-| `PaymentService` | Payment execution, PSP routing, refunds |
-| `BudgetService` | Budget enforcement, spending counters, period resets |
-| `ProfileService` | Checkout profiles (address, email, phone) |
-| `MerchantAccountService` | Saved merchant credentials per wallet |
-| `MerchantDirectoryService` | Merchant registry, backend sync, protocol discovery |
-| `VGSProxyService` | VGS outbound proxy for PCI-compliant card operations |
+---
 
-### Database
+## Cross-Service Auth: SDK vs Lane-Auth
 
-11 SQL migrations using Supabase (PostgreSQL) with Row Level Security on all tables:
+The Lane platform has two separate auth systems in different repos:
 
-```
-001_developers.sql          — Developer accounts
-002_api_keys.sql            — API key management
-003_vgs_vault_configs.sql   — VGS vault configurations
-004_wallets_cards.sql       — Wallets and payment cards
-005_checkout_profiles.sql   — Saved checkout information
-006_merchant_accounts.sql   — Per-merchant credentials
-007_agentic_tokens.sql      — Scoped payment tokens
-008_transactions.sql        — Transaction ledger
-009_budgets.sql             — Spending limits and counters
-010_audit_log.sql           — Immutable audit trail
-011_merchant_directory.sql  — Merchant directory, sync log, protocol manifests
+| | SDK Server (`lane-agent-sdk`) | Auth Service (`lane-auth`) |
+|---|---|---|
+| **Base URL** | `api.getonlane.com/sdk` | `auth.getonlane.com` |
+| **Purpose** | Developer onboarding, SDK access gating | Identity, sessions, compliance |
+| **DB access** | Service role key (bypasses RLS) | Anon key (subject to RLS) |
+| **Token type** | `lane_sk_` API keys | `lane_cli_` + `lane_rt_` token pairs |
+| **Anti-phishing** | 4-char device code (`LANE-XXXX`) | 8-char code + 2-digit number match |
+
+```mermaid
+graph TB
+    subgraph "lane-agent-sdk repo"
+        SDK_SERVER["SDK Server (Express)<br/>api.getonlane.com/sdk"]
+        WALLET["Wallet App (Next.js)<br/>agent.getonlane.com"]
+        CLI["Lane CLI<br/>npx lane ..."]
+        SDK_LIB["SDK Library<br/>Lane.create()"]
+    end
+
+    subgraph "lane-auth repo"
+        AUTH["Auth Service (Next.js)<br/>auth.getonlane.com"]
+    end
+
+    subgraph Supabase
+        DB["PostgreSQL<br/>developers · api_keys<br/>auth_sessions · wallets"]
+    end
+
+    CLI -->|"/agent/auth/*"| SDK_SERVER
+    WALLET -->|"popup for OTP"| AUTH
+    WALLET -->|"/agent/auth/complete-session"| SDK_SERVER
+    SDK_LIB -->|"/agent/auth/verify-sdk-access"| SDK_SERVER
+    SDK_SERVER -->|"service role key"| DB
+    AUTH -->|"anon key + RLS"| DB
+
+    style SDK_SERVER fill:#e6f0ff,stroke:#4a90d9
+    style WALLET fill:#e6f0ff,stroke:#4a90d9
+    style CLI fill:#e6f0ff,stroke:#4a90d9
+    style SDK_LIB fill:#e6f0ff,stroke:#4a90d9
+    style AUTH fill:#ffebeb,stroke:#d94a4a
 ```
 
-## Architecture
+---
 
-### System Overview
+## Project Structure
 
 ```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                            AI Agent Layer                                │
-│                  Claude · Cursor · Custom Agents                         │
-├──────────────────┬────────────────────────┬──────────────────────────────┤
-│   MCP Server     │    SDK Client Library   │         CLI                  │
-│   (stdio/HTTP)   │    (TypeScript/JS)      │    (16 commands)             │
-│                  │                         │                              │
-│  14 tools        │  17 resource classes    │  login · pay · balance       │
-│  Zod validation  │  Lazy initialization    │  checkout · set-budget       │
-│  JSON responses  │  Type-safe methods      │  setup-mcp · vendor          │
-├──────────────────┴────────────────────────┴──────────────────────────────┤
-│                          HTTP Client (src/client.ts)                      │
-│                                                                          │
-│  HMAC-SHA256 signing    Exponential backoff     Circuit breaker           │
-│  Idempotency keys       Retry on 5xx/429        (3 failures → 30s open)  │
-│  Request ID tracking    Rate limit awareness     Event emitter            │
-├──────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│                        Express Server (port 3001)                        │
-│                                                                          │
-│  ┌────────┐  ┌───────────┐  ┌────────────┐  ┌─────────┐  ┌───────────┐ │
-│  │JSON    │─▶│ API Key   │─▶│ Rate Limit │─▶│ HMAC    │─▶│ Audit     │ │
-│  │Parser  │  │ Auth      │  │            │  │ Verify  │  │ Logger    │ │
-│  └────────┘  └───────────┘  └────────────┘  └─────────┘  └─────┬─────┘ │
-│                                                                  │       │
-│  ┌───────────────────────────────────────────────────────────────┘       │
-│  │                                                                       │
-│  ▼  Routes                                                               │
-│  ┌──────────┬──────────┬──────────┬──────────┬────────────────┐          │
-│  │ /auth    │ /wallets │  /pay    │  /admin  │  /merchants    │          │
-│  │          │          │          │          │                │          │
-│  │ login    │ create   │ tokens   │ budgets  │ list/search    │          │
-│  │ exchange │ cards    │ execute  │ spending │ get by id/slug │          │
-│  │ rotate   │ profiles │ refunds  │ members  │ capabilities   │          │
-│  │          │ accounts │          │ export   │ sync/discover  │          │
-│  └────┬─────┴────┬─────┴────┬─────┴────┬─────┴───────┬────────┘         │
-│       │          │          │          │             │                    │
-│  ─────┴──────────┴──────────┴──────────┴─────────────┴───────────────    │
-│                        Service Container (DI)                            │
-│                                                                          │
-│  ┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────────┐ │
-│  │ Wallet   │ Card     │ Token    │ Payment  │ Budget   │ Merchant     │ │
-│  │ Service  │ Service  │ Service  │ Service  │ Service  │ Directory    │ │
-│  ├──────────┼──────────┼──────────┼──────────┼──────────┤ Service      │ │
-│  │ Profile  │ Merchant │ VGS      │          │          │              │ │
-│  │ Service  │ Account  │ Proxy    │          │          │ 30m cache    │ │
-│  │          │ Service  │ Service  │          │          │ auto-sync    │ │
-│  └──────────┴──────────┴──────────┴──────────┴──────────┴──────────────┘ │
-│                                                                          │
-├──────────────────────────────────────────────────────────────────────────┤
-│                        Payment Infrastructure                            │
-│                                                                          │
-│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────────┐ │
-│  │  Routing Engine   │  │  VGS Integration │  │  PSP Registry          │ │
-│  │                   │  │                  │  │                        │ │
-│  │  MerchantRegistry │  │  Outbound Proxy  │  │  ┌──────────────────┐ │ │
-│  │  PaymentRouter    │  │  Token Manager   │  │  │ Stripe (pri: 1)  │ │ │
-│  │                   │  │  Card Detection  │  │  │ Worldpay (pri: 2)│ │ │
-│  │  4-tier routing:  │  │  Luhn Validation │  │  │ CyberSource (3)  │ │ │
-│  │  billing_api      │  │  Collect Forms   │  │  └──────────────────┘ │ │
-│  │  acp              │  │                  │  │                        │ │
-│  │  vic              │  │  PCI DSS Level 1 │  │  Priority failover    │ │
-│  │  fallback         │  │  PAN never       │  │  Health checks        │ │
-│  │                   │  │  touches Lane    │  │                        │ │
-│  └──────────────────┘  └──────────────────┘  └────────────────────────┘ │
-│                                                                          │
-├──────────────────────────────────────────────────────────────────────────┤
-│                    Supabase (PostgreSQL + Row Level Security)             │
-│                                                                          │
-│  developers · api_keys · wallets · cards · tokens · transactions         │
-│  budgets · profiles · merchant_accounts · audit_log                      │
-│  merchant_directory · sync_log · protocol_manifests                      │
-│                                                                          │
-│  11 migrations · GIN indexes · trigram search · RLS on all tables        │
-└──────────────────────────────────────────────────────────────────────────┘
+lane-agent-sdk/
+├── src/
+│   ├── lane.ts                    # SDK entry point (Lane class)
+│   ├── client.ts                  # HTTP client (HMAC, retries, circuit breaker)
+│   ├── config.ts                  # Config resolution
+│   ├── errors.ts                  # Typed error hierarchy
+│   ├── types.ts                   # Shared types
+│   ├── index.ts                   # Public exports
+│   ├── resources/                 # 22 resource classes
+│   │   ├── base.ts                # Base resource with _get/_post/_put/_delete
+│   │   ├── auth.ts                # Authentication
+│   │   ├── wallets.ts             # Wallets
+│   │   ├── pay.ts                 # Payments
+│   │   ├── merchants.ts           # Merchant directory
+│   │   ├── instructions.ts        # VIC instructions
+│   │   ├── mandates.ts            # Spending mandates
+│   │   └── ...                    # 15 more resource files
+│   ├── auth/
+│   │   ├── browser-flow.ts        # Local callback server for login
+│   │   ├── token-store.ts         # ~/.lane/credentials.json I/O
+│   │   ├── biometric.ts           # Touch ID / passkey confirmation
+│   │   └── confirmation.ts        # Payment confirmation flow
+│   ├── cli/
+│   │   ├── index.ts               # CLI entry point (Commander)
+│   │   ├── terse.ts               # Terse output helpers
+│   │   ├── branding.ts            # CLI logo and colors
+│   │   └── commands/              # 26 command files
+│   ├── mcp/
+│   │   ├── server.ts              # MCP server (discovery + auth modes)
+│   │   ├── tool.ts                # Base tool class (LaneTool<T>)
+│   │   └── tools/                 # 28 tool files
+│   ├── vgs/
+│   │   ├── proxy.ts               # VGS outbound proxy
+│   │   ├── token.ts               # VGS token management
+│   │   ├── card-types.ts          # Card brand detection, Luhn
+│   │   └── collect.ts             # VGS Collect form generation
+│   ├── psp/
+│   │   ├── registry.ts            # PSP adapter registry
+│   │   ├── types.ts               # PSP interfaces
+│   │   └── adapters/              # Stripe, Worldpay, CyberSource
+│   ├── routing/
+│   │   └── engine.ts              # 5-tier payment routing
+│   └── adapters/                  # Framework adapters
+│       ├── openai/                # OpenAI function calling
+│       ├── langchain/             # LangChain tools
+│       ├── crewai/                # CrewAI tools
+│       └── vercel-ai/             # Vercel AI SDK
+├── server/
+│   ├── index.ts                   # Express entry point
+│   ├── middleware/
+│   │   └── api-key-auth.ts        # API key validation
+│   ├── routes/
+│   │   ├── agent/                 # /agent/* routes
+│   │   │   ├── auth.ts            # Login, token, complete-session
+│   │   │   ├── admin.ts           # Whoami, rotate-key, keys
+│   │   │   └── instruction.ts     # Instruction routes
+│   │   └── auth.ts                # Legacy auth routes
+│   ├── services/                  # 23 service classes
+│   │   ├── wallet-service.ts
+│   │   ├── payment-service.ts
+│   │   ├── budget-service.ts
+│   │   ├── instruction-service.ts
+│   │   ├── mandate-service.ts
+│   │   └── ...
+│   ├── lib/
+│   │   ├── service-container.ts   # DI container
+│   │   ├── errors.ts              # Server error types
+│   │   └── logger.ts              # Structured logger
+│   └── db/
+│       └── migrations/            # Legacy migration scripts
+├── wallet/                        # Next.js wallet app (agent.getonlane.com)
+│   ├── src/app/
+│   │   ├── authorize/page.tsx     # Device code verification
+│   │   ├── dashboard/             # Developer dashboard
+│   │   └── onboarding/            # Onboarding flow
+│   └── public/
+│       └── SKILL.md               # Agent skill documentation
+├── supabase/
+│   └── migrations/                # 32 SQL migrations
+├── poc/                           # End-to-end proof of concept
+├── tsup.config.ts                 # Build config (ESM + CJS + CLI)
+└── vitest.config.ts               # Test config
 ```
 
-### Request Lifecycle
+---
 
-```
-  Client                    Lane Server                          External
-    │                           │                                   │
-    │  POST /api/sdk/pay        │                                   │
-    │  Authorization: Bearer    │                                   │
-    │  X-Lane-Signature: sha256 │                                   │
-    │  X-Lane-Timestamp: ...    │                                   │
-    │  Idempotency-Key: ...     │                                   │
-    │ ─────────────────────────▶│                                   │
-    │                           │                                   │
-    │                     ┌─────┴─────┐                             │
-    │                     │ API Key   │  Verify key in DB           │
-    │                     │ Auth      │                              │
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ Rate      │  Check rate limit           │
-    │                     │ Limit     │                              │
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ HMAC      │  Verify request signature   │
-    │                     │ Verify    │                              │
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ Audit     │  Log request                │
-    │                     │ Logger    │                              │
-    │                     └─────┬─────┘                             │
-    │                           │                                   │
-    │                     ┌─────┴─────┐                             │
-    │                     │ Budget    │  Check daily/weekly/monthly  │
-    │                     │ Service   │  limits, merchant allow/deny │
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ Payment   │                              │
-    │                     │ Router    │  Select: billing_api         │
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ VGS       │  Detokenize card ───────────▶│ VGS Vault
-    │                     │ Proxy     │◀──────────── real PAN ──────│
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ PSP       │  Charge via Worldpay ──────▶│ Worldpay
-    │                     │ Adapter   │◀──────── auth code ────────│
-    │                     └─────┬─────┘                             │
-    │                     ┌─────┴─────┐                             │
-    │                     │ Record    │  Update spend counters      │
-    │                     │ Spend     │  Write transaction row      │
-    │                     └─────┬─────┘                             │
-    │                           │                                   │
-    │  200 OK                   │                                   │
-    │  { transactionId,         │                                   │
-    │    status: "success",     │                                   │
-    │    receiptUrl }           │                                   │
-    │ ◀─────────────────────────│                                   │
-    │                           │                                   │
-```
+## Environment Variables
 
-### PSP Adapters
+### SDK (Client)
 
-Three payment processor adapters with priority-based failover:
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `LANE_API_KEY` | API key for authentication | — |
+| `LANE_BASE_URL` | SDK server base URL | `https://api.getonlane.com/sdk` |
+| `LANE_API_URL` | API URL for sell-side operations | `https://api.getonlane.com` |
+| `LANE_TEST_MODE` | Force test mode | `false` (auto-detected from key prefix) |
+| `LANE_TIMEOUT` | Request timeout (ms) | `30000` |
+| `LANE_MAX_RETRIES` | Max retry attempts | `2` |
 
-```ts
-import { PSPRegistry, StripeAdapter, WorldpayAdapter, CyberSourceAdapter } from 'lane-sdk'
+### Server
 
-const registry = new PSPRegistry()
-registry.register(new StripeAdapter(config), 1)      // Primary
-registry.register(new WorldpayAdapter(config), 2)     // Secondary
-registry.register(new CyberSourceAdapter(config), 3)  // Tertiary
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SUPABASE_URL` | Supabase project URL | — (required) |
+| `SUPABASE_SERVICE_KEY` | Supabase service role key | — (required) |
+| `PORT` | Express server port | `3001` |
+| `LOG_LEVEL` | Logger level | `INFO` |
+| `WALLET_APP_URL` | Wallet app URL (for auth redirects) | `https://api.getonlane.com` |
 
-const primary = registry.getPrimary()
-const result = await primary.charge({
-  amount: 4999,
-  currency: 'USD',
-  token: 'vgs_tok_...',
-  cardholderName: 'AI Agent',
-})
-```
+---
 
 ## Development
 
@@ -1025,36 +1030,35 @@ const result = await primary.charge({
 # Install dependencies
 npm install
 
-# Build (ESM + CJS + CLI + DTS)
+# Build (ESM + CJS + CLI + server + DTS)
 npm run build
 
 # Type check
-npx tsc --noEmit
+npm run lint
 
-# Run tests (110 tests via Vitest)
+# Run tests (651 tests via Vitest)
 npm test
 
 # Watch mode
-npm run dev          # Build
-npm run test:watch   # Tests
+npm run dev
 ```
 
-### Test Coverage
+### Test Suite
 
-| Suite | Tests | Covers |
-|---|---|---|
-| `config.test.ts` | 13 | Config resolution (constructor, env, file) |
-| `errors.test.ts` | 18 | Error hierarchy, factory, serialization |
-| `lane.test.ts` | 6 | Lane class initialization, resource accessors |
-| `lane.phase.test.ts` | 7 | Phase-specific resource availability |
-| `signature.test.ts` | 11 | HMAC signing, webhook verification |
-| `token-store.test.ts` | 8 | File credential storage, permissions |
-| `card-types.test.ts` | 13 | Card brand detection, Luhn check, masking |
-| `collect.test.ts` | 10 | VGS Collect form generation |
-| `token.test.ts` | 4 | VGS token management |
-| `engine.test.ts` | 9 | Payment routing decisions, budget enforcement |
-| `tool.test.ts` | 4 | MCP tool execution, error formatting |
-| `registry.test.ts` | 7 | PSP adapter registration, failover |
+651 tests across 48 test files:
+
+| Category | Files | Tests | Coverage |
+|---|---|---|---|
+| SDK core | `config`, `errors`, `lane`, `signature` | ~50 | Config resolution, error hierarchy, initialization |
+| Agent UX | `sdk-accessibility`, `mcp-accessibility`, `cli-accessibility`, `error-consistency`, `scorecard` | ~200 | Agent-facing API quality, error messages, competitive analysis |
+| Compliance | `budget-enforcement`, `input-validation`, `pci-compliance`, `soc2-audit` | ~110 | Budget limits, PCI controls, audit trail |
+| Server | `instruction-service`, `mandate-service`, `state-machines`, `mandate-edge-cases` | ~100 | Service logic, state transitions, edge cases |
+| CLI | `login`, `pay`, `status`, `terse` | ~40 | Command output, terse formatting |
+| MCP | `pay`, `pay-with-mandate`, `provision-vic`, `confirm-instruction`, `budget-tools` | ~50 | Tool execution, error handling |
+| Auth | `biometric`, `confirmation` | ~20 | Biometric flows, confirmation lifecycle |
+| Infrastructure | `routing/engine`, `merchants/ucp-directory`, `mcp/tool`, `mcp/server` | ~40 | Routing decisions, merchant resolution, MCP lifecycle |
+
+---
 
 ## License