@kaleidorg/mind 0.5.1 → 0.6.1

package/skills/flashnet-swaps/SKILL.md

@@ -0,0 +1,158 @@
+---
+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
+metadata:
+  author: kaleidoswap
+  version: "1.0.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.

package/skills/kaleido-lsps/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: kaleido-lsps
 description: "Buy inbound Lightning channel capacity from a Lightning Service Provider (LSPS1). Quote a channel, estimate fees, place a channel order, and check order status. Triggers when the user wants inbound liquidity, says they can't receive a payment, needs a channel, asks about LSP fees, or wants to check the status of a channel order / LSP order."
-tools: lsp_get_info, lsp_get_network_info, lsp_estimate_fees, lsp_create_order, lsp_get_order, rln_get_node_info, rln_pay_invoice
-triggers: inbound, liquidity, channel order, lsp, lsps1, receive limit, can't receive, open channel, channel from, check status, order status, check the order, channel status, lsp status, check my channel
+tools: lsp_get_info, lsp_get_network_info, lsp_estimate_fees, lsp_create_order, lsp_get_order, 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, rln_get_node_info, rln_list_channels, rln_pay_invoice
+triggers: inbound, liquidity, channel order, lsp, lsps1, receive limit, can't receive, open channel, channel from, check status, order status, check the order, channel status, lsp status, check my channel, check lsp order, did the channel open, lsp order status, list my channels, my channels, channel capacity
 metadata:
   author: kaleidoswap
   version: "0.2.0"
@@ -21,11 +21,11 @@ talks to — the KaleidoSwap maker by default. Tool names are LSP-agnostic
 You have **no knowledge** of LSP capabilities, fees, channel sizes, or order
 status. Every number, capacity, fee, order id, or invoice in your reply MUST
 come from a tool result returned in the CURRENT turn. Never quote a fee from
-memory. Never claim an order completed without calling `lsp_get_order`.
+memory. Never claim an order completed without calling `kaleidoswap_lsp_get_order`.
 Never reuse a number from a previous turn.
 
 **Calling the tool IS the answer.** Don't write "the LSP info is fetched with
-`lsp_get_info`" — call it. Don't reveal tool names in your reply; describe
+`kaleidoswap_lsp_get_info`" — call it. Don't reveal tool names in your reply; describe
 what you're doing in plain language.
 
 If a tool needs a required argument the user didn't give (e.g. `client_pubkey`
@@ -40,7 +40,7 @@ The same conventions as trading apply:
 
 ## Tools and the flow
 
-### Step 1 — `lsp_get_info`
+### Step 1 — `kaleidoswap_lsp_get_info`
 No args. Returns the LSP's `OrderOptions` (min/max channel size, min/max
 expiry, etc.) and the `assets` list. **Call it once before estimating** so you
 can validate the user's request against the LSP's limits.
@@ -49,7 +49,7 @@ If the user wants 1M sats inbound but `max_initial_lsp_balance_sat` is 500k,
 say so plainly and offer the maximum — don't push through and let the maker
 reject it.
 
-### Step 2 — `lsp_estimate_fees` (read-only)
+### Step 2 — `kaleidoswap_lsp_estimate_fees` (read-only)
 Required args: `lsp_balance_sat`, `client_balance_sat`, `channel_expiry_blocks`.
 
 Defaults you can use silently if the user didn't specify:
@@ -60,10 +60,10 @@ Returns `{setup_fee, capacity_fee, duration_fee, total_fee}` — surface
 `total_fee` to the user and the breakdown when relevant.
 
 ### Step 3 — `rln_get_node_info`
-No args. Returns `{pubkey, ...}`. **Pubkey is required by `lsp_create_order` —
+No args. Returns `{pubkey, ...}`. **Pubkey is required by `kaleidoswap_lsp_create_order` —
 fetch it deterministically. Never invent a pubkey.**
 
-### Step 4 — `lsp_create_order` 🔒 spend
+### Step 4 — `kaleidoswap_lsp_create_order` 🔒 spend
 Required args: `client_pubkey` (from step 3), `lsp_balance_sat`. The maker
 also expects `client_balance_sat`, `required_channel_confirmations`,
 `funding_confirms_within_blocks`, `channel_expiry_blocks`, `announce_channel`
@@ -72,7 +72,7 @@ didn't specify, so just pass the values the user actually named.
 
 Returns:
 - `order_id`
-- `access_token` (save it — required for `lsp_get_order`)
+- `access_token` (save it — required for `kaleidoswap_lsp_get_order`)
 - `payment.bolt11.invoice` — Lightning invoice to pay
 - `payment.bolt11.order_total_sat` — the sats that need to flow
 - `payment.onchain.address` — optional on-chain fallback
@@ -82,11 +82,26 @@ Returns:
 Hand the `payment.bolt11.invoice` to `rln_pay_invoice`. This is a separate
 spend gate at the wallet contract; the user confirms paying the LSP.
 
-### Step 6 — `lsp_get_order` (poll)
-**Args: `order_id`, `access_token` (BOTH required — never omit either).**
-`order_state` progresses `CREATED → CHANNEL_OPENING → COMPLETED` (or `FAILED`).
-Poll until terminal. Always pass the exact order_id and access_token from the
-previous `lsp_create_order` result (or from the summary that listed them).
+### Verify the opened channel — `rln_list_channels`
+After an order completes (or when the user asks "do I have a channel with X
+inbound?", "list my channels", "did my channel open?"), call
+`rln_list_channels`. It returns each channel's `capacity_sat`, `inbound_sat`,
+`outbound_sat`, `ready`/`status`, and RGB `asset_*` amounts. Match the
+requested capacity against an actual channel to confirm it opened correctly.
+A freshly-bought channel opens ASYNCHRONOUSLY — if it isn't listed yet, say
+it's still opening, don't claim failure. Do NOT use `rln_get_node_info` for
+this (it only has counts + aggregate balance, not per-channel capacity).
+
+### Step 6 — poll the order (`lsp_get_order` / `kaleidoswap_lsp_get_order`)
+Use `lsp_get_order` on CLI hosts, `kaleidoswap_lsp_get_order` on desktop —
+whichever your host exposes. **Args: `order_id`, `access_token` (BOTH
+required — never omit either).** `order_state` progresses
+`CREATED → CHANNEL_OPENING → COMPLETED` (or `FAILED`). Poll until terminal.
+Always pass the exact order_id and access_token from the previous
+create-order result **or from the most recent assistant message/summary**
+(the one that said something like "order_id=xxx access_token=yyy" or "To
+check status use: lsp_get_order(order_id=..., access_token=...)"). If
+memory/remember is available, first recall the last LSPS1 order details.
 Report the outcome plainly with the new channel id from `channel.channel_id` if present.
 
 ## Don'ts
@@ -97,11 +112,13 @@ Report the outcome plainly with the new channel id from `channel.channel_id` if
 - Don't describe how a tool works — call it.
 - Don't pay a Lightning invoice without confirming the amount + LSP — the
   spend gate at `rln_pay_invoice` shows the user the destination.
-- Don't claim an order completed without polling `lsp_get_order` with BOTH
+- Don't claim an order completed without polling `kaleidoswap_lsp_get_order` with BOTH
   `order_id` and `access_token` and seeing `order_state: COMPLETED`.
-- Never call `lsp_get_order` with only the access_token or only the order_id.
+- Never call `kaleidoswap_lsp_get_order` with only the access_token or only the order_id.
   Always extract the exact values from the previous turn's summary (the one that
-  said "order_id=... access_token=...") and pass them as separate arguments.
+  said "order_id=... access_token=..." or the explicit "To check status use..." line)
+  and pass them as separate arguments. If using the `remember` tool, first recall
+  the last channel/LSPS1 order details.
 - Don't ask the user for their node pubkey — fetch it from `rln_get_node_info`.
 
 ## When the deterministic recipe handles it

package/skills/kaleido-trading/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: kaleido-trading
-description: "Trade on KaleidoSwap — quote and execute swaps between BTC and RGB assets (USDT, XAUT). Get assets and pairs, pull an executable quote, place a market order, or track an atomic swap end-to-end. Triggers when the user wants a quote, to swap or trade assets, or to rebalance between BTC and stablecoins."
-tools: kaleidoswap_get_assets, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_get_nodeinfo, kaleidoswap_place_order, kaleidoswap_get_order_status, kaleidoswap_get_order_history
-triggers: quote, swap, trade, rebalance, slippage, pair, pairs, usdt, xaut, kaleidoswap, rfq
+description: "Trade on KaleidoSwap — quote and execute swaps between BTC and RGB assets (USDT, XAUT). Get assets and pairs, pull an executable quote, place a market order, track orders, or run/poll an atomic swap end-to-end. Triggers when the user wants a quote, to swap or trade assets, to rebalance between BTC and stablecoins, or to check the status of an order / swap / atomic swap."
+tools: kaleidoswap_get_assets, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_place_order, kaleidoswap_get_order_status, kaleidoswap_atomic_init, kaleidoswap_atomic_execute, kaleidoswap_atomic_status, rln_get_node_info, rln_atomic_taker
+triggers: quote, swap, trade, rebalance, slippage, pair, pairs, usdt, xaut, kaleidoswap, rfq, check status, order status, check the order, swap status, check my swap, atomic status
 metadata:
   author: kaleidoswap
   version: "0.4.0"
@@ -40,15 +40,28 @@ which pair + amount.
 
 ## Asset codes (canonical)
 
+KaleidoSwap is the maker for **BTC ↔ RGB asset** atomic swaps. The asset
+family is **RGB**: USDT, XAUT, and any other RGB asset the maker prices.
+The RGB assets live on the user's **RLN** (RGB Lightning Node) — NOT on
+Spark, Arkade, or any other chain.
+
 Only these codes are accepted:
 
 - `BTC` (Bitcoin, amounts always in satoshis)
-- `USDT` (Tether) — **not** `USD`, **not** `tether`
-- `XAUT` (Tether Gold) — **not** `XAU`, **not** `gold`
+- `USDT` (Tether, the RGB asset) — **not** `USD`, **not** `tether`
+- `XAUT` (Tether Gold, the RGB asset) — **not** `XAU`, **not** `gold`
 
 When the user types `USD` they almost always mean `USDT` — confirm before
 quoting. Same for `gold` → `XAUT`. Don't silently substitute.
 
+**Do NOT trade here:**
+
+- `USDB` and any other **Spark-native token** — those are on the Spark
+  layer and trade on **Flashnet** (skill: `flashnet-swaps`), not on
+  KaleidoSwap. Route the user there instead of inventing a maker pair.
+- Tokens from external chains (Ethereum USDT, Solana, etc.). They are
+  not in the maker's catalog and the wallet does not custody them.
+
 ## Tools
 
 ### `kaleidoswap_get_pairs` — no args
@@ -113,13 +126,16 @@ Only after `kaleidoswap_get_quote` returned an `rfq_id` THIS turn, and only when
 the user has explicitly approved the amount + direction. Pass the `rfq_id` as
 `quote_id`.
 
-**Save the `order_id` AND `access_token` from the result** — you will need both
-for polling status later.
+**Save the `order_id` AND `access_token` from the result** (BOTH required — never omit either). Extract them verbatim from the tool result (or the most recent assistant summary that listed "order_id=... access_token=..."). If memory/remember is available, first recall the last order details before polling status. You will need both for `kaleidoswap_get_order_status` later.
 
 ### `kaleidoswap_get_order_status(order_id, access_token)`
-Poll after placing an order. **Pass both the order_id and the access_token**
-(saved from place_order). Report status plainly — pending, settling,
-completed, failed.
+**Args: `order_id`, `access_token` (BOTH required — never omit either).**
+Poll after placing an order (or atomic). `order_state` (or equivalent) progresses
+to terminal states. Always pass the exact values from the previous
+`kaleidoswap_place_order` result **or from the most recent assistant message/summary**
+(the one that said something like "order_id=xxx access_token=yyy" or "To check status use: kaleidoswap_get_order_status(order_id=..., access_token=...)").
+If memory/remember is available, first recall the last order/swap details.
+Report the outcome plainly.
 
 ## Flow
 
@@ -128,11 +144,11 @@ completed, failed.
 3. **Read + present** — compute the receive amount + fee from the response (see
    "Reading the quote response"). **Never hide cost.**
 4. **Place** — spend-gated by the engine. The host pauses for the user.
-5. **Track** — poll `kaleidoswap_get_order_status(order_id, access_token)` (use both values saved from place_order) until it terminates.
+5. **Track** — poll `kaleidoswap_get_order_status(order_id, access_token)` (use both values saved from place_order or the explicit "To check status..." template) until it terminates. For atomic swaps the status tool is `kaleidoswap_atomic_status(atomic_id)`.
 
 ## Don'ts
 
-- Don't invent prices, quotes, rfq_ids, or order_ids.
+- Don't invent prices, quotes, rfq_ids, order_ids, or access_tokens.
 - Don't reuse a number from a previous turn.
 - Don't describe how a tool works — call it.
 - Don't call `kaleidoswap_get_quote` with from/to only — ask for the amount.
@@ -142,7 +158,15 @@ completed, failed.
 - Don't accept `XAU` as `XAUT` or `USD` as `USDT` silently — confirm.
 - Don't retry the same failing tool call in a loop. If a call fails, read the
   error and either ask the user, fix the args, or stop.
+- Don't claim an order completed without polling the status tool with BOTH
+  required ids/tokens and seeing a terminal state.
+- Never call `kaleidoswap_get_order_status` with only the access_token or only
+  the order_id. Always extract the exact values from the previous turn's summary
+  (the one that said "order_id=... access_token=..." or the explicit "To check
+  status use..." line) and pass them as separate arguments. If using the
+  `remember` tool, first recall the last order details.
 
 For the full atomic-swap flow (init → whitelist on the RGB node → execute), a
 deterministic recipe drives the chain — the agentic loop is not safe to plan a
-multi-step, two-service swap on a small model.
+multi-step, two-service swap on a small model. Status for atomics uses the
+`atomic_id` (or payment_hash) surfaced in the recipe summary.

package/skills/liquidity-optimizer/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: liquidity-optimizer
+description: "Analyze and optimize the node's Lightning liquidity. Reads channels, balances and payment history, then explains the node's liquidity health and recommends concrete actions: buy inbound, open/close channels, rebalance BTC↔assets, or tune routing fees. Triggers when the user wants to rebalance, optimize liquidity, fix inbound/outbound balance, free up capital, lower fees, or asks 'how healthy is my node?' / 'where is my liquidity?'."
+tools: rln_list_channels, rln_get_balances, rln_get_node_info, rln_list_payments, kaleidoswap_lsp_get_info, kaleidoswap_lsp_estimate_fees, kaleidoswap_lsp_quote_asset_channel, rln_open_channel, rln_close_channel
+triggers: rebalance, rebalancing, optimize liquidity, liquidity, inbound, outbound, lopsided, depleted channel, free up capital, stuck funds, channel balance, routing fee, lower fees, fee optimization, node health, healthy node, where is my liquidity, capacity
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+---
+
+# Liquidity optimizer
+
+Help the user keep their RGB Lightning node's liquidity healthy: balanced
+inbound/outbound, capital not stuck in dead channels, and fees set so the node
+can actually route and receive. You **analyze real channel state and recommend
+actions** — you never move funds without an explicit, confirmed instruction.
+
+## Critical rules — these override everything else
+
+You have **no knowledge** of the node's channels, balances, or capacity. Every
+number, channel id, ratio, or fee in your reply MUST come from a tool result
+returned in the CURRENT turn. Never quote a balance from memory or reuse a
+number from a previous turn — re-read it.
+
+**Calling the tool IS the analysis.** Don't say "I'd check your channels with
+`rln_list_channels`" — call it, then report what it returned in plain language.
+Don't reveal raw tool names in your reply.
+
+**Read freely, spend never (without confirmation).** `rln_list_channels`,
+`rln_get_balances`, `rln_get_node_info`, `rln_list_payments`,
+`kaleidoswap_lsp_get_info`, and `kaleidoswap_lsp_estimate_fees` are read-only —
+use them as much as you need. `rln_open_channel`, `rln_close_channel`, and
+buying a channel are **spends**: only call them when the user explicitly asked
+for that action this turn, and each goes through the wallet's confirmation gate.
+When you merely *recommend* an action, describe it — do not execute it.
+
+## How to assess liquidity
+
+### 1 — Read the state (always start here)
+- `rln_list_channels` → `channel_count`, `total_outbound_msat`,
+  `total_inbound_msat`, and per-channel `outbound_balance_msat`,
+  `inbound_balance_msat`, `is_usable`, capacity, peer, and any RGB asset
+  allocation. **Balances are in millisats (msat); divide by 1000 for sats.**
+- `rln_get_balances` → on-chain (vanilla/colored) + Lightning balance, to see
+  uncommitted capital that could open a channel.
+- `rln_get_node_info` → pubkey, peer/channel counts, sync state.
+- `rln_list_payments` (optional) → recent flow direction, to infer whether the
+  node mostly sends or receives.
+
+### 2 — Compute the picture (per channel and overall)
+For each channel, the **outbound ratio** = `outbound / (outbound + inbound)`:
+- **~0% (all inbound):** can receive but can't send — depleted outbound.
+- **~100% (all outbound):** can send but can't receive — no inbound liquidity.
+- **40–60%:** balanced and healthy.
+Then look at the totals: is the node short on **inbound** (can't receive) or
+short on **outbound** (can't send)? Flag channels that are `is_usable: false`
+(offline/pending peer) or that hold meaningful capital but never route.
+
+### 3 — Recommend, prioritized
+Lead with a one-line health verdict, then a short ordered action list. Match the
+remedy to the problem:
+- **Low inbound / "can't receive":** buy inbound from the LSP. Use
+  `kaleidoswap_lsp_get_info` for limits and `kaleidoswap_lsp_estimate_fees`
+  (or `kaleidoswap_lsp_quote_asset_channel` for an asset channel) to give a real
+  fee, then hand off to the channel-order flow. Don't invent the fee.
+- **Low outbound / "can't send":** open a channel to a well-connected peer with
+  spare on-chain BTC (`rln_open_channel`), or fund the wallet first.
+- **Lopsided but funded both ways:** rebalance instead of opening new channels —
+  for BTC↔asset imbalance, suggest a swap (the trading flow), since circular
+  rebalancing may not be available on this node.
+- **Dead/offline channels with stuck capital:** consider closing
+  (`rln_close_channel`) to reclaim funds, but only if the user confirms — note
+  on-chain fees and the ~hours for funds to settle.
+- **Fees:** if the node should route more, suggest lower routing fees; if it's
+  draining outbound cheaply, suggest raising them. If no fee-setting tool is
+  available this turn, give the recommendation and tell the user where to set it
+  rather than pretending you changed it.
+
+## Output style
+Concise and scannable. A verdict line, then "Top actions" as a short numbered
+list with the concrete number behind each (e.g. "Channel abc12… is 97% outbound
+— buy ~200k inbound, est. fee from the LSP"). No walls of JSON.
+
+## Don'ts
+- Don't invent channels, balances, ratios, capacities, or fees — read them.
+- Don't forget msat→sat conversion when reporting channel balances.
+- Don't open or close a channel, or buy liquidity, unless the user asked for
+  that action this turn — recommendations are not actions.
+- Don't claim you changed fees or rebalanced if no tool did it — say what the
+  user should do.
+- Don't reuse last turn's numbers — re-read before advising again.

package/skills/merchant-finder/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: merchant-finder
 description: "Find Bitcoin-accepting merchants near the user using live BTC Map data and the device's real location. Triggers when the user asks where to spend Bitcoin, buy pizza/food with sats or bitcoin, eat at restaurants/cafes paying with sats, for a shop, store, restaurant, cafe, bar, or ATM that accepts Bitcoin, or for merchants nearby or in a city like turin."
-tools: find_merchant_locations
-triggers: merchant, merchants, shop, shops, store, stores, restaurant, restaurants, cafe, cafes, bar, bars, atm, atms, accept, accepts, accepting, nearby, near me, around, place, places, spend, find, pizza, pizz, food, coffee, eat, dinner, lunch, buy, bitcoin map, btcmap
+tools: find_merchant_locations, search_knowledge
+triggers: merchant, merchants, shop, shops, store, stores, restaurant, restaurants, cafe, cafes, bar, bars, atm, atms, accept, accepts, accepting, nearby, near me, around me, where can i spend, pizza, pizz, food, coffee, eat, dinner, lunch, bitcoin map, btcmap
 metadata:
   author: kaleidoswap
   version: "0.3.0"

package/skills/portfolio-manager/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: portfolio-manager
+description: "Keep a BTC / USDT / XAUT portfolio near its target allocation. Read live balances and prices, detect drift versus targets, and (when allowed) rebalance via an atomic swap on KaleidoSwap. Triggers when the user asks to rebalance, check allocation, review the portfolio, or optimize holdings — and is the skill the scheduled 'rebalance' loop runs."
+tools: rln_get_balances, rln_list_assets, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_atomic_init, kaleidoswap_atomic_execute, kaleidoswap_atomic_status, get_price, get_market_data
+triggers: rebalance, allocation, portfolio, drift, optimize, target, weighting, holdings
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+---
+
+# Portfolio manager
+
+Keep the holdings near their target weights across **BTC**, **USDT**, and
+**XAUT**. You fetch everything live — never assume a balance, price, or target.
+
+## Critical rules — these override everything else
+
+- **Read before you act.** Get balances (`rln_get_balances`) and prices
+  (`get_price`) every run. Never reuse a number from a previous turn.
+- **Respect `dry_run`.** When `dry_run` is true you describe the rebalance you
+  *would* make — you do NOT call `kaleidoswap_atomic_init`/`_execute`. This is
+  non-negotiable.
+- **Respect fund safety.** Never propose a swap that breaches the BTC reserve or
+  stop-loss floor passed in the task parameters. The host's risk gate is the
+  final word, but don't even suggest a breach.
+- **Below-minimum drift = do nothing.** If every asset is within the drift
+  threshold, say so and stop. Churn is a cost, not a feature.
+
+## How to think about a rebalance
+
+1. **Snapshot.** `rln_get_balances` → BTC sats + each RGB asset (raw units).
+2. **Value it.** Convert each holding to a common denomination using
+   `get_price`. Do NOT do arithmetic free-hand on raw RGB units — use the
+   display fields the tools return; only convert sats↔USD with the live BTC
+   price.
+3. **Compare to targets.** Targets come in the task parameters (e.g.
+   `BTC 70 / USDT 20 / XAUT 10`). Compute each asset's current weight and its
+   drift = current − target.
+4. **Decide.** If the largest drift exceeds the threshold, the over-weight asset
+   sells into the most under-weight asset. One swap per run — smallest trade
+   that brings the worst drift back inside the band.
+5. **Quote.** `kaleidoswap_get_quote(from, to, amount)` for that single leg.
+6. **Execute** (only when `dry_run` is false and the size is within limits): the
+   atomic swap recipe drives `kaleidoswap_atomic_init` → `_execute`; then poll
+   `kaleidoswap_atomic_status`.
+
+## Asset codes (canonical)
+
+`BTC` (satoshis), `USDT` (not `USD`), `XAUT` (not `XAU`/gold).
+
+## Scheduled (background) runs
+
+When run by the `rebalance` loop, after deciding, return STRICT JSON only:
+
+```
+{"task":"rebalance","timestamp":"<ISO8601>","action":"rebalance|noop","dry_run":<bool>,"reason":"<why>","details":{"from":"<asset>","to":"<asset>","amount":"<n>","drift":{}}}
+```
+
+`action` is `noop` when within band. Put the human explanation in `reason`.
+
+## Don'ts
+
+- Don't invent prices, quotes, or balances — call the tool.
+- Don't rebalance on noise — honor the drift threshold.
+- Don't place more than one swap per run.
+- Don't breach the reserve / stop-loss, ever.
+- Don't execute anything when `dry_run` is true.

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

@@ -1,8 +1,8 @@
 ---
 name: rgb-lightning-node
-description: "Drive the user's local RGB Lightning Node (RLN) — read its pubkey/status, whitelist a swap, or create Lightning/RGB receive invoices. Triggers when the user asks about the node, needs an invoice, or is mid-atomic-swap and the maker needs the node pubkey or a swapstring whitelisted."
-tools: rln_get_node_info, rln_whitelist_swap, rln_create_ln_invoice, rln_create_rgb_invoice
-triggers: node, nodeinfo, pubkey, peer, channels, whitelist, taker, swapstring, invoice, receive, rgb invoice, ln invoice
+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, 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_open_channel, rln_close_channel, rln_connect_peer, rln_get_channel_id, rln_whitelist_swap, rln_atomic_taker, rln_list_payments, rln_create_ln_invoice, rln_create_rgb_invoice
+triggers: node, nodeinfo, pubkey, peer, channels, channel capacity, list channels, inbound, capacity, asset balance, whitelist, taker, swapstring, invoice, receive, rgb invoice, ln invoice
 metadata:
   author: kaleidoswap
   version: "0.1.0"
@@ -47,12 +47,39 @@ Call this when:
   `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, not yours). For "how much can I receive?",
-the LSPS skill answers what's available to BUY (`lsp_get_info`); the current
-remote-balance breakdown isn't exposed by this skill's tools.
-
-### `rln_whitelist_swap` — { swapstring } — 🔒 confirm-gated
+**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` — no args
+Lists RGB assets known to the node with per-asset balances (settled, future,
+spendable, offchain_outbound, offchain_inbound). Use for "what assets do I
+hold / what's my USDT balance".
+
+### `rln_get_asset_balance` — { asset_id }
+Balance for one RGB asset by id. Use after `rln_list_assets` gave you the id,
+or when the user names a specific asset.
+
+### `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
@@ -90,9 +117,9 @@ A user-driven swap on KaleidoSwap is a two-service flow. Keep them straight:
 | 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_whitelist_swap` (pass the swapstring) |
+| Whitelist | **node** | `rln_atomic_taker` (pass the swapstring) |
 | Execute | maker | `kaleidoswap_atomic_execute` (needs swapstring + taker_pubkey + payment_hash) |
-| Status | maker | `kaleidoswap_atomic_status` |
+| 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