bitwalt · Sep 1, 2026 · Aug 17, 2026 · Sep 1, 2026
diff --git a/mintlify-docs/README.md b/mintlify-docs/README.md
@@ -83,7 +83,6 @@ The documentation will be available at `http://localhost:3000`
 - `api-reference.mdx` - Complete API documentation
 - `types.mdx` - Pydantic models and enums
 - `examples.mdx` - Real-world code examples
-- `error-handling.mdx` - Exception handling guide
 - `websocket.mdx` - Real-time data streaming
 - `utilities.mdx` - Helper functions
 
@@ -94,16 +93,16 @@ The documentation will be available at `http://localhost:3000`
 - `api-reference.mdx` - API method documentation
 - `types.mdx` - Type definitions
 - `utilities.mdx` - Utility classes
-- `error-handling.mdx` - Error management
 - `examples.mdx` - Code examples
 - `websocket.mdx` - WebSocket integration
 - `best-practices.mdx` - Best practices guide
 - `troubleshooting.mdx` - Common issues
 
-### API Reference (6 pages)
+### API Reference (9 pages)
 ✅ Migrated + expanded with OpenAPI
-- `introduction.mdx`, `getting-started.mdx`, `error-handling.mdx`
+- `introduction.mdx`, `getting-started.mdx`, `swap-protocol.mdx`
 - `rgb-lsps1-apis.mdx`, `market-apis.mdx`, `swap-apis.mdx`
+- `faq.mdx`, `troubleshooting.mdx`, `additional-resources.mdx`
 - Automatic endpoint reference generated from `openapi.json`
 
 ## 🎨 Customization

diff --git a/mintlify-docs/ai-tools/additional-resources.mdx b/mintlify-docs/ai-tools/additional-resources.mdx
@@ -23,16 +23,6 @@ Every AI surface is open source under the [KaleidoSwap organisation](https://git
   </Card>
 </CardGroup>
 
-### Focused MCP servers
-
-| Repository | Tool prefix | Domain |
-|-----------|-------------|--------|
-| [wdk-wallet-mcp](https://github.com/kaleidoswap/wdk-wallet-mcp) | `wdk_*` | RGB Lightning Node wallet, channels, atomic swap taker |
-| [wdk-wallet-spark-mcp](https://github.com/kaleidoswap/wdk-wallet-spark-mcp) | `spark_*` | Spark wallet, Lightning, token transfers, BTC bridge |
-| [wdk-wallet-liquid-mcp](https://github.com/kaleidoswap/wdk-wallet-liquid-mcp) | `liquid_*` | Liquid wallet, L-BTC and asset balances, confidential sends |
-| [kaleidoswap-mcp](https://github.com/kaleidoswap/kaleidoswap-mcp) _(archived)_ | `kaleidoswap_*` | Superseded by the `kaleidoswap_*` tools in kaleido-mcp |
-| [l402-gateway-mcp](https://github.com/kaleidoswap/l402-gateway-mcp) _(archived)_ | `mpp_*`, `l402_*` | Superseded by the `mpp_*` / `l402_*` tools in kaleido-mcp |
-
 ## Protocol Specifications
 
 <CardGroup cols={2}>
@@ -50,42 +40,32 @@ Every AI surface is open source under the [KaleidoSwap organisation](https://git
   </Card>
 </CardGroup>
 
-## KaleidoSwap References
+## Get Help
 
-Reading these first makes the agent tooling considerably easier to reason about, since the tools are thin wrappers over them.
+Check [Troubleshooting](/ai-tools/troubleshooting) for errors and the [FAQ](/ai-tools/faq) for questions.
 
-<CardGroup cols={2}>
-  <Card title="Swap Protocol" icon="arrows-rotate" href="/api-reference/swap-protocol">
-    How the atomic HTLC flow settles, which is what the swap tools orchestrate.
-  </Card>
-  <Card title="RGB LSPS1 APIs" icon="code" href="/api-reference/rgb-lsps1-apis">
-    The channel-ordering endpoints behind `kaleidoswap_lsp_*`.
-  </Card>
-  <Card title="CLI" icon="terminal" href="/cli/introduction">
-    The binary KaleidoAgent shells out to, and the source of the node lifecycle tools.
-  </Card>
-  <Card title="SDK" icon="code" href="/sdk/introduction">
-    Call the swap infrastructure directly from TypeScript or Python, skipping the agent layer.
-  </Card>
-</CardGroup>
+For anything else, report a problem through your preferred channel from the options below, including:
 
-## Product and Community
+1. Which surface and version (MCP server name, KaleidoAgent commit, or Desktop App version)
+2. The network you are on (Regtest, 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
 
-<CardGroup cols={2}>
-  <Card title="AI Tools product page" icon="sparkles" href="https://kaleidoswap.com/products/ai-tools">
-    Product overview, plus readable and downloadable copies of each skill.
+<CardGroup cols={3}>
+  <Card title="Telegram Community" icon="telegram" href="https://t.me/kaleidoswap">
+    Ask the community.
   </Card>
-  <Card title="Telegram" icon="telegram" href="https://t.me/kaleidoswap">
-    Community support and discussion.
-  </Card>
-  <Card title="GitHub" icon="github" href="https://github.com/kaleidoswap">
-    Issues, pull requests, and the full source.
+  <Card title="GitHub Issues" icon="github" href="https://github.com/kaleidoswap">
+    Report a bug on the relevant repository.
   </Card>
   <Card title="Email Support" icon="envelope" href="mailto:support@kaleidoswap.com">
     Direct support for urgent issues.
   </Card>
 </CardGroup>
 
-<Note>
-  When reporting a problem with an AI surface, include the tool name that failed, the network you are on, and your config with the seed and any API keys removed. See [Troubleshooting](/ai-tools/troubleshooting) first.
-</Note>
+---
+
+<Card title="AI Tools product page" icon="sparkles" href="https://kaleidoswap.com/products/ai-tools">
+  Product overview, plus readable and downloadable copies of each skill.
+</Card>
diff --git a/mintlify-docs/ai-tools/faq.mdx b/mintlify-docs/ai-tools/faq.mdx
@@ -94,7 +94,9 @@ description: "Common questions about the KaleidoSwap AI tools, covering custody,
 
 ## Get Help
 
-Check the [Troubleshooting](/ai-tools/troubleshooting) for errors rather than questions. For anything else, report a problem through your preferred channel from the options below, including:
+Check the [Troubleshooting](/ai-tools/troubleshooting) for errors rather than questions, and [Additional Resources](/ai-tools/additional-resources) for upstream documentation and links.
+
+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)

diff --git a/mintlify-docs/ai-tools/getting-started.mdx b/mintlify-docs/ai-tools/getting-started.mdx
@@ -1,10 +1,10 @@
 ---
 title: "AI Tools: Getting Started"
 sidebarTitle: "Getting Started"
-description: "Connect an AI agent to Bitcoin, from a first read-only tool call on a test network through to a verified quote before you enable live execution"
+description: "Pick the right way to connect an AI agent to Bitcoin, MCP servers, KaleidoAgent, or KaleidoMind, with the prerequisites and the spend gate each one gives you"
 ---
 
-This is the path from an installed tool to a verified swap. It goes read-only first, then quoting, then execution, because every step after the first one moves real value.
+Four surfaces expose the same Bitcoin tools to a model, and they differ mostly in who runs the agent loop and what stops a spend. This page covers what to have in place first, which surface fits, and how each one gates the calls that move value.
 
 ## Before You Start
 
@@ -26,97 +26,19 @@ If you have not installed anything yet, start with [Installation](/ai-tools/inst
 | Talk to a wallet by chat or voice, on-device | [KaleidoMind](/ai-tools/kaleido-mind) |
 | Change agent behavior without touching code | [Skills](/ai-tools/skills) |
 
-## First Run: MCP Servers
+Whichever surface you pick, the first run follows the same order: a read-only call, then a wallet call, then a quote, and only then an execution. That order is diagnostic as much as it is cautious. A failure at the read-only step is a connection problem, a failure at the wallet step is a seed or network problem, and anything that reaches a quote has both already ruled out.
 
-<Steps>
-  <Step title="Add the gateway to your host">
-    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 on the [MCP Servers page](/ai-tools/mcp-servers#client-configuration).
-  </Step>
-
-  <Step title="Restart the host">
-    MCP hosts read their config at startup. A running client will not pick up a new server until you restart it.
-  </Step>
-
-  <Step title="Call a read-only tool">
-    Start with something that cannot move funds. Ask for market data, which needs no seed and no node:
-
-    ```
-    What is the current Bitcoin price and the Fear and Greed index?
-    ```
-
-    That exercises `l402_get_price` and `l402_get_sentiment`. If it answers, the connection works.
-  </Step>
-
-  <Step title="Check the wallet is wired">
-    Now confirm the wallet tools resolve:
-
-    ```
-    Show me my Spark balance and my Spark address.
-    ```
-
-    This calls `spark_get_balance` and `spark_get_address`. An error here is a seed or network problem, not a connection problem.
-  </Step>
-
-  <Step title="Quote before you trade">
-    Ask for a price without placing anything:
-
-    ```
-    Quote 100000 sats of BTC into USDT. Do not place an order.
-    ```
-
-    `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.
-  </Step>
-
-  <Step title="Execute only once the quote looks right">
-    An atomic swap needs the DEX tools and the wallet tools together, and the node must hold the asset in a channel. The [cross-server sequence](/ai-tools/mcp-servers#atomic-swap-across-servers) shows each call in order.
-  </Step>
-</Steps>
-
-## First Run: KaleidoAgent
-
-<Steps>
-  <Step title="Keep dry run enabled">
-    `portfolio.dry_run` defaults to `true` in `agent.config.json`. Leave it there. The agent will reason, decide, and report a trade without submitting it.
-  </Step>
-
-  <Step title="Start the agent">
-    ```bash
-    npm start
-    ```
-
-    That runs the agent and the status API on `http://localhost:4242`. For the dashboard, also run `npm run dev:webapp` and open `http://localhost:5173`.
-  </Step>
-
-  <Step title="Trigger a loop by hand">
-    Rather than waiting on the schedule, ask the status API to run one:
-
-    ```bash
-    curl -X POST http://localhost:4242/run \
-      -H 'Content-Type: application/json' \
-      -d '{"task_id":"rebalance"}'
-    ```
-
-    Then read `GET /status` to see the decision, the balances it saw, and the token cost.
-  </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.
-  </Step>
-
-  <Step title="Only then disable dry run">
-    Set `portfolio.dry_run` to `false` when the dry-run decisions have looked correct across several runs.
-  </Step>
-</Steps>
+Each surface carries its own walkthrough: [MCP Servers](/ai-tools/mcp-servers#first-run) and [KaleidoAgent](/ai-tools/kaleido-agent#first-run). KaleidoMind ships inside a host rather than running on its own, so its first run is the [Desktop App installation](/desktop-app/getting-started/installation). [Skills](/ai-tools/skills) change how an agent behaves on any of these surfaces, they are not a surface of their own.
 
 ## What Confirmation Looks Like
 
 The two agent surfaces gate spending differently, and it is worth knowing which one you are relying on.
 
 | Surface | Gate |
 |---------|------|
-| **KaleidoMind** | Structural. Every fund-moving tool is marked `requiresConfirmation`, so the engine pauses for the host's confirmation sheet. The model cannot bypass it |
-| **KaleidoAgent** | Policy. `dry_run` plus the risk limits in `agent.config.json`, checked before submission |
-| **MCP servers in a generic host** | Whatever your host provides. Most MCP clients prompt per tool call, but that is the client's behaviour, not the server's |
+| **[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 |
+| **[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>
   A generic MCP host is the least protected path. If your client auto-approves tool calls, an LLM can spend from the configured wallet without asking you. Use a test network seed until you know how your client handles approvals.

diff --git a/mintlify-docs/ai-tools/installation.mdx b/mintlify-docs/ai-tools/installation.mdx
@@ -8,9 +8,9 @@ Each AI surface installs independently. Pick the one that matches what you are b
 
 | Surface | Install path | Prerequisites |
 |---------|-------------|---------------|
-| **[MCP servers](/ai-tools/mcp-servers)** | `npx` for the gateway, local build for the focused servers | Node.js 20+, an MCP host |
-| **[KaleidoAgent](/ai-tools/kaleido-agent)** | Clone and build from source | Node.js 20+, KaleidoCLI, Nanobot, an LLM API key |
-| **[KaleidoMind](/ai-tools/kaleido-mind)** | Ships inside the Desktop App, or build the repo for development | Desktop App, or pnpm and the QVAC SDK |
+| **[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 |
 
 <Warning>
   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.
@@ -38,19 +38,19 @@ node dist/index.js
   `kaleidoswap-mcp` and `l402-gateway-mcp` are archived, their own READMEs point integrators at `kaleido-mcp` instead. Do not clone or build them for a new setup.
 </Note>
 
-Full environment variable reference, stdio vs. HTTP transport, the tool surface, and client config JSON for every server live on the [MCP Servers page](/ai-tools/mcp-servers#installation-&-configuration).
+For the full environment variable reference, stdio vs. HTTP transport, the tool surface by domain, and client config JSON for every server, check the [MCP Servers page](/ai-tools/mcp-servers).
 
 ## KaleidoAgent
 
-Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/getting-started) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key.
+Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/installation) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key.
 
 ```bash
 git clone https://github.com/kaleidoswap/kaleido-agent.git
 cd kaleido-agent
 npm run install:all
 ```
 
-From there, setting the API key, configuring the wallet in `agent.config.json`, and starting the dashboard are covered step by step on the [KaleidoAgent page](/ai-tools/kaleido-agent#run-it), along with the container deployment option.
+To set the API key, configure the wallet in `agent.config.json`, start the dashboard, or deploy in a container, check the [KaleidoAgent page](/ai-tools/kaleido-agent#run-it).
 
 ## KaleidoMind
 
@@ -86,3 +86,5 @@ To exercise the engine against a model without a phone, use the playground from
 ```bash
 pnpm play "pay bob 3 eur"
 ```
+
+For how the tiered funnel routes a request, the tool contract shared across transports, the skills the engine loads, and where it runs across desktop, phone, and paired devices, check the [KaleidoMind page](/ai-tools/kaleido-mind).
diff --git a/mintlify-docs/ai-tools/introduction.mdx b/mintlify-docs/ai-tools/introduction.mdx
@@ -25,9 +25,9 @@ The product overview lives at [kaleidoswap.com/products/ai-tools](https://kaleid
   </Card>
 </CardGroup>
 
-<Note>
+<Warning>
   Every tool surface here signs with a real BIP-39 mnemonic or drives a live node. See [Installation](/ai-tools/installation) for how to keep test and mainnet seeds apart.
-</Note>
+</Warning>
 
 ## Which one do I need?
 

diff --git a/mintlify-docs/ai-tools/kaleido-agent.mdx b/mintlify-docs/ai-tools/kaleido-agent.mdx
@@ -8,9 +8,9 @@ description: "Run an autonomous non-custodial agent that rebalances a Bitcoin L2
 
 It manages a Lightning and RGB wallet, executes atomic HTLC swaps on the KaleidoSwap DEX, runs portfolio rebalancing and DCA strategies, keeps Lightning channel liquidity healthy, and serves as an interactive wallet-assistant chat, all driven by an LLM (Claude or OpenAI) reasoning over [KaleidoCLI](/cli/introduction) and MCP tool calls.
 
-<Info>
+<Note>
   KaleidoAgent is a separate, always-on server. It does **not** currently embed [KaleidoMind](/ai-tools/kaleido-mind)'s `Engine` and runs its own agent loop instead. See [KaleidoMind's relationship note](/ai-tools/kaleido-mind#relationship-to-kaleidoagent) for the convergence path being considered.
-</Info>
+</Note>
 
 ## Capabilities
 
@@ -109,7 +109,7 @@ Same 5-step HTLC protocol as elsewhere in the KaleidoSwap stack, driven via `kal
 
 ## Run It
 
-Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/getting-started) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key.
+Prerequisites: Node.js 20 or newer, [KaleidoCLI](/cli/installation) in `$PATH`, the [Nanobot](https://nanobot.dev) runtime, and an Anthropic or OpenAI API key.
 
 <Steps>
   <Step title="Clone and install">
@@ -158,6 +158,36 @@ docker compose --env-file .env.container -f docker-compose.container.yml up -d
   `agent.config.json` holds a real BIP-39 mnemonic. Start on test networks, keep `dry_run` enabled until the setup is verified, and never commit or share the file.
 </Warning>
 
+## First Run
+
+With the agent running, drive one loop by hand and read what it decided before letting it trade for real.
+
+<Steps>
+  <Step title="Confirm dry run is still on">
+    `portfolio.dry_run` defaults to `true` in `agent.config.json`. Leave it there. The agent will reason, decide, and report a trade without submitting it.
+  </Step>
+
+  <Step title="Trigger a loop by hand">
+    Rather than waiting on the schedule, ask the [status API](#status-api) to run one:
+
+    ```bash
+    curl -X POST http://localhost:4242/run \
+      -H 'Content-Type: application/json' \
+      -d '{"task_id":"rebalance"}'
+    ```
+
+    Then read `GET /status` to see the decision, the balances it saw, and the token cost. The dashboard on `http://localhost:5173` shows the same run if you started it.
+  </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.
+  </Step>
+
+  <Step title="Only then disable dry run">
+    Set `portfolio.dry_run` to `false` when the dry-run decisions have looked correct across several runs.
+  </Step>
+</Steps>
+
 ## Status API
 
 The agent exposes a localhost-only control API on port `4242`, used by the dashboard and callable directly.

diff --git a/mintlify-docs/ai-tools/kaleido-mind.mdx b/mintlify-docs/ai-tools/kaleido-mind.mdx
@@ -8,9 +8,9 @@ description: "On-device reasoning engine behind agentic KaleidoSwap wallets, wit
 
 The design starts from a hard constraint: small on-device models are slow and unreliable at multi-step planning. KaleidoMind avoids asking them to do that work.
 
-<Info>
+<Note>
   KaleidoMind does not run by itself, it is a library embedded by a host: the [Rate mobile wallet](https://github.com/kaleidoswap/Rate) (React Native, fully on-device QVAC), the [Desktop App](/desktop-app/getting-started/introduction)'s Tauri sidecar, or an eval and benchmark harness. **[KaleidoAgent](/ai-tools/kaleido-agent) does not currently use this library**, it has its own separate agent loop. See [Relationship to KaleidoAgent](#relationship-to-kaleidoagent) below.
-</Info>
+</Note>
 
 ## The Tiered Funnel
-Original file line number
+Diff line change
@@ Expand Up @@
     The design starts from a hard constraint: small on-device models are slow and unreliable at multi-step planning. KaleidoMind avoids asking them to do that work.
-    <Info>
+    <Note>
       KaleidoMind does not run by itself, it is a library embedded by a host: the [Rate mobile wallet](https://github.com/kaleidoswap/Rate) (React Native, fully on-device QVAC), the [Desktop App](/desktop-app/getting-started/introduction)'s Tauri sidecar, or an eval and benchmark harness. **[KaleidoAgent](/ai-tools/kaleido-agent) does not currently use this library**, it has its own separate agent loop. See [Relationship to KaleidoAgent](#relationship-to-kaleidoagent) below.
-    </Info>
+    </Note>
     ## The Tiered Funnel
@@ Expand Down @@