@kaleidorg/mind 0.4.0 → 0.5.1

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

@@ -0,0 +1,108 @@
+---
+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
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+---
+
+# RGB Lightning Node (taker-side)
+
+You drive the **user's own** RGB Lightning Node running locally. In a KaleidoSwap
+atomic swap the **maker** owns init / execute / status (those are
+`kaleidoswap_atomic_*` tools, separate REST endpoints). The node's job in a
+swap is narrow: **expose its pubkey and whitelist the maker's swapstring**.
+The node does NOT init or execute swaps.
+
+## Critical rules
+
+You have **no knowledge** of the node's pubkey, channel state, balance, or any
+invoice contents. Every value in your reply MUST come from a tool result
+returned in the CURRENT turn — never invent a pubkey, channel id, invoice
+string, or sats balance. Never reuse a value from a previous turn.
+
+**Calling the tool IS the answer.** If the user asks "what's my pubkey?", call
+`rln_get_node_info` — do not describe how to fetch it.
+
+## When to use each tool
+
+### `rln_get_node_info` — no args
+Returns:
+- `pubkey` — the node's identity (32-byte hex).
+- `num_channels` — total channels (may include unusable ones).
+- `num_usable_channels` — subset that can route a payment right now.
+- `local_balance_sat` — **sats YOU own** across all channels. This is your
+  **spend** capacity (outbound). It is **NOT** receive capacity, **NOT**
+  inbound liquidity, and **NOT** total channel capacity.
+- `pending_outbound_payments_sat` — in-flight, temporarily locked.
+- `num_peers` — currently connected peers.
+
+Call this when:
+- The user asks about the node, pubkey, peers, channel count, or how much
+  they can **spend**.
+- An atomic swap is in progress and the maker needs `taker_pubkey` —
+  fetch the pubkey from this tool's `pubkey` field and pass it to
+  `kaleidoswap_atomic_execute`.
+
+**Do NOT** use this tool's `local_balance_sat` to answer a question about
+**inbound liquidity / receive capacity** — that is a different quantity
+(the peer's side of each channel, 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
+Tell the node "I accept this swap." Args: the `swapstring` returned by
+`kaleidoswap_atomic_init`. The node validates and stores it; **no funds move
+here**, but the user is committing to the swap so the engine pauses for
+confirmation.
+
+Call this **after** `kaleidoswap_atomic_init` and **before**
+`kaleidoswap_atomic_execute`. Never call with an empty or invented swapstring
+— the node will reject it.
+
+### `rln_create_ln_invoice` — Lightning invoice for receiving sats
+Args:
+- `amount_sats` (optional) — omit for an amountless invoice.
+- `expiry_sec` (default 3600) — invoice TTL in seconds.
+- `asset_id` + `asset_amount` — optional, for RGB-over-Lightning.
+
+Use when the user wants to **receive** a Lightning payment. Do NOT call inside
+an atomic swap flow unless the user explicitly asked to invoice someone.
+
+### `rln_create_rgb_invoice` — on-chain RGB receive invoice
+Args:
+- `min_confirmations` (default 1).
+- `witness` (default false).
+- `asset_id` (optional — omit for an any-asset invoice).
+- `expiration_timestamp` (optional, Unix seconds).
+
+Use when the user wants to **receive** an RGB asset directly (not over
+Lightning). Outside the atomic swap flow.
+
+## The maker / node split
+
+A user-driven swap on KaleidoSwap is a two-service flow. Keep them straight:
+
+| Step | Owner | Tool |
+|------|-------|------|
+| Quote | maker | `kaleidoswap_get_quote` |
+| Init  | maker | `kaleidoswap_atomic_init` (returns swapstring + payment_hash) |
+| Pubkey | **node** | `rln_get_node_info` (read `pubkey`) |
+| Whitelist | **node** | `rln_whitelist_swap` (pass the swapstring) |
+| Execute | maker | `kaleidoswap_atomic_execute` (needs swapstring + taker_pubkey + payment_hash) |
+| Status | maker | `kaleidoswap_atomic_status` |
+
+The node's two contributions to the swap are the **pubkey** and the
+**whitelist ack** — nothing more. Don't reach for `/makerinit` or
+`/makerexecute`; those are for nodes that act AS the maker, which is not us.
+
+## Reply style
+
+- One short sentence built from the tool result.
+- Pubkeys are long hex strings — quote them in monospace if you can, never
+  truncate them when the user explicitly asked for them.
+- For `rln_get_node_info`, if the user just said "what's my node status?",
+  surface pubkey + num_usable_channels + local_balance_sat. Don't dump the
+  whole `details` object.

package/skills/wallet-assistant/SKILL.md

@@ -1,38 +1,49 @@
 ---
 name: wallet-assistant
-description: Everyday wallet tasks on this phone — check the BTC/asset balance, create an invoice to receive, send a payment, look up a contact, get the BTC price, or convert a fiat amount to sats. Triggers when the user asks about their balance, wants to receive or send money, pay an invoice, or pay a contact.
-tools: get_balances, get_price, fiat_to_sats, resolve_contact, send_payment, rln_pay_invoice, rln_create_ln_invoice, spark_create_invoice
-triggers: balance, pay, send, receive, address, invoice, transactions, contact, funds, money, price, sats, eur, gbp
+description: Everyday wallet tasks on this phone — check the BTC/asset balance, create an invoice to receive, send a payment, look up a contact, or quote a swap (e.g. "how many sats is 10 USDT?"). Triggers when the user asks about their balance, wants to receive or send money, pay an invoice, pay a contact, or convert between BTC and supported assets.
+tools: get_balances, resolve_contact, send_payment, rln_pay_invoice, rln_create_ln_invoice, spark_create_invoice, kaleidoswap_get_quote
+triggers: balance, pay, send, receive, address, invoice, transactions, contact, funds, money, sats
 ---
 
 # Wallet assistant
 
 You operate the user's on-device multi-L2 Bitcoin wallet. ALWAYS use a tool to
-get real data — NEVER invent a balance, address, amount, price, or result.
+get real data — NEVER invent a balance, address, amount, price, or quote.
 
 ## Critical rules
 
-You have no knowledge of balances, prices, addresses, or invoices. Every value
-in your reply MUST come from a tool result returned in the CURRENT turn — do
-not reuse a number from a previous turn.
+You have no knowledge of balances, addresses, invoices, prices, or quotes.
+Every value in your reply MUST come from a tool result returned in the CURRENT
+turn — do not reuse a number from a previous turn.
+
+NEVER mention the exact name of any tool (such as "kaleidoswap_get_quote") in
+your text reply to the user. Only use tools via the proper function call
+format when needed; describe what you are doing in plain language.
 
 When a tool returns multiple fields, **report all the load-bearing ones**:
-- `get_balances` may return `{confirmed, pending, total}` — when `pending`
+- The balance tool may return `{confirmed, pending, total}` — when `pending`
   is non-zero, report BOTH. `confirmed` is spendable; `pending` is settling
   and is NOT spendable yet. The user needs to know the difference.
-- `fiat_to_sats` returns `{sats}` plus a `note` when the currency was an
-  approximation — surface the note.
+- The quote tool returns display strings (e.g. the to amount and fee in
+  human readable form). Read these strings verbatim — do NOT do unit math
+  yourself.
 
 ## Rules
 
-- Balance / "how much do I have" → call `get_balances`, then state the number.
-- Receive / "an invoice for N sats" → call `rln_create_ln_invoice` (or
-  `spark_create_invoice`) with the amount.
-- Price → `get_price`. "How many sats is 3 EUR" → `fiat_to_sats`.
-- Pay a Lightning invoice → `rln_pay_invoice`.
-- Send to a person/amount → first `resolve_contact` (and `fiat_to_sats` if the
-  amount is in fiat), then `send_payment` with the amount in sats and the
-  recipient. State the amount and destination; the app asks the user to confirm
-  before it sends.
-
-Keep replies short, but never drop a balance component or a fee.
+- **Balance / "how much do I have"** → use the balance tool, then state the
+  number.
+- **Receive / "an invoice for N sats"** → use the invoice creation tool (for
+  the appropriate layer) with the amount.
+- **"How many sats is N USDT?" / "What's 0.1 BTC in USDT?" / "convert N X
+  to Y"** → use the quote/conversion tool and
+  read the display fields from the result. Supported pairs: any of
+  BTC/USDT/XAUT against each other. Fiat (EUR/USD/GBP) is NOT quoted by
+  the maker — if the user asks "how much sats is 10 EUR", say so plainly
+  and offer USDT as the closest analogue (USDT is a USD-pegged stablecoin).
+- **Pay a Lightning invoice** → use the lightning payment tool.
+- **Send to a person/amount** → first resolve the contact, then use the send
+  payment tool with the amount in sats and the recipient. State the amount and
+  destination; the app asks the user to confirm before it sends.
+
+Keep replies short, but never drop a balance component, a fee, or the
+quote's `rfq_id` when present.

package/src/funnel.ts

@@ -31,6 +31,7 @@ import type { Recipe } from './recipe/types.js';
 import { SkillRegistry } from './skills/registry.js';
 import type { Skill } from './skills/types.js';
 import type { LLMProvider } from './providers/types.js';
+import type { Retriever } from './rag/retriever.js';
 import type { ConfirmDecision, Message, ToolResult } from './types.js';
 
 /** Base system prompt for the wallet assistant. Hosts may override. */
@@ -53,6 +54,16 @@ export const DEFAULT_WALLET_SYSTEM = [
   '   the required field missing.',
   '5. All BTC amounts are in satoshis. Asset codes are case-insensitive but the',
   '   canonical forms are BTC, USDT, XAUT — do not silently shorten to USD, XAU.',
+  '6. NEVER name a tool, function, endpoint, or argument key in your reply.',
+  '   Tools are private plumbing. Bad: "use kaleidoswap_get_quote with amount 1".',
+  '   Good: "I can quote that for you — one moment." If you need information',
+  '   from the user (like an amount), ASK in plain English without referencing',
+  '   how the system will use it.',
+  '7. A price/rate question (e.g. "price of USDT", "BTC price", "how much is',
+  '   1 USDT") is a UNIT QUOTE — answer with the value of 1 of the named asset',
+  '   in the denomination the user asked for (default: sats when pricing USDT/',
+  '   XAUT, USDT when pricing BTC). Never ask the user "how much do you want"',
+  '   for a price question.',
   '',
   'Keep replies short and friendly. When a tool returns multiple fields, surface',
   "the ones that matter — never collapse a structured result to a single number",
@@ -98,12 +109,14 @@ export interface FunnelCallbacks {
     arguments: Record<string, unknown>;
     result: unknown;
   }) => void;
-  onConfirm?: (call: { name: string; arguments: Record<string, unknown> }) => Promise<ConfirmDecision>;
+  onConfirm?: (call: { name: string; arguments: Record<string, unknown>; summary?: string }) => Promise<ConfirmDecision>;
 }
 
 export interface FunnelResult {
   text: string;
   tier: 'fast' | 'recipe' | 'agentic';
+  /** What handled the turn: the intent (fast), recipe name (recipe), or skill name (agentic). */
+  route?: string;
   /** Fast tier only: the matched intent + raw tool result (e.g. for a balance card). */
   intent?: string;
   data?: unknown;
@@ -132,6 +145,19 @@ export interface FunnelOptions {
   renderFast?: (intent: string, result: unknown) => string;
   /** Diagnostics sink (tier routing, tool calls). Default: silent. */
   log?: (message: string) => void;
+  /**
+   * Optional retriever for AUTO-injecting relevant knowledge chunks into the
+   * agentic-tier system prompt (T1 only — recipes/fast-path are deterministic
+   * and don't need it). When set, the top-`topKRag` chunks for the user's
+   * query are prepended as `## Relevant context`. Default: no auto-inject
+   * (the `search_knowledge` tool stays available for on-demand lookups).
+   *
+   * Small models often don't choose to call search_knowledge; auto-inject
+   * makes the corpus useful by default without the model having to opt in.
+   */
+  retriever?: Retriever;
+  /** How many chunks to auto-inject when `retriever` is set. Default 3. */
+  topKRag?: number;
 }
 
 function defaultRenderFast(intent: string, r: any): string {
@@ -157,6 +183,8 @@ export class Funnel {
   private readonly getSettings: () => FunnelSettings;
   private readonly renderFast: (intent: string, result: unknown) => string;
   private readonly log: (message: string) => void;
+  private readonly retriever?: Retriever;
+  private readonly topKRag: number;
 
   /** Skill registry, rebuilt only when the disabled-skills set changes. */
   private skillsCache: { key: string; reg: SkillRegistry } | null = null;
@@ -176,6 +204,8 @@ export class Funnel {
     this.getSettings = opts.getSettings ?? (() => ({}));
     this.renderFast = opts.renderFast ?? defaultRenderFast;
     this.log = opts.log ?? (() => {});
+    if (opts.retriever) this.retriever = opts.retriever;
+    this.topKRag = opts.topKRag ?? 3;
   }
 
   /** Skills currently enabled (e.g. for a skills sheet). */
@@ -205,18 +235,24 @@ export class Funnel {
     if (fast && (await this.registry.getDef(fast.tool))) {
       this.log(`tier=fast-path → ${fast.tool}`);
       const r = await this.registry.execute(fast.tool, fast.args);
-      return { text: this.renderFast(fast.intent.name, r), tier: 'fast', intent: fast.intent.name, data: r };
+      return { text: this.renderFast(fast.intent.name, r), tier: 'fast', route: fast.intent.name, intent: fast.intent.name, data: r };
     }
 
-    // ── T2: recipe multi-step — fires only when the recipe is confident given
-    // its extracted slots (payments need a recipient; receive always fires),
-    // and the registry implements the recipe's final action.
+    // ── T2: recipe multi-step — fires when:
+    //   (a) the recipe is confident given its deterministic slots, OR
+    //   (b) `forceModelExtract` is on — the LLM does the actual extraction
+    //       inside runRecipe, so we don't gate on the regex result. If the
+    //       LLM still doesn't yield enough, runRecipe returns status:
+    //       'needs-info' with a friendly "please specify X" instead of
+    //       running steps with bad data.
+    // Either way the registry must implement the recipe's final action.
     const recipe = this.recipes.select(text);
     const slots = recipe?.extract?.(text) ?? null;
+    const deterministicallyConfident =
+      !!slots && (recipe?.confident ? recipe.confident(slots) : Object.keys(slots).length > 0);
     const fires =
       !!recipe &&
-      !!slots &&
-      (recipe.confident ? recipe.confident(slots) : Object.keys(slots).length > 0) &&
+      (recipe.forceModelExtract === true || deterministicallyConfident) &&
       !!(await this.registry.getDef(recipe.final.tool));
     if (recipe && fires) {
       this.log(`tier=recipe:${recipe.name} slots=${JSON.stringify(slots)}`);
@@ -229,19 +265,38 @@ export class Funnel {
           cbs.onStep?.(name);
         },
       });
-      return { text: res.text, tier: 'recipe' };
+      return { text: res.text, tier: 'recipe', route: recipe.name };
     }
 
     // ── T1: skill-scoped agentic loop ──
     const skills = this.skillsFor(settings.disabledSkills);
     const skill = skills.select(text);
-    const base = settings.persona ? `${this.system}\n\n## Your persona\n${settings.persona}` : this.system;
+    let base = settings.persona ? `${this.system}\n\n## Your persona\n${settings.persona}` : this.system;
+
+    // Auto-inject relevant knowledge chunks (best-effort — corpus is grounding
+    // truth, history is conversational context; both reach the model but the
+    // RAG block sits above history so the model treats it as authoritative).
+    // Only fires for agentic turns and only when the host opts in via
+    // `retriever` AND the user hasn't disabled RAG in settings.
+    const ragOn = settings.ragEnabled !== false;
+    if (this.retriever && ragOn && this.topKRag > 0) {
+      try {
+        const hits = await this.retriever.search(text, this.topKRag);
+        if (hits.length) {
+          const chunks = hits.map((h) => `- ${h.text}`).join('\n');
+          base = `${base}\n\n## Relevant context (read first; trust this over conversation history)\n${chunks}`;
+          this.log(`rag injected ${hits.length} chunks`);
+        }
+      } catch (e) {
+        this.log(`rag failed: ${(e as Error)?.message ?? e}`);
+      }
+    }
+
     const { system, allowedTools } = skills.compose(base, skill);
 
     // Ambient tools stay available even when a skill narrows the set — gated
     // by the user's memory/knowledge toggles (default on).
     const memoryOn = settings.memoryEnabled !== false;
-    const ragOn = settings.ragEnabled !== false;
     const ambient = [...(memoryOn ? AMBIENT_MEMORY : []), ...(ragOn ? AMBIENT_RAG : [])];
     const disabledAmbient = [...(memoryOn ? [] : AMBIENT_MEMORY), ...(ragOn ? [] : AMBIENT_RAG)];
     let scoped: string[] | undefined;
@@ -280,6 +335,6 @@ export class Funnel {
       onToolResult: cbs.onToolResult,
       onConfirm: cbs.onConfirm,
     });
-    return { text: res.text ?? '', tier: 'agentic', toolCalls: res.toolCalls, turns: res.turns };
+    return { text: res.text ?? '', tier: 'agentic', route: skill?.name, toolCalls: res.toolCalls, turns: res.turns };
   }
 }

package/src/index.ts

@@ -81,8 +81,19 @@ export type {
   BindLsps1Options,
 } from './lsps1/contract.js';
 
-// ── KaleidoSwap atomic-swap recipe (opt-in — register via Funnel.recipes) ──
+// ── KaleidoSwap recipes (opt-in — register via Funnel.recipes) ──
+// price recipe is read-only (quote-only); atomic recipe runs the full swap.
+// Register the price recipe FIRST so phrasings like "BTC price" are answered
+// without firing any spend.
+export { kaleidoswapPriceRecipe } from './recipe/kaleidoswap-price.js';
 export { kaleidoswapAtomicRecipe } from './recipe/kaleidoswap-atomic.js';
+export {
+  kaleidoswapChannelOrderRecipe,
+  extractChannelOrder,
+} from './recipe/kaleidoswap-channel-order.js';
+
+// ── Buy-an-asset-channel recipe (opt-in — register via Funnel.recipes) ─────
+export { buyAssetChannelRecipe, extractBuyAsset } from './recipe/buy-asset-channel.js';
 
 // ── Recipes (mobile multi-step: "recipes, not planning") ───────────────────
 export { runRecipe, extractSlots, RecipeRegistry } from './recipe/runner.js';
@@ -145,7 +156,7 @@ export { walletHistoryToDocuments, contactsToDocuments } from './knowledge/walle
 export type { WalletTx, Contact } from './knowledge/wallet.js';
 export { merchantsToDocuments } from './knowledge/merchants.js';
 export type { Merchant } from './knowledge/merchants.js';
-export { createBtcMapToolSource, BTC_MAP_SAMPLE } from './knowledge/btc-map.js';
+export { createBtcMapToolSource } from './knowledge/btc-map.js';
 export type {
   BtcMapToolOptions,
   BtcMapMerchant,
@@ -165,6 +176,7 @@ export {
   SkillRegistry,
   parseSkill,
   keywordSelector,
+  createEmbeddingSkillSelector,
   READ_REFERENCE_TOOL,
 } from './skills/registry.js';
 export { createSkillReferenceToolSource } from './skills/reference-source.js';

package/src/kaleidoswap/contract.test.ts

@@ -23,12 +23,14 @@ describe('KALEIDOSWAP_TOOLS — shape invariants', () => {
       'kaleidoswap_atomic_init',
       'kaleidoswap_atomic_execute',
       'kaleidoswap_atomic_status',
+      'kaleidoswap_lsp_quote_asset_channel',
+      'kaleidoswap_lsp_create_asset_channel',
     ]);
   });
 
   it('every tool has a group and a parameters object', () => {
     for (const t of KALEIDOSWAP_TOOLS) {
-      expect(['market', 'orders', 'atomic']).toContain(t.group);
+      expect(['market', 'orders', 'atomic', 'liquidity']).toContain(t.group);
       expect(t.parameters).toBeDefined();
       expect((t.parameters as any).type).toBe('object');
     }
@@ -43,10 +45,11 @@ describe('KALEIDOSWAP_TOOLS — shape invariants', () => {
   it('lists every spend tool exactly once in KALEIDOSWAP_SPEND_TOOLS', () => {
     const expected = KALEIDOSWAP_TOOLS.filter((t) => t.spend).map((t) => t.name).sort();
     expect([...KALEIDOSWAP_SPEND_TOOLS].sort()).toEqual(expected);
-    // Sanity: place_order, atomic_init, atomic_execute are spend; the rest aren't.
+    // Sanity: place_order, atomic_init/execute, create_asset_channel are spend; the rest aren't.
     expect(expected).toEqual([
       'kaleidoswap_atomic_execute',
       'kaleidoswap_atomic_init',
+      'kaleidoswap_lsp_create_asset_channel',
       'kaleidoswap_place_order',
     ]);
   });
@@ -95,6 +98,8 @@ describe('bindKaleidoswapTools', () => {
     kaleidoswap_atomic_init:       async (a) => ({ ok: true, tool: 'atomic_init', args: a }),
     kaleidoswap_atomic_execute:    async (a) => ({ ok: true, tool: 'atomic_execute', args: a }),
     kaleidoswap_atomic_status:     async (a) => ({ ok: true, tool: 'atomic_status', args: a }),
+    kaleidoswap_lsp_quote_asset_channel:  async (a) => ({ ok: true, tool: 'lsp_quote_asset_channel', args: a }),
+    kaleidoswap_lsp_create_asset_channel: async (a) => ({ ok: true, tool: 'lsp_create_asset_channel', args: a }),
   });
 
   it('binds every tool when all handlers are present', () => {

package/src/kaleidoswap/contract.ts

@@ -9,8 +9,8 @@
  *   - eval    → stub handlers, also via `bindKaleidoswapTools`
  *
  * Because the schemas are identical everywhere, skills are portable and the
- * model comparison is honest. Tools are grouped (`market`, `orders`, `atomic`)
- * so a host can expose a read-only subset for sandbox/eval modes.
+ * model comparison is honest. Tools are grouped (`market`, `orders`, `atomic`,
+ * `liquidity`) so a host can expose a read-only subset for sandbox/eval modes.
  *
  * Spend tools (place an order, init/execute an atomic swap) carry
  * `spend: true` → `requiresConfirmation: true`, so the Engine always pauses
@@ -24,7 +24,7 @@ import { InProcessToolSource } from '../tools/in-process.js';
 import type { InProcessTool } from '../tools/in-process.js';
 
 /** Functional grouping for selective binding (e.g. read-only sandbox). */
-export type KaleidoswapGroup = 'market' | 'orders' | 'atomic';
+export type KaleidoswapGroup = 'market' | 'orders' | 'atomic' | 'liquidity';
 
 export interface KaleidoswapToolDef extends ToolDef {
   /** Functional group — lets a host expose a subset. */
@@ -86,7 +86,7 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
   // ─── orders (orderbook / market-order flow) ─────────────────────────────
   t('orders',
     'kaleidoswap_place_order',
-    'Place an order using an executable quote. Returns an order id. SPEND: the host pauses for user confirmation before the maker is called. Use only after kaleidoswap_get_quote and only when the user has explicitly approved the amount + destination.',
+    'Place an order using an executable quote. Returns order_id + access_token (save the token — required for get_order_status). SPEND: the host pauses for user confirmation before the maker is called. Use only after kaleidoswap_get_quote and only when the user has explicitly approved the amount + destination.',
     {
       quote_id: { type: 'string', description: 'The quote id returned by kaleidoswap_get_quote (must still be valid).' },
     },
@@ -95,9 +95,10 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
 
   t('orders',
     'kaleidoswap_get_order_status',
-    'Check the status of an order by id — pending / settling / completed / failed. Poll this after place_order until the order settles.',
+    'Check the status of an order by id — pending / settling / completed / failed. Poll this after place_order until the order settles. Requires the access_token returned by place_order for authenticated orders.',
     {
       order_id: { type: 'string', description: 'The order id returned by kaleidoswap_place_order.' },
+      access_token: { type: 'string', description: 'The per-order access token returned by kaleidoswap_place_order. Required for status checks on the order.' },
     },
     ['order_id']),
 
@@ -136,6 +137,27 @@ export const KALEIDOSWAP_TOOLS: KaleidoswapToolDef[] = [
       atomic_id: { type: 'string', description: 'The atomic id from kaleidoswap_atomic_init.' },
     },
     ['atomic_id']),
+
+  // ─── liquidity (buy a NEW channel pre-loaded with an asset — onboarding) ──
+  t('liquidity',
+    'kaleidoswap_lsp_quote_asset_channel',
+    'Quote buying a NEW Lightning channel pre-loaded with an RGB asset (e.g. USDT, XAUT) from the maker LSP. This is the onboarding path for a user who has on-chain BTC but no channel yet and wants to hold an asset — they pay once to receive a channel that already holds the asset. Read-only: returns an rfq_id, the BTC price in sats, the channel/setup fee, the total to pay, and when the quote expires. Re-quote rather than reusing a stale rfq_id.',
+    {
+      asset:        { type: 'string', description: 'RGB asset to receive in the channel, e.g. "USDT" or "XAUT".' },
+      asset_amount: { type: 'number', description: 'How much of the asset to load into the channel, in the asset’s display units (e.g. 100 for 100 USDT).' },
+    },
+    ['asset', 'asset_amount']),
+
+  t('liquidity',
+    'kaleidoswap_lsp_create_asset_channel',
+    'Order a new Lightning channel pre-loaded with an RGB asset from the maker LSP, using a fresh rfq_id from kaleidoswap_lsp_quote_asset_channel. SPEND: confirmation-gated. Returns an order id and the payment (on-chain address or Lightning invoice) the user pays to open the channel; the channel opens only after the payment confirms. Poll kaleidoswap_lsp_get_order to track it.',
+    {
+      asset:        { type: 'string', description: 'RGB asset to receive (must match the quote).' },
+      asset_amount: { type: 'number', description: 'Asset amount in display units (must match the quote).' },
+      rfq_id:       { type: 'string', description: 'The rfq_id from kaleidoswap_lsp_quote_asset_channel (must still be valid).' },
+    },
+    ['asset', 'asset_amount', 'rfq_id'],
+    /* spend */ true),
 ];
 
 /** All tool names that move funds (confirmation-gated). */

package/src/knowledge/bitcoin-copilot.ts

@@ -174,4 +174,115 @@ export const BITCOIN_COPILOT_DOCS: RagDocument[] = [
       'accumulate BTC or an asset over time without timing the market.',
     metadata: { topic: 'trading' },
   },
+  {
+    id: 'spend-vs-receive-capacity',
+    text:
+      'Two completely different numbers, often confused: your SPEND capacity ' +
+      '(outbound, local balance — what you can send right now) and your ' +
+      'RECEIVE capacity (inbound, remote balance — what others can pay you ' +
+      'without opening a new channel). Knowing local_balance does NOT tell ' +
+      'you receive capacity, and vice versa. "How much can I spend?" → local ' +
+      'balance. "How much can I receive?" → inbound, derived from channels ' +
+      'or bought from an LSP.',
+    metadata: { topic: 'liquidity' },
+  },
+  {
+    id: 'nodeinfo-fields',
+    text:
+      'Common RGB Lightning Node fields and what they actually mean: pubkey ' +
+      '(your node identity); num_channels (total channels, including unusable ' +
+      'ones); num_usable_channels (subset that can route — what you spend ' +
+      'with); local_balance_sat (sats YOU own across all channels — your ' +
+      'spend / outbound capacity); pending_outbound_payments_sat (in-flight, ' +
+      'temporarily locked); eventual_close_fees_sat (cost if you close every ' +
+      'channel now); num_peers (connected peers). local_balance_sat is NOT ' +
+      'receive capacity and NOT total channel capacity.',
+    metadata: { topic: 'lightning' },
+  },
+  {
+    id: 'channel-two-sided',
+    text:
+      'Every Lightning channel has TWO balances: your side (local — what you ' +
+      'can spend) and the peer\'s side (remote — what they can spend, which ' +
+      'is what YOU can receive). Total channel capacity = local + remote and ' +
+      'is fixed at open time. Routing a payment moves sats from one side to ' +
+      'the other; it does NOT change total capacity. So if you "have 2 ' +
+      'channels with 1,000,000 sats total capacity", that does NOT mean you ' +
+      'can spend 1M and receive 1M — only the split tells you.',
+    metadata: { topic: 'channels' },
+  },
+  {
+    id: 'lsp-info-meaning',
+    text:
+      'The LSPS1 `get_info` endpoint returns the LSP\'s OFFER (min/max ' +
+      'channel size you can buy, fees, accepted payment options). It is NOT ' +
+      'your current inbound capacity — it describes what the LSP is willing ' +
+      'to sell you. To learn your CURRENT receive capacity, sum the remote ' +
+      'balance of your existing channels; to BUY MORE, use lsp_get_info and ' +
+      'lsp_create_order.',
+    metadata: { topic: 'channels' },
+  },
+  {
+    id: 'asset-channels',
+    text:
+      'RGB asset channels (colored channels) carry one specific asset like ' +
+      'USDT or XAUT alongside the BTC funding. Asset capacity is SEPARATE per ' +
+      'asset — having 100,000 sats spendable in BTC channels does not give ' +
+      'you USDT spendable; you need a USDT channel (or buy one via LSPS1). ' +
+      'Likewise, USDT inbound and BTC inbound are independent numbers.',
+    metadata: { topic: 'rgb' },
+  },
+  {
+    id: 'swap-vs-payment',
+    text:
+      'Swap and payment are different actions. A SWAP trades one asset for ' +
+      'another via the KaleidoSwap maker (quote → init → execute). A PAYMENT ' +
+      'moves an existing balance to a recipient over Lightning or on-chain ' +
+      '(no maker). "Send 10 USDT to Alice" is a payment; "swap 10 USDT to ' +
+      'BTC" is a swap. They use different tools, different fees, and a swap ' +
+      'is always between two assets the maker prices.',
+    metadata: { topic: 'usage' },
+  },
+  {
+    id: 'asset-channel-prereq',
+    text:
+      'Why you must buy a channel BEFORE swapping an RGB asset. An RGB ' +
+      'Lightning swap moves an asset (USDT, XAUT, …) across a channel that ' +
+      'already carries that asset. If you have no USDT channel, the maker ' +
+      'cannot pay you USDT over Lightning — there is no rail to push it ' +
+      "down. Open a USDT channel from the LSP first (LSPS1 with `asset_id`, " +
+      '`lsp_asset_amount`) — the LSP funds the asset on their side, you get ' +
+      'inbound USDT capacity, and afterwards a BTC→USDT swap can settle into ' +
+      'that channel. Same for XAUT or any other RGB asset. You need ONE ' +
+      'channel per asset you want to receive over Lightning.',
+    metadata: { topic: 'rgb-channels' },
+  },
+  {
+    id: 'asset-channel-buy',
+    text:
+      "Buying a channel that already has an asset inside. Use LSPS1 with " +
+      "`asset_id` to ask the LSP to open a channel that's pre-funded on the " +
+      "LSP side with a specific RGB asset. `lsp_asset_amount` is the asset " +
+      "units the LSP commits on their side (your future inbound capacity " +
+      "in that asset). `lsp_balance_sat` is the sats the LSP commits for " +
+      "fees/anchor; `client_balance_sat` is what you push in sats. Common " +
+      "shape: lsp_balance_sat 5_000_000, client_balance_sat 100_000, " +
+      "asset_id <USDT id>, lsp_asset_amount 100_000_000 micro-USDT (= 100 " +
+      "USDT). Pay the resulting Lightning invoice and the channel opens " +
+      "with the asset pre-loaded.",
+    metadata: { topic: 'rgb-channels' },
+  },
+  {
+    id: 'asset-channel-with-push',
+    text:
+      "Receiving an asset balance ON your side at channel open. Beyond the " +
+      "LSP-funded asset, you can request the LSP push some asset balance to " +
+      "YOUR side during the open via `client_asset_amount`. This costs sats " +
+      "(BTC → asset at the maker rate), so the maker requires a fresh " +
+      "`rfq_id` from `kaleidoswap_get_quote(BTC → asset)` to lock the " +
+      "price. The order then charges the BTC equivalent on top of the " +
+      "channel fee. Use when you want spendable asset balance immediately " +
+      "(not just inbound capacity).",
+    metadata: { topic: 'rgb-channels' },
+  },
 ];