jaspervault_cli 1.0.26 → 1.0.27

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

@@ -0,0 +1,124 @@
+# Onboarding Reference
+
+## 1. Wallet Initialization (`jv vault setup`)
+
+Initialize the JasperVault delegation wallet via WalletConnect. This is the ONLY recommended initialization method.
+
+### Syntax
+
+```
+jv vault setup --network <name> [--timeout <seconds>] [--vault-index <n>] [--pretty]
+```
+
+### 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
+
+### 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 |
+
+### Important Notes
+
+- **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`.
+
+---
+
+## 2. Deposit Tokens (`jv deposit`)
+
+Deposit tokens from Base network to JasperVault via Hyperlane warp routes. Uses WalletConnect for transaction signing (no private key needed).
+
+### Syntax
+
+```
+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 |
+
+### 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).
+
+### Output
+
+```json
+{
+  "success": true,
+  "token": "jbtc",
+  "amount": "0.01",
+  "txHash": "0x...",
+  "arrived": true,
+  "arrivalTimeMs": 12345,
+  "message": "Deposit confirmed"
+}
+```
+
+### Important Notes
+
+- **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.

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

@@ -0,0 +1,294 @@
+# Queries Reference
+
+## 1. List Positions (`jv orders list`)
+
+Query active or historical positions from the Subgraph.
+
+### Syntax
+
+```
+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 |
+
+### Time Format (`--since` / `--until`)
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Relative days | `7d` | 7 days ago |
+| Relative weeks | `1w` | 1 week ago |
+| Relative hours | `2h` | 2 hours ago |
+| ISO date | `2025-01-01` | Specific date |
+| Unix timestamp | `1704067200` | Seconds since epoch |
+
+### Output
+
+```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",
+      "leverage": "50",
+      "createdTime": "2025-03-15T10:30:00.000Z"
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "limit": 20,
+  "totalPages": 1
+}
+```
+
+### Key Output Fields
+
+| Field | Description |
+|-------|-------------|
+| `id` | Order ID (use for TP/SL/protect commands) |
+| `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) |
+
+**Always use the human-readable fields** (`margin`, `size`, `entryPriceUsd`, `leverage`) when reporting to the user. The 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
+```
+
+---
+
+## 3. Portfolio Statistics (`jv orders stats`)
+
+Get aggregate statistics for all positions in your vault.
+
+### Syntax
+
+```
+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
+```
+
+---
+
+## 4. Get Market Price (`jv price`)
+
+Fetch the current market price from the Quote Center oracle.
+
+### Syntax
+
+```
+jv price --symbol <symbol> [options]
+```
+
+### Options
+
+| 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 |
+
+### Output
+
+```json
+{
+  "symbol": "JBTC",
+  "price": "68476.123456789012345678",
+  "priceWei": "68476123456789012345678",
+  "source": "quote_center",
+  "timestamp": "2025-03-15T10:30:00.000Z"
+}
+```
+
+**Always use the `price` field** (human-readable) when reporting to the user.
+
+### Example
+
+```bash
+jv price --symbol JBTC --pretty
+```
+
+---
+
+## 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]
+```
+
+### Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--pretty` | No | — | Pretty-print JSON output |
+
+### Output
+
+The command connects via SSE and waits up to 60s for the job result:
+
+```json
+{
+  "jobId": "MARKET_ORDER_xxx",
+  "status": "completed",
+  "transactionHash": "0x...",
+  "gasUsed": "150000"
+}
+```
+
+| Status | Meaning |
+|--------|---------|
+| `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
+```
+
+---
+
+## 6. Limit Order Management (`jv limit-order`)
+
+### List Limit Orders
+
+```
+jv limit-order list --wallet <address> [--status <status>] [--pretty]
+```
+
+| 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
+
+```
+jv limit-order status <id> [--pretty]
+```
+
+Query a specific limit order by its ID.
+
+### 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
+```
+
+---
+
+## 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 |
+
+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`.

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

@@ -0,0 +1,274 @@
+# Trading Reference
+
+## 1. Create Order (`jv order create`)
+
+Open, close, reduce, or add size to perpetual positions.
+
+### Syntax
+
+```
+jv order create --side <long|short> --symbol <symbol> -m <margin> [options]
+```
+
+### Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--side <long\|short>` | Yes | — | Position side |
+| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`, `CBBTC`) |
+| `-m, --margin <usdc>` | Yes | — | Margin (collateral) in USDC |
+| `--leverage <n>` | No | `50` (from chain config) | Leverage multiplier |
+| `--limit-price <price>` | No | — | Limit price in USDC (omit for market order) |
+| `--margin-account <addr>` | No | from profile | Override margin vault address |
+| `--position-account <addr>` | No | from profile | Override position vault address |
+| `--ppo` | No | — | Enable PPO hedge option protection |
+| `--ppo-expire <duration>` | No | `30m` | PPO expiry: `30m` or `8h` |
+| `--ppo-category <ATM\|OTM>` | No | `ATM` | PPO option category |
+| `--ppo-tier <1-5>` | No | — | OTM strike offset tier (required if OTM) |
+| `--network <name>` | No | `jaspervault` | Network name |
+| `--ttl <seconds>` | No | `3600` | Order TTL in seconds |
+| `--pretty` | No | — | Pretty-print JSON output |
+
+### Market Order vs Limit Order
+
+- **Market order** (no `--limit-price`): Executes immediately at current market price. The CLI auto-waits up to 60s for the on-chain result via SSE.
+- **Limit order** (`--limit-price <N>`): Places a limit order that triggers when price reaches the target. Returns immediately with a `limitOrderId`.
+
+### Market Order Output (TWO JSON lines)
+
+**Line 1 — Submission:**
+```json
+{"success":true,"orderType":"market","jobId":"MARKET_ORDER_xxx","statusUrl":"/api/job/status/...","streamUrl":"/api/job/stream/..."}
+```
+
+**Line 2 — Execution result (auto-waits up to 60s):**
+```json
+{"jobId":"MARKET_ORDER_xxx","status":"completed","transactionHash":"0x..."}
+```
+
+**CRITICAL rules after market order execution:**
+1. If `status === "completed"` → the order IS executed. Do NOT retry or place another order.
+2. If `status === "failed"` → report the error to the user.
+3. If `status === "timeout"` → use `jv job status <jobId> --pretty` to check later.
+4. The `operation` field (if present) contains raw on-chain data in wei — do NOT interpret it.
+5. To verify the actual position, run `jv orders list --pretty` and read the human-readable fields.
+6. Report: "Order executed. Tx: {transactionHash}. Let me check your updated position..." then run `jv orders list --pretty`.
+
+**Limit order output:**
+```json
+{"success":true,"orderType":"limit","limitOrderId":"0x..."}
+```
+Tell the user: "Limit order placed. ID: {limitOrderId}."
+
+### Stderr Output
+
+Before submitting, the CLI prints an estimate to stderr:
+```
+Estimated: ~0.043860 JBTC @ $68,476 (~$3,000 JUSDC total, 50x)
+```
+This is informational only — the actual execution price may differ.
+
+### Common Patterns
+
+**Open a long position (market):**
+```bash
+jv order create --side long --symbol JBTC -m 60 --pretty
+```
+
+**Open a short position (limit):**
+```bash
+jv order create --side short --symbol JBTC -m 100 --limit-price 72000 --pretty
+```
+
+**Close a long position (full close — use opposite side with same margin):**
+```bash
+jv order create --side short --symbol JBTC -m 60 --pretty
+```
+
+**Reduce a long position (partial close):**
+```bash
+jv order create --side short --symbol JBTC -m 30 --pretty
+```
+
+**Add size to existing long:**
+```bash
+jv order create --side long --symbol JBTC -m 50 --pretty
+```
+
+**Open with PPO protection (ATM, 30 min):**
+```bash
+jv order create --side long --symbol JBTC -m 60 --ppo --pretty
+```
+
+**Open with PPO protection (OTM tier 3, 8 hours):**
+```bash
+jv order create --side long --symbol JBTC -m 60 --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3 --pretty
+```
+
+---
+
+## 2. Add PPO Protection (`jv order protect`)
+
+Add hedge option protection to an **existing position** without changing position size.
+
+### Syntax
+
+```
+jv order protect --order-id <id> --symbol <symbol> [options]
+```
+
+### Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--order-id <id>` | Yes | — | Existing perps order ID |
+| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`) |
+| `--ppo-expire <duration>` | No | `30m` | Option expiry: `30m` or `8h` |
+| `--ppo-category <ATM\|OTM>` | No | `ATM` | Option category |
+| `--ppo-tier <1-5>` | No | — | OTM strike offset tier (required if OTM) |
+| `--network <name>` | No | `jaspervault` | Network name |
+| `--ttl <seconds>` | No | `3600` | Signature TTL in seconds |
+| `--pretty` | No | — | Pretty-print JSON output |
+
+### Output
+
+The command auto-waits up to 60s for the on-chain result via SSE:
+```json
+{"jobId":"OPTION_ORDER_xxx","status":"completed","transactionHash":"0x..."}
+```
+
+### Important
+
+- Use `jv order protect` to add hedge to an **existing** position.
+- Do NOT use `jv order create --ppo` for this — that adds position size.
+- The CLI auto-detects position side (LONG/SHORT) from the order and selects the correct hedge type (PUT for LONG, CALL for SHORT).
+
+---
+
+## 3. Take-Profit (`jv tp set`)
+
+Set a take-profit limit order for an existing position.
+
+### Syntax
+
+```
+jv tp set --order-id <id> --price <usdc> --symbol <symbol> [options]
+```
+
+### Options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `--order-id <id>` | Yes | — | Existing order ID (position to close) |
+| `--price <usdc>` | Yes | — | Target price in USDC |
+| `--symbol <symbol>` | Yes | — | Asset symbol (e.g., `JBTC`) |
+| `--side <long\|short>` | No | `long` | Position side being closed |
+| `--ppo` | No | — | Enable PPO hedge on the TP order |
+| `--ppo-expire <duration>` | No | `30m` | PPO expiry: `30m` or `8h` |
+| `--ppo-category <ATM\|OTM>` | No | `ATM` | PPO option category |
+| `--ppo-tier <1-5>` | No | — | OTM strike offset tier |
+| `--network <name>` | No | `jaspervault` | Network name |
+| `--ttl <seconds>` | No | `86400` | Order TTL in seconds (default: 24h) |
+| `--pretty` | No | — | Pretty-print JSON output |
+
+### Output
+
+```json
+{"success":true,"orderType":"limit","limitOrderId":"0x..."}
+```
+
+### Example
+
+```bash
+# Set TP at $75,000 for a long position
+jv tp set --order-id 123 --price 75000 --symbol JBTC --pretty
+
+# Set TP for a short position
+jv tp set --order-id 456 --price 60000 --symbol JBTC --side short --pretty
+```
+
+---
+
+## 4. Stop-Loss (`jv sl set`)
+
+Set a stop-loss limit order for an existing position. Same options as `jv tp set`.
+
+### Syntax
+
+```
+jv sl set --order-id <id> --price <usdc> --symbol <symbol> [options]
+```
+
+Options are identical to `jv tp set` (see above).
+
+### Example
+
+```bash
+# Set SL at $65,000 for a long position
+jv sl set --order-id 123 --price 65000 --symbol JBTC --pretty
+
+# Set SL for a short position
+jv sl set --order-id 456 --price 80000 --symbol JBTC --side short --pretty
+```
+
+---
+
+## 5. PPO (Perpetual Put Option) Details
+
+PPO provides hedge protection for positions. Key concepts:
+
+### Option Categories
+
+| Category | Description | `--ppo-tier` |
+|----------|-------------|--------------|
+| `ATM` (default) | At-the-money — strike = current price | Not needed |
+| `OTM` | Out-of-the-money — strike offset from current price | Required (1-5) |
+
+### OTM Tiers
+
+| Tier | Strike Offset | Ratio |
+|------|---------------|-------|
+| 1 | 0.1% | 0.001 |
+| 2 | 0.2% | 0.002 |
+| 3 | 0.3% | 0.003 |
+| 4 | 0.4% | 0.004 |
+| 5 | 0.5% | 0.005 |
+
+### Expiry Options
+
+| Duration | Seconds | Flag |
+|----------|---------|------|
+| 30 minutes (default) | 1800 | `--ppo-expire 30m` |
+| 8 hours | 28800 | `--ppo-expire 8h` |
+
+### Hedge Type (auto-selected)
+
+- **LONG position** → PUT option (protects against price drop)
+- **SHORT position** → CALL option (protects against price rise)
+
+### Intent Mapping
+
+| User Says | Action | Command |
+|-----------|--------|---------|
+| "加保护" / "add protection" to existing | `jv order protect` | `jv order protect --order-id <id> --symbol JBTC` |
+| "开仓 + 保护" / "open with protection" | `jv order create --ppo` | `jv order create --side long -m 60 --symbol JBTC --ppo` |
+| "加仓 + 保护" / "add size with protection" | `jv order create --ppo` (same side) | `jv order create --side long -m 50 --symbol JBTC --ppo` |
+| "8小时" / "8 hour" | Add `--ppo-expire 8h` | |
+| "OTM" / "价外" | Add `--ppo-category OTM`, then ask for tier | |
+| "ATM" / "平价" or nothing | Default ATM, 30 min | |
+| "取消PPO" / "cancel PPO" / "remove hedge" | Order WITHOUT `--ppo` | See below |
+
+### PPO Cancellation (IMPORTANT)
+
+The smart contract **automatically cancels** existing PPO hedge options when you execute any position operation (reduce, close, add size) **without** the `--ppo` flag. There is **NO separate "cancel PPO" command**.
+
+| User Request | Correct Action | Command |
+|--------------|---------------|---------|
+| "减仓 + 取消PPO" | Single reduce order without `--ppo` | `jv order create --side <opposite> -m <amount> --symbol JBTC` |
+| "加仓 + 取消PPO" | Single add-size order without `--ppo` | `jv order create --side <same> -m <amount> --symbol JBTC` |
+| "平仓" (full close) | Close order without `--ppo` | `jv order create --side <opposite> -m <full_margin> --symbol JBTC` |
+| "减仓 + 保留PPO" | Reduce order WITH `--ppo` | `jv order create --side <opposite> -m <amount> --symbol JBTC --ppo` |
+
+**NEVER do this:**
+- Do NOT try to cancel PPO as a separate step. There is no "cancel PPO" command.
+- Do NOT send two orders when one suffices. "减仓 + 取消PPO" = ONE order without `--ppo`.

package/dist/src/templates/skill-content/scripts/check-init.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Quick vault initialization check — exits 0 if ready, non-zero otherwise
+jv orders list --pretty 2>/dev/null
+exit $?