jaspervault_cli 1.0.27 → 1.0.29

package/dist/src/templates/skill-content/references/onboarding.md

@@ -1,124 +1,105 @@
 # Onboarding Reference
 
-## 1. Wallet Initialization (`jv vault setup`)
+## 1. Wallet Initialization — `wallet_setup`
 
-Initialize the JasperVault delegation wallet via WalletConnect. This is the ONLY recommended initialization method.
+Initialize the JasperVault delegation wallet. The user signs in their browser — no private key needed.
 
-### Syntax
+### Parameters
 
-```
-jv vault setup --network <name> [--timeout <seconds>] [--vault-index <n>] [--pretty]
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `network` | No | `jaspervault` | Network name |
+| `vault_types` | No | `33,37` | Comma-separated vault types |
+
+### Flow
+
+1. Call `wallet_setup` (no parameters needed for default setup).
+2. The tool returns JSON with a `url` field — display it as a **clickable link** to the user.
+3. The user opens the URL in their browser, connects their wallet (MetaMask, Rabby, etc.), and signs the delegation authorization.
+4. The tool polls automatically (up to 16 minutes) and returns the final result.
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "walletAddress": "0x...",
+  "delegationAddress": "0x...",
+  "marginAccount": "0x...",
+  "vaults": [{"type": 33, "address": "0x..."}, {"type": 37, "address": "0x..."}]
+}
 ```
 
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--network <name>` | Yes | `jaspervault` | Network name |
-| `--timeout <seconds>` | No | `120` | WalletConnect connection timeout |
-| `--vault-index <n>` | No | `1` | Vault index for address derivation |
-| `--pretty` | No | — | Pretty-print JSON output |
-
-### Step-by-Step Flow
-
-1. Run the command:
-   ```
-   jv vault setup --network jaspervault --timeout 120
-   ```
-
-2. The command is **long-running** (up to 2 minutes). It will be auto-backgrounded by the agent runtime after ~10 seconds. You will receive a `sessionId`.
-
-3. The **first JSON output** contains the QR code URL:
-   ```json
-   {"qrCodeUrl": "https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=wc%3A..."}
-   ```
-   **You MUST display this `qrCodeUrl` as a clickable link** so the user can scan it with their mobile wallet (e.g., MetaMask, Rainbow, Trust Wallet).
-
-4. **Poll for completion** every 15 seconds using `process poll` with the `sessionId`:
-   - While waiting, you'll see heartbeat lines: `{"status":"waiting","phase":"wallet_scan","elapsed":10,"message":"Waiting for wallet connection..."}`
-   - Continue polling until you see the **second JSON line** with `"success":true` or the process exits.
-
-5. On success, the output includes:
-   ```json
-   {
-     "success": true,
-     "walletAddress": "0x...",
-     "delegationAddress": "0x...",
-     "vaultAddress": "0x...",
-     "network": "jaspervault"
-   }
-   ```
-
-6. The CLI automatically:
-   - Generates and saves a delegation key to `~/.jaspervault/keys.json`
-   - Saves the vault profile to `~/.jaspervault/profile.json`
-   - Registers the delegation key on-chain via WalletConnect signing
+The tool automatically saves the delegation key and vault profile locally.
 
 ### Error Handling
 
 | Error | Cause | Action |
 |-------|-------|--------|
-| `Connection timed out after Ns` | User didn't scan QR in time | Re-run `jv vault setup` with longer `--timeout` |
-| `Connection rejected or failed` | User rejected in wallet | Re-run `jv vault setup` |
-| `Failed to initialize WalletConnect` | Network issue | Check internet connection, retry |
+| Session expired/failed | User didn't complete signing in time | Call `wallet_setup` again |
+| Failed to create session | Network/API issue | Check internet connection, retry |
 
-### Important Notes
+### Important
 
-- **NEVER suggest `jv vault init`** — that requires a `PRIVATE_KEY` environment variable and is for advanced/CI use only.
-- If error messages mention "Run `jv vault init`", ignore that and use `jv vault setup` instead.
-- The delegation key has a 1-week expiry. If commands start failing after a week, re-run `jv vault setup`.
+- Never suggest `vault init` — that requires `PRIVATE_KEY` and is for CI/automation only.
+- The delegation key expires after 1 week. If tools start failing, call `wallet_setup` again.
 
 ---
 
-## 2. Deposit Tokens (`jv deposit`)
+## 2. Deposit Tokens — `deposit_via_browser`
 
-Deposit tokens from Base network to JasperVault via Hyperlane warp routes. Uses WalletConnect for transaction signing (no private key needed).
+Deposit tokens from Base network to JasperVault via Hyperlane warp routes.
 
-### Syntax
+### Parameters
 
-```
-jv deposit --token <token> --amount <amount> [--wallet <address>] [--vault-index <n>] [--network <name>] [--timeout <seconds>] [--no-wait] [--pretty]
-```
-
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--token <token>` | Yes | — | Token to deposit: `jbtc`, `jusdc`, `cbbtc`, or `usdc` |
-| `--amount <amount>` | Yes | — | Amount in human-readable units (e.g., `0.01` for BTC, `1000` for USDC) |
-| `--wallet <address>` | No | from profile | Override wallet address (default: from vault profile) |
-| `--vault-index <n>` | No | `1` | Vault index for recipient address derivation |
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--timeout <seconds>` | No | `120` | WalletConnect timeout |
-| `--no-wait` | No | — | Skip polling for arrival on JasperVault |
-| `--pretty` | No | — | Pretty-print JSON output |
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `token` | Yes | — | Token: `jbtc`, `jusdc`, `cbbtc`, or `usdc` |
+| `amount` | Yes | — | Amount in human-readable units (e.g., `0.01` for BTC, `1000` for USDC) |
+| `network` | No | `jaspervault` | Network name |
 
 ### Flow
 
-1. The CLI connects via WalletConnect (QR scan — same flow as `jv vault setup`).
-2. It checks token balance and allowance on Base.
-3. If allowance is insufficient, it sends an approval transaction first.
-4. It sends the `transferRemote` transaction via Hyperlane warp router.
-5. Unless `--no-wait`, it polls for token arrival on JasperVault (up to 60s).
+1. Call `deposit_via_browser` with `token` and `amount`.
+2. The tool returns JSON with a `url` field — display it as a **clickable link**.
+3. The user opens the URL in their browser to approve the deposit.
+4. The tool polls until the transaction is confirmed (up to 16 minutes).
 
-### Output
+### Success Response
 
 ```json
 {
   "success": true,
   "token": "jbtc",
   "amount": "0.01",
-  "txHash": "0x...",
+  "transactionHash": "0x...",
   "arrived": true,
   "arrivalTimeMs": 12345,
   "message": "Deposit confirmed"
 }
 ```
 
-### Important Notes
+### Important
+
+- Token names are lowercase: `jbtc`, `jusdc`, `cbbtc`, `usdc`.
+- Amount is human-readable (e.g., `0.01` BTC, `1000` USDC) — the tool handles decimal conversion.
+- Tokens are bridged cross-chain from Base to JasperVault via Hyperlane.
+- If `arrived` is `false`, tokens may still be in transit. Tell the user to wait a few minutes.
+
+---
+
+## 3. Withdraw Tokens — `withdraw_via_browser`
+
+Withdraw tokens from JasperVault back to Base.
+
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `token` | Yes | — | Token: `jbtc`, `jusdc`, `cbbtc`, or `usdc` |
+| `amount` | Yes | — | Amount in human-readable units |
+| `network` | No | `base_uat` | Network name |
+
+### Flow
 
-- **WalletConnect QR**: The deposit command uses WalletConnect. When you see the `qrCodeUrl` output, display it as a clickable link — same as `jv vault setup`.
-- **Token names**: Use lowercase: `jbtc`, `jusdc`, `cbbtc`, `usdc`.
-- **Amount format**: Human-readable (e.g., `0.01` BTC, `1000` USDC). The CLI handles decimal conversion.
-- **Cross-chain**: Tokens are bridged from Base (chain 8453) to JasperVault (chain 55531) via Hyperlane.
-- If `arrived` is `false`, the tokens may still be in transit. Tell the user to wait a few minutes and check their balance.
+Same browser-signing flow as deposit — call the tool, display the URL, wait for completion.

package/dist/src/templates/skill-content/references/queries.md

@@ -1,29 +1,21 @@
 # Queries Reference
 
-## 1. List Positions (`jv orders list`)
+## 1. List Positions — `list_orders`
 
-Query active or historical positions from the Subgraph.
+Query active or historical positions.
 
-### Syntax
+### Parameters
 
-```
-jv orders list [options]
-```
-
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--position-side <long\|short>` | No | — | Filter by position side |
-| `--all` | No | — | Include closed/liquidated positions (default: active only) |
-| `--since <time>` | No | — | Filter orders created after this time |
-| `--until <time>` | No | — | Filter orders created before this time |
-| `--page <n>` | No | `1` | Page number |
-| `--limit <n>` | No | `20` | Results per page |
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--pretty` | No | — | Pretty-print JSON output |
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `position_side` | No | — | Filter: `LONG` or `SHORT` |
+| `all` | No | `false` | `true` to include closed/liquidated positions |
+| `since` | No | — | Filter orders after this time (e.g., `7d`, `2025-01-01`) |
+| `until` | No | — | Filter orders before this time |
+| `page` | No | `1` | Page number |
+| `limit` | No | `20` | Results per page |
 
-### Time Format (`--since` / `--until`)
+### Time Formats for `since` / `until`
 
 | Format | Example | Description |
 |--------|---------|-------------|
@@ -33,21 +25,14 @@ jv orders list [options]
 | ISO date | `2025-01-01` | Specific date |
 | Unix timestamp | `1704067200` | Seconds since epoch |
 
-### Output
+### Response
 
 ```json
 {
   "orders": [
     {
       "id": "123",
-      "holder": "0x...",
-      "writer": "0x...",
-      "recipient": "0x...",
       "orderType": 0,
-      "productType": "50000000000000",
-      "marginDeposited": "60000000",
-      "quantity": "43860000000000000",
-      "entryPrice": "68476000000000000000000",
       "margin": "60.000000",
       "size": "0.043860000000000000",
       "entryPriceUsd": "68476.000000000000000000",
@@ -62,114 +47,53 @@ jv orders list [options]
 }
 ```
 
-### Key Output Fields
+### Key Fields
 
 | Field | Description |
 |-------|-------------|
-| `id` | Order ID (use for TP/SL/protect commands) |
+| `id` | Order ID (use for TP/SL/protect tools) |
 | `orderType` | `0` = Long, `1` = Short |
 | `margin` | Human-readable margin in USDC |
 | `size` | Human-readable position size in asset units |
 | `entryPriceUsd` | Human-readable entry price in USD |
-| `leverage` | Leverage multiplier (extracted from `productType`) |
-| `createdTime` | ISO timestamp of order creation |
-| `marginDeposited` | Raw margin in wei (6 decimals for USDC) |
-| `quantity` | Raw position size in wei (18 decimals) |
-| `entryPrice` | Raw entry price in wei (18 decimals) |
+| `leverage` | Leverage multiplier |
+| `createdTime` | ISO timestamp |
 
-**Always use the human-readable fields** (`margin`, `size`, `entryPriceUsd`, `leverage`) when reporting to the user. The raw wei fields are for reference only.
+Always use the human-readable fields (`margin`, `size`, `entryPriceUsd`) when reporting to the user. Raw wei fields are for reference only.
 
 ### Examples
 
-```bash
-# List active positions
-jv orders list --pretty
-
-# List only long positions
-jv orders list --position-side long --pretty
-
-# List all positions including closed (last 7 days)
-jv orders list --all --since 7d --pretty
-
-# Paginate results
-jv orders list --page 2 --limit 10 --pretty
-```
-
----
-
-## 2. Get Single Position (`jv orders get`)
-
-Get detailed information for a specific order by ID.
-
-### Syntax
-
 ```
-jv orders get <orderId> [options]
-```
-
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--pretty` | No | — | Pretty-print JSON output |
-
-### Output
-
-Same fields as `jv orders list` but for a single order.
-
-### Example
-
-```bash
-jv orders get 123 --pretty
+list_orders → all active positions
+list_orders { position_side: "LONG" } → only longs
+list_orders { all: true, since: "7d" } → all positions last 7 days
 ```
 
 ---
 
-## 3. Portfolio Statistics (`jv orders stats`)
-
-Get aggregate statistics for all positions in your vault.
+## 2. Get Single Position — `get_order`
 
-### Syntax
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `order_id` | Yes | Order ID |
 
-```
-jv orders stats [options]
-```
-
-### Options
-
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--pretty` | No | — | Pretty-print JSON output |
-
-### Example
-
-```bash
-jv orders stats --pretty
-```
+Returns same fields as `list_orders` for a single order.
 
 ---
 
-## 4. Get Market Price (`jv price`)
-
-Fetch the current market price from the Quote Center oracle.
+## 3. Portfolio Statistics — `get_order_stats`
 
-### Syntax
+No parameters required. Returns aggregate statistics for all positions in your vault.
 
-```
-jv price --symbol <symbol> [options]
-```
+---
 
-### Options
+## 4. Get Market Price — `get_price`
 
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
-| `--network <name>` | No | `jaspervault` | Network name |
-| `--pretty` | No | — | Pretty-print JSON output |
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `symbol` | Yes | Asset symbol (e.g., `JBTC`, `CBBTC`) |
 
-### Output
+### Response
 
 ```json
 {
@@ -181,35 +105,19 @@ jv price --symbol <symbol> [options]
 }
 ```
 
-**Always use the `price` field** (human-readable) when reporting to the user.
-
-### Example
-
-```bash
-jv price --symbol JBTC --pretty
-```
+Use the `price` field (human-readable) when reporting to the user.
 
 ---
 
-## 5. Job Status (`jv job status`)
-
-Check the execution status of an async job (market order, option creation, etc.).
-
-### Syntax
-
-```
-jv job status <jobId> [options]
-```
+## 5. Job Status — `get_job_status`
 
-### Options
+Check execution status of an async job (market order, option creation, etc.).
 
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--pretty` | No | — | Pretty-print JSON output |
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `job_id` | Yes | Job ID from market order creation |
 
-### Output
-
-The command connects via SSE and waits up to 60s for the job result:
+### Response
 
 ```json
 {
@@ -224,71 +132,33 @@ The command connects via SSE and waits up to 60s for the job result:
 |--------|---------|
 | `completed` | Job finished successfully |
 | `failed` | Job failed (check `error` field) |
-| `timeout` | SSE connection timed out — job may still be processing |
-
-### Example
-
-```bash
-jv job status MARKET_ORDER_xxx --pretty
-```
+| `timeout` | SSE timed out — job may still be processing |
 
 ---
 
-## 6. Limit Order Management (`jv limit-order`)
+## 6. Limit Order Management
 
-### List Limit Orders
+### List Limit Orders — `list_limit_orders`
 
-```
-jv limit-order list --wallet <address> [--status <status>] [--pretty]
-```
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `wallet` | Yes | Wallet address |
+| `status` | No | Filter: `PENDING`, `TRIGGERED`, `EXECUTING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED` |
 
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--wallet <address>` | Yes | — | Wallet address to query |
-| `--status <status>` | No | — | Filter: `PENDING`, `TRIGGERED`, `EXECUTING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED` |
-| `--pretty` | No | — | Pretty-print JSON output |
+### Get Limit Order Status — `get_limit_order_status`
 
-### Get Limit Order Status
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `limit_order_id` | Yes | Limit order ID |
 
-```
-jv limit-order status <id> [--pretty]
-```
-
-Query a specific limit order by its ID.
-
-### Cancel Limit Order
+### Cancel Limit Order — `cancel_limit_order`
 
-```
-jv limit-order cancel <id> [--pretty]
-```
-
-Cancel a pending limit order by its ID.
-
-### Examples
-
-```bash
-# List all pending limit orders
-jv limit-order list --wallet 0x1234... --status PENDING --pretty
-
-# Check specific limit order
-jv limit-order status 0xabc... --pretty
-
-# Cancel a limit order
-jv limit-order cancel 0xabc... --pretty
-```
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `limit_order_id` | Yes | Limit order ID to cancel |
 
 ---
 
-## Error Codes
-
-All CLI commands use consistent exit codes:
-
-| Code | Name | Meaning |
-|------|------|---------|
-| `0` | SUCCESS | Command completed successfully |
-| `1` | CONFIG_ERROR | Missing config, delegation key, or vault profile |
-| `2` | NETWORK_ERROR | RPC or API connection failure |
-| `3` | BUSINESS_ERROR | Order not found, insufficient balance, contract revert |
-| `4` | HTTP_ERROR | HTTP request failure |
+## Error Handling
 
-When a command fails with exit code 1 and mentions "delegation key not found" or "vault not initialized", guide the user to run `jv vault setup`.
+When a tool call fails with errors like "delegation key not found" or "vault not initialized" or "no profile", the vault needs initialization. Guide the user to run `wallet_setup`.