@kaleidorg/mind 0.8.1 → 0.10.0

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"}`

package/skills/kaleido-trading/SKILL.md

@@ -1,179 +1,35 @@
 ---
 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, 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 a swap / atomic swap."
-tools: kaleidoswap_get_assets, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_atomic_init, kaleidoswap_atomic_execute, kaleidoswap_atomic_status, rln_get_node_info, rln_atomic_taker, rln_refresh_transfers, rln_get_asset_balance, rln_list_channels, rln_list_swaps, rln_get_swap
-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
+description: "Quote and run KaleidoSwap atomic swaps between BTC and RGB assets (USDT, XAUT): pairs, assets, quotes, swap execution and swap status."
+tools: kaleidoswap_get_pairs, kaleidoswap_get_assets, kaleidoswap_get_quote, kaleidoswap_atomic_init, rln_atomic_taker, rln_get_node_info, kaleidoswap_atomic_execute, kaleidoswap_atomic_status, rln_refresh_transfers
+requires-tools: kaleidoswap_get_quote
+triggers: quote, swap, trade, pair, pairs, usdt, xaut, kaleidoswap, rfq, atomic, swap status
 metadata:
   author: kaleidoswap
-  version: "0.5.0"
+  version: "0.6.0"
 ---
-
 # KaleidoSwap trading
 
-Quote and execute swaps on the KaleidoSwap maker. The model picks tools by
-name; the host binds them through whichever transport it runs over (WDK on
-mobile, HTTP/MCP/CLI on desktop).
-
-## Critical rules — these override everything else
-
-You have **no knowledge** of any price, quote, fee, pair, or order. Every
-number, pair, or quote id in your reply MUST come from a tool result returned
-in the CURRENT turn:
-
-- "What pairs are listed?" → call `kaleidoswap_get_pairs` and list them.
-- "Quote 100k sats to USDT" → call `kaleidoswap_get_quote(BTC, USDT, 100000)`,
-  then state the receive amount + fee from the result.
-
-**Calling the tool IS the answer.** Never write "the pairs are listed using
-kaleidoswap_get_pairs" or "the function returns the quote" — just call it.
-
-**Never reuse a number across turns.** If the user asks a new question, the
-previous turn's quote, price, or fee is irrelevant — fetch fresh.
-
-**Never invent a quote.** Without an `rfq_id` and a `to_asset.amount` returned
-this turn, you do not have a quote. Say so and re-quote.
-
-This skill is for tradeable pair quotes on the maker. It does NOT do generic
-"what is bitcoin worth in USD" spot prices — that's the wallet's job. If the
-user asks for a plain BTC price (not a swap), say you can quote a swap and ask
-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, 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
-Use when the user asks "what can I trade", "list pairs", "what's available",
-or before quoting an unfamiliar pair.
-
-### `kaleidoswap_get_quote` — REQUIRES `amount`
-Required args: `from_asset` AND `to_asset` AND `amount`. The maker rejects a
-quote that has no amount.
-
-**If the user didn't give an amount, ASK for it. Do NOT call the tool with
-from/to alone, and do NOT make up an amount.**
-
-`amount` is in the smallest unit of `from_asset`. Use the EXACT number the user
-typed (scaled if they used "k"/"m"/"M" shorthand: 100k → 100000, 2m → 2000000).
-**Never** copy an amount from a previous turn or from these instructions.
-
-Critical unit-and-leg anchor:
-- If the user says **sats** or **satoshis** anywhere, the BTC leg is implied
-  (sats = the smallest unit of BTC). `BTC` is always `from_asset` OR `to_asset`
-  depending on the verb.
-- "X sats TO Y" → `from_asset: "BTC"`, `to_asset: "Y"`, `amount: X-as-sats`.
-- "X Y TO BTC" (Y ∈ {USDT, XAUT}) → `from_asset: "Y"`, `to_asset: "BTC"`,
-  `amount: X-in-Y-units`.
-- "buy Z of A with B" → spent = B → `from_asset: "B"`, received = A → `to_asset: "A"`,
-  `amount: <amount of B the user wants to spend>`.
-- "rate of X to Y" with NO number → no amount → ASK: "How much do you want to
-  swap?" → do NOT call the tool yet.
-
-### Reading the quote response
-
-`kaleidoswap_get_quote` returns ready-to-read display fields — **use them
-verbatim. Do NOT do any arithmetic yourself.** The response looks like:
-
-```
-{
-  "rfq_id": "<id>",
-  "from_amount_display": "100,000 BTC-sats",   ← what the user spends
-  "to_amount_display":   "0.063176 USDT",       ← what the user receives
-  "fee_display":         "0.000638 USDT",        ← the fee
-  "expires_at": <epoch>,
-  ...raw numeric fields you should ignore...
-}
-```
-
-To state the answer, copy the strings:
-- Receive amount → `to_amount_display`.
-- Fee → `fee_display`.
-- `rfq_id` is the quote handle (needed to start the atomic swap), short-lived (~60s) —
-  mention it expires soon.
-
-**Read `to_amount_display` / `fee_display` exactly as given.** Do NOT compute
-`amount ÷ 10^precision`, do NOT restate the raw `price`/`amount` integers, and
-do NOT copy the numbers from this document — they are placeholders. The only
-correct numbers are the `*_display` strings in the CURRENT tool result.
-
-A good reply: *"100,000 sats → <to_amount_display> (fee <fee_display>). Quote
-<rfq_id> is valid ~60s — want me to place it?"*
-
-### `kaleidoswap_atomic_init` 🔒 spend
-Only after `kaleidoswap_get_quote` returned an `rfq_id` THIS turn, and only when
-the user has explicitly approved the amount + direction. Starts the atomic
-swap from that quote; the rest of the chain (`rln_atomic_taker` →
-`kaleidoswap_atomic_execute` → `kaleidoswap_atomic_status`) is described
-below and in `references/atomic.md`.
-
-### `kaleidoswap_atomic_status`
-Poll after executing an atomic swap until it reaches a terminal state
-(completed / failed / expired). Pass the exact ids returned by
-`kaleidoswap_atomic_init` (or surfaced in the most recent swap summary) — never
-invent them. Report the outcome plainly.
-
-## Flow
-
-1. **Pick a pair** — skip when obvious (`BTC/USDT`, `BTC/XAUT`).
-2. **Quote** — `kaleidoswap_get_quote`. REQUIRES amount; ask if missing.
-3. **Read + present** — compute the receive amount + fee from the response (see
-   "Reading the quote response"). **Never hide cost.**
-4. **Swap** — `kaleidoswap_atomic_init` → `rln_atomic_taker` →
-   `kaleidoswap_atomic_execute`. Spend-gated by the engine; the host pauses for
-   the user.
-5. **Track** — poll `kaleidoswap_atomic_status` with the ids from
-   `kaleidoswap_atomic_init` until it terminates.
-
-## Don'ts
-
-- Don't invent prices, quotes, rfq_ids, swap 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.
-- Don't make up an amount the user didn't give.
-- Don't do unit math or restate raw integers — read the `*_display` strings.
-- Don't copy numbers from the skill docs — only the current tool result is real.
-- 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 a swap completed without polling `kaleidoswap_atomic_status`
-  and seeing a terminal state.
-
-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. Status for atomics uses the
-`atomic_id` (or payment_hash) surfaced in the recipe summary.
-
-## Over kaleido-mcp (desktop, Claude Code)
-
-kaleido-mcp 0.3.0+ is **atomic-only**. Its quote takes `from_asset_id` / `from_layer` /
-`from_amount` (display units) and returns `amount_raw` values that
-`kaleidoswap_atomic_init` takes unchanged. The full chain is quote →
-`kaleidoswap_atomic_init` → `rln_atomic_taker` + `rln_get_node_info` →
-`kaleidoswap_atomic_execute` → poll `kaleidoswap_atomic_status` →
-`rln_refresh_transfers`. Read `references/atomic.md` before the first swap,
-and `references/assets.md` for units and precision. Always follow the
-argument names in the tool schema you were given.
-
+Amounts in `kaleidoswap_get_quote` are **display units**: `from_amount: 0.0005`
+means 0.0005 BTC (50,000 sats; 1 BTC = 100,000,000 sats). Asset ids accept a
+ticker (`BTC`, `USDT`, `XAUT`) or an `rgb:…` id.
+
+## Do
+- Quote with exactly one amount: `from_amount` to sell a fixed input,
+  `to_amount` to buy a fixed output. No amount given → ask for one.
+- Report `from_asset.amount_display`, `to_asset.amount_display` and
+  `expires_at` as given; `price` is in the maker's raw units, don't quote it.
+  The quote expires in about 60 s.
+- Executing a swap moves funds: only after the user says yes to that quote.
+  Chain: `kaleidoswap_atomic_init` (rfq_id, both asset ids, both `amount_raw`
+  values unchanged) → `rln_atomic_taker` (swapstring) → `rln_get_node_info`
+  (pubkey) → `kaleidoswap_atomic_execute` → poll `kaleidoswap_atomic_status`.
+  Details and errors: `references/atomic.md`.
+- `USD` is not `USDT` and `gold` is not `XAUT`: confirm before quoting.
+  Spark tokens such as USDB trade on Flashnet (`flashnet-swaps`), not here.
+
+## Examples
+- "Quote 0.0005 BTC to USDT" → `kaleidoswap_get_quote {"from_asset_id":"BTC","to_asset_id":"USDT","from_amount":0.0005}`
+- "Swap 100k sats into XAUT" → `kaleidoswap_get_quote {"from_asset_id":"BTC","to_asset_id":"XAUT","from_amount":0.001}`
+- "I want to receive 10 USDT, how much BTC?" → `kaleidoswap_get_quote {"from_asset_id":"BTC","to_asset_id":"USDT","to_amount":10}`
+- "Status of swap 9f2c…" → `kaleidoswap_atomic_status {"payment_hash":"9f2c…"}`

package/skills/kaleido-trading/references/assets.md

@@ -40,10 +40,10 @@ Read precision from the API; the table is illustrative.
 
 | Tool | Units |
 |---|---|
-| `kaleidoswap_get_quote` (kaleido-mcp) | display (`0.001` BTC, `65.0` USDT) |
-| `kaleidoswap_atomic_init` (kaleido-mcp) | raw: pass `quote.*.amount_raw` unchanged |
-| `kaleidoswap_get_quote` (in-app contract) | sats for BTC, asset units otherwise |
-| `rln_send_asset` / `rln_create_rgb_invoice` (kaleido-mcp) | display units |
+| `kaleidoswap_get_quote` | display (`0.001` BTC, `65.0` USDT) |
+| `kaleidoswap_atomic_init` | raw: pass `quote.*.amount_raw` unchanged |
+| `rln_send_asset` / `rln_create_rgb_invoice` / `rln_issue_asset` | display units |
+| `rln_list_assets` / `rln_get_asset_balance` balances | raw: divide by 10^precision |
 
 ## Mapping user words
 

package/skills/kaleido-trading/references/atomic.md

@@ -1,13 +1,11 @@
-# Atomic swap over kaleido-mcp
+# Atomic swap
 
 Every KaleidoSwap swap settles as an atomic HTLC swap between the maker and
-the user's RGB Lightning Node (RLN). There is no deposit or order flow on
-kaleido-mcp 0.3.0+. If either side fails, nothing settles. Typical end-to-end
+the user's RGB Lightning Node (RLN). There is no deposit or order flow. If either side fails, nothing settles. Typical end-to-end
 time: 2–15 s.
 
-These are kaleido-mcp's argument names. In-app wallets that bind the
-`@kaleidorg/mind` KaleidoSwap contract use the simpler `from_asset` /
-`to_asset` / `amount` quote and run the chain through a recipe instead.
+The argument names are the same in kaleido-mcp and in the `@kaleidorg/mind`
+KaleidoSwap contract.
 
 ## Steps
 
@@ -58,7 +56,7 @@ and is not an order id.
 
 The swap needs outbound capacity on the asset you send and inbound capacity on
 the asset you receive. If either side is short, `atomic_execute` fails. Buy a
-channel first (skill: `kaleido-lsps`).
+channel first (skill: `channel-manager`).
 
 ## Reading the result