bitwalt · Sep 21, 2026
diff --git 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.
 
 <CardGroup cols={2}>
   <Card title="kaleido-agent" icon="robot" href="https://github.com/kaleidoswap/kaleido-agent">
@@ -16,7 +16,7 @@ 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.
   </Card>
   <Card title="kaleido-mcp" icon="server" href="https://github.com/kaleidoswap/kaleido-mcp">
-    The gateway that composes every domain behind one connection. Published to npm.
+    The gateway that composes every domain behind one connection. Published to npm, though the release currently trails `main`.
   </Card>
   <Card title="Rate" icon="mobile" href="https://github.com/kaleidoswap/Rate">
     The React Native mobile wallet that hosts KaleidoMind with voice control.

diff --git a/mintlify-docs/ai-tools/faq.mdx b/mintlify-docs/ai-tools/faq.mdx
@@ -60,16 +60,23 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody,
   </Accordion>
 
   <Accordion title="How do I stop an agent from spending?">
-    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.
   </Accordion>
 
@@ -84,7 +91,7 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody,
   </Accordion>
 
   <Accordion title="Is any of this open source?">
-    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.
   </Accordion>
 
   <Accordion title="Can I use these tools with the Desktop App or the Extension?">

diff --git a/mintlify-docs/ai-tools/getting-started.mdx b/mintlify-docs/ai-tools/getting-started.mdx
@@ -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 |
 
 <Warning>

diff --git a/mintlify-docs/ai-tools/installation.mdx b/mintlify-docs/ai-tools/installation.mdx
@@ -18,11 +18,18 @@ 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:
 
 ```bash
 npx -y kaleido-mcp
 ```
+<Warning>
+  The npm release currently trails `main`. The published build predates the node
+  lifecycle tools (`kaleido_node_*`) and still exposes the removed order tools,
+  so `npx` will not give you the full surface documented on this page. Until the
+  next release lands, build from source for `kaleido_node_*` and the RFQ swap flow.
+</Warning>
+
 
 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:
 

diff --git 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 |
 
+<Warning>
+  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.
+</Warning>
+
 ## Trading Modes
 
 | Mode | Settlement |
@@ -180,7 +193,7 @@ With the agent running, drive one loop by hand and read what it decided before l
   </Step>
 
   <Step title="Review the risk limits">
-    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.
   </Step>
 
   <Step title="Only then disable dry run">

diff --git a/mintlify-docs/ai-tools/mcp-servers.mdx b/mintlify-docs/ai-tools/mcp-servers.mdx
@@ -52,11 +52,18 @@ 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:
 
 ```bash
 npx -y kaleido-mcp
 ```
+<Warning>
+  The npm release currently trails `main`. The published build predates the node
+  lifecycle tools (`kaleido_node_*`) and still exposes the removed order tools,
+  so `npx` will not give you the full surface documented on this page. Until the
+  next release lands, build from source for `kaleido_node_*` and the RFQ swap flow.
+</Warning>
+
 
 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:
 
@@ -164,11 +171,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` |

diff --git a/mintlify-docs/ai-tools/troubleshooting.mdx b/mintlify-docs/ai-tools/troubleshooting.mdx
@@ -155,7 +155,7 @@ description: "Fix common KaleidoSwap AI tool problems, covering MCP connection f
   <Accordion title="Trading stopped on its own" icon="hand">
     **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.

diff --git 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。
 
 <CardGroup cols={2}>
   <Card title="kaleido-agent" icon="robot" href="https://github.com/kaleidoswap/kaleido-agent">

diff --git a/mintlify-docs/cn/ai-tools/faq.mdx b/mintlify-docs/cn/ai-tools/faq.mdx
@@ -60,7 +60,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种
   </Accordion>
 
   <Accordion title="怎样阻止代理花钱？">
-    有几种相互独立的控制手段，而且值得同时用上多个：
+    在 KaleidoAgent 上，只有一项控制在代码层面强制生效：`dry_run`。下表其余项是作为运行规则传递给模型的，请当作指引而非支出上限：
 
     | 控制项 | 效果 |
     |---------|--------|
@@ -84,7 +84,7 @@ description: "关于 KaleidoSwap AI 工具的常见问题：托管方式、种
   </Accordion>
 
   <Accordion title="这些都是开源的吗？">
-    是的。所有仓库都公开在 [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)。
   </Accordion>
 
   <Accordion title="这些工具能配合桌面应用或浏览器扩展使用吗？">

diff --git a/mintlify-docs/cn/ai-tools/getting-started.mdx b/mintlify-docs/cn/ai-tools/getting-started.mdx
@@ -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 客户端会为每次工具调用弹出确认，但那是客户端的行为，不是服务器的 |
 
 <Warning>

diff --git a/mintlify-docs/cn/ai-tools/installation.mdx b/mintlify-docs/cn/ai-tools/installation.mdx
@@ -23,6 +23,12 @@ description: "安装 KaleidoSwap AI 工具：MCP 服务器网关、KaleidoAgent
 ```bash
 npx -y kaleido-mcp
 ```
+<Warning>
+  npm 上的发布版本落后于 `main`。已发布的构建不包含节点生命周期工具（`kaleido_node_*`），
+  并且仍然暴露已移除的订单工具，因此 `npx` 无法提供本页所记录的完整工具集。
+  在下一个发布版本发布之前，请从源码构建以使用 `kaleido_node_*` 和 RFQ 交换流程。
+</Warning>
+
 
 另有三个按钱包划分的服务器 `wdk-wallet-mcp`、`wdk-wallet-spark-mcp` 和 `wdk-wallet-liquid-mcp`，它们保持独立而未并入网关，需要从源码构建：
 

diff --git 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/mcp-servers.mdx b/mintlify-docs/cn/ai-tools/mcp-servers.mdx
@@ -57,6 +57,12 @@ KaleidoSwap 通过 **`kaleido-mcp`** 这一个统一服务器，把钱包、DEX
 ```bash
 npx -y kaleido-mcp
 ```
+<Warning>
+  npm 上的发布版本落后于 `main`。已发布的构建不包含节点生命周期工具（`kaleido_node_*`），
+  并且仍然暴露已移除的订单工具，因此 `npx` 无法提供本页所记录的完整工具集。
+  在下一个发布版本发布之前，请从源码构建以使用 `kaleido_node_*` 和 RFQ 交换流程。
+</Warning>
+
 
 实际使用中由 MCP 宿主替你执行这条命令，把宿主配置指向该命令即可（见下面的[客户端配置](#client-configuration)）。若用于开发，或要运行某个特定提交，请改为从源码构建：
 
@@ -164,11 +170,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` 轮询原子交换状态 |

diff --git a/mintlify-docs/cn/ai-tools/troubleshooting.mdx b/mintlify-docs/cn/ai-tools/troubleshooting.mdx
@@ -155,7 +155,7 @@ description: "解决 KaleidoSwap AI 工具的常见问题：MCP 连接失败、
   <Accordion title="交易自己停了" icon="hand">
     **现象**：代理原本在执行，之后就不再提交交换了。
 
-    **原因**：某个风险上限被触发。最常见的是 `stop_loss_btc_sats`（低于其 BTC 阈值时停止所有交易），或者 `min_btc_reserve_sats`。
+    **原因**：通常是 `dry_run` 仍然开启，因此决策只是模拟而未执行。否则就是模型自己选择不交易，例如它根据指令应用了 `stop_loss_btc_sats` 或 `min_btc_reserve_sats`，或者某次工具调用失败了。
 
     **解决办法**：
     1. 读取 `GET /status` 查看余额和最近的运行记录。

diff --git 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
@@ -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
@@ -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/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