jaspervault_cli 1.0.28 → 1.0.30

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

@@ -1,29 +1,24 @@
 # Queries Reference
 
-## 1. List Positions (`jv orders list`)
+> All tools below are MCP tools. Call them directly — never run `jv` shell commands.
+> These tools require no setup beyond `wallet_setup`. No private keys, no environment variables.
 
-Query active or historical positions from the Subgraph.
+## 1. List Positions — `list_orders`
 
-### Syntax
+Query active or historical positions.
 
-```
-jv orders list [options]
-```
+### Parameters
 
-### Options
+| 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 |
 
-| 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`)
+### Time Formats for `since` / `until`
 
 | Format | Example | Description |
 |--------|---------|-------------|
@@ -33,21 +28,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 +50,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 +108,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.).
+## 5. Job Status — `get_job_status`
 
-### Syntax
+Check execution status of an async job (market order, option creation, etc.).
 
-```
-jv job status <jobId> [options]
-```
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `job_id` | Yes | Job ID from market order creation |
 
-### 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:
+### Response
 
 ```json
 {
@@ -224,71 +135,43 @@ 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]
-```
-
-| 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.
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `wallet` | Yes | Wallet address |
+| `status` | No | Filter: `PENDING`, `TRIGGERED`, `EXECUTING`, `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED` |
 
-### Cancel Limit Order
+### Get Limit Order Status — `get_limit_order_status`
 
-```
-jv limit-order cancel <id> [--pretty]
-```
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `limit_order_id` | Yes | Limit order ID |
 
-Cancel a pending limit order by its ID.
-
-### Examples
+### Cancel Limit Order — `cancel_limit_order`
 
-```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
+## Error Handling
 
-All CLI commands use consistent exit codes:
+When a tool fails, check the error message:
 
-| 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 Pattern | Meaning | Action |
+|--------------|---------|--------|
+| "delegation key not found" | Vault not initialized | Call `wallet_setup` |
+| "vault not initialized" | Vault not initialized | Call `wallet_setup` |
+| "no profile" / "profile not found" | Vault not initialized | Call `wallet_setup` |
+| "delegation expired" | Key expired (1 week limit) | Call `wallet_setup` again |
+| Network/timeout errors | Transient issue | Retry the tool call |
 
-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`.
+**NEVER respond to these errors by asking for private keys or suggesting environment variables.** The answer is always `wallet_setup`.