diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
index d749955..eafa8b9 100644
--- a/.github/workflows/gh-pages.yml
+++ b/.github/workflows/gh-pages.yml
@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-      - feature/ai-readability-p0
   workflow_dispatch: # 仍保留手动触发的功能
 
 jobs:
diff --git a/docs/ai-support/ai-llms.en.md b/docs/ai-support/ai-llms.en.md
index 211381b..8df0493 100644
--- a/docs/ai-support/ai-llms.en.md
+++ b/docs/ai-support/ai-llms.en.md
@@ -56,3 +56,4 @@ Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary,
 - For tool calls, branch on the structured `error.code` / `error.retryable`, never on the human-readable `message`.
 - Read operations are safe to retry; signing / Remote Write operations require user approval (HITL) and must not be auto-retried — see each tool's Safety section.
 - Default to testnets (`nile` / `shasta`) when experimenting; use `mainnet` only for real funds.
+- Version contracts: each tool page documents what is stable vs. volatile under its Compatibility & Migration section — consult it before pinning to any name, flag, or output field.
diff --git a/docs/ai-support/ai-llms.zh.md b/docs/ai-support/ai-llms.zh.md
index 6f962e8..608a641 100644
--- a/docs/ai-support/ai-llms.zh.md
+++ b/docs/ai-support/ai-llms.zh.md
@@ -56,3 +56,4 @@ TronLink 的开发者文档以机器可读形式发布，便于 AI 智能体和
 - 工具调用请基于结构化的 `error.code` / `error.retryable` 分支,**不要**解析人类可读的 `message`。
 - 读操作可安全重试;签名 / 远程写操作需要用户审批（HITL）,且不得自动重试——见各工具的「安全」一节。
 - 实验时默认用测试网（`nile` / `shasta`）;只有动用真实资金时才用 `mainnet`。
+- 版本契约：每个工具页在「兼容性与迁移策略」一节列明了哪些是稳定契约、哪些会变动——在依赖任何名称、flag 或输出字段前请先查阅该节。
diff --git a/docs/ai-support/mcp-server-tronlink.en.md b/docs/ai-support/mcp-server-tronlink.en.md
index 1ca2e46..6aa6893 100644
--- a/docs/ai-support/mcp-server-tronlink.en.md
+++ b/docs/ai-support/mcp-server-tronlink.en.md
@@ -8,7 +8,7 @@
 
 **Key Highlights:**
 - Dual-mode architecture: **Playwright** (browser automation) + **Direct API** (on-chain operations)
-- 32 built-in Flow Recipes with pre-checks and dependency resolution
+- 24 built-in Flow Recipes with pre-checks and dependency resolution
 - Non-custodial local transaction signing via encrypted `agent-wallet`
 - Multi-signature management with real-time WebSocket monitoring
 - Gas-free TRC20 transfers via GasFree service integration
@@ -27,7 +27,7 @@ flowchart TD
   Multi["TronLinkMultiSigCapability (5 tools)"]
   GasFree["TronLinkGasFreeCapability (3 tools)"]
   Util["Utility Capabilities<br/>Build · StateSnapshot · TRON Crypto"]
-  Flow["Flow Recipes<br/>(32 built-in, pre-checked)"]
+  Flow["Flow Recipes<br/>(24 built-in, pre-checked)"]
   Ext["TronGrid API / Multi-Sig Service / GasFree Service"]
   Chain["TRON Blockchain"]
   Agent -- "MCP Protocol — stdio / JSON-RPC 2.0" --> Server
@@ -156,7 +156,9 @@ Runtime wallet management via `@bankofai/agent-wallet` (encrypted `local_secure`
 - `tl_wallet_set_active` — Switch the active wallet by ID (hot-swaps into all capabilities)
 
 If no wallet exists at startup, the server prompts two paths: call `tl_wallet_create` to auto-generate one, or create one manually via CLI and set `AGENT_WALLET_PASSWORD`.
-The auto-create path generates a random password, saves it to `~/.agent-wallet/runtime_secrets.json`, creates an encrypted `main` wallet, and enables the running session to use it.
+
+!!! warning "Auto-create writes the password to disk in plaintext — test/dev only"
+    The auto-create path generates a random password and saves it **in plaintext** to `~/.agent-wallet/runtime_secrets.json`, then creates an encrypted `main` wallet and lets the running session use it. Anyone with read access to that file controls the wallet. For production, use the manual path: create the wallet out-of-band and inject `AGENT_WALLET_PASSWORD` from a secret manager — never rely on the on-disk plaintext password.
 
 ### 6. TRON Cryptography Utils
 
@@ -174,49 +176,49 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256).
 
 ---
 
-## Flow Recipes (32 Built-In)
+## Flow Recipes (24 Built-In)
 
 Pre-configured multi-step workflows with dependency checks and parameter templates.
 
 ### Playwright Flows
-| Flow | Description |
-|------|-------------|
-| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta |
-| `enableTestNetworksFlow` | Enable testnet visibility |
-| `transferTrxFlow` | TRX transfer via UI |
-| `transferTokenFlow` | Token transfer via UI |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | `src/flows/switch-network.ts` |
+| `enableTestNetworksFlow` | Enable testnet visibility | `src/flows/switch-network.ts` |
+| `transferTrxFlow` | TRX transfer via UI | `src/flows/transfer-trx.ts` |
+| `transferTokenFlow` | Token transfer via UI | `src/flows/transfer-trx.ts` |
 
 ### On-Chain Flows (11)
-| Flow | Description |
-|------|-------------|
-| `chainCheckBalanceFlow` | Query balance |
-| `chainTransferTrxFlow` | TRX transfer with pre-checks |
-| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks |
-| `chainStakeFlow` | Stake TRX |
-| `chainUnstakeFlow` | Unstake TRX |
-| `chainGetStakingFlow` | Query staking info |
-| `chainDelegateResourceFlow` | Delegate bandwidth/energy |
-| `chainUndelegateResourceFlow` | Undelegate resources |
-| `chainSetupMultisigFlow` | Setup multi-sig permissions |
-| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx |
-| `chainSwapV3Flow` | SunSwap V3 token swap |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `chainCheckBalanceFlow` | Query balance | `src/flows/onchain.ts` |
+| `chainTransferTrxFlow` | TRX transfer with pre-checks | `src/flows/onchain.ts` |
+| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | `src/flows/onchain.ts` |
+| `chainStakeFlow` | Stake TRX | `src/flows/onchain.ts` |
+| `chainUnstakeFlow` | Unstake TRX | `src/flows/onchain.ts` |
+| `chainGetStakingFlow` | Query staking info | `src/flows/onchain.ts` |
+| `chainDelegateResourceFlow` | Delegate bandwidth/energy | `src/flows/onchain.ts` |
+| `chainUndelegateResourceFlow` | Undelegate resources | `src/flows/onchain.ts` |
+| `chainSetupMultisigFlow` | Setup multi-sig permissions | `src/flows/onchain.ts` |
+| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | `src/flows/onchain.ts` |
+| `chainSwapV3Flow` | SunSwap V3 token swap | `src/flows/onchain.ts` |
 
 ### Multi-Sig Flows (6)
-| Flow | Description |
-|------|-------------|
-| `multisigQueryAuthFlow` | Query permissions |
-| `multisigListTransactionsFlow` | List pending transactions |
-| `multisigMonitorFlow` | WebSocket real-time monitoring |
-| `multisigStopMonitorFlow` | Stop monitoring |
-| `multisigSubmitTxFlow` | Submit signed transaction |
-| `multisigCheckFlow` | Full status check |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `multisigQueryAuthFlow` | Query permissions | `src/flows/multisig.ts` |
+| `multisigListTransactionsFlow` | List pending transactions | `src/flows/multisig.ts` |
+| `multisigMonitorFlow` | WebSocket real-time monitoring | `src/flows/multisig.ts` |
+| `multisigStopMonitorFlow` | Stop monitoring | `src/flows/multisig.ts` |
+| `multisigSubmitTxFlow` | Submit signed transaction | `src/flows/multisig.ts` |
+| `multisigCheckFlow` | Full status check | `src/flows/multisig.ts` |
 
 ### GasFree Flows (3)
-| Flow | Description |
-|------|-------------|
-| `gasfreeCheckAccountFlow` | Query eligibility |
-| `gasfreeTransactionHistoryFlow` | Query history |
-| `gasfreeSendFlow` | Gas-free TRC20 transfer |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `gasfreeCheckAccountFlow` | Query eligibility | `src/flows/gasfree.ts` |
+| `gasfreeTransactionHistoryFlow` | Query history | `src/flows/gasfree.ts` |
+| `gasfreeSendFlow` | Gas-free TRC20 transfer | `src/flows/gasfree.ts` |
 
 ---
 
@@ -394,7 +396,7 @@ mcp-server-tronlink/
 │   │   ├── state-snapshot.ts       # UI state extraction
 │   │   └── tron-crypto.ts          # Address derivation, signing, Base58
 │   └── flows/
-│       ├── index.ts                # Flow registry (32 recipes)
+│       ├── index.ts                # Flow registry (24 recipes)
 │       ├── switch-network.ts       # Network switching flows
 │       ├── transfer-trx.ts         # Transfer flows
 │       ├── multisig.ts             # 6 multi-sig flows
@@ -420,9 +422,11 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump
 | `@noble/hashes` | ^2.0.1 | Keccak-256, SHA256 |
 | `@tronlink/tronlink-mcp-core` | ^0.1.0 | Core MCP server framework |
 | `playwright` | ^1.49.0 | Browser automation |
-| `@bankofai/agent-wallet` | ^2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible |
+| `@bankofai/agent-wallet` | 2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible |
 | `ws` | ^8.18.0 | WebSocket (multi-sig monitoring) |
 
+> **About @bankofai/agent-wallet:** Pinned to exact 2.3.0 (no caret, to avoid silently picking up 2.4.0 on npm). The package's GitHub repo is currently not public (HTTP 404); source transparency comes from the npm publish — audit it via `npm pack @bankofai/agent-wallet@2.3.0`. Upgrading to 2.4.0 should be evaluated against its changelog first.
+
 ---
 
 ## Tool Contract & Side Effects
@@ -446,7 +450,7 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump
 
 These are **docs-side mirrors** of the most critical tool inputs — useful when an agent is writing a tool-call call site without an MCP session open. Runtime `list_tools` remains the authoritative source: the schemas there carry full Zod metadata (descriptions, `default`, etc.) plus `meta.schemaVersion`. Fields below are derived from `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts` and follow JSON Schema Draft 7. The full set of 52 tool schemas is **not** reproduced here — see core for the SSOT.
 
-> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI.
+> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI.
 
 #### `tl_chain_send` — **Remote Write**
 
@@ -700,6 +704,20 @@ The Direct-API path signs with a local encrypted wallet managed by `@bankofai/ag
 5. **Gas-Free Operations** — TRC20 transfers without TRX balance requirements
 6. **Infrastructure Testing** — Contract deployment, fixture management, mock servers
 
+### End-to-end example: swap 100 TRX for USDT on SunSwap V3
+
+A realistic agent turn, showing the tool-call sequence. The agent reads first, gets a fresh quote, surfaces it for human approval, then executes — never auto-executing a Remote Write off a read.
+
+> **User:** "Swap 100 TRX for USDT on SunSwap V3, max 0.5% slippage."
+
+1. `tl_chain_get_account` (Network Read) — confirm the active wallet holds ≥ 100 TRX plus enough for fees.
+2. `tl_chain_swap_v3` with `action=estimate` (Network Read) — `from_token="TRX"`, `to_token="<USDT contract>"`, `amount="100"`, `fee_tier=3000`, `slippage=0.5`. Returns the quoted output and route.
+3. Agent surfaces the quote to the user and waits for confirmation (HITL — this is a Remote Write).
+4. `tl_chain_swap_v3` with `action=execute` and the **same** explicit `slippage=0.5` — signs with the local `agent-wallet` and broadcasts. Returns `txId`.
+5. `tl_chain_get_tx` (Network Read) with the returned `txId` — confirm on-chain success before reporting back.
+
+> If step 4 returns an uncertain/failed result, do **not** auto-retry: `TL_CHAIN_SWAP_FAILED` is not retryable — re-check the chain with `tl_chain_get_tx` first (see Swap safety).
+
 ---
 
 ## Quick Start
@@ -713,8 +731,8 @@ npm install && npm run build
 #   TL_TRONGRID_URL=https://nile.trongrid.io
 #
 # 3. If no wallet exists, choose one path:
-#   Option A: call tl_wallet_create after startup
-#   Option B: create one locally, then set AGENT_WALLET_PASSWORD
+#   Option A (manual): create one locally, then set AGENT_WALLET_PASSWORD
+#   Option B (auto-create): call tl_wallet_create after startup
 
 # 4. Use with Claude Code
 # "Check my TRX balance"
@@ -722,6 +740,17 @@ npm install && npm run build
 # "Swap 100 TRX for USDT on SunSwap V3"
 ```
 
+**Which path? (scenario → path)**
+
+| Scenario | Recommended path | Why |
+|----------|------------------|-----|
+| Production (real funds) | A — manual + secret manager | Path B writes the password in plaintext to `~/.agent-wallet/runtime_secrets.json` |
+| CI / automation (testnet) | A — manual + env injection | Same — keep the password out of an on-disk file |
+| Local dev (one-off) | B — auto-create | No pre-config; the password is generated automatically |
+| Temp demo | B + tmpfs directory | Point `AGENT_WALLET_DIR` at a tmpfs path destroyed at job end |
+
+> Path B (auto-create) writes the generated password in plaintext to `~/.agent-wallet/runtime_secrets.json` so a restart can reuse the wallet. See [Wallet Secret Storage](#wallet-secret-storage) for the full Path A / Path B comparison and how to enforce Path A.
+
 ## Version & License
 
 - **Package:** `@tronlink/mcp-server-tronlink` v0.1.1
diff --git a/docs/ai-support/mcp-server-tronlink.zh.md b/docs/ai-support/mcp-server-tronlink.zh.md
index b975f0a..1edc8b5 100644
--- a/docs/ai-support/mcp-server-tronlink.zh.md
+++ b/docs/ai-support/mcp-server-tronlink.zh.md
@@ -8,7 +8,7 @@
 
 **核心亮点：**
 - 双模架构：**Playwright**（浏览器自动化）+ **Direct API**（链上操作）
-- 32 个内置 Flow Recipe，带预检查和依赖解析
+- 24 个内置 Flow Recipe，带预检查和依赖解析
 - 基于加密 `agent-wallet` 的非托管本地交易签名
 - 多签管理，支持实时 WebSocket 监控
 - 通过 GasFree 服务集成实现零 Gas TRC20 转账
@@ -27,7 +27,7 @@ flowchart TD
   Multi["TronLinkMultiSigCapability (5 个工具)"]
   GasFree["TronLinkGasFreeCapability (3 个工具)"]
   Util["实用能力<br/>Build · StateSnapshot · TRON Crypto"]
-  Flow["Flow Recipes<br/>(32 个内置流程配方)"]
+  Flow["Flow Recipes<br/>(24 个内置流程配方)"]
   Ext["TronGrid API / 多签服务 / GasFree 服务"]
   Chain["TRON 区块链"]
   Agent -- "MCP 协议 — stdio / JSON-RPC 2.0" --> Server
@@ -156,7 +156,9 @@ TRON 多签服务的 REST + WebSocket API：
 - `tl_wallet_set_active` — 按 ID 切换活跃钱包（热切换到所有能力）
 
 如果启动时没有钱包，服务器会提示两条路径：调用 `tl_wallet_create` 自动生成，或通过 CLI 手动创建后设置 `AGENT_WALLET_PASSWORD`。
-自动创建这条路径会生成随机密码，把密码保存到 `~/.agent-wallet/runtime_secrets.json`，创建一个加密的 `main` 钱包，并让当前会话立即可用。
+
+!!! warning "自动创建会把密码以明文写入磁盘——仅限测试/开发"
+    自动创建这条路径会生成随机密码，并把它**以明文**保存到 `~/.agent-wallet/runtime_secrets.json`，随后创建一个加密的 `main` 钱包并让当前会话立即可用。任何能读取该文件的人都能控制钱包。生产环境请使用手动路径：在外部创建钱包，并通过密钥管理器注入 `AGENT_WALLET_PASSWORD`——不要依赖落盘的明文密码。
 
 ### 6. TRON 密码学工具
 
@@ -174,49 +176,49 @@ hexToAddress()             0x41... → T 地址
 
 ---
 
-## Flow Recipes（32 个内置流程）
+## Flow Recipes（24 个内置流程）
 
 预配置的多步骤工作流，带依赖检查和参数模板。
 
 ### Playwright 流程
-| 流程 | 说明 |
-|------|------|
-| `switchNetworkFlow` | 切换到主网/Nile/Shasta |
-| `enableTestNetworksFlow` | 启用测试网可见性 |
-| `transferTrxFlow` | 通过 UI 进行 TRX 转账 |
-| `transferTokenFlow` | 通过 UI 进行代币转账 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `switchNetworkFlow` | 切换到主网/Nile/Shasta | `src/flows/switch-network.ts` |
+| `enableTestNetworksFlow` | 启用测试网可见性 | `src/flows/switch-network.ts` |
+| `transferTrxFlow` | 通过 UI 进行 TRX 转账 | `src/flows/transfer-trx.ts` |
+| `transferTokenFlow` | 通过 UI 进行代币转账 | `src/flows/transfer-trx.ts` |
 
 ### 链上流程（11 个）
-| 流程 | 说明 |
-|------|------|
-| `chainCheckBalanceFlow` | 查询余额 |
-| `chainTransferTrxFlow` | 带预检查的 TRX 转账 |
-| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 |
-| `chainStakeFlow` | 质押 TRX |
-| `chainUnstakeFlow` | 解除质押 TRX |
-| `chainGetStakingFlow` | 查询质押信息 |
-| `chainDelegateResourceFlow` | 代理带宽/能量 |
-| `chainUndelegateResourceFlow` | 取消代理资源 |
-| `chainSetupMultisigFlow` | 设置多签权限 |
-| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 |
-| `chainSwapV3Flow` | SunSwap V3 代币兑换 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `chainCheckBalanceFlow` | 查询余额 | `src/flows/onchain.ts` |
+| `chainTransferTrxFlow` | 带预检查的 TRX 转账 | `src/flows/onchain.ts` |
+| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 | `src/flows/onchain.ts` |
+| `chainStakeFlow` | 质押 TRX | `src/flows/onchain.ts` |
+| `chainUnstakeFlow` | 解除质押 TRX | `src/flows/onchain.ts` |
+| `chainGetStakingFlow` | 查询质押信息 | `src/flows/onchain.ts` |
+| `chainDelegateResourceFlow` | 代理带宽/能量 | `src/flows/onchain.ts` |
+| `chainUndelegateResourceFlow` | 取消代理资源 | `src/flows/onchain.ts` |
+| `chainSetupMultisigFlow` | 设置多签权限 | `src/flows/onchain.ts` |
+| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 | `src/flows/onchain.ts` |
+| `chainSwapV3Flow` | SunSwap V3 代币兑换 | `src/flows/onchain.ts` |
 
 ### 多签流程（6 个）
-| 流程 | 说明 |
-|------|------|
-| `multisigQueryAuthFlow` | 查询权限 |
-| `multisigListTransactionsFlow` | 列出待处理交易 |
-| `multisigMonitorFlow` | WebSocket 实时监控 |
-| `multisigStopMonitorFlow` | 停止监控 |
-| `multisigSubmitTxFlow` | 提交签名交易 |
-| `multisigCheckFlow` | 完整状态检查 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `multisigQueryAuthFlow` | 查询权限 | `src/flows/multisig.ts` |
+| `multisigListTransactionsFlow` | 列出待处理交易 | `src/flows/multisig.ts` |
+| `multisigMonitorFlow` | WebSocket 实时监控 | `src/flows/multisig.ts` |
+| `multisigStopMonitorFlow` | 停止监控 | `src/flows/multisig.ts` |
+| `multisigSubmitTxFlow` | 提交签名交易 | `src/flows/multisig.ts` |
+| `multisigCheckFlow` | 完整状态检查 | `src/flows/multisig.ts` |
 
 ### GasFree 流程（3 个）
-| 流程 | 说明 |
-|------|------|
-| `gasfreeCheckAccountFlow` | 查询资格 |
-| `gasfreeTransactionHistoryFlow` | 查询历史 |
-| `gasfreeSendFlow` | 免 Gas TRC20 转账 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `gasfreeCheckAccountFlow` | 查询资格 | `src/flows/gasfree.ts` |
+| `gasfreeTransactionHistoryFlow` | 查询历史 | `src/flows/gasfree.ts` |
+| `gasfreeSendFlow` | 免 Gas TRC20 转账 | `src/flows/gasfree.ts` |
 
 ---
 
@@ -386,7 +388,7 @@ mcp-server-tronlink/
 │   │   ├── state-snapshot.ts       # UI 状态提取
 │   │   └── tron-crypto.ts          # 地址派生、签名、Base58
 │   └── flows/
-│       ├── index.ts                # 流程注册（32 个配方）
+│       ├── index.ts                # 流程注册（24 个配方）
 │       ├── switch-network.ts       # 网络切换流程
 │       ├── transfer-trx.ts         # 转账流程
 │       ├── multisig.ts             # 6 个多签流程
@@ -412,14 +414,16 @@ mcp-server-tronlink/
 | `@noble/hashes` | ^2.0.1 | Keccak-256、SHA256 |
 | `@tronlink/tronlink-mcp-core` | ^0.1.0 | 核心 MCP 服务框架 |
 | `playwright` | ^1.49.0 | 浏览器自动化 |
-| `@bankofai/agent-wallet` | ^2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 |
+| `@bankofai/agent-wallet` | 2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 |
 | `ws` | ^8.18.0 | WebSocket（多签监控） |
 
+> **关于 @bankofai/agent-wallet：** 版本精确钉死在 2.3.0（不用 caret，避免静默升到 npm 上的 2.4.0）。该包的 GitHub 仓库当前未公开（HTTP 404），源码透明性由 npm publish 提供——可用 `npm pack @bankofai/agent-wallet@2.3.0` 解包审计。是否升级到 2.4.0 需另行评估其 changelog 后决定。
+
 ---
 
 ## 工具契约与副作用
 
-**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。
+**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。
 
 **逐工具输入 schema 可在运行时发现。** 每个工具的参数都由 core 用 Zod 校验,并通过 MCP `list_tools` 方法以 JSON `inputSchema` 形式暴露,因此客户端无需阅读本页即可枚举参数名、类型和必填项。下方表格按能力归纳工具;`list_tools` 才是权威的机器可读来源。
 
@@ -434,11 +438,11 @@ mcp-server-tronlink/
 - **人工确认（HITL）：** 写操作工具使用加密的本地 `agent-wallet` 签名；浏览器模式下由用户在 TronLink UI 审批。生产环境应将每个「远程写」工具视为需要确认。
 - **重试：** 只读工具可安全重试；「远程写」工具除非证明幂等，否则不得自动重试。
 
-### 精选工具 schema（文档侧镜像）
+### 精选工具 schema（文档侧镜像） { #selected-tool-schemas-inline-mirror }
 
 以下是最关键工具输入的**文档侧镜像**——当 agent 需要在没有打开 MCP 会话的情况下写工具调用站点时使用。运行时 `list_tools` 仍是权威源：那里有完整的 Zod 元信息（描述、`default` 等）以及 `meta.schemaVersion`。下方字段抄自 `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts`，遵循 JSON Schema Draft 7。**未**镜像全部 52 个工具——以 core 仓库为 SSOT。
 
-> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。
+> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。
 
 #### `tl_chain_send` —— **Remote Write**
 
@@ -623,7 +627,7 @@ mcp-server-tronlink/
 
 重启后用 `list_tools` 验证：`tl_evaluate` 应当不再出现。同一套模式也适用于 `tl_seed_contract` / `tl_seed_contracts`（仅 e2e 的合约部署工具）。
 
-### 钱包密钥存储
+### 钱包密钥存储 { #wallet-secret-storage }
 
 Direct-API 路径使用 `@bankofai/agent-wallet` 管理的本地加密钱包签名。解锁这把钱包有两条路径，请按目的明确选择。
 
@@ -691,6 +695,20 @@ Direct-API 路径使用 `@bankofai/agent-wallet` 管理的本地加密钱包签
 5. **免 Gas 操作** — 无需 TRX 余额即可完成 TRC20 转账
 6. **基础设施测试** — 合约部署、固件管理、Mock 服务
 
+### 端到端示例：在 SunSwap V3 上用 100 TRX 兑换 USDT
+
+一个真实的 agent 回合，展示工具调用顺序。agent 先读取、再现取报价、交人工确认后才执行——绝不基于 read 结果自动触发「远程写」。
+
+> **用户：** "在 SunSwap V3 上用 100 TRX 兑换 USDT，滑点上限 0.5%。"
+
+1. `tl_chain_get_account`（Network Read）—— 确认当前钱包持有 ≥ 100 TRX 且留有手续费余量。
+2. `tl_chain_swap_v3`，`action=estimate`（Network Read）—— `from_token="TRX"`、`to_token="<USDT 合约>"`、`amount="100"`、`fee_tier=3000`、`slippage=0.5`。返回报价输出与路径。
+3. agent 把报价呈现给用户并等待确认（HITL——这是一笔远程写）。
+4. `tl_chain_swap_v3`，`action=execute`，并传入**相同的**显式 `slippage=0.5`——用本地 `agent-wallet` 签名并广播。返回 `txId`。
+5. `tl_chain_get_tx`（Network Read），传入返回的 `txId`——在回报前先确认链上成功。
+
+> 若第 4 步返回结果未知 / 失败，**不要**自动重试：`TL_CHAIN_SWAP_FAILED` 不可重试——先用 `tl_chain_get_tx` 核对链上状态（见「兑换安全」）。
+
 ---
 
 ## 快速开始
@@ -703,10 +721,10 @@ npm install && npm run build
 export TL_TRONGRID_URL="https://nile.trongrid.io"
 
 # 3. 如果本地还没有钱包，二选一：
-# 方案 A：在 MCP 会话里调用 tl_wallet_create
-# 方案 B：本地执行
-# agent-wallet start local_secure --generate --wallet-id main
-# 然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD
+# 路径 A（手动）：本地执行
+#   agent-wallet start local_secure --generate --wallet-id main
+#   然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD
+# 路径 B（自动创建）：在 MCP 会话里调用 tl_wallet_create
 
 # 4. 配合 Claude Code 使用
 # 配置好 .mcp.json 后自然语言使用：
@@ -715,6 +733,17 @@ export TL_TRONGRID_URL="https://nile.trongrid.io"
 # "在 SunSwap V3 上用 100 TRX 兑换 USDT"
 ```
 
+**该选哪条路径？（场景 → 路径）**
+
+| 场景 | 推荐路径 | 原因 |
+|------|---------|------|
+| 生产环境（真实资金） | A — 手动创建 + secret manager | 路径 B 会把密码以明文写入 `~/.agent-wallet/runtime_secrets.json` |
+| CI / 自动化（测试网） | A — 手动创建 + env 注入 | 同上——避免密码落盘到文件 |
+| 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 |
+| 临时 demo 演示 | B + tmpfs 目录 | 把 `AGENT_WALLET_DIR` 指到任务结束即销毁的 tmpfs |
+
+> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#wallet-secret-storage)。
+
 ## 版本与许可证
 
 - **包：** `@tronlink/mcp-server-tronlink` v0.1.1
@@ -726,7 +755,7 @@ export TL_TRONGRID_URL="https://nile.trongrid.io"
 - **语义化版本。** 1.0 之前：**minor** 升级（0.x → 0.y）允许破坏性变更；**patch** 升级（0.1.x → 0.1.y）不变更工具名、输入 schema、`error.code` 值或 `meta.schemaVersion` 语义。1.0 之后：标准 semver，仅 major 允许破坏。
 - **稳定契约**（patch 不会动）：
     - 工具名（`tl_chain_send`、`tl_chain_swap_v3`、`tl_multisig_*`、`tl_gasfree_*`、`tl_evaluate` 等）
-    - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码)）
+    - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes)）
     - `error.retryable` 语义
     - `meta.schemaVersion` 的 major 分量
     - 必需环境变量名（`TL_TRONGRID_URL`、`TL_MULTISIG_SECRET_KEY`、`AGENT_WALLET_PASSWORD` 等）
diff --git a/docs/ai-support/mcp-tronlink-signer.en.md b/docs/ai-support/mcp-tronlink-signer.en.md
index 5d99315..160d7f6 100644
--- a/docs/ai-support/mcp-tronlink-signer.en.md
+++ b/docs/ai-support/mcp-tronlink-signer.en.md
@@ -4,6 +4,22 @@
 
 MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet.
 
+> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version-license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK.
+
+## Which to use
+
+TronLink ships three ways to let an AI agent act on Tron. Pick based on whether a human must approve each transaction and where the agent runs.
+
+| | `mcp-tronlink-signer` (this server) | `mcp-server-tronlink` (Direct-API mode) | `tronlink-cli` |
+| --- | --- | --- | --- |
+| Approval | HITL — user approves every transaction in the browser | No HITL — signs automatically | HITL — user approves in the browser |
+| Credentials on host | None (keys stay in the TronLink extension) | Uses `AGENT_WALLET_PASSWORD` to unlock a local wallet | None (keys stay in the TronLink extension) |
+| Interface | MCP server | MCP server | Shell / command line |
+| Best for | Agents that should never move funds without explicit human sign-off | Automated, unattended flows: CI, testnet scripting | Interactive terminal use with human sign-off |
+| Private-key exposure | Lowest | Higher (credential on host) | Lowest |
+
+If unsure, prefer `mcp-tronlink-signer` (safest default).
+
 ## Setup
 
 ### Claude Code
@@ -56,6 +72,55 @@ All tools support an optional `network` parameter (`mainnet` / `nile` / `shasta`
 
 **Human-in-the-loop.** Every tool that signs (`send_trx`, `send_trc20`, `sign_message`, `sign_typed_data`, `sign_transaction`) opens the TronLink approval page in the browser. The AI agent **cannot** sign without the user clicking Approve. Treat Remote Write tools as requiring confirmation in production.
 
+### Selected tool schemas (inline mirror)
+
+Docs-side mirrors of the core write tools' inputs, derived from the tool parameters documented in the table above — useful when an agent is writing a tool-call site without an MCP session open. Field names and the required set are mirrored here; runtime `list_tools` remains the authoritative source for the full input schemas (exact field types, defaults, and any Zod metadata).
+
+`send_trx`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Amount of TRX to send" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["to", "amount"]
+}
+```
+
+`send_trc20`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" },
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Token amount to send" },
+    "decimals": { "description": "Optional token decimals" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["contractAddress", "to", "amount"]
+}
+```
+
+`sign_typed_data`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "typedData": { "description": "EIP-712 typed-data object to sign" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["typedData"]
+}
+```
+
+> Field types above are intentionally left unspecified where they could not be confirmed against the upstream Zod definitions; consult `list_tools` for the exact types. `sign_message` (`message`, `network?`) and `sign_transaction` (`transaction`, `broadcast`, `network?`) follow the same parameter shapes shown in the tool table.
+
 ## MCP Resources
 
 | URI | Description |
@@ -172,6 +237,8 @@ The server returns errors in the standard MCP shape. Each error carries a stable
 
 This page mirrors a downstream README; for the source of truth see the GitHub releases above and the `CHANGELOG.md` in each package. Entries below cover the **MCP-visible** surface (tools, schema, security boundaries) — internal refactors are omitted.
 
+> **Sync policy.** This inline changelog mirrors the package `CHANGELOG.md` / README; the project's **GitHub releases are the authoritative source**. This page may lag a release by a short window until the docs are updated, so verify against the GitHub releases (and `list_tools`) when an exact version matters.
+
 #### v0.1.4 _(npm-only, not GitHub-tagged at time of writing)_
 
 Patch-only. No new tools, no breaking input/output shapes. Verify against `list_tools` after upgrade.
diff --git a/docs/ai-support/mcp-tronlink-signer.zh.md b/docs/ai-support/mcp-tronlink-signer.zh.md
index 33667db..4f7c3b0 100644
--- a/docs/ai-support/mcp-tronlink-signer.zh.md
+++ b/docs/ai-support/mcp-tronlink-signer.zh.md
@@ -4,6 +4,22 @@
 
 将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具的服务器，供 Claude 及其他 AI 客户端使用。通过 TronLink 浏览器钱包对 TRON 交易进行签名，需用户在浏览器中授权确认 — 私钥始终留在钱包中，不会对外暴露。
 
+> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#version-license)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。
+
+## 该用哪个
+
+TronLink 提供了三种方式让 AI 智能体在 Tron 上执行操作。请根据是否需要人工审批每一笔交易、以及智能体运行在何处来选择。
+
+| | `mcp-tronlink-signer`（本服务器） | `mcp-server-tronlink`（Direct-API 模式） | `tronlink-cli` |
+| --- | --- | --- | --- |
+| 审批 | HITL —— 用户在浏览器中审批每一笔交易 | 无 HITL —— 自动签名 | HITL —— 用户在浏览器中审批 |
+| 主机上的凭证 | 无（私钥保留在 TronLink 扩展内） | 使用 `AGENT_WALLET_PASSWORD` 解锁本地钱包 | 无（私钥保留在 TronLink 扩展内） |
+| 接口形态 | MCP 服务器 | MCP 服务器 | Shell / 命令行 |
+| 适用场景 | 任何资金转移都必须经人工显式签字确认的智能体 | 自动化、无人值守流程：CI、测试网脚本 | 需要人工签字确认的交互式终端使用 |
+| 私钥暴露风险 | 最低 | 较高（凭证位于主机上） | 最低 |
+
+如果不确定，优先选择 `mcp-tronlink-signer`（最安全的默认选项）。
+
 ## 配置
 
 ### Claude Code
@@ -56,6 +72,55 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si
 
 **人工确认（HITL）。** 所有涉及签名的工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 浏览器审批页。AI agent **无法**在用户点击 Approve 之前签名。生产环境必须把 Remote Write 工具视为需要确认。
 
+### 部分工具 Schema（内联镜像）
+
+以下是核心写操作工具入参的文档侧镜像，依据上方工具表中记录的参数整理而成 —— 在没有 MCP 会话时，便于智能体离线编写工具调用。这里镜像的是字段名与 required 集合；运行时 `list_tools` 仍是完整输入 schema（精确字段类型、默认值及 Zod 元数据）的权威来源。
+
+`send_trx`：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Amount of TRX to send" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["to", "amount"]
+}
+```
+
+`send_trc20`：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" },
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Token amount to send" },
+    "decimals": { "description": "Optional token decimals" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["contractAddress", "to", "amount"]
+}
+```
+
+`sign_typed_data`：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "typedData": { "description": "EIP-712 typed-data object to sign" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["typedData"]
+}
+```
+
+> 凡无法对照上游 Zod 定义确认的字段类型，上面均有意留空；精确类型请查 `list_tools`。`sign_message`（`message`、`network?`）与 `sign_transaction`（`transaction`、`broadcast`、`network?`）遵循工具表中所示的同样参数形态。
+
 ## MCP 资源
 
 | URI | 说明 |
@@ -115,7 +180,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si
 
 > 「已发送 5 TRX——链上已确认（交易 `0a1b2c…`）。」
 
-> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#错误)）。
+> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#errors)）。
 
 ## 取消
 
@@ -125,9 +190,9 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si
 
 当调用 `sign_transaction` 且 `broadcast: true` 时，服务器会在广播后自动轮询链上确认状态，并返回执行结果（`success` 或 `pending`）。如果交易在链上失败（如 `OUT_OF_ENERGY`、Solidity revert），错误信息会连同解码后的原因一并返回给 AI 智能体。
 
-## 错误
+## 错误 { #errors }
 
-server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码) 为准；signer 特有错误如下：
+server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes) 为准；signer 特有错误如下：
 
 | 条件 | Retryable | 何时发生 |
 | --- | :---: | --- |
@@ -148,13 +213,13 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r
 |---|---|---|
 | **Prompt 注入** | 工具输入按原始值作为调用参数，server 不会再次提交给 LLM。TronLink 审批页渲染的是解析后的交易字段，不是 agent 的自由文本。 | 链上拿到的字符串（备注、revert 原因）视为不可信；分支应基于 `txId` / `status` / `code`，而非 prose。 |
 | **本地 HTTP listener** | 本地审批 server **仅绑定 `127.0.0.1`**（端口 `TRON_HTTP_PORT`，默认 3386，被占用时自增），永远不接受跨主机连接。每个 server session 有唯一 ID，前一次 session 的浏览器标签会被自动失效。 | 不要把 3386 端口转发到外网。同一台机器不要用相同 `TRON_HTTP_PORT` 跑两份。 |
-| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#环境变量) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 |
+| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#environment-variables) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 |
 | **API key 处理（token passthrough）** | `TRON_API_KEY` 仅在启动时从 env 读取，仅用于到 TronGrid 的出站；**不**会出现在任何工具响应、错误 `details` 或 MCP resource 中。server 不接受 MCP 客户端传入的 Authorization header 并转发到上游。 | API key 放进 MCP host 的 secret manager，不要写进会提交 git 的 `mcpServers` 配置。 |
 | **签名必须 HITL** | 所有签名工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 审批页，**不存在程序化绕过**。私钥始终留在 TronLink。 | 不需要运维额外强制 HITL——这是结构性保证。不要试图通过移除浏览器层来"加固"。 |
 | **浏览器标签劫持** | 审批页基于 server session ID 验证每次请求，过期的标签会被忽略；心跳检测会在断连时关闭 session。 | 同一用户跑多个 agent 时，请让每个 agent 启动自己的 signer 实例；跨实例的请求串扰由 session ID 屏蔽，但 UI 层混淆不防。 |
 | **Confused deputy** | signer 以已连接的 TronLink 账户身份执行，没有来自 MCP 客户端的逐次授权 scope。 | 一个 signer 实例 = 一个 TronLink 账户，不要把多个终端用户复用到同一个实例。 |
 
-## 环境变量
+## 环境变量 { #environment-variables }
 
 | 变量名 | 说明 | 默认值 |
 | ------ | ---- | ------ |
@@ -162,16 +227,18 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r
 | `TRON_HTTP_PORT` | 本地 HTTP 服务端口 | `3386` |
 | `TRON_API_KEY` | TronGrid API Key（可选） | - |
 
-## 版本与许可证
+## 版本与许可证 { #version-license }
 
 - **包：** `mcp-tronlink-signer` v0.1.4
 - **许可证：** MIT —— `SPDX-License-Identifier: MIT`
 - **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases)
 
-### 内联 changelog
+### 内联 changelog { #inline-changelog }
 
 本页是下游 README 镜像；以 GitHub releases 与各包 `CHANGELOG.md` 为准。下方条目只覆盖 **MCP 可见面**（工具、schema、安全边界），内部重构不列。
 
+> **同步策略。** 此内联 changelog 镜像软件包的 `CHANGELOG.md` / README；项目的 **GitHub releases 为权威来源**。在文档更新之前，本页可能比某个发布版本短暂滞后，因此当需要精确版本号时，请以 GitHub releases（以及 `list_tools`）为准核对。
+
 #### v0.1.4 _(仅 npm，截至本文写就尚未在 GitHub 打 tag)_
 
 仅 patch 修复。无新工具、无破坏性输入/输出 shape 变化。升级后用 `list_tools` 复核。
@@ -190,7 +257,7 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r
 - **改进** —— 单页审批流：一个常驻浏览器标签 + 心跳检测；server 重启后旧标签自动失效。
 - **改进** —— TRC20 金额校验改用 BigInt 小数转换（处理 0 位小数、>18 位小数等边界）。
 - **改进** —— `send_trx`、`sign_transaction` 在提交失败时返回真实的 broadcast 错误，不再是空消息。
-- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#错误)）。
+- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#errors)）。
 
 #### v0.1.1 — 2026-04-15
 
diff --git a/docs/ai-support/tronlink-cli.en.md b/docs/ai-support/tronlink-cli.en.md
index c2e44d1..0af6ded 100644
--- a/docs/ai-support/tronlink-cli.en.md
+++ b/docs/ai-support/tronlink-cli.en.md
@@ -435,11 +435,13 @@ tronlink reward --json
 
 ### Common Token Contracts
 
-| Token | Network | Contract                            |
-| ----- | ------- | ----------------------------------- |
-| USDT  | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
-| USDD  | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz |
-| USDC  | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 |
+> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The table below is a subset reconciled to that SSOT.
+
+| Token | Network | Contract                            | Decimals |
+| ----- | ------- | ----------------------------------- | -------- |
+| USDT  | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
+| USDC  | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 |
+| USDD  | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 |
 
 ### Example: AI Transfer Flow
 
diff --git a/docs/ai-support/tronlink-cli.zh.md b/docs/ai-support/tronlink-cli.zh.md
index c42a2d8..fd177e4 100644
--- a/docs/ai-support/tronlink-cli.zh.md
+++ b/docs/ai-support/tronlink-cli.zh.md
@@ -431,11 +431,13 @@ tronlink reward --json
 
 ### 常用代币合约
 
-| 代币 | 网络 | 合约地址 |
-| ---- | ---- | -------- |
-| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
-| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz |
-| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 |
+> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下表为对齐该 SSOT 的子集。
+
+| 代币 | 网络 | 合约地址 | 精度 |
+| ---- | ---- | -------- | ---- |
+| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
+| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 |
+| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 |
 
 ### 示例：AI 转账流程
 
@@ -472,7 +474,7 @@ CLI 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级允
     - 子命令名与其必填位置参数 / flag。
     - **Exit code** —— Exit Codes 表中的每一条都属于公开面。minor 允许为此前的通用失败新增 code；重新分配已有数字属于 major。
     - **`--json` 输出 key** —— 顶层 key（`ok`、`error.code`、`error.retryable`、`txid` 等）以及 `error` 下的结构。minor 允许新增可选字段；改名 / 删除属于 major。
-    - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 共享 SSOT）。
+    - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 共享 SSOT）。
 - **不稳定契约**（随时可能变化）：
     - 未带 `--json` 的人类可读 stdout 文本。
     - 提示、横幅、颜色码的具体文本。
diff --git a/docs/ai-support/tronlink-mcp-core.en.md b/docs/ai-support/tronlink-mcp-core.en.md
index 4da7a52..ddb9c3a 100644
--- a/docs/ai-support/tronlink-mcp-core.en.md
+++ b/docs/ai-support/tronlink-mcp-core.en.md
@@ -60,6 +60,18 @@ flowchart TD
 
 **mcp-server-tronlink is a consumer of tronlink-mcp-core.** The core defines WHAT tools exist; the server provides HOW they work.
 
+### Which one should I pick?
+
+Use this decision matrix to choose between the two packages by scenario:
+
+| Scenario | Pick tronlink-mcp-core | Pick mcp-server-tronlink |
+|----------|:---:|:---:|
+| Building a custom MCP server that embeds your own business logic | ✅ | |
+| Giving a ready-to-run server directly to an agent | | ✅ |
+| Extending capabilities with a custom `Capability` implementation | ✅ | |
+| Testing or mocking with injectable fixtures / mock server | ✅ | |
+| Learning how the MCP framework (interfaces, tools, response format) works | ✅ | |
+
 ---
 
 ## ISessionManager Interface
diff --git a/docs/ai-support/tronlink-mcp-core.zh.md b/docs/ai-support/tronlink-mcp-core.zh.md
index 3024d60..17d0914 100644
--- a/docs/ai-support/tronlink-mcp-core.zh.md
+++ b/docs/ai-support/tronlink-mcp-core.zh.md
@@ -60,6 +60,18 @@ flowchart TD
 
 **mcp-server-tronlink 是 tronlink-mcp-core 的使用者。** 核心库定义了工具"是什么"；服务器提供了工具"怎么工作"。
 
+### 该选哪个？
+
+按场景用下面的决策矩阵在两个包之间做选择：
+
+| 场景 | 选 tronlink-mcp-core | 选 mcp-server-tronlink |
+|------|:---:|:---:|
+| 构建嵌入自有业务逻辑的自定义 MCP 服务器 | ✅ | |
+| 直接把一个开箱即用的服务器交给 agent 使用 | | ✅ |
+| 通过自定义 `Capability` 实现扩展能力 | ✅ | |
+| 用可注入的 fixture / mock server 做测试或 mock | ✅ | |
+| 学习 MCP 框架（接口、工具、响应格式）的工作原理 | ✅ | |
+
 ---
 
 ## ISessionManager 接口
@@ -247,7 +259,7 @@ interface GasFreeCapability {
 
 所有工具使用 `tl_` 前缀，分为 13 个类别：
 
-> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#精选工具-schema文档侧镜像) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。
+> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#selected-tool-schemas-inline-mirror) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。
 
 ### 1. 会话管理（2 个）
 | 工具 | 说明 |
@@ -385,7 +397,7 @@ interface GasFreeCapability {
 }
 ```
 
-### 错误码
+### 错误码 (Error Codes)
 
 这是本框架所有工具返回错误码的**唯一数据源**（SSOT）。下游 server（`mcp-server-tronlink`、`mcp-tronlink-signer`）继承这些错误码并可扩展自有错误码。`retryable` 反映框架层面的安全性，agent 仍**必须**叠加调用工具的副作用分级——无论 `retryable` 为何，**结果未确认的 Remote Write 绝不能自动重试**。
 
diff --git a/docs/ai-support/tronlink-signer.zh.md b/docs/ai-support/tronlink-signer.zh.md
index b56098a..f499d9d 100644
--- a/docs/ai-support/tronlink-signer.zh.md
+++ b/docs/ai-support/tronlink-signer.zh.md
@@ -50,7 +50,7 @@ await signer.stop();
 
 ### `signer.sendTrx(to, amount, network?, options?): Promise<BroadcastResult>`
 
-向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#广播结果)）。
+向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#broadcast-result)）。
 
 | 参数 | 类型 | 说明 |
 | ---- | ---- | ---- |
@@ -61,7 +61,7 @@ await signer.stop();
 
 ### `signer.sendTrc20(contractAddress, to, amount, decimals?, network?, options?): Promise<BroadcastResult>`
 
-发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#广播结果)。
+发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#broadcast-result)。
 
 | 参数 | 类型 | 说明 |
 | ---- | ---- | ---- |
@@ -93,7 +93,7 @@ const { signature } = await signer.signTypedData({
 
 ### `signer.signTransaction(transaction, network?, broadcast?, options?): Promise<{ signedTransaction; txId?; status?; error? }>`
 
-对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#广播结果)。
+对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#broadcast-result)。
 
 | 参数 | 类型 | 说明 |
 | ---- | ---- | ---- |
@@ -121,7 +121,7 @@ const result = await signer.signTransaction(tx, "nile", true, {
 });
 ```
 
-### 广播结果
+### 广播结果 { #broadcast-result }
 
 广播类方法（`sendTrx`、`sendTrc20`、以及 `broadcast: true` 时的 `signTransaction`）均返回 `BroadcastResult`：
 
@@ -302,7 +302,7 @@ export type {
 
 - **包：** `tronlink-signer` v0.1.4
 - **许可证：** MIT —— `SPDX-License-Identifier: MIT`
-- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#内联-changelog)，SDK 层跟随同一波次。
+- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#inline-changelog)，SDK 层跟随同一波次。
 
 ### 兼容性与迁移策略
 
diff --git a/docs/ai-support/tronlink-skills.en.md b/docs/ai-support/tronlink-skills.en.md
index 2e3e958..4e6dfa4 100644
--- a/docs/ai-support/tronlink-skills.en.md
+++ b/docs/ai-support/tronlink-skills.en.md
@@ -264,6 +264,22 @@ tron-wallet (check balance) → tron-staking (staking info) → tron-staking (AP
 tron-resource (check status) → tron-resource (estimate cost) → tron-resource (optimize-cost)
 ```
 
+### End-to-end examples
+
+**"Is swapping 100 TRX for USDT worth it right now?"**
+
+1. `token-price` (`tron-market`) — fetch current TRX and USDT prices to establish the reference value of 100 TRX.
+2. `kline` (`tron-market`) — pull recent candlesticks to judge whether TRX is trending up or down (timing).
+3. `resource-info` (`tron-resource`) — check the account's Energy/Bandwidth so the agent can estimate whether the swap will have to burn TRX for fees.
+4. `swap-quote` (`tron-swap`) — request an actual quote for 100 TRX → USDT, including expected output and price impact.
+5. The agent compares the quote's effective rate against the spot price from step 1, factors in the resource cost from step 3, and answers whether the swap is favorable. These steps are **read-only** — to actually execute, route to `mcp-server-tronlink` `tl_chain_swap_v3` (Remote Write, HITL, set `minOut`) or the [signer SDK](tronlink-signer.md).
+
+**"Did my last USDT transfer go through, and what's my balance now?"**
+
+1. `tx-status` (`tron-swap`) — look up the most recent transfer's status and confirmations.
+2. `account-info` (`tron-wallet`) — confirm the current balances after that transfer settled.
+3. `resource-info` (`tron-resource`) — verify enough Energy/Bandwidth remains for a follow-up transfer (otherwise it would burn TRX). Sending the next transfer is a Remote Write — route to the [signer SDK](tronlink-signer.md) `sendTrc20` or `mcp-server-tronlink` `tl_chain_send`.
+
 ---
 
 ## TRON Resource Model Reference
@@ -416,6 +432,16 @@ export TRONGRID_API_KEY="your-api-key"
 export TRON_NETWORK="mainnet"    # or "shasta" / "nile"
 ```
 
+#### TronGrid API key — credential management
+
+`TRONGRID_API_KEY` is optional (read-only, higher rate limits), but if you set one, manage it across these five dimensions:
+
+- **Storage** — keep it in an environment variable or a secrets manager. Never hardcode it in source, in config committed to git, or in chat/agent logs.
+- **Least-privilege** — provision a key scoped only to the read endpoints these skills call; don't reuse a broader production key.
+- **Rotation** — rotate on a fixed schedule, and whenever someone with access leaves; keep the rotation window short.
+- **Leak-detection** — monitor TronGrid usage for anomalous call volume or unexpected source IPs, and scan repository history with a secret scanner for accidental commits.
+- **Revocation** — if a key leaks, revoke it immediately in the TronGrid dashboard and issue a fresh one before resuming traffic.
+
 ### Network Support
 
 | Network | URL | Use Case |
@@ -426,6 +452,8 @@ export TRON_NETWORK="mainnet"    # or "shasta" / "nile"
 
 ### Built-In Token Shortcuts
 
+> The symbols below are the ones `tron_api.mjs` recognizes as shortcuts for their contract addresses. For any token not listed here (e.g. USDD), look up its address in [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot) and pass it explicitly.
+
 | Symbol | Contract Address |
 |--------|------------------|
 | TRX | Native (no contract) |
@@ -498,6 +526,18 @@ tronlink-skills/
 
 ---
 
+## Troubleshooting
+
+| Symptom | Cause | What to do |
+|---------|-------|------------|
+| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill-mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. |
+| TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). |
+| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill-mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs <command> ...`) instead of `tools/call`. |
+| `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. |
+| Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add <name>`), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. |
+
+---
+
 ## Address Format Support
 
 Both formats are supported and auto-normalized across all commands:
@@ -553,7 +593,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma
 
 - **Stable contracts** (won't change in a minor or patch):
     - The 33 CLI command names and their required / optional flags (`tron_api.mjs <command> [...]`).
-    - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill--mcp-tool-map) (`tron_*` form) and their `inputSchema` keys.
+    - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill-mcp-tool-map) (`tron_*` form) and their `inputSchema` keys.
     - Exit codes: `0` success, `1` query error / invalid input, `2` unsupported / unknown command.
     - The `Network Read` side-effect classification — no command will ever become a Remote Write without a major bump.
 - **Volatile contracts** (may change in a minor):
diff --git a/docs/ai-support/tronlink-skills.zh.md b/docs/ai-support/tronlink-skills.zh.md
index d40a626..30a425e 100644
--- a/docs/ai-support/tronlink-skills.zh.md
+++ b/docs/ai-support/tronlink-skills.zh.md
@@ -50,7 +50,7 @@ tron_api.mjs (Node.js 18+, 原生 fetch, 零依赖)
 
 ---
 
-## 6 大技能详解
+## 6 大技能详解 { #the-6-skills }
 
 ### 1. tron-wallet（6 个命令）
 
@@ -153,7 +153,7 @@ Stake 2.0 查询与 SR 信息。
 
 ---
 
-## Skill ↔ MCP 工具映射
+## Skill ↔ MCP 工具映射 { #skill-mcp-tool-map }
 
 `scripts/mcp_server.mjs`（即[方式二](#mcp)的封装）将 **33 个 CLI 命令中的 25 个** 暴露为 MCP 工具——签名、输入字段、输出结构都由同一份 `tron_api.mjs` 实现派生，因此 CLI 与 MCP 工具保证等价。剩余 8 个 CLI-only 命令仍可通过方式一（skill 提示词）和方式三（直接 CLI）使用。需要按用户提问路由到具体工具，或核对 `tools/list` 输出时，请用下表。
 
@@ -264,6 +264,22 @@ tron-wallet（查余额）→ tron-staking（质押信息）→ tron-staking（A
 tron-resource（检查状态）→ tron-resource（估算成本）→ tron-resource（optimize-cost）
 ```
 
+### 端到端示例
+
+**"把 100 TRX 换成 USDT 现在划算吗？"**
+
+1. `token-price`（`tron-market`）—— 获取 TRX 与 USDT 当前价格，确定 100 TRX 的参考价值。
+2. `kline`（`tron-market`）—— 拉取近期 K 线，判断 TRX 处于上行还是下行趋势（择时）。
+3. `resource-info`（`tron-resource`）—— 查询账户的能量/带宽，便于估算本次兑换是否需要燃烧 TRX 抵扣手续费。
+4. `swap-quote`（`tron-swap`）—— 对 100 TRX → USDT 请求实际报价，含预期到账数量与价格冲击。
+5. 智能体将报价的有效汇率与第 1 步现货价对比，结合第 3 步的资源成本，回答兑换是否划算。以上均为**只读**——若要真正执行，请路由到 `mcp-server-tronlink` 的 `tl_chain_swap_v3`（Remote Write、HITL，必传 `minOut`）或 [signer SDK](tronlink-signer.md)。
+
+**"我上一笔 USDT 转账到账了吗？现在余额多少？"**
+
+1. `tx-status`（`tron-swap`）—— 查询最近一笔转账的状态与确认数。
+2. `account-info`（`tron-wallet`）—— 确认该转账结算后的当前余额。
+3. `resource-info`（`tron-resource`）—— 核对剩余能量/带宽是否足够下一笔转账（否则将燃烧 TRX）。发送下一笔转账属于 Remote Write——请路由到 [signer SDK](tronlink-signer.md) 的 `sendTrc20` 或 `mcp-server-tronlink` 的 `tl_chain_send`。
+
 ---
 
 ## TRON 资源模型参考
@@ -404,7 +420,7 @@ bash uninstall.sh
 
 ---
 
-## 配置说明
+## 配置说明 { #configuration }
 
 ### 环境变量
 
@@ -416,6 +432,16 @@ export TRONGRID_API_KEY="your-api-key"
 export TRON_NETWORK="mainnet"    # 或 "shasta" / "nile"
 ```
 
+#### TronGrid API Key —— 凭证管理
+
+`TRONGRID_API_KEY` 是可选的（只读、提高限额），但一旦配置，请从以下五个维度管理：
+
+- **存储** —— 保存在环境变量或密钥管理器中。切勿硬编码在源码、提交到 git 的配置或聊天/智能体日志里。
+- **最小权限** —— 只签发覆盖这些技能所需只读端点的 Key，不要复用更大权限的生产 Key。
+- **轮换** —— 按固定周期轮换，有访问权限的成员离职时也应轮换；保持轮换窗口尽量短。
+- **泄漏检测** —— 监控 TronGrid 用量是否出现异常调用量或非预期来源 IP，并用密钥扫描器扫描仓库历史排查误提交。
+- **吊销** —— 一旦 Key 泄漏，立即在 TronGrid 控制台吊销并签发新 Key，再恢复流量。
+
 ### 网络支持
 
 | 网络 | 地址 | 用途 |
@@ -426,6 +452,8 @@ export TRON_NETWORK="mainnet"    # 或 "shasta" / "nile"
 
 ### 内置代币快捷符号
 
+> 下表为 `tron_api.mjs` 内置、可直接用符号名代替合约地址的代币。未列出的代币（如 USDD）请在 [reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot) 查询地址并显式传入。
+
 | 符号 | 合约地址 |
 |------|----------|
 | TRX | 原生代币（无合约） |
@@ -498,6 +526,18 @@ tronlink-skills/
 
 ---
 
+## 故障排查
+
+| 现象 | 原因 | 处理方式 |
+|------|------|----------|
+| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#the-6-skills) / [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 |
+| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#configuration)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 |
+| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill-mcp-tool-map)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs <command> ...`），不要走 `tools/call`。 |
+| `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 |
+| 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add <name>`），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 |
+
+---
+
 ## 地址格式支持
 
 所有命令均支持并自动归一化两种格式：
@@ -553,7 +593,7 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级
 
 - **稳定契约**（minor / patch 不会动）：
     - 33 个 CLI 命令名与其必填 / 可选 flag（`tron_api.mjs <command> [...]`）。
-    - [Skill ↔ MCP 工具映射](#skill--mcp-工具映射) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。
+    - [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。
     - Exit code：`0` 成功，`1` 查询错误 / 参数非法，`2` 未支持 / 未知命令。
     - `Network Read` 副作用分级——任何命令未经 major 升级都不会变成 Remote Write。
 - **不稳定契约**（minor 允许变化）：
diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt
index ec9e1d5..e9e8919 100644
--- a/docs/llms-full.en.txt
+++ b/docs/llms-full.en.txt
@@ -2,11 +2,11 @@
 
 > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index.
 
-- Generated: 2026-05-21T14:08:15Z
-- Commit: e724781c635f
+- Generated: 2026-06-04T07:06:28Z
+- Commit: a08525609c43
 - Language: en
 - Pages: 23
-- Token estimate: ~56,926 (chars / 4)
+- Token estimate: ~60,333 (chars / 4)
 ---
 
 <!-- source: docs/introduction.en.md | url: introduction/ -->
@@ -240,6 +240,7 @@ Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary,
 - For tool calls, branch on the structured `error.code` / `error.retryable`, never on the human-readable `message`.
 - Read operations are safe to retry; signing / Remote Write operations require user approval (HITL) and must not be auto-retried — see each tool's Safety section.
 - Default to testnets (`nile` / `shasta`) when experimenting; use `mainnet` only for real funds.
+- Version contracts: each tool page documents what is stable vs. volatile under its Compatibility & Migration section — consult it before pinning to any name, flag, or output field.
 
 ---
 
@@ -2084,7 +2085,7 @@ Modified hash:
 
 **Key Highlights:**
 - Dual-mode architecture: **Playwright** (browser automation) + **Direct API** (on-chain operations)
-- 32 built-in Flow Recipes with pre-checks and dependency resolution
+- 24 built-in Flow Recipes with pre-checks and dependency resolution
 - Non-custodial local transaction signing via encrypted `agent-wallet`
 - Multi-signature management with real-time WebSocket monitoring
 - Gas-free TRC20 transfers via GasFree service integration
@@ -2103,7 +2104,7 @@ flowchart TD
   Multi["TronLinkMultiSigCapability (5 tools)"]
   GasFree["TronLinkGasFreeCapability (3 tools)"]
   Util["Utility Capabilities<br/>Build · StateSnapshot · TRON Crypto"]
-  Flow["Flow Recipes<br/>(32 built-in, pre-checked)"]
+  Flow["Flow Recipes<br/>(24 built-in, pre-checked)"]
   Ext["TronGrid API / Multi-Sig Service / GasFree Service"]
   Chain["TRON Blockchain"]
   Agent -- "MCP Protocol — stdio / JSON-RPC 2.0" --> Server
@@ -2232,7 +2233,9 @@ Runtime wallet management via `@bankofai/agent-wallet` (encrypted `local_secure`
 - `tl_wallet_set_active` — Switch the active wallet by ID (hot-swaps into all capabilities)
 
 If no wallet exists at startup, the server prompts two paths: call `tl_wallet_create` to auto-generate one, or create one manually via CLI and set `AGENT_WALLET_PASSWORD`.
-The auto-create path generates a random password, saves it to `~/.agent-wallet/runtime_secrets.json`, creates an encrypted `main` wallet, and enables the running session to use it.
+
+!!! warning "Auto-create writes the password to disk in plaintext — test/dev only"
+    The auto-create path generates a random password and saves it **in plaintext** to `~/.agent-wallet/runtime_secrets.json`, then creates an encrypted `main` wallet and lets the running session use it. Anyone with read access to that file controls the wallet. For production, use the manual path: create the wallet out-of-band and inject `AGENT_WALLET_PASSWORD` from a secret manager — never rely on the on-disk plaintext password.
 
 ### 6. TRON Cryptography Utils
 
@@ -2250,49 +2253,49 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256).
 
 ---
 
-## Flow Recipes (32 Built-In)
+## Flow Recipes (24 Built-In)
 
 Pre-configured multi-step workflows with dependency checks and parameter templates.
 
 ### Playwright Flows
-| Flow | Description |
-|------|-------------|
-| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta |
-| `enableTestNetworksFlow` | Enable testnet visibility |
-| `transferTrxFlow` | TRX transfer via UI |
-| `transferTokenFlow` | Token transfer via UI |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | `src/flows/switch-network.ts` |
+| `enableTestNetworksFlow` | Enable testnet visibility | `src/flows/switch-network.ts` |
+| `transferTrxFlow` | TRX transfer via UI | `src/flows/transfer-trx.ts` |
+| `transferTokenFlow` | Token transfer via UI | `src/flows/transfer-trx.ts` |
 
 ### On-Chain Flows (11)
-| Flow | Description |
-|------|-------------|
-| `chainCheckBalanceFlow` | Query balance |
-| `chainTransferTrxFlow` | TRX transfer with pre-checks |
-| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks |
-| `chainStakeFlow` | Stake TRX |
-| `chainUnstakeFlow` | Unstake TRX |
-| `chainGetStakingFlow` | Query staking info |
-| `chainDelegateResourceFlow` | Delegate bandwidth/energy |
-| `chainUndelegateResourceFlow` | Undelegate resources |
-| `chainSetupMultisigFlow` | Setup multi-sig permissions |
-| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx |
-| `chainSwapV3Flow` | SunSwap V3 token swap |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `chainCheckBalanceFlow` | Query balance | `src/flows/onchain.ts` |
+| `chainTransferTrxFlow` | TRX transfer with pre-checks | `src/flows/onchain.ts` |
+| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | `src/flows/onchain.ts` |
+| `chainStakeFlow` | Stake TRX | `src/flows/onchain.ts` |
+| `chainUnstakeFlow` | Unstake TRX | `src/flows/onchain.ts` |
+| `chainGetStakingFlow` | Query staking info | `src/flows/onchain.ts` |
+| `chainDelegateResourceFlow` | Delegate bandwidth/energy | `src/flows/onchain.ts` |
+| `chainUndelegateResourceFlow` | Undelegate resources | `src/flows/onchain.ts` |
+| `chainSetupMultisigFlow` | Setup multi-sig permissions | `src/flows/onchain.ts` |
+| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | `src/flows/onchain.ts` |
+| `chainSwapV3Flow` | SunSwap V3 token swap | `src/flows/onchain.ts` |
 
 ### Multi-Sig Flows (6)
-| Flow | Description |
-|------|-------------|
-| `multisigQueryAuthFlow` | Query permissions |
-| `multisigListTransactionsFlow` | List pending transactions |
-| `multisigMonitorFlow` | WebSocket real-time monitoring |
-| `multisigStopMonitorFlow` | Stop monitoring |
-| `multisigSubmitTxFlow` | Submit signed transaction |
-| `multisigCheckFlow` | Full status check |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `multisigQueryAuthFlow` | Query permissions | `src/flows/multisig.ts` |
+| `multisigListTransactionsFlow` | List pending transactions | `src/flows/multisig.ts` |
+| `multisigMonitorFlow` | WebSocket real-time monitoring | `src/flows/multisig.ts` |
+| `multisigStopMonitorFlow` | Stop monitoring | `src/flows/multisig.ts` |
+| `multisigSubmitTxFlow` | Submit signed transaction | `src/flows/multisig.ts` |
+| `multisigCheckFlow` | Full status check | `src/flows/multisig.ts` |
 
 ### GasFree Flows (3)
-| Flow | Description |
-|------|-------------|
-| `gasfreeCheckAccountFlow` | Query eligibility |
-| `gasfreeTransactionHistoryFlow` | Query history |
-| `gasfreeSendFlow` | Gas-free TRC20 transfer |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `gasfreeCheckAccountFlow` | Query eligibility | `src/flows/gasfree.ts` |
+| `gasfreeTransactionHistoryFlow` | Query history | `src/flows/gasfree.ts` |
+| `gasfreeSendFlow` | Gas-free TRC20 transfer | `src/flows/gasfree.ts` |
 
 ---
 
@@ -2470,7 +2473,7 @@ mcp-server-tronlink/
 │   │   ├── state-snapshot.ts       # UI state extraction
 │   │   └── tron-crypto.ts          # Address derivation, signing, Base58
 │   └── flows/
-│       ├── index.ts                # Flow registry (32 recipes)
+│       ├── index.ts                # Flow registry (24 recipes)
 │       ├── switch-network.ts       # Network switching flows
 │       ├── transfer-trx.ts         # Transfer flows
 │       ├── multisig.ts             # 6 multi-sig flows
@@ -2496,9 +2499,11 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump
 | `@noble/hashes` | ^2.0.1 | Keccak-256, SHA256 |
 | `@tronlink/tronlink-mcp-core` | ^0.1.0 | Core MCP server framework |
 | `playwright` | ^1.49.0 | Browser automation |
-| `@bankofai/agent-wallet` | ^2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible |
+| `@bankofai/agent-wallet` | 2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible |
 | `ws` | ^8.18.0 | WebSocket (multi-sig monitoring) |
 
+> **About @bankofai/agent-wallet:** Pinned to exact 2.3.0 (no caret, to avoid silently picking up 2.4.0 on npm). The package's GitHub repo is currently not public (HTTP 404); source transparency comes from the npm publish — audit it via `npm pack @bankofai/agent-wallet@2.3.0`. Upgrading to 2.4.0 should be evaluated against its changelog first.
+
 ---
 
 ## Tool Contract & Side Effects
@@ -2522,7 +2527,7 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump
 
 These are **docs-side mirrors** of the most critical tool inputs — useful when an agent is writing a tool-call call site without an MCP session open. Runtime `list_tools` remains the authoritative source: the schemas there carry full Zod metadata (descriptions, `default`, etc.) plus `meta.schemaVersion`. Fields below are derived from `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts` and follow JSON Schema Draft 7. The full set of 52 tool schemas is **not** reproduced here — see core for the SSOT.
 
-> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI.
+> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI.
 
 #### `tl_chain_send` — **Remote Write**
 
@@ -2776,6 +2781,20 @@ The Direct-API path signs with a local encrypted wallet managed by `@bankofai/ag
 5. **Gas-Free Operations** — TRC20 transfers without TRX balance requirements
 6. **Infrastructure Testing** — Contract deployment, fixture management, mock servers
 
+### End-to-end example: swap 100 TRX for USDT on SunSwap V3
+
+A realistic agent turn, showing the tool-call sequence. The agent reads first, gets a fresh quote, surfaces it for human approval, then executes — never auto-executing a Remote Write off a read.
+
+> **User:** "Swap 100 TRX for USDT on SunSwap V3, max 0.5% slippage."
+
+1. `tl_chain_get_account` (Network Read) — confirm the active wallet holds ≥ 100 TRX plus enough for fees.
+2. `tl_chain_swap_v3` with `action=estimate` (Network Read) — `from_token="TRX"`, `to_token="<USDT contract>"`, `amount="100"`, `fee_tier=3000`, `slippage=0.5`. Returns the quoted output and route.
+3. Agent surfaces the quote to the user and waits for confirmation (HITL — this is a Remote Write).
+4. `tl_chain_swap_v3` with `action=execute` and the **same** explicit `slippage=0.5` — signs with the local `agent-wallet` and broadcasts. Returns `txId`.
+5. `tl_chain_get_tx` (Network Read) with the returned `txId` — confirm on-chain success before reporting back.
+
+> If step 4 returns an uncertain/failed result, do **not** auto-retry: `TL_CHAIN_SWAP_FAILED` is not retryable — re-check the chain with `tl_chain_get_tx` first (see Swap safety).
+
 ---
 
 ## Quick Start
@@ -2789,8 +2808,8 @@ npm install && npm run build
 #   TL_TRONGRID_URL=https://nile.trongrid.io
 #
 # 3. If no wallet exists, choose one path:
-#   Option A: call tl_wallet_create after startup
-#   Option B: create one locally, then set AGENT_WALLET_PASSWORD
+#   Option A (manual): create one locally, then set AGENT_WALLET_PASSWORD
+#   Option B (auto-create): call tl_wallet_create after startup
 
 # 4. Use with Claude Code
 # "Check my TRX balance"
@@ -2798,6 +2817,17 @@ npm install && npm run build
 # "Swap 100 TRX for USDT on SunSwap V3"
 ```
 
+**Which path? (scenario → path)**
+
+| Scenario | Recommended path | Why |
+|----------|------------------|-----|
+| Production (real funds) | A — manual + secret manager | Path B writes the password in plaintext to `~/.agent-wallet/runtime_secrets.json` |
+| CI / automation (testnet) | A — manual + env injection | Same — keep the password out of an on-disk file |
+| Local dev (one-off) | B — auto-create | No pre-config; the password is generated automatically |
+| Temp demo | B + tmpfs directory | Point `AGENT_WALLET_DIR` at a tmpfs path destroyed at job end |
+
+> Path B (auto-create) writes the generated password in plaintext to `~/.agent-wallet/runtime_secrets.json` so a restart can reuse the wallet. See [Wallet Secret Storage](#wallet-secret-storage) for the full Path A / Path B comparison and how to enforce Path A.
+
 ## Version & License
 
 - **Package:** `@tronlink/mcp-server-tronlink` v0.1.1
@@ -2886,6 +2916,18 @@ flowchart TD
 
 **mcp-server-tronlink is a consumer of tronlink-mcp-core.** The core defines WHAT tools exist; the server provides HOW they work.
 
+### Which one should I pick?
+
+Use this decision matrix to choose between the two packages by scenario:
+
+| Scenario | Pick tronlink-mcp-core | Pick mcp-server-tronlink |
+|----------|:---:|:---:|
+| Building a custom MCP server that embeds your own business logic | ✅ | |
+| Giving a ready-to-run server directly to an agent | | ✅ |
+| Extending capabilities with a custom `Capability` implementation | ✅ | |
+| Testing or mocking with injectable fixtures / mock server | ✅ | |
+| Learning how the MCP framework (interfaces, tools, response format) works | ✅ | |
+
 ---
 
 ## ISessionManager Interface
@@ -3750,6 +3792,22 @@ tron-wallet (check balance) → tron-staking (staking info) → tron-staking (AP
 tron-resource (check status) → tron-resource (estimate cost) → tron-resource (optimize-cost)
 ```
 
+### End-to-end examples
+
+**"Is swapping 100 TRX for USDT worth it right now?"**
+
+1. `token-price` (`tron-market`) — fetch current TRX and USDT prices to establish the reference value of 100 TRX.
+2. `kline` (`tron-market`) — pull recent candlesticks to judge whether TRX is trending up or down (timing).
+3. `resource-info` (`tron-resource`) — check the account's Energy/Bandwidth so the agent can estimate whether the swap will have to burn TRX for fees.
+4. `swap-quote` (`tron-swap`) — request an actual quote for 100 TRX → USDT, including expected output and price impact.
+5. The agent compares the quote's effective rate against the spot price from step 1, factors in the resource cost from step 3, and answers whether the swap is favorable. These steps are **read-only** — to actually execute, route to `mcp-server-tronlink` `tl_chain_swap_v3` (Remote Write, HITL, set `minOut`) or the [signer SDK](tronlink-signer.md).
+
+**"Did my last USDT transfer go through, and what's my balance now?"**
+
+1. `tx-status` (`tron-swap`) — look up the most recent transfer's status and confirmations.
+2. `account-info` (`tron-wallet`) — confirm the current balances after that transfer settled.
+3. `resource-info` (`tron-resource`) — verify enough Energy/Bandwidth remains for a follow-up transfer (otherwise it would burn TRX). Sending the next transfer is a Remote Write — route to the [signer SDK](tronlink-signer.md) `sendTrc20` or `mcp-server-tronlink` `tl_chain_send`.
+
 ---
 
 ## TRON Resource Model Reference
@@ -3902,6 +3960,16 @@ export TRONGRID_API_KEY="your-api-key"
 export TRON_NETWORK="mainnet"    # or "shasta" / "nile"
 ```
 
+#### TronGrid API key — credential management
+
+`TRONGRID_API_KEY` is optional (read-only, higher rate limits), but if you set one, manage it across these five dimensions:
+
+- **Storage** — keep it in an environment variable or a secrets manager. Never hardcode it in source, in config committed to git, or in chat/agent logs.
+- **Least-privilege** — provision a key scoped only to the read endpoints these skills call; don't reuse a broader production key.
+- **Rotation** — rotate on a fixed schedule, and whenever someone with access leaves; keep the rotation window short.
+- **Leak-detection** — monitor TronGrid usage for anomalous call volume or unexpected source IPs, and scan repository history with a secret scanner for accidental commits.
+- **Revocation** — if a key leaks, revoke it immediately in the TronGrid dashboard and issue a fresh one before resuming traffic.
+
 ### Network Support
 
 | Network | URL | Use Case |
@@ -3912,6 +3980,8 @@ export TRON_NETWORK="mainnet"    # or "shasta" / "nile"
 
 ### Built-In Token Shortcuts
 
+> The symbols below are the ones `tron_api.mjs` recognizes as shortcuts for their contract addresses. For any token not listed here (e.g. USDD), look up its address in [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot) and pass it explicitly.
+
 | Symbol | Contract Address |
 |--------|------------------|
 | TRX | Native (no contract) |
@@ -3984,6 +4054,18 @@ tronlink-skills/
 
 ---
 
+## Troubleshooting
+
+| Symptom | Cause | What to do |
+|---------|-------|------------|
+| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill-mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. |
+| TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). |
+| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill-mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs <command> ...`) instead of `tools/call`. |
+| `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. |
+| Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add <name>`), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. |
+
+---
+
 ## Address Format Support
 
 Both formats are supported and auto-normalized across all commands:
@@ -4039,7 +4121,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma
 
 - **Stable contracts** (won't change in a minor or patch):
     - The 33 CLI command names and their required / optional flags (`tron_api.mjs <command> [...]`).
-    - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill--mcp-tool-map) (`tron_*` form) and their `inputSchema` keys.
+    - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill-mcp-tool-map) (`tron_*` form) and their `inputSchema` keys.
     - Exit codes: `0` success, `1` query error / invalid input, `2` unsupported / unknown command.
     - The `Network Read` side-effect classification — no command will ever become a Remote Write without a major bump.
 - **Volatile contracts** (may change in a minor):
@@ -4060,6 +4142,22 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma
 
 MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet.
 
+> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version-license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK.
+
+## Which to use
+
+TronLink ships three ways to let an AI agent act on Tron. Pick based on whether a human must approve each transaction and where the agent runs.
+
+| | `mcp-tronlink-signer` (this server) | `mcp-server-tronlink` (Direct-API mode) | `tronlink-cli` |
+| --- | --- | --- | --- |
+| Approval | HITL — user approves every transaction in the browser | No HITL — signs automatically | HITL — user approves in the browser |
+| Credentials on host | None (keys stay in the TronLink extension) | Uses `AGENT_WALLET_PASSWORD` to unlock a local wallet | None (keys stay in the TronLink extension) |
+| Interface | MCP server | MCP server | Shell / command line |
+| Best for | Agents that should never move funds without explicit human sign-off | Automated, unattended flows: CI, testnet scripting | Interactive terminal use with human sign-off |
+| Private-key exposure | Lowest | Higher (credential on host) | Lowest |
+
+If unsure, prefer `mcp-tronlink-signer` (safest default).
+
 ## Setup
 
 ### Claude Code
@@ -4112,6 +4210,55 @@ All tools support an optional `network` parameter (`mainnet` / `nile` / `shasta`
 
 **Human-in-the-loop.** Every tool that signs (`send_trx`, `send_trc20`, `sign_message`, `sign_typed_data`, `sign_transaction`) opens the TronLink approval page in the browser. The AI agent **cannot** sign without the user clicking Approve. Treat Remote Write tools as requiring confirmation in production.
 
+### Selected tool schemas (inline mirror)
+
+Docs-side mirrors of the core write tools' inputs, derived from the tool parameters documented in the table above — useful when an agent is writing a tool-call site without an MCP session open. Field names and the required set are mirrored here; runtime `list_tools` remains the authoritative source for the full input schemas (exact field types, defaults, and any Zod metadata).
+
+`send_trx`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Amount of TRX to send" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["to", "amount"]
+}
+```
+
+`send_trc20`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" },
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Token amount to send" },
+    "decimals": { "description": "Optional token decimals" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["contractAddress", "to", "amount"]
+}
+```
+
+`sign_typed_data`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "typedData": { "description": "EIP-712 typed-data object to sign" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["typedData"]
+}
+```
+
+> Field types above are intentionally left unspecified where they could not be confirmed against the upstream Zod definitions; consult `list_tools` for the exact types. `sign_message` (`message`, `network?`) and `sign_transaction` (`transaction`, `broadcast`, `network?`) follow the same parameter shapes shown in the tool table.
+
 ## MCP Resources
 
 | URI | Description |
@@ -4228,6 +4375,8 @@ The server returns errors in the standard MCP shape. Each error carries a stable
 
 This page mirrors a downstream README; for the source of truth see the GitHub releases above and the `CHANGELOG.md` in each package. Entries below cover the **MCP-visible** surface (tools, schema, security boundaries) — internal refactors are omitted.
 
+> **Sync policy.** This inline changelog mirrors the package `CHANGELOG.md` / README; the project's **GitHub releases are the authoritative source**. This page may lag a release by a short window until the docs are updated, so verify against the GitHub releases (and `list_tools`) when an exact version matters.
+
 #### v0.1.4 _(npm-only, not GitHub-tagged at time of writing)_
 
 Patch-only. No new tools, no breaking input/output shapes. Verify against `list_tools` after upgrade.
@@ -5031,11 +5180,13 @@ tronlink reward --json
 
 ### Common Token Contracts
 
-| Token | Network | Contract                            |
-| ----- | ------- | ----------------------------------- |
-| USDT  | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
-| USDD  | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz |
-| USDC  | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 |
+> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The table below is a subset reconciled to that SSOT.
+
+| Token | Network | Contract                            | Decimals |
+| ----- | ------- | ----------------------------------- | -------- |
+| USDT  | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
+| USDC  | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 |
+| USDD  | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 |
 
 ### Example: AI Transfer Flow
 
@@ -5343,11 +5494,21 @@ TRON addresses have two interchangeable encodings:
 
 - `1 TRX = 1,000,000 SUN`. Amounts in `tronWeb` transaction builders (e.g. `sendTrx`) are expressed in **SUN**.
 
-## Common token contracts (Mainnet)
+## Common token contracts (SSOT)
 
-| Token | Standard | Contract address |
-|---|---|---|
-| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
+This is the single source of truth (SSOT) for common mainnet token contract addresses. Other pages — [TronLink CLI](../ai-support/tronlink-cli.md) and [TronLink Skills](../ai-support/tronlink-skills.md) — reconcile to this table; when an address changes, update it here first.
+
+| Token | Standard | Mainnet contract address | Decimals | Notes |
+|---|---|---|---|---|
+| TRX | native | — | 6 | Native coin, no TRC-20 contract |
+| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | |
+| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | |
+| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | |
+| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX |
+| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | |
+| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | |
+| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | |
+| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | |
 
 For any other token, look up its contract address on [TronScan](https://tronscan.org/#/tokens). Always verify a token's contract address before integrating — addresses differ per network.
 
diff --git a/docs/llms-full.txt b/docs/llms-full.txt
index ec9e1d5..e9e8919 100644
--- a/docs/llms-full.txt
+++ b/docs/llms-full.txt
@@ -2,11 +2,11 @@
 
 > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index.
 
-- Generated: 2026-05-21T14:08:15Z
-- Commit: e724781c635f
+- Generated: 2026-06-04T07:06:28Z
+- Commit: a08525609c43
 - Language: en
 - Pages: 23
-- Token estimate: ~56,926 (chars / 4)
+- Token estimate: ~60,333 (chars / 4)
 ---
 
 <!-- source: docs/introduction.en.md | url: introduction/ -->
@@ -240,6 +240,7 @@ Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary,
 - For tool calls, branch on the structured `error.code` / `error.retryable`, never on the human-readable `message`.
 - Read operations are safe to retry; signing / Remote Write operations require user approval (HITL) and must not be auto-retried — see each tool's Safety section.
 - Default to testnets (`nile` / `shasta`) when experimenting; use `mainnet` only for real funds.
+- Version contracts: each tool page documents what is stable vs. volatile under its Compatibility & Migration section — consult it before pinning to any name, flag, or output field.
 
 ---
 
@@ -2084,7 +2085,7 @@ Modified hash:
 
 **Key Highlights:**
 - Dual-mode architecture: **Playwright** (browser automation) + **Direct API** (on-chain operations)
-- 32 built-in Flow Recipes with pre-checks and dependency resolution
+- 24 built-in Flow Recipes with pre-checks and dependency resolution
 - Non-custodial local transaction signing via encrypted `agent-wallet`
 - Multi-signature management with real-time WebSocket monitoring
 - Gas-free TRC20 transfers via GasFree service integration
@@ -2103,7 +2104,7 @@ flowchart TD
   Multi["TronLinkMultiSigCapability (5 tools)"]
   GasFree["TronLinkGasFreeCapability (3 tools)"]
   Util["Utility Capabilities<br/>Build · StateSnapshot · TRON Crypto"]
-  Flow["Flow Recipes<br/>(32 built-in, pre-checked)"]
+  Flow["Flow Recipes<br/>(24 built-in, pre-checked)"]
   Ext["TronGrid API / Multi-Sig Service / GasFree Service"]
   Chain["TRON Blockchain"]
   Agent -- "MCP Protocol — stdio / JSON-RPC 2.0" --> Server
@@ -2232,7 +2233,9 @@ Runtime wallet management via `@bankofai/agent-wallet` (encrypted `local_secure`
 - `tl_wallet_set_active` — Switch the active wallet by ID (hot-swaps into all capabilities)
 
 If no wallet exists at startup, the server prompts two paths: call `tl_wallet_create` to auto-generate one, or create one manually via CLI and set `AGENT_WALLET_PASSWORD`.
-The auto-create path generates a random password, saves it to `~/.agent-wallet/runtime_secrets.json`, creates an encrypted `main` wallet, and enables the running session to use it.
+
+!!! warning "Auto-create writes the password to disk in plaintext — test/dev only"
+    The auto-create path generates a random password and saves it **in plaintext** to `~/.agent-wallet/runtime_secrets.json`, then creates an encrypted `main` wallet and lets the running session use it. Anyone with read access to that file controls the wallet. For production, use the manual path: create the wallet out-of-band and inject `AGENT_WALLET_PASSWORD` from a secret manager — never rely on the on-disk plaintext password.
 
 ### 6. TRON Cryptography Utils
 
@@ -2250,49 +2253,49 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256).
 
 ---
 
-## Flow Recipes (32 Built-In)
+## Flow Recipes (24 Built-In)
 
 Pre-configured multi-step workflows with dependency checks and parameter templates.
 
 ### Playwright Flows
-| Flow | Description |
-|------|-------------|
-| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta |
-| `enableTestNetworksFlow` | Enable testnet visibility |
-| `transferTrxFlow` | TRX transfer via UI |
-| `transferTokenFlow` | Token transfer via UI |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | `src/flows/switch-network.ts` |
+| `enableTestNetworksFlow` | Enable testnet visibility | `src/flows/switch-network.ts` |
+| `transferTrxFlow` | TRX transfer via UI | `src/flows/transfer-trx.ts` |
+| `transferTokenFlow` | Token transfer via UI | `src/flows/transfer-trx.ts` |
 
 ### On-Chain Flows (11)
-| Flow | Description |
-|------|-------------|
-| `chainCheckBalanceFlow` | Query balance |
-| `chainTransferTrxFlow` | TRX transfer with pre-checks |
-| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks |
-| `chainStakeFlow` | Stake TRX |
-| `chainUnstakeFlow` | Unstake TRX |
-| `chainGetStakingFlow` | Query staking info |
-| `chainDelegateResourceFlow` | Delegate bandwidth/energy |
-| `chainUndelegateResourceFlow` | Undelegate resources |
-| `chainSetupMultisigFlow` | Setup multi-sig permissions |
-| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx |
-| `chainSwapV3Flow` | SunSwap V3 token swap |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `chainCheckBalanceFlow` | Query balance | `src/flows/onchain.ts` |
+| `chainTransferTrxFlow` | TRX transfer with pre-checks | `src/flows/onchain.ts` |
+| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | `src/flows/onchain.ts` |
+| `chainStakeFlow` | Stake TRX | `src/flows/onchain.ts` |
+| `chainUnstakeFlow` | Unstake TRX | `src/flows/onchain.ts` |
+| `chainGetStakingFlow` | Query staking info | `src/flows/onchain.ts` |
+| `chainDelegateResourceFlow` | Delegate bandwidth/energy | `src/flows/onchain.ts` |
+| `chainUndelegateResourceFlow` | Undelegate resources | `src/flows/onchain.ts` |
+| `chainSetupMultisigFlow` | Setup multi-sig permissions | `src/flows/onchain.ts` |
+| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | `src/flows/onchain.ts` |
+| `chainSwapV3Flow` | SunSwap V3 token swap | `src/flows/onchain.ts` |
 
 ### Multi-Sig Flows (6)
-| Flow | Description |
-|------|-------------|
-| `multisigQueryAuthFlow` | Query permissions |
-| `multisigListTransactionsFlow` | List pending transactions |
-| `multisigMonitorFlow` | WebSocket real-time monitoring |
-| `multisigStopMonitorFlow` | Stop monitoring |
-| `multisigSubmitTxFlow` | Submit signed transaction |
-| `multisigCheckFlow` | Full status check |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `multisigQueryAuthFlow` | Query permissions | `src/flows/multisig.ts` |
+| `multisigListTransactionsFlow` | List pending transactions | `src/flows/multisig.ts` |
+| `multisigMonitorFlow` | WebSocket real-time monitoring | `src/flows/multisig.ts` |
+| `multisigStopMonitorFlow` | Stop monitoring | `src/flows/multisig.ts` |
+| `multisigSubmitTxFlow` | Submit signed transaction | `src/flows/multisig.ts` |
+| `multisigCheckFlow` | Full status check | `src/flows/multisig.ts` |
 
 ### GasFree Flows (3)
-| Flow | Description |
-|------|-------------|
-| `gasfreeCheckAccountFlow` | Query eligibility |
-| `gasfreeTransactionHistoryFlow` | Query history |
-| `gasfreeSendFlow` | Gas-free TRC20 transfer |
+| Flow | Description | Source File |
+|------|-------------|-------------|
+| `gasfreeCheckAccountFlow` | Query eligibility | `src/flows/gasfree.ts` |
+| `gasfreeTransactionHistoryFlow` | Query history | `src/flows/gasfree.ts` |
+| `gasfreeSendFlow` | Gas-free TRC20 transfer | `src/flows/gasfree.ts` |
 
 ---
 
@@ -2470,7 +2473,7 @@ mcp-server-tronlink/
 │   │   ├── state-snapshot.ts       # UI state extraction
 │   │   └── tron-crypto.ts          # Address derivation, signing, Base58
 │   └── flows/
-│       ├── index.ts                # Flow registry (32 recipes)
+│       ├── index.ts                # Flow registry (24 recipes)
 │       ├── switch-network.ts       # Network switching flows
 │       ├── transfer-trx.ts         # Transfer flows
 │       ├── multisig.ts             # 6 multi-sig flows
@@ -2496,9 +2499,11 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump
 | `@noble/hashes` | ^2.0.1 | Keccak-256, SHA256 |
 | `@tronlink/tronlink-mcp-core` | ^0.1.0 | Core MCP server framework |
 | `playwright` | ^1.49.0 | Browser automation |
-| `@bankofai/agent-wallet` | ^2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible |
+| `@bankofai/agent-wallet` | 2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible |
 | `ws` | ^8.18.0 | WebSocket (multi-sig monitoring) |
 
+> **About @bankofai/agent-wallet:** Pinned to exact 2.3.0 (no caret, to avoid silently picking up 2.4.0 on npm). The package's GitHub repo is currently not public (HTTP 404); source transparency comes from the npm publish — audit it via `npm pack @bankofai/agent-wallet@2.3.0`. Upgrading to 2.4.0 should be evaluated against its changelog first.
+
 ---
 
 ## Tool Contract & Side Effects
@@ -2522,7 +2527,7 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump
 
 These are **docs-side mirrors** of the most critical tool inputs — useful when an agent is writing a tool-call call site without an MCP session open. Runtime `list_tools` remains the authoritative source: the schemas there carry full Zod metadata (descriptions, `default`, etc.) plus `meta.schemaVersion`. Fields below are derived from `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts` and follow JSON Schema Draft 7. The full set of 52 tool schemas is **not** reproduced here — see core for the SSOT.
 
-> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI.
+> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI.
 
 #### `tl_chain_send` — **Remote Write**
 
@@ -2776,6 +2781,20 @@ The Direct-API path signs with a local encrypted wallet managed by `@bankofai/ag
 5. **Gas-Free Operations** — TRC20 transfers without TRX balance requirements
 6. **Infrastructure Testing** — Contract deployment, fixture management, mock servers
 
+### End-to-end example: swap 100 TRX for USDT on SunSwap V3
+
+A realistic agent turn, showing the tool-call sequence. The agent reads first, gets a fresh quote, surfaces it for human approval, then executes — never auto-executing a Remote Write off a read.
+
+> **User:** "Swap 100 TRX for USDT on SunSwap V3, max 0.5% slippage."
+
+1. `tl_chain_get_account` (Network Read) — confirm the active wallet holds ≥ 100 TRX plus enough for fees.
+2. `tl_chain_swap_v3` with `action=estimate` (Network Read) — `from_token="TRX"`, `to_token="<USDT contract>"`, `amount="100"`, `fee_tier=3000`, `slippage=0.5`. Returns the quoted output and route.
+3. Agent surfaces the quote to the user and waits for confirmation (HITL — this is a Remote Write).
+4. `tl_chain_swap_v3` with `action=execute` and the **same** explicit `slippage=0.5` — signs with the local `agent-wallet` and broadcasts. Returns `txId`.
+5. `tl_chain_get_tx` (Network Read) with the returned `txId` — confirm on-chain success before reporting back.
+
+> If step 4 returns an uncertain/failed result, do **not** auto-retry: `TL_CHAIN_SWAP_FAILED` is not retryable — re-check the chain with `tl_chain_get_tx` first (see Swap safety).
+
 ---
 
 ## Quick Start
@@ -2789,8 +2808,8 @@ npm install && npm run build
 #   TL_TRONGRID_URL=https://nile.trongrid.io
 #
 # 3. If no wallet exists, choose one path:
-#   Option A: call tl_wallet_create after startup
-#   Option B: create one locally, then set AGENT_WALLET_PASSWORD
+#   Option A (manual): create one locally, then set AGENT_WALLET_PASSWORD
+#   Option B (auto-create): call tl_wallet_create after startup
 
 # 4. Use with Claude Code
 # "Check my TRX balance"
@@ -2798,6 +2817,17 @@ npm install && npm run build
 # "Swap 100 TRX for USDT on SunSwap V3"
 ```
 
+**Which path? (scenario → path)**
+
+| Scenario | Recommended path | Why |
+|----------|------------------|-----|
+| Production (real funds) | A — manual + secret manager | Path B writes the password in plaintext to `~/.agent-wallet/runtime_secrets.json` |
+| CI / automation (testnet) | A — manual + env injection | Same — keep the password out of an on-disk file |
+| Local dev (one-off) | B — auto-create | No pre-config; the password is generated automatically |
+| Temp demo | B + tmpfs directory | Point `AGENT_WALLET_DIR` at a tmpfs path destroyed at job end |
+
+> Path B (auto-create) writes the generated password in plaintext to `~/.agent-wallet/runtime_secrets.json` so a restart can reuse the wallet. See [Wallet Secret Storage](#wallet-secret-storage) for the full Path A / Path B comparison and how to enforce Path A.
+
 ## Version & License
 
 - **Package:** `@tronlink/mcp-server-tronlink` v0.1.1
@@ -2886,6 +2916,18 @@ flowchart TD
 
 **mcp-server-tronlink is a consumer of tronlink-mcp-core.** The core defines WHAT tools exist; the server provides HOW they work.
 
+### Which one should I pick?
+
+Use this decision matrix to choose between the two packages by scenario:
+
+| Scenario | Pick tronlink-mcp-core | Pick mcp-server-tronlink |
+|----------|:---:|:---:|
+| Building a custom MCP server that embeds your own business logic | ✅ | |
+| Giving a ready-to-run server directly to an agent | | ✅ |
+| Extending capabilities with a custom `Capability` implementation | ✅ | |
+| Testing or mocking with injectable fixtures / mock server | ✅ | |
+| Learning how the MCP framework (interfaces, tools, response format) works | ✅ | |
+
 ---
 
 ## ISessionManager Interface
@@ -3750,6 +3792,22 @@ tron-wallet (check balance) → tron-staking (staking info) → tron-staking (AP
 tron-resource (check status) → tron-resource (estimate cost) → tron-resource (optimize-cost)
 ```
 
+### End-to-end examples
+
+**"Is swapping 100 TRX for USDT worth it right now?"**
+
+1. `token-price` (`tron-market`) — fetch current TRX and USDT prices to establish the reference value of 100 TRX.
+2. `kline` (`tron-market`) — pull recent candlesticks to judge whether TRX is trending up or down (timing).
+3. `resource-info` (`tron-resource`) — check the account's Energy/Bandwidth so the agent can estimate whether the swap will have to burn TRX for fees.
+4. `swap-quote` (`tron-swap`) — request an actual quote for 100 TRX → USDT, including expected output and price impact.
+5. The agent compares the quote's effective rate against the spot price from step 1, factors in the resource cost from step 3, and answers whether the swap is favorable. These steps are **read-only** — to actually execute, route to `mcp-server-tronlink` `tl_chain_swap_v3` (Remote Write, HITL, set `minOut`) or the [signer SDK](tronlink-signer.md).
+
+**"Did my last USDT transfer go through, and what's my balance now?"**
+
+1. `tx-status` (`tron-swap`) — look up the most recent transfer's status and confirmations.
+2. `account-info` (`tron-wallet`) — confirm the current balances after that transfer settled.
+3. `resource-info` (`tron-resource`) — verify enough Energy/Bandwidth remains for a follow-up transfer (otherwise it would burn TRX). Sending the next transfer is a Remote Write — route to the [signer SDK](tronlink-signer.md) `sendTrc20` or `mcp-server-tronlink` `tl_chain_send`.
+
 ---
 
 ## TRON Resource Model Reference
@@ -3902,6 +3960,16 @@ export TRONGRID_API_KEY="your-api-key"
 export TRON_NETWORK="mainnet"    # or "shasta" / "nile"
 ```
 
+#### TronGrid API key — credential management
+
+`TRONGRID_API_KEY` is optional (read-only, higher rate limits), but if you set one, manage it across these five dimensions:
+
+- **Storage** — keep it in an environment variable or a secrets manager. Never hardcode it in source, in config committed to git, or in chat/agent logs.
+- **Least-privilege** — provision a key scoped only to the read endpoints these skills call; don't reuse a broader production key.
+- **Rotation** — rotate on a fixed schedule, and whenever someone with access leaves; keep the rotation window short.
+- **Leak-detection** — monitor TronGrid usage for anomalous call volume or unexpected source IPs, and scan repository history with a secret scanner for accidental commits.
+- **Revocation** — if a key leaks, revoke it immediately in the TronGrid dashboard and issue a fresh one before resuming traffic.
+
 ### Network Support
 
 | Network | URL | Use Case |
@@ -3912,6 +3980,8 @@ export TRON_NETWORK="mainnet"    # or "shasta" / "nile"
 
 ### Built-In Token Shortcuts
 
+> The symbols below are the ones `tron_api.mjs` recognizes as shortcuts for their contract addresses. For any token not listed here (e.g. USDD), look up its address in [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot) and pass it explicitly.
+
 | Symbol | Contract Address |
 |--------|------------------|
 | TRX | Native (no contract) |
@@ -3984,6 +4054,18 @@ tronlink-skills/
 
 ---
 
+## Troubleshooting
+
+| Symptom | Cause | What to do |
+|---------|-------|------------|
+| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill-mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. |
+| TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). |
+| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill-mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs <command> ...`) instead of `tools/call`. |
+| `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. |
+| Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add <name>`), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. |
+
+---
+
 ## Address Format Support
 
 Both formats are supported and auto-normalized across all commands:
@@ -4039,7 +4121,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma
 
 - **Stable contracts** (won't change in a minor or patch):
     - The 33 CLI command names and their required / optional flags (`tron_api.mjs <command> [...]`).
-    - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill--mcp-tool-map) (`tron_*` form) and their `inputSchema` keys.
+    - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill-mcp-tool-map) (`tron_*` form) and their `inputSchema` keys.
     - Exit codes: `0` success, `1` query error / invalid input, `2` unsupported / unknown command.
     - The `Network Read` side-effect classification — no command will ever become a Remote Write without a major bump.
 - **Volatile contracts** (may change in a minor):
@@ -4060,6 +4142,22 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma
 
 MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet.
 
+> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version-license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK.
+
+## Which to use
+
+TronLink ships three ways to let an AI agent act on Tron. Pick based on whether a human must approve each transaction and where the agent runs.
+
+| | `mcp-tronlink-signer` (this server) | `mcp-server-tronlink` (Direct-API mode) | `tronlink-cli` |
+| --- | --- | --- | --- |
+| Approval | HITL — user approves every transaction in the browser | No HITL — signs automatically | HITL — user approves in the browser |
+| Credentials on host | None (keys stay in the TronLink extension) | Uses `AGENT_WALLET_PASSWORD` to unlock a local wallet | None (keys stay in the TronLink extension) |
+| Interface | MCP server | MCP server | Shell / command line |
+| Best for | Agents that should never move funds without explicit human sign-off | Automated, unattended flows: CI, testnet scripting | Interactive terminal use with human sign-off |
+| Private-key exposure | Lowest | Higher (credential on host) | Lowest |
+
+If unsure, prefer `mcp-tronlink-signer` (safest default).
+
 ## Setup
 
 ### Claude Code
@@ -4112,6 +4210,55 @@ All tools support an optional `network` parameter (`mainnet` / `nile` / `shasta`
 
 **Human-in-the-loop.** Every tool that signs (`send_trx`, `send_trc20`, `sign_message`, `sign_typed_data`, `sign_transaction`) opens the TronLink approval page in the browser. The AI agent **cannot** sign without the user clicking Approve. Treat Remote Write tools as requiring confirmation in production.
 
+### Selected tool schemas (inline mirror)
+
+Docs-side mirrors of the core write tools' inputs, derived from the tool parameters documented in the table above — useful when an agent is writing a tool-call site without an MCP session open. Field names and the required set are mirrored here; runtime `list_tools` remains the authoritative source for the full input schemas (exact field types, defaults, and any Zod metadata).
+
+`send_trx`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Amount of TRX to send" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["to", "amount"]
+}
+```
+
+`send_trc20`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" },
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Token amount to send" },
+    "decimals": { "description": "Optional token decimals" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["contractAddress", "to", "amount"]
+}
+```
+
+`sign_typed_data`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "typedData": { "description": "EIP-712 typed-data object to sign" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["typedData"]
+}
+```
+
+> Field types above are intentionally left unspecified where they could not be confirmed against the upstream Zod definitions; consult `list_tools` for the exact types. `sign_message` (`message`, `network?`) and `sign_transaction` (`transaction`, `broadcast`, `network?`) follow the same parameter shapes shown in the tool table.
+
 ## MCP Resources
 
 | URI | Description |
@@ -4228,6 +4375,8 @@ The server returns errors in the standard MCP shape. Each error carries a stable
 
 This page mirrors a downstream README; for the source of truth see the GitHub releases above and the `CHANGELOG.md` in each package. Entries below cover the **MCP-visible** surface (tools, schema, security boundaries) — internal refactors are omitted.
 
+> **Sync policy.** This inline changelog mirrors the package `CHANGELOG.md` / README; the project's **GitHub releases are the authoritative source**. This page may lag a release by a short window until the docs are updated, so verify against the GitHub releases (and `list_tools`) when an exact version matters.
+
 #### v0.1.4 _(npm-only, not GitHub-tagged at time of writing)_
 
 Patch-only. No new tools, no breaking input/output shapes. Verify against `list_tools` after upgrade.
@@ -5031,11 +5180,13 @@ tronlink reward --json
 
 ### Common Token Contracts
 
-| Token | Network | Contract                            |
-| ----- | ------- | ----------------------------------- |
-| USDT  | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
-| USDD  | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz |
-| USDC  | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 |
+> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The table below is a subset reconciled to that SSOT.
+
+| Token | Network | Contract                            | Decimals |
+| ----- | ------- | ----------------------------------- | -------- |
+| USDT  | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
+| USDC  | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 |
+| USDD  | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 |
 
 ### Example: AI Transfer Flow
 
@@ -5343,11 +5494,21 @@ TRON addresses have two interchangeable encodings:
 
 - `1 TRX = 1,000,000 SUN`. Amounts in `tronWeb` transaction builders (e.g. `sendTrx`) are expressed in **SUN**.
 
-## Common token contracts (Mainnet)
+## Common token contracts (SSOT)
 
-| Token | Standard | Contract address |
-|---|---|---|
-| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
+This is the single source of truth (SSOT) for common mainnet token contract addresses. Other pages — [TronLink CLI](../ai-support/tronlink-cli.md) and [TronLink Skills](../ai-support/tronlink-skills.md) — reconcile to this table; when an address changes, update it here first.
+
+| Token | Standard | Mainnet contract address | Decimals | Notes |
+|---|---|---|---|---|
+| TRX | native | — | 6 | Native coin, no TRC-20 contract |
+| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | |
+| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | |
+| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | |
+| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX |
+| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | |
+| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | |
+| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | |
+| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | |
 
 For any other token, look up its contract address on [TronScan](https://tronscan.org/#/tokens). Always verify a token's contract address before integrating — addresses differ per network.
 
diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt
index 6c0e0dc..11d0a36 100644
--- a/docs/llms-full.zh.txt
+++ b/docs/llms-full.zh.txt
@@ -2,11 +2,11 @@
 
 > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。
 
-- Generated: 2026-05-21T14:08:15Z
-- Commit: e724781c635f
+- Generated: 2026-06-04T07:06:28Z
+- Commit: a08525609c43
 - Language: zh
 - Pages: 23
-- Token estimate: ~39,427 (chars / 4)
+- Token estimate: ~41,582 (chars / 4)
 ---
 
 <!-- source: docs/introduction.zh.md | url: introduction/ -->
@@ -238,6 +238,7 @@ TronLink 的开发者文档以机器可读形式发布，便于 AI 智能体和
 - 工具调用请基于结构化的 `error.code` / `error.retryable` 分支,**不要**解析人类可读的 `message`。
 - 读操作可安全重试;签名 / 远程写操作需要用户审批（HITL）,且不得自动重试——见各工具的「安全」一节。
 - 实验时默认用测试网（`nile` / `shasta`）;只有动用真实资金时才用 `mainnet`。
+- 版本契约：每个工具页在「兼容性与迁移策略」一节列明了哪些是稳定契约、哪些会变动——在依赖任何名称、flag 或输出字段前请先查阅该节。
 
 ---
 
@@ -715,7 +716,7 @@ img {
 
 ### 回调 `code` 枚举
 
-完整取值见上方[回传消息码](#回传消息码)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。
+完整取值见上方[回传消息码](#result-code)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。
 
 ---
 
@@ -1291,7 +1292,7 @@ interface SwitchTronChainParameter {
 
 ### TIP-6963（provider 发现）
 
-事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#trontip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`：
+事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#get-tronlink-provider-via-tip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`：
 
 - `TIP6963:requestProvider` —— 由 DApp 派发，无 payload。
 - `TIP6963:announceProvider` —— 由已安装的每个钱包派发，`detail = { info: { uuid, name, icon, rdns }, provider }`。TronLink 的 `rdns = "org.tronlink.www"`、`name = "TronLink"`。
@@ -2006,7 +2007,7 @@ ledger返回的实际签名hash：
 
 **核心亮点：**
 - 双模架构：**Playwright**（浏览器自动化）+ **Direct API**（链上操作）
-- 32 个内置 Flow Recipe，带预检查和依赖解析
+- 24 个内置 Flow Recipe，带预检查和依赖解析
 - 基于加密 `agent-wallet` 的非托管本地交易签名
 - 多签管理，支持实时 WebSocket 监控
 - 通过 GasFree 服务集成实现零 Gas TRC20 转账
@@ -2025,7 +2026,7 @@ flowchart TD
   Multi["TronLinkMultiSigCapability (5 个工具)"]
   GasFree["TronLinkGasFreeCapability (3 个工具)"]
   Util["实用能力<br/>Build · StateSnapshot · TRON Crypto"]
-  Flow["Flow Recipes<br/>(32 个内置流程配方)"]
+  Flow["Flow Recipes<br/>(24 个内置流程配方)"]
   Ext["TronGrid API / 多签服务 / GasFree 服务"]
   Chain["TRON 区块链"]
   Agent -- "MCP 协议 — stdio / JSON-RPC 2.0" --> Server
@@ -2154,7 +2155,9 @@ TRON 多签服务的 REST + WebSocket API：
 - `tl_wallet_set_active` — 按 ID 切换活跃钱包（热切换到所有能力）
 
 如果启动时没有钱包，服务器会提示两条路径：调用 `tl_wallet_create` 自动生成，或通过 CLI 手动创建后设置 `AGENT_WALLET_PASSWORD`。
-自动创建这条路径会生成随机密码，把密码保存到 `~/.agent-wallet/runtime_secrets.json`，创建一个加密的 `main` 钱包，并让当前会话立即可用。
+
+!!! warning "自动创建会把密码以明文写入磁盘——仅限测试/开发"
+    自动创建这条路径会生成随机密码，并把它**以明文**保存到 `~/.agent-wallet/runtime_secrets.json`，随后创建一个加密的 `main` 钱包并让当前会话立即可用。任何能读取该文件的人都能控制钱包。生产环境请使用手动路径：在外部创建钱包，并通过密钥管理器注入 `AGENT_WALLET_PASSWORD`——不要依赖落盘的明文密码。
 
 ### 6. TRON 密码学工具
 
@@ -2172,49 +2175,49 @@ hexToAddress()             0x41... → T 地址
 
 ---
 
-## Flow Recipes（32 个内置流程）
+## Flow Recipes（24 个内置流程）
 
 预配置的多步骤工作流，带依赖检查和参数模板。
 
 ### Playwright 流程
-| 流程 | 说明 |
-|------|------|
-| `switchNetworkFlow` | 切换到主网/Nile/Shasta |
-| `enableTestNetworksFlow` | 启用测试网可见性 |
-| `transferTrxFlow` | 通过 UI 进行 TRX 转账 |
-| `transferTokenFlow` | 通过 UI 进行代币转账 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `switchNetworkFlow` | 切换到主网/Nile/Shasta | `src/flows/switch-network.ts` |
+| `enableTestNetworksFlow` | 启用测试网可见性 | `src/flows/switch-network.ts` |
+| `transferTrxFlow` | 通过 UI 进行 TRX 转账 | `src/flows/transfer-trx.ts` |
+| `transferTokenFlow` | 通过 UI 进行代币转账 | `src/flows/transfer-trx.ts` |
 
 ### 链上流程（11 个）
-| 流程 | 说明 |
-|------|------|
-| `chainCheckBalanceFlow` | 查询余额 |
-| `chainTransferTrxFlow` | 带预检查的 TRX 转账 |
-| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 |
-| `chainStakeFlow` | 质押 TRX |
-| `chainUnstakeFlow` | 解除质押 TRX |
-| `chainGetStakingFlow` | 查询质押信息 |
-| `chainDelegateResourceFlow` | 代理带宽/能量 |
-| `chainUndelegateResourceFlow` | 取消代理资源 |
-| `chainSetupMultisigFlow` | 设置多签权限 |
-| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 |
-| `chainSwapV3Flow` | SunSwap V3 代币兑换 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `chainCheckBalanceFlow` | 查询余额 | `src/flows/onchain.ts` |
+| `chainTransferTrxFlow` | 带预检查的 TRX 转账 | `src/flows/onchain.ts` |
+| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 | `src/flows/onchain.ts` |
+| `chainStakeFlow` | 质押 TRX | `src/flows/onchain.ts` |
+| `chainUnstakeFlow` | 解除质押 TRX | `src/flows/onchain.ts` |
+| `chainGetStakingFlow` | 查询质押信息 | `src/flows/onchain.ts` |
+| `chainDelegateResourceFlow` | 代理带宽/能量 | `src/flows/onchain.ts` |
+| `chainUndelegateResourceFlow` | 取消代理资源 | `src/flows/onchain.ts` |
+| `chainSetupMultisigFlow` | 设置多签权限 | `src/flows/onchain.ts` |
+| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 | `src/flows/onchain.ts` |
+| `chainSwapV3Flow` | SunSwap V3 代币兑换 | `src/flows/onchain.ts` |
 
 ### 多签流程（6 个）
-| 流程 | 说明 |
-|------|------|
-| `multisigQueryAuthFlow` | 查询权限 |
-| `multisigListTransactionsFlow` | 列出待处理交易 |
-| `multisigMonitorFlow` | WebSocket 实时监控 |
-| `multisigStopMonitorFlow` | 停止监控 |
-| `multisigSubmitTxFlow` | 提交签名交易 |
-| `multisigCheckFlow` | 完整状态检查 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `multisigQueryAuthFlow` | 查询权限 | `src/flows/multisig.ts` |
+| `multisigListTransactionsFlow` | 列出待处理交易 | `src/flows/multisig.ts` |
+| `multisigMonitorFlow` | WebSocket 实时监控 | `src/flows/multisig.ts` |
+| `multisigStopMonitorFlow` | 停止监控 | `src/flows/multisig.ts` |
+| `multisigSubmitTxFlow` | 提交签名交易 | `src/flows/multisig.ts` |
+| `multisigCheckFlow` | 完整状态检查 | `src/flows/multisig.ts` |
 
 ### GasFree 流程（3 个）
-| 流程 | 说明 |
-|------|------|
-| `gasfreeCheckAccountFlow` | 查询资格 |
-| `gasfreeTransactionHistoryFlow` | 查询历史 |
-| `gasfreeSendFlow` | 免 Gas TRC20 转账 |
+| 流程 | 说明 | 源文件 |
+|------|------|--------|
+| `gasfreeCheckAccountFlow` | 查询资格 | `src/flows/gasfree.ts` |
+| `gasfreeTransactionHistoryFlow` | 查询历史 | `src/flows/gasfree.ts` |
+| `gasfreeSendFlow` | 免 Gas TRC20 转账 | `src/flows/gasfree.ts` |
 
 ---
 
@@ -2384,7 +2387,7 @@ mcp-server-tronlink/
 │   │   ├── state-snapshot.ts       # UI 状态提取
 │   │   └── tron-crypto.ts          # 地址派生、签名、Base58
 │   └── flows/
-│       ├── index.ts                # 流程注册（32 个配方）
+│       ├── index.ts                # 流程注册（24 个配方）
 │       ├── switch-network.ts       # 网络切换流程
 │       ├── transfer-trx.ts         # 转账流程
 │       ├── multisig.ts             # 6 个多签流程
@@ -2410,14 +2413,16 @@ mcp-server-tronlink/
 | `@noble/hashes` | ^2.0.1 | Keccak-256、SHA256 |
 | `@tronlink/tronlink-mcp-core` | ^0.1.0 | 核心 MCP 服务框架 |
 | `playwright` | ^1.49.0 | 浏览器自动化 |
-| `@bankofai/agent-wallet` | ^2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 |
+| `@bankofai/agent-wallet` | 2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 |
 | `ws` | ^8.18.0 | WebSocket（多签监控） |
 
+> **关于 @bankofai/agent-wallet：** 版本精确钉死在 2.3.0（不用 caret，避免静默升到 npm 上的 2.4.0）。该包的 GitHub 仓库当前未公开（HTTP 404），源码透明性由 npm publish 提供——可用 `npm pack @bankofai/agent-wallet@2.3.0` 解包审计。是否升级到 2.4.0 需另行评估其 changelog 后决定。
+
 ---
 
 ## 工具契约与副作用
 
-**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。
+**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。
 
 **逐工具输入 schema 可在运行时发现。** 每个工具的参数都由 core 用 Zod 校验,并通过 MCP `list_tools` 方法以 JSON `inputSchema` 形式暴露,因此客户端无需阅读本页即可枚举参数名、类型和必填项。下方表格按能力归纳工具;`list_tools` 才是权威的机器可读来源。
 
@@ -2436,7 +2441,7 @@ mcp-server-tronlink/
 
 以下是最关键工具输入的**文档侧镜像**——当 agent 需要在没有打开 MCP 会话的情况下写工具调用站点时使用。运行时 `list_tools` 仍是权威源：那里有完整的 Zod 元信息（描述、`default` 等）以及 `meta.schemaVersion`。下方字段抄自 `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts`，遵循 JSON Schema Draft 7。**未**镜像全部 52 个工具——以 core 仓库为 SSOT。
 
-> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。
+> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。
 
 #### `tl_chain_send` —— **Remote Write**
 
@@ -2689,6 +2694,20 @@ Direct-API 路径使用 `@bankofai/agent-wallet` 管理的本地加密钱包签
 5. **免 Gas 操作** — 无需 TRX 余额即可完成 TRC20 转账
 6. **基础设施测试** — 合约部署、固件管理、Mock 服务
 
+### 端到端示例：在 SunSwap V3 上用 100 TRX 兑换 USDT
+
+一个真实的 agent 回合，展示工具调用顺序。agent 先读取、再现取报价、交人工确认后才执行——绝不基于 read 结果自动触发「远程写」。
+
+> **用户：** "在 SunSwap V3 上用 100 TRX 兑换 USDT，滑点上限 0.5%。"
+
+1. `tl_chain_get_account`（Network Read）—— 确认当前钱包持有 ≥ 100 TRX 且留有手续费余量。
+2. `tl_chain_swap_v3`，`action=estimate`（Network Read）—— `from_token="TRX"`、`to_token="<USDT 合约>"`、`amount="100"`、`fee_tier=3000`、`slippage=0.5`。返回报价输出与路径。
+3. agent 把报价呈现给用户并等待确认（HITL——这是一笔远程写）。
+4. `tl_chain_swap_v3`，`action=execute`，并传入**相同的**显式 `slippage=0.5`——用本地 `agent-wallet` 签名并广播。返回 `txId`。
+5. `tl_chain_get_tx`（Network Read），传入返回的 `txId`——在回报前先确认链上成功。
+
+> 若第 4 步返回结果未知 / 失败，**不要**自动重试：`TL_CHAIN_SWAP_FAILED` 不可重试——先用 `tl_chain_get_tx` 核对链上状态（见「兑换安全」）。
+
 ---
 
 ## 快速开始
@@ -2701,10 +2720,10 @@ npm install && npm run build
 export TL_TRONGRID_URL="https://nile.trongrid.io"
 
 # 3. 如果本地还没有钱包，二选一：
-# 方案 A：在 MCP 会话里调用 tl_wallet_create
-# 方案 B：本地执行
-# agent-wallet start local_secure --generate --wallet-id main
-# 然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD
+# 路径 A（手动）：本地执行
+#   agent-wallet start local_secure --generate --wallet-id main
+#   然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD
+# 路径 B（自动创建）：在 MCP 会话里调用 tl_wallet_create
 
 # 4. 配合 Claude Code 使用
 # 配置好 .mcp.json 后自然语言使用：
@@ -2713,6 +2732,17 @@ export TL_TRONGRID_URL="https://nile.trongrid.io"
 # "在 SunSwap V3 上用 100 TRX 兑换 USDT"
 ```
 
+**该选哪条路径？（场景 → 路径）**
+
+| 场景 | 推荐路径 | 原因 |
+|------|---------|------|
+| 生产环境（真实资金） | A — 手动创建 + secret manager | 路径 B 会把密码以明文写入 `~/.agent-wallet/runtime_secrets.json` |
+| CI / 自动化（测试网） | A — 手动创建 + env 注入 | 同上——避免密码落盘到文件 |
+| 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 |
+| 临时 demo 演示 | B + tmpfs 目录 | 把 `AGENT_WALLET_DIR` 指到任务结束即销毁的 tmpfs |
+
+> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#wallet-secret-storage)。
+
 ## 版本与许可证
 
 - **包：** `@tronlink/mcp-server-tronlink` v0.1.1
@@ -2724,7 +2754,7 @@ export TL_TRONGRID_URL="https://nile.trongrid.io"
 - **语义化版本。** 1.0 之前：**minor** 升级（0.x → 0.y）允许破坏性变更；**patch** 升级（0.1.x → 0.1.y）不变更工具名、输入 schema、`error.code` 值或 `meta.schemaVersion` 语义。1.0 之后：标准 semver，仅 major 允许破坏。
 - **稳定契约**（patch 不会动）：
     - 工具名（`tl_chain_send`、`tl_chain_swap_v3`、`tl_multisig_*`、`tl_gasfree_*`、`tl_evaluate` 等）
-    - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码)）
+    - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes)）
     - `error.retryable` 语义
     - `meta.schemaVersion` 的 major 分量
     - 必需环境变量名（`TL_TRONGRID_URL`、`TL_MULTISIG_SECRET_KEY`、`AGENT_WALLET_PASSWORD` 等）
@@ -2801,6 +2831,18 @@ flowchart TD
 
 **mcp-server-tronlink 是 tronlink-mcp-core 的使用者。** 核心库定义了工具"是什么"；服务器提供了工具"怎么工作"。
 
+### 该选哪个？
+
+按场景用下面的决策矩阵在两个包之间做选择：
+
+| 场景 | 选 tronlink-mcp-core | 选 mcp-server-tronlink |
+|------|:---:|:---:|
+| 构建嵌入自有业务逻辑的自定义 MCP 服务器 | ✅ | |
+| 直接把一个开箱即用的服务器交给 agent 使用 | | ✅ |
+| 通过自定义 `Capability` 实现扩展能力 | ✅ | |
+| 用可注入的 fixture / mock server 做测试或 mock | ✅ | |
+| 学习 MCP 框架（接口、工具、响应格式）的工作原理 | ✅ | |
+
 ---
 
 ## ISessionManager 接口
@@ -2988,7 +3030,7 @@ interface GasFreeCapability {
 
 所有工具使用 `tl_` 前缀，分为 13 个类别：
 
-> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#精选工具-schema文档侧镜像) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。
+> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#selected-tool-schemas-inline-mirror) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。
 
 ### 1. 会话管理（2 个）
 | 工具 | 说明 |
@@ -3126,7 +3168,7 @@ interface GasFreeCapability {
 }
 ```
 
-### 错误码
+### 错误码 (Error Codes)
 
 这是本框架所有工具返回错误码的**唯一数据源**（SSOT）。下游 server（`mcp-server-tronlink`、`mcp-tronlink-signer`）继承这些错误码并可扩展自有错误码。`retryable` 反映框架层面的安全性，agent 仍**必须**叠加调用工具的副作用分级——无论 `retryable` 为何，**结果未确认的 Remote Write 绝不能自动重试**。
 
@@ -3632,6 +3674,22 @@ tron-wallet（查余额）→ tron-staking（质押信息）→ tron-staking（A
 tron-resource（检查状态）→ tron-resource（估算成本）→ tron-resource（optimize-cost）
 ```
 
+### 端到端示例
+
+**"把 100 TRX 换成 USDT 现在划算吗？"**
+
+1. `token-price`（`tron-market`）—— 获取 TRX 与 USDT 当前价格，确定 100 TRX 的参考价值。
+2. `kline`（`tron-market`）—— 拉取近期 K 线，判断 TRX 处于上行还是下行趋势（择时）。
+3. `resource-info`（`tron-resource`）—— 查询账户的能量/带宽，便于估算本次兑换是否需要燃烧 TRX 抵扣手续费。
+4. `swap-quote`（`tron-swap`）—— 对 100 TRX → USDT 请求实际报价，含预期到账数量与价格冲击。
+5. 智能体将报价的有效汇率与第 1 步现货价对比，结合第 3 步的资源成本，回答兑换是否划算。以上均为**只读**——若要真正执行，请路由到 `mcp-server-tronlink` 的 `tl_chain_swap_v3`（Remote Write、HITL，必传 `minOut`）或 [signer SDK](tronlink-signer.md)。
+
+**"我上一笔 USDT 转账到账了吗？现在余额多少？"**
+
+1. `tx-status`（`tron-swap`）—— 查询最近一笔转账的状态与确认数。
+2. `account-info`（`tron-wallet`）—— 确认该转账结算后的当前余额。
+3. `resource-info`（`tron-resource`）—— 核对剩余能量/带宽是否足够下一笔转账（否则将燃烧 TRX）。发送下一笔转账属于 Remote Write——请路由到 [signer SDK](tronlink-signer.md) 的 `sendTrc20` 或 `mcp-server-tronlink` 的 `tl_chain_send`。
+
 ---
 
 ## TRON 资源模型参考
@@ -3784,6 +3842,16 @@ export TRONGRID_API_KEY="your-api-key"
 export TRON_NETWORK="mainnet"    # 或 "shasta" / "nile"
 ```
 
+#### TronGrid API Key —— 凭证管理
+
+`TRONGRID_API_KEY` 是可选的（只读、提高限额），但一旦配置，请从以下五个维度管理：
+
+- **存储** —— 保存在环境变量或密钥管理器中。切勿硬编码在源码、提交到 git 的配置或聊天/智能体日志里。
+- **最小权限** —— 只签发覆盖这些技能所需只读端点的 Key，不要复用更大权限的生产 Key。
+- **轮换** —— 按固定周期轮换，有访问权限的成员离职时也应轮换；保持轮换窗口尽量短。
+- **泄漏检测** —— 监控 TronGrid 用量是否出现异常调用量或非预期来源 IP，并用密钥扫描器扫描仓库历史排查误提交。
+- **吊销** —— 一旦 Key 泄漏，立即在 TronGrid 控制台吊销并签发新 Key，再恢复流量。
+
 ### 网络支持
 
 | 网络 | 地址 | 用途 |
@@ -3794,6 +3862,8 @@ export TRON_NETWORK="mainnet"    # 或 "shasta" / "nile"
 
 ### 内置代币快捷符号
 
+> 下表为 `tron_api.mjs` 内置、可直接用符号名代替合约地址的代币。未列出的代币（如 USDD）请在 [reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot) 查询地址并显式传入。
+
 | 符号 | 合约地址 |
 |------|----------|
 | TRX | 原生代币（无合约） |
@@ -3866,6 +3936,18 @@ tronlink-skills/
 
 ---
 
+## 故障排查
+
+| 现象 | 原因 | 处理方式 |
+|------|------|----------|
+| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#the-6-skills) / [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 |
+| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#configuration)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 |
+| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill-mcp-tool-map)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs <command> ...`），不要走 `tools/call`。 |
+| `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 |
+| 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add <name>`），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 |
+
+---
+
 ## 地址格式支持
 
 所有命令均支持并自动归一化两种格式：
@@ -3921,7 +4003,7 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级
 
 - **稳定契约**（minor / patch 不会动）：
     - 33 个 CLI 命令名与其必填 / 可选 flag（`tron_api.mjs <command> [...]`）。
-    - [Skill ↔ MCP 工具映射](#skill--mcp-工具映射) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。
+    - [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。
     - Exit code：`0` 成功，`1` 查询错误 / 参数非法，`2` 未支持 / 未知命令。
     - `Network Read` 副作用分级——任何命令未经 major 升级都不会变成 Remote Write。
 - **不稳定契约**（minor 允许变化）：
@@ -3942,6 +4024,22 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级
 
 将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具的服务器，供 Claude 及其他 AI 客户端使用。通过 TronLink 浏览器钱包对 TRON 交易进行签名，需用户在浏览器中授权确认 — 私钥始终留在钱包中，不会对外暴露。
 
+> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#version-license)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。
+
+## 该用哪个
+
+TronLink 提供了三种方式让 AI 智能体在 Tron 上执行操作。请根据是否需要人工审批每一笔交易、以及智能体运行在何处来选择。
+
+| | `mcp-tronlink-signer`（本服务器） | `mcp-server-tronlink`（Direct-API 模式） | `tronlink-cli` |
+| --- | --- | --- | --- |
+| 审批 | HITL —— 用户在浏览器中审批每一笔交易 | 无 HITL —— 自动签名 | HITL —— 用户在浏览器中审批 |
+| 主机上的凭证 | 无（私钥保留在 TronLink 扩展内） | 使用 `AGENT_WALLET_PASSWORD` 解锁本地钱包 | 无（私钥保留在 TronLink 扩展内） |
+| 接口形态 | MCP 服务器 | MCP 服务器 | Shell / 命令行 |
+| 适用场景 | 任何资金转移都必须经人工显式签字确认的智能体 | 自动化、无人值守流程：CI、测试网脚本 | 需要人工签字确认的交互式终端使用 |
+| 私钥暴露风险 | 最低 | 较高（凭证位于主机上） | 最低 |
+
+如果不确定，优先选择 `mcp-tronlink-signer`（最安全的默认选项）。
+
 ## 配置
 
 ### Claude Code
@@ -3994,6 +4092,55 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si
 
 **人工确认（HITL）。** 所有涉及签名的工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 浏览器审批页。AI agent **无法**在用户点击 Approve 之前签名。生产环境必须把 Remote Write 工具视为需要确认。
 
+### 部分工具 Schema（内联镜像）
+
+以下是核心写操作工具入参的文档侧镜像，依据上方工具表中记录的参数整理而成 —— 在没有 MCP 会话时，便于智能体离线编写工具调用。这里镜像的是字段名与 required 集合；运行时 `list_tools` 仍是完整输入 schema（精确字段类型、默认值及 Zod 元数据）的权威来源。
+
+`send_trx`：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Amount of TRX to send" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["to", "amount"]
+}
+```
+
+`send_trc20`：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" },
+    "to": { "description": "Recipient TRON address (T-prefix base58)" },
+    "amount": { "description": "Token amount to send" },
+    "decimals": { "description": "Optional token decimals" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["contractAddress", "to", "amount"]
+}
+```
+
+`sign_typed_data`：
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "typedData": { "description": "EIP-712 typed-data object to sign" },
+    "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" }
+  },
+  "required": ["typedData"]
+}
+```
+
+> 凡无法对照上游 Zod 定义确认的字段类型，上面均有意留空；精确类型请查 `list_tools`。`sign_message`（`message`、`network?`）与 `sign_transaction`（`transaction`、`broadcast`、`network?`）遵循工具表中所示的同样参数形态。
+
 ## MCP 资源
 
 | URI | 说明 |
@@ -4053,7 +4200,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si
 
 > 「已发送 5 TRX——链上已确认（交易 `0a1b2c…`）。」
 
-> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#错误)）。
+> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#errors)）。
 
 ## 取消
 
@@ -4065,7 +4212,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si
 
 ## 错误
 
-server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码) 为准；signer 特有错误如下：
+server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes) 为准；signer 特有错误如下：
 
 | 条件 | Retryable | 何时发生 |
 | --- | :---: | --- |
@@ -4086,7 +4233,7 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r
 |---|---|---|
 | **Prompt 注入** | 工具输入按原始值作为调用参数，server 不会再次提交给 LLM。TronLink 审批页渲染的是解析后的交易字段，不是 agent 的自由文本。 | 链上拿到的字符串（备注、revert 原因）视为不可信；分支应基于 `txId` / `status` / `code`，而非 prose。 |
 | **本地 HTTP listener** | 本地审批 server **仅绑定 `127.0.0.1`**（端口 `TRON_HTTP_PORT`，默认 3386，被占用时自增），永远不接受跨主机连接。每个 server session 有唯一 ID，前一次 session 的浏览器标签会被自动失效。 | 不要把 3386 端口转发到外网。同一台机器不要用相同 `TRON_HTTP_PORT` 跑两份。 |
-| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#环境变量) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 |
+| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#environment-variables) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 |
 | **API key 处理（token passthrough）** | `TRON_API_KEY` 仅在启动时从 env 读取，仅用于到 TronGrid 的出站；**不**会出现在任何工具响应、错误 `details` 或 MCP resource 中。server 不接受 MCP 客户端传入的 Authorization header 并转发到上游。 | API key 放进 MCP host 的 secret manager，不要写进会提交 git 的 `mcpServers` 配置。 |
 | **签名必须 HITL** | 所有签名工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 审批页，**不存在程序化绕过**。私钥始终留在 TronLink。 | 不需要运维额外强制 HITL——这是结构性保证。不要试图通过移除浏览器层来"加固"。 |
 | **浏览器标签劫持** | 审批页基于 server session ID 验证每次请求，过期的标签会被忽略；心跳检测会在断连时关闭 session。 | 同一用户跑多个 agent 时，请让每个 agent 启动自己的 signer 实例；跨实例的请求串扰由 session ID 屏蔽，但 UI 层混淆不防。 |
@@ -4110,6 +4257,8 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r
 
 本页是下游 README 镜像；以 GitHub releases 与各包 `CHANGELOG.md` 为准。下方条目只覆盖 **MCP 可见面**（工具、schema、安全边界），内部重构不列。
 
+> **同步策略。** 此内联 changelog 镜像软件包的 `CHANGELOG.md` / README；项目的 **GitHub releases 为权威来源**。在文档更新之前，本页可能比某个发布版本短暂滞后，因此当需要精确版本号时，请以 GitHub releases（以及 `list_tools`）为准核对。
+
 #### v0.1.4 _(仅 npm，截至本文写就尚未在 GitHub 打 tag)_
 
 仅 patch 修复。无新工具、无破坏性输入/输出 shape 变化。升级后用 `list_tools` 复核。
@@ -4128,7 +4277,7 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r
 - **改进** —— 单页审批流：一个常驻浏览器标签 + 心跳检测；server 重启后旧标签自动失效。
 - **改进** —— TRC20 金额校验改用 BigInt 小数转换（处理 0 位小数、>18 位小数等边界）。
 - **改进** —— `send_trx`、`sign_transaction` 在提交失败时返回真实的 broadcast 错误，不再是空消息。
-- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#错误)）。
+- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#errors)）。
 
 #### v0.1.1 — 2026-04-15
 
@@ -4201,7 +4350,7 @@ await signer.stop();
 
 ### `signer.sendTrx(to, amount, network?, options?): Promise<BroadcastResult>`
 
-向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#广播结果)）。
+向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#broadcast-result)）。
 
 | 参数 | 类型 | 说明 |
 | ---- | ---- | ---- |
@@ -4212,7 +4361,7 @@ await signer.stop();
 
 ### `signer.sendTrc20(contractAddress, to, amount, decimals?, network?, options?): Promise<BroadcastResult>`
 
-发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#广播结果)。
+发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#broadcast-result)。
 
 | 参数 | 类型 | 说明 |
 | ---- | ---- | ---- |
@@ -4244,7 +4393,7 @@ const { signature } = await signer.signTypedData({
 
 ### `signer.signTransaction(transaction, network?, broadcast?, options?): Promise<{ signedTransaction; txId?; status?; error? }>`
 
-对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#广播结果)。
+对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#broadcast-result)。
 
 | 参数 | 类型 | 说明 |
 | ---- | ---- | ---- |
@@ -4453,7 +4602,7 @@ export type {
 
 - **包：** `tronlink-signer` v0.1.4
 - **许可证：** MIT —— `SPDX-License-Identifier: MIT`
-- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#内联-changelog)，SDK 层跟随同一波次。
+- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#inline-changelog)，SDK 层跟随同一波次。
 
 ### 兼容性与迁移策略
 
@@ -4909,11 +5058,13 @@ tronlink reward --json
 
 ### 常用代币合约
 
-| 代币 | 网络 | 合约地址 |
-| ---- | ---- | -------- |
-| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t |
-| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz |
-| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 |
+> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下表为对齐该 SSOT 的子集。
+
+| 代币 | 网络 | 合约地址 | 精度 |
+| ---- | ---- | -------- | ---- |
+| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
+| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 |
+| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 |
 
 ### 示例：AI 转账流程
 
@@ -4950,7 +5101,7 @@ CLI 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级允
     - 子命令名与其必填位置参数 / flag。
     - **Exit code** —— Exit Codes 表中的每一条都属于公开面。minor 允许为此前的通用失败新增 code；重新分配已有数字属于 major。
     - **`--json` 输出 key** —— 顶层 key（`ok`、`error.code`、`error.retryable`、`txid` 等）以及 `error` 下的结构。minor 允许新增可选字段；改名 / 删除属于 major。
-    - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 共享 SSOT）。
+    - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 共享 SSOT）。
 - **不稳定契约**（随时可能变化）：
     - 未带 `--json` 的人类可读 stdout 文本。
     - 提示、横幅、颜色码的具体文本。
@@ -5221,11 +5372,21 @@ TRON 地址有两种可互转的编码：
 
 - `1 TRX = 1,000,000 SUN`。`tronWeb` 交易构造器（如 `sendTrx`）中的金额以 **SUN** 为单位。
 
-## 常用代币合约（主网）
+## 常用代币合约（SSOT）
 
-| 代币 | 标准 | 合约地址 |
-|---|---|---|
-| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
+本表是常用主网代币合约地址的单一可信源（SSOT）。其他页面——[TronLink CLI](../ai-support/tronlink-cli.md) 与 [TronLink Skills](../ai-support/tronlink-skills.md)——均对齐本表；地址变更时，请先在此处更新。
+
+| 代币 | 标准 | 主网合约地址 | 精度 | 备注 |
+|---|---|---|---|---|
+| TRX | 原生 | — | 6 | 原生币，无 TRC-20 合约 |
+| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | |
+| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | |
+| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | |
+| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX |
+| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | |
+| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | |
+| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | |
+| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | |
 
 其他代币请在 [TronScan](https://tronscan.org/#/tokens) 查询其合约地址。集成前务必核对代币合约地址——不同网络上的地址不同。
 
diff --git a/docs/llms.txt b/docs/llms.txt
index a25dc91..ed2f30e 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -2,7 +2,7 @@
 
 > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK).
 
-> Updated: 2026-05-21T14:08:15Z · Commit: e724781c635f
+> Updated: 2026-06-04T07:06:28Z · Commit: a08525609c43
 
 How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events.
 
diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt
index 372276c..fd24848 100644
--- a/docs/llms.zh.txt
+++ b/docs/llms.zh.txt
@@ -2,7 +2,7 @@
 
 > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。
 
-> Updated: 2026-05-21T14:08:15Z · Commit: e724781c635f
+> Updated: 2026-06-04T07:06:28Z · Commit: a08525609c43
 
 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。
 
diff --git a/docs/mobile/deeplink.zh.md b/docs/mobile/deeplink.zh.md
index 962ba87..38779c5 100644
--- a/docs/mobile/deeplink.zh.md
+++ b/docs/mobile/deeplink.zh.md
@@ -208,7 +208,7 @@ img {
 }
 ```
 
-## 回传消息码
+## 回传消息码 { #result-code }
 
 > 注意：转账请求中 `tokenId` 与 `contract` 互斥，两者同时传入会返回消息码 `10025`。
 
@@ -447,4 +447,4 @@ img {
 
 ### 回调 `code` 枚举
 
-完整取值见上方[回传消息码](#回传消息码)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。
+完整取值见上方[回传消息码](#result-code)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。
diff --git a/docs/plugin-wallet/active-requests.zh.md b/docs/plugin-wallet/active-requests.zh.md
index d5a1dba..ef98f68 100644
--- a/docs/plugin-wallet/active-requests.zh.md
+++ b/docs/plugin-wallet/active-requests.zh.md
@@ -40,7 +40,7 @@ try {
 > **旧版用法（不推荐）：** [兼容用法：tron_requestAccounts](#tron_requestaccounts)
 
 
-## 获取TronLink的provider TIP-6963
+## 获取TronLink的provider TIP-6963 { #get-tronlink-provider-via-tip-6963 }
 
 ### 简介
 当多个钱包同时存在，会出现对 `window.tron` 对象的抢占行为。为了保证 DApp 可以获取到特定钱包的 provider，所以实现 TIP-6963 规范。
@@ -535,7 +535,7 @@ interface SwitchTronChainParameter {
 
 ### TIP-6963（provider 发现）
 
-事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#trontip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`：
+事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#get-tronlink-provider-via-tip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`：
 
 - `TIP6963:requestProvider` —— 由 DApp 派发，无 payload。
 - `TIP6963:announceProvider` —— 由已安装的每个钱包派发，`detail = { info: { uuid, name, icon, rdns }, provider }`。TronLink 的 `rdns = "org.tronlink.www"`、`name = "TronLink"`。
diff --git a/docs/reference/networks.en.md b/docs/reference/networks.en.md
index c41f627..90582d0 100644
--- a/docs/reference/networks.en.md
+++ b/docs/reference/networks.en.md
@@ -31,10 +31,20 @@ TRON addresses have two interchangeable encodings:
 
 - `1 TRX = 1,000,000 SUN`. Amounts in `tronWeb` transaction builders (e.g. `sendTrx`) are expressed in **SUN**.
 
-## Common token contracts (Mainnet)
+## Common token contracts (SSOT)
 
-| Token | Standard | Contract address |
-|---|---|---|
-| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
+This is the single source of truth (SSOT) for common mainnet token contract addresses. Other pages — [TronLink CLI](../ai-support/tronlink-cli.md) and [TronLink Skills](../ai-support/tronlink-skills.md) — reconcile to this table; when an address changes, update it here first.
+
+| Token | Standard | Mainnet contract address | Decimals | Notes |
+|---|---|---|---|---|
+| TRX | native | — | 6 | Native coin, no TRC-20 contract |
+| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | |
+| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | |
+| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | |
+| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX |
+| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | |
+| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | |
+| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | |
+| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | |
 
 For any other token, look up its contract address on [TronScan](https://tronscan.org/#/tokens). Always verify a token's contract address before integrating — addresses differ per network.
diff --git a/docs/reference/networks.zh.md b/docs/reference/networks.zh.md
index f82df09..1271c06 100644
--- a/docs/reference/networks.zh.md
+++ b/docs/reference/networks.zh.md
@@ -31,10 +31,20 @@ TRON 地址有两种可互转的编码：
 
 - `1 TRX = 1,000,000 SUN`。`tronWeb` 交易构造器（如 `sendTrx`）中的金额以 **SUN** 为单位。
 
-## 常用代币合约（主网）
+## 常用代币合约（SSOT）
 
-| 代币 | 标准 | 合约地址 |
-|---|---|---|
-| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
+本表是常用主网代币合约地址的单一可信源（SSOT）。其他页面——[TronLink CLI](../ai-support/tronlink-cli.md) 与 [TronLink Skills](../ai-support/tronlink-skills.md)——均对齐本表；地址变更时，请先在此处更新。
+
+| 代币 | 标准 | 主网合约地址 | 精度 | 备注 |
+|---|---|---|---|---|
+| TRX | 原生 | — | 6 | 原生币，无 TRC-20 合约 |
+| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | |
+| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | |
+| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | |
+| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX |
+| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | |
+| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | |
+| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | |
+| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | |
 
 其他代币请在 [TronScan](https://tronscan.org/#/tokens) 查询其合约地址。集成前务必核对代币合约地址——不同网络上的地址不同。
diff --git a/mkdocs.yml b/mkdocs.yml
index 5744244..f949432 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -125,6 +125,7 @@ plugins:
 # Markdown 扩展（开启 mermaid 图表渲染）
 markdown_extensions:
   - admonition
+  - attr_list
   - pymdownx.details
   - pymdownx.superfences:
       custom_fences:
diff --git a/scripts/gen_llms_full.py b/scripts/gen_llms_full.py
index 060f944..fa63c21 100644
--- a/scripts/gen_llms_full.py
+++ b/scripts/gen_llms_full.py
@@ -136,6 +136,21 @@ def page_url(rel: str, lang: str) -> str:
     return f"{slug}/"
 
 
+# Strips a trailing id-only attr_list block (e.g. ` { #errors }`) from an
+# ATX heading. We add these to CJK headings so MkDocs emits a stable anchor
+# (the default slugify drops CJK); they're build-time syntax, not prose, so
+# the plain-text bundles shouldn't carry them. Deliberately narrow: only an
+# `#id` block at end-of-line, so headings like `Promise<{ ... }>` are untouched.
+HEADING_ATTR_ID_RE = re.compile(r"^(#{1,6}\s.*?)\s*\{:?\s*#[\w-]+\s*\}\s*$")
+
+
+def strip_heading_anchor_ids(md: str) -> str:
+    """Drop ` { #id }` attr_list suffixes from heading lines in `md`."""
+    return "\n".join(
+        (HEADING_ATTR_ID_RE.sub(r"\1", line) for line in md.splitlines())
+    )
+
+
 def render_bundle(pages: list[str], lang: str, sha: str, generated_at: str) -> tuple[str, int, list[str]]:
     """Return (full_text, page_count, missing) for one language."""
     body_parts: list[str] = []
@@ -149,7 +164,7 @@ def render_bundle(pages: list[str], lang: str, sha: str, generated_at: str) -> t
         body_parts.append("")
         body_parts.append(f"<!-- source: docs/{rel} | url: {page_url(rel, lang)} -->")
         body_parts.append("")
-        body_parts.append(path.read_text(encoding="utf-8").rstrip())
+        body_parts.append(strip_heading_anchor_ids(path.read_text(encoding="utf-8").rstrip()))
         body_parts.append("")
 
     body = "\n".join(body_parts)