@kaleidorg/mind 0.9.0 → 0.10.0

package/skills/bitrefill/SKILL.md

@@ -1,166 +1,39 @@
 ---
 name: bitrefill
-description: "Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, and eSIMs across 180+ countries, payable in crypto, Lightning, USDC via x402, or pre-funded account balance. Use these tools to actually transact: bitrefill_search → bitrefill_get_product → bitrefill_create_invoice (spend, confirmed) → bitrefill_get_invoice/bitrefill_get_order for the redemption code."
-tools: bitrefill_search, bitrefill_get_product, bitrefill_get_balance, bitrefill_create_invoice, bitrefill_get_invoice, bitrefill_get_order, spark_pay_invoice, spark_get_balance, rln_pay_invoice
-triggers: bitrefill, gift card, gift cards, giftcard, voucher, vouchers, top-up, topup, top up, refill, esim, e-sim, mobile plan, mobile top-up, prepaid, amazon, steam, google play, app store, itunes, playstation, xbox, netflix, spotify, uber
-compatibility: "Live REST adapter on the CLI/desktop when BITREFILL_API_KEY (Personal) or BITREFILL_API_ID + BITREFILL_API_SECRET (Business) are set. Without those env vars the tools aren't registered — tell the user and stop."
+description: "Buy gift cards, mobile top-ups and eSIMs on Bitrefill (1,500+ brands, 180+ countries), paid from the Bitrefill balance or over Lightning: search, pick a package, create the invoice, read the redemption code."
+tools: bitrefill_search, bitrefill_get_product, bitrefill_get_balance, bitrefill_create_invoice, bitrefill_get_invoice, bitrefill_get_order, spark_pay_invoice, rln_pay_invoice
+requires-tools: bitrefill_search
+triggers: bitrefill, gift card, gift cards, giftcard, voucher, top-up, topup, top up, esim, e-sim, mobile plan, prepaid, amazon, steam, google play, app store, itunes, playstation, xbox, netflix, spotify, uber
+compatibility: "Needs BITREFILL_API_KEY (Personal) or BITREFILL_API_ID + BITREFILL_API_SECRET (Business); without them the tools are not registered."
 metadata:
   author: bitrefill
-  version: "3.0.0"
+  version: "3.1.0"
   homepage: "https://www.bitrefill.com"
   docs: "https://docs.bitrefill.com"
-  repository: "https://github.com/bitrefill/cli"
+  repository: "https://github.com/bitrefill/agents"
 ---
-
 # Bitrefill
 
-Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+
-countries. Codes deliver instantly after the invoice settles.
-
-This skill is **action-shaped**: when the host has the `bitrefill_*` tools
-wired, you transact through them directly. Don't navigate browser / MCP / CLI
-fallbacks unless the tools are absent.
-
-## Critical rules (read first)
-
-1. **Never invent product or package ids.** Every `product_id` and
-   `package_id` MUST come from a `bitrefill_search` + `bitrefill_get_product`
-   result in the current turn.
-2. **Confirm before spending.** `bitrefill_create_invoice` is the spend — it
-   is automatically confirmation-gated by the host. Before calling it, show
-   the user product, denomination, total price, and payment method in plain
-   English, then call the tool. The host will fire one confirmation; on
-   approve, the invoice is created.
-3. **Codes are cash.** When you read `redemption_info.code` from
-   `bitrefill_get_order`, return it once, advise the user to store it
-   securely, and **never** repeat it in summaries or future turns.
-4. **No tools wired = no purchase.** If `bitrefill_search` isn't available
-   in this session (no API key configured), say so directly: *"Bitrefill
-   purchases need a `BITREFILL_API_KEY` env var. Set one and restart, or
-   browse <https://www.bitrefill.com> directly."* Don't fall back to
-   inventing products.
-
-## Happy-path playbook
-
-For a typical buy ("a $25 Amazon US gift card with my balance"):
-
-1. **`bitrefill_search({ query, country? })`** — find candidate products.
-   - "amazon" → `{ query: "amazon", country: "US" }` if the user named a
-     country, else just `{ query: "amazon" }`.
-   - Returns a list of `{ id, name, country, category }` rows. Pick the one
-     that matches the user's intent. If multiple plausible matches, ask the
-     user once instead of guessing.
-
-2. **`bitrefill_get_product({ product_id })`** — read the `packages` array
-   for the right denomination. Each package has `{ id, value, price,
-   currency }`. **The `package_id` is what you pass to create_invoice**, NOT
-   the bare `value`.
-
-3. **`bitrefill_get_balance()`** *(optional)* — when the user said "with my
-   balance" or asked "can I afford it", verify the account has enough
-   before creating the invoice. Skip when paying with Lightning / on-chain.
-
-4. **`bitrefill_create_invoice({ products, payment_method, ... })`** —
-   confirmation-gated spend. Choose `payment_method` per the user's request:
-   - `"balance"` + `auto_pay: true` — instant settlement from account
-     balance. **Default** when the user says "with my balance" or doesn't
-     specify and balance is sufficient.
-   - `"lightning"` — fastest crypto path. Response carries a BOLT11
-     invoice the user pays out-of-band (see step 5b — Spark, if connected,
-     pays it directly). **Requires `refund_address`** in case it expires.
-   - `"bitcoin"`, `"usdc_base"`, `"usdc_polygon"`, `"usdt_tron"`,
-     `"usdt_ethereum"` — same pattern, slower confirmation; also need
-     `refund_address`.
-
-   Line items: `products: [{ product_id, package_id, quantity }]`. Up to 20
-   per invoice.
-
-5. **Settlement.**
-
-   a. **`balance` + `auto_pay:true`** — the invoice is usually `complete`
-      on creation. Read its `order_id`(s) and skip to step 6.
-
-   b. **`lightning` with Spark connected** — the response includes a BOLT11
-      invoice (commonly under `payment.lightning_invoice`, surface whatever
-      field the host returns). Pay it with **`spark_pay_invoice({ invoice:
-      <bolt11> })`** — that's one extra confirmation gate, and Spark settles
-      it in seconds. (Same pattern if RLN is the user's Lightning layer:
-      use `rln_pay_invoice`.) Then `bitrefill_get_invoice` should already
-      report `paid` / `complete`.
-
-   c. **`lightning` or on-chain without an on-device wallet** — relay the
-      payment URI to the user and **poll** `bitrefill_get_invoice({
-      invoice_id })` until `status:"complete"`. Don't poll faster than
-      every ~5s; give up after a few minutes and hand the invoice id back
-      to the user to check later.
-
-6. **`bitrefill_get_order({ order_id })`** — read `redemption_info`:
-   - `.code` — the gift-card code or top-up PIN. The actual product.
-   - `.pin` — additional PIN for prepaid cards (often present alongside
-     the code).
-   - `.link` — brand redemption URL when applicable.
-   - `.instructions` — brand-specific redemption steps.
-
-   Present the code in the chat ONCE, then tell the user to store it and
-   redeem ASAP. Don't echo it in subsequent replies, summaries, or memory.
-
-## Choosing a payment method
-
-| Method | Speed | Blast radius | Use when |
-|---|---|---|---|
-| `balance` + `auto_pay:true` | Instant | Capped at account balance | Default. User pre-funded the account; lowest risk. |
-| `lightning` | Seconds | Whatever's in the user's LN wallet | User asks for "pay with Lightning" or wants no pre-funding. |
-| `bitcoin` | 10–60 min | One on-chain UTXO | User asks for "pay on-chain" or invoice > Lightning capacity. |
-| `usdc_base` (x402) | Seconds | Agent USDC wallet balance | Agent has an x402-capable USDC wallet. |
-| Other on-chain (USDT/USDC variants) | Variable | One UTXO per network | User explicitly requested. |
-
-Default to `balance` when available; ask the user before switching to a
-crypto method.
-
-## Failure handling
-
-Tool errors surface as thrown messages like `"bitrefill bitrefill_create_invoice failed: HTTP 401 ..."`. Relay them as plain English:
-
-- **401 Unauthorized** — `BITREFILL_API_KEY` is unset or wrong. Tell the
-  user; don't retry.
-- **400 / validation errors** — usually a bad `package_id` or
-  `payment_method`. Re-read the product's `packages` array and retry once,
-  then stop and ask.
-- **402 Payment Required** (with `balance`) — account underfunded. Show
-  the deficit; suggest topping up or switching payment method.
-- **Invoice `expired`** — re-create the invoice; an old quote isn't
-  reusable.
-
-## Reply style
-
-- Show the candidate product list as a short bulleted list (≤5 rows).
-- Before the spend, summarize in one line:
-  `Buying: 1× Amazon US $25 — total $25.00 USD, paying with balance. Confirm?`
-- After settlement: one line on success, then the redemption details on a
-  separate line so the user can copy the code.
-- After delivering the code, suggest redeeming ASAP and do NOT repeat the
-  code in later turns.
-
-## References (deep-dive, on demand)
-
-The references below cover paths and host hardening — they're for hosts
-that **don't** have the `bitrefill_*` tools wired (browser-only,
-MCP-capable client, npm CLI, raw REST). When the tools above are
-available, you don't need to read them.
-
-| File | When |
-|------|------|
-| [api.md](references/api.md) | Mapping the contract tools back to raw REST endpoints. |
-| [mcp.md](references/mcp.md) | Host has the Bitrefill remote MCP wired instead of the contract. |
-| [cli.md](references/cli.md) | `@bitrefill/cli` npm path (auth-bound). |
-| [cli-headless-auth.md](references/cli-headless-auth.md) | Magic-link auth via an agent inbox. |
-| [browse.md](references/browse.md) | Browser-only hosts. |
-| [host-openclaw.md](references/host-openclaw.md) | OpenClaw-specific path. |
-| [capability-matrix.md](references/capability-matrix.md) | Per-client cheat sheet. |
-| [safeguards.md](references/safeguards.md) | Spending policy + per-host hardening. |
-| [troubleshooting.md](references/troubleshooting.md) | Common errors. |
-
-## Source of truth
-
-Skill describes the contract + playbook. For exhaustive enums (countries,
-payment methods, full endpoint list), see <https://docs.bitrefill.com>.
+Product and package ids come from `bitrefill_search` and
+`bitrefill_get_product` in this turn; never invent them.
+
+## Do
+1. `bitrefill_search` (`query`, optional `country`); if several products match, ask once.
+2. `bitrefill_get_product` (`product_id`); pick the package whose `value` matches
+   and use its `id` as `package_id`.
+3. Show product, value, total price and payment method, then
+   `bitrefill_create_invoice` (confirm-gated):
+   - default `payment_method: "balance"` with `auto_pay: true` (check
+     `bitrefill_get_balance` first);
+   - `"lightning"` needs `refund_address`; pay the returned BOLT11 with
+     `spark_pay_invoice` or `rln_pay_invoice`.
+4. Poll `bitrefill_get_invoice` until `complete`, then `bitrefill_get_order`.
+   Show `redemption_info.code` once and never repeat it.
+- 401 means the API key is missing or wrong: say so and stop.
+
+## Examples
+- "A $25 Amazon US gift card" → `bitrefill_search {"query":"amazon","country":"US"}`
+- "Show the packages" → `bitrefill_get_product {"product_id":"amazon-us"}`
+- "Buy it with my balance" → `bitrefill_create_invoice {"products":[{"product_id":"amazon-us","package_id":"<package id>","quantity":1}],"payment_method":"balance","auto_pay":true}`
+
+Hosts without these tools (remote MCP, CLI, browser): see `references/`.

package/skills/channel-manager/SKILL.md

@@ -1,59 +1,38 @@
 ---
 name: channel-manager
-description: "Keep the Lightning node healthy: check node info, audit channels and liquidity, flush stuck RGB transfers, and (when allowed) buy inbound/asset channel capacity via the KaleidoSwap LSP. Triggers when the user asks about node health, channels, liquidity, or inbound capacity — and is the skill the scheduled 'heartbeat' loop runs."
-tools: rln_get_node_info, rln_list_channels, rln_get_balances, rln_list_assets, rln_refresh_transfers, kaleidoswap_lsp_get_info, kaleidoswap_lsp_estimate_fees, kaleidoswap_lsp_create_order, rln_pay_invoice
-triggers: node, channel, channels, liquidity, inbound, outbound, lsp, heartbeat, health, transfers, stuck
+description: "Lightning channels and liquidity for the RGB Lightning Node: node health, channel audit, inbound/outbound balance, buying a channel or asset channel from the KaleidoSwap LSP, opening and closing channels. Runs the scheduled heartbeat."
+tools: rln_get_node_info, rln_list_channels, rln_get_balances, rln_refresh_transfers, rln_connect_peer, rln_open_channel, rln_close_channel, rln_get_channel_id, rln_pay_invoice, kaleidoswap_lsp_get_info, kaleidoswap_lsp_estimate_fees, kaleidoswap_lsp_create_order, kaleidoswap_lsp_get_order, kaleidoswap_lsp_quote_asset_channel, kaleidoswap_lsp_create_asset_channel
+requires-tools: rln_list_channels
+triggers: channel, channels, liquidity, inbound, outbound, lsp, lsps1, capacity, rebalance channel, can't receive, open channel, close channel, channel order, heartbeat, health, stuck
 metadata:
   author: kaleidoswap
-  version: "0.1.0"
+  version: "0.2.0"
 ---
-
 # Channel manager
 
-Keep the RGB Lightning node healthy and liquid. Read state every run; only buy
-capacity when the user allows it and it's actually needed.
-
-## Critical rules — these override everything else
-
-- **Diagnose before acting.** `rln_get_node_info` + `rln_list_channels` +
-  `rln_get_balances` first. Report what you see; don't guess.
-- **Respect `dry_run`.** When true, describe the action you *would* take (e.g.
-  "buy 1M sat inbound") but do NOT call `kaleidoswap_lsp_create_order` or
-  `rln_pay_invoice`.
-- **Buying capacity is a spend** — it routes through the host's risk gate. Never
-  propose one that breaches the BTC reserve, and always show the LSP fee
-  (`kaleidoswap_lsp_estimate_fees`) before recommending it.
-
-## Health checks (run in order)
-
-1. **Node up?** `rln_get_node_info` — pubkey, block height, synced.
-2. **Channels.** `rln_list_channels` — count, capacity, outbound vs inbound. Flag
-   any channel whose outbound is below the configured floor.
-3. **Stuck transfers.** `rln_refresh_transfers` to flush pending RGB transfers;
-   report anything still pending afterward.
-4. **Liquidity verdict.** If usable inbound (or an asset's inbound) is below the
-   threshold in the task parameters, that's the trigger to consider buying.
-
-## Buying capacity (only when needed + allowed)
-
-1. `kaleidoswap_lsp_get_info` — confirm the LSP is reachable + its limits.
-2. `kaleidoswap_lsp_estimate_fees` — show the fee for the size you'd buy.
-3. `kaleidoswap_lsp_create_order` (spend-gated) — create the order; it returns an
-   invoice/onchain address. Pay via `rln_pay_invoice` only after approval.
-
-## Scheduled (background) runs
-
-When run by the `heartbeat` loop, return STRICT JSON only:
-
-```
-{"task":"heartbeat","timestamp":"<ISO8601>","action":"ok|flush|buy_capacity|alert","dry_run":<bool>,"reason":"<why>","details":{"channels":<n>,"outbound_sat":<n>,"inbound_sat":<n>,"pending_transfers":<n>}}
-```
-
-Use `ok` when nothing needs doing, `alert` when a human should look.
-
-## Don'ts
-
-- Don't buy capacity that isn't needed, or when within the liquidity threshold.
-- Don't pay an LSP invoice when `dry_run` is true.
-- Don't invent channel ids, balances, or fees — read them from tools.
-- Don't breach the BTC reserve to open a channel.
+Read state first: `rln_get_node_info`, `rln_list_channels`, `rln_get_balances`.
+Outbound = what the node can send; inbound = what it can receive. Report
+numbers from this turn's results only.
+
+## Do
+- Health: count usable channels, total outbound vs inbound, channels with
+  `is_usable: false`; `rln_refresh_transfers {}` flushes pending RGB transfers.
+- Can't receive → buy inbound: `kaleidoswap_lsp_get_info` (limits and
+  `lsp_connection_url`), `rln_connect_peer`, `kaleidoswap_lsp_estimate_fees`
+  (show `total_fee`), then `kaleidoswap_lsp_create_order` with `client_pubkey`
+  from `rln_get_node_info`, pay its invoice with `rln_pay_invoice`, poll
+  `kaleidoswap_lsp_get_order` until `COMPLETED`.
+- Wants an asset (USDT/XAUT) but has no channel →
+  `kaleidoswap_lsp_quote_asset_channel` then
+  `kaleidoswap_lsp_create_asset_channel` with the fresh `rfq_id`.
+- Can't send → open a channel with spare on-chain BTC (`rln_open_channel`).
+- Every order, open, close and payment is confirm-gated; recommend first,
+  execute only on an explicit request. With `dry_run` true, describe only.
+- Heartbeat runs: `action` is `ok`, `flush`, `buy_capacity` or `alert`.
+
+## Examples
+- "How healthy is my node?" → `rln_list_channels {}`
+- "Fee for 500k sats inbound?" → `kaleidoswap_lsp_estimate_fees {"lsp_balance_sat":500000,"client_balance_sat":0,"channel_expiry_blocks":4320}`
+- "Buy 500k inbound" → `rln_get_node_info {}` then `kaleidoswap_lsp_create_order {"client_pubkey":"<pubkey>","lsp_balance_sat":500000,"client_balance_sat":0,"channel_expiry_blocks":4320}`
+- "A channel holding 100 USDT" → `kaleidoswap_lsp_quote_asset_channel {"asset":"USDT","asset_amount":100}`
+- "Did order 7a1b open?" → `kaleidoswap_lsp_get_order {"order_id":"7a1b"}`

package/skills/flashnet-swaps/SKILL.md

@@ -1,158 +1,32 @@
 ---
 name: flashnet-swaps
-description: "Swap between BTC and Spark tokens (e.g. USDB) using Flashnet — a Spark-native AMM. Run by quoting `flashnet_simulate_swap` first, then `flashnet_execute_swap` on confirmation. Pairs with the spark-wallet skill: the same Spark wallet that holds your BTC is what signs the swap. Triggers on swap/exchange/convert/trade phrasings involving BTC + a Spark token, or explicit mention of Flashnet."
-tools: flashnet_list_pools, flashnet_get_pool, flashnet_simulate_swap, flashnet_execute_swap, flashnet_get_balance, spark_get_balance, spark_get_address, get_price, fiat_to_sats
-triggers: flashnet, swap, exchange, convert, trade, usdb, amm, pool, liquidity, btc to usdb, usdb to btc, spark swap
+description: "Swap BTC and Spark tokens (e.g. USDB) on Flashnet, the Spark-native AMM, from the in-app Spark wallet: list pools, simulate, execute."
+tools: flashnet_list_pools, flashnet_get_pool, flashnet_simulate_swap, flashnet_execute_swap, flashnet_get_balance, spark_get_balance
+requires-tools: flashnet_simulate_swap
+triggers: flashnet, usdb, amm, pool, pools, spark swap, btc to usdb, usdb to btc
 metadata:
   author: kaleidoswap
-  version: "1.0.0"
+  version: "1.1.0"
   venue: flashnet
 ---
-
 # Flashnet swaps
 
-Flashnet is a Spark-native AMM. The user's Spark wallet IS the swap account —
-there's no separate exchange balance. A swap takes one asset from the wallet,
-sends it through a pool, and returns the other asset to the same wallet, in
-seconds. Two pool curve types exist (constant-product and V3 concentrated
-liquidity) — the model doesn't need to care; the pool id is enough.
-
-## What Flashnet trades (and what it does NOT)
-
-**Flashnet trades:**
-- **BTC** ↔ **Spark-native tokens**. The canonical example is **USDB**.
-- Whatever pools `flashnet_list_pools` returns — that list is the
-  authoritative answer to "what can I trade here?".
-
-**Flashnet does NOT trade:**
-- **RGB assets** (USDT, XAUT, …). RGB assets live on the RLN layer and
-  trade via the **KaleidoSwap maker** (`kaleido-trading` skill), not here.
-  USDT on Flashnet does not exist — never offer it.
-- Assets the user holds on Arkade, on-chain BTC reserves, or any external
-  chain. The trade-account is the Spark wallet.
-
-If the user asks for an asset you can't see in `flashnet_list_pools`, tell
-them so plainly and (if it's a known RGB asset like USDT/XAUT) point them
-at the kaleido-trading skill rather than inventing a Flashnet pool.
-
-## Critical rules (read first)
-
-1. **Never invent a pool id, asset address, or amount.** Every `pool_id`,
-   `asset_in_address`, `asset_out_address`, `amount_in` you pass MUST come
-   from `flashnet_list_pools` / `flashnet_simulate_swap` / a tool-returned
-   value in the CURRENT turn — never from history, never guessed.
-   **ALWAYS start a swap by calling `flashnet_list_pools`** to get the real
-   pool id + asset addresses. You may pass `BTC` as a literal asset (the
-   host resolves it), but for any TOKEN you must use the exact
-   `asset_a_address` / `asset_b_address` the pool returned. Token tickers
-   (e.g. `USDB`) only resolve if the network publishes them or the host is
-   configured; if a ticker doesn't resolve, the result rows carry the
-   addresses — use those. Each pool row includes `asset_a_symbol` /
-   `asset_b_symbol` when known (e.g. `"BTC"`); pick the pool whose pair
-   matches the user's intent and read its addresses from that row.
-2. **Always simulate before executing.** Call `flashnet_simulate_swap` to
-   get `amount_out` + `price_impact_pct`, show the user the rate in plain
-   English, get explicit confirmation, then call `flashnet_execute_swap`.
-   The host fires one extra confirmation gate on execute — that's the
-   safety net, not the primary one.
-3. **Compute `min_amount_out` yourself.** Never pass the simulated
-   `amount_out` directly to execute. The standard formula is
-   `min_amount_out = floor(amount_out × (1 − max_slippage_bps / 10000))`.
-   Default `max_slippage_bps: 50` (0.5%). Use 100 for volatile pairs or
-   high price impact (>0.5%); ask the user before going higher than 1%.
-4. **Smallest units, as strings.** `amount_in` / `min_amount_out` are in
-   the asset's smallest unit (sats for BTC; the token's smallest decimal
-   place for tokens). Pass them as JSON strings so BigInt-sized values
-   survive round-trip. e.g. `amount_in: "100000"` for 100k sats, NOT
-   `amount_in: 100000`.
-5. **High price impact = stop and ask.** If
-   `simulate_swap.price_impact_pct > 1.0`, surface it explicitly:
-   "This trade would move the price by 1.7%. Continue?" Don't auto-execute
-   anything with >2% impact without a clear user yes.
-6. **Get the direction right — `asset_in` is what the user SPENDS,
-   `asset_out` is what they GET.** Parse the request literally:
-   - "spend 2000 sats to get USDB" → asset_in = BTC, asset_out = USDB,
-     amount_in = 2000 (the sats spent).
-   - "swap 10 USDB to BTC" / "sell 10 USDB for sats" → asset_in = USDB,
-     asset_out = BTC, amount_in = the USDB amount.
-   - "buy USDB with 2000 sats" → asset_in = BTC, asset_out = USDB.
-   `amount_in` is ALWAYS denominated in `asset_in`. Double-check before
-   simulating: if the user said "spend N sats", asset_in MUST be BTC and
-   amount_in MUST be N.
-
-## Happy-path playbook
-
-For a typical "swap 100k sats to USDB":
-
-1. **`flashnet_list_pools({ asset_a: <BTC>, asset_b: <USDB> })`** — find a
-   pool. Pick the first result (already sorted by TVL desc). Save its
-   `pool_id`, `asset_a_address`, `asset_b_address`.
-
-   - If the user named a specific asset by *symbol* (e.g. "USDB"), the host
-     fills in the token address based on the active Spark network. The
-     model just passes the symbol or whatever address the prior tool
-     returned.
-
-2. **`flashnet_simulate_swap({ pool_id, asset_in_address, asset_out_address, amount_in })`**
-   — get `amount_out`, `execution_price`, `price_impact_pct`,
-   `fee_paid_asset_in`. Show the user one short line:
-
-   `Swap 100,000 sats → ~497,500 USDB (0.5% pool fee, 0.18% price impact).
-    Proceed?`
-
-3. **Compute `min_amount_out`** from the simulated `amount_out` and the
-   chosen slippage tolerance (default 0.5% / 50 bps). Don't trust the
-   simulated value as-is.
-
-4. **`flashnet_execute_swap({ pool_id, asset_in_address, asset_out_address,
-   amount_in, min_amount_out, max_slippage_bps })`** — SPEND, gated. On
-   success returns the swap `request_id` and the actual `amount_out`.
-   Surface the realised amount on a single line.
-
-## When to use which tool
-
-| Tool | Use when |
-|---|---|
-| `flashnet_list_pools` | First step of any swap; or when the user asks "what pools exist for X/Y". |
-| `flashnet_get_pool` | User wants pool depth / current price / TVL before swapping. |
-| `flashnet_simulate_swap` | EVERY swap, before execute. Also for "what would I get if I swapped 5k sats?" — read-only quote. |
-| `flashnet_execute_swap` | After user confirms the simulated quote. Confirmation-gated. |
-| `flashnet_get_balance` | Pre-swap balance check, or "what do I have on Spark/Flashnet". (Reads from the same wallet `spark_get_balance` reads — they are not separate accounts.) |
-
-## Cross-skill flow with spark-wallet
-
-The Spark wallet and Flashnet share the same on-device account. Common
-chains:
-
-- **Pre-swap balance check.** `spark_get_balance` (or
-  `flashnet_get_balance`) → confirm the user has enough sats → quote →
-  execute.
-- **Deposit then swap.** User has on-chain BTC → `spark_get_address` to
-  receive into Spark → wait for confirmation (the user does that
-  externally) → swap.
-- **Swap then pay invoice.** User has USDB but needs to pay a BOLT11
-  invoice → swap USDB → BTC (this skill) → `spark_pay_invoice` (the
-  spark-wallet skill) → done.
-
-## Failure handling
-
-Tool errors arrive as `Error.message`. Common ones:
-
-- **`Insufficient balance`** — the wallet doesn't hold enough
-  `asset_in`. Surface the deficit. Suggest depositing or swapping less.
-- **`Slippage exceeded` / `min_amount_out not met`** — the pool moved
-  between simulate and execute. Re-simulate and try again (the host can
-  do this; don't loop more than 2× automatically — ask the user after
-  that).
-- **`Pool not found` / `Asset not allowed`** — pool id stale or wrong
-  network. Re-list pools.
-- **Authentication / connection errors** — the Spark wallet isn't
-  initialized. Say so plainly; don't fake a result.
-
-## Reply style
-
-- Quote line: amount in, amount out, fee, price impact — all on one line.
-- After execute: one-line result with realised amount and tx id.
-- Never paste a multi-line JSON of the simulate/execute response.
-- Don't echo `amount_in` / `min_amount_out` raw numbers in subsequent
-  turns; the model isn't a ledger.
+The Spark wallet is the swap account. Flashnet trades BTC against Spark tokens
+only; RGB assets (USDT, XAUT) trade on KaleidoSwap (`kaleido-trading`).
+
+## Do
+- Start with `flashnet_list_pools`; take `pool_id` and the asset addresses
+  from its result. Never invent a pool or address.
+- `amount_in` and `min_amount_out` are strings in the smallest unit
+  (sats for BTC). `asset_in` is what the user spends.
+- Always `flashnet_simulate_swap` first; show `amount_out` and
+  `price_impact_pct`; ask before going on if impact is above 1%.
+- `min_amount_out = floor(amount_out × (1 − max_slippage_bps / 10000))`,
+  default `max_slippage_bps` 50. Then `flashnet_execute_swap`
+  (confirm-gated).
+- "Slippage exceeded": re-simulate once, then ask the user.
+
+## Examples
+- "Pools for BTC/USDB" → `flashnet_list_pools {"asset_a":"BTC","asset_b":"USDB"}`
+- "What would 100k sats get me in USDB?" → `flashnet_simulate_swap {"pool_id":"<pool_id>","asset_in_address":"<BTC address>","asset_out_address":"<USDB address>","amount_in":"100000"}`
+- "Do it" → `flashnet_execute_swap {"pool_id":"<pool_id>","asset_in_address":"<BTC address>","asset_out_address":"<USDB address>","amount_in":"100000","min_amount_out":"<computed>","max_slippage_bps":50}`

package/skills/kaleido-node/SKILL.md

@@ -1,63 +1,33 @@
 ---
 name: kaleido-node
-description: "Run the RGB Lightning Node itself: list environments, start/stop/tear down the Docker stack, check reachability, initialise the wallet once, unlock it after every restart, and recover from a down or locked node. Triggers when the user wants to start, stop, unlock or set up their node, or when node calls fail with 'unreachable' or 'wallet locked'. Uses kaleido-mcp's kaleido_node_* tools (or the kaleido CLI)."
+description: "Run the RGB Lightning Node process: list environments, start, stop or tear down the Docker stack, check reachability, initialise the wallet once and unlock it after every restart. Use when node calls fail with 'unreachable' or 'wallet locked'."
 tools: kaleido_node_list, kaleido_node_up, kaleido_node_ps, kaleido_node_status, kaleido_node_info, kaleido_node_use, kaleido_node_init, kaleido_node_unlock, kaleido_node_lock, kaleido_node_stop, kaleido_node_down, rln_get_node_info, rln_create_utxos
-triggers: start node, stop node, start my node, stop my node, node up, node down, unlock, unlock node, lock node, wallet locked, init node, initialise node, initialize node, docker, environment, node status, node unreachable, mnemonic, seed phrase
+requires-tools: kaleido_node_status
+triggers: start node, stop node, node up, node down, unlock, unlock node, lock node, wallet locked, init node, initialise node, initialize node, docker, environment, node status, node unreachable
 metadata:
   author: kaleidoswap
-  version: "0.1.0"
+  version: "0.2.0"
 ---
-
 # Kaleido node lifecycle
 
-Operate the node process, not the wallet. For balances, invoices, payments and
-channels use the `rgb-lightning-node` skill.
-
-These tools come from kaleido-mcp and wrap the `kaleido` CLI, which must be
-installed on the machine running the MCP server. In-app wallets don't have
-them. If a tool is not in your list, say what the user should run instead
-(CLI column below).
-
-## Tools
-
-| Step | MCP tool | CLI equivalent |
-|---|---|---|
-| List environments | `kaleido_node_list()` | `kaleido --json --agent node list` |
-| Start | `kaleido_node_up({ name? })` | `kaleido --agent node up <NAME>` |
-| Container status | `kaleido_node_ps({ name? })` | `kaleido --agent node ps <NAME>` |
-| Reachability | `kaleido_node_status()` | `kaleido --json --agent node info` |
-| Node + network info | `kaleido_node_info()` | `kaleido --json --agent node info` |
-| Select active node | `kaleido_node_use({ name, node? })` | — |
-| First-time wallet init | `kaleido_node_init({ password, mnemonic? })` | `kaleido --agent node init` |
-| Unlock after restart | `kaleido_node_unlock({ password, announce_alias?, announce_address? })` | `kaleido --agent node unlock <PASSWORD>` |
-| Lock | `kaleido_node_lock()` | — |
-| Stop (keep data) | `kaleido_node_stop({ name? })` | `kaleido --agent node stop <NAME>` |
-| Tear down (keep volumes) | `kaleido_node_down({ name? })` | `kaleido --agent node down <NAME>` |
-
-`name` can be omitted when only one environment exists.
-
-## Flows
-
-- **First run:** `kaleido_node_up` → `kaleido_node_init` → `kaleido_node_unlock`
-  → create colored UTXOs (`rln_create_utxos`, or
-  `kaleido --agent wallet create-utxos`). Until UTXOs exist, issuing or
-  receiving RGB assets fails.
-- **After a restart:** `kaleido_node_up` (if containers are down) →
-  `kaleido_node_unlock`. Unlock is needed after every restart.
-- **Node unreachable** (`rln_get_node_info` fails): `kaleido_node_status`, then
-  `kaleido_node_up` and `kaleido_node_unlock`.
-- **"wallet locked" errors:** `kaleido_node_unlock`.
-- **Stuck pending RGB transfers:** `kaleido --json asset fail-transfers` marks
-  them failed (CLI only).
-
-## Safety
-
-1. **Passwords:** ask the user for the password at the moment it is needed.
-   Never store, repeat or log it.
-2. **Mnemonic:** `kaleido_node_init` shows the seed phrase once. Tell the user
-   to write it down offline before continuing. It cannot be recovered.
-   Never paste it back into the chat.
-3. **State changes need a yes:** `up`, `stop`, `down`, `init`, `unlock` and
-   `lock` change the node; confirm first. `down` removes containers (volumes
-   stay); say so.
-4. **Dry run:** describe the steps only; call no state-changing tool.
+These tools wrap the `kaleido` CLI on the machine running kaleido-mcp. For
+balances, invoices and channels use `rgb-lightning-node`. `name` can be
+omitted when only one environment exists.
+
+## Do
+- First run: `kaleido_node_up` → `kaleido_node_init` → `kaleido_node_unlock` →
+  `rln_create_utxos {}` (needed before issuing or receiving RGB assets).
+- After a restart: `kaleido_node_up` if containers are down, then
+  `kaleido_node_unlock`.
+- Unreachable: `kaleido_node_status`, then up and unlock.
+- Ask for the password when it is needed; never store or repeat it.
+- `kaleido_node_init` shows the mnemonic once: tell the user to write it down
+  offline and never echo it back.
+- `up`, `stop`, `down`, `init`, `unlock`, `lock` change the node: confirm
+  first. `down` removes containers; volumes stay.
+
+## Examples
+- "Is my node running?" → `kaleido_node_status {}`
+- "Start my node" → `kaleido_node_up {}`
+- "Unlock the node" → `kaleido_node_unlock {"password":"<password from the user>"}`
+- "Use the signet environment" → `kaleido_node_use {"name":"signet"}`