TronLink · YukiXue1 · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git 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
@@ -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
@@ -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
@@ -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,15 +731,26 @@ 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"
 # "Send 10 TRX to TAddress..."
 # "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
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,7 +4,6 @@ on: @@
       push:
         branches:
           - main
-          - feature/ai-readability-p0
       workflow_dispatch: # 仍保留手动触发的功能
     jobs:
@@ Expand Down @@