@kaleidorg/mind 0.6.0 → 0.6.2

package/dist/wallet/contract.js

@@ -32,10 +32,26 @@ const asset = { type: 'string', description: "Asset ticker, e.g. 'USDT', 'XAUT',
 /** The full contract. Keep descriptions terse — small models read every word. */
 export const WALLET_TOOLS = [
     // ── Spark ──────────────────────────────────────────────────────────────
-    t('spark', 'spark_get_balance', 'Get the Spark wallet BTC balance.'),
-    t('spark', 'spark_get_address', 'Get a Spark deposit address to receive BTC.'),
-    t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice to receive BTC.', { amount_sats: sats }),
-    t('spark', 'spark_send', 'Send BTC from Spark to an address or invoice.', { amount_sats: sats, to: { type: 'string', description: 'Address or invoice' } }, ['amount_sats', 'to'], true),
+    t('spark', 'spark_get_balance', 'Get the Spark wallet balances — BTC sats AND every Spark-native token (e.g. USDB). Returns `{ total: <sats>, tokens: [{ address, balance, symbol?, decimals?, available_to_send? }], connected, layer, network }`. Use for ANY "balance / how much / what do I have on Spark" question — call it fresh every time, balances change. The `tokens` array surfaces ALL Spark-native tokens the wallet holds, so you do NOT need to call flashnet_get_balance separately for that (flashnet_get_balance is the AMM-client view of the same wallet and returns the same numbers). For RGB asset balances (USDT, XAUT) use the RLN tools — RGB assets are NOT on Spark.'),
+    // The user-facing "Spark address" — an off-chain Spark identity (sparkrt1…/
+    // spark1…). For OFF-CHAIN peer transfers WITHIN Spark. NOT a Bitcoin
+    // on-chain address. Use spark_get_onchain_address for the on-chain deposit
+    // path; use spark_create_invoice for a Lightning invoice.
+    t('spark', 'spark_get_address', 'Get the user\'s Spark address (sparkrt1…/spark1…) — an OFF-CHAIN Spark identity for receiving Spark-to-Spark transfers. NOT a Bitcoin on-chain address (does not start with bc1/tb1/bcrt1) and NOT a Lightning invoice. For "an on-chain address to deposit BTC into Spark" use spark_get_onchain_address. For a Lightning invoice use spark_create_invoice.'),
+    // Real on-chain Bitcoin address used to deposit BTC FROM mainnet INTO the
+    // Spark wallet. The SDK calls this a "static deposit address" — bc1…/tb1…/
+    // bcrt1…. The opposite of spark_get_address.
+    t('spark', 'spark_get_onchain_address', 'Get a real Bitcoin ON-CHAIN address (bc1…/tb1…/bcrt1…) for depositing BTC from the Bitcoin L1 into the Spark wallet. Use ANY time the user asks for "an on-chain address", "deposit address", "Bitcoin address to fund Spark", "where do I send my on-chain BTC". This is NOT the Spark identity (spark_get_address) and NOT a Lightning invoice (spark_create_invoice).'),
+    t('spark', 'spark_create_invoice', 'Create a Spark Lightning invoice (BOLT11) to receive BTC over Lightning. Returns an invoice string the user can share. Use when the user asks for "an invoice", "a lightning invoice", "pay me", or names an amount they want received. NOT an address.', { amount_sats: sats }),
+    // Explicit Lightning-invoice payer. BOLT11 invoices encode the amount, so
+    // `amount_sats` is optional and only used for amount-less ("any-amount")
+    // invoices. Prefer this over `spark_send` when the destination is a BOLT11
+    // invoice — it removes ambiguity for small models and gives the cross-skill
+    // bitrefill flow a single, unambiguous target.
+    t('spark', 'spark_pay_invoice', 'Pay a Lightning (BOLT11) invoice from the Spark wallet. The invoice already encodes the amount; pass amount_sats ONLY for amount-less invoices. Use this for any BOLT11 destination (Bitrefill, contact, raw invoice).', { invoice: { type: 'string', description: 'BOLT11 Lightning invoice (lnbc…/lntb…/lnbcrt…).' }, amount_sats: { type: 'number', description: 'Required ONLY when the invoice has no amount; omit otherwise.' } }, ['invoice'], 
+    /* spend */ true),
+    t('spark', 'spark_send', 'Send BTC from Spark to an on-chain address (bc1…/tb1…). For BOLT11 invoices, prefer spark_pay_invoice.', { amount_sats: sats, to: { type: 'string', description: 'On-chain Bitcoin address.' } }, ['amount_sats', 'to'], 
+    /* spend */ true),
     // ── RLN / RGB ──────────────────────────────────────────────────────────
     t('rln', 'rln_get_balances', 'Get RLN node balances (BTC + RGB assets).'),
     t('rln', 'rln_get_node_info', 'Get RLN node status and sync state.'),

package/dist/wallet/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/wallet/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/wallet/contract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaleidorg/mind",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Local-first reasoning + function-calling engine for KaleidoSwap. QVAC-powered.",
   "license": "Apache-2.0",
   "type": "module",
@@ -66,8 +66,8 @@
     }
   },
   "devDependencies": {
-    "@qvac/sdk": "^0.13.1",
-    "@types/node": "^20.0.0",
-    "vitest": "^1.6.0"
+    "@qvac/sdk": "^0.13.5",
+    "@types/node": "^20.19.43",
+    "vitest": "^1.6.1"
   }
 }

package/skills/bitrefill/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: bitrefill
-description: "Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, and eSIMs across 180+ countries, payable in crypto, Lightning, USDC via x402, or pre-funded account balance. Routes the host agent to its highest-fidelity channel (residential browser, MCP server, npm CLI, or REST API) based on detected runtime capabilities, with a dedicated OpenClaw integration guide for chat-channel scenarios. Triggers when the user mentions Bitrefill, gift cards, mobile top-up, eSIM data plan, refilling a phone, or asks to pay or check out with crypto, Lightning, USDC, or x402."
-compatibility: "Detects host capabilities at runtime. Paths require: browse — residential-IP browser; MCP — MCP-capable client + Bitrefill OAuth/API key; CLI — Node.js >=18 + shell + npm + @bitrefill/cli >=0.3.0 (headless login/verify via magic link); API — outbound HTTP + Bitrefill API key (Personal) or API ID/Secret (Business/Affiliate). OpenClaw host gets a dedicated guide."
+description: "Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, and eSIMs across 180+ countries, payable in crypto, Lightning, USDC via x402, or pre-funded account balance. Use these tools to actually transact: bitrefill_search → bitrefill_get_product → bitrefill_create_invoice (spend, confirmed) → bitrefill_get_invoice/bitrefill_get_order for the redemption code."
+tools: bitrefill_search, bitrefill_get_product, bitrefill_get_balance, bitrefill_create_invoice, bitrefill_get_invoice, bitrefill_get_order, spark_pay_invoice, spark_get_balance, rln_pay_invoice
+triggers: bitrefill, gift card, gift cards, giftcard, voucher, vouchers, top-up, topup, top up, refill, esim, e-sim, mobile plan, mobile top-up, prepaid, amazon, steam, google play, app store, itunes, playstation, xbox, netflix, spotify, uber
+compatibility: "Live REST adapter on the CLI/desktop when BITREFILL_API_KEY (Personal) or BITREFILL_API_ID + BITREFILL_API_SECRET (Business) are set. Without those env vars the tools aren't registered — tell the user and stop."
 metadata:
   author: bitrefill
-  version: "2.1.5"
+  version: "3.0.0"
   homepage: "https://www.bitrefill.com"
   docs: "https://docs.bitrefill.com"
   repository: "https://github.com/bitrefill/cli"
@@ -12,55 +14,153 @@ metadata:
 
 # Bitrefill
 
-Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+ countries and 1,500+ brands. Pay with crypto, Lightning, USDC via x402, or pre-funded account balance. Codes deliver instantly after payment confirms.
-
-This skill **routes by capability, not by use case**. Same intent ("buy a Steam card") plays out differently across hosts. Pick a path below based on what your runtime can do.
-
-## Pick a path
-
-Walk these checks **in order**. First match wins.
-
-1. **Inside OpenClaw?** Check for `~/.openclaw/openclaw.json`, `~/.openclaw/skills/`, or `openclaw` on PATH. If yes → read [host-openclaw.md](references/host-openclaw.md) first. **Default purchase path: guest CLI via `exec`** (no auth). Sign in for `balance`/cashback. OpenClaw also supports MCP, API, Browse, chat-channel scenarios (Telegram, cron, mobile camera).
-
-2. **Browse-only intent (no purchase)?** If the user only wants to explore, compare prices, or learn how products work:
-   - Have a residential-IP browser (ChatGPT Atlas, Cursor browser tool, Claude/Playwright Chrome extension, OpenClaw on user host)? → [browse.md](references/browse.md).
-   - Datacenter egress only (ChatGPT web/Agent, Gemini consumer, Jules)? `www.bitrefill.com` returns **403 Cloudflare** to datacenter IPs. Use [mcp.md](references/mcp.md) `search-products` / `product-details` instead — they return the same catalog without scraping.
-
-3. **MCP supported?** Bitrefill ships a remote HTTP/SSE MCP at `https://api.bitrefill.com/mcp`. Works on Claude.ai (Pro+), Cowork, Claude Desktop, Claude Code, ChatGPT (Plus+), Atlas, Codex CLI, Gemini CLI, Cursor, OpenCode, OpenClaw. **Highest-fidelity purchase channel — typed tool calls, OAuth or API key, no shell needed.** → [mcp.md](references/mcp.md).
-
-4. **Shell + `npm install` available?** CLI ≥ 0.3.0: **guest checkout first** (no auth — `buy-products --email` + crypto). Sign in for `balance`, cashback, order history. → [cli.md](references/cli.md). Headless sign-in → [cli-headless-auth.md](references/cli-headless-auth.md).
-
-5. **Outbound HTTP from agent loop?** Anywhere shell exists, plus Claude Code `WebFetch`. Last resort — verbose, no typed validation. → [api.md](references/api.md).
-
-6. **None of the above** (e.g. Gemini consumer free tier): give the user a `bitrefill.com` link and stop.
-
-Don't know which host you're in? Read [capability-matrix.md](references/capability-matrix.md) — per-client cheat sheet maps every leading agent product to its viable paths.
-
-## Top spending safeguards (read full list before any purchase)
-
-This skill enables **real-money transactions**. Codes deliver instantly and digital goods are non-refundable per EU consumer rights.
-
-- **Confirm before buying.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user opts in for the current session.
-- **Treat codes as cash.** Never paste in group chats or public channels. Prefer in-memory storage over plain-text logs. Advise user to redeem ASAP.
-- **Use a dedicated, low-balance account.** Never give the agent access to high-balance accounts or crypto wallet seeds. This skill is **not a wallet**.
-- **Log every purchase.** `invoice_id`, product, amount, payment method.
-
-Full safeguards + per-host hardening (OpenClaw exec-approvals, Cursor auto-approve, Codex sandbox, Claude Code allowlist) → [safeguards.md](references/safeguards.md).
-
-## References
-
-| File | Use when |
-|------|----------|
-| [browse.md](references/browse.md) | Agent has residential-IP browser; user wants to explore |
-| [mcp.md](references/mcp.md) | MCP-capable host; preferred purchase path |
-| [cli.md](references/cli.md) | Shell + npm; guest checkout or signed-in CLI ≥ 0.3.0 |
-| [cli-headless-auth.md](references/cli-headless-auth.md) | AgentMail or equivalent inbox + magic-link auth for headless agents |
-| [api.md](references/api.md) | HTTP-only runtime; Personal / Business / Affiliate REST tiers |
-| [host-openclaw.md](references/host-openclaw.md) | OpenClaw Gateway — guest CLI via `exec` preferred |
-| [capability-matrix.md](references/capability-matrix.md) | Per-client viable paths cheat sheet |
-| [safeguards.md](references/safeguards.md) | Spending policy + per-host hardening |
-| [troubleshooting.md](references/troubleshooting.md) | Common errors across all paths |
+Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+
+countries. Codes deliver instantly after the invoice settles.
+
+This skill is **action-shaped**: when the host has the `bitrefill_*` tools
+wired, you transact through them directly. Don't navigate browser / MCP / CLI
+fallbacks unless the tools are absent.
+
+## Critical rules (read first)
+
+1. **Never invent product or package ids.** Every `product_id` and
+   `package_id` MUST come from a `bitrefill_search` + `bitrefill_get_product`
+   result in the current turn.
+2. **Confirm before spending.** `bitrefill_create_invoice` is the spend — it
+   is automatically confirmation-gated by the host. Before calling it, show
+   the user product, denomination, total price, and payment method in plain
+   English, then call the tool. The host will fire one confirmation; on
+   approve, the invoice is created.
+3. **Codes are cash.** When you read `redemption_info.code` from
+   `bitrefill_get_order`, return it once, advise the user to store it
+   securely, and **never** repeat it in summaries or future turns.
+4. **No tools wired = no purchase.** If `bitrefill_search` isn't available
+   in this session (no API key configured), say so directly: *"Bitrefill
+   purchases need a `BITREFILL_API_KEY` env var. Set one and restart, or
+   browse <https://www.bitrefill.com> directly."* Don't fall back to
+   inventing products.
+
+## Happy-path playbook
+
+For a typical buy ("a $25 Amazon US gift card with my balance"):
+
+1. **`bitrefill_search({ query, country? })`** — find candidate products.
+   - "amazon" → `{ query: "amazon", country: "US" }` if the user named a
+     country, else just `{ query: "amazon" }`.
+   - Returns a list of `{ id, name, country, category }` rows. Pick the one
+     that matches the user's intent. If multiple plausible matches, ask the
+     user once instead of guessing.
+
+2. **`bitrefill_get_product({ product_id })`** — read the `packages` array
+   for the right denomination. Each package has `{ id, value, price,
+   currency }`. **The `package_id` is what you pass to create_invoice**, NOT
+   the bare `value`.
+
+3. **`bitrefill_get_balance()`** *(optional)* — when the user said "with my
+   balance" or asked "can I afford it", verify the account has enough
+   before creating the invoice. Skip when paying with Lightning / on-chain.
+
+4. **`bitrefill_create_invoice({ products, payment_method, ... })`** —
+   confirmation-gated spend. Choose `payment_method` per the user's request:
+   - `"balance"` + `auto_pay: true` — instant settlement from account
+     balance. **Default** when the user says "with my balance" or doesn't
+     specify and balance is sufficient.
+   - `"lightning"` — fastest crypto path. Response carries a BOLT11
+     invoice the user pays out-of-band (see step 5b — Spark, if connected,
+     pays it directly). **Requires `refund_address`** in case it expires.
+   - `"bitcoin"`, `"usdc_base"`, `"usdc_polygon"`, `"usdt_tron"`,
+     `"usdt_ethereum"` — same pattern, slower confirmation; also need
+     `refund_address`.
+
+   Line items: `products: [{ product_id, package_id, quantity }]`. Up to 20
+   per invoice.
+
+5. **Settlement.**
+
+   a. **`balance` + `auto_pay:true`** — the invoice is usually `complete`
+      on creation. Read its `order_id`(s) and skip to step 6.
+
+   b. **`lightning` with Spark connected** — the response includes a BOLT11
+      invoice (commonly under `payment.lightning_invoice`, surface whatever
+      field the host returns). Pay it with **`spark_pay_invoice({ invoice:
+      <bolt11> })`** — that's one extra confirmation gate, and Spark settles
+      it in seconds. (Same pattern if RLN is the user's Lightning layer:
+      use `rln_pay_invoice`.) Then `bitrefill_get_invoice` should already
+      report `paid` / `complete`.
+
+   c. **`lightning` or on-chain without an on-device wallet** — relay the
+      payment URI to the user and **poll** `bitrefill_get_invoice({
+      invoice_id })` until `status:"complete"`. Don't poll faster than
+      every ~5s; give up after a few minutes and hand the invoice id back
+      to the user to check later.
+
+6. **`bitrefill_get_order({ order_id })`** — read `redemption_info`:
+   - `.code` — the gift-card code or top-up PIN. The actual product.
+   - `.pin` — additional PIN for prepaid cards (often present alongside
+     the code).
+   - `.link` — brand redemption URL when applicable.
+   - `.instructions` — brand-specific redemption steps.
+
+   Present the code in the chat ONCE, then tell the user to store it and
+   redeem ASAP. Don't echo it in subsequent replies, summaries, or memory.
+
+## Choosing a payment method
+
+| Method | Speed | Blast radius | Use when |
+|---|---|---|---|
+| `balance` + `auto_pay:true` | Instant | Capped at account balance | Default. User pre-funded the account; lowest risk. |
+| `lightning` | Seconds | Whatever's in the user's LN wallet | User asks for "pay with Lightning" or wants no pre-funding. |
+| `bitcoin` | 10–60 min | One on-chain UTXO | User asks for "pay on-chain" or invoice > Lightning capacity. |
+| `usdc_base` (x402) | Seconds | Agent USDC wallet balance | Agent has an x402-capable USDC wallet. |
+| Other on-chain (USDT/USDC variants) | Variable | One UTXO per network | User explicitly requested. |
+
+Default to `balance` when available; ask the user before switching to a
+crypto method.
+
+## Failure handling
+
+Tool errors surface as thrown messages like `"bitrefill bitrefill_create_invoice failed: HTTP 401 ..."`. Relay them as plain English:
+
+- **401 Unauthorized** — `BITREFILL_API_KEY` is unset or wrong. Tell the
+  user; don't retry.
+- **400 / validation errors** — usually a bad `package_id` or
+  `payment_method`. Re-read the product's `packages` array and retry once,
+  then stop and ask.
+- **402 Payment Required** (with `balance`) — account underfunded. Show
+  the deficit; suggest topping up or switching payment method.
+- **Invoice `expired`** — re-create the invoice; an old quote isn't
+  reusable.
+
+## Reply style
+
+- Show the candidate product list as a short bulleted list (≤5 rows).
+- Before the spend, summarize in one line:
+  `Buying: 1× Amazon US $25 — total $25.00 USD, paying with balance. Confirm?`
+- After settlement: one line on success, then the redemption details on a
+  separate line so the user can copy the code.
+- After delivering the code, suggest redeeming ASAP and do NOT repeat the
+  code in later turns.
+
+## References (deep-dive, on demand)
+
+The references below cover paths and host hardening — they're for hosts
+that **don't** have the `bitrefill_*` tools wired (browser-only,
+MCP-capable client, npm CLI, raw REST). When the tools above are
+available, you don't need to read them.
+
+| File | When |
+|------|------|
+| [api.md](references/api.md) | Mapping the contract tools back to raw REST endpoints. |
+| [mcp.md](references/mcp.md) | Host has the Bitrefill remote MCP wired instead of the contract. |
+| [cli.md](references/cli.md) | `@bitrefill/cli` npm path (auth-bound). |
+| [cli-headless-auth.md](references/cli-headless-auth.md) | Magic-link auth via an agent inbox. |
+| [browse.md](references/browse.md) | Browser-only hosts. |
+| [host-openclaw.md](references/host-openclaw.md) | OpenClaw-specific path. |
+| [capability-matrix.md](references/capability-matrix.md) | Per-client cheat sheet. |
+| [safeguards.md](references/safeguards.md) | Spending policy + per-host hardening. |
+| [troubleshooting.md](references/troubleshooting.md) | Common errors. |
 
 ## Source of truth
 
-Skill summarizes and routes. For exhaustive enums (countries, payment methods, full endpoint list), follow link-outs to <https://docs.bitrefill.com>.
+Skill describes the contract + playbook. For exhaustive enums (countries,
+payment methods, full endpoint list), see <https://docs.bitrefill.com>.

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: 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, lsp_get_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"
@@ -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 — `kaleidoswap_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 `kaleidoswap_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
@@ -101,7 +116,9 @@ Report the outcome plainly with the new channel id from `channel.channel_id` if
   `order_id` and `access_token` and seeing `order_state: COMPLETED`.
 - 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."
+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
+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.