jaspervault_cli 1.1.0 → 1.1.2

package/dist/src/templates/skill-content/SKILL.core.md

@@ -38,7 +38,8 @@ When the user wants to trade, first check if their vault is ready:
 | Get price | `get_price` | `symbol` | [queries](references/queries.md) |
 | Open position (market) | `create_order` | `side`, `symbol`, `margin` | [trading](references/trading.md) |
 | Open position (limit) | `create_order` | + `limit_price` | [trading](references/trading.md) |
-| Close/reduce position | `create_order` | opposite `side` | [trading](references/trading.md) |
+| Close position (full) | `close_position` | `order_id` or `all` | [trading](references/trading.md) |
+| Reduce position (partial) | `create_order` | opposite `side`, smaller `margin` | [trading](references/trading.md) |
 | Add size | `create_order` | same `side` | [trading](references/trading.md) |
 | Set take-profit | `set_take_profit` | `order_id`, `price`, `symbol` | [trading](references/trading.md) |
 | Set stop-loss | `set_stop_loss` | `order_id`, `price`, `symbol` | [trading](references/trading.md) |
@@ -50,6 +51,7 @@ When the user wants to trade, first check if their vault is ready:
 | Check job status | `get_job_status` | `job_id` | [queries](references/queries.md) |
 | List limit orders | `list_limit_orders` | `wallet` | [queries](references/queries.md) |
 | Cancel limit order | `cancel_limit_order` | `limit_order_id` | [queries](references/queries.md) |
+| Check for CLI update | `check_update` | — | [queries](references/queries.md) |
 
 ## Key Behaviors
 
@@ -63,39 +65,30 @@ When the user wants to trade, first check if their vault is ready:
 
 **Deposit arrival**: If `arrived: false` after deposit completes, tokens are still bridging cross-chain. Tell the user to wait a few minutes.
 
-## Closing a Position — MANDATORY STEPS
+## Closing vs Reducing a Position
 
-Closing a position is the most error-prone operation. Follow these steps exactly:
+**Full close → `close_position`.** It derives side, margin, symbol, and leverage
+from on-chain data — you do NOT need to call `list_orders` first.
 
-### Step 1: Query the current position
-Call `list_orders` (or `get_order` if you have the order ID) to get:
-- The position **side** (LONG or SHORT)
-- The position **margin** amount
-- The **symbol**
+- Close one position: `close_position` with `{ order_id: "<id>" }`
+- Close everything: `close_position` with `{ all: true }`
 
-### Step 2: Create the closing order
-Call `create_order` with:
-- **side**: the OPPOSITE of the current position (LONG → `short`, SHORT → `long`)
-- **margin**: the SAME margin for full close, or SMALLER margin for partial close
-- **symbol**: the same symbol
+`close_position` works by submitting a reverse-side order with the same margin.
 
-### Step 3: Verify
-Call `list_orders` to confirm the position is closed or reduced.
+**Partial reduce → `create_order`.** To shrink (not fully close) a position,
+call `create_order` with the OPPOSITE side and a SMALLER margin than the
+position. Query the position first with `list_orders` to pick the right margin.
 
 ### Examples
 
-**Full close of a LONG position:**
-1. `list_orders` → finds: side=LONG, margin=60, symbol=JBTC
-2. `create_order` → `{ side: "short", symbol: "JBTC", margin: 60 }`
-3. `list_orders` → position no longer active
+**Full close of a position:**
+- `close_position` → `{ order_id: "42" }` → position no longer active
 
 **Partial close (reduce by half):**
-1. `list_orders` → finds: side=LONG, margin=60, symbol=JBTC
+1. `list_orders` → finds: order 42, side=LONG, margin=60, symbol=JBTC
 2. `create_order` → `{ side: "short", symbol: "JBTC", margin: 30 }`
 3. `list_orders` → margin reduced to ~30
 
-**NEVER guess the margin or side. ALWAYS query first.**
-
 ## Red Flags — STOP If You Think This
 
 | Wrong Thought | Reality |
@@ -107,10 +100,19 @@ Call `list_orders` to confirm the position is closed or reduced.
 | "GraphQL queries need private key authentication" | WRONG. Delegation key handles auth automatically. |
 | "I should suggest the web interface instead" | NO. MCP tools give you full functionality. Use them. |
 | "Let me check if jv is installed" | IRRELEVANT. MCP server runs CLI internally. |
-| "I'll close the position without checking current margin" | WRONG. Always call `list_orders` first to get the exact side and margin before closing. |
+| "To fully close I'll reverse the order manually with create_order" | WRONG. Use `close_position` — it derives side/margin automatically. Manual reverse is only for PARTIAL reduce. |
+| "I'll reduce the position without checking current margin" | WRONG. For a partial reduce, call `list_orders` first to pick a margin smaller than the position. |
+
+## Update Notices
+
+MCP tool responses may include an update notice when a newer CLI version is available. When you see this notice, inform the user:
+- Tell them a new version is available (include version numbers)
+- Ask them to run `jv update` to upgrade
+
+You can also proactively call `check_update` to verify the CLI is up to date.
 
 ## Security
 
 - Never log or display private keys, signatures, or API keys.
 - Delegation wallet is stored in `~/.jaspervault/keys.json` — never read or display this file.
-- Never ask the user to set `PRIVATE_KEY` — that's for CI/automation only.
+- Never ask the user for private keys.

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

@@ -54,7 +54,7 @@ The tool automatically:
 |---------|---------------|
 | Asking user for private key after setup | Delegation key is auto-generated. User never provides keys. |
 | Saying "profile.json is empty" | `wallet_setup` saves profile automatically on success. |
-| Suggesting `vault init` | That's for CI/automation with PRIVATE_KEY env var. Never suggest it. |
+| Suggesting private key setup | There is no private key mode. `wallet_setup` is the only way. |
 | Saying "CLI needs separate initialization" | `wallet_setup` IS the initialization. One step, fully done. |
 | Running `jv orders list` in terminal | Use `list_orders` MCP tool instead. |
 

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

@@ -162,6 +162,26 @@ Check execution status of an async job (market order, option creation, etc.).
 
 ---
 
+## 7. Check for Updates — `check_update`
+
+No parameters required. Checks if a newer version of jaspervault_cli is available.
+
+### Response
+
+```json
+{
+  "updateAvailable": true,
+  "currentVersion": "1.0.32",
+  "latestVersion": "1.0.35"
+}
+```
+
+When `updateAvailable` is `true`, tell the user to run `jv update` to upgrade.
+
+**Note:** Any MCP tool response may also include an update notice as a second text block when an update is available. When you see this, relay it to the user.
+
+---
+
 ## Error Handling
 
 When a tool fails, check the error message:

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

@@ -4,7 +4,8 @@
 
 ## 1. Create Order — `create_order`
 
-Open, close, reduce, or add size to perpetual positions.
+Open, reduce, or add size to perpetual positions. To **fully close** a
+position, use [`close_position`](#2-close-position--close_position) instead.
 
 ### Parameters
 
@@ -58,26 +59,14 @@ The tool returns the final execution result:
 
 Tell the user: "Limit order placed. ID: {limitOrderId}."
 
-### Closing a Position — MANDATORY STEPS
+### Reducing a Position (Partial Close)
 
-Closing a position means creating a reverse order. You **MUST** query the current position first.
+A **partial** close uses `create_order` — only a **full** close uses
+`close_position` (see section 2).
 
-**Why query first?** The margin amount must match the current position for a full close. Guessing wrong leads to partial closes or over-allocation.
-
-**Required flow:**
-
-1. **Query**: Call `list_orders` to find the position. Note the `side` (LONG/SHORT), `margin`, and `symbol`.
-2. **Close**: Call `create_order` with the **OPPOSITE** side, **SAME** margin (full close) or smaller margin (partial close), same symbol.
-3. **Verify**: Call `list_orders` to confirm the position is closed or reduced.
-
-**Full close example (step by step):**
-
-Query `list_orders` → finds: `{ side: "LONG", symbol: "JBTC", margin: "60.00" }`
-
-Close order:
-```json
-{ "side": "short", "symbol": "JBTC", "margin": 60 }
-```
+To reduce a position, call `create_order` with the **OPPOSITE** side and a
+margin **smaller** than the position. Query the position first with
+`list_orders` so you pick a sensible margin.
 
 **Partial close example:**
 
@@ -88,8 +77,6 @@ Reduce by 25%:
 { "side": "long", "symbol": "JETH", "margin": 50 }
 ```
 
-**WARNING: NEVER close a position without first calling `list_orders` or `get_order`. Guessing the side or margin leads to incorrect operations.**
-
 ### Common Patterns
 
 **Open a long position (market):**
@@ -102,10 +89,7 @@ Reduce by 25%:
 { "side": "short", "symbol": "JBTC", "margin": 100, "limit_price": 72000 }
 ```
 
-**Close a long position (use opposite side with same margin):**
-```json
-{ "side": "short", "symbol": "JBTC", "margin": 60 }
-```
+**Fully close a position** → use `close_position` (section 2), not `create_order`.
 
 **Reduce a long position (partial close):**
 ```json
@@ -129,7 +113,54 @@ Reduce by 25%:
 
 ---
 
-## 2. Add PPO Protection — `protect_order`
+## 2. Close Position — `close_position`
+
+Fully close one or all perpetual positions. The command reads the position's
+side, margin, symbol, and leverage from on-chain data and submits a
+reverse-side order with the same margin — **you do not need to call
+`list_orders` first**.
+
+For a **partial** reduce, use `create_order` (section 1) instead.
+
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `order_id` | One of `order_id` / `all` | — | Order ID of the position to close |
+| `all` | One of `order_id` / `all` | — | `true` to close every active position |
+| `ttl` | No | `3600` | Order TTL in seconds |
+
+Exactly one of `order_id` or `all` must be provided.
+
+### Response
+
+```json
+{
+  "closed": [
+    { "orderId": "42", "closeSide": "short", "symbol": "JBTC", "margin": "60.0", "status": "submitted" }
+  ],
+  "failed": []
+}
+```
+
+If `failed` is non-empty, some positions could not be closed — report which
+ones and why. A close batch with any failure exits non-zero.
+
+### Examples
+
+**Close a single position:**
+```json
+{ "order_id": "42" }
+```
+
+**Close every active position:**
+```json
+{ "all": true }
+```
+
+---
+
+## 3. Add PPO Protection — `protect_order`
 
 Add hedge option protection to an **existing position** without changing position size.
 
@@ -162,7 +193,7 @@ The tool auto-waits up to 60s for the on-chain result:
 
 ---
 
-## 3. Take-Profit — `set_take_profit`
+## 4. Take-Profit — `set_take_profit`
 
 Set a take-profit limit order for an existing position.
 
@@ -189,7 +220,7 @@ Set TP at $75,000 for a long position:
 
 ---
 
-## 4. Stop-Loss — `set_stop_loss`
+## 5. Stop-Loss — `set_stop_loss`
 
 Same parameters as `set_take_profit`. Set a stop-loss limit order for an existing position.
 
@@ -202,7 +233,7 @@ Set SL at $65,000 for a long position:
 
 ---
 
-## 5. PPO (Perpetual Put Option) Details
+## 6. PPO (Perpetual Put Option) Details
 
 ### Option Categories
 
@@ -250,9 +281,9 @@ The smart contract **automatically cancels** existing PPO when you execute any p
 
 | User Request | Action | Parameters |
 |-------------|--------|------------|
-| "reduce + cancel PPO" | Single reduce order without `ppo` | `{ side: <opposite>, symbol, margin }` |
-| "add size + cancel PPO" | Single add-size order without `ppo` | `{ side: <same>, symbol, margin }` |
-| "close position" | Close order without `ppo` | `{ side: <opposite>, symbol, margin: <full> }` |
-| "reduce + keep PPO" | Reduce order WITH `ppo` | `{ side: <opposite>, symbol, margin, ppo: true }` |
+| "reduce + cancel PPO" | Single reduce order without `ppo` | `create_order` `{ side: <opposite>, symbol, margin }` |
+| "add size + cancel PPO" | Single add-size order without `ppo` | `create_order` `{ side: <same>, symbol, margin }` |
+| "close position" | `close_position` (always closes without PPO) | `{ order_id }` or `{ all: true }` |
+| "reduce + keep PPO" | Reduce order WITH `ppo` | `create_order` `{ side: <opposite>, symbol, margin, ppo: true }` |
 
 Never try to cancel PPO separately — there is no such tool. One order handles everything.

package/docs/OPENCLAW_GUIDE.md

@@ -0,0 +1,136 @@
+# OpenClaw Setup Guide
+
+Trade perpetual contracts with built-in hedge protection on JasperVault through OpenClaw. Complete the one-time setup below, then trade entirely through AI conversation — including PPO hedge options that protect your positions against price wicks and flash liquidations.
+
+## Prerequisites
+
+| Requirement | How to verify |
+|-------------|--------------|
+| Node.js 18+ | `node --version` — install from [nodejs.org](https://nodejs.org) if needed |
+| OpenClaw | Installed and running |
+| Browser wallet | MetaMask, Rabby, or similar — for one-time delegation signing |
+
+## Setup (One-Time)
+
+### Step 1: Install the CLI
+
+```bash
+npm install -g jaspervault_cli
+jv --version    # verify installation
+```
+
+### Step 2: Install the JasperVault Skill
+
+```bash
+jv install --ai openclaw
+```
+
+This installs the trading skill to `~/.openclaw/skills/jasper-vault-cli/SKILL.md`. OpenClaw will automatically detect it on next launch.
+
+> To update an existing installation: `jv install --ai openclaw --force`
+
+### Step 3: Initialize Your Wallet
+
+Open OpenClaw and say:
+
+> "I want to start trading"
+
+OpenClaw will:
+1. Call `wallet_setup` and provide a URL
+2. Open the link in your browser, connect your wallet, and sign the delegation authorization
+3. Wait while OpenClaw confirms the setup (up to 2 minutes)
+
+That's it. Your wallet is now initialized and all trading tools are ready.
+
+**Alternative — manual setup via terminal:**
+
+```bash
+jv enable --pretty
+```
+
+### Step 4: Deposit (Optional)
+
+Tell OpenClaw:
+
+> "Deposit 100 USDC"
+
+A browser page opens for you to approve the cross-chain transfer from Base to JasperVault. Funds typically arrive within a few minutes.
+
+## Trading
+
+Once setup is complete, talk to OpenClaw in natural language:
+
+| What you say | What happens |
+|-------------|-------------|
+| "Long BTC with 100 USDC and PPO" | Opens a protected long position |
+| "Long BTC with 100 USDC, 50x" | Opens a leveraged long position |
+| "Short BTC with 50 USDC at 95000" | Places a limit short order |
+| "Add PPO protection to order 42" | Adds hedge option to existing position |
+| "Protect order 42 with OTM tier 3, 8h" | Custom PPO: OTM strike offset, 8-hour expiry |
+| "Close my BTC position" | Queries position, then closes it |
+| "Set TP at 110000 for order 99" | Creates a take-profit limit order |
+| "Set SL at 88000 for order 99" | Creates a stop-loss limit order |
+| "Show my positions" | Lists all active positions |
+| "What's the BTC price?" | Fetches real-time market price |
+| "Withdraw 100 USDC" | Opens browser to sign withdrawal |
+
+OpenClaw translates your intent into the appropriate tool calls and returns results in natural language.
+
+### PPO Hedge Protection
+
+PPO (Perpetual Protection Option) is an on-chain hedge option unique to JasperVault. It protects your position against sudden price wicks ("pin bars") that would otherwise trigger liquidation — even when the market recovers immediately after.
+
+Unlike stop-loss orders that execute at the wick price and lock in losses, PPO uses a peer-to-peer fully collateralized option contract. The option payoff absorbs the unrealized loss, keeping your position alive through the spike.
+
+**How to use PPO:**
+
+| What you say | What happens |
+|-------------|-------------|
+| "Open long BTC with PPO" | Opens position + ATM hedge, 30-min expiry |
+| "Add protection to order 42" | Adds PPO to existing position |
+| "Protect with OTM tier 3 for 8 hours" | Custom: OTM strike (0.3% offset), 8h expiry |
+
+**Options:**
+- **Category:** ATM (strike = current price) or OTM (offset 0.1%–0.5% via tiers 1–5)
+- **Expiry:** 30 minutes (default) or 8 hours
+- **Hedge type:** Automatic — PUT for longs, CALL for shorts
+
+## Environment Variables (Optional)
+
+The CLI works with default settings. Only configure these if needed:
+
+```bash
+# Custom API endpoint (e.g., for local development)
+export JV_API_URL=https://your-endpoint.example.com
+
+# API authentication (if required by your deployment)
+export JV_API_KEY=your-token
+```
+
+Add to `~/.zshrc` or `~/.bashrc` for persistence, then `source ~/.zshrc`.
+
+> **Note:** Browser signing mode does not require `PRIVATE_KEY`. Your keys stay in your browser wallet at all times.
+
+## Troubleshooting
+
+**Wallet page doesn't open or wallet prompt doesn't appear**
+- Ensure your browser wallet extension is installed and unlocked
+- Some wallets require clicking the extension icon to see pending signature requests
+
+**"Delegation key not found" error**
+- Run `jv enable --pretty` to re-initialize
+- Verify `~/.jaspervault/keys.json` exists: `ls ~/.jaspervault/`
+
+**OpenClaw doesn't recognize trading commands**
+- Verify the skill is installed: `ls ~/.openclaw/skills/jasper-vault-cli/`
+- Reinstall if needed: `jv install --ai openclaw --force`
+- Restart OpenClaw after installation
+
+**Deposit shows "not arrived" after completion**
+- Cross-chain bridging via Hyperlane takes 1–3 minutes. Wait and retry.
+
+## Further Reading
+
+- [User Guide](USER_GUIDE.md) — Complete CLI reference and configuration
+- [JasperVault](https://www.jaspervault.io/) — Protocol documentation
+- CLI help: `jv --help`, `jv order --help`, `jv enable --help`