bbsyaya · May 21, 2026 · May 20, 2026 · May 20, 2026 · May 20, 2026 · May 20, 2026
diff --git a/.github/workflows/check-doc-schema-parity.yml b/.github/workflows/check-doc-schema-parity.yml
@@ -0,0 +1,41 @@
+name: Check doc/schema parity
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/ai-support/mcp-server-tronlink.*.md"
+      - "scripts/check_doc_schema_parity.py"
+      - ".github/workflows/check-doc-schema-parity.yml"
+  pull_request:
+    paths:
+      - "docs/ai-support/mcp-server-tronlink.*.md"
+      - "scripts/check_doc_schema_parity.py"
+      - ".github/workflows/check-doc-schema-parity.yml"
+  schedule:
+    # Daily — catches upstream Zod schema drift even if our docs are unchanged.
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+    inputs:
+      schemas_pin:
+        description: "Upstream ref (SHA or branch) to check against; default = main"
+        required: false
+        default: "main"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Run parity check
+        env:
+          SCHEMAS_PIN: ${{ github.event.inputs.schemas_pin || 'main' }}
+        run: python3 scripts/check_doc_schema_parity.py
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - feature/ai-readability-p0
   workflow_dispatch: # 仍保留手动触发的功能
 
 jobs:

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,50 @@
+# AGENTS.md
+
+This repository is the **public documentation site** for TronLink developer integrations. It is *not* the source code of TronLink itself, the MCP servers, the CLI, or the Signer SDK — those live in separate repositories listed below.
+
+If you are an AI coding agent or an autonomous tool reading this for orientation, start with the curated index, not by enumerating files.
+
+## Entry points for AI agents
+
+- **Curated index:** [docs/llms.txt](docs/llms.txt) — short, link-only map of the documentation, following [llmstxt.org](https://llmstxt.org/). Use this first.
+- **Single-fetch full text:** [docs/llms-full.txt](docs/llms-full.txt) — every English page concatenated for one-shot ingestion. The header records the generating commit SHA, UTC timestamp, page count, and a rough token estimate; check those before relying on the content.
+- **Human-readable site:** [https://docs.tronlink.org/docs/](https://docs.tronlink.org/docs/)
+
+## Topic map
+
+| Surface | Doc |
+| --- | --- |
+| DApp integration in the browser (TIP-6963 / `eth_requestAccounts` / `tronWeb`) | [docs/dapp/getting-started.en.md](docs/dapp/getting-started.en.md) + [docs/plugin-wallet/*](docs/plugin-wallet/) |
+| Mobile DeepLink (`tronlinkoutside://`) | [docs/mobile/deeplink.en.md](docs/mobile/deeplink.en.md) |
+| AI-agent tooling overview | [docs/ai-support/ai-llms.en.md](docs/ai-support/ai-llms.en.md) |
+| MCP server (production) | [docs/ai-support/mcp-server-tronlink.en.md](docs/ai-support/mcp-server-tronlink.en.md) |
+| MCP framework / SSOT error codes | [docs/ai-support/tronlink-mcp-core.en.md](docs/ai-support/tronlink-mcp-core.en.md) |
+| MCP signer wrapper (HITL signing) | [docs/ai-support/mcp-tronlink-signer.en.md](docs/ai-support/mcp-tronlink-signer.en.md) |
+| Signer SDK (browser-approval signing) | [docs/ai-support/tronlink-signer.en.md](docs/ai-support/tronlink-signer.en.md) |
+| Read-only Skills package | [docs/ai-support/tronlink-skills.en.md](docs/ai-support/tronlink-skills.en.md) |
+| CLI (transactions via browser approval) | [docs/ai-support/tronlink-cli.en.md](docs/ai-support/tronlink-cli.en.md) |
+| Networks, addresses, glossary, FAQ | [docs/reference/](docs/reference/) |
+
+## Source-of-truth boundaries
+
+- **Error codes & retry semantics:** the SSOT is [docs/ai-support/tronlink-mcp-core.en.md#error-codes](docs/ai-support/tronlink-mcp-core.en.md#error-codes). Downstream docs link into it; do not duplicate the table.
+- **Per-tool input schemas:** the SSOT is the running MCP server's `list_tools` (returns `inputSchema` per tool). Doc tables are a summary, not a contract.
+- **Versions:** each AI-support page ends with `Version & License` keyed to the corresponding upstream `package.json`.
+
+## Upstream code repositories (not in this repo)
+
+- [github.com/TronLink/mcp-server-tronlink](https://github.com/TronLink/mcp-server-tronlink)
+- [github.com/TronLink/tronlink-mcp-core](https://github.com/TronLink/tronlink-mcp-core)
+- [github.com/TronLink/mcp-tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer) (monorepo includes `tronlink-signer`)
+- [github.com/TronLink/tronlink-cli](https://github.com/TronLink/tronlink-cli)
+- [github.com/TronLink/tronlink-skills](https://github.com/TronLink/tronlink-skills)
+
+If you need to change runtime behavior (tool schemas, error codes, transaction logic), open a PR there. PRs to this repo should only update prose, examples, and diagrams.
+
+## How to refresh derived files
+
+```bash
+python3 scripts/gen_llms_full.py
+```
+
+This regenerates `docs/llms-full.txt` with a fresh commit SHA, timestamp, and token estimate. Run it after any change under `docs/`.
diff --git a/README.md b/README.md
@@ -2,6 +2,17 @@
 
 This is the official developer documentation for the TronLink wallet, providing comprehensive development guides and API references.
 
+## 🤖 For AI Agents
+
+If you are an AI agent (Claude, Cursor, Codex, etc.) reading this repo, start here:
+
+- [`AGENTS.md`](AGENTS.md) — orientation: topic map, SSOT boundaries (error codes, schemas, versions), upstream package pointers.
+- [`docs/llms.txt`](docs/llms.txt) / [`docs/llms.zh.txt`](docs/llms.zh.txt) — curated [llmstxt.org](https://llmstxt.org/) indexes. **Source filenames** carry `.en`/`.zh` suffixes; **deployed URLs** strip them: `/docs/llms.txt` (EN) and `/docs/zh/llms.txt` (ZH).
+- [`docs/llms-full.en.txt`](docs/llms-full.en.txt) / [`docs/llms-full.zh.txt`](docs/llms-full.zh.txt) — every page concatenated for single-fetch ingestion. Deployed at `/docs/llms-full.txt` (EN) and `/docs/zh/llms-full.txt` (ZH).
+- [`docs/ai-support/`](docs/ai-support/) — MCP servers, Skills, CLI, signer SDK. Live AI/agent surface; see [`ai-llms.en.md`](docs/ai-support/ai-llms.en.md) for the overview.
+
+Branch on structured `error.code` / `error.retryable`, never on prose. Sign / Remote Write tools require user approval (HITL) and must not be auto-retried — see each tool's Safety section.
+
 ## 📖 Documentation Contents
 
 - **Introduction** - Overview of TronLink and the TRON ecosystem
@@ -19,6 +30,13 @@ This is the official developer documentation for the TronLink wallet, providing
   - Message Signature
   - General Transfer
   - Stake2.0
+- **AI Support** - AI agent tooling and machine-readable documentation
+  - AI / LLMs (entry point + `llms.txt` / `llms-full.*.txt` endpoints)
+  - MCP Server TronLink (52 tools: on-chain, multi-sig, GasFree)
+  - TronLink MCP Core (framework library, SSOT for error codes & schemas)
+  - TronLink Skills (read-only agent skills, 33 commands / 25 MCP tools)
+  - MCP TronLink Signer & TronLink Signer SDK (HITL signing)
+  - TronLink CLI
 
 ## 🚀 Getting Started
 

diff --git a/docs/ai-support/ai-llms.en.md b/docs/ai-support/ai-llms.en.md
@@ -0,0 +1,53 @@
+# AI / LLMs
+
+TronLink's developer documentation is published in machine-readable form so AI agents and LLM-based tools can discover, read, and integrate it directly.
+
+## Available endpoints
+
+> **URL ≠ source filename.** Source files carry `.en` / `.zh` suffixes (`llms.zh.txt`, `llms-full.en.txt`, `llms-full.zh.txt`) so the mkdocs i18n plugin can route them. **In the deployed site the suffix is stripped** — Chinese variants live under `/docs/zh/`. Use the deployed URLs below; the source-name URLs (e.g. `/docs/llms-full.en.txt`) return 404.
+
+| Endpoint (deployed URL) | Description |
+| --- | --- |
+| [/docs/llms.txt](/docs/llms.txt) | Curated English index of key pages ([llmstxt.org](https://llmstxt.org/) format) |
+| [/docs/zh/llms.txt](/docs/zh/llms.txt) | Curated Chinese index — same layout, links into `/docs/zh/` pages |
+| [/docs/llms-full.txt](/docs/llms-full.txt) | Every English page concatenated for single-fetch ingestion (built from `docs/llms-full.en.txt`) |
+| [/docs/zh/llms-full.txt](/docs/zh/llms-full.txt) | Every Chinese page concatenated for single-fetch ingestion (built from `docs/llms-full.zh.txt`) |
+
+Production URLs: `https://docs.tronlink.org/docs/llms.txt`, `https://docs.tronlink.org/docs/zh/llms.txt`, and the matching `llms-full.txt` bundles under each locale root.
+
+## Which file should I use?
+
+| Use case | URL |
+| --- | --- |
+| Navigate / find the right English page | `/docs/llms.txt` — short, link-only map |
+| Navigate / find the right Chinese page | `/docs/zh/llms.txt` — same layout, Chinese descriptions |
+| Ingest the whole English documentation in one request | `/docs/llms-full.txt` |
+| Ingest the whole Chinese documentation in one request | `/docs/zh/llms-full.txt` |
+
+Start with the index for your language and follow its links; fetch a full bundle when you need everything at once. The Chinese index points at `/docs/zh/` slugs; the English index points at `/docs/` slugs.
+
+## Add to your AI tool
+
+- **Cursor** — Settings → Features → Docs → *Add new doc*, paste `https://docs.tronlink.org/docs/llms.txt`.
+- **Claude / MCP-capable agents** — TronLink ships MCP servers for live wallet and chain access; see [MCP Server TronLink](mcp-server-tronlink.md) and [MCP TronLink Signer](mcp-tronlink-signer.md) for host configuration. For documentation context, point the tool at the `llms.txt` URL above.
+- **Other tools** — any tool that accepts a custom documentation URL can use the `llms.txt` / `llms-full.txt` endpoints.
+
+## Coverage
+
+The bundle covers the full documentation, including the AI/agent tooling:
+
+- [MCP Server TronLink](mcp-server-tronlink.md) — on-chain, multi-sig, and GasFree tools (Playwright + Direct API)
+- [TronLink MCP Core](tronlink-mcp-core.md) — framework library: schemas, tool definitions, flow recipes
+- [TronLink Skills](tronlink-skills.md) — read-only agent skill set (wallet, token, market, swap, resource, staking)
+- [MCP TronLink Signer](mcp-tronlink-signer.md) — MCP server wrapping the signer SDK
+- [TronLink Signer](tronlink-signer.md) — standalone signer SDK
+- [TronLink CLI](tronlink-cli.md) — command-line tool
+
+Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary, FAQ) sections.
+
+## Notes for agents
+
+- Start from `llms.txt` — it is the authoritative map. Don't enumerate the site blindly.
+- 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.
diff --git a/docs/ai-support/ai-llms.zh.md b/docs/ai-support/ai-llms.zh.md
@@ -0,0 +1,53 @@
+# AI / LLMs
+
+TronLink 的开发者文档以机器可读形式发布，便于 AI 智能体和基于 LLM 的工具直接发现、读取与集成。
+
+## 可用端点
+
+> **URL ≠ 源文件名。** 源文件带 `.en` / `.zh` 后缀（`llms.zh.txt`、`llms-full.en.txt`、`llms-full.zh.txt`），mkdocs 的 i18n 插件靠这个后缀来分流；**部署后后缀会被剥掉**，中文版本搬到 `/docs/zh/` 下。请使用下表中的部署 URL；带语言后缀的源文件名 URL（如 `/docs/llms-full.en.txt`）会 404。
+
+| 端点（部署 URL） | 说明 |
+| --- | --- |
+| [/docs/llms.txt](/docs/llms.txt) | 英文版精选索引（[llmstxt.org](https://llmstxt.org/) 规范） |
+| [/docs/zh/llms.txt](/docs/zh/llms.txt) | 中文版精选索引——同样版式，链接指向 `/docs/zh/` 下的中文页面 |
+| [/docs/llms-full.txt](/docs/llms-full.txt) | 所有英文页面全文聚合，便于单次抓取（由 `docs/llms-full.en.txt` 构建） |
+| [/docs/zh/llms-full.txt](/docs/zh/llms-full.txt) | 所有中文页面全文聚合，便于单次抓取（由 `docs/llms-full.zh.txt` 构建） |
+
+生产地址：`https://docs.tronlink.org/docs/llms.txt`、`https://docs.tronlink.org/docs/zh/llms.txt`，以及对应的 `/llms-full.txt` 全文聚合。
+
+## 该用哪个文件？
+
+| 场景 | URL |
+| --- | --- |
+| 导航 / 找到正确的英文页面 | `/docs/llms.txt` —— 简短的纯链接地图 |
+| 导航 / 找到正确的中文页面 | `/docs/zh/llms.txt` —— 中文描述、同样版式 |
+| 一次抓取整份英文文档 | `/docs/llms-full.txt` |
+| 一次抓取整份中文文档 | `/docs/zh/llms-full.txt` |
+
+请先用对应语言的索引并跟随其链接；需要一次性获取全部内容时再抓全文包。中文索引指向 `/docs/zh/` 下的页面，英文索引指向 `/docs/` 下的页面。
+
+## 添加到你的 AI 工具
+
+- **Cursor** —— Settings → Features → Docs → *Add new doc*,粘贴 `https://docs.tronlink.org/docs/llms.txt`。
+- **Claude / 支持 MCP 的智能体** —— TronLink 提供 MCP 服务以实现实时钱包与链上访问,host 配置见 [MCP Server TronLink](mcp-server-tronlink.md) 与 [MCP TronLink Signer](mcp-tronlink-signer.md)。仅作文档上下文时,把工具指向上面的 `llms.txt` 地址即可。
+- **其他工具** —— 任何支持自定义文档 URL 的工具都可使用 `llms.txt` / `llms-full.txt` 端点。
+
+## 覆盖范围
+
+该聚合覆盖完整文档,包括 AI/智能体工具链：
+
+- [MCP Server TronLink](mcp-server-tronlink.md) —— 链上、多签、GasFree 工具（Playwright + Direct API）
+- [TronLink MCP Core](tronlink-mcp-core.md) —— 框架库：schema、工具定义、流程配方
+- [TronLink Skills](tronlink-skills.md) —— 只读智能体技能集（钱包、代币、行情、兑换、资源、质押）
+- [MCP TronLink Signer](mcp-tronlink-signer.md) —— 封装签名 SDK 的 MCP 服务
+- [TronLink Signer](tronlink-signer.md) —— 独立签名 SDK
+- [TronLink CLI](tronlink-cli.md) —— 命令行工具
+
+以及 DApp 集成、移动端（DeepLink）和参考（网络、术语表、FAQ）章节。
+
+## 给智能体的说明
+
+- 从 `llms.txt` 开始——它是权威地图。不要盲目枚举站点文件。
+- 工具调用请基于结构化的 `error.code` / `error.retryable` 分支,**不要**解析人类可读的 `message`。
+- 读操作可安全重试;签名 / 远程写操作需要用户审批（HITL）,且不得自动重试——见各工具的「安全」一节。
+- 实验时默认用测试网（`nile` / `shasta`）;只有动用真实资金时才用 `mainnet`。
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,7 @@ on: @@
       push:
         branches:
           - main
+          - feature/ai-readability-p0
       workflow_dispatch: # 仍保留手动触发的功能
     jobs:
@@ Expand Down @@