@kaleidorg/mind 0.8.1 → 0.10.0

package/skills/rgb-lightning-node/SKILL.md

@@ -1,260 +1,42 @@
 ---
 name: rgb-lightning-node
-description: "Drive the user's local RGB Lightning Node (RLN) — read its pubkey/status, list channels and their capacities, check RGB asset balances, manage channels/peers, whitelist a swap, or create Lightning/RGB receive invoices. Triggers when the user asks about the node, their channels or capacities, needs an invoice, wants to issue/mint a new RGB token or NFT, or is mid-atomic-swap and the maker needs the node pubkey or a swapstring whitelisted."
-tools: rln_get_node_info, rln_get_balances, rln_list_channels, rln_list_assets, rln_get_asset_balance, rln_refresh_transfers, rln_get_address, rln_send_btc, rln_send_asset, rln_pay_invoice, rln_open_channel, rln_close_channel, rln_connect_peer, rln_get_channel_id, rln_atomic_taker, rln_list_swaps, rln_get_swap, rln_list_payments, rln_create_ln_invoice, rln_create_rgb_invoice, rln_list_transfers, rln_create_utxos, rln_issue_asset
-triggers: node, nodeinfo, pubkey, peer, channels, channel capacity, list channels, open channel, close channel, inbound, capacity, asset balance, whitelist, taker, swapstring, swaps, payments, invoice, receive, send asset, send rgb, on-chain address, deposit, rgb invoice, ln invoice, issue, mint, new token, nft, utxos, transfers
+description: "Operate the user's RGB Lightning Node: RGB asset balances, issue a new RGB token or NFT, RGB and Lightning invoices, send assets or BTC, pay invoices, channels and node status."
+tools: rln_get_node_info, rln_get_balances, rln_list_assets, rln_get_asset_balance, rln_refresh_transfers, rln_list_transfers, rln_create_utxos, rln_issue_asset, rln_create_rgb_invoice, rln_send_asset, rln_create_ln_invoice, rln_pay_invoice, rln_get_address, rln_send_btc, rln_list_channels, rln_list_payments
+requires-tools: rln_get_node_info
+triggers: node, pubkey, balance, balances, rgb, asset, assets, token, nft, issue, mint, utxos, transfers, invoice, receive, send asset, pay invoice, on-chain address, channels, payments
 metadata:
   author: kaleidoswap
-  version: "0.3.3"
+  version: "0.4.0"
 ---
-
-# RGB Lightning Node (taker-side)
-
-You drive the **user's own** RGB Lightning Node running locally. In a KaleidoSwap
-atomic swap the **maker** owns init / execute / status (those are
-`kaleidoswap_atomic_*` tools, separate REST endpoints). The node's job in a
-swap is narrow: **expose its pubkey and whitelist the maker's swapstring**.
-The node does NOT init or execute swaps.
-
-## Critical rules
-
-You have **no knowledge** of the node's pubkey, channel state, balance, or any
-invoice contents. Every value in your reply MUST come from a tool result
-returned in the CURRENT turn — never invent a pubkey, channel id, invoice
-string, or sats balance. Never reuse a value from a previous turn.
-
-**Calling the tool IS the answer.** If the user asks "what's my pubkey?", call
-`rln_get_node_info` — do not describe how to fetch it.
-
-## When to use each tool
-
-### `rln_get_node_info` — no args
-Returns:
-- `pubkey` — the node's identity (32-byte hex).
-- `num_channels` — total channels (may include unusable ones).
-- `num_usable_channels` — subset that can route a payment right now.
-- `local_balance_sat` — **sats YOU own** across all channels. This is your
-  **spend** capacity (outbound). It is **NOT** receive capacity, **NOT**
-  inbound liquidity, and **NOT** total channel capacity.
-- `pending_outbound_payments_sat` — in-flight, temporarily locked.
-- `num_peers` — currently connected peers.
-
-Call this when:
-- The user asks about the node, pubkey, peers, channel count, or how much
-  they can **spend**.
-- An atomic swap is in progress and the maker needs `taker_pubkey` —
-  fetch the pubkey from this tool's `pubkey` field and pass it to
-  `kaleidoswap_atomic_execute`.
-
-**Do NOT** use this tool's `local_balance_sat` to answer a question about
-**inbound liquidity / receive capacity** — that is a different quantity (the
-peer's side of each channel). For per-channel inbound/outbound and total
-capacity, use `rln_list_channels` (below), NOT this tool.
-
-### `rln_list_channels` — no args
-Returns `{ channels: [...], count }`. Each channel carries:
-- `channel_id`, `peer_alias`, `status`, `ready`, `is_usable`
-- `capacity_sat` — total channel size.
-- `outbound_sat` — what YOU can send (your local balance).
-- `inbound_sat` — what you can RECEIVE on this channel (the peer's side).
-- `asset_id`, `asset_local_amount`, `asset_remote_amount` — for RGB asset
-  channels: the asset and how much is on each side.
-
-Call this when the user asks to **list channels**, asks about **per-channel
-capacity**, **inbound/receive capacity**, or wants to **verify a channel they
-just bought** opened with the requested size. Report each channel as one line:
-`capacity_sat total — outbound_sat / inbound_sat (asset if present), status`.
-
-When verifying a freshly-bought channel: a channel order opens
-ASYNCHRONOUSLY (seconds to minutes after payment). If the new channel isn't
-listed yet, say it's still opening and suggest checking again — don't claim
-failure.
-
-### `rln_list_assets` — { schemas? }
-Lists RGB assets known to the node: `asset_id`, `ticker`, `name`, `precision`
-(in-app wallets also return balances). `schemas` is an optional filter — an
-array of `"Nia"`, `"Uda"`, `"Cfa"`; call it with `{}` to list everything.
-Use for "what assets do I hold / what's my USDT balance".
-
-Call it **once** per question. An empty list is a real answer: the node holds
-no RGB assets yet — tell the user that (and offer to issue one) instead of
-calling it again.
-
-### Tickers are not asset ids
-`asset_id` arguments take the full RGB id (`rgb:…`), never a ticker like
-`USDT` or `HCK`. When the user names an asset by ticker or name, first call
-`rln_list_assets`, find the entry whose `ticker`/`name` matches, and pass its
-`asset_id`. If nothing matches, say the node has no such asset — do not guess
-an id.
-
-### `rln_get_asset_balance` — { asset_id }
-Balance for one RGB asset by id. Resolve a ticker to its `asset_id` with
-`rln_list_assets` first.
-
-| Field | Meaning |
-|---|---|
-| `settled` / `spendable` | On-chain (RGB_L1), UTXO-bound |
-| `future` | Pending settlement |
-| `offchain_outbound` | In a Lightning channel: what you can **send** |
-| `offchain_inbound` | Channel receive capacity for this asset |
-
-For USDT/XAUT held in an RGB channel, report `offchain_outbound`; `spendable`
-is 0 and that is normal.
-
-### `rln_refresh_transfers` — no args
-Syncs pending RGB transfers. Call it before re-reading a balance or transfer
-status that looks stale (e.g. right after an invoice was paid or a swap filled).
-
-### `rln_get_address` — no args
-An on-chain BTC address of the node, for funding it. Not an RGB invoice and not
-a Lightning invoice.
-
-### `rln_send_btc` — { address, amount_sat, fee_rate? } — 🔒 confirm-gated
-Sends on-chain BTC from the node. Only when the user gave both the address and
-the amount.
-
-### `rln_send_asset` — 🔒 confirm-gated
-Sends an RGB asset to the recipient encoded in an RGB invoice. Use the argument
-names of the schema you were given: in-app wallets take `{ asset, amount, to }`
-(ticker or asset_id, units, the invoice); kaleido-mcp takes
-`{ asset_id, amount, recipient_id }`, where `asset_id` is the `rgb:…` id from
-`rln_list_assets`. Never invent a recipient.
-
-### `rln_pay_invoice` — { invoice } — 🔒 confirm-gated
-Pays a BOLT11 Lightning invoice from the node. Pass the full invoice string.
-
-### Channels and peers
-- `rln_connect_peer { peer_pubkey_and_addr }` — `pubkey@host:port`. Needed
-  before opening a channel to a peer the node has never seen.
-- `rln_open_channel { peer_pubkey_and_addr, capacity_sat, asset_id?, asset_amount?, push_msat?, is_public? }`
-  — 🔒 confirm-gated. Locks on-chain BTC (and optionally an RGB asset) into a
-  channel. Opening is asynchronous: report the `temporary_channel_id` and
-  suggest checking `rln_list_channels`.
-- `rln_get_channel_id { temporary_channel_id }` — the final `channel_id` once
-  the channel is established.
-- `rln_close_channel { channel_id, peer_pubkey, force? }` — 🔒 confirm-gated.
-  Both values come from `rln_list_channels`. `force` only for an unresponsive
-  peer.
-
-### `rln_list_payments` — { limit? }
-Recent Lightning payments, sent and received. Use for "did I get paid" /
-"what did I pay" over Lightning.
-
-### `rln_list_swaps` / `rln_get_swap { payment_hash, taker? }`
-Atomic swaps as the node sees them (HTLC status). For the maker-side status use
-`kaleidoswap_atomic_status`.
-
-### `rln_atomic_taker` — { swapstring } — 🔒 confirm-gated
-Tell the node "I accept this swap." Args: the `swapstring` returned by
-`kaleidoswap_atomic_init`. The node validates and stores it; **no funds move
-here**, but the user is committing to the swap so the engine pauses for
-confirmation.
-
-Call this **after** `kaleidoswap_atomic_init` and **before**
-`kaleidoswap_atomic_execute`. Never call with an empty or invented swapstring
-— the node will reject it.
-
-### `rln_create_ln_invoice` — Lightning invoice for receiving sats
-Args:
-- `amount_sats` (optional) — omit for an amountless invoice.
-- `description` (optional, kaleido-mcp) — memo shown to the payer.
-- `expiry_sec` (default 3600, kaleido-mcp only) — invoice TTL in seconds.
-
-Reply with the full `invoice` string from the result — never write an invoice
-yourself.
-
-Use when the user wants to **receive** a Lightning payment. Do NOT call inside
-an atomic swap flow unless the user explicitly asked to invoice someone.
-
-### `rln_create_rgb_invoice` — on-chain RGB receive invoice
-Args (use the names in your schema):
-- in-app wallets: `asset` (ticker or asset_id) + `amount`.
-- kaleido-mcp: `asset_id` (the `rgb:…` id from `rln_list_assets` — never a
-  ticker; omit for an any-asset invoice), `amount` (display units),
-  `duration_seconds` (default 86400).
-
-Reply with the full `invoice` string; the payer needs all of it.
-
-Use when the user wants to **receive** an RGB asset directly (not over
-Lightning). Outside the atomic swap flow.
-
-### `rln_list_transfers` — { asset_id }
-Transfers for one asset (issuance, sends, receives) with `status`
-(`WaitingCounterparty`, `WaitingConfirmations`, `Settled`, `Failed`). Use it to
-answer "has my RGB invoice been paid?". Pass the `asset_id` (`rgb:…`) from
-`rln_list_assets` or `rln_issue_asset`; in-app wallets also accept a ticker.
-
-### `rln_create_utxos` — { num?, size?, up_to?, fee_rate? } — 🔒 confirm-gated
-Creates colorable UTXOs (spends a little on-chain BTC). A fresh node needs
-these before it can **issue** or **receive** RGB assets. Call it when an RGB
-call fails with "no available UTXOs", then retry the original action. The
-defaults (`num` 5, `fee_rate` 1) are fine; set `up_to: true` to only top up to
-`num` free UTXOs.
-
-### `rln_issue_asset` — { name, ticker?, amount?, precision?, schema?, details? } — 🔒 confirm-gated
-Creates a **new** RGB asset owned by this node. `schema`: `NIA` fungible token
-(default), `CFA` collectible, `UDA` unique asset / NFT (supply 1).
-- `ticker` (uppercase, 1–8 letters/digits, nothing else) is required for `NIA`
-  and `UDA`.
-- `amount` is the total supply in display units (a number), required for `NIA`
-  and `CFA` — if the user did not say how many, ask before calling;
-  the raw supply is `amount × 10^precision` (`precision` defaults to 0).
-- `details` is an optional description for `CFA` and `UDA`.
-
-Reply with the returned `asset_id` — the user needs it to invoice or send the
-new asset.
-
-Examples:
-- "issue 1000 TICKET tokens called Hackathon Ticket" →
-  `rln_issue_asset { name: "Hackathon Ticket", ticker: "TICKET", amount: 1000 }`
-- "mint an NFT called Genesis Badge" →
-  `rln_issue_asset { name: "Genesis Badge", ticker: "GENESISB", schema: "UDA" }`
-- "has anyone paid my TICKET invoice?" → `rln_refresh_transfers` →
-  `rln_list_transfers { asset_id: "<TICKET asset_id from rln_list_assets>" }`
-
-kaleido-mcp exposes these three as `wdk_issue_asset`, `wdk_create_utxos` and
-`wdk_list_transfers`, with the same arguments and `rln_*` aliases.
-
-### Recipe: issue your own RGB asset
-1. `rln_get_node_info` — the node is reachable and unlocked.
-2. `rln_create_utxos {}` — skip if the node already has free colored UTXOs;
-   wait for the funding tx to confirm before issuing.
-3. `rln_issue_asset { name, ticker, amount }` — confirm with the user first.
-4. `rln_create_rgb_invoice` on the receiver's node, then `rln_send_asset` with
-   the new `asset_id` to distribute it.
-5. `rln_refresh_transfers` → `rln_list_transfers { asset_id }` until the
-   transfer is `Settled`.
-
-## The maker / node split
-
-A user-driven swap on KaleidoSwap is a two-service flow. Keep them straight:
-
-| Step | Owner | Tool |
-|------|-------|------|
-| Quote | maker | `kaleidoswap_get_quote` |
-| Init  | maker | `kaleidoswap_atomic_init` (returns swapstring + payment_hash) |
-| Pubkey | **node** | `rln_get_node_info` (read `pubkey`) |
-| Whitelist | **node** | `rln_atomic_taker` (pass the swapstring) |
-| Execute | maker | `kaleidoswap_atomic_execute` (needs swapstring + taker_pubkey + payment_hash) |
-| Status | maker | `kaleidoswap_atomic_status` (pass atomic_id or payment_hash from the atomic recipe summary or prior init result; see "remember" line in history) |
-
-The node's two contributions to the swap are the **pubkey** and the
-**whitelist ack** — nothing more. Don't reach for `/makerinit` or
-`/makerexecute`; those are for nodes that act AS the maker, which is not us.
-
-## Safety
-
-- Show amount, recipient and asset before any send; the engine also asks for
-  confirmation on every 🔒 tool.
-- Flag a send above half of the available balance.
-- If the node is unreachable or the wallet is locked, use the `kaleido-node`
-  skill (start / unlock) before retrying.
-
-## Reply style
-
-- One short sentence built from the tool result.
-- Pubkeys are long hex strings — quote them in monospace if you can, never
-  truncate them when the user explicitly asked for them.
-- For `rln_get_node_info`, if the user just said "what's my node status?",
-  surface pubkey + num_usable_channels + local_balance_sat. Don't dump the
-  whole `details` object.
+# RGB Lightning Node
+
+Every value in a reply comes from a tool result in this turn. RGB `asset_id`s
+look like `rgb:…`; a ticker is not an id — find the id with `rln_list_assets`.
+Amounts are display units (10 = 10 USDT) except fields named `*_sat`/`*_sats`.
+
+## Do
+- Holdings: one `rln_list_assets {}` call. Each asset already carries
+  `balance` (`spendable`, `settled`, `future`, `offchain_outbound`,
+  `offchain_inbound`) in raw units: divide by 10^`precision`. Assets held in a
+  Lightning channel show in `offchain_outbound`. Use `rln_get_asset_balance`
+  only for a single asset the user names.
+- Issue: `rln_issue_asset` (confirm-gated). `ticker` 1–8 uppercase letters or
+  digits; `amount` is the total supply; `precision` defaults to 0;
+  `schema` is `NIA` (token, default), `CFA` (collectible, no ticker) or `UDA`
+  (NFT, supply 1). If it fails with "no available UTXOs", call
+  `rln_create_utxos {}` and retry. Reply with the new `asset_id`.
+- Send an asset: `recipient_id` is the `utxob:…`/`wvout:…` part of the RGB
+  invoice. Never invent a recipient or an invoice.
+- Receive: `rln_create_rgb_invoice` (RGB) or `rln_create_ln_invoice` (BTC over
+  Lightning); reply with the full `invoice` string.
+- Stale balance or transfer: `rln_refresh_transfers {}` once, then re-read.
+- Node unreachable or locked: switch to the `kaleido-node` skill.
+
+## Examples
+- "Which RGB assets do I hold?" → `rln_list_assets {}`
+- "Issue a token named Skill Test, ticker SKT, supply 1000" → `rln_issue_asset {"name":"Skill Test","ticker":"SKT","amount":1000,"precision":0}`
+- "Send 5 SKT to rgb:~/~/~/sig/any/1/utxob:abc" → `rln_list_assets {}` then `rln_send_asset {"asset_id":"<SKT asset_id>","recipient_id":"utxob:abc","amount":5}`
+- "Invoice me 10 USDT" → `rln_create_rgb_invoice {"asset_id":"<USDT asset_id>","amount":10}`
+- "Lightning invoice for 5000 sats" → `rln_create_ln_invoice {"amount_sats":5000}`
+
+Channels, peers and swap internals: read `references/channels.md`.

package/skills/rgb-lightning-node/references/channels.md

@@ -0,0 +1,34 @@
+# Channels, peers, payments and swaps
+
+| Tool | Arguments | Notes |
+|---|---|---|
+| `rln_get_node_info` | — | `pubkey`, `num_channels`, `num_usable_channels`, `local_balance_sat` (what you can **send**, not receive) |
+| `rln_list_channels` | `usable_only?` | Per channel: `capacity_sat`, outbound (send) and inbound (receive) balance, `is_usable`, RGB `asset_id` + local/remote asset amounts |
+| `rln_get_balances` | `skip_sync?` | On-chain BTC (vanilla + colored) and Lightning BTC. RGB assets are in `rln_list_assets` |
+| `rln_connect_peer` | `peer_pubkey_and_addr` | `pubkey@host:port` |
+| `rln_open_channel` | `peer_pubkey_and_addr`, `capacity_sat`, `push_msat?`, `asset_id?`, `asset_amount?`, `is_public?` | Confirm-gated. Opens asynchronously: report `temporary_channel_id` |
+| `rln_get_channel_id` | `temporary_channel_id` | Final `channel_id` once open |
+| `rln_close_channel` | `channel_id`, `peer_pubkey`, `force?` | Confirm-gated. `force` only for an unresponsive peer |
+| `rln_list_payments` | `limit?` | Lightning payments sent and received |
+| `rln_pay_invoice` | `invoice` | Confirm-gated. The BOLT11 string, unchanged |
+| `rln_get_address` | — | On-chain BTC deposit address (not an invoice) |
+| `rln_send_btc` | `address`, `amount_sat`, `fee_rate?` | Confirm-gated |
+| `rln_list_transfers` | `asset_id` | RGB transfers with status `WaitingCounterparty` → `WaitingConfirmations` → `Settled` / `Failed` |
+| `rln_list_swaps` / `rln_get_swap` | — / `payment_hash`, `taker?` | The node's view of atomic swaps |
+| `rln_atomic_taker` | `swapstring` | Confirm-gated. Whitelists a maker swap; see the `kaleido-trading` skill |
+
+A channel bought from an LSP appears in `rln_list_channels` only after its
+funding transaction confirms; if it is missing, say it is still opening.
+
+## Issuing and distributing an asset
+
+1. `rln_get_node_info {}` — node reachable and unlocked.
+2. `rln_create_utxos {}` — only on a fresh node or after "no available UTXOs";
+   wait for the funding transaction to confirm.
+3. `rln_issue_asset {"name":"Hackathon Ticket","ticker":"TICKET","amount":1000}`.
+4. The receiver runs `rln_create_rgb_invoice`; you run `rln_send_asset` with
+   the new `asset_id` and the invoice's `recipient_id`.
+5. `rln_refresh_transfers {}` then `rln_list_transfers {"asset_id":"<asset_id>"}`
+   until the transfer is `Settled`.
+
+kaleido-mcp also exposes every `rln_*` tool as `wdk_*` with the same arguments.

package/skills/spark-wallet/SKILL.md

@@ -1,236 +1,34 @@
 ---
 name: spark-wallet
-description: "Operate the user's Spark BTC wallet on this device — check Spark balance, get a Spark deposit address, create a Spark Lightning invoice to receive, pay any BOLT11 Lightning invoice with Spark, or send BTC on-chain from Spark. Use this when the user names Spark explicitly OR when paying a Lightning invoice on a phone where Spark is the connected layer. Pairs with the bitrefill skill: a Bitrefill purchase that returns a Lightning invoice is paid with `spark_pay_invoice`."
-tools: spark_get_balance, spark_get_address, spark_get_onchain_address, spark_create_invoice, spark_pay_invoice, spark_send, get_price, fiat_to_sats, bitrefill_search, bitrefill_get_product, bitrefill_get_balance, bitrefill_create_invoice, bitrefill_get_invoice, bitrefill_get_order
-triggers: spark, sprak, spakr, spark wallet, pay with spark, send with spark, spark balance, spark address, spark invoice, lightning invoice, pay invoice, bolt11, ln invoice, pay this invoice, on-chain address, onchain address, deposit address, deposit btc, fund spark
-requires-tools: spark_get_balance
+description: "The in-app Spark wallet: Spark balance and tokens (e.g. USDB), Spark address, on-chain deposit address, Lightning invoice to receive, pay a BOLT11 invoice, send BTC on-chain."
+tools: spark_get_balance, spark_get_address, spark_get_onchain_address, spark_create_invoice, spark_pay_invoice, spark_send, get_price, fiat_to_sats
+requires-tools: spark_create_invoice
+triggers: spark, spark wallet, pay with spark, spark balance, spark address, spark invoice, deposit address, fund spark, usdb balance
 metadata:
   author: kaleidoswap
-  version: "1.0.0"
+  version: "1.1.0"
   layer: spark
 ---
-
 # Spark wallet
 
-Spark is one of the user's connected BTC layers (alongside RLN/RGB and Arkade
-on some hosts). It speaks Lightning natively — receive via `spark_create_invoice`,
-send via `spark_pay_invoice` (BOLT11) or `spark_send` (on-chain). All numbers
-are in **satoshis** unless stated otherwise.
-
-## Three "addresses", three different tools (read this carefully)
-
-The word "address" can mean three completely different things on Spark.
-Each has a DIFFERENT tool, a DIFFERENT shape, and a DIFFERENT use. If you
-return the wrong one, the user loses money on a bad deposit. Pick by what
-the user is trying to DO, not just by the word "address":
-
-| User intent | Tool | What you get | Looks like |
-|---|---|---|---|
-| Receive a **Spark-to-Spark** transfer (off-chain, within Spark) | `spark_get_address` | Spark identity / pubkey | `sparkrt1…` / `spark1…` |
-| Deposit **L1 Bitcoin** into Spark from the on-chain world | `spark_get_onchain_address` | Real Bitcoin on-chain address | `bc1…` / `tb1…` / `bcrt1…` |
-| Receive over **Lightning** (BOLT11) | `spark_create_invoice` | A Lightning invoice string | `lnbc…` / `lntb…` / `lnbcrt…` |
-
-**Disambiguation by phrasing — examples:**
-
-- "give me my **on-chain address**" / "**bitcoin address** to fund Spark"
-  / "**deposit address**" / "where do I send BTC from my hardware wallet
-  / mainnet" → `spark_get_onchain_address`. Result starts with bc1/tb1/
-  bcrt1 — verify before replying.
-- "my **Spark address**" / "give me a **Spark address**" / "where do I
-  receive a **Spark transfer**" → `spark_get_address`. Result starts with
-  spark1/sparkrt1. **DO NOT label this as an on-chain address — it is
-  off-chain.**
-- "give me an **invoice for N sats**" / "an **LN invoice**" / "**pay me**
-  N sats" → `spark_create_invoice({amount_sats: N})`. Result is a `lnbc…`
-  string.
-
-**Critical: when the user says "on-chain", they mean L1 Bitcoin.** Never
-return a `sparkrt1…` and call it "on-chain". If you return a
-`spark_get_address` result, you MUST describe it as a Spark (off-chain)
-address — never as an on-chain or Bitcoin address. If you return a
-`spark_get_onchain_address` result, you can call it an on-chain Bitcoin
-deposit address.
-
-A useful sanity check before you send the reply: glance at the
-`address` string's prefix. If it begins with `spark`, it's the off-chain
-Spark identity. If it begins with `bc1`/`tb1`/`bcrt1`, it's an on-chain
-BTC address. If it begins with `lnbc`/`lntb`/`lnbcrt`, it's a Lightning
-invoice. Whatever you call it in your reply MUST match its actual prefix.
-
-## What Spark holds (and what it does NOT)
-
-This is the single most important thing to get right when the user asks
-about "assets on Spark" or "what can I trade on Spark".
-
-**Spark holds:**
-- **BTC** (sats) — Spark's native on-chain-pegged BTC.
-- **Spark-native tokens** — e.g. **USDB**. These are tokens issued on the
-  Spark protocol itself, traded on **Flashnet** (Spark-native AMM).
-
-**Spark does NOT hold:**
-- **RGB assets** (USDT, XAUT, …). RGB assets are a DIFFERENT protocol on
-  Bitcoin/Lightning — they live on the user's **RLN** (RGB Lightning Node),
-  NOT Spark. A USDT balance, if the user has one, is on RLN — never on
-  Spark.
-- Tokens from any other chain (Ethereum USDT, Tron USDT, Solana, …). The
-  wallet does not custody those at all.
-
-**Asset → which skill / venue:**
-
-| Asset | Layer | Swap venue | Skill |
-|---|---|---|---|
-| BTC / sats | Spark / RLN / on-chain | Either (depends on direction) | spark-wallet (Spark side), wallet-assistant |
-| USDB (and other Spark tokens) | Spark | **Flashnet** (AMM) | **flashnet-swaps** |
-| USDT, XAUT (RGB assets) | RLN/RGB | **KaleidoSwap maker** | **kaleido-trading** |
-
-If the user asks "what can I trade on Spark?", the correct answer lists
-Spark-native tokens (BTC + USDB and anything else
-`flashnet_list_pools` shows). **Never** answer USDT/XAUT for Spark.
-Conversely, if asked "what can I trade on KaleidoSwap?", that's RGB
-assets (USDT, XAUT) — **not** USDB.
-
-When in doubt about what's actually tradeable, the source of truth is the
-TOOL, not your training data — call `flashnet_list_pools` (Spark side) or
-`kaleidoswap_get_assets` (RGB side) and report what comes back.
-
-## Critical rules (read first)
-
-1. **Always re-fetch volatile state — every turn, every time.** Balance,
-   address, invoice status, and any number that can change MUST come from a
-   tool call THIS turn. Do NOT reuse a value from a previous turn, even if
-   the user asked the exact same question 30 seconds ago. The user wouldn't
-   ask twice if they didn't want a fresh check.
-
-   - "what's my balance?" → ALWAYS call `spark_get_balance`. Yes, even if
-     you just called it. The whole point of asking again is to get a new
-     reading.
-   - "give me my address" → ALWAYS call `spark_get_address`. Spark may
-     rotate or surface a fresh address.
-   - "did my invoice settle?" → ALWAYS re-fetch the invoice/order status.
-
-   The ONLY thing you can reuse from history is the user's own input
-   (e.g. "the invoice I just made" → look up its id in history and call
-   the status tool on it).
-
-2. **Never invent a balance, invoice or address.** Every BTC number, BOLT11
-   string, and address in your reply MUST come from a Spark tool result
-   returned in the CURRENT turn — never guessed, never quoted from memory.
-
-3. **Read the tool result exactly.** `spark_get_balance` returns
-   `{ total, layer, network, connected }`. `connected: true` means the
-   Spark wallet IS active and reachable; `total: 0` with `connected: true`
-   simply means the user has no sats yet (perfectly normal for a fresh
-   wallet on regtest). Do NOT say "your wallet isn't connected" unless
-   `connected: false` or the tool threw an error. Say "your Spark wallet
-   is connected but empty — fund it with `spark_get_address`" when
-   `total: 0, connected: true`.
-
-4. **Choose the right send tool by destination shape.**
-   - Starts with `lnbc…` / `lntb…` / `lnbcrt…` → BOLT11 Lightning invoice → use
-     **`spark_pay_invoice`**.
-   - Starts with `bc1…` / `tb1…` / `bcrt1…` → on-chain Bitcoin address → use
-     **`spark_send`**.
-   - Looks like `name@domain` (a Lightning address) → not a Spark target;
-     either ask the host to resolve it first or use the cross-cutting
-     `send_payment` router. Spark itself doesn't dereference LNURL.
-
-5. **BOLT11 invoices encode their amount.** Don't pass `amount_sats` to
-   `spark_pay_invoice` unless the invoice is amount-less. Re-stating the
-   amount can produce silently-wrong sends on amount-less invoices.
-
-6. **Confirm before spending.** `spark_pay_invoice` and `spark_send` are
-   confirmation-gated by the contract — the host fires the gate
-   automatically. Before the call, summarize in one line:
-   `Paying 12,540 sats to lnbc12540n… from Spark. Confirm?`
-
-7. **Spark genuinely unavailable = stop, don't guess.** If the tool
-   THROWS with "Your SPARK wallet isn't connected yet" (an actual error,
-   not a 0 balance), say so plainly and stop — don't substitute RLN or
-   Arkade silently. The user may genuinely want Spark.
-
-8. **Never refuse an action a listed tool performs.** If a tool in your
-   set does what the user asked, CALL IT — do not reason about whether
-   "get" means "create", whether the wording is an exact match, or
-   whether some other tool would be "more correct". The user asking to
-   "create an address" when you have `spark_get_address` means: call
-   `spark_get_address`. Refusing to use an available tool is always wrong.
-
-## How to call the tools
-
-### Reads
-
-- **`spark_get_balance({})`** — current Spark balances. Returns the BTC
-  balance (`total` in sats) AND every Spark-native **token** the wallet
-  holds (`tokens[]` — each with `address`, `balance`, optional `symbol`
-  and `decimals`). When the user asks "what do I have on Spark" or
-  "what's my Spark balance", surface BOTH the sats AND any non-zero
-  token balances; an answer that only mentions BTC when tokens are
-  present is incomplete.
-  - `flashnet_get_balance` returns the same numbers (it's the AMM-client
-    view of the same wallet) — there's no need to call it just to learn
-    the token balance.
-- **`spark_get_address({})`** — the user's **Spark identity**
-  (`sparkrt1…`/`spark1…`), an OFF-CHAIN Spark-to-Spark receive target.
-  Reusable — getting and creating are the same operation, so the right
-  response to "create a Spark address" is ALSO this tool. NEVER call its
-  result an on-chain address or a Bitcoin address; it is neither. NEVER
-  reply "I cannot create an address" — this tool IS how you create one.
-- **`spark_get_onchain_address({})`** — a real Bitcoin **on-chain
-  deposit** address (`bc1…`/`tb1…`/`bcrt1…`) for funding Spark from L1.
-  Use whenever the user says "on-chain", "bitcoin address", "deposit
-  address", "fund Spark", or otherwise indicates they want to send L1
-  BTC. NEVER substitute `spark_get_address` here.
-
-### Receive
-
-- **`spark_create_invoice({ amount_sats? })`** — Spark Lightning invoice.
-  - Omit `amount_sats` for an "any amount" invoice.
-  - Returns `{ invoice: "lnbc…", … }`.
-  - This is the tool for "give me an invoice for N sats", NOT for any
-    "address" ask.
-
-### Send — pick by destination
-
-- **`spark_pay_invoice({ invoice, amount_sats? })`** — pay a BOLT11 invoice.
-  - The model's default Lightning spend tool. Use this for invoices from
-    Bitrefill, a contact's invoice paste, or any `ln…` string.
-  - Pass `amount_sats` ONLY when the invoice is amount-less (a 0-amount
-    invoice). For ordinary amount-bound invoices, OMIT it.
-- **`spark_send({ amount_sats, to })`** — on-chain Bitcoin send.
-  - Use only when `to` is an on-chain address (`bc1…`). Never pass a BOLT11
-    invoice here.
-
-### Helpers
-
-- **`get_price({ fiat? })`** / **`fiat_to_sats({ amount, currency })`** —
-  for "how many sats is €10" style sub-questions before a Spark spend.
-
-## Cross-skill flow with Bitrefill
-
-When the user wants to buy something from Bitrefill and pay with Spark, the
-typical chain is:
-
-1. Call `bitrefill_search` / `bitrefill_get_product` to confirm the product +
-   the right `package_id` (see the `bitrefill` skill).
-2. Call `bitrefill_create_invoice({ products, payment_method: "lightning",
-   refund_address: <a Spark or on-chain address> })` — Bitrefill returns a
-   BOLT11 invoice on the response under `payment.lightning_invoice` (or
-   similar — relay whatever the host surfaces).
-3. **Pay with Spark**: `spark_pay_invoice({ invoice: <that BOLT11> })`. One
-   confirmation gate; Spark settles the invoice in seconds.
-4. Poll `bitrefill_get_invoice` until `status:"complete"`, then
-   `bitrefill_get_order` for the redemption code.
-
-If the user pre-funded a Bitrefill account, prefer
-`payment_method:"balance"` instead — no Spark spend, instant settlement. Use
-the Lightning path when the user explicitly says "pay with Spark/Lightning"
-or has no Bitrefill balance.
-
-## Reply style
-
-- One short sentence per fact ("Spark holds 124,500 sats.").
-- For invoices: show the invoice on its own line so the user can copy it.
-- For sends: one-line pre-spend summary (amount + destination + "from
-  Spark"), then the result.
-- When `spark_get_balance` says zero and the user asked to spend, stop and
-  say so — don't try to source funds from another layer silently.
+Spark holds BTC (sats) and Spark-native tokens such as USDB. RGB assets (USDT,
+XAUT) live on the RGB Lightning Node, not on Spark.
+
+## Do
+- Balance: `spark_get_balance` returns `total` sats and `tokens[]`; report
+  both. `total: 0` with `connected: true` is an empty wallet, not an error.
+- Three different "addresses" — pick by intent and check the prefix:
+  - Spark-to-Spark receive → `spark_get_address` (`spark1…`/`sparkrt1…`, off-chain).
+  - Deposit on-chain BTC → `spark_get_onchain_address` (`bc1…`/`tb1…`/`bcrt1…`).
+  - Receive over Lightning → `spark_create_invoice` (`lnbc…`/`lntb…`).
+- Pay a BOLT11 invoice → `spark_pay_invoice`; pass `amount_sats` only for an
+  amount-less invoice. On-chain address → `spark_send`. Both are
+  confirm-gated.
+- If a tool errors with "not connected", say so; don't switch layers.
+
+## Examples
+- "Spark balance?" → `spark_get_balance {}`
+- "Address to deposit BTC into Spark" → `spark_get_onchain_address {}`
+- "Invoice for 1500 sats" → `spark_create_invoice {"amount_sats":1500}`
+- "Pay lnbc12540n1p…" → `spark_pay_invoice {"invoice":"lnbc12540n1p…"}`
+- "Send 20000 sats to bc1q…" → `spark_send {"amount_sats":20000,"to":"bc1q…"}`