superacli 1.1.0 → 1.1.2

package/ref-btcbot/docs/skills/btcbot.orders/SKILL.md

@@ -1,60 +0,0 @@
----
-skill_name: btcbot.orders
-description: List recent paper orders with realized PnL
-tags: btc, trading, hedging, paper, bot, orders, dcli
-category: analytical
----
-
-# View Orders
-
-**When to use:** To review recent paper trades, realized PnL, and the reasons behind each hedge action.
-
-**Command:**
-```bash
-dcli btcbot orders list --json
-```
-
-**Interpret output:**
-- `orders`: array of recent paper orders (newest first)
-- Each order includes:
-  - `id`: unique order identifier
-  - `ts`: execution timestamp
-  - `mode`: always "paper" in v1
-  - `side`: "buy" or "sell"
-  - `qty`: absolute quantity traded
-  - `price`: execution price
-  - `realizedPnl`: realized PnL from any position reduction
-  - `perpQtyAfter`: perp quantity after the order
-  - `avgPerpEntryAfter`: new average entry price
-  - `reasons`: list of signal rationales that triggered the order
-
-**Example snippet:**
-```json
-{
-  "data": {
-    "orders": [
-      {
-        "id": "ord_1773011255993",
-        "ts": "2026-03-08T23:07:35.993Z",
-        "mode": "paper",
-        "side": "sell",
-        "qty": 0.062516,
-        "price": 66294.25,
-        "realizedPnl": 0,
-        "perpQtyAfter": -0.062516,
-        "avgPerpEntryAfter": 66294.25,
-        "reasons": [
-          "moderate_realized_vol",
-          "mean_reversion_neutral",
-          "downtrend_requires_more_hedge"
-        ]
-      }
-    ]
-  }
-}
-```
-
-**Follow-up skills:**
-- `btcbot.positions` to see current position after these orders
-- `btcbot.status` for overall state
-- `btcbot.run-once` to generate new orders if needed

package/ref-btcbot/docs/skills/btcbot.positions/SKILL.md

@@ -1,54 +0,0 @@
----
-skill_name: btcbot.positions
-description: List current spot and perp positions with mark-to-market
-tags: btc, trading, hedging, paper, bot, positions, dcli
-category: analytical
----
-
-# View Positions
-
-**When to use:** To inspect current spot inventory, perp hedge, and mark-to-market valuations.
-
-**Command:**
-```bash
-dcli btcbot positions list --json
-```
-
-**Interpret output:**
-- `position.spotQty`: configured spot BTC inventory (always positive)
-- `position.perpQty`: current perp position (negative = short hedge)
-- `position.avgPerpEntry`: average entry price of the perp position
-- `position.realizedPnl`: cumulative realized PnL from closed legs
-- `mark.spotValue`: spot inventory value in quote currency
-- `mark.perpUnrealized`: unrealized PnL of the perp position
-- `mark.netDeltaBtc`: net BTC exposure (spot + perp)
-- `mark.grossNotional`: gross notional exposure
-- `mark.equityEstimate`: total equity estimate
-
-**Example snippet:**
-```json
-{
-  "data": {
-    "position": {
-      "spotQty": 0.25,
-      "perpQty": -0.0625,
-      "avgPerpEntry": 66294.25,
-      "realizedPnl": 0
-    },
-    "snapshot": {
-      "mark": {
-        "spotValue": 16573.56,
-        "perpUnrealized": 0,
-        "netDeltaBtc": 0.1875,
-        "grossNotional": 20718.01,
-        "equityEstimate": 116573.56
-      }
-    }
-  }
-}
-```
-
-**Follow-up skills:**
-- `btcbot.status` for broader state context
-- `btcbot.orders` to see how the position was built
-- `btcbot.run-once` to update valuations

package/ref-btcbot/docs/skills/btcbot.risk/SKILL.md

@@ -1,69 +0,0 @@
----
-skill_name: btcbot.risk
-description: Show risk report including any cooldowns or violations
-tags: btc, trading, hedging, paper, bot, risk, dcli
-category: analytical
----
-
-# Risk Report
-
-**When to use:** To check if the bot is in a risk cooldown, has consecutive losses, or hit any notional limits.
-
-**Command:**
-```bash
-dcli btcbot risk report --json
-```
-
-**Interpret output:**
-- `risk`: latest risk evaluation from the most recent cycle
-  - `ok`: true if no risk violations
-  - `violations`: list of active risk blocks (empty if none)
-- `runtime`: bot runtime state
-  - `cooldownUntil`: timestamp when trading will resume (null if not cooling down)
-  - `consecutiveLosses`: count of consecutive losing trades
-  - `lastError`: last error that triggered a cooldown (if any)
-
-**Common violations:**
-- `cooldown_active`: bot is in a risk cooldown period
-- `signal_not_ready`: insufficient market history
-- `order_notional_limit`: order size exceeds MAX_NOTIONAL_PER_ORDER
-- `gross_notional_limit`: gross exposure would exceed MAX_GROSS_NOTIONAL
-
-**Example snippet (no issues):**
-```json
-{
-  "data": {
-    "risk": {
-      "ok": true,
-      "violations": []
-    },
-    "runtime": {
-      "cooldownUntil": null,
-      "consecutiveLosses": 0,
-      "lastError": null
-    }
-  }
-}
-```
-
-**Example snippet (in cooldown):**
-```json
-{
-  "data": {
-    "risk": {
-      "ok": false,
-      "violations": ["cooldown_active"]
-    },
-    "runtime": {
-      "cooldownUntil": "2026-03-09T00:15:00.000Z",
-      "consecutiveLosses": 2,
-      "lastError": "order_notional_limit"
-    }
-  }
-}
-```
-
-**Follow-up skills:**
-- `btcbot.status` to see when the cooldown ends
-- `btcbot.config` to review risk limits
-- `btcbot.run-once` after cooldown expires

package/ref-btcbot/docs/skills/btcbot.run-loop/SKILL.md

@@ -1,63 +0,0 @@
----
-skill_name: btcbot.run-loop
-description: Run a bounded loop with a small iteration count for testing
-tags: btc, trading, hedging, paper, bot, loop, dcli
-category: operational
----
-
-# Run Bounded Loop
-
-**When to use:** To simulate continuous operation over a few iterations while keeping execution time bounded. Default is 3 iterations.
-
-**Command:**
-```bash
-dcli btcbot run loop 5 --json
-```
-
-Replace `5` with your desired iteration count (1–10 recommended for testing).
-
-**Interpret output:**
-- `iterations`: number of cycles that ran
-- `last.signal`: signal from the final cycle
-- `last.order`: order from the final cycle (may be null if no rebalance)
-- `last.runtime.consecutiveLosses`: loss streak counter
-- `last.mark.equityEstimate`: equity after the final cycle
-
-**Example snippet:**
-```json
-{
-  "data": {
-    "ok": true,
-    "iterations": 3,
-    "last": {
-      "signal": {
-        "ready": true,
-        "price": 66242.4,
-        "hedgeRatio": 0.25,
-        "targetPerpBtc": -0.0625,
-        "deltaBtc": 0.000028,
-        "shouldRebalance": false,
-        "reasons": [
-          "moderate_realized_vol",
-          "mean_reversion_neutral",
-          "downtrend_requires_more_hedge"
-        ]
-      },
-      "order": null,
-      "runtime": {
-        "consecutiveLosses": 0,
-        "lastRunAt": "2026-03-08T23:12:25.477Z"
-      },
-      "mark": {
-        "equityEstimate": 116563.84,
-        "netDeltaBtc": 0.1875
-      }
-    }
-  }
-}
-```
-
-**Follow-up skills:**
-- `btcbot.status` for current state
-- `btcbot.orders` to see all orders from the loop
-- `btcbot.risk` if you expect cooldowns

package/ref-btcbot/docs/skills/btcbot.run-once/SKILL.md

@@ -1,63 +0,0 @@
----
-skill_name: btcbot.run-once
-description: Execute a single bot cycle and view the resulting signal/order
-tags: btc, trading, hedging, paper, bot, run, dcli
-category: operational
----
-
-# Run One Bot Cycle
-
-**When to use:** To fetch fresh market data, compute a hedge signal, and optionally execute a paper order in a single step.
-
-**Command:**
-```bash
-dcli btcbot run once --json
-```
-
-**Interpret output:**
-- `signal.ready`: true if enough market history is available
-- `signal.price`: latest BTC price from the 15m candle
-- `signal.hedgeRatio`: computed hedge ratio (0–1)
-- `signal.targetPerpBtc`: target perp position (negative = short hedge)
-- `signal.deltaBtc`: BTC quantity to trade to reach target
-- `signal.shouldRebalance`: true if delta exceeds rebalance threshold
-- `signal.reasons`: list of signal rationales
-- `order`: populated only if a trade was executed
-- `risk.violations`: empty if trade is allowed; otherwise lists blocked reasons
-
-**Example snippet:**
-```json
-{
-  "data": {
-    "signal": {
-      "ready": true,
-      "price": 66294.25,
-      "hedgeRatio": 0.25,
-      "targetPerpBtc": -0.0625,
-      "deltaBtc": -0.0625,
-      "shouldRebalance": true,
-      "reasons": [
-        "moderate_realized_vol",
-        "mean_reversion_neutral",
-        "downtrend_requires_more_hedge"
-      ]
-    },
-    "order": {
-      "side": "sell",
-      "qty": 0.0625,
-      "price": 66294.25,
-      "realizedPnl": 0,
-      "perpQtyAfter": -0.0625
-    },
-    "risk": {
-      "ok": true,
-      "violations": []
-    }
-  }
-}
-```
-
-**Follow-up skills:**
-- `btcbot.status` to see updated position
-- `btcbot.orders` to view the executed order
-- `btcbot.run-loop` to run multiple cycles

package/ref-btcbot/docs/skills/btcbot.status/SKILL.md

@@ -1,59 +0,0 @@
----
-skill_name: btcbot.status
-description: Show current bot state, position, last signal, and risk status
-tags: btc, trading, hedging, paper, bot, status, dcli
-category: operational
----
-
-# Bot Status Check
-
-**When to use:** Before any bot interaction to understand current state, position, and whether the bot is in cooldown.
-
-**Command:**
-```bash
-dcli btcbot status show --json
-```
-
-**Interpret output:**
-- `state.mode`: always "paper" in v1
-- `state.position.spotQty`: your configured spot BTC inventory
-- `state.position.perpQty`: current perp hedge (negative = short hedge)
-- `state.runtime.lastRunAt`: timestamp of last cycle
-- `state.runtime.cooldownUntil`: if set, bot will not trade until this time
-- `snapshot.mark.equityEstimate`: total equity including unrealized PnL
-- `snapshot.mark.netDeltaBtc`: net BTC exposure (spot + perp)
-- `snapshot.signal.hedgeRatio`: current hedge ratio (0–1)
-
-**Example snippet:**
-```json
-{
-  "data": {
-    "state": {
-      "mode": "paper",
-      "position": {
-        "spotQty": 0.25,
-        "perpQty": -0.0625,
-        "realizedPnl": 0
-      },
-      "runtime": {
-        "lastRunAt": "2026-03-08T23:07:35.994Z",
-        "cooldownUntil": null
-      }
-    },
-    "snapshot": {
-      "mark": {
-        "equityEstimate": 116573.56,
-        "netDeltaBtc": 0.1875
-      },
-      "signal": {
-        "hedgeRatio": 0.25
-      }
-    }
-  }
-}
-```
-
-**Follow-up skills:**
-- `btcbot.run-once` if no recent run
-- `btcbot.risk` if cooldown is active
-- `btcbot.positions` for detailed position view

package/ref-btcbot/examples/sample-candles.json

@@ -1,52 +0,0 @@
-[
-  {"open":43000,"high":43110,"low":42940,"close":43080},
-  {"open":43080,"high":43220,"low":43010,"close":43190},
-  {"open":43190,"high":43310,"low":43110,"close":43280},
-  {"open":43280,"high":43360,"low":43190,"close":43210},
-  {"open":43210,"high":43300,"low":43150,"close":43260},
-  {"open":43260,"high":43450,"low":43210,"close":43410},
-  {"open":43410,"high":43520,"low":43320,"close":43470},
-  {"open":43470,"high":43500,"low":43310,"close":43360},
-  {"open":43360,"high":43420,"low":43240,"close":43300},
-  {"open":43300,"high":43480,"low":43260,"close":43440},
-  {"open":43440,"high":43540,"low":43380,"close":43490},
-  {"open":43490,"high":43620,"low":43400,"close":43580},
-  {"open":43580,"high":43710,"low":43520,"close":43690},
-  {"open":43690,"high":43760,"low":43590,"close":43620},
-  {"open":43620,"high":43740,"low":43580,"close":43680},
-  {"open":43680,"high":43850,"low":43610,"close":43810},
-  {"open":43810,"high":43920,"low":43710,"close":43890},
-  {"open":43890,"high":44010,"low":43820,"close":43970},
-  {"open":43970,"high":44030,"low":43880,"close":43920},
-  {"open":43920,"high":44080,"low":43890,"close":44010},
-  {"open":44010,"high":44210,"low":43980,"close":44180},
-  {"open":44180,"high":44320,"low":44100,"close":44290},
-  {"open":44290,"high":44410,"low":44220,"close":44380},
-  {"open":44380,"high":44430,"low":44240,"close":44270},
-  {"open":44270,"high":44320,"low":44160,"close":44210},
-  {"open":44210,"high":44350,"low":44190,"close":44300},
-  {"open":44300,"high":44470,"low":44220,"close":44410},
-  {"open":44410,"high":44520,"low":44310,"close":44480},
-  {"open":44480,"high":44610,"low":44420,"close":44570},
-  {"open":44570,"high":44630,"low":44490,"close":44520},
-  {"open":44520,"high":44600,"low":44410,"close":44460},
-  {"open":44460,"high":44520,"low":44330,"close":44390},
-  {"open":44390,"high":44460,"low":44280,"close":44310},
-  {"open":44310,"high":44420,"low":44250,"close":44370},
-  {"open":44370,"high":44510,"low":44310,"close":44490},
-  {"open":44490,"high":44640,"low":44450,"close":44590},
-  {"open":44590,"high":44710,"low":44520,"close":44680},
-  {"open":44680,"high":44820,"low":44600,"close":44790},
-  {"open":44790,"high":44910,"low":44720,"close":44880},
-  {"open":44880,"high":45010,"low":44810,"close":44970},
-  {"open":44970,"high":45120,"low":44910,"close":45080},
-  {"open":45080,"high":45240,"low":45010,"close":45190},
-  {"open":45190,"high":45310,"low":45120,"close":45280},
-  {"open":45280,"high":45420,"low":45210,"close":45390},
-  {"open":45390,"high":45510,"low":45320,"close":45470},
-  {"open":45470,"high":45600,"low":45420,"close":45580},
-  {"open":45580,"high":45650,"low":45460,"close":45510},
-  {"open":45510,"high":45620,"low":45420,"close":45440},
-  {"open":45440,"high":45510,"low":45360,"close":45490},
-  {"open":45490,"high":45610,"low":45440,"close":45570}
-]

package/ref-btcbot/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "ref-btcbot",
-  "version": "0.1.0",
-  "description": "Standalone 15m BTC hedging bot with dcli plugin integration",
-  "main": "src/web/server.js",
-  "type": "commonjs",
-  "scripts": {
-    "start": "node src/cli.js server",
-    "bot:once": "node src/cli.js run once",
-    "bot:loop": "node src/cli.js run loop",
-    "backtest": "node src/cli.js backtest run",
-    "validate": "node src/cli.js config validate"
-  },
-  "dependencies": {
-    "dotenv": "^17.3.1",
-    "express": "^4.18.2"
-  }
-}

package/ref-btcbot/plugin/plugin.json

@@ -1,146 +0,0 @@
-{
-  "name": "btcbot",
-  "version": "0.1.0",
-  "description": "Operate the ref-btcbot 15m BTC hedging bot through dcli",
-  "source": "local://ref-btcbot",
-  "tags": ["btc", "trading", "hedging", "paper", "bot"],
-  "checks": [
-    { "type": "binary", "name": "node" }
-  ],
-  "commands": [
-    {
-      "namespace": "btcbot",
-      "resource": "status",
-      "action": "show",
-      "description": "Show bot status",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "status", "show"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": []
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "run",
-      "action": "once",
-      "description": "Run one bot cycle",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "run", "once"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": []
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "run",
-      "action": "loop",
-      "description": "Run a bounded bot loop",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "run", "loop"],
-        "positionalArgs": ["iterations"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": [
-        { "name": "iterations", "type": "string", "required": false }
-      ]
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "backtest",
-      "action": "run",
-      "description": "Run a local backtest from a candle JSON file",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "backtest", "run"],
-        "positionalArgs": ["file"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": [
-        { "name": "file", "type": "string", "required": true }
-      ]
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "positions",
-      "action": "list",
-      "description": "List current bot position",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "positions", "list"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": []
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "orders",
-      "action": "list",
-      "description": "List bot orders",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "orders", "list"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": []
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "risk",
-      "action": "report",
-      "description": "Show latest risk report",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "risk", "report"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": []
-    },
-    {
-      "namespace": "btcbot",
-      "resource": "config",
-      "action": "validate",
-      "description": "Validate bot config",
-      "adapter": "process",
-      "adapterConfig": {
-        "command": "node",
-        "cwd": "/home/jarancibia/ai/dcli/ref-btcbot",
-        "baseArgs": ["src/cli.js", "config", "validate"],
-        "parseJson": true,
-        "timeout_ms": 15000,
-        "missingDependencyHelp": "Install Node.js and run node --version"
-      },
-      "args": []
-    }
-  ]
-}