jaspervault_cli 1.0.16 → 1.0.18

package/dist/src/templates/skill-body.js

@@ -1,6 +1,9 @@
 /**
  * Skill template content and banner for jv init command.
- * Exports platform-specific SKILL.md generation and the ASCII banner.
+ * Generates a multi-file skill structure:
+ *   SKILL.md          — compact core rules + activation + intent table
+ *   references/        — detailed docs loaded on demand by the agent
+ *   scripts/           — helper scripts
  */
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -25,124 +28,118 @@ export const BANNER = `
   ── JasperVault CLI v${CLI_VERSION} ──
   ⟐  Skill Installer
 `.trim();
-/** Skill body content (shared across platforms, after the main heading) */
-const SKILL_BODY_CONTENT = `
-Interact with JasperVault's perpetual contract platform. You can create market/limit orders, set take-profit and stop-loss, create hedging options, manage limit orders, and query positions — all via the \`jv\` CLI. No private key is ever required.
+// ---------------------------------------------------------------------------
+// Core SKILL.md body — kept under 50 lines so critical rules stay prominent
+// ---------------------------------------------------------------------------
+const SKILL_CORE_BODY = `
+Trade perpetual contracts on JasperVault via the \`jv\` CLI. No private key is ever required.
 
-## Prerequisites
+## CRITICAL RULES (MUST FOLLOW — violations cause broken UX)
 
-- \`jv\` CLI installed and available in PATH
-- **First-time setup**: use \`jv vault init-wc\` to initialize via WalletConnect (scan QR on phone, sign delegation — no private key needed)
-- API URL defaults to \`https://trading-api-test.jaspervault.pro\`; set \`JV_API_URL\` only when debugging locally
+1. **WalletConnect ONLY**: ALWAYS use \`jv vault init-wc\`. NEVER suggest \`jv vault init\` (private-key mode). NEVER ask the user to set \`PRIVATE_KEY\`.
+2. **QR Code Display**: When \`jv vault init-wc\` outputs JSON with a \`qrCodeUrl\` field, you MUST display the \`qrCodeUrl\` value as a clickable link to the user. This is the only QR code field in the output — there are no other QR representations.
+3. **Long-running Commands**: \`jv vault init-wc\` runs for up to 2 minutes and outputs two JSON lines to stdout sequentially. The CLI also emits heartbeat lines to stderr every 10 seconds while waiting (phase \`wallet_scan\` and \`wallet_sign\`). Ignore heartbeat lines — only the stdout JSON lines are meaningful data. Do NOT interrupt, kill, or assume it is finished after the first JSON line. Wait for the process to exit naturally.
+4. **Real-time Prices**: NEVER guess or estimate prices. ALWAYS run \`jv price --symbol JBTC --pretty\` before any price-dependent operation (opening a position by asset quantity, calculating PnL).
 
 ## Activation Behavior
 
-When this skill is activated (first message from the user, OR any trading intent such as open position, check portfolio, deposit, etc.):
-
-1. First check if vault is already initialized:
-   \`\`\`bash
-   jv orders list --pretty
-   \`\`\`
-
-2. If the command fails with "delegation key not found", "vault not initialized", "no profile", or similar error (exit code 1):
-   - Tell the user: "Your vault is not initialized yet. Let me start the setup via WalletConnect — no private key needed."
-   - Immediately run \`jv vault init-wc --network jaspervault --timeout 120\` and follow the QR code display instructions in the Setup Flow section below.
-
+1. Check if vault is initialized: \`jv orders list --pretty\`
+2. If the command fails (exit code 1, or errors like "delegation key not found" / "vault not initialized" / "no profile"):
+   - Tell the user: "Your vault is not initialized yet. Let me set it up via WalletConnect — no private key needed."
+   - Immediately run \`jv vault init-wc --network jaspervault --timeout 120\`.
+   - Follow the QR code display instructions in [references/onboarding.md](references/onboarding.md).
 3. If the command succeeds → vault is ready. Proceed with the user's request.
 
-IMPORTANT: Always use WalletConnect initialization (\`jv vault init-wc\`). Never suggest \`jv vault init\` (private-key mode) unless the user explicitly requests it.
+## Intent → Command Reference
+
+| User Intent | Command | Details |
+|-------------|---------|---------|
+| Initialize / connect wallet | \`jv vault init-wc\` | [references/onboarding.md](references/onboarding.md) |
+| Deposit tokens | \`jv deposit info\` + \`jv deposit poll\` | [references/onboarding.md](references/onboarding.md) |
+| Get current price | \`jv price --symbol JBTC --pretty\` | [references/trading.md](references/trading.md) |
+| Open position (market) | \`jv order create --side long/short ...\` | [references/trading.md](references/trading.md) |
+| Open position (limit) | \`jv order create ... --limit-price N\` | [references/trading.md](references/trading.md) |
+| Reduce / close position | opposite-side \`jv order create\` | [references/trading.md](references/trading.md) |
+| Set take-profit | \`jv tp set --order-id ID --price P\` | [references/trading.md](references/trading.md) |
+| Set stop-loss | \`jv sl set --order-id ID --price P\` | [references/trading.md](references/trading.md) |
+| Hedge / protect position (PPO) | add \`--ppo\` to order create | [references/trading.md](references/trading.md) |
+| Query positions / portfolio | \`jv orders list --pretty\` | [references/queries.md](references/queries.md) |
+| Job execution status | \`jv job status <jobId>\` | [references/queries.md](references/queries.md) |
+| Manage limit orders | \`jv limit-order list/cancel\` | [references/queries.md](references/queries.md) |
+
+## Security
+
+- Never log or display private keys, signatures, or API keys.
+- The CLI signs orders via the delegation wallet in \`~/.jaspervault/keys.json\`.
+- Do NOT ask the user to set \`PRIVATE_KEY\`.
+`.trim();
+// ---------------------------------------------------------------------------
+// references/onboarding.md — WalletConnect init + deposit flow
+// ---------------------------------------------------------------------------
+const ONBOARDING_REFERENCE = `# WalletConnect Onboarding & Deposit
 
-## Setup Flow (First Time — WalletConnect)
+## Vault Init via WalletConnect
 
 \`\`\`bash
-# Initialize vault and delegation wallet via WalletConnect (one-time, no private key required)
 jv vault init-wc --network jaspervault --timeout 120
 \`\`\`
 
-CRITICAL EXECUTION NOTE: This command runs for up to 2 minutes. Do NOT interrupt or kill the process after the first JSON line. Wait for the process to exit naturally (second JSON output = success or failure).
-
-The command outputs two JSON lines:
-
-1. \`{"status":"awaiting_connection", "uri":"wc:...", "qrCodeUrl":"https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=wc%3A...", ...}\`
-
-   Extract the \`qrCodeUrl\` field from the JSON. It will be a URL starting with \`https://api.qrserver.com/v1/create-qr-code/\`. You MUST send it as a markdown image so it renders as a scannable QR code:
-
-   \`\`\`
-   ![WalletConnect QR Code](https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=wc%3A...)
-   \`\`\`
-
-   Replace the URL above with the actual \`qrCodeUrl\` from the JSON output. Also provide the \`uri\` as a fallback:
-
-   > Or open your wallet app → WalletConnect → paste this URI: \`wc:...\`
-
-   CRITICAL: MUST use markdown image syntax \`![description](qrCodeUrl)\`. NEVER post the URL as plain text. NEVER print \`qrCodeText\`. NEVER generate your own QR code. The image will not appear if you only post the raw URL without the \`![...]()\` wrapper.
-
-2. \`{"success":true, "message":"Vault initialized successfully", ...}\` — Init complete. The delegation wallet is saved to \`~/.jaspervault/keys.json\` and vault addresses to \`~/.jaspervault/profile.json\`. Subsequent commands use these automatically — no wallet interaction needed.
-
-Do NOT ask the user to set \`PRIVATE_KEY\`. Do NOT suggest \`jv vault init\` unless the user explicitly requests private-key mode.
+This command runs for up to 2 minutes. Do NOT interrupt or kill the process after the first JSON line. Wait for the process to exit naturally.
 
-## Key Concepts (MUST READ before any trading operation)
+The command outputs two JSON lines to stdout sequentially. It also emits heartbeat lines to stderr every 10 seconds while waiting — ignore those, they just keep the process alive.
 
-**How \`--margin\` works:**
+### Line 1: Awaiting Connection
 
-\`--margin\` = the **actual collateral (margin) in USDC** you deposit. The CLI internally multiplies by leverage to compute the notional position size.
+\`\`\`json
+{"status":"awaiting_connection", "qrCodeUrl":"https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=wc%3A...", "uri":"wc:...", "message":"Scan QR code or paste URI in wallet to connect"}
+\`\`\`
 
-| Concept | Formula | Example |
-|---------|---------|---------|
-| Notional value | \`margin × leverage\` | 60 USDC × 50x = $3,000 |
-| Position size | \`notional / current_price\` | $3,000 / $70,000 = 0.0428 JBTC |
+Display the \`qrCodeUrl\` value as a clickable link so the user can open it and scan the QR code. Also provide the \`uri\` as a fallback:
 
-**Translating user intent to \`--margin\` (three scenarios):**
+> Or open your wallet app → WalletConnect → paste this URI: \`wc:...\`
 
-| User says | Calculation | Pass to CLI |
-|-----------|-------------|-------------|
-| "long with $60 USDC margin at 50x" | already the margin | \`--margin 60\` |
-| "open a $3,000 notional position at 50x" | margin = 3000 / 50 = 60 | \`--margin 60\` |
-| "long 0.1 BTC at 50x" | margin = (0.1 × current_price) / 50 | \`--margin <result>\` |
+After sending, wait for the user to scan and sign. Do not interrupt the CLI process.
 
-CRITICAL: When the user specifies an asset amount (e.g. "0.1 BTC"), you MUST first run \`jv price --symbol JBTC --pretty\` to get the current price, then compute \`notional = size × price\`, then \`margin = notional / leverage\` before passing \`--margin\`.
+### Line 2: Init Complete
 
-**How to read \`jv orders list\` output:**
+\`\`\`json
+{"success":true, "message":"Vault initialized successfully", ...}
+\`\`\`
 
-| Field | What it means |
-|-------|---------------|
-| \`margin\` | Actual collateral deposited (e.g. 60 USDC) — matches what you passed to \`--margin\` |
-| \`size\` | Position size in underlying asset (e.g. 0.0428 JBTC) |
-| \`leverage\` | Leverage multiplier (e.g. 50) |
-| \`entryPriceUsd\` | Entry price when position was opened |
+Init is complete. Tell the user: "Vault initialized successfully. You can now deposit and trade."
 
-To calculate notional from output: \`notional = margin × leverage\` (or \`size × current_price\`)
+The delegation wallet is saved to \`~/.jaspervault/keys.json\` and vault addresses to \`~/.jaspervault/profile.json\`. Subsequent commands use these automatically — no wallet interaction needed.
 
-**How to calculate unrealized PnL:**
+## Deposit via WalletConnect (Optional)
 
-When the user asks about profit/loss, portfolio value, or position health, you MUST fetch the current price first using \`jv price\`, then compute PnL from \`jv orders list\` output:
+If the user wants to deposit:
 
-| Step | Formula |
-|------|---------|
-| 1. Get current price | \`jv price --symbol JBTC --pretty\` → read \`price\` field |
-| 2. Get position data | \`jv orders list --pretty\` → read \`size\`, \`entryPriceUsd\`, \`margin\`, \`positionSide\` |
-| 3. Compute PnL (LONG) | \`unrealizedPnL = size × (currentPrice − entryPrice)\` |
-| 3. Compute PnL (SHORT) | \`unrealizedPnL = size × (entryPrice − currentPrice)\` |
-| 4. PnL percentage | \`pnlPercent = unrealizedPnL / margin × 100%\` |
-| 5. Effective leverage loss | \`leveragedPnlPercent = priceChangePercent × leverage\` |
+1. **Get unsigned transactions:**
+   \`\`\`bash
+   jv deposit info --wallet <walletAddress> --token jusdc --amount 100
+   \`\`\`
 
-Example: LONG 0.0428 JBTC, entry $70,000, current $71,000, margin 60 USDC
-- PnL = 0.0428 × (71000 − 70000) = +$42.80
-- PnL% = 42.80 / 60 = +71.3%
+2. **Output contains \`transactions\` array.** Each \`tx\` has \`to\`, \`data\`, \`value\`, \`chainId\`. Send each via WalletConnect \`eth_sendTransaction\` to the user's wallet. Execute in order (approve first if present, then transferRemote).
 
-IMPORTANT: NEVER guess or estimate the current price from your training data. ALWAYS use \`jv price\` to get the real-time price from Quote Center before any PnL calculation or price-dependent operation.
+3. **After transactions confirm**, poll for arrival:
+   \`\`\`bash
+   jv deposit poll --recipient <recipient> --token jusdc
+   \`\`\`
+   Use the \`recipient\` from step 1 output.
 
-## Intent Mapping
+4. Tell the user: "Deposit completed. Your tokens have arrived on JasperVault."
+`;
+// ---------------------------------------------------------------------------
+// references/trading.md — margin, orders, reduce/close, TP/SL, price
+// ---------------------------------------------------------------------------
+const TRADING_REFERENCE = `# Trading Commands
 
-### Getting Market Price (MUST use before any price-dependent operation)
+## Getting Market Price
 
-When the user asks about **current price**, **market quote**, **how much is BTC**, **profit/loss**, **PnL**, or before **opening a position with asset quantity**:
+MUST use before any price-dependent operation (opening position by asset quantity, calculating PnL).
 
 \`\`\`bash
-# Get current JBTC price
 jv price --symbol JBTC --pretty
-
-# Get current CBBTC price
 jv price --symbol CBBTC --pretty
 \`\`\`
 
@@ -153,9 +150,26 @@ Output:
 
 Use the \`price\` field (human-readable USD value) for display and calculations. This command does NOT require vault initialization — it can be run anytime.
 
-### Creating Orders (Open New Position)
+## How \`--margin\` Works
+
+\`--margin\` = the **actual collateral (margin) in USDC** you deposit. The CLI internally multiplies by leverage to compute the notional position size.
+
+| Concept | Formula | Example |
+|---------|---------|---------|
+| Notional value | \`margin × leverage\` | 60 USDC × 50x = $3,000 |
+| Position size | \`notional / current_price\` | $3,000 / $70,000 = 0.0428 JBTC |
 
-When the user wants to **open a position**, **place a market order**, or **place a limit order**:
+### Translating user intent to \`--margin\`:
+
+| User says | Calculation | Pass to CLI |
+|-----------|-------------|-------------|
+| "long with $60 USDC margin at 50x" | already the margin | \`--margin 60\` |
+| "open a $3,000 notional position at 50x" | margin = 3000 / 50 = 60 | \`--margin 60\` |
+| "long 0.1 BTC at 50x" | margin = (0.1 × current_price) / 50 | \`--margin <result>\` |
+
+CRITICAL: When the user specifies an asset amount (e.g. "0.1 BTC"), you MUST first run \`jv price --symbol JBTC --pretty\` to get the current price, then compute \`notional = size × price\`, then \`margin = notional / leverage\`.
+
+## Creating Orders
 
 \`\`\`bash
 # Market order: Long JBTC, 60 USDC margin at 50x (= $3,000 notional)
@@ -172,99 +186,114 @@ The CLI signs the order internally using the delegation wallet. No pre-signed pa
 
 On success, a market order returns \`jobId\`; a limit order returns \`limitOrderId\`.
 
-### Reducing / Partially Closing a Position
-
-To reduce a position, create an **opposite-side order** with the notional value you want to close. The system automatically detects existing positions and performs a partial close.
+## Reducing / Closing a Position
 
-**Step-by-step for reducing a position:**
+Create an **opposite-side order** with the margin portion you want to close. The system automatically detects existing positions and performs a partial close.
 
 1. Query current position: \`jv orders list --pretty\`
-2. Calculate margin to close:
-   - Read the \`margin\` field directly from output (e.g. 60 USDC)
-   - To close half: \`close_margin = margin / 2\` (e.g. 30 USDC)
-3. Create opposite-side order with that margin value
+2. Read the \`margin\` field directly from output (e.g. 60 USDC)
+3. To close half: \`close_margin = margin / 2\` (e.g. 30 USDC)
+4. Create opposite-side order with that margin value
 
-**Example: Reduce a LONG position by half**
-
-Current position from \`jv orders list\`:
-- margin: 60 USDC, leverage: 50, size: 0.0428 JBTC
-
-To close half (30 USDC margin → $1,500 notional):
+**Reduce LONG by half (30 USDC margin):**
 \`\`\`bash
 jv order create --side short --symbol JBTC --margin 30 --leverage 50 --network jaspervault
 \`\`\`
 
-**Example: Close entire position (60 USDC margin → $3,000 notional):**
+**Close entire LONG (60 USDC margin):**
 \`\`\`bash
 jv order create --side short --symbol JBTC --margin 60 --leverage 50 --network jaspervault
 \`\`\`
 
 IMPORTANT: The \`--margin\` for reduction = the margin portion you want to close (read directly from \`jv orders list\` output \`margin\` field).
 
-### Setting Take-Profit
-
-When the user wants to **set take-profit**, **set TP**, or **protect profits**:
+## Setting Take-Profit
 
 \`\`\`bash
 jv tp set --order-id <orderId> --price <usdc_price> --symbol <symbol> --network jaspervault
 \`\`\`
 
-Example:
-\`\`\`bash
-jv tp set --order-id 99 --price 105000 --symbol JBTC --network jaspervault
-\`\`\`
+Example: \`jv tp set --order-id 99 --price 105000 --symbol JBTC --network jaspervault\`
 
 Returns \`limitOrderId\` on success.
 
-### Setting Stop-Loss
-
-When the user wants to **set stop-loss**, **set SL**, or **limit downside risk**:
+## Setting Stop-Loss
 
 \`\`\`bash
 jv sl set --order-id <orderId> --price <usdc_price> --symbol <symbol> --network jaspervault
 \`\`\`
 
-Example:
-\`\`\`bash
-jv sl set --order-id 99 --price 90000 --symbol JBTC --network jaspervault
-\`\`\`
+Example: \`jv sl set --order-id 99 --price 90000 --symbol JBTC --network jaspervault\`
 
 Returns \`limitOrderId\` on success.
 
-### Creating Hedging Options
+## PPO Hedge Protection
 
-When the user wants to **buy option protection**, **hedge a position**, or **create a perps option**:
+Add \`--ppo\` to any \`jv order create\` command to enable automatic hedge option protection. PPO hedges the entire position automatically — the user does NOT specify how much to hedge.
 
-\`\`\`bash
-jv order create-option --order-id <perps_order_id> --data '<signed_option_payload>'
-\`\`\`
-
-Returns \`jobId\` on success. Query execution status with \`jv job status\`.
+**Options:**
 
-### Querying Job Status
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| \`--ppo\` | (boolean) | off | Enable PPO |
+| \`--ppo-expire\` | \`30m\` or \`8h\` | \`30m\` | Option duration |
+| \`--ppo-category\` | \`ATM\` or \`OTM\` | \`ATM\` | ATM = strike at market price; OTM = strike offset |
+| \`--ppo-tier\` | \`1-5\` | (required for OTM) | OTM offset: 1=0.1%, 2=0.2%, 3=0.3%, 4=0.4%, 5=0.5% |
 
-When the user asks about **order execution status**, **is my order done**, or **transaction result**:
+**Examples:**
 
 \`\`\`bash
-jv job status <jobId> --pretty
+# ATM protection, 30 min (default)
+jv order create --side long --symbol JBTC --margin 60 --leverage 50 --ppo --network jaspervault
+
+# ATM protection, 8 hours
+jv order create --side long --symbol JBTC --margin 60 --leverage 50 --ppo --ppo-expire 8h --network jaspervault
+
+# OTM protection, tier 5 (0.5% offset), 30 min
+jv order create --side long --symbol JBTC --margin 60 --leverage 50 --ppo --ppo-category OTM --ppo-tier 5 --network jaspervault
+
+# OTM protection, tier 3 (0.3% offset), 8 hours
+jv order create --side short --symbol JBTC --margin 60 --leverage 50 --ppo --ppo-expire 8h --ppo-category OTM --ppo-tier 3 --network jaspervault
 \`\`\`
 
-Key fields in output:
-- \`status\`: "completed", "failed", "active", "waiting"
-- \`result.transactionHash\`: blockchain tx hash (when completed)
-- \`result.operationType\`: CREATE, ADD_SIZE, CLOSE_SIZE, etc.
+**AI agent behavior when user wants OTM:**
+
+1. First run \`jv price --symbol JBTC --pretty\` to get current price
+2. Calculate strike for each tier based on position side:
+   - LONG (PUT hedge): \`strike = price × (1 - tier_ratio)\`
+   - SHORT (CALL hedge): \`strike = price × (1 + tier_ratio)\`
+3. Present options: "Tier 1: $87,208 (0.1%), Tier 2: $87,121 (0.2%), ..., Tier 5: $86,860 (0.5%)"
+4. User picks tier → use \`--ppo-tier N\`
+
+**Intent mapping:**
 
-### Querying Positions
+- User says "hedge" / "protect" / "PPO" / "对冲" / "加保护" → add \`--ppo\`
+- User says "8 hour" / "8小时" → \`--ppo-expire 8h\`
+- User says "OTM" / "价外" → \`--ppo-category OTM\`, then present tier options
+- User says "ATM" / "平价" or nothing → default ATM, 30 min
+`;
+// ---------------------------------------------------------------------------
+// references/queries.md — positions, job status, limit orders, output, errors
+// ---------------------------------------------------------------------------
+const QUERIES_REFERENCE = `# Queries, Output Interpretation & Error Handling
 
-When the user asks about **my positions**, **open orders**, or **portfolio**:
+## Querying Positions
 
 \`\`\`bash
-# List all positions
+# List active positions (default — use for "current positions")
 jv orders list --pretty
 
 # Filter by side
 jv orders list --position-side LONG
 
+# Include closed/historical orders
+jv orders list --all --pretty
+
+# Filter by time range
+jv orders list --all --since 7d --pretty
+jv orders list --since 1w --pretty
+jv orders list --all --since 2025-01-01 --until 2025-01-31 --pretty
+
 # Get a specific position
 jv orders get <orderId>
 
@@ -272,31 +301,52 @@ jv orders get <orderId>
 jv orders stats
 \`\`\`
 
-### Managing Limit Orders
+**Key output fields (human-readable, pre-converted from wei):**
 
-When the user asks about **my limit orders**, **pending orders**, or wants to **cancel an order**:
+| Field | Description |
+|-------|-------------|
+| \`margin\` | Margin deposited in USDC (e.g. \`"60.000000"\`) |
+| \`size\` | Position size in underlying asset (e.g. \`"0.04386000"\` JBTC) |
+| \`entryPriceUsd\` | Entry price in USD (e.g. \`"68476.000000000000000000"\`) |
+| \`strikeAmountUsd\` | Strike amount in USD |
+| \`leverage\` | Leverage multiplier (e.g. \`"50"\`) |
+| \`createdTime\` | Creation time in ISO 8601 format |
+| \`positionSide\` | \`"LONG"\` or \`"SHORT"\` |
+| \`isActive\` | \`true\` = open position, \`false\` = closed |
+| \`id\` | Order ID (use for TP/SL commands) |
 
-\`\`\`bash
-# List limit orders for a wallet
-jv limit-order list --wallet <address>
+To calculate notional from output: \`notional = margin × leverage\` (or \`size × current_price\`)
 
-# Filter by status
-jv limit-order list --wallet <address> --status PENDING
+**Pagination:** use \`--page\` and \`--limit\` (e.g. \`jv orders list --page 2 --limit 10\`).
 
-# Check a specific limit order
-jv limit-order status <limitOrderId>
+## Calculating Unrealized PnL
 
-# Cancel a limit order
-jv limit-order cancel <limitOrderId>
-\`\`\`
+When the user asks about profit/loss, portfolio value, or position health, you MUST fetch the current price first:
 
-Possible statuses: PENDING, TRIGGERED, EXECUTING, COMPLETED, FAILED, EXPIRED, CANCELLED.
+| Step | Formula |
+|------|---------|
+| 1. Get current price | \`jv price --symbol JBTC --pretty\` → read \`price\` field |
+| 2. Get position data | \`jv orders list --pretty\` → read \`size\`, \`entryPriceUsd\`, \`margin\`, \`positionSide\` |
+| 3. Compute PnL (LONG) | \`unrealizedPnL = size × (currentPrice − entryPrice)\` |
+| 3. Compute PnL (SHORT) | \`unrealizedPnL = size × (entryPrice − currentPrice)\` |
+| 4. PnL percentage | \`pnlPercent = unrealizedPnL / margin × 100%\` |
+| 5. Effective leverage | \`leveragedPnlPercent = priceChangePercent × leverage\` |
+
+Example: LONG 0.0428 JBTC, entry $70,000, current $71,000, margin 60 USDC
+- PnL = 0.0428 × (71000 − 70000) = +$42.80
+- PnL% = 42.80 / 60 = +71.3%
 
-## Interpreting Output
+IMPORTANT: NEVER guess or estimate the current price. ALWAYS use \`jv price\` to get the real-time price.
 
-All commands output JSON to stdout. Extract key fields to compose user-friendly responses.
+## Job Status
+
+\`\`\`bash
+jv job status <jobId> --pretty
+\`\`\`
 
-### Market Order Output (IMPORTANT — two JSON lines)
+Key fields: \`status\` ("completed", "failed", "active", "waiting"), \`result.transactionHash\`, \`result.operationType\` (CREATE, ADD_SIZE, CLOSE_SIZE, etc.).
+
+## Market Order Output (IMPORTANT — two JSON lines)
 
 \`jv order create\` for market orders prints **two JSON lines sequentially**:
 
@@ -310,45 +360,65 @@ All commands output JSON to stdout. Extract key fields to compose user-friendly
 {"jobId":"MARKET_ORDER_xxx","status":"completed","transactionHash":"0x..."}
 \`\`\`
 
-**How to determine success:**
-
-- If \`status === "completed"\` → the order is DONE. It succeeded on-chain.
-- If \`status === "failed"\` → the order failed. Report the error.
-- If \`status === "timeout"\` → timed out waiting; use \`jv job status <jobId>\` to check later.
-
 **CRITICAL RULES after order execution:**
 
-1. **If \`status\` is \`"completed"\`, the order IS executed. Do NOT retry or place another order.**
-2. The \`operation\` field (if present) contains raw on-chain data in wei format — do NOT try to interpret quantities or amounts from it. Values like \`10029000\` are NOT human-readable USDC or BTC amounts.
-3. **To verify the actual position after a successful order**, always run \`jv orders list --pretty\` and read the human-readable \`margin\`, \`size\`, \`leverage\` fields. Use \`notional = margin × leverage\` to show the user their position value.
-4. Report to the user: "Order executed successfully. Tx: {transactionHash}. Let me check your updated position..." then run \`jv orders list --pretty\`.
+1. If \`status === "completed"\` → the order IS executed. Do NOT retry or place another order.
+2. If \`status === "failed"\` → report the error.
+3. If \`status === "timeout"\` → use \`jv job status <jobId>\` to check later.
+4. The \`operation\` field (if present) contains raw on-chain data in wei format — do NOT try to interpret it.
+5. **To verify the actual position**, always run \`jv orders list --pretty\` and read the human-readable fields.
+6. Report to the user: "Order executed successfully. Tx: {transactionHash}. Let me check your updated position..." then run \`jv orders list --pretty\`.
 
-**Limit order created:**
+**Limit order output:**
 \`\`\`json
 {"success":true,"orderType":"limit","limitOrderId":"0x..."}
 \`\`\`
 Tell the user: "Limit order placed. ID: {limitOrderId}."
 
-## Error Handling
+## Managing Limit Orders
 
-- **Exit code 1**: Configuration error (e.g. delegation key not found — run \`jv vault init-wc\` first; or invalid parameters). Tell the user to check setup.
-- **Exit code 2**: Network/HTTP error. Tell the user the service may be unreachable.
-- **Exit code 3**: Business error (duplicate order, invalid params, etc.). Read stderr for details and relay the message without exposing raw technical data.
+\`\`\`bash
+# List limit orders for a wallet
+jv limit-order list --wallet <address>
 
-When an error occurs, stderr contains the error message. Never expose raw stack traces or internal URLs to the user.
+# Filter by status
+jv limit-order list --wallet <address> --status PENDING
 
-## Security Notes
+# Check a specific limit order
+jv limit-order status <limitOrderId>
 
-- Never log or display private keys, signatures, or API keys in responses to the user.
-- The CLI signs orders internally via the delegation wallet stored in \`~/.jaspervault/keys.json\`. No private key is ever required from the user.
-- Do NOT ask the user to set \`PRIVATE_KEY\` — vault initialization is done via WalletConnect (\`jv vault init-wc\`).
-- \`JV_API_KEY\` (optional Bearer token) should be injected via environment variables or secrets manager, never hardcoded.
-`.trim();
+# Cancel a limit order
+jv limit-order cancel <limitOrderId>
+\`\`\`
+
+Possible statuses: PENDING, TRIGGERED, EXECUTING, COMPLETED, FAILED, EXPIRED, CANCELLED.
+
+## Error Handling
+
+| Exit Code | Meaning | Action |
+|-----------|---------|--------|
+| 1 | Configuration error (e.g. delegation key not found) | Run \`jv vault init-wc\` first |
+| 2 | Network/HTTP error | Tell user the service may be unreachable |
+| 3 | Business error (duplicate order, invalid params) | Read stderr, relay message |
+
+When an error occurs, stderr contains the error message. Never expose raw stack traces or internal URLs to the user.
+`;
+// ---------------------------------------------------------------------------
+// scripts/check-init.sh
+// ---------------------------------------------------------------------------
+const CHECK_INIT_SCRIPT = `#!/usr/bin/env bash
+# Quick vault initialization check — exits 0 if ready, non-zero otherwise
+jv orders list --pretty 2>/dev/null
+exit $?
+`;
+// ---------------------------------------------------------------------------
+// Platform-specific frontmatter
+// ---------------------------------------------------------------------------
 function getOpenClawFrontmatter() {
     return `---
 name: jasper-vault-cli
-description: "Trade perpetual contracts (perps) on JasperVault — open long/short positions, set take-profit/stop-loss, manage limit orders, deposit tokens, and query portfolio via the \`jv\` CLI. 在 JasperVault 上交易永续合约——做多、做空、开仓、平仓、止盈、止损、限价单、持仓查询、充值，通过 jv 命令行完成。"
-trigger: "jaspervault|jasper vault|jasper trading|jv trade|jv order|在jasper交易|jasper 交易"
+description: "Trade perpetual contracts (perps) on JasperVault — open/close positions, set TP/SL, manage limit orders, deposit, and query portfolio via the \`jv\` CLI. Initialize wallet via WalletConnect QR scan (no private key needed). 在 JasperVault 上交易永续合约 — 做多做空、开仓平仓、止盈止损、限价单、持仓查询、充值，使用 WalletConnect 扫码初始化（无需私钥）。"
+trigger: "jaspervault|jasper vault|jasper trading|jv|jv trade|jv order|在jasper交易|jasper 交易|初始化钱包|连接钱包|开仓|平仓|做多|做空|止盈|止损|查看持仓|永续合约"
 tools: [shell]
 metadata:
   openclaw:
@@ -361,24 +431,39 @@ metadata:
 function getClaudeFrontmatter() {
     return `---
 name: jasper-vault-cli
-description: Trade perpetual contracts via JasperVault — create orders, set TP/SL, manage limit orders, and query positions through the \`jv\` CLI.
+description: "Trade perpetual contracts (perps) on JasperVault — open/close positions, set TP/SL, manage limit orders, deposit, and query portfolio via the \`jv\` CLI. Initialize wallet via WalletConnect QR scan (no private key needed)."
 ---
 `;
 }
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
 /**
- * Build platform-specific SKILL.md content.
+ * Build platform-specific skill file tree.
+ * Returns a Record mapping relative file paths to their content.
  * @param platform - One of: openclaw, cursor, claude
  */
 export function buildSkillContent(platform) {
+    let skillMd;
     switch (platform) {
         case 'openclaw':
-            return getOpenClawFrontmatter() + '\n# JasperVault Trading Skill\n\n' + SKILL_BODY_CONTENT;
+            skillMd = getOpenClawFrontmatter() + '\n# JasperVault Trading Skill\n\n' + SKILL_CORE_BODY;
+            break;
         case 'claude':
-            return getClaudeFrontmatter() + '\n# JasperVault Trading Skill\n\n' + SKILL_BODY_CONTENT;
+            skillMd = getClaudeFrontmatter() + '\n# JasperVault Trading Skill\n\n' + SKILL_CORE_BODY;
+            break;
         case 'cursor':
-            return '# jasper-vault-cli\n\n' + SKILL_BODY_CONTENT;
+            skillMd = '# jasper-vault-cli\n\n' + SKILL_CORE_BODY;
+            break;
         default:
             throw new Error(`Unknown platform: ${platform}`);
     }
+    return {
+        'SKILL.md': skillMd,
+        'references/onboarding.md': ONBOARDING_REFERENCE,
+        'references/trading.md': TRADING_REFERENCE,
+        'references/queries.md': QUERIES_REFERENCE,
+        'scripts/check-init.sh': CHECK_INIT_SCRIPT,
+    };
 }
 //# sourceMappingURL=skill-body.js.map

package/dist/src/templates/skill-body.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-body.js","sourceRoot":"","sources":["../../../src/templates/skill-body.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CACzC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,EAAE,OAAO,CAAC,CACzC,CAAC;AAEzB,sEAAsE;AACtE,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;wBAcE,WAAW;;CAElC,CAAC,IAAI,EAAE,CAAC;AAET,2EAA2E;AAC3E,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6T1B,CAAC,IAAI,EAAE,CAAC;AAET,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;CAWR,CAAC;AACF,CAAC;AAED,SAAS,oBAAoB;IAC3B,OAAO;;;;CAIR,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,sBAAsB,EAAE,GAAG,mCAAmC,GAAG,kBAAkB,CAAC;QAC7F,KAAK,QAAQ;YACX,OAAO,oBAAoB,EAAE,GAAG,mCAAmC,GAAG,kBAAkB,CAAC;QAC3F,KAAK,QAAQ;YACX,OAAO,wBAAwB,GAAG,kBAAkB,CAAC;QACvD;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;AACH,CAAC"}
+{"version":3,"file":"skill-body.js","sourceRoot":"","sources":["../../../src/templates/skill-body.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CACzC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,EAAE,OAAO,CAAC,CACzC,CAAC;AAEzB,sEAAsE;AACtE,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;wBAcE,WAAW;;CAElC,CAAC,IAAI,EAAE,CAAC;AAIT,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAE9E,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCvB,CAAC,IAAI,EAAE,CAAC;AAET,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD5B,CAAC;AAEF,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAE9E,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2IzB,CAAC;AAEF,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAE9E,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+HzB,CAAC;AAEF,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,iBAAiB,GAAG;;;;CAIzB,CAAC;AAEF,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,SAAS,sBAAsB;IAC7B,OAAO;;;;;;;;;;;CAWR,CAAC;AACF,CAAC;AAED,SAAS,oBAAoB;IAC3B,OAAO;;;;CAIR,CAAC;AACF,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,IAAI,OAAe,CAAC;IAEpB,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,GAAG,sBAAsB,EAAE,GAAG,mCAAmC,GAAG,eAAe,CAAC;YAC3F,MAAM;QACR,KAAK,QAAQ;YACX,OAAO,GAAG,oBAAoB,EAAE,GAAG,mCAAmC,GAAG,eAAe,CAAC;YACzF,MAAM;QACR,KAAK,QAAQ;YACX,OAAO,GAAG,wBAAwB,GAAG,eAAe,CAAC;YACrD,MAAM;QACR;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,OAAO;QACL,UAAU,EAAE,OAAO;QACnB,0BAA0B,EAAE,oBAAoB;QAChD,uBAAuB,EAAE,iBAAiB;QAC1C,uBAAuB,EAAE,iBAAiB;QAC1C,uBAAuB,EAAE,iBAAiB;KAC3C,CAAC;AACJ,CAAC"}

package/dist/src/types.d.ts

@@ -38,6 +38,8 @@ export interface OrderIntentParams {
     network?: string;
     ttlSeconds?: number;
     orderID?: number;
+    /** 0 = Normal (no PPO), 1 = PPO (hedge option protection) */
+    limitType?: number;
 }
 export interface TpSlIntentParams {
     orderID: number;