docs: verify machine contracts against shipped packages; add security disclosure channel and AI-entry hardening

.github/workflows/check-doc-schema-parity.yml

@@ -7,11 +7,15 @@ on:
     paths:
       - "docs/ai-support/mcp-server-tronlink.*.md"
       - "scripts/check_doc_schema_parity.py"
+      - "scripts/gen_llms_full.py"
+      - "docs/security.txt"
       - ".github/workflows/check-doc-schema-parity.yml"
   pull_request:
     paths:
       - "docs/ai-support/mcp-server-tronlink.*.md"
       - "scripts/check_doc_schema_parity.py"
+      - "scripts/gen_llms_full.py"
+      - "docs/security.txt"
       - ".github/workflows/check-doc-schema-parity.yml"
   schedule:
     # Daily — catches upstream Zod schema drift even if our docs are unchanged.
@@ -39,3 +43,9 @@ jobs:
         env:
           SCHEMAS_PIN: ${{ github.event.inputs.schemas_pin || 'main' }}
         run: python3 scripts/check_doc_schema_parity.py
+
+      # Piggybacks on the daily cron: an RFC 9116 security.txt whose
+      # Expires has lapsed is treated as invalid by consumers, and a
+      # dormant repo would never notice via the deploy-time check alone.
+      - name: Check security.txt freshness
+        run: python3 scripts/gen_llms_full.py --check-security-expiry

.github/workflows/gh-pages.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches:
       - main
-      - feature/ai-readability-p0
+      - feature/ai-fix
   workflow_dispatch: # 仍保留手动触发的功能
 
+# Serialize deploys: without this, a slow older run can finish after a
+# newer one and silently roll the live site back to stale content.
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -26,11 +32,36 @@ jobs:
         sudo pip3 install mkdocs-minify-plugin
         sudo pip3 install mkdocs-static-i18n
 
+    # Gate BEFORE building: an expired security.txt must never deploy
+    # (the post-deploy --verify would only catch it after it went live).
+    - name: Check security.txt freshness
+      run: python3 scripts/gen_llms_full.py --check-security-expiry
+
+    # Regenerate the llms bundles at deploy time so the deployed
+    # commit SHA / timestamp headers can never drift from the content,
+    # even if a PR forgot to run the script locally.
+    - name: Regenerate llms bundles
+      run: python3 scripts/gen_llms_full.py
+
     - name: Build the document
       run: mkdocs build
 
     - name: Add CNAME file
-      run: echo 'docs.tronlink.org' > site/CNAME  
+      run: echo 'docs.tronlink.org' > site/CNAME
+
+    # Agents probe several filename conventions for the same entry file, so
+    # mirror AGENTS.txt at the .md paths. docs/security.txt deploys to
+    # /security.txt (legacy RFC 9116 location); copy it to /.well-known/
+    # (canonical) here because mkdocs skips dot-directories under docs/.
+    # .nojekyll disables Jekyll processing on the gh-pages branch — without
+    # it, Pages drops dot-directories like .well-known from the served site.
+    - name: Publish agent-entry variants and security.txt
+      run: |
+        cp site/AGENTS.txt site/AGENTS.md
+        cp site/AGENTS.txt site/CLAUDE.md
+        mkdir -p site/.well-known
+        cp site/security.txt site/.well-known/security.txt
+        touch site/.nojekyll
 
     - name: Build and Deploy
       uses: JamesIves/github-pages-deploy-action@v4
@@ -42,14 +73,19 @@ jobs:
     - name: Verify deployed links
       run: |
         BASE=https://docs.tronlink.org
-        for i in $(seq 1 30); do
-          if curl -sf -o /dev/null "$BASE/llms.txt"; then
-            echo "Site live, running sample verify"
+        WANT="${GITHUB_SHA::12}"
+        # A plain 200 on llms.txt only proves the PREVIOUS deployment is
+        # alive (origin or CDN cache) — endpoints new in this deploy would
+        # still 404. Gate on the llms.txt Commit stamp instead, with a
+        # cache-busting query so Fastly can't serve a stale copy.
+        for i in $(seq 1 90); do
+          if curl -sf "$BASE/llms.txt?fresh=$WANT-$i" | grep -q "Commit: $WANT"; then
+            echo "Deploy $WANT live, running sample verify"
             python3 scripts/gen_llms_full.py --verify "$BASE"
             exit $?
           fi
-          echo "Waiting for deploy to propagate ($i/30)..."
+          echo "Waiting for deploy $WANT to propagate ($i/90)..."
           sleep 10
         done
-        echo "Timeout (5 min) waiting for $BASE/llms.txt to come up"
+        echo "Timeout (15 min) waiting for $BASE/llms.txt to serve commit $WANT"
         exit 1

AGENTS.md

@@ -4,10 +4,13 @@ This repository is the **public documentation site** for TronLink developer inte
 
 If you are an AI coding agent or an autonomous tool reading this for orientation, start with the curated index, not by enumerating files.
 
+> This is the repository-root variant with repository-relative links. The deployed site serves the same file at [https://docs.tronlink.org/AGENTS.txt](https://docs.tronlink.org/AGENTS.txt) (source: `docs/AGENTS.txt`; mirrored at `/AGENTS.md` and `/CLAUDE.md` at deploy time) with absolute URLs so links survive HTTP fetching. Keep the two in sync when editing either.
+
 ## 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.
+- **Static MCP tool contracts:** [docs/reference/mcp-tools.json](docs/reference/mcp-tools.json) — every MCP tool definition (name, description, `inputSchema`) captured from the published npm servers via `tools/list`, for agents that need the full contract without spawning a server. (MCP `annotations` would be captured too; the current servers publish none.)
 - **Human-readable site:** [https://docs.tronlink.org/](https://docs.tronlink.org/)
 
 ## Topic map
@@ -17,20 +20,31 @@ If you are an AI coding agent or an autonomous tool reading this for orientation
 | 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) |
+| Cross-surface security invariants & vulnerability disclosure | [docs/ai-support/security-model.en.md](docs/ai-support/security-model.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) |
+| Cross-surface error-code map (DApp / DeepLink / MCP / CLI, with retryable flags) | [docs/reference/error-code-map.en.md](docs/reference/error-code-map.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.
+- **Per-tool input schemas:** the SSOT is the running MCP server's `list_tools` (returns `inputSchema` per tool). [docs/reference/mcp-tools.json](docs/reference/mcp-tools.json) is a stamped static snapshot of that output; doc tables are a summary, not a contract.
 - **Versions:** each AI-support page ends with `Version & License` keyed to the corresponding upstream `package.json`.
 
+## Continuous verification (enforced in CI)
+
+- **Doc ↔ schema parity:** [scripts/check_doc_schema_parity.py](scripts/check_doc_schema_parity.py) runs on every push and PR and daily on a schedule ([.github/workflows/check-doc-schema-parity.yml](.github/workflows/check-doc-schema-parity.yml)). It diffs the inline JSON Schema mirrors in the MCP server doc against the upstream Zod schemas (`tronlink-mcp-core` `src/mcp-server/schemas.ts`); an upstream rename or required/optional drift fails the build, so published schema mirrors cannot silently rot. (The published servers emit no schema-version marker on the wire; this CI check is the guard.)
+- **Post-deploy link check:** every deploy ends with `scripts/gen_llms_full.py --verify`, probing the llms endpoints, the agent-entry mirrors, the `security.txt` pointer, and sampled index links for HTTP 200.
+
+## Security disclosures
+
+Report vulnerabilities privately to tronlink@tronlink.org with a `[SECURITY]` subject prefix — never in a public issue. Machine-readable pointer: [https://docs.tronlink.org/.well-known/security.txt](https://docs.tronlink.org/.well-known/security.txt) (RFC 9116); full policy: [SECURITY.md](SECURITY.md).
+
 ## Upstream code repositories (not in this repo)
 
 - [github.com/TronLink/mcp-server-tronlink](https://github.com/TronLink/mcp-server-tronlink)
@@ -44,7 +58,8 @@ If you need to change runtime behavior (tool schemas, error codes, transaction l
 ## How to refresh derived files
 
 ```bash
-python3 scripts/gen_llms_full.py
+python3 scripts/gen_llms_full.py     # llms-full bundles + index header stamps
+python3 scripts/dump_mcp_tools.py    # static MCP tool contracts (docs/reference/mcp-tools.json)
 ```
 
-This regenerates `docs/llms-full.txt` with a fresh commit SHA, timestamp, and token estimate. Run it after any change under `docs/`.
+Run the first after any change under `docs/` (CI also runs it automatically at deploy time); run the second when an upstream npm package publishes a new version.

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please do **not** open a public GitHub issue for security vulnerabilities.
+
+Report privately by email to **tronlink@tronlink.org** — TronLink's officially published contact address (listed on [tronlink.org](https://www.tronlink.org/)) — with a subject line starting with `[SECURITY]`.
+
+Where possible, include:
+
+- The affected surface and version: the TronLink extension or mobile app, `mcp-server-tronlink`, `tronlink-mcp-core`, `mcp-tronlink-signer`, `tronlink-signer`, `@tronlink/tronlink-cli`, `tronlink-skills`, or this documentation site.
+- Reproduction steps or a proof of concept.
+- An impact assessment — in particular whether funds can be moved, or a signing approval bypassed, without user interaction.
+
+The machine-readable disclosure pointer is published at [https://docs.tronlink.org/.well-known/security.txt](https://docs.tronlink.org/.well-known/security.txt) (RFC 9116; also served at `/security.txt`).
+
+## Scope
+
+This repository holds the developer documentation site ([docs.tronlink.org](https://docs.tronlink.org/)). Vulnerabilities in TronLink products themselves live in their own repositories (listed in [AGENTS.md](AGENTS.md)); until each of those ships its own security policy, use the reporting channel above for them as well.
+
+Issues in scope for this repository specifically:
+
+- Content injection / XSS on docs.tronlink.org.
+- Documentation that instructs an unsafe default — e.g. an example that bypasses human-in-the-loop approval, weakens the SSRF allowlist, or would leak a private key or API secret.
+- Supply-chain issues in the site build pipeline (`.github/workflows/`, `scripts/`).
+
+## What not to report here
+
+Lost funds, phishing reports, and account-support requests are user-support matters — use the support channels on [tronlink.org](https://www.tronlink.org/), not this policy.