diff --git a/mintlify-docs/ai-tools/additional-resources.mdx b/mintlify-docs/ai-tools/additional-resources.mdx
index 2836e1d..bd5ba88 100644
--- a/mintlify-docs/ai-tools/additional-resources.mdx
+++ b/mintlify-docs/ai-tools/additional-resources.mdx
@@ -6,7 +6,7 @@ description: "Links for the KaleidoSwap AI tools, covering source repositories,
## Source Repositories
-Every AI surface is open source under the [KaleidoSwap organisation](https://github.com/kaleidoswap).
+Every AI surface is public under the [KaleidoSwap organisation](https://github.com/kaleidoswap), with the gateway, KaleidoAgent and KaleidoMind under Apache 2.0.
@@ -16,13 +16,25 @@ Every AI surface is open source under the [KaleidoSwap organisation](https://git
The on-device engine: tiered funnel, recipe engine, tool contract, memory and retrieval, and the eval harness.
- The gateway that composes every domain behind one connection. Published to npm.
+ The gateway that composes every domain behind one connection. Published to npm as `kaleido-mcp`; 0.3.0 adds the `KALEIDO_NETWORK=signet` preset.
The React Native mobile wallet that hosts KaleidoMind with voice control.
+
+ The `kaleido` command line, which also runs a local signet RGB Lightning Node in Docker.
+
+## Test Network
+
+| Resource | Where |
+|----------|-------|
+| KaleidoSwap API (signet) | `https://api.signet.kaleidoswap.com` |
+| RGB faucet (GitHub login) | [faucet.mutinynet.kaleidoswap.com](https://faucet.mutinynet.kaleidoswap.com) |
+| Local signet RGB Lightning Node | [KaleidoCLI](/cli/installation), `kaleido setup` |
+| End-to-end walkthrough | [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent) |
+
## Protocol Specifications
@@ -47,7 +59,7 @@ Check [Troubleshooting](/ai-tools/troubleshooting) for errors and the [FAQ](/ai-
For anything else, report a problem through your preferred channel from the options below, including:
1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version)
-2. The network you are on (Regtest, Signet, or mainnet)
+2. The network you are on (signet or mainnet)
3. The tool name that failed and the error text
4. Host and runtime versions (MCP client, Node.js)
5. Your config with the seed and any keys removed
diff --git a/mintlify-docs/ai-tools/build-local-rgb-agent.mdx b/mintlify-docs/ai-tools/build-local-rgb-agent.mdx
new file mode 100644
index 0000000..f818730
--- /dev/null
+++ b/mintlify-docs/ai-tools/build-local-rgb-agent.mdx
@@ -0,0 +1,266 @@
+---
+title: "Build a Local AI Agent with RGB in 15 Minutes"
+sidebarTitle: "Build a Local RGB Agent"
+description: "Run a signet RGB Lightning Node, connect it to kaleido-mcp, and drive it with a local QVAC model through KaleidoMind: check balances, receive and send USDT, quote and swap"
+---
+
+This tutorial takes you from an empty machine to a local language model that reads and moves RGB assets on signet. Every piece runs on your computer: the model runs through [QVAC](https://www.npmjs.com/package/@qvac/sdk), the reasoning engine is [KaleidoMind](/ai-tools/kaleido-mind), the tools come from [`kaleido-mcp`](/ai-tools/mcp-servers), and the RGB Lightning Node runs in Docker through [KaleidoCLI](/cli/introduction). The only network calls go to your node, to the signet KaleidoSwap API, and to the Bitcoin and RGB services the node itself needs.
+
+```
+you ─▶ KaleidoMind (QVAC model, local) ─▶ kaleido-mcp (stdio) ─▶ RGB Lightning Node (Docker, signet)
+ └──────────▶ api.signet.kaleidoswap.com
+```
+
+
+ Everything here runs on signet, with test coins that have no value. Do not reuse a seed or a password from this tutorial anywhere else.
+
+
+## Prerequisites
+
+| Requirement | Why |
+|-------------|-----|
+| Node.js 20+ | Runs `kaleido-mcp` and the KaleidoMind host |
+| Python 3.10+ | Runs KaleidoCLI |
+| Docker with Compose | Runs the RGB Lightning Node |
+| A GitHub account | Signs you in to the RGB faucet |
+| About 1 GB of free disk | For the local model and the node's data |
+
+No API key and no hosted LLM are needed.
+
+## 1. Start a Signet RGB Lightning Node
+
+Install KaleidoCLI with its install script. It is not on PyPI yet, so `pip install` will not find it:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh
+```
+
+Create and start one node with the signet defaults, then initialise and unlock its wallet:
+
+```bash
+kaleido setup # creates and starts one signet node in Docker
+kaleido node init # once: sets the wallet password and prints the mnemonic
+kaleido node unlock # after every restart
+kaleido node info # confirms the node answers on http://localhost:3001
+```
+
+KaleidoCLI calls this network `mutinynet`; it is the same signet that the KaleidoSwap signet API and the RGB faucet use. Write down the mnemonic that `kaleido node init` prints.
+
+
+ The [Node Environments](/cli/node-environments) page covers running several nodes, switching between them, and reading logs.
+
+
+## 2. Fund the Node
+
+RGB assets live on Bitcoin UTXOs, so the node needs a little signet BTC before it can receive anything.
+
+
+
+ Print an on-chain address and send it coins from the public [Mutinynet faucet](https://faucet.mutinynet.com):
+
+ ```bash
+ kaleido wallet address
+ ```
+
+ Signet blocks arrive about every 30 seconds. Check with `kaleido wallet balance`.
+
+
+
+ Split some of that BTC into UTXOs that can hold RGB allocations:
+
+ ```bash
+ kaleido wallet create-utxos
+ ```
+
+
+
+ Create an RGB invoice. Leave out the asset ID to accept any asset:
+
+ ```bash
+ kaleido asset invoice
+ ```
+
+ Open the [KaleidoSwap RGB faucet](https://faucet.mutinynet.kaleidoswap.com), sign in with GitHub, and paste the invoice. Once the transfer confirms, `kaleido asset refresh` followed by `kaleido asset list` shows the asset.
+
+
+
+## 3. Run kaleido-mcp on Signet
+
+`KALEIDO_NETWORK=signet` points `kaleido-mcp` at `https://api.signet.kaleidoswap.com` and Spark's test network. Point `RLN_NODE_URL` at the node from step 1:
+
+```bash
+KALEIDO_NETWORK=signet RLN_NODE_URL=http://localhost:3001 npx -y kaleido-mcp
+```
+
+The server logs `network: signet` and waits on stdio. You do not need to keep it running by hand: the agent in the next step starts it as a child process. `WDK_SEED` is optional here; without it the Spark tools stay off and the RGB, DEX, payment and market tools still work. See [MCP Servers](/ai-tools/mcp-servers#network-preset) for every variable.
+
+
+ Want to try the tools before writing any code? Add the same command to Claude Desktop or Claude Code with the config in [Client Configuration](/ai-tools/mcp-servers#client-configuration), then ask for your RGB balance. The rest of this tutorial swaps that hosted model for a local one.
+
+
+## 4. Wire a Local QVAC Model with KaleidoMind
+
+Create a project and install the engine, the QVAC SDK, and the MCP client:
+
+```bash
+mkdir rgb-agent && cd rgb-agent
+npm init -y && npm pkg set type=module
+npm install @kaleidorg/mind @qvac/sdk @modelcontextprotocol/sdk
+```
+
+KaleidoMind works with `@qvac/sdk` 0.13 and later; installing the latest release is recommended. Save this as `agent.mjs`:
+
+```js agent.mjs
+import { createInterface } from 'node:readline/promises';
+import { completion, cancel, loadModel, QWEN3_600M_INST_Q4 } from '@qvac/sdk';
+import { Funnel, ToolRegistry, confirmReadback } from '@kaleidorg/mind';
+import { McpToolSource } from '@kaleidorg/mind/mcp';
+import { createQvacProvider } from '@kaleidorg/mind/qvac';
+
+// 1. kaleido-mcp on signet, launched over stdio
+const kaleido = new McpToolSource({
+ id: 'kaleido',
+ transport: {
+ kind: 'stdio',
+ command: 'npx',
+ args: ['-y', 'kaleido-mcp'],
+ env: {
+ PATH: process.env.PATH,
+ HOME: process.env.HOME,
+ KALEIDO_NETWORK: 'signet',
+ RLN_NODE_URL: 'http://localhost:3001',
+ },
+ },
+});
+await kaleido.connect();
+
+// 2. A local model through QVAC (downloaded on first run)
+const modelId = await loadModel({
+ modelSrc: QWEN3_600M_INST_Q4,
+ modelType: 'llm',
+ modelConfig: { ctx_size: 8192, tools: true },
+});
+const provider = createQvacProvider({ completion, cancel, getModelId: () => modelId });
+
+// 3. The tiered funnel, with a confirmation prompt before any spend
+const funnel = new Funnel({ provider, tools: new ToolRegistry([kaleido]) });
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+while (true) {
+ const text = await rl.question('\n> ');
+ if (!text.trim()) continue;
+ const out = await funnel.runTurn(text, {
+ onConfirm: async (call) => {
+ const answer = await rl.question(`${confirmReadback(call)} [y/N] `);
+ return { approved: answer.trim().toLowerCase() === 'y' };
+ },
+ });
+ console.log(out.text);
+}
+```
+
+Run it:
+
+```bash
+node agent.mjs
+```
+
+The first start downloads the model. Every fund-moving tool pauses on the `onConfirm` callback, so nothing leaves the node until you type `y`.
+
+
+ This is a minimal host. The [`@kaleidorg/mind` README](https://www.npmjs.com/package/@kaleidorg/mind) and the `examples/node-minimal` and `examples/rgb-agent` folders in the [kaleido-mind repository](https://github.com/kaleidoswap/kaleido-mind) go further, with skills, recipes, and a larger model. A 0.6B model handles the fast path and the recipes well; for open-ended requests a larger model such as Qwen3 1.7B or 4B does noticeably better.
+
+
+## 5. Prompts to Try
+
+Go read-only first, then receive, then spend.
+
+| Prompt | What runs |
+|--------|-----------|
+| `What RGB assets does my node hold, and how much of each?` | `wdk_list_assets`, `wdk_get_asset_balance` |
+| `Show my BTC balance on-chain and in Lightning.` | `wdk_get_balances` |
+| `Create an RGB invoice to receive 10 USDT, using transport endpoint rpcs://proxy.iriswallet.com/0.2/json-rpc.` | `wdk_create_rgb_invoice` |
+| `Send 5 USDT to this RGB invoice: ` | `wdk_send_asset` 🔒 |
+| `Quote 100000 sats of BTC over Lightning into USDT over RGB Lightning. Do not execute.` | `kaleidoswap_get_quote` |
+| `Swap 100000 sats into USDT with an atomic swap.` | `kaleidoswap_get_quote` → `kaleidoswap_atomic_init` → `wdk_atomic_taker` → `kaleidoswap_atomic_execute` 🔒 → `kaleidoswap_atomic_status` |
+
+KaleidoMind may call the legacy `rln_*` names for the same tools; `kaleido-mcp` serves both.
+
+To try a send without a second wallet, ask a friend for an RGB invoice, or create one on a second node with `kaleido node create`.
+
+
+ An atomic swap settles over Lightning, so the node needs a channel with the KaleidoSwap maker that carries the asset. The quickest way to get one on signet is to buy it from the LSP: `Buy a channel from the KaleidoSwap LSP preloaded with 10 USDT` runs `kaleidoswap_lsp_quote_asset_channel` and `kaleidoswap_lsp_create_asset_channel`, which you pay on-chain. Allow a few blocks for the channel to open before you swap.
+
+
+## Mock Mode: No Node, No Funds
+
+To build the agent logic before the node is ready, or in CI, swap the MCP source for the stateful mock wallet in `@kaleidorg/mind/testing`. It is bound to the same tool contract, so the code that drives it later drives a real node:
+
+```js mock.mjs
+import { Funnel, confirmReadback } from '@kaleidorg/mind';
+import { MockWallet, scriptedProvider } from '@kaleidorg/mind/testing';
+
+const wallet = new MockWallet();
+const funnel = new Funnel({ provider: scriptedProvider(), tools: wallet.registry() });
+
+const out = await funnel.runTurn('what is my balance?', {
+ onConfirm: async (call) => {
+ console.log(confirmReadback(call));
+ return { approved: true };
+ },
+});
+console.log(out.text);
+```
+
+`scriptedProvider()` needs no model at all. Replace it with the QVAC provider from step 4 to test a real model against the mock wallet, then replace `wallet.registry()` with `new ToolRegistry([kaleido])` to go live.
+
+## Troubleshooting
+
+
+
+ The installer puts `kaleido` in a user script directory that may not be on your `PATH` yet. Open a new terminal, or follow the path the installer printed. See [CLI Installation](/cli/installation).
+
+
+
+ Run `kaleido node info`. If it fails, start the containers with `kaleido node up` and unlock with `kaleido node unlock`; the wallet locks again on every restart. Then check that `RLN_NODE_URL` matches the URL that `kaleido node list` marks as active.
+
+
+
+ Run `kaleido asset refresh` and wait for a confirmation. If the node has no free UTXOs, the invoice cannot be created or settled: run `kaleido wallet create-utxos` again after funding with BTC.
+
+
+
+ The payer fetches the transfer data from an RGB proxy listed in the invoice. Create the invoice with `kaleido asset invoice`, which adds the default proxy, or name the proxy in your prompt as in the table above.
+
+
+
+ Confirm `kaleido-mcp` logged `network: signet`. An explicit `KALEIDOSWAP_API_URL` or `KALEIDO_API_URL` in your environment overrides the preset.
+
+
+
+ Check `wdk_list_channels`: you need a usable channel with the maker that carries the asset you are buying or selling. Without one the quote works but settlement cannot.
+
+
+
+ Small models are weak at open-ended planning. Phrase requests concretely, as in the prompts above, or load a larger QVAC model. KaleidoMind's recipes handle the multi-step flows deterministically so the model only fills slots.
+
+
+
+More fixes are in [AI Tools Troubleshooting](/ai-tools/troubleshooting).
+
+## Ideas for Hackathon Projects
+
+
+
+ QVAC also runs speech-to-text and text-to-speech locally. `createQvacVoice` and `runVoiceAssistant` in `@kaleidorg/mind/qvac` give you a hands-free loop with a spoken confirmation before every spend.
+
+
+ Let the agent find a paid API with `search_paid_apis`, then pay it per call over Lightning with the `mpp_*` and `l402_*` tools. No signups, no API keys.
+
+
+ Watch prices with `l402_get_price` and `kaleidoswap_get_spreads`, and rebalance between BTC and USDT with atomic swaps. Keep the confirmation gate on until the decisions look right.
+
+
+ Issue a ticket or loyalty token as a new RGB asset. Today this works from the CLI (`kaleido asset issue nia`) and against KaleidoMind's mock wallet; `kaleido-mcp` does not expose an issuance tool yet.
+
+
diff --git a/mintlify-docs/ai-tools/faq.mdx b/mintlify-docs/ai-tools/faq.mdx
index d1ee3c7..654bc40 100644
--- a/mintlify-docs/ai-tools/faq.mdx
+++ b/mintlify-docs/ai-tools/faq.mdx
@@ -46,11 +46,20 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody,
- The tools can reach mainnet, but treat it as the last step rather than the first. Start on Regtest or Signet with a throwaway seed, keep `dry_run` enabled on KaleidoAgent until the dry-run decisions look correct, and only then switch networks.
+ The tools can reach mainnet, but treat it as the last step rather than the first. Start on signet with a throwaway seed, keep `dry_run` enabled on KaleidoAgent until the dry-run decisions look correct, and only then switch networks.
Note that the different surfaces carry different maturity: KaleidoAgent and the MCP servers drive live funds directly, and an LLM making a wrong tool call is a real failure mode.
+
+ Everything in these docs runs on signet. Point `kaleido-mcp` at it with `KALEIDO_NETWORK=signet`, which selects the signet KaleidoSwap API at `https://api.signet.kaleidoswap.com`.
+
+ - **RGB assets:** the [KaleidoSwap RGB faucet](https://faucet.mutinynet.kaleidoswap.com) sends test assets to an RGB invoice from your node. Sign in with GitHub.
+ - **A node:** [KaleidoCLI](/cli/installation) runs a signet RGB Lightning Node locally with `kaleido setup`.
+
+ [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent) walks through both.
+
+
Three separate cost lines:
@@ -60,16 +69,23 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody,
- Several independent controls, and it is worth using more than one:
+ On KaleidoAgent, one control is enforced in code:
| Control | Effect |
|---------|--------|
- | `dry_run` | Simulates the decision without executing |
+ | `dry_run` | Blocks execution before any tool is called. Simulates the decision without executing |
+
+ The rest are passed to the model as operating rules rather than enforced independently, so treat them as guidance and not as a spending limit:
+
+ | Control | Intended effect |
+ |---------|--------|
| `max_swap_usd` | Caps a single trade |
| `stop_loss_btc_sats` | Halts all trading below a BTC threshold |
| `min_btc_reserve_sats` | Keeps a floor across the node and Spark |
| `max_concurrent_orders` | Caps simultaneous open orders |
+ The controls that hold regardless of what the model decides are `dry_run` and keeping the funded balance small.
+
On KaleidoMind the equivalent is structural rather than configured: fund-moving tools are marked `requiresConfirmation` and pause for the host's confirmation sheet.
@@ -84,7 +100,7 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody,
- Yes. Every repository is public under [github.com/kaleidoswap](https://github.com/kaleidoswap): the MCP servers, KaleidoAgent, KaleidoMind, and the skills themselves. See [Additional Resources](/ai-tools/additional-resources) for the direct links.
+ Yes, with one caveat. The gateway, the per-wallet MCP servers, KaleidoAgent, KaleidoMind and the skills are all public under [github.com/kaleidoswap](https://github.com/kaleidoswap). `kaleido-mcp`, KaleidoAgent and KaleidoMind are Apache 2.0. The three per-wallet servers are public but do not yet carry a licence file, so treat them as source-available until one lands. See [Additional Resources](/ai-tools/additional-resources) for the direct links.
@@ -99,7 +115,7 @@ Check the [Troubleshooting](/ai-tools/troubleshooting) for errors rather than qu
For anything else, report a problem through your preferred channel from the options below, including:
1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version)
-2. The network you are on (Regtest, Signet, or mainnet)
+2. The network you are on (signet or mainnet)
3. The tool name that failed and the error text
4. Host and runtime versions (MCP client, Node.js)
5. Your config with the seed and any keys removed
diff --git a/mintlify-docs/ai-tools/getting-started.mdx b/mintlify-docs/ai-tools/getting-started.mdx
index 775b5ed..fa9559d 100644
--- a/mintlify-docs/ai-tools/getting-started.mdx
+++ b/mintlify-docs/ai-tools/getting-started.mdx
@@ -10,12 +10,12 @@ Four surfaces expose the same Bitcoin tools to a model, and they differ mostly i
| Requirement | Details |
|-------------|---------|
-| **A test network** | Regtest or Signet. Never a first run on mainnet |
+| **A test network** | Signet. The KaleidoSwap API runs a signet instance at `https://api.signet.kaleidoswap.com`, and the [RGB faucet](https://faucet.mutinynet.kaleidoswap.com) sends test assets. Never a first run on mainnet |
| **A wallet seed** | A throwaway BIP-39 mnemonic for the test network, set as `WDK_SEED` |
-| **A node** | Only for the `wdk_*` tools and atomic swaps. Spark tools need just a seed, market data needs nothing |
+| **A node** | Only for the `wdk_*` tools and atomic swaps. [KaleidoCLI](/cli/installation) starts a signet RGB Lightning Node with one command. Spark tools need just a seed, market data needs nothing |
| **An MCP host or LLM key** | Claude Desktop or another MCP client, or an Anthropic/OpenAI key for KaleidoAgent |
-If you have not installed anything yet, start with [Installation](/ai-tools/installation).
+If you have not installed anything yet, start with [Installation](/ai-tools/installation). For an end-to-end path from an empty machine to a local model moving RGB assets on signet, follow [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent).
## Pick a Surface
@@ -37,7 +37,7 @@ The two agent surfaces gate spending differently, and it is worth knowing which
| Surface | Gate |
|---------|------|
| **[KaleidoMind](/ai-tools/kaleido-mind)** | Structural. Every fund-moving tool is marked `requiresConfirmation`, so the engine pauses for the host's confirmation sheet. The model cannot bypass it |
-| **[KaleidoAgent](/ai-tools/kaleido-agent)** | Policy. `dry_run` plus the risk limits in `agent.config.json`, checked before submission |
+| **[KaleidoAgent](/ai-tools/kaleido-agent)** | Mixed. `dry_run` is enforced in code; the other risk limits in `agent.config.json` are rules given to the model, not an independent ceiling |
| **[MCP servers](/ai-tools/mcp-servers)** | Whatever your host provides. Most MCP clients prompt per tool call, but that is the client's behaviour, not the server's |
diff --git a/mintlify-docs/ai-tools/installation.mdx b/mintlify-docs/ai-tools/installation.mdx
index b5c92b8..6f70491 100644
--- a/mintlify-docs/ai-tools/installation.mdx
+++ b/mintlify-docs/ai-tools/installation.mdx
@@ -10,7 +10,7 @@ Each AI surface installs independently. Pick the one that matches what you are b
|---------|-------------|---------------|
| **[MCP servers](#mcp-servers)** | `npx` for the gateway, local build for the focused servers | Node.js 20+, an MCP host |
| **[KaleidoAgent](#kaleidoagent)** | Clone and build from source | Node.js 20+, KaleidoCLI, Nanobot, an LLM API key |
-| **[KaleidoMind](#kaleidomind)** | Ships inside the Desktop App, or build the repo for development | Desktop App, or pnpm and the QVAC SDK |
+| **[KaleidoMind](#kaleidomind)** | Ships inside the Desktop App, `npm install @kaleidorg/mind` for your own host, or build the repo for development | Desktop App, or Node.js and the QVAC SDK (`@qvac/sdk`) |
Every surface here signs with a real BIP-39 mnemonic or drives a live node. Start on test networks, keep `dry_run` enabled until a setup is verified, and never put a mainnet seed in a file you commit or share.
@@ -18,12 +18,20 @@ Each AI surface installs independently. Pick the one that matches what you are b
## MCP Servers
-`kaleido-mcp` is the fastest path to a working tool call, published to npm with no local build required:
+`kaleido-mcp` is the quickest path to a first tool call, published to npm. `KALEIDO_NETWORK=signet` points it at the signet KaleidoSwap API and Spark's test network in one variable:
```bash
-npx -y kaleido-mcp
+KALEIDO_NETWORK=signet npx -y kaleido-mcp
```
+
+ The docs describe `kaleido-mcp` 0.3.0 and later, which adds the `KALEIDO_NETWORK`
+ preset and the `kaleido_node_*` tools and settles swaps atomically only. If `npx`
+ resolves an older cached version, run `npx -y kaleido-mcp@latest` once.
+
+
+For the RGB tools you also need an RGB Lightning Node. [KaleidoCLI](/cli/installation) runs one on signet in Docker, see [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent) for the full path.
+
Three per-wallet servers, `wdk-wallet-mcp`, `wdk-wallet-spark-mcp`, and `wdk-wallet-liquid-mcp`, remain standalone rather than folded into the gateway and build from source:
```bash
@@ -64,6 +72,14 @@ The fastest path. The [Desktop App](/desktop-app/getting-started/installation) b
KaleidoMind depends on a local AI runtime and may not be available on Windows yet. Every trading and node feature works without it, so run the app in **Only Node** mode if Mind is unavailable on your platform.
+### In your own Node.js app
+
+```bash
+npm install @kaleidorg/mind @qvac/sdk
+```
+
+`@qvac/sdk` is an optional peer dependency, so the engine also runs without it against a mock provider. The [`@kaleidorg/mind` README](https://www.npmjs.com/package/@kaleidorg/mind) has the quickstart, and the [kaleido-mind repository](https://github.com/kaleidoswap/kaleido-mind) carries runnable examples (`examples/node-minimal`, `examples/rgb-agent`).
+
### From source, for development
```bash
diff --git a/mintlify-docs/ai-tools/kaleido-agent.mdx b/mintlify-docs/ai-tools/kaleido-agent.mdx
index 82d2c43..dfa4bce 100644
--- a/mintlify-docs/ai-tools/kaleido-agent.mdx
+++ b/mintlify-docs/ai-tools/kaleido-agent.mdx
@@ -76,17 +76,30 @@ Each loop is driven by a [skill](/ai-tools/skills).
## Risk Controls
-Risk limits live in `agent.config.json` under `portfolio`. They are checked before any swap is submitted.
+Risk limits live in `agent.config.json` under `portfolio`. They are not all enforced the same way, and the difference matters when you size them.
+
+`dry_run` is enforced in code. The swap executor refuses before any tool is called, so no phrasing in a prompt or a skill reaches past it.
| Parameter | Default | Effect |
|-----------|---------|--------|
-| `dry_run` | `true` | Simulates the decision without executing a swap |
+| `dry_run` | `true` | Blocks execution in code. Simulates the decision without executing a swap |
+
+The remaining parameters are passed to the model as operating rules, in the run prompt and in the skill files. They shape what a cooperative model does. They are not an independent ceiling, so a model that ignores them is not currently stopped by anything else.
+
+| Parameter | Default | Intended effect |
+|-----------|---------|--------|
| `max_swap_usd` | `200` | Caps the USD value of a single trade |
| `min_btc_reserve_sats` | `50000` | Minimum combined BTC balance across the RLN node and Spark |
| `stop_loss_btc_sats` | `30000` | Halts all trading below this BTC threshold |
| `rebalance_threshold_pct` | `5` | Minimum drift percentage that triggers a swap |
| `max_concurrent_orders` | `3` | Caps simultaneous open orders |
+
+ Treat the second table as guidance to the model, not as a spending limit. Until
+ these are enforced outside the reasoning loop, `dry_run` and a small funded
+ balance are the only controls that hold against a model that gets it wrong.
+
+
## Trading Modes
| Mode | Settlement |
@@ -180,7 +193,7 @@ With the agent running, drive one loop by hand and read what it decided before l
- Confirm `max_swap_usd`, `min_btc_reserve_sats`, and `stop_loss_btc_sats` match what you are willing to lose on a test network. These are checked before any swap is submitted, see [Risk Controls](#risk-controls) above.
+ Confirm `max_swap_usd`, `min_btc_reserve_sats`, and `stop_loss_btc_sats` match what you are willing to lose on a test network. These are passed to the model as rules rather than enforced in code, so keep `dry_run` on and the balance small until you trust the decisions, see [Risk Controls](#risk-controls) above.
diff --git a/mintlify-docs/ai-tools/kaleido-mind.mdx b/mintlify-docs/ai-tools/kaleido-mind.mdx
index c237c1a..da091cf 100644
--- a/mintlify-docs/ai-tools/kaleido-mind.mdx
+++ b/mintlify-docs/ai-tools/kaleido-mind.mdx
@@ -43,15 +43,17 @@ The canonical tool contract lives in core as `ToolDef[]`, with a `spend` flag th
| Layer | Status | Tools |
|-------|--------|-------|
| Spark | Shipped | `spark_get_balance` · `spark_get_address` · `spark_get_onchain_address` · `spark_create_invoice` · `spark_pay_invoice` 🔒 · `spark_send` 🔒 |
-| RLN / RGB | Shipped | `rln_get_balances` · `rln_get_node_info` · `rln_list_channels` · `rln_create_ln_invoice` · `rln_create_rgb_invoice` · `rln_pay_invoice` 🔒 · `rln_send_asset` 🔒 |
+| RLN / RGB | Shipped | `rln_get_balances` · `rln_get_node_info` · `rln_list_assets` · `rln_list_transfers` · `rln_list_channels` · `rln_create_ln_invoice` · `rln_create_rgb_invoice` · `rln_create_utxos` · `rln_pay_invoice` 🔒 · `rln_send_asset` 🔒 · `rln_issue_asset` 🔒 |
| Arkade | Shipped | `arkade_get_balance` · `arkade_get_address` · `arkade_send` 🔒 |
| Liquid | Planned, not implemented | `liquid_get_balance` · `liquid_create_invoice` · `liquid_send` 🔒 (type-defined in the contract, no adapter yet) |
+`rln_issue_asset` is part of the KaleidoMind contract and runs against the mock wallet in `@kaleidorg/mind/testing`, but `kaleido-mcp` does not expose an issuance tool yet, so a host bound to the gateway cannot issue an RGB asset through it today.
+
Plus cross-cutting router tools: `get_balances(layer?)`, `resolve_contact(name)`, `get_price(asset?, fiat?)`, `fiat_to_sats(amount, currency)`, `get_swap_quote`/`execute_swap`, the unified `send_payment(asset, amount, to, layer?)` that picks the rail automatically, and its receive counterpart `create_invoice(asset?, amount?, layer?)`.
### KaleidoSwap Trading & LSPS1
-Separate contracts for DEX trading (`kaleidoswap_get_quote`, `kaleidoswap_place_order`, `kaleidoswap_atomic_init`/`execute`/`status`) and LSP-agnostic channel orders (`lsp_get_info`, `lsp_get_network_info`, `lsp_estimate_fees`, `lsp_create_order`, `lsp_get_order`). The atomic swap chain runs as a single confirm-gated recipe (`kaleidoswapAtomicRecipe`): quote, then after one confirmation init on the maker, read the node's pubkey, whitelist the HTLC as taker, and execute.
+Separate contracts for DEX trading (`kaleidoswap_get_quote`, then `kaleidoswap_atomic_init`/`execute`/`status`; `kaleido-mcp` 0.3.0 settles swaps atomically only) and LSP-agnostic channel orders (`lsp_get_info`, `lsp_get_network_info`, `lsp_estimate_fees`, `lsp_create_order`, `lsp_get_order`). The atomic swap chain runs as a single confirm-gated recipe (`kaleidoswapAtomicRecipe`): quote, then after one confirmation init on the maker, read the node's pubkey, whitelist the HTLC as taker, and execute.
## Skills
@@ -59,7 +61,27 @@ Skills are Agent-Skills-spec playbooks (`SKILL.md` plus progressive disclosure)
## QVAC: On-Device Inference
-LLM, embedding, speech-to-text, and text-to-speech inference all run through the [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk), locally on-device by default, or delegated to an explicitly paired, user-controlled desktop for heavier work. Published as the `@kaleidorg/mind/qvac` subpath so the SDK stays a peer dependency rather than a hard requirement of core. Memory and RAG (long-term recall, wallet-history retrieval, merchant discovery) also route through QVAC's embeddings, with near-duplicate consolidation to keep memory from bloating.
+LLM, embedding, speech-to-text, and text-to-speech inference all run through the [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk), Tether's local AI runtime, locally on-device by default, or delegated to an explicitly paired, user-controlled desktop for heavier work. Published as the `@kaleidorg/mind/qvac` subpath so the SDK stays a peer dependency rather than a hard requirement of core. Memory and RAG (long-term recall, wallet-history retrieval, merchant discovery) also route through QVAC's embeddings, with near-duplicate consolidation to keep memory from bloating.
+
+| Package | Version |
+|---------|---------|
+| `@qvac/sdk` | The core engine works with 0.13 and later. Install the latest release, which is what the hosts and evals are tested against |
+| `@kaleidorg/mind` | Takes `@qvac/sdk` as an optional peer dependency, so the engine also runs with no model at all against the mock provider |
+
+`createQvacProvider` turns the SDK's `completion` into the engine's `LLMProvider`. The SDK functions are injected rather than imported, so the host owns the model lifecycle (`loadModel`, `unloadModel`) and the engine never pulls QVAC into a bundle that does not need it.
+
+## Build With It
+
+The [`@kaleidorg/mind` README](https://www.npmjs.com/package/@kaleidorg/mind) has a quickstart, and the [kaleido-mind repository](https://github.com/kaleidoswap/kaleido-mind) carries two runnable examples:
+
+| Example | What it shows |
+|---------|---------------|
+| `examples/node-minimal` | The smallest Node.js host: a QVAC model, the funnel, and a confirm callback |
+| `examples/rgb-agent` | A local agent bound to `kaleido-mcp` on signet, moving RGB assets on a real RGB Lightning Node |
+
+`@kaleidorg/mind/testing` provides a stateful `MockWallet` bound to the real tool contract and a scripted provider, so the full funnel, recipes and confirm gate run in CI or on a laptop with no node, no funds and no model.
+
+For a step-by-step version on signet, follow [Build a Local RGB Agent](/ai-tools/build-local-rgb-agent).
## Where It Runs
@@ -76,5 +98,5 @@ The fastest way to try it is the Desktop App. [Download the latest release](http
## Publishing & Subpaths
-Published from `packages/core` as `@kaleidorg/mind`, with subpaths: `./mcp` (MCP tool source helpers), `./skills` (skill loader), `./logger`, and `./qvac` (the on-device inference adapter). Also on npm: `apps/provider` as `@kaleidorg/mind-provider`, the Tauri desktop sidecar that the Desktop App embeds. The CLI in `apps/cli` is for terminal and eval use from the repository and is not published.
+Published from `packages/core` as `@kaleidorg/mind`, with subpaths: `./mcp` (MCP tool source helpers), `./skills` (skill loader), `./logger`, `./qvac` (the on-device inference adapter), and `./testing` (mock wallet and scripted provider). Also on npm: `apps/provider` as `@kaleidorg/mind-provider`, the Tauri desktop sidecar that the Desktop App embeds. The CLI in `apps/cli` is for terminal and eval use from the repository and is not published.
diff --git a/mintlify-docs/ai-tools/mcp-servers.mdx b/mintlify-docs/ai-tools/mcp-servers.mdx
index 411cf06..0038351 100644
--- a/mintlify-docs/ai-tools/mcp-servers.mdx
+++ b/mintlify-docs/ai-tools/mcp-servers.mdx
@@ -52,12 +52,19 @@ If you have an integration still pointing at `kaleidoswap-mcp` or `l402-gateway-
## Installation & Configuration
-`kaleido-mcp` is published to npm, so the fastest path needs no local build:
+`kaleido-mcp` is published to npm, which is the quickest way to a first tool call. Start on signet:
```bash
-npx -y kaleido-mcp
+KALEIDO_NETWORK=signet npx -y kaleido-mcp
```
+
+ This page documents `kaleido-mcp` 0.3.0 and later. 0.3.0 adds the `KALEIDO_NETWORK`
+ preset and the `kaleido_node_*` lifecycle tools, and drops the order-based swap
+ tools in favour of atomic swaps. If `npx` resolves an older cached version, run
+ `npx -y kaleido-mcp@latest` once, or build from source.
+
+
In practice an MCP host runs this for you, point its config at the command (see [Client Configuration](#client-configuration) below). For development, or to run a specific commit, build from source instead:
```bash
@@ -70,24 +77,36 @@ npm run build
Either way, the server reads the same environment variables and speaks stdio by default:
```bash
-# stdio (Claude Desktop, KaleidoAgent, ...)
-WDK_SEED="word1 word2 ..." node dist/index.js
+# stdio (Claude Desktop, Claude Code, KaleidoAgent, ...)
+KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js
# HTTP transport
-PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
+PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js
```
+### Network Preset
+
+`KALEIDO_NETWORK` picks a set of defaults in one variable. It accepts `mainnet` (the default) or `signet`:
+
+| Preset | KaleidoSwap API | Spark network |
+|--------|-----------------|---------------|
+| `mainnet` | `https://api.kaleidoswap.com` | `MAINNET` |
+| `signet` | `https://api.signet.kaleidoswap.com` | Spark's test network (`REGTEST` in the Spark SDK) |
+
+The preset only fills in defaults. Any variable you set explicitly, such as `KALEIDOSWAP_API_URL` or `SPARK_NETWORK`, wins over it. An unknown value stops the server at startup rather than silently falling back to mainnet. `RLN_NODE_URL` is not part of the preset: point it at your own node, which on signet is usually the one [KaleidoCLI](/cli/installation) runs on `http://localhost:3001`.
+
| Env var | Required | Description |
|---------|----------|--------------|
+| `KALEIDO_NETWORK` | No | `mainnet` (default) or `signet`. Sets the defaults in [Network Preset](#network-preset) |
| `WDK_SEED` | Yes, for Spark tools | BIP-39 mnemonic for the Spark wallet. The server still boots without it, the Spark tools are just disabled |
-| `SPARK_NETWORK` | No | `MAINNET` or `REGTEST` |
+| `SPARK_NETWORK` | No | Overrides the preset's Spark network: `MAINNET`, or `REGTEST` for Spark's test network |
| `SPARK_SCAN_API_KEY` | No | SparkScan API key |
| `SPARK_USDT_TOKEN` | No | Default Spark token identifier |
| `RLN_NODE_URL` | No | RLN daemon URL, default `http://localhost:3001` |
-| `KALEIDOSWAP_API_URL` | No | KaleidoSwap API URL, default `https://api.kaleidoswap.com` |
+| `KALEIDOSWAP_API_URL` | No | Overrides the preset's KaleidoSwap API URL. `KALEIDO_API_URL` is accepted as well |
| `KALEIDO_BIN` | No | Path to the `kaleido` binary, for the node lifecycle tools |
| `KALEIDO_NODE_URL` | No | Node URL passed as `--node-url` to the node lifecycle tools |
-| `KALEIDO_API_URL` | No | API URL passed as `--api-url` to the node lifecycle tools |
+| `KALEIDO_API_URL` | No | API URL passed as `--api-url` to the node lifecycle tools, and a fallback for `KALEIDOSWAP_API_URL` |
| `KALEIDO_ENV_NAME` | No | Default environment name for the node lifecycle tools |
| `PORT` | No | Enable Streamable HTTP transport instead of stdio |
| `MCP_AUTH_TOKEN` | No | Bearer token for HTTP mode |
@@ -164,11 +183,6 @@ All tools below are served by `kaleido-mcp` over a single connection. The 🔒 i
| `kaleidoswap_get_pairs` | Tradeable pairs with available layer routes |
| `kaleidoswap_get_quote` | Price quote for a swap, returns output amount, price, fee, `rfq_id` |
| `kaleidoswap_get_spreads` | Quotes across every route for a pair, to compare or find arbitrage |
- | `kaleidoswap_place_order` | Place a REST swap order, returns a `deposit_address` |
- | `kaleidoswap_get_order_status` | Poll order status until `FILLED`, `FAILED`, `EXPIRED`, or `CANCELLED` |
- | `kaleidoswap_get_open_orders` | Orders placed in this session with last known status |
- | `kaleidoswap_cancel_order` | Mark an order cancelled in the local session tracker |
- | `kaleidoswap_get_position` | Session trading stats: fill rate, volume by asset |
| `kaleidoswap_atomic_init` | Step 1 of an atomic swap, returns `swapstring` and `payment_hash` |
| `kaleidoswap_atomic_execute` 🔒 | Step 3, confirm execution after `wdk_atomic_taker` whitelists the HTLC |
| `kaleidoswap_atomic_status` | Poll atomic swap status by `payment_hash` |
@@ -179,7 +193,7 @@ All tools below are served by `kaleido-mcp` over a single connection. The 🔒 i
| `kaleidoswap_lsp_quote_asset_channel` | Quote a new channel pre-loaded with an RGB asset (USDT, XAUT) |
| `kaleidoswap_lsp_create_asset_channel` 🔒 | Order a new asset-preloaded channel from the LSP |
- Configured with `KALEIDOSWAP_API_URL`. See the [Swap Protocol](/api-reference/swap-protocol) and [RGB LSPS1 APIs](/api-reference/rgb-lsps1-apis) references for the underlying endpoints.
+ Configured with `KALEIDO_NETWORK`, or `KALEIDOSWAP_API_URL` for a custom endpoint. Swaps are atomic only: the order-based tools (`kaleidoswap_place_order`, `kaleidoswap_get_order_status` and the rest) were removed in 0.3.0. See the [Swap Protocol](/api-reference/swap-protocol) and [RGB LSPS1 APIs](/api-reference/rgb-lsps1-apis) references for the underlying endpoints.
@@ -227,30 +241,37 @@ All tools below are served by `kaleido-mcp` over a single connection. The 🔒 i
## Client Configuration
-Add a server to an MCP host such as Claude Desktop. `npx` works for the published gateway; the standalone wallet servers run from a local build.
+Add a server to an MCP host such as Claude Desktop or Claude Code. `npx` works for the published gateway; the standalone wallet servers run from a local build.
These configuration files hold a real BIP-39 mnemonic in plain text. Start on test networks and never commit or share a config containing a mainnet seed.
-```json kaleido-mcp
+```json Claude Desktop
{
"mcpServers": {
"kaleido": {
"command": "npx",
"args": ["-y", "kaleido-mcp"],
"env": {
+ "KALEIDO_NETWORK": "signet",
"WDK_SEED": "your twelve word seed phrase",
- "SPARK_NETWORK": "REGTEST",
- "RLN_NODE_URL": "http://localhost:3001",
- "KALEIDOSWAP_API_URL": "https://api.kaleidoswap.com"
+ "RLN_NODE_URL": "http://localhost:3001"
}
}
}
}
```
+```bash Claude Code
+claude mcp add kaleido \
+ --env KALEIDO_NETWORK=signet \
+ --env RLN_NODE_URL=http://localhost:3001 \
+ --env WDK_SEED="your twelve word seed phrase" \
+ -- npx -y kaleido-mcp
+```
+
```json wdk-wallet-mcp
{
"mcpServers": {
@@ -281,13 +302,15 @@ Add a server to an MCP host such as Claude Desktop. `npx` works for the publishe
```
+On Claude Desktop the file is `claude_desktop_config.json` (**Settings > Developer > Edit Config**). `WDK_SEED` is optional: leave it out and the Spark tools are disabled while the RGB node, DEX, payment and market tools keep working. The standalone Spark server takes no network preset, so it sets `SPARK_NETWORK` directly; `REGTEST` is the name the Spark SDK gives its hosted test network.
+
## First Run
Go read-only first, then quoting, then execution. Every step after the first one moves real value.
- Drop the `kaleido-mcp` block into your MCP host's config, pointing `KALEIDOSWAP_API_URL` at a test environment and `SPARK_NETWORK` at `REGTEST`. The full JSON is in [Client Configuration](#client-configuration) above.
+ Drop the `kaleido-mcp` block into your MCP host's config with `KALEIDO_NETWORK` set to `signet`. The full JSON is in [Client Configuration](#client-configuration) above.
@@ -318,7 +341,7 @@ Go read-only first, then quoting, then execution. Every step after the first one
Ask for a price without placing anything:
```
- Quote 100000 sats of BTC into USDT. Do not place an order.
+ Quote 100000 sats of BTC into USDT. Do not execute anything.
```
`kaleidoswap_get_quote` returns an `rfq_id`, raw amounts, the fee, and an expiry. Read the raw amounts carefully: they are in the asset's smallest unit, not display units.
diff --git a/mintlify-docs/ai-tools/skills.mdx b/mintlify-docs/ai-tools/skills.mdx
index 1eca60c..a0c83f4 100644
--- a/mintlify-docs/ai-tools/skills.mdx
+++ b/mintlify-docs/ai-tools/skills.mdx
@@ -16,7 +16,7 @@ A skill is a self-contained `SKILL.md` file loaded at runtime. It scopes which t
| `dca` | Scheduled, price-aware purchases bounded by user-set caps |
| `wallet-assistant` | Interactive balances, invoices, payments, and swaps over chat |
| `cross-l2` | Asset moves between Spark, Lightning, and on-chain Bitcoin |
-| `kaleidoswap` | KaleidoSwap DEX reference: quotes, atomic swaps, REST orders, open positions |
+| `kaleidoswap` | KaleidoSwap DEX reference: quotes and atomic swaps |
| `mpp` | Access to HTTP 402-gated APIs over Lightning |
| `node-manager` | RGB Lightning Node lifecycle, wallet unlock, channel and balance inspection |
| `portfolio-loop` | Scheduled portfolio rebalancer: measures drift against targets, executes the minimum atomic swap, folds in DCA |
@@ -29,3 +29,14 @@ Each file is published under [`skills/` in the kaleido-agent repository](https:/
Skills can be listed, enabled, and disabled at runtime through the agent's `/skills` [status API endpoint](/ai-tools/kaleido-agent#status-api).
+## Use the skills in Claude Code
+
+The [KaleidoMind](/ai-tools/kaleido-mind) repository ships its bundled skills as a Claude Code plugin, together with the `kaleido-mcp` server configured for signet:
+
+```bash
+/plugin marketplace add kaleidoswap/kaleido-mind
+/plugin install kaleido-mind@kaleidoswap
+```
+
+The plugin runs `npx -y kaleido-mcp` with `KALEIDO_NETWORK=signet`. Set `RLN_NODE_URL` to point at your RGB Lightning Node and `WDK_SEED` to enable the Spark wallet tools. Some KaleidoMind skills (Spark wallet, Bitrefill, Flashnet, merchant finder) rely on tools that only the KaleidoMind runtime provides.
+
diff --git a/mintlify-docs/ai-tools/troubleshooting.mdx b/mintlify-docs/ai-tools/troubleshooting.mdx
index f2b0b82..255cc91 100644
--- a/mintlify-docs/ai-tools/troubleshooting.mdx
+++ b/mintlify-docs/ai-tools/troubleshooting.mdx
@@ -98,7 +98,7 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f
**Symptoms**: Tools return empty balances for a wallet you know is funded.
**Solutions**:
- 1. **Check the network.** `SPARK_NETWORK` and the node's own network must match where the funds are. A Regtest seed shows nothing on mainnet.
+ 1. **Check the network.** `KALEIDO_NETWORK` (or `SPARK_NETWORK`) and the node's own network must match where the funds are. A signet wallet shows nothing on mainnet, and the reverse.
2. **Confirm the seed.** A different mnemonic derives a different wallet, not an empty one.
3. **Wait for sync.** A node that has just unlocked may not have caught up to the chain tip.
4. **Distinguish on-chain from Lightning.** `wdk_get_balances` separates vanilla and colored UTXOs from the Lightning balance, and an asset in a channel is not an on-chain balance.
@@ -155,7 +155,7 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f
**Symptoms**: The agent was executing, then stopped submitting swaps.
- **Cause**: A risk limit tripped. Most often `stop_loss_btc_sats`, which halts all trading below its BTC threshold, or `min_btc_reserve_sats`.
+ **Cause**: Usually `dry_run` is still on, so decisions are simulated rather than executed. Otherwise the model declined to trade, which can happen when it applies `stop_loss_btc_sats` or `min_btc_reserve_sats` from its instructions, or when a tool call failed.
**Solutions**:
1. Read `GET /status` for balances and recent runs.
@@ -201,7 +201,7 @@ Check the [FAQ](/ai-tools/faq) for questions rather than errors, and [Additional
For anything else, report a problem through your preferred channel from the options below, including:
1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version)
-2. The network you are on (Regtest, Signet, or mainnet)
+2. The network you are on (signet or mainnet)
3. The tool name that failed and the error text
4. Host and runtime versions (MCP client, Node.js)
5. Your config with the seed and any keys removed
diff --git a/mintlify-docs/cn/ai-tools/additional-resources.mdx b/mintlify-docs/cn/ai-tools/additional-resources.mdx
index 44ed165..3d76d7b 100644
--- a/mintlify-docs/cn/ai-tools/additional-resources.mdx
+++ b/mintlify-docs/cn/ai-tools/additional-resources.mdx
@@ -6,7 +6,7 @@ description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP
## 源码仓库
-每一种 AI 接入方式都在 [KaleidoSwap 组织](https://github.com/kaleidoswap)下开源。
+每一种 AI 接入方式都公开在 [KaleidoSwap 组织](https://github.com/kaleidoswap) 下，其中网关、KaleidoAgent 和 KaleidoMind 采用 Apache 2.0。
@@ -16,13 +16,25 @@ description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP
本地端引擎：分层漏斗、recipe 引擎、工具契约、记忆与检索，以及评测框架。
- 把所有领域组合到一条连接背后的统一网关。已发布到 npm。
+ 把所有领域组合到一条连接背后的统一网关。以 `kaleido-mcp` 发布到 npm；0.3.0 新增 `KALEIDO_NETWORK=signet` 预设。
以语音控制承载 KaleidoMind 的 React Native 移动钱包。
+
+ `kaleido` 命令行工具，也可以在 Docker 中运行本地 signet RGB Lightning Node。
+
+## 测试网络 {#test-network}
+
+| 资源 | 位置 |
+|----------|-------|
+| KaleidoSwap API（signet） | `https://api.signet.kaleidoswap.com` |
+| RGB 水龙头（GitHub 登录） | [faucet.mutinynet.kaleidoswap.com](https://faucet.mutinynet.kaleidoswap.com) |
+| 本地 signet RGB Lightning Node | [KaleidoCLI](/cn/cli/installation)，`kaleido setup` |
+| 端到端演练 | [构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent) |
+
## 协议规范
@@ -47,7 +59,7 @@ description: "KaleidoSwap AI 工具的相关链接：各个源码仓库、MCP
其他情况请通过下面任一渠道反馈问题，并附上：
1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本）
-2. 你所在的网络（regtest、signet 或主网）
+2. 你所在的网络（signet 或主网）
3. 失败的工具名称和报错文本
4. 宿主与运行时版本（MCP 客户端、Node.js）
5. 你的配置，并移除其中的种子和所有密钥
diff --git a/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx b/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx
new file mode 100644
index 0000000..71681c4
--- /dev/null
+++ b/mintlify-docs/cn/ai-tools/build-local-rgb-agent.mdx
@@ -0,0 +1,266 @@
+---
+title: "15 分钟构建一个支持 RGB 的本地 AI 代理"
+sidebarTitle: "构建本地 RGB 代理"
+description: "运行一个 signet RGB Lightning Node，把它接入 kaleido-mcp，再通过 KaleidoMind 用本地 QVAC 模型驱动它：查询余额、收发 USDT、报价与交换"
+---
+
+本教程带你从一台空机器出发，最终得到一个能在 signet 上读取并转移 RGB 资产的本地语言模型。所有组件都运行在你的电脑上：模型通过 [QVAC](https://www.npmjs.com/package/@qvac/sdk) 运行，推理引擎是 [KaleidoMind](/cn/ai-tools/kaleido-mind)，工具来自 [`kaleido-mcp`](/cn/ai-tools/mcp-servers)，RGB Lightning Node 则通过 [KaleidoCLI](/cn/cli/introduction) 在 Docker 中运行。唯一的网络调用是发往你的节点、signet KaleidoSwap API，以及节点自身所需的比特币与 RGB 服务。
+
+```
+你 ─▶ KaleidoMind（QVAC 模型，本地）─▶ kaleido-mcp（stdio）─▶ RGB Lightning Node（Docker，signet）
+ └──────────▶ api.signet.kaleidoswap.com
+```
+
+
+ 本教程的一切都运行在 signet 上，使用的测试币没有任何价值。不要在其他任何地方复用本教程中的种子或密码。
+
+
+## 前置条件 {#prerequisites}
+
+| 要求 | 用途 |
+|-------------|-----|
+| Node.js 20+ | 运行 `kaleido-mcp` 和 KaleidoMind 宿主 |
+| Python 3.10+ | 运行 KaleidoCLI |
+| Docker 与 Compose | 运行 RGB Lightning Node |
+| 一个 GitHub 账号 | 登录 RGB 水龙头 |
+| 约 1 GB 可用磁盘 | 存放本地模型和节点数据 |
+
+不需要任何 API 密钥，也不需要托管的 LLM。
+
+## 1. 启动一个 signet RGB Lightning Node {#1-start-a-signet-rgb-lightning-node}
+
+用安装脚本安装 KaleidoCLI。它尚未发布到 PyPI，所以 `pip install` 找不到它：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kaleidoswap/kaleido-cli/master/install.sh | sh
+```
+
+使用 signet 默认值创建并启动一个节点，然后初始化并解锁它的钱包：
+
+```bash
+kaleido setup # 在 Docker 中创建并启动一个 signet 节点
+kaleido node init # 仅一次：设置钱包密码并打印助记词
+kaleido node unlock # 每次重启后都要执行
+kaleido node info # 确认节点在 http://localhost:3001 上响应
+```
+
+KaleidoCLI 把这个网络称为 `mutinynet`，它与 KaleidoSwap signet API 和 RGB 水龙头使用的是同一个 signet。请记下 `kaleido node init` 打印的助记词。
+
+
+ [节点环境](/cn/cli/node-environments)页面介绍了如何运行多个节点、在节点之间切换以及查看日志。
+
+
+## 2. 为节点注资 {#2-fund-the-node}
+
+RGB 资产依附在比特币 UTXO 上，因此节点在接收任何资产之前需要少量 signet BTC。
+
+
+
+ 打印一个链上地址，并从公共的 [Mutinynet 水龙头](https://faucet.mutinynet.com)向它发币：
+
+ ```bash
+ kaleido wallet address
+ ```
+
+ signet 大约每 30 秒出一个块。用 `kaleido wallet balance` 查看余额。
+
+
+
+ 把一部分 BTC 拆分成可以承载 RGB 分配的 UTXO：
+
+ ```bash
+ kaleido wallet create-utxos
+ ```
+
+
+
+ 创建一张 RGB 发票。不指定资产 ID 即可接收任意资产：
+
+ ```bash
+ kaleido asset invoice
+ ```
+
+ 打开 [KaleidoSwap RGB 水龙头](https://faucet.mutinynet.kaleidoswap.com)，用 GitHub 登录并粘贴发票。转账确认后，先运行 `kaleido asset refresh`，再用 `kaleido asset list` 就能看到该资产。
+
+
+
+## 3. 在 signet 上运行 kaleido-mcp {#3-run-kaleido-mcp-on-signet}
+
+`KALEIDO_NETWORK=signet` 会把 `kaleido-mcp` 指向 `https://api.signet.kaleidoswap.com` 和 Spark 测试网络。把 `RLN_NODE_URL` 指向第 1 步中的节点：
+
+```bash
+KALEIDO_NETWORK=signet RLN_NODE_URL=http://localhost:3001 npx -y kaleido-mcp
+```
+
+服务器会输出 `network: signet` 并在 stdio 上等待。你不需要手动保持它运行：下一步中的代理会把它作为子进程启动。这里 `WDK_SEED` 是可选的；不设置时 Spark 工具保持关闭，RGB、DEX、支付和行情工具照常可用。全部变量见 [MCP 服务器](/cn/ai-tools/mcp-servers#network-preset)。
+
+
+ 想在写代码之前先试用这些工具？用[客户端配置](/cn/ai-tools/mcp-servers#client-configuration)中的配置把同一条命令添加到 Claude Desktop 或 Claude Code，然后询问你的 RGB 余额。本教程余下部分会把这个托管模型换成本地模型。
+
+
+## 4. 通过 KaleidoMind 接入本地 QVAC 模型 {#4-wire-a-local-qvac-model-with-kaleidomind}
+
+创建一个项目，安装引擎、QVAC SDK 和 MCP 客户端：
+
+```bash
+mkdir rgb-agent && cd rgb-agent
+npm init -y && npm pkg set type=module
+npm install @kaleidorg/mind @qvac/sdk @modelcontextprotocol/sdk
+```
+
+KaleidoMind 支持 `@qvac/sdk` 0.13 及以上版本，建议安装最新版本。把下面的代码保存为 `agent.mjs`：
+
+```js agent.mjs
+import { createInterface } from 'node:readline/promises';
+import { completion, cancel, loadModel, QWEN3_600M_INST_Q4 } from '@qvac/sdk';
+import { Funnel, ToolRegistry, confirmReadback } from '@kaleidorg/mind';
+import { McpToolSource } from '@kaleidorg/mind/mcp';
+import { createQvacProvider } from '@kaleidorg/mind/qvac';
+
+// 1. 通过 stdio 启动运行在 signet 上的 kaleido-mcp
+const kaleido = new McpToolSource({
+ id: 'kaleido',
+ transport: {
+ kind: 'stdio',
+ command: 'npx',
+ args: ['-y', 'kaleido-mcp'],
+ env: {
+ PATH: process.env.PATH,
+ HOME: process.env.HOME,
+ KALEIDO_NETWORK: 'signet',
+ RLN_NODE_URL: 'http://localhost:3001',
+ },
+ },
+});
+await kaleido.connect();
+
+// 2. 通过 QVAC 加载本地模型（首次运行时下载）
+const modelId = await loadModel({
+ modelSrc: QWEN3_600M_INST_Q4,
+ modelType: 'llm',
+ modelConfig: { ctx_size: 8192, tools: true },
+});
+const provider = createQvacProvider({ completion, cancel, getModelId: () => modelId });
+
+// 3. 分层漏斗，任何花费之前都会弹出确认
+const funnel = new Funnel({ provider, tools: new ToolRegistry([kaleido]) });
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+while (true) {
+ const text = await rl.question('\n> ');
+ if (!text.trim()) continue;
+ const out = await funnel.runTurn(text, {
+ onConfirm: async (call) => {
+ const answer = await rl.question(`${confirmReadback(call)} [y/N] `);
+ return { approved: answer.trim().toLowerCase() === 'y' };
+ },
+ });
+ console.log(out.text);
+}
+```
+
+运行它：
+
+```bash
+node agent.mjs
+```
+
+首次启动会下载模型。每个动用资金的工具都会在 `onConfirm` 回调处暂停，在你输入 `y` 之前，任何资金都不会离开节点。
+
+
+ 这是一个最小的宿主。[`@kaleidorg/mind` README](https://www.npmjs.com/package/@kaleidorg/mind) 以及 [kaleido-mind 仓库](https://github.com/kaleidoswap/kaleido-mind)中的 `examples/node-minimal` 和 `examples/rgb-agent` 目录走得更远，包含 skills、recipe 和更大的模型。0.6B 模型能很好地处理快速路径和 recipe；对于开放式请求，Qwen3 1.7B 或 4B 这类更大的模型表现明显更好。
+
+
+## 5. 可以尝试的提示词 {#5-prompts-to-try}
+
+先只读，再收款，最后花费。
+
+| 提示词 | 调用的工具 |
+|--------|-----------|
+| `What RGB assets does my node hold, and how much of each?` | `wdk_list_assets`、`wdk_get_asset_balance` |
+| `Show my BTC balance on-chain and in Lightning.` | `wdk_get_balances` |
+| `Create an RGB invoice to receive 10 USDT, using transport endpoint rpcs://proxy.iriswallet.com/0.2/json-rpc.` | `wdk_create_rgb_invoice` |
+| `Send 5 USDT to this RGB invoice: ` | `wdk_send_asset` 🔒 |
+| `Quote 100000 sats of BTC over Lightning into USDT over RGB Lightning. Do not execute.` | `kaleidoswap_get_quote` |
+| `Swap 100000 sats into USDT with an atomic swap.` | `kaleidoswap_get_quote` → `kaleidoswap_atomic_init` → `wdk_atomic_taker` → `kaleidoswap_atomic_execute` 🔒 → `kaleidoswap_atomic_status` |
+
+KaleidoMind 可能会用旧的 `rln_*` 名称调用同样的工具；`kaleido-mcp` 两种名称都提供。
+
+如果没有第二个钱包也想试试发送，可以向朋友要一张 RGB 发票，或者用 `kaleido node create` 在第二个节点上生成一张。
+
+
+ 原子交换通过闪电网络结算，因此节点需要与 KaleidoSwap 做市方之间有一条承载该资产的通道。在 signet 上获取通道最快的方式是向 LSP 购买：`Buy a channel from the KaleidoSwap LSP preloaded with 10 USDT` 会调用 `kaleidoswap_lsp_quote_asset_channel` 和 `kaleidoswap_lsp_create_asset_channel`，并通过链上付款。交换之前请等几个区块让通道打开。
+
+
+## Mock 模式：无需节点与资金 {#mock-mode-no-node-no-funds}
+
+如果想在节点就绪之前或在 CI 中构建代理逻辑，可以把 MCP 工具源换成 `@kaleidorg/mind/testing` 中的有状态 mock 钱包。它绑定的是同一份工具契约，因此驱动它的代码之后同样可以驱动真实节点：
+
+```js mock.mjs
+import { Funnel, confirmReadback } from '@kaleidorg/mind';
+import { MockWallet, scriptedProvider } from '@kaleidorg/mind/testing';
+
+const wallet = new MockWallet();
+const funnel = new Funnel({ provider: scriptedProvider(), tools: wallet.registry() });
+
+const out = await funnel.runTurn('what is my balance?', {
+ onConfirm: async (call) => {
+ console.log(confirmReadback(call));
+ return { approved: true };
+ },
+});
+console.log(out.text);
+```
+
+`scriptedProvider()` 完全不需要模型。把它换成第 4 步中的 QVAC provider，就能用真实模型测试 mock 钱包；再把 `wallet.registry()` 换成 `new ToolRegistry([kaleido])`，即可接入真实节点。
+
+## 故障排查 {#troubleshooting}
+
+
+
+ 安装程序会把 `kaleido` 放在一个用户脚本目录中，该目录可能还不在你的 `PATH` 里。请打开一个新的终端，或按照安装程序打印的路径操作。见 [CLI 安装](/cn/cli/installation)。
+
+
+
+ 运行 `kaleido node info`。如果失败，用 `kaleido node up` 启动容器，再用 `kaleido node unlock` 解锁；每次重启后钱包都会重新锁定。然后确认 `RLN_NODE_URL` 与 `kaleido node list` 标记为当前活动的 URL 一致。
+
+
+
+ 运行 `kaleido asset refresh` 并等待一次确认。如果节点没有空闲的 UTXO，发票就无法创建或结算：用 BTC 注资后再运行一次 `kaleido wallet create-utxos`。
+
+
+
+ 付款方会从发票中列出的 RGB 代理获取转账数据。请用 `kaleido asset invoice` 创建发票（它会加入默认代理），或像上表那样在提示词中指明代理。
+
+
+
+ 确认 `kaleido-mcp` 输出了 `network: signet`。环境中显式设置的 `KALEIDOSWAP_API_URL` 或 `KALEIDO_API_URL` 会覆盖预设。
+
+
+
+ 检查 `wdk_list_channels`：你需要一条与做市方之间、可用且承载所买卖资产的通道。没有它，报价可以成功，但无法结算。
+
+
+
+ 小模型不擅长开放式规划。请像上面的提示词那样把请求说具体，或者加载更大的 QVAC 模型。KaleidoMind 的 recipe 会以确定性方式处理多步流程，模型只需要填槽。
+
+
+
+更多解决办法见 [AI 工具故障排查](/cn/ai-tools/troubleshooting)。
+
+## 黑客松项目灵感 {#ideas-for-hackathon-projects}
+
+
+
+ QVAC 也能在本地运行语音转文字和文字转语音。`@kaleidorg/mind/qvac` 中的 `createQvacVoice` 和 `runVoiceAssistant` 提供免手操作的循环，每次花费前都会语音确认。
+
+
+ 让代理用 `search_paid_apis` 找到付费 API，再通过 `mpp_*` 和 `l402_*` 工具按次经闪电网络付款。无需注册，也无需 API 密钥。
+
+
+ 用 `l402_get_price` 和 `kaleidoswap_get_spreads` 盯盘，并通过原子交换在 BTC 与 USDT 之间再平衡。在决策看起来可靠之前，请一直保留确认关卡。
+
+
+ 把门票或积分代币发行为新的 RGB 资产。目前可以通过 CLI（`kaleido asset issue nia`）以及 KaleidoMind 的 mock 钱包实现；`kaleido-mcp` 尚未提供发行工具。
+
+
diff --git a/mintlify-docs/cn/ai-tools/faq.mdx b/mintlify-docs/cn/ai-tools/faq.mdx
index 28c9f43..05bf808 100644
--- a/mintlify-docs/cn/ai-tools/faq.mdx
+++ b/mintlify-docs/cn/ai-tools/faq.mdx
@@ -46,11 +46,20 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种
- 这些工具能够访问主网，但请把它当作最后一步而不是第一步。先用一次性种子在 regtest 或 signet 上起步，在 KaleidoAgent 上保持 `dry_run` 开启，直到 dry-run 的决策看起来都正确，然后再切换网络。
+ 这些工具能够访问主网，但请把它当作最后一步而不是第一步。先用一次性种子在 signet 上起步，在 KaleidoAgent 上保持 `dry_run` 开启，直到 dry-run 的决策看起来都正确，然后再切换网络。
另外要注意，不同接入方式的成熟度并不相同：KaleidoAgent 和 MCP 服务器会直接动用真实资金，而 LLM 调错一个工具是真实存在的失败模式。
+
+ 本文档中的一切都运行在 signet 上。用 `KALEIDO_NETWORK=signet` 把 `kaleido-mcp` 指向它，这会选用位于 `https://api.signet.kaleidoswap.com` 的 signet KaleidoSwap API。
+
+ - **RGB 资产：** [KaleidoSwap RGB 水龙头](https://faucet.mutinynet.kaleidoswap.com)会把测试资产发送到你节点生成的 RGB 发票。使用 GitHub 登录。
+ - **节点：** [KaleidoCLI](/cn/cli/installation) 通过 `kaleido setup` 在本地运行一个 signet RGB Lightning Node。
+
+ [构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent)会完整演示这两步。
+
+
三条相互独立的成本线：
@@ -60,7 +69,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种
- 有几种相互独立的控制手段，而且值得同时用上多个：
+ 在 KaleidoAgent 上，只有一项控制在代码层面强制生效：`dry_run`。下表其余项是作为运行规则传递给模型的，请当作指引而非支出上限：
| 控制项 | 效果 |
|---------|--------|
@@ -84,7 +93,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种
- 是的。所有仓库都公开在 [github.com/kaleidoswap](https://github.com/kaleidoswap) 下：MCP 服务器、KaleidoAgent、KaleidoMind，以及 skill 本身。直达链接见[更多资源](/cn/ai-tools/additional-resources)。
+ 是的，但有一点需要说明。网关、各个钱包 MCP 服务器、KaleidoAgent、KaleidoMind 和 skill 都公开在 [github.com/kaleidoswap](https://github.com/kaleidoswap) 下。`kaleido-mcp`、KaleidoAgent 和 KaleidoMind 采用 Apache 2.0。三个钱包服务器虽然公开，但尚未附带许可证文件，在许可证落地之前请按 source-available 对待。直达链接见[更多资源](/cn/ai-tools/additional-resources)。
@@ -99,7 +108,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种
其他情况请通过下面任一渠道反馈问题，并附上：
1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本）
-2. 你所在的网络（regtest、signet 或主网）
+2. 你所在的网络（signet 或主网）
3. 失败的工具名称和报错文本
4. 宿主与运行时版本（MCP 客户端、Node.js）
5. 你的配置，并移除其中的种子和所有密钥
diff --git a/mintlify-docs/cn/ai-tools/getting-started.mdx b/mintlify-docs/cn/ai-tools/getting-started.mdx
index 97bfbba..f7e019b 100644
--- a/mintlify-docs/cn/ai-tools/getting-started.mdx
+++ b/mintlify-docs/cn/ai-tools/getting-started.mdx
@@ -10,12 +10,12 @@ description: "选择把 AI 代理接入比特币的方式：MCP 服务器、Kale
| 要求 | 说明 |
|-------------|---------|
-| **一个测试网络** | regtest 或 signet。首次运行绝不要用主网 |
+| **一个测试网络** | signet。KaleidoSwap API 在 `https://api.signet.kaleidoswap.com` 提供 signet 实例，[RGB 水龙头](https://faucet.mutinynet.kaleidoswap.com)可发放测试资产。首次运行绝不要用主网 |
| **一份钱包种子** | 用于测试网络的一次性 BIP-39 助记词，设置到 `WDK_SEED` |
-| **一个节点** | 仅 `wdk_*` 工具和原子交换需要。Spark 工具只需要种子，行情数据什么都不需要 |
+| **一个节点** | 仅 `wdk_*` 工具和原子交换需要。[KaleidoCLI](/cn/cli/installation) 一条命令即可启动一个 signet RGB Lightning Node。Spark 工具只需要种子，行情数据什么都不需要 |
| **一个 MCP 宿主或 LLM 密钥** | Claude Desktop 或其他 MCP 客户端，或者用于 KaleidoAgent 的 Anthropic / OpenAI 密钥 |
-如果你还没有安装任何组件，请先看[安装](/cn/ai-tools/installation)。
+如果你还没有安装任何组件，请先看[安装](/cn/ai-tools/installation)。想从一台空机器一路走到让本地模型在 signet 上操作 RGB 资产，请按照[构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent)操作。
## 选择接入方式 {#pick-a-surface}
@@ -37,7 +37,7 @@ description: "选择把 AI 代理接入比特币的方式：MCP 服务器、Kale
| 接入方式 | 把关机制 |
|---------|------|
| **[KaleidoMind](/cn/ai-tools/kaleido-mind)** | 结构性把关。每个会动用资金的工具都标记了 `requiresConfirmation`，引擎会暂停并等待宿主的确认面板。模型无法绕过 |
-| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 策略性把关。`dry_run` 加上 `agent.config.json` 中的风险上限，在提交前校验 |
+| **[KaleidoAgent](/cn/ai-tools/kaleido-agent)** | 混合把关。`dry_run` 在代码层面强制生效；`agent.config.json` 中其余风险上限是给模型的规则，不是独立的上限 |
| **[MCP 服务器](/cn/ai-tools/mcp-servers)** | 取决于你的宿主客户端。多数 MCP 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的 |
diff --git a/mintlify-docs/cn/ai-tools/installation.mdx b/mintlify-docs/cn/ai-tools/installation.mdx
index f7f2a02..3e3eb1d 100644
--- a/mintlify-docs/cn/ai-tools/installation.mdx
+++ b/mintlify-docs/cn/ai-tools/installation.mdx
@@ -10,7 +10,7 @@ description: "安装 KaleidoSwap AI 工具：MCP 服务器网关、KaleidoAgent
|---------|-------------|---------------|
| **[MCP 服务器](#mcp-servers)** | 网关用 `npx`，专用服务器需本地构建 | Node.js 20+，一个 MCP 宿主客户端 |
| **[KaleidoAgent](#kaleidoagent)** | 克隆仓库并从源码构建 | Node.js 20+、KaleidoCLI、Nanobot、一个 LLM API 密钥 |
-| **[KaleidoMind](#kaleidomind)** | 随桌面应用一起提供，或构建仓库用于开发 | 桌面应用，或 pnpm 与 QVAC SDK |
+| **[KaleidoMind](#kaleidomind)** | 随桌面应用一起提供，在你自己的宿主中 `npm install @kaleidorg/mind`，或构建仓库用于开发 | 桌面应用，或 Node.js 与 QVAC SDK（`@qvac/sdk`） |
这里的每一种接入方式都会使用真实的 BIP-39 助记词签名，或直接驱动一个运行中的节点。请先在测试网络上起步，在配置验证通过之前保持 `dry_run` 开启，并且永远不要把主网种子写入会被提交或分享的文件。
@@ -18,12 +18,20 @@ description: "安装 KaleidoSwap AI 工具：MCP 服务器网关、KaleidoAgent
## MCP 服务器 {#mcp-servers}
-`kaleido-mcp` 是跑通工具调用的最快路径，已发布到 npm，无需本地构建：
+`kaleido-mcp` 是跑通工具调用的最快路径，已发布到 npm。`KALEIDO_NETWORK=signet` 用一个变量把它指向 signet KaleidoSwap API 和 Spark 测试网络：
```bash
-npx -y kaleido-mcp
+KALEIDO_NETWORK=signet npx -y kaleido-mcp
```
+
+ 本文档描述的是 `kaleido-mcp` 0.3.0 及以上版本：它新增了 `KALEIDO_NETWORK` 预设和
+ `kaleido_node_*` 工具，并且只通过原子交换结算。如果 `npx` 解析到了较旧的缓存版本，
+ 请运行一次 `npx -y kaleido-mcp@latest`。
+
+
+使用 RGB 工具还需要一个 RGB Lightning Node。[KaleidoCLI](/cn/cli/installation) 可以在 Docker 中运行一个 signet 节点，完整流程见[构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent)。
+
另有三个按钱包划分的服务器 `wdk-wallet-mcp`、`wdk-wallet-spark-mcp` 和 `wdk-wallet-liquid-mcp`，它们保持独立而未并入网关，需要从源码构建：
```bash
@@ -64,6 +72,14 @@ KaleidoMind 是嵌入宿主应用中的引擎，而不是一个独立安装的
KaleidoMind 依赖本地 AI 运行时，目前在 Windows 上可能尚不可用。所有交易与节点功能都不依赖它，因此如果你的平台上 Mind 暂不可用，可以用 **Only Node** 模式运行应用。
+### 在你自己的 Node.js 应用中 {#in-your-own-nodejs-app}
+
+```bash
+npm install @kaleidorg/mind @qvac/sdk
+```
+
+`@qvac/sdk` 是可选的 peer 依赖，因此引擎在没有它的情况下也能配合 mock provider 运行。快速上手见 [`@kaleidorg/mind` README](https://www.npmjs.com/package/@kaleidorg/mind)，[kaleido-mind 仓库](https://github.com/kaleidoswap/kaleido-mind)中还有可运行的示例（`examples/node-minimal`、`examples/rgb-agent`）。
+
### 从源码构建，用于开发
```bash
diff --git a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx
index 6f555ba..e0a5c72 100644
--- a/mintlify-docs/cn/ai-tools/kaleido-agent.mdx
+++ b/mintlify-docs/cn/ai-tools/kaleido-agent.mdx
@@ -76,7 +76,11 @@ KaleidoAgent 把 `kaleido-mcp`（[统一的 MCP 服务器](/cn/ai-tools/mcp-serv
## 风险控制 {#risk-controls}
-风险上限位于 `agent.config.json` 的 `portfolio` 之下。每笔交换提交之前都会校验它们。
+风险上限位于 `agent.config.json` 的 `portfolio` 之下。它们的生效方式并不相同，在设定数值时这一区别很重要。
+
+`dry_run` 在代码层面强制生效：交换执行器会在调用任何工具之前拒绝，提示词或 skill 中的任何措辞都无法绕过它。
+
+其余参数是作为运行规则传递给模型的，写在运行提示词和 skill 文件里。它们能约束一个配合的模型，但并不是独立的上限，因此忽略它们的模型目前不会被其他机制阻止。
| 参数 | 默认值 | 作用 |
|-----------|---------|--------|
diff --git a/mintlify-docs/cn/ai-tools/kaleido-mind.mdx b/mintlify-docs/cn/ai-tools/kaleido-mind.mdx
index 78e904e..c175927 100644
--- a/mintlify-docs/cn/ai-tools/kaleido-mind.mdx
+++ b/mintlify-docs/cn/ai-tools/kaleido-mind.mdx
@@ -43,15 +43,17 @@ description: "驱动 KaleidoSwap 代理式钱包的本地端推理引擎：分
| 分层 | 状态 | 工具 |
|-------|--------|-------|
| Spark | 已上线 | `spark_get_balance` · `spark_get_address` · `spark_get_onchain_address` · `spark_create_invoice` · `spark_pay_invoice` 🔒 · `spark_send` 🔒 |
-| RLN / RGB | 已上线 | `rln_get_balances` · `rln_get_node_info` · `rln_list_channels` · `rln_create_ln_invoice` · `rln_create_rgb_invoice` · `rln_pay_invoice` 🔒 · `rln_send_asset` 🔒 |
+| RLN / RGB | 已上线 | `rln_get_balances` · `rln_get_node_info` · `rln_list_assets` · `rln_list_transfers` · `rln_list_channels` · `rln_create_ln_invoice` · `rln_create_rgb_invoice` · `rln_create_utxos` · `rln_pay_invoice` 🔒 · `rln_send_asset` 🔒 · `rln_issue_asset` 🔒 |
| Arkade | 已上线 | `arkade_get_balance` · `arkade_get_address` · `arkade_send` 🔒 |
| Liquid | 计划中，尚未实现 | `liquid_get_balance` · `liquid_create_invoice` · `liquid_send` 🔒（契约中已定义类型，但还没有适配器） |
+`rln_issue_asset` 属于 KaleidoMind 的契约，可以在 `@kaleidorg/mind/testing` 的 mock 钱包上运行，但 `kaleido-mcp` 目前尚未提供发行工具，因此接入网关的宿主暂时无法通过它发行 RGB 资产。
+
此外还有跨层的路由工具：`get_balances(layer?)`、`resolve_contact(name)`、`get_price(asset?, fiat?)`、`fiat_to_sats(amount, currency)`、`get_swap_quote`/`execute_swap`，会自动选择结算通道的统一 `send_payment(asset, amount, to, layer?)`，以及与之对应的收款工具 `create_invoice(asset?, amount?, layer?)`。
### KaleidoSwap 交易与 LSPS1
-DEX 交易（`kaleidoswap_get_quote`、`kaleidoswap_place_order`、`kaleidoswap_atomic_init`/`execute`/`status`）与不绑定特定 LSP 的通道订单（`lsp_get_info`、`lsp_get_network_info`、`lsp_estimate_fees`、`lsp_create_order`、`lsp_get_order`）各有独立的契约。原子交换链路以单个需确认的 recipe（`kaleidoswapAtomicRecipe`）运行：先报价，用户确认一次后在做市方一侧初始化，读取节点的 pubkey，以接单方身份把 HTLC 加入白名单，然后执行。
+DEX 交易（先 `kaleidoswap_get_quote`，再 `kaleidoswap_atomic_init`/`execute`/`status`；`kaleido-mcp` 0.3.0 只通过原子交换结算）与不绑定特定 LSP 的通道订单（`lsp_get_info`、`lsp_get_network_info`、`lsp_estimate_fees`、`lsp_create_order`、`lsp_get_order`）各有独立的契约。原子交换链路以单个需确认的 recipe（`kaleidoswapAtomicRecipe`）运行：先报价，用户确认一次后在做市方一侧初始化，读取节点的 pubkey，以接单方身份把 HTLC 加入白名单，然后执行。
## Skills
@@ -59,7 +61,27 @@ Skills 是符合 Agent Skills 规范的操作手册（`SKILL.md` 加渐进式披
## QVAC：本地端推理
-LLM、嵌入、语音转文字和文字转语音推理全部通过 [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk) 完成，默认在本地端运行，较重的任务也可以委托给用户明确配对并自行掌控的桌面端。它以 `@kaleidorg/mind/qvac` 子路径发布，使该 SDK 保持为 peer 依赖，而不是 core 的硬性依赖。记忆与 RAG（长期回忆、钱包历史检索、商户发现）同样走 QVAC 的嵌入能力，并通过近重复内容合并来避免记忆膨胀。
+LLM、嵌入、语音转文字和文字转语音推理全部通过 Tether 的本地 AI 运行时 [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk) 完成，默认在本地端运行，较重的任务也可以委托给用户明确配对并自行掌控的桌面端。它以 `@kaleidorg/mind/qvac` 子路径发布，使该 SDK 保持为 peer 依赖，而不是 core 的硬性依赖。记忆与 RAG（长期回忆、钱包历史检索、商户发现）同样走 QVAC 的嵌入能力，并通过近重复内容合并来避免记忆膨胀。
+
+| 包 | 版本 |
+|---------|---------|
+| `@qvac/sdk` | 核心引擎支持 0.13 及以上版本。建议安装最新版本，宿主与评测都以它为测试基准 |
+| `@kaleidorg/mind` | 把 `@qvac/sdk` 作为可选 peer 依赖，因此引擎在完全没有模型的情况下也能配合 mock provider 运行 |
+
+`createQvacProvider` 把 SDK 的 `completion` 转换为引擎所需的 `LLMProvider`。SDK 函数通过注入而非导入的方式传入，因此由宿主掌控模型生命周期（`loadModel`、`unloadModel`），引擎也不会把 QVAC 打进不需要它的包里。
+
+## 动手构建 {#build-with-it}
+
+[`@kaleidorg/mind` README](https://www.npmjs.com/package/@kaleidorg/mind) 提供快速上手，[kaleido-mind 仓库](https://github.com/kaleidoswap/kaleido-mind)中有两个可运行的示例：
+
+| 示例 | 演示内容 |
+|---------|---------------|
+| `examples/node-minimal` | 最小的 Node.js 宿主：一个 QVAC 模型、漏斗和一个确认回调 |
+| `examples/rgb-agent` | 在 signet 上接入 `kaleido-mcp` 的本地代理，在真实的 RGB Lightning Node 上转移 RGB 资产 |
+
+`@kaleidorg/mind/testing` 提供绑定真实工具契约的有状态 `MockWallet` 和脚本化 provider，因此完整的漏斗、recipe 和确认关卡可以在 CI 或笔记本上运行，无需节点、资金或模型。
+
+想在 signet 上按步骤操作，请参阅[构建本地 RGB 代理](/cn/ai-tools/build-local-rgb-agent)。
## 运行环境
@@ -76,4 +98,4 @@ LLM、嵌入、语音转文字和文字转语音推理全部通过 [QVAC SDK](ht
## 发布与子路径
-从 `packages/core` 以 `@kaleidorg/mind` 发布，包含这些子路径：`./mcp`（MCP 工具源辅助函数）、`./skills`（skill 加载器）、`./logger` 和 `./qvac`（本地端推理适配器）。npm 上还有 `apps/provider`，即桌面应用嵌入的 Tauri 桌面 sidecar，包名为 `@kaleidorg/mind-provider`。`apps/cli` 中的 CLI 供仓库内的终端与评测使用，不对外发布。
+从 `packages/core` 以 `@kaleidorg/mind` 发布，包含这些子路径：`./mcp`（MCP 工具源辅助函数）、`./skills`（skill 加载器）、`./logger`、`./qvac`（本地端推理适配器）和 `./testing`（mock 钱包与脚本化 provider）。npm 上还有 `apps/provider`，即桌面应用嵌入的 Tauri 桌面 sidecar，包名为 `@kaleidorg/mind-provider`。`apps/cli` 中的 CLI 供仓库内的终端与评测使用，不对外发布。
diff --git a/mintlify-docs/cn/ai-tools/mcp-servers.mdx b/mintlify-docs/cn/ai-tools/mcp-servers.mdx
index b33111d..427a801 100644
--- a/mintlify-docs/cn/ai-tools/mcp-servers.mdx
+++ b/mintlify-docs/cn/ai-tools/mcp-servers.mdx
@@ -52,12 +52,18 @@ KaleidoSwap 通过 **`kaleido-mcp`** 这一个统一服务器，把钱包、DEX
## 安装与配置 {#installation-and-configuration}
-`kaleido-mcp` 已发布到 npm，因此最快的路径不需要本地构建：
+`kaleido-mcp` 已发布到 npm，这是跑通第一次工具调用的最快方式。请从 signet 开始：
```bash
-npx -y kaleido-mcp
+KALEIDO_NETWORK=signet npx -y kaleido-mcp
```
+
+ 本页描述的是 `kaleido-mcp` 0.3.0 及以上版本。0.3.0 新增了 `KALEIDO_NETWORK` 预设和
+ `kaleido_node_*` 生命周期工具，并移除了基于订单的交换工具，改为只使用原子交换。如果
+ `npx` 解析到了较旧的缓存版本，请运行一次 `npx -y kaleido-mcp@latest`，或从源码构建。
+
+
实际使用中由 MCP 宿主替你执行这条命令，把宿主配置指向该命令即可（见下面的[客户端配置](#client-configuration)）。若用于开发，或要运行某个特定提交，请改为从源码构建：
```bash
@@ -70,24 +76,36 @@ npm run build
无论哪种方式，服务器读取的环境变量都相同，并且默认使用 stdio 通信：
```bash
-# stdio（Claude Desktop、KaleidoAgent 等）
-WDK_SEED="word1 word2 ..." node dist/index.js
+# stdio（Claude Desktop、Claude Code、KaleidoAgent 等）
+KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js
# HTTP 传输
-PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
+PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js
```
+### 网络预设 {#network-preset}
+
+`KALEIDO_NETWORK` 用一个变量选定一组默认值，可取 `mainnet`（默认）或 `signet`：
+
+| 预设 | KaleidoSwap API | Spark 网络 |
+|--------|-----------------|---------------|
+| `mainnet` | `https://api.kaleidoswap.com` | `MAINNET` |
+| `signet` | `https://api.signet.kaleidoswap.com` | Spark 测试网络（Spark SDK 中名为 `REGTEST`） |
+
+预设只负责填充默认值。你显式设置的任何变量（例如 `KALEIDOSWAP_API_URL` 或 `SPARK_NETWORK`）都会覆盖它。未知取值会让服务器在启动时直接退出，而不是悄悄回退到主网。`RLN_NODE_URL` 不属于预设：请把它指向你自己的节点，在 signet 上通常就是 [KaleidoCLI](/cn/cli/installation) 运行在 `http://localhost:3001` 的那个节点。
+
| 环境变量 | 是否必需 | 说明 |
|---------|----------|--------------|
+| `KALEIDO_NETWORK` | 否 | `mainnet`（默认）或 `signet`。设置[网络预设](#network-preset)中的默认值 |
| `WDK_SEED` | 使用 Spark 工具时必需 | Spark 钱包的 BIP-39 助记词。没有它服务器仍能启动，只是 Spark 工具会被禁用 |
-| `SPARK_NETWORK` | 否 | `MAINNET` 或 `REGTEST` |
+| `SPARK_NETWORK` | 否 | 覆盖预设中的 Spark 网络：`MAINNET`，或代表 Spark 测试网络的 `REGTEST` |
| `SPARK_SCAN_API_KEY` | 否 | SparkScan API 密钥 |
| `SPARK_USDT_TOKEN` | 否 | 默认的 Spark 代币标识符 |
| `RLN_NODE_URL` | 否 | RLN 守护进程 URL，默认 `http://localhost:3001` |
-| `KALEIDOSWAP_API_URL` | 否 | KaleidoSwap API URL，默认 `https://api.kaleidoswap.com` |
+| `KALEIDOSWAP_API_URL` | 否 | 覆盖预设中的 KaleidoSwap API URL，也接受 `KALEIDO_API_URL` |
| `KALEIDO_BIN` | 否 | `kaleido` 可执行文件的路径，供节点生命周期工具使用 |
| `KALEIDO_NODE_URL` | 否 | 以 `--node-url` 传给节点生命周期工具的节点 URL |
-| `KALEIDO_API_URL` | 否 | 以 `--api-url` 传给节点生命周期工具的 API URL |
+| `KALEIDO_API_URL` | 否 | 以 `--api-url` 传给节点生命周期工具的 API URL，同时作为 `KALEIDOSWAP_API_URL` 的备选 |
| `KALEIDO_ENV_NAME` | 否 | 节点生命周期工具的默认环境名 |
| `PORT` | 否 | 启用 Streamable HTTP 传输，替代 stdio |
| `MCP_AUTH_TOKEN` | 否 | HTTP 模式下的 Bearer token |
@@ -164,11 +182,6 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
| `kaleidoswap_get_pairs` | 可交易的交易对及其可用的分层路由 |
| `kaleidoswap_get_quote` | 一笔交换的价格报价，返回输出数量、价格、费用和 `rfq_id` |
| `kaleidoswap_get_spreads` | 某个交易对在每条路由上的报价，用于比价或发现套利机会 |
- | `kaleidoswap_place_order` | 下一个 REST 交换订单，返回一个 `deposit_address` |
- | `kaleidoswap_get_order_status` | 轮询订单状态，直到 `FILLED`、`FAILED`、`EXPIRED` 或 `CANCELLED` |
- | `kaleidoswap_get_open_orders` | 本会话中下过的订单及其最后已知状态 |
- | `kaleidoswap_cancel_order` | 在本地会话跟踪器中把订单标记为已取消 |
- | `kaleidoswap_get_position` | 本会话交易统计：成交率、按资产统计的交易量 |
| `kaleidoswap_atomic_init` | 原子交换的第 1 步，返回 `swapstring` 和 `payment_hash` |
| `kaleidoswap_atomic_execute` 🔒 | 第 3 步，在 `wdk_atomic_taker` 把 HTLC 加入白名单后确认执行 |
| `kaleidoswap_atomic_status` | 按 `payment_hash` 轮询原子交换状态 |
@@ -179,7 +192,7 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
| `kaleidoswap_lsp_quote_asset_channel` | 为预装了 RGB 资产（USDT、XAUT）的新通道报价 |
| `kaleidoswap_lsp_create_asset_channel` 🔒 | 向 LSP 订购一条预装资产的新通道 |
- 通过 `KALEIDOSWAP_API_URL` 配置。底层接口端点请见[交换协议](/cn/api-reference/swap-protocol)和 [RGB LSPS1 API](/cn/api-reference/rgb-lsps1-apis)参考。
+ 通过 `KALEIDO_NETWORK` 配置，自定义端点则用 `KALEIDOSWAP_API_URL`。交换只走原子交换：基于订单的工具（`kaleidoswap_place_order`、`kaleidoswap_get_order_status` 等）已在 0.3.0 中移除。底层接口端点请见[交换协议](/cn/api-reference/swap-protocol)和 [RGB LSPS1 API](/cn/api-reference/rgb-lsps1-apis)参考。
@@ -227,30 +240,37 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
## 客户端配置 {#client-configuration}
-把服务器添加到 Claude Desktop 这类 MCP 宿主中。已发布的网关用 `npx` 即可；独立的钱包服务器则从本地构建运行。
+把服务器添加到 Claude Desktop 或 Claude Code 这类 MCP 宿主中。已发布的网关用 `npx` 即可；独立的钱包服务器则从本地构建运行。
这些配置文件以明文保存着真实的 BIP-39 助记词。请先在测试网络上起步，绝不要提交或分享包含主网种子的配置。
-```json kaleido-mcp
+```json Claude Desktop
{
"mcpServers": {
"kaleido": {
"command": "npx",
"args": ["-y", "kaleido-mcp"],
"env": {
+ "KALEIDO_NETWORK": "signet",
"WDK_SEED": "your twelve word seed phrase",
- "SPARK_NETWORK": "REGTEST",
- "RLN_NODE_URL": "http://localhost:3001",
- "KALEIDOSWAP_API_URL": "https://api.kaleidoswap.com"
+ "RLN_NODE_URL": "http://localhost:3001"
}
}
}
}
```
+```bash Claude Code
+claude mcp add kaleido \
+ --env KALEIDO_NETWORK=signet \
+ --env RLN_NODE_URL=http://localhost:3001 \
+ --env WDK_SEED="your twelve word seed phrase" \
+ -- npx -y kaleido-mcp
+```
+
```json wdk-wallet-mcp
{
"mcpServers": {
@@ -281,13 +301,15 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
```
+在 Claude Desktop 中，配置文件是 `claude_desktop_config.json`（**Settings > Developer > Edit Config**）。`WDK_SEED` 是可选的：不设置时 Spark 工具会被禁用，而 RGB 节点、DEX、支付和行情工具照常可用。独立的 Spark 服务器没有网络预设，因此直接设置 `SPARK_NETWORK`；`REGTEST` 是 Spark SDK 对其托管测试网络的命名。
+
## 首次运行 {#first-run}
顺序是先只读，再报价，最后执行 —— 因为除第一步之外，每一步都会动用真实价值。
- 把 `kaleido-mcp` 配置块加入你的 MCP 宿主配置，将 `KALEIDOSWAP_API_URL` 指向测试环境，并把 `SPARK_NETWORK` 设为 `REGTEST`。完整 JSON 见上面的[客户端配置](#client-configuration)。
+ 把 `kaleido-mcp` 配置块加入你的 MCP 宿主配置，并把 `KALEIDO_NETWORK` 设为 `signet`。完整 JSON 见上面的[客户端配置](#client-configuration)。
@@ -315,10 +337,10 @@ PORT=3010 WDK_SEED="word1 word2 ..." node dist/index.js
- 只询价，不下单：
+ 只询价，不执行：
```
- Quote 100000 sats of BTC into USDT. Do not place an order.
+ Quote 100000 sats of BTC into USDT. Do not execute anything.
```
`kaleidoswap_get_quote` 会返回一个 `rfq_id`、原始数量、费用和过期时间。请仔细核对原始数量：它们以资产的最小单位计价，不是显示单位。
diff --git a/mintlify-docs/cn/ai-tools/skills.mdx b/mintlify-docs/cn/ai-tools/skills.mdx
index e4d2f77..5a09652 100644
--- a/mintlify-docs/cn/ai-tools/skills.mdx
+++ b/mintlify-docs/cn/ai-tools/skills.mdx
@@ -16,7 +16,7 @@ description: "SKILL.md 操作手册限定代理能调用哪些工具并承载执
| `dca` | 按计划、感知价格的买入，受用户设定的上限约束 |
| `wallet-assistant` | 以对话方式查询余额、生成发票、支付和交换 |
| `cross-l2` | 在 Spark、闪电网络和链上比特币之间转移资产 |
-| `kaleidoswap` | KaleidoSwap DEX 参考：报价、原子交换、REST 订单、未平仓头寸 |
+| `kaleidoswap` | KaleidoSwap DEX 参考：报价与原子交换 |
| `mpp` | 通过闪电网络访问受 HTTP 402 门控的 API |
| `node-manager` | RGB Lightning Node 生命周期、钱包解锁、通道与余额检查 |
| `portfolio-loop` | 定时的投资组合再平衡器：对照目标测量偏移，执行最小规模的原子交换，并把 DCA 一并纳入 |
@@ -29,3 +29,14 @@ description: "SKILL.md 操作手册限定代理能调用哪些工具并承载执
skill 可以在运行时通过代理的 `/skills` [状态 API 接口端点](/cn/ai-tools/kaleido-agent#status-api)列出、启用和禁用。
+## 在 Claude Code 中使用 skill
+
+[KaleidoMind](/cn/ai-tools/kaleido-mind) 仓库将其内置 skill 作为 Claude Code 插件发布，并附带已配置为 signet 的 `kaleido-mcp` 服务器：
+
+```bash
+/plugin marketplace add kaleidoswap/kaleido-mind
+/plugin install kaleido-mind@kaleidoswap
+```
+
+该插件以 `KALEIDO_NETWORK=signet` 运行 `npx -y kaleido-mcp`。将 `RLN_NODE_URL` 指向你的 RGB Lightning Node，并设置 `WDK_SEED` 以启用 Spark 钱包工具。部分 KaleidoMind skill（Spark 钱包、Bitrefill、Flashnet、商户查找）依赖仅由 KaleidoMind 运行时提供的工具。
+
diff --git a/mintlify-docs/cn/ai-tools/troubleshooting.mdx b/mintlify-docs/cn/ai-tools/troubleshooting.mdx
index 919e000..23b7885 100644
--- a/mintlify-docs/cn/ai-tools/troubleshooting.mdx
+++ b/mintlify-docs/cn/ai-tools/troubleshooting.mdx
@@ -98,7 +98,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、
**现象**：对一个你确定已入资的钱包，工具返回空余额。
**解决办法**：
- 1. **检查网络。** `SPARK_NETWORK` 和节点自身的网络必须与资金所在的网络一致。regtest 的种子在主网上什么都看不到。
+ 1. **检查网络。** `KALEIDO_NETWORK`（或 `SPARK_NETWORK`）和节点自身的网络必须与资金所在的网络一致。signet 钱包在主网上什么都看不到，反之亦然。
2. **确认种子。** 换一份助记词派生出的是另一个钱包，而不是一个空钱包。
3. **等待同步。** 刚解锁的节点可能还没追上链的最新高度。
4. **区分链上与闪电。** `wdk_get_balances` 会把普通与着色 UTXO 和闪电余额分开列出，而通道里的资产并不是链上余额。
@@ -155,7 +155,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、
**现象**：代理原本在执行，之后就不再提交交换了。
- **原因**：某个风险上限被触发。最常见的是 `stop_loss_btc_sats`（低于其 BTC 阈值时停止所有交易），或者 `min_btc_reserve_sats`。
+ **原因**：通常是 `dry_run` 仍然开启，因此决策只是模拟而未执行。否则就是模型自己选择不交易，例如它根据指令应用了 `stop_loss_btc_sats` 或 `min_btc_reserve_sats`，或者某次工具调用失败了。
**解决办法**：
1. 读取 `GET /status` 查看余额和最近的运行记录。
@@ -201,7 +201,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、
其他情况请通过下面任一渠道反馈问题，并附上：
1. 使用的接入方式与版本（MCP 服务器名称、KaleidoAgent 提交号，或桌面应用版本）
-2. 你所在的网络（regtest、signet 或主网）
+2. 你所在的网络（signet 或主网）
3. 失败的工具名称和报错文本
4. 宿主与运行时版本（MCP 客户端、Node.js）
5. 你的配置，并移除其中的种子和所有密钥
diff --git a/mintlify-docs/cn/desktop-app/support/changelog.mdx b/mintlify-docs/cn/desktop-app/support/changelog.mdx
index ddd0d4a..ed2bb0e 100644
--- a/mintlify-docs/cn/desktop-app/support/changelog.mdx
+++ b/mintlify-docs/cn/desktop-app/support/changelog.mdx
@@ -6,7 +6,7 @@ description: "KaleidoSwap 桌面应用版本历史：从最新版本回溯到 al
## v0.5.0（当前版本）
-**发布日期：** 21 June 2026
+**发布日期：** 2026 年 7 月 10 日
**支持平台：** macOS（Apple Silicon 和 Intel）、Windows (x64)、Linux（AppImage、deb、rpm）
diff --git a/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx b/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx
index 1170c3b..9ce6c67 100644
--- a/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx
+++ b/mintlify-docs/cn/whats-kaleidoswap/architecture.mdx
@@ -19,7 +19,7 @@ KaleidoSwap 是垂直整合的：同一套 SDK 驱动我们发布的每一个客
| **智能层** | 负责本地推理的 KaleidoMind，负责自主执行的 KaleidoAgent |
| **结算** | 比特币 —— 上面所有层最终锚定的地方 |
-桌面应用、SDK、CLI、钱包引擎以及 MCP/AI 工具链均为开源（MIT），可在 [GitHub](https://github.com/kaleidoswap) 上查阅；浏览器扩展和做市方的询价引擎目前尚未开源。
+桌面应用、SDK、CLI 和钱包引擎以 MIT 开源，AI 工具链（`kaleido-mcp`、KaleidoAgent、KaleidoMind）以 Apache 2.0 开源，均可在 [GitHub](https://github.com/kaleidoswap) 上查阅；浏览器扩展和做市方的询价引擎目前尚未开源。
## 集成层
diff --git a/mintlify-docs/desktop-app/support/changelog.mdx b/mintlify-docs/desktop-app/support/changelog.mdx
index 706df03..7d8cdce 100644
--- a/mintlify-docs/desktop-app/support/changelog.mdx
+++ b/mintlify-docs/desktop-app/support/changelog.mdx
@@ -6,7 +6,7 @@ description: "KaleidoSwap Desktop App version history: new features, changes, an
## v0.5.0 (Current)
-**Released:** 21 June 2026
+**Released:** 10 July 2026
**Platforms:** macOS (Apple Silicon and Intel), Windows (x64), Linux (AppImage, deb, rpm)
diff --git a/mintlify-docs/docs.json b/mintlify-docs/docs.json
index 5091d85..1df98d3 100644
--- a/mintlify-docs/docs.json
+++ b/mintlify-docs/docs.json
@@ -242,7 +242,8 @@
"pages": [
"ai-tools/introduction",
"ai-tools/installation",
- "ai-tools/getting-started"
+ "ai-tools/getting-started",
+ "ai-tools/build-local-rgb-agent"
]
},
{
@@ -588,7 +589,8 @@
"pages": [
"cn/ai-tools/introduction",
"cn/ai-tools/installation",
- "cn/ai-tools/getting-started"
+ "cn/ai-tools/getting-started",
+ "cn/ai-tools/build-local-rgb-agent"
]
},
{
diff --git a/mintlify-docs/whats-kaleidoswap/architecture.mdx b/mintlify-docs/whats-kaleidoswap/architecture.mdx
index d918088..59ed7ca 100644
--- a/mintlify-docs/whats-kaleidoswap/architecture.mdx
+++ b/mintlify-docs/whats-kaleidoswap/architecture.mdx
@@ -19,7 +19,7 @@ This page walks the stack from the top down. For the protocols themselves and wh
| **Intelligence layer** | KaleidoMind for local reasoning, KaleidoAgent for autonomous execution |
| **Settlement** | Bitcoin — where every layer above anchors |
-The desktop app, SDKs, CLI, wallet engine, and MCP/AI tooling are open source (MIT) and inspectable on [GitHub](https://github.com/kaleidoswap); the browser extension and the maker-side RFQ engine are not public today.
+The desktop app, SDKs, CLI and wallet engine are open source under MIT, and the AI tooling (`kaleido-mcp`, KaleidoAgent, KaleidoMind) under Apache 2.0, all inspectable on [GitHub](https://github.com/kaleidoswap); the browser extension and the maker-side RFQ engine are not public today.
## Integration layer