From 2887942d13c15bff6cfa95899fa2940e5f2adb59 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:01 +0800
Subject: [PATCH 01/13] docs(x402): align with SDK 2.1.0 and facilitator v2.2.2

- Packages, imports and samples follow @bankofai/x402-tron 2.1.0 on official @x402/* 2.28.0; Node.js 24.22.1+.
- Facilitator error codes, rate limits, /sponsoring/ready, sponsoring scope (Nile, API key) and GasFree proxy behaviour match v2.2.2.
- TRON resource sponsoring now notes the 2.1.0 client extension requirement.
- Decimal TRON CAIP-2 IDs; the API Catalog keeps hex IDs; catalog CI rules.
- Diagrams: catalog consumer is wallet-cli, MCP catalog lookup not shipped, zh permitTransferFrom.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 changelog/x402.md                             |  40 +++++++
 docs/x402/AGENTS.md                           |  10 +-
 docs/x402/api-catalog/get-started.md          |   6 +-
 docs/x402/api-catalog/index.md                |   2 +-
 docs/x402/api-catalog/list-your-service.md    |  13 ++-
 docs/x402/api-catalog/reference.md            |  14 ++-
 .../x402/core-concepts/OfficialFacilitator.md |  36 +++---
 docs/x402/core-concepts/client-server.md      |   6 +-
 docs/x402/core-concepts/facilitator.md        |  23 ++--
 docs/x402/core-concepts/gateway.md            |   2 +-
 docs/x402/core-concepts/http-402.md           |  16 +--
 .../network-and-token-support.md              |  29 +++--
 docs/x402/core-concepts/wallet.md             |   4 +-
 docs/x402/faq.md                              |  50 ++++----
 .../getting-started/quickstart-for-human.md   |  24 ++--
 .../getting-started/quickstart-for-sellers.md |  75 +++++-------
 docs/x402/index.md                            |  12 +-
 docs/x402/sdk-features.md                     | 109 ++++++++++--------
 .../current/x402.md                           |  40 +++++++
 .../current/x402/AGENTS.md                    |  10 +-
 .../current/x402/api-catalog/get-started.md   |   6 +-
 .../current/x402/api-catalog/index.md         |   2 +-
 .../x402/api-catalog/list-your-service.md     |  13 ++-
 .../current/x402/api-catalog/reference.md     |  14 ++-
 .../x402/core-concepts/OfficialFacilitator.md |  36 +++---
 .../x402/core-concepts/client-server.md       |   6 +-
 .../current/x402/core-concepts/facilitator.md |  25 ++--
 .../current/x402/core-concepts/gateway.md     |   2 +-
 .../current/x402/core-concepts/http-402.md    |  16 +--
 .../network-and-token-support.md              |  29 +++--
 .../current/x402/core-concepts/wallet.md      |   6 +-
 .../current/x402/faq.md                       |  50 ++++----
 .../getting-started/quickstart-for-human.md   |  24 ++--
 .../getting-started/quickstart-for-sellers.md |  75 +++++-------
 .../current/x402/index.md                     |  12 +-
 .../current/x402/sdk-features.md              | 109 ++++++++++--------
 .../x402-api-catalog-pipeline.light.svg       |   4 +-
 .../diagrams/x402-api-catalog-pipeline.svg    |   4 +-
 .../x402-api-catalog-pipeline.zh.light.svg    |   4 +-
 .../diagrams/x402-api-catalog-pipeline.zh.svg |   4 +-
 .../x402-payment-scheme-flow.zh.light.svg     |   2 +-
 .../diagrams/x402-payment-scheme-flow.zh.svg  |   2 +-
 42 files changed, 555 insertions(+), 411 deletions(-)

diff --git a/changelog/x402.md b/changelog/x402.md
index 1fc8792f..de867bdc 100644
--- a/changelog/x402.md
+++ b/changelog/x402.md
@@ -7,6 +7,46 @@ description: 'Release notes for the x402 payment protocol, SDK, and CLI.'
 
 Release notes for the x402 protocol, SDK, and [Wallet CLI guide](/wallet-cli/).
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Facilitator error codes completed
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- The facilitator error list now includes the protocol-level sponsoring reasons (`approval_transaction_reused`, `sponsor_approval_lifetime_exceeded`, `sponsor_existing_delegation`), `400 permit2_invalid_authorization` on `/settle`, `500 internal_error`, and the GasFree proxy's `502 bad_gateway`.
+- **Wallet CLI reference** — a table of the error codes a reader will hit (`missing_wallet_address`, `auth_required`, `invalid_option`, `no_matching_requirement`, `permit2_allowance_required`, …) with exit codes, and the `bai recharge` rules: `--to`, the token default (USDC on Base, USDT elsewhere) and the minimum amounts behind `invalid_amount`.
+
+👉 [Facilitator](/x402/core-concepts/facilitator/) · [Wallet CLI reference](/wallet-cli/command-reference/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 25, 2026</div>
+<div className="changelog-body">
+
+### Docs aligned with SDK 2.1.0 and facilitator v2.2.2
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **SDK 2.1.0** — the SDK pages follow the 2.1.0 package set: `@bankofai/x402-tron` 2.1.0 and the new `@bankofai/x402-tron-extensions` 2.1.0 (upgrade the two together) on official `@x402/core` 2.28.0, with the official `@x402/*` HTTP/MCP integrations, `@x402/evm` and `@x402/extensions` 2.28.0. The quickstarts import from `@x402/core`, `@x402/fetch` and `@x402/express`, and construct `new x402ResourceServer(...)` in place of `createResourceServer` from `@bankofai/x402-core`, which is not used with the 2.1 mechanism. The local EVM package, `@bankofai/x402-extensions` and the `typescript/packages/legacy/` compatibility packages were removed in 2.1.0 (the root `legacy/` archive, including the retired Python SDK, already in 2.0.0). TRON resource sponsoring now needs an explicitly registered client extension, and the SDK requires Node.js 24.22.1+. The official `@x402/evm` ships no BSC default assets, so BSC routes must be priced with an explicit `{ asset, amount, extra }` object and BSC assets must be allowlisted on the client; among the networks these docs cover, the default assets are now USDT on TRON and USDC on Base / Base Sepolia.
+- **Pending settlement** — `settlement_pending` is documented as a non-terminal result to reconcile rather than resubmit. 2.1.0 adds the injectable `pendingSettlementStore` (the default `InMemoryTronPendingSettlementStore` covers one process only) and the `settlement_store_unavailable` and `settlement_execution_failed` codes, and extends `chain_read_failed` (already used by `exact` Permit2 reads) to `upto` preflight reads. `HTTPFacilitatorClient` now comes from official Core with a 90 s default timeout; the examples set 120 s.
+- **TRON-only examples** — the repository examples now cover TRON only, so the seller quickstart points BSC and Base sellers to the official facilitator or the upstream `@x402/evm` examples. The official facilitator v2.2.1 and v2.2.2 are security releases (Node.js and dependency updates; v2.2.2 also installs the patched system Brotli for CVE-2026-111497); its documented behavior is unchanged.
+- **Decimal TRON IDs** — examples and tables use `tron:728126428` (mainnet), `tron:3448148188` (Nile) and `tron:2494104990` (Shasta). The x402 SDK still accepts the hex forms as input; wallet-cli's `--network` does not. The API Catalog is the exception: its schema still accepts only the hex form.
+- **Official facilitator limits** — anonymous callers get 10 requests per IP per minute and API Keys 1,000 per minute, counted separately for `/verify` and `/settle` (both are limited). Over the limit returns `429` with `Retry-After`. The docs previously said one `/settle` per minute.
+- **Resource sponsoring on Nile** — the official facilitator lists `trc20ApprovalResourceSponsoring` in `/supported` but enables it on Nile only, for Nile USDT, and requires an API Key (`sponsor_auth_required` / `sponsor_network_disabled` otherwise). `GET /sponsoring/ready` and the `/verify` / `/settle` error codes are now documented.
+- **Settlement records** — successful settlements are unique per (network, asset, payer, nonce) through a partial unique index. This corrects the Sep 9 note that the table had no unique constraint.
+- **API Catalog** — local checks need Python 3.11+; the checklist adds the remaining CI rules (required `pay.md` strings, a TRON `exact` + `permit2` first route, no `--scheme exact_gasfree`, all four `status` keys) and notes that fixed-count tests must be updated in the same PR. The list commands read the local cache and download only when it is missing or lacks what was asked for, so run `update-catalog` to refresh a cache that may be stale.
+- **Wallet CLI reference** — now targets `@tron-walletcli/wallet-cli@4.15.1` and documents the default $1 per-payment cap for known stablecoins (`amount_exceeds_limit`), `--out` (required for binary responses), `--max-gasfree-fee-raw`, and that `--max-raw-amount` requires `--token` or `--asset`. The quick start warns that a first TRON `exact` payment in a token may broadcast a one-time `approve(Permit2, MaxUint256)`, and the result reference covers a response format error after settlement (`retryPayment: false`). It also notes that the wallet-cli Skill pins 4.14.0, so Skill users install that version instead.
+- **Protocol details** — a `402` carries its requirements in the Base64 `PAYMENT-REQUIRED` header with a `{}` body, and verification failures put the reason in that header's `error`; an insufficient Permit2 allowance on `exact` / `upto` returns `412 permit2_allowance_required`. EVM `exact` also supports the `upfront` payment flow. Permit2 payloads use `payload.permit2Authorization`. DHLU was removed from the token tables (no current code references it), BSC mainnet USDC is marked as explicit-asset only, the official facilitator's rate-limit counters are per instance, and the npm packages are Apache-2.0 (the repository LICENSE is MIT).
+
+👉 [SDK Features](/x402/sdk-features/) · [Official Facilitator](/x402/core-concepts/OfficialFacilitator/) · [List Your Service](/x402/api-catalog/list-your-service/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 28, 2026</div>
 <div className="changelog-body">
diff --git a/docs/x402/AGENTS.md b/docs/x402/AGENTS.md
index 30419d17..afacdca3 100644
--- a/docs/x402/AGENTS.md
+++ b/docs/x402/AGENTS.md
@@ -18,7 +18,7 @@ import TabItem from '@theme/TabItem';
 - `docs/faq.md` — Frequently Asked Questions.
 - `sidebars.js` — Docusaurus sidebar configuration.
 - `docusaurus.config.js` — Main Docusaurus configuration file.
-- `docs/sdk-features.md` — Feature matrix for the TypeScript-only x402 SDK (`@bankofai/x402-*` packages).
+- `docs/sdk-features.md` — Feature matrix for the TypeScript-only x402 SDK (`@bankofai/x402-tron` and `@bankofai/x402-tron-extensions` on the official `@x402/*` packages).
 
 ---
 
@@ -35,8 +35,8 @@ Documentation must reflect code changes immediately. Follow these dependency map
 
 ## 4. Style & Writing Standards
 
-- Use **TypeScript** as the primary example language (the SDK is TypeScript-only; the previous Python SDK lives under `legacy/`).
-- Prefer code samples that work with the published `@bankofai/x402-*` npm packages. Runnable `examples/typescript/` code may be used as a reference implementation when it matches the package API.
+- Use **TypeScript** as the primary example language (the SDK is TypeScript-only; the previous Python SDK was removed in x402 v2.0.0).
+- Prefer code samples that work with the published npm packages (`@bankofai/x402-tron`, `@bankofai/x402-tron-extensions` and the official `@x402/*` packages). Runnable `examples/typescript/` code may be used as a reference implementation when it matches the package API.
 - All API examples **must include complete error handling**.
 - Target audience: developers with **2–5 years of experience**.
 - Use Docusaurus MDX components (`<Tabs>`, `<TabItem>`) for multi-language examples.
@@ -66,7 +66,7 @@ Documentation must reflect code changes immediately. Follow these dependency map
 <Tabs>
   <TabItem value="TRON" label="TRON">
 
-- **Network Identifier**: Must follow the `tron:<hex_chain_id>` CAIP-2 format. Use exported constants from `@bankofai/x402-tron` (`TRON_MAINNET`, `TRON_NILE`, `TRON_SHASTA`) instead of hard-coding names.
+- **Network Identifier**: Must follow the `tron:<decimal_chain_id>` CAIP-2 format (e.g. `tron:3448148188` for Nile); hex forms such as `tron:0xcd8690dc` are deprecated input aliases. Use exported constants from `@bankofai/x402-tron` (`TRON_MAINNET`, `TRON_NILE`, `TRON_SHASTA`) instead of hard-coding names.
 - **Signature Standard**: TRON signatures must reference the **TIP-712** standard (do not confuse with EIP-712).
 - **Address Format**: Token addresses must use Base58 encoding (must start with `T`).
 - **Node Access**: Must connect to TronGrid endpoints.
@@ -142,7 +142,7 @@ When SDK code changes in any of the following areas, you **must** update `docs/s
 - New signers added under the `*/signers/` directory.
 - New features introduced in the Client or Server components.
 
-> **Note**: The SDK is TypeScript-only. Cross-check documentation against the published `@bankofai/x402-*` package API, `typescript/packages/` exports, and `examples/typescript/` reference source.
+> **Note**: The SDK is TypeScript-only. Cross-check documentation against the published package APIs (`@bankofai/x402-tron`, `@bankofai/x402-tron-extensions`, official `@x402/*`), `typescript/packages/` exports, and `examples/typescript/` reference source.
 
 ---
 
diff --git a/docs/x402/api-catalog/get-started.md b/docs/x402/api-catalog/get-started.md
index b810dfeb..f5796d7b 100644
--- a/docs/x402/api-catalog/get-started.md
+++ b/docs/x402/api-catalog/get-started.md
@@ -5,18 +5,18 @@ description: "Discover catalog services and preview payments with wallet-cli."
 
 # Catalog Quick Start
 
-Install `@tron-walletcli/wallet-cli@4.14.0` using the [Wallet CLI quick start](/wallet-cli/quickstart/). Catalog reads need no wallet or password; payment previews and payments require a configured account.
+Install Wallet CLI using the [Wallet CLI quick start](/wallet-cli/quickstart/). Catalog reads need no wallet or password; payment previews and payments require a configured account.
 
 ## Browse providers
 
 ```bash
+wallet-cli x402 update-catalog -o json
 wallet-cli x402 provider-list -o json
 wallet-cli x402 provider-show dia -o json
 wallet-cli x402 endpoint-list dia -o json
-wallet-cli x402 update-catalog -o json
 ```
 
-`provider-list` supports network, category, and capability filters. `update-catalog` refreshes the local cache.
+`update-catalog` downloads the catalog to the local cache. `provider-list`, `provider-show`, and `endpoint-list` read that cache and download from the catalog only when the cache is missing or lacks what was asked for; they never refresh it, so run `update-catalog` again when you want the latest providers and prices. `provider-list` supports `--network`, `--category`, and `--capability` filters.
 
 ## Choose an endpoint and network
 
diff --git a/docs/x402/api-catalog/index.md b/docs/x402/api-catalog/index.md
index 9a86d241..9cf05710 100644
--- a/docs/x402/api-catalog/index.md
+++ b/docs/x402/api-catalog/index.md
@@ -35,7 +35,7 @@ Three consumers share the same data:
 
 - **[Catalog website](https://bankofai.io/catalog)**: for humans to browse and compare services.
 - **wallet-cli**: search, inspect, and make paid calls from the command line.
-- **MCP**: `@bankofai/x402-mcp` lets an Agent pay for an x402 endpoint over MCP. Catalog-aware MCP discovery — browsing the catalog by name from inside an MCP client — is not shipped yet; use `wallet-cli x402 provider-list` for discovery today.
+- **MCP**: `@x402/mcp` (the official MCP integration used since SDK 2.1.0) lets an Agent pay for an x402 endpoint over MCP. Catalog-aware MCP discovery — browsing the catalog by name from inside an MCP client — is not shipped yet; use `wallet-cli x402 provider-list` for discovery today.
 
 ## What's in the catalog
 
diff --git a/docs/x402/api-catalog/list-your-service.md b/docs/x402/api-catalog/list-your-service.md
index 9a7efbca..1c84c718 100644
--- a/docs/x402/api-catalog/list-your-service.md
+++ b/docs/x402/api-catalog/list-your-service.md
@@ -163,7 +163,7 @@ Full field definitions: [Data Format & API Reference](./reference.md).
 
 ### How to write pay.md
 
-`pay.md` is read by humans and Agents alike. Three parts are recommended: basic service info, endpoint addresses and prices, and copy-paste call examples. The catalog's CI tests require every `pay.md` to contain a `wallet-cli x402 pay` example with `--network tron:728126428` and `--scheme exact`, to mention `exact_gasfree`, and to cover Base Mainnet (`eip155:8453`). The real SunPump file, `providers/sunpump-token-launch/pay.md`:
+`pay.md` is read by humans and Agents alike. Three parts are recommended: basic service info, endpoint addresses and prices, and copy-paste call examples. The catalog's CI tests require every `pay.md` to contain a `wallet-cli x402 pay` example with `--network tron:728126428` and `--scheme exact`, to mention `exact_gasfree`, and to cover Base Mainnet: the text must contain `Base Mainnet`, `eip155:8453`, a `-base` gateway provider, `USDC`, and `EIP-3009`, and must not mention `Sepolia` or `eip155:84532`. The real SunPump file, `providers/sunpump-token-launch/pay.md`:
 
 ````markdown
 # SunPump Agent Token Launch API
@@ -286,20 +286,21 @@ CI enforces the following rules — go through them before submitting:
 - `version` must be `1`.
 - `fqn` is lowercase letters/digits/hyphens and must match the directory name.
 - `category` must be one of the allowed values (see [reference](./reference.md#allowed-categories)).
-- `chains` needs at least one entry, using CAIP-2 style chain IDs. TRON IDs must be `tron:0x2b6653dc`, `tron:0xcd8690dc`, or `tron:0x94a9059e`. CI tests require every provider to list Base Mainnet `eip155:8453` and reject Base Sepolia `eip155:84532`.
+- `chains` needs at least one entry, using CAIP-2 style chain IDs. TRON IDs must be `tron:0x2b6653dc`, `tron:0xcd8690dc`, or `tron:0x94a9059e` — the decimal form (`tron:728126428`) is rejected; see [Chain IDs](./reference.md#chain-ids). CI tests require every provider to list Base Mainnet `eip155:8453` and reject Base Sepolia `eip155:84532`.
 - `isFirstParty`, `isFeatured` (booleans) and `featuredTags` (string array, may be empty `[]`) are **required** — missing any of them fails validation.
 - For every endpoint: `method` must be uppercase, `path` must start with `/`, and `maxPriceUsd` must not be less than `minPriceUsd`.
 - `serviceUrl`, every endpoint `url`, and every route `url` must start with `https://`.
 - Unknown fields are rejected — at the top level and in endpoints, routes, `i18n.<locale>`, and `status`.
 - `x402Routes` is optional in the schema, but CI tests require every endpoint to publish exactly one Base Mainnet route: `scheme` `exact`, `assetTransferMethod` `eip3009`, and a `provider` ending in `-base`. Every route's `network` must also appear in `chains`, and `exact_gasfree` is allowed only on TRON networks. Every route needs `network`, `provider`, `scheme`, and `url`; an `exact` route must also carry `assetTransferMethod` (`permit2` or `eip3009`), and an `exact_gasfree` route must **omit** it. A network may appear more than once — TRON typically publishes both an `exact` and an `exact_gasfree` route — as long as each `(provider, network, scheme, url)` combination is unique. Legacy `fee` / `feeConfig` fields are rejected. See the [reference](./reference.md#x402routes--multi-network-routing).
+- On every endpoint with TRON routes, the first TRON route must be `exact` + `permit2` (the default), and the service-level `description` — including its `i18n` translations — must not contain `--scheme exact_gasfree`.
 - The service and every endpoint must provide `i18n.zh-CN` translations for `title`, `subtitle`, `description`, and `useCase`.
-- `status`, if present, only accepts: `catalog` `listed`/`unlisted`; `gateway` `configured`/`unknown`/`unavailable`; `payment` `paid-route`/`mainnet`/`testnet`/`unknown`; `upstream` `public`/`authenticated`/`unknown`/`unavailable`.
+- `status` is optional, but if present it must include all four keys, and only accepts: `catalog` `listed`/`unlisted`; `gateway` `configured`/`unknown`/`unavailable`; `payment` `paid-route`/`mainnet`/`testnet`/`unknown`; `upstream` `public`/`authenticated`/`unknown`/`unavailable`.
 - `pay.md` must be submitted together with `catalog.json`; both files are scanned for sensitive data.
 - No keys, private keys, or private network addresses anywhere.
 
 ## Step 2: Validate locally
 
-Before submitting, install the validation dependency, then run validation, build, and the unit tests locally — the same steps CI runs:
+Before submitting, install the validation dependency, then run validation, build, and the unit tests locally — the same steps CI runs. The scripts need Python 3.11 or newer (CI uses 3.12); on 3.10 they fail with `ImportError: cannot import name 'UTC' from 'datetime'`.
 
 ```bash
 pip install -r requirements.txt
@@ -310,6 +311,10 @@ python3 -m unittest discover -s tests
 
 The first two print `validated N provider(s)` and `built N provider(s) into dist`, where N counts every provider in the repository, yours included.
 
+:::note Pinned counts in the tests
+`tests/test_build.py` pins current catalog totals, such as the number of Base Mainnet routes across all providers. A new provider that passes `validate.py` can still fail those assertions (for example `AssertionError: 20 != 18`); update the expected counts in the same PR.
+:::
+
 ## Step 3: Open the Pull Request
 
 Add the two files to the [catalog repository](https://github.com/BofAI/x402-catalog) under the matching directory, together with the regenerated `dist/` files:
diff --git a/docs/x402/api-catalog/reference.md b/docs/x402/api-catalog/reference.md
index 3eb42820..a7e99d02 100644
--- a/docs/x402/api-catalog/reference.md
+++ b/docs/x402/api-catalog/reference.md
@@ -59,7 +59,7 @@ An endpoint may serve the same capability across several chains, each settling t
 
 | Field | Type | Description |
 |---|---|---|
-| `network` | string | Canonical CAIP-2 chain ID this route settles on (e.g. `tron:0x2b6653dc`, `eip155:56`, `eip155:8453`). Legacy TRON aliases such as `tron:nile` are rejected by schema validation. |
+| `network` | string | CAIP-2 chain ID this route settles on (e.g. `tron:0x2b6653dc`, `eip155:56`, `eip155:8453`). For TRON the catalog accepts only the hexadecimal IDs listed under [Chain IDs](#chain-ids); aliases such as `tron:nile` and the decimal form `tron:728126428` are both rejected by the catalog's validation. |
 | `provider` | string | The gateway provider `fqn` that handles this network |
 | `scheme` | string | x402 payment scheme for this route: `exact` or, on TRON, `exact_gasfree` — each route declares its own |
 | `assetTransferMethod` | string | **Required** for every `exact` route: use `permit2` for TRON/BSC routes and `eip3009` for Base USDC routes. **Omit** it only on `exact_gasfree` routes. |
@@ -68,7 +68,7 @@ An endpoint may serve the same capability across several chains, each settling t
 The build passes this through to outputs as `x402_routes`. When present, callers/agents pick the route matching their intended payment chain; the top-level `url` remains the default route.
 
 :::note GasFree routes
-On TRON you can add an `exact_gasfree` route alongside the `exact` one for the same endpoint: a relayer pays the network energy and deducts its fee from the payment token, so the payer needs no TRX. GasFree routes are TRON-only and must not carry `assetTransferMethod`. Since x402 SDK 1.0.1 (current release 1.2.0) the relayer cost is estimated client-side, so catalog routes must **not** publish the legacy `fee` or `feeConfig` fields.
+On TRON you can add an `exact_gasfree` route alongside the `exact` one for the same endpoint: a relayer pays the network energy and deducts its fee from the payment token, so the payer needs no TRX. GasFree routes are TRON-only and must not carry `assetTransferMethod`. Since x402 SDK 1.0.1 the relayer cost is estimated client-side, so catalog routes must **not** publish the legacy `fee` or `feeConfig` fields.
 :::
 
 For example, an endpoint may expose one route per supported chain — TRON Mainnet, BSC Mainnet, and Base Mainnet — each with its own `provider` and `scheme`. To call one, point `wallet-cli x402 pay` at the chosen route's `url` and pass the matching `--network` / `--scheme`:
@@ -88,7 +88,7 @@ The other routes reuse the same request body, swapping only the route `url`, `--
 
 ### status block
 
-`status` is optional and describes the state of each stage of the service, with four keys: `catalog` / `gateway` / `payment` / `upstream`. When omitted, the build output (service detail) fills in defaults automatically:
+`status` is optional and describes the state of each stage of the service, with four keys: `catalog` / `gateway` / `payment` / `upstream`. When present, all four keys are required. When omitted, the build output (service detail) fills in defaults automatically:
 
 ```json
 { "catalog": "listed", "gateway": "unknown", "payment": "unknown", "upstream": "unknown" }
@@ -105,7 +105,7 @@ Allowed values:
 
 ## pay.md
 
-Submitted alongside `catalog.json` in the same directory — a human- and Agent-readable call guide, and a **required** file. Recommended contents: basic service info (FQN, entry address, category, settlement chains), each endpoint's address and price, plus copy-paste call examples. The catalog's CI tests currently require a `wallet-cli x402 pay` example with `--network tron:728126428` and `--scheme exact`, a mention of `exact_gasfree`, and Base Mainnet (`eip155:8453`) coverage. Like `catalog.json`, this file goes through the sensitive-data scan (see below).
+Submitted alongside `catalog.json` in the same directory — a human- and Agent-readable call guide, and a **required** file. Recommended contents: basic service info (FQN, entry address, category, settlement chains), each endpoint's address and price, plus copy-paste call examples. The catalog's CI tests currently require a `wallet-cli x402 pay` example with `--network tron:728126428` and `--scheme exact`, a mention of `exact_gasfree`, and Base Mainnet coverage (the strings `Base Mainnet`, `eip155:8453`, `-base`, `USDC`, and `EIP-3009`, with no `Sepolia` or `eip155:84532`). Like `catalog.json`, this file goes through the sensitive-data scan (see below).
 
 ## Allowed categories
 
@@ -122,6 +122,10 @@ security   shopping    storage     translation
 
 `chains` uses CAIP-2 style chain identifiers. Mainnets and testnets are both recognized:
 
+:::note TRON ID format
+The catalog schema accepts TRON chains only in the hexadecimal form below. The x402 SDK (since 2.0.0) and Wallet CLI use the decimal CAIP-2 IDs — `tron:728126428` (mainnet), `tron:3448148188` (Nile), `tron:2494104990` (Shasta). The SDK still accepts the hexadecimal values as deprecated aliases of the same chains; Wallet CLI's global `--network` (used by `x402 pay` and account commands) does not — use the decimal ID or an alias such as `tron`, `nile` or `shasta`; only the catalog filter `x402 provider-list --network` also accepts the hex form. That is why the CLI examples pass `--network tron:728126428` while `catalog.json` lists `tron:0x2b6653dc`.
+:::
+
 | Chain | ID |
 |---|---|
 | TRON mainnet | `tron:0x2b6653dc` |
@@ -214,6 +218,8 @@ These are additive — the raw `title`, `subtitle`, `category`, `chains`, and `i
 
 ## Local build and run
 
+Requires Python 3.11 or newer.
+
 ```bash
 # install the validation dependency (jsonschema)
 pip install -r requirements.txt
diff --git a/docs/x402/core-concepts/OfficialFacilitator.md b/docs/x402/core-concepts/OfficialFacilitator.md
index 76058d44..c6f736ac 100644
--- a/docs/x402/core-concepts/OfficialFacilitator.md
+++ b/docs/x402/core-concepts/OfficialFacilitator.md
@@ -56,11 +56,13 @@ Official Facilitator supports **two calling modes**.
 
 | Mode | Rate Limit | Description |
 |-----|-----|-----|
-| **Anonymous Mode** | Official service: 1 request per IP per minute. Self-hosted deployments default to 10 requests per IP per minute when `rate_limit.anonymous` is omitted (configurable). | No API Key required, suitable for local development and functional testing |
-| **API Key Mode** | Official service: 1000 requests per API Key per minute. Self-hosted deployments use the same default when `rate_limit.authenticated` is omitted (configurable). | API Key required, suitable for production environments and high-frequency payment requests |
+| **Anonymous Mode** | Official service: 10 requests per IP per minute, counted separately for `/verify` and `/settle`. This is also the self-hosted default when `rate_limit.anonymous` is omitted (configurable). | No API Key required, suitable for local development and functional testing |
+| **API Key Mode** | Official service: 1000 requests per API Key per minute, counted separately for `/verify` and `/settle`. Self-hosted deployments use the same default when `rate_limit.authenticated` is omitted (configurable). | API Key required, suitable for production environments and high-frequency payment requests |
 
 The calling methods for both modes are exactly the same, but they differ in **identity recognition and interface rate limiting strategies**.
 
+> **Counters are per instance.** The official production config uses `rate_limit.store: memory`, so each facilitator instance keeps its own counters; requests that land on different instances are not counted against one shared total. Self-hosted deployments default to the same in-memory store — set `rate_limit.store: redis` (with `redis_url`) to share counters across replicas.
+
 ---
 
 ### Anonymous Calling Mode
@@ -69,8 +71,8 @@ If the request **does not carry an API Key**, the Facilitator will treat the req
 
 In anonymous mode:
 
-- The `/settle` interface is **rate-limited**
-- The **official service allows 1 request per IP per minute**. Self-hosted deployments default to **10 requests per IP per minute** when `rate_limit.anonymous` is omitted; this limit is configurable.
+- The `/verify` and `/settle` interfaces are **rate-limited**, each with its own counter
+- The **official service allows 10 requests per IP per minute** on each of them — the same as the self-hosted default when `rate_limit.anonymous` is omitted; this limit is configurable.
 
 This mode is mainly used for:
 
@@ -87,7 +89,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
   -d '{ ... }'
 ```
 
-Although anonymous mode can call all core interfaces normally, due to the very low call frequency of `/settle`, it is **not suitable for production environments**.
+Although anonymous mode can call all core interfaces normally, due to the low per-IP limit on `/verify` and `/settle`, it is **not suitable for production environments**.
 
 If your application needs to handle real user payments or higher frequency requests, it is recommended to use **API Key calling mode**.
 
@@ -112,7 +114,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
 
 When the Facilitator recognizes the API Key:
 
-- On the official service, the `/settle` limit increases to **1000 requests per API Key per minute**
+- On the official service, the `/verify` and `/settle` limits each increase to **1000 requests per API Key per minute**
 
 This means your service can support **production-level payment throughput**.
 
@@ -246,23 +248,31 @@ After clicking **"Confirm"**, you will return to the Dashboard page, and the API
 |------|------|------|
 | GET | `/health` | Service health check |
 | GET | `/supported` | Query supported payment capabilities and configurations |
-| POST | `/verify` | Verify payment payload validity |
+| POST | `/verify` | Verify payment payload validity (**rate-limited**) |
 | POST | `/settle` | Perform on-chain settlement (**rate-limited**)|
 | GET | `/payments/tx/{tx_hash}` | Query payment records by settlement transaction hash |
 | GET | `/payments?network=&nonce=[&asset=&payer=]` | Query payment records by the on-chain authorization identity |
 | GET | `/payments` | Authenticated seller's settlement feed (`?limit=&offset=`; `limit` defaults to `50` and is capped at `200` — a larger value is silently reduced to `200`, not rejected; `offset` defaults to `0`) |
+| GET | `/sponsoring/ready` | TRON approval resource sponsoring readiness (`?network=` checks one network); HTTP `200` when ready, `503` otherwise (booting, recovering, degraded, or sponsoring disabled) |
 
-> There is **no** `/fee/quote` endpoint, and the schemes carry no facilitator fee. Rate limiting only applies to the `/settle` interface; other interfaces are not affected by rate limiting.
+> There is **no** `/fee/quote` endpoint, and the schemes carry no facilitator fee. Rate limiting applies to `/verify` and `/settle` (separate counters); other interfaces are not rate-limited. A request over the limit receives HTTP `429` with `{"error":"rate_limit_exceeded"}` and a `Retry-After` header.
 
 ### Networks and schemes the official service settles
 
 | Network | Environment |
 |---|---|
-| `tron:0x2b6653dc` (TRON Mainnet) · `tron:0xcd8690dc` (Nile) | mainnet · testnet |
+| `tron:728126428` (TRON Mainnet) · `tron:3448148188` (Nile) | mainnet · testnet |
 | `eip155:56` (BSC) · `eip155:97` (BSC testnet) | mainnet · testnet |
 | `eip155:8453` (Base) · `eip155:84532` (Base Sepolia) | mainnet · testnet |
 
-Each of these networks registers `exact`, `upto`, and `batch-settlement`; TRON additionally registers `exact_gasfree` where the service holds GasFree relayer credentials (TRON Mainnet and Nile). Query `/supported` for the authoritative list of the deployment you are pointing at. The official facilitator does not currently enable the `trc20ApprovalResourceSponsoring` extension — TRON approval resource sponsoring requires a self-hosted facilitator. On its EVM networks (BSC and Base) it does register the ERC-20 approval gas-sponsoring extension for every EVM network it serves — but sponsoring only kicks in when the resource server declares that extension on the route.
+Each of these networks registers `exact`, `upto`, and `batch-settlement`; TRON additionally registers `exact_gasfree` where the service holds GasFree relayer credentials (TRON Mainnet and Nile). Query `/supported` for the authoritative list of the deployment you are pointing at. TRON networks are reported with decimal CAIP-2 identifiers; the older hex forms (`tron:0x2b6653dc`, `tron:0xcd8690dc`) are still accepted as input aliases.
+
+`/supported` lists two extensions:
+
+- `erc20ApprovalGasSponsoring` — registered for every EVM network the service serves (BSC and Base).
+- `trc20ApprovalResourceSponsoring` — TRON approval resource sponsoring is enabled **on Nile only**, for the configured asset (Nile USDT), and **requires an API Key**. An anonymous request that carries the extension is rejected with `sponsor_auth_required`; an authenticated request for TRON Mainnet is rejected with `sponsor_network_disabled`. `GET /sponsoring/ready` reports whether the sponsoring runtime is ready.
+
+Either sponsorship only kicks in when the resource server declares the extension on the route.
 
 ### Payment Record Query
 
@@ -282,7 +292,7 @@ The `/payments/tx/{tx_hash}` and `/payments?network=&nonce=[&asset=&payer=]` int
 > When an API Key is provided, these interfaces only return payment records associated with your account; you will not see data from other sellers.
 
 :::danger Without an API Key
-The `tx_hash` and `network` + `nonce` lookups add **no seller filter** when the request is anonymous, so the response may include records bound to a seller — anyone holding an exact identifier can resolve the corresponding record. The `/payments` list endpoint still requires authentication, so there is no unauthenticated listing endpoint; but these lookups are not rate-limited either (the official service's 1-request-per-IP-per-minute anonymous limit covers `/settle` only), and settlement tx hashes are public on-chain data. Treat settlement metadata as effectively public rather than seller-private.
+The `tx_hash` and `network` + `nonce` lookups add **no seller filter** when the request is anonymous, so the response may include records bound to a seller — anyone holding an exact identifier can resolve the corresponding record. The `/payments` list endpoint still requires authentication, so there is no unauthenticated listing endpoint; but these lookups are not rate-limited either (the official service's 10-requests-per-IP-per-minute anonymous limit covers `/verify` and `/settle` only), and settlement tx hashes are public on-chain data. Treat settlement metadata as effectively public rather than seller-private.
 
 **This describes the current implementation, not a recommended access-control policy.** Send your API Key to keep queries scoped to your own account, and never treat a settlement tx hash or its nonce as a secret.
 :::
@@ -293,7 +303,7 @@ The `tx_hash` and `network` + `nonce` lookups add **no seller filter** when the
 
 **Q: Can it run normally without configuring an API Key?**
 
-Yes, it can run, but the official service limits `/settle` to 1 request per IP per minute. A self-hosted deployment defaults to 10 requests per IP per minute when `rate_limit.anonymous` is omitted, and that limit is configurable. Anonymous access is only suitable for testing; any real traffic must be configured with an API Key.
+Yes, it can run, but the official service limits `/verify` and `/settle` to 10 requests per IP per minute each — the same as the self-hosted default when `rate_limit.anonymous` is omitted, which is configurable. Anonymous access is only suitable for testing; any real traffic must be configured with an API Key.
 
 **Q: Does the API Key expire?**
 
@@ -301,7 +311,7 @@ Currently, API Keys do not actively expire, but if you actively delete and recre
 
 **Q: Can I use the same API Key for multiple projects?**
 
-Yes, the same API Key can be reused across multiple service instances. On the official service, those instances share that Key's limit of 1000 `/settle` requests per minute; the quota does not reset for each server using the Key.
+Yes, the same API Key can be reused across multiple service instances. On the official service the limit is keyed by API Key, not by calling server: your instances draw on the same 1000 `/settle` requests per minute (and a separate 1000 for `/verify`) rather than each getting its own quota. Those counters are kept per facilitator instance (`rate_limit.store: memory`), so the limit applies within each facilitator instance, not as one global total.
 
 **Q: I want to change my API Key, how do I do it?**
 
diff --git a/docs/x402/core-concepts/client-server.md b/docs/x402/core-concepts/client-server.md
index 6f8dab46..7b561731 100644
--- a/docs/x402/core-concepts/client-server.md
+++ b/docs/x402/core-concepts/client-server.md
@@ -25,7 +25,7 @@ Clients can take many forms, including:
 
 - **Initiate Requests**: Send the initial HTTP request to the resource server.
 - **Handle Payment Requirements**: Parse the `402 Payment Required` response and extract payment details.
-- **Manage Token Approvals**: Authorize Permit2 (one-time `approve(Permit2)`) for plain ERC-20/TRC-20 tokens; ERC-3009 tokens need no approve. Who broadcasts it differs by chain. **On TRON** the client auto-broadcasts the approve on first payment, paying the Energy itself — unless the server advertises the `trc20ApprovalResourceSponsoring` extension (SDK 1.2.0+), in which case the client signs it **without broadcasting** and the facilitator sponsors the Energy/Bandwidth and broadcasts it. **On EVM the client never broadcasts anything**: it either attaches a signed, unbroadcast approve for the facilitator to relay (when the server advertises `eip2612GasSponsoring` or `erc20ApprovalGasSponsoring`), or, with no such extension declared, verification fails with `permit2_allowance_required` and the allowance must be granted once out of band before the first payment. See [SDK Feature Matrix](../sdk-features.md#extensions).
+- **Manage Token Approvals**: Authorize Permit2 (one-time `approve(Permit2)`) for plain ERC-20/TRC-20 tokens; ERC-3009 tokens need no approve. Who broadcasts it differs by chain. **On TRON** the client auto-broadcasts the approve on first payment, paying the Energy itself (with the default `allowanceMode: "auto"`; `"skip"` leaves the approval to your app) — unless the server advertises the `trc20ApprovalResourceSponsoring` extension, in which case the client signs it **without broadcasting** and the facilitator sponsors the Energy/Bandwidth and broadcasts it. Since 2.1.0 this needs the client extension from `@bankofai/x402-tron-extensions` registered with `client.registerExtension(createTrc20ApprovalResourceSponsoringClientExtension(signer))`; without it, a sponsored payment fails with `trc20_approval_client_extension_not_registered` instead of falling back to a client broadcast. **On EVM the client never broadcasts anything**: it either attaches an off-chain EIP-2612 permit signature (when the server advertises `eip2612GasSponsoring`) or a signed, unbroadcast approve transaction for the facilitator to relay (`erc20ApprovalGasSponsoring`), or, with no such extension declared, verification fails with `permit2_allowance_required` and the allowance must be granted once out of band before the first payment. See [SDK Feature Matrix](../sdk-features.md#extensions).
 - **Prepare Payment Payload**: Construct and sign a payment payload according to server requirements.
 - **Retry with Payment**: Attach the `PAYMENT-SIGNATURE` header and resend the request.
 
@@ -45,7 +45,7 @@ Servers may include:
 
 ### Core Responsibilities
 
-- **Define Payment Requirements**: Respond with HTTP `402 Payment Required` when a request lacks valid payment credentials, detailing payment requirements in the response body.
+- **Define Payment Requirements**: Respond with HTTP `402 Payment Required` when a request lacks valid payment credentials, detailing payment requirements in the Base64-encoded `PAYMENT-REQUIRED` response header (the body is `{}` by default).
 - **Validate Payment Payload**: Call the Facilitator service to verify the incoming signed payload.
 - **Settle Transactions**: Upon successful validation, submit the transaction via the Facilitator to complete on-chain settlement.
 - **Deliver Resources**: After confirming payment, return the requested resource to the client.
@@ -72,6 +72,8 @@ In the x402 protocol, a typical interaction between client and server proceeds a
   }}
 />
 
+The diagram shows the order the client observes: the resource arrives after settlement. Under the default `authorization` flow the server runs its handler before settling and releases the response only once settlement succeeds (step 5 above).
+
 ---
 
 ## Summary
diff --git a/docs/x402/core-concepts/facilitator.md b/docs/x402/core-concepts/facilitator.md
index 66e7d7b3..7730e534 100644
--- a/docs/x402/core-concepts/facilitator.md
+++ b/docs/x402/core-concepts/facilitator.md
@@ -19,7 +19,7 @@ By introducing a Facilitator, servers no longer need to maintain direct connecti
 
 - **Payment Verification**: Ensures that the signed payload strictly complies with the server's declared payment requirements.
 - **Payment Settlement**: Submits validated transactions to the blockchain and monitors their confirmation status.
-- **Settlement Records**: Persists one row per settle attempt — the store applies no de-duplication and holds no unique constraint, so failures and retries accumulate. At most one *successful* row exists per authorization identity in practice, because on-chain replay protection lets a given authorization settle only once. It also answers record queries, seller-scoped when the caller authenticates. A save failure is logged but never changes the `/settle` response.
+- **Settlement Records**: Persists one row for each settle attempt that reaches a result from the settle mechanism — success or failure — so failed attempts and retries accumulate. Requests rejected before or around settlement get no row: malformed bodies (400), sponsoring-access rejections (403/503), Permit2 replay-guard errors, and internal errors (500). A partial unique index on (`network`, `asset`, `payer`, `nonce`) where `status = 'success'` allows at most one *successful* row per authorization, complementing on-chain replay protection, which lets a given authorization settle only once. It also answers record queries, seller-scoped when the caller authenticates. A save failure is logged but never changes the `/settle` response.
 - **Result Feedback**: Returns verification and settlement results to the server, enabling it to decide whether to deliver the requested resource.
 
 > **Note**: The Facilitator **does not custody funds** and does not act as an escrow. It only executes verification and on-chain operations according to the client's signed authorization.
@@ -31,7 +31,7 @@ Integrating a Facilitator provides significant advantages:
 - **Reduced Operational Overhead**: Servers do not need to directly manage blockchain nodes or RPC infrastructure.
 - **Protocol Standardization**: Ensures consistent payment verification and settlement processes across services.
 - **Fast Integration**: Servers can begin accepting payments with minimal blockchain development effort.
-- **Resource Fee Management**: The Facilitator covers transaction execution costs such as TRX (Energy and Bandwidth) / BNB, reducing the operational burden on the server. Since SDK 1.2.0 a TRON Facilitator may additionally opt into the `trc20ApprovalResourceSponsoring` extension, temporarily delegating its own Stake 2.0 Energy — and, when needed, Bandwidth — to the payer so the payer's first `approve(Permit2)` costs them no TRX. This is opt-in: the Facilitator must register the sponsoring runtime together with a bounded sponsorship policy and a durable operation coordinator. Either way the resource server must also declare the extension on the route — that declaration is what makes an SDK client attach the sponsoring payload (the Facilitator itself does not check it, so a non-SDK client could skip that step). EVM networks have an equivalent capability — sponsoring the payer's ERC-20 `approve` gas — but the SDK does not wire it up for you: a self-hosted Facilitator must register the extension itself. The official Facilitator registers it for the EVM networks it serves; see [Official Facilitator](./OfficialFacilitator.md).
+- **Resource Fee Management**: The Facilitator covers transaction execution costs such as TRX (Energy and Bandwidth) / BNB, reducing the operational burden on the server. Since SDK 1.2.0 a TRON Facilitator may additionally opt into the `trc20ApprovalResourceSponsoring` extension, temporarily delegating its own Stake 2.0 Energy — and, when needed, Bandwidth — to the payer so the payer's first `approve(Permit2)` costs them no TRX. This is opt-in: the Facilitator must register the sponsoring runtime together with a bounded sponsorship policy and a durable operation coordinator. Either way the resource server must also declare the extension on the route — that declaration is what makes an SDK client attach the sponsoring payload (the Facilitator itself does not check it, so a non-SDK client could skip that step). EVM networks have an equivalent capability — sponsoring the payer's ERC-20 `approve` gas — but the SDK does not wire it up for you: a self-hosted Facilitator must register the extension itself. The official Facilitator registers it for the EVM networks it serves, and enables TRON approval resource sponsoring on Nile for API Key holders; see [Official Facilitator](./OfficialFacilitator.md).
 
 Although developers may implement verification and settlement logic locally, using a Facilitator significantly accelerates development and ensures protocol-compliant implementation.
 
@@ -74,7 +74,7 @@ Quick usage examples can be found in [OfficialFacilitator](./OfficialFacilitator
 If you need full control over the settlement wallet, RPC endpoints, energy management, or which networks and schemes are registered — or you have specific privacy or compliance requirements — you can deploy your own Facilitator service.
 
 > ⚠️ **Self-hosting security notes:**
-> - A self-hosted Facilitator needs a **dedicated funded wallet** to pay blockchain transaction fees. It is resolved through `@bankofai/agent-wallet` and unlocked out-of-band (for example `AGENT_WALLET_PASSWORD`) — the raw private key never enters the service process
+> - A self-hosted Facilitator needs a **dedicated funded wallet** to pay blockchain transaction fees. It is resolved through `@bankofai/agent-wallet` v3: with the `privy` or `wallet_cli` provider the key stays outside the service process; the `raw_secret` provider keeps a plaintext key in its config and is for development only
 > - **This Facilitator wallet should be separate from your payment recipient wallet** — create a new wallet specifically for this purpose
 > - Only deposit a small amount of tokens into the Facilitator wallet (enough for fees); do not store large amounts
 > - Never place a raw private key in `.env`, a config file, or a shell command — **and never upload wallet material to GitHub or share it with anyone**
@@ -91,30 +91,35 @@ Whether using the official service or a self-hosted instance, the Facilitator pr
 |--------|------|-------------|
 | GET | `/health` | Liveness check |
 | GET | `/supported` | Supported payment capabilities and configuration |
-| POST | `/verify` | Verify payment payload validity |
+| POST | `/verify` | Verify payment payload validity (**rate-limited**, see below) |
 | POST | `/settle` | Execute on-chain settlement (**rate-limited**, see below); persists a settlement record |
 | GET | `/payments/tx/{tx_hash}` | Query payment records by settlement transaction hash (seller-scoped when authenticated) |
 | GET | `/payments?network=&nonce=[&asset=&payer=]` | Query payment records by the on-chain authorization identity (seller-scoped when authenticated) |
 | GET | `/payments` | Authenticated seller's settlement feed (`?limit=&offset=`; `limit` defaults to `50` and is capped at `200` — a larger value is silently reduced to `200`, not rejected; `offset` defaults to `0`) |
+| GET | `/sponsoring/ready` | TRON approval resource sponsoring readiness (`?network=` checks one network); HTTP `200` when ready, `503` otherwise (booting, recovering, degraded, or sponsoring disabled) |
 | GET | `/metrics` | Prometheus metrics (operational; exposed on the main port only when monitoring shares it) |
 | ALL | `/mainnet/*` · `/nile/*` | GasFree Open API transparent proxy (HMAC-signed) — used internally by the TRON `exact_gasfree` scheme |
 
 Record-query failures use these codes: `404 not_found` when no record matches, `400 invalid_identity_query` for a partial identity query (any of `network`/`nonce`/`asset`/`payer` without the required `network`+`nonce` pair), and `400 missing_identity_or_auth` when `/payments` is called with neither identity parameters nor an API Key.
 
+`/verify` and `/settle` keep the x402 response shape (`invalidReason` / `errorReason`). Besides the SDK's own reasons, the service returns: `400 invalid_json` or `missing_parameters` for a malformed body; `413` `{"code":"body_too_large","message":…}` (default limit 1 MiB); `429` `{"error":"rate_limit_exceeded"}`; `403 sponsor_auth_required`, `sponsor_network_disabled` or `sponsor_pay_to_invalid` when a request carries `trc20ApprovalResourceSponsoring` that the deployment will not sponsor; and `503` with `Retry-After` for transient conditions (`sponsor_owner_busy`, `sponsor_recovery_in_progress`, `sponsor_storage_unavailable`, and on `/settle` only `permit2_authorization_busy`, `permit2_storage_unavailable`, `permit2_nonce_check_unavailable`). On `/settle`, a Permit2 authorization whose nonce is already consumed fails with `permit2_nonce_consumed` (HTTP 200) without broadcasting a new transaction; a malformed one fails `/settle` with `400 permit2_invalid_authorization`. Sponsored approvals can also fail at the protocol level (HTTP 200, in `invalidReason` / `errorReason`): `approval_transaction_reused` (the signed approve was already used for a different payment request), `sponsor_approval_lifetime_exceeded` (the signed approve is valid for longer than 630 seconds) and, on `/settle` only, `sponsor_existing_delegation`. An unexpected failure returns `500 internal_error`. The GasFree proxy is served only under `/mainnet` and `/nile` (any other path gets a plain `404`), and answers `502 bad_gateway` when the upstream fails or its response is too large.
+
 > There is **no** `/fee/quote` endpoint, and the schemes carry no facilitator fee at all. Payment records are keyed on the on-chain authorization identity (`network` + `scheme` + `asset` + `payer` + `nonce`), not a client-supplied payment ID.
 
 ---
 
 ## Rate Limiting
 
-The `/settle` endpoint enforces dynamic rate limits based on the caller's authentication status:
+The `/verify` and `/settle` endpoints enforce dynamic rate limits based on the caller's authentication status, with a separate counter for each endpoint:
 
 | Mode | Rate Limit | How to Authenticate |
 |------|------------|---------------------|
-| **Authenticated** | Official service: 1000 requests per API Key per minute. Self-hosted deployments use the same default when `rate_limit.authenticated` is omitted (configurable). | Include `X-API-KEY: <your_key>` header |
-| **Anonymous** | Official service: 1 request per IP per minute. Self-hosted deployments default to 10 requests per IP per minute when `rate_limit.anonymous` is omitted (configurable). | No API Key provided |
+| **Authenticated** | Official service: 1000 requests per API Key per minute, counted separately for `/verify` and `/settle`. Self-hosted deployments use the same default when `rate_limit.authenticated` is omitted (configurable). | Include `X-API-KEY: <your_key>` header |
+| **Anonymous** | Official service: 10 requests per IP per minute, counted separately for `/verify` and `/settle`. This is also the self-hosted default when `rate_limit.anonymous` is omitted (configurable). | No API Key provided |
+
+Other endpoints (`/supported`, `/payments/*`, `/sponsoring/ready`, `/health`) are not rate-limited. Over the limit, the response is HTTP `429` `{"error":"rate_limit_exceeded"}` with a `Retry-After` header.
 
-Other endpoints (`/verify`, `/supported`, `/payments/*`) are not individually rate-limited.
+> **Counters are per instance.** The official production config uses `rate_limit.store: memory`, so each facilitator instance keeps its own counters; requests that land on different instances are not counted against one shared total. Self-hosted deployments default to the same in-memory store — set `rate_limit.store: redis` (with `redis_url`) to share counters across replicas.
 
 > **Tip**: For any production workload, apply for an API Key via the [Admin Portal](https://admin-facilitator.bankofai.io) to unlock the higher rate limit.
 
@@ -132,7 +137,7 @@ How access currently behaves:
 - **With a valid `X-API-KEY`** — results are filtered to the seller that key belongs to.
 - **Anonymous `tx_hash` or `network` + `nonce` lookup** — the current implementation adds **no seller filter**, so the response may include records that are bound to a seller.
 - **The `/payments` list endpoint** — still requires authentication: with no identity parameters and no API Key it returns `400`, and a partial identity query returns `400` rather than degrading into a feed.
-- **No rate limit on these lookups** — the official service's 1-request-per-IP-per-minute anonymous limit applies to `/settle` only; the record-query endpoints are not individually rate-limited.
+- **No rate limit on these lookups** — the official service's anonymous limit applies to `/verify` and `/settle` only; the record-query endpoints are not individually rate-limited.
 
 Settlement tx hashes are public on-chain data, and the `network` + `nonce` lookup additionally resolves **failed** settlements — including pre-broadcast failures, which carry no tx hash at all and so cannot be reached any other way. The practical consequence is that **settlement metadata should be treated as effectively public**, even though no unauthenticated listing endpoint exists. The response body never includes the seller id, so what a lookup exposes is the payment metadata of a seller-bound record, not seller attribution.
 
diff --git a/docs/x402/core-concepts/gateway.md b/docs/x402/core-concepts/gateway.md
index 6e5fdc83..58105b61 100644
--- a/docs/x402/core-concepts/gateway.md
+++ b/docs/x402/core-concepts/gateway.md
@@ -74,7 +74,7 @@ Providers turn calls into cash flow. Agents turn calls into capabilities. The ga
 
 ### For AI Agents: one catalog, many APIs, pay as you go
 
-- **CLI discovery today** — `wallet-cli x402 provider-list` / `provider-show` / `endpoint-list` find the right API and its routes. Paying over MCP is supported via `@bankofai/x402-mcp`; catalog-aware MCP discovery is not shipped yet.
+- **CLI discovery today** — `wallet-cli x402 provider-list` / `provider-show` / `endpoint-list` find the right API and its routes. Paying over MCP is supported via `@x402/mcp`; catalog-aware MCP discovery is not shipped yet.
 - **Per-call pricing** — no subscriptions, no minimums.
 - **Live price transparency** — the gateway returns the computed price in its `402` response, and the client's authorization binds the selected payment requirement. The quote itself is not a gateway cryptographic signature.
 - **No accounts, no keys** — your wallet is your identity; nothing to register or manage.
diff --git a/docs/x402/core-concepts/http-402.md b/docs/x402/core-concepts/http-402.md
index 8666d91f..83bbb491 100644
--- a/docs/x402/core-concepts/http-402.md
+++ b/docs/x402/core-concepts/http-402.md
@@ -49,13 +49,13 @@ When the server returns a `402 Payment Required` response, the decoded `PAYMENT-
   "error": "Payment required",
   "resource": {
     "url": "http://example.com/protected",
-    "description": null,
-    "mimeType": null
+    "description": "",
+    "mimeType": ""
   },
   "accepts": [
     {
       "scheme": "exact",
-      "network": "tron:0xcd8690dc",
+      "network": "tron:3448148188",
       "amount": "100",
       "asset": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
       "payTo": "<SELLER_TRON_ADDRESS>",
@@ -79,8 +79,8 @@ When the server returns a `402 Payment Required` response, the decoded `PAYMENT-
   "error": "Payment required",
   "resource": {
     "url": "http://example.com/protected",
-    "description": null,
-    "mimeType": null
+    "description": "",
+    "mimeType": ""
   },
   "accepts": [
     {
@@ -124,12 +124,12 @@ When the server returns a `402 Payment Required` response, the decoded `PAYMENT-
 | `resource`          | Information about the requested resource                                    |
 | `accepts`           | Array of accepted payment options                                           |
 | `scheme`            | Payment scheme (`exact`, `upto`, `batch-settlement`, or `exact_gasfree`)  |
-| `network`           | Network identifier — the three TRON IDs (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) or any `eip155:<chainId>`: a resource server registers `eip155:*` by default, so this field is not limited to `eip155:56` / `97` / `8453` / `84532`. Settlement is bounded separately by the networks the facilitator has configured  |
+| `network`           | Network identifier — the three TRON IDs (`tron:728126428`, `tron:3448148188`, `tron:2494104990`) or any `eip155:<chainId>`: a resource server registers `eip155:*` by default, so this field is not limited to `eip155:56` / `97` / `8453` / `84532`. Settlement is bounded separately by the networks the facilitator has configured  |
 | `amount`            | Payment amount in the smallest unit (e.g., 100 = 0.0001 USDT)              |
 | `asset`             | TRC-20/BEP-20 token contract address                                        |
 | `payTo`             | Seller's wallet address                                                     |
 | `maxTimeoutSeconds` | Maximum validity duration of the payment                                    |
-| `extra`             | Scheme-specific data — `assetTransferMethod` (`eip3009` / `permit2`), the token `name`/`version` for EIP-3009 assets and for permit2 assets that also support EIP-2612, and, for a scheme that declares a non-default payment flow, `paymentFlow` (`upfront` or `escrow`) — every built-in scheme uses the default `authorization` flow, which is omitted from `extra`. It carries no fee object: the schemes take no facilitator fee. |
+| `extra`             | Scheme-specific data — `assetTransferMethod` (`eip3009` / `permit2`), the token `name`/`version` for EIP-3009 assets and for permit2 assets that also support EIP-2612, and, when a route selects a non-default payment flow, `paymentFlow` (`upfront` or `escrow`) — the default `authorization` flow is omitted from `extra`. TRON schemes and EVM `upto` / `batch-settlement` support only `authorization`; EVM `exact` also supports `upfront`. It carries no fee object: the schemes take no facilitator fee. |
 | `extensions`        | Additional context for the payment scheme (e.g., EVM gas-sponsoring, TRON `trc20ApprovalResourceSponsoring`, payment-identifier) |
 
 ## Payment Signature Structure
@@ -144,7 +144,7 @@ The client responds via the `PAYMENT-SIGNATURE` header with a signed payload:
   "x402Version": 2,
   "accepted": {
     "scheme": "exact",
-    "network": "tron:0xcd8690dc",
+    "network": "tron:3448148188",
     "asset": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
     "amount": "100",
     "payTo": "<SELLER_TRON_ADDRESS>",
diff --git a/docs/x402/core-concepts/network-and-token-support.md b/docs/x402/core-concepts/network-and-token-support.md
index ee2fa15b..e965658d 100644
--- a/docs/x402/core-concepts/network-and-token-support.md
+++ b/docs/x402/core-concepts/network-and-token-support.md
@@ -7,8 +7,8 @@ import TabItem from '@theme/TabItem';
 
 ## TRON Network Identifiers
 
-x402 adopts the CAIP-2 network identifier format `tron:<hex_chain_id>`.
-Use the exported constants from `@bankofai/x402-tron` (`TRON_MAINNET`, `TRON_NILE`, `TRON_SHASTA`) in application code instead of copying opaque hex strings.
+x402 adopts the CAIP-2 network identifier format `tron:<decimal_chain_id>`.
+Use the exported constants from `@bankofai/x402-tron` (`TRON_MAINNET`, `TRON_NILE`, `TRON_SHASTA`) in application code instead of copying identifier strings.
 
 ### Identifier Reference
 
@@ -18,7 +18,7 @@ Use the exported constants from `@bankofai/x402-tron` (`TRON_MAINNET`, `TRON_NIL
 | **TRON Shasta**  | `tron:2494104990`  | `TRON_SHASTA`  | TRON Shasta Testnet |
 | **TRON Nile**    | `tron:3448148188`  | `TRON_NILE`    | TRON Nile Testnet |
 
-> **TRON ID format**: since `@bankofai/x402-tron` 2.0.0 the SDK constants use decimal CAIP-2 references. The older hexadecimal forms (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) are still accepted as input aliases, and are what the official facilitator and the API catalog currently report.
+> **TRON ID format**: since `@bankofai/x402-tron` 2.0.0 the SDK constants use decimal CAIP-2 references. The older hexadecimal forms (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) are still accepted as input aliases and are normalized to the decimal form. The official facilitator reports the decimal identifiers in `/supported`; the API Catalog still lists the hexadecimal forms.
 
 ---
 
@@ -31,7 +31,7 @@ In the x402 protocol (on-the-wire), BSC uses the EIP-155 chain ID format:
 | **BSC Mainnet**  | `eip155:56`   | BSC Mainnet (Production)      |
 | **BSC Testnet**  | `eip155:97`   | BSC Testnet (Chapel)          |
 
-> **Note**: A self-hosted Facilitator's YAML config takes **canonical CAIP-2 identifiers only** — `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532`, `tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`. Friendly aliases such as `bsc:mainnet` or `tron:nile` are not resolved and are rejected at startup.
+> **Note**: A self-hosted Facilitator's YAML config takes **canonical CAIP-2 identifiers only** — `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532`, `tron:728126428`, `tron:3448148188`, `tron:2494104990`. Deprecated hexadecimal TRON IDs (`tron:0x…`) are still accepted and normalized to decimal. Friendly aliases such as `bsc:mainnet` or `tron:nile` are not resolved and are rejected at startup.
 
 ---
 
@@ -81,18 +81,17 @@ x402 supports **TRC-20, BEP-20, and ERC-20** tokens. TRON/BSC routes use their c
 | **USDD** | `tron:728126428` | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` |
 | **USDD** | `tron:3448148188`    | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` |
 | **USDT** | `eip155:56`    | `0x55d398326f99059fF775485246999027B3197955` |
-| **USDC** | `eip155:56`    | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
+| **USDC** | `eip155:56`    | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` (not in any shipped token registry — explicit asset only) |
 | **USDT** | `eip155:97`    | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
 | **USDC** | `eip155:97`    | `0x64544969ed7EBf5f083679233325356EbE738930` |
-| **DHLU** | `eip155:97`    | `0x375cADdd2cB68cE82e3D9B075D551067a7b4B816` |
 | **USDC** | `eip155:8453`  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 | **USDC** | `eip155:84532` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 
-> **Default assets vs. opt-in assets (SDK 1.1.0+)**: the default-asset registry resolves **USDT** on TRON (`tron:728126428`, `tron:3448148188`, `tron:2494104990`) and BSC Mainnet (`eip155:56`), and **USDC** on BSC Testnet (`eip155:97`) and Base (`eip155:8453`, `eip155:84532`). The registry also ships defaults for twenty further EVM networks (MegaETH, Monad, Polygon, Arbitrum, Mezo, Radius, XDC, Celo, Flare and others) that this page does not table. Everything else in the table above — TRON USDD, BSC Mainnet USDC, BSC Testnet USDT, DHLU, and any custom token — is server-advertised only: with the 1.1.0 client spend controls on by default, a client refuses to pay it unless you allowlist it via `spendControls.allowedAssets`. For CLI asset selection, follow the [wallet-cli command reference](/wallet-cli/command-reference/).
+> **Default assets vs. opt-in assets (SDK 1.1.0+)**: the default-asset registries resolve **USDT** on TRON (`tron:728126428`, `tron:3448148188`, `tron:2494104990`, from `@bankofai/x402-tron`) and **USDC** on Base (`eip155:8453`, `eip155:84532`, from the official `@x402/evm` 2.28.0). `@x402/evm` also ships defaults for further EVM networks (Ethereum, Polygon, Arbitrum, Avalanche, Celo, Sei, MegaETH, Monad, XDC, Flare and others) that this page does not table, but **none for BSC**: a BSC route must be priced with an explicit `{ asset, amount, extra }` object. Everything else in the table above — TRON USDD, every BSC asset, and any custom token — is server-advertised only: with the 1.1.0 client spend controls on by default, a client refuses to pay it unless you allowlist it via `spendControls.allowedAssets`. For CLI asset selection, follow the [wallet-cli command reference](/wallet-cli/command-reference/).
 
-> **Extensibility**: The protocol is highly extensible. By registering tokens through the TRON token registry (`registerToken` from `@bankofai/x402-tron`) or the server's `EVM_TOKENS` config table, you can support any custom TRC-20 or BEP-20 token.
+> **Extensibility**: The protocol is highly extensible. By registering tokens through the TRON token registry (`registerToken` from `@bankofai/x402-tron`) or an explicit `{ asset, amount, extra }` price on the server route, you can support any custom TRC-20 or BEP-20 token.
 
-> **Token selection for the `exact` scheme**: EIP-3009 tokens (for example official Base USDC and BSC testnet DHLU) settle gaslessly via `transferWithAuthorization`. Plain ERC-20 tokens (for example BSC USDC/USDT and TRON USDT/USDD) settle via the Permit2 path — the client auto-broadcasts a one-time `approve(Permit2)` on first payment, or, on TRON when the server advertises `trc20ApprovalResourceSponsoring` (SDK 1.2.0+), signs it and lets the facilitator sponsor and broadcast it. You set the per-token method on the server under `accepts[].price.extra`; the SDK surfaces it on the wire as `accepts[].extra`: EIP-3009 → `{ name, version }`; plain ERC-20 → `{ assetTransferMethod: "permit2" }`. A permit2 asset that also implements EIP-2612 carries `{ name, version }` alongside `assetTransferMethod`; omitting that pair is precisely how a server tells clients to skip EIP-2612. Both sponsoring paths live inside the permit2 branch, so neither applies to an EIP-3009 asset. On a permit2 asset the client signs a gasless EIP-2612 permit when a `readContract` capability is available (from the signer or a configured RPC), the server advertises the `eip2612GasSponsoring` extension, `extra` carries both `name` and `version`, and the current Permit2 allowance does not already cover the payment. Note the asymmetry: a *missing* read capability skips the permit entirely, whereas a read that *throws* is caught and signing proceeds. Otherwise the client *tries* ERC-20 approval gas sponsoring, which needs `readContract`, the separate `erc20ApprovalGasSponsoring` extension from the server, a signer that can both sign raw transactions and report a transaction count, and again an allowance that does not already cover the payment; there the client signs an `approve` for `MaxUint256` — always the max, regardless of the payment amount — that the facilitator broadcasts. When neither path qualifies the payload carries no sponsoring extension at all. Among the shipped default assets the flag is set on MegaETH MegaUSD (mainnet) and on Mezo mUSD and Radius SBC (mainnet and testnet).
+> **Token selection for the `exact` scheme**: EIP-3009 tokens (for example official Base USDC) settle gaslessly via `transferWithAuthorization`. Plain ERC-20 tokens (for example BSC USDC/USDT and TRON USDT/USDD) settle via the Permit2 path and need a one-time `approve(Permit2)` — on TRON the client auto-broadcasts it on first payment (on EVM it never does; see the sponsoring paths below), or, on TRON when the server advertises `trc20ApprovalResourceSponsoring` (SDK 1.2.0+), signs it and lets the facilitator sponsor and broadcast it (since 2.1.0 only with the client extension from `@bankofai/x402-tron-extensions` registered). You set the per-token method on the server under `accepts[].price.extra`; the SDK surfaces it on the wire as `accepts[].extra`: EIP-3009 → `{ name, version }`; plain ERC-20 → `{ assetTransferMethod: "permit2" }`. A permit2 asset that also implements EIP-2612 carries `{ name, version }` alongside `assetTransferMethod`; omitting that pair is precisely how a server tells clients to skip EIP-2612. Both sponsoring paths live inside the permit2 branch, so neither applies to an EIP-3009 asset. On a permit2 asset the client signs a gasless EIP-2612 permit when a `readContract` capability is available (from the signer or a configured RPC), the server advertises the `eip2612GasSponsoring` extension, `extra` carries both `name` and `version`, and the current Permit2 allowance does not already cover the payment. Note the asymmetry: a *missing* read capability skips the permit entirely, whereas a read that *throws* is caught and signing proceeds. Otherwise the client *tries* ERC-20 approval gas sponsoring, which needs `readContract`, the separate `erc20ApprovalGasSponsoring` extension from the server, a signer that can sign raw transactions, and a transaction count (from the signer or a configured RPC), and again an allowance that does not already cover the payment; there the client signs an `approve` for `MaxUint256` — always the max, regardless of the payment amount — that the facilitator broadcasts. When neither path qualifies the payload carries no sponsoring extension at all. Among the shipped default assets the `supportsEip2612` flag is set on MegaETH MegaUSD (mainnet) and on Mezo mUSD and Radius SBC (mainnet and testnet).
 
 ---
 
@@ -136,8 +135,8 @@ x402 defines five named payment schemes. Four have complete client + server + fa
 
 The `exact` scheme pays the exact amount advertised. It covers two token transfer paths:
 
-- **EIP-3009 `transferWithAuthorization`** — for tokens that natively support it (e.g. official Base USDC and BSC testnet DHLU). Gasless: no `approve` needed; the client signs a typed-data authorization and the facilitator calls `transferWithAuthorization` on-chain.
-- **Permit2** — for plain ERC-20 / TRC-20 tokens that do not implement ERC-3009 (e.g. BSC USDC/USDT, TRON USDT/USDD). The client signs a Permit2 witness and the facilitator settles via the `x402ExactPermit2Proxy` contract. A one-time `approve(Permit2)` is required; the client auto-broadcasts it on first payment. On TRON, SDK 1.2.0 adds the `trc20ApprovalResourceSponsoring` extension — when the server advertises it, the client signs that approve without broadcasting it and the facilitator delegates the Energy/Bandwidth and broadcasts it, so the payer needs no TRX for the approve.
+- **EIP-3009 `transferWithAuthorization`** — for tokens that natively support it (e.g. official Base USDC). Gasless: no `approve` needed; the client signs a typed-data authorization and the facilitator calls `transferWithAuthorization` on-chain.
+- **Permit2** — for plain ERC-20 / TRC-20 tokens that do not implement ERC-3009 (e.g. BSC USDC/USDT, TRON USDT/USDD). The client signs a Permit2 witness and the facilitator settles via the `x402ExactPermit2Proxy` contract. A one-time `approve(Permit2)` is required; on TRON the client auto-broadcasts it on first payment, while on EVM it must already be in place or be relayed through a gas-sponsoring extension. On TRON, SDK 1.2.0 adds the `trc20ApprovalResourceSponsoring` extension — when the server advertises it, the client signs that approve without broadcasting it and the facilitator delegates the Energy/Bandwidth and broadcasts it, so the payer needs no TRX for the approve. Since 2.1.0 the client must register `createTrc20ApprovalResourceSponsoringClientExtension(signer)` from `@bankofai/x402-tron-extensions`; otherwise the payment fails with `trc20_approval_client_extension_not_registered`.
 
 The `exact` scheme conforms to the **v2 wire format** published by the **x402 Foundation**: a stock v2 client can pay a protected endpoint on this SDK's server directly, and this SDK's client can pay any v2-compliant server — no project-specific translation required. Transfer authorization data is carried in `payload.authorization` on the EIP-3009 path and in `payload.permit2Authorization` on the Permit2 path.
 
@@ -151,7 +150,7 @@ A payment-channel scheme for high-frequency micro-payments (e.g. AI agent per-to
 
 ### `auth-capture` Scheme
 
-An EVM client implementation for refundable Base Commerce Payments: authorize funds first, then capture, void, or refund them later. The published SDK currently exposes `@bankofai/x402-evm/auth-capture/client`; its server and facilitator implementations are not shipped yet, so it cannot currently be deployed end to end using only the published package.
+An EVM client implementation for refundable Base Commerce Payments: authorize funds first, then capture, void, or refund them later. The official `@x402/evm` package (which the SDK uses for EVM since 2.1.0) currently exposes `@x402/evm/auth-capture/client`; its server and facilitator implementations are not shipped yet, so it cannot currently be deployed end to end using only the published package.
 
 ### `exact_gasfree` Scheme
 
@@ -220,7 +219,7 @@ You may deploy your own Facilitator to gain full control over payment verificati
 
 | Core Component | TRON/BSC/Base Implementation |
 | :------------- | :---------------------- |
-| **Networks**   | The three TRON IDs (`tron:728126428`, `tron:2494104990`, `tron:3448148188`) plus any `eip155:<chainId>` — client and resource server both default to `eip155:*`, and the SDK ships default assets for twenty EVM networks beyond `eip155:56` / `97` / `8453` / `84532`. What can actually settle is bounded by the networks the facilitator has configured, which it must enumerate explicitly |
+| **Networks**   | The three TRON IDs (`tron:728126428`, `tron:2494104990`, `tron:3448148188`) plus any `eip155:<chainId>` — client and resource server both default to `eip155:*`, and the official `@x402/evm` ships default assets for Base, Base Sepolia and many other EVM networks, but not BSC (`eip155:56` / `97` need an explicit asset). What can actually settle is bounded by the networks the facilitator has configured, which it must enumerate explicitly |
 | **Token Standard** | TRC-20 (built-in USDT & USDD support), BEP-20, ERC-20 (Base official USDC) |
 | **Signing Mechanism** | TIP-712 / EIP-712 typed data signing |
 | **Payment Schemes** | `exact`, `upto`, `batch-settlement`, `exact_gasfree` (TRON) |
@@ -242,7 +241,7 @@ registerToken(TRON_NILE, {
 });
 ```
 
-On the **resource server** side, custom EVM tokens are advertised by adding an entry to the server's `EVM_TOKENS` table in `src/chains/evm.ts` — an explicit `{ asset, amount, extra }` object. Adding a chain is one table entry; no SDK changes are needed.
+On the **resource server** side, custom EVM tokens are advertised with an explicit `{ asset, amount, extra }` price object in the route's `accepts`; no SDK changes are needed. (The `EVM_TOKENS` table of the earlier example server was removed with the EVM examples in x402 v2.1.0; see the [upstream EVM examples](https://github.com/x402-foundation/x402/tree/main/examples/typescript).)
 
 Once registered, you can use the custom token symbol in TRON prices (e.g., `"0.001 MYT"`).
 
@@ -257,4 +256,4 @@ x402 is deeply tailored for blockchain-native architectures, providing seamless
 - **Development Environment**: Use testnets for development and debugging.
 - **Default Settlement Asset**: TRON/BSC routes use their configured stablecoins; Base uses official **USDC**.
 - **Security Model**: TIP-712 / EIP-712 typed data signing ensures secure, trust-minimized payment authorization.
-- **Extensibility**: Expand support for any custom TRC-20/BEP-20 token via the TRON token registry (`registerToken`) or the server's `EVM_TOKENS` config table.
+- **Extensibility**: Expand support for any custom TRC-20/BEP-20 token via the TRON token registry (`registerToken`) or an explicit `{ asset, amount, extra }` route price.
diff --git a/docs/x402/core-concepts/wallet.md b/docs/x402/core-concepts/wallet.md
index c3b4c917..eb5717ab 100644
--- a/docs/x402/core-concepts/wallet.md
+++ b/docs/x402/core-concepts/wallet.md
@@ -76,7 +76,7 @@ x402 uses typed data signing for secure payment authorization.
 
 ## Token Approval
 
-For the `exact` payment scheme, plain ERC-20/TRC-20 tokens (e.g. BSC USDC/USDT, TRON USDT/USDD) settle via the Permit2 path. The client must authorize the Permit2 contract to transfer tokens — a one-time `approve(Permit2, max)`. On TRON the client SDK auto-broadcasts this approve on the first payment; on EVM it never broadcasts — it attaches a signed, unbroadcast approve for the facilitator to relay when the server advertises a gas-sponsoring extension, and otherwise the allowance must be granted once out of band or verification fails with `permit2_allowance_required`. On TRON, when the resource server advertises `trc20ApprovalResourceSponsoring` (SDK 1.2.0+), the client signs the `approve(Permit2, MaxUint256)` transaction but does not broadcast it — the facilitator temporarily delegates the Energy — and, when needed, Bandwidth — that the payer lacks and broadcasts it, so the payer needs no TRX for that first approve. This requires an activated, single-signature TRON EOA. ERC-3009 tokens (e.g. BSC testnet DHLU) need no approve — they settle gaslessly via `transferWithAuthorization`.
+For the `exact` payment scheme, plain ERC-20/TRC-20 tokens (e.g. BSC USDC/USDT, TRON USDT/USDD) settle via the Permit2 path. The client must authorize the Permit2 contract to transfer tokens — a one-time `approve(Permit2, max)`. On TRON the client SDK auto-broadcasts this approve on the first payment; on EVM it never broadcasts — it attaches a signed EIP-2612 permit or a signed, unbroadcast approve for the facilitator to relay when the server advertises a gas-sponsoring extension, and otherwise the allowance must be granted once out of band or verification fails with `permit2_allowance_required`. On TRON, when the resource server advertises `trc20ApprovalResourceSponsoring` (SDK 1.2.0+), the client signs the `approve(Permit2, MaxUint256)` transaction but does not broadcast it — the facilitator temporarily delegates the Energy — and, when needed, Bandwidth — that the payer lacks and broadcasts it, so the payer needs no TRX for that first approve. This requires an activated, single-signature TRON EOA. Since 2.1.0 the client must register `createTrc20ApprovalResourceSponsoringClientExtension(signer)` from `@bankofai/x402-tron-extensions`; otherwise the payment fails with `trc20_approval_client_extension_not_registered`. ERC-3009 tokens (e.g. official Base USDC) need no approve — they settle gaslessly via `transferWithAuthorization`.
 
 ---
 
@@ -97,7 +97,7 @@ For the `exact` payment scheme, plain ERC-20/TRC-20 tokens (e.g. BSC USDC/USDT,
 | Network | RPC Endpoint |
 | :------- | :------------ |
 | **Mainnet** | `https://bsc-dataseed.binance.org` |
-| **Testnet** | `https://data-seed-prebsc-1-s1.binance.org:8545` |
+| **Testnet** | `https://bsc-testnet-rpc.publicnode.com` |
 
 ---
 
diff --git a/docs/x402/faq.md b/docs/x402/faq.md
index 1e13abf4..e74c92d9 100644
--- a/docs/x402/faq.md
+++ b/docs/x402/faq.md
@@ -11,7 +11,7 @@ x402 revives the long-unused HTTP `402 Payment Required` status code and transfo
 
 #### Is x402 a commercial product?
 
-**No.** x402 is an open-source blockchain implementation of the x402 protocol, released under the MIT license. You are free to use it without purchasing any commercial product.
+**No.** x402 is an open-source blockchain implementation of the x402 protocol. The [repository](https://github.com/BofAI/x402) is MIT-licensed, while the published npm packages `@bankofai/x402-tron` and `@bankofai/x402-tron-extensions` declare `Apache-2.0` in their `package.json` (as do the official `@x402/*` packages). You are free to use it without purchasing any commercial product.
 
 #### Why replace traditional payment channels or API keys?
 
@@ -27,13 +27,13 @@ Not at all. Any Web API or content provider—whether Web3-native or traditional
 
 #### What languages and frameworks are supported?
 
-x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` packages:
+x402 is a **TypeScript-only** SDK: the TRON packages are published as `@bankofai/x402-tron` and `@bankofai/x402-tron-extensions`, and Core, EVM and the framework integrations are the official `@x402/*` packages:
 
 - **Server middleware**: Express, Fastify, Hono, Next.js
-- **Client**: wrapped `fetch` (`@bankofai/x402-fetch`), Axios, MCP transport
+- **Client**: wrapped `fetch` (`@x402/fetch`), Axios, MCP transport
 - **Facilitator**: chain-agnostic engine with per-scheme verify + settle
 
-The previous Python SDK lives under `legacy/` for reference.
+The retired Python SDK and the old root `legacy/` archive were removed in x402 v2.0.0, and the compatibility npm packages under `typescript/packages/legacy/` in v2.1.0.
 
 ---
 
@@ -70,7 +70,7 @@ Common pricing models include:
 
 x402 defines five named payment schemes. Four are available end to end; `auth-capture` currently ships client-side support only:
 
-- **`exact`**: Pay the exact advertised amount. EIP-3009 tokens (e.g. official Base USDC and BSC testnet DHLU) settle gaslessly via `transferWithAuthorization`; plain ERC-20/TRC-20 tokens (e.g. BSC USDC/USDT, TRON USDT/USDD) settle via the Permit2 path with a one-time `approve(Permit2)`. The `exact` wire payload conforms to the **x402 Foundation** v2 spec.
+- **`exact`**: Pay the exact advertised amount. EIP-3009 tokens (e.g. official Base USDC) settle gaslessly via `transferWithAuthorization`; plain ERC-20/TRC-20 tokens (e.g. BSC USDC/USDT, TRON USDT/USDD) settle via the Permit2 path with a one-time `approve(Permit2)`. The `exact` wire payload conforms to the **x402 Foundation** v2 spec.
 - **`upto`**: Usage-based billing — the client signs a Permit2 authorization for up to a **maximum**; the server settles only the **real usage** (≤ max). Ideal for **metered billing**, **LLM token usage**.
 - **`batch-settlement`**: Payment-channel for high-frequency micro-payments — deposit once, pay many requests with off-chain vouchers, settle in one batch tx. Includes a refund path.
 - **`exact_gasfree`** (TRON only): Allows buyers to pay with USDT/USDD without holding TRX for gas. A relayer pays the on-chain energy via the GasFree API — no API keys required on the client side. The relayer deducts its own fee from the payment token, on top of the payment amount.
@@ -82,10 +82,10 @@ x402 defines five named payment schemes. Four are available end to end; `auth-ca
 
 - A stock v2 client can directly access this SDK's `exact` protected endpoints with no project-specific adapter layer.
 - This SDK's client can pay v2-compatible servers directly.
-- In the V2 structure, transfer authorization data is carried in the `payload.authorization` field (a structured object).
-- BSC USDT/USDC are plain ERC-20s (no ERC-3009). They settle via the Permit2 path under the `exact` scheme — the client auto-broadcasts a one-time `approve(Permit2)` on first payment. ERC-3009 tokens like BSC testnet **DHLU** settle gaslessly with no approve.
+- In the V2 structure, transfer authorization data is a structured object: `payload.authorization` on the EIP-3009 path, `payload.permit2Authorization` on the Permit2 path.
+- BSC USDT/USDC are plain ERC-20s (no ERC-3009). They settle via the Permit2 path under the `exact` scheme and need a one-time `approve(Permit2)`. On EVM the client never broadcasts it: it must already be in place, or be relayed by the facilitator through a gas-sponsoring extension the server advertises — otherwise the request fails with `permit2_allowance_required`.
 - Base Mainnet official USDC uses EIP-3009 under `exact`: the payer signs `transferWithAuthorization`, so no Permit2 approval is required.
-- The `legacy/examples/bsc-testnet-smoke/` directory (part of the `legacy/` tree, kept for reference) contains smoke tests for bidirectional interoperability (Coinbase official client → BANK OF AI server, BANK OF AI client → Coinbase official server) that you can use as a debugging and integration reference.
+- The former `legacy/examples/bsc-testnet-smoke/` interoperability smoke tests were removed together with the root `legacy/` archive in x402 v2.0.0. Use the runnable [`examples/typescript`](https://github.com/BofAI/x402/tree/main/examples/typescript) workspace as the current client → server → facilitator reference; since v2.1.0 it covers TRON only, so for EVM use the [upstream examples](https://github.com/x402-foundation/x402/tree/main/examples/typescript).
 
 ---
 
@@ -95,22 +95,23 @@ x402 defines five named payment schemes. Four are available end to end; `auth-ca
 
 | Network                     | Token         | Status      |
 | --------------------------- | ------------- | ----------- |
-| TRON Mainnet (`tron:0x2b6653dc`) | USDT (TRC-20) | **Mainnet** |
-| TRON Nile (`tron:0xcd8690dc`)       | USDT (TRC-20) | **Testnet** |
-| TRON Shasta (`tron:0x94a9059e`)   | USDT (TRC-20) | **Testnet** (SDK/CLI only — the official facilitator does not settle Shasta; use Nile or self-host) |
-| TRON Mainnet (`tron:0x2b6653dc`) | USDD (TRC-20) | **Mainnet** |
-| TRON Nile (`tron:0xcd8690dc`)       | USDD (TRC-20) | **Testnet** |
+| TRON Mainnet (`tron:728126428`) | USDT (TRC-20) | **Mainnet** |
+| TRON Nile (`tron:3448148188`)       | USDT (TRC-20) | **Testnet** |
+| TRON Shasta (`tron:2494104990`)   | USDT (TRC-20) | **Testnet** (SDK/CLI only — the official facilitator does not settle Shasta; use Nile or self-host) |
+| TRON Mainnet (`tron:728126428`) | USDD (TRC-20) | **Mainnet** |
+| TRON Nile (`tron:3448148188`)       | USDD (TRC-20) | **Testnet** |
 | BSC Mainnet (`eip155:56`)     | USDT (BEP-20) | **Mainnet** |
-| BSC Mainnet (`eip155:56`)     | USDC (BEP-20) | **Mainnet** |
+| BSC Mainnet (`eip155:56`)     | USDC (BEP-20; `0x8AC76a…`, not in any shipped token registry — explicit asset only) | **Mainnet** |
 | BSC Testnet (`eip155:97`)     | USDT (BEP-20) | **Testnet** |
 | BSC Testnet (`eip155:97`)     | USDC (BEP-20) | **Testnet** |
-| BSC Testnet (`eip155:97`)     | DHLU (BEP-20, for `exact` interop tests) | **Testnet** |
 | Base Mainnet (`eip155:8453`) | Official USDC (ERC-20, EIP-3009) | **Mainnet** |
 | Base Sepolia (`eip155:84532`) | USDC (ERC-20, EIP-3009) | **Testnet** |
 
-Only some of these are **default assets** (USDT on TRON and BSC Mainnet, USDC on BSC Testnet and Base). Since SDK 1.1.0 a client's spend controls reject any other asset — including TRON USDD, BSC Mainnet USDC and BSC Testnet USDT — unless it is allowlisted via `spendControls.allowedAssets`.
+TRON identifiers use decimal chain IDs since x402 v2.0.0 (`@bankofai/x402-tron` 2.0.0); the older hex forms (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) are still accepted as input aliases.
 
-Custom TRC-20 tokens can be added via the TRON token registry (`registerToken` from `@bankofai/x402-tron`); custom BEP-20 tokens are advertised by adding an entry to the server's `EVM_TOKENS` config table.
+Only some of these are **default assets** (USDT on the three TRON networks, USDC on Base and Base Sepolia). Since SDK 1.1.0 a client's spend controls reject any other asset — including TRON USDD and every BSC asset — unless it is allowlisted via `spendControls.allowedAssets`.
+
+Custom TRC-20 tokens can be added via the TRON token registry (`registerToken` from `@bankofai/x402-tron`); custom BEP-20 tokens are advertised with an explicit `{ asset, amount, extra }` price on the server route.
 
 #### What fees are involved?
 
@@ -130,7 +131,7 @@ Custom TRC-20 tokens can be added via the TRON token registry (`registerToken` f
 
 1. **Buyer (client/agent)** signs locally (browser, serverless function, or agent VM).
 2. **Seller** verifies signatures without accessing private keys.
-3. **Facilitator** submits transactions with its own settlement wallet, resolved through `@bankofai/agent-wallet` — the raw key never enters the facilitator process.
+3. **Facilitator** submits transactions with its own settlement wallet, resolved through `@bankofai/agent-wallet` — with the `privy` or `wallet_cli` provider the key stays outside the facilitator process (`raw_secret` keeps a plaintext key in config and is for development only).
 
 #### How does refunds work?
 
@@ -167,11 +168,11 @@ The flow mirrors a human user:
 Install the published packages in your TypeScript app and build against npm, for example:
 
 ```bash
-pnpm add @bankofai/x402-fetch @bankofai/x402-tron @bankofai/x402-evm @bankofai/agent-wallet
-pnpm add @bankofai/x402-core @bankofai/x402-express
+pnpm add @x402/core@2.28.0 @x402/fetch@2.28.0 @bankofai/x402-tron@2.1.0 @x402/evm@2.28.0 @bankofai/agent-wallet
+pnpm add @x402/express@2.28.0
 ```
 
-Use the framework package that matches your server (`express`, `hono`, `fastify`, or `next`). The [`examples/typescript`](https://github.com/BofAI/x402/tree/main/examples/typescript) workspace is a runnable reference for client → server → facilitator flows, not a prerequisite for application development.
+Use the framework package that matches your server (`@x402/express`, `@x402/hono`, `@x402/fastify`, or `@x402/next`), at the same `2.28.0` as `@x402/core` — `@bankofai/x402-tron` 2.1.0 requires exactly `@x402/core@2.28.0`. Add `@bankofai/x402-tron-extensions@2.1.0` only if you use TRON resource sponsoring. The [`examples/typescript`](https://github.com/BofAI/x402/tree/main/examples/typescript) workspace is a runnable reference for client → server → facilitator flows, not a prerequisite for application development.
 
 #### Which testnet is recommended?
 
@@ -195,10 +196,11 @@ Common causes:
 
 1. Invalid signature (incorrect domain or payload).
 2. Insufficient payment amount.
-3. Insufficient token allowance granted to Facilitator.
-4. Insufficient wallet balance.
+3. Insufficient wallet balance.
+
+The response body is `{}` by default. The reason is the `error` field of the payment requirements carried, Base64-encoded, in the `PAYMENT-REQUIRED` response header — decode it (for example with `decodePaymentRequiredHeader` from `@x402/core/http`) for diagnostics.
 
-Check the `error` field in the server’s JSON response for detailed diagnostics.
+An insufficient Permit2 allowance on the `exact` / `upto` Permit2 path does not return 402: the server answers HTTP `412 Precondition Failed` with `error: "permit2_allowance_required"` in the same header. (The `batch-settlement` deposit path reports it as a 402 with its own scheme-specific code.)
 
 #### It works on Nile but fails on Mainnet — why?
 
diff --git a/docs/x402/getting-started/quickstart-for-human.md b/docs/x402/getting-started/quickstart-for-human.md
index ed142a18..26712ae1 100644
--- a/docs/x402/getting-started/quickstart-for-human.md
+++ b/docs/x402/getting-started/quickstart-for-human.md
@@ -10,7 +10,7 @@ This guide is for developers who want to **call an x402-protected API from code*
 > **Testnet first:** This guide uses testnet by default. You can safely follow every step without spending real money.
 
 :::info (TypeScript-only)
-x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` packages. This guide shows how to integrate the published npm packages directly.
+x402 is a **TypeScript-only** SDK: the TRON mechanism ships as `@bankofai/x402-tron` and runs on the official `@x402/*` Core and HTTP packages. This guide shows how to integrate the published npm packages directly.
 :::
 
 ---
@@ -31,7 +31,7 @@ x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` packa
 
 ### Checklist Before You Start
 
-- [ ] **Node.js 22+** and **pnpm 11.1+** installed
+- [ ] **Node.js 24.22.1+** and **pnpm 11.1+** installed
 - [ ] A dedicated **test wallet** created (see below)
 - [ ] Test tokens claimed (free)
 - [ ] A target x402-protected API URL, such as the `/credit` endpoint from [Quickstart for Sellers](./quickstart-for-sellers.md)
@@ -94,16 +94,16 @@ x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` packa
 Install the published npm packages in your TypeScript application:
 
 ```bash
-pnpm add @bankofai/agent-wallet @bankofai/x402-fetch @bankofai/x402-tron
+pnpm add @bankofai/agent-wallet @x402/core@2.28.0 @x402/fetch@2.28.0 @bankofai/x402-tron@2.1.0
 pnpm add -D tsx   # to run the TypeScript entry point below
 ```
 
-Use `npm install` or `yarn add` with the same package names if your project does not use pnpm.
+Use `npm install` or `yarn add` with the same package names if your project does not use pnpm. Keep `@x402/core` and `@x402/fetch` at exactly `2.28.0` — `@bankofai/x402-tron` 2.1.0 declares `@x402/core@2.28.0` as an exact peer dependency.
 
 :::info Wallet Management
-x402 uses [Agent Wallet](../../Agent-Wallet/QuickStart.md) to resolve and manage wallet credentials. Agent Wallet is installed with the package set above. Private key resolution priority:
-1. Encrypted wallet file (imported via the Agent Wallet CLI)
-2. Environment variable `AGENT_WALLET_PRIVATE_KEY`
+x402 uses [Agent Wallet](../../Agent-Wallet/QuickStart.md) to resolve and manage wallet credentials. Agent Wallet (3.0+) is installed with the package set above. Wallet resolution priority:
+1. The Agent Wallet CLI config (`~/.agent-wallet`), when it contains at least one wallet — set up with `agent-wallet start raw_secret`, `wallet_cli` or `privy`
+2. Environment variables `AGENT_WALLET_PRIVATE_KEY` (or `AGENT_WALLET_MNEMONIC`)
 
 This guide uses the environment variable method.
 :::
@@ -145,7 +145,8 @@ The client wraps `fetch` so HTTP `402 Payment Required` challenges are paid auto
 
 ```typescript
 import { resolveWallet, type Wallet, type Eip712Capable } from "@bankofai/agent-wallet";
-import { x402Client, wrapFetchWithPayment } from "@bankofai/x402-fetch";
+import { x402Client } from "@x402/core/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
 import { createClientTronSigner, TRON_NILE } from "@bankofai/x402-tron";
 import { ExactTronScheme } from "@bankofai/x402-tron/exact/client";
 
@@ -210,15 +211,14 @@ See [SDK Feature Matrix](../sdk-features.md) for the full options, including `al
 
 | Problem | Cause | Solution |
 |---------|-------|----------|
-| `WalletNotFoundError` / no wallet resolved | agent-wallet has no wallet, or `AGENT_WALLET_PRIVATE_KEY` is not set in this shell | Run `agent-wallet start`, or run the `export` in **the same terminal window** as the script |
-| `WalletNotFoundError: No active wallet set` | agent-wallet has no wallet configured | Run `agent-wallet start` and follow the prompts to import your private key |
+| `resolve_wallet could not find a wallet source in config or env` | agent-wallet has no wallet, or `AGENT_WALLET_PRIVATE_KEY` is not set in this shell | Run `agent-wallet start`, or run the `export` in **the same terminal window** as the script |
 | `Insufficient balance` / balance error | Test wallet doesn't have enough USDT/USDD | Go back to Prerequisites and claim test tokens from the faucet |
 | `No network/scheme registered for x402 version: 2 …` | No scheme is registered for any network the server advertises — this is raised before your selector runs | Check that the server's `accepts` includes `network: TRON_NILE` and that you called `client.register(TRON_NILE, …)` |
 | `permit2_allowance_required` | The Permit2 allowance is missing or too low | On TRON the SDK auto-broadcasts the one-time `approve` on first payment; if it persists, check that the wallet holds enough TRX for that approve |
 | `approval_reset_required` (TRON) | The token already has a non-zero but insufficient Permit2 allowance, and the default `zero-first` strategy will not overwrite it | Set the token's Permit2 allowance back to `0`, then retry — the SDK never inserts an implicit `approve(0)` |
 | `approval_asset_unsupported` (TRON) | The token is not a known Permit2 asset and no approval strategy was configured for it | Configure it with `createTrc20ApprovalPolicy`, or pay with a supported token |
 | `Connection timeout` | Network or request timeout | Check the API service, facilitator, and TRON RPC connection |
-| `ERR_PACKAGE_PATH_NOT_EXPORTED` | Project is not declared as ESM | Add `"type": "module"` to your `package.json` |
+| `Top-level await is currently not supported with the "cjs" output format` (under `tsx`) | Project is not declared as ESM, so the script's top-level `await` is compiled as CommonJS | Add `"type": "module"` to your `package.json` |
 
 If you need finer-grained error handling in your code:
 
@@ -232,7 +232,7 @@ try {
     console.error(await res.text());
   }
 } catch (error) {
-  if (error instanceof Error && error.message.includes("no payment option")) {
+  if (error instanceof Error && error.message.includes("No network/scheme registered")) {
     console.error("No matching payment option — check TRON_NILE vs the server's accepts");
   } else if (error instanceof Error && error.message.includes("allowance")) {
     console.error("Insufficient token allowance — check wallet balance");
diff --git a/docs/x402/getting-started/quickstart-for-sellers.md b/docs/x402/getting-started/quickstart-for-sellers.md
index d3e9975b..2f7fd583 100644
--- a/docs/x402/getting-started/quickstart-for-sellers.md
+++ b/docs/x402/getting-started/quickstart-for-sellers.md
@@ -16,7 +16,7 @@ After completing this guide, you'll have a **service that charges for API calls*
 The entire flow takes **4 steps**, estimated time: **15–20 minutes**.
 
 :::info (TypeScript-only)
-x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` packages. This guide shows how to build with the published npm packages.
+x402 is a **TypeScript-only** SDK: the TRON mechanism ships as `@bankofai/x402-tron` and runs on the official `@x402/*` Core, EVM and framework packages. This guide shows how to build with the published npm packages.
 :::
 
 ---
@@ -28,7 +28,7 @@ x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` packa
 In your terminal (Terminal on macOS/Linux, or PowerShell/Command Prompt on Windows), run the following commands to confirm the required tools are installed:
 
 ```bash
-node --version    # Requires Node.js 22 or higher
+node --version    # Requires Node.js 24.22.1 or higher
 pnpm --version    # Requires pnpm 11.1 or higher
 git --version     # Version control tool
 ```
@@ -132,14 +132,14 @@ Deposit a small amount of official USDC on Base Mainnet. The resource server onl
 
 ## Step 1: Install the SDK Packages
 
-Install the Express adapter and the TRON/EVM payment schemes in your TypeScript API project:
+Install official Core, the Express adapter and the TRON/EVM payment schemes in your TypeScript API project:
 
 ```bash
-pnpm add express @bankofai/x402-core @bankofai/x402-express @bankofai/x402-tron @bankofai/x402-evm
+pnpm add express @x402/core@2.28.0 @x402/express@2.28.0 @bankofai/x402-tron@2.1.0 @x402/evm@2.28.0
 pnpm add -D tsx   # to run the TypeScript entry point below
 ```
 
-Use the framework package that matches your server (`@bankofai/x402-express`, `@bankofai/x402-hono`, `@bankofai/x402-fastify`, or `@bankofai/x402-next`). Use `npm install` or `yarn add` with the same package names if your project does not use pnpm.
+Use the framework package that matches your server (`@x402/express`, `@x402/hono`, `@x402/fastify`, or `@x402/next`), at the same `2.28.0` as `@x402/core` — `@bankofai/x402-tron` 2.1.0 declares `@x402/core@2.28.0` as an exact peer dependency. Install `@x402/evm` only for BSC/Base routes. Use `npm install` or `yarn add` with the same package names if your project does not use pnpm.
 
 If you want a more complete client → server → facilitator example, refer to the repository [examples](https://github.com/BofAI/x402/tree/main/examples/typescript). Application development should still depend on the published packages instead of linking the monorepo source.
 
@@ -169,16 +169,13 @@ Here are minimal Express resource servers for TRON and Base. `GET /credit` requi
 
 ```typescript
 import express from "express";
-import { createResourceServer } from "@bankofai/x402-core";
-import { HTTPFacilitatorClient } from "@bankofai/x402-core/server";
-import {
-  x402HTTPResourceServer,
-  paymentMiddlewareFromHTTPServer,
-} from "@bankofai/x402-express";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { x402HTTPResourceServer } from "@x402/core/http";
+import { paymentMiddlewareFromHTTPServer } from "@x402/express";
 import { TRON_NILE } from "@bankofai/x402-tron";
 import { ExactTronScheme } from "@bankofai/x402-tron/exact/server";
 
-const server = createResourceServer(
+const server = new x402ResourceServer(
   new HTTPFacilitatorClient({
     // Replace this before running — the server syncs with the facilitator on
     // startup, so a placeholder URL makes the first protected request fail
@@ -222,15 +219,12 @@ express()
 
 ```typescript
 import express from "express";
-import { createResourceServer } from "@bankofai/x402-core";
-import { HTTPFacilitatorClient } from "@bankofai/x402-core/server";
-import {
-  x402HTTPResourceServer,
-  paymentMiddlewareFromHTTPServer,
-} from "@bankofai/x402-express";
-import { ExactEvmScheme } from "@bankofai/x402-evm/exact/server";
-
-const server = createResourceServer(
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { x402HTTPResourceServer } from "@x402/core/http";
+import { paymentMiddlewareFromHTTPServer } from "@x402/express";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+
+const server = new x402ResourceServer(
   new HTTPFacilitatorClient({
     // Replace this before running — the server syncs with the facilitator on
     // startup, so a placeholder URL makes the first protected request fail
@@ -313,7 +307,7 @@ The officially hosted Facilitator service requires **no infrastructure to mainta
 Set the `url` in `HTTPFacilitatorClient` to the official endpoint:
 
 ```typescript
-const server = createResourceServer(
+const server = new x402ResourceServer(
   new HTTPFacilitatorClient({
     url: "https://facilitator.bankofai.io",
   })
@@ -322,7 +316,7 @@ const server = createResourceServer(
 
 This is the address your x402 server uses to verify and settle payments — **for API calls only**, no need to open it in a browser.
 
-> ⚠️ **Without an API Key, this endpoint is rate-limited** (one `/settle` call per IP per minute). Suitable for testing only.
+> ⚠️ **Without an API Key, this endpoint is rate-limited** (10 requests per IP per minute, counted separately for `/verify` and `/settle`). Suitable for testing only.
 
 #### 4.2 Apply for an API Key
 
@@ -330,14 +324,14 @@ This is the address your x402 server uses to verify and settle payments — **fo
 2. On the Dashboard, click **"Create API Key"**
 3. Confirm, then click **View** in the Dashboard to see and copy your API Key
 
-With an API Key, the official service allows **1,000 `/settle` requests per API Key per minute**, sufficient for production use.
+With an API Key, the official service allows **1,000 requests per API Key per minute for each of `/verify` and `/settle`**, sufficient for production use.
 
 #### 4.3 Wire the API Key into Your Server
 
 The official key is sent as the `X-API-KEY` header on every facilitator call. Keep it in an environment variable or secret manager, and pass it with facilitator requests in production.
 
 ```bash
-FACILITATOR_API_KEY=paste_your_api_key_here
+export FACILITATOR_API_KEY=paste_your_api_key_here
 ```
 
 `HTTPFacilitatorClient` sends the header only if you give it `createAuthHeaders` — without this the server silently stays on the anonymous tier:
@@ -364,7 +358,7 @@ new HTTPFacilitatorClient({
 
 The self-hosted option gives you full control over the settlement wallet, RPC endpoints, and which networks and schemes you register — neither the SDK nor the facilitator charges a fee of its own. It runs the example facilitator (`examples/typescript/facilitator/basic`), which exposes `/verify`, `/settle`, `/supported` over HTTP and dispatches by the payment's `network` field.
 
-> **Base sellers:** the bundled example facilitator registers only `eip155:97` and `eip155:56` (`EVM_NETWORKS` in `facilitator/basic/src/chains/evm.ts`). To settle on Base, either use the official facilitator — which enables `eip155:8453` and `eip155:84532` — or add those ids to `EVM_NETWORKS` yourself.
+> **BSC and Base sellers:** since x402 v2.1.0 the bundled example facilitator registers TRON networks only (`TRON_NETWORKS` in `facilitator/basic/src/chains/tron.ts`). To settle on BSC or Base, either use the official facilitator — which enables `eip155:56`, `eip155:97`, `eip155:8453` and `eip155:84532` — or build an EVM facilitator with official `@x402/evm` following the [upstream examples](https://github.com/x402-foundation/x402/tree/main/examples/typescript).
 
 > ⚠️ **Security reminder — please read first:**
 > - A self-hosted Facilitator uses your wallet to submit on-chain settlement transactions — **this wallet should be separate from your receiving wallet**
@@ -377,27 +371,25 @@ The facilitator verifies signatures and settles on-chain. It registers the `exac
 
 ```typescript
 // examples/typescript/facilitator/basic/src/index.ts (abridged)
-import { x402Facilitator } from "@bankofai/x402-core/facilitator";
+import { x402Facilitator } from "@x402/core/facilitator";
 
 const facilitator = new x402Facilitator()
   .onBeforeSettle(async ctx => console.log("[settle] before", ctx.requirements.network))
   .onAfterSettle(async ctx => console.log("[settle] after", ctx.requirements.network))
   .onSettleFailure(async ctx => console.log("[settle] failure", ctx));
 
-// Register each chain only if its wallet resolves (EVM-only, TRON-only, or both).
-const evm = await registerEvm(facilitator);
+// Register each chain only if its wallet resolves. Only TRON networks are registered.
 const tron = await registerTron(facilitator);
 
 // Exposes POST /verify, POST /settle, GET /supported on FACILITATOR_PORT.
 app.listen(PORT, () => console.log(`🚀 Facilitator on http://localhost:${PORT}`));
 ```
 
-Each chain module adapts the agent-wallet to a facilitator signer:
+The TRON chain module adapts the agent-wallet to a facilitator signer:
 
-- **EVM** — `createFacilitatorEvmSigner(wallet, { network, rpcUrl })`, then `facilitator.register(network, new ExactEvmScheme(signer))`
 - **TRON** — `createFacilitatorTronSigner(wallet, { network, apiKey })`, then `facilitator.register(network, new ExactTronScheme(signer))`
 
-The signer factories build the viem client / TronWeb internally; the example **never reads a raw private key** — `AGENT_WALLET_PRIVATE_KEY` is consumed by `@bankofai/agent-wallet`.
+The signer factory builds TronWeb internally; the example **never reads a raw private key** — `AGENT_WALLET_PRIVATE_KEY` is consumed by `@bankofai/agent-wallet`.
 
 #### 4.2 Start the Facilitator
 
@@ -410,9 +402,10 @@ pnpm dev:facilitator
 **After a successful start, you should see output like:**
 
 ```
-[evm] facilitator registered eip155:97 (0x…)
 [tron] facilitator registered tron:3448148188 (T…)
-🚀 Facilitator on http://localhost:4022  (evm=true, tron=true)
+[tron] facilitator registered tron:2494104990 (T…)
+[tron] facilitator registered tron:728126428 (T…)
+🚀 Facilitator on http://localhost:4022  (tron=true)
 ```
 
 > ✅ **Success:** Facilitator is running on port 4022 — **keep this terminal window open, do not close it**
@@ -472,10 +465,10 @@ To test the complete pay → receive content flow, use the minimal client in [Qu
 |---------|-------|----------|
 | `Failed to fetch` / connection refused | Facilitator or server not running | Start the facilitator first, then run your API server entry point |
 | Client selects nothing / no matching requirement | The client selected a network or token that the server does not advertise | Check the server's `accepts` (network + token), e.g. `TRON_NILE` + `USDT` |
-| `ERR_PACKAGE_PATH_NOT_EXPORTED` under `npx tsx` | Project is not declared as ESM | Add `"type": "module"` to your `package.json` |
+| `Top-level await is currently not supported with the "cjs" output format` under `npx tsx` | Project is not declared as ESM, so an entry file with top-level `await` is compiled as CommonJS | Add `"type": "module"` to your `package.json` |
 | `No network/scheme registered for x402 version: 2 …` | The selected client network has no registered scheme | Ensure the client registers your target network, such as `TRON_NILE` |
-| `Insufficient balance` / allowance error | Test wallet lacks test tokens, or Permit2 allowance too low | Claim test tokens from the faucet; the client auto-approves Permit2 on first payment |
-| `Connection timeout` | Network or request timeout | Check your connection. Note the SDK reads no environment variables — `EVM_RPC_URL` is honoured by the reference example apps; in your own server pass the RPC URL to the signer factory |
+| `Insufficient balance` / allowance error | Test wallet lacks test tokens, or Permit2 allowance too low | Claim test tokens from the faucet. On TRON the client auto-approves Permit2 on first payment; on EVM, approve Permit2 once yourself |
+| `Connection timeout` | Network or request timeout | Check your connection. Note the SDK reads no environment variables — `TRON_GRID_API_KEY` is read by the reference example apps; in your own code pass `apiKey` / `rpcUrl` to the signer factory |
 
 ---
 
@@ -500,15 +493,11 @@ price: "1 USDT",
 
 ### 2. Set a Reliable EVM RPC
 
-BSC mainnet needs a stable endpoint. Set this for both the client and facilitator:
-
-```bash
-EVM_RPC_URL=https://bsc-rpc.publicnode.com
-```
+BSC mainnet needs a stable endpoint, such as `https://bsc-rpc.publicnode.com`. The SDK reads no environment variables, and since v2.1.0 the repository examples are TRON-only — configure the endpoint on the EVM signers you build with official `@x402/evm`, for both the client and a self-hosted facilitator.
 
 ### 3. (Self-Hosted) Switch the Facilitator to Mainnet
 
-The example facilitator's `TRON_NETWORKS` already includes `TRON_MAINNET` (`tron:728126428`), and `EVM_NETWORKS` includes `eip155:97` and `eip155:56` — Base (`eip155:8453` / `eip155:84532`) is not registered there, so add it if you settle on Base. Fund the Facilitator wallet with real TRX/BNB to cover settlement gas, then restart:
+The example facilitator's `TRON_NETWORKS` already includes `TRON_MAINNET` (`tron:728126428`); it registers no EVM networks, so settle BSC or Base through the official facilitator or your own `@x402/evm` facilitator. Fund the Facilitator wallet with real TRX to cover settlement energy, then restart:
 
 ```bash
 pnpm dev:facilitator
diff --git a/docs/x402/index.md b/docs/x402/index.md
index cfbfdf7f..1d93a7a2 100644
--- a/docs/x402/index.md
+++ b/docs/x402/index.md
@@ -17,7 +17,7 @@ x402 currently supports **TRON**, **BNB Smart Chain (BSC)**, and **Base**, with
 Feel free to submit a PR to the [GitHub repository](https://github.com/BofAI/docs). Our only principle is to maintain neutrality — aside from essential resource links, please avoid promotional or branded content.
 
 **Building with x402?**
-Install the published [`@bankofai/x402-*`](https://www.npmjs.com/package/@bankofai/x402-tron) packages in your TypeScript app. The [`x402` repository](https://github.com/BofAI/x402) ships runnable client → server → facilitator examples under `examples/typescript/` for reference — `exact`, `gasfree`, `upto`, and `batch-settlement`.
+Install the published [`@bankofai/x402-tron`](https://www.npmjs.com/package/@bankofai/x402-tron) packages together with the official `@x402/*` packages in your TypeScript app. The [`x402` repository](https://github.com/BofAI/x402) ships runnable client → server → facilitator examples under `examples/typescript/` for reference — `exact`, `gasfree`, `upto`, and `batch-settlement`.
 
 ---
 
@@ -86,9 +86,9 @@ Our goal is to build a low-barrier, permissionless, developer-friendly programma
 
 x402 currently supports the following networks:
 
-- **TRON Mainnet** (`tron:0x2b6653dc`)
-- **TRON Shasta Testnet** (`tron:0x94a9059e`) — SDK/CLI only; not settled by the official facilitator
-- **TRON Nile Testnet** (`tron:0xcd8690dc`)
+- **TRON Mainnet** (`tron:728126428`)
+- **TRON Shasta Testnet** (`tron:2494104990`) — SDK/CLI only; not settled by the official facilitator
+- **TRON Nile Testnet** (`tron:3448148188`)
 - **BSC Mainnet** (`eip155:56`)
 - **BSC Testnet** (`eip155:97`)
 - **Base Mainnet** (`eip155:8453`)
@@ -96,7 +96,9 @@ x402 currently supports the following networks:
 
 Base Mainnet payments use official USDC with the `exact` scheme and EIP-3009 authorization.
 
-> **SDK (TypeScript-only)**: x402 is a TypeScript-only SDK published as granular `@bankofai/x402-*` npm packages (`core`, `evm`, `tron`, `fetch`, `express`, `hono`, `fastify`, `next`, `axios`, `mcp`, `extensions`). The source is maintained in a pnpm/turbo monorepo, but application development should install the published packages. It defines five named schemes: `exact` (ERC-3009 / Permit2), `upto`, `batch-settlement`, `exact_gasfree` (TRON), and the currently client-only `auth-capture` (EVM). The previous-generation Python + TypeScript SDK lives under `legacy/` for reference. See the [SDK Feature Matrix](./x402/sdk-features) for the full breakdown.
+Since x402 v2.0.0, TRON identifiers use decimal chain IDs; the older hex forms (`tron:0x2b6653dc`, `tron:0x94a9059e`, `tron:0xcd8690dc`) are still accepted as input aliases.
+
+> **SDK (TypeScript-only)**: x402 is a TypeScript-only SDK: the TRON mechanism and TRON resource-sponsoring extension ship as `@bankofai/x402-tron` and `@bankofai/x402-tron-extensions`, on top of the official `@x402/*` packages (`core`, `evm`, `fetch`, `express`, `hono`, `fastify`, `next`, `axios`, `mcp`, `extensions`). The source is maintained in a pnpm/turbo monorepo, but application development should install the published packages. It defines five named schemes: `exact` (ERC-3009 / Permit2), `upto`, `batch-settlement`, `exact_gasfree` (TRON), and the currently client-only `auth-capture` (EVM). The previous-generation Python + TypeScript SDK archive was removed in x402 v2.0.0, and the compatibility npm packages under `typescript/packages/legacy/` in v2.1.0. See the [SDK Feature Matrix](./x402/sdk-features) for the full breakdown.
 
 ---
 
diff --git a/docs/x402/sdk-features.md b/docs/x402/sdk-features.md
index 16e72013..ab1da43a 100644
--- a/docs/x402/sdk-features.md
+++ b/docs/x402/sdk-features.md
@@ -1,15 +1,15 @@
 ---
 title: 'SDK Feature Matrix'
-description: 'Feature support matrix for the x402 TypeScript SDK, published as granular @bankofai/x402-* packages.'
+description: 'Feature support matrix for the x402 TypeScript SDK: the @bankofai/x402-tron and @bankofai/x402-tron-extensions packages on official @x402/* Core.'
 ---
 
 # SDK Feature Matrix
 
 This page tracks the feature support of the x402 SDK.
 
-> **SDK (TypeScript-only)**: x402 is a **TypeScript-only** SDK published as granular `@bankofai/x402-*` npm packages. The source is maintained in a pnpm/turbo monorepo, but applications should depend on the published packages. The previous-generation Python + TypeScript SDK lives under `legacy/` for reference.
+> **SDK (TypeScript-only)**: x402 is a **TypeScript-only** SDK. It publishes the TRON mechanism and the TRON resource-sponsoring extension as the `@bankofai/x402-tron` and `@bankofai/x402-tron-extensions` npm packages and builds on the official x402 Foundation `@x402/*` packages for Core, EVM, the HTTP/MCP integrations and the generic extensions. The source is maintained in a pnpm/turbo monorepo, but applications should depend on the published packages. The previous-generation Python + TypeScript SDK archive (`legacy/`) was removed from the repository in 2.0.0, and the `typescript/packages/legacy/` compatibility packages in 2.1.0.
 >
-> **Current release: 1.2.0** (2026-08-28). The 11 `@bankofai/x402-*` packages share one version line but no longer all move together: 1.2.0 published `@bankofai/x402-extensions` and `@bankofai/x402-tron` at `1.2.0`, `@bankofai/x402-express`, `-fastify`, `-hono` and `-next` at `1.1.1`, and left `@bankofai/x402-core`, `-evm`, `-fetch`, `-axios` and `-mcp` at `1.1.0` (no API or dependency change in this release). Each package pins its internal dependencies to `~` of the published version of that dependency, so install the set as published above. The SDK requires **Node.js 22+**.
+> **Current release: 2.1.0** (2026-10-23). The payment call chain now runs on official `@x402/core` `2.28.0`, which `@bankofai/x402-tron` `2.1.0` declares as an exact peer dependency; use the matching official HTTP/MCP integration (`@x402/fetch`, `@x402/axios`, `@x402/express`, `@x402/fastify`, `@x402/hono`, `@x402/next` or `@x402/mcp`, all `2.28.0`). TRON resource sponsoring moved to the separate `@bankofai/x402-tron-extensions` `2.1.0`, which pins the exact mechanism version — upgrade the two TRON packages together. EVM uses official `@x402/evm` `2.28.0` and the generic extensions official `@x402/extensions` `2.28.0`; the local EVM package and `@bankofai/x402-extensions` were removed. `@bankofai/x402-core` and the `@bankofai/x402-*` HTTP/MCP adapters built on it are not interchangeable with the 2.1 mechanism — new TRON integrations use official Core and adapters. Upgrading from 2.0 is a source migration; see the [TRON 2.1 migration guide](https://github.com/BofAI/x402/blob/main/docs/migrations/tron-2.1.md). The SDK requires **Node.js 24.22.1+**; the runnable examples use `@bankofai/agent-wallet` **3.0+**.
 
 ---
 
@@ -17,17 +17,18 @@ This page tracks the feature support of the x402 SDK.
 
 | Package | Purpose |
 |---------|---------|
-| `@bankofai/x402-core` | Protocol types, client/facilitator/server engines, `HTTPFacilitatorClient`, observability |
-| `@bankofai/x402-evm` | EVM mechanism: `exact`, `upto`, `batch-settlement`, plus the `auth-capture` client (`@bankofai/x402-evm/auth-capture/client` — no server or facilitator export) |
-| `@bankofai/x402-tron` | TRON mechanism: `exact`, `upto`, `batch-settlement`, `exact_gasfree` |
-| `@bankofai/x402-fetch` | Wrapped-`fetch` client (`wrapFetchWithPayment`) |
-| `@bankofai/x402-express` | Express server middleware |
-| `@bankofai/x402-hono` | Hono server middleware |
-| `@bankofai/x402-fastify` | Fastify server middleware |
-| `@bankofai/x402-next` | Next.js server middleware |
-| `@bankofai/x402-axios` | Axios client wrapper |
-| `@bankofai/x402-mcp` | MCP transport (client + server) for AI agents |
-| `@bankofai/x402-extensions` | Extensions: EVM gas-sponsoring (`eip2612GasSponsoring`, `erc20ApprovalGasSponsoring`), TRON resource sponsoring (`trc20ApprovalResourceSponsoring`, new in 1.2.0), payment-identifier, bazaar, sign-in-with-x, offer-receipt, builder-code |
+| `@bankofai/x402-tron` | TRON mechanism: `exact`, `upto`, `batch-settlement`, `exact_gasfree`; TRON signer factories, `/rpc` and `/transactions` utilities, TRON logger |
+| `@bankofai/x402-tron-extensions` | TRON approval resource sponsoring (`trc20ApprovalResourceSponsoring`): declaration, client pre-signing extension, facilitator runtime and coordinator — moved here in 2.1.0 |
+| `@x402/core` (official) | Protocol types, client/facilitator/server engines, `HTTPFacilitatorClient` |
+| `@x402/evm` (official) | EVM mechanism: `exact`, `upto`, `batch-settlement`, plus the `auth-capture` client (`@x402/evm/auth-capture/client` — no server or facilitator export) |
+| `@x402/fetch` (official) | Wrapped-`fetch` client (`wrapFetchWithPayment`) |
+| `@x402/express` (official) | Express server middleware |
+| `@x402/hono` (official) | Hono server middleware |
+| `@x402/fastify` (official) | Fastify server middleware |
+| `@x402/next` (official) | Next.js server middleware |
+| `@x402/axios` (official) | Axios client wrapper |
+| `@x402/mcp` (official) | MCP transport (client + server) for AI agents |
+| `@x402/extensions` (official) | Generic extensions: EVM gas-sponsoring (`eip2612GasSponsoring`, `erc20ApprovalGasSponsoring`), payment-identifier, bazaar, sign-in-with-x, offer-receipt, builder-code |
 
 ---
 
@@ -55,14 +56,14 @@ This page tracks the feature support of the x402 SDK.
 | `tron:728126428` | `TRON_MAINNET` | ✅ |
 | `tron:3448148188` | `TRON_NILE` | ✅ |
 | `tron:2494104990` | `TRON_SHASTA` | ✅ |
-| `eip155:56` (BSC Mainnet) | - | ✅ |
-| `eip155:97` (BSC Testnet) | - | ✅ |
+| `eip155:56` (BSC Mainnet) | - | ✅ (explicit asset only) |
+| `eip155:97` (BSC Testnet) | - | ✅ (explicit asset only) |
 | `eip155:8453` (Base Mainnet) | - | ✅ |
 | `eip155:84532` (Base Sepolia) | - | ✅ (CLI/SDK testing) |
 
-> **TRON ID format**: since `@bankofai/x402-tron` 2.0.0 the SDK constants use decimal CAIP-2 references. The older hexadecimal forms (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) are still accepted as input aliases, and are what the official facilitator and the API catalog currently report.
+> **TRON ID format**: since `@bankofai/x402-tron` 2.0.0 the SDK constants use decimal CAIP-2 references. The older hexadecimal forms (`tron:0x2b6653dc`, `tron:0xcd8690dc`, `tron:0x94a9059e`) are still accepted as input aliases and are normalized to the decimal form. The official facilitator reports the decimal identifiers in `/supported`; the API Catalog still lists the hexadecimal forms.
 
-> Twenty further upstream EVM chains (MegaETH, Monad, Polygon, Arbitrum One/Sepolia, Celo, XDC, Flare, Mezo, Radius, Stable, ADI, HPP, Igra, …) are also wired into the EVM default-asset registry. The public API Catalog publishes Base Mainnet routes only; Base Sepolia remains available for CLI/SDK testing.
+> EVM support comes from the official `@x402/evm` 2.28.0. Its default-asset registry covers Base, Base Sepolia, Ethereum, Polygon, Arbitrum One/Sepolia, Avalanche, Celo, Sei, MegaETH, Monad, Stable, XDC, Flare, Mezo, Radius, ADI, HPP, Igra and others — but **not BSC**. On BSC, price a route with an explicit `{ asset, amount, extra }` object (a `$` price fails with `No default asset configured for network eip155:56`), and clients must allowlist the asset in `spendControls.allowedAssets`. The public API Catalog publishes Base Mainnet routes only; Base Sepolia remains available for CLI/SDK testing.
 
 ---
 
@@ -90,7 +91,7 @@ A scheme/network server now declares which payment flows it supports per asset-t
 
 Legacy v1.0 `SchemeNetworkServer` implementations may omit their payment-flow declaration; they continue to use the authorization flow.
 
-`upfront` and `escrow` are orchestration hooks for custom schemes. As of 1.1.0 every built-in server scheme (`exact`, `upto`, `batch-settlement`, `exact_gasfree`) declares `authorization` only, so `extra.paymentFlow` does not appear on the wire with the shipped schemes.
+The TRON server schemes (`exact`, `upto`, `batch-settlement`, `exact_gasfree`) and the EVM `upto` and `batch-settlement` schemes declare `authorization` only. The official EVM `exact` scheme (`@x402/evm`) also supports `upfront`, for both `eip3009` and `permit2`: a route opts in by setting `extra: { paymentFlow: "upfront" }` on that payment option, and only then does `extra.paymentFlow` appear on the wire. No shipped scheme declares `escrow`; it remains a hook for custom schemes.
 
 > **x402 Foundation v2 compatibility**: The `exact` scheme (EVM and TRON) conforms to the v2 wire format published by the **x402 Foundation**. Stock v2 clients interoperate with this SDK's server and vice versa. See [Network & Token Support → `exact` Scheme](./core-concepts/network-and-token-support.md#exact-scheme) for details.
 
@@ -98,31 +99,42 @@ Legacy v1.0 `SchemeNetworkServer` implementations may omit their payment-flow de
 
 ## Extensions {#extensions}
 
-`@bankofai/x402-extensions` ships optional protocol extensions: `bazaar`, `sign-in-with-x`, `offer-receipt`, `payment-identifier`, `eip2612-gas-sponsoring`, `erc20-approval-gas-sponsoring`, `trc20-approval-resource-sponsoring`, and `builder-code`. All of them are exported from the package root — there is no per-extension import subpath for the sponsoring extensions. A resource server declares an extension in `PaymentRequired.extensions`; the sponsoring extensions and `payment-identifier` act only on a declared extension, while `builder-code` attribution is attached by whichever party registered it.
+The generic protocol extensions — `bazaar`, `sign-in-with-x`, `offer-receipt`, `payment-identifier`, `eip2612-gas-sponsoring`, `erc20-approval-gas-sponsoring`, and `builder-code` — come from official `@x402/extensions` `2.28.0`: most through subpaths such as `@x402/extensions/bazaar`, the two EVM gas-sponsoring extensions from the package root. TRON `trc20-approval-resource-sponsoring` ships separately in `@bankofai/x402-tron-extensions`, exported from its root and from `/trc20-approval-resource-sponsoring` (with `/client`, `/facilitator` and `/resourceService` beneath it). A resource server declares an extension in `PaymentRequired.extensions`; the sponsoring extensions and `payment-identifier` act only on a declared extension, while `builder-code` attribution is attached by whichever party registered it.
 
-### TRON approval resource sponsoring (new in 1.2.0)
+### TRON approval resource sponsoring (new in 1.2.0, separate package since 2.1.0)
 
 `trc20ApprovalResourceSponsoring` (wire-schema version `1`) lets a payer make their **first** TRON Permit2 payment or channel deposit without holding TRX. Instead of broadcasting the one-time `approve(Permit2, MaxUint256)` itself, the client signs that transaction and attaches the signed bytes to the payment payload; the facilitator strictly decodes and validates them against the selected payment, temporarily delegates the Stake 2.0 Energy — and, when needed, Bandwidth — that the payer lacks, broadcasts the transaction unchanged, and reclaims the delegation afterwards through a recoverable state machine.
 
 | Party | What it does |
 |-------|--------------|
 | Resource server | **Opts in** — spread `declareTrc20ApprovalResourceSponsoringExtension()` into the route's `extensions`. The route must use `extra.assetTransferMethod: "permit2"`. |
-| Client | **Nothing to configure** — `@bankofai/x402-tron` attaches the signed approval automatically when the server declared version `1`, the selected path uses Permit2, and the current Permit2 allowance is insufficient. |
-| Facilitator | **Opts in** — register `createTrc20ApprovalResourceSponsoringExtension(runtime)` with a runtime built by `createTrc20ResourceSponsoringRuntime({ ... })` from `@bankofai/x402-tron`. |
+| Client | **Opts in** (since 2.1.0) — register `client.registerExtension(createTrc20ApprovalResourceSponsoringClientExtension(signer))` after the payment schemes. It attaches the signed approval when the server declared version `1`, the selected path uses Permit2, and the current Permit2 allowance is insufficient. Without it, a sponsored payment fails with `trc20_approval_client_extension_not_registered`. |
+| Facilitator | **Opts in** — register `createTrc20ApprovalResourceSponsoringExtension(runtime)` with a runtime built by `createTrc20ResourceSponsoringRuntime({ ... })`, both from `@bankofai/x402-tron-extensions`. A facilitator without the runtime returns `sponsor_runtime_unavailable`. |
 
 It applies to TRON `exact` (with `assetTransferMethod: "permit2"`), TRON `upto`, and the Permit2 **deposit/top-up** path of `batch-settlement`. It is not used for EIP-3009 transfers, nor for batch vouchers, claims, settles, or refunds. It sponsors only that one `approve` transaction — the scheme payload still remains the sole authority over amount, recipient, nonce, and deadline, and no fee is charged inside the approval. There is no new endpoint: the flow stays `402 Payment Required` → `PAYMENT-SIGNATURE` → `/verify` → `/settle`.
 
 ```typescript
-import { declareTrc20ApprovalResourceSponsoringExtension } from "@bankofai/x402-extensions";
-
-const route = {
-  price: {
-    amount: "1000000",
-    asset: "T...",
-    extra: { assetTransferMethod: "permit2" },
-  },
-  extensions: {
-    ...declareTrc20ApprovalResourceSponsoringExtension(),
+import type { RoutesConfig } from "@x402/core/http";
+import { TRON_NILE } from "@bankofai/x402-tron";
+import { declareTrc20ApprovalResourceSponsoringExtension } from "@bankofai/x402-tron-extensions";
+
+const routes: RoutesConfig = {
+  "GET /weather": {
+    accepts: [
+      {
+        scheme: "exact",
+        network: TRON_NILE,
+        payTo: "T...",
+        price: {
+          amount: "1000000",
+          asset: "T...",
+          extra: { assetTransferMethod: "permit2" },
+        },
+      },
+    ],
+    extensions: {
+      ...declareTrc20ApprovalResourceSponsoringExtension(),
+    },
   },
 };
 ```
@@ -131,23 +143,22 @@ const route = {
 - The payer must be an **activated, single-signature TRON EOA** using the default owner permission. Multisig and custom-permission accounts are not supported.
 - Under the default `zero-first` approval strategy a **non-zero but insufficient** allowance is rejected with `approval_reset_required` — the SDK never inserts an implicit `approve(0)`. A token that is not a known Permit2 asset raises `approval_asset_unsupported` unless you configure a strategy for it with `createTrc20ApprovalPolicy`.
 - A production facilitator must back the runtime with a durable operation coordinator and run reconciliation at startup and on a schedule. The exported `InMemoryTrc20SponsoringCoordinator` is for tests and single-process development only.
-- The [official facilitator](./core-concepts/OfficialFacilitator.md) does **not** currently enable this extension. TRON approval sponsoring requires a self-hosted facilitator with a resource-owner wallet that has Stake 2.0 capacity.
+- The [official facilitator](./core-concepts/OfficialFacilitator.md) advertises this extension in `/supported`, but its production configuration sponsors **TRON Nile USDT only** and requires an API Key. Sponsoring on TRON Mainnet, or for other tokens, requires a self-hosted facilitator with a resource-owner wallet that has Stake 2.0 capacity.
 :::
 
 ---
 
 ## Signers
 
-Key custody is in [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wallet); the SDK never sees a raw private key. The signer factories build the chain client (viem / TronWeb) internally.
+The TRON signer factories in `@bankofai/x402-tron` adapt a wallet — such as one resolved by [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wallet) — so the SDK never sees a raw private key, and build TronWeb internally.
 
 | Signer factory | Role |
 |----------|------|
 | `createClientTronSigner` | Client (TRON) |
-| `createClientEvmSigner` | Client (EVM) |
 | `createFacilitatorTronSigner` | Facilitator (TRON) |
-| `createFacilitatorEvmSigner` | Facilitator (EVM) |
 | `createAuthorizerTronSigner` | Authorizer (TRON, batch-settlement) |
-| `createAuthorizerEvmSigner` | Authorizer (EVM, batch-settlement) |
+
+EVM signing uses the public signer adapters of official `@x402/evm` (for example `toClientEvmSigner` and `toFacilitatorEvmSigner`). The former `@bankofai/x402-evm` agent-wallet factories (`createClientEvmSigner`, `createFacilitatorEvmSigner`, `createAuthorizerEvmSigner`) were retired in 2.1.0; follow the [upstream EVM examples](https://github.com/x402-foundation/x402/tree/main/examples/typescript).
 
 ---
 
@@ -181,7 +192,7 @@ Since 1.1.0 a client will only pay assets it recognizes from the default-asset r
 | Protected-route integration | ✅ (`paymentMiddlewareFromHTTPServer`, `x402HTTPResourceServer`) |
 | Multi-chain `accepts` advertisement | ✅ |
 | Gas-sponsoring extension, EVM (`eip2612GasSponsoring` / `erc20ApprovalGasSponsoring`) | ✅ |
-| Resource-sponsoring extension, TRON (`trc20ApprovalResourceSponsoring`) | ✅ — new in 1.2.0; declare with `declareTrc20ApprovalResourceSponsoringExtension()` |
+| Resource-sponsoring extension, TRON (`trc20ApprovalResourceSponsoring`) | ✅ — new in 1.2.0; declare with `declareTrc20ApprovalResourceSponsoringExtension()` from `@bankofai/x402-tron-extensions` |
 | Payment verification (via facilitator) | ✅ |
 | Payment settlement (via facilitator) | ✅ |
 
@@ -198,10 +209,13 @@ Since 1.1.0 a client will only pay assets it recognizes from the default-asset r
 | Confirm transaction (receipt polling) | ✅ |
 | Extension hooks (`onBeforeSettle` / `onAfterSettle` / `onSettleFailure`) | ✅ |
 | EVM smart accounts — deployed accounts, ERC-7702 delegation, ERC-6492 counterfactual wallets | ✅ — signature verification is facilitator-side; ERC-6492 requires an explicit `eip6492AllowedFactories` allowlist |
+| Pending settlement (`settlement_pending`) | ✅ — new in 2.0.0. When a transaction was broadcast but its receipt is not yet known, settlement returns the non-terminal `settlement_pending` with the original transaction ID; reconcile that transaction instead of resubmitting. TRON receipt waiting defaults to 90 s (`confirmationTimeoutMs` on `createFacilitatorTronSigner`) |
+| Pending-settlement recovery, TRON | ✅ — new in 2.1.0. The TRON facilitator schemes save the original transaction ID (or GasFree relayer trace) before waiting for the receipt, so a retry of the same payment resumes it instead of broadcasting again. The default `InMemoryTronPendingSettlementStore` covers one process only; for restarts or multiple replicas, inject a persistent, shared `TronPendingSettlementStore` through the `pendingSettlementStore` constructor option. A failed save after broadcast returns `settlement_store_unavailable` (keeping the known transaction ID); an unhandled settlement callback error returns `settlement_execution_failed` |
+| `upto` preflight reads, TRON | ✅ — new in 2.1.0. A failed or malformed allowance/balance read returns `chain_read_failed` before any settlement is broadcast |
 
 > The self-hosted example facilitator (`facilitator/basic`) exposes `/verify`, `/settle`, `/supported`. The official hosted facilitator additionally offers the settlement-record queries `GET /payments/tx/{tx_hash}` and `GET /payments`, plus `/health` — see [Official Facilitator](./core-concepts/OfficialFacilitator.md). Prometheus metrics are served on a separate monitoring port (`9001` in the shipped configs), not on the public API base. There is no `/fee/quote` endpoint: the SDK schemes carry no facilitator fee.
 >
-> `HTTPFacilitatorClient` uses typed timeout errors and a 90-second default timeout since 1.1.0. Its rate-limit retry (3 attempts) applies to `getSupported()` only — `verify()` and `settle()` surface a 429 to the caller rather than retrying.
+> Since 2.1.0, `HTTPFacilitatorClient` comes from official `@x402/core` `2.28.0`: it uses typed timeout errors and a 90-second default timeout, and the repository examples set `timeoutMs: 120_000` explicitly. After switching to the official HTTP/MCP packages, recheck your request timeouts. Its rate-limit retry (3 attempts) applies to `getSupported()` only — `verify()` and `settle()` surface a 429 to the caller rather than retrying.
 
 ---
 
@@ -211,24 +225,23 @@ Since 1.1.0 a client will only pay assets it recognizes from the default-asset r
 |--------|---------|--------|
 | USDT (TRC-20) | `tron:728126428`, `tron:3448148188`, `tron:2494104990` | ✅ |
 | USDD (TRC-20) | `tron:728126428`, `tron:3448148188` | ✅ |
-| USDT (BEP-20) | `eip155:56`, `eip155:97` | ✅ |
-| USDC (BEP-20) | `eip155:56`, `eip155:97` | ✅ |
-| DHLU (BSC testnet, ERC-3009) | `eip155:97` | ✅ |
+| USDT (BEP-20) | `eip155:56`, `eip155:97` | ✅ (explicit asset) |
+| USDC (BEP-20) | `eip155:56`, `eip155:97` | ✅ (explicit asset; the `eip155:56` address is in no shipped token registry) |
 | Official USDC (ERC-20, EIP-3009) | `eip155:8453`, `eip155:84532` | ✅ |
-| Custom TRC-20 / BEP-20 | any | ✅ (via token registry / `EVM_TOKENS` config) |
+| Custom TRC-20 / BEP-20 | any | ✅ (via the TRON token registry / an explicit `{ asset, amount, extra }` price) |
 
-> Only some of these are **default assets**: USDT on TRON and BSC Mainnet, USDC on BSC Testnet and Base. Since 1.1.0 a client's spend controls reject every other asset — USDD, BSC Mainnet USDC, BSC Testnet USDT, DHLU, custom tokens — unless it is allowlisted via `spendControls.allowedAssets`. See [Network & Token Support](./core-concepts/network-and-token-support.md#supported-tokens).
+> Only some of these are **default assets**: USDT on the three TRON networks and USDC on Base and Base Sepolia. Since 1.1.0 a client's spend controls reject every other asset — USDD, every BSC asset, custom tokens — unless it is allowlisted via `spendControls.allowedAssets`. See [Network & Token Support](./core-concepts/network-and-token-support.md#supported-tokens).
 
 ---
 
 ## Observability
 
-All `@bankofai/x402-*` packages write through one process-global logger from `@bankofai/x402-core`. Call `setLogger(...)` once at startup to redirect logs to a file, `pino`/`winston`, or `noopLogger` to silence.
+The TRON mechanism writes through a process-global logger exported by `@bankofai/x402-tron` (since 2.1.0; previously from `@bankofai/x402-core`). Call `setLogger(...)` once at startup to redirect logs to a file, `pino`/`winston`, or `noopLogger` to silence. Official `@x402/core` and `@x402/extensions` do not use this logger — register lifecycle hooks where you need their events logged.
 
 ---
 
 ## Legend
 
 - ✅ = Implemented
-- ⏳ = Planned / In Progress
-- ❌ = Not Planned
+- ⚠️ = Partially implemented (see the notes column)
+- ❌ = Not supported
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md
index 70441a61..62c3e8e2 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/x402.md
@@ -7,6 +7,46 @@ description: 'x402 支付协议、SDK 与 CLI 的版本发布记录。'
 
 x402 协议、SDK 与 [Wallet CLI 指引](/zh-Hans/wallet-cli/) 的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### Facilitator 错误码补全
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- facilitator 错误列表补充了协议层的赞助原因（`approval_transaction_reused`、`sponsor_approval_lifetime_exceeded`、`sponsor_existing_delegation`）、`/settle` 的 `400 permit2_invalid_authorization`、`500 internal_error`，以及 GasFree 代理的 `502 bad_gateway`。
+- **Wallet CLI 命令参考**——新增常见错误码表（`missing_wallet_address`、`auth_required`、`invalid_option`、`no_matching_requirement`、`permit2_allowance_required` 等）及退出码，并补充 `bai recharge` 的规则：`--to`、代币默认值（Base 上 USDC，其他网络 USDT）和触发 `invalid_amount` 的最低金额。
+
+👉 [Facilitator](/zh-Hans/x402/core-concepts/facilitator/) · [Wallet CLI 命令参考](/zh-Hans/wallet-cli/command-reference/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-25</div>
+<div className="changelog-body">
+
+### 文档对齐 SDK 2.1.0 与 Facilitator v2.2.2
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **SDK 2.1.0**——SDK 相关页面按 2.1.0 版本组合更新：`@bankofai/x402-tron` 2.1.0 与新增的 `@bankofai/x402-tron-extensions` 2.1.0（两者需一起升级）运行在官方 `@x402/core` 2.28.0 之上，搭配官方 `@x402/*` HTTP/MCP 集成、`@x402/evm` 与 `@x402/extensions` 2.28.0。快速入门改为从 `@x402/core`、`@x402/fetch`、`@x402/express` 导入，并用 `new x402ResourceServer(...)` 取代 `@bankofai/x402-core` 的 `createResourceServer`（2.1 机制不使用它）。本地 EVM 包、`@bankofai/x402-extensions` 与 `typescript/packages/legacy/` 兼容包已在 2.1.0 删除（根目录 `legacy/`，含已退役的 Python SDK，早在 2.0.0 删除）。TRON 资源赞助现在需要显式注册 client 扩展；SDK 要求 Node.js 24.22.1+。官方 `@x402/evm` 不内置 BSC 默认资产，BSC 路由须用显式的 `{ asset, amount, extra }` 对象定价，client 也须放行 BSC 资产；在本文档涉及的网络中，默认资产现为 TRON 上的 USDT 与 Base / Base Sepolia 上的 USDC。
+- **待确认结算**——补充了 `settlement_pending`：它不是终态，应对账而不是重新提交。2.1.0 新增可注入的 `pendingSettlementStore`（默认的 `InMemoryTronPendingSettlementStore` 只覆盖单个进程），以及 `settlement_store_unavailable`、`settlement_execution_failed` 错误码，并把 `chain_read_failed`（此前已用于 `exact` 的 Permit2 读取）扩展到 `upto` 的预检读取。`HTTPFacilitatorClient` 现在来自官方 Core，默认超时 90 秒；示例设置为 120 秒。
+- **示例仅覆盖 TRON**——仓库示例现在只覆盖 TRON，卖家快速入门因此引导 BSC 与 Base 卖家使用官方 facilitator 或上游 `@x402/evm` 示例。官方 facilitator v2.2.1 与 v2.2.2 都是安全更新版本（更新 Node.js 与依赖；v2.2.2 还装入了修复 CVE-2026-111497 的系统 Brotli），文档中描述的行为不变。
+- **TRON ID 改为十进制**——示例和表格统一使用 `tron:728126428`（主网）、`tron:3448148188`（Nile）、`tron:2494104990`（Shasta），x402 SDK 仍接受十六进制写法作为输入，wallet-cli 的 `--network` 不接受。API Catalog 例外：它的 schema 目前只接受十六进制。
+- **官方 Facilitator 限流**——匿名调用每个 IP 每分钟 10 次，API Key 每分钟 1,000 次，`/verify` 与 `/settle` 分别计数（两者都限流）。超限返回 `429` 并带 `Retry-After`。此前文档写的是每分钟一次 `/settle`。
+- **Nile 资源赞助**——官方 Facilitator 在 `/supported` 中列出 `trc20ApprovalResourceSponsoring`，但仅在 Nile 为 Nile USDT 启用，且需要 API Key（否则返回 `sponsor_auth_required` / `sponsor_network_disabled`）。补充了 `GET /sponsoring/ready` 以及 `/verify`、`/settle` 的错误码。
+- **结算记录**——成功的结算按 (network, asset, payer, nonce) 由部分唯一索引保证唯一。这更正了 9 月 9 日记录中"表上没有唯一约束"的说法。
+- **API Catalog**——本地自检需要 Python 3.11+；提交清单补齐其余 CI 规则（`pay.md` 必含的字符串、TRON 第一条路由须为 `exact` + `permit2`、不得出现 `--scheme exact_gasfree`、`status` 四个键必填），并说明写死数量的测试需在同一个 PR 里更新。列表命令读取本地缓存，只有缓存不存在或缺少所需内容时才下载，因此缓存可能过期时请运行 `update-catalog` 刷新。
+- **Wallet CLI 命令参考**——改为以 `@tron-walletcli/wallet-cli@4.15.1` 为准，补充已知稳定币默认每笔最多 1 美元的上限（`amount_exceeds_limit`）、`--out`（二进制响应必须使用）、`--max-gasfree-fee-raw`，以及 `--max-raw-amount` 必须同时指定 `--token` 或 `--asset`。快速入门提示 TRON 上某代币的首次 `exact` 付款可能先广播一次 `approve(Permit2, MaxUint256)`；结果说明补充了结算后出现响应格式错误的情况（`retryPayment: false`）。快速入门还注明 wallet-cli Skill 锁定 4.14.0，配合 Skill 使用时应安装该版本。
+- **协议细节**——`402` 的付款要求放在 Base64 编码的 `PAYMENT-REQUIRED` 头中，响应体为 `{}`；验证失败的原因也在该头的 `error` 字段；`exact` / `upto` 的 Permit2 额度不足返回 `412 permit2_allowance_required`。EVM `exact` 还支持 `upfront` 付款流程。Permit2 载荷使用 `payload.permit2Authorization`。代币表删除了 DHLU（现有代码均不再引用），BSC 主网 USDC 标注为仅可作为显式资产；官方 Facilitator 的限流计数按实例；npm 包许可证为 Apache-2.0（仓库 LICENSE 为 MIT）。
+
+👉 [SDK 功能](/zh-Hans/x402/sdk-features/) · [官方 Facilitator](/zh-Hans/x402/core-concepts/OfficialFacilitator/) · [上架服务](/zh-Hans/x402/api-catalog/list-your-service/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-28</div>
 <div className="changelog-body">
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/AGENTS.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/AGENTS.md
index 58f225b5..40921997 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/AGENTS.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/AGENTS.md
@@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem';
 - `docs/faq.md` — 常见问题解答。
 - `sidebars.js` — Docusaurus 侧边栏配置文件。
 - `docusaurus.config.js` — Docusaurus 主配置文件。
-- `docs/sdk-features.md` — 仅 TypeScript 的 x402 SDK（`@bankofai/x402-*` 包）功能矩阵。
+- `docs/sdk-features.md` — 仅 TypeScript 的 x402 SDK（基于官方 `@x402/*` 包的 `@bankofai/x402-tron` 与 `@bankofai/x402-tron-extensions`）功能矩阵。
 
 ## 3. 代码与文档的同步机制
 
@@ -28,8 +28,8 @@ import TabItem from '@theme/TabItem';
 - 底层机制的变更 $\rightarrow$ 需更新 `core-concepts` 文档。
 
 ## 4. 风格与规范 
-- 以 **TypeScript** 作为主要代码示例（SDK 仅 TypeScript；此前的 Python SDK 已移至 `legacy/`）。
-- 优先提供可直接基于已发布 `@bankofai/x402-*` npm 包运行的代码示例。`examples/typescript/` 中的可运行代码可作为与包 API 一致时的参考实现。
+- 以 **TypeScript** 作为主要代码示例（SDK 仅 TypeScript；此前的 Python SDK 已在 x402 v2.0.0 中移除）。
+- 优先提供可直接基于已发布 npm 包（`@bankofai/x402-tron`、`@bankofai/x402-tron-extensions` 与官方 `@x402/*`）运行的代码示例。`examples/typescript/` 中的可运行代码可作为与包 API 一致时的参考实现。
 - 所有 API 调用示例必须包含完整的错误处理逻辑。
 - 内容撰写面向具有 **2–5 年经验** 的开发者。
 - 必须使用 Docusaurus MDX 组件（`<Tabs>`、`<TabItem>`）来展示多语言代码。
@@ -58,7 +58,7 @@ import TabItem from '@theme/TabItem';
 <Tabs>
   <TabItem value="TRON" label="TRON">
 
-- **网络标识**：必须遵循 `tron:<hex_chain_id>` CAIP-2 格式。优先使用 `@bankofai/x402-tron` 导出的常量（`TRON_MAINNET`、`TRON_NILE`、`TRON_SHASTA`），不要硬编码旧的名称。
+- **网络标识**：必须遵循 `tron:<decimal_chain_id>` CAIP-2 格式（如 Nile 为 `tron:3448148188`）；`tron:0xcd8690dc` 这类十六进制写法是已弃用的输入别名。优先使用 `@bankofai/x402-tron` 导出的常量（`TRON_MAINNET`、`TRON_NILE`、`TRON_SHASTA`），不要硬编码旧的名称。
 - **签名标准**：TRON 签名必须引用 **TIP-712** 标准（请勿混淆为 EIP-712）。
 - **地址格式**：Token 地址必须使用 Base58 编码格式（即以 `T` 开头的地址）。
 - **节点接入**：节点访问需指向 TronGrid 端点。
@@ -126,7 +126,7 @@ import TabItem from '@theme/TabItem';
 - `*/signers/` 目录中新增了签名器。
 - 客户端 (Client) 或服务端 (Server) 新增了功能特性。
 
-**注意**：SDK 仅 TypeScript。更新文档时需对照已发布的 `@bankofai/x402-*` 包 API、`typescript/packages/` 的导出与 `examples/typescript/` 的参考源码交叉检查。
+**注意**：SDK 仅 TypeScript。更新文档时需对照已发布包（`@bankofai/x402-tron`、`@bankofai/x402-tron-extensions`、官方 `@x402/*`）的 API、`typescript/packages/` 的导出与 `examples/typescript/` 的参考源码交叉检查。
 
 
 ## 12.开发常用命令 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md
index a411c026..14e31e86 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/get-started.md
@@ -5,18 +5,18 @@ description: "用 wallet-cli 查询目录和预览付费接口。"
 
 # Catalog 快速入门
 
-先按 [Wallet CLI 快速入门](/zh-Hans/wallet-cli/quickstart/)安装 `@tron-walletcli/wallet-cli@4.14.0`。目录查询不需要钱包或密码，支付预览和付款需要已配置账户。
+先按 [Wallet CLI 快速入门](/zh-Hans/wallet-cli/quickstart/)安装 Wallet CLI。目录查询不需要钱包或密码，支付预览和付款需要已配置账户。
 
 ## 浏览目录
 
 ```bash
+wallet-cli x402 update-catalog -o json
 wallet-cli x402 provider-list -o json
 wallet-cli x402 provider-show dia -o json
 wallet-cli x402 endpoint-list dia -o json
-wallet-cli x402 update-catalog -o json
 ```
 
-`provider-list` 可按支持的网络、类别和 capability 过滤。`update-catalog` 会更新本地缓存。
+`update-catalog` 把目录下载到本地缓存。`provider-list`、`provider-show` 和 `endpoint-list` 读取该缓存，只有缓存不存在或缺少所需内容时才从目录下载；它们不会刷新缓存，需要最新的服务和价格时请重新运行 `update-catalog`。`provider-list` 支持 `--network`、`--category` 和 `--capability` 过滤。
 
 ## 选择接口和网络
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md
index cf73d5ad..b2bd5e14 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/index.md
@@ -35,7 +35,7 @@ import ThemedImage from '@theme/ThemedImage';
 
 - **[前端目录站](https://bankofai.io/catalog)**：给人浏览、比较服务。
 - **wallet-cli**：在命令行里搜索、查看、直接付费调用。
-- **MCP**：`@bankofai/x402-mcp` 让 Agent 能通过 MCP 为 x402 端点付款。支持目录发现的 MCP（在 MCP 客户端里按名称浏览目录）尚未发布，当前请用 `wallet-cli x402 provider-list` 做发现。
+- **MCP**：`@x402/mcp`（SDK 2.1.0 起使用的官方 MCP 集成）让 Agent 能通过 MCP 为 x402 端点付款。支持目录发现的 MCP（在 MCP 客户端里按名称浏览目录）尚未发布，当前请用 `wallet-cli x402 provider-list` 做发现。
 
 ## 目录里有什么
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md
index 130bde1f..322b1c12 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md
@@ -163,7 +163,7 @@ SunPump 服务的真实文件 `providers/sunpump-token-launch/catalog.json`：
 
 ### pay.md 怎么写
 
-`pay.md` 是人和 Agent 都会读的调用说明，建议包含三部分：服务基本信息、各端点的地址与价格、可直接复制的调用示例。目录仓库的 CI 测试要求每个 `pay.md` 都包含带 `--network tron:728126428` 和 `--scheme exact` 的 `wallet-cli x402 pay` 示例、提到 `exact_gasfree`，并覆盖 Base 主网（`eip155:8453`）。SunPump 的真实文件 `providers/sunpump-token-launch/pay.md`：
+`pay.md` 是人和 Agent 都会读的调用说明，建议包含三部分：服务基本信息、各端点的地址与价格、可直接复制的调用示例。目录仓库的 CI 测试要求每个 `pay.md` 都包含带 `--network tron:728126428` 和 `--scheme exact` 的 `wallet-cli x402 pay` 示例、提到 `exact_gasfree`，并覆盖 Base 主网：文中必须出现 `Base Mainnet`、`eip155:8453`、以 `-base` 结尾的 gateway provider、`USDC` 和 `EIP-3009`，且不得出现 `Sepolia` 或 `eip155:84532`。SunPump 的真实文件 `providers/sunpump-token-launch/pay.md`：
 
 ````markdown
 # SunPump Agent Token Launch API
@@ -286,20 +286,21 @@ CI 会强制以下规则，建议提交前逐条对照：
 - `version` 必须为 `1`。
 - `fqn` 为小写字母/数字/连字符，且与目录名一致。
 - `category` 必须是合法类目之一（见[参考](./reference.md#合法类目)）。
-- `chains` 至少一条，使用 CAIP-2 风格的链 ID。TRON 链 ID 只能是 `tron:0x2b6653dc`、`tron:0xcd8690dc` 或 `tron:0x94a9059e`。CI 测试要求每个服务都列出 Base 主网 `eip155:8453`，并拒绝 Base Sepolia `eip155:84532`。
+- `chains` 至少一条，使用 CAIP-2 风格的链 ID。TRON 链 ID 只能是 `tron:0x2b6653dc`、`tron:0xcd8690dc` 或 `tron:0x94a9059e`，十进制形式（`tron:728126428`）会被拒绝，见[链 ID](./reference.md#链-id)。CI 测试要求每个服务都列出 Base 主网 `eip155:8453`，并拒绝 Base Sepolia `eip155:84532`。
 - `isFirstParty`、`isFeatured`（布尔值）与 `featuredTags`（字符串数组，可为空 `[]`）为**必填**，缺一即校验失败。
 - 每个 endpoint 的 `method` 必须大写、`path` 以 `/` 开头、`maxPriceUsd` 不小于 `minPriceUsd`。
 - `serviceUrl`、各端点 `url` 和各路由 `url` 都必须以 `https://` 开头。
 - 不允许出现未定义的字段——顶层、端点、路由、`i18n.<locale>` 和 `status` 都会拒绝未知字段。
 - `x402Routes` 在 schema 中是选填，但 CI 测试要求每个端点恰好发布一条 Base 主网路由：`scheme` 为 `exact`、`assetTransferMethod` 为 `eip3009`，`provider` 以 `-base` 结尾。每条路由的 `network` 都必须出现在 `chains` 里，`exact_gasfree` 只能用于 TRON 网络。每条路由都需要 `network`、`provider`、`scheme` 和 `url`；`exact` 路由还必须带 `assetTransferMethod`（`permit2` 或 `eip3009`），`exact_gasfree` 路由则必须**省略**该字段。同一网络可以出现多次——TRON 通常同时发布 `exact` 与 `exact_gasfree` 两条路由——只要每组 `(provider, network, scheme, url)` 唯一即可。旧的 `fee` / `feeConfig` 字段会被拒绝。详见[参考](./reference.md#x402routes--多网络路由)。
+- 凡有 TRON 路由的端点，第一条 TRON 路由必须是 `exact` + `permit2`（默认方式）；服务级 `description`（含 `i18n` 翻译）不得包含 `--scheme exact_gasfree`。
 - 服务与每个 endpoint 都必须提供 `i18n.zh-CN` 的 `title`、`subtitle`、`description`、`useCase`。
-- 如填写 `status`，取值只能是：`catalog` 为 `listed`/`unlisted`；`gateway` 为 `configured`/`unknown`/`unavailable`；`payment` 为 `paid-route`/`mainnet`/`testnet`/`unknown`；`upstream` 为 `public`/`authenticated`/`unknown`/`unavailable`。
+- `status` 可不填；如填写，四个键都必须给出，取值只能是：`catalog` 为 `listed`/`unlisted`；`gateway` 为 `configured`/`unknown`/`unavailable`；`payment` 为 `paid-route`/`mainnet`/`testnet`/`unknown`；`upstream` 为 `public`/`authenticated`/`unknown`/`unavailable`。
 - `pay.md` 必须与 `catalog.json` 一同提交，两份文件都会被敏感信息扫描。
 - 不得包含任何密钥、私钥或内网地址。
 
 ## 第 2 步：本地自检
 
-提交前先安装校验依赖，再在本地跑一遍校验、构建和单元测试（与 CI 的步骤相同）：
+提交前先安装校验依赖，再在本地跑一遍校验、构建和单元测试（与 CI 的步骤相同）。脚本需要 Python 3.11 或更高版本（CI 用 3.12）；在 3.10 上会报 `ImportError: cannot import name 'UTC' from 'datetime'`。
 
 ```bash
 pip install -r requirements.txt
@@ -310,6 +311,10 @@ python3 -m unittest discover -s tests
 
 前两条会输出 `validated N provider(s)` 和 `built N provider(s) into dist`，N 是仓库里全部服务的数量（包括你新加的）。
 
+:::note 测试里写死的数量
+`tests/test_build.py` 固定了目录当前的若干总数，例如所有服务的 Base 主网路由总数。新服务即使通过 `validate.py`，也可能在这些断言上失败（例如 `AssertionError: 20 != 18`）；请在同一个 PR 里更新期望值。
+:::
+
 ## 第 3 步：提交 Pull Request
 
 把这两份文件加入[目录仓库](https://github.com/BofAI/x402-catalog)对应目录，并一起提交重新生成的 `dist/` 文件：
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md
index a6892fe8..a30db1f2 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/reference.md
@@ -59,7 +59,7 @@ description: catalog.json / pay.md 的字段定义、合法类目与链 ID，以
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| `network` | string | 该路由结算所在的标准 CAIP-2 链 ID（如 `tron:0x2b6653dc`、`eip155:56`、`eip155:8453`）。旧的 TRON 别名如 `tron:nile` 会被 schema 校验拒绝。 |
+| `network` | string | 该路由结算所在的 CAIP-2 链 ID（如 `tron:0x2b6653dc`、`eip155:56`、`eip155:8453`）。TRON 只接受[链 ID](#链-id) 中列出的十六进制形式；`tron:nile` 之类的别名和十进制形式 `tron:728126428` 都会被目录的校验拒绝。 |
 | `provider` | string | 处理该网络的 gateway provider `fqn` |
 | `scheme` | string | 该路由的 x402 支付方案：`exact`，或在 TRON 上 `exact_gasfree` —— 由每条路由各自声明 |
 | `assetTransferMethod` | string | 每条 `exact` 路由都**必须填写**：TRON/BSC 路由使用 `permit2`，Base USDC 路由使用 `eip3009`。只有 `exact_gasfree` 路由应省略该字段。 |
@@ -68,7 +68,7 @@ description: catalog.json / pay.md 的字段定义、合法类目与链 ID，以
 构建时该字段以 `x402_routes` 透传到产物。存在时，调用方/Agent 按目标支付链选择对应路由；顶层 `url` 仍是默认路由。
 
 :::note GasFree 路由
-在 TRON 上，可以为同一端点在 `exact` 路由之外再加一条 `exact_gasfree` 路由：由 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需 TRX。GasFree 路由仅限 TRON，且不能带 `assetTransferMethod`。自 x402 SDK 1.0.1 起（当前版本 1.2.0），relayer 费用由客户端估算，因此目录路由**不得**再发布旧的 `fee` 或 `feeConfig` 字段。
+在 TRON 上，可以为同一端点在 `exact` 路由之外再加一条 `exact_gasfree` 路由：由 relayer 代付网络能量、并从支付代币里扣除手续费，付款方无需 TRX。GasFree 路由仅限 TRON，且不能带 `assetTransferMethod`。自 x402 SDK 1.0.1 起，relayer 费用由客户端估算，因此目录路由**不得**再发布旧的 `fee` 或 `feeConfig` 字段。
 :::
 
 例如一个端点可以为每条支持的链各提供一条路由 —— TRON 主网、BSC 主网和 Base 主网，各有自己的 `provider` 和 `scheme`。调用时把 `wallet-cli x402 pay` 指向所选路由的 `url`，并传入匹配的 `--network` / `--scheme`：
@@ -88,7 +88,7 @@ wallet-cli x402 pay --dry-run -o json 'https://x402-gateway.bankofai.io/provider
 
 ### status 块
 
-`status` 为选填，描述服务各环节的状态，包含 `catalog` / `gateway` / `payment` / `upstream` 四个键。未提供时，构建产物（服务详情）会自动填充默认值：
+`status` 为选填，描述服务各环节的状态，包含 `catalog` / `gateway` / `payment` / `upstream` 四个键；填写时四个键都必须给出。未提供时，构建产物（服务详情）会自动填充默认值：
 
 ```json
 { "catalog": "listed", "gateway": "unknown", "payment": "unknown", "upstream": "unknown" }
@@ -105,7 +105,7 @@ wallet-cli x402 pay --dry-run -o json 'https://x402-gateway.bankofai.io/provider
 
 ## pay.md
 
-与 `catalog.json` 同目录提交、面向人和 Agent 的可读调用说明，为**必交**文件。建议包含：服务基本信息（FQN、入口地址、类目、结算链）、各端点的地址与价格，以及可直接复制的调用示例。目录仓库的 CI 测试要求包含带 `--network tron:728126428` 和 `--scheme exact` 的 `wallet-cli x402 pay` 示例、提到 `exact_gasfree`，并覆盖 Base 主网（`eip155:8453`）。该文件与 `catalog.json` 一样会经过敏感信息扫描（见下）。
+与 `catalog.json` 同目录提交、面向人和 Agent 的可读调用说明，为**必交**文件。建议包含：服务基本信息（FQN、入口地址、类目、结算链）、各端点的地址与价格，以及可直接复制的调用示例。目录仓库的 CI 测试要求包含带 `--network tron:728126428` 和 `--scheme exact` 的 `wallet-cli x402 pay` 示例、提到 `exact_gasfree`，并覆盖 Base 主网（须出现 `Base Mainnet`、`eip155:8453`、`-base`、`USDC` 和 `EIP-3009`，不得出现 `Sepolia` 或 `eip155:84532`）。该文件与 `catalog.json` 一样会经过敏感信息扫描（见下）。
 
 ## 合法类目
 
@@ -122,6 +122,10 @@ security   shopping    storage     translation
 
 `chains` 采用 CAIP-2 风格的链标识，主网与测试网均可识别：
 
+:::note TRON ID 格式
+目录 schema 只接受下表中十六进制形式的 TRON 链 ID。x402 SDK（2.0.0 起）和 Wallet CLI 使用十进制 CAIP-2 ID —— `tron:728126428`（主网）、`tron:3448148188`（Nile）、`tron:2494104990`（Shasta）。SDK 仍把十六进制值作为同一条链的已弃用别名接受；Wallet CLI 的全局 `--network`（`x402 pay` 和账户类命令使用）不接受——请用十进制 ID 或 `tron`、`nile`、`shasta` 等别名；只有目录筛选 `x402 provider-list --network` 也接受十六进制写法。因此 CLI 示例传 `--network tron:728126428`，而 `catalog.json` 写 `tron:0x2b6653dc`。
+:::
+
 | 链 | ID |
 |---|---|
 | TRON 主网 | `tron:0x2b6653dc` |
@@ -214,6 +218,8 @@ CI 构建后生成静态快照 `dist/`，由 Catalog Server 通过 `/api/` 路
 
 ## 本地构建与运行
 
+需要 Python 3.11 或更高版本。
+
 ```bash
 # 安装校验依赖（jsonschema）
 pip install -r requirements.txt
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md
index 8a67d851..c342fad7 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/OfficialFacilitator.md
@@ -62,11 +62,13 @@ Facilitator 由官方持续维护和升级，包括：
 
 | 模式 |限速 |说明 |
 |-----|-----|-----|
-| **匿名调用（Anonymous Mode）** | 官方服务：每个 IP 每分钟最多 1 次；自建部署未配置 `rate_limit.anonymous` 时，默认每个 IP 每分钟最多 10 次（可自行调整） | 不需要 API Key，适用于本地开发和功能测试 |
-| **API Key 调用（API Key Mode）** | 官方服务：每个 API Key 每分钟最多 1000 次；自建部署未配置 `rate_limit.authenticated` 时采用相同默认值（可自行调整） | 需要 API Key，适用于生产环境和高频支付请求 |
+| **匿名调用（Anonymous Mode）** | 官方服务：每个 IP 每分钟最多 10 次，`/verify` 与 `/settle` 分别计数；这也是自建部署未配置 `rate_limit.anonymous` 时的默认值（可自行调整） | 不需要 API Key，适用于本地开发和功能测试 |
+| **API Key 调用（API Key Mode）** | 官方服务：每个 API Key 每分钟最多 1000 次，`/verify` 与 `/settle` 分别计数；自建部署未配置 `rate_limit.authenticated` 时采用相同默认值（可自行调整） | 需要 API Key，适用于生产环境和高频支付请求 |
 
 两种模式的调用方式完全相同，但在 **身份识别与接口限速策略** 上有所不同。
 
+> **计数按实例进行。** 官方生产配置使用 `rate_limit.store: memory`，每个 facilitator 实例各自维护计数器；落到不同实例上的请求不会累计到同一个总数里。自建部署默认同样使用内存存储——如需在多个副本间共享计数，请设置 `rate_limit.store: redis`（并配置 `redis_url`）。
+
 
 
 
@@ -78,8 +80,8 @@ Facilitator 由官方持续维护和升级，包括：
 
 在匿名模式下：
 
-- `/settle` 接口会启用 **限速**
-- **官方服务按每个 IP 每分钟最多调用 1 次**；自建部署未配置 `rate_limit.anonymous` 时，默认按每个 IP 每分钟最多调用 **10 次**，且可自行调整。
+- `/verify` 与 `/settle` 接口会启用 **限速**，各自独立计数
+- **官方服务对每个接口按每个 IP 每分钟最多调用 10 次**，与自建部署未配置 `rate_limit.anonymous` 时的默认值相同，且可自行调整。
 
 该模式主要用于：
 
@@ -96,7 +98,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
   -d '{ ... }'
 ```
 
-虽然匿名模式可以正常调用所有核心接口，但由于 `/settle` 的调用频率非常低，因此 **不适合生产环境使用**。
+虽然匿名模式可以正常调用所有核心接口，但由于 `/verify` 与 `/settle` 的单 IP 限额较低，因此 **不适合生产环境使用**。
 
 如果你的应用需要处理真实用户支付或较高频率的请求，建议使用 **API Key 调用模式**。
 
@@ -121,7 +123,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
 
 当 Facilitator 识别到 API Key 后：
 
-- 在官方服务上，`/settle` 限额提升至**每个 API Key 每分钟 1000 次**
+- 在官方服务上，`/verify` 与 `/settle` 的限额各自提升至**每个 API Key 每分钟 1000 次**
 
 这意味着你的服务可以支持 **生产级别的支付吞吐量**。
 
@@ -256,23 +258,31 @@ curl -X POST https://facilitator.bankofai.io/settle \
 |------|------|------|
 | GET | `/health` | 服务健康检查 |
 | GET | `/supported` | 查询支持的支付能力和配置 |
-| POST | `/verify` | 验证支付载荷有效性 |
+| POST | `/verify` | 验证支付载荷有效性（**受限速保护**） |
 | POST | `/settle` | 执行链上结算（**受限速保护**） |
 | GET | `/payments/tx/{tx_hash}` | 按结算交易哈希查询支付记录 |
 | GET | `/payments?network=&nonce=[&asset=&payer=]` | 按链上授权身份查询支付记录 |
 | GET | `/payments` | 已认证卖家的结算记录流（`?limit=&offset=`；`limit` 默认 `50`、上限 `200`——超过 `200` 会被静默压到 `200`，不会报错；`offset` 默认 `0`） |
+| GET | `/sponsoring/ready` | TRON 授权资源赞助的就绪状态（`?network=` 只查单个网络）；就绪返回 HTTP `200`，否则（启动中、恢复中、降级或未启用赞助）返回 `503` |
 
-> **不存在** `/fee/quote` 端点，各方案也不收取 facilitator 费用。限速仅作用于 `/settle` 接口，其他接口不受限速影响。
+> **不存在** `/fee/quote` 端点，各方案也不收取 facilitator 费用。限速作用于 `/verify` 与 `/settle`（分别计数），其他接口不限速。超出限额的请求返回 HTTP `429`、响应体 `{"error":"rate_limit_exceeded"}`，并带 `Retry-After` 头。
 
 ### 官方服务结算的网络与方案
 
 | 网络 | 环境 |
 |---|---|
-| `tron:0x2b6653dc`（TRON 主网）· `tron:0xcd8690dc`（Nile） | 主网 · 测试网 |
+| `tron:728126428`（TRON 主网）· `tron:3448148188`（Nile） | 主网 · 测试网 |
 | `eip155:56`（BSC）· `eip155:97`（BSC 测试网） | 主网 · 测试网 |
 | `eip155:8453`（Base）· `eip155:84532`（Base Sepolia） | 主网 · 测试网 |
 
-以上网络均注册了 `exact`、`upto` 与 `batch-settlement`；TRON 在服务持有 GasFree 中继凭证的网络上（TRON 主网与 Nile）额外注册 `exact_gasfree`。以所连接部署的 `/supported` 返回为准。官方 facilitator 目前未启用 `trc20ApprovalResourceSponsoring` 扩展——TRON 授权资源赞助需要自建 facilitator。但在其 EVM 网络（BSC 与 Base）上，官方确实为每一条 EVM 网络注册了 ERC-20 授权 gas 代付扩展——不过只有当资源服务端在路由上声明该扩展时，代付才会真正生效。
+以上网络均注册了 `exact`、`upto` 与 `batch-settlement`；TRON 在服务持有 GasFree 中继凭证的网络上（TRON 主网与 Nile）额外注册 `exact_gasfree`。以所连接部署的 `/supported` 返回为准。TRON 网络以十进制 CAIP-2 标识返回；旧的十六进制写法（`tron:0x2b6653dc`、`tron:0xcd8690dc`）仍可作为输入别名。
+
+`/supported` 列出两个扩展：
+
+- `erc20ApprovalGasSponsoring`——为官方服务的每一条 EVM 网络（BSC 与 Base）注册。
+- `trc20ApprovalResourceSponsoring`——TRON 授权资源赞助**仅在 Nile 上启用**，仅针对配置的资产（Nile USDT），并且**需要 API Key**。匿名请求若携带该扩展，会被以 `sponsor_auth_required` 拒绝；已认证请求若针对 TRON 主网，会被以 `sponsor_network_disabled` 拒绝。`GET /sponsoring/ready` 可查询赞助运行时是否就绪。
+
+无论哪种代付，只有当资源服务端在路由上声明了对应扩展时才会真正生效。
 
 ### 支付记录查询
 
@@ -292,7 +302,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
 > 提供 API Key 时，这两个接口只返回与你的账户关联的支付记录，不会看到其他卖家的数据。
 
 :::danger 不带 API Key 时
-匿名请求下，`tx_hash` 与 `network` + `nonce` 查询**不添加卖家过滤**，返回结果可能包含已绑定卖家的记录——任何持有准确标识符的人都能查到对应记录。`/payments` 列表接口仍要求身份验证，因此不存在免认证的列表接口；但这两个查询接口也没有限流（官方服务按每个 IP 每分钟 1 次的匿名限流只覆盖 `/settle`），而结算 tx hash 又是链上公开数据。请把结算元数据视为事实上公开，而非按卖家隔离。
+匿名请求下，`tx_hash` 与 `network` + `nonce` 查询**不添加卖家过滤**，返回结果可能包含已绑定卖家的记录——任何持有准确标识符的人都能查到对应记录。`/payments` 列表接口仍要求身份验证，因此不存在免认证的列表接口；但这两个查询接口也没有限流（官方服务按每个 IP 每分钟 10 次的匿名限流只覆盖 `/verify` 与 `/settle`），而结算 tx hash 又是链上公开数据。请把结算元数据视为事实上公开，而非按卖家隔离。
 
 **以上描述的是当前实现行为，不代表推荐的访问控制策略。** 想让查询限定在自己账户范围内请带上 API Key，并且绝不要把结算 tx hash 或其 nonce 当作秘密。
 :::
@@ -303,7 +313,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
 
 **Q：不配置 API Key 能正常运行吗？**
 
-可以运行，但官方服务将 `/settle` 限制为每个 IP 每分钟 1 次。自建部署未配置 `rate_limit.anonymous` 时，默认每个 IP 每分钟 10 次，且可自行调整。匿名访问只适合测试，任何真实流量都必须配置 API Key。
+可以运行，但官方服务将 `/verify` 与 `/settle` 各自限制为每个 IP 每分钟 10 次，与自建部署未配置 `rate_limit.anonymous` 时的默认值相同，且可自行调整。匿名访问只适合测试，任何真实流量都必须配置 API Key。
 
 **Q：API Key 会过期吗？**
 
@@ -311,7 +321,7 @@ curl -X POST https://facilitator.bankofai.io/settle \
 
 **Q：我可以在多个项目中使用同一个 API Key 吗？**
 
-可以，同一个 API Key 可以在多个服务实例中复用。在官方服务上，这些实例共享该 Key 每分钟 1000 次 `/settle` 调用的限额；不会因为使用这个 Key 的服务器增多而分别重置配额。
+可以，同一个 API Key 可以在多个服务实例中复用。在官方服务上，限额按 API Key 而非调用方服务器计算：你的各个实例共用该 Key 每分钟 1000 次 `/settle` 调用的限额（`/verify` 另有独立的 1000 次），不会每台服务器各得一份配额。这些计数器按 facilitator 实例维护（`rate_limit.store: memory`），因此限额在每个 facilitator 实例内生效，而不是一个全局总数。
 
 **Q：我想更换 API Key，怎么操作？**
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md
index 55cc651a..3702c53c 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/client-server.md
@@ -23,7 +23,7 @@ import ThemedImage from '@theme/ThemedImage';
 
 - **发起请求**：向资源服务器发送初始 HTTP 请求。
 - **处理支付要求**：解析 `402 Payment Required` 响应，并提取支付详情。
-- **管理代币授权**：为普通 ERC-20/TRC-20 代币授权 Permit2（一次性 `approve(Permit2)`）；ERC-3009 代币无需授权。由谁广播因链而异。**在 TRON 上**，client 会在首次付款时自动广播该授权、能量自付——除非 server 声明了 `trc20ApprovalResourceSponsoring` 扩展（SDK 1.2.0+），此时 client 只签名不广播，由 facilitator 赞助能量/带宽并广播。**在 EVM 上 client 从不广播任何交易**：要么在 server 声明了 `eip2612GasSponsoring` 或 `erc20ApprovalGasSponsoring` 时附上一笔已签名但未广播的授权交由 facilitator 转发；要么在没有任何相关扩展时，验款直接以 `permit2_allowance_required` 失败，授权必须在首次付款前另行完成。详见 [SDK 功能矩阵](../sdk-features.md#extensions)。
+- **管理代币授权**：为普通 ERC-20/TRC-20 代币授权 Permit2（一次性 `approve(Permit2)`）；ERC-3009 代币无需授权。由谁广播因链而异。**在 TRON 上**，client 会在首次付款时自动广播该授权、能量自付（默认 `allowanceMode: "auto"` 时如此；设为 `"skip"` 则由应用自行处理授权）——除非 server 声明了 `trc20ApprovalResourceSponsoring` 扩展，此时 client 只签名不广播，由 facilitator 赞助能量/带宽并广播。2.1.0 起，这需要用 `client.registerExtension(createTrc20ApprovalResourceSponsoringClientExtension(signer))` 注册 `@bankofai/x402-tron-extensions` 中的 client 扩展；未注册时，受赞助的付款会以 `trc20_approval_client_extension_not_registered` 失败，不会退回由 client 自行广播。**在 EVM 上 client 从不广播任何交易**：要么附上链下的 EIP-2612 permit 签名（server 声明了 `eip2612GasSponsoring` 时），或附上一笔已签名但未广播的授权交易交由 facilitator 转发（`erc20ApprovalGasSponsoring`）；要么在没有任何相关扩展时，验款直接以 `permit2_allowance_required` 失败，授权必须在首次付款前另行完成。详见 [SDK 功能矩阵](../sdk-features.md#extensions)。
 - **准备支付载荷**：根据服务端的要求，构建并签署支付载荷。
 - **携带支付凭证重发请求**：在请求头中附加 `PAYMENT-SIGNATURE` 并重新发送请求。
 
@@ -41,7 +41,7 @@ import ThemedImage from '@theme/ThemedImage';
 
 ### 核心职责
 
-- **定义支付要求**：对未附带有效支付凭证的请求响应 HTTP `402 Payment Required`，并在响应体中详细说明支付要求。
+- **定义支付要求**：对未附带有效支付凭证的请求响应 HTTP `402 Payment Required`，并在 Base64 编码的 `PAYMENT-REQUIRED` 响应头中详细说明支付要求（响应体默认为 `{}`）。
 - **验证支付载荷**：调用 Facilitator 服务对传入的签名载荷进行验证。
 - **结算交易**：验证通过后，通过 Facilitator 提交交易以完成资金结算。
 - **交付资源**：支付确认无误后，向客户端返回所请求的资源。
@@ -66,6 +66,8 @@ import ThemedImage from '@theme/ThemedImage';
   }}
 />
 
+图中是客户端看到的顺序：资源在结算之后才到达。在默认的 `authorization` 流程下，服务端会先执行处理逻辑再结算，并在结算成功后才放出响应（见上文第 5 步）。
+
 ## 总结
 
 在 x402 协议体系中：
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md
index 8fa8adb4..2e866511 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/facilitator.md
@@ -19,7 +19,7 @@ Facilitator 是一种中间件服务，主要负责：
 
 - **支付验证**：确认客户端提交的签名载荷严格符合服务端声明的支付要求。
 - **支付结算**：将验证通过的交易提交至区块链网络，并监控上链状态。
-- **结算记录**：每次 settle 尝试写入一行——记录层不做任何去重、也没有唯一约束，因此失败与重试都会累积。实际上每个授权身份至多只会有一条*成功*记录，但这来自链上的重放保护（同一笔授权只能结算一次），而非记录层的去重。它同时支持记录查询，调用方认证后才按卖家过滤。保存失败只会记日志，绝不影响 `/settle` 的返回。
+- **结算记录**：每次拿到结算机制结果（成功或失败）的 settle 尝试写入一行，因此失败与重试都会累积。在结算之前或结算过程中被拒绝的请求不写记录：请求体格式错误（400）、赞助访问被拒（403/503）、Permit2 重放防护错误，以及内部错误（500）。表上有一个针对 (`network`, `asset`, `payer`, `nonce`) 且条件为 `status = 'success'` 的部分唯一索引，保证每笔授权至多一条*成功*记录，与链上的重放保护（同一笔授权只能结算一次）互为补充。它同时支持记录查询，调用方认证后才按卖家过滤。保存失败只会记日志，绝不影响 `/settle` 的返回。
 - **结果反馈**：将验证与结算结果返回给服务端，作为服务端决定是否交付资源的依据。
 
 > **注意**：Facilitator **不持有资金**，也不充当托管方——它仅根据客户端签名的指令执行验证与链上操作。
@@ -31,7 +31,7 @@ Facilitator 是一种中间件服务，主要负责：
 - **降低运维门槛**：服务端无需直接处理区块链节点交互或 RPC 管理。
 - **协议标准化**：确保跨服务的支付验证与结算流程保持一致。
 - **快速集成**：服务端仅需极少的区块链开发工作即可开始接收支付。
-- **资源费管理**：Facilitator 负责支付交易执行所需的 TRX（能量 Energy 和带宽 Bandwidth）/BNB，降低了服务端的持有成本。自 SDK 1.2.0 起，TRON 的 Facilitator 还可以选择启用 `trc20ApprovalResourceSponsoring` 扩展，向付款方临时委托自己的 Stake 2.0 能量（必要时还有带宽），使付款方的首笔 `approve(Permit2)` 无需 TRX。该能力需要主动启用：Facilitator 必须注册赞助 runtime，并配套有界的赞助策略与持久化的操作协调器。无论哪种代付，资源服务端都还要在路由上声明对应扩展——正是这个声明让 SDK 客户端附带代付载荷（Facilitator 本身并不校验它，因此非 SDK 客户端可以绕过这一步）。EVM 网络上有对应的能力——为付款方的 ERC-20 `approve` 代付 gas——但 SDK 不会替你接好：自建 Facilitator 必须自行注册该扩展。官方 Facilitator 已为其服务的 EVM 网络注册，详见[官方 Facilitator](./OfficialFacilitator.md)。
+- **资源费管理**：Facilitator 负责支付交易执行所需的 TRX（能量 Energy 和带宽 Bandwidth）/BNB，降低了服务端的持有成本。自 SDK 1.2.0 起，TRON 的 Facilitator 还可以选择启用 `trc20ApprovalResourceSponsoring` 扩展，向付款方临时委托自己的 Stake 2.0 能量（必要时还有带宽），使付款方的首笔 `approve(Permit2)` 无需 TRX。该能力需要主动启用：Facilitator 必须注册赞助 runtime，并配套有界的赞助策略与持久化的操作协调器。无论哪种代付，资源服务端都还要在路由上声明对应扩展——正是这个声明让 SDK 客户端附带代付载荷（Facilitator 本身并不校验它，因此非 SDK 客户端可以绕过这一步）。EVM 网络上有对应的能力——为付款方的 ERC-20 `approve` 代付 gas——但 SDK 不会替你接好：自建 Facilitator 必须自行注册该扩展。官方 Facilitator 已为其服务的 EVM 网络注册，并在 Nile 上为持有 API Key 的调用方启用了 TRON 授权资源赞助，详见[官方 Facilitator](./OfficialFacilitator.md)。
 
 虽然开发者可以选择在本地自行实现验证与结算逻辑，但使用 Facilitator 能显著加速开发周期并确保协议实现的规范性。
 
@@ -74,7 +74,7 @@ Facilitator 是一种中间件服务，主要负责：
 如果您希望完全掌控结算钱包、RPC 节点、能量管理，或注册哪些网络与方案，又或有特定的隐私/合规要求，可以选择自己部署 Facilitator 服务。
 
 > ⚠️ **自托管安全提示：**
-> - 自托管 Facilitator 需要一个**有余额的专用钱包**来支付区块链手续费。该钱包通过 `@bankofai/agent-wallet` 解析、在进程外解锁（例如 `AGENT_WALLET_PASSWORD`）——原始私钥不会进入服务进程
+> - 自托管 Facilitator 需要一个**有余额的专用钱包**来支付区块链手续费。该钱包通过 `@bankofai/agent-wallet` v3 解析：使用 `privy` 或 `wallet_cli` provider 时私钥留在服务进程之外；`raw_secret` provider 会把明文私钥存在配置中，仅适用于开发环境
 > - **这个 Facilitator 钱包应与您的收款钱包分开**，请专门创建一个新钱包
 > - Facilitator 钱包只需存入少量代币（用于手续费），不要存入大量资金
 > - 不要把原始私钥写进 `.env`、配置文件或命令行，**更不要提交到 Git 或分享给任何人**
@@ -91,30 +91,35 @@ Facilitator 是一种中间件服务，主要负责：
 |------|------|------|
 | GET | `/health` | 服务健康检查 |
 | GET | `/supported` | 查询支持的支付能力和配置 |
-| POST | `/verify` | 验证支付载荷有效性 |
-| POST | `/settle` | 执行链上结算（官方 Facilitator 下**受限速保护**）；并持久化一条结算记录 |
+| POST | `/verify` | 验证支付载荷有效性（**受限速保护**，见下文） |
+| POST | `/settle` | 执行链上结算（**受限速保护**，见下文）；并持久化一条结算记录 |
 | GET | `/payments/tx/{tx_hash}` | 按结算交易哈希查询支付记录（认证后仅返回当前卖家的记录） |
 | GET | `/payments?network=&nonce=[&asset=&payer=]` | 按链上授权身份查询支付记录（认证后仅返回当前卖家的记录） |
 | GET | `/payments` | 已认证卖家的结算记录流（`?limit=&offset=`；`limit` 默认 `50`、上限 `200`——超过 `200` 会被静默压到 `200`，不会报错；`offset` 默认 `0`） |
+| GET | `/sponsoring/ready` | TRON 授权资源赞助的就绪状态（`?network=` 只查单个网络）；就绪返回 HTTP `200`，否则（启动中、恢复中、降级或未启用赞助）返回 `503` |
 | GET | `/metrics` | Prometheus 指标（运维用途；仅当监控与主端口共用时才在主端口暴露） |
 | ALL | `/mainnet/*` · `/nile/*` | GasFree Open API 透明代理（HMAC 签名）——由 TRON `exact_gasfree` 方案内部使用 |
 
 记录查询的失败会返回以下错误码：无匹配记录时 `404 not_found`；身份查询参数不完整（传了 `network`/`nonce`/`asset`/`payer` 中的部分，但缺少必需的 `network`+`nonce` 组合）时 `400 invalid_identity_query`；调用 `/payments` 但既未提供身份参数也未提供 API Key 时 `400 missing_identity_or_auth`。
 
+`/verify` 与 `/settle` 保持 x402 的响应结构（`invalidReason` / `errorReason`）。除 SDK 自身的原因外，服务还会返回：请求体格式错误时 `400 invalid_json` 或 `missing_parameters`；`413` `{"code":"body_too_large","message":…}`（默认上限 1 MiB）；`429` `{"error":"rate_limit_exceeded"}`；请求携带 `trc20ApprovalResourceSponsoring` 但部署不予赞助时 `403 sponsor_auth_required`、`sponsor_network_disabled` 或 `sponsor_pay_to_invalid`；暂时性状况返回 `503` 并带 `Retry-After`（`sponsor_owner_busy`、`sponsor_recovery_in_progress`、`sponsor_storage_unavailable`，以及仅 `/settle` 会返回的 `permit2_authorization_busy`、`permit2_storage_unavailable`、`permit2_nonce_check_unavailable`）。`/settle` 时 nonce 已被消耗的 Permit2 授权会以 `permit2_nonce_consumed`（HTTP 200）失败，不会广播新交易；授权格式错误时 `/settle` 返回 `400 permit2_invalid_authorization`。受赞助的授权还可能在协议层失败（HTTP 200，放在 `invalidReason` / `errorReason` 里）：`approval_transaction_reused`（已签名的 approve 已被用于另一笔不同的支付请求）、`sponsor_approval_lifetime_exceeded`（已签名 approve 的有效期超过 630 秒），以及仅 `/settle` 会返回的 `sponsor_existing_delegation`。未预期的异常返回 `500 internal_error`。GasFree 代理只挂在 `/mainnet` 和 `/nile` 下（其他路径直接返回普通的 `404`），上游失败或响应过大时返回 `502 bad_gateway`。
+
 > **不存在** `/fee/quote` 端点，各方案也完全不收取 facilitator 费用。支付记录以链上授权身份（`network` + `scheme` + `asset` + `payer` + `nonce`）为键，而非客户端提供的 payment ID。
 
 ---
 
 ## 限速策略
 
-`/settle` 端点根据调用方的认证状态动态执行限速：
+`/verify` 与 `/settle` 端点根据调用方的认证状态动态执行限速，两个端点各自独立计数：
 
 | 模式 | 限速 | 认证方式 |
 |------|------|----------|
-| **已认证** | 官方服务：每个 API Key 每分钟最多 1000 次；自建部署未配置 `rate_limit.authenticated` 时采用相同默认值（可自行调整） | 请求头携带 `X-API-KEY: <your_key>` |
-| **匿名** | 官方服务：每个 IP 每分钟最多 1 次；自建部署未配置 `rate_limit.anonymous` 时，默认每个 IP 每分钟最多 10 次（可自行调整） | 不携带 API Key |
+| **已认证** | 官方服务：每个 API Key 每分钟最多 1000 次，`/verify` 与 `/settle` 分别计数；自建部署未配置 `rate_limit.authenticated` 时采用相同默认值（可自行调整） | 请求头携带 `X-API-KEY: <your_key>` |
+| **匿名** | 官方服务：每个 IP 每分钟最多 10 次，`/verify` 与 `/settle` 分别计数；这也是自建部署未配置 `rate_limit.anonymous` 时的默认值（可自行调整） | 不携带 API Key |
+
+其他端点（`/supported`、`/payments/*`、`/sponsoring/ready`、`/health`）不限速。超出限额时返回 HTTP `429` `{"error":"rate_limit_exceeded"}`，并带 `Retry-After` 头。
 
-其他端点（`/verify`、`/supported`、`/payments/*`）不单独限速。
+> **计数按实例进行。** 官方生产配置使用 `rate_limit.store: memory`，每个 facilitator 实例各自维护计数器；落到不同实例上的请求不会累计到同一个总数里。自建部署默认同样使用内存存储——如需在多个副本间共享计数，请设置 `rate_limit.store: redis`（并配置 `redis_url`）。
 
 > **提示**：任何生产级别的工作负载都建议通过[管理后台](https://admin-facilitator.bankofai.io)申请 API Key，以解锁更高的限速配额。
 
@@ -132,7 +137,7 @@ Facilitator 是一种中间件服务，主要负责：
 - **携带有效 `X-API-KEY`**——查询结果按该 Key 对应的卖家过滤。
 - **匿名调用 `tx_hash` 或 `network` + `nonce` 查询接口**——当前实现**不添加卖家过滤**，返回结果可能包含已绑定卖家的记录。
 - **`/payments` 列表接口**——仍要求身份验证：不带身份参数又不带 API Key 时返回 `400`，只给部分身份参数同样返回 `400`，不会退化成记录流。
-- **这两个查询接口没有限流**——官方服务按每个 IP 每分钟 1 次的匿名限流只作用于 `/settle`，记录查询接口没有单独限流。
+- **这两个查询接口没有限流**——官方服务的匿名限流只作用于 `/verify` 与 `/settle`，记录查询接口没有单独限流。
 
 结算 tx hash 属于链上公开数据，而 `network` + `nonce` 查询还能查到**失败**的结算——包括广播前就失败的那些，它们根本没有 tx hash，也就无从通过其他途径查到。实际后果是：**结算元数据应当被视为事实上公开的**，尽管并不存在免认证的列表接口。响应体从不包含卖家 id，因此查询暴露的是某条已绑定卖家记录的支付元数据，而不是卖家归属本身。
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md
index d342b5c8..c315ebee 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md
@@ -74,7 +74,7 @@ import ThemedImage from '@theme/ThemedImage';
 
 ### 面向 AI Agent：一个目录，汇聚海量 API，按需付费
 
-- **当前用 CLI 发现** —— `wallet-cli x402 provider-list` / `provider-show` / `endpoint-list` 可定位所需 API 及其路由。通过 MCP 付款由 `@bankofai/x402-mcp` 支持；支持目录发现的 MCP 尚未发布。
+- **当前用 CLI 发现** —— `wallet-cli x402 provider-list` / `provider-show` / `endpoint-list` 可定位所需 API 及其路由。通过 MCP 付款由 `@x402/mcp` 支持；支持目录发现的 MCP 尚未发布。
 - **按次计费** —— 无需订阅，无最低消费。
 - **实时价格透明** —— 网关在 `402` 响应中返回实时计算的价格，客户端授权会绑定所选支付要求；报价本身并不是网关的密码学签名。
 - **无账号、无密钥** —— 钱包即身份，无需注册或管理任何 API Key。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md
index d59b88c9..868d8729 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/http-402.md
@@ -49,13 +49,13 @@ x402 定义了一组标准化 HTTP 标头用于支付通信：
   "error": "Payment required",
   "resource": {
     "url": "http://example.com/protected",
-    "description": null,
-    "mimeType": null
+    "description": "",
+    "mimeType": ""
   },
   "accepts": [
     {
       "scheme": "exact",
-      "network": "tron:0xcd8690dc",
+      "network": "tron:3448148188",
       "amount": "100",
       "asset": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
       "payTo": "<SELLER_TRON_ADDRESS>",
@@ -79,8 +79,8 @@ x402 定义了一组标准化 HTTP 标头用于支付通信：
   "error": "Payment required",
   "resource": {
     "url": "http://example.com/protected",
-    "description": null,
-    "mimeType": null
+    "description": "",
+    "mimeType": ""
   },
   "accepts": [
     {
@@ -123,12 +123,12 @@ x402 定义了一组标准化 HTTP 标头用于支付通信：
 | `resource`          | 关于请求资源的信息                                |
 | `accepts`           | 接受的支付选项数组                                |
 | `scheme`            | 支付方案（`exact`、`upto`、`batch-settlement`、`exact_gasfree`）  |
-| `network`           | 网络标识符——三个 TRON 标识（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）或任意 `eip155:<chainId>`：资源服务端默认注册 `eip155:*`，因此该字段并不限于 `eip155:56` / `97` / `8453` / `84532`。能否结算则另由 facilitator 已配置的网络决定 |
+| `network`           | 网络标识符——三个 TRON 标识（`tron:728126428`、`tron:3448148188`、`tron:2494104990`）或任意 `eip155:<chainId>`：资源服务端默认注册 `eip155:*`，因此该字段并不限于 `eip155:56` / `97` / `8453` / `84532`。能否结算则另由 facilitator 已配置的网络决定 |
 | `amount`            | 支付金额，以最小单位计（例如：100 = 0.0001 USDT） |
 | `asset`             | TRC-20/BEP-20 代币合约地址                               |
 | `payTo`             | 卖家的钱包地址                              |
 | `maxTimeoutSeconds` | 支付有效期的最大时长                              |
-| `extra`             | 方案相关数据——`assetTransferMethod`（`eip3009` / `permit2`）、EIP-3009 资产、以及同时支持 EIP-2612 的 permit2 资产的 `name`/`version`，以及声明了非默认付款流程时的 `paymentFlow`（`upfront` 或 `escrow`）——内置方案全部使用默认的 `authorization` 流程，该字段不会写入 `extra`。其中不含费用对象：各方案不收取 facilitator 费用。 |
+| `extra`             | 方案相关数据——`assetTransferMethod`（`eip3009` / `permit2`）、EIP-3009 资产、以及同时支持 EIP-2612 的 permit2 资产的 `name`/`version`，以及路由选择了非默认付款流程时的 `paymentFlow`（`upfront` 或 `escrow`）——默认的 `authorization` 流程不会写入 `extra`。TRON 方案与 EVM `upto` / `batch-settlement` 只支持 `authorization`；EVM `exact` 还支持 `upfront`。其中不含费用对象：各方案不收取 facilitator 费用。 |
 | `extensions`        | 支付方案的附加上下文（如 EVM gas 赞助、TRON 的 `trc20ApprovalResourceSponsoring`、payment-identifier） |
 
 ## 支付签名结构
@@ -143,7 +143,7 @@ x402 定义了一组标准化 HTTP 标头用于支付通信：
   "x402Version": 2,
   "accepted": {
     "scheme": "exact",
-    "network": "tron:0xcd8690dc",
+    "network": "tron:3448148188",
     "asset": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
     "amount": "100",
     "payTo": "<SELLER_TRON_ADDRESS>",
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md
index 5500f375..970c33de 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md
@@ -7,8 +7,8 @@ import TabItem from '@theme/TabItem';
 
 ## TRON 网络标识符
 
-x402 采用 CAIP-2 网络标识符格式：`tron:<hex_chain_id>`。
-应用代码中优先使用 `@bankofai/x402-tron` 导出的常量（`TRON_MAINNET`、`TRON_NILE`、`TRON_SHASTA`），不要手动复制不透明的 hex 字符串。
+x402 采用 CAIP-2 网络标识符格式：`tron:<decimal_chain_id>`（十进制链 ID）。
+应用代码中优先使用 `@bankofai/x402-tron` 导出的常量（`TRON_MAINNET`、`TRON_NILE`、`TRON_SHASTA`），不要手动复制标识符字符串。
 
 ### 标识符参考表
 
@@ -18,7 +18,7 @@ x402 采用 CAIP-2 网络标识符格式：`tron:<hex_chain_id>`。
 | **TRON Shasta**         | `tron:2494104990`  | `TRON_SHASTA`  | TRON Shasta 测试网 |
 | **TRON Nile**           | `tron:3448148188`  | `TRON_NILE`    | TRON Nile 测试网 |
 
-> **TRON 标识格式**：自 `@bankofai/x402-tron` 2.0.0 起，SDK 常量使用十进制 CAIP-2 引用。旧的十六进制形式（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）仍可作为输入别名使用，官方 facilitator 与 API Catalog 目前返回的也是十六进制形式。
+> **TRON 标识格式**：自 `@bankofai/x402-tron` 2.0.0 起，SDK 常量使用十进制 CAIP-2 引用。旧的十六进制形式（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）仍可作为输入别名使用，并会被规范化为十进制形式。官方 facilitator 的 `/supported` 返回十进制标识；API Catalog 目前仍列出十六进制形式。
 
 
 ## BSC 网络标识符
@@ -30,7 +30,7 @@ x402 采用 CAIP-2 网络标识符格式：`tron:<hex_chain_id>`。
 | **BSC Mainnet**        | `eip155:56` | BSC 主网 (生产环境) |
 | **BSC Testnet**         | `eip155:97`  | BSC 测试网   |
 
-> **注意**：自托管 Facilitator 的 YAML 配置**只接受规范的 CAIP-2 标识符**——`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`、`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`。`bsc:mainnet`、`tron:nile` 这类易读别名不会被解析，启动时会直接报错。
+> **注意**：自托管 Facilitator 的 YAML 配置**只接受规范的 CAIP-2 标识符**——`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`、`tron:728126428`、`tron:3448148188`、`tron:2494104990`。已弃用的十六进制 TRON 标识（`tron:0x…`）仍被接受，并会规范化为十进制。`bsc:mainnet`、`tron:nile` 这类易读别名不会被解析，启动时会直接报错。
 
 
 ## Base 网络标识符
@@ -75,18 +75,17 @@ x402 支持 **TRC-20、BEP-20 和 ERC-20** 代币。TRON/BSC 路由使用各自
 | **USDD** | `tron:728126428` | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` |
 | **USDD** | `tron:3448148188`    | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` |
 | **USDT** | `eip155:56` | `0x55d398326f99059fF775485246999027B3197955` |
-| **USDC** | `eip155:56` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
+| **USDC** | `eip155:56` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d`（不在任何内置代币注册表中——仅能作为显式资产） |
 | **USDT** | `eip155:97`    | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
 | **USDC** | `eip155:97`    | `0x64544969ed7EBf5f083679233325356EbE738930` |
-| **DHLU** | `eip155:97`    | `0x375cADdd2cB68cE82e3D9B075D551067a7b4B816` |
 | **USDC** | `eip155:8453`  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
 | **USDC** | `eip155:84532` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
 
-> **默认资产与需显式放行的资产（SDK 1.1.0 起）**：默认资产注册表在 TRON（`tron:728126428`、`tron:3448148188`、`tron:2494104990`）与 BSC 主网（`eip155:56`）上解析 **USDT**，在 BSC 测试网（`eip155:97`）与 Base（`eip155:8453`、`eip155:84532`）上解析 **USDC**。注册表还为本页未列表的二十条 EVM 网络（MegaETH、Monad、Polygon、Arbitrum、Mezo、Radius、XDC、Celo、Flare 等）内置了默认资产。上表中的其余代币——TRON USDD、BSC 主网 USDC、BSC 测试网 USDT、DHLU 以及任何自定义代币——都属于「仅由服务端公布」：1.1.0 的客户端消费管控默认开启，除非你通过 `spendControls.allowedAssets` 放行，否则客户端会拒绝支付。CLI 资产选择请参见 [wallet-cli 命令参考](/zh-Hans/wallet-cli/command-reference/)。
+> **默认资产与需显式放行的资产（SDK 1.1.0 起）**：默认资产注册表在 TRON（`tron:728126428`、`tron:3448148188`、`tron:2494104990`，来自 `@bankofai/x402-tron`）上解析 **USDT**，在 Base（`eip155:8453`、`eip155:84532`，来自官方 `@x402/evm` 2.28.0）上解析 **USDC**。`@x402/evm` 还为本页未列表的其他 EVM 网络（Ethereum、Polygon、Arbitrum、Avalanche、Celo、Sei、MegaETH、Monad、XDC、Flare 等）内置了默认资产，但**不包括 BSC**：BSC 路由必须用显式的 `{ asset, amount, extra }` 对象定价。上表中的其余代币——TRON USDD、所有 BSC 资产以及任何自定义代币——都属于「仅由服务端公布」：1.1.0 的客户端消费管控默认开启，除非你通过 `spendControls.allowedAssets` 放行，否则客户端会拒绝支付。CLI 资产选择请参见 [wallet-cli 命令参考](/zh-Hans/wallet-cli/command-reference/)。
 
-> **扩展支持**：协议具有高度的可扩展性。通过 TRON 代币注册表（`@bankofai/x402-tron` 的 `registerToken`）或 server 的 `EVM_TOKENS` 配置表，您可以轻松配置并支持任意自定义的 TRC-20/BEP-20 代币。
+> **扩展支持**：协议具有高度的可扩展性。通过 TRON 代币注册表（`@bankofai/x402-tron` 的 `registerToken`）或在 server 路由上使用显式的 `{ asset, amount, extra }` 价格，您可以轻松配置并支持任意自定义的 TRC-20/BEP-20 代币。
 
-> **关于 `exact` 方案的代币选择**：EIP-3009 代币（如 Base 官方 USDC、BSC 测试网 DHLU）通过 `transferWithAuthorization` 无 gas 结算。普通 ERC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算——客户端首次付款时自动广播一次性 `approve(Permit2)`；在 TRON 上，若 server 声明了 `trc20ApprovalResourceSponsoring`（SDK 1.2.0+），则改为客户端签名、由 facilitator 赞助并广播。每种代币的结算方式由你在 server 端 `accepts[].price.extra` 里配置，SDK 会在协议数据中以 `accepts[].extra` 下发：EIP-3009 → `{ name, version }`；普通 ERC-20 → `{ assetTransferMethod: "permit2" }`。若某个 permit2 资产同时实现了 EIP-2612，`extra` 会在 `assetTransferMethod` 之外一并带上 `{ name, version }`；反过来，省略这对字段正是服务端告诉客户端「跳过 EIP-2612」的方式。两条代付路径都位于 permit2 分支内，因此对 EIP-3009 资产一概不适用。在 permit2 资产上，客户端签名无 gas 的 EIP-2612 permit 需要同时满足：具备 `readContract` 能力（由签名方或已配置的 RPC 提供）、服务端声明了 `eip2612GasSponsoring` 扩展、`extra` 里 `name` 与 `version` 都在、且当前 Permit2 额度尚不足以覆盖本次支付。注意这里的不对称：**缺少**读取能力会直接跳过 permit，而读取**抛错**则会被捕获、签名照常进行。否则客户端会*尝试* ERC-20 授权 gas 代付，这条路径要求 `readContract` 能力、服务端声明另一个独立的 `erc20ApprovalGasSponsoring` 扩展、签名方既能签原始交易又能报告交易计数，同样也要求现有额度不足；此时由客户端签名一笔 `MaxUint256` 的 `approve`——始终是最大值，与支付金额无关——由 facilitator 负责广播。两条路径都不满足时，载荷里不会带任何代付扩展。内置默认资产中带该标记的是 MegaETH MegaUSD（主网）以及 Mezo mUSD 与 Radius SBC（主网与测试网均有）。
+> **关于 `exact` 方案的代币选择**：EIP-3009 代币（如 Base 官方 USDC）通过 `transferWithAuthorization` 无 gas 结算。普通 ERC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算，需要一次性 `approve(Permit2)`——在 TRON 上客户端首次付款时自动广播（EVM 上从不广播，见下文的代付路径）；在 TRON 上，若 server 声明了 `trc20ApprovalResourceSponsoring`（SDK 1.2.0+），则改为客户端签名、由 facilitator 赞助并广播（从 2.1.0 起须注册 `@bankofai/x402-tron-extensions` 中的客户端扩展）。每种代币的结算方式由你在 server 端 `accepts[].price.extra` 里配置，SDK 会在协议数据中以 `accepts[].extra` 下发：EIP-3009 → `{ name, version }`；普通 ERC-20 → `{ assetTransferMethod: "permit2" }`。若某个 permit2 资产同时实现了 EIP-2612，`extra` 会在 `assetTransferMethod` 之外一并带上 `{ name, version }`；反过来，省略这对字段正是服务端告诉客户端「跳过 EIP-2612」的方式。两条代付路径都位于 permit2 分支内，因此对 EIP-3009 资产一概不适用。在 permit2 资产上，客户端签名无 gas 的 EIP-2612 permit 需要同时满足：具备 `readContract` 能力（由签名方或已配置的 RPC 提供）、服务端声明了 `eip2612GasSponsoring` 扩展、`extra` 里 `name` 与 `version` 都在、且当前 Permit2 额度尚不足以覆盖本次支付。注意这里的不对称：**缺少**读取能力会直接跳过 permit，而读取**抛错**则会被捕获、签名照常进行。否则客户端会*尝试* ERC-20 授权 gas 代付，这条路径要求 `readContract` 能力、服务端声明另一个独立的 `erc20ApprovalGasSponsoring` 扩展、签名方能签原始交易，并能获取交易计数（由签名方或已配置的 RPC 提供），同样也要求现有额度不足；此时由客户端签名一笔 `MaxUint256` 的 `approve`——始终是最大值，与支付金额无关——由 facilitator 负责广播。两条路径都不满足时，载荷里不会带任何代付扩展。内置默认资产中带 `supportsEip2612` 标记的是 MegaETH MegaUSD（主网）以及 Mezo mUSD 与 Radius SBC（主网与测试网均有）。
 
 ## 安全签名
 
@@ -118,8 +117,8 @@ x402 定义了五种命名支付方案。其中四种按链族提供完整的 cl
 
 `exact` 方案支付公布的准确金额，覆盖两种代币转账路径：
 
-- **EIP-3009 `transferWithAuthorization`**：适用于原生支持该标准的代币（如 Base 官方 USDC、BSC 测试网 DHLU）。无 gas：无需 `approve`；客户端签署类型化数据授权，facilitator 在链上调用 `transferWithAuthorization`。
-- **Permit2**：适用于不实现 ERC-3009 的普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）。客户端签署 Permit2 witness，facilitator 通过 `x402ExactPermit2Proxy` 合约结算。需要一次性 `approve(Permit2)`；客户端首次付款时自动广播。在 TRON 上，SDK 1.2.0 新增了 `trc20ApprovalResourceSponsoring` 扩展——若 server 声明了它，client 只签名而不广播该授权，由 facilitator 委托能量/带宽并广播，因此付款方授权时无需 TRX。
+- **EIP-3009 `transferWithAuthorization`**：适用于原生支持该标准的代币（如 Base 官方 USDC）。无 gas：无需 `approve`；客户端签署类型化数据授权，facilitator 在链上调用 `transferWithAuthorization`。
+- **Permit2**：适用于不实现 ERC-3009 的普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）。客户端签署 Permit2 witness，facilitator 通过 `x402ExactPermit2Proxy` 合约结算。需要一次性 `approve(Permit2)`；在 TRON 上客户端首次付款时自动广播，在 EVM 上则须事先授权或通过 gas 代付扩展转发。在 TRON 上，SDK 1.2.0 新增了 `trc20ApprovalResourceSponsoring` 扩展——若 server 声明了它，client 只签名而不广播该授权，由 facilitator 委托能量/带宽并广播，因此付款方授权时无需 TRX。从 2.1.0 起，客户端必须注册 `@bankofai/x402-tron-extensions` 中的 `createTrc20ApprovalResourceSponsoringClientExtension(signer)`，否则付款会以 `trc20_approval_client_extension_not_registered` 失败。
 
 `exact` 方案遵循 **x402 Foundation** 发布的 **v2 链路格式**：标准 v2 客户端可直接向本 SDK 的服务端发起付款请求，本 SDK 客户端也可直接访问任何 v2 兼容的服务端——无需项目特定的转换。转账授权数据在 EIP-3009 路径下位于 `payload.authorization`，在 Permit2 路径下位于 `payload.permit2Authorization`。
 
@@ -133,7 +132,7 @@ x402 定义了五种命名支付方案。其中四种按链族提供完整的 cl
 
 ### `auth-capture` 方案
 
-面向可退款 Base Commerce Payments 的 EVM client 实现：先授权资金，之后再执行 capture、void 或 refund。当前发布的 SDK 仅提供 `@bankofai/x402-evm/auth-capture/client`；server 与 facilitator 实现尚未发布，因此暂时无法只依靠发布包完成端到端部署。
+面向可退款 Base Commerce Payments 的 EVM client 实现：先授权资金，之后再执行 capture、void 或 refund。官方 `@x402/evm` 包（SDK 自 2.1.0 起用它处理 EVM）目前仅提供 `@x402/evm/auth-capture/client`；server 与 facilitator 实现尚未发布，因此暂时无法只依靠发布包完成端到端部署。
 
 ### `exact_gasfree` 方案
 
@@ -193,7 +192,7 @@ CLI 取的是服务端 `accepts` 列表中第一条匹配你过滤条件的支
 
 | 核心组件     | TRON/BSC/Base 实现详情                              |
 | :----------- | :----------------------------------------- |
-| **网络环境** | 三个 TRON 标识（`tron:728126428`、`tron:2494104990`、`tron:3448148188`）以及任意 `eip155:<chainId>`——客户端与资源服务端默认注册的都是 `eip155:*`，SDK 为 `eip155:56` / `97` / `8453` / `84532` 之外的二十条 EVM 网络也内置了默认资产。但真正能结算的范围由 facilitator 显式配置的网络决定 |
+| **网络环境** | 三个 TRON 标识（`tron:728126428`、`tron:2494104990`、`tron:3448148188`）以及任意 `eip155:<chainId>`——客户端与资源服务端默认注册的都是 `eip155:*`，官方 `@x402/evm` 为 Base、Base Sepolia 及许多其他 EVM 网络内置了默认资产，但不包括 BSC（`eip155:56` / `97` 需显式指定资产）。但真正能结算的范围由 facilitator 显式配置的网络决定 |
 | **代币标准** | TRC-20 代币（默认内置 USDT 和 USDD 支持）、BEP-20 代币、ERC-20 代币（Base 官方 USDC） |
 | **签名机制** | TIP-712 / EIP-712 类型化数据签名                     |
 | **支付方案** | `exact`、`upto`、`batch-settlement`、`exact_gasfree`（TRON） |
@@ -213,7 +212,7 @@ registerToken(TRON_NILE, {
 });
 ```
 
-在**资源服务器**侧，自定义 EVM 代币通过在 server 的 `src/chains/evm.ts` 中的 `EVM_TOKENS` 表添加一条目来公布——一个显式的 `{ asset, amount, extra }` 对象。添加一条链仅需一条表项；无需改动 SDK。
+在**资源服务器**侧，自定义 EVM 代币通过在路由的 `accepts` 中使用显式的 `{ asset, amount, extra }` 价格对象来公布；无需改动 SDK。（旧示例 server 的 `EVM_TOKENS` 表已随 EVM 示例在 x402 v2.1.0 中移除，请参考[上游 EVM 示例](https://github.com/x402-foundation/x402/tree/main/examples/typescript)。）
 
 注册完成后，即可在 TRON 价格中使用自定义代币符号（例如 `"0.001 MYT"`）。
 
@@ -226,4 +225,4 @@ x402 专为区块链架构深度定制，提供了原生的 TRC-20/BEP-20/ERC-20
 - **开发环境**：推荐优先使用 **测试网** 进行开发与调试。
 - **默认结算资产**：TRON/BSC 路由使用各自配置的稳定币；Base 使用官方 **USDC**。
 - **安全机制**：TIP-712 / EIP-712 类型化数据签名机制确保了安全且最小化信任 (Trust-minimized) 的支付授权流程。
-- **扩展能力**：可通过 TRON 代币注册表（`registerToken`）或 server 的 `EVM_TOKENS` 配置表灵活扩展支持任意自定义的 **TRC-20/BEP-20 代币**。
+- **扩展能力**：可通过 TRON 代币注册表（`registerToken`）或显式的 `{ asset, amount, extra }` 路由价格灵活扩展支持任意自定义的 **TRC-20/BEP-20 代币**。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md
index 1c1cc387..9e9d75ac 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/wallet.md
@@ -56,9 +56,7 @@ x402 协议采用类型化数据签名来执行安全的支付授权。
 
 ## 代币授权
 
-对于 `exact` 支付方案，普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算。客户端需授权 Permit2 合约划转代币——一次性 `approve(Permit2, max)`。在 TRON 上，客户端 SDK 会在首次付款时自动广播此授权；在 EVM 上则从不广播——当 server 声明了 gas 代付扩展时，客户端附上一笔已签名但未广播的授权交由 facilitator 转发，否则授权必须另行完成，不然验款会以 `permit2_allowance_required` 失败。在 TRON 上，当 resource server 声明了 `trc20ApprovalResourceSponsoring`（SDK 1.2.0+）时，client 只签名 `approve(Permit2, MaxUint256)` 而不广播——由 facilitator 临时委托付款方所缺的能量（必要时还有带宽）并广播，因此付款方首笔授权无需 TRX。该路径要求付款方是已激活的单签名 TRON EOA。ERC-3009 代币（如 BSC 测试网 DHLU）无需授权——通过 `transferWithAuthorization` 无 gas 结算。
-
-x402 客户端 SDK 会自动处理此操作。
+对于 `exact` 支付方案，普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算。客户端需授权 Permit2 合约划转代币——一次性 `approve(Permit2, max)`。在 TRON 上，客户端 SDK 会在首次付款时自动广播此授权；在 EVM 上则从不广播——当 server 声明了 gas 代付扩展时，客户端附上 EIP-2612 permit 签名或一笔已签名但未广播的授权交由 facilitator 转发，否则授权必须另行完成，不然验款会以 `permit2_allowance_required` 失败。在 TRON 上，当 resource server 声明了 `trc20ApprovalResourceSponsoring`（SDK 1.2.0+）时，client 只签名 `approve(Permit2, MaxUint256)` 而不广播——由 facilitator 临时委托付款方所缺的能量（必要时还有带宽）并广播，因此付款方首笔授权无需 TRX。该路径要求付款方是已激活的单签名 TRON EOA。从 2.1.0 起，客户端必须注册 `@bankofai/x402-tron-extensions` 中的 `createTrc20ApprovalResourceSponsoringClientExtension(signer)`，否则付款会以 `trc20_approval_client_extension_not_registered` 失败。ERC-3009 代币（如 Base 官方 USDC）无需授权——通过 `transferWithAuthorization` 无 gas 结算。
 
 ## 网络节点端点
 
@@ -80,7 +78,7 @@ x402 客户端 SDK 会自动处理此操作。
 | 网络环境 (Network)  | RPC 端点 (Endpoint)              |
 | :------------------ | :------------------------------- |
 | **Mainnet** (主网)  | `https://bsc-dataseed.binance.org`        |
-| **Testnet** (测试网)   | `https://data-seed-prebsc-1-s1.binance.org:8545`       |
+| **Testnet** (测试网)   | `https://bsc-testnet-rpc.publicnode.com`       |
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md
index 2e3f6a32..5b290ae8 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md
@@ -11,7 +11,7 @@ x402 唤醒了长期闲置的 HTTP `402 Payment Required` 状态码，将其转
 
 #### x402 是商业产品吗？
 
-**不是。** x402 是 x402 协议针对区块链的开源实现，遵循 MIT 许可协议发布。您无需购买任何商业产品即可自由使用。
+**不是。** x402 是 x402 协议针对区块链的开源实现。[代码仓库](https://github.com/BofAI/x402)采用 MIT 许可协议，而已发布的 npm 包 `@bankofai/x402-tron` 与 `@bankofai/x402-tron-extensions` 在其 `package.json` 中声明的是 `Apache-2.0`（官方 `@x402/*` 包同样如此）。您无需购买任何商业产品即可自由使用。
 
 #### 为什么要摒弃传统支付渠道或 API 密钥？
 
@@ -25,13 +25,13 @@ x402 唤醒了长期闲置的 HTTP `402 Payment Required` 状态码，将其转
 
 #### 支持哪些语言和框架？
 
-x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发布：
+x402 是**仅 TypeScript** 的 SDK：TRON 相关包以 `@bankofai/x402-tron` 与 `@bankofai/x402-tron-extensions` 发布，Core、EVM 与框架集成使用官方 `@x402/*` 包：
 
 - **服务端中间件**：Express、Fastify、Hono、Next.js
-- **客户端**：包装 `fetch`（`@bankofai/x402-fetch`）、Axios、MCP 传输
+- **客户端**：包装 `fetch`（`@x402/fetch`）、Axios、MCP 传输
 - **Facilitator**：链无关引擎，按方案 verify + settle
 
-此前的 Python SDK 已移至 `legacy/` 仅供参考。
+已退役的 Python SDK 与旧的根目录 `legacy/` 归档已在 x402 v2.0.0 中移除，`typescript/packages/legacy/` 下的兼容 npm 包也已在 v2.1.0 中移除。
 
 ### Facilitator
 
@@ -62,7 +62,7 @@ x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发
 
 x402 定义了五种命名支付方案。其中四种可端到端使用；`auth-capture` 目前仅提供客户端支持：
 
-- **`exact`**：支付公布的准确金额。EIP-3009 代币（如 Base 官方 USDC、BSC 测试网 DHLU）通过 `transferWithAuthorization` 无 gas 结算；普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算，首次付款需一次性 `approve(Permit2)`。`exact` 的协议 payload 遵循 **x402 Foundation** 的 v2 规范。
+- **`exact`**：支付公布的准确金额。EIP-3009 代币（如 Base 官方 USDC）通过 `transferWithAuthorization` 无 gas 结算；普通 ERC-20/TRC-20 代币（如 BSC USDC/USDT、TRON USDT/USDD）通过 Permit2 路径结算，首次付款需一次性 `approve(Permit2)`。`exact` 的协议 payload 遵循 **x402 Foundation** 的 v2 规范。
 - **`upto`**：按量计费——客户端签署最高至最大金额的 Permit2 授权，服务端仅结算**实际用量**（≤ max）。非常适合**按量计费**、**LLM Token 消耗**等场景。
 - **`batch-settlement`**：面向高频微支付的支付通道——一次性链上存入，然后用链下凭证支付多次请求，一笔交易批量结算。含退款路径。
 - **`exact_gasfree`**（仅限 TRON）：允许买家使用 USDT/USDD 付款而无需持有 TRX 来支付 gas。由 relayer 通过 GasFree API 支付链上 energy——客户端无需配置 API 密钥。relayer 会在付款金额之外，从支付代币中扣除自己的中继费。
@@ -74,10 +74,10 @@ x402 定义了五种命名支付方案。其中四种可端到端使用；`auth-
 
 - 标准的 v2 客户端可以直接访问本 SDK 的 `exact` 受保护端点，无需任何项目特定的适配层。
 - 本 SDK 的客户端可以直接向 v2 兼容的服务端付款。
-- V2 结构中转账授权数据位于 `payload.authorization` 字段（结构化对象）。
-- BSC USDT/USDC 是普通 ERC-20（无 ERC-3009），在 `exact` 方案下通过 Permit2 路径结算——客户端首次付款时自动广播一次性 `approve(Permit2)`。ERC-3009 代币（如 BSC 测试网 DHLU）则无 gas 结算，无需 approve。
+- V2 结构中转账授权数据是结构化对象：EIP-3009 路径位于 `payload.authorization`，Permit2 路径位于 `payload.permit2Authorization`。
+- BSC USDT/USDC 是普通 ERC-20（无 ERC-3009），在 `exact` 方案下通过 Permit2 路径结算，需要一次性 `approve(Permit2)`。在 EVM 上客户端从不广播该授权：要么事先已授权，要么在 server 声明了 gas 代付扩展时交由 facilitator 转发——否则请求会以 `permit2_allowance_required` 失败。
 - Base 主网官方 USDC 在 `exact` 下使用 EIP-3009：付款方签署 `transferWithAuthorization`，无需 Permit2 approve。
-- 仓库中的 `legacy/examples/bsc-testnet-smoke/` 目录（属于保留作参考的 `legacy/` 目录）提供了双向互通的烟雾测试示例（Coinbase 官方客户端 → BANK OF AI 服务端、BANK OF AI 客户端 → Coinbase 官方服务端），可作为调试与集成参考。
+- 原 `legacy/examples/bsc-testnet-smoke/` 互通烟雾测试已随根目录 `legacy/` 归档在 x402 v2.0.0 中移除。当前请以可运行的 [`examples/typescript`](https://github.com/BofAI/x402/tree/main/examples/typescript) 工作区作为 client → server → facilitator 的参考；自 v2.1.0 起它只覆盖 TRON，EVM 请参考[上游示例](https://github.com/x402-foundation/x402/tree/main/examples/typescript)。
 
 ### 资产、网络及费用
 
@@ -85,22 +85,23 @@ x402 定义了五种命名支付方案。其中四种可端到端使用；`auth-
 
 | 网络                          | 代币          | 状态        |
 | ----------------------------- | ------------- | ----------- |
-| TRON 主网 (`tron:0x2b6653dc`)    | USDT (TRC-20) | **Mainnet** |
-| TRON Nile (`tron:0xcd8690dc`)       | USDT (TRC-20) | **Testnet** |
-| TRON Shasta (`tron:0x94a9059e`)   | USDT (TRC-20) | **测试网**（仅 SDK/CLI 支持——官方 facilitator 不结算 Shasta，请用 Nile 或自建） |
-| TRON Mainnet (`tron:0x2b6653dc`) | USDD (TRC-20) | **Mainnet** |
-| TRON Nile (`tron:0xcd8690dc`)       | USDD (TRC-20) | **Testnet** |
+| TRON 主网 (`tron:728126428`)    | USDT (TRC-20) | **Mainnet** |
+| TRON Nile (`tron:3448148188`)       | USDT (TRC-20) | **Testnet** |
+| TRON Shasta (`tron:2494104990`)   | USDT (TRC-20) | **测试网**（仅 SDK/CLI 支持——官方 facilitator 不结算 Shasta，请用 Nile 或自建） |
+| TRON Mainnet (`tron:728126428`) | USDD (TRC-20) | **Mainnet** |
+| TRON Nile (`tron:3448148188`)       | USDD (TRC-20) | **Testnet** |
 | BSC 主网 (`eip155:56`) | USDT (BEP-20) | **Mainnet** |
-| BSC 主网 (`eip155:56`) | USDC (BEP-20) | **Mainnet** |
+| BSC 主网 (`eip155:56`) | USDC（BEP-20；`0x8AC76a…`，不在任何内置代币注册表中——仅能作为显式资产） | **Mainnet** |
 | BSC testnet (`eip155:97`)      | USDT (BEP-20) | **Testnet** |
 | BSC testnet (`eip155:97`)      | USDC (BEP-20) | **Testnet** |
-| BSC testnet (`eip155:97`)      | DHLU (BEP-20, 用于 `exact` 互通测试) | **Testnet** |
 | Base 主网 (`eip155:8453`) | 官方 USDC（ERC-20，EIP-3009） | **Mainnet** |
 | Base Sepolia (`eip155:84532`) | USDC（ERC-20，EIP-3009） | **Testnet** |
 
-其中只有一部分是**默认资产**（TRON 与 BSC 主网的 USDT、BSC 测试网与 Base 的 USDC）。SDK 1.1.0 起，客户端消费管控会拒绝其他资产——包括 TRON USDD、BSC 主网 USDC、BSC 测试网 USDT——除非通过 `spendControls.allowedAssets` 放行。
+自 x402 v2.0.0（`@bankofai/x402-tron` 2.0.0）起，TRON 标识使用十进制链 ID；旧的十六进制写法（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）仍可作为输入别名。
 
-此外，可通过 TRON 代币注册表（`@bankofai/x402-tron` 的 `registerToken`）添加自定义 TRC-20 代币；自定义 BEP-20 代币则通过在 server 的 `EVM_TOKENS` 配置表中添加条目来公布。
+其中只有一部分是**默认资产**（TRON 三个网络上的 USDT，Base 与 Base Sepolia 上的 USDC）。SDK 1.1.0 起，客户端消费管控会拒绝其他资产——包括 TRON USDD 和所有 BSC 资产——除非通过 `spendControls.allowedAssets` 放行。
+
+此外，可通过 TRON 代币注册表（`@bankofai/x402-tron` 的 `registerToken`）添加自定义 TRC-20 代币；自定义 BEP-20 代币则通过在 server 路由上使用显式的 `{ asset, amount, extra }` 价格来公布。
 
 #### 涉及哪些费用？
 
@@ -118,7 +119,7 @@ x402 定义了五种命名支付方案。其中四种可端到端使用；`auth-
 
 1.  **买家（客户端/代理）**：在本地运行时环境（如浏览器、Serverless 函数、代理虚拟机）中完成签名。
 2.  **卖家**：无需接触买家私钥；仅负责验证签名的有效性。
-3.  **Facilitator**：使用自己的结算钱包提交交易，钱包通过 `@bankofai/agent-wallet` 解析——原始私钥不会进入 facilitator 进程。
+3.  **Facilitator**：使用自己的结算钱包提交交易，钱包通过 `@bankofai/agent-wallet` 解析——使用 `privy` 或 `wallet_cli` provider 时私钥留在 facilitator 进程之外（`raw_secret` 把明文私钥存在配置中，仅适用于开发环境）。
 
 #### 退款机制如何运作？
 
@@ -149,11 +150,11 @@ x402 定义了五种命名支付方案。其中四种可端到端使用；`auth-
 在您的 TypeScript 应用中安装已发布的 npm 包并基于这些包开发，例如：
 
 ```bash
-pnpm add @bankofai/x402-fetch @bankofai/x402-tron @bankofai/x402-evm @bankofai/agent-wallet
-pnpm add @bankofai/x402-core @bankofai/x402-express
+pnpm add @x402/core@2.28.0 @x402/fetch@2.28.0 @bankofai/x402-tron@2.1.0 @x402/evm@2.28.0 @bankofai/agent-wallet
+pnpm add @x402/express@2.28.0
 ```
 
-请根据服务框架选择对应包（`express`、`hono`、`fastify` 或 `next`）。[`examples/typescript`](https://github.com/BofAI/x402/tree/main/examples/typescript) 工作区是 client → server → facilitator 流程的可运行参考，不是应用开发的前置条件。
+请根据服务框架选择对应包（`@x402/express`、`@x402/hono`、`@x402/fastify` 或 `@x402/next`），版本与 `@x402/core` 一致为 `2.28.0`——`@bankofai/x402-tron` 2.1.0 要求精确的 `@x402/core@2.28.0`。仅在使用 TRON 资源赞助时再安装 `@bankofai/x402-tron-extensions@2.1.0`。[`examples/typescript`](https://github.com/BofAI/x402/tree/main/examples/typescript) 工作区是 client → server → facilitator 流程的可运行参考，不是应用开发的前置条件。
 
 #### 推荐使用哪个测试网？
 
@@ -175,10 +176,11 @@ BSC 上推荐使用 **BSC Testnet** 进行测试。该网络是 BSC 主网的镜
 
 1.  **签名无效**：域 (Domain) 参数配置错误或载荷 (Payload) 字段不匹配。
 2.  **支付金额不足**：签名载荷中的金额低于服务端要求的金额。
-3.  **授权额度 (Allowance) 不足**：客户端对 Facilitator 的代币授权额度不足。
-4.  **账户余额不足**：客户端钱包地址缺乏足够的 USDT。
+3.  **账户余额不足**：客户端钱包地址缺乏足够的 USDT。
+
+响应体默认是 `{}`。失败原因在 `PAYMENT-REQUIRED` 响应头里——该头部是 Base64 编码的付款要求，其中的 `error` 字段即诊断信息，可用 `@x402/core/http` 的 `decodePaymentRequiredHeader` 解码查看。
 
-建议查看服务端返回的 JSON 响应中的 `error` 字段，以获取具体的错误诊断信息。
+`exact` / `upto` 的 Permit2 路径上授权额度 (Allowance) 不足时，返回的不是 402：服务端会响应 HTTP `412 Precondition Failed`，同一头部中的 `error` 为 `"permit2_allowance_required"`。（`batch-settlement` 的存入路径则以 402 返回其方案专属的错误码。）
 
 #### 在 Nile 测试网运行正常，切换到主网后失败，常见原因有哪些？
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md
index 388748e6..e5c6c11e 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 > **测试网优先：** 本指南默认使用测试网，您可以安全地完成每一步而不花费真实资金。
 
 :::info SDK（仅 TypeScript）
-x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发布。本指南展示如何直接集成已发布的 npm 包。
+x402 是**仅 TypeScript** 的 SDK：TRON 机制以 `@bankofai/x402-tron` 发布，运行在官方 `@x402/*` Core 与 HTTP 包之上。本指南展示如何直接集成已发布的 npm 包。
 :::
 
 ---
@@ -31,7 +31,7 @@ x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发
 
 ### 开始前清单
 
-- [ ] 已安装 **Node.js 22+** 和 **pnpm 11.1+**
+- [ ] 已安装 **Node.js 24.22.1+** 和 **pnpm 11.1+**
 - [ ] 已创建专用**测试钱包**（见下文）
 - [ ] 已领取测试代币（免费）
 - [ ] 有一个目标 x402 保护的 API URL（例如按[卖家快速入门](./quickstart-for-sellers.md)启动的 `/credit` 接口）
@@ -94,16 +94,16 @@ x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发
 在您的 TypeScript 应用中安装已发布的 npm 包：
 
 ```bash
-pnpm add @bankofai/agent-wallet @bankofai/x402-fetch @bankofai/x402-tron
+pnpm add @bankofai/agent-wallet @x402/core@2.28.0 @x402/fetch@2.28.0 @bankofai/x402-tron@2.1.0
 pnpm add -D tsx   # 运行下面的 TypeScript 入口文件
 ```
 
-如果您的项目不使用 pnpm，也可以用 `npm install` 或 `yarn add` 安装同名包。
+如果您的项目不使用 pnpm，也可以用 `npm install` 或 `yarn add` 安装同名包。`@x402/core` 与 `@x402/fetch` 请保持精确的 `2.28.0`——`@bankofai/x402-tron` 2.1.0 将 `@x402/core@2.28.0` 声明为精确版本的 peer 依赖。
 
 :::info 钱包管理
-x402 使用 [Agent Wallet](../../Agent-Wallet/QuickStart.md) 解析和管理钱包凭据。Agent Wallet 会随上面的包一起安装。私钥解析优先级：
-1. 加密钱包文件（通过 Agent Wallet CLI 导入）
-2. 环境变量 `AGENT_WALLET_PRIVATE_KEY`
+x402 使用 [Agent Wallet](../../Agent-Wallet/QuickStart.md) 解析和管理钱包凭据。Agent Wallet（3.0+）会随上面的包一起安装。钱包解析优先级：
+1. Agent Wallet CLI 配置（`~/.agent-wallet`），且其中至少有一个钱包——通过 `agent-wallet start raw_secret`、`wallet_cli` 或 `privy` 配置
+2. 环境变量 `AGENT_WALLET_PRIVATE_KEY`（或 `AGENT_WALLET_MNEMONIC`）
 
 本指南使用环境变量方式。
 :::
@@ -145,7 +145,8 @@ const signer = await createClientTronSigner(wallet, {
 
 ```typescript
 import { resolveWallet, type Wallet, type Eip712Capable } from "@bankofai/agent-wallet";
-import { x402Client, wrapFetchWithPayment } from "@bankofai/x402-fetch";
+import { x402Client } from "@x402/core/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
 import { createClientTronSigner, TRON_NILE } from "@bankofai/x402-tron";
 import { ExactTronScheme } from "@bankofai/x402-tron/exact/client";
 
@@ -209,15 +210,14 @@ client.setSpendControls({ maxAmountPerPayment: "$5" });
 
 | 问题 | 原因 | 解决方案 |
 |---------|-------|----------|
-| `WalletNotFoundError` / 解析不到钱包 | agent-wallet 里没有钱包，或当前 shell 未设置 `AGENT_WALLET_PRIVATE_KEY` | 执行 `agent-wallet start`，或确保在**运行脚本的同一终端窗口**中执行 `export` |
-| `WalletNotFoundError: No active wallet set` | agent-wallet 未配置钱包 | 运行 `agent-wallet start` 并按提示导入私钥 |
+| `resolve_wallet could not find a wallet source in config or env` | agent-wallet 里没有钱包，或当前 shell 未设置 `AGENT_WALLET_PRIVATE_KEY` | 执行 `agent-wallet start`，或确保在**运行脚本的同一终端窗口**中执行 `export` |
 | `Insufficient balance` / 余额错误 | 测试钱包 USDT/USDD 不足 | 返回前置准备，从水龙头领取测试代币 |
 | `No network/scheme registered for x402 version: 2 …` | server 公布的网络里没有任何一个注册了 scheme——该错误在 selector 运行之前就会抛出 | 检查 server 的 `accepts` 是否包含 `network: TRON_NILE`，以及是否调用了 `client.register(TRON_NILE, …)` |
 | `permit2_allowance_required` | Permit2 授权额度缺失或过低 | 在 TRON 上 SDK 会在首次付款时自动广播一次性 `approve`；若仍存在，检查钱包是否有足够 TRX 支付这笔授权 |
 | `approval_reset_required`（TRON） | 该代币的 Permit2 授权额度非零但不足，默认的 `zero-first` 策略不会直接覆写 | 先把该代币的 Permit2 授权额度重置为 `0` 再重试——SDK 不会自动插入 `approve(0)` |
 | `approval_asset_unsupported`（TRON） | 该代币不属于已知 Permit2 资产，也没有为它配置授权策略 | 用 `createTrc20ApprovalPolicy` 为其配置策略，或改用受支持的代币付款 |
 | `Connection timeout` | 网络或请求超时 | 检查 API 服务、facilitator 和 TRON RPC 连接 |
-| `ERR_PACKAGE_PATH_NOT_EXPORTED` | 项目未声明为 ESM | 在 `package.json` 中添加 `"type": "module"` |
+| （`tsx` 下）`Top-level await is currently not supported with the "cjs" output format` | 项目未声明为 ESM，脚本中的顶层 `await` 被按 CommonJS 编译 | 在 `package.json` 中添加 `"type": "module"` |
 
 如需更细粒度的错误处理：
 
@@ -231,7 +231,7 @@ try {
     console.error(await res.text());
   }
 } catch (error) {
-  if (error instanceof Error && error.message.includes("no payment option")) {
+  if (error instanceof Error && error.message.includes("No network/scheme registered")) {
     console.error("No matching payment option — check TRON_NILE vs the server's accepts");
   } else if (error instanceof Error && error.message.includes("allowance")) {
     console.error("Insufficient token allowance — check wallet balance");
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md
index 8f6d27d3..0f038173 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md
@@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem';
 整个流程共 **4 步**，预计耗时 **15–20 分钟**。
 
 :::info SDK（仅 TypeScript）
-x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发布。本指南展示如何基于已发布的 npm 包开发。
+x402 是**仅 TypeScript** 的 SDK：TRON 机制以 `@bankofai/x402-tron` 发布，运行在官方 `@x402/*` Core、EVM 与框架包之上。本指南展示如何基于已发布的 npm 包开发。
 :::
 
 ---
@@ -28,7 +28,7 @@ x402 是**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` 包发
 在终端（macOS/Linux 的 Terminal，或 Windows 的 PowerShell/命令提示符）中运行以下命令，确认所需工具已安装：
 
 ```bash
-node --version    # 需要 Node.js 22 或更高版本
+node --version    # 需要 Node.js 24.22.1 或更高版本
 pnpm --version    # 需要 pnpm 11.1 或更高版本
 git --version     # 版本控制工具
 ```
@@ -132,14 +132,14 @@ git --version     # 版本控制工具
 
 ## 第一步：安装 SDK 包
 
-在您的 TypeScript API 项目中安装 Express 适配器以及 TRON/EVM 支付 scheme：
+在您的 TypeScript API 项目中安装官方 Core、Express 适配器以及 TRON/EVM 支付 scheme：
 
 ```bash
-pnpm add express @bankofai/x402-core @bankofai/x402-express @bankofai/x402-tron @bankofai/x402-evm
+pnpm add express @x402/core@2.28.0 @x402/express@2.28.0 @bankofai/x402-tron@2.1.0 @x402/evm@2.28.0
 pnpm add -D tsx   # 运行下面的 TypeScript 入口文件
 ```
 
-请根据服务框架选择对应包（`@bankofai/x402-express`、`@bankofai/x402-hono`、`@bankofai/x402-fastify` 或 `@bankofai/x402-next`）。如果项目不使用 pnpm，也可以用 `npm install` 或 `yarn add` 安装同名包。
+请根据服务框架选择对应包（`@x402/express`、`@x402/hono`、`@x402/fastify` 或 `@x402/next`），版本与 `@x402/core` 一致为 `2.28.0`——`@bankofai/x402-tron` 2.1.0 将 `@x402/core@2.28.0` 声明为精确版本的 peer 依赖。`@x402/evm` 仅在使用 BSC/Base 路由时需要。如果项目不使用 pnpm，也可以用 `npm install` 或 `yarn add` 安装同名包。
 
 如果开发者想要一个更完整的 client → server → facilitator 例子，可以参考仓库中的 [examples](https://github.com/BofAI/x402/tree/main/examples/typescript)；应用开发仍应依赖已发布的 npm 包，而不是链接 monorepo 源码。
 
@@ -169,16 +169,13 @@ pnpm add -D tsx   # 运行下面的 TypeScript 入口文件
 
 ```typescript
 import express from "express";
-import { createResourceServer } from "@bankofai/x402-core";
-import { HTTPFacilitatorClient } from "@bankofai/x402-core/server";
-import {
-  x402HTTPResourceServer,
-  paymentMiddlewareFromHTTPServer,
-} from "@bankofai/x402-express";
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { x402HTTPResourceServer } from "@x402/core/http";
+import { paymentMiddlewareFromHTTPServer } from "@x402/express";
 import { TRON_NILE } from "@bankofai/x402-tron";
 import { ExactTronScheme } from "@bankofai/x402-tron/exact/server";
 
-const server = createResourceServer(
+const server = new x402ResourceServer(
   new HTTPFacilitatorClient({
     // 运行前请替换——服务端启动时会与 facilitator 同步，
     // 占位地址会让第一个受保护请求失败（主机不可达或返回 HTTP 错误状态时是 500；
@@ -221,15 +218,12 @@ express()
 
 ```typescript
 import express from "express";
-import { createResourceServer } from "@bankofai/x402-core";
-import { HTTPFacilitatorClient } from "@bankofai/x402-core/server";
-import {
-  x402HTTPResourceServer,
-  paymentMiddlewareFromHTTPServer,
-} from "@bankofai/x402-express";
-import { ExactEvmScheme } from "@bankofai/x402-evm/exact/server";
-
-const server = createResourceServer(
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { x402HTTPResourceServer } from "@x402/core/http";
+import { paymentMiddlewareFromHTTPServer } from "@x402/express";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
+
+const server = new x402ResourceServer(
   new HTTPFacilitatorClient({
     // 运行前请替换——服务端启动时会与 facilitator 同步，
     // 占位地址会让第一个受保护请求失败（主机不可达或返回 HTTP 错误状态时是 500；
@@ -311,7 +305,7 @@ Facilitator 是一个**自动结算服务**：当有人为您的 API 付款时
 在 `HTTPFacilitatorClient` 中将 `url` 设为官方端点：
 
 ```typescript
-const server = createResourceServer(
+const server = new x402ResourceServer(
   new HTTPFacilitatorClient({
     url: "https://facilitator.bankofai.io",
   })
@@ -320,7 +314,7 @@ const server = createResourceServer(
 
 这是您的 x402 server 用于验证和结算付款的地址——**仅供 API 调用**，无需在浏览器中打开。
 
-> ⚠️ **未配置 API Key 时，该端点受速率限制**（每个 IP 每分钟一次 `/settle`）。仅适合测试。
+> ⚠️ **未配置 API Key 时，该端点受速率限制**（每个 IP 每分钟 10 次，`/verify` 与 `/settle` 分别计数）。仅适合测试。
 
 #### 4.2 申请 API Key
 
@@ -328,14 +322,14 @@ const server = createResourceServer(
 2. 在 Dashboard 上点击 **"Create API Key"**
 3. 确认后，在 Dashboard 点击 **View** 查看并复制您的 API Key
 
-配置 API Key 后，官方服务允许**每个 API Key 每分钟调用 `/settle` 1,000 次**，足以满足生产需求。
+配置 API Key 后，官方服务允许**每个 API Key 每分钟 `/verify` 与 `/settle` 各 1,000 次**，足以满足生产需求。
 
 #### 4.3 将 API Key 接入您的 server
 
 官方 key 以 `X-API-KEY` 头的形式随每次 facilitator 调用发送。生产环境中，请将它保存在环境变量或密钥管理系统中，并随 facilitator 请求发送。
 
 ```bash
-FACILITATOR_API_KEY=paste_your_api_key_here
+export FACILITATOR_API_KEY=paste_your_api_key_here
 ```
 
 只有传入 `createAuthHeaders`，`HTTPFacilitatorClient` 才会发送该请求头——否则服务端会静默停留在匿名档位：
@@ -362,7 +356,7 @@ new HTTPFacilitatorClient({
 
 自托管方式让您完全掌控结算钱包、RPC 节点以及注册哪些网络与方案——SDK 与 facilitator 本身都不收取任何费用。它运行示例 facilitator（`examples/typescript/facilitator/basic`），通过 HTTP 暴露 `/verify`、`/settle`、`/supported`，并按付款的 `network` 字段分发。
 
-> **Base 卖家注意：** 仓库自带的示例 facilitator 只注册了 `eip155:97` 与 `eip155:56`（见 `facilitator/basic/src/chains/evm.ts` 的 `EVM_NETWORKS`）。要在 Base 上结算，请使用已启用 `eip155:8453` 与 `eip155:84532` 的官方 facilitator，或自行把这两个网络加进 `EVM_NETWORKS`。
+> **BSC 与 Base 卖家注意：** 自 x402 v2.1.0 起，仓库自带的示例 facilitator 只注册 TRON 网络（见 `facilitator/basic/src/chains/tron.ts` 的 `TRON_NETWORKS`）。要在 BSC 或 Base 上结算，请使用已启用 `eip155:56`、`eip155:97`、`eip155:8453` 与 `eip155:84532` 的官方 facilitator，或参考[上游示例](https://github.com/x402-foundation/x402/tree/main/examples/typescript)用官方 `@x402/evm` 自建 EVM facilitator。
 
 > ⚠️ **安全提醒——请先阅读：**
 > - 自托管 Facilitator 使用您的钱包提交链上结算交易——**此钱包应与您的收款钱包分开**
@@ -375,27 +369,25 @@ facilitator 验证签名并在链上结算。它按链注册 `exact` scheme 并
 
 ```typescript
 // examples/typescript/facilitator/basic/src/index.ts（节选）
-import { x402Facilitator } from "@bankofai/x402-core/facilitator";
+import { x402Facilitator } from "@x402/core/facilitator";
 
 const facilitator = new x402Facilitator()
   .onBeforeSettle(async ctx => console.log("[settle] before", ctx.requirements.network))
   .onAfterSettle(async ctx => console.log("[settle] after", ctx.requirements.network))
   .onSettleFailure(async ctx => console.log("[settle] failure", ctx));
 
-// 仅当钱包解析成功时才注册该链（可仅 EVM、仅 TRON，或两者）。
-const evm = await registerEvm(facilitator);
+// 仅当钱包解析成功时才注册该链。只注册 TRON 网络。
 const tron = await registerTron(facilitator);
 
 // 在 FACILITATOR_PORT 上暴露 POST /verify、POST /settle、GET /supported。
 app.listen(PORT, () => console.log(`🚀 Facilitator on http://localhost:${PORT}`));
 ```
 
-每个链模块将 agent-wallet 适配为 facilitator signer：
+TRON 链模块将 agent-wallet 适配为 facilitator signer：
 
-- **EVM** —— `createFacilitatorEvmSigner(wallet, { network, rpcUrl })`，然后 `facilitator.register(network, new ExactEvmScheme(signer))`
 - **TRON** —— `createFacilitatorTronSigner(wallet, { network, apiKey })`，然后 `facilitator.register(network, new ExactTronScheme(signer))`
 
-signer 工厂内部构建 viem client / TronWeb；示例**从不读取原始私钥**——`AGENT_WALLET_PRIVATE_KEY` 由 `@bankofai/agent-wallet` 消费。
+signer 工厂内部构建 TronWeb；示例**从不读取原始私钥**——`AGENT_WALLET_PRIVATE_KEY` 由 `@bankofai/agent-wallet` 消费。
 
 #### 4.2 启动 Facilitator
 
@@ -408,9 +400,10 @@ pnpm dev:facilitator
 **启动成功后，应看到类似输出：**
 
 ```
-[evm] facilitator registered eip155:97 (0x…)
 [tron] facilitator registered tron:3448148188 (T…)
-🚀 Facilitator on http://localhost:4022  (evm=true, tron=true)
+[tron] facilitator registered tron:2494104990 (T…)
+[tron] facilitator registered tron:728126428 (T…)
+🚀 Facilitator on http://localhost:4022  (tron=true)
 ```
 
 > ✅ **成功：** Facilitator 在 4022 端口运行——**保持此终端窗口打开，不要关闭**
@@ -470,10 +463,10 @@ curl -si http://localhost:4021/credit | grep -i '^payment-required:' | cut -d' '
 |---------|-------|----------|
 | `Failed to fetch` / connection refused | facilitator 或 server 未运行 | 先启动 facilitator，再运行您的 API server 入口文件 |
 | 客户端选不出付款选项 | 客户端选择的网络或代币与 server 公布的选项不匹配 | 检查 server 的 `accepts`（网络 + 代币），例如 `TRON_NILE` + `USDT` |
-| `npx tsx` 下出现 `ERR_PACKAGE_PATH_NOT_EXPORTED` | 项目未声明为 ESM | 在 `package.json` 中添加 `"type": "module"` |
+| `npx tsx` 下出现 `Top-level await is currently not supported with the "cjs" output format` | 项目未声明为 ESM，含顶层 `await` 的入口文件被按 CommonJS 编译 | 在 `package.json` 中添加 `"type": "module"` |
 | `No network/scheme registered for x402 version: 2 …` | 客户端选择的网络没有注册的 scheme | 确保 client 注册了目标网络，例如 `TRON_NILE` |
-| `Insufficient balance` / allowance 错误 | 测试钱包缺少测试代币，或 Permit2 授权额度过低 | 从水龙头领取测试代币；client 在首次付款时会自动批准 Permit2 |
-| `Connection timeout` | 网络或请求超时 | 检查连接。注意 SDK 不读取任何环境变量——`EVM_RPC_URL` 由 参考示例程序识别；在自己的服务端里请把 RPC 地址直接传给 signer 工厂函数 |
+| `Insufficient balance` / allowance 错误 | 测试钱包缺少测试代币，或 Permit2 授权额度过低 | 从水龙头领取测试代币。在 TRON 上 client 首次付款时会自动批准 Permit2；在 EVM 上需要自己先批准一次 Permit2 |
+| `Connection timeout` | 网络或请求超时 | 检查连接。注意 SDK 不读取任何环境变量——`TRON_GRID_API_KEY` 由参考示例程序读取；在自己的代码里请把 `apiKey` / `rpcUrl` 直接传给 signer 工厂函数 |
 
 ---
 
@@ -498,15 +491,11 @@ price: "1 USDT",
 
 ### 2. 设置可靠的 EVM RPC
 
-BSC 主网需要稳定端点。为 client 和 facilitator 都设置：
-
-```bash
-EVM_RPC_URL=https://bsc-rpc.publicnode.com
-```
+BSC 主网需要稳定端点，例如 `https://bsc-rpc.publicnode.com`。SDK 不读取环境变量，且自 v2.1.0 起仓库示例只覆盖 TRON——请在用官方 `@x402/evm` 构建的 EVM signer 上配置该端点，client 与自托管 facilitator 都需要。
 
 ### 3.（自托管）将 Facilitator 切换到主网
 
-示例 facilitator 的 `TRON_NETWORKS` 已包含 `TRON_MAINNET`（`tron:728126428`），`EVM_NETWORKS` 已包含 `eip155:97` 与 `eip155:56`——但不含 Base（`eip155:8453` / `eip155:84532`），若在 Base 结算需自行添加。向 Facilitator 钱包充入足够的真实 TRX/BNB 以支付结算 gas，然后重启：
+示例 facilitator 的 `TRON_NETWORKS` 已包含 `TRON_MAINNET`（`tron:728126428`）；它不注册任何 EVM 网络，BSC 或 Base 请通过官方 facilitator 或您自建的 `@x402/evm` facilitator 结算。向 Facilitator 钱包充入足够的真实 TRX 以支付结算能量，然后重启：
 
 ```bash
 pnpm dev:facilitator
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md
index 8eacb38c..95aa880d 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/index.md
@@ -13,7 +13,7 @@ x402 是一种基于 HTTP `402 Payment Required` 状态码的区块链开放支
 
 **有意参与文档共建？** 欢迎在 [GitHub 仓库](https://github.com/BofAI/docs)提交 PR！我们唯一的原则是保持文档的中立性：除必要的资源链接外，请避免包含任何品牌推广内容。
 
-**使用 x402 开发？** 请在您的 TypeScript 应用中安装已发布的 [`@bankofai/x402-*`](https://www.npmjs.com/package/@bankofai/x402-tron) 包。[`x402` 仓库](https://github.com/BofAI/x402) 在 `examples/typescript/` 下提供完整 client → server → facilitator 可运行示例，用于参考——`exact`、`gasfree`、`upto`、`batch-settlement`。
+**使用 x402 开发？** 请在您的 TypeScript 应用中安装已发布的 [`@bankofai/x402-tron`](https://www.npmjs.com/package/@bankofai/x402-tron) 等包，并搭配官方 `@x402/*` 包。[`x402` 仓库](https://github.com/BofAI/x402) 在 `examples/typescript/` 下提供完整 client → server → facilitator 可运行示例，用于参考——`exact`、`gasfree`、`upto`、`batch-settlement`。
 
 ## 为什么要使用 x402？
 
@@ -72,9 +72,9 @@ x402 支持广泛的应用场景，包括：
 
 x402 目前支持以下网络环境：
 
-- **TRON 主网** (`tron:0x2b6653dc`)
-- **TRON Shasta 测试网** (`tron:0x94a9059e`)——仅 SDK/CLI 可用，官方 facilitator 不结算
-- **TRON Nile 测试网** (`tron:0xcd8690dc`)
+- **TRON 主网** (`tron:728126428`)
+- **TRON Shasta 测试网** (`tron:2494104990`)——仅 SDK/CLI 可用，官方 facilitator 不结算
+- **TRON Nile 测试网** (`tron:3448148188`)
 - **BSC 主网** （`eip155:56`）
 - **BSC 测试网** （`eip155:97`)
 - **Base 主网**（`eip155:8453`）
@@ -82,7 +82,9 @@ x402 目前支持以下网络环境：
 
 Base 主网使用官方 USDC，通过 `exact` 方案和 EIP-3009 授权完成支付。
 
-> **SDK（仅 TypeScript）**：x402 是仅 TypeScript 的 SDK，以颗粒化 `@bankofai/x402-*` npm 包发布（`core`、`evm`、`tron`、`fetch`、`express`、`hono`、`fastify`、`next`、`axios`、`mcp`、`extensions`）。源码由 pnpm/turbo monorepo 维护，但应用开发应安装已发布的包。它定义了五种命名方案：`exact`（ERC-3009 / Permit2）、`upto`、`batch-settlement`、`exact_gasfree`（TRON），以及目前仅有 client 的 `auth-capture`（EVM）。此前的 Python + TypeScript SDK 已移至 `legacy/` 仅供参考。完整对比详见 [SDK 功能特性](./x402/sdk-features)。
+自 x402 v2.0.0 起，TRON 标识使用十进制链 ID；旧的十六进制写法（`tron:0x2b6653dc`、`tron:0x94a9059e`、`tron:0xcd8690dc`）仍可作为输入别名。
+
+> **SDK（仅 TypeScript）**：x402 是仅 TypeScript 的 SDK：TRON 机制与 TRON 资源赞助扩展以 `@bankofai/x402-tron` 和 `@bankofai/x402-tron-extensions` 发布，构建在官方 `@x402/*` 包（`core`、`evm`、`fetch`、`express`、`hono`、`fastify`、`next`、`axios`、`mcp`、`extensions`）之上。源码由 pnpm/turbo monorepo 维护，但应用开发应安装已发布的包。它定义了五种命名方案：`exact`（ERC-3009 / Permit2）、`upto`、`batch-settlement`、`exact_gasfree`（TRON），以及目前仅有 client 的 `auth-capture`（EVM）。上一代 Python + TypeScript SDK 归档已在 x402 v2.0.0 中移除，`typescript/packages/legacy/` 下的兼容 npm 包也已在 v2.1.0 中移除。完整对比详见 [SDK 功能特性](./x402/sdk-features)。
 
 
 ## 快速开始
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
index 03865aac..98786c82 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
@@ -1,15 +1,15 @@
 ---
 title: 'SDK 功能矩阵'
-description: 'x402 TypeScript SDK 的功能支持矩阵，以颗粒化 @bankofai/x402-* 包发布。'
+description: 'x402 TypeScript SDK 的功能支持矩阵：基于官方 @x402/* Core 的 @bankofai/x402-tron 与 @bankofai/x402-tron-extensions 包。'
 ---
 
 # SDK 功能矩阵
 
 本页跟踪 x402 SDK 的功能支持情况。
 
-> **SDK（仅 TypeScript）**：x402 是一个**仅 TypeScript** 的 SDK，以颗粒化的 `@bankofai/x402-*` npm 包发布。源码由 pnpm/turbo monorepo 维护，但应用应依赖已发布的包。此前的 Python + TypeScript SDK 已移至 `legacy/` 仅供参考。
+> **SDK（仅 TypeScript）**：x402 是一个**仅 TypeScript** 的 SDK。TRON 机制与 TRON 资源赞助扩展以 `@bankofai/x402-tron` 与 `@bankofai/x402-tron-extensions` npm 包发布，Core、EVM、HTTP/MCP 集成和通用扩展则直接使用 x402 Foundation 官方的 `@x402/*` 包。源码由 pnpm/turbo monorepo 维护，但应用应依赖已发布的包。上一代 Python + TypeScript SDK 的 `legacy/` 归档已在 2.0.0 中从仓库移除，`typescript/packages/legacy/` 下的兼容包也已在 2.1.0 中移除。
 >
-> **当前版本：1.2.0**（2026-08-28）。11 个 `@bankofai/x402-*` 包共用一条版本线，但不再次次齐步发布：1.2.0 发布了 `@bankofai/x402-extensions` 与 `@bankofai/x402-tron` 的 `1.2.0`，`@bankofai/x402-express`、`-fastify`、`-hono`、`-next` 的 `1.1.1`，而 `@bankofai/x402-core`、`-evm`、`-fetch`、`-axios`、`-mcp` 仍为 `1.1.0`（本次发布未变更其 API 与依赖）。每个包将内部依赖锁定为对应包已发布版本的 `~` 范围，因此请按上述版本组合安装。SDK 要求 **Node.js 22+**。
+> **当前版本：2.1.0**（2026-10-23）。付款调用链改为基于官方 `@x402/core` `2.28.0`，`@bankofai/x402-tron` `2.1.0` 将其声明为精确版本的 peer 依赖；请搭配对应的官方 HTTP/MCP 集成（`@x402/fetch`、`@x402/axios`、`@x402/express`、`@x402/fastify`、`@x402/hono`、`@x402/next` 或 `@x402/mcp`，均为 `2.28.0`）。TRON 资源赞助移入独立的 `@bankofai/x402-tron-extensions` `2.1.0`，它锁定机制包的精确版本——两个 TRON 包需一起升级。EVM 直接使用官方 `@x402/evm` `2.28.0`，通用扩展使用官方 `@x402/extensions` `2.28.0`；本地 EVM 包与 `@bankofai/x402-extensions` 已移除。`@bankofai/x402-core` 及基于它的 `@bankofai/x402-*` HTTP/MCP 适配器不能与 2.1 机制混用——新的 TRON 集成请使用官方 Core 与适配器。从 2.0 升级需要迁移源码，见 [TRON 2.1 迁移指南](https://github.com/BofAI/x402/blob/main/docs/migrations/tron-2.1.md)。SDK 要求 **Node.js 24.22.1+**；可运行示例使用 `@bankofai/agent-wallet` **3.0+**。
 
 ---
 
@@ -17,17 +17,18 @@ description: 'x402 TypeScript SDK 的功能支持矩阵，以颗粒化 @bankofai
 
 | 包 | 用途 |
 |---------|---------|
-| `@bankofai/x402-core` | 协议类型、client/facilitator/server 引擎、`HTTPFacilitatorClient`、可观测性 |
-| `@bankofai/x402-evm` | EVM 机制：`exact`、`upto`、`batch-settlement`，另含 `auth-capture` 的 client（`@bankofai/x402-evm/auth-capture/client`，不导出 server 与 facilitator） |
-| `@bankofai/x402-tron` | TRON 机制：`exact`、`upto`、`batch-settlement`、`exact_gasfree` |
-| `@bankofai/x402-fetch` | 包装 `fetch` 的 client（`wrapFetchWithPayment`） |
-| `@bankofai/x402-express` | Express server 中间件 |
-| `@bankofai/x402-hono` | Hono server 中间件 |
-| `@bankofai/x402-fastify` | Fastify server 中间件 |
-| `@bankofai/x402-next` | Next.js server 中间件 |
-| `@bankofai/x402-axios` | Axios client 包装 |
-| `@bankofai/x402-mcp` | 面向 AI 代理的 MCP 传输（client + server） |
-| `@bankofai/x402-extensions` | 扩展：EVM gas 赞助（`eip2612GasSponsoring`、`erc20ApprovalGasSponsoring`）、TRON 资源赞助（`trc20ApprovalResourceSponsoring`，1.2.0 新增）、payment-identifier、bazaar、sign-in-with-x、offer-receipt、builder-code |
+| `@bankofai/x402-tron` | TRON 机制：`exact`、`upto`、`batch-settlement`、`exact_gasfree`；TRON signer 工厂、`/rpc` 与 `/transactions` 工具、TRON logger |
+| `@bankofai/x402-tron-extensions` | TRON 授权资源赞助（`trc20ApprovalResourceSponsoring`）：声明、client 预签名扩展、facilitator runtime 与协调器——2.1.0 起移入此包 |
+| `@x402/core`（官方） | 协议类型、client/facilitator/server 引擎、`HTTPFacilitatorClient` |
+| `@x402/evm`（官方） | EVM 机制：`exact`、`upto`、`batch-settlement`，另含 `auth-capture` 的 client（`@x402/evm/auth-capture/client`，不导出 server 与 facilitator） |
+| `@x402/fetch`（官方） | 包装 `fetch` 的 client（`wrapFetchWithPayment`） |
+| `@x402/express`（官方） | Express server 中间件 |
+| `@x402/hono`（官方） | Hono server 中间件 |
+| `@x402/fastify`（官方） | Fastify server 中间件 |
+| `@x402/next`（官方） | Next.js server 中间件 |
+| `@x402/axios`（官方） | Axios client 包装 |
+| `@x402/mcp`（官方） | 面向 AI 代理的 MCP 传输（client + server） |
+| `@x402/extensions`（官方） | 通用扩展：EVM gas 赞助（`eip2612GasSponsoring`、`erc20ApprovalGasSponsoring`）、payment-identifier、bazaar、sign-in-with-x、offer-receipt、builder-code |
 
 ---
 
@@ -55,14 +56,14 @@ description: 'x402 TypeScript SDK 的功能支持矩阵，以颗粒化 @bankofai
 | `tron:728126428` | `TRON_MAINNET` | ✅ |
 | `tron:3448148188` | `TRON_NILE` | ✅ |
 | `tron:2494104990` | `TRON_SHASTA` | ✅ |
-| `eip155:56`（BSC 主网） | - | ✅ |
-| `eip155:97`（BSC 测试网） | - | ✅ |
+| `eip155:56`（BSC 主网） | - | ✅（仅显式资产） |
+| `eip155:97`（BSC 测试网） | - | ✅（仅显式资产） |
 | `eip155:8453`（Base 主网） | - | ✅ |
 | `eip155:84532`（Base Sepolia） | - | ✅（CLI/SDK 测试） |
 
-> **TRON 标识格式**：自 `@bankofai/x402-tron` 2.0.0 起，SDK 常量使用十进制 CAIP-2 引用。旧的十六进制形式（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）仍可作为输入别名使用，官方 facilitator 与 API Catalog 目前返回的也是十六进制形式。
+> **TRON 标识格式**：自 `@bankofai/x402-tron` 2.0.0 起，SDK 常量使用十进制 CAIP-2 引用。旧的十六进制形式（`tron:0x2b6653dc`、`tron:0xcd8690dc`、`tron:0x94a9059e`）仍可作为输入别名使用，并会被规范化为十进制形式。官方 facilitator 的 `/supported` 返回十进制标识；API Catalog 目前仍列出十六进制形式。
 
-> 另有二十条上游 EVM 链（MegaETH、Monad、Polygon、Arbitrum One/Sepolia、Celo、XDC、Flare、Mezo、Radius、Stable、ADI、HPP、Igra 等）也已接入 EVM 默认资产注册表。公开 API Catalog 只发布 Base 主网路由；Base Sepolia 保留用于 CLI/SDK 测试。
+> EVM 支持来自官方 `@x402/evm` 2.28.0。其默认资产注册表覆盖 Base、Base Sepolia、Ethereum、Polygon、Arbitrum One/Sepolia、Avalanche、Celo、Sei、MegaETH、Monad、Stable、XDC、Flare、Mezo、Radius、ADI、HPP、Igra 等链，但**不包括 BSC**。在 BSC 上，路由价格须写成显式的 `{ asset, amount, extra }` 对象（写 `$` 价格会报 `No default asset configured for network eip155:56`），client 也须把该资产加入 `spendControls.allowedAssets`。公开 API Catalog 只发布 Base 主网路由；Base Sepolia 保留用于 CLI/SDK 测试。
 
 ---
 
@@ -90,7 +91,7 @@ scheme/network server 现在会按资产转账方式声明自己支持哪些付
 
 v1.0 的 `SchemeNetworkServer` 实现可以不声明付款流程，它们会继续沿用 authorization 流程。
 
-`upfront` 与 `escrow` 是给自定义方案用的编排钩子。截至 1.1.0，内置的四个 server 方案（`exact`、`upto`、`batch-settlement`、`exact_gasfree`）都只声明 `authorization`，因此使用内置方案时 `extra.paymentFlow` 不会出现在协议数据里。
+TRON 的 server 方案（`exact`、`upto`、`batch-settlement`、`exact_gasfree`）以及 EVM 的 `upto` 与 `batch-settlement` 只声明 `authorization`。官方 EVM `exact` 方案（`@x402/evm`）在 `eip3009` 和 `permit2` 下还支持 `upfront`：路由在该付款选项上设置 `extra: { paymentFlow: "upfront" }` 即可启用，只有这时 `extra.paymentFlow` 才会出现在协议数据里。没有任何内置方案声明 `escrow`，它仍是留给自定义方案的钩子。
 
 > **x402 Foundation v2 兼容性**：`exact` 方案（EVM 和 TRON）符合 **x402 Foundation** 发布的 v2 线格式。标准 v2 client 可与本 SDK 的 server 互通，反之亦然。详见[网络与代币支持 → `exact` 方案](./core-concepts/network-and-token-support.md#exact-scheme)。
 
@@ -98,31 +99,42 @@ v1.0 的 `SchemeNetworkServer` 实现可以不声明付款流程，它们会继
 
 ## 扩展（Extensions） {#extensions}
 
-`@bankofai/x402-extensions` 提供一组可选的协议扩展：`bazaar`、`sign-in-with-x`、`offer-receipt`、`payment-identifier`、`eip2612-gas-sponsoring`、`erc20-approval-gas-sponsoring`、`trc20-approval-resource-sponsoring` 与 `builder-code`。它们均从包根导出——赞助类扩展没有单独的子路径入口。由 resource server 在 `PaymentRequired.extensions` 中声明某个扩展；赞助类扩展与 `payment-identifier` 只在 server 声明后才生效，而 `builder-code` 的归属码由注册了它的一方自行附加，不依赖 server 声明。
+通用协议扩展——`bazaar`、`sign-in-with-x`、`offer-receipt`、`payment-identifier`、`eip2612-gas-sponsoring`、`erc20-approval-gas-sponsoring` 与 `builder-code`——来自官方 `@x402/extensions` `2.28.0`：大多通过 `@x402/extensions/bazaar` 这类子路径导入，两个 EVM gas 赞助扩展从包根导入。TRON 的 `trc20-approval-resource-sponsoring` 单独发布在 `@bankofai/x402-tron-extensions` 中，从包根及 `/trc20-approval-resource-sponsoring`（其下另有 `/client`、`/facilitator`、`/resourceService`）导出。由 resource server 在 `PaymentRequired.extensions` 中声明某个扩展；赞助类扩展与 `payment-identifier` 只在 server 声明后才生效，而 `builder-code` 的归属码由注册了它的一方自行附加，不依赖 server 声明。
 
-### TRON 授权资源赞助（1.2.0 新增）
+### TRON 授权资源赞助（1.2.0 新增，2.1.0 起为独立包）
 
 `trc20ApprovalResourceSponsoring`（协议 schema 版本 `1`）让付款方在**不持有 TRX** 的情况下完成 TRON 上的**首笔** Permit2 付款或通道存入。client 不再自行广播那笔一次性的 `approve(Permit2, MaxUint256)`，而是签名后将已签名的交易字节随付款载荷一并上传；facilitator 严格解码并将其与本次付款绑定校验，临时向付款方委托其所缺的（Stake 2.0）能量——必要时还有带宽，原封不动地广播该交易，随后通过可恢复的状态机回收委托的资源。
 
 | 角色 | 做什么 |
 |------|--------|
 | Resource server | **主动启用**——将 `declareTrc20ApprovalResourceSponsoringExtension()` 展开到路由的 `extensions` 里。该路由必须使用 `extra.assetTransferMethod: "permit2"`。 |
-| Client | **无需配置**——当 server 声明了版本 `1`、所选路径为 Permit2、且当前 Permit2 授权额度不足时，`@bankofai/x402-tron` 会自动附上已签名的授权交易。 |
-| Facilitator | **主动启用**——用 `@bankofai/x402-tron` 的 `createTrc20ResourceSponsoringRuntime({ ... })` 构造 runtime，再注册 `createTrc20ApprovalResourceSponsoringExtension(runtime)`。 |
+| Client | **主动启用**（2.1.0 起）——注册完付款 scheme 后，调用 `client.registerExtension(createTrc20ApprovalResourceSponsoringClientExtension(signer))`。当 server 声明了版本 `1`、所选路径为 Permit2、且当前 Permit2 授权额度不足时，它会附上已签名的授权交易。未注册时，受赞助的付款会报 `trc20_approval_client_extension_not_registered`。 |
+| Facilitator | **主动启用**——用 `createTrc20ResourceSponsoringRuntime({ ... })` 构造 runtime，再注册 `createTrc20ApprovalResourceSponsoringExtension(runtime)`，两者均来自 `@bankofai/x402-tron-extensions`。facilitator 缺少 runtime 时返回 `sponsor_runtime_unavailable`。 |
 
 适用于 TRON 的 `exact`（`assetTransferMethod: "permit2"`）、TRON 的 `upto`，以及 `batch-settlement` 的 Permit2 **存入/补充**路径；不用于 EIP-3009 转账，也不用于批量结算的凭证、claim、settle 与退款路径。它只赞助那一笔 `approve` 交易——付款金额、收款方、nonce、截止时间仍然只由 scheme 载荷决定，且这笔 `approve` 内部不会向用户收取任何费用。也没有新增接口：流程仍为 `402 Payment Required` → `PAYMENT-SIGNATURE` → `/verify` → `/settle`。
 
 ```typescript
-import { declareTrc20ApprovalResourceSponsoringExtension } from "@bankofai/x402-extensions";
-
-const route = {
-  price: {
-    amount: "1000000",
-    asset: "T...",
-    extra: { assetTransferMethod: "permit2" },
-  },
-  extensions: {
-    ...declareTrc20ApprovalResourceSponsoringExtension(),
+import type { RoutesConfig } from "@x402/core/http";
+import { TRON_NILE } from "@bankofai/x402-tron";
+import { declareTrc20ApprovalResourceSponsoringExtension } from "@bankofai/x402-tron-extensions";
+
+const routes: RoutesConfig = {
+  "GET /weather": {
+    accepts: [
+      {
+        scheme: "exact",
+        network: TRON_NILE,
+        payTo: "T...",
+        price: {
+          amount: "1000000",
+          asset: "T...",
+          extra: { assetTransferMethod: "permit2" },
+        },
+      },
+    ],
+    extensions: {
+      ...declareTrc20ApprovalResourceSponsoringExtension(),
+    },
   },
 };
 ```
@@ -131,23 +143,22 @@ const route = {
 - 付款方必须是**已激活的单签名 TRON 外部账户（EOA）**，且使用默认的 owner 权限；不支持多签与自定义权限账户。
 - 在默认的 `zero-first` 授权策略下，**非零但不足**的授权额度会直接报 `approval_reset_required`——SDK 不会自动插入一笔 `approve(0)`。不属于已知 Permit2 资产的代币会报 `approval_asset_unsupported`，除非你用 `createTrc20ApprovalPolicy` 为它配置策略。
 - 生产环境的 facilitator 必须为 runtime 配备持久化的操作协调器，并在启动时及定时运行对账；导出的 `InMemoryTrc20SponsoringCoordinator` 仅用于测试和单进程开发。
-- [官方 facilitator](./core-concepts/OfficialFacilitator.md) 目前**未**启用该扩展；TRON 授权赞助需要自建 facilitator，并准备一个有 Stake 2.0 资源量的资源持有钱包。
+- [官方 facilitator](./core-concepts/OfficialFacilitator.md) 已在 `/supported` 中声明该扩展，但其生产配置**只赞助 TRON Nile 上的 USDT**，且需要 API Key。要在 TRON 主网或为其他代币赞助，需要自建 facilitator，并准备一个有 Stake 2.0 资源量的资源持有钱包。
 :::
 
 ---
 
 ## Signer
 
-密钥托管在 [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wallet) 中；SDK 从不接触原始私钥。signer 工厂内部构建链 client（viem / TronWeb）。
+`@bankofai/x402-tron` 中的 TRON signer 工厂对钱包（例如由 [`@bankofai/agent-wallet`](https://github.com/BofAI/agent-wallet) 解析出的钱包）做适配，SDK 从不接触原始私钥；TronWeb 由工厂在内部构建。
 
 | signer 工厂 | 角色 |
 |----------|------|
 | `createClientTronSigner` | Client（TRON） |
-| `createClientEvmSigner` | Client（EVM） |
 | `createFacilitatorTronSigner` | Facilitator（TRON） |
-| `createFacilitatorEvmSigner` | Facilitator（EVM） |
 | `createAuthorizerTronSigner` | Authorizer（TRON，batch-settlement） |
-| `createAuthorizerEvmSigner` | Authorizer（EVM，batch-settlement） |
+
+EVM 签名使用官方 `@x402/evm` 的公开 signer 适配器（例如 `toClientEvmSigner`、`toFacilitatorEvmSigner`）。原 `@bankofai/x402-evm` 的 agent-wallet 工厂（`createClientEvmSigner`、`createFacilitatorEvmSigner`、`createAuthorizerEvmSigner`）已在 2.1.0 中退役，请参考[上游 EVM 示例](https://github.com/x402-foundation/x402/tree/main/examples/typescript)。
 
 ---
 
@@ -181,7 +192,7 @@ const route = {
 | 受保护路由集成 | ✅（`paymentMiddlewareFromHTTPServer`、`x402HTTPResourceServer`） |
 | 多链 `accepts` 公布 | ✅ |
 | EVM gas 赞助扩展（`eip2612GasSponsoring` / `erc20ApprovalGasSponsoring`） | ✅ |
-| TRON 资源赞助扩展（`trc20ApprovalResourceSponsoring`） | ✅ —— 1.2.0 新增；用 `declareTrc20ApprovalResourceSponsoringExtension()` 声明 |
+| TRON 资源赞助扩展（`trc20ApprovalResourceSponsoring`） | ✅ —— 1.2.0 新增；用 `@bankofai/x402-tron-extensions` 的 `declareTrc20ApprovalResourceSponsoringExtension()` 声明 |
 | 付款验证（通过 facilitator） | ✅ |
 | 付款结算（通过 facilitator） | ✅ |
 
@@ -198,10 +209,13 @@ const route = {
 | 确认交易（回执轮询） | ✅ |
 | 扩展钩子（`onBeforeSettle` / `onAfterSettle` / `onSettleFailure`） | ✅ |
 | EVM 智能账户——已部署账户、ERC-7702 委托、ERC-6492 反事实钱包 | ✅ —— 签名验证在 facilitator 侧；ERC-6492 需显式配置 `eip6492AllowedFactories` 白名单 |
+| 待确认结算（`settlement_pending`） | ✅ —— 2.0.0 新增。交易已广播但回执尚未确定时，结算返回非终态的 `settlement_pending` 并保留原交易 ID；应对账该交易，而不是重新提交。TRON 回执等待默认 90 秒（`createFacilitatorTronSigner` 的 `confirmationTimeoutMs`） |
+| 待确认结算恢复（TRON） | ✅ —— 2.1.0 新增。TRON facilitator 各 scheme 在等待回执前先保存原交易 ID（或 GasFree 中继 trace），同一笔付款重试时会续接该交易，而不会再次广播。默认的 `InMemoryTronPendingSettlementStore` 只覆盖单个进程；需要重启恢复或多副本部署时，通过构造参数 `pendingSettlementStore` 注入持久化、可共享的 `TronPendingSettlementStore`。广播后保存失败返回 `settlement_store_unavailable`（保留已知交易 ID）；结算回调未处理的异常返回 `settlement_execution_failed` |
+| `upto` 预检读取（TRON） | ✅ —— 2.1.0 新增。授权额度/余额读取失败或返回格式异常时，在广播任何结算交易之前返回 `chain_read_failed` |
 
 > 自托管示例 facilitator（`facilitator/basic`）暴露 `/verify`、`/settle`、`/supported`。官方托管 facilitator 额外提供结算记录查询 `GET /payments/tx/{tx_hash}` 与 `GET /payments`，以及 `/health`——详见[官方 Facilitator](./core-concepts/OfficialFacilitator.md)。Prometheus 指标在独立的监控端口上（发布配置中为 `9001`），不在对外 API 端口。没有 `/fee/quote` 端点：SDK 的各方案不收取 facilitator 费用。
 >
-> 1.1.0 起，`HTTPFacilitatorClient` 使用带类型的超时错误，默认超时 90 秒。其限流重试（3 次）只作用于 `getSupported()`——`verify()` 与 `settle()` 遇到 429 会直接抛给调用方，不会重试。
+> 2.1.0 起，`HTTPFacilitatorClient` 来自官方 `@x402/core` `2.28.0`：使用带类型的超时错误，默认超时为 90 秒；仓库示例显式设置了 `timeoutMs: 120_000`。切换到官方 HTTP/MCP 包后，请重新核对请求超时设置。其限流重试（3 次）只作用于 `getSupported()`——`verify()` 与 `settle()` 遇到 429 会直接抛给调用方，不会重试。
 
 ---
 
@@ -211,24 +225,23 @@ const route = {
 |--------|---------|--------|
 | USDT（TRC-20） | `tron:728126428`、`tron:3448148188`、`tron:2494104990` | ✅ |
 | USDD（TRC-20） | `tron:728126428`、`tron:3448148188` | ✅ |
-| USDT（BEP-20） | `eip155:56`、`eip155:97` | ✅ |
-| USDC（BEP-20） | `eip155:56`、`eip155:97` | ✅ |
-| DHLU（BSC 测试网，ERC-3009） | `eip155:97` | ✅ |
+| USDT（BEP-20） | `eip155:56`、`eip155:97` | ✅（显式资产） |
+| USDC（BEP-20） | `eip155:56`、`eip155:97` | ✅（显式资产；`eip155:56` 的地址不在任何内置代币注册表中） |
 | 官方 USDC（ERC-20，EIP-3009） | `eip155:8453`、`eip155:84532` | ✅ |
-| 自定义 TRC-20 / BEP-20 | 任意 | ✅（通过代币注册表 / `EVM_TOKENS` 配置） |
+| 自定义 TRC-20 / BEP-20 | 任意 | ✅（通过 TRON 代币注册表 / 显式的 `{ asset, amount, extra }` 价格） |
 
-> 其中只有一部分是**默认资产**：TRON 与 BSC 主网上的 USDT、BSC 测试网与 Base 上的 USDC。1.1.0 起，客户端消费管控会拒绝其余资产——USDD、BSC 主网 USDC、BSC 测试网 USDT、DHLU、自定义代币——除非通过 `spendControls.allowedAssets` 放行。详见[网络与代币支持](./core-concepts/network-and-token-support.md#supported-tokens)。
+> 其中只有一部分是**默认资产**：TRON 三个网络上的 USDT，以及 Base 与 Base Sepolia 上的 USDC。1.1.0 起，客户端消费管控会拒绝其余资产——USDD、所有 BSC 资产、自定义代币——除非通过 `spendControls.allowedAssets` 放行。详见[网络与代币支持](./core-concepts/network-and-token-support.md#supported-tokens)。
 
 ---
 
 ## 可观测性
 
-所有 `@bankofai/x402-*` 包通过 `@bankofai/x402-core` 的一个进程级 logger 输出日志。启动时调用一次 `setLogger(...)` 即可将日志重定向到文件、`pino`/`winston`，或用 `noopLogger` 静默。
+TRON 机制通过 `@bankofai/x402-tron` 导出的进程级 logger 输出日志（2.1.0 起；此前来自 `@bankofai/x402-core`）。启动时调用一次 `setLogger(...)` 即可将日志重定向到文件、`pino`/`winston`，或用 `noopLogger` 静默。官方 `@x402/core` 与 `@x402/extensions` 不使用该 logger——需要记录它们的事件时，请注册生命周期钩子。
 
 ---
 
 ## 图例
 
 - ✅ = 已实现
-- ⏳ = 计划中 / 进行中
-- ❌ = 不计划
+- ⚠️ = 部分实现（见说明列）
+- ❌ = 不支持
diff --git a/static/img/diagrams/x402-api-catalog-pipeline.light.svg b/static/img/diagrams/x402-api-catalog-pipeline.light.svg
index 2504efa6..a9070f95 100644
--- a/static/img/diagrams/x402-api-catalog-pipeline.light.svg
+++ b/static/img/diagrams/x402-api-catalog-pipeline.light.svg
@@ -60,11 +60,11 @@
   <line x1="439.5" y1="240" x2="439.5" y2="280" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="#ffffff"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="#f8fafc" stroke="#64748b" stroke-width="1.5"/>
-  <text x="439.5" y="309" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">x402-cli</text>
+  <text x="439.5" y="309" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">wallet-cli</text>
   <text x="439.5" y="328" fill="#64748b" font-size="10" text-anchor="middle">search, inspect, paid calls</text>
   <line x1="726.5" y1="240" x2="726.5" y2="280" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="#ffffff"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="#f8fafc" stroke="#64748b" stroke-width="1.5"/>
   <text x="726.5" y="309" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">MCP</text>
-  <text x="726.5" y="328" fill="#64748b" font-size="10" text-anchor="middle">Agents call services by name</text>
+  <text x="726.5" y="328" fill="#64748b" font-size="10" text-anchor="middle">Pays endpoints; no catalog lookup yet</text>
 </svg>
diff --git a/static/img/diagrams/x402-api-catalog-pipeline.svg b/static/img/diagrams/x402-api-catalog-pipeline.svg
index ec765829..2534bdb0 100644
--- a/static/img/diagrams/x402-api-catalog-pipeline.svg
+++ b/static/img/diagrams/x402-api-catalog-pipeline.svg
@@ -60,11 +60,11 @@
   <line x1="439.5" y1="240" x2="439.5" y2="280" stroke="#64748b" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="#0f172a"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
-  <text x="439.5" y="309" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">x402-cli</text>
+  <text x="439.5" y="309" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">wallet-cli</text>
   <text x="439.5" y="328" fill="#94a3b8" font-size="10" text-anchor="middle">search, inspect, paid calls</text>
   <line x1="726.5" y1="240" x2="726.5" y2="280" stroke="#64748b" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="#0f172a"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
   <text x="726.5" y="309" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">MCP</text>
-  <text x="726.5" y="328" fill="#94a3b8" font-size="10" text-anchor="middle">Agents call services by name</text>
+  <text x="726.5" y="328" fill="#94a3b8" font-size="10" text-anchor="middle">Pays endpoints; no catalog lookup yet</text>
 </svg>
diff --git a/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg b/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg
index 0d0941c9..3cccaa65 100644
--- a/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg
+++ b/static/img/diagrams/x402-api-catalog-pipeline.zh.light.svg
@@ -60,11 +60,11 @@
   <line x1="439.5" y1="240" x2="439.5" y2="280" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="#ffffff"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="#f8fafc" stroke="#64748b" stroke-width="1.5"/>
-  <text x="439.5" y="309" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">x402-cli</text>
+  <text x="439.5" y="309" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">wallet-cli</text>
   <text x="439.5" y="328" fill="#64748b" font-size="10" text-anchor="middle">搜索、查看、付费调用</text>
   <line x1="726.5" y1="240" x2="726.5" y2="280" stroke="#94a3b8" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="#ffffff"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="#f8fafc" stroke="#64748b" stroke-width="1.5"/>
   <text x="726.5" y="309" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">MCP</text>
-  <text x="726.5" y="328" fill="#64748b" font-size="10" text-anchor="middle">Agent 按名字直接调用</text>
+  <text x="726.5" y="328" fill="#64748b" font-size="10" text-anchor="middle">仅付费调用 · 暂不支持按目录查找</text>
 </svg>
diff --git a/static/img/diagrams/x402-api-catalog-pipeline.zh.svg b/static/img/diagrams/x402-api-catalog-pipeline.zh.svg
index 258ba913..413c525e 100644
--- a/static/img/diagrams/x402-api-catalog-pipeline.zh.svg
+++ b/static/img/diagrams/x402-api-catalog-pipeline.zh.svg
@@ -60,11 +60,11 @@
   <line x1="439.5" y1="240" x2="439.5" y2="280" stroke="#64748b" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="#0f172a"/>
   <rect x="327" y="284" width="225" height="58" rx="8" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
-  <text x="439.5" y="309" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">x402-cli</text>
+  <text x="439.5" y="309" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">wallet-cli</text>
   <text x="439.5" y="328" fill="#94a3b8" font-size="10" text-anchor="middle">搜索、查看、付费调用</text>
   <line x1="726.5" y1="240" x2="726.5" y2="280" stroke="#64748b" stroke-width="1.5" marker-end="url(#ah-slate)"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="#0f172a"/>
   <rect x="614" y="284" width="225" height="58" rx="8" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
   <text x="726.5" y="309" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">MCP</text>
-  <text x="726.5" y="328" fill="#94a3b8" font-size="10" text-anchor="middle">Agent 按名字直接调用</text>
+  <text x="726.5" y="328" fill="#94a3b8" font-size="10" text-anchor="middle">仅付费调用 · 暂不支持按目录查找</text>
 </svg>
diff --git a/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg b/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg
index fe509bcc..9e66bcdc 100644
--- a/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg
+++ b/static/img/diagrams/x402-payment-scheme-flow.zh.light.svg
@@ -47,7 +47,7 @@
   <rect x="170" y="278" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="278" width="540" height="55" rx="8" fill="#fffbeb" stroke="#d97706" stroke-width="1.5"/>
   <text x="440.0" y="303" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">结算 Settle</text>
-  <text x="440.0" y="322" fill="#64748b" font-size="10" text-anchor="middle">transferWithAuthorization · Permit2 · 批量领取 · GasFree 中继</text>
+  <text x="440.0" y="322" fill="#64748b" font-size="10" text-anchor="middle">transferWithAuthorization · Permit2 permitTransferFrom · 批量领取 · GasFree 中继</text>
   <circle cx="150" cy="298" r="13" fill="#ffffff" stroke="#d97706" stroke-width="1.5"/>
   <text x="150" y="302" fill="#0f172a" font-size="11" font-weight="700" text-anchor="middle">3</text>
   <text x="724" y="302" fill="#d97706" font-size="10" font-weight="600">FACILITATOR</text>
diff --git a/static/img/diagrams/x402-payment-scheme-flow.zh.svg b/static/img/diagrams/x402-payment-scheme-flow.zh.svg
index ef7d242c..63aa056c 100644
--- a/static/img/diagrams/x402-payment-scheme-flow.zh.svg
+++ b/static/img/diagrams/x402-payment-scheme-flow.zh.svg
@@ -47,7 +47,7 @@
   <rect x="170" y="278" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="278" width="540" height="55" rx="8" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
   <text x="440.0" y="303" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">结算 Settle</text>
-  <text x="440.0" y="322" fill="#94a3b8" font-size="10" text-anchor="middle">transferWithAuthorization · Permit2 · 批量领取 · GasFree 中继</text>
+  <text x="440.0" y="322" fill="#94a3b8" font-size="10" text-anchor="middle">transferWithAuthorization · Permit2 permitTransferFrom · 批量领取 · GasFree 中继</text>
   <circle cx="150" cy="298" r="13" fill="#1e293b" stroke="#fbbf24" stroke-width="1.5"/>
   <text x="150" y="302" fill="#f8fafc" font-size="11" font-weight="700" text-anchor="middle">3</text>
   <text x="724" y="302" fill="#fbbf24" font-size="10" font-weight="600">FACILITATOR</text>

From a9cc212f6fa476e80f75cf49ac92e812b2a4e45c Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:01 +0800
Subject: [PATCH 02/13] docs(wallet-cli): document 4.15.1 behaviour

- Common error-code table with exit codes.
- Spend cap, --dry-run, route filters and paymentStatus details.
- B.AI recharge: routes, token default, minimums and check order.
- Skills pin 4.14.0; Node.js security baselines.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/BANK-OF-AI/QuickStart.md                 |  2 +-
 docs/wallet-cli/command-reference.md          | 28 +++++++++++++++----
 docs/wallet-cli/index.md                      |  2 +-
 docs/wallet-cli/quickstart.md                 | 10 ++++---
 .../current/BANK-OF-AI/QuickStart.md          |  2 +-
 .../current/wallet-cli/command-reference.md   | 28 +++++++++++++++----
 .../current/wallet-cli/index.md               |  2 +-
 .../current/wallet-cli/quickstart.md          | 10 ++++---
 8 files changed, 62 insertions(+), 22 deletions(-)

diff --git a/docs/BANK-OF-AI/QuickStart.md b/docs/BANK-OF-AI/QuickStart.md
index d6a66b23..1be0f452 100644
--- a/docs/BANK-OF-AI/QuickStart.md
+++ b/docs/BANK-OF-AI/QuickStart.md
@@ -15,7 +15,7 @@ Choose an entry point for your task:
 | Recharge B.AI | [wallet-cli recharge guidance](/wallet-cli/command-reference/) |
 | DeFi workflows and data queries | [Skill catalog](/McpServer-Skills/SKILLS/BANKOFAISkill/) |
 
-Installation requires Node.js 20 or newer and an agent that supports local Skills. Select only the Skills you need. Installing a Skill does not install its external CLI or configure a wallet; match its dependency version to the installed CLI.
+Installation requires Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ and an agent that supports local Skills. Select only the Skills you need. Installing a Skill does not install its external CLI or configure a wallet; match its dependency version to the installed CLI.
 
 Complete wallet setup locally. Never send a private key, mnemonic, or master password to an AI. Before paying, check the network, address, token, amount, and fees.
 
diff --git a/docs/wallet-cli/command-reference.md b/docs/wallet-cli/command-reference.md
index 12833ff9..7f705e87 100644
--- a/docs/wallet-cli/command-reference.md
+++ b/docs/wallet-cli/command-reference.md
@@ -6,7 +6,7 @@ description: "Commands and payment options for wallet-cli."
 
 # Wallet CLI Command Reference
 
-This reference targets the published **4.14.0** package. Use schema discovery to inspect command parameters.
+This reference targets the published **4.15.1** package. Use schema discovery to inspect command parameters.
 
 ```bash
 wallet-cli --json-schema -o json
@@ -19,21 +19,39 @@ wallet-cli bai recharge --json-schema -o json
 - `--network`: explicit payment network; use `tron:728126428` for TRON mainnet.
 - `--account`: wallet-cli account selection.
 - `--token` or `--asset` and `--decimals`: select an asset according to the schema.
-- `--max-amount` / `--max-raw-amount`: mutually exclusive payment caps.
+- `--max-amount` / `--max-raw-amount`: mutually exclusive payment caps. `--max-raw-amount` is in smallest units and requires `--token` or `--asset`, because a raw amount has no unit. Without `--max-amount` or `--max-raw-amount`, a built-in ceiling of $1 per payment applies to known stablecoins; routes priced above it are dropped before signing, and the command fails with `amount_exceeds_limit` when every offered route is above it. A `--dry-run` preview does not apply this built-in cap, so a preview can pass while the real payment still fails with `amount_exceeds_limit`.
 - `--dry-run`: read payment requirements without signing.
 - `--method`, `--header`, `--body` / `--body-file`: HTTP request options.
+- `--out <path>`: write the response body byte-for-byte to a new file instead of `data.response`; an existing file is refused before any request is sent. Binary media types (such as `application/octet-stream`, images, audio, video, PDF, and archives) require `--out`.
 - `--password-stdin`: secure master-password input for signing.
 - `-o json`: machine output.
 
 ## GasFree payments {#gasfree-payments-tron}
 
-To pay a TRON route through GasFree, pass `--scheme exact_gasfree` and cap `--max-gasfree-fee`. Without `--scheme`, the first matching route the server offers is used, which can be a GasFree route; pass `--scheme exact` to rule that out. Use `--gasfree-relay` to select the relay service. The payment amount cap does not include the GasFree fee.
+To pay a TRON route through GasFree, pass `--scheme exact_gasfree` and cap the fee with `--max-gasfree-fee` (or `--max-gasfree-fee-raw` in smallest units). Without `--scheme`, the first matching route the server offers is used, which can be a GasFree route; pass `--scheme exact` to rule that out. Use `--gasfree-relay` to select the relay service. The payment amount cap does not include the GasFree fee.
 
 ## Result handling
 
 Operations return `wallet-cli.result.v1` with `success`, `command`, and `data` or `error`. Exit `0` means command success, `1` execution failure, and `2` invalid invocation. Schema discovery returns a command catalog or input schema rather than an operation envelope.
 
-The paid response is in `data.response`. On failure inspect `error.details.paymentStatus` and `retryPayment`. `not_sent` means no payment was sent; `unknown` means the outcome cannot be established. Reconcile the existing transaction rather than paying again when `retryPayment: false` is returned.
+The paid response is in `data.response`. On failure inspect `error.details.paymentStatus` and `retryPayment`. `not_sent` means no payment was sent; `unknown` means the outcome cannot be established. Reconcile the existing transaction rather than paying again when `retryPayment: false` is returned. A response format error can also occur after the payment has settled; `error.details` then keeps `paymentStatus: "settled"`, the transaction hash, and `retryPayment: false`, so reconcile with the provider instead of paying again. A successful paid result reports what was paid in `data.payment`.
+
+### Common error codes
+
+| Code | Exit | When |
+| --- | --- | --- |
+| `missing_wallet_address` | 1 | No wallet-cli account is configured (also for `--dry-run`) |
+| `auth_required` | 1 | A real payment was attempted without `--password-stdin` |
+| `invalid_option` | 2 | `--max-raw-amount` without `--token` / `--asset`, a binary response without `--out`, or mutually exclusive flags |
+| `output_exists` | 2 | The `--out` file already exists; nothing was sent |
+| `no_matching_requirement` | 1 | No route matched `--network` / `--token` / `--asset` / `--scheme`, or, without `--max-amount` / `--max-raw-amount`, no route uses an asset the built-in spend control allows; `paymentStatus: "not_sent"` |
+| `amount_exceeds_limit` | 1 | The route's price is above `--max-amount`, `--max-raw-amount` or the built-in $1 cap; `not_sent` |
+| `permit2_allowance_required` | 1 | Permit2 allowance missing on an unsponsored route |
+| `gasfree_insufficient_balance` / `fee_cap_exceeded` | 1 | GasFree balance or `--max-gasfree-fee` too low |
+| `provider_error` / `provider_rate_limited` | 1 | The endpoint or facilitator failed or returned 429 (`error.details.retryAfterSeconds` when sent) |
+| `invalid_x402_response` | 1 | The paid response could not be decoded; may carry `paymentStatus: "settled"` |
+
+`paymentStatus` appears in `error.details` only for real payments; a `--dry-run` failure carries no `error.details`.
 
 ## B.AI recharge
 
@@ -42,6 +60,6 @@ wallet-cli bai recharge 1 --network tron:728126428 --token USDT --dry-run -o jso
 wallet-cli bai recharge-orders --json-schema -o json
 ```
 
-Requires a wallet-cli account and a stored B.AI API key. Recharge supports the configured mainnet routes only. A preview creates no order, binds no wallet, and makes no payment. A real recharge may first bind the paying address, which must be within the authorized operation. `creditStatus: "unconfirmed"` is not a failed payment: use `bai report-recharge` for the original transaction instead of paying again.
+Requires a wallet-cli account and a stored B.AI API key; without the key every `bai` command, including a preview, exits `2` with `bai_credentials_missing` (after the amount and network checks). Recharge supports the configured mainnet routes only: TRON USDT / USDD, BSC USDT and Base USDC. `--to` takes a B.AI account email or an EVM / TRON / Solana address; omit it to recharge your own account. `--token` defaults to USDC on Base and USDT elsewhere. The minimum is 1 USDT / USDC (USDD has none) — below that the command fails with `invalid_amount`. A preview creates no order, binds no wallet, and makes no payment. A real recharge may first bind the paying address, which must be within the authorized operation. `creditStatus: "unconfirmed"` is not a failed payment: use `bai report-recharge` for the original transaction instead of paying again.
 
 [Quick start](/wallet-cli/quickstart/) · [FAQ](/wallet-cli/faq/)
diff --git a/docs/wallet-cli/index.md b/docs/wallet-cli/index.md
index 8e26c43b..34dce2b5 100644
--- a/docs/wallet-cli/index.md
+++ b/docs/wallet-cli/index.md
@@ -5,7 +5,7 @@ description: "Use wallet-cli for payments and service discovery."
 
 # Wallet CLI and x402
 
-Use **`@tron-walletcli/wallet-cli@4.14.0`** for new command-line integrations.
+Use **`@tron-walletcli/wallet-cli@4.15.1`** for new command-line integrations.
 
 | Task | Entry point |
 | --- | --- |
diff --git a/docs/wallet-cli/quickstart.md b/docs/wallet-cli/quickstart.md
index d4472ee3..98be7010 100644
--- a/docs/wallet-cli/quickstart.md
+++ b/docs/wallet-cli/quickstart.md
@@ -6,21 +6,23 @@ description: "Install wallet-cli and preview an x402 payment."
 
 # Wallet CLI Quick Start
 
-Requires Node.js 20 or newer.
+Requires Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+.
 
 ## Install and inspect
 
 ```bash
-npm install -g @tron-walletcli/wallet-cli@4.14.0
+npm install -g @tron-walletcli/wallet-cli@4.15.1
 wallet-cli --version
 wallet-cli x402 pay --json-schema -o json
 ```
 
+If you will use the wallet-cli Skill, install the version that Skill pins instead (currently 4.14.0) — see the [Skills quick start](/McpServer-Skills/SKILLS/QuickStart/).
+
 :::tip Permission error on install?
 If `npm install -g` fails with a permission error (such as `EACCES`) on macOS or Linux, see npm's official guide: [Resolving EACCES permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
 :::
 
-In 4.14.0, help, version, and schema discovery do not read wallet data. A first operational command may return `command: "migration"`: only the migration ran, so inspect its result before invoking the original command again.
+Since 4.14.0, help, version, and schema discovery do not read wallet data. A first operational command may return `command: "migration"`: only the migration ran, so inspect its result before invoking the original command again.
 
 ## Prepare an account
 
@@ -55,7 +57,7 @@ wallet-cli x402 pay https://x402-gateway.bankofai.io/providers/dia-price-tron/v1
   --dry-run -o json
 ```
 
-Before paying, confirm the network, recipient, amount, and fees. Remove `--dry-run` only for the authorized payment, and supply the master password through `--password-stdin` from an approved secure source, never a password argument. Cap GasFree fees separately with `--max-gasfree-fee`.
+Before paying, confirm the network, recipient, amount, and fees. Remove `--dry-run` only for the authorized payment, and supply the master password through `--password-stdin` from an approved secure source, never a password argument. Cap GasFree fees separately with `--max-gasfree-fee`. On TRON, a first `exact` payment in a token may broadcast `approve(Permit2, MaxUint256)` from the account before paying, unless the endpoint sponsors the approval: it burns the account's Energy or TRX and leaves an unlimited Permit2 allowance on that token. The result reports it in `data.approval`.
 
 After an uncertain result, reconcile the transaction and inspect `error.details.paymentStatus`. Do not pay again when `retryPayment: false` is returned.
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md
index c718c34b..65debe64 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/BANK-OF-AI/QuickStart.md
@@ -15,7 +15,7 @@ description: "选择 BANK OF AI Skills，使用 wallet-cli 配置钱包与支付
 | 充值 B.AI | [wallet-cli 充值说明](/zh-Hans/wallet-cli/command-reference/) |
 | DeFi 业务与数据查询 | [Skill 列表](/zh-Hans/McpServer-Skills/SKILLS/BANKOFAISkill/) |
 
-安装需要 Node.js 20 或更新版本，以及支持本地 Skills 的 Agent。按需选择 Skill；Skill 安装不会自动安装外部 CLI，也不会自动配置钱包。检查 Skill 依赖版本与实际 CLI 一致。
+安装需要 Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+，以及支持本地 Skills 的 Agent。按需选择 Skill；Skill 安装不会自动安装外部 CLI，也不会自动配置钱包。检查 Skill 依赖版本与实际 CLI 一致。
 
 首次配置钱包在本地完成。不要把私钥、助记词或主密码发给 AI；支付前核对网络、地址、币种、金额与手续费。
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/command-reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/command-reference.md
index 23fe905c..32ef0d43 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/command-reference.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/command-reference.md
@@ -6,7 +6,7 @@ description: "wallet-cli 命令与支付参数。"
 
 # Wallet CLI 命令参考
 
-以 **4.14.0** 发布包为准。通过命令 schema 查询可用参数。
+以 **4.15.1** 发布包为准。通过命令 schema 查询可用参数。
 
 ```bash
 wallet-cli --json-schema -o json
@@ -19,21 +19,39 @@ wallet-cli bai recharge --json-schema -o json
 - `--network`：指定支付网络；TRON 主网使用 `tron:728126428`。
 - `--account`：选择 wallet-cli 账户。
 - `--token` 或 `--asset`、`--decimals`：按 schema 指定支付资产。
-- `--max-amount` / `--max-raw-amount`：二选一，限制支付数量。
+- `--max-amount` / `--max-raw-amount`：二选一，限制支付数量。`--max-raw-amount` 以最小单位计，必须同时指定 `--token` 或 `--asset`，因为原始数量本身没有单位。`--max-amount` 和 `--max-raw-amount` 都不指定时，已知稳定币默认每笔上限 1 美元；超过该价格的路线会在签名前被排除；所有路线都超过时，命令以 `amount_exceeds_limit` 失败。`--dry-run` 预览不应用这个内置上限，所以预览能通过，实际付款仍可能以 `amount_exceeds_limit` 失败。
 - `--dry-run`：读取支付要求，不签名。
 - `--method`、`--header`、`--body` / `--body-file`：HTTP 请求配置。
+- `--out <path>`：把响应体按原始字节写入新文件，而不是放在 `data.response`；文件已存在时在发出任何请求前即拒绝。二进制媒体类型（如 `application/octet-stream`、图片、音视频、PDF、压缩包）必须使用 `--out`。
 - `--password-stdin`：实际签名所需主密码的安全输入通道。
 - `-o json`：机器输出。
 
 ## GasFree 支付 {#gasfree-payments-tron}
 
-要通过 GasFree 支付 TRON 路线，请指定 `--scheme exact_gasfree`，并用 `--max-gasfree-fee` 限制手续费。不指定 `--scheme` 时，会使用服务端给出的第一条匹配路线，这条路线可能就是 GasFree；如需排除，请指定 `--scheme exact`。使用 `--gasfree-relay` 选择服务。支付金额上限不包含 GasFree 手续费。
+要通过 GasFree 支付 TRON 路线，请指定 `--scheme exact_gasfree`，并用 `--max-gasfree-fee`（或以最小单位计的 `--max-gasfree-fee-raw`）限制手续费。不指定 `--scheme` 时，会使用服务端给出的第一条匹配路线，这条路线可能就是 GasFree；如需排除，请指定 `--scheme exact`。使用 `--gasfree-relay` 选择服务。支付金额上限不包含 GasFree 手续费。
 
 ## 结果处理
 
 操作返回 `wallet-cli.result.v1`，包含 `success`、`command`、`data` 或 `error`。退出码 `0` 表示命令成功，`1` 为执行错误，`2` 为调用错误。schema 查询返回命令目录或输入 schema，不是操作结果对象。
 
-支付读取 `data.response`；失败时查看 `error.details.paymentStatus` 和 `retryPayment`。`not_sent` 表示未发送支付，`unknown` 表示不能确定；`retryPayment: false` 时应核对已有交易，不能再次支付。
+支付读取 `data.response`；失败时查看 `error.details.paymentStatus` 和 `retryPayment`。`not_sent` 表示未发送支付，`unknown` 表示不能确定；`retryPayment: false` 时应核对已有交易，不能再次支付。响应格式错误也可能发生在付款已结算之后，此时 `error.details` 仍保留 `paymentStatus: "settled"`、交易哈希和 `retryPayment: false`，应凭交易哈希与服务方核对，不要再次付款。付款成功时，`data.payment` 会给出实际支付的资产与数量。
+
+### 常见错误码
+
+| 错误码 | 退出码 | 出现场景 |
+| --- | --- | --- |
+| `missing_wallet_address` | 1 | 没有配置 wallet-cli 账户（`--dry-run` 也需要） |
+| `auth_required` | 1 | 实际付款时没有传 `--password-stdin` |
+| `invalid_option` | 2 | `--max-raw-amount` 没带 `--token` / `--asset`、二进制响应没带 `--out`，或同时传了互斥参数 |
+| `output_exists` | 2 | `--out` 指定的文件已存在；未发出任何请求 |
+| `no_matching_requirement` | 1 | 没有路线匹配 `--network` / `--token` / `--asset` / `--scheme`，或在未传 `--max-amount` / `--max-raw-amount` 时，没有路线使用内置支出控制允许的资产；`paymentStatus: "not_sent"` |
+| `amount_exceeds_limit` | 1 | 路线价格高于 `--max-amount`、`--max-raw-amount` 或内置的 1 美元上限；`not_sent` |
+| `permit2_allowance_required` | 1 | 未代付的路线上缺少 Permit2 授权额度 |
+| `gasfree_insufficient_balance` / `fee_cap_exceeded` | 1 | GasFree 余额不足或 `--max-gasfree-fee` 过低 |
+| `provider_error` / `provider_rate_limited` | 1 | 端点或 facilitator 出错或返回 429（有则带 `error.details.retryAfterSeconds`） |
+| `invalid_x402_response` | 1 | 付费响应无法解码；可能带 `paymentStatus: "settled"` |
+
+只有实际付款时 `error.details` 里才会带 `paymentStatus`；`--dry-run` 失败时没有 `error.details`。
 
 ## B.AI 充值
 
@@ -42,6 +60,6 @@ wallet-cli bai recharge 1 --network tron:728126428 --token USDT --dry-run -o jso
 wallet-cli bai recharge-orders --json-schema -o json
 ```
 
-需要 wallet-cli 账户及已存储的 B.AI API Key。充值只支持配置中允许的主网；预览不创建订单、不绑定钱包、不付款。实际充值可能先绑定付款地址，需在授权范围内执行。`creditStatus: "unconfirmed"` 不代表付款失败，应使用 `bai report-recharge` 报告原交易，不要重新充值。
+需要 wallet-cli 账户及已存储的 B.AI API Key；没有 Key 时所有 `bai` 命令（包括预览）都会以退出码 `2` 返回 `bai_credentials_missing`（金额和网络检查之后）。充值只支持配置中允许的主网路线：TRON USDT / USDD、BSC USDT、Base USDC。`--to` 可填 B.AI 账户邮箱或 EVM / TRON / Solana 地址，省略则给自己充值；`--token` 在 Base 上默认 USDC，其他网络默认 USDT；最低金额为 1 USDT / USDC（USDD 无下限），低于下限返回 `invalid_amount`。预览不创建订单、不绑定钱包、不付款。实际充值可能先绑定付款地址，需在授权范围内执行。`creditStatus: "unconfirmed"` 不代表付款失败，应使用 `bai report-recharge` 报告原交易，不要重新充值。
 
 [快速入门](/zh-Hans/wallet-cli/quickstart/) · [常见问题](/zh-Hans/wallet-cli/faq/)
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md
index de9636cd..18056c2d 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md
@@ -5,7 +5,7 @@ description: "使用 wallet-cli 进行支付和服务发现。"
 
 # Wallet CLI 与 x402
 
-新的命令行接入使用 **`@tron-walletcli/wallet-cli@4.14.0`**。
+新的命令行接入使用 **`@tron-walletcli/wallet-cli@4.15.1`**。
 
 | 需求 | 新入口 |
 | --- | --- |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/quickstart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/quickstart.md
index 201751f3..3fd2b0e0 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/quickstart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/quickstart.md
@@ -6,21 +6,23 @@ description: "安装 wallet-cli 并预览 x402 支付。"
 
 # Wallet CLI 快速入门
 
-需要 Node.js 20 或更新版本。
+需要 Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+。
 
 ## 安装和检查
 
 ```bash
-npm install -g @tron-walletcli/wallet-cli@4.14.0
+npm install -g @tron-walletcli/wallet-cli@4.15.1
 wallet-cli --version
 wallet-cli x402 pay --json-schema -o json
 ```
 
+如果要配合 wallet-cli Skill 使用，请改装该 Skill 锁定的版本（目前是 4.14.0），见 [Skills 快速入门](/zh-Hans/McpServer-Skills/SKILLS/QuickStart/)。
+
 :::tip 安装时报权限错误？
 在 macOS 或 Linux 上，如果 `npm install -g` 报权限错误（如 `EACCES`），请参考 npm 官方文档：[Resolving EACCES permissions errors when installing packages globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)。
 :::
 
-4.14.0 的帮助、版本和 schema 查询不读取钱包数据。首次执行其他命令可能返回 `command: "migration"`；这表示只完成了迁移，原命令尚未执行，需检查结果后再运行。
+从 4.14.0 起，帮助、版本和 schema 查询不读取钱包数据。首次执行其他命令可能返回 `command: "migration"`；这表示只完成了迁移，原命令尚未执行，需检查结果后再运行。
 
 ## 准备钱包
 
@@ -55,7 +57,7 @@ wallet-cli x402 pay https://x402-gateway.bankofai.io/providers/dia-price-tron/v1
   --dry-run -o json
 ```
 
-确认网络、收款地址、金额和费用后才能付款。实际付款去掉 `--dry-run`，使用 `--password-stdin` 从已授权的安全来源输入主密码；不要把密码放到命令行参数中。GasFree 需要单独限制 `--max-gasfree-fee`。
+确认网络、收款地址、金额和费用后才能付款。实际付款去掉 `--dry-run`，使用 `--password-stdin` 从已授权的安全来源输入主密码；不要把密码放到命令行参数中。GasFree 需要单独限制 `--max-gasfree-fee`。在 TRON 上，某个代币的首次 `exact` 付款可能会先从账户广播 `approve(Permit2, MaxUint256)`（端点代付授权时除外）：这会消耗账户自己的 Energy 或 TRX，并给 Permit2 留下该代币的无限额度授权。结果会在 `data.approval` 中说明。
 
 支付结果不确定时先检查交易和 `error.details.paymentStatus`；出现 `retryPayment: false` 时不要重新付款。
 

From c108988ed77a0fdab261b5a1d8cd5caad065935c Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:01 +0800
Subject: [PATCH 03/13] docs(8004): align with SDK 1.2.1 and registry contracts

- Subgraph defaults per language, aliases (bsc/evm resolve to 97 without chainId 56), feeLimit and embeddings.
- New Common Contract Errors section, by contract function.
- getAgent/loadAgent/registerIPFS behaviour without a subgraph or uploader.
- agentWallet is cleared on transfer; Quick Start sample notes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 changelog/8004.md                             | 38 +++++++++
 docs/8004/QuickStart.md                       |  3 +
 docs/8004/SupportedNetworks.md                |  8 +-
 docs/8004/Usage/ConfigureAgents.md            | 84 ++++++++++++-------
 docs/8004/Usage/Install.md                    |  8 +-
 docs/8004/Usage/RegistrationHTTP.md           |  7 +-
 docs/8004/contract.md                         |  8 ++
 docs/8004/general.md                          |  2 +-
 docs/8004/sdk-features.md                     | 60 ++++++++-----
 .../current/8004.md                           | 38 +++++++++
 .../current/8004/QuickStart.md                |  7 +-
 .../current/8004/SupportedNetworks.md         |  8 +-
 .../current/8004/Usage/ConfigureAgents.md     | 81 +++++++++++-------
 .../current/8004/Usage/Install.md             |  8 +-
 .../current/8004/Usage/RegistrationHTTP.md    |  7 +-
 .../current/8004/contract.md                  | 10 ++-
 .../current/8004/general.md                   |  2 +-
 .../current/8004/sdk-features.md              | 60 ++++++++-----
 18 files changed, 313 insertions(+), 126 deletions(-)

diff --git a/changelog/8004.md b/changelog/8004.md
index 5317a1f6..4bf01d80 100644
--- a/changelog/8004.md
+++ b/changelog/8004.md
@@ -7,6 +7,44 @@ description: 'Release notes for the 8004 Protocol.'
 
 Release notes for the 8004 Protocol.
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Subgraph defaults, aliases and contract errors
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **Subgraph** — the Python SDK ships default subgraph URLs for Base Mainnet and Base Sepolia (TypeScript ships none; BSC has none in either), so the pages no longer say a subgraph always has to be deployed by you.
+- **Config and aliases** — Python-only `embeddings`; `feeLimit` defaults (120,000,000 SUN in TypeScript, 10,000,000 in Python); TypeScript's `bsc` / `bsc:mainnet` / `evm` aliases, all of which resolve to BSC Testnet unless `chainId: 56` is passed; the TypeScript IPFS prerequisite is an `ipfsUploader` callback, and Python RPC endpoints include Base.
+- **New: Common Contract Errors** — the registry revert reasons a reader hits through the documented flows (`Not authorized`, `reserved key`, `expired`, `invalid wallet sig`, `Self-feedback not allowed`, …) with their causes.
+
+👉 [Configure Agents](/8004/Usage/ConfigureAgents/) · [SDK Feature Matrix](/8004/sdk-features/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 23, 2026</div>
+<div className="changelog-body">
+
+### Docs aligned with 8004 SDK 1.2.1
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **Release** — the feature matrix names `@bankofai/8004-sdk` 1.2.1 (the Python package is still not on PyPI). The TypeScript SDK needs Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x).
+- **Base networks** — Base Mainnet and Base Sepolia, with their official ERC-8004 registry addresses, are documented (all three registries in TypeScript; Identity and Reputation only in Python, via `eip155:8453` / `eip155:84532`). TRON agent IDs use the network's chain ID as prefix (for example `3448148188:<tokenId>` on Nile).
+- **Registration files** — since 1.2.0, `registerIPFS()` publishes the canonical registration-v1 keys (`services`, `x402Support`, `registrations`) and uses the TRC-8004 `type` on TRON. TypeScript `toJSON()` still returns the internal names, so map them before hosting the file yourself. This updates the Sep 9 note.
+- **Feature matrix** — adds the TypeScript registry read APIs, the new `register()` overloads, and per-agent approvals; reading an agent's owner is now supported in both languages. The TypeScript `updateRegistration` sample now type-checks under `strict`.
+- **On-chain metadata sample** — the TypeScript sample called `agent.register()`, which always mints a new agent; it now uses `updateOnChainMetadata()`. The Python sample now writes staged keys through `registerIPFS()`, since on a registered agent `register(uri)` and `updateRegistration()` only update the URI.
+- **BSC network names** — the network table listed BSC as `mainnet` / `testnet`, but a bare `mainnet` resolves to TRON and TypeScript rejects `testnet`. BSC is now given as `eip155:56` / `eip155:97`.
+- **Indexing and IPFS** — Python `refreshIndex()` / `refreshAgentIndex()` are marked as not working in 1.2.1 (the SDK builds its indexer without the Identity Registry), so without a subgraph Python `getAgent()` raises `Agent … not found in index` and TypeScript returns `undefined`. TypeScript reads `ipfs://` URIs through the public `ipfs.io` gateway; Python needs an IPFS client for that and for `giveFeedback(feedbackFile=...)`. The TRON chain-ID agent IDs date from 1.1.2, not 1.2.0.
+
+👉 [SDK Feature Matrix](/8004/sdk-features/) · [Supported Networks](/8004/SupportedNetworks/) · [Contracts](/8004/contract/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 9, 2026</div>
 <div className="changelog-body">
diff --git a/docs/8004/QuickStart.md b/docs/8004/QuickStart.md
index c2ab8495..70aca13e 100644
--- a/docs/8004/QuickStart.md
+++ b/docs/8004/QuickStart.md
@@ -117,6 +117,8 @@ agent.setActive(True)
 agent.setX402Support(False)
 
 # Register on-chain
+# Replace with the URL where you host this agent's registration JSON;
+# loadAgent() below fetches it, and a URL that does not serve it raises an HTTP error.
 reg_tx = agent.register("https://example.com/agent-card.json")
 reg = reg_tx.wait_confirmed(timeout=180).result
 
@@ -185,6 +187,7 @@ async function main() {
   agent.setX402Support(false);
 
   // Register on-chain
+  // Replace with the URL where you host this agent's registration JSON.
   const tx = await agent.register("https://example.com/agent-card.json");
   const { result: registrationFile } = await tx.waitConfirmed();
 
diff --git a/docs/8004/SupportedNetworks.md b/docs/8004/SupportedNetworks.md
index 12770400..7cda8527 100644
--- a/docs/8004/SupportedNetworks.md
+++ b/docs/8004/SupportedNetworks.md
@@ -8,10 +8,14 @@ The SDK currently supports the following networks and default RPC/node endpoints
 | :--- | :--- | :--- | :--- |
 | **EVM** | BSC Mainnet | `eip155:56` (`chainId=56`) | `https://bsc-dataseed.binance.org` |
 | **EVM** | BSC Testnet | `eip155:97` (`chainId=97`) | `https://data-seed-prebsc-1-s1.binance.org:8545` |
+| **EVM** | Base Mainnet | `eip155:8453` (`chainId=8453`) | `https://mainnet.base.org` |
+| **EVM** | Base Sepolia | `eip155:84532` (`chainId=84532`) | `https://sepolia.base.org` |
 | **TRON** | TRON Mainnet | `mainnet` | `https://api.trongrid.io` |
 | **TRON** | Nile Testnet | `nile` | `https://nile.trongrid.io` |
 | **TRON** | Shasta Testnet | `shasta` | `https://api.shasta.trongrid.io` |
 
 Notes:
-- Explorer defaults are `bscscan.com` / `testnet.bscscan.com` for BSC and `tronscan.org` variants for TRON.
-- Subgraph URL is currently optional and may be unavailable depending on deployment.
+- Explorer defaults are `bscscan.com` / `testnet.bscscan.com` for BSC, `basescan.org` / `sepolia.basescan.org` for Base, and `tronscan.org` variants for TRON.
+- Base was added to the TypeScript SDK in 1.2.0; it also accepts the aliases `base` and `base:sepolia`. The Python SDK has no Base aliases and no Base Validation Registry entry; it only knows the Identity and Reputation Registry addresses for `chainId` 8453 / 84532, so pass `network="eip155:8453"` / `"eip155:84532"`. A bare `network="base"` is not rejected in Python: it falls back to chainId 97 (BSC Testnet).
+- The default endpoints apply to the TypeScript SDK. The Python SDK has no default endpoint: `rpcUrl` is required, and `SDK(...)` raises `rpcUrl is required` without it.
+- Subgraph is optional. The Python SDK has built-in subgraph URLs for Base Mainnet and Base Sepolia; the TypeScript SDK has none, so pass `subgraphUrl`. BSC has no built-in subgraph in either SDK.
diff --git a/docs/8004/Usage/ConfigureAgents.md b/docs/8004/Usage/ConfigureAgents.md
index 55f44891..9fc7aedd 100644
--- a/docs/8004/Usage/ConfigureAgents.md
+++ b/docs/8004/Usage/ConfigureAgents.md
@@ -172,9 +172,9 @@ agent.setMCP("https://mcp.example.com/");
 
 
 
-When you set the MCP endpoint, the SDK will automatically:
-*   Fetch tools, prompts, and resources from the endpoint.
-*   Populate the agent's capabilities.
+What `setMCP()` does beyond recording the endpoint differs by language:
+*   **Python**: by default (`auto_fetch=True`) it fetches tools, prompts, and resources from the endpoint and stores them on the MCP endpoint entry as `mcpTools`, `mcpPrompts`, and `mcpResources`. A failed fetch is skipped: network and parse errors are logged only at debug level, and a non-HTTP(S) endpoint logs a warning. Pass `auto_fetch=False` to turn this off.
+*   **TypeScript**: it only records the endpoint URL and version (default `2025-06-18`). It does not contact the endpoint.
 
 ### A2A (Agent-to-Agent) Endpoint
 
@@ -200,9 +200,9 @@ agent.setA2A("https://a2a.example.com/agent-card.json");
 
 
 
-The SDK will automatically:
-*   Fetch skills from the A2A agent card.
-*   Index these capabilities for search.
+What `setA2A()` does beyond recording the endpoint differs by language:
+*   **Python**: by default (`auto_fetch=True`) it fetches the skill tags (`skills[].tags`) from the A2A agent card and stores them on the A2A endpoint entry as `a2aSkills`. A failed fetch is skipped: network and parse errors are logged only at debug level, and a non-HTTP(S) endpoint logs a warning. Pass `auto_fetch=False` to turn this off.
+*   **TypeScript**: it only records the agent card URL and version (default `0.3.0`). It does not fetch the card.
 
 ### ENS
 
@@ -227,9 +227,9 @@ agent.setENS("myagent.eth");
 
 
 
-This stores the ENS name in:
-*   The registration file.
-*   As on-chain metadata.
+Both SDKs store the ENS name as an `ENS` endpoint in the registration file. Writing it on-chain as the `agentName` metadata key differs:
+*   **Python**: the first `register()` (minting) writes `agentName` on-chain for you; on an already registered agent, `register(uri)` only updates the URI, so use `registerIPFS()`, which writes changed metadata including `agentName`.
+*   **TypeScript**: `setENS()` only changes the local registration file, and `register()` / `registerIPFS()` do not send `agentName`. Call `await agent.updateOnChainMetadata()` on a registered agent to write it.
 
 ### Remove Endpoints
 
@@ -369,7 +369,7 @@ The SDK builds the typed data for you, but it cannot invent the new wallet's sig
 | :--- | :--- |
 | `signature` (Python) / `signature` (TS) | Uses your bytes as-is. This is the path for smart contract wallets and any external/offline signer. |
 | `new_wallet_signer` (Python) / `newWalletSigner` (TS) | Signs with that key. The SDK checks the key's address against `newWallet` first and raises if they differ. |
-| neither | Falls back to the SDK signer — **and this only succeeds if the SDK signer's address is the new wallet**. Otherwise it raises `New wallet must sign. Provide new_wallet_signer (EOA) or signature (ERC-1271/external).` |
+| neither | Falls back to the SDK signer — **and this only succeeds if the SDK signer's address is the new wallet**. Otherwise Python raises `New wallet must sign. Provide new_wallet_signer (EOA) or signature (ERC-1271/external).` and TypeScript throws `newWalletSigner address (…) does not match newWallet (…).` If the TypeScript SDK has no signer at all, it throws `New wallet signature is required. Provide options.newWalletSigner or options.signature.` |
 
 :::caution The bare one-argument call is not the general case
 `setWallet(address)` with no signing option works **only** when the SDK signer already is that address. Since the transaction sender must also be the owner or an approved operator, the bare call is effectively for "point the agent at the wallet I am already signing with". To attach a wallet that is *different* from the SDK signer, you must supply `new_wallet_signer` / `newWalletSigner` or a ready-made `signature`.
@@ -400,10 +400,9 @@ agent.addSkill("advanced_reasoning_planning/strategic_planning", validate_oasf=T
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// Add a skill without validation
+// The TypeScript SDK does not validate against the OASF taxonomy:
+// addSkill() accepts any string
 agent.addSkill("custom_skill/my_skill");
-
-// Add a skill with validation
 agent.addSkill("advanced_reasoning_planning/strategic_planning");
 ```
 
@@ -430,10 +429,9 @@ agent.addDomain("finance_and_business/investment_services", validate_oasf=True)
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// Add a domain without validation
+// The TypeScript SDK does not validate against the OASF taxonomy:
+// addDomain() accepts any string
 agent.addDomain("custom_domain/my_domain");
-
-// Add a domain with validation
 agent.addDomain("finance_and_business/investment_services");
 ```
 
@@ -568,21 +566,26 @@ Certain properties can be managed directly as on-chain metadata.
 <TabItem value="python" label="python">
 
 ```python
-# Update on-chain metadata
+# Update on-chain metadata (the agent must already be registered)
 agent.setMetadata({"version": "1.1.0", "tier": "pro"})
-# If already registered and updating URI, you can call:
-# tx = agent.updateRegistration(agentURI="https://example.com/agent-card-updated.json")
-# tx.wait_confirmed(timeout=180)
+# setMetadata() only stages the keys. On a registered agent, the next registerIPFS()
+# (requires an IPFS client) uploads the file, replaces the URI with ipfs://..., and then
+# writes each changed key on chain (best-effort) inside wait_confirmed().
+# register(uri) and updateRegistration() update only the URI of a registered agent.
+tx = agent.registerIPFS()
+tx.wait_confirmed(timeout=180)
 ```
 
 </TabItem>
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// Update on-chain metadata
+// Update on-chain metadata (the agent must already be registered)
 agent.setMetadata({ version: "1.1.0", tier: "pro" });
-const tx = await agent.register("https://example.com/agent-card-updated.json");
-await tx.waitConfirmed();
+// Sends one setMetadata transaction per key in the local metadata (plus agentName
+// when an ENS name is set) and returns their hashes.
+// Do not call register() here: it always mints a new agent.
+const txHashes = await agent.updateOnChainMetadata();
 ```
 
 </TabItem>
@@ -608,8 +611,8 @@ agent = sdk.loadAgent("97:123")
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// Query agent summary by ID
-const agentSummary = await sdk.getAgent("97:123");
+// Load agent by ID
+const agent = await sdk.loadAgent("97:123");
 ```
 
 </TabItem>
@@ -634,9 +637,11 @@ print(agent.active)
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-console.log(agentSummary?.name);
-console.log(agentSummary?.description);
-console.log(agentSummary?.active);
+// The TypeScript Agent has no name/description/active getters; read them from toJSON()
+const file = agent.toJSON();
+console.log(file.name);
+console.log(file.description);
+console.log(file.active);
 ```
 
 </TabItem>
@@ -680,7 +685,7 @@ const agent = sdk.createAgent({
 });
 
 agent.setMCP("https://mcp.example.com/")
-     .setMetadata({ ens: "advanced-agent.eth" })
+     .setENS("advanced-agent.eth")
      .addSkill("advanced_reasoning_planning/strategic_planning")
      .addDomain("technology/data_science/data_science")
      .setActive(true)
@@ -693,4 +698,23 @@ await tx.waitConfirmed();
 
 
 </TabItem>
-</Tabs>
\ No newline at end of file
+</Tabs>
+
+## Common Contract Errors
+
+These revert reasons come from the TRC-8004 / ERC-8004 registry contracts; the "Where" column names the contract function and the SDK calls that send it. On EVM networks a string reason such as `Not authorized` appears in the SDK's transaction error (usually from gas estimation). A custom ERC-721 error raised inside a Reputation or Validation call, such as `giveFeedback()` on an unregistered agent, may show only as its selector (`0x7e273289` is `ERC721NonexistentToken`). On TRON both SDKs report only `TRON transaction reverted: <hash> (REVERT)`, so look the transaction up on TronScan to see the reason.
+
+| Revert reason | Where | Cause and fix |
+| --- | --- | --- |
+| `Not authorized` | Identity Registry `setMetadata` / `setAgentURI` / `setAgentWallet`, sent by `updateOnChainMetadata()`, `updateRegistration(<uri>)`, `registerIPFS()` and `setWallet()`; Validation Registry `validationRequest` | The sender is not the agent's owner, approved address or operator. Sign with the owner, or `addOperator()` (TypeScript also `agent.approve()`) first |
+| `ERC721InsufficientApproval` | `transferFrom`, sent by TypeScript `transfer()` | The sender is not the owner, approved address or operator. Python `transfer()` checks the owner before sending and raises `ValueError: Only the current owner (…) can transfer the agent` instead |
+| `reserved key` | `register()` metadata, `setMetadata` | `agentWallet` is reserved; use `setWallet()` |
+| `bad wallet` / `expired` / `deadline too far` | `setWallet` | Zero address; `deadline` already passed; `deadline` more than 5 minutes ahead |
+| `invalid wallet sig` | `setWallet` | The signature was not produced by the new wallet (ECDSA, or ERC-1271 for contract wallets) |
+| `Self-feedback not allowed` | `giveFeedback` | The agent's owner, an operator or the approved address rated the agent |
+| `index must be > 0` / `index out of bounds` | `revokeFeedback`, `appendResponse`, `readFeedback` (SDK `getFeedback()`) | `feedbackIndex` is 0, or higher than the last feedback that client gave the agent (including when it gave none) |
+| `Already revoked` | `revokeFeedback` | The feedback was already revoked |
+| `Empty URI` | `appendResponse` | `responseURI` is empty. Python `appendResponse()` builds the URI only when an IPFS client is configured and the response has `text` or `attachments`; otherwise, or when the IPFS upload fails, it sends an empty URI and hits this error |
+| `clientAddresses required` | `getSummary`, called by Python `getReputationSummary()` without a subgraph | The agent has no feedback yet, so the client list read from the chain is empty. `sdk.getReputationSummary()` takes no client list, so treat this as "no reputation yet" (TypeScript returns zeros instead) |
+| `exists` / `not validator` / `resp>100` / `unknown` | Validation request / response | Duplicate request hash; responder is not the named validator; score above 100; unknown request hash |
+| `ERC721NonexistentToken` | Identity Registry writes and `ownerOf` / `tokenURI` reads, `giveFeedback`, `validationRequest` | The agent ID is not registered on the configured network. Python `loadAgent()` raises `Failed to load agent …`; TypeScript `loadAgent()` does not throw and returns an agent with an empty URI |
diff --git a/docs/8004/Usage/Install.md b/docs/8004/Usage/Install.md
index 7335ef8d..6e6d3d21 100644
--- a/docs/8004/Usage/Install.md
+++ b/docs/8004/Usage/Install.md
@@ -7,7 +7,7 @@
 *   **Python**: 3.11 or higher
 *   **pip**: Package manager
 *   **Private Key**: For signing transactions (not required for read-only mode)
-*   **RPC Node**: An RPC endpoint for a [supported network](/8004/SupportedNetworks/) — an EVM endpoint for BSC, or a TRON node endpoint
+*   **RPC Node**: An RPC endpoint for a [supported network](/8004/SupportedNetworks/) — an EVM endpoint for BSC or Base, or a TRON node endpoint
 *   **IPFS Provider (Optional)**: Pinata, Filecoin account, or local IPFS node
 *   **Subgraph (Optional)**: Use this when your deployment provides a subgraph endpoint
 
@@ -42,11 +42,11 @@ pip install -e .
 
 ## Install with TypeScript
 ### Prerequisites
-*   **Node.js**: 20 or higher
+*   **Node.js**: 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x)
 *   **npm or yarn**: Package manager
 *   **Write Operation Configuration**: Write operations require configuring a `signer` (private key string)
-*   **RPC Node**: An RPC endpoint for a [supported network](/8004/SupportedNetworks/) — an EVM endpoint for BSC, or a TRON node endpoint
-*   **IPFS Provider (Optional)**: Pinata, Filecoin account, or local IPFS node
+*   **RPC Node**: An RPC endpoint for a [supported network](/8004/SupportedNetworks/) — an EVM endpoint for BSC or Base, or a TRON node endpoint
+*   **IPFS (Optional)**: the TypeScript SDK has no built-in provider; pass an `ipfsUploader` callback for `registerIPFS()`
 *   **Subgraph (Optional)**: You may provide `subgraphUrl` or `subgraphOverrides` as needed.
 
 
diff --git a/docs/8004/Usage/RegistrationHTTP.md b/docs/8004/Usage/RegistrationHTTP.md
index 82febd72..fdc2c84b 100644
--- a/docs/8004/Usage/RegistrationHTTP.md
+++ b/docs/8004/Usage/RegistrationHTTP.md
@@ -347,7 +347,7 @@ const jsonContent = JSON.stringify(registrationData, null, 2);
 
 // 5. Update the URI on-chain (only if the URI has changed)
 const tx = await agent.updateRegistration("https://yourdomain.com/agents/my-agent-updated.json");
-await tx.waitConfirmed();
+if ("waitConfirmed" in tx) await tx.waitConfirmed(); // returns the Agent itself when no URI is passed
 ```
 
 </TabItem>
@@ -396,7 +396,8 @@ The SDK generates a registration file compliant with the 8004 standard:
 }
 ```
 
-**Note:** two things to watch when you publish this file.
+**Note:** three things to watch when you publish this file.
 
-* **TypeScript does not emit these keys.** Python's `registrationFile().to_dict()` (and `str(...)`) produces exactly the shape above. In `@bankofai/8004-sdk` **1.1.2**, `agent.toJSON()` returns the SDK's internal shape — `endpoints` and `x402support` — and `uploadRegistrationFile()` serialises that object as-is, so `registerIPFS()` publishes the internal keys too. Map `endpoints` → `services` and `x402support` → `x402Support` yourself before hosting the file from TypeScript.
+* **TypeScript's `toJSON()` is not this shape.** Python's `registrationFile().to_dict()` (and `str(...)`) produces the keys above, but for an agent built with `createAgent()` neither carries chain or registry info, so `registrations` comes out as `[]` and `type` is the EIP-8004 URL even on TRON; `agent.toJson()` passes that info and fills in `registrations` (once the agent has an ID) and the TRON `type`. In `@bankofai/8004-sdk` **1.2.1**, `agent.toJSON()` still returns the SDK's internal shape — `endpoints` and `x402support` — so map `endpoints` → `services` and `x402support` → `x402Support` yourself before hosting the file from TypeScript. `registerIPFS()` does not need this: since 1.2.0 it publishes the canonical keys (`type`, `services`, `registrations` with the minted agent ID, `x402Support`), plus TypeScript's own `tags` and `metadata`, and `loadAgent()` reads both the canonical and the internal key names.
+* **TRON uses a different `type`.** On TRON, the file that `registerIPFS()` publishes in either SDK — and Python's `agent.toJson()` — sets `type` to `https://github.com/tronprotocol/tips/blob/master/tip-8004.md#registration-v1` instead of the EIP-8004 URL.
 * `setA2A()` defaults the endpoint version to `0.30` in Python and `0.3.0` in TypeScript. Pass the version explicitly if you need both languages to agree.
diff --git a/docs/8004/contract.md b/docs/8004/contract.md
index 7743929d..5e8c07e4 100644
--- a/docs/8004/contract.md
+++ b/docs/8004/contract.md
@@ -17,3 +17,11 @@
 | BSC Testnet           | IdentityRegistry     | 0x8004A818BFB912233c491871b3d84c89A494BD9e      |
 | BSC Testnet           | ReputationRegistry   | 0x8004B663056A597Dffe9eCcC1965A193B7388713      |
 | BSC Testnet           | ValidationRegistry   | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272      |
+| Base Mainnet          | IdentityRegistry     | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432      |
+| Base Mainnet          | ReputationRegistry   | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63      |
+| Base Mainnet          | ValidationRegistry   | 0x8004Cc8439f36fd5F9F049D9fF86523Df6dAAB58      |
+| Base Sepolia          | IdentityRegistry     | 0x8004A818BFB912233c491871b3d84c89A494BD9e      |
+| Base Sepolia          | ReputationRegistry   | 0x8004B663056A597Dffe9eCcC1965A193B7388713      |
+| Base Sepolia          | ValidationRegistry   | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272      |
+
+The Base addresses are the official ERC-8004 Registry deployments that the TypeScript SDK (1.2.0 and later) is configured with. The Python SDK ships only the Identity and Reputation Registry addresses for Base.
diff --git a/docs/8004/general.md b/docs/8004/general.md
index 8a9c9de9..e7abe194 100644
--- a/docs/8004/general.md
+++ b/docs/8004/general.md
@@ -26,7 +26,7 @@ The 8004 Protocol leverages the blockchain as a shared public registry that anyo
 
   This file defines the Agent’s basic information, payment wallet, and multiple communication endpoints (such as Web, MCP, DID, etc.), and supports automatic domain matching or `.well-known` path verification to confirm endpoint ownership.  
 
-  As an NFT asset, the Agent identity is transferable. Upon ownership transfer, the payment address is automatically reset to ensure secure control of service revenue by the new owner.
+  As an NFT asset, the Agent identity is transferable. Upon ownership transfer, the payment address (`agentWallet`) is cleared, so the previous owner's wallet stops receiving service revenue; the new owner sets a new one with `setWallet`.
 
 - **Reputation System**
   
diff --git a/docs/8004/sdk-features.md b/docs/8004/sdk-features.md
index a704a0e1..42a310cb 100644
--- a/docs/8004/sdk-features.md
+++ b/docs/8004/sdk-features.md
@@ -9,7 +9,7 @@ This page tracks what the 8004 SDK actually implements, and where the TypeScript
 
 > **Two implementations, one repository.** `8004-sdk` ships a TypeScript package and a Python package from the same repository (`ts/` and `python/`). They target the same contracts and the same registration file format, but **they are not feature-identical** — the gaps are listed under [Language parity](#language-parity).
 >
-> **Current release:** `@bankofai/8004-sdk` **1.1.2** on npm; the Python package is not on PyPI, so install it from the repository's `main` branch. TypeScript requires **Node.js ≥ 20**; Python requires **Python ≥ 3.11**.
+> **Current release:** `@bankofai/8004-sdk` **1.2.1** on npm; the Python package (source version `1.2.1`) is not on PyPI, so install it from the repository's `main` branch. TypeScript requires **Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x)**; Python requires **Python ≥ 3.11**.
 
 ---
 
@@ -40,24 +40,30 @@ The Python package is not yet published to PyPI; install it from the repository.
 | `SDK` — chain clients, registries, top-level calls | ✅ | ✅ | |
 | `Agent` — registration file builder + on-chain agent | ✅ | ✅ | |
 | `TransactionHandle` — await confirmation, map the result | ✅ | ✅ | `waitConfirmed()` / `wait_confirmed()` |
-| `SubgraphClient` — indexed queries | ✅ | ✅ | Optional; requires a deployed subgraph |
+| `SubgraphClient` — indexed queries | ✅ | ✅ | Optional. Python ships default subgraph URLs for Base Mainnet and Base Sepolia (and Ethereum, Polygon, Sepolia); TypeScript ships none, so pass `subgraphUrl`. Neither has a BSC default |
 | `AgentIndexer` | ✅ | ✅ | Python also exposes `refreshIndex` / `refreshAgentIndex` |
 
 ---
 
 ## Networks
 
-Contract addresses ship with the SDK in `resource/chains.json` and are identical in both languages. The full list is on the [Contract Addresses](/8004/contract/) page.
+Contract addresses ship with the SDK. The BSC and TRON entries are identical in both languages; for Base, the TypeScript SDK configures all three registries, while the Python SDK knows only the Identity and Reputation Registry addresses. The full list is on the [Contract Addresses](/8004/contract/) page.
+
+Pass BSC as `eip155:56` / `eip155:97`. A bare `mainnet` resolves to **TRON** mainnet in both SDKs, and a bare `testnet` is rejected by TypeScript (Python falls back to chainId 97). TypeScript additionally accepts `bsc`, `bsc:mainnet` and `evm`, but without `chainId: 56` **all three resolve to BSC Testnet (97)** — including `bsc:mainnet`. Use `eip155:56` for BSC Mainnet.
 
 | Ecosystem | Network name | CAIP-2 / chainId | EIP-712 chainId | Default endpoint |
 |---|---|---|---|---|
-| BSC | `mainnet` | `eip155:56` / `56` | `56` | `https://bsc-dataseed.binance.org` |
-| BSC | `testnet` | `eip155:97` / `97` | `97` | `https://data-seed-prebsc-1-s1.binance.org:8545` |
-| TRON | `mainnet` | — | `728126428` | `https://api.trongrid.io` |
-| TRON | `nile` | — | `3448148188` | `https://nile.trongrid.io` |
-| TRON | `shasta` | — | `2494104990` | `https://api.shasta.trongrid.io` |
+| BSC | `eip155:56` | `eip155:56` / `56` | `56` | `https://bsc-dataseed.binance.org` |
+| BSC | `eip155:97` | `eip155:97` / `97` | `97` | `https://data-seed-prebsc-1-s1.binance.org:8545` |
+| Base | `base` | `eip155:8453` / `8453` | `8453` | `https://mainnet.base.org` |
+| Base | `base:sepolia` | `eip155:84532` / `84532` | `84532` | `https://sepolia.base.org` |
+| TRON | `mainnet` | — / `728126428` | `728126428` | `https://api.trongrid.io` |
+| TRON | `nile` | — / `3448148188` | `3448148188` | `https://nile.trongrid.io` |
+| TRON | `shasta` | — / `2494104990` | `2494104990` | `https://api.shasta.trongrid.io` |
+
+Use the bare TRON names (`mainnet` / `nile` / `shasta`) — that is what the examples show. Both SDKs also accept a `tron:`-prefixed alias (`tron:nile`, and a bare `tron` resolves to Nile), stripping the prefix internally; these are the SDK's own aliases, not the CAIP-2 identifiers x402 uses. The EIP-712 chainId column is what the SDK puts in the typed-data domain when signing an agent-wallet change on TRON. Since 1.1.2 both SDKs also use that value as the TRON chainId, so agent IDs take the form `3448148188:<tokenId>` on Nile (older releases produced `1:<tokenId>`; persisted IDs are not rewritten). `loadAgent()` and the reputation calls in both SDKs reject an ID whose chain prefix differs from the configured network; indexer and subgraph queries such as `getAgent()` and `searchFeedback()` do not check it.
 
-Use the bare TRON names (`mainnet` / `nile` / `shasta`) — that is what the examples show. Both SDKs also accept a `tron:`-prefixed alias (`tron:nile`, and a bare `tron` resolves to Nile), stripping the prefix internally; these are the SDK's own aliases, not the CAIP-2 identifiers x402 uses. The EIP-712 chainId column is what the SDK puts in the typed-data domain when signing an agent-wallet change on TRON.
+Base uses the official ERC-8004 Registry deployments. TypeScript accepts `base` / `base:mainnet` / `eip155:8453` and `base:sepolia` / `eip155:84532`. Python accepts only `eip155:8453` / `eip155:84532` and has no Base Validation Registry; a bare `network="base"` is not rejected but falls back to chainId 97 (BSC Testnet).
 
 ---
 
@@ -68,10 +74,12 @@ Use the bare TRON names (`mainnet` / `nile` / `shasta`) — that is what the exa
 | Create an agent locally | ✅ | ✅ | `sdk.createAgent(...)` |
 | Edit name / description / image | ✅ | ✅ | `agent.updateInfo({...})` — edits the local registration file; publish it with `updateRegistration()` |
 | Register with an HTTP(S) URI | ✅ | ✅ | `agent.register(agentURI)` |
-| Register via IPFS upload | ✅ | ✅ | `agent.registerIPFS()` |
+| Register without a URI, or with on-chain metadata entries | ✅ | ✅ | TS passes them explicitly: `agent.register()` / `agent.register(agentURI, metadata)`. Python's `register(agentURI)` takes only the URI but mints the metadata staged with `setMetadata()` (plus the ENS name as `agentName`); `registerIPFS()` mints without a URI first |
+| Register via IPFS upload | ✅ | ✅ | `agent.registerIPFS()` — for a new agent, mints first, then uploads the file with the minted agent ID and sets the URI (two transactions) |
 | Update the on-chain URI | ✅ | ✅ | `agent.updateRegistration(...)` |
 | Set the agent URI locally | ✅ | ✅ | `agent.setAgentUri(uri)` — local only, no transaction |
 | Load an agent from chain by ID | ✅ | ✅ | `sdk.loadAgent(agentId)` — works without a subgraph |
+| Read the on-chain agent URI | ✅ | ❌ | `sdk.getAgentURI(agentId)` |
 | MCP / A2A / ENS endpoints | ✅ | ✅ | `setMCP()`, `setA2A()`, `setENS()` |
 | Remove endpoints | ✅ | ✅ | `removeEndpoint()`, `removeEndpoints()` |
 | OASF skills and domains | ✅ | ✅ | `addSkill()`, `addDomain()`, `removeSkill()`, `removeDomain()` — but stored differently: Python builds an `OASF` entry inside `services` (its `version` is `0.8`), TypeScript pushes the slugs into a flat `tags` array |
@@ -79,7 +87,8 @@ Use the bare TRON names (`mainnet` / `nile` / `shasta`) — that is what the exa
 | Trust models | ✅ | ✅ | `setTrust(...)` — an object in TypeScript, keyword arguments in Python; both cover `reputation`, `cryptoEconomic`, `teeAttestation` |
 | Replace the trust model list wholesale | ✅ | ✅ | TypeScript `agent.setTrustModels([...])` normalises the names; Python `agent.trustModels([...])` assigns them as given |
 | Arbitrary metadata | ✅ | ✅ | `setMetadata()` |
-| Read / delete a single metadata key | ❌ | ✅ | `agent.getMetadata()`, `agent.delMetadata()` |
+| Read local metadata / delete one key | ❌ | ✅ | `agent.getMetadata()` returns a copy of all local metadata; `agent.delMetadata(key)` deletes one key — local registration file |
+| Read one on-chain metadata value | ✅ | ❌ | `sdk.getMetadata(agentId, key)` — returns the raw bytes as hex |
 | Push metadata changes on-chain | ✅ | ❌ | `agent.updateOnChainMetadata()` |
 | Active flag | ✅ | ✅ | `setActive()`; Python also has `activate()` / `deactivate()` |
 | x402 support flag | ✅ | ✅ | `setX402Support()` |
@@ -118,7 +127,9 @@ All reputation calls live on the `SDK` object in both languages.
 | Aggregate summary | ✅ | ✅ | `sdk.getReputationSummary(...)` |
 | Revoke your own feedback | ✅ | ✅ | `sdk.revokeFeedback(...)` |
 | Append a response to feedback | ✅ | ✅ | `sdk.appendResponse(...)` |
-| Search feedback | ✅ | ✅ | `sdk.searchFeedback(...)` — subgraph-backed |
+| Search feedback | ✅ | ✅ | `sdk.searchFeedback(...)` — subgraph-backed; without a subgraph, TypeScript returns `[]` and Python reads a single agent's feedback from chain |
+| Read all feedback from chain | ✅ | ❌ | `sdk.readAllFeedback(...)` |
+| Read clients, last index, response count | ✅ | ❌ | `sdk.getClients()`, `sdk.getLastIndex()`, `sdk.getResponseCount()` |
 | Build a feedback file | ❌ | ✅ | `sdk.prepareFeedbackFile(...)` |
 
 :::note Self-feedback is blocked on-chain
@@ -134,6 +145,8 @@ The Reputation Registry rejects feedback from the agent's owner and from any app
 | Request validation | ✅ | ❌ | `sdk.validationRequest(...)` |
 | Submit a validator response | ✅ | ❌ | `sdk.validationResponse(...)` |
 | Read validation status | ✅ | ❌ | `sdk.getValidationStatus(...)` |
+| Aggregate validation summary | ✅ | ❌ | `sdk.getValidationSummary(...)` |
+| List an agent's / a validator's request hashes | ✅ | ❌ | `sdk.getAgentValidations(...)`, `sdk.getValidatorRequests(...)` |
 
 :::caution Validation is TypeScript-only today
 The Python package resolves the Validation Registry contract and ships its ABI, but exposes **no** validation methods. Use the TypeScript SDK, or call the contract directly, if you need the Validation Registry from Python.
@@ -150,11 +163,13 @@ The registry itself is deliberately generic: only the validator named in the req
 | Transfer the agent | ✅ | ✅ | `agent.transfer(...)`; Python also has `sdk.transferAgent(...)` |
 | Approve the new owner as operator during transfer | ✅ | ❌ | TS `transfer(to, approveOperator)`; the Python `Agent.transfer` takes only the address |
 | Add / remove an operator | ✅ | ✅ | `agent.addOperator()`, `agent.removeOperator()` |
-| Read the owner | ❌ | ✅ | `sdk.getAgentOwner()` |
+| Approve an address for this agent only | ✅ | ❌ | `agent.approve(operator)` |
+| Read approvals | ✅ | ❌ | `sdk.getApproved(agentId)`, `sdk.isApprovedForAll(owner, operator)` |
+| Read the owner | ✅ | ✅ | `sdk.getAgentOwner()` |
 | Ownership / transfer pre-checks | ❌ | ✅ | `sdk.isAgentOwner()`, `sdk.canTransferAgent()` |
 
 :::note Transfer clears the agent wallet
-The Identity Registry clears `agentWallet` on every transfer, so `getAgentWallet()` returns the zero address afterwards. The new owner must call `setWallet()` again.
+The Identity Registry clears `agentWallet` on every transfer, so it reads back as the zero address afterwards — which the SDKs report as `undefined` (TypeScript `sdk.getAgentWallet()`) / `None` (Python `agent.getWallet()`). The new owner must call `setWallet()` again.
 :::
 
 ---
@@ -164,13 +179,13 @@ The Identity Registry clears `agentWallet` on every transfer, so `getAgentWallet
 | Feature | TypeScript | Python | Requires subgraph |
 |---|:--:|:--:|:--:|
 | `sdk.loadAgent(agentId)` | ✅ | ✅ | No — reads the chain directly |
-| `sdk.getAgent(agentId)` | ✅ | ✅ | Yes |
+| `sdk.getAgent(agentId)` | ✅ | ✅ | Yes (Python falls back to its local index cache, which `refreshIndex` cannot fill in 1.2.1 — see below) |
 | `sdk.searchAgents(filters)` | ✅ | ✅ | Yes |
-| `sdk.searchFeedback(filters)` | ✅ | ✅ | Yes |
+| `sdk.searchFeedback(filters)` | ✅ | ✅ | Yes, except Python's on-chain fallback for a single `agentId` |
 | `sdk.getSubgraphClient(chainId?)` — Python `sdk.get_subgraph_client()` | ✅ | ✅ | — returns nothing when unconfigured |
-| `sdk.refreshIndex()`, `sdk.refreshAgentIndex()` | ❌ | ✅ | Yes — same indexer as `getAgent` |
+| `sdk.refreshIndex()`, `sdk.refreshAgentIndex()` | ❌ | ⚠️ | Broken in 1.2.1: the SDK builds its indexer without the Identity Registry, so `refreshAgentIndex()` raises `Failed to get agent data: Identity registry not available` and `refreshIndex()` returns `[]` |
 
-If no subgraph is configured, the index-backed calls are unavailable — `loadAgent()` remains the way to fetch an agent.
+Without a subgraph (TypeScript unless you pass `subgraphUrl` or a `subgraphOverrides` entry for the chain; Python on BSC unless you pass `subgraphOverrides`, and always on TRON), `searchAgents()` is unavailable, Python `getAgent()` raises `Agent … not found in index` and TypeScript `getAgent()` returns `undefined`, TypeScript `searchFeedback()` returns `[]`, and Python `searchFeedback()` works only for a single `agentId`. `loadAgent()` remains the way to fetch an agent. On TRON, Python's `getAgent("<chainId>:<agentId>")` still queries a subgraph URL given in `subgraphOverrides` or the `SUBGRAPH_URL_<chainId>` environment variable.
 
 ---
 
@@ -186,9 +201,9 @@ The two languages configure storage completely differently.
 | Filecoin | `ipfs="filecoinPin"` | `filecoinPrivateKey` |
 | Self-hosted IPFS node | `ipfs="node"` | `ipfsNodeUrl` |
 
-**TypeScript** ships none of these. `SDKConfig` exposes a single `ipfsUploader?: (json: string) => Promise<string>` callback that you implement yourself; `registerIPFS()` throws `No ipfsUploader configured` without it.
+**TypeScript** ships none of these. `SDKConfig` exposes a single `ipfsUploader?: (json: string) => Promise<string>` callback that you implement yourself; `registerIPFS()` throws `No ipfsUploader configured` without it. For a new agent that error comes from `waitConfirmed()`, after the registration transaction has already minted the agent with an empty URI, so configure the uploader first.
 
-IPFS is optional in both languages. It is needed only for `registerIPFS()` and for reading an `ipfs://` agent URI; HTTP(S) registration works without it.
+IPFS is optional in both languages. It is needed for `registerIPFS()`; in Python also for reading an `ipfs://` agent URI and for `giveFeedback(feedbackFile=...)` (which raises without an IPFS client). TypeScript reads `ipfs://` URIs through the public `https://ipfs.io/ipfs/` gateway with no configuration. HTTP(S) registration works without IPFS.
 
 ---
 
@@ -197,9 +212,9 @@ IPFS is optional in both languages. It is needed only for `registerIPFS()` and f
 The two implementations diverge in four ways worth planning around:
 
 1. **Validation is TypeScript-only.** See above — this is the largest functional gap.
-2. **Defaults and config shapes differ.** `setA2A()` defaults to version `0.30` in Python and `0.3.0` in TypeScript; `subgraphUrl` and `ipfsUploader` are TypeScript-only constructor options, while `registryOverrides`, `indexingStore` and the built-in IPFS providers are Python-only.
+2. **Defaults and config shapes differ.** `setA2A()` defaults to version `0.30` in Python and `0.3.0` in TypeScript; `subgraphUrl` and `ipfsUploader` are TypeScript-only constructor options, while `registryOverrides`, `indexingStore`, `embeddings` and the built-in IPFS providers are Python-only. `feeLimit` (TRON, in SUN) defaults to 120,000,000 in TypeScript and 10,000,000 in Python.
 3. **Reading agent fields.** Python exposes twenty-one read-only properties on `Agent` (`name`, `description`, `endpoints`, `mcpTools`, `owners`, `operators`, `updatedAt`, and so on). TypeScript exposes only `agent.agentId`; everything else is read through `agent.toJSON()`.
-4. **Helper coverage.** Python adds ownership pre-checks (`isAgentOwner`, `canTransferAgent`), metadata accessors (`getMetadata`, `delMetadata`), `activate()` / `deactivate()`, and `saveToFile()`. TypeScript adds `updateOnChainMetadata()`, `uploadRegistrationFile()` and `submitRegister()`.
+4. **Helper coverage.** TypeScript also exposes `sdk.getTypedDataChainId()`; Python also exposes `sdk.chain_id()`, `sdk.registries()`, `sdk.set_chain()`, `sdk.isReadOnly` and `agent.registrationFile()` / `agent.toJson()`. Python adds ownership pre-checks (`isAgentOwner`, `canTransferAgent`), metadata accessors (`getMetadata`, `delMetadata`), `activate()` / `deactivate()`, and `saveToFile()`. TypeScript adds `updateOnChainMetadata()`, `uploadRegistrationFile()`, `submitRegister()`, `agent.approve()`, and the Registry read calls listed above (`getAgentURI`, `sdk.getMetadata`, `getApproved`, `isApprovedForAll`, `readAllFeedback`, `getClients`, `getLastIndex`, `getResponseCount`, and the validation reads).
 
 :::note Two Python names are defined twice
 In the Python `Agent` class, `transfer` and `trustModels` are each defined twice and the later definition wins. The effective `transfer` is `transfer(newOwnerAddress)` — the earlier four-argument form with `approve_operator` is unreachable — and the read-only `trustModels` property is shadowed by the setter of the same name, so `agent.trustModels` returns the bound method rather than the list. Read the trust models from `agent.registrationFile()` instead.
@@ -211,3 +226,4 @@ In the Python `Agent` class, `transfer` and `trustModels` are each defined twice
 
 - ✅ = Implemented
 - ❌ = Not implemented in this language
+- ⚠️ = Present but not working in the current release
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/8004.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/8004.md
index d43b3c99..91b74ddc 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/8004.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/8004.md
@@ -7,6 +7,44 @@ description: '8004 协议的版本发布记录。'
 
 8004 协议的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### Subgraph 默认值、别名与合约错误
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **Subgraph**——Python SDK 内置了 Base 主网与 Base Sepolia 的默认 subgraph 地址（TypeScript 没有；BSC 两边都没有），相关页面不再说 subgraph 一定要自行部署。
+- **配置与别名**——Python 独有的 `embeddings`；`feeLimit` 默认值（TypeScript 120,000,000 SUN，Python 10,000,000）；TypeScript 的 `bsc` / `bsc:mainnet` / `evm` 别名，不传 `chainId: 56` 时都会解析为 BSC 测试网；TypeScript 的 IPFS 前置条件是 `ipfsUploader` 回调；Python 的 RPC 端点包含 Base。
+- **新增「常见合约错误」**——按文档流程会碰到的注册表回退原因（`Not authorized`、`reserved key`、`expired`、`invalid wallet sig`、`Self-feedback not allowed` 等）及其原因。
+
+👉 [配置 Agent](/zh-Hans/8004/Usage/ConfigureAgents/) · [SDK 功能矩阵](/zh-Hans/8004/sdk-features/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-23</div>
+<div className="changelog-body">
+
+### 文档对齐 8004 SDK 1.2.1
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **版本**——功能矩阵改为 `@bankofai/8004-sdk` 1.2.1（Python 包仍未发布到 PyPI）。TypeScript SDK 需要 Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+（26.x）。
+- **Base 网络**——补充 Base 主网与 Base Sepolia 及其官方 ERC-8004 注册表地址（TypeScript 支持全部三个注册表；Python 仅支持身份与信誉注册表，需使用 `eip155:8453` / `eip155:84532`）。TRON 上的 Agent ID 以所在网络的 chainId 为前缀（如 Nile 上为 `3448148188:<tokenId>`）。
+- **注册文件**——自 1.2.0 起，`registerIPFS()` 发布规范的 registration-v1 键名（`services`、`x402Support`、`registrations`），TRON 上使用 TRC-8004 的 `type`。TypeScript 的 `toJSON()` 仍返回内部键名，自行托管文件前需要转换。本条更新了 9 月 9 日的说明。
+- **功能矩阵**——补充 TypeScript 注册表读取 API、`register()` 新重载和单个 Agent 授权；读取 Agent 所有者现在两种语言都支持。TypeScript 的 `updateRegistration` 示例现可在 `strict` 下通过类型检查。
+- **链上元数据示例**——TypeScript 示例原先调用 `agent.register()`，它总会铸造新 Agent；现改用 `updateOnChainMetadata()`。Python 示例改为通过 `registerIPFS()` 写入暂存的键，因为对已注册的 Agent，`register(uri)` 与 `updateRegistration()` 只更新 URI。
+- **BSC 网络名**——网络表原先把 BSC 写成 `mainnet` / `testnet`，但单写 `mainnet` 会解析为 TRON，TypeScript 也会拒绝 `testnet`。BSC 现写为 `eip155:56` / `eip155:97`。
+- **索引与 IPFS**——Python 的 `refreshIndex()` / `refreshAgentIndex()` 标注为 1.2.1 中不可用（SDK 构造索引器时没有传入身份注册表），因此没有 subgraph 时 Python 的 `getAgent()` 会抛出 `Agent … not found in index`，TypeScript 返回 `undefined`。TypeScript 通过公共 `ipfs.io` 网关读取 `ipfs://` URI；Python 读取它以及 `giveFeedback(feedbackFile=...)` 都需要 IPFS 客户端。以 TRON chainId 为前缀的 Agent ID 自 1.1.2 起使用，而非 1.2.0。
+
+👉 [SDK 功能矩阵](/zh-Hans/8004/sdk-features/) · [支持的网络](/zh-Hans/8004/SupportedNetworks/) · [合约地址](/zh-Hans/8004/contract/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-09</div>
 <div className="changelog-body">
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/QuickStart.md
index 564a321b..8a5015e3 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/QuickStart.md
@@ -118,13 +118,15 @@ agent.setActive(True)
 agent.setX402Support(False)
 
 # Register on-chain
+# Replace with the URL where you host this agent's registration JSON;
+# loadAgent() below fetches it, and a URL that does not serve it raises an HTTP error.
 reg_tx = agent.register("https://example.com/agent-card.json")
 reg = reg_tx.wait_confirmed(timeout=180).result
 
 # Optional: point the agent at a dedicated wallet (requires signature verification).
 # By default the agent wallet is the owner's wallet. The one-argument form below only
 # works when the SDK signer IS that wallet; otherwise pass new_wallet_signer.
-# See Configure Agents -> "How the signature is supplied".
+# 参见「配置代理」->「签名从何而来」。
 # agent.setWallet("TYourTronWalletAddress")
 
 print(f"✅ Agent registered!")
@@ -186,13 +188,14 @@ async function main() {
   agent.setX402Support(false);
 
   // Register on-chain
+  // Replace with the URL where you host this agent's registration JSON.
   const tx = await agent.register("https://example.com/agent-card.json");
   const { result: registrationFile } = await tx.waitConfirmed();
 
   // Optional: point the agent at a dedicated wallet (requires signature verification).
   // By default the agent wallet is the owner's wallet. The one-argument form below only
   // works when the SDK signer IS that wallet; otherwise pass newWalletSigner.
-  // See Configure Agents -> "How the signature is supplied".
+  // 参见「配置代理」->「签名从何而来」。
   // await agent.setWallet('TYourTronWalletAddress');
 
   console.log('✅ Agent registered!');
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/SupportedNetworks.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/SupportedNetworks.md
index e41888fb..91fc377b 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/SupportedNetworks.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/SupportedNetworks.md
@@ -9,11 +9,15 @@ SDK 当前支持以下网络及默认 RPC/节点端点：
 | :--- | :--- | :--- | :--- |
 | **EVM** | BSC 主网 | `eip155:56` (`chainId=56`) | `https://bsc-dataseed.binance.org` |
 | **EVM** | BSC 测试网 | `eip155:97` (`chainId=97`) | `https://data-seed-prebsc-1-s1.binance.org:8545` |
+| **EVM** | Base 主网 | `eip155:8453` (`chainId=8453`) | `https://mainnet.base.org` |
+| **EVM** | Base Sepolia 测试网 | `eip155:84532` (`chainId=84532`) | `https://sepolia.base.org` |
 | **TRON** | TRON 主网 | `mainnet` | `https://api.trongrid.io` |
 | **TRON** | Nile 测试网 | `nile` | `https://nile.trongrid.io` |
 | **TRON** | Shasta 测试网 | `shasta` | `https://api.shasta.trongrid.io` |
 
 **说明：**
 
-- BSC 默认区块浏览器为 `bscscan.com` / `testnet.bscscan.com`，TRON 默认浏览器为 `tronscan.org` 及其对应测试网版本。
-- Subgraph URL 当前为可选配置，具体是否可用取决于部署情况。
+- BSC 默认区块浏览器为 `bscscan.com` / `testnet.bscscan.com`，Base 为 `basescan.org` / `sepolia.basescan.org`，TRON 默认浏览器为 `tronscan.org` 及其对应测试网版本。
+- Base 自 1.2.0 起加入 TypeScript SDK，也可使用别名 `base` 与 `base:sepolia`。Python SDK 没有 Base 别名，也没有 Base 的验证注册表条目；它只内置了 `chainId` 8453 / 84532 上身份注册表与信誉注册表的地址，请传 `network="eip155:8453"` / `"eip155:84532"`。在 Python 中单写 `network="base"` 不会报错，而是回落到 chainId 97（BSC 测试网）。
+- 上表的默认端点适用于 TypeScript SDK。Python SDK 没有默认端点：必须传入 `rpcUrl`，否则 `SDK(...)` 会报 `rpcUrl is required`。
+- Subgraph 为可选。Python SDK 内置了 Base 主网与 Base Sepolia 的 subgraph 地址；TypeScript SDK 没有内置，需自行传 `subgraphUrl`。两个 SDK 都没有 BSC 的内置 subgraph。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/ConfigureAgents.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/ConfigureAgents.md
index 1d35f306..29ec2e18 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/ConfigureAgents.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/ConfigureAgents.md
@@ -172,9 +172,9 @@ agent.setMCP("https://mcp.example.com/");
 
 
 
-当你设置 MCP 端点时，SDK 会自动：
-*   从端点获取工具、提示词（prompts）和资源。
-*   填充代理的能力集（capabilities）。
+除记录端点外，`setMCP()` 的行为因语言而异：
+*   **Python**：默认（`auto_fetch=True`）会从端点获取工具、提示词（prompts）和资源，并以 `mcpTools`、`mcpPrompts`、`mcpResources` 存入该 MCP 端点条目。获取失败会被跳过：网络和解析错误只在 debug 级别记录，非 HTTP(S) 端点会记录一条 warning。传 `auto_fetch=False` 可关闭。
+*   **TypeScript**：只记录端点 URL 和版本（默认 `2025-06-18`），不会访问该端点。
 
 ### A2A (Agent-to-Agent) 端点
 
@@ -200,9 +200,9 @@ agent.setA2A("https://a2a.example.com/agent-card.json");
 
 
 
-SDK 会自动：
-*   从 A2A 代理卡片（agent card）中获取技能。
-*   为搜索索引这些能力。
+除记录端点外，`setA2A()` 的行为因语言而异：
+*   **Python**：默认（`auto_fetch=True`）会从 A2A 代理卡片（agent card）中获取技能标签（`skills[].tags`），并以 `a2aSkills` 存入该 A2A 端点条目。获取失败会被跳过：网络和解析错误只在 debug 级别记录，非 HTTP(S) 端点会记录一条 warning。传 `auto_fetch=False` 可关闭。
+*   **TypeScript**：只记录代理卡片 URL 和版本（默认 `0.3.0`），不会获取该卡片。
 
 ### ENS
 
@@ -227,9 +227,9 @@ agent.setENS("myagent.eth");
 
 
 
-这会将 ENS 名称存储在：
-*   注册文件中。
-*   作为链上元数据。
+两个 SDK 都会把 ENS 名称作为 `ENS` 端点存入注册文件。以 `agentName` 元数据键写上链则有区别：
+*   **Python**：首次 `register()`（铸造）时会自动把 `agentName` 写上链；对已注册的 Agent，`register(uri)` 只更新 URI，需改用 `registerIPFS()`，它会把包括 `agentName` 在内的改动元数据写上链。
+*   **TypeScript**：`setENS()` 只修改本地注册文件，`register()` / `registerIPFS()` 也不会发送 `agentName`。需在已注册的 Agent 上调用 `await agent.updateOnChainMetadata()` 才会写上链。
 
 ### 移除端点 
 
@@ -367,7 +367,7 @@ SDK 会替你构造类型化数据，但它无法凭空造出新钱包的签名
 | :--- | :--- |
 | `signature`（Python / TS 同名） | 直接使用你给的字节。这是智能合约钱包以及任何外部/离线签名场景的路径。 |
 | `new_wallet_signer`（Python）/ `newWalletSigner`（TS） | 用该私钥签名。SDK 会先校验该私钥对应的地址是否等于 `newWallet`，不一致则直接报错。 |
-| 两者都不传 | 回退到 SDK signer——**且仅当 SDK signer 的地址就是新钱包时才会成功**。否则抛出 `New wallet must sign. Provide new_wallet_signer (EOA) or signature (ERC-1271/external).` |
+| 两者都不传 | 回退到 SDK signer——**且仅当 SDK signer 的地址就是新钱包时才会成功**。否则 Python 抛出 `New wallet must sign. Provide new_wallet_signer (EOA) or signature (ERC-1271/external).`，TypeScript 抛出 `newWalletSigner address (…) does not match newWallet (…).`。若 TypeScript SDK 根本没有 signer，则抛出 `New wallet signature is required. Provide options.newWalletSigner or options.signature.` |
 
 :::caution 只传一个地址并不是通用写法
 不带任何签名参数的 `setWallet(address)`，**仅**在 SDK signer 本身就是该地址时才可用。又因为交易发送方还必须是所有者或获授权的操作员，所以这种写法实际上只适用于「把 Agent 指向我当前正在用来签名的这个钱包」。若要绑定一个与 SDK signer *不同*的钱包，就必须提供 `new_wallet_signer` / `newWalletSigner`，或一个已经准备好的 `signature`。
@@ -398,10 +398,9 @@ agent.addSkill("advanced_reasoning_planning/strategic_planning", validate_oasf=T
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// 添加技能而不进行验证
+// TypeScript SDK 不做 OASF 分类法校验：
+// addSkill() 接受任意字符串
 agent.addSkill("custom_skill/my_skill");
-
-// 添加带有验证的技能
 agent.addSkill("advanced_reasoning_planning/strategic_planning");
 ```
 
@@ -428,10 +427,9 @@ agent.addDomain("finance_and_business/investment_services", validate_oasf=True)
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// 添加领域而不进行验证
+// TypeScript SDK 不做 OASF 分类法校验：
+// addDomain() 接受任意字符串
 agent.addDomain("custom_domain/my_domain");
-
-// 添加带有验证的领域
 agent.addDomain("finance_and_business/investment_services");
 ```
 
@@ -566,21 +564,25 @@ agent.setTrust({ reputation: true, cryptoEconomic: true, teeAttestation: true })
 <TabItem value="python" label="python">
 
 ```python
-# 更新链上元数据
+# 更新链上元数据（Agent 须已注册）
 agent.setMetadata({"version": "1.1.0", "tier": "pro"})
-# 若已注册并要更新 URI，可调用：
-# tx = agent.updateRegistration(agentURI="https://example.com/agent-card-updated.json")
-# tx.wait_confirmed(timeout=180)
+# setMetadata() 只暂存这些键。对已注册的 Agent，下一次 registerIPFS()（需配置 IPFS 客户端）
+# 会上传文件、把 URI 替换为 ipfs://...，然后在 wait_confirmed() 中逐个把改动过的键
+# 写上链（尽力而为）。对已注册的 Agent，register(uri) 与 updateRegistration() 只更新 URI。
+tx = agent.registerIPFS()
+tx.wait_confirmed(timeout=180)
 ```
 
 </TabItem>
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// 更新链上元数据
+// 更新链上元数据（Agent 须已注册）
 agent.setMetadata({ version: "1.1.0", tier: "pro" });
-const tx = await agent.register("https://example.com/agent-card-updated.json");
-await tx.waitConfirmed();
+// 本地元数据中的每个键各发送一笔 setMetadata 交易（设置了 ENS 名称时另加一笔 agentName），
+// 返回交易哈希列表。
+// 不要在这里调用 register()：它总是会铸造一个新 Agent。
+const txHashes = await agent.updateOnChainMetadata();
 ```
 
 </TabItem>
@@ -606,8 +608,8 @@ agent = sdk.loadAgent("97:123")
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-// 通过 ID 查询代理摘要
-const agentSummary = await sdk.getAgent("97:123");
+// 通过 ID 加载代理
+const agent = await sdk.loadAgent("97:123");
 ```
 
 </TabItem>
@@ -632,9 +634,11 @@ print(agent.active)
 <TabItem value="TypeScript" label="TypeScript">
 
 ```typescript
-console.log(agentSummary?.name);
-console.log(agentSummary?.description);
-console.log(agentSummary?.active);
+// TypeScript 的 Agent 没有 name/description/active 访问器，需从 toJSON() 读取
+const file = agent.toJSON();
+console.log(file.name);
+console.log(file.description);
+console.log(file.active);
 ```
 
 </TabItem>
@@ -678,7 +682,7 @@ const agent = sdk.createAgent({
 });
 
 agent.setMCP("https://mcp.example.com/")
-     .setMetadata({ ens: "advanced-agent.eth" })
+     .setENS("advanced-agent.eth")
      .addSkill("advanced_reasoning_planning/strategic_planning")
      .addDomain("technology/data_science/data_science")
      .setActive(true)
@@ -692,3 +696,22 @@ await tx.waitConfirmed();
 
 </TabItem>
 </Tabs>
+
+## 常见合约错误
+
+以下回退原因来自 TRC-8004 / ERC-8004 注册表合约；"位置"一列写的是合约函数，以及会发送它的 SDK 调用。在 EVM 网络上，`Not authorized` 这类字符串原因会出现在 SDK 的交易错误里（通常来自 gas 估算）。在信誉或验证合约调用里触发的 ERC-721 自定义错误（例如对未注册 Agent 调用 `giveFeedback()`）可能只显示选择器（`0x7e273289` 即 `ERC721NonexistentToken`）。在 TRON 上两种 SDK 都只报 `TRON transaction reverted: <hash> (REVERT)`，需要到 TronScan 查看交易才能看到原因。
+
+| 回退原因 | 位置 | 原因与处理 |
+| --- | --- | --- |
+| `Not authorized` | 身份注册表的 `setMetadata` / `setAgentURI` / `setAgentWallet`，由 `updateOnChainMetadata()`、`updateRegistration(<uri>)`、`registerIPFS()` 和 `setWallet()` 发送；验证注册表的 `validationRequest` | 发送方不是该 Agent 的所有者、被批准地址或操作员。改用所有者签名，或先 `addOperator()`（TypeScript 还可用 `agent.approve()`） |
+| `ERC721InsufficientApproval` | `transferFrom`，由 TypeScript 的 `transfer()` 发送 | 发送方不是所有者、被批准地址或操作员。Python 的 `transfer()` 会在发送前检查所有者，直接抛出 `ValueError: Only the current owner (…) can transfer the agent` |
+| `reserved key` | `register()` 的元数据、`setMetadata` | `agentWallet` 是保留键，请用 `setWallet()` |
+| `bad wallet` / `expired` / `deadline too far` | `setWallet` | 零地址；`deadline` 已过期；`deadline` 超过当前时间 5 分钟 |
+| `invalid wallet sig` | `setWallet` | 签名不是由新钱包产生（ECDSA，合约钱包则为 ERC-1271） |
+| `Self-feedback not allowed` | `giveFeedback` | Agent 的所有者、操作员或被批准地址给自己的 Agent 评分 |
+| `index must be > 0` / `index out of bounds` | `revokeFeedback`、`appendResponse`、`readFeedback`（SDK 的 `getFeedback()`） | `feedbackIndex` 为 0，或大于该客户端给这个 Agent 的最后一条反馈序号（包括从未给过反馈） |
+| `Already revoked` | `revokeFeedback` | 该反馈已被撤回 |
+| `Empty URI` | `appendResponse` | `responseURI` 为空。Python 的 `appendResponse()` 只有在配置了 IPFS 客户端、且回复带有 `text` 或 `attachments` 时才会生成 URI，否则（或 IPFS 上传失败时）发送空 URI 并触发此错误 |
+| `clientAddresses required` | `getSummary`，没有 subgraph 时由 Python 的 `getReputationSummary()` 调用 | 该 Agent 还没有任何反馈，从链上读到的客户端列表为空。`sdk.getReputationSummary()` 不接受客户端列表参数，按「尚无信誉」处理即可（TypeScript 则返回 0） |
+| `exists` / `not validator` / `resp>100` / `unknown` | 验证请求 / 响应 | 请求哈希重复；响应者不是指定的验证者；分数超过 100；请求哈希不存在 |
+| `ERC721NonexistentToken` | 身份注册表的写操作和 `ownerOf` / `tokenURI` 读取、`giveFeedback`、`validationRequest` | 该 Agent ID 未在所配置网络上注册。Python 的 `loadAgent()` 会抛出 `Failed to load agent …`；TypeScript 的 `loadAgent()` 不报错，返回一个 URI 为空的 Agent |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/Install.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/Install.md
index e4175aef..35df961b 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/Install.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/Install.md
@@ -7,7 +7,7 @@
 * **Python**: 3.11 或更高版本
 * **pip**: 包管理器
 * **私钥**: 用于签署交易（若仅运行只读模式则不需要）
-* **RPC 节点**: [受支持网络](/zh-Hans/8004/SupportedNetworks/)的 RPC 端点——BSC 使用 EVM 端点，TRON 使用 TRON 节点端点
+* **RPC 节点**: [受支持网络](/zh-Hans/8004/SupportedNetworks/)的 RPC 端点——BSC 或 Base 使用 EVM 端点，TRON 使用 TRON 节点端点
 * **IPFS 提供商（可选）**: Pinata、Filecoin 账号或本地 IPFS 节点
 * **Subgraph（可选）**: 当你的部署提供 subgraph 端点时使用
 
@@ -40,11 +40,11 @@ pip install -e .
 
 ## 通过 TypeScript 安装
 ### 前置要求
-* **Node.js**: 20 或更高版本
+* **Node.js**: 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+（26.x）
 * **npm 或 yarn**: 包管理器
 * **写入操作配置**: 写入操作需配置 `signer`（私钥字符串）
-* **RPC 节点**: [受支持网络](/zh-Hans/8004/SupportedNetworks/)的 RPC 端点——BSC 使用 EVM 端点，TRON 使用 TRON 节点端点
-* **IPFS 提供商（可选）**: Pinata、Filecoin 账号或本地 IPFS 节点
+* **RPC 节点**: [受支持网络](/zh-Hans/8004/SupportedNetworks/)的 RPC 端点——BSC 或 Base 使用 EVM 端点，TRON 使用 TRON 节点端点
+* **IPFS（可选）**: TypeScript SDK 没有内置提供商，`registerIPFS()` 需要传入 `ipfsUploader` 回调
 * **Subgraph（可选）**: 可按需传入 `subgraphUrl` 或 `subgraphOverrides`
 
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/RegistrationHTTP.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/RegistrationHTTP.md
index e5c6f883..564ca7cf 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/RegistrationHTTP.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/Usage/RegistrationHTTP.md
@@ -346,7 +346,7 @@ const jsonContent = JSON.stringify(registrationData, null, 2);
 
 // 5. 在链上更新 URI（仅当 URI 发生更改时）
 const tx = await agent.updateRegistration("https://yourdomain.com/agents/my-agent-updated.json");
-await tx.waitConfirmed();
+if ("waitConfirmed" in tx) await tx.waitConfirmed(); // 未传 URI 时直接返回 Agent 本身
 ```
 
 </TabItem>
@@ -395,7 +395,8 @@ SDK 会生成符合 8004 标准的注册文件：
 }
 ```
 
-说明：发布这个文件时有两点需要注意。
+说明：发布这个文件时有三点需要注意。
 
-* **TypeScript 不会输出这两个键。** Python 的 `registrationFile().to_dict()`（以及 `str(...)`）产出的正是上面这种形态。而在 `@bankofai/8004-sdk` **1.1.2** 中，`agent.toJSON()` 返回的是 SDK 内部结构——`endpoints` 与 `x402support`——且 `uploadRegistrationFile()` 会把该对象原样序列化，因此 `registerIPFS()` 发布出去的同样是内部键名。在 TypeScript 中自行托管文件时，请自己把 `endpoints` → `services`、`x402support` → `x402Support` 转换好。
+* **TypeScript 的 `toJSON()` 不是这种形态。** Python 的 `registrationFile().to_dict()`（以及 `str(...)`）产出的键与上面一致，但对 `createAgent()` 创建的 Agent，二者都不带链与注册表信息，因此 `registrations` 为 `[]`，且即使在 TRON 上 `type` 也是 EIP-8004 的 URL；`agent.toJson()` 会传入这些信息，补全 `registrations`（Agent 已有 ID 时）以及 TRON 的 `type`。而在 `@bankofai/8004-sdk` **1.2.1** 中，`agent.toJSON()` 返回的仍是 SDK 内部结构——`endpoints` 与 `x402support`——因此在 TypeScript 中自行托管文件时，请自己把 `endpoints` → `services`、`x402support` → `x402Support` 转换好。`registerIPFS()` 则无需这一步：自 1.2.0 起，它发布的是规范键名（`type`、`services`、带有铸造出的 Agent ID 的 `registrations`、`x402Support`），外加 TypeScript 自有的 `tags` 与 `metadata`；`loadAgent()` 也能同时读取规范键名与内部键名。
+* **TRON 使用不同的 `type`。** 在 TRON 上，两个 SDK 通过 `registerIPFS()` 发布的文件——以及 Python 的 `agent.toJson()`——会把 `type` 设为 `https://github.com/tronprotocol/tips/blob/master/tip-8004.md#registration-v1`，而不是 EIP-8004 的 URL。
 * `setA2A()` 的端点版本默认值，Python 为 `0.30`，TypeScript 为 `0.3.0`。若需要两个语言一致，请显式传入版本号。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/contract.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/contract.md
index 91a76d03..2ee942ed 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/contract.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/contract.md
@@ -17,4 +17,12 @@
 | BSC Mainnet           | ValidationRegistry   | 0x8004Cc8439f36fd5F9F049D9fF86523Df6dAAB58      |
 | BSC Testnet           | IdentityRegistry     | 0x8004A818BFB912233c491871b3d84c89A494BD9e      |
 | BSC Testnet           | ReputationRegistry   | 0x8004B663056A597Dffe9eCcC1965A193B7388713      |
-| BSC Testnet           | ValidationRegistry   | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272      |
\ No newline at end of file
+| BSC Testnet           | ValidationRegistry   | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272      |
+| Base Mainnet          | IdentityRegistry     | 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432      |
+| Base Mainnet          | ReputationRegistry   | 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63      |
+| Base Mainnet          | ValidationRegistry   | 0x8004Cc8439f36fd5F9F049D9fF86523Df6dAAB58      |
+| Base Sepolia          | IdentityRegistry     | 0x8004A818BFB912233c491871b3d84c89A494BD9e      |
+| Base Sepolia          | ReputationRegistry   | 0x8004B663056A597Dffe9eCcC1965A193B7388713      |
+| Base Sepolia          | ValidationRegistry   | 0x8004Cb1BF31DAf7788923b405b754f57acEB4272      |
+
+Base 地址为官方 ERC-8004 注册表部署，即 TypeScript SDK（1.2.0 及以上）内置的配置。Python SDK 只内置了 Base 上身份注册表与信誉注册表的地址。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/general.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/general.md
index 3baf9406..fdc2cfc0 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/general.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/general.md
@@ -15,7 +15,7 @@
 ## 核心概念
 - **身份认证**
   
-  8004 协议建立了一套无许可的身份认证体系，允许任何 Agent 或服务通过铸造 NFT 兼容身份完成注册，其核心是将链上身份 (agentId) 映射至存储于任意位置（HTTPS、IPFS 或链上）的元数据文件 (agent-registration.json)。该文件定义了 Agent 的基本信息、支付钱包及多样化的通信端点（如 Web、MCP、DID 等），并支持通过域名自动匹配或 `.well-known` 路径验证端点所有权。作为 NFT 资产，Agent 身份具备可转移性，且在所有权转移时会自动重置支付地址，从而确保新所有者对服务收入的安全控制。
+  8004 协议建立了一套无许可的身份认证体系，允许任何 Agent 或服务通过铸造 NFT 兼容身份完成注册，其核心是将链上身份 (agentId) 映射至存储于任意位置（HTTPS、IPFS 或链上）的元数据文件 (agent-registration.json)。该文件定义了 Agent 的基本信息、支付钱包及多样化的通信端点（如 Web、MCP、DID 等），并支持通过域名自动匹配或 `.well-known` 路径验证端点所有权。作为 NFT 资产，Agent 身份具备可转移性，所有权转移时支付地址（`agentWallet`）会被清空，原所有者的钱包不再接收服务收入；新所有者需用 `setWallet` 重新设置。
 - **信誉系统**
   
   8004 协议定义了一个中立的公共信誉存储标准。反馈由客户端地址自行提交，归属即由该地址确定，并通过结构化标签支持多维度评价。注册表本身只强制最小限度的规则——尤其是 Agent 的所有者及其授权操作员不能给该 Agent 留下反馈——并提供针对调用方指定客户端集合的链上聚合。除此之外的信誉算法、排名聚合与反垃圾过滤逻辑，均交由生态应用层自主构建。
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/sdk-features.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/sdk-features.md
index 6a90ec2f..e019e3e3 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/sdk-features.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/8004/sdk-features.md
@@ -9,7 +9,7 @@ description: '8004 SDK 在 TypeScript 与 Python 两个实现中的特性支持
 
 > **同一个仓库，两套实现。** `8004-sdk` 从同一仓库（`ts/` 与 `python/`）分别发布 TypeScript 包与 Python 包。它们面向相同的合约、相同的注册文件格式，但**功能并不完全对等**——差异汇总见[语言差异](#语言差异)。
 >
-> **当前版本：** npm 上的 `@bankofai/8004-sdk` 为 **1.1.2**；Python 包未发布到 PyPI，请从仓库 `main` 分支安装。TypeScript 要求 **Node.js ≥ 20**；Python 要求 **Python ≥ 3.11**。
+> **当前版本：** npm 上的 `@bankofai/8004-sdk` 为 **1.2.1**；Python 包（源码版本 `1.2.1`）未发布到 PyPI，请从仓库 `main` 分支安装。TypeScript 要求 **Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+（26.x）**；Python 要求 **Python ≥ 3.11**。
 
 ---
 
@@ -40,24 +40,30 @@ Python 包尚未发布到 PyPI，请从仓库安装。
 | `SDK`——链客户端、注册表、顶层调用 | ✅ | ✅ | |
 | `Agent`——注册文件构造器 + 链上 Agent | ✅ | ✅ | |
 | `TransactionHandle`——等待确认并映射结果 | ✅ | ✅ | `waitConfirmed()` / `wait_confirmed()` |
-| `SubgraphClient`——索引查询 | ✅ | ✅ | 可选；需已部署 subgraph |
+| `SubgraphClient`——索引查询 | ✅ | ✅ | 可选。Python 内置了 Base 主网与 Base Sepolia（以及 Ethereum、Polygon、Sepolia）的默认 subgraph 地址；TypeScript 没有内置，需自行传 `subgraphUrl`。两者都没有 BSC 的默认 subgraph |
 | `AgentIndexer` | ✅ | ✅ | Python 额外提供 `refreshIndex` / `refreshAgentIndex` |
 
 ---
 
 ## 支持网络
 
-合约地址随 SDK 一起分发在 `resource/chains.json` 中，两个语言完全一致。完整列表见[合约地址](/zh-Hans/8004/contract/)页面。
+合约地址随 SDK 一起分发。BSC 与 TRON 的条目在两个语言中完全一致；Base 网络在 TypeScript SDK 中配置了全部三个注册表，Python SDK 只内置了身份注册表与信誉注册表的地址。完整列表见[合约地址](/zh-Hans/8004/contract/)页面。
+
+BSC 请写成 `eip155:56` / `eip155:97`。单写 `mainnet` 在两个 SDK 中都会解析为 **TRON** 主网，单写 `testnet` 会被 TypeScript 拒绝（Python 会回落到 chainId 97）。TypeScript 还接受 `bsc`、`bsc:mainnet` 和 `evm`，但不传 `chainId: 56` 时**三者都会解析为 BSC 测试网（97）**——包括 `bsc:mainnet`。BSC 主网请用 `eip155:56`。
 
 | 生态 | 网络名 | CAIP-2 / chainId | EIP-712 chainId | 默认端点 |
 |---|---|---|---|---|
-| BSC | `mainnet` | `eip155:56` / `56` | `56` | `https://bsc-dataseed.binance.org` |
-| BSC | `testnet` | `eip155:97` / `97` | `97` | `https://data-seed-prebsc-1-s1.binance.org:8545` |
-| TRON | `mainnet` | — | `728126428` | `https://api.trongrid.io` |
-| TRON | `nile` | — | `3448148188` | `https://nile.trongrid.io` |
-| TRON | `shasta` | — | `2494104990` | `https://api.shasta.trongrid.io` |
+| BSC | `eip155:56` | `eip155:56` / `56` | `56` | `https://bsc-dataseed.binance.org` |
+| BSC | `eip155:97` | `eip155:97` / `97` | `97` | `https://data-seed-prebsc-1-s1.binance.org:8545` |
+| Base | `base` | `eip155:8453` / `8453` | `8453` | `https://mainnet.base.org` |
+| Base | `base:sepolia` | `eip155:84532` / `84532` | `84532` | `https://sepolia.base.org` |
+| TRON | `mainnet` | — / `728126428` | `728126428` | `https://api.trongrid.io` |
+| TRON | `nile` | — / `3448148188` | `3448148188` | `https://nile.trongrid.io` |
+| TRON | `shasta` | — / `2494104990` | `2494104990` | `https://api.shasta.trongrid.io` |
+
+TRON 请使用裸名称（`mainnet` / `nile` / `shasta`），示例中也是这么写的。两个 SDK 同时接受带 `tron:` 前缀的别名（如 `tron:nile`，单独的 `tron` 会解析为 Nile），内部会去掉该前缀；这是 SDK 自身的别名，与 x402 使用的 CAIP-2 标识不是一回事。EIP-712 chainId 一列，是 SDK 在 TRON 上签署 Agent 钱包变更时写入类型化数据域的值。自 1.1.2 起，两个 SDK 也把该值用作 TRON 的 chainId，因此 Nile 上的 Agent ID 形如 `3448148188:<tokenId>`（旧版本生成的是 `1:<tokenId>`，已保存的 ID 不会被自动改写）。两个 SDK 的 `loadAgent()` 与信誉相关调用会拒绝链前缀与当前所配网络不一致的 ID；`getAgent()`、`searchFeedback()` 等索引器 / subgraph 查询不做这项检查。
 
-TRON 请使用裸名称（`mainnet` / `nile` / `shasta`），示例中也是这么写的。两个 SDK 同时接受带 `tron:` 前缀的别名（如 `tron:nile`，单独的 `tron` 会解析为 Nile），内部会去掉该前缀；这是 SDK 自身的别名，与 x402 使用的 CAIP-2 标识不是一回事。EIP-712 chainId 一列，是 SDK 在 TRON 上签署 Agent 钱包变更时写入类型化数据域的值。
+Base 使用官方 ERC-8004 注册表部署。TypeScript 接受 `base` / `base:mainnet` / `eip155:8453` 以及 `base:sepolia` / `eip155:84532`。Python 只接受 `eip155:8453` / `eip155:84532`，也没有 Base 的验证注册表；单写 `network="base"` 不会报错，而是回落到 chainId 97（BSC 测试网）。
 
 ---
 
@@ -68,10 +74,12 @@ TRON 请使用裸名称（`mainnet` / `nile` / `shasta`），示例中也是这
 | 本地创建 Agent | ✅ | ✅ | `sdk.createAgent(...)` |
 | 修改名称 / 描述 / 图片 | ✅ | ✅ | `agent.updateInfo({...})`——只改本地注册文件，需再调 `updateRegistration()` 发布 |
 | 以 HTTP(S) URI 注册 | ✅ | ✅ | `agent.register(agentURI)` |
-| 通过 IPFS 上传注册 | ✅ | ✅ | `agent.registerIPFS()` |
+| 不带 URI 注册，或附带链上元数据条目注册 | ✅ | ✅ | TS 显式传参：`agent.register()` / `agent.register(agentURI, metadata)`。Python 的 `register(agentURI)` 只接受 URI，但会把 `setMetadata()` 暂存的元数据（以及作为 `agentName` 的 ENS 名称）随铸造一起写入；`registerIPFS()` 会先不带 URI 铸造 |
+| 通过 IPFS 上传注册 | ✅ | ✅ | `agent.registerIPFS()`——新 Agent 会先铸造，再带着铸造出的 Agent ID 上传文件并设置 URI（两笔交易） |
 | 更新链上 URI | ✅ | ✅ | `agent.updateRegistration(...)` |
 | 在本地设置 agent URI | ✅ | ✅ | `agent.setAgentUri(uri)`——仅本地，不发交易 |
 | 按 ID 从链上加载 Agent | ✅ | ✅ | `sdk.loadAgent(agentId)`——无需 subgraph |
+| 读取链上 agent URI | ✅ | ❌ | `sdk.getAgentURI(agentId)` |
 | MCP / A2A / ENS 端点 | ✅ | ✅ | `setMCP()`、`setA2A()`、`setENS()` |
 | 移除端点 | ✅ | ✅ | `removeEndpoint()`、`removeEndpoints()` |
 | OASF 技能与领域 | ✅ | ✅ | `addSkill()`、`addDomain()`、`removeSkill()`、`removeDomain()`——但存储位置不同：Python 在 `services` 中构建 `OASF` 条目（其 `version` 为 `0.8`），TypeScript 则把 slug 推入扁平的 `tags` 数组 |
@@ -79,7 +87,8 @@ TRON 请使用裸名称（`mainnet` / `nile` / `shasta`），示例中也是这
 | 信任模型 | ✅ | ✅ | `setTrust(...)`——TypeScript 传对象，Python 传关键字参数；两者都支持 `reputation`、`cryptoEconomic`、`teeAttestation` |
 | 整体替换信任模型列表 | ✅ | ✅ | TypeScript 的 `agent.setTrustModels([...])` 会归一化名称；Python 的 `agent.trustModels([...])` 按原样赋值 |
 | 任意元数据 | ✅ | ✅ | `setMetadata()` |
-| 读取 / 删除单个元数据键 | ❌ | ✅ | `agent.getMetadata()`、`agent.delMetadata()` |
+| 读取本地元数据 / 删除单个键 | ❌ | ✅ | `agent.getMetadata()` 返回全部本地元数据的副本；`agent.delMetadata(key)` 删除单个键——针对本地注册文件 |
+| 读取单个链上元数据值 | ✅ | ❌ | `sdk.getMetadata(agentId, key)`——以十六进制返回原始字节 |
 | 将元数据变更推送上链 | ✅ | ❌ | `agent.updateOnChainMetadata()` |
 | 激活标志 | ✅ | ✅ | `setActive()`；Python 另有 `activate()` / `deactivate()` |
 | x402 支持标志 | ✅ | ✅ | `setX402Support()` |
@@ -118,7 +127,9 @@ TRON 请使用裸名称（`mainnet` / `nile` / `shasta`），示例中也是这
 | 聚合摘要 | ✅ | ✅ | `sdk.getReputationSummary(...)` |
 | 撤销自己的反馈 | ✅ | ✅ | `sdk.revokeFeedback(...)` |
 | 对反馈追加回应 | ✅ | ✅ | `sdk.appendResponse(...)` |
-| 检索反馈 | ✅ | ✅ | `sdk.searchFeedback(...)`——依赖 subgraph |
+| 检索反馈 | ✅ | ✅ | `sdk.searchFeedback(...)`——依赖 subgraph；没有 subgraph 时，TypeScript 返回 `[]`，Python 会从链上读取单个 Agent 的反馈 |
+| 从链上读取全部反馈 | ✅ | ❌ | `sdk.readAllFeedback(...)` |
+| 读取客户端列表、最新索引、回应数 | ✅ | ❌ | `sdk.getClients()`、`sdk.getLastIndex()`、`sdk.getResponseCount()` |
 | 构建反馈文件 | ❌ | ✅ | `sdk.prepareFeedbackFile(...)` |
 
 :::note 链上禁止自评
@@ -134,6 +145,8 @@ TRON 请使用裸名称（`mainnet` / `nile` / `shasta`），示例中也是这
 | 发起验证请求 | ✅ | ❌ | `sdk.validationRequest(...)` |
 | 提交验证者响应 | ✅ | ❌ | `sdk.validationResponse(...)` |
 | 读取验证状态 | ✅ | ❌ | `sdk.getValidationStatus(...)` |
+| 验证聚合摘要 | ✅ | ❌ | `sdk.getValidationSummary(...)` |
+| 列出某 Agent / 某验证者的请求哈希 | ✅ | ❌ | `sdk.getAgentValidations(...)`、`sdk.getValidatorRequests(...)` |
 
 :::caution 验证功能目前仅 TypeScript 可用
 Python 包会解析验证注册表合约、也内置了它的 ABI，但**没有**暴露任何验证方法。如果需要在 Python 中使用验证注册表，请改用 TypeScript SDK，或直接调用合约。
@@ -150,11 +163,13 @@ Python 包会解析验证注册表合约、也内置了它的 ABI，但**没有*
 | 转让 Agent | ✅ | ✅ | `agent.transfer(...)`；Python 另有 `sdk.transferAgent(...)` |
 | 转让时将新所有者设为操作员 | ✅ | ❌ | TS 为 `transfer(to, approveOperator)`；Python 的 `Agent.transfer` 只接受地址 |
 | 添加 / 移除操作员 | ✅ | ✅ | `agent.addOperator()`、`agent.removeOperator()` |
-| 读取所有者 | ❌ | ✅ | `sdk.getAgentOwner()` |
+| 仅针对该 Agent 授权某地址 | ✅ | ❌ | `agent.approve(operator)` |
+| 读取授权情况 | ✅ | ❌ | `sdk.getApproved(agentId)`、`sdk.isApprovedForAll(owner, operator)` |
+| 读取所有者 | ✅ | ✅ | `sdk.getAgentOwner()` |
 | 所有权 / 转让前置检查 | ❌ | ✅ | `sdk.isAgentOwner()`、`sdk.canTransferAgent()` |
 
 :::note 转让会清空 Agent 钱包
-身份注册表在每次转让时都会清空 `agentWallet`，因此转让后 `getAgentWallet()` 返回零地址。新所有者必须重新调用 `setWallet()`。
+身份注册表在每次转让时都会清空 `agentWallet`，转让后链上读到的是零地址——SDK 会把它报告为 `undefined`（TypeScript `sdk.getAgentWallet()`）/ `None`（Python `agent.getWallet()`）。新所有者必须重新调用 `setWallet()`。
 :::
 
 ---
@@ -164,13 +179,13 @@ Python 包会解析验证注册表合约、也内置了它的 ABI，但**没有*
 | 能力 | TypeScript | Python | 是否需要 subgraph |
 |---|:--:|:--:|:--:|
 | `sdk.loadAgent(agentId)` | ✅ | ✅ | 否——直接读链 |
-| `sdk.getAgent(agentId)` | ✅ | ✅ | 是 |
+| `sdk.getAgent(agentId)` | ✅ | ✅ | 是（Python 没有 subgraph 时回落到本地索引缓存，但 1.2.1 中 `refreshIndex` 无法填充它——见下文） |
 | `sdk.searchAgents(filters)` | ✅ | ✅ | 是 |
-| `sdk.searchFeedback(filters)` | ✅ | ✅ | 是 |
+| `sdk.searchFeedback(filters)` | ✅ | ✅ | 是；Python 指定单个 `agentId` 时可回退到链上读取 |
 | `sdk.getSubgraphClient(chainId?)`——Python 为 `sdk.get_subgraph_client()` | ✅ | ✅ | ——未配置时不返回 |
-| `sdk.refreshIndex()`、`sdk.refreshAgentIndex()` | ❌ | ✅ | 是——与 `getAgent` 共用索引器 |
+| `sdk.refreshIndex()`、`sdk.refreshAgentIndex()` | ❌ | ⚠️ | 1.2.1 中不可用：SDK 构造索引器时没有传入身份注册表，`refreshAgentIndex()` 会抛 `Failed to get agent data: Identity registry not available`，`refreshIndex()` 返回 `[]` |
 
-若未配置 subgraph，依赖索引的调用不可用——此时 `loadAgent()` 仍是获取 Agent 的途径。
+没有 subgraph 时（TypeScript 除非传了 `subgraphUrl` 或该链的 `subgraphOverrides`；Python 在 BSC 上除非传了 `subgraphOverrides`，在 TRON 上则总是如此），`searchAgents()` 不可用；Python 的 `getAgent()` 会抛出 `Agent … not found in index`，TypeScript 的 `getAgent()` 返回 `undefined`，TypeScript 的 `searchFeedback()` 返回 `[]`，Python 的 `searchFeedback()` 只能针对单个 `agentId` 使用。此时 `loadAgent()` 仍是获取 Agent 的途径。在 TRON 上，Python 的 `getAgent("<chainId>:<agentId>")` 仍会查询 `subgraphOverrides` 或环境变量 `SUBGRAPH_URL_<chainId>` 给出的 subgraph 地址。
 
 ---
 
@@ -186,9 +201,9 @@ Python 包会解析验证注册表合约、也内置了它的 ABI，但**没有*
 | Filecoin | `ipfs="filecoinPin"` | `filecoinPrivateKey` |
 | 自建 IPFS 节点 | `ipfs="node"` | `ipfsNodeUrl` |
 
-**TypeScript** 不内置任何提供方。`SDKConfig` 只暴露一个需要你自行实现的 `ipfsUploader?: (json: string) => Promise<string>` 回调；未提供时 `registerIPFS()` 会抛出 `No ipfsUploader configured`。
+**TypeScript** 不内置任何提供方。`SDKConfig` 只暴露一个需要你自行实现的 `ipfsUploader?: (json: string) => Promise<string>` 回调；未提供时 `registerIPFS()` 会抛出 `No ipfsUploader configured`。对新 Agent 来说，这个错误要到 `waitConfirmed()` 才出现，此时注册交易已经用空 URI 铸造了该 Agent，所以请先配置好 uploader。
 
-两个语言中 IPFS 都是可选的。只有 `registerIPFS()` 以及读取 `ipfs://` 形式的 agent URI 才需要它；HTTP(S) 注册无需配置。
+两个语言中 IPFS 都是可选的。`registerIPFS()` 需要它；Python 读取 `ipfs://` 形式的 agent URI、以及 `giveFeedback(feedbackFile=...)` 也需要它（未配置 IPFS 客户端时会报错）。TypeScript 无需任何配置，通过公共网关 `https://ipfs.io/ipfs/` 读取 `ipfs://` URI。HTTP(S) 注册无需 IPFS。
 
 ---
 
@@ -197,9 +212,9 @@ Python 包会解析验证注册表合约、也内置了它的 ABI，但**没有*
 两套实现有四处差异值得在选型时纳入考虑：
 
 1. **验证功能仅 TypeScript 有。** 见上文——这是最大的功能缺口。
-2. **默认值与配置形态不同。** `setA2A()` 的默认版本 Python 为 `0.30`、TypeScript 为 `0.3.0`；`subgraphUrl` 与 `ipfsUploader` 是 TypeScript 独有的构造参数，而 `registryOverrides`、`indexingStore` 及内置 IPFS 提供方则是 Python 独有。
+2. **默认值与配置形态不同。** `setA2A()` 的默认版本 Python 为 `0.30`、TypeScript 为 `0.3.0`；`subgraphUrl` 与 `ipfsUploader` 是 TypeScript 独有的构造参数，而 `registryOverrides`、`indexingStore`、`embeddings` 及内置 IPFS 提供方则是 Python 独有。`feeLimit`（TRON，单位 SUN）的默认值 TypeScript 为 120,000,000，Python 为 10,000,000。
 3. **读取 Agent 字段的方式不同。** Python 在 `Agent` 上暴露了二十一个只读属性（`name`、`description`、`endpoints`、`mcpTools`、`owners`、`operators`、`updatedAt` 等）。TypeScript 只暴露 `agent.agentId`，其余一律通过 `agent.toJSON()` 读取。
-4. **辅助方法各有侧重。** Python 多出所有权前置检查（`isAgentOwner`、`canTransferAgent`）、元数据存取（`getMetadata`、`delMetadata`）、`activate()` / `deactivate()` 以及 `saveToFile()`。TypeScript 多出 `updateOnChainMetadata()`、`uploadRegistrationFile()` 与 `submitRegister()`。
+4. **辅助方法各有侧重。** TypeScript 另有 `sdk.getTypedDataChainId()`；Python 另有 `sdk.chain_id()`、`sdk.registries()`、`sdk.set_chain()`、`sdk.isReadOnly` 以及 `agent.registrationFile()` / `agent.toJson()`。Python 多出所有权前置检查（`isAgentOwner`、`canTransferAgent`）、元数据存取（`getMetadata`、`delMetadata`）、`activate()` / `deactivate()` 以及 `saveToFile()`。TypeScript 多出 `updateOnChainMetadata()`、`uploadRegistrationFile()`、`submitRegister()`、`agent.approve()`，以及上文列出的注册表读取调用（`getAgentURI`、`sdk.getMetadata`、`getApproved`、`isApprovedForAll`、`readAllFeedback`、`getClients`、`getLastIndex`、`getResponseCount` 和各项验证读取）。
 
 :::note Python 中有两个同名定义重复
 在 Python 的 `Agent` 类里，`transfer` 与 `trustModels` 各自被定义了两次，最终生效的是后一个。生效的 `transfer` 是 `transfer(newOwnerAddress)`——此前那个带 `approve_operator` 的四参数版本不可达；而只读的 `trustModels` 属性被同名 setter 覆盖，因此 `agent.trustModels` 返回的是绑定方法而非列表。要读取信任模型，请改用 `agent.registrationFile()`。
@@ -211,3 +226,4 @@ Python 包会解析验证注册表合约、也内置了它的 ABI，但**没有*
 
 - ✅ = 已实现
 - ❌ = 该语言未实现
+- ⚠️ = 存在但在当前版本中不可用

From c1715b55691e1429365f46a62183b26cc04d53b4 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:02 +0800
Subject: [PATCH 04/13] docs(openclaw, mcp): match installer and TRON MCP
 Server code

- OpenClaw: installer prompts and output (skills 1.4.6 copy mode), first-install-only configuration, Clean mode scope, Node.js error text.
- Recharge MCP (recharge.bankofai.io/mcp) is offline; point to wallet-cli bai recharge.
- TRON MCP: npm 1.1.7 vs v1.1.8, endpoints and rate limits, Docker --readonly, 405 on GET/DELETE /mcp, agent-wallet 2.x reset.
- add-mcp -y installs project-level config; walkthrough includes the scope prompt.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 changelog/mcp-server.md                       |  34 ++++
 changelog/openclaw-extension.md               |  33 ++++
 .../MCP/BSCMCPServer/Features.md              |   2 +
 .../MCP/BSCMCPServer/Installation.md          |   7 +-
 .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md |  69 +++++---
 .../MCP/TRONMCPServer/Intro.md                |   2 +-
 .../LocalPrivatizedDeployment.md              |  52 +++---
 .../MCP/TRONMCPServer/OfficialServerAccess.md |  16 +-
 .../MCP/TRONMCPServer/QuickStart.md           |  10 +-
 .../MCP/TRONMCPServer/ToolList.md             |   8 +-
 docs/Openclaw-extension/FAQ.md                |  12 +-
 docs/Openclaw-extension/Intro.md              |   2 +-
 docs/Openclaw-extension/QuickStart.md         | 156 ++++++++++++------
 .../current/mcp-server.md                     |  34 ++++
 .../current/openclaw-extension.md             |  33 ++++
 .../MCP/BSCMCPServer/Features.md              |   2 +
 .../MCP/BSCMCPServer/Installation.md          |   7 +-
 .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md |  69 +++++---
 .../MCP/TRONMCPServer/Intro.md                |   2 +-
 .../LocalPrivatizedDeployment.md              |  52 +++---
 .../MCP/TRONMCPServer/OfficialServerAccess.md |  16 +-
 .../MCP/TRONMCPServer/QuickStart.md           |  10 +-
 .../MCP/TRONMCPServer/ToolList.md             |   8 +-
 .../current/Openclaw-extension/FAQ.md         |  12 +-
 .../current/Openclaw-extension/Intro.md       |   2 +-
 .../current/Openclaw-extension/QuickStart.md  | 156 ++++++++++++------
 26 files changed, 586 insertions(+), 220 deletions(-)

diff --git a/changelog/mcp-server.md b/changelog/mcp-server.md
index c561d71b..d5661a92 100644
--- a/changelog/mcp-server.md
+++ b/changelog/mcp-server.md
@@ -7,6 +7,40 @@ description: 'Release notes for MCP Server.'
 
 Release notes for MCP Server.
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Package contents, Docker mode and HTTP details
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- The npm package ships `build/`, `bin/`, `package.json`, `README.md` and `LICENSE`; the Docker image always runs read-only (`--readonly` is hard-coded); `GET` / `DELETE /mcp` return 405 and SSE is not supported; `GET /` returns server information; `tron` / `trx` / `testnet` are accepted network aliases.
+
+👉 [Local Deployment](/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment/) · [Tool List](/McpServer-Skills/MCP/TRONMCPServer/ToolList/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 23, 2026</div>
+<div className="changelog-body">
+
+### TRON MCP Server docs matched to the code
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **RPC without an API key** — on `main` (tag `v1.1.8`), Mainnet requests without `TRONGRID_API_KEY` go to `https://hptg.bankofai.io`; with a key they go to `api.trongrid.io`. Nile and Shasta always use the TronGrid testnet nodes. npm `1.1.7` still uses `api.trongrid.io` without a key.
+- **Tools and prompts** — `write_contract` takes no `feeLimit` (only `deploy_contract` does); `tron://networks` returns `{"supportedNetworks":[...]}`; read-only mode registers 4 prompts, not 6.
+- **Wallet errors** — the FAQ now quotes the real agent-wallet 2.x error texts (`resolve_wallet could not find a wallet source in config or env`, `Password required for local_secure wallets`, `No active wallet set.`, `MAC mismatch — wrong password or corrupted file`). agent-wallet 2.3.x and 2.4.0 also accept the aliases `TRON_PRIVATE_KEY` and `TRON_MNEMONIC`, but read these env vars only when no password resolves and the wallet directory holds no wallets; otherwise they are silently ignored. On that path, with both a private key and a mnemonic set, agent-wallet 2.3.x gives `Wallet not configured.` and 2.4.0 gives `Provide only one of AGENT_WALLET_PRIVATE_KEY or AGENT_WALLET_MNEMONIC`.
+- **Node.js** — a source checkout of `v1.1.8` requires 22.23.4+ (22.x) or 24.22.1+ (24.x); npm `1.1.7`, which `npx` runs, declares `>=20`. The pages recommend the October 2026 security releases either way. The cloud-service Quick Start replaced its hard requirement "Node.js v20.0.0 or higher" with "Node.js, needed to run `npx`", recommending 22.23.4+ or 24.22.1+.
+- **Agent Wallet install pinned to 2.x** — the server depends on `@bankofai/agent-wallet ^2.3.0`, but an unpinned `npm install -g @bankofai/agent-wallet` now installs 3.0.0, which has no `local_secure` wallets, master password, or `--save-runtime-secrets`. The pages now use `npm install -g @bankofai/agent-wallet@2` and note that the Agent-Wallet docs describe 3.x.
+
+👉 [Quick Start](/McpServer-Skills/MCP/TRONMCPServer/QuickStart/) · [FAQ](/McpServer-Skills/MCP/TRONMCPServer/FAQ/) · [Local Private Deployment](/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 9, 2026</div>
 <div className="changelog-body">
diff --git a/changelog/openclaw-extension.md b/changelog/openclaw-extension.md
index bacfb5e7..4283ddce 100644
--- a/changelog/openclaw-extension.md
+++ b/changelog/openclaw-extension.md
@@ -7,6 +7,39 @@ description: 'Release notes for the Openclaw Extension.'
 
 Release notes for the Openclaw Extension.
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Installer details corrected
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- The skill configuration phase (API key prompt, `Next steps`) runs only for skills that were not already in the skill list before the run (on the default global install it covers `~/.openclaw/skills/`, `~/.agents/skills/` and other agents' skill folders), so re-installs print `No new skills were installed.` and skip it; the Quick Start now says so and points to the manual API key steps. The `Proceed with installation?` prompt and the `bankofai-recharge` remote URL are documented.
+- The Node.js error text matches what the installer prints (on Windows without the `Error: ` prefix); the manual `bankofai-config.json` steps set `chmod 600` like the installer does; Windows is described as almost identical with the differences in the FAQ; deleting `~/.openclaw/skills/` removes skills only — MCP entries, the API key file, global npm packages and `~/.agent-wallet` stay; Clean mode clears the MCP entries, skills and config files and re-initialises agent-wallet, but never uninstalls the npm packages.
+
+👉 [Quick Start](/Openclaw-extension/QuickStart/) · [FAQ](/Openclaw-extension/FAQ/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 23, 2026</div>
+<div className="changelog-body">
+
+### Docs matched to the current installer
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **Correction to the Sep 9 entry** — those installer changes never shipped. The installer on `main` still pins Skills `v1.5.15` (14 skills, no `wallet-cli`), `@bankofai/agent-wallet` 2.3.1 and `@bankofai/mcp-server-tron` 1.1.7, and writes `base_url: https://chat.ainft.com`. The Quick Start and FAQ now describe that installer, and a note at the top explains that its wallet steps follow agent-wallet 2.x.
+- **What else the docs now say** — selecting `x402-payment` also runs `npm install --global @bankofai/x402-cli@1.0.1`; the TronScan API key is optional (without one the skill uses `ts.bankofai.io`); a project-level install goes to `<cwd>/skills/`; there is no TronGrid prompt; with an existing wallet, agent-wallet 2.3.1 first asks whether to add one or exit; and on Windows the installer exits if `~/.openclaw` is missing.
+- **Node.js** — both installers check the full version against `^22.23.4 || ^24.22.1 || >=26.12.1` before installing anything.
+
+👉 [Quick Start](/Openclaw-extension/QuickStart/) · [FAQ](/Openclaw-extension/FAQ/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 9, 2026</div>
 <div className="changelog-body">
diff --git a/docs/McpServer-Skills/MCP/BSCMCPServer/Features.md b/docs/McpServer-Skills/MCP/BSCMCPServer/Features.md
index de103d95..ed1fcb1e 100644
--- a/docs/McpServer-Skills/MCP/BSCMCPServer/Features.md
+++ b/docs/McpServer-Skills/MCP/BSCMCPServer/Features.md
@@ -19,3 +19,5 @@ The project is divided into the following core functional modules:
 **Common Components**: Shared utilities and types  
 
 **Greenfield**: Support for file management operations on the Greenfield network, including file uploads, downloads, and the management of files and storage buckets  
+
+**Agents (ERC-8004)**: Register and resolve on-chain AI agent identities on the ERC-8004 Identity Registry (`register_erc8004_agent`, `set_erc8004_agent_uri`, `get_erc8004_agent`, `get_erc8004_agent_wallet`)
diff --git a/docs/McpServer-Skills/MCP/BSCMCPServer/Installation.md b/docs/McpServer-Skills/MCP/BSCMCPServer/Installation.md
index 15e354c8..10342ac4 100644
--- a/docs/McpServer-Skills/MCP/BSCMCPServer/Installation.md
+++ b/docs/McpServer-Skills/MCP/BSCMCPServer/Installation.md
@@ -3,7 +3,7 @@
 ### Prerequisites
 
 * **bun** v1.2.10 or higher  
-* **Node.js** v18 or higher (this page previously stated v17; the rest of the BANK OF AI toolchain requires 18+, and the TRON MCP server requires 20+)
+* **Node.js** v17 or higher (the upstream README's requirement; `package.json` declares no `engines`, and the project's release workflow uses Node.js 20)
 
 ### Quick Start
 
@@ -22,6 +22,7 @@
     * `PRIVATE_KEY`: Your wallet private key (required for executing transactions)
     * `LOG_LEVEL`: Set the log level (`DEBUG`, `INFO`, `WARN`, `ERROR`)
     * `PORT`: Server port number (default: `3001` — the TRON MCP server also defaults to 3001, so change one of them if you run both locally)
+    * `BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION` (optional, default `false`): by default, transfer and payment tools only return a preview and a `confirmToken` (valid for 5 minutes) without sending anything; call `confirm_transfer` with that token to execute. Set it to `true` to execute immediately
 
 4. **Install dependencies and start the development server:**
     ```bash
@@ -49,9 +50,11 @@ Use the following template to configure the local server in your MCP client:
 }
 ```
 
+> The template follows the upstream README. With a `url` entry the client connects to the already running server, so the `env` block is not passed to it: the server reads `PRIVATE_KEY` from its own `.env`.
+
 ### Test with the Web UI
 
-Use @modelcontextprotocol/inspector for testing. Run the following command to launch the test UI:
+Use @modelcontextprotocol/inspector for testing. Run the following command to launch the test UI (the script runs the latest inspector through `npx`, which currently requires Node.js 22.19 or later):
 
 ```bash
 bun run test
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
index 542090af..dee972ba 100644
--- a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
+++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
@@ -12,11 +12,15 @@ Connection issues usually occur during the initial configuration phase. If your
 
 This is the most common issue. Troubleshoot in the following order:
 
-1. **Check Node.js version**. TRON MCP Server requires v20.0.0 or higher:
+1. **Check Node.js version**. What is declared depends on how you run the server:
+   - **`npx -y @bankofai/mcp-server-tron`** runs the npm package `1.1.7`, which declares Node.js `>=20`.
+   - **A source checkout** of `main` (tag `v1.1.8`) requires 22.23.4+ (22.x) or 24.22.1+ (24.x). Its `package.json` still says `1.1.7`, so the server reports version `1.1.7` there too.
+
+   Either way, we recommend the October 2026 security releases, 22.23.4+ or 24.22.1+:
    ```bash
-   node --version  # Should output v20.x.x or higher
+   node --version  # recommended: v22.23.4+ or v24.22.1+
    ```
-   If your version is too low, upgrade Node.js first.
+   If your version is below what your route declares, upgrade Node.js first.
 
 2. **Check that npx is available**. Run `npx --version` in your terminal. If the command is not found, your Node.js installation is incomplete — reinstall it.
 
@@ -47,15 +51,22 @@ When using HTTP mode (`npx -y @bankofai/mcp-server-tron --http`, or `npm run sta
 
 3. **Firewall blocking**. If you're accessing the local HTTP service from another machine, check whether the firewall allows inbound connections on that port.
 
-### Write tools appear but return "Wallet not configured" error
+### Write tools appear but return a wallet error {#write-tools-wallet-error}
+
+As of v1.1.7, write tools (transfers, staking, etc.) are always visible in the AI's tool list, but wallet availability is checked at execution time. If you call a write tool without a usable wallet, the tool returns an error such as `Error transferring TRX: <reason>`, where `<reason>` comes from Agent Wallet — see [Wallet error messages](#wallet-error-messages) below for what each one means.
 
-As of v1.1.7, write tools (transfers, staking, etc.) are always visible in the AI's tool list, but wallet availability is checked at execution time. If you call a write tool without a configured wallet, it will return an error prompting you to set up a wallet.
+To enable write operations, set up Agent Wallet **2.x**, the version this server depends on:
 
-To enable write operations, configure [Agent Wallet](../../../Agent-Wallet/Intro.md):
+```bash
+npm install -g @bankofai/agent-wallet@2
+agent-wallet start local_secure --save-runtime-secrets
+```
 
-- Set `AGENT_WALLET_PASSWORD` environment variable with your master password
+- `--save-runtime-secrets` writes your master password to `~/.agent-wallet/runtime_secrets.json`; alternatively, set the `AGENT_WALLET_PASSWORD` environment variable to it
 - Optionally set `AGENT_WALLET_DIR` if using a custom wallet directory
 
+The [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md) describes Agent Wallet 3.x, which this server does not use yet — use the 2.x commands above.
+
 After configuring, restart your AI client. For detailed instructions, see [Local Private Deployment](./LocalPrivatizedDeployment.md).
 
 :::info
@@ -66,22 +77,36 @@ If you're connected via the official cloud service or using `--readonly` mode, w
 
 ## Authentication & Key Issues
 
-### "Wallet not configured" error
+### Wallet error messages {#wallet-error-messages}
+
+TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for all wallet management. When a write tool (or `get_wallet_address` / `sign_message`) cannot get a wallet, the error text tells you which case you hit:
 
-This means no wallet has been set up for signing transactions. TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for all wallet management. To resolve:
+| Error text | Meaning |
+| :--- | :--- |
+| `resolve_wallet could not find a wallet source in config or env` | No wallet at all: no password resolves, the wallet directory holds no wallets, and none of `AGENT_WALLET_PRIVATE_KEY`, `TRON_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC` or `TRON_MNEMONIC` is set. |
+| `Password required for local_secure wallets` | Wallets exist in the wallet directory, but no password resolved — neither `runtime_secrets.json` nor `AGENT_WALLET_PASSWORD`. |
+| `No active wallet set.` | A password resolved, but the wallet directory holds no wallets. In this case the private-key and mnemonic variables are ignored — create or import a wallet with Agent Wallet, or remove the password so the env-var path is used. |
+| `MAC mismatch — wrong password or corrupted file` | A password was found but does not match the keystore (see the next section). |
+| `Wallet not configured.` | Agent Wallet could not even load its configuration — for example a malformed `runtime_secrets.json` or `wallets_config.json`. With agent-wallet 2.3.x (what a source checkout's `package-lock.json` installs), setting both a private key and a mnemonic also ends here, when the env-var path is reached (see below the table). |
+| `Provide only one of AGENT_WALLET_PRIVATE_KEY or AGENT_WALLET_MNEMONIC` | A private key (`AGENT_WALLET_PRIVATE_KEY` or `TRON_PRIVATE_KEY`) and a mnemonic (`AGENT_WALLET_MNEMONIC` or `TRON_MNEMONIC`) are both set and the env-var path is reached, with agent-wallet 2.4.0 — what `npx -y @bankofai/mcp-server-tron` (npm `1.1.7`, dependency `^2.3.0`) installs today. The server passes the text through, e.g. `Error transferring TRX: Provide only one of …`, or `Error: Provide only one of …` from `get_wallet_address`. Unset one of the two. |
 
-1. **Install and initialize Agent Wallet** following the [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md).
-2. **Set the environment variable**:
+Both agent-wallet versions read the private key from `AGENT_WALLET_PRIVATE_KEY` or its alias `TRON_PRIVATE_KEY`, and the mnemonic from `AGENT_WALLET_MNEMONIC` or its alias `TRON_MNEMONIC`. They read these env vars only on the env-var path — when no password resolves **and** the wallet directory holds no wallets. Otherwise the variables are silently ignored, and neither of the both-set errors above can occur.
+
+To resolve the first two:
+
+1. **No wallet yet: install and initialize Agent Wallet 2.x** with `npm install -g @bankofai/agent-wallet@2`, then `agent-wallet start local_secure --save-runtime-secrets`, which also saves the master password to `runtime_secrets.json`. (The [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md) describes 3.x, which this server does not use yet.)
+2. **Wallets already exist: make the password available** — export it:
    ```bash
    export AGENT_WALLET_PASSWORD='<your-master-password>'
    ```
-3. **Restart your AI client** for the changes to take effect.
+   or save it to `runtime_secrets.json` as described in [Local Private Deployment](./LocalPrivatizedDeployment.md) (Path 1). Re-running `agent-wallet start` does not help: with wallets present it only offers `add`, which creates a new wallet and makes it the active one, or `exit`, which saves nothing.
+3. **Restart your AI client** for the changes to take effect. The server resolves the wallet source once and caches it, so a restart is required after changing wallet settings.
 
-### "Agent wallet password incorrect" error
+### "MAC mismatch — wrong password or corrupted file" error
 
-`AGENT_WALLET_PASSWORD` must exactly match the master password generated when you ran `agent-wallet start`. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory.
+The password the server resolved (from `runtime_secrets.json` or `AGENT_WALLET_PASSWORD`) must exactly match the master password you set when you ran `agent-wallet start`. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory.
 
-If the password is lost, you'll need to re-initialize. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ.md) for details.
+If the password is lost, you'll need to re-initialize. **Warning: this wipes all wallets and keys — ensure funds are moved or mnemonics backed up before proceeding.** Run `agent-wallet reset` to wipe and start over. In agent-wallet 2.x (what this server uses), `reset` deletes every file in `~/.agent-wallet` — `master.json`, `wallets_config.json`, `runtime_secrets.json` and the `secret_*.json` keystores. The Agent-Wallet pages describe 3.x, whose `reset` removes only `wallets_config.json`.
 
 ### TronGrid API Key not working
 
@@ -115,7 +140,7 @@ Interacting with smart contracts (including TRC20 token transfers) requires Ener
 **How to resolve:**
 - Estimate cost first: "Estimate how much Energy is needed to call this contract's transfer function"
 - Stake TRX for Energy: "Stake 500 TRX for Energy"
-- If using `write_contract`, have the AI increase the `feeLimit` parameter
+- `write_contract` has no fee-limit parameter, so make sure the wallet holds enough TRX to burn for the Energy shortfall. Only `deploy_contract` accepts a `feeLimit` (in Sun, default 1,000,000,000 = 1000 TRX), which you can ask the AI to raise for a large deployment
 
 ### "Account not found" or "Account not activated"
 
@@ -158,7 +183,7 @@ If this keeps happening, remind the AI: "Please only use tools provided by TRON
 
 Several common causes and solutions:
 
-- **No TronGrid API Key**: Public RPC has rate limits; adding a free API Key can significantly improve performance
+- **No TronGrid API Key**: Without `TRONGRID_API_KEY`, Mainnet requests go to the BANK OF AI fallback endpoint `https://hptg.bankofai.io` on a source checkout from `v1.1.8`, and to `https://api.trongrid.io` without a key on npm `1.1.7` (what `npx` runs). Setting a free API Key sends them to `https://api.trongrid.io` under your own quota in both versions
 - **Complex multi-tool workflows**: Some operations (like full wallet analysis) require multiple sequential calls — waiting is normal
 - **Use testnet for development**: Nile and Shasta testnets are usually faster
 - **Be more specific in prompts**: Reduce the AI's exploratory calls — tell it directly which tool to use and which network to query
@@ -183,7 +208,13 @@ Yes. Define multiple MCP Server entries in your MCP client configuration — for
 
 ### How do I update to the latest version?
 
-If you're using the `npx` method, you always get the latest published version. To force clearing the cache:
+If you're using the `npx` method, `npx -y @bankofai/mcp-server-tron` does not always fetch the latest release: it can run a copy that is already installed — globally, in the current project, or, on older npm versions, in the npx cache. To always get the latest published version, ask for it explicitly, for example in your MCP client configuration:
+
+```bash
+npx -y @bankofai/mcp-server-tron@latest
+```
+
+To clear the npx cache instead, delete `~/.npm/_npx` (and, if needed, run `npm cache clean --force`). The third-party `clear-npx-cache` package does the same:
 
 ```bash
 npx clear-npx-cache
@@ -200,5 +231,5 @@ npm run build
 
 ### What MCP protocol version is supported?
 
-TRON MCP Server supports MCP protocol version **2025-11-25**, using `@modelcontextprotocol/sdk` 1.22.0 or higher.
+The protocol version is negotiated by `@modelcontextprotocol/sdk`, which the server depends on as `^1.22.0`; a source checkout's `package-lock.json` pins 1.27.1. MCP protocol version **2025-11-25** requires SDK 1.24.1 or later — SDK 1.22.0–1.24.0 top out at 2025-06-18. Older protocol versions requested by the client are also accepted.
 
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md
index 2f0a0fc6..738dc833 100644
--- a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md
+++ b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md
@@ -17,7 +17,7 @@ This means different things to different people:
 
 ## What Can It Do?
 
-TRON MCP Server covers almost all common TRON blockchain operations, from read-only queries to asset management, providing **97 tools**, **6 prompt templates**, and **1 resource definition**.
+TRON MCP Server covers almost all common TRON blockchain operations, from read-only queries to asset management, providing **97 tools**, **6 prompt templates**, and **1 resource definition**. In read-only mode (the official cloud service or `--readonly`), write tools and the 2 write prompts are not registered, leaving 68 read tools and 4 prompt templates.
 
 Here is an overview of core capabilities — each one can be triggered via natural language:
 
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
index a086ee22..134d731c 100644
--- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
+++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
@@ -29,15 +29,17 @@ Of course, all read-only query capabilities are also fully retained.
 
 | Requirement | Description |
 | :--- | :--- |
-| **Node.js** | v20.0.0 or higher ([download](https://nodejs.org/)) |
+| **Node.js** | Recommended: 22.23.4+ (22.x) or 24.22.1+ (24.x), the October 2026 security releases ([download](https://nodejs.org/)). A source checkout of `main` (tag `v1.1.8`, Option B below) requires this range (its `package.json` still says `1.1.7`, so the server reports version `1.1.7`); the npm package `1.1.7` that `npx` runs (Option A) declares `>=20`. |
 | **TronGrid API Key** | Optional but recommended ([apply here](https://www.trongrid.io/)) |
 
 Verify your Node.js version:
 
 ```bash
-node --version  # Should output v20.x.x or higher
+node --version  # recommended: v22.23.4+ or v24.22.1+
 ```
 
+The requirement is the `engines` field in `package.json`: on a source checkout, `npm install` under another Node.js version prints an `EBADENGINE` warning but still installs, and the server does not check the Node.js version at runtime.
+
 ### Security Principles
 
 Before configuring your wallet, make sure to understand the following security principles:
@@ -50,7 +52,7 @@ Before configuring your wallet, make sure to understand the following security p
 ## Installation Steps
 ### Step 1: Configure Wallet
 
-The wallet determines which identity the AI assistant uses to perform on-chain operations. TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for secure wallet management. If no wallet is configured, write tools will return an error prompting you to set up a wallet.
+The wallet determines which identity the AI assistant uses to perform on-chain operations. TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for secure wallet management. If no wallet is configured, write tools return a wallet error when called (see [FAQ](./FAQ.md#write-tools-wallet-error)).
 
 #### Agent Wallet
 
@@ -63,34 +65,38 @@ TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for wallet m
 | Runtime Wallet Switching | Yes |
 | Recommended For | All use cases |
 
-> For installation, initialization, and detailed usage of Agent Wallet, see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md).
+> TRON MCP Server depends on Agent Wallet **2.x** (`@bankofai/agent-wallet ^2.3.0`). The [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md) describes 3.x, which this server does not use yet — follow the 2.x commands on this page.
 
-First, install Agent Wallet:
+First, install the Agent Wallet 2.x CLI:
 
 ```bash
-npm install -g @bankofai/agent-wallet
+npm install -g @bankofai/agent-wallet@2
 ```
 
+The `@2` pin installs the latest 2.x release (2.4.0 at the time of writing). Without it, npm installs 3.x, which has no `local_secure` wallets, no master password, and no `--save-runtime-secrets`, so the steps below would not work.
+
 Then, choose one of the following two paths depending on your situation:
 
 #### Path 1: Generate a New Wallet (Recommended for New Users)
 
-If you don't have an existing private key, use `agent-wallet start` to generate a new wallet with an encrypted keystore and master password:
+If you don't have an existing private key, use `agent-wallet start local_secure` to generate a new wallet with an encrypted keystore and master password:
 
 ```bash
-agent-wallet start
+agent-wallet start local_secure --save-runtime-secrets
 ```
 
-Follow the interactive prompts to set your master password and generate a wallet. Agent Wallet manages the encrypted keystore for you, but the server still needs the password at signing time — plain `agent-wallet start` does not persist it. Do one of:
+Follow the interactive prompts to set your master password and generate a wallet. Agent Wallet manages the encrypted keystore for you, but the server still needs the password at signing time. `--save-runtime-secrets` writes it to `~/.agent-wallet/runtime_secrets.json`; without the flag it is not persisted, and you must instead export `AGENT_WALLET_PASSWORD` in the environment the MCP server runs in.
+
+If you already ran `agent-wallet start` without the flag, do not run it again to fix this: with wallets present it only offers `add`, which creates a new wallet and makes it the active one, or `exit`, which saves nothing. Export `AGENT_WALLET_PASSWORD`, or save the password with one of these commands:
 
-- run `agent-wallet start --save-runtime-secrets`, which writes the password to `~/.agent-wallet/runtime_secrets.json`, or
-- export `AGENT_WALLET_PASSWORD` in the environment the MCP server runs in.
+- `agent-wallet sign msg hello -n tron --save-runtime-secrets` — asks for the password, saves it, then signs a test message with the active wallet. It saves the password before checking it, so if it prints `Wrong password`, delete `~/.agent-wallet/runtime_secrets.json` and run it again.
+- `agent-wallet add local_secure --save-runtime-secrets` — checks the password before saving it, but also creates an additional wallet (the active wallet stays the same).
 
-Without either, unlocking a `local_secure` wallet fails when a write tool is called. Use `AGENT_WALLET_DIR` if your keystore lives outside `~/.agent-wallet`.
+Without a saved or exported password, unlocking a `local_secure` wallet fails when a write tool is called. Use `AGENT_WALLET_DIR` if your keystore lives outside `~/.agent-wallet`.
 
 #### Path 2: Import an Existing Private Key
 
-If you already have a private key you want to use, set it via the `AGENT_WALLET_PRIVATE_KEY` environment variable. Note the precedence: the env-var path is only reached when no password resolves (neither `runtime_secrets.json` nor `AGENT_WALLET_PASSWORD`) **and** the wallet directory holds no wallets. If you already ran Path 1, saved a runtime password, or ran the Openclaw installer, the keystore path wins and this variable is silently ignored.
+If you already have a private key you want to use, set it via the `AGENT_WALLET_PRIVATE_KEY` environment variable (Agent Wallet also accepts the alias `TRON_PRIVATE_KEY`, and a mnemonic via `AGENT_WALLET_MNEMONIC` or `TRON_MNEMONIC`). Note the precedence: the env-var path is only reached when no password resolves (neither `runtime_secrets.json` nor `AGENT_WALLET_PASSWORD`) **and** the wallet directory holds no wallets. If you already ran Path 1, saved a runtime password, or ran the Openclaw installer, the keystore path wins and these variables are silently ignored.
 
 ```bash
 export AGENT_WALLET_PRIVATE_KEY=your_private_key_here
@@ -120,14 +126,22 @@ echo $AGENT_WALLET_PRIVATE_KEY
 
 #### TronGrid API Key
 
-The TRON Mainnet public RPC has strict rate limits. For frequent on-chain queries, it is strongly recommended to configure a free TronGrid API Key:
+On a source checkout from `v1.1.8`, the API Key also decides which Mainnet endpoint the server talks to. For frequent on-chain queries, it is recommended to configure a free TronGrid API Key:
 
 ```bash
 # Add to ~/.zshrc or ~/.bashrc
 export TRONGRID_API_KEY="<your-TronGrid-API-Key>"
 ```
 
-Register for free at [trongrid.io](https://www.trongrid.io/). The server still works without this, but may encounter rate-limiting errors during high-frequency operations. Testnet networks (Nile, Shasta) are less affected by rate limits.
+Register for free at [trongrid.io](https://www.trongrid.io/). How the variable affects each network (the only difference between versions is Mainnet without a key):
+
+| Network | `TRONGRID_API_KEY` set | `TRONGRID_API_KEY` not set |
+| :--- | :--- | :--- |
+| **Mainnet** | `https://api.trongrid.io`, with your key sent as `TRON-PRO-API-KEY` (your own quota) | Source checkout from `v1.1.8`: falls back to the BANK OF AI endpoint `https://hptg.bankofai.io`. npm `1.1.7` (what `npx` runs): `https://api.trongrid.io` without a key |
+| **Nile** | `https://nile.trongrid.io` (key header also sent) | `https://nile.trongrid.io` |
+| **Shasta** | `https://api.shasta.trongrid.io` (key header also sent) | `https://api.shasta.trongrid.io` |
+
+The server works without a key, but keyless requests to TronGrid (Mainnet on npm `1.1.7`, and Nile / Shasta) share TronGrid's public rate limits, so high-frequency use can hit rate-limit errors. Set one if you want Mainnet traffic to go to TronGrid under your own quota.
 
 
 ---
@@ -138,7 +152,7 @@ Multiple deployment options are available. For most users, Option A is sufficien
 
 #### Option A: Run directly with npx (Recommended)
 
-No need to clone the repository — run the latest version directly via `npx`. This is also the default method used in the MCP client configuration examples below.
+No need to clone the repository — run the latest version directly via `npx`. This is also the command used in the [Configuration Notes](#configuration-notes) below.
 
 ```bash
 npx -y @bankofai/mcp-server-tron
@@ -173,7 +187,7 @@ From a source checkout (Option B) you can use the script instead:
 npm run start:http
 ```
 
-This will start a local stateless Streamable HTTP server (default: `http://localhost:3001/mcp`) that your MCP client can connect to. Each request is handled independently — no session state is maintained between requests.
+This will start a local stateless Streamable HTTP server (default: `http://localhost:3001/mcp`) that your MCP client can connect to. `GET` and `DELETE` on `/mcp` return `405` (SSE is not supported), and `GET /` returns server information. Each request is handled independently — no session state is maintained between requests.
 
 You can customize the port and host via environment variables:
 
@@ -182,11 +196,11 @@ export MCP_PORT=3001      # default: 3001
 export MCP_HOST=0.0.0.0   # default: 0.0.0.0
 ```
 
-The Docker and source-checkout start scripts also read `MCP_LOG_DIR` (default `/app/logs` in the container, `./logs` from a checkout). The published npm package ships only `build/` and `bin/`, so that variable does not apply to the `npx` route above.
+The Docker and source-checkout start scripts also read `MCP_LOG_DIR` (default `/app/logs` in the container, `./logs` from a checkout). The published npm package ships only `build/`, `bin/`, `package.json`, `README.md` and `LICENSE`, so that variable does not apply to the `npx` route above.
 
 #### Option D: Docker Deployment
 
-Run TRON MCP Server in a Docker container for isolated, reproducible environments. The Docker image runs in **read-only HTTP mode** by default.
+Run TRON MCP Server in a Docker container for isolated, reproducible environments. The Docker image always runs in **read-only HTTP mode**: `docker-start.sh` passes `--readonly`, and there is no switch to turn it off.
 
 ```bash
 # 1. Create a .env file for sensitive variables (never commit this file)
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md
index de9f4449..a02a3a88 100644
--- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md
+++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md
@@ -85,7 +85,7 @@ If you have Node.js installed and prefer the command line, run the following dir
 npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y
 ```
 
-The `-y` flag skips all interactive prompts and automatically installs to every AI tool detected on your computer. Once complete, it will show ✅ Installation complete! along with the list of agents it was installed to.
+The `-y` flag skips all interactive prompts. add-mcp then writes project-level config in the current directory: for the AI tools it detects there (from marker folders and files such as `.claude`, `.cursor`, `.vscode` or `.mcp.json`), or, if it detects none, for every tool that supports a project config. When it finishes it prints `Installation complete` and the agents it installed to.
 
 Once installation is complete, you can start interacting with the TRON blockchain via TRON MCP Server.
 
@@ -117,7 +117,7 @@ The installer automatically detects the remote MCP service URL and generates a s
 
 **2️⃣ Choose which AI tools to install to**
 
-The installer auto-detects AI tools on your computer (e.g., Claude Code, Cursor, Cline, etc.). Use Space to select the ones you want:
+The installer detects AI tools from marker folders and files in the current directory (such as `.claude`, `.cursor`, `.vscode` or `.mcp.json`), for example Claude Code or Cursor. Use Space to select the ones you want:
 
 ```
 ◇  Detected 1 agent
@@ -128,7 +128,7 @@ The installer auto-detects AI tools on your computer (e.g., Claude Code, Cursor,
 
 **3️⃣ Confirm installation details**
 
-The installer displays an installation summary. Review it and select `Yes` to proceed:
+If every tool you selected supports both project and global config, the installer first asks **Installation scope** (`Project` / `Global`); the summary below is for `Project`. It then displays an installation summary. Review it and select `Yes` to proceed:
 
 ```
 ◇  Installation Summary ────╮
@@ -151,11 +151,11 @@ When you see output like this, TRON MCP Server has been successfully installed t
 ```
 ◇  Installation complete
 │
-◇  Installed to 1 agent ───────╮
-│                              │
-│  ✓ Claude Code: ~/.mcp.json  │
-│                              │
-├──────────────────────────────╯
+◇  Installed to 1 agent ──────────────────╮
+│                                         │
+│  ✓ Claude Code: ~/my-project/.mcp.json  │
+│                                         │
+├─────────────────────────────────────────╯
 │
 └  Done!
 ```
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md
index 2437a124..4765bf4b 100644
--- a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md
+++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md
@@ -2,7 +2,7 @@
 
 The goal of this page is simple: **get you connected in 1 minute and make your first blockchain query.**
 
-We'll use the [official cloud service](./OfficialServerAccess.md) for this quick start. The cloud service is read-only — no dependencies to install, no wallet to configure, no API Key required. Just copy a config snippet into your AI client and start asking questions.
+We'll use the [official cloud service](./OfficialServerAccess.md) for this quick start. The cloud service is read-only — no dependencies to install, no wallet to configure, no API Key required. Just paste one install prompt into your AI Agent and start asking questions.
 
 ---
 
@@ -11,12 +11,12 @@ We'll use the [official cloud service](./OfficialServerAccess.md) for this quick
 Before you begin, make sure you have the following installed:
 
 - Any AI client that supports MCP
-- **Node.js v20.0.0 or higher** (needed for `npx` command execution) ([Node.js Download](https://nodejs.org/))
+- **Node.js** — needed to run `npx` ([Node.js Download](https://nodejs.org/)). We recommend the October 2026 security releases: 22.23.4+ (22.x) or 24.22.1+ (24.x)
 
 Verify your Node.js version:
 
 ```bash
-node --version  # should output v20.x.x or higher
+node --version  # recommended: v22.23.4+ or v24.22.1+
 ```
 
 ---
@@ -60,7 +60,7 @@ Check the TRX balance of TRON address TXyz...
 If everything is working, the AI will automatically call the `get_balance` tool and return the TRX balance of that address. Seeing a result means you've successfully connected.
 
 :::info About the Cloud Service's Capabilities
-The configuration above connects to the **official cloud read-only service**, which supports all query operations (checking balances, looking up transactions, reading contract state, etc.) but does not support write operations (transfers, contract calls, etc.). For full read/write capabilities, please refer to [Local Private Deployment](./LocalPrivatizedDeployment.md).
+The install above connects to the **official cloud read-only service**, which supports all query operations (checking balances, looking up transactions, reading contract state, etc.) but does not support write operations (transfers, contract calls, etc.). For full read/write capabilities, please refer to [Local Private Deployment](./LocalPrivatizedDeployment.md).
 :::
 
 ---
@@ -80,7 +80,7 @@ Once connected, try a few more prompts to get a feel for what TRON MCP Server ca
 | "Get the ABI of contract TXyz..." | Read a smart contract interface definition |
 | "Query the latest events triggered by contract TXyz..." | Get contract event logs |
 
-These are just the tip of the iceberg. For the full list of 97 tools and 6 prompt templates, see [Full Capability List](./ToolList.md).
+These are just the tip of the iceberg. For the full list of 97 tools and 6 prompt templates (the read-only cloud service exposes the 68 read tools and 4 of the prompts), see [Full Capability List](./ToolList.md).
 
 ---
 
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md
index 8f5b581a..af1daa13 100644
--- a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md
+++ b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md
@@ -12,11 +12,11 @@ Each tool is labeled with a **mode** — "read" or "write":
 - **Read tools**: Only query on-chain data and do not affect any state. They can be used in both cloud services and local deployments.
 - **Write tools**: Modify blockchain state (e.g., transfers, staking, contract interactions). These require a configured wallet (via [Agent Wallet](../../../Agent-Wallet/Intro.md)) to execute.
 
-Write tools are always visible in the AI’s tool list, but wallet availability is checked at execution time. If no wallet is configured, calling a write tool will return an error prompting you to set up a wallet. In **read-only mode** (cloud service or `--readonly` flag), write tools are not registered.
+Write tools are always visible in the AI’s tool list, but wallet availability is checked at execution time. If no wallet is configured, calling a write tool returns a wallet error (see [FAQ](./FAQ.md#wallet-error-messages)). In **read-only mode** (cloud service or `--readonly` flag), the 29 write tools and the 2 write prompts (`prepare_transfer`, `interact_with_contract`) are not registered, leaving 68 read tools and 4 prompts.
 :::
 
 :::tip `network` parameter
-Most tools include an optional `network` parameter used to specify the target network (`mainnet`, `nile`, or `shasta`). If not specified, the default is `mainnet`.
+Most tools include an optional `network` parameter used to specify the target network (`mainnet`, `nile`, or `shasta`; `tron` / `trx` are aliases for `mainnet` and `testnet` for `nile`). If not specified, the default is `mainnet`.
 
 During testing, it is recommended to explicitly set `nile` each time to avoid unintended operations on the mainnet.
 :::
@@ -353,6 +353,8 @@ These tools provide direct access to TRON full-node RPC methods for advanced que
 
 Prompts are pre-defined workflow templates that guide the AI through complex multi-step operations. They help ensure safety (e.g., confirming before transfers) and thoroughness (e.g., checking balance before sending).
 
+The two prompts with "Requires Wallet: Yes" are not registered in read-only mode (cloud service or `--readonly`), so read-only connections see only the other 4.
+
 | Prompt Name | Description | Key Parameters | Requires Wallet |
 | :--- | :--- | :--- | :--- |
 | `prepare_transfer` | Safely prepare and execute a token transfer with balance checks, cost estimation, and user confirmation. | `tokenType`, `recipient`, `amount`, `network`, `tokenAddress` | Yes |
@@ -376,4 +378,4 @@ Resources provide static reference data that the AI can query for context.
 
 | Resource Name | URI | Description |
 | :--- | :--- | :--- |
-| `supported_networks` | `tron://networks` | Returns the list of all supported TRON networks and their configuration (RPC URLs, explorer links, etc.). |
+| `supported_networks` | `tron://networks` | Returns the identifiers of the supported TRON networks as JSON: `{"supportedNetworks": ["mainnet", "nile", "shasta"]}`. RPC URLs and explorer links are not included. |
diff --git a/docs/Openclaw-extension/FAQ.md b/docs/Openclaw-extension/FAQ.md
index a82241e5..42fdeb61 100644
--- a/docs/Openclaw-extension/FAQ.md
+++ b/docs/Openclaw-extension/FAQ.md
@@ -10,7 +10,7 @@ Don't panic when you see an error — it's usually just a small setting that's n
 
 **In short**: Your computer doesn't have Node.js installed, or the version is too old.
 
-**How to fix**: Go to the [Node.js official website](https://nodejs.org/) and download the latest stable version (LTS, v20 or higher — `@bankofai/mcp-server-tron`, which the wizard installs, declares `node >= 20`). Install it like any regular software by clicking "Next" all the way through. Then close the terminal window and run the installation command again.
+**How to fix**: Go to the [Node.js official website](https://nodejs.org/) and download the latest stable version (LTS — the installer requires 22.23.4+ on 22.x, 24.22.1+ on 24.x, or 26.12.1+; Node.js 24 is the safest choice). Install it like any regular software by clicking "Next" all the way through. Then close the terminal window and run the installation command again.
 
 ### Error Says "command not found: git"
 
@@ -62,7 +62,7 @@ Don't panic when you see an error — it's usually just a small setting that's n
 
 ### Why Can Others Send Transfers While My AI Can Only Read Data?
 
-**Reason**: Your AI is currently in ultra-safe "read-only mode." This is because you skipped the AgentWallet configuration during installation and didn't provide it with wallet keys.
+**Reason**: Transfers and trades must be signed by a wallet in AgentWallet, and your AI can't find a usable one. The installer doesn't let you skip this step — on a first install, if `agent-wallet start` fails or is cancelled, the whole installer stops — so this usually means the wallet setup never finished, or the wallet data in `~/.agent-wallet` was reset or deleted afterwards.
 
 **How to fix**: Run the installation script again. At the AgentWallet setup level, follow the prompts carefully to properly configure your wallet. After configuring and restarting, transfer and trading functions will be activated.
 
@@ -83,7 +83,7 @@ Don't panic when you see an error — it's usually just a small setting that's n
 **How to fix**:
 
 1. **Quick fix**: Wait a few minutes before asking again.
-2. **Permanent fix**: Go to [TronGrid](https://www.trongrid.io/) and apply for a free dedicated API Key. Enter this key during installation, and AI will be able to use the VIP express lane.
+2. **Permanent fix**: Go to [TronGrid](https://www.trongrid.io/) and apply for a free dedicated API Key. The installer doesn't ask for this key — set it yourself as the `TRONGRID_API_KEY` environment variable (see [How to Add API Keys](./QuickStart.md#️-how-to-add-api-keys-vip-pass-after-installation)), restart OpenClaw, and AI will be able to use the VIP express lane.
 
 ---
 
@@ -95,7 +95,7 @@ Absolutely! When the installation wizard reaches Level 4, it will list all skill
 
 ### I'm Done With It — How Do I Uninstall?
 
-The simplest brute-force method: Open your file manager, find the `~/.openclaw/skills/` (Mac/Linux) or `%USERPROFILE%\.openclaw\skills\` (Windows) directory, delete the skill folder(s) you no longer want, then restart the AI software — they'll be completely gone.
+The simplest brute-force method: Open your file manager, find the `~/.openclaw/skills/` (Mac/Linux) or `%USERPROFILE%\.openclaw\skills\` (Windows) directory, delete the skill folder(s) you no longer want, then restart the AI software — the skills are gone. The MCP server entries, `~/.mcporter/bankofai-config.json`, the global npm packages and `~/.agent-wallet` stay. The installer's Clean mode removes the MCP entries, the installed skills, `~/.x402-config.json` and `bankofai-config.json`, then re-initialises agent-wallet (`agent-wallet reset`, then `start --override`); it does not uninstall the global npm packages.
 
 ### I Messed Everything Up — Can I Reinstall?
 
@@ -110,11 +110,11 @@ Reinstall anytime! Don't worry about breaking your computer.
 
 ### Does the Installer Need Admin Privileges?
 
-Not for the config files — those all land under your user directory, and the installer touches neither the registry nor Program Files. The one thing that reaches outside it is the pinned global install `npm install -g @bankofai/agent-wallet@<version>`. On Windows that goes to `%APPDATA%\npm` and needs no elevation; on macOS or Linux with a system-wide Node it writes to the global `node_modules` directory (for example `/usr/local/lib/node_modules`) and may ask for your password.
+Not for the config files — those all land under your user directory, and the installer touches neither the registry nor Program Files. The things that reach outside it are the pinned global npm installs: `npm install -g @bankofai/agent-wallet@<version>` (unless 2.3.1 is already installed), and `npm install --global @bankofai/x402-cli@<version>` (only when the x402-payment skill is installed). On Windows these go to `%APPDATA%\npm` and need no elevation; on macOS or Linux with a system-wide Node it writes to the global `node_modules` directory (for example `/usr/local/lib/node_modules`) and may ask for your password.
 
 ### Is the Windows Experience the Same as Mac/Linux?
 
-Identical. The Windows installer (`install.ps1`) is a full port of the Linux/macOS version (`install.sh`) — same installation flow, same multi-select menus, same config file structure. The only differences are file paths (`~/` becomes `%USERPROFILE%\`) and file permissions (`chmod 600` becomes `icacls` ACL).
+Almost. The Windows installer (`install.ps1`) is a port of the Linux/macOS version (`install.sh`) — same installation flow, same multi-select menus, same config file structure. The differences are file paths (`~/` becomes `%USERPROFILE%\`), file permissions (`chmod 600` becomes `icacls` ACL), and the OpenClaw check: if the `.openclaw` folder doesn't exist in your home directory, `install.sh` warns and asks `Continue anyway? (y/N)`, while `install.ps1` stops with an error — install OpenClaw first, then re-run it.
 
 ### Can I Use WSL (Windows Subsystem for Linux)?
 
diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md
index 9ffcdc93..34d625ab 100644
--- a/docs/Openclaw-extension/Intro.md
+++ b/docs/Openclaw-extension/Intro.md
@@ -51,7 +51,7 @@ It will digest all the boring code and data for you, and report back in the clea
 
 - **I'm a total beginner**: Perfect! Don't want to deal with code, get dizzy looking at charts, and just want to chat with AI to help you check data and make trades? This was tailor-made for you.
 - **I'm a Web3 veteran**: Tired of opening web pages and connecting wallets every day? Want a personal trading assistant on call 24/7? It can save you tons of time watching charts and checking contracts.
-- **I'm a Windows user**: No problem at all! Since v1.4.5, OpenClaw Extension natively supports Windows 10/11. One PowerShell command and you're set — the experience is identical to Mac/Linux.
+- **I'm a Windows user**: No problem at all! Since v1.4.5, OpenClaw Extension natively supports Windows 10/11. One PowerShell command and you're set — the experience is almost identical to Mac/Linux (the few differences are listed in the [FAQ](./FAQ.md)).
 
 ---
 
diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md
index 24392a77..416076d4 100644
--- a/docs/Openclaw-extension/QuickStart.md
+++ b/docs/Openclaw-extension/QuickStart.md
@@ -2,6 +2,10 @@
 
 Our goal: **Spend a few minutes following the wizard, clicking a few buttons, and get your AI to successfully fetch its first piece of on-chain data.**
 
+:::note Versions pinned by the installer
+The one-click installer currently installs **agent-wallet 2.3.1** and **Skills v1.5.15**. The wallet steps on this page therefore follow agent-wallet 2.x (master password, `local_secure` wallets), not the 3.x behavior described in the [Agent-Wallet docs](../Agent-Wallet/Intro.md).
+:::
+
 ---
 
 ## 🕹️ Prerequisites
@@ -9,7 +13,7 @@ Our goal: **Spend a few minutes following the wizard, clicking a few buttons, an
 Before you begin, make sure the following basic software is installed on your computer (if not, download and install them from their official websites just like any regular software):
 
 1. **OpenClaw**: Your AI assistant software.
-2. **Node.js** (v20 or above): the wizard installs `@bankofai/mcp-server-tron`, which declares `node >= 20`. *(Extremely important — neither installer enforces 20: the macOS/Linux script only checks that `node` exists, and the Windows script enforces only 18. An older runtime passes pre-flight and fails later.)*
+2. **Node.js** (22.23.4+ on 22.x, 24.22.1+ on 24.x, or 26.12.1+): both installers check the full version against `^22.23.4 || ^24.22.1 || >=26.12.1` and stop before installing anything if Node.js is missing or too old. *(Node.js 24 is the safest choice: it satisfies every component the wizard installs.)*
 3. **Git**: A small tool used to download skill packs.
 
 **Windows users, additional requirements:**
@@ -68,7 +72,7 @@ install.bat
 </TabItem>
 </Tabs>
 
-🚑 **First Aid: Got an error right after pressing Enter?** If the screen says `command not found: node` (Mac/Linux) or `node is not recognized` (Windows), it means your computer is missing the prerequisites mentioned above. 👉 [Click here to see how to fix it](./FAQ.md#error-says-command-not-found-node-or-npm-install-failed)
+🚑 **First Aid: Got an error right after pressing Enter?** If the screen says `Error: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 is required` (possibly followed by `found vX.Y.Z`; on Windows a similar message without `Error: ` appears under `Installation failed with error:`), it means your computer is missing the prerequisites mentioned above. 👉 [Click here to see how to fix it](./FAQ.md#error-says-command-not-found-node-or-npm-install-failed)
 
 If there are no errors, an English wizard will appear on screen. Think of it as a text-based mini-game with 4 levels:
 
@@ -102,7 +106,7 @@ If you chose `2` (Clean install), the installer lists everything that will be de
 The following data will be permanently deleted:
   • ALL MCP entries in: ~/.mcporter/mcporter.json
   • ALL installed skills (global and workspace)
-  • x402 config file: ~/.x402-config.json
+  • legacy x402 config file: ~/.x402-config.json
   • BANK OF AI local config: ~/.mcporter/bankofai-config.json
   • AgentWallet config will be overwritten by: agent-wallet start --override --save-runtime-secrets
 
@@ -115,9 +119,9 @@ After confirming, the installer automatically removes old skills:
 ```
 Running cleanup...
 
-◇  Found 10 unique installed skill(s)
+◇  Found 14 unique installed skill(s)
 ◇  Removal process complete
-◆  Successfully removed 10 skill(s)
+◆  Successfully removed 14 skill(s)
 
 ✓ Clean install cleanup completed.
 
@@ -130,7 +134,8 @@ Then runs `agent-wallet reset` to completely wipe old wallet data:
 Step 0: AgentWallet Setup
 
 Launching: agent-wallet reset
-This will delete ALL wallet data in: ~/.agent-wallet
+This will delete ALL wallet data in: /home/<you>/.agent-wallet
+   4 file(s): master.json, wallets_config.json, runtime_secrets.json, secret_<id>.json
 
 ✔ Are you sure you want to reset? This cannot be undone. Yes
 ✔ Really delete everything? Last chance! Yes
@@ -209,8 +214,12 @@ If you chose auto-generate in step ②, the master password generated for you wi
 This master password is the key to your AI's wallet. **Lose it and you lose access to the wallet.** Write it down on paper, save it in a password manager — anything but forgetting it.
 :::
 
-:::tip See "Wallet already initialized." during a Normal install upgrade?
-If you've previously installed AgentWallet and chose Normal install, the wizard skips the password setup and lets you enter a Wallet ID and generate a wallet directly. Your previous master password and existing wallets are preserved.
+:::tip Already have wallets? (Normal install upgrade)
+If AgentWallet already has wallets and you chose Normal install, the wizard first shows `Already initialized with N wallet(s), active: <id>` and asks **What would you like to do?**
+- **exit** — keep everything as is; the installer continues to the next level.
+- **add** — choose the wallet type, then unlock with your **existing** master password (`Master Password (enter your existing password to unlock)`; this prompt is skipped if the password was saved to `runtime_secrets.json` by an earlier install). After `Wallet already initialized.`, enter a new Wallet ID and generate a wallet as in steps ③–④; the new wallet becomes the active one. No new password is set.
+
+Your previous master password and existing wallets are preserved either way.
 :::
 
 (🚑 Got stuck with an error? 👉 [Click here to see how to fix AgentWallet installation failures](./FAQ.md#agentwallet-installation-failed))
@@ -272,12 +281,16 @@ Unlike TRON (which uses the encrypted AgentWallet), BNB Chain currently stores y
 
 #### bankofai-recharge (Recharge Assistant)
 
-This one is fully automatic — no input needed! It connects to BANK OF AI's remote recharge service.
+This one is fully automatic — no input needed! It registers the remote server `https://recharge.bankofai.io/mcp` (type `remote` in the add-mcp summary).
 
 ```
 ✓ Configuration saved for bankofai-recharge.
 ```
 
+:::caution The recharge MCP service is offline
+`https://recharge.bankofai.io/mcp` has been taken offline. The installer still selects and registers `bankofai-recharge` by default, but its tools no longer respond, so you can uncheck it in the MCP selection above. To top up your BANK OF AI account, use wallet-cli's [`bai recharge`](../wallet-cli/command-reference.md#bai-recharge) instead.
+:::
+
 ### 🟢 Level 4: Pick Your Skill Packs (Give AI a "Brain")
 
 First, choose where to install the skills:
@@ -294,15 +307,20 @@ Select skills installation scope:
 
 Press Enter (or type `1`) to install globally — this way all your OpenClaw workspaces can use these skills.
 
+:::note If you choose `2` (Workspace-level)
+After you pick skills in the picker below, the skills tool asks **Installation scope** (`Project` / `Global`) once more. Choose `Project` to install into a `skills/` folder inside the directory you ran the installer from (`<current directory>/skills/<skill>`); choosing `Global` installs to `~/.openclaw/skills/` anyway, but the installer then compares only the workspace list, so it prints `No new skills were installed.`, skips the API key prompt and `Next steps`, and does not install the x402 CLI. Choose `1` above if you want global skills.
+:::
+
 Then the skill picker launches:
 
 ```
-◇  Found 10 skills
+◇  Found 14 skills
 │
 ◇  Select skills to install (space to toggle)
-│  agent-wallet, bankofai-guide, recharge-skill, SunPerp Perpetual Futures Trading,
-│  SunPump Meme Token Toolkit, SunSwap DEX Trading, TronScan Data Lookup,
-│  USDD / JUST Protocol, wallet-cli, x402-payment
+│  agent-wallet, bankofai-guide, Multi-Sig & Account Permissions, recharge-skill,
+│  SunPerp Perpetual Futures Trading, SunPump Meme Token Toolkit, SunSwap DEX Trading,
+│  TRC20 Token Toolkit, TronScan Data Lookup, TRX Staking & SR Voting, twitter-digest,
+│  twitter-mcp, USDD / JUST Protocol, x402-payment
 ```
 
 Here's what each skill does:
@@ -311,50 +329,87 @@ Here's what each skill does:
 | :--- | :--- |
 | **agent-wallet** | AgentWallet management operations (view wallets, sign transactions) |
 | **bankofai-guide** | Onboarding helper that walks the AI through next steps after installation |
-| **SunSwap DEX Trading** | Swap tokens on SunSwap (TRON's biggest DEX) |
-| **SunPerp Perpetual Futures** | Trade perpetual futures on SunPerp |
+| **Multi-Sig & Account Permissions** | Manage TRON multi-sig permissions — keys, thresholds, and co-signed proposals |
+| **recharge-skill** | Check and top up your BANK OF AI balance |
+| **SunPerp Perpetual Futures Trading** | Trade perpetual futures on SunPerp |
 | **SunPump Meme Token Toolkit** | Create and trade meme tokens on SunPump; query token info, rankings, holders, and trade history |
+| **SunSwap DEX Trading** | Swap tokens on SunSwap (TRON's biggest DEX) |
+| **TRC20 Token Toolkit** | TRC20 transfers, approvals, balance queries, and token metadata |
 | **TronScan Data Lookup** | Query blockchain data via TronScan |
+| **TRX Staking & SR Voting** | Stake TRX, vote for Super Representatives, and claim voting rewards |
+| **twitter-digest** | Generate an X/Twitter daily digest (mentions, home timeline, reply opportunities) |
+| **twitter-mcp** | Install and authorize the `xurl` CLI for X/Twitter, or register the hosted X MCP bridge |
 | **USDD / JUST Protocol** | Manage USDD stablecoin and JUST Protocol positions |
-| **wallet-cli** | Standalone TRON wallet operations (transfers, staking, voting, signing) via the pinned `wallet-cli` npm package |
-| **x402-payment** | x402 protocol payments (agent-to-agent) |
-| **recharge-skill** | Check and top up your BANK OF AI balance |
+| **x402-payment** | Pay x402-protected HTTP APIs on TRON or BSC through the `x402-cli` command |
 
 After selecting, the installer shows a security risk assessment:
 
 ```
 ◇  Security Risk Assessments
 │                                     Gen               Socket            Snyk
+│  agent-wallet                       Safe              1 alert           High Risk
 │  bankofai-guide                     Safe              0 alerts          High Risk
+│  Multi-Sig & Account Permissions    --                --                --
 │  recharge-skill                     Safe              1 alert           Med Risk
 │  SunPerp Perpetual Futures Trading  --                --                --
-│  SunPump Meme Token Toolkit         --                --                --
-│  SunSwap DEX Trading                --                --                --
-│  TronScan Data Lookup               --                --                --
-│  USDD / JUST Protocol               --                --                --
-│  wallet-cli                         --                --                --
+│  ...
 │  x402-payment                       Safe              1 alert           Med Risk
-│  agent-wallet                       Safe              1 alert           High Risk
 ```
 
-Review the report, then confirm to proceed. When installation completes:
+Review the report, then answer the `Proceed with installation?` prompt with `Yes`. When installation completes:
 
 ```
-◇  Installed 10 skills
+◇  Proceed with installation?
+│  Yes
 │
-│  ✓ agent-wallet → ~/.openclaw/skills/agent-wallet
-│  ✓ bankofai-guide → ~/.openclaw/skills/bankofai-guide
-│  ✓ recharge-skill → ~/.openclaw/skills/recharge-skill
-│  ✓ SunPerp Perpetual Futures Trading → ~/.openclaw/skills/sunperp-perpetual-futures-trading
-│  ✓ SunPump Meme Token Toolkit → ~/.openclaw/skills/sunpump-meme-token-toolkit
-│  ✓ SunSwap DEX Trading → ~/.openclaw/skills/sunswap-dex-trading
-│  ✓ TronScan Data Lookup → ~/.openclaw/skills/tronscan-data-lookup
-│  ✓ USDD / JUST Protocol → ~/.openclaw/skills/usdd-just-protocol
-│  ✓ wallet-cli → ~/.openclaw/skills/wallet-cli
-│  ✓ x402-payment → ~/.openclaw/skills/x402-payment
-```
-
-After skills are installed, the installer enters a configuration phase:
+◇  Installed 14 skills
+│
+│  ✓ agent-wallet (copied)
+│    → ~/.openclaw/skills/agent-wallet
+│  ✓ bankofai-guide (copied)
+│    → ~/.openclaw/skills/bankofai-guide
+│  ✓ Multi-Sig & Account Permissions (copied)
+│    → ~/.openclaw/skills/multi-sig-account-permissions
+│  ✓ recharge-skill (copied)
+│    → ~/.openclaw/skills/recharge-skill
+│  ✓ SunPerp Perpetual Futures Trading (copied)
+│    → ~/.openclaw/skills/sunperp-perpetual-futures-trading
+│  ✓ SunPump Meme Token Toolkit (copied)
+│    → ~/.openclaw/skills/sunpump-meme-token-toolkit
+│  ✓ SunSwap DEX Trading (copied)
+│    → ~/.openclaw/skills/sunswap-dex-trading
+│  ✓ TRC20 Token Toolkit (copied)
+│    → ~/.openclaw/skills/trc20-token-toolkit
+│  ✓ TronScan Data Lookup (copied)
+│    → ~/.openclaw/skills/tronscan-data-lookup
+│  ✓ TRX Staking & SR Voting (copied)
+│    → ~/.openclaw/skills/trx-staking-sr-voting
+│  ✓ twitter-digest (copied)
+│    → ~/.openclaw/skills/twitter-digest
+│  ✓ twitter-mcp (copied)
+│    → ~/.openclaw/skills/twitter-mcp
+│  ✓ USDD / JUST Protocol (copied)
+│    → ~/.openclaw/skills/usdd-just-protocol
+│  ✓ x402-payment (copied)
+│    → ~/.openclaw/skills/x402-payment
+```
+
+#### x402 CLI (only if x402-payment is installed)
+
+If `x402-payment` is among your installed skills, the installer then installs the pinned payment CLI globally (it skips this when `x402-cli` 1.0.1 is already present):
+
+```
+Installing @bankofai/x402-cli@1.0.1...
+✓ Installed x402 CLI 1.0.1
+```
+
+This runs `npm install --global @bankofai/x402-cli@1.0.1`, so — like the AgentWallet CLI — it lands in your global npm directory rather than in an OpenClaw folder.
+
+After skills are installed, the installer compares the skill list before and after and runs a configuration phase for each skill it considers new:
+
+:::caution Only on a first install
+"New" means not present in the skill list before this run. That list covers `~/.openclaw/skills/`, the shared `~/.agents/skills/` folder and the skill folders of any other agent on the machine, so where these skills are already in one of them (for example from an earlier install) the installer prints `No new skills were installed.` after the x402 CLI step (an already-installed CLI shows `✓ x402 CLI 1.0.1 is already installed`), skips the prompts below, and the final summary shows only the MCP config file. In that case create the API key file by hand — see [How to Add API Keys](#️-how-to-add-api-keys-vip-pass-after-installation) — and set `TRONSCAN_API_KEY` yourself if you want it.
+:::
 
 #### recharge-skill API Key Configuration
 
@@ -366,9 +421,13 @@ Recharge requests use the remote BANK OF AI recharge MCP endpoint.
 ? Enter BANKOFAI_API_KEY (optional, hidden):
 ```
 
+:::caution Recharging through recharge-skill no longer works
+The remote recharge MCP endpoint that recharge-skill uses for recharges has been taken offline, so recharge requests through this skill fail. To top up, use [`wallet-cli bai recharge`](../wallet-cli/command-reference.md#bai-recharge).
+:::
+
 **Don't have one? Just press Enter to skip.** You can always create the config file later — see "[How to Add API Keys](#️-how-to-add-api-keys-vip-pass-after-installation)" below.
 
-When `Installation Complete!` lights up at the bottom of the screen — congratulations, you've passed all levels!
+When `Installation Complete!` lights up at the bottom of the screen — congratulations, you've passed all levels! The `Installed skills` list and `Next steps` below appear only when the installer detected new skills; otherwise the summary goes straight from the config-file lines to the closing `Repository:` / `Skills:` links.
 
 ```
 ═══════════════════════════════════════
@@ -382,13 +441,17 @@ When `Installation Complete!` lights up at the bottom of the screen — congratu
 ✓ Installed skills:
   • agent-wallet
   • bankofai-guide
+  • Multi-Sig & Account Permissions
   • recharge-skill
   • SunPerp Perpetual Futures Trading
   • SunPump Meme Token Toolkit
   • SunSwap DEX Trading
+  • TRC20 Token Toolkit
   • TronScan Data Lookup
+  • TRX Staking & SR Voting
+  • twitter-digest
+  • twitter-mcp
   • USDD / JUST Protocol
-  • wallet-cli
   • x402-payment
   Verify with: npx skills list -g
 
@@ -439,7 +502,7 @@ Totally get it! You were just browsing during installation and pressed Enter to
 | Key Name | What's It For? | Where to Get It for Free? |
 | :--- | :--- | :--- |
 | `TRONGRID_API_KEY` | Express lane for the TRON toolbox — without it you'll be throttled | Register for free at [trongrid.io](https://www.trongrid.io/) |
-| `TRONSCAN_API_KEY` | Required for the TronScan data lookup skill | Apply for free at [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) |
+| `TRONSCAN_API_KEY` | Optional for the TronScan Data Lookup skill — without it the skill goes through the BofAI proxy `ts.bankofai.io`; your own key gives higher rate limits | Apply for free at [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) |
 | `BANKOFAI_API_KEY` | Used for topping up or checking balance on BANK OF AI | Get it after logging in at [chat.bankofai.io/key](https://chat.bankofai.io/key) |
 
 
@@ -490,7 +553,8 @@ If you have this key, simply copy and run the following command in the terminal
 <TabItem value="mac" label="Linux / macOS" default>
 
 ```bash
-mkdir -p ~/.mcporter && echo '{"api_key": "paste_your_BANKOFAI_API_KEY_here", "base_url": "https://chat.bankofai.io/"}' > ~/.mcporter/bankofai-config.json
+mkdir -p ~/.mcporter && echo '{"api_key": "paste_your_BANKOFAI_API_KEY_here", "base_url": "https://chat.ainft.com"}' > ~/.mcporter/bankofai-config.json
+chmod 600 ~/.mcporter/bankofai-config.json   # the installer does this too; the file holds your API key
 ```
 
 </TabItem>
@@ -498,7 +562,7 @@ mkdir -p ~/.mcporter && echo '{"api_key": "paste_your_BANKOFAI_API_KEY_here", "b
 
 ```powershell
 New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.mcporter" | Out-Null
-'{"api_key": "paste_your_BANKOFAI_API_KEY_here", "base_url": "https://chat.bankofai.io/"}' | Out-File -Encoding utf8 "$env:USERPROFILE\.mcporter\bankofai-config.json"
+'{"api_key": "paste_your_BANKOFAI_API_KEY_here", "base_url": "https://chat.ainft.com"}' | Out-File -Encoding utf8 "$env:USERPROFILE\.mcporter\bankofai-config.json"
 ```
 
 </TabItem>
@@ -518,7 +582,7 @@ After installation, the following files are created on your machine. All sensiti
 | `~/.mcporter/mcporter.json` | MCP server configurations (including BNB Chain private key if provided) |
 | `~/.mcporter/bankofai-config.json` | BANK OF AI API key |
 | `~/.openclaw/skills/` | Globally installed skill packs |
-| `.openclaw/skills/` | Workspace-level skill packs (if you chose option 2) |
+| `skills/` (in the directory you ran the installer from) | Workspace-level skill packs (if you chose option 2, then `Project`) |
 | `~/.agent-wallet/` | AgentWallet encrypted wallet data |
 
 </TabItem>
@@ -529,7 +593,7 @@ After installation, the following files are created on your machine. All sensiti
 | `%USERPROFILE%\.mcporter\mcporter.json` | MCP server configurations (including BNB Chain private key if provided) |
 | `%USERPROFILE%\.mcporter\bankofai-config.json` | BANK OF AI API key |
 | `%USERPROFILE%\.openclaw\skills\` | Globally installed skill packs |
-| `.openclaw\skills\` | Workspace-level skill packs (if you chose option 2) |
+| `skills\` (in the directory you ran the installer from) | Workspace-level skill packs (if you chose option 2, then `Project`) |
 | `%USERPROFILE%\.agent-wallet\` | AgentWallet encrypted wallet data |
 
 </TabItem>
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/mcp-server.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/mcp-server.md
index 18d0e46c..da1a39ad 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/mcp-server.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/mcp-server.md
@@ -7,6 +7,40 @@ description: 'MCP Server 的版本发布记录。'
 
 MCP Server 的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### 包内容、Docker 模式与 HTTP 细节
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- npm 包包含 `build/`、`bin/`、`package.json`、`README.md` 与 `LICENSE`；Docker 镜像始终以只读模式运行（`--readonly` 写死）；`/mcp` 的 `GET` / `DELETE` 返回 405、不支持 SSE；`GET /` 返回服务信息；`tron` / `trx` / `testnet` 是可用的网络别名。
+
+👉 [本地部署](/zh-Hans/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment/) · [工具列表](/zh-Hans/McpServer-Skills/MCP/TRONMCPServer/ToolList/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-23</div>
+<div className="changelog-body">
+
+### TRON MCP Server 文档按代码更正
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **未配置 API Key 时的 RPC**——`main`（tag `v1.1.8`）中，未设置 `TRONGRID_API_KEY` 时主网请求走 `https://hptg.bankofai.io`，设置后走 `api.trongrid.io`。Nile 与 Shasta 始终使用 TronGrid 测试网节点。npm 上的 `1.1.7` 在未配置 Key 时仍使用 `api.trongrid.io`。
+- **工具与提示词**——`write_contract` 没有 `feeLimit` 参数（只有 `deploy_contract` 有）；`tron://networks` 返回 `{"supportedNetworks":[...]}`；只读模式下注册 4 个提示词，而非 6 个。
+- **钱包报错**——常见问题改为引用 agent-wallet 2.x 的真实报错文本（`resolve_wallet could not find a wallet source in config or env`、`Password required for local_secure wallets`、`No active wallet set.`、`MAC mismatch — wrong password or corrupted file`）。agent-wallet 2.3.x 和 2.4.0 都接受别名 `TRON_PRIVATE_KEY` 和 `TRON_MNEMONIC`，但只有在解析不到密码且钱包目录里没有钱包时才会读取这些环境变量，否则会静默忽略。在这条路径上同时设置了私钥和助记词时，agent-wallet 2.3.x 报 `Wallet not configured.`，2.4.0 报 `Provide only one of AGENT_WALLET_PRIVATE_KEY or AGENT_WALLET_MNEMONIC`。
+- **Node.js**——源码检出的 `v1.1.8` 要求 22.23.4+（22.x）或 24.22.1+（24.x）；`npx` 运行的 npm `1.1.7` 声明的是 `>=20`。无论哪种方式，页面都推荐 2026 年 10 月的安全更新版本。云服务快速开始页把硬性要求「Node.js v20.0.0 或更高版本」改为「需要 Node.js 以执行 `npx`」，并推荐 22.23.4+ 或 24.22.1+。
+- **Agent Wallet 安装固定到 2.x**——服务端依赖 `@bankofai/agent-wallet ^2.3.0`，但不带版本号的 `npm install -g @bankofai/agent-wallet` 现在会装上 3.0.0，它没有 `local_secure` 钱包、主密码和 `--save-runtime-secrets`。页面现改用 `npm install -g @bankofai/agent-wallet@2`，并注明 Agent-Wallet 文档描述的是 3.x。
+
+👉 [快速开始](/zh-Hans/McpServer-Skills/MCP/TRONMCPServer/QuickStart/) · [常见问题与排查](/zh-Hans/McpServer-Skills/MCP/TRONMCPServer/FAQ/) · [本地私有化部署](/zh-Hans/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-09</div>
 <div className="changelog-body">
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/openclaw-extension.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/openclaw-extension.md
index 37e1cb01..9abe6823 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/openclaw-extension.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/openclaw-extension.md
@@ -7,6 +7,39 @@ description: 'Openclaw 扩展的版本发布记录。'
 
 Openclaw 扩展的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### 安装器细节更正
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- 技能配置环节（API Key 提示、`Next steps`）只对运行前技能列表里没有的技能运行（默认的全局安装下，列表涵盖 `~/.openclaw/skills/`、`~/.agents/skills/` 和其他 Agent 的技能目录），因此重装会打印 `No new skills were installed.` 并跳过；快速开始已说明这一点并指向手动补填 API Key 的步骤。补充了 `Proceed with installation?` 提示和 `bankofai-recharge` 的远程地址。
+- Node.js 报错文字改为安装器实际输出（Windows 上没有 `Error: ` 前缀）；手动创建 `bankofai-config.json` 的步骤和安装器一样加上 `chmod 600`；Windows 改为「基本一样，差异见 FAQ」；删除 `~/.openclaw/skills/` 只会移除技能——MCP 条目、API Key 文件、全局 npm 包和 `~/.agent-wallet` 仍保留；Clean 模式会清掉 MCP 条目、技能和配置文件并重新初始化 agent-wallet，但从不卸载 npm 包。
+
+👉 [快速开始](/zh-Hans/Openclaw-extension/QuickStart/) · [常见问题](/zh-Hans/Openclaw-extension/FAQ/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-23</div>
+<div className="changelog-body">
+
+### 文档按当前安装器更正
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **更正 9 月 9 日的条目**——那条所述的安装器改动并未发布。`main` 上的安装器仍锁定 Skills `v1.5.15`（14 个 Skill，不含 `wallet-cli`）、`@bankofai/agent-wallet` 2.3.1 与 `@bankofai/mcp-server-tron` 1.1.7，并写入 `base_url: https://chat.ainft.com`。快速入门与常见问题现按这一安装器描述，页首也说明了其钱包步骤遵循 agent-wallet 2.x。
+- **文档的其他更正**——选择 `x402-payment` 时还会执行 `npm install --global @bankofai/x402-cli@1.0.1`；TronScan API Key 为可选（不填时 Skill 走 `ts.bankofai.io`）；项目级安装位置为 `<cwd>/skills/`；安装过程没有 TronGrid 提示；已有钱包时 agent-wallet 2.3.1 会先询问新增还是退出；Windows 上缺少 `~/.openclaw` 时安装器直接退出。
+- **Node.js**——两个安装器都会在安装任何内容之前，按 `^22.23.4 || ^24.22.1 || >=26.12.1` 检查完整版本号。
+
+👉 [快速开始](/zh-Hans/Openclaw-extension/QuickStart/) · [常见问题](/zh-Hans/Openclaw-extension/FAQ/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-09</div>
 <div className="changelog-body">
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Features.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Features.md
index b33b8bd3..d78ba9e8 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Features.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Features.md
@@ -18,3 +18,5 @@
 **公共组件**：共享工具程序和类型
 
 **Greenfield**：支持 Greenfield 网络上的文件管理操作，包括文件的上传、下载，以及文件和存储桶 (buckets) 的管理
+
+**Agents（ERC-8004）**：在 ERC-8004 身份注册表上注册和查询链上 AI Agent 身份（`register_erc8004_agent`、`set_erc8004_agent_uri`、`get_erc8004_agent`、`get_erc8004_agent_wallet`）
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Installation.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Installation.md
index 1f855cc0..1be43f26 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Installation.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/BSCMCPServer/Installation.md
@@ -3,7 +3,7 @@
 ### 前置要求
 
 * **bun** v1.2.10 或更高版本
-* **Node.js** v18 或更高版本（该项目自身的下限是 v17，但 BANK OF AI 工具链的其余部分要求 18+，TRON MCP 服务更要求 20+）
+* **Node.js** v17 或更高版本（上游 README 的要求；`package.json` 未声明 `engines`，项目的发布流程使用 Node.js 20）
 
 ### 快速开始
 
@@ -22,6 +22,7 @@
     * `PRIVATE_KEY`：你的钱包私钥（执行交易操作时必填）
     * `LOG_LEVEL`：设置日志级别（`DEBUG`, `INFO`, `WARN`, `ERROR`）
     * `PORT`：服务器端口号（默认：`3001` —— TRON MCP 服务的默认端口同样是 3001，本地同时运行两者时需要改掉其中一个）
+    * `BNBCHAIN_MCP_SKIP_TRANSFER_CONFIRMATION`（可选，默认 `false`）：默认情况下，转账和支付类工具只返回预览和 `confirmToken`（5 分钟内有效），不会发送交易；需再用该 token 调用 `confirm_transfer` 才会执行。设为 `true` 则立即执行
 
 4.  **安装依赖并启动开发服务器：**
     ```bash
@@ -50,8 +51,10 @@
 }
 ```
 
+> 该模板沿用上游 README。使用 `url` 配置时，客户端连接的是已在运行的服务，`env` 块不会传给服务进程：服务从自己的 `.env` 读取 `PRIVATE_KEY`。
+
 ### 使用 Web UI 测试
-使用 @modelcontextprotocol/inspector 进行测试。运行以下命令启动测试 UI：
+使用 @modelcontextprotocol/inspector 进行测试。运行以下命令启动测试 UI（该脚本通过 `npx` 运行最新版 inspector，目前要求 Node.js 22.19 及以上）：
 
 ```bash
 bun run test
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
index b64c562b..ceadf408 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
@@ -12,11 +12,15 @@
 
 这是最常见的问题。按以下顺序逐一排查：
 
-1. **检查 Node.js 版本**。TRON MCP Server 需要 v20.0.0 或更高版本：
+1. **检查 Node.js 版本**。声明的版本要求取决于你运行服务端的方式：
+   - **`npx -y @bankofai/mcp-server-tron`** 运行的是 npm 包 `1.1.7`，它声明的是 Node.js `>=20`。
+   - **源码检出**的 `main`（tag `v1.1.8`）要求 22.23.4+（22.x）或 24.22.1+（24.x）。其 `package.json` 里的版本号仍是 `1.1.7`，因此服务端上报的版本也是 `1.1.7`。
+
+   无论哪种方式，都推荐使用 2026 年 10 月的安全更新版本 22.23.4+ 或 24.22.1+：
    ```bash
-   node --version  # 应输出 v20.x.x 或更高
+   node --version  # 推荐：v22.23.4+ 或 v24.22.1+
    ```
-   如果版本太低，请先升级 Node.js。
+   如果版本低于你所用方式声明的要求，请先升级 Node.js。
 
 2. **检查 npx 是否可用**。在终端运行 `npx --version`。如果找不到命令，说明 Node.js 安装不完整，需要重新安装。
 
@@ -47,15 +51,22 @@
 
 3. **防火墙拦截**。如果你从另一台机器访问本地 HTTP 服务，检查防火墙是否允许该端口的入站连接。
 
-### 写入工具出现但返回"钱包未配置"错误
+### 写入工具出现但返回钱包错误 {#write-tools-wallet-error}
+
+从 v1.1.7 起，写入工具（转账、质押等）始终出现在 AI 的工具列表中，但会在执行时检查钱包是否已配置。如果没有可用钱包就调用写入工具，会返回类似 `Error transferring TRX: <原因>` 的错误，其中 `<原因>` 来自 Agent Wallet——各条错误的含义见下方[钱包错误信息](#wallet-error-messages)。
 
-从 v1.1.7 起，写入工具（转账、质押等）始终出现在 AI 的工具列表中，但会在执行时检查钱包是否已配置。如果没有配置钱包就调用写入工具，会返回错误提示你设置钱包。
+要启用写入操作，请配置本服务端所依赖的 Agent Wallet **2.x**：
 
-要启用写入操作，请配置 [Agent Wallet](../../../Agent-Wallet/Intro.md)：
+```bash
+npm install -g @bankofai/agent-wallet@2
+agent-wallet start local_secure --save-runtime-secrets
+```
 
-- 设置 `AGENT_WALLET_PASSWORD` 环境变量为你的主密码
+- `--save-runtime-secrets` 会把主密码写入 `~/.agent-wallet/runtime_secrets.json`；也可以改为把 `AGENT_WALLET_PASSWORD` 环境变量设为主密码
 - 可选设置 `AGENT_WALLET_DIR`（如使用自定义钱包目录）
 
+[Agent-Wallet 文档](../../../Agent-Wallet/Intro.md)描述的是 Agent Wallet 3.x，本服务端尚未使用该版本——请使用上面的 2.x 命令。
+
 配置完成后重启 AI 客户端即可。详细说明请参阅[本地私有化部署](./LocalPrivatizedDeployment.md)。
 
 :::info
@@ -66,22 +77,36 @@
 
 ## 认证与密钥问题
 
-### "钱包未配置"错误
+### 钱包错误信息 {#wallet-error-messages}
+
+TRON MCP Server 使用 [Agent Wallet](../../../Agent-Wallet/Intro.md) 进行所有钱包管理。当写入工具（或 `get_wallet_address` / `sign_message`）拿不到钱包时，错误文本会告诉你属于哪种情况：
 
-这表示尚未设置用于签名交易的钱包。TRON MCP Server 使用 [Agent Wallet](../../../Agent-Wallet/Intro.md) 进行所有钱包管理。解决方法：
+| 错误文本 | 含义 |
+| :--- | :--- |
+| `resolve_wallet could not find a wallet source in config or env` | 完全没有钱包：解析不到密码，钱包目录中没有任何钱包，且 `AGENT_WALLET_PRIVATE_KEY`、`TRON_PRIVATE_KEY`、`AGENT_WALLET_MNEMONIC`、`TRON_MNEMONIC` 都未设置。 |
+| `Password required for local_secure wallets` | 钱包目录中有钱包，但没有解析到密码——既没有 `runtime_secrets.json`，也没有 `AGENT_WALLET_PASSWORD`。 |
+| `No active wallet set.` | 解析到了密码，但钱包目录中没有任何钱包。此时私钥和助记词环境变量都会被忽略——请用 Agent Wallet 创建或导入钱包，或去掉密码以走环境变量私钥路径。 |
+| `MAC mismatch — wrong password or corrupted file` | 找到了密码，但与 keystore 不匹配（见下一节）。 |
+| `Wallet not configured.` | Agent Wallet 连配置都无法加载——例如 `runtime_secrets.json` 或 `wallets_config.json` 格式错误。使用 agent-wallet 2.3.x（源码检出按 `package-lock.json` 安装的版本）时，在走到环境变量路径时（见表格下方说明）同时设置了私钥和助记词，也会得到这条错误。 |
+| `Provide only one of AGENT_WALLET_PRIVATE_KEY or AGENT_WALLET_MNEMONIC` | 使用 agent-wallet 2.4.0（`npx -y @bankofai/mcp-server-tron`，即 npm `1.1.7`、依赖 `^2.3.0`，当前安装的版本）时，走到了环境变量路径，且同时设置了私钥（`AGENT_WALLET_PRIVATE_KEY` 或 `TRON_PRIVATE_KEY`）和助记词（`AGENT_WALLET_MNEMONIC` 或 `TRON_MNEMONIC`）。服务端会原样透传这段文本，例如 `Error transferring TRX: Provide only one of …`，或 `get_wallet_address` 返回的 `Error: Provide only one of …`。去掉其中一个即可。 |
 
-1. **安装并初始化 Agent Wallet**，参阅 [Agent-Wallet 文档](../../../Agent-Wallet/Intro.md)。
-2. **设置环境变量**：
+两个 agent-wallet 版本都从 `AGENT_WALLET_PRIVATE_KEY` 或其别名 `TRON_PRIVATE_KEY` 读取私钥，从 `AGENT_WALLET_MNEMONIC` 或其别名 `TRON_MNEMONIC` 读取助记词。只有走到环境变量路径——解析不到任何密码**且**钱包目录里一个钱包都没有——时才会读取这些变量；否则它们会被静默忽略，上面两种「同时设置」引起的错误也都不会出现。
+
+前两种情况的解决方法：
+
+1. **还没有钱包：安装并初始化 Agent Wallet 2.x**：执行 `npm install -g @bankofai/agent-wallet@2`，再执行 `agent-wallet start local_secure --save-runtime-secrets`，同时把主密码保存到 `runtime_secrets.json`。（[Agent-Wallet 文档](../../../Agent-Wallet/Intro.md)描述的是 3.x，本服务端尚未使用该版本。）
+2. **已经有钱包：让服务端能拿到密码**——导出环境变量：
    ```bash
    export AGENT_WALLET_PASSWORD='<你的主密码>'
    ```
-3. **重启 AI 客户端**使配置生效。
+   或按[本地私有化部署](./LocalPrivatizedDeployment.md)（路径 1）的方法保存到 `runtime_secrets.json`。重新执行 `agent-wallet start` 没有用：已有钱包时它只提供 `add`（创建一个新钱包并把它设为当前钱包）和 `exit`（不保存任何内容）两个选项。
+3. **重启 AI 客户端**使配置生效。服务端只解析一次钱包来源并缓存，修改钱包设置后必须重启。
 
-### "Agent Wallet 密码错误"
+### "MAC mismatch — wrong password or corrupted file" 错误
 
-`AGENT_WALLET_PASSWORD` 必须与运行 `agent-wallet start` 时生成的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。
+服务端解析到的密码（来自 `runtime_secrets.json` 或 `AGENT_WALLET_PASSWORD`）必须与运行 `agent-wallet start` 时设置的主密码完全一致。请确认钱包目录存在（`ls ~/.agent-wallet/`），如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。
 
-如果密码丢失，需要重新初始化钱包。**警告：此操作会清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始——详见 [CLI 命令行手册 → 重置](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset重置所有数据)和 [Agent-Wallet 常见问题](../../../Agent-Wallet/FAQ.md)。
+如果密码丢失，需要重新初始化钱包。**警告：此操作会清除所有钱包和密钥——请务必提前转移资金或备份助记词。** 运行 `agent-wallet reset` 清除并重新开始。在 agent-wallet 2.x（本服务使用的版本）中，`reset` 会删除 `~/.agent-wallet` 里的所有文件——`master.json`、`wallets_config.json`、`runtime_secrets.json` 以及 `secret_*.json` 密钥库。Agent-Wallet 文档描述的是 3.x，其 `reset` 只删除 `wallets_config.json`。
 
 ### TronGrid API Key 不生效
 
@@ -115,7 +140,7 @@
 **怎么解决：**
 - 先预估费用："预估调用这个合约的 transfer 函数需要多少能量"
 - 质押 TRX 换取能量："质押 500 TRX 获取能量"
-- 如果使用 `write_contract`，可以让 AI 提高 `feeLimit` 参数
+- `write_contract` 没有手续费上限参数，请确保钱包有足够 TRX 燃烧以补足能量缺口。只有 `deploy_contract` 接受 `feeLimit`（单位 Sun，默认 1,000,000,000 = 1000 TRX），部署大合约时可以让 AI 调高它
 
 ### "账户不存在"或"账户未激活"
 
@@ -158,7 +183,7 @@ AI 可能将 TRON MCP Server 的能力与其他区块链工具混淆。如果它
 
 几种常见原因和对策：
 
-- **没有 TronGrid API Key**：公共 RPC 有频率限制，添加免费的 API Key 可以显著改善
+- **没有 TronGrid API Key**：未设置 `TRONGRID_API_KEY` 时，`v1.1.8` 起的源码检出中主网请求走 BANK OF AI 回退节点 `https://hptg.bankofai.io`，npm `1.1.7`（`npx` 运行的版本）则不带 Key 访问 `https://api.trongrid.io`。配置免费的 API Key 后，两个版本都会以你自己的配额访问 `https://api.trongrid.io`
 - **复杂的多工具工作流**：某些操作（如钱包全貌分析）需要多个串行调用，等待是正常的
 - **使用测试网开发**：Nile 和 Shasta 测试网通常响应更快
 - **提示词更明确**：减少 AI 的探索性调用——直接告诉它用哪个工具、查哪个网络
@@ -183,7 +208,13 @@ AI 可能将 TRON MCP Server 的能力与其他区块链工具混淆。如果它
 
 ### 如何更新到最新版本？
 
-如果你使用的是 `npx` 方式运行，每次都会自动获取最新发布版本。若要强制刷新缓存：
+如果你使用的是 `npx` 方式运行，`npx -y @bankofai/mcp-server-tron` 并不一定会拉取最新版本：它可能直接运行已安装的副本——全局安装的、当前项目里的，或者在较旧的 npm 版本上 npx 缓存里的。要始终获取最新发布版本，请显式指定，例如在 MCP 客户端配置中使用：
+
+```bash
+npx -y @bankofai/mcp-server-tron@latest
+```
+
+也可以清除 npx 缓存：删除 `~/.npm/_npx`（必要时再执行 `npm cache clean --force`）。第三方包 `clear-npx-cache` 的作用相同：
 
 ```bash
 npx clear-npx-cache
@@ -200,6 +231,6 @@ npm run build
 
 ### 支持哪个 MCP 协议版本？
 
-TRON MCP Server 支持 MCP 协议版本 **2025-11-25**，使用 `@modelcontextprotocol/sdk` 1.22.0 或更高版本。
+协议版本由 `@modelcontextprotocol/sdk` 协商决定，服务端对它的依赖是 `^1.22.0`；源码检出的 `package-lock.json` 锁定为 1.27.1。MCP 协议版本 **2025-11-25** 需要 SDK 1.24.1 或更高版本——SDK 1.22.0–1.24.0 最高只支持 2025-06-18。客户端请求的更早协议版本同样可以使用。
 
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md
index 8ec6b500..f23d69aa 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md
@@ -17,7 +17,7 @@ TRON MCP Server 是连接 AI 助手与 TRON 区块链的桥梁。它基于 [Mode
 
 ## 它能做什么？
 
-TRON MCP Server 覆盖了 TRON 区块链上几乎所有常见操作，从只读查询到资产管理，共提供 **97 个工具**、**6 个提示词模板**和 **1 个资源定义**。
+TRON MCP Server 覆盖了 TRON 区块链上几乎所有常见操作，从只读查询到资产管理，共提供 **97 个工具**、**6 个提示词模板**和 **1 个资源定义**。在只读模式（官方云服务或 `--readonly`）下，写入工具和 2 个写入类提示词模板不会被注册，只剩 68 个读取工具和 4 个提示词模板。
 
 以下是核心能力概览——每一项都可以通过自然语言触发：
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
index 72e6dace..ee3a696a 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
@@ -29,15 +29,17 @@
 
 | 要求 | 说明 |
 | :--- | :--- |
-| **Node.js** | v20.0.0 或更高版本（[下载](https://nodejs.org/)） |
+| **Node.js** | 推荐 22.23.4+（22.x）或 24.22.1+（24.x），即 2026 年 10 月的安全更新版本（[下载](https://nodejs.org/)）。源码检出的 `main`（tag `v1.1.8`，即下文方式 B）要求这一范围（其 `package.json` 里的版本号仍是 `1.1.7`，因此服务端上报的版本也是 `1.1.7`）；`npx` 运行的 npm 包 `1.1.7`（方式 A）声明的是 `>=20`。 |
 | **TronGrid API Key** | 可选但推荐（[申请地址](https://www.trongrid.io/)） |
 
 验证 Node.js 版本：
 
 ```bash
-node --version  # 应输出 v20.x.x 或更高
+node --version  # 推荐：v22.23.4+ 或 v24.22.1+
 ```
 
+这一要求写在 `package.json` 的 `engines` 字段里：在源码检出中用其他 Node.js 版本执行 `npm install`，会打印 `EBADENGINE` 警告但仍会完成安装；服务端运行时也不会检查 Node.js 版本。
+
 ### 安全原则
 
 在配置钱包之前，请务必理解以下安全原则：
@@ -50,7 +52,7 @@ node --version  # 应输出 v20.x.x 或更高
 ## 安装步骤
 ### 第一步：配置钱包
 
-钱包决定了 AI 助手以哪个身份执行链上操作。TRON MCP Server 使用 [Agent Wallet](../../../Agent-Wallet/Intro.md) 进行安全的钱包管理。如果没有配置钱包，写入工具会在执行时返回错误提示你设置钱包。
+钱包决定了 AI 助手以哪个身份执行链上操作。TRON MCP Server 使用 [Agent Wallet](../../../Agent-Wallet/Intro.md) 进行安全的钱包管理。如果没有配置钱包，调用写入工具时会返回钱包错误（见[常见问题](./FAQ.md#write-tools-wallet-error)）。
 
 #### Agent Wallet
 
@@ -63,34 +65,38 @@ TRON MCP Server 使用 [Agent Wallet](../../../Agent-Wallet/Intro.md) 管理钱
 | 运行时切换钱包 | 是 |
 | 推荐场景 | 所有使用场景 |
 
-> Agent Wallet 的安装、初始化及详细用法请参阅 [Agent-Wallet 文档](../../../Agent-Wallet/Intro.md)。
+> TRON MCP Server 依赖 Agent Wallet **2.x**（`@bankofai/agent-wallet ^2.3.0`）。[Agent-Wallet 文档](../../../Agent-Wallet/Intro.md)描述的是 3.x，本服务端尚未使用该版本——请按本页的 2.x 命令操作。
 
-首先，安装 Agent Wallet：
+首先，安装 Agent Wallet 2.x CLI：
 
 ```bash
-npm install -g @bankofai/agent-wallet
+npm install -g @bankofai/agent-wallet@2
 ```
 
+`@2` 会安装最新的 2.x 版本（撰写时为 2.4.0）。不加版本号时 npm 会安装 3.x，它没有 `local_secure` 钱包、主密码和 `--save-runtime-secrets`，下面的步骤将无法使用。
+
 然后，根据你的情况选择以下两种路径之一：
 
 #### 路径 1：生成新钱包（推荐新用户使用）
 
-如果你没有现成的私钥，使用 `agent-wallet start` 生成新钱包，包含加密密钥库和主密码：
+如果你没有现成的私钥，使用 `agent-wallet start local_secure` 生成新钱包，包含加密密钥库和主密码：
 
 ```bash
-agent-wallet start
+agent-wallet start local_secure --save-runtime-secrets
 ```
 
-按照交互式提示设置主密码并生成钱包。Agent Wallet 会自动管理加密密钥库，但服务端在签名时仍然需要这个密码——而直接跑 `agent-wallet start` 并不会持久化它。请二选一：
+按照交互式提示设置主密码并生成钱包。Agent Wallet 会自动管理加密密钥库，但服务端在签名时仍然需要这个密码。`--save-runtime-secrets` 会把它写入 `~/.agent-wallet/runtime_secrets.json`；不加这个参数时密码不会被持久化，你需要改为在 MCP 服务端运行的环境里 export `AGENT_WALLET_PASSWORD`。
+
+如果你已经不带这个参数执行过 `agent-wallet start`，不要为此重新执行它：已有钱包时它只提供 `add`（创建一个新钱包并把它设为当前钱包）和 `exit`（不保存任何内容）两个选项。请 export `AGENT_WALLET_PASSWORD`，或用下面任一命令保存密码：
 
-- 执行 `agent-wallet start --save-runtime-secrets`，把密码写入 `~/.agent-wallet/runtime_secrets.json`；或
-- 在 MCP 服务端运行的环境里 export `AGENT_WALLET_PASSWORD`。
+- `agent-wallet sign msg hello -n tron --save-runtime-secrets`——询问密码并保存，然后用当前钱包签一条测试消息。它在校验密码之前就会保存，所以如果输出 `Wrong password`，请删除 `~/.agent-wallet/runtime_secrets.json` 后重试。
+- `agent-wallet add local_secure --save-runtime-secrets`——先校验密码再保存，但同时会多创建一个钱包（当前钱包不变）。
 
-两者都没有时，调用写操作工具会因为无法解锁 `local_secure` 钱包而失败。密钥库不在 `~/.agent-wallet` 时请用 `AGENT_WALLET_DIR` 指定。
+既没有保存也没有导出密码时，调用写操作工具会因为无法解锁 `local_secure` 钱包而失败。密钥库不在 `~/.agent-wallet` 时请用 `AGENT_WALLET_DIR` 指定。
 
 #### 路径 2：导入已有私钥
 
-如果你已经有想使用的私钥，通过 `AGENT_WALLET_PRIVATE_KEY` 环境变量设置。注意优先级：只有在**解析不到任何密码**（既没有 `runtime_secrets.json`，也没有 `AGENT_WALLET_PASSWORD`）**且**钱包目录里一个钱包都没有时，才会走到这条环境变量路径。如果你已经执行过「路径 1」、保存过运行时密码，或跑过 Openclaw 安装器，密钥库路径会优先生效，该变量会被静默忽略。
+如果你已经有想使用的私钥，通过 `AGENT_WALLET_PRIVATE_KEY` 环境变量设置（Agent Wallet 也接受别名 `TRON_PRIVATE_KEY`，以及通过 `AGENT_WALLET_MNEMONIC` 或 `TRON_MNEMONIC` 设置助记词）。注意优先级：只有在**解析不到任何密码**（既没有 `runtime_secrets.json`，也没有 `AGENT_WALLET_PASSWORD`）**且**钱包目录里一个钱包都没有时，才会走到这条环境变量路径。如果你已经执行过「路径 1」、保存过运行时密码，或跑过 Openclaw 安装器，密钥库路径会优先生效，这些变量会被静默忽略。
 
 ```bash
 export AGENT_WALLET_PRIVATE_KEY=你的私钥
@@ -120,14 +126,22 @@ echo $AGENT_WALLET_PRIVATE_KEY
 
 #### TronGrid API Key
 
-TRON 主网公共 RPC 有严格的频率限制。对于频繁的链上查询，强烈建议配置一个免费的 TronGrid API Key：
+在 `v1.1.8` 起的源码检出中，API Key 还决定了服务端访问哪个主网节点。对于频繁的链上查询，建议配置一个免费的 TronGrid API Key：
 
 ```bash
 # 添加到 ~/.zshrc 或 ~/.bashrc
 export TRONGRID_API_KEY="<你的-TronGrid-API-Key>"
 ```
 
-在 [trongrid.io](https://www.trongrid.io/) 免费注册即可获取。不配置也能使用，但高频操作时可能会遇到限速错误。测试网（Nile、Shasta）受限速影响较小。
+在 [trongrid.io](https://www.trongrid.io/) 免费注册即可获取。该变量对各网络的影响（各版本唯一的差别在于未配置 Key 时的主网）：
+
+| 网络 | 已设置 `TRONGRID_API_KEY` | 未设置 `TRONGRID_API_KEY` |
+| :--- | :--- | :--- |
+| **Mainnet** | `https://api.trongrid.io`，并以 `TRON-PRO-API-KEY` 请求头携带你的 Key（使用你自己的配额） | `v1.1.8` 起的源码检出：回退到 BANK OF AI 节点 `https://hptg.bankofai.io`。npm `1.1.7`（`npx` 运行的版本）：不带 Key 访问 `https://api.trongrid.io` |
+| **Nile** | `https://nile.trongrid.io`（同样携带 Key 请求头） | `https://nile.trongrid.io` |
+| **Shasta** | `https://api.shasta.trongrid.io`（同样携带 Key 请求头） | `https://api.shasta.trongrid.io` |
+
+不配置 Key 也能正常使用，但不带 Key 发往 TronGrid 的请求（npm `1.1.7` 的主网，以及 Nile / Shasta）共用 TronGrid 的公共限流，高频使用时可能遇到限流错误。如果希望主网请求走 TronGrid 并使用你自己的配额，再配置即可。
 
 ---
 
@@ -137,7 +151,7 @@ export TRONGRID_API_KEY="<你的-TronGrid-API-Key>"
 
 #### 方式 A：npx 直接运行（推荐）
 
-无需克隆仓库，通过 `npx` 直接运行最新版本。这也是下方 MCP 客户端配置示例中默认采用的方式。
+无需克隆仓库，通过 `npx` 直接运行最新版本。这也是下文[配置说明](#配置说明)中使用的命令。
 
 ```bash
 npx -y @bankofai/mcp-server-tron
@@ -172,7 +186,7 @@ npx -y @bankofai/mcp-server-tron --http
 npm run start:http
 ```
 
-这会启动一个本地无状态 Streamable HTTP 服务器（默认：`http://localhost:3001/mcp`），每个请求独立处理，不维护会话状态。
+这会启动一个本地无状态 Streamable HTTP 服务器（默认：`http://localhost:3001/mcp`），对 `/mcp` 的 `GET` 和 `DELETE` 返回 `405`（不支持 SSE），`GET /` 返回服务信息。每个请求独立处理，不维护会话状态。
 
 你可以通过环境变量自定义端口和主机：
 
@@ -181,11 +195,11 @@ export MCP_PORT=3001      # 默认：3001
 export MCP_HOST=0.0.0.0   # 默认：0.0.0.0
 ```
 
-Docker 与源码检出的启动脚本还会读取 `MCP_LOG_DIR`（容器内默认 `/app/logs`，源码检出默认 `./logs`）。已发布的 npm 包只包含 `build/` 与 `bin/`，因此该变量不适用于上面的 `npx` 方式。
+Docker 与源码检出的启动脚本还会读取 `MCP_LOG_DIR`（容器内默认 `/app/logs`，源码检出默认 `./logs`）。已发布的 npm 包只包含 `build/`、`bin/`、`package.json`、`README.md` 与 `LICENSE`，因此该变量不适用于上面的 `npx` 方式。
 
 #### 方式 D：Docker 部署
 
-在 Docker 容器中运行 TRON MCP Server，适合隔离、可重现的环境。Docker 镜像默认以**只读 HTTP 模式**运行。
+在 Docker 容器中运行 TRON MCP Server，适合隔离、可重现的环境。Docker 镜像始终以**只读 HTTP 模式**运行：`docker-start.sh` 固定传入 `--readonly`，没有关闭它的开关。
 
 ```bash
 # 1. 创建 .env 文件存放敏感变量（切勿将此文件提交到版本控制）
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md
index 335d85ec..ab971335 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md
@@ -85,7 +85,7 @@ AI 给出 ✅ 确认后，TRON MCP Server 就已就位，可以直接开始提
 npx add-mcp https://tron-mcp-server.bankofai.io/mcp -y
 ```
 
-`-y` 参数会跳过所有交互选择，自动安装到你电脑上检测到的所有 AI 工具中。安装完成后会显示 ✅ 安装完成！以及安装到了哪些 Agent。
+`-y` 参数会跳过所有交互选择。add-mcp 随后在当前目录写入项目级配置：写给它在当前目录检测到的 AI 工具（依据 `.claude`、`.cursor`、`.vscode`、`.mcp.json` 等标志性文件夹和文件）；一个都没检测到时，则写给所有支持项目配置的工具。完成后会打印 `Installation complete` 以及安装到了哪些 Agent。
 
 安装完成后，即可使用 TRON MCP Server 开始与 TRON 区块链交互。
 
@@ -117,7 +117,7 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp
 
 **2️⃣ 选择要安装到哪些 AI 工具**
 
-安装器会自动检测你电脑上装了哪些 AI 工具（如 Claude Code、Cursor、Cline 等），用空格键勾选你要用的：
+安装器会根据当前目录里的标志性文件夹和文件（如 `.claude`、`.cursor`、`.vscode`、`.mcp.json`）检测 AI 工具，例如 Claude Code、Cursor。用空格键勾选你要用的：
 
 ```
 ◇  Detected 1 agent
@@ -128,7 +128,7 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp
 
 **3️⃣ 确认安装信息**
 
-安装器会展示安装摘要，确认无误后选择 `Yes` 开始安装：
+如果勾选的工具都同时支持项目级和全局配置，安装器会先问 **Installation scope**（`Project` / `Global`），下面的摘要对应 `Project`。随后安装器会展示安装摘要，确认无误后选择 `Yes` 开始安装：
 
 ```
 ◇  Installation Summary ────╮
@@ -151,11 +151,11 @@ npx add-mcp https://tron-mcp-server.bankofai.io/mcp
 ```
 ◇  Installation complete
 │
-◇  Installed to 1 agent ───────╮
-│                              │
-│  ✓ Claude Code: ~/.mcp.json  │
-│                              │
-├──────────────────────────────╯
+◇  Installed to 1 agent ──────────────────╮
+│                                         │
+│  ✓ Claude Code: ~/my-project/.mcp.json  │
+│                                         │
+├─────────────────────────────────────────╯
 │
 └  Done!
 ```
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md
index b4c52239..c6595e71 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md
@@ -2,7 +2,7 @@
 
 这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次区块链查询。**
 
-我们会使用[官方云服务](./OfficialServerAccess.md)来完成这次快速体验。云服务是只读的，不需要安装任何依赖、不需要配置钱包、不需要申请 API Key——你只需要把一段配置复制到 AI 客户端，就能开始提问。
+我们会使用[官方云服务](./OfficialServerAccess.md)来完成这次快速体验。云服务是只读的，不需要安装任何依赖、不需要配置钱包、不需要申请 API Key——你只需要把一段安装提示词粘贴给 AI Agent，就能开始提问。
 
 ---
 
@@ -11,12 +11,12 @@
 在开始之前，确保你已经安装了以下工具：
 
 - 所有支持 MCP 的 AI 客户端
-- **Node.js v20.0.0 或更高版本**（用于执行 `npx` 命令）（[Node.js 下载](https://nodejs.org/)）
+- **Node.js**——用于执行 `npx` 命令（[Node.js 下载](https://nodejs.org/)）。推荐使用 2026 年 10 月的安全更新版本：22.23.4+（22.x）或 24.22.1+（24.x）
 
 验证 Node.js 版本：
 
 ```bash
-node --version  # 应输出 v20.x.x 或更高
+node --version  # 推荐：v22.23.4+ 或 v24.22.1+
 ```
 
 ---
@@ -60,7 +60,7 @@ AI 给出 ✅ 确认后，TRON MCP Server 就已就位，可以直接开始提
 如果一切正常，AI 会自动调用 `get_balance` 工具并返回该地址的 TRX 余额。看到结果，说明你已经成功接入了。
 
 :::info 关于云服务的能力范围
-以上配置连接的是**官方云只读服务**，支持所有查询类操作（查余额、查交易、查合约状态等），但不支持写操作（转账、合约调用等）。如需完整的读写功能，请参阅[本地私有化部署](./LocalPrivatizedDeployment.md)。
+以上安装连接的是**官方云只读服务**，支持所有查询类操作（查余额、查交易、查合约状态等），但不支持写操作（转账、合约调用等）。如需完整的读写功能，请参阅[本地私有化部署](./LocalPrivatizedDeployment.md)。
 :::
 
 ---
@@ -80,7 +80,7 @@ AI 给出 ✅ 确认后，TRON MCP Server 就已就位，可以直接开始提
 | "获取合约 TXyz... 的 ABI" | 读取智能合约接口定义 |
 | "查询合约 TXyz... 最近触发的事件" | 获取合约事件日志 |
 
-这些只是冰山一角。完整的 97 个工具和 6 个提示词模板，请查阅 [完整能力清单](./ToolList.md)。
+这些只是冰山一角。完整的 97 个工具和 6 个提示词模板（只读云服务提供其中 68 个读取工具和 4 个提示词模板），请查阅 [完整能力清单](./ToolList.md)。
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md
index 9a26450f..8f7ea9c0 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md
@@ -12,11 +12,11 @@ TRON MCP Server 提供 **97 个工具**、**6 个提示词模板**和 **1 个资
 - **读取工具**：只查询链上数据，不影响任何状态。在云服务和本地部署中均可使用。
 - **写入工具**：会修改区块链状态（转账、质押、合约调用等）。执行时需要已配置的钱包（通过 [Agent Wallet](../../../Agent-Wallet/Intro.md)）。
 
-写入工具始终会出现在 AI 的可用工具列表中，但会在执行时检查钱包是否已配置。如果没有配置钱包，调用写入工具会返回错误提示你设置钱包。在**只读模式**（云服务或 `--readonly` 标志）下，写入工具不会被注册。
+写入工具始终会出现在 AI 的可用工具列表中，但会在执行时检查钱包是否已配置。如果没有配置钱包，调用写入工具会返回钱包错误（见[常见问题](./FAQ.md#wallet-error-messages)）。在**只读模式**（云服务或 `--readonly` 标志）下，29 个写入工具和 2 个写入类提示词模板（`prepare_transfer`、`interact_with_contract`）不会被注册，只剩 68 个读取工具和 4 个提示词模板。
 :::
 
 :::tip network 参数
-大多数工具都有一个可选的 `network` 参数，用于指定目标网络（`mainnet`、`nile` 或 `shasta`）。不指定时默认走主网。在测试阶段，建议每次都明确指定 `nile`，避免意外操作主网。
+大多数工具都有一个可选的 `network` 参数，用于指定目标网络（`mainnet`、`nile` 或 `shasta`；`tron` / `trx` 等同于 `mainnet`，`testnet` 等同于 `nile`）。不指定时默认走主网。在测试阶段，建议每次都明确指定 `nile`，避免意外操作主网。
 :::
 
 ---
@@ -341,6 +341,8 @@ TRON 的链上治理机制——超级代表可以创建和投票表决网络参
 
 工具是单个操作，而提示词模板是**预定义的多步工作流**。当你触发一个提示词时，AI 会按照预设的流程串联多个工具来完成任务——比如转账前先检查余额、预估费用、请你确认，然后才执行。
 
+"是否需要钱包"为"是"的 2 个提示词模板在只读模式（云服务或 `--readonly`）下不会被注册，只读连接只能看到其余 4 个。
+
 | 提示词名称 | 描述 | 关键参数 | 是否需要钱包 |
 | :--- | :--- | :--- | :--- |
 | `prepare_transfer` | 安全准备和执行代币转账，含余额检查、费用预估和用户确认 | `tokenType`, `recipient`, `amount`, `network`, `tokenAddress` | 是 |
@@ -364,4 +366,4 @@ TRON 的链上治理机制——超级代表可以创建和投票表决网络参
 
 | 资源名称 | URI | 描述 |
 | :--- | :--- | :--- |
-| `supported_networks` | `tron://networks` | 返回所有支持的 TRON 网络及其配置信息（RPC 地址、浏览器链接等） |
+| `supported_networks` | `tron://networks` | 以 JSON 返回支持的 TRON 网络标识：`{"supportedNetworks": ["mainnet", "nile", "shasta"]}`，不包含 RPC 地址或浏览器链接 |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md
index 1a4cf6f4..ca2d1c95 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md
@@ -10,7 +10,7 @@
 
 **简单来说**：你的电脑上没装 Node.js，或者版本太老了。
 
-**怎么解决**：去 [Node.js 官网](https://nodejs.org/) 下载最新的稳定版（LTS，v20 或更高——向导安装的 `@bankofai/mcp-server-tron` 声明了 `node >= 20`），像装普通软件一样一路点"下一步"装好。然后关掉终端里的黑框框，重新运行一次安装口令。
+**怎么解决**：去 [Node.js 官网](https://nodejs.org/) 下载最新的稳定版（LTS——安装器要求 22.x 为 22.23.4+、24.x 为 24.22.1+，或 26.12.1+；推荐选 Node.js 24），像装普通软件一样一路点"下一步"装好。然后关掉终端里的黑框框，重新运行一次安装口令。
 
 ### 报错里写着 "command not found: git"
 
@@ -62,7 +62,7 @@
 
 ### 凭什么别人能转账，我的 AI 只能查数据？
 
-**原因**：你现在的 AI 是极度安全的"只读模式"。因为你在安装时跳过了 AgentWallet 配置，没有给它留钱包钥匙。
+**原因**：转账和交易都需要 AgentWallet 里的钱包来签名，而你的 AI 找不到可用的钱包。安装器并不允许跳过这一步——首次安装时如果 `agent-wallet start` 失败或被取消，整个安装器都会直接退出——所以这通常说明钱包配置没有走完，或者之后 `~/.agent-wallet` 里的钱包数据被重置或删除了。
 
 **怎么解决**：重新跑一次安装脚本，在 AgentWallet 设置那一关跟着提示认真把钱包配好。配好并重启后，转账和交易功能就会被激活。
 
@@ -83,7 +83,7 @@
 **怎么解决**：
 
 1. **治标**：歇几分钟再问。
-2. **治本**：去 [TronGrid](https://www.trongrid.io/) 免费申请一个专属的 API Key。安装时把这个 Key 填进去，AI 就能跑 VIP 高速通道了。
+2. **治本**：去 [TronGrid](https://www.trongrid.io/) 免费申请一个专属的 API Key。安装器不会询问这个 Key——请自己把它设为环境变量 `TRONGRID_API_KEY`（见「[事后怎么补填 API Key](./QuickStart.md#️-事后怎么补填-api-keyvip-通行证)」），重启 OpenClaw 后，AI 就能跑 VIP 高速通道了。
 
 ---
 
@@ -95,7 +95,7 @@
 
 ### 玩腻了，怎么卸载它们？
 
-最简单粗暴的方法：打开电脑的文件夹，找到 `~/.openclaw/skills/`（Mac/Linux）或 `%USERPROFILE%\.openclaw\skills\`（Windows）目录，把你不想用的技能文件夹直接删掉，然后重启 AI 软件，它就彻底消失了。
+最简单粗暴的方法：打开电脑的文件夹，找到 `~/.openclaw/skills/`（Mac/Linux）或 `%USERPROFILE%\.openclaw\skills\`（Windows）目录，把你不想用的技能文件夹直接删掉，然后重启 AI 软件，技能就没了。MCP 服务条目、`~/.mcporter/bankofai-config.json`、全局 npm 包和 `~/.agent-wallet` 仍会保留。安装器的 Clean 模式会清掉 MCP 条目、已装技能、`~/.x402-config.json` 和 `bankofai-config.json`，并重新初始化 agent-wallet（先 `agent-wallet reset`，再 `start --override`）；它不会卸载全局 npm 包。
 
 ### 我瞎填了一通装坏了，能重新装吗？
 
@@ -110,11 +110,11 @@
 
 ### 安装需要管理员权限吗？
 
-配置文件不需要——它们都写在当前用户目录下，安装器也不会碰注册表或 Program Files。唯一会写到用户目录之外的是带版本号的全局安装 `npm install -g @bankofai/agent-wallet@<版本>`。在 Windows 上它会装到 `%APPDATA%\npm`，无需提权；在 macOS 或 Linux 上若 Node 是系统级安装，则会写入全局 `node_modules` 目录（例如 `/usr/local/lib/node_modules`），可能要求输入密码。
+配置文件不需要——它们都写在当前用户目录下，安装器也不会碰注册表或 Program Files。会写到用户目录之外的是带版本号的全局 npm 安装：`npm install -g @bankofai/agent-wallet@<版本>`（已装有 2.3.1 时跳过），以及 `npm install --global @bankofai/x402-cli@<版本>`（仅在装了 x402-payment 技能时执行）。在 Windows 上它们会装到 `%APPDATA%\npm`，无需提权；在 macOS 或 Linux 上若 Node 是系统级安装，则会写入全局 `node_modules` 目录（例如 `/usr/local/lib/node_modules`），可能要求输入密码。
 
 ### Windows 和 Mac/Linux 的安装体验一样吗？
 
-一模一样。Windows 安装器 (`install.ps1`) 是 Linux/macOS 版本 (`install.sh`) 的完整移植——相同的安装流程、相同的多选菜单、相同的配置文件结构。唯一的区别是文件路径从 `~/` 变成了 `%USERPROFILE%\`，文件权限从 `chmod 600` 变成了 `icacls` ACL。
+基本一样。Windows 安装器 (`install.ps1`) 是 Linux/macOS 版本 (`install.sh`) 的移植——相同的安装流程、相同的多选菜单、相同的配置文件结构。区别在于：文件路径从 `~/` 变成了 `%USERPROFILE%\`，文件权限从 `chmod 600` 变成了 `icacls` ACL；另外是 OpenClaw 检查——如果你的用户目录下没有 `.openclaw` 文件夹，`install.sh` 会给出警告并询问 `Continue anyway? (y/N)`，而 `install.ps1` 会直接报错退出，需要先装好 OpenClaw 再重新运行。
 
 ### 可以用 WSL (Windows Subsystem for Linux) 安装吗？
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md
index 1328d586..86686b83 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md
@@ -51,7 +51,7 @@ OpenClaw Extension 的出现，是为了让你的 Web3 体验从"每步都要亲
 
 - **我是纯小白玩家**：太棒了！不想折腾代码，看图表就头晕，只想用平时聊天的方式让 AI 帮忙查数据、做交易，这就是为你量身定制的。
 - **我是 Web3 老手**：懒得天天开网页连钱包，想拥有一个随叫随到的私人交易助理，它能帮你省下大把盯盘和查合约的时间。
-- **我是 Windows 用户**：完全没问题！v1.4.5 起原生支持 Windows 10/11，PowerShell 搞定安装，体验和 Mac/Linux 一模一样。
+- **我是 Windows 用户**：完全没问题！v1.4.5 起原生支持 Windows 10/11，PowerShell 搞定安装，体验和 Mac/Linux 基本一样（少数差异见[常见问题](./FAQ.md)）。
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md
index f5e55529..a80e1775 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md
@@ -2,6 +2,10 @@
 
 我们的目标是：**花几分钟跟着向导点几下，让你的 AI 成功查到第一笔链上数据。**
 
+:::note 安装器锁定的版本
+一键安装器目前安装的是 **agent-wallet 2.3.1** 和 **Skills v1.5.15**。因此本页的钱包步骤遵循 agent-wallet 2.x（主密码、`local_secure` 钱包），而不是 [Agent-Wallet 文档](../Agent-Wallet/Intro.md)中介绍的 3.x 行为。
+:::
+
 ---
 
 ## 🕹️ 准备工作
@@ -9,7 +13,7 @@
 在开始之前，请确保你的电脑上已经装好了以下几种基础软件（如果没有，请像装普通软件一样去官网下载安装）：
 
 1. **OpenClaw**：你的 AI 助手软件。
-2. **Node.js**（v20 或以上）：安装向导会装 `@bankofai/mcp-server-tron`，它声明了 `node >= 20`。*（极其重要——两个安装器都不强制 20：macOS/Linux 脚本只检查 `node` 是否存在，Windows 脚本也只强制 18。版本过低会通过预检但在后面报错。）*
+2. **Node.js**（22.x 需 22.23.4+，24.x 需 24.22.1+，或 26.12.1+）：两个安装器都会按 `^22.23.4 || ^24.22.1 || >=26.12.1` 检查完整版本号，未安装或版本过低会在安装任何内容之前直接报错退出。*（推荐 Node.js 24：它能满足安装向导所装的全部组件。）*
 3. **Git**：用来下载技能包的小工具。
 
 **Windows 用户额外注意：**
@@ -68,7 +72,7 @@ install.bat
 </TabItem>
 </Tabs>
 
-🚑 **急救包：敲完回车就报错了？** 如果屏幕提示 `command not found: node`（Mac/Linux）或 `node is not recognized`（Windows），说明你的电脑缺少上面说的基础环境。👉 [点这里看怎么解决](./FAQ.md#报错里写着-command-not-found-node-或-npm-install-失败)
+🚑 **急救包：敲完回车就报错了？** 如果屏幕提示 `Error: Node.js ^22.23.4 || ^24.22.1 || >=26.12.1 is required`（后面可能跟着 `found vX.Y.Z`；Windows 上会在 `Installation failed with error:` 下方显示类似的提示，前面没有 `Error: `），说明你的电脑缺少上面说的基础环境。👉 [点这里看怎么解决](./FAQ.md#报错里写着-command-not-found-node-或-npm-install-失败)
 
 如果没有报错，屏幕上会跳出安装向导。请把它当成一个文字小游戏，整个流程分 4 关：
 
@@ -102,7 +106,7 @@ Installation Mode
 The following data will be permanently deleted:
   • ALL MCP entries in: ~/.mcporter/mcporter.json
   • ALL installed skills (global and workspace)
-  • x402 config file: ~/.x402-config.json
+  • legacy x402 config file: ~/.x402-config.json
   • BANK OF AI local config: ~/.mcporter/bankofai-config.json
   • AgentWallet config will be overwritten by: agent-wallet start --override --save-runtime-secrets
 
@@ -115,9 +119,9 @@ The following data will be permanently deleted:
 ```
 Running cleanup...
 
-◇  Found 10 unique installed skill(s)
+◇  Found 14 unique installed skill(s)
 ◇  Removal process complete
-◆  Successfully removed 10 skill(s)
+◆  Successfully removed 14 skill(s)
 
 ✓ Clean install cleanup completed.
 
@@ -130,7 +134,8 @@ Clean complete — proceeding with fresh setup...
 Step 0: AgentWallet Setup
 
 Launching: agent-wallet reset
-This will delete ALL wallet data in: ~/.agent-wallet
+This will delete ALL wallet data in: /home/<you>/.agent-wallet
+   4 file(s): master.json, wallets_config.json, runtime_secrets.json, secret_<id>.json
 
 ✔ Are you sure you want to reset? This cannot be undone. Yes
 ✔ Really delete everything? Last chance! Yes
@@ -209,8 +214,12 @@ Active wallet: my_wallet_1
 主密码是打开你 AI 钱包的唯一钥匙。**丢了密码 = 丢了钱包的访问权限。** 拿笔写下来、存到密码管理器里——随便什么方式，千万别忘了。
 :::
 
-:::tip 升级安装时看到 "Wallet already initialized."？
-如果你之前已经装过 AgentWallet，选普通安装后向导会跳过密码设置，直接让你输入 Wallet ID 并生成钱包。之前的主密码和已有钱包都会保留。
+:::tip 已经有钱包了？（普通安装升级）
+如果 AgentWallet 里已经有钱包，而你选了普通安装，向导会先显示 `Already initialized with N wallet(s), active: <id>`，并询问 **What would you like to do?**
+- **exit**——什么都不改，安装器直接进入下一关。
+- **add**——先选钱包类型，再用你**原来的**主密码解锁（`Master Password (enter your existing password to unlock)`；如果之前的安装已把密码保存到 `runtime_secrets.json`，这一步会自动跳过）。看到 `Wallet already initialized.` 后，按第 ③–④ 步输入新的 Wallet ID 并生成钱包；新钱包会成为当前活跃钱包。不会设置新密码。
+
+无论选哪个，之前的主密码和已有钱包都会保留。
 :::
 
 （🚑 报错卡住了？👉 [点这里看 AgentWallet 安装失败怎么解决](./FAQ.md#agentwallet-安装失败了)）
@@ -272,12 +281,16 @@ This server still uses PRIVATE_KEY configuration.
 
 #### bankofai-recharge（充值助手）
 
-这个全自动，不用输入任何东西！它会自动连接 BANK OF AI 的远程充值服务。
+这个全自动，不用输入任何东西！它注册的是远程服务 `https://recharge.bankofai.io/mcp`（add-mcp 汇总里显示为 `remote` 类型）。
 
 ```
 ✓ Configuration saved for bankofai-recharge.
 ```
 
+:::caution 充值 MCP 服务已下线
+`https://recharge.bankofai.io/mcp` 已经下线。安装器仍会默认勾选并注册 `bankofai-recharge`，但它的工具已不再响应，你可以在上面的 MCP 选择环节取消勾选。给 BANK OF AI 账户充值，请改用 wallet-cli 的 [`bai recharge`](../wallet-cli/command-reference.md#bai-充值)。
+:::
+
 ### 🟢 第 4 关：挑选技能包（给 AI 装"脑子"）
 
 先选安装范围：
@@ -294,15 +307,20 @@ Select skills installation scope:
 
 直接按回车（或输入 `1`）选全局安装——这样你所有 OpenClaw 工作区都能用这些技能。
 
+:::note 如果你选了 `2`（工作区级别）
+在下面的技能选择之后，技能工具会再问一次 **Installation scope**（`Project` / `Global`）。选 `Project` 会装到你运行安装器时所在目录下的 `skills/` 文件夹（`<当前目录>/skills/<技能>`）；选 `Global` 则仍然装到 `~/.openclaw/skills/`，但安装器之后只比较工作区的技能列表，于是会打印 `No new skills were installed.`、跳过 API Key 提示和 `Next steps`，也不会安装 x402 CLI。想装成全局技能，请在上一步选 `1`。
+:::
+
 然后技能选择器启动：
 
 ```
-◇  Found 10 skills
+◇  Found 14 skills
 │
 ◇  Select skills to install (space to toggle)
-│  agent-wallet, bankofai-guide, recharge-skill, SunPerp Perpetual Futures Trading,
-│  SunPump Meme Token Toolkit, SunSwap DEX Trading, TronScan Data Lookup,
-│  USDD / JUST Protocol, wallet-cli, x402-payment
+│  agent-wallet, bankofai-guide, Multi-Sig & Account Permissions, recharge-skill,
+│  SunPerp Perpetual Futures Trading, SunPump Meme Token Toolkit, SunSwap DEX Trading,
+│  TRC20 Token Toolkit, TronScan Data Lookup, TRX Staking & SR Voting, twitter-digest,
+│  twitter-mcp, USDD / JUST Protocol, x402-payment
 ```
 
 每个技能是干啥的：
@@ -311,50 +329,87 @@ Select skills installation scope:
 | :--- | :--- |
 | **agent-wallet** | AgentWallet 钱包管理操作（查看钱包、签署交易） |
 | **bankofai-guide** | 安装完成后引导 AI 帮你完成后续操作的入门助手 |
-| **SunSwap DEX Trading** | 在 SunSwap（波场最大的去中心化交易所）上换币 |
-| **SunPerp Perpetual Futures** | 在 SunPerp 上做永续合约交易 |
+| **Multi-Sig & Account Permissions** | 管理 TRON 多签权限——密钥、阈值与联署提案 |
+| **recharge-skill** | 查询和充值 BANK OF AI 余额 |
+| **SunPerp Perpetual Futures Trading** | 在 SunPerp 上做永续合约交易 |
 | **SunPump Meme Token Toolkit** | 在 SunPump 上创建与交易 meme 代币，查询代币信息、排行、持有者与交易历史 |
+| **SunSwap DEX Trading** | 在 SunSwap（波场最大的去中心化交易所）上换币 |
+| **TRC20 Token Toolkit** | TRC20 转账、授权、余额查询与代币元数据 |
 | **TronScan Data Lookup** | 通过 TronScan 查链上数据 |
+| **TRX Staking & SR Voting** | 质押 TRX、给超级代表投票并领取投票奖励 |
+| **twitter-digest** | 生成 X/Twitter 日报（提及、首页时间线、可回复机会） |
+| **twitter-mcp** | 安装并授权 X/Twitter 的 `xurl` 命令行工具，或注册托管的 X MCP 桥接 |
 | **USDD / JUST Protocol** | 管理 USDD 稳定币与 JUST 协议仓位 |
-| **wallet-cli** | 通过锁定版 `wallet-cli` npm 包直接完成 TRON 钱包操作（转账、质押、投票、签名） |
-| **x402-payment** | x402 协议支付（Agent 间付款） |
-| **recharge-skill** | 查询和充值 BANK OF AI 余额 |
+| **x402-payment** | 通过 `x402-cli` 命令在 TRON 或 BSC 上为 x402 保护的 HTTP API 付款 |
 
 选完后，安装器会显示安全风险评估：
 
 ```
 ◇  Security Risk Assessments
 │                                     Gen               Socket            Snyk
+│  agent-wallet                       Safe              1 alert           High Risk
 │  bankofai-guide                     Safe              0 alerts          High Risk
+│  Multi-Sig & Account Permissions    --                --                --
 │  recharge-skill                     Safe              1 alert           Med Risk
 │  SunPerp Perpetual Futures Trading  --                --                --
-│  SunPump Meme Token Toolkit         --                --                --
-│  SunSwap DEX Trading                --                --                --
-│  TronScan Data Lookup               --                --                --
-│  USDD / JUST Protocol               --                --                --
-│  wallet-cli                         --                --                --
+│  ...
 │  x402-payment                       Safe              1 alert           Med Risk
-│  agent-wallet                       Safe              1 alert           High Risk
 ```
 
-查看报告后确认继续。安装完成时：
+查看报告后，在 `Proceed with installation?` 提示处选 `Yes`。安装完成时：
 
 ```
-◇  Installed 10 skills
+◇  Proceed with installation?
+│  Yes
 │
-│  ✓ agent-wallet → ~/.openclaw/skills/agent-wallet
-│  ✓ bankofai-guide → ~/.openclaw/skills/bankofai-guide
-│  ✓ recharge-skill → ~/.openclaw/skills/recharge-skill
-│  ✓ SunPerp Perpetual Futures Trading → ~/.openclaw/skills/sunperp-perpetual-futures-trading
-│  ✓ SunPump Meme Token Toolkit → ~/.openclaw/skills/sunpump-meme-token-toolkit
-│  ✓ SunSwap DEX Trading → ~/.openclaw/skills/sunswap-dex-trading
-│  ✓ TronScan Data Lookup → ~/.openclaw/skills/tronscan-data-lookup
-│  ✓ USDD / JUST Protocol → ~/.openclaw/skills/usdd-just-protocol
-│  ✓ wallet-cli → ~/.openclaw/skills/wallet-cli
-│  ✓ x402-payment → ~/.openclaw/skills/x402-payment
-```
-
-技能装完后，安装器会自动进入配置环节：
+◇  Installed 14 skills
+│
+│  ✓ agent-wallet (copied)
+│    → ~/.openclaw/skills/agent-wallet
+│  ✓ bankofai-guide (copied)
+│    → ~/.openclaw/skills/bankofai-guide
+│  ✓ Multi-Sig & Account Permissions (copied)
+│    → ~/.openclaw/skills/multi-sig-account-permissions
+│  ✓ recharge-skill (copied)
+│    → ~/.openclaw/skills/recharge-skill
+│  ✓ SunPerp Perpetual Futures Trading (copied)
+│    → ~/.openclaw/skills/sunperp-perpetual-futures-trading
+│  ✓ SunPump Meme Token Toolkit (copied)
+│    → ~/.openclaw/skills/sunpump-meme-token-toolkit
+│  ✓ SunSwap DEX Trading (copied)
+│    → ~/.openclaw/skills/sunswap-dex-trading
+│  ✓ TRC20 Token Toolkit (copied)
+│    → ~/.openclaw/skills/trc20-token-toolkit
+│  ✓ TronScan Data Lookup (copied)
+│    → ~/.openclaw/skills/tronscan-data-lookup
+│  ✓ TRX Staking & SR Voting (copied)
+│    → ~/.openclaw/skills/trx-staking-sr-voting
+│  ✓ twitter-digest (copied)
+│    → ~/.openclaw/skills/twitter-digest
+│  ✓ twitter-mcp (copied)
+│    → ~/.openclaw/skills/twitter-mcp
+│  ✓ USDD / JUST Protocol (copied)
+│    → ~/.openclaw/skills/usdd-just-protocol
+│  ✓ x402-payment (copied)
+│    → ~/.openclaw/skills/x402-payment
+```
+
+#### x402 CLI（仅在装了 x402-payment 时）
+
+如果已安装的技能里有 `x402-payment`，安装器接着会全局安装锁定版本的支付命令行工具（如果已装好 `x402-cli` 1.0.1 则跳过）：
+
+```
+Installing @bankofai/x402-cli@1.0.1...
+✓ Installed x402 CLI 1.0.1
+```
+
+这一步执行的是 `npm install --global @bankofai/x402-cli@1.0.1`，所以它和 AgentWallet 命令行工具一样，会装进全局 npm 目录，而不是 OpenClaw 的文件夹。
+
+技能装完后，安装器会比较安装前后的技能列表，对它认为新装的技能逐个进入配置环节：
+
+:::caution 只在首次安装时出现
+「新装」指本次运行前技能列表里没有的技能。这个列表会扫描 `~/.openclaw/skills/`、共享目录 `~/.agents/skills/`，以及本机其他 Agent 的技能目录，所以只要这些技能已经在其中某个目录里（例如以前装过），安装器就会在 x402 CLI 步骤之后打印 `No new skills were installed.`（CLI 已装过时显示的是 `✓ x402 CLI 1.0.1 is already installed`），跳过下面的提示，最后的汇总也只显示 MCP 配置文件。这种情况下，请按[怎么补填 API Key](#️-事后怎么补填-api-keyvip-通行证)手动创建 API Key 文件，需要的话再自行设置 `TRONSCAN_API_KEY`。
+:::
 
 #### recharge-skill API Key 配置
 
@@ -366,9 +421,13 @@ Recharge requests use the remote BANK OF AI recharge MCP endpoint.
 ? Enter BANKOFAI_API_KEY (optional, hidden):
 ```
 
+:::caution 通过 recharge-skill 充值已不可用
+recharge-skill 充值时调用的远程充值 MCP 服务已经下线，因此通过这个技能发起的充值会失败。需要充值时，请使用 [`wallet-cli bai recharge`](../wallet-cli/command-reference.md#bai-充值)。
+:::
+
 **现在没有？直接按回车跳过。** 以后拿到了 Key 可以手动创建配置文件，详见下方「[事后怎么补填 API Key](#️-事后怎么补填-api-keyvip-通行证)」。
 
-当屏幕底部亮起 `Installation Complete!` 时——恭喜，通关成功！
+当屏幕底部亮起 `Installation Complete!` 时——恭喜，通关成功！下面的 `Installed skills` 列表和 `Next steps` 只有在安装器检测到新技能时才会出现，否则汇总在配置文件那几行之后，直接接上结尾的 `Repository:` / `Skills:` 链接。
 
 ```
 ═══════════════════════════════════════
@@ -382,13 +441,17 @@ Recharge requests use the remote BANK OF AI recharge MCP endpoint.
 ✓ Installed skills:
   • agent-wallet
   • bankofai-guide
+  • Multi-Sig & Account Permissions
   • recharge-skill
   • SunPerp Perpetual Futures Trading
   • SunPump Meme Token Toolkit
   • SunSwap DEX Trading
+  • TRC20 Token Toolkit
   • TronScan Data Lookup
+  • TRX Staking & SR Voting
+  • twitter-digest
+  • twitter-mcp
   • USDD / JUST Protocol
-  • wallet-cli
   • x402-payment
   Verify with: npx skills list -g
 
@@ -439,7 +502,7 @@ Skills: https://github.com/BofAI/skills
 | Key 名称 | 它是干嘛的？ | 去哪免费领？ |
 | :--- | :--- | :--- |
 | `TRONGRID_API_KEY` | 波场工具箱的高速通道，不填会被限速 | [trongrid.io](https://www.trongrid.io/) 免费注册获取 |
-| `TRONSCAN_API_KEY` | TronScan 查数据技能必须用到 | [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) 免费申请 |
+| `TRONSCAN_API_KEY` | TronScan Data Lookup 技能可选——不填时技能会走 BofAI 代理 `ts.bankofai.io`；填自己的 Key 可获得更高的频率限制 | [tronscan.org](https://tronscan.org/#/myaccount/apiKeys) 免费申请 |
 | `BANKOFAI_API_KEY` | 给 BANK OF AI 充值或查余额用 | [chat.bankofai.io/key](https://chat.bankofai.io/key) 登录后获取 |
 
 
@@ -490,7 +553,8 @@ Skills: https://github.com/BofAI/skills
 <TabItem value="mac" label="Linux / macOS" default>
 
 ```bash
-mkdir -p ~/.mcporter && echo '{"api_key": "你的BANKOFAI_API_KEY填在这里", "base_url": "https://chat.bankofai.io/"}' > ~/.mcporter/bankofai-config.json
+mkdir -p ~/.mcporter && echo '{"api_key": "你的BANKOFAI_API_KEY填在这里", "base_url": "https://chat.ainft.com"}' > ~/.mcporter/bankofai-config.json
+chmod 600 ~/.mcporter/bankofai-config.json   # 安装器也会这么做；这个文件里有你的 API Key
 ```
 
 </TabItem>
@@ -498,7 +562,7 @@ mkdir -p ~/.mcporter && echo '{"api_key": "你的BANKOFAI_API_KEY填在这里",
 
 ```powershell
 New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.mcporter" | Out-Null
-'{"api_key": "你的BANKOFAI_API_KEY填在这里", "base_url": "https://chat.bankofai.io/"}' | Out-File -Encoding utf8 "$env:USERPROFILE\.mcporter\bankofai-config.json"
+'{"api_key": "你的BANKOFAI_API_KEY填在这里", "base_url": "https://chat.ainft.com"}' | Out-File -Encoding utf8 "$env:USERPROFILE\.mcporter\bankofai-config.json"
 ```
 
 </TabItem>
@@ -518,7 +582,7 @@ New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.mcporter" | Out-Nul
 | `~/.mcporter/mcporter.json` | MCP 服务器配置（包括 BNB Chain 私钥，如果你填了的话） |
 | `~/.mcporter/bankofai-config.json` | BANK OF AI 的 API Key |
 | `~/.openclaw/skills/` | 全局安装的技能包 |
-| `.openclaw/skills/` | 工作区级别的技能包（选了选项 2 才有） |
+| `skills/`（位于你运行安装器时所在的目录） | 工作区级别的技能包（选了选项 2 并选 `Project` 才有） |
 | `~/.agent-wallet/` | AgentWallet 加密钱包数据 |
 
 </TabItem>
@@ -529,7 +593,7 @@ New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.mcporter" | Out-Nul
 | `%USERPROFILE%\.mcporter\mcporter.json` | MCP 服务器配置（包括 BNB Chain 私钥，如果你填了的话） |
 | `%USERPROFILE%\.mcporter\bankofai-config.json` | BANK OF AI 的 API Key |
 | `%USERPROFILE%\.openclaw\skills\` | 全局安装的技能包 |
-| `.openclaw\skills\` | 工作区级别的技能包（选了选项 2 才有） |
+| `skills\`（位于你运行安装器时所在的目录） | 工作区级别的技能包（选了选项 2 并选 `Project` 才有） |
 | `%USERPROFILE%\.agent-wallet\` | AgentWallet 加密钱包数据 |
 
 </TabItem>

From e5ae9fff53fd19bd8441ad57bafe70354aedc478 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:02 +0800
Subject: [PATCH 05/13] docs(agent-wallet, skills): rewrite Agent Wallet for
 3.0.0 and fix Skills setup

- Agent Wallet 3.0.0: wallet types, exec-script credentials, canonical CAIP-2 networks, error codes, signAndBroadcast timeouts, wallet_cli TRON payload requirements, config schema.
- Skills: install from /tree/main, per-skill credentials, npm install after install and update, sun-cli 1.2.2, Permit2 approval per swap.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 changelog/agent-wallet.md                     |  55 ++
 changelog/skills.md                           |  48 ++
 docs/Agent-Wallet/Developer/CLI-Reference.md  | 382 +++++-------
 docs/Agent-Wallet/Developer/SDK-Cookbook.md   | 330 ++--------
 docs/Agent-Wallet/Developer/SDK-Guide.md      | 539 ++++-------------
 docs/Agent-Wallet/FAQ.md                      | 170 +++---
 docs/Agent-Wallet/Intro.md                    | 105 ++--
 docs/Agent-Wallet/QuickStart.md               | 221 +++----
 docs/McpServer-Skills/SKILLS/BANKOFAISkill.md |  20 +-
 docs/McpServer-Skills/SKILLS/Faq.md           |  10 +-
 docs/McpServer-Skills/SKILLS/Intro.md         |   4 +-
 docs/McpServer-Skills/SKILLS/QuickStart.md    |  17 +-
 .../current/agent-wallet.md                   |  57 +-
 .../current/skills.md                         |  48 ++
 .../Agent-Wallet/Developer/CLI-Reference.md   | 413 +++++--------
 .../Agent-Wallet/Developer/SDK-Cookbook.md    | 331 ++--------
 .../Agent-Wallet/Developer/SDK-Guide.md       | 565 +++++-------------
 .../current/Agent-Wallet/FAQ.md               | 210 ++++---
 .../current/Agent-Wallet/Intro.md             | 132 ++--
 .../current/Agent-Wallet/QuickStart.md        | 237 ++++----
 .../McpServer-Skills/SKILLS/BANKOFAISkill.md  |  20 +-
 .../current/McpServer-Skills/SKILLS/Faq.md    |  10 +-
 .../current/McpServer-Skills/SKILLS/Intro.md  |   4 +-
 .../McpServer-Skills/SKILLS/QuickStart.md     |  17 +-
 .../agent-wallet-x402-permit-flow.light.svg   |  10 +-
 .../agent-wallet-x402-permit-flow.svg         |  10 +-
 ...agent-wallet-x402-permit-flow.zh.light.svg |  12 +-
 .../agent-wallet-x402-permit-flow.zh.svg      |  12 +-
 28 files changed, 1430 insertions(+), 2559 deletions(-)

diff --git a/changelog/agent-wallet.md b/changelog/agent-wallet.md
index 111096ee..e97df563 100644
--- a/changelog/agent-wallet.md
+++ b/changelog/agent-wallet.md
@@ -7,6 +7,61 @@ description: 'Release notes for Agent Wallet.'
 
 Release notes for Agent Wallet.
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Error codes, Privy automation and config schema
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **SDK Guide** — lists the `code` values of `WalletCliExecutionError` / `WalletCliUsageError` (`capability_missing`, `network_mismatch`, `timeout`, …) and that wallet-cli's own failure codes pass through; a `wallet_cli` chainId mismatch throws `SigningError`; `signAndBroadcast()` returns `{ txId, stage: 'timeout' }` when a broadcast times out or the `wait` deadline passes, and throws `WalletCliSubmittedTransactionError` only when a status query fails after broadcast; the `/advanced` export list is complete.
+- **CLI Reference** — `privy` automation needs both `--app-id` and `--app-secret-exec`, otherwise a reuse or secret prompt exits 1; `-g/--generate` is parsed but ignored; the `wallets_config.json` layout is described.
+
+👉 [SDK Guide](/Agent-Wallet/Developer/SDK-Guide/) · [CLI Reference](/Agent-Wallet/Developer/CLI-Reference/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 21, 2026</div>
+<div className="changelog-body">
+
+### Docs rewritten for Agent Wallet 3.0
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Breaking</span></div>
+
+- **Rewritten for 3.0.0** — every page now follows `@bankofai/agent-wallet` 3.0.0. The wallet types are `wallet_cli` (recommended), `privy` and `raw_secret`. `local_secure`, the master password, `AGENT_WALLET_PASSWORD`, `runtime_secrets.json`, and the `init`, `change-password` and `sign msg` commands no longer exist. See [Upgrading from 2.x](/Agent-Wallet/FAQ/#upgrade-from-2x).
+- **Credentials** — wallet-cli and Privy secrets should come from exec scripts (`--cli-password-exec`, `--app-secret-exec`; a direct `--app-secret` value is also accepted but stored in plaintext); 3.x has no password environment variable. The env fallback reads only `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`; the 2.x aliases such as `TRON_PRIVATE_KEY` are no longer read.
+- **Exact network IDs** — `-n` / `network` accept only canonical CAIP-2 strings such as `tron:728126428`, `tron:3448148188` or `eip155:56`. Aliases like `tron:nile` and hex TRON IDs are rejected.
+- **Signed transactions** — `signTransaction()` returns a `SignedTransactionArtifact` with a `family` field instead of a string, and the cookbook branches on it. `signMessage` was removed.
+- **TypeScript only** — the Python tabs were removed. The PyPI package `bankofai-agent-wallet` stopped at 2.4.0 and follows the 2.x model.
+- **Reference fixes** — `reset` removes only `wallets_config.json`; the error list now includes the `ExternalSigner*` and `WalletCli*` classes; the `/advanced` and `/integrations/wallet-cli` entry points and `AGENT_WALLET_WALLET_CLI_PATH` are documented.
+
+👉 [Quick Start](/Agent-Wallet/QuickStart/) · [CLI Reference](/Agent-Wallet/Developer/CLI-Reference/) · [SDK Guide](/Agent-Wallet/Developer/SDK-Guide/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Sep 10, 2026</div>
+<div className="changelog-body">
+
+### Agent Wallet v3.0.0
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">Breaking</span></div>
+
+- **Wallet types** — new `wallet_cli` type delegates TRON and EVM transaction and typed-data signing to a local wallet-cli account (compatible range `>=4.13.0 <5.0.0`). `local_secure`, the master password, `AGENT_WALLET_PASSWORD` and `runtime_secrets.json` are removed; existing `local_secure` wallets are not converted.
+- **Signing API** — `signTransaction()` returns a `SignedTransactionArtifact` with a `family` field (`rawTransaction` for EVM, `transaction` for TRON) instead of a string. `signRaw()`, `signMessage()` and the CLI `sign msg` command are removed; only transaction and typed-data signing remain.
+- **Package surface** — low-level adapters, clients and config resolvers move to `@bankofai/agent-wallet/advanced`; wallet-cli helpers are under `@bankofai/agent-wallet/integrations/wallet-cli`. `ConfigWalletProvider` is now `new ConfigWalletProvider(dir, options)`.
+- **Credentials and environment** — Privy and wallet-cli secrets accept `{ "exec": "/absolute/script" }` references (`--app-secret-exec`, `--cli-password-exec`). The 2.x aliases `TRON_PRIVATE_KEY`, `TRON_MNEMONIC` and `TRON_ACCOUNT_INDEX` are no longer read; use `AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC` and `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`.
+- Published to npm on September 10, 2026. The Python package stays at 2.4.0 on PyPI. Upgrade steps: [Upgrading from 2.x](/Agent-Wallet/FAQ/#upgrade-from-2x).
+
+👉 [Introduction](/Agent-Wallet/Intro/) · [CLI Reference](/Agent-Wallet/Developer/CLI-Reference/) · [SDK Guide](/Agent-Wallet/Developer/SDK-Guide/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 9, 2026</div>
 <div className="changelog-body">
diff --git a/changelog/skills.md b/changelog/skills.md
index b183061a..48548fb0 100644
--- a/changelog/skills.md
+++ b/changelog/skills.md
@@ -7,6 +7,54 @@ description: 'Release notes for SKILLS.'
 
 Release notes for SKILLS.
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Setup steps and credentials per Skill
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **Quick Start** — the two steps `npx skills add` does not do: `npm install -g @sun-protocol/sun-cli@1.2.2` for SunSwap / SunPump, and `npm install` inside the SunPerp, TronScan and USDD Skill folders. `x402`, `bai` and `8004` are wallet-cli command families outside the wallet-cli Skill's scope.
+- **Skill catalog** — the credentials column names the environment variables each Skill reads (`TRON_PRIVATE_KEY`, `SUNPERP_ACCESS_KEY` / `SUNPERP_SECRET_KEY`, `TRONSCAN_API_KEY`, …); the SunPump Skill asks for a logo image before a launch; the SunPerp example no longer suggests changing an existing position's stop-loss.
+
+👉 [Quick Start](/McpServer-Skills/SKILLS/QuickStart/) · [Skill Catalog](/McpServer-Skills/SKILLS/BANKOFAISkill/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 22, 2026</div>
+<div className="changelog-body">
+
+### Skills 3.0.1 — Node.js security baseline
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span></div>
+
+- **Node.js** — the bundled Node.js Skills and the wallet-cli installer require Node.js `^22.23.4 || ^24.22.1 || >=26.12.1`, the October 2026 security releases. The installer validates the full version, including when the pinned CLI is already installed.
+- **wallet-cli pin unchanged** — the `wallet-cli` Skill still pins `@tron-walletcli/wallet-cli@4.14.0`.
+- **Docs** — the Skills and BANK OF AI quick starts state the new Node.js requirement.
+
+👉 [Quick Start](/McpServer-Skills/SKILLS/QuickStart/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 21, 2026</div>
+<div className="changelog-body">
+
+### Install Skills from the stable main branch
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- **Install command** — now `npx skills add https://github.com/BofAI/skills/tree/main -g`. Without `/tree/main` the installer uses the repository's default branch, `develop`, whose unreleased `wallet-cli` Skill pins a different CLI version from the `@tron-walletcli/wallet-cli@4.14.0` the docs install. The FAQ's update instructions follow the same rule, and no longer pass `-y`, which made the skills CLI install into every agent detected on the machine (all 79 known agents when none is detected) and overwrite their copies.
+
+👉 [Quick Start](/McpServer-Skills/SKILLS/QuickStart/) · [FAQ](/McpServer-Skills/SKILLS/Faq/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 28, 2026</div>
 <div className="changelog-body">
diff --git a/docs/Agent-Wallet/Developer/CLI-Reference.md b/docs/Agent-Wallet/Developer/CLI-Reference.md
index 7a419d7b..e18112e2 100644
--- a/docs/Agent-Wallet/Developer/CLI-Reference.md
+++ b/docs/Agent-Wallet/Developer/CLI-Reference.md
@@ -1,115 +1,137 @@
 # CLI Reference
 
-A complete reference for every Agent-wallet command. Whether you're reviewing the basics or configuring automation scripts, you'll find the answer here.
+A complete reference for every `agent-wallet` 3.x command. Whether you're reviewing the basics or configuring automation scripts, you'll find the answer here.
 
 :::tip Just getting started?
-If you haven't created a wallet yet, head to [Quick Start](../QuickStart.md) first — three steps, under a minute.
+If you haven't created a wallet yet, head to [Quick Start](../QuickStart.md) first.
+:::
+
+```
+Usage: agent-wallet <command> [options]
+
+Commands:
+  start             Quick setup: init + configure wallet
+  add               Add a wallet configuration
+  list              List all configured wallets
+  use [id]          Set the active wallet
+  inspect <id>      Show wallet details
+  resolve-address [id]  Resolve wallet addresses
+  remove [id]       Remove a wallet
+  sign              Sign transactions or typed data
+  reset             Delete all wallet data
+```
+
+Every command accepts `--dir, -d <path>` (wallet directory, default `~/.agent-wallet`, or `AGENT_WALLET_DIR` when set) and `--help, -h`. Add `-h` after any command or subcommand — for example `agent-wallet start wallet_cli -h` — to see its exact options.
+
+:::caution Removed in 3.0
+`init`, `change-password`, `sign msg`, the `local_secure` wallet type, and the `-p/--password` and `--save-runtime-secrets` flags no longer exist; `-g/--generate` is still parsed but ignored — 3.x does not generate keys. Agent-wallet 3.x has no master password and does not generate keys.
 :::
 
 ---
 
 ## Basic Commands
 
-The core operations you'll use most often — creating wallets and signing.
+### `agent-wallet start` (Create a Wallet and Make It Active)
 
-### `agent-wallet start` (Initialize / Create Wallet)
-
-**Interactive creation (recommended):**
 ```bash
-agent-wallet start
+agent-wallet start                       # interactive: choose a wallet type
+agent-wallet start <raw_secret|privy|wallet_cli> [options]
 ```
-The system walks you through choosing a wallet type, generating keys, and setting a master password. Just follow the prompts.
 
-:::danger Avoid the `raw_secret` wallet type for real funds
-The interactive wizard may offer a `raw_secret` option. This type stores your private key **unencrypted** on disk — any program with file system access can read it directly. Only use `raw_secret` in fully isolated test environments. For any wallet holding real funds, always choose `local_secure`.
-:::
+Creates the wallet directory if needed, adds one wallet, and makes it the **active** wallet. If wallets already exist, `start` first asks whether to `add` another or `exit`; pass `--override` to skip that question.
 
-:::tip Privy wallet type
-The wizard also offers a `privy` option for Privy-managed server wallets. This type delegates key custody to Privy's infrastructure — no local private key is stored on disk. You'll need a Privy App ID, App Secret, and Wallet ID to configure it:
+Naming the wallet type as a subcommand skips the type prompt. For CI or a background service, also pass `-w` and every credential flag — without them the CLI prompts, and prompts fail in a non-interactive environment. If wallets may already exist, pass `--override` too; otherwise the add/exit question can't be asked and `start` exits 1.
+
+| Option | Applies to | Description |
+| :--- | :--- | :--- |
+| `-w, --wallet-id <id>` | all | Wallet ID to create. Prompt defaults: `default_raw`, `default_privy`, `default_cli` |
+| `--override` | `start` only | Skip the "already initialized" prompt when wallets already exist |
+| `-k, --private-key <hex>` | `raw_secret` | Import a hex private key |
+| `-m, --mnemonic <words>` | `raw_secret` | Import a BIP-39 mnemonic |
+| `-mi, --mnemonic-index <n>` | `raw_secret` | Account index for the mnemonic (default `0`; requires `-m`) |
+| `--derive-as <profile>` | `raw_secret` | `eip155` or `tron`; answers the mnemonic derivation prompt (3.0.0 checks the value but does not store it, so it does not change the derived addresses) |
+| `--app-id <id>` | `privy` | Privy app ID |
+| `--app-secret <secret>` | `privy` | Privy app secret (plaintext; prefer `--app-secret-exec`) |
+| `--app-secret-exec <path>` | `privy` | Executable that prints the Privy app secret |
+| `--privy-wallet-id <id>` | `privy` | Existing Privy wallet ID |
+| `--account <label>` | `wallet_cli` | Existing wallet-cli account label or ID (the wallet-cli active account if omitted) |
+| `--cli-password-exec <path>` | `wallet_cli` | Executable that prints the wallet-cli keystore password |
+| `-d, --dir <path>` | all | Wallet directory |
+
+#### `wallet_cli` wallets
+
+Links an existing [wallet-cli](../../wallet-cli/quickstart.md) account as a TRON + EVM signer. **It does not create or import keys** — create the account with wallet-cli first.
 
 ```bash
-agent-wallet start   # then choose "privy" when prompted
+agent-wallet start wallet_cli \
+  --wallet-id my_cli_wallet \
+  --account main-1 \
+  --cli-password-exec /absolute/path/to/fetch-password.sh
 ```
 
-The default wallet ID for Privy wallets is `default_privy`.
-:::
+- Requires `@tron-walletcli/wallet-cli` `>=4.13.0 <5.0.0`. Agent-wallet looks for it in this order: `AGENT_WALLET_WALLET_CLI_PATH`, a copy installed as a local package dependency alongside Agent-wallet, then `wallet-cli` on your `PATH`. If it is missing, the command prints install guidance and exits 1.
+- The account is checked with wallet-cli **before** any password is collected; the canonical account ID is saved, so later changes to wallet-cli's active account don't affect this wallet.
+- `--cli-password <plaintext>` is rejected so the password never lands in shell history or the process list. Without `--cli-password-exec`, an interactive prompt offers `direct` (stored as plaintext in `wallets_config.json`, mode `0600`) or `exec`.
 
-**Custom password:**
-```bash
-agent-wallet start local_secure -p Abc12345!
-```
-`-p` applies to `local_secure` only. Passing it to a bare `start` works when you then pick `local_secure` at the type prompt, but choosing `raw_secret` or `privy` there exits with `--password is only valid for local_secure quick start.` — naming the type on the command line, as above, avoids that.
+#### Privy wallets {#privy-wallets}
 
-Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters. A password typed at the interactive prompt is re-prompted until it passes; one supplied through `-p`, `AGENT_WALLET_PASSWORD`, or `runtime_secrets.json` is not — a weak value there prints the validation errors and exits 1.
+Links an existing [Privy](https://privy.io) server wallet. No private key is stored on your disk; signing calls Privy's API, so it needs network access.
 
-When creating a new password interactively, you must enter it twice for confirmation. If the two entries don't match, the CLI will ask you to try again.
+```bash
+agent-wallet start privy -w default_privy \
+  --app-id <privy-app-id> \
+  --app-secret-exec /absolute/path/to/fetch-privy-secret.sh \
+  --privy-wallet-id <privy-wallet-id>
+```
 
-**Default wallet IDs:** If you don't specify a wallet ID, the system defaults to `default_secure` for `local_secure` wallets and `default_raw` for `raw_secret` wallets.
+#### `raw_secret` wallets
 
-:::caution Shell history risk
-Passing `-p` inline records the password in your terminal's history file. For production wallets, prefer interactive mode (`agent-wallet start` without `-p`) or set `AGENT_WALLET_PASSWORD` as an environment variable — see [Non-Interactive Execution](#non-interactive-execution-for-automation--background-services).
+:::danger Avoid `raw_secret` for real funds
+This type stores your private key or mnemonic **unencrypted** in `wallets_config.json` — any program with file system access can read it. Only use it with throwaway keys in isolated test environments.
 :::
 
-**Import an existing private key:**
 ```bash
-agent-wallet start -p Abc12345! -k your-private-key-hex
+agent-wallet start raw_secret -w default_raw -k <private-key-hex>
+agent-wallet start raw_secret -w default_raw -m "word1 word2 ..." --derive-as eip155
 ```
 
-**Import a mnemonic:**
+### `agent-wallet add` (Add Another Wallet)
+
 ```bash
-agent-wallet start -p Abc12345! -m "word1 word2 word3 ..."
+agent-wallet add
+agent-wallet add <raw_secret|privy|wallet_cli> [options]
 ```
 
-#### Skip the prompts: name the wallet type directly
+Same subcommands and options as `start` (except `--override`). The new wallet becomes active only if no wallet was active before; switch with `use`.
 
-`start` and `add` also take the wallet type as a subcommand, which skips the type prompt. For CI or a background service you must also pass `-w` — without it the CLI still prompts for a wallet ID, and in a non-interactive environment that prompt fails with `Cannot prompt for wallet id in a non-interactive environment. Pass the required flags explicitly.` and exits 1:
+### `agent-wallet sign` (Core Signing Operations)
 
 ```bash
-agent-wallet start local_secure -w default_secure -p Abc12345! -g   # encrypted, generate a new key
-agent-wallet start raw_secret -w default_raw -k your-private-key    # plaintext, dev only
-agent-wallet start privy -w default_privy --app-id <id> --app-secret <secret> --privy-wallet-id <wallet>
+agent-wallet sign tx '<json>' -n <network> [-w <wallet-id>]
+agent-wallet sign typed-data '<json>' -n <network> [-w <wallet-id>]
 ```
 
-`add` works the same way (`add local_secure` / `add raw_secret` / `add privy`) for a second wallet.
-
-| Option | Applies to | Description |
+| Option | Short | Description |
 | :--- | :--- | :--- |
-| `-w, --wallet-id <id>` | all | Wallet ID to create |
-| `-g, --generate` | `local_secure` | Generate a new random key |
-| `-k, --private-key <hex>` | `local_secure`, `raw_secret` | Import a private key |
-| `-m, --mnemonic <words>` | `local_secure`, `raw_secret` | Import a mnemonic |
-| `-mi, --mnemonic-index <n>` | `local_secure`, `raw_secret` | Account index when deriving from the mnemonic |
-| `--derive-as <profile>` | `local_secure`, `raw_secret` | Mnemonic derivation profile: `eip155` or `tron` |
-| `-p, --password <pass>` | `local_secure` | Master password |
-| `--app-id` / `--app-secret` / `--privy-wallet-id` | `privy` | Privy app credentials and wallet ID |
-| `-d, --dir <path>` | all | Secrets directory (default `~/.agent-wallet`) |
-| `--save-runtime-secrets` | `local_secure` | Persist the password to `runtime_secrets.json`. The `raw_secret` and `privy` paths never read it — they collect no password |
-| `--override` | `start` only | Skip the confirmation prompt when wallets already exist |
-
-Run `agent-wallet start local_secure --help` or `agent-wallet add privy --help` for the exact options of one mode.
-
-### `agent-wallet sign` (Core Signing Operations)
+| `--network` | `-n` | Canonical CAIP-2 network: `eip155:<chainId>` or `tron:<chainId>`. **Required for `raw_secret` and `wallet_cli`.** Optional for `privy` (EVM transactions use the payload's `chainId`), but must be canonical if given |
+| `--wallet-id` | `-w` | Wallet to sign with (defaults to the active wallet) |
+| `--dir` | `-d` | Wallet directory |
 
-For `local_secure` and `raw_secret` wallets, every `sign` subcommand requires `--network` / `-n` to specify the chain. Privy wallets are the exception: their chain type comes from Privy, and EVM transaction payloads carry their own `chainId`, so `--network` is optional for Privy signing.
+Only exact canonical identifiers are accepted — `tron`, `eip155`, `evm:1`, `tron:nile`, `tron:mainnet`, hex TRON ids, and any case or whitespace variants are rejected. Use `tron:728126428` (mainnet), `tron:3448148188` (Nile), `tron:2494104990` (Shasta), `eip155:1`, `eip155:56`, `eip155:97`, and so on. For `wallet_cli` wallets the network must also be one wallet-cli itself knows — its built-ins (`eip155:1`, `eip155:11155111`, `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532` (the two Base networks were added in wallet-cli 4.14.0) and the three TRON networks) or a network added to wallet-cli's own config — otherwise signing fails with `wallet-cli network '<id>' is unavailable` (code `network_mismatch` in the SDK). `raw_secret` and `privy` wallets have no such limit.
 
-:::info Password retry behavior
-When signing with a `local_secure` wallet, the CLI will prompt for the master password if it's not provided via `-p`, `~/.agent-wallet/runtime_secrets.json`, or `AGENT_WALLET_PASSWORD` (in that order of precedence). If the password is wrong, the sign command fails immediately with exit code 1 ("Wrong password. Please try again."). The 3-attempt interactive retry loop applies to the `start`, `add`, `change-password`, and `resolve-address` prompts, not to `sign`.
-:::
-
-**Sign a message:**
+**Sign a TRON transaction** (build the unsigned transaction first, e.g. via TronGrid; `raw_data_hex` is required, and `wallet_cli` wallets also need `raw_data` and a matching `txID`):
 ```bash
-agent-wallet sign msg "Hello" -n tron
-# Output: Signature: d220de880cbc1c3f...
+agent-wallet sign tx '{"txID":"...","raw_data_hex":"0a02...","raw_data":{}}' -n tron:3448148188
+# Output: "Signed tx:" followed by the signed transaction as pretty-printed JSON
 ```
 
-**Sign a transaction** (build the unsigned tx via RPC first):
+**Sign an EVM transaction** (`chainId` should match `-n`; `wallet_cli` wallets reject a mismatch with a `SigningError`, `raw_secret` and `privy` sign with the payload's `chainId`):
 ```bash
-agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron
-# Output: a line reading `Signed tx:` followed by the signed transaction as pretty-printed JSON
-# (a single line is used only when the result is not valid JSON)
+agent-wallet sign tx '{"chainId":97,"nonce":0,"gas":"0x5208","gasPrice":"0x3b9aca00","to":"0x...","value":"0x0"}' -n eip155:97
+# Output: Signed tx: <raw transaction hex, without 0x>
 ```
 
-**Sign EIP-712 typed data:**
+**Sign EIP-712 / TIP-712 typed data:**
 ```bash
 agent-wallet sign typed-data '{
   "types": {
@@ -120,30 +142,11 @@ agent-wallet sign typed-data '{
   "domain": {"name":"MyDApp","chainId":1},
   "message": {"to":"0x7099...","amount":1000000}
 }' -n eip155:1
+# Output: Signature: <hex, without 0x>
 ```
 
----
-
-### `agent-wallet init` (Initialize Secrets Directory)
-
-Initialize the secrets directory and set the master password — without creating a wallet yet. This is useful for advanced scenarios where you want to prepare the directory before adding wallets.
-
-```bash
-agent-wallet init
-```
-
-**Non-interactive mode:**
-```bash
-agent-wallet init -p 'Abc12345!'
-```
-
-| Flag | Description |
-| :--- | :--- |
-| `--password, -p <pw>` | Master password (skip prompt) |
-| `--save-runtime-secrets` | Persist password to `runtime_secrets.json` |
-
-:::tip When to use `init` vs `start`
-`start` = `init` + create a wallet in one step. If you just need to set up the directory and password first (e.g., for a CI pipeline or when importing keys later), use `init` alone.
+:::note No message signing
+`sign msg` was removed in 3.0. Agent-wallet only signs transactions and typed data.
 :::
 
 ---
@@ -152,37 +155,27 @@ agent-wallet init -p 'Abc12345!'
 
 Manage multiple wallets — add, switch, inspect, remove.
 
-**Add a new wallet:**
-```bash
-agent-wallet add
-```
-
-**List all wallets:**
+**List all wallets** (`*` marks the active one):
 ```bash
 agent-wallet list
 ```
 
-**Switch the active wallet:**
+**Switch the active wallet** (omit the ID to pick from a list):
 ```bash
 agent-wallet use my-bsc-wallet
 ```
 
-**Inspect a wallet:**
+**Inspect a wallet** (secrets are always shown as `[redacted]`):
 ```bash
 agent-wallet inspect my-bsc-wallet
 ```
 
-To see the wallet's derived addresses, use the separate `resolve-address` command:
-```bash
-agent-wallet resolve-address my-bsc-wallet
-```
-
 **Sign with a specific wallet** (without switching the active one):
 ```bash
-agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!'
+agent-wallet sign typed-data '<json>' -n eip155:56 -w my-bsc-wallet
 ```
 
-**Remove a wallet:**
+**Remove a wallet** (omit the ID to pick from a list):
 ```bash
 agent-wallet remove my-bsc-wallet
 ```
@@ -191,24 +184,26 @@ agent-wallet remove my-bsc-wallet
 | :--- | :--- | :--- |
 | `--yes` | `-y` | Skip confirmation prompt (**required in non-interactive / agent contexts**) |
 
+Removing a `wallet_cli` or `privy` wallet only deletes Agent-wallet's configuration entry — the wallet-cli account or Privy wallet itself is untouched.
+
 ### `agent-wallet resolve-address` (Resolve Wallet Addresses)
 
-Display the on-chain addresses associated with a wallet. Local wallets (`local_secure`, `raw_secret`) always show both an EVM and a TRON address. `local_secure` wallets (however created — a mnemonic import stores the single key derived under the chosen `--derive-as` profile) and private-key `raw_secret` wallets derive both addresses from the same stored key; only `raw_secret` **mnemonic** wallets derive each chain's address from the mnemonic via its own derivation path. Privy wallets show the single address reported by Privy.
+Display the on-chain addresses associated with a wallet, without signing:
+
+- `raw_secret` wallets show both an EVM and a TRON address derived from the same secret material.
+- `wallet_cli` wallets show both addresses when the wallet-cli account has both families (one address otherwise). No password is requested.
+- `privy` wallets show the single address reported by Privy.
 
 ```bash
 agent-wallet resolve-address my-wallet
 ```
 
-If you omit the wallet ID, the CLI will present an interactive list to choose from:
-
-```bash
-agent-wallet resolve-address
-```
+If you omit the wallet ID, the CLI will present an interactive list to choose from.
 
 Example output:
 ```
 Wallet  my-wallet
-Type    local_secure
+Type    raw_secret
 
 Addresses
 EVM   0x742D35CC6634C0532925a3B844Bc9E7595F2bD18
@@ -219,102 +214,36 @@ TRON  TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC
 
 ## Non-Interactive Execution (For Automation & Background Services)
 
-By default, signing commands pause and prompt you to type your password interactively. But if an AI agent is running in the background, or you're running an automation script, this "stop and wait for input" behavior will cause the program to hang or error out.
-
-To let the program run silently from start to finish (non-interactive mode), you need to pre-supply the password. Depending on your use case, there are three approaches:
-
-### Method A: Environment Variable Injection (Recommended for AI Agents / CI Pipelines)
-
-Store the password in the current system environment. When the program needs the password, it automatically retrieves it — fully silent:
-
-```bash
-export AGENT_WALLET_PASSWORD='Abc12345!'
-```
-
-Once set, all signing commands in the current window return results instantly, no more pausing:
-
-```bash
-agent-wallet sign msg "Hello" -n tron
-agent-wallet sign tx '{"txID":"..."}' -n tron
-```
-
-:::tip Prevent this command from being recorded in shell history
-To prevent the command from being recorded in shell history, edit `~/.zshrc` / `~/.bashrc` directly in a text editor rather than running the command in the terminal. Alternatively, prefix the command with a space — but only if you have verified that `HISTCONTROL=ignorespace` is active in Bash (`echo $HISTCONTROL`) or `HIST_IGNORE_SPACE` is active in Zsh (`setopt | grep HIST_IGNORE_SPACE`). These settings are **not** enabled by default on most systems and must be configured explicitly.
-:::
-
-:::caution Password contains special characters? Always use single quotes
-```bash
-# ✅ Correct — shell treats it literally
-export AGENT_WALLET_PASSWORD='P@ss$w0rd!'
-
-# ❌ Wrong — $ gets expanded by the shell, password silently breaks
-export AGENT_WALLET_PASSWORD="P@ss$w0rd!"
-```
-:::
-
-<details>
-<summary>GitHub Actions / CI example</summary>
-
-In CI/CD environments, never hardcode the password in workflow files. Use repository secrets instead:
-
-```yaml
-# .github/workflows/sign.yml
-jobs:
-  sign:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: agent-wallet sign msg "Hello" -n tron
-        env:
-          AGENT_WALLET_PASSWORD: ${{ secrets.AGENT_WALLET_PASSWORD }}
-```
-
-</details>
-
-### Method B: Local Password Cache (Convenience vs. Security Trade-off)
-
-After running a command once with the `--save-runtime-secrets` flag, the password is cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables:
-
-```bash
-agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets
-```
-
-:::danger This disables the dual-lock protection
-Caching the password next to the wallet file means a single file system compromise grants full access to your funds — defeating Agent-wallet's core "physical file + password separation" security model. **Only use this for throwaway test wallets.**
+There is no master password to supply in 3.x. To run without prompts:
 
-`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Make sure this file is never committed to git or synced to the cloud.
+- **Creating wallets:** name the type and pass every value as a flag (`-w`, `-k`/`-m` plus `--derive-as`, `--app-id`/`--privy-wallet-id`, `--account`). With `start`, add `--override` when wallets may already exist — otherwise it exits 1. For `privy`, pass **both** `--app-id` and `--app-secret-exec` (or `--app-secret`): when a Privy wallet already exists and neither `--app-id` nor `--app-secret` is passed (`--app-secret-exec` alone does not count), the CLI asks whether to reuse its credentials; with `--app-id` but no secret it asks where the secret comes from. Either prompt exits 1 non-interactively.
+- **Secrets:** use exec scripts — `--cli-password-exec` for wallet-cli, `--app-secret-exec` for Privy. The path must point to an executable file (not an inline shell command). It inherits the process environment, its trimmed stdout is used as the secret, and it times out after 10 seconds by default. For `wallet_cli` the script runs again for **every** signature.
+- **Signing:** always pass `-n`, and `-w` if you don't want to depend on the active wallet.
+- **Removing / resetting:** pass `-y`.
+- **Check flag spelling:** the CLI ignores flags it does not recognise instead of failing, so a misspelled flag (for example `--walet-id`) silently falls back to a prompt or a default.
 
-The tool automatically sets restrictive file permissions (`600` — owner-read-only) on creation. If you've manually moved or copied the file, verify the permissions: `chmod 600 ~/.agent-wallet/runtime_secrets.json`.
+`wallets_config.json` holds `active_wallet` and a `wallets` map keyed by wallet ID; each entry has a `type` and `params`: `raw_secret` → `source` with `private_key`, or `mnemonic` plus `account_index`; `privy` → `app_id`, `app_secret`, `wallet_id`; `wallet_cli` → `account` (optional) and `password`. `app_secret` and `password` are either a string or an exec reference (`private_key` and `mnemonic` are plain strings) (`timeout` in milliseconds is optional):
 
-To remove the cached password and restore full dual-lock protection:
-
-```bash
-rm ~/.agent-wallet/runtime_secrets.json
+```json
+{ "exec": "/absolute/path/to/fetch-password.sh", "timeout": 10000 }
 ```
 
-After deletion, signing commands will prompt for the password interactively again (or read from `AGENT_WALLET_PASSWORD` if set).
-:::
-
-### Method C: Inline `-p` Flag (For One-Off Commands)
+### Custom Storage Directory
 
-Pass the password directly at the end of the command. The program takes the password and runs immediately — no prompts:
+All commands support `--dir` to use a wallet directory other than `~/.agent-wallet`. Set `AGENT_WALLET_DIR` to make it the default for both the CLI and the SDK:
 
 ```bash
-agent-wallet sign msg "Hello" -n tron -p 'Abc12345!'
+agent-wallet start raw_secret --dir /Volumes/MyUSB/agent-wallet
+agent-wallet list --dir /Volumes/MyUSB/agent-wallet
 ```
 
-:::danger Security Warning
-When using `-p` to pass the password inline, the plaintext password is recorded in your terminal's `history`. Only use this method in fully isolated test environments!
-:::
+### Environment Variables
 
-### Custom Storage Directory
-
-All commands support the `--dir` flag to specify a custom Agent-wallet storage path (default: `~/.agent-wallet`). For example, you can store your Agent-wallet directly on an encrypted USB drive — plug and play, unplug and go:
-
-```bash
-agent-wallet start --dir /Volumes/MyUSB/agent-wallet
-agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet
-```
+| Variable | Purpose |
+| :--- | :--- |
+| `AGENT_WALLET_DIR` | Default wallet directory (CLI and SDK) |
+| `AGENT_WALLET_WALLET_CLI_PATH` | Path to the wallet-cli executable or its JavaScript entrypoint, when it is not on `PATH` |
+| `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC` / `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | SDK environment fallback only (used when no wallet is configured) — see [SDK Guide](./SDK-Guide.md#environment-variable-fallback) |
 
 ---
 
@@ -323,33 +252,9 @@ agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet
 :::danger The following operations are irreversible — use with extreme caution!
 :::
 
-### `agent-wallet change-password` (Change Master Password)
-
-After changing, **all key files are re-encrypted with the new password**. The old password becomes invalid immediately — make sure to update your password manager.
+### `agent-wallet reset` (Reset All Data) {#agent-wallet-reset-reset-all-data}
 
-**Interactive mode (default):**
-```bash
-agent-wallet change-password
-```
-
-**Non-interactive mode** (for automation scripts):
-```bash
-agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!'
-```
-
-| Flag | Description |
-| :--- | :--- |
-| `--password, -p <pw>` | Current master password (skip prompt) |
-| `--new-password <pw>` | New master password (skip prompt) |
-| `--save-runtime-secrets` | Update cached password in `runtime_secrets.json` |
-
-:::caution
-Both `-p` and `--new-password` will be recorded in shell history. For production use, prefer interactive mode or pipe passwords from a secrets manager.
-:::
-
-### `agent-wallet reset` (Reset All Data)
-
-Deletes the files the CLI manages inside `~/.agent-wallet/` — `master.json`, `wallets_config.json`, `runtime_secrets.json`, and every `secret_*.json`. **This is a nuclear option — once executed, all wallets, keys, and configuration are gone, with no recovery.** The directory itself and anything else in it (including `cred_*.json`) are left in place. The CLI asks for confirmation **twice**; pass `-y/--yes` to skip both prompts in automation.
+Deletes `wallets_config.json` from the wallet directory — every wallet configuration, including any `raw_secret` keys stored in it. Other files in the directory are left in place. wallet-cli accounts and Privy wallets themselves are not affected. The CLI asks for confirmation **twice**; pass `-y/--yes` to skip both prompts in automation.
 
 ```bash
 agent-wallet reset
@@ -359,33 +264,32 @@ agent-wallet reset
 
 ## Real-World Example: Signing in a Shell Script
 
-The CLI isn't just for manual typing — it integrates perfectly into your automation scripts.
-
-This minimal example demonstrates how to perform a non-interactive signing operation in a Bash script and capture the signature into a variable (the CLI prints `Signature: <hex>`, so the prefix is stripped with `sed`):
+This minimal example performs a non-interactive typed-data signature in a Bash script and captures the result into a variable. The CLI prints `Signature: <hex>`, so the script strips the prefix and checks that what remains is a 130-character hex signature. It deliberately avoids piping into `sed`: in a pipeline the exit status is the last command's, so a failed signature would still look successful.
 
 ```bash
 #!/bin/bash
-# Enable strict mode: stop immediately on any error
-set -e
-
-# 1. Password should already be set in the environment before running this script.
-#    e.g. via ~/.zshrc / ~/.bashrc — see "Save and Activate the Password" in QuickStart.
-#    NEVER hardcode a real password in a script file (it will end up in git history).
-if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then
-  echo "Error: AGENT_WALLET_PASSWORD not set" >&2
-  exit 1
-fi
+# Strict mode: stop on errors, unset variables, and failures inside pipelines
+set -euo pipefail
+
+# Typed data to sign (built by your own logic)
+TYPED_DATA='{"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}],"Message":[{"name":"contents","type":"string"}]},"primaryType":"Message","domain":{"name":"MyScript","chainId":56},"message":{"contents":"Hello from my script"}}'
 
 echo "Calling local Agent-wallet for signing..."
 
-# 2. Core operation: execute signing, capture the hash output into the SIGNATURE variable
-SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron | sed 's/^Signature: //')
+# On failure the CLI exits non-zero and prints the reason (e.g. "Wallet 'my-bsc-wallet' not found")
+if ! OUTPUT=$(agent-wallet sign typed-data "$TYPED_DATA" -n eip155:56 -w my-bsc-wallet); then
+  echo "❌ Signing failed: $OUTPUT" >&2
+  exit 1
+fi
+
+SIGNATURE=${OUTPUT#Signature: }
+if [[ ! "$SIGNATURE" =~ ^[0-9a-fA-F]{130}$ ]]; then
+  echo "❌ Unexpected output: $OUTPUT" >&2
+  exit 1
+fi
 
-# 3. Got the clean signature value — continue with downstream logic
 echo "✅ Signing successful!"
 echo "Extracted signature: $SIGNATURE"
-
-# From here, you can use $SIGNATURE to build requests, construct JSON, or pass it to other pipeline tasks...
 ```
 
 ---
diff --git a/docs/Agent-Wallet/Developer/SDK-Cookbook.md b/docs/Agent-Wallet/Developer/SDK-Cookbook.md
index 7ce3e9a6..4f65d3f7 100644
--- a/docs/Agent-Wallet/Developer/SDK-Cookbook.md
+++ b/docs/Agent-Wallet/Developer/SDK-Cookbook.md
@@ -1,19 +1,16 @@
 import ThemedImage from '@theme/ThemedImage';
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # SDK Cookbook
 
 :::tip Why read this page?
 In the [SDK Guide](./SDK-Guide.md), you learned how to use Agent-wallet for "offline signing." But in real-world scenarios, an AI agent can't just sign — it needs to: **1. Query the node to build a transaction → 2. Agent-wallet signs → 3. Broadcast to the blockchain.**
 
-Agent-wallet focuses on doing the core secure signing step (step 2) well. This page provides a set of **"ready-to-use"** complete scripts that combine TronGrid and Ethers.js / Web3.py to walk you through the full end-to-end flow. You can copy these scripts directly into your production environment!
+Agent-wallet focuses on doing the core secure signing step (step 2) well. This page provides a set of **"ready-to-use"** complete scripts that combine TronGrid and Ethers.js with the `@bankofai/agent-wallet` 3.x SDK to walk you through the full end-to-end flow. You can copy these scripts directly into your production environment!
 :::
 
 This page walks through three real-world scenarios end to end: sending TRX on TRON, sending BNB on BSC, and signing an x402 payment permit. Each example is complete and runnable — copy, configure your addresses, and go.
 
-All examples are available in both TypeScript and Python — use the tabs to switch.
+All examples are TypeScript — Agent-wallet 3.x has no Python SDK (the PyPI package `bankofai-agent-wallet` stopped at 2.4.0).
 
 ---
 
@@ -22,11 +19,11 @@ All examples are available in both TypeScript and Python — use the tabs to swi
 Before running any example below, make sure you have:
 
 1. Installed the Agent-wallet SDK (see [SDK Guide](./SDK-Guide.md))
-2. Initialized a local wallet via the CLI, or configured static mode environment variables
-3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode — strongly recommended)
+2. Configured a wallet with the CLI — a `wallet_cli` wallet is recommended (see [Quick Start](../QuickStart.md)) — or set the environment fallback variables
+3. Funded the wallet on the testnet you use (the TRON address must have received TRX at least once to be activated)
 
-:::danger Avoid static mode (`AGENT_WALLET_PRIVATE_KEY`) for real funds
-Static mode stores your private key as plaintext in an environment variable — the exact exposure Agent-wallet's `local_secure` mode is designed to prevent. Only use `AGENT_WALLET_PRIVATE_KEY` in fully isolated, offline test environments with throwaway keys. For mainnet operations, always use `AGENT_WALLET_PASSWORD` with your local Agent-wallet.
+:::danger Avoid the environment fallback (`AGENT_WALLET_PRIVATE_KEY`) and `raw_secret` for real funds
+Both keep your private key in plaintext. Only use them in fully isolated test environments with throwaway keys. For mainnet operations, use a `wallet_cli` (or `privy`) wallet.
 :::
 
 ---
@@ -37,7 +34,7 @@ Static mode stores your private key as plaintext in an environment variable —
 
 **How it works**:
 
-TRON transactions cannot be constructed directly by the client from scratch. The flow must start with a call to TronGrid's `createtransaction` endpoint, which returns an unsigned transaction object containing `txID` and `raw_data` generated by the network node. That object is then passed to Agent-wallet for local signing — the signing process is fully offline and the private key never leaves the machine. Finally, the signed transaction is submitted to TronGrid's `broadcasttransaction` endpoint to be published on-chain.
+TRON transactions cannot be constructed directly by the client from scratch. The flow must start with a call to TronGrid's `createtransaction` endpoint, which returns an unsigned transaction object containing `txID` and `raw_data` generated by the network node. That object is then passed to Agent-wallet for signing — `raw_secret` signs in-process and `wallet_cli` delegates to a local wallet-cli subprocess, so the private key never leaves the machine. Finally, the signed transaction is submitted to TronGrid's `broadcasttransaction` endpoint to be published on-chain.
 
 <ThemedImage
   alt="TRON transfer: TronGrid builds, Agent-wallet signs, TronGrid broadcasts"
@@ -47,48 +44,17 @@ TRON transactions cannot be constructed directly by the client from scratch. The
   }}
 />
 
-Agent-wallet only participates in the middle signing step. It requires no RPC connection and has no awareness of the transaction's business meaning.
+Agent-wallet only participates in the middle signing step. It needs no RPC connection and has no awareness of the transaction's business meaning.
 
 ### Install Dependencies
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```bash
 npm install @bankofai/agent-wallet axios
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-This example uses `aiohttp` (a third-party HTTP library) and `asyncio` (Python standard library — no install needed):
-
-```bash
-pip install aiohttp
-```
-
-:::caution If you see missing standard library module errors
-If importing `asyncio` or other standard library modules fails, it's usually because system dependencies were missing when pyenv built Python from source. Install the following packages and then re-run `pyenv install 3.11`:
-
-```bash
-# CentOS / RHEL / Amazon Linux
-sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel
-
-# Ubuntu / Debian
-sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev
-```
-:::
-
-</TabItem>
-</Tabs>
-
-
 
 ### Full Code
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```typescript
 import { resolveWalletProvider } from "@bankofai/agent-wallet";
 import axios from "axios";
@@ -101,7 +67,7 @@ async function transferTRX(
   amountSun: number // 1 TRX = 1_000_000 SUN
 ) {
   // Step 1: Initialize Agent-wallet
-  const provider = resolveWalletProvider({ network: "tron:nile" });
+  const provider = resolveWalletProvider({ network: "tron:3448148188" }); // Nile
   const wallet = await provider.getActiveWallet();
 
   // Ensure fromAddress matches the wallet — a mismatch will cause a TronGrid error
@@ -127,13 +93,12 @@ async function transferTRX(
 
   console.log("Unsigned txID:", unsignedTx.txID);
 
-  // Step 3: Sign locally with Agent-wallet
-  let signedTx: Record<string, unknown>;
-  try {
-    signedTx = JSON.parse(await wallet.signTransaction(unsignedTx));
-  } catch (e) {
-    throw new Error(`signTransaction returned invalid JSON: ${e}`);
+  // Step 3: Sign with Agent-wallet — the result is a typed artifact
+  const signed = await wallet.signTransaction(unsignedTx);
+  if (signed.family !== "tron") {
+    throw new Error("Expected a TRON signing result — check the wallet network");
   }
+  const signedTx = signed.transaction;
   if (!signedTx.signature) {
     throw new Error("Signed transaction is missing the signature field");
   }
@@ -165,84 +130,10 @@ transferTRX(
 ).catch(console.error);
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-import json
-import aiohttp
-from agent_wallet import resolve_wallet_provider
-
-TRONGRID_API = "https://nile.trongrid.io"  # Nile testnet; change to https://api.trongrid.io for mainnet
-
-async def transfer_trx(
-    from_address: str,
-    to_address: str,
-    amount_sun: int,  # 1 TRX = 1_000_000 SUN
-):
-    # Step 1: Initialize Agent-wallet
-    provider = resolve_wallet_provider(network="tron:nile")
-    wallet = await provider.get_active_wallet()
-
-    async with aiohttp.ClientSession() as session:
-        # Step 2: Build the unsigned transaction via TronGrid
-        async with session.post(
-            f"{TRONGRID_API}/wallet/createtransaction",
-            json={
-                "owner_address": from_address,
-                "to_address": to_address,
-                "amount": amount_sun,
-                "visible": True,
-            },
-        ) as resp:
-            unsigned_tx = await resp.json()
-
-        if "txID" not in unsigned_tx:
-            raise ValueError(f"Failed to build transaction: {unsigned_tx}")
-
-        print("Unsigned txID:", unsigned_tx["txID"])
-
-        # Step 3: Sign locally with Agent-wallet
-        raw_signed = await wallet.sign_transaction(unsigned_tx)
-        try:
-            signed_tx = json.loads(raw_signed)
-        except json.JSONDecodeError as e:
-            raise ValueError(f"signTransaction returned invalid JSON: {e}") from e
-        if "signature" not in signed_tx:
-            raise ValueError("Signed transaction is missing the signature field")
-        print("Signed, signature:", signed_tx["signature"])
-
-        # Step 4: Broadcast via TronGrid
-        async with session.post(
-            f"{TRONGRID_API}/wallet/broadcasttransaction",
-            json=signed_tx,
-        ) as resp:
-            broadcast_result = await resp.json()
-
-        if broadcast_result.get("result"):
-            print("Broadcast successful! txID:", signed_tx["txID"])
-        else:
-            print("Broadcast failed:", broadcast_result)
-
-    return signed_tx["txID"]
-
-# Example usage
-asyncio.run(
-    transfer_trx(
-        from_address="YOUR_TRON_ADDRESS",      # replace with your wallet address
-        to_address="RECIPIENT_TRON_ADDRESS",   # replace with the recipient address
-        amount_sun=1_000_000,                  # 1 TRX
-    )
-)
-```
-
-</TabItem>
-</Tabs>
 
 :::caution Notes
 - Use the Nile testnet for testing. Get test tokens from the [Nile Faucet](https://nileex.io/join/getJoinPage).
-- For mainnet, change `TRONGRID_API` to `https://api.trongrid.io` and `network` to `tron:mainnet`.
+- For mainnet, change `TRONGRID_API` to `https://api.trongrid.io` and `network` to `tron:728126428`. Aliases such as `tron:nile` / `tron:mainnet` are rejected in 3.x.
 :::
 
 :::tip `visible: true` and address format
@@ -262,7 +153,7 @@ The example uses Base58 addresses, consistent with `visible: true`.
 
 **How it works**:
 
-EVM transactions require the caller to construct the transaction object themselves. Unlike TRON, the fields of an EVM transaction (`nonce`, `gas`, `chainId`, etc.) must be queried from the current chain state via RPC and filled in manually — there is no centralized API that generates them for you. Once the unsigned transaction is built, it is passed to Agent-wallet for local signing, which returns a hex-encoded signed transaction. That signed transaction is then broadcast to the network via `sendRawTransaction`.
+EVM transactions require the caller to construct the transaction object themselves. Unlike TRON, the fields of an EVM transaction (`nonce`, `gas`, `chainId`, etc.) must be queried from the current chain state via RPC and filled in manually — there is no centralized API that generates them for you. Once the unsigned transaction is built, it is passed to Agent-wallet for signing, which returns `{ family: "evm", rawTransaction }` with the hex-encoded signed transaction. That signed transaction is then broadcast to the network via `sendRawTransaction`.
 
 <ThemedImage
   alt="EVM transfer: RPC builds, Agent-wallet signs, RPC broadcasts"
@@ -276,34 +167,18 @@ The example uses BSC Testnet, but switching to Ethereum, Polygon, Base, or any o
 
 ### Install Dependencies
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```bash
 npm install @bankofai/agent-wallet ethers
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```bash
-pip install web3
-```
-
-</TabItem>
-</Tabs>
-
 ### Full Code
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```typescript
 import { resolveWalletProvider } from "@bankofai/agent-wallet";
 import { ethers } from "ethers";
 
 // BSC Testnet
-const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545";
+const RPC_URL = "https://bsc-testnet-rpc.publicnode.com";
 const CHAIN_ID = 97; // BSC testnet; use 56 for mainnet
 
 async function transferBNB(
@@ -338,13 +213,16 @@ async function transferBNB(
 
   console.log("Transaction built, nonce:", nonce);
 
-  // Step 4: Sign locally with Agent-wallet
-  const signedTxHex = await wallet.signTransaction(unsignedTx);
+  // Step 4: Sign with Agent-wallet — the result is a typed artifact
+  const signed = await wallet.signTransaction(unsignedTx);
+  if (signed.family !== "evm") {
+    throw new Error("Expected an EVM signing result — check the wallet network");
+  }
   console.log("Signed");
 
   // Step 5: Broadcast
-  // signTransaction returns hex without '0x' prefix; ethers requires it
-  const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex);
+  // rawTransaction is hex without the '0x' prefix; ethers requires it
+  const txResponse = await rpcProvider.broadcastTransaction("0x" + signed.rawTransaction);
   console.log("Broadcast successful! txHash:", txResponse.hash);
 
   // Wait for confirmation (optional — add timeout to avoid hanging)
@@ -365,82 +243,6 @@ transferBNB(
 ).catch(console.error);
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-from agent_wallet import resolve_wallet_provider
-from eth_utils import to_checksum_address
-from web3 import AsyncWeb3
-
-# BSC Testnet
-RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"
-CHAIN_ID = 97  # BSC testnet; use 56 for mainnet
-
-async def transfer_bnb(to_address: str, amount_ether: str):
-    # Step 1: Initialize Agent-wallet
-    provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}")
-    wallet = await provider.get_active_wallet()
-    from_address = await wallet.get_address()
-
-    # Step 2: Query nonce and gas info via RPC
-    w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL))
-    nonce = await w3.eth.get_transaction_count(from_address, "latest")
-    fee_data = await w3.eth.fee_history(1, "latest", [50])
-    base_fee = fee_data["baseFeePerGas"][-1]
-    priority_fee = await w3.eth.max_priority_fee
-
-    # Step 3: Build the unsigned transaction
-    unsigned_tx = {
-        # eth-account rejects a non-checksummed address
-        "to": to_checksum_address(to_address),
-        "value": w3.to_wei(amount_ether, "ether"),
-        "gas": 21000,
-        "maxFeePerGas": base_fee + priority_fee,
-        "maxPriorityFeePerGas": priority_fee,
-        "nonce": nonce,
-        "chainId": CHAIN_ID,
-        "type": 2,  # EIP-1559
-    }
-
-    print("Transaction built, nonce:", nonce)
-
-    # Step 4: Sign locally with Agent-wallet
-    signed_tx_hex = await wallet.sign_transaction(unsigned_tx)
-    print("Signed")
-
-    # Step 5: Broadcast
-    raw = signed_tx_hex[2:] if signed_tx_hex.startswith("0x") else signed_tx_hex
-    tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(raw))
-    print("Broadcast successful! txHash:", tx_hash.hex())
-
-    # Optional: wait for confirmation
-    # NOTE: This blocks the event loop for up to `timeout` seconds.
-    # For production AI agents, consider running this in a background task
-    # or using asyncio.wait_for() with a shorter timeout and retry logic.
-    try:
-        receipt = await asyncio.wait_for(
-            w3.eth.wait_for_transaction_receipt(tx_hash),
-            timeout=120
-        )
-        print("Confirmed in block:", receipt["blockNumber"])
-    except asyncio.TimeoutError:
-        print("Confirmation timed out — the transaction may still confirm. txHash:", tx_hash.hex())
-
-    return tx_hash.hex()
-
-# Example usage
-asyncio.run(
-    transfer_bnb(
-        to_address="0xYOUR_RECIPIENT_ADDRESS",  # replace with the recipient address
-        amount_ether="0.001",
-    )
-)
-```
-
-</TabItem>
-</Tabs>
 
 :::caution Notes
 - Use BSC Testnet (chainId=97) for testing. Get test tokens from the [BSC Faucet](https://testnet.binance.org/faucet-smart).
@@ -455,30 +257,27 @@ asyncio.run(
 
 **How it works**:
 
-x402 payments do not work by sending a direct transfer. Instead, they use a "sign first, verify to proceed" model. The agent signs a `TransferWithAuthorization` structure (EIP-712 format), and the resulting signature is sent alongside the request as a payment credential. The server verifies the signature and returns the content only if it is valid. The agent never has to wait for on-chain confirmation — latency is minimal.
+x402 payments do not work by sending a direct transfer. Instead, they use a "sign first, verify to proceed" model. The agent signs a `TransferWithAuthorization` structure (EIP-712 format), and the resulting signature is sent alongside the request as a payment credential. The server verifies the signature, settles the payment through the facilitator, and returns the content only after settlement succeeds; if settlement fails it returns `402` instead. Agent-wallet's part is only the local signature — it never broadcasts a transaction itself.
 
 :::note Which structure to sign
 This walkthrough signs EIP-3009 `TransferWithAuthorization` — the authorization Base USDC uses under the x402 `exact` scheme. It is not the same as the `PaymentPermit` typed-data struct in the repository's own x402 examples (`bsc-x402-sign-typed-data.ts`, `tron-x402-sign-typed-data.ts`), whose domain is `x402PaymentPermit` with primary type `PaymentPermitDetails` and fields `{ buyer, amount, nonce }`. Match whichever structure the server advertises in its `402` challenge. Which authorization applies is per token, not per chain: TRON's USDT/USDD and BSC's USDT/USDC settle through Permit2, while EIP-3009 tokens such as official Base USDC use `transferWithAuthorization` — see [Network and token support](../../x402/core-concepts/network-and-token-support.md).
 :::
 
 <ThemedImage
-  alt="x402 PaymentPermit: sign first, verify to proceed"
+  alt="x402 payment authorization: sign first, verify to proceed"
   sources={{
     light: '/img/diagrams/agent-wallet-x402-permit-flow.light.svg',
     dark: '/img/diagrams/agent-wallet-x402-permit-flow.svg',
   }}
 />
 
-The PaymentPermit data is automatically constructed by the x402 SDK based on the payment parameters returned by the server. Agent-wallet is only responsible for the final signing step. The example below shows the underlying signing logic, useful for scenarios that require custom integration or bypassing the x402 SDK.
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+The authorization data is automatically constructed by the x402 SDK based on the payment parameters returned by the server. Agent-wallet is only responsible for the final signing step. The example below shows the underlying signing logic, useful for scenarios that require custom integration or bypassing the x402 SDK.
 
 ```typescript
 import { resolveWalletProvider } from "@bankofai/agent-wallet";
-import type { Eip712Capable } from "@bankofai/agent-wallet";
+import type { Eip712Capable, Wallet } from "@bankofai/agent-wallet";
 
-async function signPaymentPermit(authorization: {
+async function signTransferWithAuthorization(authorization: {
   from: string;
   to: string;
   value: string;
@@ -487,6 +286,7 @@ async function signPaymentPermit(authorization: {
   nonce: string;
 }) {
   // Initialize Agent-wallet (EVM wallet, network must match the x402 payment network)
+  // With a wallet_cli wallet, Base needs wallet-cli 4.14.0 or later (earlier versions fail with network_mismatch)
   const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base mainnet
   const wallet = await provider.getActiveWallet();
 
@@ -519,67 +319,22 @@ async function signPaymentPermit(authorization: {
   };
 
   // signTypedData lives on Eip712Capable, not on the base Wallet interface
-  const signer = wallet as unknown as Eip712Capable;
+  if (!("signTypedData" in wallet)) {
+    throw new Error("This wallet cannot sign typed data");
+  }
+  const signer = wallet as Wallet & Eip712Capable;
 
-  // Sign locally with Agent-wallet
+  // Sign with Agent-wallet (hex signature without the 0x prefix)
   const signature = await signer.signTypedData(typedData);
-  console.log("PaymentPermit signature:", signature);
+  console.log("TransferWithAuthorization signature:", signature);
 
   return signature;
 }
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from agent_wallet import resolve_wallet_provider
-
-async def sign_payment_permit(authorization: dict) -> str:
-    # Initialize Agent-wallet (EVM wallet, network must match the x402 payment network)
-    provider = resolve_wallet_provider(network="eip155:8453")  # Base mainnet
-    wallet = await provider.get_active_wallet()
-
-    # Build EIP-712 typed data (aligned with the x402 protocol spec)
-    typed_data = {
-        "types": {
-            "EIP712Domain": [
-                {"name": "name", "type": "string"},
-                {"name": "version", "type": "string"},
-                {"name": "chainId", "type": "uint256"},
-                {"name": "verifyingContract", "type": "address"},
-            ],
-            "TransferWithAuthorization": [
-                {"name": "from", "type": "address"},
-                {"name": "to", "type": "address"},
-                {"name": "value", "type": "uint256"},
-                {"name": "validAfter", "type": "uint256"},
-                {"name": "validBefore", "type": "uint256"},
-                {"name": "nonce", "type": "bytes32"},
-            ],
-        },
-        "primaryType": "TransferWithAuthorization",
-        "domain": {
-            "name": "USD Coin",
-            "version": "2",
-            "chainId": 8453,
-            "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  # Base USDC
-        },
-        "message": authorization,
-    }
-
-    # Sign locally with Agent-wallet
-    signature = await wallet.sign_typed_data(typed_data)
-    print("PaymentPermit signature:", signature)
-
-    return signature
-```
-
-</TabItem>
-</Tabs>
 
 :::tip
-The x402 SDK automatically constructs the PaymentPermit data and calls the signing interface, so you typically won't need to write this code manually. The example above shows the underlying signing logic, which is useful for custom integration scenarios. See the [x402 Protocol documentation](../../x402/index.md) for details.
+The x402 SDK automatically constructs the authorization data and calls the signing interface, so you typically won't need to write this code manually. The example above shows the underlying signing logic, which is useful for custom integration scenarios. See the [x402 Protocol documentation](../../x402/index.md) for details.
 :::
 
 ---
@@ -590,15 +345,22 @@ The Agent-wallet repository includes additional ready-to-run examples covering m
 
 | Example | Description |
 | :--- | :--- |
+| `tron-sign-and-broadcast` | Build a TRX transfer via TronGrid, sign, and broadcast |
+| `bsc-sign-and-broadcast` | Build, sign, and broadcast a BSC transaction |
+| `wallet-cli-sign` | Sign through a configured `wallet_cli` wallet |
 | `dual-sign-typed-data-from-private-key` | Sign EIP-712 typed data on both TRON and EVM from a single private key |
 | `switch-active-wallet` | Programmatically switch between multiple wallets |
-| `create-wallet-provider` | Direct provider instantiation without auto-resolution (TypeScript only) |
+| `create-wallet-provider` | Resolve wallet providers with `resolveWalletProvider` |
 | `tron-x402-sign-typed-data` | x402 PaymentPermit signing on TRON |
 | `bsc-x402-sign-typed-data` | x402 PaymentPermit signing on BSC |
 | `verify-tron-privy-typed-data` | Verify Privy TRON EIP-712 signatures |
 | `compare-sign-consistency` | Cross-wallet signature consistency testing |
 
-The repository currently provides [TypeScript examples](https://github.com/BofAI/agent-wallet/tree/main/packages/typescript/examples).
+See the [TypeScript examples](https://github.com/BofAI/agent-wallet/tree/main/packages/typescript/examples).
+
+:::tip TRON transfers through wallet-cli
+With a `wallet_cli` wallet you can also let wallet-cli build and broadcast TRON transfers: `signAndBroadcast` from `@bankofai/agent-wallet/integrations/wallet-cli` runs build → sign → broadcast and returns `stage: "submitted"`; pass `wait: true` to also poll the transaction status until it is confirmed, fails, or times out. These helpers are TRON-only, and mainnet (`tron:728126428`) requires `confirmMainnet: true`.
+:::
 
 ---
 
diff --git a/docs/Agent-Wallet/Developer/SDK-Guide.md b/docs/Agent-Wallet/Developer/SDK-Guide.md
index af5cffeb..2511306c 100644
--- a/docs/Agent-Wallet/Developer/SDK-Guide.md
+++ b/docs/Agent-Wallet/Developer/SDK-Guide.md
@@ -1,35 +1,29 @@
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # SDK Guide
 
 You've tried the CLI and can sign from the command line. Now you want signing inside your own code — an MCP Server, an automation script, an AI agent workflow.
 
-This page shows you how. By the end, you'll be able to initialize a wallet provider, retrieve the active wallet, and sign messages, transactions, and EIP-712 typed data — all in a few lines of TypeScript or Python.
+This page shows you how. By the end, you'll be able to resolve a wallet, read its address, and sign transactions and EIP-712 / TIP-712 typed data with the `@bankofai/agent-wallet` 3.x TypeScript SDK.
 
 :::tip New here?
-If you haven't created a wallet yet, start with the [Quick Start](../QuickStart.md) first (takes under a minute). The SDK reads from the same wallet the CLI creates — no need to set up anything twice.
+If you haven't created a wallet yet, start with the [Quick Start](../QuickStart.md). The SDK reads the same `wallets_config.json` the CLI writes — no need to set up anything twice.
 :::
 
-Both installation instructions and code examples are provided for TypeScript and Python — use the tabs to switch.
+:::note Python SDK
+Agent-wallet 3.x is TypeScript only. The Python package `bankofai-agent-wallet` on PyPI stopped at 2.4.0 and follows the 2.x model (`local_secure`, master password, `sign_message`); it does not support the `wallet_cli` type or the 3.x signing results described here.
+:::
 
 ---
 
 ## Step 1: Install
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 **Check Your Node.js Version**
 
-Requires Node.js ≥ 18 — that is the package's own `engines` floor. Installing the current LTS is recommended: Node 18 reached end-of-life in April 2025 and Node 20 in April 2026. Check your current version:
+Use Node.js `^22.23.4 || ^24.22.1 || >=26.12.1` — the October 2026 security releases. This is the `engines` range on the source `main` branch; the published npm `3.0.0` still declares `>=18.0.0`, but wallet-cli `4.15.1` itself declares the same range. On `main`, when the `wallet_cli` wallet type launches wallet-cli through a JavaScript entrypoint with the current Node (a locally installed package, or an `AGENT_WALLET_WALLET_CLI_PATH` pointing at a `.js` file), it checks the same range first; a `wallet-cli` executable found on `PATH` is not checked. (In the published `3.0.0`, that entrypoint check only requires Node.js 20+.) Check your current version:
 
 ```bash
 node -v
 ```
 
-If the output is `v18.0.0` or higher, you can proceed directly to installation. Otherwise, follow the instructions below.
-
 :::tip Install / Upgrade Node.js
 
 We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions:
@@ -56,115 +50,26 @@ You can also download the **LTS** installer directly from [nodejs.org](https://n
 npm install @bankofai/agent-wallet
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-**Check Your Python Version**
-
-Requires Python ≥ 3.11 (the SDK uses 3.11+ features):
-
-```bash
-python3 --version
-```
-
-If the output is `3.11.x` or higher, you can proceed directly to installation. Otherwise, follow the instructions below.
-
-:::tip Install / Upgrade Python
-
-We recommend using [pyenv](https://github.com/pyenv/pyenv) to manage Python versions:
-
-```bash
-# Step 1: Install pyenv
-curl https://pyenv.run | bash
-```
-
-After installation, you need to add pyenv to your shell config manually — otherwise the terminal won't find the `pyenv` command:
-
-```bash
-# Append these three lines to ~/.bashrc (or ~/.zshrc for zsh users)
-echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
-echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
-echo 'eval "$(pyenv init -)"' >> ~/.bashrc
-
-# Reload config to apply changes in the current terminal
-source ~/.bashrc
-```
-
-Once pyenv is available, install the required system dependencies first. **Skipping this step will cause modules like `_ctypes` and `ssl` to be missing, which can break standard library imports including `asyncio`.**
-
-```bash
-# CentOS / RHEL / Amazon Linux / Fedora
-sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel
-
-# Ubuntu / Debian
-sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev
-```
-
-Then build Python:
-
-```bash
-pyenv install 3.11
-pyenv global 3.11
-```
-
-You can also download an installer from [python.org](https://www.python.org/downloads/), selecting **3.11 or higher**.
-
-:::
-
-**Install the SDK**
-
-```bash
-pip install bankofai-agent-wallet
-```
-
-Both chain stacks (`eth-account` for EVM and `tronpy` for TRON) are installed unconditionally — there are no per-chain extras.
-
-Verify the installation:
+The package ships both ESM and CommonJS builds. Only if you use `wallet_cli` wallets, also install the optional peer dependency:
 
 ```bash
-python3 -c "import agent_wallet; print('Installation successful')"
+npm install '@tron-walletcli/wallet-cli@^4.13.0'
 ```
 
-</TabItem>
-</Tabs>
-
 ---
 
-## Step 2: Configure a Mode
-
-Before calling the SDK, you need to tell Agent-wallet where to find your keys via environment variables.
-
-Don't be intimidated by the concepts — `resolveWalletProvider()` is extremely smart. It detects what is available — environment variables, a saved runtime-secrets password, or an existing local wallet config — and decides the mode for you. No `if/else` logic needed in your code.
-
-It supports two modes:
-
-### 🛡️ Core Usage: Local Agent-wallet Mode (Strongly Recommended)
-
-If you've already followed the [Quick Start](../QuickStart.md), your private key is already safely locked inside a hidden file on your machine.
-
-**In this mode, you never need to (and shouldn't) touch your plaintext private key.** Just tell the SDK your "unlock password" and you're good to go.
-
-```bash
-export AGENT_WALLET_PASSWORD='Abc12345!'
-# Optional: if you changed the wallet storage directory, tell the SDK where to look
-export AGENT_WALLET_DIR="$HOME/.agent-wallet"
-```
+## Step 2: Choose Where the Key Comes From
 
-:::caution Always use single quotes when the password contains special characters
-Auto-generated strong passwords may contain `$`, `!`, or other shell-special characters. Always use single quotes to prevent the shell from expanding and corrupting the password:
+`resolveWalletProvider()` / `resolveWallet()` decide the source for you — no `if/else` in your code:
 
-```bash
-# ✅ Correct: single quotes, password passed as-is
-export AGENT_WALLET_PASSWORD='P@ss$w0rd!'
+1. **Wallet config (recommended).** If `wallets_config.json` in the wallet directory (`dir` option → `AGENT_WALLET_DIR` → `~/.agent-wallet`) contains at least one wallet, a `ConfigWalletProvider` is used. It handles every wallet type the CLI can create: `wallet_cli`, `privy`, and `raw_secret`.
+2. **Environment variable fallback.** Otherwise an `EnvWalletProvider` reads a key from the environment.
 
-# ❌ Wrong: double quotes, $ gets expanded by the shell
-export AGENT_WALLET_PASSWORD="P@ss$w0rd!"
-```
-:::
+There is no password to export: `wallet_cli` credentials come from the exec script or value saved in the wallet config, and `privy` credentials are saved there too.
 
-### ⚠️ Fallback: Static Injection Mode (Test Environments Only)
+### Environment Variable Fallback {#environment-variable-fallback}
 
-If you're working in a disposable environment (e.g., a GitHub Actions CI pipeline), or you only have someone else's temporary test key, you can skip the local Agent-wallet and feed the private key directly to the SDK.
+For disposable environments (e.g. a CI pipeline with a throwaway test key) you can skip the wallet config and feed the key directly:
 
 ```bash
 export AGENT_WALLET_PRIVATE_KEY='your-private-key-in-hex'
@@ -172,163 +77,88 @@ export AGENT_WALLET_PRIVATE_KEY='your-private-key-in-hex'
 export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...'
 ```
 
-:::danger Extremely Dangerous: Violates Core Security Principles!
-Static mode reads your private key in plaintext, which means you forfeit Agent-wallet's encryption protection and fall back to the "single point of failure" approach described in the introduction. Only use this mode in fully isolated test environments or one-off CI/CD scripts! For mainnet operations with real funds, always use local Agent-wallet mode.
-:::
-
-:::tip What if environment variables conflict?
-If both a password and a private key exist in your environment variables, the SDK prioritizes security: it forces `AGENT_WALLET_PASSWORD` to enter local Agent-wallet mode and ignores the plaintext private key.
+:::danger Plaintext key
+This reads your private key in plaintext from the environment. Only use it in fully isolated test environments with throwaway keys. Setting both variables at once is an error.
 :::
 
 ### Environment Variable Reference
 
-| Variable | Purpose | Mode | Required |
-| :--- | :--- | :--- | :--- |
-| `AGENT_WALLET_PASSWORD` | Master password, unlocks the local hidden file | 🛡️ Local Agent-wallet | Core required |
-| `AGENT_WALLET_DIR` | Key directory (default `~/.agent-wallet`) | 🛡️ Local Agent-wallet | Optional |
-| `AGENT_WALLET_PRIVATE_KEY` | Plaintext private key (hex) | ⚠️ Static Injection | Choose one (with mnemonic) |
-| `AGENT_WALLET_MNEMONIC` | Plaintext mnemonic phrase | ⚠️ Static Injection | Choose one (with private key) |
-| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 derivation index (default `0`) | ⚠️ Static Injection | Optional |
+| Variable | Purpose | Used by |
+| :--- | :--- | :--- |
+| `AGENT_WALLET_DIR` | Wallet directory (default `~/.agent-wallet`) | Wallet config |
+| `AGENT_WALLET_WALLET_CLI_PATH` | wallet-cli executable or JavaScript entrypoint, when not on `PATH` | `wallet_cli` wallets |
+| `AGENT_WALLET_PRIVATE_KEY` | Plaintext private key (hex) | Env fallback — choose one |
+| `AGENT_WALLET_MNEMONIC` | Plaintext mnemonic phrase | Env fallback — choose one |
+| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | Mnemonic account index (default `0`) | Env fallback |
 
-:::note Legacy variable names
-The SDK still accepts the older `TRON_PRIVATE_KEY`, `TRON_MNEMONIC`, and `TRON_ACCOUNT_INDEX` variables, which map to `AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC`, and `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`. They work on EVM networks too, despite the name. Prefer the `AGENT_WALLET_*` names in new setups.
-:::
+The env fallback is only consulted when the wallet config has no wallets. The 2.x names `TRON_PRIVATE_KEY`, `TRON_MNEMONIC`, `TRON_ACCOUNT_INDEX` and `AGENT_WALLET_PASSWORD` are no longer read.
 
 ---
 
 ## Usage Examples
 
-### Initialize the Wallet Provider
-
-The starting point for all operations is `resolveWalletProvider()`. It selects the appropriate mode and returns a wallet provider; call `getActiveWallet()` to get the active wallet. Selection is not driven by environment variables alone: a password saved in the runtime-secrets file counts too, and if the wallet directory already holds any wallet, local mode wins even with no environment variable set at all.
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
-```typescript
-import { resolveWalletProvider } from "@bankofai/agent-wallet";
-
-const provider = resolveWalletProvider({ network: "tron:nile" });
-const wallet = await provider.getActiveWallet();
-
-// Check the current wallet address
-const address = await wallet.getAddress();
-console.log("Address:", address);
-```
+### Networks
 
-</TabItem>
-<TabItem value="python" label="Python">
+Every `network` option takes an exact canonical CAIP-2 string: `eip155:<chainId>` (e.g. `eip155:1`, `eip155:56`, `eip155:97`) or `tron:<chainId>` (`tron:728126428` mainnet, `tron:3448148188` Nile, `tron:2494104990` Shasta). Aliases such as `tron:nile`, `tron:mainnet`, bare `tron` / `eip155`, hex TRON ids, and case or whitespace variants throw a `NetworkError`.
 
-```python
-import asyncio
-from agent_wallet import resolve_wallet_provider
+`raw_secret`, env-fallback and `wallet_cli` wallets **require** a network — it selects the EVM or TRON signer (and, for a mnemonic, the derivation path `m/44'/60'/0'/0/{index}` or `m/44'/195'/0'/0/{index}`). `privy` wallets may omit it.
 
-provider = resolve_wallet_provider(network="tron:nile")
+For `wallet_cli` wallets the network must also be one wallet-cli itself knows — its built-ins (`eip155:1`, `eip155:11155111`, `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532` (the two Base networks were added in wallet-cli 4.14.0) and the three TRON networks) or a network added to wallet-cli's own config — otherwise signing fails with `network_mismatch`. `raw_secret` and `privy` wallets have no such limit.
 
-async def main():
-    wallet = await provider.get_active_wallet()
+### Resolve a Wallet
 
-    # Check the current wallet address
-    address = await wallet.get_address()
-    print("Address:", address)
-
-asyncio.run(main())
-```
-
-</TabItem>
-</Tabs>
-
-Once you have `wallet`, you can call any of the three signing methods below. `signMessage` and `signTypedData` return a hex-encoded signature string (without the `0x` prefix); `signTransaction` returns the full serialized signed transaction — hex without `0x` on EVM, and a JSON string on TRON. `signTypedData` is declared on a separate `Eip712Capable` interface rather than on `Wallet`, in both languages. TypeScript enforces this, so cast the wallet before calling it; Python only enforces it at type-check time — the call works at runtime, and the repo's own idiom for keeping type checkers happy is an `isinstance(wallet, Eip712Capable)` guard.
-
-#### Shortcut: `resolveWallet()`
-
-When you only need the wallet and never touch the provider itself, `resolveWallet()` collapses both steps into one call. It takes the same `network` and `dir` options, plus an optional `walletId` to pick a specific wallet instead of the active one. `walletId` applies to local wallet-config mode only — in static-injection mode it is ignored and the environment wallet is returned.
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+The shortest path is `resolveWallet()`. It takes `network`, `dir`, and an optional `walletId` to pick a specific configured wallet instead of the active one (ignored in env-fallback mode):
 
 ```typescript
 import { resolveWallet } from "@bankofai/agent-wallet";
 
-const wallet = await resolveWallet({ network: "tron:nile" });
+const wallet = await resolveWallet({ network: "tron:3448148188" });
+console.log("Address:", await wallet.getAddress());
 
 // Or target a specific wallet instead of the active one
-const other = await resolveWallet({ network: "tron:nile", walletId: "trading" });
-```
-
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-from agent_wallet import resolve_wallet
-
-async def main():
-    wallet = await resolve_wallet(network="tron:nile")
-
-    # Or target a specific wallet instead of the active one
-    other = await resolve_wallet(network="tron:nile", wallet_id="trading")
-
-asyncio.run(main())
+const other = await resolveWallet({ network: "eip155:56", walletId: "trading" });
 ```
 
-</TabItem>
-</Tabs>
-
-Both functions also accept `dir` to point at a wallet directory other than `~/.agent-wallet`, which is the programmatic equivalent of the `AGENT_WALLET_DIR` environment variable.
-
-:::note Privy authorization keys
-Every signing method takes an optional second argument, `SignOptions`. Its only field is forwarded as the `privy-authorization-signature` header — required when a Privy wallet is governed by an authorization-key policy. Local wallets ignore it. The field is `authorizationSignature` in TypeScript and `authorization_signature` in Python:
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+When you need the provider itself, use `resolveWalletProvider()`:
 
 ```typescript
-await wallet.signMessage(message, { authorizationSignature });
-```
-
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from agent_wallet import SignOptions
+import { resolveWalletProvider } from "@bankofai/agent-wallet";
 
-await wallet.sign_message(message, SignOptions(authorization_signature=signature))
+const provider = resolveWalletProvider({ network: "tron:3448148188" });
+const wallet = await provider.getActiveWallet();     // or getActiveWallet("eip155:56")
 ```
 
-</TabItem>
-</Tabs>
-:::
-
-### Sign a Message
+Both functions accept `dir`, the programmatic equivalent of `AGENT_WALLET_DIR`.
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+### The `Wallet` Interface
 
 ```typescript
-const sig = await wallet.signMessage(new TextEncoder().encode("Hello"));
-console.log("Signature:", sig);
-```
+interface Wallet {
+  getAddress(): Promise<string>;
+  signTransaction(payload: TransactionPayload, options?: SignOptions): Promise<SignedTransactionArtifact>;
+}
 
-</TabItem>
-<TabItem value="python" label="Python">
+interface Eip712Capable {
+  signTypedData(data: Record<string, unknown>, options?: SignOptions): Promise<string>;
+}
 
-```python
-sig = await wallet.sign_message(b"Hello")
-print("Signature:", sig)
+type SignOptions = {
+  authorizationSignature?: string; // forwarded to Privy as privy-authorization-signature
+  signal?: AbortSignal;            // cancels a wallet-cli signing subprocess
+};
 ```
 
-</TabItem>
-</Tabs>
+- `signTransaction` returns a typed artifact: `{ family: "evm", rawTransaction }` (hex **without** `0x`) or `{ family: "tron", transaction }` (the transaction object with `txID` and `signature` attached). Branch on `family` — don't parse strings.
+- `signTypedData` returns a hex signature **without** the `0x` prefix. It lives on the separate `Eip712Capable` interface; check for it before calling (all three built-in wallet types implement it).
+- There is no `signMessage` or `signRaw` in 3.x.
 
 ### Sign a Transaction
 
-Agent-wallet only handles signing — not building or broadcasting. You need to construct the unsigned transaction via RPC (e.g. TronGrid, Infura) first, then pass it to the SDK for signing.
+Agent-wallet only handles signing — not building or broadcasting. You need to construct the unsigned transaction via RPC (e.g. TronGrid, an EVM node) first, then pass it to the SDK.
 
 #### TRON Transaction
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+The payload must contain `raw_data_hex` (as returned by TronGrid). For `raw_secret`, `privy` and environment-variable wallets a missing `txID` is computed from `raw_data_hex`. A `wallet_cli` wallet needs the complete transaction — `raw_data`, `raw_data_hex` and a `txID` equal to the SHA-256 of `raw_data_hex` — or wallet-cli refuses to sign.
 
 ```typescript
 // 1. Caller builds the unsigned transaction via TronGrid
@@ -338,41 +168,18 @@ const unsignedTx = {
   raw_data: { /* raw data returned by TronGrid */ },
 };
 
-// 2. SDK signs locally (no network call)
-const signedTxJson = await wallet.signTransaction(unsignedTx);
-console.log("Signed transaction:", signedTxJson);
+// 2. SDK signs (raw_secret signs in-process; wallet_cli delegates to wallet-cli)
+const signed = await wallet.signTransaction(unsignedTx);
+if (signed.family !== "tron") throw new Error("expected a TRON wallet");
+console.log("Signed transaction:", signed.transaction);
 
-// 3. Caller is responsible for broadcasting
+// 3. Caller broadcasts signed.transaction
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-# 1. Caller builds the unsigned transaction via TronGrid
-unsigned_tx = {
-    "txID": "abc123...",
-    "raw_data_hex": "0a02...",
-    "raw_data": {},  # raw data returned by TronGrid
-}
-
-# 2. SDK signs locally (no network call)
-signed_tx_json = await wallet.sign_transaction(unsigned_tx)
-print("Signed transaction:", signed_tx_json)
-
-# 3. Caller is responsible for broadcasting
-```
-
-</TabItem>
-</Tabs>
-
 #### EVM Transaction (BSC, Ethereum, etc.)
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```typescript
-const signedTxHex = await wallet.signTransaction({
+const signed = await wallet.signTransaction({
   type: "eip1559",
   to: "0xRecipient...",
   value: 0n,
@@ -382,45 +189,26 @@ const signedTxHex = await wallet.signTransaction({
   nonce: 0,
   chainId: 56,
 });
-console.log("Signed tx:", signedTxHex);
-```
-
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from eth_utils import to_checksum_address
-
-signed_tx_hex = await wallet.sign_transaction({
-    "type": 2,  # optional here — what eth-account requires is BOTH fee fields, or gasPrice for a legacy tx
-    "to": to_checksum_address("0xRecipient..."),
-    "value": 0,
-    "gas": 21000,
-    "maxFeePerGas": 20000000000,
-    "maxPriorityFeePerGas": 1000000000,
-    "nonce": 0,
-    "chainId": 56,
-})
-print("Signed tx:", signed_tx_hex)
+if (signed.family !== "evm") throw new Error("expected an EVM wallet");
+console.log("Signed tx:", "0x" + signed.rawTransaction);
 ```
 
-</TabItem>
-</Tabs>
+`wallet_cli` wallets additionally reject a `chainId` that doesn't match the wallet's network, already-signed payloads, and EIP-4844 / EIP-7702 transactions.
 
 ### Sign EIP-712 Typed Data
 
-Used for x402 protocol PaymentPermit signatures, Permit2, and similar scenarios:
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+Used for x402 payment authorizations, Permit2, and similar scenarios:
 
 ```typescript
-import type { Eip712Capable } from "@bankofai/agent-wallet";
+import type { Eip712Capable, Wallet } from "@bankofai/agent-wallet";
+
+function supportsTypedData(wallet: Wallet): wallet is Wallet & Eip712Capable {
+  return "signTypedData" in wallet && typeof wallet.signTypedData === "function";
+}
 
-// signTypedData lives on Eip712Capable, not on the base Wallet interface
-const signer = wallet as unknown as Eip712Capable;
+if (!supportsTypedData(wallet)) throw new Error("wallet cannot sign typed data");
 
-const sig = await signer.signTypedData({
+const sig = await wallet.signTypedData({
   types: {
     EIP712Domain: [
       { name: "name", type: "string" },
@@ -438,119 +226,60 @@ const sig = await signer.signTypedData({
 console.log("Signature:", sig);
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-sig = await wallet.sign_typed_data({
-    "types": {
-        "EIP712Domain": [
-            {"name": "name", "type": "string"},
-            {"name": "chainId", "type": "uint256"},
-        ],
-        "Transfer": [
-            {"name": "to", "type": "address"},
-            {"name": "amount", "type": "uint256"},
-        ],
-    },
-    "primaryType": "Transfer",
-    "domain": {"name": "MyDApp", "chainId": 1},
-    "message": {"to": "0x...", "amount": 1000000},
-})
-print("Signature:", sig)
-```
-
-</TabItem>
-</Tabs>
-
 ---
 
 ### Manage Multiple Wallets
 
-If you need to manage multiple wallets in code, use `resolveWalletProvider()` in local mode. The provider reads the wallet configuration and lets you switch the active wallet:
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+`ConfigWalletProvider` reads and edits the wallet configuration. You get one from `resolveWalletProvider()` (when wallets are configured) or by constructing it directly with `new ConfigWalletProvider(dir, { network })`:
 
 ```typescript
 import { resolveWalletProvider, ConfigWalletProvider } from "@bankofai/agent-wallet";
 
-// Local mode: AGENT_WALLET_PASSWORD must be set
-const provider = resolveWalletProvider({ network: "tron:nile" });
+const provider = resolveWalletProvider({ network: "tron:3448148188" });
 
 if (provider instanceof ConfigWalletProvider) {
   // List all wallets — returns [walletId, config, isActive] tuples
-  const wallets = provider.listWallets();
-  for (const [id, config, isActive] of wallets) {
+  for (const [id, config, isActive] of provider.listWallets()) {
     console.log(`${id} (${config.type})${isActive ? " ← active" : ""}`);
   }
 
-  // Switch the active wallet
+  // Switch the active wallet (persisted to wallets_config.json)
   provider.setActive("my-evm-wallet");
+
+  // Or use a specific wallet on a specific network without switching
+  const bsc = await provider.getWallet("my-evm-wallet", "eip155:56");
 }
 
-// Get and use
+// With no active wallet set, this falls back to the first configured wallet
 const wallet = await provider.getActiveWallet();
-const sig = await wallet.signMessage(new TextEncoder().encode("Hello"));
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-from agent_wallet import resolve_wallet_provider, ConfigWalletProvider
-
-# AGENT_WALLET_PASSWORD must be set
-provider = resolve_wallet_provider(network="tron:nile")
-
-async def main():
-    if isinstance(provider, ConfigWalletProvider):
-        # List all wallets — returns [(wallet_id, config, is_active)] tuples
-        wallets = provider.list_wallets()
-        for wallet_id, config, is_active in wallets:
-            print(f"{wallet_id} ({config.type}){'  ← active' if is_active else ''}")
-
-        # Switch the active wallet
-        provider.set_active("my-evm-wallet")
-
-    # Get and use
-    wallet = await provider.get_active_wallet()
-    sig = await wallet.sign_message(b"Hello")
-    print("Signature:", sig)
-
-asyncio.run(main())
-```
-
-</TabItem>
-</Tabs>
-
 ---
 
 ### Error Handling
 
-When a signing operation fails, the SDK throws specific error types. It's recommended to catch and handle them explicitly in your code to avoid runtime crashes.
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+The SDK's typed errors extend `WalletError`. A few setup and input failures are thrown as plain `Error` instead: no wallet source found (no configured wallets and no `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`), both of those env vars set at once, a malformed private key, or an invalid `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`. Catch the specific types you can handle:
 
 ```typescript
 import {
   WalletNotFoundError,
+  NetworkError,
   SigningError,
-  DecryptionError,
+  WalletCliNotFoundError,
+  WalletCliExecutionError,
 } from "@bankofai/agent-wallet";
 
 try {
   const wallet = await provider.getActiveWallet();
-  const sig = await wallet.signMessage(new TextEncoder().encode("Hello"));
-  console.log("Signature:", sig);
+  const signed = await wallet.signTransaction(unsignedTx);
 } catch (e) {
   if (e instanceof WalletNotFoundError) {
-    console.error("Wallet not found — check that an active wallet is set");
-  } else if (e instanceof DecryptionError) {
-    console.error("Decryption failed — check that the master password is correct");
-  } else if (e instanceof SigningError) {
+    console.error("Wallet not found — check the wallet id");
+  } else if (e instanceof NetworkError) {
+    console.error("Invalid or mismatched network — use canonical CAIP-2, e.g. tron:3448148188");
+  } else if (e instanceof WalletCliNotFoundError) {
+    console.error("wallet-cli is not installed or not on PATH");
+  } else if (e instanceof WalletCliExecutionError || e instanceof SigningError) {
     console.error("Signing failed:", e.message);
   } else {
     throw e;
@@ -558,60 +287,46 @@ try {
 }
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from agent_wallet import WalletNotFoundError, SigningError, DecryptionError
-
-try:
-    wallet = await provider.get_active_wallet()
-    sig = await wallet.sign_message(b"Hello")
-    print("Signature:", sig)
-except WalletNotFoundError:
-    print("Wallet not found — check that an active wallet is set")
-except DecryptionError:
-    print("Decryption failed — check that the master password is correct")
-except SigningError as e:
-    print(f"Signing failed: {e}")
-```
-
-</TabItem>
-</Tabs>
-
-Error type hierarchy:
+Error type hierarchy (all exported from the package root):
 
 ```
 WalletError
-├── WalletNotFoundError        # Specified wallet not found
-├── DecryptionError            # Wrong password or corrupted key file
-├── SigningError               # Signing operation failed
-├── NetworkError               # Network identifier mismatch
-├── InsufficientBalanceError   # Insufficient balance
-├── UnsupportedOperationError  # Operation not supported by this wallet type
-├── PrivyConfigError           # Privy wallet configuration error
-├── PrivyRequestError          # Privy API request failed
-├── PrivyRateLimitError        # Privy API rate limit exceeded
-└── PrivyAuthError             # Privy authentication failed
-```
-
-:::note Python imports
-TypeScript exports all of the above from the package root. Python's top-level `agent_wallet` exports only `WalletError`, `WalletNotFoundError`, `DecryptionError`, `SigningError`, `NetworkError`, and `UnsupportedOperationError`. Import the remaining five from `agent_wallet.core.errors`:
-
-```python
-from agent_wallet.core.errors import (
-    InsufficientBalanceError,
-    PrivyConfigError,
-    PrivyRequestError,
-    PrivyRateLimitError,
-    PrivyAuthError,
-)
-```
+├── WalletNotFoundError              # Specified wallet id not found (or no wallets configured)
+├── DecryptionError                  # Kept for compatibility; not thrown by 3.x wallet types
+├── InsufficientBalanceError         # Not thrown by the SDK; for your own code
+├── SigningError                     # Signing operation failed or payload rejected
+├── NetworkError                     # Non-canonical or mismatched network
+├── UnsupportedOperationError        # Operation not supported by this wallet
+└── ExternalSignerError
+    ├── ExternalSignerConfigError
+    │   ├── PrivyConfigError
+    │   └── WalletCliConfigError
+    ├── ExternalSignerExecutionError
+    │   ├── PrivyRequestError
+    │   ├── PrivyRateLimitError
+    │   ├── PrivyAuthError
+    │   └── WalletCliExecutionError
+    │       └── WalletCliSubmittedTransactionError
+    ├── ExternalSignerUsageError
+    │   └── WalletCliUsageError
+    └── ExternalSignerNotFoundError
+        └── WalletCliNotFoundError
+```
+
+`WalletCliExecutionError` and `WalletCliUsageError` carry a `code`. Codes raised by agent-wallet itself: `capability_missing` (the wallet-cli executable cannot sign this family; an account without an address for the family raises `contract_mismatch`), `network_mismatch` (network unknown to wallet-cli; checked after the capability), `contract_mismatch`, `unsupported_version`, `unsupported_runtime`, `migration_required` / `migration_completed` / `migration_cancelled`, `timeout`, `aborted`, `spawn_error`, `stdin_write`, `output_limit`, `status_query_failed`, and `internal_error` when wallet-cli's failure envelope has an empty `code` (an envelope with no `code` at all raises `contract_mismatch`). When wallet-cli returns a failure envelope, its own code is passed through unchanged (for example `account_not_found`, `auth_failed`): exit `2` becomes `WalletCliUsageError`, exit `1` becomes `WalletCliExecutionError`. A `wallet_cli` transaction whose `chainId` does not match `-n` is rejected with `SigningError`, not `NetworkError`.
+
+:::tip Don't auto-retry wallet-cli timeouts
+If `signAndBroadcast()` from `@bankofai/agent-wallet/integrations/wallet-cli` times out, don't resend automatically — check the result first. Two timeouts are not exceptions: when the broadcast times out with a known `txId`, or when the `wait: true` polling deadline passes, the call returns `{ txId, stage: 'timeout' }`. A timeout while building or signing, or a broadcast timeout before any `txId` is known, throws `WalletCliExecutionError` with code `timeout`. `WalletCliSubmittedTransactionError` is thrown only when, with `wait: true`, a status query fails after the transaction was broadcast (including a status query that itself times out, in which case its `code` is `timeout`); it carries that `txId`. Plain `signTransaction()` never broadcasts, so it never throws this error.
 :::
 
-:::tip About InsufficientBalanceError
-`InsufficientBalanceError` is **not** thrown by the SDK itself — Agent-wallet is a sign-only tool and does not check balances. This error type is provided as a convenience for your application code to throw when you detect insufficient funds before initiating a transaction.
-:::
+### Advanced Entry Points
+
+| Import path | Contents |
+| :--- | :--- |
+| `@bankofai/agent-wallet` | `resolveWallet`, `resolveWalletProvider`, `ConfigWalletProvider`, `EnvWalletProvider`, `Network`, `WalletType`, `loadConfig` / `saveConfig`, types and errors |
+| `@bankofai/agent-wallet/advanced` | Low-level adapters and clients (`EvmSigner`, `TronSigner`, `RawSecretSigner`, `PrivyAdapter`, `WalletCliAdapter`, `PrivyClient`, `WalletCliClient`), secret providers (`ExecSecretProvider`, `StaticSecretProvider`) |
+| `@bankofai/agent-wallet/advanced` (continued) | Also `LocalSigner`, the config resolvers (`ExternalSignerConfigResolver`, `PrivyConfigResolver`, `WalletCliConfigResolver`), `resolveSecret` / `isSecretRef` / `DEFAULT_EXEC_TIMEOUT_MS` / `DEFAULT_SECRET_STDOUT_LIMIT` / `DEFAULT_SECRET_STDERR_LIMIT`, `defaultSecretProviderFactory`, and `parseWalletCliNetwork` / `assertTronWalletCliNetwork` |
+| `@bankofai/agent-wallet/integrations/wallet-cli` | TRON-only helpers that use wallet-cli for build / broadcast / status: `signAndBroadcast`, `buildTransfer`, `broadcast`, `getTxStatus`, `getBalance`, `getTxInfo` |
 
 ---
 
diff --git a/docs/Agent-Wallet/FAQ.md b/docs/Agent-Wallet/FAQ.md
index 8e6cb54a..44ebd95d 100644
--- a/docs/Agent-Wallet/FAQ.md
+++ b/docs/Agent-Wallet/FAQ.md
@@ -1,45 +1,54 @@
 # FAQ
 
-Let's answer the three things you're probably most worried about, then cover the day-to-day details.
+Let's answer the things you're probably most worried about, then cover the day-to-day details.
 
 ---
 
 ## 💰 Will AI drain my entire wallet?
 
-This is the most common question, and the answer is: **even if your AI agent gets compromised, your core assets stay safe.**
-
-We strongly recommend creating a dedicated wallet just for your AI agent, topped up with only the small amount it actually needs (e.g., enough to cover gas fees). Your main wallet and large holdings never get touched. Worst case, the loss is limited to whatever was in that small agent wallet.
+The best protection is to limit what's at stake: **create a dedicated wallet just for your AI agent**, topped up with only the small amount it actually needs (e.g., enough to cover gas fees). Your main wallet and large holdings never get touched. Worst case, the loss is limited to whatever was in that small agent wallet.
 
 ```bash
-# Create a dedicated small wallet for your AI agent
-agent-wallet add
+# Create a dedicated wallet-cli account for your agent, then link it
+wallet-cli create --label agent-small -o json
+agent-wallet add wallet_cli --wallet-id agent_small --account agent-small \
+  --cli-password-exec /absolute/path/to/fetch-password.sh
 ```
 
-And your wallet file is protected by strong encryption. Even if someone gets hold of the file, without the master password it's just garbage — brute-forcing it is economically worthless.
+With a `wallet_cli` wallet, the key itself sits in wallet-cli's encrypted keystore — Agent-wallet's config only holds the wallet-cli account ID and a password source.
 
 ---
 
 ## 🔌 Can my AI still sign if I go offline?
 
-Yes, for `local_secure` and `raw_secret` wallets: **signing completes 100% on your local machine** — no RPC calls, no cloud services, no remote API requests, and your private key never touches the network.
-
-The one exception is the `privy` wallet type, which custodies the key with Privy and sends signing requests to Privy's API — it requires network by design.
+`raw_secret` wallets sign in-process with no network calls, and `wallet_cli` wallets sign in a local wallet-cli subprocess. The `privy` wallet type is different: the key is custodied by Privy and signing requests go to Privy's API, so it needs network by design.
 
-Going offline only affects transaction building and broadcasting (that's the MCP Server's job). Signing itself is fully offline.
+Going offline mainly affects building and broadcasting transactions (the MCP server's or your own code's job).
 
 ---
 
-## 🔑 What if I forget my password?
+## 🔑 Is there still a master password? What if I forget it?
+
+### I used `local_secure` and `AGENT_WALLET_PASSWORD` in 2.x — what now? {#upgrade-from-2x}
 
-**It's gone.**
+Agent-wallet 3.0 removed the `local_secure` wallet type, the agent-wallet master password, `AGENT_WALLET_PASSWORD`, `runtime_secrets.json`, and the `init`, `change-password` and `sign msg` commands. 3.x does not read or convert `local_secure` wallets.
 
-The master password is the only credential for decrypting all private keys. There's no "forgot password" flow, no backdoor.
+Before upgrading:
 
-If you forget your password:
-- Have another backup of your private key or mnemonic? Run `agent-wallet reset`, reinitialize, and reimport.
-- No backup at all? Access to that wallet is lost.
+1. Back up `~/.agent-wallet`.
+2. With 2.x still installed, make sure you can access the original private key or mnemonic.
+3. Move the 2.x directory out of the way, for example `mv ~/.agent-wallet ~/.agent-wallet-2x`. 3.x rejects a `wallets_config.json` that still lists `local_secure` wallets (`Invalid wallet config`), so every command that loads the config — including `start` — fails until the old file is gone (`reset` still works). Alternatively, point 3.x at a new directory with `--dir` or `AGENT_WALLET_DIR`.
+4. After upgrading, re-create the wallet with one of the 3.x types:
+   - **Local production signing:** import the key into wallet-cli (`wallet-cli import private-key` or `wallet-cli import mnemonic`), then `agent-wallet start wallet_cli`.
+   - **Hosted signing:** `agent-wallet start privy`.
+   - **Development only:** `agent-wallet start raw_secret`.
+5. Confirm the new wallet resolves the expected address (`agent-wallet resolve-address`) and can sign, then delete the old 2.x directory yourself.
 
-**So do this right now**: open your password manager and store the master password. Seriously.
+Also update environment variables: `TRON_PRIVATE_KEY`, `TRON_MNEMONIC` and `TRON_ACCOUNT_INDEX` are no longer read — use `AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC` and `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`. Network values must be canonical (`tron:728126428`, `tron:3448148188`, `eip155:1` …).
+
+### What if I forget the wallet-cli password?
+
+The password that protects a `wallet_cli` wallet belongs to wallet-cli's keystore, not to Agent-wallet. Agent-wallet cannot recover it. Restore the account in wallet-cli from your mnemonic or private-key backup (`wallet-cli import mnemonic` / `wallet-cli import private-key`), then link it to Agent-wallet again.
 
 ---
 
@@ -47,95 +56,86 @@ If you forget your password:
 
 ### What exactly is Agent-wallet?
 
-A purely local encrypted signing tool. It does two things: 1) encrypts and stores your private keys; 2) signs locally. No internet, no cloud. It has no standalone UI of its own — instead, it operates as an invisible security hub that integrates seamlessly into AI frontends like OpenClaw.
+A signing layer for AI agents. It gives your code one interface — `getAddress`, `signTransaction`, `signTypedData` — and routes each request to the key backend you configured (`wallet_cli`, `privy`, or `raw_secret`). It doesn't build or broadcast transactions, and it has no UI of its own.
+
+### Agent-wallet or wallet-cli — which do I need?
+
+- **wallet-cli** holds keys (encrypted keystore) and is the official setup entry for new users and BANK OF AI tools. See [wallet-cli](../wallet-cli/quickstart.md).
+- **Agent-wallet** is for code that is built on the `@bankofai/agent-wallet` SDK. With the `wallet_cli` type it signs through your wallet-cli account, so both can share one key.
 
 ### CLI vs SDK — which do I need?
 
-- **CLI** — command-line tool for creating wallets, managing keys, and manually testing signatures
-- **SDK** — TypeScript / Python library for calling signing directly from your own code
+- **CLI** — command-line tool for configuring wallets and manually testing signatures
+- **SDK** — TypeScript library for calling signing directly from your own code
 
-Most users don't need the SDK. If you're using OpenClaw and MCP Server, creating a wallet with the CLI and setting the environment variable is all you need. The SDK is for developers building their own agents.
+The SDK reads the configuration the CLI creates.
 
-### What's the difference between Agent-wallet and MetaMask?
+### Can I sign a plain message?
 
-MetaMask is a browser wallet designed for humans, with a graphical interface that requires you to manually click "Confirm" for every signature. Agent-wallet is a command-line wallet designed for AI agents, purpose-built for non-interactive use — AI can silently invoke signing in the background without anyone watching the screen. Both use similar encryption under the hood (Keystore V3), but they serve completely different use cases.
+No. 3.x signs transactions and EIP-712 / TIP-712 typed data only; `sign msg`, `signMessage()` and `signRaw()` were removed.
 
 ### How many wallets can I create on one machine?
 
-No limit. You can create separate wallets for different AI agents, different chains, or different purposes. Use `agent-wallet add` to create and `agent-wallet use` to switch between them.
+No limit. You can configure separate wallets for different AI agents, different chains, or different purposes. Use `agent-wallet add` to add and `agent-wallet use` to switch between them.
 
 ---
 
 ## Wallet Types
 
-### What's the difference between `local_secure`, `raw_secret`, and `privy`?
+### What's the difference between `wallet_cli`, `privy`, and `raw_secret`?
 
-| | `local_secure` | `raw_secret` | `privy` |
+| | `wallet_cli` | `privy` | `raw_secret` |
 | :--- | :---: | :---: | :---: |
-| **Key storage** | ✅ Encrypted locally | ❌ Plaintext locally | ☁️ Privy cloud custody |
-| **If an agent reads the file** | ✅ Key is inaccessible | ❌ Stolen instantly | ✅ No local key file |
-| **Requires master password** | ✅ Yes | ❌ No | ❌ No (uses API credentials) |
-| **Use case** | ✅ All scenarios | ⚠️ Fully isolated dev only | ✅ Server-side agents with Privy |
+| **Key storage** | ✅ wallet-cli encrypted keystore | ☁️ Privy cloud custody | ❌ Plaintext in `wallets_config.json` |
+| **If an agent reads Agent-wallet's config** | ✅ No key inside (only a wallet-cli account ID and password source) | ✅ No key inside (API credentials; the app secret can be an exec script) | ❌ Key stolen instantly |
+| **Network needed to sign** | No | Yes (Privy API) | No |
+| **Use case** | ✅ Local production signing | ✅ Server-side agents with Privy | ⚠️ Fully isolated dev only |
 
 :::danger `raw_secret` exposes your private key as plaintext
-`raw_secret` stores your key unencrypted — the exact exposure `local_secure` mode is designed to prevent. If any other process on your machine can read files, your key can be stolen instantly. **Always use `local_secure`** unless you're 100% certain no other agent is running on that machine and it's a fully isolated, offline test environment.
+Any process that can read files in your home directory can read the key. Use `raw_secret` only with throwaway keys in a fully isolated test environment.
 :::
 
-:::tip Privy wallets
-The `privy` type delegates key custody to [Privy](https://privy.io)'s server-side wallet infrastructure. No private key is stored on your local disk — signing requests are sent to Privy's API. This is ideal for server-side AI agents that already use Privy for wallet management. You'll need a Privy App ID, App Secret, and Wallet ID to set it up.
+:::tip Store wallet-cli and Privy secrets as exec scripts
+Use `--cli-password-exec` / `--app-secret-exec` so the secret is fetched (for example from 1Password) when needed instead of being written into `wallets_config.json`. A password typed at the `direct` prompt is stored there in plaintext (file mode `0600`).
 :::
 
 ### What values does the `network` parameter accept?
 
+Exact canonical CAIP-2 identifiers only:
+
 | Value | Description |
 | :--- | :--- |
-| `tron:mainnet` | TRON Mainnet |
-| `tron:nile` | TRON Nile Testnet |
-| `tron:shasta` | TRON Shasta Testnet |
+| `tron:728126428` | TRON Mainnet |
+| `tron:3448148188` | TRON Nile Testnet |
+| `tron:2494104990` | TRON Shasta Testnet |
 | `eip155:1` | Ethereum Mainnet |
 | `eip155:56` | BSC Mainnet |
+| `eip155:97` | BSC Testnet |
 | `eip155:137` | Polygon Mainnet |
 | `eip155:8453` | Base Mainnet |
 | `eip155:42161` | Arbitrum Mainnet |
 
-> These are common examples, not an exhaustive whitelist: agent-wallet validates only the family prefix, so any `eip155:<chainId>` or `tron:<network>` value is accepted (including the canonical CAIP-2 TRON ids like `tron:0x2b6653dc` that the x402 tooling requires).
+> These are common examples, not a whitelist: any `eip155:<positive chainId>` or `tron:<positive chainId>` is accepted. Aliases (`tron:nile`, `tron:mainnet`, `evm:1`), bare `tron` / `eip155`, hex TRON ids such as `tron:0x2b6653dc`, and case or whitespace variants are rejected.
+>
+> For `wallet_cli` wallets the network must also be one wallet-cli itself knows — its built-ins (`eip155:1`, `eip155:11155111`, `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532` (the two Base networks were added in wallet-cli 4.14.0) and the three TRON networks in the table) or a network added to wallet-cli's own config — otherwise signing fails with `network_mismatch`. `raw_secret` and `privy` wallets have no such limit.
 
 ---
 
 ## Security
 
-### The password is also stored in an environment variable — how is that different from a plaintext private key?
-
-The difference is enormous! It's the difference between leaving cash on the table and locking it in a double-layered safe.
-
-When you use a Web3 wallet like MetaMask, you never copy-paste your raw private key every time — you unlock it with a short password. Agent-wallet is essentially a command-line MetaMask built for AI agents.
-
-* Traditional approach (plaintext private key): It's like leaving cash right on the table. Any malicious browser extension, one careless code commit, or a background log scan — one glance at your environment variables and the money is gone instantly. A classic single point of failure.
-* Agent-wallet approach: It splits the risk into two locks.
-   1. Physical safe: Your private key is encrypted with industry-grade algorithms and locked in a hidden folder deep in your system (`~/.agent-wallet`).
-   2. Unlock password: What you put in your environment variable is merely the password to open this safe.
-
-This means if a leak occurs:
-
-* If a hacker only steals your password (e.g., by scanning environment variables), they don't have your encrypted wallet file — the password is just a useless string.
-* If a hacker only steals your encrypted wallet file, they don't have your master password — the file is uncrackable gibberish that would take millennia to brute-force.
-
-A hacker would need to simultaneously break into your computer, locate and steal the hidden wallet file, AND steal the password from your environment variables to touch your funds. The difficulty of this attack is orders of magnitude higher than simply scanning environment variables!
-
 ### Does the private key ever leave my machine?
 
-For `local_secure` and `raw_secret` wallets — never: zero network requests, zero RPC calls, zero cloud services; the key never leaves your machine. `privy` wallets are the exception: the key is custodied by Privy (it never sits on your disk), and signing requests go to Privy's API.
+For `raw_secret` and `wallet_cli` wallets, signing happens locally — Agent-wallet makes no network request to sign. `privy` wallets are the exception: the key is custodied by Privy (it never sits on your disk), and signing requests go to Privy's API.
 
-### How should I store the master password securely?
+### How does a `wallet_cli` wallet handle the password?
 
-- ✅ Use a password manager (1Password, Bitwarden)
-- ✅ Pass it via the `AGENT_WALLET_PASSWORD` environment variable
-- ❌ Don't hardcode it in source code
-- ❌ Don't commit environment variable files containing the password to git
+Agent-wallet never reads or decrypts the wallet-cli keystore. For each signature it pins the configured account and network, obtains the password (running the exec script again each time, 10-second default timeout), writes it only to that one wallet-cli subprocess's stdin, and checks that the returned signer matches the account. The password is never passed on the command line.
 
-### Is the encryption algorithm secure? Can it be brute-forced?
+### How should I store secrets securely?
 
-Agent-wallet uses the Keystore V3 standard encryption (scrypt + AES-128-CTR), the exact same encryption scheme used by official Ethereum wallets. The scrypt algorithm is specifically designed to make brute-force attacks extremely expensive in both computation and memory — even with dedicated hardware, cracking a strong password would take tens of thousands of years.
+- ✅ Use a password manager (1Password, Bitwarden) and reference it with an exec script
+- ❌ Don't hardcode secrets in source code or pass them as command-line arguments
+- ❌ Don't commit `~/.agent-wallet/wallets_config.json` or `.env` files to git
 
 ---
 
@@ -143,7 +143,7 @@ Agent-wallet uses the Keystore V3 standard encryption (scrypt + AES-128-CTR), th
 
 ### What operating systems are supported?
 
-macOS, Linux, and Windows. As long as you can run Node.js >= 18 or Python >= 3.11, you're good to go. Windows support was added in v2.3.x — file permission features (like `chmod 600`) are gracefully skipped on Windows since it doesn't support Unix-style permissions.
+macOS, Linux, and Windows, with Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (the same range applies when you use wallet-cli). File permission hardening (`chmod 600` on `wallets_config.json`, `700` on the directory) is skipped on platforms that don't support Unix-style permissions. On Windows, point `AGENT_WALLET_WALLET_CLI_PATH` at wallet-cli's JavaScript entrypoint rather than a `.cmd` / `.bat` shim.
 
 ### `npm install -g` gives a permission error?
 
@@ -159,13 +159,17 @@ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
 source ~/.zshrc
 ```
 
-### I configured the password but AI says "wallet not found" or "wrong password"?
+### My agent says "wallet not found" or "network is required"?
 
-The three most common causes:
+The most common causes:
 
-1. **Password didn't take effect**: You ran `export` in Terminal A, but the AI runs in Terminal B. Solution: restart the AI backend service (see [Quick Start](./QuickStart.md) Step 2).
-2. **Shell ate the password**: A password wrapped in double quotes contains `$` or `!`, which the shell expanded. Solution: switch to single quotes.
-3. **Wrong storage directory**: You previously used `--dir` to specify a custom path, but the AI is looking at the default path. Solution: `export AGENT_WALLET_DIR="/your/custom/path"`.
+1. **Wrong storage directory**: you used `--dir` when creating the wallet, but the agent looks at the default path. Set `AGENT_WALLET_DIR="/your/custom/path"` in the agent's environment and restart it.
+2. **No active wallet (CLI)**: `agent-wallet sign` without `-w` fails when no wallet is active. Run `agent-wallet list`; if nothing is marked `*`, run `agent-wallet use <id>`. (The SDK's `resolveWallet()` / `getActiveWallet()` don't fail here — they fall back to the first configured wallet.)
+3. **Missing or non-canonical network**: `raw_secret` and `wallet_cli` wallets need a network such as `tron:3448148188` or `eip155:56`.
+
+### `wallet-cli not found` when adding a `wallet_cli` wallet?
+
+Install a compatible version (`npm install -g '@tron-walletcli/wallet-cli@^4.13.0'`) and make sure `wallet-cli --version` works in the same shell, or set `AGENT_WALLET_WALLET_CLI_PATH`. wallet-cli 4.12.x and 5.x are not supported by Agent-wallet 3.x.
 
 ### `agent-wallet` command not found?
 
@@ -183,36 +187,24 @@ source ~/.zshrc
 
 ---
 
-## Cross-language
-
-### Are key files compatible between Python and TypeScript?
-
-Yes. Both implementations use exactly the same encryption format. A wallet created with the CLI works directly with the Python SDK, and vice versa.
-
-### Do both languages produce the same signature?
-
-Identical. Same private key + same data = same signature.
-
----
-
 ## OpenClaw Integration
 
 ### Is OpenClaw required?
 
-No. Agent-wallet is a standalone signing tool that can be used independently via CLI or SDK. OpenClaw is simply the most convenient frontend — it lets you invoke signing using natural language, without writing any code.
+No. Agent-wallet is a standalone signing tool that can be used independently via CLI or SDK.
 
 ### OpenClaw says "signing failed" or "wallet not connected"?
 
 Troubleshoot in this order:
 
-1. Confirm the `AGENT_WALLET_PASSWORD` environment variable is set (run `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set" || echo "Password NOT set"` in the terminal where OpenClaw is running)
-2. Confirm the MCP Server was started **after** the environment variable was set
-3. Confirm a wallet has been initialized: `agent-wallet list` should show at least one wallet
-4. If everything above checks out, try signing manually via CLI: `agent-wallet sign msg "test" -n tron`
+1. Confirm the tool you use actually signs through Agent-wallet 3.x — new BANK OF AI setups use [wallet-cli](../wallet-cli/quickstart.md) directly.
+2. Confirm a wallet has been configured: `agent-wallet list` should show at least one wallet, with `*` on the active one.
+3. Confirm the agent's environment uses the same wallet directory (`AGENT_WALLET_DIR`), and restart the agent after changing it.
+4. Try signing manually: `agent-wallet sign typed-data '<json>' -n eip155:56`.
 
-### Does signing in OpenClaw cost gas fees?
+### Does signing cost gas fees?
 
-Signing itself costs zero gas. Signing is purely a local cryptographic operation using your private key — it's completed entirely on your machine. Gas fees are only incurred when a signed transaction is broadcast to the blockchain. Operations like checking addresses or signing messages are always free.
+Signing itself costs zero gas. Gas fees are only incurred when a signed transaction is broadcast to the blockchain.
 
 ---
 
diff --git a/docs/Agent-Wallet/Intro.md b/docs/Agent-Wallet/Intro.md
index 3264bb6d..d39dee1b 100644
--- a/docs/Agent-Wallet/Intro.md
+++ b/docs/Agent-Wallet/Intro.md
@@ -1,7 +1,7 @@
 # Introduction
 
 :::note
-Agent Wallet documentation remains for existing SDK, server, and community integrations. The official setup entry for new users is [wallet-cli](/wallet-cli/quickstart/); the stores are not automatically interchangeable.
+Agent Wallet documentation covers the `@bankofai/agent-wallet` 3.x SDK and CLI used by existing SDK, server, and community integrations. The official setup entry for new users is [wallet-cli](../wallet-cli/quickstart.md). Since 3.0, Agent-wallet can **link** an existing wallet-cli account through the `wallet_cli` wallet type, but it never imports, copies, or decrypts wallet-cli keys.
 :::
 
 ## Enjoy the Convenience of AI Agents Without the Private Key Risk
@@ -30,63 +30,62 @@ The common thread: **your private key is always exposed somewhere** — on disk,
 
 ---
 
-## The Breakthrough: Agent-wallet — The Web3 Wallet Designed Exclusively for AI
+## The Approach: One Signing Interface, Keys Kept Elsewhere
 
-When you use a Web3 wallet like TronLink/MetaMask, do you paste your raw private key in every time? Of course not. You unlock it with a password, and let it sign on your behalf.
+When you use a Web3 wallet like TronLink/MetaMask, do you paste your raw private key into every app? Of course not. The wallet holds the key and signs on your behalf.
 
-**Agent-wallet is a local TronLink/MetaMask purpose-built for AI agents.**
+**Agent-wallet gives your AI agent the same thing: a single signing interface (`getAddress`, `signTransaction`, `signTypedData`) in front of a key backend you choose.** Your agent code — or the MCP server / skill it uses — asks Agent-wallet to sign; it never needs to handle the key itself.
 
-It minimizes your risk through a **"physical + password separation"** dual-lock mechanism:
+Agent-wallet 3.x supports three wallet types:
 
-1. **Lock #1 (Physical file):** Your private key is encrypted with industry-grade algorithms and stored in a hidden folder deep in your system (`~/.agent-wallet`).
-2. **Lock #2 (Authorization password):** Your AI agent only needs the "unlock password" (which you can set in an environment variable) to operate.
-
-**🤔 You might ask: "What if the AI leaks my unlock password?"**
-
-This is the most elegant part of Agent-wallet: **a leaked password ≠ stolen assets.**
-
-If a hacker steals only your password through a malicious plugin, they can't do anything — because they don't have your encrypted wallet file. If they steal only the wallet file without the password, it's just uncrackable gibberish.
+| Wallet type | Where the key lives | Recommended for |
+| :--- | :--- | :--- |
+| `wallet_cli` | In the encrypted keystore of [wallet-cli](../wallet-cli/quickstart.md). Agent-wallet never reads or decrypts that keystore; each signature runs in a restricted wallet-cli subprocess, and the keystore password is handed to that subprocess only for that one signature. | Local production signing |
+| `privy` | Custodied by [Privy](https://privy.io) — no private key on your disk. Signing requests go to Privy's API. | Server-side agents that already use Privy |
+| `raw_secret` | Stored **in plaintext** in `~/.agent-wallet/wallets_config.json`. | Development and throwaway test keys only |
 
-**A hacker would need to simultaneously break into your system, locate the hidden wallet file, AND steal the password from your environment variables to touch your funds.** The difficulty and cost of this kind of attack is orders of magnitude higher than simply scanning a plaintext private key in environment variables!
+For CI and other disposable environments, the SDK can also read a key straight from environment variables (`AGENT_WALLET_PRIVATE_KEY` or `AGENT_WALLET_MNEMONIC`). That is plaintext too — see the [SDK Guide](./Developer/SDK-Guide.md).
 
-**Bottom line: steal the file — it's useless without the password. Leak the password — it's useless without the file.**
+:::caution Upgrading from 2.x
+3.0 removed the `local_secure` encrypted wallet type, the agent-wallet master password, `AGENT_WALLET_PASSWORD`, and `runtime_secrets.json`. Existing 2.x `local_secure` wallets are **not** converted automatically. Back up `~/.agent-wallet`, confirm you can still access the original key material with 2.x, then re-create the wallet as `wallet_cli` (recommended), `privy`, or `raw_secret`. See the [FAQ](./FAQ.md#upgrade-from-2x).
+:::
 
 ---
 
 ## How It Compares
 
-| | :x: Traditional (plaintext key in configuration files) | :white_check_mark: Agent-wallet |
+| | :x: Traditional (plaintext key in configuration files) | :white_check_mark: Agent-wallet with `wallet_cli` |
 | :--- | :--- | :--- |
-| **How it works** | :x: Hand your card and PIN directly to the AI | :white_check_mark: **Give AI the password, file stays locked locally** |
-| **Log / env variable leak** | :rotating_light: **Total loss** | :shield: **Only the password leaks — no file, hacker gets nothing** |
-| **Encrypted file stolen** | :x: Plaintext key, stolen instantly | :shield: **No password, hacker can't open the file** |
-| **Works offline?** | :warning: Depends | :white_check_mark: **100% offline signing** (`local_secure` / `raw_secret`; the `privy` type signs via Privy's API and needs network) |
+| **What the agent's config holds** | :x: The private key itself | :white_check_mark: A wallet-cli account ID and a password source (ideally an `exec` script) |
+| **Key file read by another program** | :rotating_light: **Total loss** | :shield: The keystore is encrypted by wallet-cli |
+| **One signing API for TRON and EVM** | :warning: Depends on your code | :white_check_mark: Same `Wallet` interface for every backend |
+| **Works offline?** | :warning: Depends | :white_check_mark: `wallet_cli` and `raw_secret` sign on your machine; `privy` signs via Privy's API and needs network |
 
 ---
 
-## Three Commands, Under a Minute
+## Three Steps to a First Signature
 
-No need to understand everything first — get it running, then explore:
+No need to understand everything first — get it running, then explore. This path uses the quickest wallet type, `raw_secret`, with a **throwaway test key** (never real funds):
 
 **Step 1 — Install Agent-wallet:**
 ```bash
 npm install -g @bankofai/agent-wallet
 ```
 
-**Step 2 — Create your Agent-wallet wallet:**
+**Step 2 — Import a test key:**
 ```bash
-agent-wallet start
+agent-wallet start raw_secret
 ```
-The wizard asks you to set a **master password** — press Enter and it auto-generates a strong one, displayed exactly once. This password is your only "unlock key": every time your AI agent needs to sign, it uses this password to unlock the wallet. **Save it immediately in a password manager (e.g. 1Password, Bitwarden)** — if lost, there's no way to recover it or access your assets.
+Choose `private_key` and paste a test key when prompted. The CLI warns that raw secret material is stored in plaintext in `wallets_config.json`.
 
 **Step 3 — Your first signature:**
 ```bash
-agent-wallet sign msg "Hello from my AI agent" -n tron
+agent-wallet sign typed-data '{"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}],"Message":[{"name":"contents","type":"string"}]},"primaryType":"Message","domain":{"name":"AgentWallet","chainId":1},"message":{"contents":"Hello from my AI agent"}}' -n eip155:1
 ```
 
-The CLI asks for your master password first — plain `agent-wallet start` does not persist it, so signing has to unlock the keystore. (Add `--save-runtime-secrets` at step 2, as the BANK OF AI onboarding skill does, to skip that prompt.) When a hash string appears on screen — congratulations, your Agent-wallet is live.
+When a line starting with `Signature:` appears — congratulations, your Agent-wallet is live.
 
-> Want the full step-by-step walkthrough? Head to **[Quick Start](./QuickStart.md)**.
+> For real funds, link a wallet-cli account instead. The full walkthrough is in **[Quick Start](./QuickStart.md)**.
 
 ---
 
@@ -98,60 +97,46 @@ Pick the path that fits you:
 
 ### 🎮 I'm a casual user — using existing tools
 
-You don't need to know any code! You can directly use our ready-made "all-in-one" suite: **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**.
+You don't need to know any code! You can use the ready-made suite: **[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**. Check each tool's own setup page for the wallet it expects — new setups use [wallet-cli](../wallet-cli/quickstart.md) directly.
 
 #### 🤝 How do they work together?
 
 To give you total peace of mind, we designed your AI assistant as a well-organized little "company" with clear division of labor:
 
 - 🧠 **The Business Team (OpenClaw + Skills + MCP):** They do the legwork out in the field — quick-thinking and well-equipped, they know how to check prices, calculate slippage, and find the best quotes. But most importantly: they have zero authority to touch your funds.
-- 🏦 **The CFO (Agent Wallet):** The one guarding the vault. Your private key (think: bank card PIN) is locked tight inside their local safe, completely invisible to the Business Team outside.
+- 🏦 **The CFO (Agent Wallet):** The one in front of the vault. With the `wallet_cli` type, the vault itself is wallet-cli's encrypted keystore; with `privy`, it's Privy's infrastructure.
 
-Here's how a perfect secure pipeline works:
+Here's how a secure pipeline works:
 
 1. You sit back in the boss's chair and say: "Buy 100 USDT worth of TRX."
 2. The Business Team rushes off to check prices, calculate fees, and dutifully drafts a "transaction request form."
-3. They hand the form to the **CFO (Agent Wallet)**, who sits right next to the safe.
-4. The CFO verifies everything and never takes the private key out of the safe — instead, they stamp the form right there with an "approved" seal (technically called "signing"), then pass only the stamped form back out.
+3. They hand the form to the **CFO (Agent Wallet)**.
+4. The CFO has the vault stamp the form with an "approved" seal (technically called "signing") without ever taking the private key out, then passes only the stamped form back.
 5. The Business Team takes the stamped form and gets it done on the blockchain.
 
-✨ **The key takeaway:** Throughout the entire process, the AI tools doing the legwork only ever receive the "stamped paper" — they never even catch a glimpse of the private key! This ensures AI agent can handle extremely complex tasks for you while keeping your assets absolutely secure.
-
-#### ⚙️ Sounds great — how do I connect them?
-
-Dead simple! No complex programming needed — just one thing: give the Business Team an internal passphrase to wake up the CFO.
-
-Just tell the tools the "master password" you generated when creating your Agent Wallet, like this:
-
-```bash
-export AGENT_WALLET_PASSWORD='your-master-password'
-```
-
-That's it — one line of config! Once the passphrase is set, the entire system works seamlessly and automatically. Your AI agent will transform into a top-tier Web3 personal assistant that's both brilliantly capable and absolutely secure!
+✨ **The key takeaway:** the AI tools doing the legwork only ever receive the "stamped paper" — the signed transaction or signature.
 
 > Can't wait to try it? Head to 👉 **[Quick Start](./QuickStart.md)** and follow along.
 
 ### ⌨️ I'm an advanced user — managing wallets via CLI
 
-Need password-free signing, managing multiple wallets, or custom storage directories? Head to **[CLI Reference](./Developer/CLI-Reference.md)**.
+Managing multiple wallets, exec-script credentials, or custom storage directories? Head to **[CLI Reference](./Developer/CLI-Reference.md)**.
 
 ### 👨‍💻 I'm a developer — building my own agent
 
 <details>
-<summary>Expand developer path — TypeScript / Python SDK</summary>
+<summary>Expand developer path — TypeScript SDK</summary>
 
-Agent-wallet ships a complete SDK with TypeScript and Python support — both sharing the same interface:
+Agent-wallet 3.x ships a TypeScript SDK; the same configuration the CLI writes is what the SDK reads:
 
 ```typescript
-import { resolveWalletProvider } from "@bankofai/agent-wallet";
+import { resolveWallet } from "@bankofai/agent-wallet";
 
-const provider = resolveWalletProvider({ network: "tron:nile" });
-const wallet   = await provider.getActiveWallet();
-const sig      = await wallet.signMessage(new TextEncoder().encode("Hello!"));
+const wallet = await resolveWallet({ network: "tron:3448148188" }); // TRON Nile
+const address = await wallet.getAddress();
+const signed = await wallet.signTransaction(unsignedTx); // { family: "tron", transaction }
 ```
 
-Same key file, same data, same signature — across both languages.
-
 > **[SDK Guide](./Developer/SDK-Guide.md)** — step-by-step integration guide.
 > **[SDK Cookbook](./Developer/SDK-Cookbook.md)** — end-to-end real transactions: TRON transfers, BSC transfers, x402 payment signing.
 
@@ -161,10 +146,14 @@ Same key file, same data, same signature — across both languages.
 
 ## Supported Chains
 
+Every network is given as a canonical CAIP-2 identifier:
+
 | Chain Type | Networks |
 | :--- | :--- |
-| **EVM** | Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM-compatible chain (mainnet & testnet supported) |
-| **TRON** | TRON Mainnet, Nile Testnet, Shasta Testnet |
+| **EVM** | `eip155:<chainId>` — Ethereum (`eip155:1`), BSC (`eip155:56`), Base (`eip155:8453`), and any other EVM-compatible chain, mainnet or testnet |
+| **TRON** | `tron:<chainId>` — Mainnet (`tron:728126428`), Nile Testnet (`tron:3448148188`), Shasta Testnet (`tron:2494104990`) |
+
+For `wallet_cli` wallets the network must also be one wallet-cli itself knows — its built-ins (`eip155:1`, `eip155:11155111`, `eip155:56`, `eip155:97`, `eip155:8453`, `eip155:84532` (the two Base networks were added in wallet-cli 4.14.0) and the three TRON networks) or a network added to wallet-cli's own config — otherwise signing fails with `network_mismatch`. `raw_secret` and `privy` wallets have no such limit.
 
 Both chain types share the same interface — learn it once, use it everywhere.
 
@@ -174,7 +163,7 @@ Both chain types share the same interface — learn it once, use it everywhere.
 
 | I'm wondering… | Go here |
 | :--- | :--- |
-| Will AI drain my wallet? | [FAQ](./FAQ.md) — we have a dedicated risk isolation solution |
+| Will AI drain my wallet? | [FAQ](./FAQ.md) — keep a dedicated, small agent wallet |
 | Never written code? | [Quick Start](./QuickStart.md) |
 | Prefer the command line? | [CLI Reference](./Developer/CLI-Reference.md) |
 | Building your own agent? | [SDK Guide](./Developer/SDK-Guide.md) |
diff --git a/docs/Agent-Wallet/QuickStart.md b/docs/Agent-Wallet/QuickStart.md
index 1ac93a6c..da19e12b 100644
--- a/docs/Agent-Wallet/QuickStart.md
+++ b/docs/Agent-Wallet/QuickStart.md
@@ -4,67 +4,32 @@ import TabItem from '@theme/TabItem';
 # Quick Start
 
 :::note
-Agent Wallet documentation remains for existing SDK, server, and community integrations. The official setup entry for new users is [wallet-cli](/wallet-cli/quickstart/); the stores are not automatically interchangeable.
+Agent Wallet documentation covers the `@bankofai/agent-wallet` 3.x SDK and CLI used by existing SDK, server, and community integrations. The official setup entry for new users is [wallet-cli](../wallet-cli/quickstart.md). Agent-wallet can link a wallet-cli account (Path A below), but never imports or decrypts wallet-cli keys.
 :::
 
-From zero to invoking your Agent-wallet in your AI agent chat. There are two ways to create your wallet: **command-line setup** works for every installation; **conversational setup** only works where the legacy agent-wallet and bankofai-guide Skills are still installed.
+From zero to a working Agent-wallet that your AI agent or your own code can sign with. Pick one path:
 
-:::tip Prerequisites & CLI command details
-- Your AI Agent supports shell command execution (OpenClaw, a Telegram bot, web chat, Claude Code, Cursor, etc.)
-- This page only walks you through the shortest path. For password-free configuration, managing multiple wallets, signature types, and other advanced topics, see the [CLI Reference](./Developer/CLI-Reference.md).
-:::
-
----
-
-## Method 1: Conversational Setup (Legacy Skills)
-
-:::note Historical setup
-The following conversational flow applies only to existing installations of the legacy agent-wallet and bankofai-guide Skills. Both were removed in Skills 3.0.0.
-:::
-
-If you've already installed [the BANK OF AI skill suite](../McpServer-Skills/SKILLS/QuickStart.md) from an older release that included `agent-wallet` and `bankofai-guide`, creating a wallet takes just one prompt in your AI chat — the AI generates the password, creates the wallet, and saves the config for you, with no manual file editing.
+- **Path A — Link a wallet-cli account (recommended for real funds).** Keys stay in wallet-cli's encrypted keystore.
+- **Path B — Import a raw secret (development only).** The private key or mnemonic is stored **in plaintext** in `~/.agent-wallet/wallets_config.json`.
 
-**How it works:**
+Privy users: see [CLI Reference → Privy](./Developer/CLI-Reference.md#privy-wallets).
 
-1. Open your AI Agent chat
-2. Copy and paste the following prompt:
-
-   ```
-   Create an AgentWallet
-   ```
-
-3. The AI handles the entire flow automatically:
-   - **Checks current wallet status** — tells you whether one is already configured
-   - **Asks how to create it** — offers two options:
-     - **A. Quick setup (highly recommended)**: fully automated, ~10 seconds; auto-generates a secure password; encrypted wallet stored locally
-     - **B. Detailed setup**: manually pick wallet type; custom password; more configuration options
-4. Reply `A` and the AI runs the three setup steps automatically:
-   - **Step 1**: Generate a secure password
-   - **Step 2**: Create the wallet
-   - **Step 3**: Retrieve the wallet addresses
-
-
-:::caution Your master password is critical — back it up immediately
-The master password is only shown once. The guided setup runs `agent-wallet start` with `--save-runtime-secrets`, which saves it to `~/.agent-wallet/runtime_secrets.json` — but you should also save it manually to a password manager (1Password, Bitwarden, etc.). If the local file is lost or corrupted and you have no external backup, your wallet will be permanently locked — there is no recovery mechanism, no support team, and no backdoor.
-
-⚠️ Never share this password via chat, email, screenshots, or public repositories.
+:::tip Prerequisites & CLI command details
+- Your AI Agent supports shell command execution (OpenClaw, a Telegram bot, web chat, Claude Code, Cursor, etc.), or you are integrating the SDK into your own code.
+- This page only walks you through the shortest path. For every command and flag, see the [CLI Reference](./Developer/CLI-Reference.md).
 :::
 
-:::tip Done — no env-var configuration needed
-Conversational setup passes `--save-runtime-secrets`, so the password is saved to `~/.agent-wallet/runtime_secrets.json` and your AI Agent reads it automatically when calling wallet functions. **You don't need to manually export `AGENT_WALLET_PASSWORD`.** If you'd rather use the env-var approach, see Method 2 below.
+:::caution Upgrading from 2.x?
+3.0 removed `local_secure`, the master password, `AGENT_WALLET_PASSWORD`, and `runtime_secrets.json`, and the bundled `agent-wallet` / `bankofai-guide` conversational Skills were removed in Skills 3.0.0. Existing `local_secure` wallets are not converted. See the [FAQ](./FAQ.md#upgrade-from-2x) before upgrading.
 :::
 
 ---
 
-## Method 2: Command-Line Setup (Most Control)
-
-If you want to control every step yourself, or your environment doesn't support conversational install, follow the command-line flow below.
+## Step 1: Install
 
-### Step 1: Install and Initialize Your Wallet
+### 1.1 Prepare Your Environment: Install Node.js
 
-#### 1.1 Prepare Your Environment: Install Node.js
-
-Agent-wallet requires Node.js (a runtime environment, version >= 18; installing the current LTS is recommended) on your computer.
+Agent-wallet and wallet-cli (Path A) both require **Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+** — the October 2026 security releases (the published agent-wallet `3.0.0` still declares `>=18`; wallet-cli `4.15.1` and the next agent-wallet release declare this range). An up-to-date LTS install satisfies this.
 
 Open a terminal (Mac users press `Command + Space` and search for "Terminal"), then type:
 
@@ -72,8 +37,8 @@ Open a terminal (Mac users press `Command + Space` and search for "Terminal"), t
 node -v
 ```
 
-- **If the output shows `v18.x.x` or higher:** Great, skip straight to 1.2!
-- **If there's no output or an error:** Don't panic — go to the **[Node.js official website](https://nodejs.org)** and download the latest **LTS** installer. Install it like any regular software — double-click and follow the prompts. After installation, close and reopen your terminal, then run `node -v` again to confirm.
+- **If the output is `v22.23.4`+ (22.x), `v24.22.1`+ (24.x), or `v26.12.1`+:** Great, skip straight to 1.2!
+- **If there's no output, an error, or an older version:** go to the **[Node.js official website](https://nodejs.org)** and download the latest **LTS** installer. After installation, close and reopen your terminal, then run `node -v` again to confirm.
 
 <details>
 <summary>Developer preferred: Install via nvm (beginners can skip this)</summary>
@@ -91,7 +56,7 @@ nvm install --lts && nvm use --lts
 
 </details>
 
-#### 1.2 Install Agent-wallet
+### 1.2 Install Agent-wallet
 
 ```bash
 npm install -g @bankofai/agent-wallet
@@ -102,130 +67,130 @@ Verify the installation:
 agent-wallet --help
 ```
 
-If you see the help output, you're good to go.
-
-#### 1.3 Create Your Agent-wallet Wallet
+If you see `Usage: agent-wallet <command> [options]` followed by the command list, you're good to go.
 
-Run:
-```bash
-agent-wallet start
-```
-
-The system will guide you through initializing your **Agent-wallet wallet**. The process is interactive — just follow the prompts:
-
-```
-? Quick start type: local_secure  — Encrypted key stored locally (recommended)
-Password requirements: at least 8 characters, with uppercase, lowercase, digit, and special character. e.g. Abc12345!@
-New Master Password (press Enter to auto-generate a strong password):
+---
 
-Wallet initialized!
-Wallet ID (e.g. my_wallet_1) (default_secure):
-? Import source: generate  — Generate a new random private key
+## Step 2: Create Your Wallet
 
-Wallets:
-┌────────────────┬──────────────┐
-│ Wallet ID      │ Type         │
-├────────────────┼──────────────┤
-│ default_secure │ local_secure │
-└────────────────┴──────────────┘
+<Tabs>
+<TabItem value="wallet-cli" label="Path A: wallet-cli (recommended)" default>
 
-🔑 Your master password: <your-unique-password-will-appear-here>
-⚠️ Keep this password safe. You'll need it for signing and other operations.
-   (This line appears only when you pressed Enter to let the wizard auto-generate the password.)
+**2.1 Install a compatible wallet-cli** (Agent-wallet 3.x supports `>=4.13.0 <5.0.0`):
 
-Active wallet: default_secure
+```bash
+npm install -g '@tron-walletcli/wallet-cli@^4.13.0'
+wallet-cli --version
 ```
 
-:::caution Master password = the only key to all your assets
-This password is the sole credential for decrypting all your private keys. **Lose it and it's gone forever — no backup, no backdoor, no recovery.**
+**2.2 Create (or import) a wallet-cli account.** On first use wallet-cli sets up `~/.wallet-cli` and asks you to set its master password in the terminal:
 
-Do this right now:
-1. Open your password manager (1Password, Bitwarden, etc.)
-2. Create a new entry and paste in the master password
-3. Don't screenshot it, don't put it in a desktop sticky note, don't text it to yourself
-:::
-
----
+```bash
+wallet-cli create --label main-1 -o json
+```
 
-### Step 2: Feed the Password to Your AI (Critical!)
+To restore an existing wallet instead, run `wallet-cli import mnemonic --label main-1 -o json` or `wallet-cli import private-key --label main-1 -o json`. Mnemonics, private keys and the password are entered at hidden prompts — never put them in command arguments, environment variables, logs, or chats. See the [wallet-cli Quick Start](../wallet-cli/quickstart.md) for backup.
 
-For your AI agent to automatically use your wallet, you must configure the password in its runtime environment. Select the tab matching your operating system and **just copy-paste**:
+**2.3 Create a password script** so the wallet-cli password is never stored in Agent-wallet's config. The script just prints the password to stdout — for example with the 1Password CLI:
 
-#### 2.1 Save and Activate the Password
+```bash
+#!/bin/sh
+op read 'op://Private/wallet-cli-password/password'
+```
 
-<Tabs>
-<TabItem value="mac" label="Mac Users (Zsh)" default>
+Save it (for example as `~/bin/fetch-wallet-cli-password.sh`) and make it executable with `chmod +x`.
 
-**Step 1:** Open `~/.zshrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password):
+**2.4 Link the account to Agent-wallet:**
 
 ```bash
-open -e ~/.zshrc
+agent-wallet start wallet_cli \
+  --wallet-id my_cli_wallet \
+  --account main-1 \
+  --cli-password-exec /absolute/path/to/fetch-wallet-cli-password.sh
 ```
 
-Add this line at the very end, then save and close:
+Agent-wallet first checks that wallet-cli is compatible and that the account exists (without asking for the password), then saves the canonical account ID. Expected output ends with:
 
-```bash
-export AGENT_WALLET_PASSWORD='your-master-password'
 ```
+Wallet 'my_cli_wallet' created:
+...
+Active wallet: my_cli_wallet
 
-**Step 2:** Back in the terminal, copy this command, paste and press Enter to apply the config immediately:
-
-```bash
-source ~/.zshrc
+Quick guide:
+...
 ```
 
-:::tip Why not use the echo command?
-While `echo "export ..." >> ~/.zshrc` is quicker, your actual password gets recorded verbatim in the shell's history file (`.zsh_history` / `.bash_history`). These history files are commonly scanned by security tools, backup utilities, and AI coding assistants — exactly the kind of exposure Agent-wallet is designed to prevent. Editing the config file directly in an editor keeps the password out of any command history.
+:::tip Typing the password instead of using a script
+Run `agent-wallet start wallet_cli` without `--cli-password-exec` and pick `direct` at the password-source prompt. The password is then stored as a plaintext string in `wallets_config.json` (file mode `0600`). `inspect` always shows it as `[redacted]`, but any program that can read the file can read the password. Passing `--cli-password <password>` on the command line is rejected.
 :::
 
 </TabItem>
-<TabItem value="linux" label="Linux Users">
+<TabItem value="raw-secret" label="Path B: raw_secret (dev only)">
 
-**Step 1:** Open `~/.bashrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password):
-
-```bash
-nano ~/.bashrc
-```
+:::danger Plaintext storage
+`raw_secret` writes your private key or mnemonic **unencrypted** to `~/.agent-wallet/wallets_config.json`. Any program that can read files in your home directory can read it. Use only throwaway test keys.
+:::
 
-Add this line at the very end, then save and close (in nano, press `Ctrl + O` to save, `Ctrl + X` to exit):
+Agent-wallet 3.x does not generate keys — import an existing test key:
 
 ```bash
-export AGENT_WALLET_PASSWORD='your-master-password'
+agent-wallet start raw_secret --wallet-id dev_wallet
 ```
 
-**Step 2:** Back in the terminal, copy this command, paste and press Enter to apply the config immediately:
+At the prompts, choose `private_key` (or `mnemonic`) and paste the value. Expected output:
 
-```bash
-source ~/.bashrc
 ```
-
+Warning: Raw secret material will be stored in plaintext in wallets_config.json.
+...
+Wallet 'dev_wallet' created:
+...
+Active wallet: dev_wallet
+
+Quick guide:
+...
+```
 
 </TabItem>
 </Tabs>
 
+---
 
+## Step 3: Check the Wallet
 
+**Show the addresses** (no signing, no password needed):
 
+```bash
+agent-wallet resolve-address
+```
 
-:::caution Password has special characters? Don't touch the single quotes!
-Auto-generated passwords often contain `$`, `!`, and other special characters. The commands above already use single quotes to wrap the password — **just replace the text inside the quotes, never switch to double quotes**, or the shell will silently mangle the value:
+Pick your wallet from the list. A `raw_secret` wallet, or a wallet-cli account that has both chain families, prints an EVM and a TRON address:
 
-```bash
-# ✅ Correct — single quotes, password saved as-is
-export AGENT_WALLET_PASSWORD='P@ss$w0rd!'
+```
+Wallet  my_cli_wallet
+Type    wallet_cli
 
-# ❌ Wrong — double quotes, $w0rd gets shell-expanded to empty string, password silently breaks
-export AGENT_WALLET_PASSWORD="P@ss$w0rd!"  # actual value becomes "P@ss!"
+Addresses
+EVM   0x...
+TRON  T...
 ```
-:::
 
-#### 2.2 Restart Your AI Backend Service
+**Make a test signature** on a testnet. Every signing command needs a canonical network with `-n`:
 
-:::danger Many people forget this step, then wonder why AI can't find the password!
-You just saved a new password, but the AI assistant running in the background hasn't refreshed yet — it's still blind to the change! You need to shut it down and restart it for the new password to take effect.
-:::
+```bash
+agent-wallet sign typed-data '{"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}],"Message":[{"name":"contents","type":"string"}]},"primaryType":"Message","domain":{"name":"AgentWallet","chainId":97},"message":{"contents":"hello"}}' -n eip155:97
+```
+
+Success prints `Signature: <hex>`.
+
+---
+
+## Step 4: Point Your Agent at the Wallet
+
+There is **no password environment variable** to set in 3.x. Any tool or code that uses the Agent-wallet SDK resolves the active wallet from `~/.agent-wallet/wallets_config.json` automatically.
 
-Whether or not you currently have your AI agent backend service running, make sure to **shut it down**, then **restart it** from the same terminal window where you ran the commands above.
+- If you stored the wallet somewhere else with `--dir`, set `AGENT_WALLET_DIR` to that directory in the environment your agent runs in.
+- If you used `--cli-password-exec`, make sure the script works in that environment too (for example, the 1Password CLI must be signed in for the user the agent runs as).
+- After changing environment variables, restart your AI agent backend so it picks them up.
 
 ---
 
diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md
index 8f22aa1a..6de6d30e 100644
--- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md
+++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md
@@ -17,11 +17,11 @@ BANK OF AI SKILLS can operate on **real on-chain assets**. Blockchain transactio
 | Skill | What It Does | What Key/Credential Do I Need? |
 | :--- | :--- | :--- |
 | **wallet-cli** | Standalone TRON wallet operations via the pinned `@tron-walletcli/wallet-cli@4.14.0` — transfers, staking, voting, contracts, signing, chain queries (machine-readable JSON) | A local wallet managed by wallet-cli; agent runs pass passwords via stdin only |
-| **sunswap**<br/>installs as `sunswap-dex-trading` | Check prices, get quotes, swap tokens, manage V2/V3/V4 liquidity pools | Read-only: none. Trading: wallet credentials |
-| **sunpump-agent-skill**<br/>installs as `sunpump-meme-token-toolkit` | SunPump meme coins: create tokens with one command (server-side, no wallet), market data/rankings/holders/portfolios, plus buy/sell meme coins (automatically picks the swap route based on whether the token has launched, TRON mainnet only) | Read-only & token creation: none. On-chain buy/sell: wallet credentials |
-| **sunperp-skill**<br/>installs as `sunperp-perpetual-futures-trading` | Market data, open/close positions, withdrawals | Market data: none. Trading: SunPerp API keys. Withdrawals additionally need `TRON_PRIVATE_KEY` to sign the confirmation |
-| **tronscan-skill**<br/>installs as `tronscan-data-lookup` | Look up accounts, transactions, tokens, blocks, network stats | Optional: TronScan API key — without one, requests go through the keyless BofAI proxy and may be rate-limited |
-| **usdd-skill**<br/>installs as `usdd-just-protocol` | USDD stablecoin — PSM swaps (1:1 USDT ↔ USDD), vault queries, balance checks | Read-only: none. PSM swaps: wallet credentials |
+| **sunswap**<br/>installs as `sunswap-dex-trading` | Check prices, get quotes, swap tokens, manage V2/V3/V4 liquidity pools | Read-only: none. Trading: `TRON_PRIVATE_KEY` (or `TRON_MNEMONIC` / `AGENT_WALLET_PASSWORD`); optional `TRON_NETWORK`, `TRONGRID_API_KEY` |
+| **sunpump-agent-skill**<br/>installs as `sunpump-meme-token-toolkit` | SunPump meme coins: create tokens with one command (server-side, no wallet), market data/rankings/holders/portfolios, plus buy/sell meme coins (automatically picks the swap route based on whether the token has launched, TRON mainnet only) | Read-only & token creation: none. On-chain buy/sell: `TRON_PRIVATE_KEY` (or `TRON_MNEMONIC` / `AGENT_WALLET_PASSWORD`); optional `TRONGRID_API_KEY`, `SUNPUMP_API_BASE_URL`, and `TRON_NETWORK`, which must be `mainnet` if set |
+| **sunperp-skill**<br/>installs as `sunperp-perpetual-futures-trading` | Market data, open/close positions, withdrawals | Market data: none. Trading: `SUNPERP_ACCESS_KEY` and `SUNPERP_SECRET_KEY`. Withdrawals additionally need `TRON_PRIVATE_KEY` to sign the confirmation (`TRONGRID_API_KEY`, if set, only switches the RPC host) |
+| **tronscan-skill**<br/>installs as `tronscan-data-lookup` | Look up accounts, transactions, tokens, blocks, network stats | Optional: `TRONSCAN_API_KEY` — without one, requests go through the keyless BofAI proxy and may be rate-limited |
+| **usdd-skill**<br/>installs as `usdd-just-protocol` | USDD stablecoin — PSM swaps (1:1 USDT ↔ USDD), vault queries, balance checks | PSM / vault info: none. Balance checks (unless `--address` is given) and PSM swaps, including `--dry-run`: `TRON_PRIVATE_KEY`; optional `TRON_NETWORK`, `TRONGRID_API_KEY` |
 
 Five skills install under a different directory name than their repository folder — that second name is what appears in `~/.agents/skills` and what you reference when asking an assistant to read a skill file.
 
@@ -60,7 +60,7 @@ wallet-cli is the official wallet and CLI entry point. Other Skills and server i
 :::
 
 :::caution Hard boundaries: passwords and wallet administration
-In agent-driven runs, wallet passwords are only accepted via `--password-stdin` from an approved source — the AI never puts a password in command arguments, environment variables, or the chat, and never asks you to paste a password, mnemonic, or private key into the conversation. The root wallet-administration commands `import` / `backup` / `delete` / `change-password` are **human-only by skill policy**: the AI will not run them even if you confirm. This is the skill refusing, not a lock in the CLI — the CLI itself only forces a TTY for `import` and `change-password`, and `backup` even documents a `--password-stdin` form. Any funds-moving operation on mainnet is previewed first and waits for your explicit confirmation.
+In agent-driven runs, wallet passwords are only accepted via `--password-stdin` from an approved source — the AI never puts a password in command arguments, environment variables, or the chat, and never asks you to paste a password, mnemonic, or private key into the conversation. The root wallet-administration commands `import` / `backup` / `delete` / `change-password` are **human-only by skill policy**: the AI will not run them even if you confirm. This is the skill refusing, not a lock in the CLI — the CLI itself only forces a TTY for `import mnemonic` / `import private-key` / `import keystore` (not `import watch` or `import ledger`), `change-password`, and `delete` without `--yes`, and `backup` even documents a `--password-stdin` form. Any funds-moving operation on mainnet is previewed first and waits for your explicit confirmation.
 :::
 
 Note: wallet-cli canonically uses decimal CAIP-2 network ids — `tron:728126428` (Mainnet), `tron:3448148188` (Nile), `tron:2494104990` (Shasta); `tron:mainnet` / `tron:nile` / `tron:shasta` are accepted as input aliases only. This is distinct from the hex identifiers (`tron:0x…`) used in x402 protocol metadata; `wallet-cli x402` still uses wallet-cli network identifiers.
@@ -71,7 +71,7 @@ This skill also covers TRC20/TRC10 transfers and token queries, staking and SR v
 
 ## sunswap {#sunswap}
 
-Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the AI. This skill is powered by `@sun-protocol/sun-cli` (pinned to 1.2.2) and supports swaps plus V2 AMM, V3 concentrated liquidity, and V4 hooks-enabled pools.
+Want to swap tokens, check rates, or manage liquidity on SunSwap? Just tell the AI. This skill is powered by `@sun-protocol/sun-cli` (pinned to 1.2.2; install it yourself with `npm install -g @sun-protocol/sun-cli@1.2.2`) and supports swaps plus V2 AMM, V3 concentrated liquidity, and V4 hooks-enabled pools.
 
 **Completely safe — looking only, no spending:**
 
@@ -111,7 +111,7 @@ V3 only accepts fee tiers `100`, `500`, `3000`, or `10000` (0.01% / 0.05% / 0.3%
 
 ## sunpump-agent-skill {#sunpump-agent-skill}
 
-Want to play with meme coins on SunPump? This skill is built on `@sun-protocol/sun-cli` (pinned to 1.2.2) and helps you create meme tokens, check market data, do research, and buy/sell meme coins. Token creation (`sun sunpump launch`) is **server-side — no wallet needed**: provide a name, symbol, description, and logo, and the platform signs and broadcasts the creation transaction for you. For trading, it **picks the trade path automatically**: tokens that haven't created a SunSwap V2 pair yet ("pre-launch") go through `sun sunpump buy/sell`, while tokens that already have a SunSwap V2 pair ("post-launch") use a regular `sun swap` — before placing an order the AI runs `sunpump state` to confirm which path applies. **Every sunpump-agent-skill capability — queries and trading alike — is TRON mainnet only; testnets are not supported.**
+Want to play with meme coins on SunPump? This skill is built on `@sun-protocol/sun-cli` (pinned to 1.2.2; install it yourself with `npm install -g @sun-protocol/sun-cli@1.2.2`) and helps you create meme tokens, check market data, do research, and buy/sell meme coins. Token creation (`sun sunpump launch`) is **server-side — no wallet needed**: provide a name, symbol, description, and logo, and the platform signs and broadcasts the creation transaction for you. For trading, it **picks the trade path automatically**: tokens that haven't created a SunSwap V2 pair yet ("pre-launch") go through `sun sunpump buy/sell`, while tokens that already have a SunSwap V2 pair ("post-launch") use a regular `sun swap` — before placing an order the AI runs `sunpump state` to confirm which path applies. **Every sunpump-agent-skill capability — queries and trading alike — is TRON mainnet only; testnets are not supported.**
 
 **Absolutely safe, read-only:**
 
@@ -150,7 +150,7 @@ Meme coins are highly volatile and easily manipulated. When the AI shows you tok
 :::
 
 :::tip About token creation (launch)
-Creation goes through the SunPump agent endpoint — the platform signs and broadcasts the transaction, so **no wallet is needed**. Name, symbol, and description are required; a logo is strongly recommended (launches without one may be rejected by the API). On success the AI reports the new token's contract address and creation tx hash. Like every other SunPump operation, launch is **mainnet only** — the CLI rejects any non-mainnet `--network` before doing anything, even under `--dry-run`.
+Creation goes through the SunPump agent endpoint — the platform signs and broadcasts the transaction, so **no wallet is needed**. Name, symbol, and description are required; the Skill asks for a logo image before it launches, because launches without one often fail with the server error `Invoke third part error`. On success the AI reports the new token's contract address and creation tx hash. Like every other SunPump operation, launch is **mainnet only** — the CLI rejects any non-mainnet `--network` before doing anything, even under `--dry-run`.
 :::
 
 **sunpump-agent-skill's full functionality (queries and trading) only works on TRON mainnet, not testnets.**
@@ -181,7 +181,7 @@ Want to trade contracts? This skill handles market data, opening positions, clos
 
 > Stuck in a bad position? Try: "What's BTC's funding rate right now — should I go long or short?"
 
-> Want to manage risk? Try: "Lower my BTC-USDT leverage to 5x and set stop-loss to 3%."
+> Want to manage risk? Try: "Lower my BTC-USDT leverage to 5x, then open a small BTC-USDT long with a 3% stop-loss." (a stop-loss is set when the position is opened; the Skill has no command to change the stop-loss of an existing position)
 
 > Want the big picture? Try: "List all available perpetual contracts, sorted by 24h volume."
 
diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md
index 42eaca6f..3b2cd7b9 100644
--- a/docs/McpServer-Skills/SKILLS/Faq.md
+++ b/docs/McpServer-Skills/SKILLS/Faq.md
@@ -33,7 +33,7 @@ Skills require a program called "Node.js" on your computer (similar to how some
 **Simplest fix:** Go to [nodejs.org](https://nodejs.org/), download the latest LTS version (install it like any normal app — just click "Next" through the wizard), then try again.
 
 :::tip Already have Node.js but still getting errors?
-Run `node --version` in your terminal. Skills require **v20 or higher**. If your version is too old, download the latest from the official site and install over the old one.
+Run `node --version` in your terminal. Skills require **22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+**. If your version is too old, download the latest from the official site and install over the old one.
 :::
 
 ### How do I know the skills installed successfully?
@@ -116,7 +116,7 @@ Use the [wallet-cli setup flow](/wallet-cli/quickstart/) for the official wallet
 
 ### Which AI tools support Skills?
 
-The installer targets a broad set of coding agents and assistants — Claude Code, Cursor, Codex, Cline, Gemini CLI, Amp, Zed and many more — either by symlinking into the tool's own skill directory or by copying the files where the tool has no such directory. **OpenClaw** remains the most seamless. Any AI assistant that can read local skill files works too: point it at `~/.agents/skills/<skill>/SKILL.md`.
+The installer targets a broad set of coding agents and assistants — Claude Code, Cursor, Codex, Cline, Gemini CLI, Amp, Zed and many more — either by symlinking into the tool's own skill directory or by copying the files where the tool has no such directory. The OpenClaw one-click installer is paused and is not the recommended entry point for new users. Any AI assistant that can read local skill files works too: point it at `~/.agents/skills/<skill>/SKILL.md`.
 
 ---
 
@@ -136,12 +136,14 @@ For example, if you think 20x leverage is still too risky for perpetual trading,
 rm -rf ~/.agents/skills/sunswap-dex-trading
 ```
 
-**Update:** Re-run the install command (keep `-g` so it refreshes the global copy). It will update all skills to the latest version.
+**Update:** Re-run the install command (keep `-g` so it refreshes the global copy) and select the skills to update in the list it shows; they are reinstalled from the latest stable release on `main`. A reinstall replaces each selected Skill folder, so run `npm install` again in the SunPerp, TronScan and USDD folders afterwards.
 
 ```bash
-npx skills add https://github.com/BofAI/skills -y -g
+npx skills add https://github.com/BofAI/skills/tree/main -g
 ```
 
+Do not add `-y`: it also skips the agent selection, so the skills CLI installs into every agent it detects on your machine (plus the universal directories) and overwrites their existing copies — and into all 79 agents it knows (skills 1.7.4) when it detects none. To target one agent and skip the agent prompt, pass `-a <agent>`, for example `-a claude-code`; the skill selection and `Proceed with installation?` still ask. Lines such as `✗ … does not support global skill installation` refer to agents that have no global skill directory; the other agents are installed normally.
+
 ---
 
 ## Concepts (for the Curious)
diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md
index e191f713..f230944e 100644
--- a/docs/McpServer-Skills/SKILLS/Intro.md
+++ b/docs/McpServer-Skills/SKILLS/Intro.md
@@ -45,7 +45,7 @@ After receiving your command, it doesn't just execute — it automatically runs
 2. **Preemptive troubleshooting:** "Your USDT allowance for Permit2 doesn't cover this amount — the swap will send that approval automatically before it trades."
 3. **Precise quote:** "At the latest price, 50 USDT gets you roughly 350 TRX. I've set 1% slippage protection. Ready to buy?"
 
-In this scenario, you said one sentence, and the Skill quietly handled the steps behind the scenes: check the balance covers it → validate the pair and slippage → fetch a fresh quote → show you the bill and wait for your confirmation, with the one-time TRC-20 approval handled automatically by the underlying CLI. That's the difference between a **"regular chatbot AI"** and a **"professional Web3 butler."**
+In this scenario, you said one sentence, and the Skill quietly handled the steps behind the scenes: check the balance covers it → validate the pair and slippage → fetch a fresh quote → show you the bill and wait for your confirmation, with the TRC-20 approval to Permit2 (for the swap amount, whenever the current allowance is too low) handled automatically by the underlying CLI. That's the difference between a **"regular chatbot AI"** and a **"professional Web3 butler."**
 
 ---
 
@@ -78,7 +78,7 @@ Skills covering the most common TRON scenarios — the table below shows everyth
 
 - **👶 I'm a total beginner:** Perfect! No more wrestling with candlestick charts, slippage settings, or gas fee calculations. Just tell the AI what you want in plain language — it does the hard work and feeds you the results.
 - **🕴️ I'm an experienced trader:** Tired of staring at screens all day? Let the AI batch-monitor data and calculate yields, freeing up your time and energy. You focus on strategy — let the AI handle the tedious execution.
-- **🍉 I just want to explore:** Absolutely fine! Read-only skills like "On-Chain Data Detective" are 100% free — no wallet needed, zero risk, full access to the Web3 magic.
+- **🍉 I just want to explore:** Absolutely fine! Read-only skills like [tronscan-skill](./BANKOFAISkill.md#tronscan-skill) are 100% free — no wallet needed, zero risk, full access to the Web3 magic.
 
 ---
 
diff --git a/docs/McpServer-Skills/SKILLS/QuickStart.md b/docs/McpServer-Skills/SKILLS/QuickStart.md
index e78076f5..cbcf9a8b 100644
--- a/docs/McpServer-Skills/SKILLS/QuickStart.md
+++ b/docs/McpServer-Skills/SKILLS/QuickStart.md
@@ -6,7 +6,7 @@ description: "Install selected Skills and use wallet-cli as the official wallet
 
 # Skills Quick Start
 
-Requires Node.js 20 or newer. Select the Skills you need instead of installing every legacy wallet and onboarding helper by default.
+Requires Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+. Select the Skills you need instead of installing every legacy wallet and onboarding helper by default.
 
 ## Install wallet-cli
 
@@ -22,26 +22,31 @@ If `npm install -g` fails with a permission error (such as `EACCES`) on macOS or
 ## Select the Skill
 
 ```bash
-npx skills add https://github.com/BofAI/skills --skill wallet-cli -g
+npx skills add https://github.com/BofAI/skills/tree/main --skill wallet-cli -g
 ```
 
-`npx skills add` installs definitions, not external CLI dependencies. Since Skills 3.0.0, the `wallet-cli` Skill is pinned to `@tron-walletcli/wallet-cli@4.14.0`, the same version installed above.
+`npx skills add` installs definitions, not external CLI dependencies. Since Skills 3.0.0, the `wallet-cli` Skill is pinned to `@tron-walletcli/wallet-cli@4.14.0`, the same version installed above. Keep the `/tree/main` suffix: the repository's default branch is `develop`, which can carry unreleased Skills pinned to a different CLI version.
 
 For DeFi and data workflows (SunSwap, SunPump, SunPerp, TronScan, USDD), select additional Skills interactively:
 
 ```bash
-npx skills add https://github.com/BofAI/skills -g
+npx skills add https://github.com/BofAI/skills/tree/main -g
 ```
 
 Install only what you need and read each Skill's dependency and credential requirements. Do not assume SunSwap, SunPump, SunPerp, and USDD implementations have all moved to wallet-cli.
 
+Two setup steps that `npx skills add` does not perform:
+
+- **sun-cli** for the SunSwap and SunPump Skills — they require exactly 1.2.2 (`sun --version`): `npm install -g @sun-protocol/sun-cli@1.2.2`.
+- **Node dependencies** for the SunPerp, TronScan and USDD Skills — run `npm install` inside each installed Skill folder, for example `cd ~/.agents/skills/tronscan-data-lookup && npm install`.
+
 ## Configure and use
 
 Configure and select an account locally using the [Wallet CLI quick start](/wallet-cli/quickstart/). Never paste passwords, mnemonics, or private keys into chat.
 
-- Wallet and general TRON operations: use the `wallet-cli` Skill.
+- Wallet and general TRON operations: use the `wallet-cli` Skill. The Skill itself covers TRON wallet workflows; `x402`, `bai` and `8004` are wallet-cli command families outside the Skill's scope, so use their own references below.
 - x402 payments: use [wallet-cli x402](/wallet-cli/command-reference/).
-- B.AI recharge and records: inspect `wallet-cli bai --json-schema -o json` and configure a B.AI API key.
+- B.AI recharge and records: list the `bai` commands with `wallet-cli bai --help` (a single command's input schema: `wallet-cli bai recharge --json-schema`; `wallet-cli bai --json-schema` returns the whole command catalog, not just `bai`) and configure a B.AI API key.
 - DeFi and data workflows: follow each Skill's own requirements.
 
 Skills 3.0.0 removed `bankofai-guide`, `agent-wallet`, `x402-payment`, and `recharge-skill`; see the [Skill catalog](/McpServer-Skills/SKILLS/BANKOFAISkill/) for the current list. The OpenClaw one-click installer is paused and is not the recommended entry point for new users.
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/agent-wallet.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/agent-wallet.md
index ee7626d8..95c4a37e 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/agent-wallet.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/agent-wallet.md
@@ -7,6 +7,61 @@ description: 'Agent Wallet 的版本发布记录。'
 
 Agent Wallet 的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### 错误码、Privy 自动化与配置结构
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **SDK 指南**——列出 `WalletCliExecutionError` / `WalletCliUsageError` 的 `code`（`capability_missing`、`network_mismatch`、`timeout` 等）以及 wallet-cli 自身错误码会原样透传；`wallet_cli` 的 chainId 不一致抛 `SigningError`；`signAndBroadcast()` 在广播超时或 `wait` 期限到时返回 `{ txId, stage: 'timeout' }`，只在广播后查询状态失败时抛 `WalletCliSubmittedTransactionError`；`/advanced` 的导出列表补全。
+- **CLI 参考**——`privy` 自动化需同时传 `--app-id` 和 `--app-secret-exec`，否则复用或 secret 提示会以退出码 1 结束；`-g/--generate` 会被解析但被忽略；说明了 `wallets_config.json` 的结构。
+
+👉 [SDK 接入指南](/zh-Hans/Agent-Wallet/Developer/SDK-Guide/) · [CLI 命令行手册](/zh-Hans/Agent-Wallet/Developer/CLI-Reference/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-21</div>
+<div className="changelog-body">
+
+### 按 Agent Wallet 3.0 重写文档
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">破坏性变更</span></div>
+
+- **按 3.0.0 重写**——所有页面改为对应 `@bankofai/agent-wallet` 3.0.0。钱包类型为 `wallet_cli`（推荐）、`privy` 和 `raw_secret`。`local_secure`、主密码、`AGENT_WALLET_PASSWORD`、`runtime_secrets.json`，以及 `init`、`change-password`、`sign msg` 命令都已不存在。参见[从 2.x 升级](/zh-Hans/Agent-Wallet/FAQ/#upgrade-from-2x)。
+- **凭据**——wallet-cli 与 Privy 的密钥建议由 exec 脚本提供（`--cli-password-exec`、`--app-secret-exec`；也接受直接传入 `--app-secret`，但会以明文保存），3.x 没有密码环境变量。环境变量兜底只读取 `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`，2.x 的 `TRON_PRIVATE_KEY` 等别名不再读取。
+- **网络标识必须精确**——`-n` / `network` 只接受规范的 CAIP-2 字符串，如 `tron:728126428`、`tron:3448148188`、`eip155:56`；`tron:nile` 这类别名和十六进制 TRON ID 会被拒绝。
+- **签名结果**——`signTransaction()` 返回带 `family` 字段的 `SignedTransactionArtifact`，不再是字符串，Cookbook 示例按它分支处理。`signMessage` 已移除。
+- **只提供 TypeScript**——删除了 Python 标签页。PyPI 上的 `bankofai-agent-wallet` 停在 2.4.0，沿用 2.x 模型。
+- **参考手册修正**——`reset` 只删除 `wallets_config.json`；错误类列表补上 `ExternalSigner*` 和 `WalletCli*` 两组；补充 `/advanced`、`/integrations/wallet-cli` 两个导出入口和 `AGENT_WALLET_WALLET_CLI_PATH`。
+
+👉 [快速开始](/zh-Hans/Agent-Wallet/QuickStart/) · [CLI 命令行手册](/zh-Hans/Agent-Wallet/Developer/CLI-Reference/) · [SDK 接入指南](/zh-Hans/Agent-Wallet/Developer/SDK-Guide/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-09-10</div>
+<div className="changelog-body">
+
+### Agent Wallet v3.0.0
+
+<div className="changelog-tags"><span className="changelog-tag">新版本</span><span className="changelog-tag">破坏性变更</span></div>
+
+- **钱包类型**——新增 `wallet_cli` 类型，把 TRON 与 EVM 的交易和结构化数据签名委托给本机 wallet-cli 账户（兼容范围 `>=4.13.0 <5.0.0`）。移除 `local_secure`、主密码、`AGENT_WALLET_PASSWORD` 与 `runtime_secrets.json`；已有的 `local_secure` 钱包不会被转换。
+- **签名 API**——`signTransaction()` 不再返回字符串，改为带 `family` 字段的 `SignedTransactionArtifact`（EVM 为 `rawTransaction`，TRON 为 `transaction`）。移除 `signRaw()`、`signMessage()` 和 CLI 的 `sign msg`，只保留交易与结构化数据签名。
+- **包结构**——adapter、client 和配置解析等低阶 API 移到 `@bankofai/agent-wallet/advanced`；wallet-cli 相关辅助在 `@bankofai/agent-wallet/integrations/wallet-cli`。`ConfigWalletProvider` 改为 `new ConfigWalletProvider(dir, options)`。
+- **凭据与环境变量**——Privy 和 wallet-cli 的密钥支持 `{ "exec": "/absolute/script" }` 引用（`--app-secret-exec`、`--cli-password-exec`）。2.x 的 `TRON_PRIVATE_KEY`、`TRON_MNEMONIC`、`TRON_ACCOUNT_INDEX` 不再读取，请改用 `AGENT_WALLET_PRIVATE_KEY`、`AGENT_WALLET_MNEMONIC`、`AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`。
+- 2026 年 9 月 10 日发布到 npm。Python 包在 PyPI 上停留在 2.4.0。升级步骤见[从 2.x 升级](/zh-Hans/Agent-Wallet/FAQ/#upgrade-from-2x)。
+
+👉 [简介](/zh-Hans/Agent-Wallet/Intro/) · [CLI 命令行手册](/zh-Hans/Agent-Wallet/Developer/CLI-Reference/) · [SDK 接入指南](/zh-Hans/Agent-Wallet/Developer/SDK-Guide/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-09</div>
 <div className="changelog-body">
@@ -21,7 +76,7 @@ Agent Wallet 的版本发布记录。
 - **CLI 快速上手**——自定义密码示例改为显式指定钱包类型（`start local_secure -p …`），因为在交互式类型选择里选了 `raw_secret` 或 `privy` 时 `-p` 会被拒绝。
 - **Cookbook**——x402 签名章节更名为 EIP-3009，并说明它与仓库示例中同名但域名和字段都不同的 `PaymentPermit` 结构的区别。
 
-👉 [SDK 指南](/zh-Hans/Agent-Wallet/Developer/SDK-Guide/) · [CLI 参考](/zh-Hans/Agent-Wallet/Developer/CLI-Reference/)
+👉 [SDK 接入指南](/zh-Hans/Agent-Wallet/Developer/SDK-Guide/) · [CLI 命令行手册](/zh-Hans/Agent-Wallet/Developer/CLI-Reference/)
 
 </div>
 </div>
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md
index 45ef3e98..cc24a342 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/skills.md
@@ -7,6 +7,54 @@ description: 'SKILLS 的版本发布记录。'
 
 SKILLS 的版本发布记录。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### 各 Skill 的安装步骤与凭据
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **快速入门**——补上 `npx skills add` 不会做的两步：SunSwap / SunPump 需要 `npm install -g @sun-protocol/sun-cli@1.2.2`，SunPerp、TronScan、USDD 需要在 Skill 目录里 `npm install`。`x402`、`bai`、`8004` 是 wallet-cli 的命令组，不在 wallet-cli Skill 范围内。
+- **技能大全**——凭据一列写明各 Skill 读取的环境变量（`TRON_PRIVATE_KEY`、`SUNPERP_ACCESS_KEY` / `SUNPERP_SECRET_KEY`、`TRONSCAN_API_KEY` 等）；SunPump Skill 发币前会要求提供 logo；SunPerp 的示例不再暗示可以修改已有仓位的止损。
+
+👉 [快速入门](/zh-Hans/McpServer-Skills/SKILLS/QuickStart/) · [技能大全](/zh-Hans/McpServer-Skills/SKILLS/BANKOFAISkill/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-22</div>
+<div className="changelog-body">
+
+### Skills 3.0.1——Node.js 安全基线
+
+<div className="changelog-tags"><span className="changelog-tag">新版本</span></div>
+
+- **Node.js**——内置的 Node.js Skills 与 wallet-cli 安装器要求 Node.js `^22.23.4 || ^24.22.1 || >=26.12.1`，即 2026 年 10 月的安全更新版本。安装器会校验完整版本号，即使已安装锁定版本的 CLI 也会检查。
+- **wallet-cli 锁定版本不变**——`wallet-cli` Skill 仍锁定 `@tron-walletcli/wallet-cli@4.14.0`。
+- **文档**——Skills 与 BANK OF AI 快速入门已写明新的 Node.js 要求。
+
+👉 [快速入门](/zh-Hans/McpServer-Skills/SKILLS/QuickStart/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-21</div>
+<div className="changelog-body">
+
+### 从稳定的 main 分支安装 Skills
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- **安装命令**——改为 `npx skills add https://github.com/BofAI/skills/tree/main -g`。不加 `/tree/main` 时安装器会用仓库的默认分支 `develop`，那里尚未发布的 `wallet-cli` Skill 锁定的 CLI 版本与文档安装的 `@tron-walletcli/wallet-cli@4.14.0` 不同。FAQ 中的更新步骤同样遵循这一规则，并去掉了 `-y`——它会让 skills CLI 装进本机检测到的所有 Agent（一个都没检测到时装进全部 79 个已知 Agent）并覆盖已有副本。
+
+👉 [快速入门](/zh-Hans/McpServer-Skills/SKILLS/QuickStart/) · [常见问题](/zh-Hans/McpServer-Skills/SKILLS/Faq/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-28</div>
 <div className="changelog-body">
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md
index 0e38d803..3ad38fc9 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md
@@ -1,115 +1,137 @@
 # CLI 命令行手册
 
-包含了 Agent-wallet 所有命令的完整参考。无论你是想复习基础操作，还是想配置自动化脚本，这里都有答案。
+`agent-wallet` 3.x 全部命令的完整参考。无论是查阅基础用法，还是配置自动化脚本，都能在这里找到答案。
 
-:::tip 刚刚入门？
-如果你还没创建过钱包，先去 [快速开始](../QuickStart.md) 走一遍——三步搞定，不到一分钟。
+:::tip 刚开始？
+如果你还没有创建钱包，请先去 [快速开始](../QuickStart.md)。
+:::
+
+```
+Usage: agent-wallet <command> [options]
+
+Commands:
+  start             Quick setup: init + configure wallet
+  add               Add a wallet configuration
+  list              List all configured wallets
+  use [id]          Set the active wallet
+  inspect <id>      Show wallet details
+  resolve-address [id]  Resolve wallet addresses
+  remove [id]       Remove a wallet
+  sign              Sign transactions or typed data
+  reset             Delete all wallet data
+```
+
+所有命令都支持 `--dir, -d <path>`（钱包目录，默认 `~/.agent-wallet`，设置了 `AGENT_WALLET_DIR` 时以它为准）和 `--help, -h`。在任意命令或子命令后加 `-h`——例如 `agent-wallet start wallet_cli -h`——即可查看它的确切参数。
+
+:::caution 3.0 中已移除
+`init`、`change-password`、`sign msg`、`local_secure` 钱包类型，以及 `-p/--password`、`--save-runtime-secrets` 参数都已不存在；`-g/--generate` 仍会被解析但被忽略——3.x 不生成私钥。Agent-wallet 3.x 没有主密码，也不生成私钥。
 :::
 
 ---
 
 ## 基础命令
 
-高频使用的核心操作——创建钱包和签名。
+### `agent-wallet start`（创建钱包并设为激活）
 
-### `agent-wallet start`（初始化 / 创建钱包）
-
-**交互式创建（推荐）：**
 ```bash
-agent-wallet start
+agent-wallet start                       # 交互式：选择钱包类型
+agent-wallet start <raw_secret|privy|wallet_cli> [options]
 ```
-系统会一步步引导你选择钱包类型、生成密钥、设置主密码。跟着提示走就行。
 
-:::danger 切勿对真实资金使用 `raw_secret` 钱包类型
-交互式向导可能会提供 `raw_secret` 选项。该类型将私钥**以明文形式**存储在磁盘上——任何有文件系统访问权限的程序都能直接读取。`raw_secret` 仅适用于完全隔离的测试环境。持有真实资金的钱包请始终选择 `local_secure`。
-:::
+按需创建钱包目录，添加一个钱包，并把它设为**激活**钱包。如果已存在钱包，`start` 会先询问要 `add`（再加一个）还是 `exit`；传 `--override` 可跳过这个询问。
 
-:::tip Privy 钱包类型
-向导还提供 `privy` 选项，用于 Privy 托管的服务器钱包。该类型将密钥托管交给 Privy 的基础设施——本地磁盘上不存储私钥。配置时需要 Privy App ID、App Secret 和 Wallet ID：
+把钱包类型作为子命令写出来可以跳过类型选择。在 CI 或后台服务中，还要传 `-w` 以及所有凭据参数——缺少时 CLI 会弹出提示，而在非交互环境中提示会直接失败。如果可能已有钱包，还要传 `--override`；否则无法询问 add/exit，`start` 会以退出码 1 结束。
+
+| 参数 | 适用于 | 说明 |
+| :--- | :--- | :--- |
+| `-w, --wallet-id <id>` | 全部 | 要创建的钱包 ID。提示中的默认值：`default_raw`、`default_privy`、`default_cli` |
+| `--override` | 仅 `start` | 已有钱包时跳过"已初始化"提示 |
+| `-k, --private-key <hex>` | `raw_secret` | 导入十六进制私钥 |
+| `-m, --mnemonic <words>` | `raw_secret` | 导入 BIP-39 助记词 |
+| `-mi, --mnemonic-index <n>` | `raw_secret` | 助记词账户索引（默认 `0`；需要同时传 `-m`） |
+| `--derive-as <profile>` | `raw_secret` | `eip155` 或 `tron`；用于回答助记词派生方式的提示（3.0.0 会校验取值但不保存，因此不影响派生出的地址） |
+| `--app-id <id>` | `privy` | Privy app ID |
+| `--app-secret <secret>` | `privy` | Privy app secret（明文；建议改用 `--app-secret-exec`） |
+| `--app-secret-exec <path>` | `privy` | 输出 Privy app secret 的可执行脚本 |
+| `--privy-wallet-id <id>` | `privy` | 已有的 Privy 钱包 ID |
+| `--account <label>` | `wallet_cli` | 已有的 wallet-cli 账户标签或 ID（省略时使用 wallet-cli 当前激活账户） |
+| `--cli-password-exec <path>` | `wallet_cli` | 输出 wallet-cli keystore 密码的可执行脚本 |
+| `-d, --dir <path>` | 全部 | 钱包目录 |
+
+#### `wallet_cli` 钱包
+
+把已有的 [wallet-cli](../../wallet-cli/quickstart.md) 账户连结为 TRON + EVM 签名器。**它不会创建或导入私钥**——请先用 wallet-cli 创建账户。
 
 ```bash
-agent-wallet start   # 然后在提示时选择 "privy"
+agent-wallet start wallet_cli \
+  --wallet-id my_cli_wallet \
+  --account main-1 \
+  --cli-password-exec /absolute/path/to/fetch-password.sh
 ```
 
-Privy 钱包的默认 ID 是 `default_privy`。
-:::
+- 需要 `@tron-walletcli/wallet-cli` `>=4.13.0 <5.0.0`。Agent-wallet 按以下顺序查找：`AGENT_WALLET_WALLET_CLI_PATH`、与 Agent-wallet 一起作为本地包依赖安装的副本，最后是 `PATH` 中的 `wallet-cli`。找不到时命令会打印安装指引并以 1 退出。
+- 在收集任何密码**之前**，会先向 wallet-cli 确认账户存在；保存的是规范账户 ID，之后 wallet-cli 切换激活账户也不会影响这个钱包。
+- `--cli-password <明文>` 会被拒绝，避免密码进入 shell 历史或进程列表。不带 `--cli-password-exec` 时，交互提示会让你选择 `direct`（以明文保存在 `wallets_config.json`，权限 `0600`）或 `exec`。
 
-**自定义密码：**
-```bash
-agent-wallet start local_secure -p Abc12345!
-```
-`-p` 只对 `local_secure` 有效。直接跑不带类型的 `start` 再传 `-p`，只有在随后的类型选择里选 `local_secure` 才能走通；若选了 `raw_secret` 或 `privy`，CLI 会以 `--password is only valid for local_secure quick start.` 退出。像上面那样在命令行里写明类型即可避免。
+#### Privy 钱包 {#privy-wallets}
 
-密码要求：至少 8 位，包含大写、小写、数字和特殊字符。在交互式提示里输入的密码会被反复要求重输直到通过；而通过 `-p`、`AGENT_WALLET_PASSWORD` 或 `runtime_secrets.json` 传入的密码不会——强度不足会直接打印校验错误并退出 1。
+连结已有的 [Privy](https://privy.io) 服务端钱包。你的磁盘上不保存私钥；签名会调用 Privy API，因此需要联网。
 
-交互式创建新密码时，需要输入两次进行确认。如果两次输入不一致，系统会要求你重新输入。
+```bash
+agent-wallet start privy -w default_privy \
+  --app-id <privy-app-id> \
+  --app-secret-exec /absolute/path/to/fetch-privy-secret.sh \
+  --privy-wallet-id <privy-wallet-id>
+```
 
-**默认钱包 ID：** 如果不指定钱包 ID，系统默认为 `local_secure` 钱包使用 `default_secure`，为 `raw_secret` 钱包使用 `default_raw`。
+#### `raw_secret` 钱包
 
-:::caution Shell 历史记录风险
-使用 `-p` 内联传递密码会将密码记录在终端的历史文件中。生产钱包建议使用交互式模式（不带 `-p` 的 `agent-wallet start`）或通过环境变量设置 `AGENT_WALLET_PASSWORD`——详见[非交互式执行](#非交互式执行专为自动化与后台设计)。
+:::danger 真实资金请勿使用 `raw_secret`
+该类型把你的私钥或助记词**不加密**地保存在 `wallets_config.json` 中——任何有文件系统访问权限的程序都能直接读取。只在隔离的测试环境中配合一次性私钥使用。
 :::
 
-**导入已有私钥：**
 ```bash
-agent-wallet start -p Abc12345! -k your-private-key-hex
+agent-wallet start raw_secret -w default_raw -k <private-key-hex>
+agent-wallet start raw_secret -w default_raw -m "word1 word2 ..." --derive-as eip155
 ```
 
-**导入助记词：**
+### `agent-wallet add`（再添加一个钱包）
+
 ```bash
-agent-wallet start -p Abc12345! -m "word1 word2 word3 ..."
+agent-wallet add
+agent-wallet add <raw_secret|privy|wallet_cli> [options]
 ```
 
-#### 跳过交互：直接指定钱包类型
+子命令和参数与 `start` 相同（`--override` 除外）。只有在此前没有激活钱包时，新钱包才会成为激活钱包；切换请用 `use`。
 
-`start` 和 `add` 也可以把钱包类型作为子命令传入，这样会跳过类型选择。但在 CI 或后台服务里还必须带上 `-w`——否则 CLI 仍会询问钱包 ID，而在非交互环境下该提问会以 `Cannot prompt for wallet id in a non-interactive environment. Pass the required flags explicitly.` 报错并退出 1：
+### `agent-wallet sign`（核心签名操作）
 
 ```bash
-agent-wallet start local_secure -w default_secure -p Abc12345! -g   # 加密存储，生成新私钥
-agent-wallet start raw_secret -w default_raw -k 你的私钥            # 明文，仅限开发
-agent-wallet start privy -w default_privy --app-id <id> --app-secret <secret> --privy-wallet-id <wallet>
+agent-wallet sign tx '<json>' -n <network> [-w <wallet-id>]
+agent-wallet sign typed-data '<json>' -n <network> [-w <wallet-id>]
 ```
 
-`add` 用法相同（`add local_secure` / `add raw_secret` / `add privy`），用于再加一个钱包。
-
-| 选项 | 适用类型 | 说明 |
+| 参数 | 缩写 | 说明 |
 | :--- | :--- | :--- |
-| `-w, --wallet-id <id>` | 全部 | 要创建的钱包 ID |
-| `-g, --generate` | `local_secure` | 生成一个新的随机私钥 |
-| `-k, --private-key <hex>` | `local_secure`、`raw_secret` | 导入私钥 |
-| `-m, --mnemonic <words>` | `local_secure`、`raw_secret` | 导入助记词 |
-| `-mi, --mnemonic-index <n>` | `local_secure`、`raw_secret` | 从助记词派生时的账户索引 |
-| `--derive-as <profile>` | `local_secure`、`raw_secret` | 助记词派生方案：`eip155` 或 `tron` |
-| `-p, --password <pass>` | `local_secure` | 主密码 |
-| `--app-id` / `--app-secret` / `--privy-wallet-id` | `privy` | Privy 应用凭证与钱包 ID |
-| `-d, --dir <path>` | 全部 | 密钥目录（默认 `~/.agent-wallet`） |
-| `--save-runtime-secrets` | `local_secure` | 把密码写入 `runtime_secrets.json`。`raw_secret` 与 `privy` 路径不会读取它——这两条路径根本不收集密码 |
-| `--override` | 仅 `start` | 已存在钱包时跳过确认提示 |
-
-用 `agent-wallet start local_secure --help` 或 `agent-wallet add privy --help` 查看某个模式的确切选项。
-
-### `agent-wallet sign`（核心签名操作）
-
-对于 `local_secure` 和 `raw_secret` 钱包，每条 `sign` 子命令都需要 `--network` / `-n` 来指定链。Privy 钱包例外：链类型由 Privy 提供，EVM 交易载荷本身也包含 `chainId`，因此 Privy 签名可以省略 `--network`。
+| `--network` | `-n` | 规范 CAIP-2 网络：`eip155:<chainId>` 或 `tron:<chainId>`。**`raw_secret` 和 `wallet_cli` 必填。** `privy` 可省略（EVM 交易使用 payload 中的 `chainId`），但如果提供也必须是规范格式 |
+| `--wallet-id` | `-w` | 用哪个钱包签名（默认为激活钱包） |
+| `--dir` | `-d` | 钱包目录 |
 
-:::info 密码重试机制
-使用 `local_secure` 钱包签名时，如果未通过 `-p`、`~/.agent-wallet/runtime_secrets.json` 或 `AGENT_WALLET_PASSWORD`（优先级从高到低）提供密码，CLI 会交互式提示输入主密码。密码错误时，`sign` 命令会立即以退出码 1 失败（`Wrong password. Please try again.`）；「3 次重试」机制只适用于 `start`、`add`、`change-password` 和 `resolve-address` 的交互提示，不适用于 `sign`。
-:::
+只接受精确的规范标识——`tron`、`eip155`、`evm:1`、`tron:nile`、`tron:mainnet`、十六进制 TRON id，以及任何大小写或空白变体都会被拒绝。请使用 `tron:728126428`（主网）、`tron:3448148188`（Nile）、`tron:2494104990`（Shasta）、`eip155:1`、`eip155:56`、`eip155:97` 等。`wallet_cli` 钱包还要求该网络是 wallet-cli 自身认识的网络——即它的内置网络（`eip155:1`、`eip155:11155111`、`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`（Base 自 wallet-cli 4.14.0 起才内置）及三个 TRON 网络），或在 wallet-cli 自己的配置中添加的网络——否则签名会以 `wallet-cli network '<id>' is unavailable` 失败（SDK 中的 code 为 `network_mismatch`）。`raw_secret` 和 `privy` 钱包没有这一限制。
 
-**签名消息：**
+**签名 TRON 交易**（先通过 TronGrid 等构建未签名交易；必须包含 `raw_data_hex`，`wallet_cli` 钱包还需要 `raw_data` 和匹配的 `txID`）：
 ```bash
-agent-wallet sign msg "Hello" -n tron
-# 输出: Signature: d220de880cbc1c3f...
+agent-wallet sign tx '{"txID":"...","raw_data_hex":"0a02...","raw_data":{}}' -n tron:3448148188
+# 输出："Signed tx:" 后跟格式化的已签名交易 JSON
 ```
 
-**签名交易**（需要先通过 RPC 构建未签名交易）：
+**签名 EVM 交易**（`chainId` 应与 `-n` 一致；`wallet_cli` 钱包会以 `SigningError` 拒绝不一致的情况，`raw_secret` 和 `privy` 则按 payload 中的 `chainId` 签名）：
 ```bash
-agent-wallet sign tx '{"txID":"abc123...","raw_data_hex":"0a02...","raw_data":{...}}' -n tron
-# 输出：先是一行 `Signed tx:`，随后是美化格式的已签名交易 JSON
-# （只有当结果不是合法 JSON 时才会输出成一行）
+agent-wallet sign tx '{"chainId":97,"nonce":0,"gas":"0x5208","gasPrice":"0x3b9aca00","to":"0x...","value":"0x0"}' -n eip155:97
+# 输出：Signed tx: <原始交易 hex，不带 0x>
 ```
 
-**签名 EIP-712 结构化数据：**
+**签名 EIP-712 / TIP-712 结构化数据：**
 ```bash
 agent-wallet sign typed-data '{
   "types": {
@@ -120,98 +142,68 @@ agent-wallet sign typed-data '{
   "domain": {"name":"MyDApp","chainId":1},
   "message": {"to":"0x7099...","amount":1000000}
 }' -n eip155:1
+# 输出：Signature: <hex，不带 0x>
 ```
 
----
-
-### `agent-wallet init`（初始化密钥目录）
-
-初始化密钥目录并设置主密码------但此时不会创建钱包。这在一些高级场景中很有用，比如你希望在添加钱包之前先准备好目录结构。
-
-```bash
-agent-wallet init
-```
-
-**非交互模式：**
-
-```bash
-agent-wallet init -p 'Abc12345!'
-```
-
-| 参数 | 说明 |
-| :--- | :--- |
-| `--password, -p <pw>` | 主密码（跳过交互输入） |
-| `--save-runtime-secrets` | 将密码持久化保存到  `runtime_secrets.json` |
-
-:::tip 什么时候使用 `init` 和 `start` 
-`start` = `init` + 创建钱包（一步完成）。如果你只需要先设置目录和密码（例如用于 CI
-流程，或稍后再导入私钥），可以单独使用 `init`。 
+:::note 不支持消息签名
+`sign msg` 已在 3.0 中移除。Agent-wallet 只签名交易和结构化数据。
 :::
 
-
 ---
 
 ## 钱包管理
 
 管理多个钱包——添加、切换、查看、删除。
 
-**添加新钱包：**
-```bash
-agent-wallet add
-```
-
-**列出所有钱包：**
+**列出所有钱包**（`*` 标记激活钱包）：
 ```bash
 agent-wallet list
 ```
 
-**切换活跃钱包：**
+**切换激活钱包**（省略 ID 时从列表中选择）：
 ```bash
 agent-wallet use my-bsc-wallet
 ```
 
-**查看钱包详情：**
+**查看钱包详情**（敏感信息始终显示为 `[redacted]`）：
 ```bash
 agent-wallet inspect my-bsc-wallet
 ```
 
-要查看钱包的派生地址，请使用独立的 `resolve-address` 命令：
+**用指定钱包签名**（不切换激活钱包）：
 ```bash
-agent-wallet resolve-address my-bsc-wallet
+agent-wallet sign typed-data '<json>' -n eip155:56 -w my-bsc-wallet
 ```
 
-**用指定钱包签名**（不切换活跃钱包）：
-```bash
-agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!'
-```
-
-**删除钱包：**
+**删除钱包**（省略 ID 时从列表中选择）：
 ```bash
 agent-wallet remove my-bsc-wallet
 ```
 
-| 参数 | 简写 | 说明 |
+| 参数 | 缩写 | 说明 |
 | :--- | :--- | :--- |
-| `--yes` | `-y` | 跳过确认提示（**非交互 / Agent 场景下必需**） |
+| `--yes` | `-y` | 跳过确认提示（**在非交互 / 代理环境中必须使用**） |
+
+删除 `wallet_cli` 或 `privy` 钱包只会删除 Agent-wallet 中的配置条目——wallet-cli 账户或 Privy 钱包本身不受影响。
 
 ### `agent-wallet resolve-address`（解析钱包地址）
 
-显示某个钱包关联的链上地址。本地钱包（`local_secure`、`raw_secret`）都会显示 EVM 与 TRON 两个地址：`local_secure` 钱包（无论如何创建——助记词导入时只存按 `--derive-as` 方案派生出的那一把密钥）和私钥型 `raw_secret` 钱包的两个地址由同一把密钥派生；只有 `raw_secret` **助记词**钱包会按各链自己的派生路径分别从助记词派生。Privy 钱包显示 Privy 返回的单一地址。
+不签名，只显示钱包对应的链上地址：
+
+- `raw_secret` 钱包显示由同一份密钥材料派生出的 EVM 和 TRON 两个地址。
+- `wallet_cli` 钱包在 wallet-cli 账户同时拥有两条链地址时显示两个地址（否则显示一个），不会索要密码。
+- `privy` 钱包显示 Privy 返回的单个地址。
 
 ```bash
 agent-wallet resolve-address my-wallet
 ```
 
-如果省略钱包 ID，CLI 会弹出交互式列表让你选择：
+省略钱包 ID 时，CLI 会给出交互式列表供你选择。
 
-```bash
-agent-wallet resolve-address
-```
-
-示例输出：
+输出示例：
 ```
 Wallet  my-wallet
-Type    local_secure
+Type    raw_secret
 
 Addresses
 EVM   0x742D35CC6634C0532925a3B844Bc9E7595F2bD18
@@ -220,141 +212,51 @@ TRON  TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC
 
 ---
 
-## 非交互式执行（专为自动化与后台设计）
-
-默认情况下，执行签名命令时，终端会停下来并出现一行提示，等待你手动敲击键盘输入密码。但如果是 AI 代理在后台运行，或者你在跑自动化脚本，这种"中途停下来等人输入"的机制会导致程序直接卡死报错。
-
-为了让程序能一口气静默跑完（非交互模式），你需要提前把密码"喂"给命令。根据你的使用场景，有以下三种方式：
-
-### 方式 A：环境变量注入（推荐用于 AI 代理 / CI 流水线）
-
-将密码提前存在当前系统环境里，程序运行需要密码时会自动去环境里拿，全程静默：
-
-```bash
-export AGENT_WALLET_PASSWORD='Abc12345!'
-```
-
-设置后，当前窗口的所有签名命令直接秒出结果，不再停顿等待：
-
-```bash
-agent-wallet sign msg "Hello" -n tron
-agent-wallet sign tx '{"txID":"..."}' -n tron
-```
-
-:::tip 防止此命令被记录到 Shell 历史
-建议直接用文本编辑器编辑 `~/.zshrc` / `~/.bashrc`，从根本上避免历史记录泄露。如果选择在命令前加空格来阻止记录，请先确认你的 Shell 已启用相应设置：Bash 中运行 `echo $HISTCONTROL` 确认包含 `ignorespace`，Zsh 中运行 `setopt | grep HIST_IGNORE_SPACE` 确认已开启。这些设置在大多数系统上**并非**默认启用，需要手动配置。
-:::
-
-:::caution 密码有特殊字符？务必用单引号
-```bash
-# 正确 — shell 按字面意思处理
-export AGENT_WALLET_PASSWORD='P@ss$w0rd!'
-
-# 错误 — $ 被 shell 展开，导致密码在后台静默报错
-export AGENT_WALLET_PASSWORD="P@ss$w0rd!"
-```
-:::
-
-<details>
-<summary>GitHub Actions / CI 示例</summary>
-
-在 CI/CD 环境中，切勿将密码硬编码在工作流文件里。请使用仓库密钥（Secrets）：
-
-```yaml
-# .github/workflows/sign.yml
-jobs:
-  sign:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: agent-wallet sign msg "Hello" -n tron
-        env:
-          AGENT_WALLET_PASSWORD: ${{ secrets.AGENT_WALLET_PASSWORD }}
-```
-
-</details>
-
-### 方式 B：密码本地缓存（便利性与安全性的取舍）
-
-执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量：
-
-```bash
-agent-wallet sign msg "Hello" -n tron -p 'Abc12345!' --save-runtime-secrets
-```
+## 非交互式执行（适用于自动化和后台服务）
 
-:::danger 此操作会使双重锁保护失效
-将密码缓存在钱包文件旁边，意味着一次文件系统入侵就能获取全部资金——彻底击溃 Agent-wallet 的核心"物理文件 + 密码分离"安全模型。**请仅对一次性测试钱包使用此功能。**
+3.x 没有需要提供的主密码。要做到全程无提示运行：
 
-`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。务必确保该文件不会被提交到 git 或同步到云端。
+- **创建钱包：** 写出钱包类型，并用参数提供所有值（`-w`、`-k`/`-m` 加 `--derive-as`、`--app-id`/`--privy-wallet-id`、`--account`）。使用 `start` 时，如果可能已有钱包，再加 `--override`——否则会以退出码 1 结束。`privy` 要**同时**传 `--app-id` 和 `--app-secret-exec`（或 `--app-secret`）：已有 Privy 钱包、且 `--app-id` 和 `--app-secret` 都没传时（只传 `--app-secret-exec` 不算），CLI 会询问是否复用已有凭据；传了 `--app-id` 但没传 secret 时则询问 secret 的来源。非交互环境下这两种提示都会以退出码 1 结束。
+- **密钥类凭据：** 使用 exec 脚本——wallet-cli 用 `--cli-password-exec`，Privy 用 `--app-secret-exec`。路径必须指向一个可执行文件（不是内联 shell 命令）。脚本继承进程环境变量，其 stdout 去除首尾空白后作为凭据，默认 10 秒超时。对于 `wallet_cli`，脚本会在**每次**签名时重新执行。
+- **签名：** 始终传 `-n`；如果不想依赖激活钱包，再加 `-w`。
+- **删除 / 重置：** 传 `-y`。
+- **检查参数拼写：** CLI 会直接忽略无法识别的参数而不报错，拼错的参数（例如 `--walet-id`）会静默退回到提示或默认值。
 
-工具在创建该文件时会自动设置严格的文件权限（`600`——仅所有者可读）。如果你手动移动或复制过该文件，请验证权限：`chmod 600 ~/.agent-wallet/runtime_secrets.json`。
+`wallets_config.json` 包含 `active_wallet` 和以钱包 ID 为键的 `wallets`；每个条目有 `type` 和 `params`：`raw_secret` 为 `source`（`private_key`，或 `mnemonic` 加 `account_index`）；`privy` 为 `app_id`、`app_secret`、`wallet_id`；`wallet_cli` 为 `account`（可选）和 `password`。`app_secret` 和 `password` 可以是字符串，也可以是 exec 引用（`private_key` 和 `mnemonic` 只能是字符串）（`timeout` 以毫秒为单位，可选）：
 
-要删除已缓存的密码并恢复完整的双重锁保护：
-
-```bash
-rm ~/.agent-wallet/runtime_secrets.json
+```json
+{ "exec": "/absolute/path/to/fetch-password.sh", "timeout": 10000 }
 ```
 
-删除后，签名命令将再次以交互方式提示输入密码（或从 `AGENT_WALLET_PASSWORD` 环境变量读取）。
-:::
-
-### 方式 C：命令行内联 `-p`（适合临时跑单次指令）
+### 自定义存储目录
 
-直接把密码写在命令的结尾。程序拿到密码就直接干活，不会再停下来问你：
+所有命令都支持 `--dir`，用来指定 `~/.agent-wallet` 以外的钱包目录。设置 `AGENT_WALLET_DIR` 可以让它成为 CLI 和 SDK 的默认目录：
 
 ```bash
-agent-wallet sign msg "Hello" -n tron -p 'Abc12345!'
+agent-wallet start raw_secret --dir /Volumes/MyUSB/agent-wallet
+agent-wallet list --dir /Volumes/MyUSB/agent-wallet
 ```
 
-:::danger 安全提示
-直接用 `-p` 传递密码时，明文密码会被留在你电脑的终端 `history`（历史记录）中。强烈建议仅在完全隔离的测试环境中使用此方法！
-:::
+### 环境变量
 
-### 自定义存储目录
-
-所有命令都支持 `--dir` 参数来指定 Agent-wallet 的存储路径（默认在 `~/.agent-wallet`）。比如，你可以把 Agent-wallet 直接建在加密 U 盘里，即插即用，拔下即走：
-
-```bash
-agent-wallet start --dir /Volumes/MyUSB/agent-wallet
-agent-wallet sign msg "Hello" -n tron --dir /Volumes/MyUSB/agent-wallet
-```
+| 变量 | 用途 |
+| :--- | :--- |
+| `AGENT_WALLET_DIR` | 默认钱包目录（CLI 和 SDK） |
+| `AGENT_WALLET_WALLET_CLI_PATH` | wallet-cli 不在 `PATH` 中时，指定其可执行文件或 JavaScript 入口的路径 |
+| `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC` / `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | 仅用于 SDK 的环境变量回退（没有配置任何钱包时才使用）——参见 [SDK 接入指南](./SDK-Guide.md#environment-variable-fallback) |
 
 ---
 
 ## 危险操作
 
-:::danger 以下操作不可逆，请谨慎使用！
+:::danger 以下操作不可逆，请务必谨慎！
 :::
 
-### `agent-wallet change-password`（修改主密码）
+<a id="agent-wallet-reset"></a>
 
-修改后，**所有密钥文件会用新密码重新加密**。旧密码立即失效，请确保已在密码管理器中更新。
+### `agent-wallet reset`（重置所有数据） {#agent-wallet-reset-reset-all-data}
 
-**交互式（默认）：**
-```bash
-agent-wallet change-password
-```
-
-**非交互式**（用于自动化脚本）：
-```bash
-agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!'
-```
-
-| 参数 | 说明 |
-| :--- | :--- |
-| `--password, -p <pw>` | 当前主密码（跳过提示） |
-| `--new-password <pw>` | 新主密码（跳过提示） |
-| `--save-runtime-secrets` | 同步更新 `runtime_secrets.json` 中的缓存密码 |
-
-:::caution
-`-p` 和 `--new-password` 都会被记录在 Shell 历史中。生产环境请优先使用交互式模式，或通过密钥管理器传入密码。
-:::
-
-<a id="agent-wallet-reset-reset-all-data"></a>
-
-### `agent-wallet reset`（重置所有数据）
-
-删除 `~/.agent-wallet/` 中由 CLI 管理的文件——`master.json`、`wallets_config.json`、`runtime_secrets.json`，以及所有 `secret_*.json`。**这是核弹级操作——一旦执行，所有钱包、密钥、配置全部消失，无法恢复。** 目录本身及其中的其他文件（包括 `cred_*.json`）会保留。CLI 会要求**两次**确认；自动化场景可传 `-y/--yes` 跳过这两次提问。
+删除钱包目录中的 `wallets_config.json`——所有钱包配置，包括其中保存的 `raw_secret` 私钥，都会被删除。目录中的其他文件保持不动。wallet-cli 账户和 Privy 钱包本身不受影响。CLI 会**两次**确认；在自动化中传 `-y/--yes` 跳过两次提示。
 
 ```bash
 agent-wallet reset
@@ -362,42 +264,41 @@ agent-wallet reset
 
 ---
 
-## 实战：在 Shell 脚本中调用签名
-
-CLI 不只是拿来手敲的——它可以完美嵌入你的自动化脚本。
+## 实战示例：在 Shell 脚本中签名
 
-下面这个极简示例展示了如何在 Bash 脚本中完成一次非交互式签名并把签名存入变量（CLI 输出的是 `Signature: <hex>`，用 `sed` 去掉前缀）：
+下面的最小示例在 Bash 脚本中执行一次非交互式结构化数据签名，并把结果存进变量。CLI 输出 `Signature: <hex>`，脚本会去掉前缀，并检查剩下的是不是 130 位十六进制签名。这里特意不用管道接 `sed`：管道的退出状态取最后一个命令，签名失败也会被当成成功。
 
 ```bash
 #!/bin/bash
-# 开启严格模式：遇到报错立刻停止
-set -e
-
-# 1. 密码应在运行此脚本之前已在环境中设置好。
-#    例如通过 ~/.zshrc / ~/.bashrc — 详见快速开始中的"保存并使密码生效"。
-#    切勿在脚本文件中硬编码真实密码（密码会随脚本进入 git 历史记录）。
-if [[ -z "$AGENT_WALLET_PASSWORD" ]]; then
-  echo "错误：AGENT_WALLET_PASSWORD 未设置" >&2
-  exit 1
-fi
+# 严格模式：出错、使用未定义变量、管道中任一命令失败时都立即停止
+set -euo pipefail
+
+# 要签名的结构化数据（由你自己的逻辑构建）
+TYPED_DATA='{"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}],"Message":[{"name":"contents","type":"string"}]},"primaryType":"Message","domain":{"name":"MyScript","chainId":56},"message":{"contents":"Hello from my script"}}'
 
 echo "正在调用本地 Agent-wallet 签名..."
 
-# 2. 核心操作：执行签名，并将终端打印出的哈希结果直接存入 SIGNATURE 变量
-SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron | sed 's/^Signature: //')
+# 签名失败时 CLI 以非零码退出，并输出原因（如 "Wallet 'my-bsc-wallet' not found"）
+if ! OUTPUT=$(agent-wallet sign typed-data "$TYPED_DATA" -n eip155:56 -w my-bsc-wallet); then
+  echo "❌ 签名失败：$OUTPUT" >&2
+  exit 1
+fi
 
-# 3. 拿到干净的签名值，继续后续流程
-echo "✅ 签名成功！"
-echo "提取到的签名内容是: $SIGNATURE"
+SIGNATURE=${OUTPUT#Signature: }
+if [[ ! "$SIGNATURE" =~ ^[0-9a-fA-F]{130}$ ]]; then
+  echo "❌ 输出不符合预期：$OUTPUT" >&2
+  exit 1
+fi
 
-# 接下来，你可以拿这个 $SIGNATURE 去发请求、拼 JSON，或者传给其他流水线任务...
+echo "✅ 签名成功！"
+echo "提取到的签名：$SIGNATURE"
 ```
 
 ---
 
 ## 下一步
 
-- 没写过代码？ → [快速上手](../QuickStart.md)
-- 要开发应用？ → [SDK 接入指南](./SDK-Guide.md)
-- 找现成代码？ → [完整代码示例](./SDK-Cookbook.md)
-- 查看常见问题 → [FAQ](../FAQ.md)
+- 刚接触？ → [快速开始](../QuickStart.md)
+- 要自己写代理？ → [SDK 接入指南](./SDK-Guide.md)
+- 想找现成代码？ → [完整代码示例](./SDK-Cookbook.md)
+- 常见问题 → [常见问题](../FAQ.md)
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md
index b267ef95..9e8d28ee 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md
@@ -1,19 +1,16 @@
 import ThemedImage from '@theme/ThemedImage';
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # 完整代码示例
 
 :::tip 为什么要看这个页面？
-在 [SDK 快速开始](./SDK-Guide.md) 中，你已经学会了如何让 Agent-wallet 完成"离线签名"。但在真实的业务中，AI 代理不能只会签名。它需要：**1. 去节点查数据构建交易 → 2. Agent-wallet 签名 → 3. 广播上链。**
+在 [SDK 接入指南](./SDK-Guide.md) 中，你已经学会了如何让 Agent-wallet 完成"离线签名"。但在真实的业务中，AI 代理不能只会签名。它需要：**1. 去节点查数据构建交易 → 2. Agent-wallet 签名 → 3. 广播上链。**
 
-Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页为你提供了一套**"开箱即用"**的完整脚本，结合了 TronGrid 和 Ethers.js / Web3.py，带你跑通真正的全链路闭环。你可以直接复制这些代码用于你的生产环境！
+Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页为你提供了一套**"开箱即用"**的完整脚本，结合了 TronGrid、Ethers.js 与 `@bankofai/agent-wallet` 3.x SDK，带你跑通真正的全链路闭环。你可以直接复制这些代码用于你的生产环境！
 :::
 
 本页走完三个真实场景的完整流程：在 TRON 发送 TRX、在 BSC 发送 BNB、签名 x402 支付许可。每个示例都可以直接运行——复制代码、填入你的地址，就能跑。
 
-文档提供 TypeScript 和 Python 两个版本，点击标签页切换。
+所有示例均为 TypeScript——Agent-wallet 3.x 没有 Python SDK（PyPI 上的 `bankofai-agent-wallet` 停留在 2.4.0）。
 
 ---
 
@@ -22,11 +19,11 @@ Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页
 运行以下任何示例之前，确保已经完成：
 
 1. 安装 Agent-wallet SDK（详见 [SDK 接入指南](./SDK-Guide.md)）
-2. 通过 CLI 初始化本地钱包，或配置静态模式的环境变量
-3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式——强烈推荐）
+2. 已用 CLI 配置好钱包——推荐 `wallet_cli` 钱包（参见 [快速开始](../QuickStart.md)）——或设置了环境变量回退
+3. 已在所用测试网上为钱包充值（TRON 地址至少收到过一次 TRX 才会被激活）
 
-:::danger 真金白银操作请勿使用静态模式（`AGENT_WALLET_PRIVATE_KEY`）
-静态模式将你的私钥以明文存储在环境变量中——这恰恰是 Agent-wallet `local_secure` 模式旨在防范的风险。请仅在完全隔离的离线测试环境中使用一次性测试私钥。主网操作请永远使用 `AGENT_WALLET_PASSWORD` 配合本地 Agent-wallet。
+:::danger 真金白银操作请勿使用环境变量回退（`AGENT_WALLET_PRIVATE_KEY`）或 `raw_secret`
+这两种方式都以明文保存私钥。请仅在完全隔离的测试环境中配合一次性私钥使用。主网操作请使用 `wallet_cli`（或 `privy`）钱包。
 :::
 
 ---
@@ -37,7 +34,7 @@ Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页
 
 **工作原理**：
 
-TRON 交易不能由客户端直接从零构建。流程必须从调用 TronGrid 的 `createtransaction` 接口开始——该接口返回一个包含 `txID` 和 `raw_data` 的未签名交易对象，由网络节点生成。然后把这个对象传给 Agent-wallet 进行本地签名——签名过程完全离线，私钥不会离开本机。最后，把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口，发布到链上。
+TRON 交易不能由客户端直接从零构建。流程必须从调用 TronGrid 的 `createtransaction` 接口开始——该接口返回一个包含 `txID` 和 `raw_data` 的未签名交易对象，由网络节点生成。然后把这个对象传给 Agent-wallet 签名——`raw_secret` 在进程内签名，`wallet_cli` 委托给本机的 wallet-cli 子进程，私钥都不会离开本机。最后，把签名后的交易提交给 TronGrid 的 `broadcasttransaction` 接口，发布到链上。
 
 <ThemedImage
   alt="TRON 转账：TronGrid 构建 → Agent-wallet 签名 → TronGrid 广播"
@@ -51,44 +48,12 @@ Agent-wallet 只参与中间的签名步骤，不需要 RPC 连接，也不感
 
 ### 安装依赖
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```bash
 npm install @bankofai/agent-wallet axios
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-本示例使用 `aiohttp`（第三方 HTTP 库）和 `asyncio`（Python 标准库，无需安装）：
-
-```bash
-pip install aiohttp
-```
-
-:::caution 如果出现标准库模块缺失的报错
-如果 `asyncio` 等标准库模块导入失败，通常是因为 pyenv 从源码编译 Python 时缺少系统依赖。先安装以下包，再重新运行 `pyenv install 3.11`：
-
-```bash
-# CentOS / RHEL / Amazon Linux
-sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel
-
-# Ubuntu / Debian
-sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev
-```
-:::
-
-</TabItem>
-</Tabs>
-
-
-
 ### 完整代码
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```typescript
 import { resolveWalletProvider } from "@bankofai/agent-wallet";
 import axios from "axios";
@@ -101,7 +66,7 @@ async function transferTRX(
   amountSun: number // 1 TRX = 1_000_000 SUN
 ) {
   // 第一步：初始化 Agent-wallet
-  const provider = resolveWalletProvider({ network: "tron:nile" });
+  const provider = resolveWalletProvider({ network: "tron:3448148188" }); // Nile
   const wallet = await provider.getActiveWallet();
 
   // 确保 fromAddress 与钱包地址一致——不匹配会导致 TronGrid 报错
@@ -127,13 +92,12 @@ async function transferTRX(
 
   console.log("未签名 txID：", unsignedTx.txID);
 
-  // 第三步：用 Agent-wallet 本地签名
-  let signedTx: Record<string, unknown>;
-  try {
-    signedTx = JSON.parse(await wallet.signTransaction(unsignedTx));
-  } catch (e) {
-    throw new Error(`signTransaction 返回了无效的 JSON: ${e}`);
+  // 第三步：用 Agent-wallet 签名——返回带类型的结果
+  const signed = await wallet.signTransaction(unsignedTx);
+  if (signed.family !== "tron") {
+    throw new Error("签名结果不是 TRON 交易——请检查钱包网络");
   }
+  const signedTx = signed.transaction;
   if (!signedTx.signature) {
     throw new Error("签名后的交易缺少 signature 字段");
   }
@@ -165,84 +129,10 @@ transferTRX(
 ).catch(console.error);
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-import json
-import aiohttp
-from agent_wallet import resolve_wallet_provider
-
-TRONGRID_API = "https://nile.trongrid.io"  # Nile 测试网；主网改为 https://api.trongrid.io
-
-async def transfer_trx(
-    from_address: str,
-    to_address: str,
-    amount_sun: int,  # 1 TRX = 1_000_000 SUN
-):
-    # 第一步：初始化 Agent-wallet
-    provider = resolve_wallet_provider(network="tron:nile")
-    wallet = await provider.get_active_wallet()
-
-    async with aiohttp.ClientSession() as session:
-        # 第二步：通过 TronGrid 构建未签名交易
-        async with session.post(
-            f"{TRONGRID_API}/wallet/createtransaction",
-            json={
-                "owner_address": from_address,
-                "to_address": to_address,
-                "amount": amount_sun,
-                "visible": True,
-            },
-        ) as resp:
-            unsigned_tx = await resp.json()
-
-        if "txID" not in unsigned_tx:
-            raise ValueError(f"构建交易失败：{unsigned_tx}")
-
-        print("未签名 txID：", unsigned_tx["txID"])
-
-        # 第三步：用 Agent-wallet 本地签名
-        raw_signed = await wallet.sign_transaction(unsigned_tx)
-        try:
-            signed_tx = json.loads(raw_signed)
-        except json.JSONDecodeError as e:
-            raise ValueError(f"signTransaction 返回了无效的 JSON: {e}") from e
-        if "signature" not in signed_tx:
-            raise ValueError("签名后的交易缺少 signature 字段")
-        print("已签名，signature：", signed_tx["signature"])
-
-        # 第四步：通过 TronGrid 广播
-        async with session.post(
-            f"{TRONGRID_API}/wallet/broadcasttransaction",
-            json=signed_tx,
-        ) as resp:
-            broadcast_result = await resp.json()
-
-        if broadcast_result.get("result"):
-            print("广播成功！txID：", signed_tx["txID"])
-        else:
-            print("广播失败：", broadcast_result)
-
-    return signed_tx["txID"]
-
-# 示例调用
-asyncio.run(
-    transfer_trx(
-        from_address="YOUR_TRON_ADDRESS",      # 替换成你的钱包地址
-        to_address="RECIPIENT_TRON_ADDRESS",       # 替换成收款方地址
-        amount_sun=1_000_000,                # 1 TRX
-    )
-)
-```
-
-</TabItem>
-</Tabs>
 
 :::caution 注意事项
 - 测试请使用 Nile 测试网，测试代币从 [Nile Faucet](https://nileex.io/join/getJoinPage) 领取。
-- 切换主网：把 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:mainnet`。
+- 切换主网：把 `TRONGRID_API` 改为 `https://api.trongrid.io`，`network` 改为 `tron:728126428`。3.x 会拒绝 `tron:nile` / `tron:mainnet` 这类别名。
 :::
 
 :::tip `visible: true` 与地址格式
@@ -262,7 +152,7 @@ asyncio.run(
 
 **工作原理**：
 
-EVM 交易需要调用方自己构建交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，没有集中式 API 帮你生成。未签名交易构建完成后，传给 Agent-wallet 进行本地签名，返回十六进制编码的已签名交易，最后通过 `sendRawTransaction` 广播。
+EVM 交易需要调用方自己构建交易对象。与 TRON 不同，EVM 交易的字段（`nonce`、`gas`、`chainId` 等）需要通过 RPC 查询当前链状态后手动填入，没有集中式 API 帮你生成。未签名交易构建完成后，传给 Agent-wallet 签名，返回 `{ family: "evm", rawTransaction }`，其中是十六进制编码的已签名交易，最后通过 `sendRawTransaction` 广播。
 
 <ThemedImage
   alt="EVM 转账：RPC 构建 → Agent-wallet 签名 → RPC 广播"
@@ -276,34 +166,18 @@ EVM 交易需要调用方自己构建交易对象。与 TRON 不同，EVM 交易
 
 ### 安装依赖
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```bash
 npm install @bankofai/agent-wallet ethers
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```bash
-pip install web3
-```
-
-</TabItem>
-</Tabs>
-
 ### 完整代码
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```typescript
 import { resolveWalletProvider } from "@bankofai/agent-wallet";
 import { ethers } from "ethers";
 
 // BSC 测试网
-const RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545";
+const RPC_URL = "https://bsc-testnet-rpc.publicnode.com";
 const CHAIN_ID = 97; // BSC 测试网；主网用 56
 
 async function transferBNB(
@@ -338,13 +212,16 @@ async function transferBNB(
 
   console.log("交易已构建，nonce：", nonce);
 
-  // 第四步：用 Agent-wallet 本地签名
-  const signedTxHex = await wallet.signTransaction(unsignedTx);
+  // 第四步：用 Agent-wallet 签名——返回带类型的结果
+  const signed = await wallet.signTransaction(unsignedTx);
+  if (signed.family !== "evm") {
+    throw new Error("签名结果不是 EVM 交易——请检查钱包网络");
+  }
   console.log("已签名");
 
   // 第五步：广播
-  // signTransaction 返回的十六进制不带 '0x' 前缀；ethers 需要加上
-  const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex);
+  // rawTransaction 是不带 '0x' 前缀的十六进制；ethers 需要加上
+  const txResponse = await rpcProvider.broadcastTransaction("0x" + signed.rawTransaction);
   console.log("广播成功！txHash：", txResponse.hash);
 
   // 等待确认（可选 — 添加超时以防止无限阻塞）
@@ -365,82 +242,6 @@ transferBNB(
 ).catch(console.error);
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-from agent_wallet import resolve_wallet_provider
-from eth_utils import to_checksum_address
-from web3 import AsyncWeb3
-
-# BSC 测试网
-RPC_URL = "https://data-seed-prebsc-1-s1.binance.org:8545"
-CHAIN_ID = 97  # BSC 测试网；主网用 56
-
-async def transfer_bnb(to_address: str, amount_ether: str):
-    # 第一步：初始化 Agent-wallet
-    provider = resolve_wallet_provider(network=f"eip155:{CHAIN_ID}")
-    wallet = await provider.get_active_wallet()
-    from_address = await wallet.get_address()
-
-    # 第二步：通过 RPC 查询 nonce 和 gas 信息
-    w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(RPC_URL))
-    nonce = await w3.eth.get_transaction_count(from_address, "latest")
-    fee_data = await w3.eth.fee_history(1, "latest", [50])
-    base_fee = fee_data["baseFeePerGas"][-1]
-    priority_fee = await w3.eth.max_priority_fee
-
-    # 第三步：构建未签名交易
-    unsigned_tx = {
-        # eth-account 不接受非 checksum 格式的地址
-        "to": to_checksum_address(to_address),
-        "value": w3.to_wei(amount_ether, "ether"),
-        "gas": 21000,
-        "maxFeePerGas": base_fee + priority_fee,
-        "maxPriorityFeePerGas": priority_fee,
-        "nonce": nonce,
-        "chainId": CHAIN_ID,
-        "type": 2,  # EIP-1559
-    }
-
-    print("交易已构建，nonce：", nonce)
-
-    # 第四步：用 Agent-wallet 本地签名
-    signed_tx_hex = await wallet.sign_transaction(unsigned_tx)
-    print("已签名")
-
-    # 第五步：广播
-    raw = signed_tx_hex[2:] if signed_tx_hex.startswith("0x") else signed_tx_hex
-    tx_hash = await w3.eth.send_raw_transaction(bytes.fromhex(raw))
-    print("广播成功！txHash：", tx_hash.hex())
-
-    # 可选：等待确认
-    # 注意：此调用会阻塞事件循环最多 `timeout` 秒。
-    # 生产环境的 AI Agent 建议在后台任务中执行，
-    # 或使用 asyncio.wait_for() 配合更短的超时和重试逻辑。
-    try:
-        receipt = await asyncio.wait_for(
-            w3.eth.wait_for_transaction_receipt(tx_hash),
-            timeout=120
-        )
-        print("已在区块中确认：", receipt["blockNumber"])
-    except asyncio.TimeoutError:
-        print("等待确认超时——交易可能仍会被确认。txHash：", tx_hash.hex())
-
-    return tx_hash.hex()
-
-# 示例调用
-asyncio.run(
-    transfer_bnb(
-        to_address="0xYOUR_RECIPIENT_ADDRESS",  # 替换成收款方地址
-        amount_ether="0.001",
-    )
-)
-```
-
-</TabItem>
-</Tabs>
 
 :::caution 注意事项
 - 测试请使用 BSC 测试网（chainId=97），测试代币从 [BSC Faucet](https://testnet.binance.org/faucet-smart) 领取。
@@ -455,30 +256,27 @@ asyncio.run(
 
 **工作原理**：
 
-x402 支付不是直接发一笔转账，而是"先签名、验证后放行"的模型。代理对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，把得到的签名随请求一起发给服务器作为支付凭证。服务器验证签名有效后才返回内容。代理不需要等待链上确认——延迟极低。
+x402 支付不是直接发一笔转账，而是"先签名、验证后放行"的模型。代理对一个 `TransferWithAuthorization` 结构（EIP-712 格式）进行签名，把得到的签名随请求一起发给服务器作为支付凭证。服务器验证签名后，通过 facilitator 完成结算，结算成功才返回内容；结算失败则返回 `402`。Agent-wallet 只负责本地签名，自己不会广播任何交易。
 
 :::note 该签哪个结构
 本节签的是 EIP-3009 的 `TransferWithAuthorization`——Base USDC 在 x402 `exact` 方案下使用的授权结构。它和仓库自带 x402 示例（`bsc-x402-sign-typed-data.ts`、`tron-x402-sign-typed-data.ts`）里的 `PaymentPermit` 结构并不相同：后者的域名是 `x402PaymentPermit`，主类型为 `PaymentPermitDetails`，字段是 `{ buyer, amount, nonce }`。以服务端在 `402` 响应里声明的结构为准。采用哪种授权方式取决于代币而非链：TRON 的 USDT/USDD 与 BSC 的 USDT/USDC 走 Permit2，而 Base 官方 USDC 这类 EIP-3009 代币走 `transferWithAuthorization`——详见[网络与代币支持](../../x402/core-concepts/network-and-token-support.md)。
 :::
 
 <ThemedImage
-  alt="x402 PaymentPermit：先签名，验证通过再放行"
+  alt="x402 支付授权：先签名，验证通过再放行"
   sources={{
     light: '/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg',
     dark: '/img/diagrams/agent-wallet-x402-permit-flow.zh.svg',
   }}
 />
 
-PaymentPermit 数据由 x402 SDK 根据服务器返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面的示例展示了底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+授权数据由 x402 SDK 根据服务器返回的支付参数自动构建，Agent-wallet 只负责最后的签名步骤。下面的示例展示了底层签名逻辑，适用于需要自定义集成或绕过 x402 SDK 的场景。
 
 ```typescript
 import { resolveWalletProvider } from "@bankofai/agent-wallet";
-import type { Eip712Capable } from "@bankofai/agent-wallet";
+import type { Eip712Capable, Wallet } from "@bankofai/agent-wallet";
 
-async function signPaymentPermit(authorization: {
+async function signTransferWithAuthorization(authorization: {
   from: string;
   to: string;
   value: string;
@@ -487,6 +285,7 @@ async function signPaymentPermit(authorization: {
   nonce: string;
 }) {
   // 初始化 Agent-wallet（EVM 钱包，network 必须与 x402 支付网络匹配）
+  // 使用 wallet_cli 钱包时，Base 需要 wallet-cli 4.14.0 及以上（更早的版本会报 network_mismatch）
   const provider = resolveWalletProvider({ network: "eip155:8453" }); // Base 主网
   const wallet = await provider.getActiveWallet();
 
@@ -519,67 +318,22 @@ async function signPaymentPermit(authorization: {
   };
 
   // signTypedData 定义在 Eip712Capable 上，而不在基础的 Wallet 接口上
-  const signer = wallet as unknown as Eip712Capable;
+  if (!("signTypedData" in wallet)) {
+    throw new Error("该钱包不支持结构化数据签名");
+  }
+  const signer = wallet as Wallet & Eip712Capable;
 
-  // 用 Agent-wallet 本地签名
+  // 用 Agent-wallet 签名（返回不带 0x 前缀的 hex 签名）
   const signature = await signer.signTypedData(typedData);
-  console.log("PaymentPermit 签名：", signature);
+  console.log("TransferWithAuthorization 签名：", signature);
 
   return signature;
 }
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from agent_wallet import resolve_wallet_provider
-
-async def sign_payment_permit(authorization: dict) -> str:
-    # 初始化 Agent-wallet（EVM 钱包，network 必须与 x402 支付网络匹配）
-    provider = resolve_wallet_provider(network="eip155:8453")  # Base 主网
-    wallet = await provider.get_active_wallet()
-
-    # 构建 EIP-712 结构化数据（与 x402 协议规范对齐）
-    typed_data = {
-        "types": {
-            "EIP712Domain": [
-                {"name": "name", "type": "string"},
-                {"name": "version", "type": "string"},
-                {"name": "chainId", "type": "uint256"},
-                {"name": "verifyingContract", "type": "address"},
-            ],
-            "TransferWithAuthorization": [
-                {"name": "from", "type": "address"},
-                {"name": "to", "type": "address"},
-                {"name": "value", "type": "uint256"},
-                {"name": "validAfter", "type": "uint256"},
-                {"name": "validBefore", "type": "uint256"},
-                {"name": "nonce", "type": "bytes32"},
-            ],
-        },
-        "primaryType": "TransferWithAuthorization",
-        "domain": {
-            "name": "USD Coin",
-            "version": "2",
-            "chainId": 8453,
-            "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  # Base USDC
-        },
-        "message": authorization,
-    }
-
-    # 用 Agent-wallet 本地签名
-    signature = await wallet.sign_typed_data(typed_data)
-    print("PaymentPermit 签名：", signature)
-
-    return signature
-```
-
-</TabItem>
-</Tabs>
 
 :::tip
-x402 SDK 会自动构建 PaymentPermit 数据并调用签名接口，通常不需要手写这段代码。上面的示例展示了底层签名逻辑，适用于需要自定义集成的场景。详见 [x402 协议文档](../../x402/index.md)。
+x402 SDK 会自动构建授权数据并调用签名接口，通常不需要手写这段代码。上面的示例展示了底层签名逻辑，适用于需要自定义集成的场景。详见 [x402 协议文档](../../x402/index.md)。
 :::
 
 ---
@@ -590,15 +344,22 @@ Agent-wallet 仓库中还包含更多可直接运行的进阶示例：
 
 | 示例 | 说明 |
 | :--- | :--- |
+| `tron-sign-and-broadcast` | 通过 TronGrid 构建 TRX 转账、签名并广播 |
+| `bsc-sign-and-broadcast` | 构建、签名并广播 BSC 交易 |
+| `wallet-cli-sign` | 通过已配置的 `wallet_cli` 钱包签名 |
 | `dual-sign-typed-data-from-private-key` | 用同一个私钥在 TRON 和 EVM 上签名 EIP-712 数据 |
 | `switch-active-wallet` | 在代码中切换多个钱包 |
-| `create-wallet-provider` | 不使用自动解析，直接实例化 Provider（仅 TypeScript） |
+| `create-wallet-provider` | 用 `resolveWalletProvider` 解析钱包 Provider |
 | `tron-x402-sign-typed-data` | 在 TRON 上签名 x402 PaymentPermit |
 | `bsc-x402-sign-typed-data` | 在 BSC 上签名 x402 PaymentPermit |
 | `verify-tron-privy-typed-data` | 验证 Privy TRON EIP-712 签名 |
 | `compare-sign-consistency` | 跨钱包签名一致性测试 |
 
-仓库当前提供 [TypeScript 示例](https://github.com/BofAI/agent-wallet/tree/main/packages/typescript/examples)。
+参见 [TypeScript 示例](https://github.com/BofAI/agent-wallet/tree/main/packages/typescript/examples)。
+
+:::tip 通过 wallet-cli 完成 TRON 转账
+使用 `wallet_cli` 钱包时，也可以让 wallet-cli 负责构建和广播 TRON 转账：`@bankofai/agent-wallet/integrations/wallet-cli` 中的 `signAndBroadcast` 会依次完成构建 → 签名 → 广播，并返回 `stage: "submitted"`；传入 `wait: true` 时还会轮询交易状态，直到确认、失败或超时。这些工具仅支持 TRON，主网（`tron:728126428`）需要显式传入 `confirmMainnet: true`。
+:::
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md
index 8cf6f54d..1acb7c11 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Guide.md
@@ -1,38 +1,32 @@
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # SDK 接入指南
 
-CLI 已经跑通了，能从命令行签名。现在你想把签名能力放进代码里——MCP Server、自动化脚本、AI 代理工作流。
+你已经用 CLI 在命令行里签过名了。现在你想在自己的代码里调用签名——比如 MCP Server、自动化脚本、AI 代理工作流。
 
-本页教你怎么做。完成后，你就能用几行 TypeScript 或 Python 初始化钱包 Provider、获取活跃钱包，并对消息、交易、EIP-712 结构化数据进行签名。
+这一页就教你怎么做。读完后，你就能用 `@bankofai/agent-wallet` 3.x TypeScript SDK 解析钱包、读取地址，并签名交易和 EIP-712 / TIP-712 结构化数据。
 
-:::tip 刚刚入门？
-如果还没创建过钱包，先去 [快速上手](../QuickStart.md) 走一遍（不到一分钟）。SDK 读取的就是 CLI 创建的那个钱包——不需要重复配置任何东西。
+:::tip 第一次来？
+如果还没有创建钱包，先去 [快速开始](../QuickStart.md)。SDK 读取的就是 CLI 写入的同一份 `wallets_config.json`——不用重复配置。
 :::
 
-文档提供 TypeScript 和 Python 两个版本的安装说明和代码示例，点击标签页切换。
+:::note Python SDK
+Agent-wallet 3.x 只提供 TypeScript。PyPI 上的 Python 包 `bankofai-agent-wallet` 停留在 2.4.0，沿用 2.x 模型（`local_secure`、主密码、`sign_message`），不支持 `wallet_cli` 类型，也不返回本文介绍的 3.x 签名结果。
+:::
 
 ---
 
 ## 第一步：安装
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 **检查 Node.js 版本**
 
-需要 Node.js ≥ 18——这是该包 `engines` 声明的下限。建议安装当前的 LTS 版本：Node 18 已于 2025 年 4 月、Node 20 已于 2026 年 4 月停止维护。查看当前版本：
+请使用 Node.js `^22.23.4 || ^24.22.1 || >=26.12.1`，即 2026 年 10 月的安全更新版本。这是源码 `main` 分支声明的 `engines` 范围；npm 上已发布的 `3.0.0` 仍声明 `>=18.0.0`，但 wallet-cli `4.15.1` 本身就声明了同一范围。在 `main` 上，当 `wallet_cli` 钱包类型用当前 Node 通过 JavaScript 入口启动 wallet-cli 时（本地安装的包，或指向 `.js` 文件的 `AGENT_WALLET_WALLET_CLI_PATH`），会先检查同一范围；从 `PATH` 找到的 `wallet-cli` 可执行文件则不做此检查。（已发布的 `3.0.0` 中，该入口检查只要求 Node.js 20+。）检查当前版本：
 
 ```bash
 node -v
 ```
 
-输出 `v18.0.0` 或更高，可以直接安装；否则按下面的方法升级。
-
 :::tip 安装 / 升级 Node.js
 
-推荐用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本：
+推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理 Node.js 版本：
 
 ```bash
 # 安装 nvm（已安装可跳过）
@@ -56,279 +50,115 @@ nvm use --lts
 npm install @bankofai/agent-wallet
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-**检查 Python 版本**
-
-需要 Python ≥ 3.11（SDK 使用了 3.11+ 的特性）：
-
-```bash
-python3 --version
-```
-
-输出 `3.11.x` 或更高，可以直接安装；否则按下面的方法升级。
-
-:::tip 安装 / 升级 Python
-
-推荐用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本：
-
-```bash
-# 第一步：安装 pyenv
-curl https://pyenv.run | bash
-```
-
-安装后需要手动添加到 shell 配置：
-
-```bash
-# 将以下三行追加到 ~/.bashrc（zsh 用户改为 ~/.zshrc）
-echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
-echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
-echo 'eval "$(pyenv init -)"' >> ~/.bashrc
-
-# 重新加载配置，使当前终端立即生效
-source ~/.bashrc
-```
-
-使用 pyenv 之前，先安装系统依赖，**跳过这步会导致 `_ctypes`、`ssl` 等模块缺失，进而影响 `asyncio` 等标准库的导入**：
-
-```bash
-# CentOS / RHEL / Amazon Linux / Fedora
-sudo yum install -y libffi-devel bzip2-devel openssl-devel readline-devel sqlite-devel xz-devel
-
-# Ubuntu / Debian
-sudo apt-get install -y libffi-dev libbz2-dev libssl-dev libreadline-dev libsqlite3-dev liblzma-dev
-```
-
-然后编译 Python：
-
-```bash
-pyenv install 3.11
-pyenv global 3.11
-```
-
-也可以从 [python.org](https://www.python.org/downloads/) 下载安装包，选择 **3.11 或更高版本**。
-
-:::
-
-**安装 SDK**
-
-```bash
-pip install bankofai-agent-wallet
-```
-
-两条链的依赖（EVM 的 `eth-account` 与 TRON 的 `tronpy`）都会随包一并安装——不存在按链拆分的 extra。
-
-验证安装：
+该包同时提供 ESM 和 CommonJS 构建。只有使用 `wallet_cli` 钱包时，才需要额外安装可选的 peer 依赖：
 
 ```bash
-python3 -c "import agent_wallet; print('Installation successful')"
+npm install '@tron-walletcli/wallet-cli@^4.13.0'
 ```
 
-</TabItem>
-</Tabs>
-
 ---
 
-## 第二步：配置模式
-
-调用 SDK 之前，需要通过环境变量告诉 Agent-wallet 去哪里找密钥。
-
-不要被复杂的概念吓到，`resolveWalletProvider()` 极其聪明，它会自动检测可用的凭证来源——环境变量、已保存的 runtime-secrets 密码，或已存在的本地钱包配置——并决定工作模式，代码里不需要写任何 `if/else` 判断逻辑。
-
-它支持以下两种模式：
-
-### 🛡️ 核心用法：本地 Agent-wallet 模式（强烈推荐）
-
-如果你刚才已经跟着 [快速上手](../QuickStart.md) 走过一遍，那你的私钥早就安全地躺在本地的隐藏文件里了。
-
-**在这个模式下，你根本不需要（也不应该）接触明文私钥。** 你只需要告诉 SDK 你的"开箱密码"即可。
-
-```bash
-export AGENT_WALLET_PASSWORD='Abc12345!'
-# 可选：如果你之前改过钱包存储目录，告诉 SDK 在哪找
-export AGENT_WALLET_DIR="$HOME/.agent-wallet"
-```
+## 第二步：选择私钥来源
 
-:::caution 密码含特殊字符时，务必用单引号
-自动生成的强密码可能含有 `$`、`!` 等 shell 特殊字符，务必用单引号，避免 shell 展开导致密码被破坏：
+`resolveWalletProvider()` / `resolveWallet()` 会替你决定来源——代码里不需要写 `if/else`：
 
-```bash
-# ✅ 正确：单引号，密码原样传入
-export AGENT_WALLET_PASSWORD='P@ss$w0rd!'
+1. **钱包配置（推荐）。** 如果钱包目录（`dir` 参数 → `AGENT_WALLET_DIR` → `~/.agent-wallet`）中的 `wallets_config.json` 至少包含一个钱包，就使用 `ConfigWalletProvider`。它支持 CLI 能创建的所有钱包类型：`wallet_cli`、`privy` 和 `raw_secret`。
+2. **环境变量回退。** 否则使用 `EnvWalletProvider`，从环境变量读取私钥。
 
-# ❌ 错误：双引号，$ 被 shell 展开
-export AGENT_WALLET_PASSWORD="P@ss$w0rd!"
-```
-:::
+不需要导出任何密码：`wallet_cli` 的凭据来自钱包配置中保存的 exec 脚本或值，`privy` 的凭据同样保存在那里。
 
-### ⚠️ 备用方案：静态注入模式（仅限测试环境）
+### 环境变量回退 {#environment-variable-fallback}
 
-如果你是在一个"用完即毁"的临时环境（比如 GitHub Actions 的自动化测试流水线），或者你手里只有别人的一个临时测试私钥，你可以跳过本地 Agent-wallet，直接把私钥喂给 SDK。
+在一次性环境中（例如使用一次性测试私钥的 CI 流水线），你可以跳过钱包配置，直接把私钥交给 SDK：
 
 ```bash
-export AGENT_WALLET_PRIVATE_KEY='your-private-key-in-hex'
-# 或
+export AGENT_WALLET_PRIVATE_KEY='你的十六进制私钥'
+# 或者
 export AGENT_WALLET_MNEMONIC='word1 word2 word3 ...'
 ```
 
-:::danger 极度危险：违背核心安全原则！
-静态模式直接读取明文私钥，这意味着你放弃了 Agent-wallet 引以为傲的加密保护，退回了简介中所说的"单点白给"的老路。请仅在完全隔离的测试环境、或一次性 CI/CD 脚本中使用此模式！主网真金白银操作，请永远使用本地 Agent-wallet 模式。
+:::danger 明文私钥
+这种方式以明文从环境变量读取私钥。只能在完全隔离的测试环境中配合一次性私钥使用。同时设置两个变量会报错。
 :::
 
-:::tip 环境变量冲突怎么办？
-如果环境变量里同时存在密码和私钥，SDK 会优先保护安全：强制使用 `AGENT_WALLET_PASSWORD` 进入本地 Agent-wallet 模式，忽略明文私钥。
-:::
-
-### 环境变量速查
+### 环境变量一览
 
-| 变量名 | 用途 | 模式 | 是否必填 |
-| :--- | :--- | :--- | :--- |
-| `AGENT_WALLET_PASSWORD` | 主密码，解锁本地隐藏文件 | 🛡️ 本地 Agent-wallet | 核心必填 |
-| `AGENT_WALLET_DIR` | 密钥目录（默认 `~/.agent-wallet`） | 🛡️ 本地 Agent-wallet | 可选 |
-| `AGENT_WALLET_PRIVATE_KEY` | 明文私钥（十六进制） | ⚠️ 静态注入 | 二选一（与助记词） |
-| `AGENT_WALLET_MNEMONIC` | 明文助记词短语 | ⚠️ 静态注入 | 二选一（与私钥） |
-| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | BIP-44 派生索引（默认 `0`） | ⚠️ 静态注入 | 可选 |
+| 变量 | 用途 | 使用方 |
+| :--- | :--- | :--- |
+| `AGENT_WALLET_DIR` | 钱包目录（默认 `~/.agent-wallet`） | 钱包配置 |
+| `AGENT_WALLET_WALLET_CLI_PATH` | wallet-cli 不在 `PATH` 中时，指定其可执行文件或 JavaScript 入口 | `wallet_cli` 钱包 |
+| `AGENT_WALLET_PRIVATE_KEY` | 明文私钥（hex） | 环境变量回退——二选一 |
+| `AGENT_WALLET_MNEMONIC` | 明文助记词 | 环境变量回退——二选一 |
+| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | 助记词账户索引（默认 `0`） | 环境变量回退 |
 
-:::note 遗留变量名
-SDK 仍然接受早期的 `TRON_PRIVATE_KEY`、`TRON_MNEMONIC`、`TRON_ACCOUNT_INDEX`，它们分别对应 `AGENT_WALLET_PRIVATE_KEY`、`AGENT_WALLET_MNEMONIC`、`AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`。虽然名字里带 TRON，但在 EVM 网络上同样生效。新项目建议统一用 `AGENT_WALLET_*` 这套名字。
-:::
+只有当钱包配置中没有任何钱包时，才会读取环境变量回退。2.x 的 `TRON_PRIVATE_KEY`、`TRON_MNEMONIC`、`TRON_ACCOUNT_INDEX` 和 `AGENT_WALLET_PASSWORD` 已不再读取。
 
 ---
 
 ## 使用示例
 
-### 初始化钱包 Provider
-
-所有操作的起点是 `resolveWalletProvider()`。它会选择对应模式并返回钱包 Provider，调用 `getActiveWallet()` 获取活跃钱包。模式选择并不只看环境变量：保存在 runtime-secrets 文件里的密码同样算数，而且只要钱包目录里已有任何钱包，即使一个环境变量都没设，也会走本地模式。
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
-```typescript
-import { resolveWalletProvider } from "@bankofai/agent-wallet";
-
-const provider = resolveWalletProvider({ network: "tron:nile" });
-const wallet = await provider.getActiveWallet();
-
-// 查看当前钱包地址
-const address = await wallet.getAddress();
-console.log("Address:", address);
-```
+### 网络
 
-</TabItem>
-<TabItem value="python" label="Python">
+所有 `network` 参数都只接受精确的规范 CAIP-2 字符串：`eip155:<chainId>`（如 `eip155:1`、`eip155:56`、`eip155:97`）或 `tron:<chainId>`（`tron:728126428` 主网、`tron:3448148188` Nile、`tron:2494104990` Shasta）。`tron:nile`、`tron:mainnet` 等别名、裸 `tron` / `eip155`、十六进制 TRON id，以及大小写或空白变体都会抛出 `NetworkError`。
 
-```python
-import asyncio
-from agent_wallet import resolve_wallet_provider
+`raw_secret`、环境变量回退和 `wallet_cli` 钱包**必须**提供网络——它决定使用 EVM 还是 TRON 签名器（对于助记词，还决定派生路径 `m/44'/60'/0'/0/{index}` 或 `m/44'/195'/0'/0/{index}`）。`privy` 钱包可以省略。
 
-provider = resolve_wallet_provider(network="tron:nile")
+`wallet_cli` 钱包还要求该网络是 wallet-cli 自身认识的网络——即它的内置网络（`eip155:1`、`eip155:11155111`、`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`（Base 自 wallet-cli 4.14.0 起才内置）及三个 TRON 网络），或在 wallet-cli 自己的配置中添加的网络——否则签名会以 `network_mismatch` 失败。`raw_secret` 和 `privy` 钱包没有这一限制。
 
-async def main():
-    wallet = await provider.get_active_wallet()
+### 解析钱包
 
-    # 查看当前钱包地址
-    address = await wallet.get_address()
-    print("Address:", address)
-
-asyncio.run(main())
-```
-
-</TabItem>
-</Tabs>
-
-拿到 `wallet` 之后，就可以调用下面三种签名方法。`signMessage` 与 `signTypedData` 返回十六进制签名字符串（不带 `0x` 前缀）；`signTransaction` 返回完整的已签名交易——EVM 上是不带 `0x` 的十六进制序列化结果，TRON 上是 JSON 字符串。`signTypedData` 在两种语言里都声明在独立的 `Eip712Capable` 接口上，而不在 `Wallet` 上。TypeScript 会强制这一点，调用前需先做类型转换；Python 只在静态类型检查时体现——运行时可以直接调用，仓库自己让类型检查通过的写法是加一层 `isinstance(wallet, Eip712Capable)` 判断。
-
-#### 快捷方式：`resolveWallet()`
-
-如果你只需要 wallet、完全用不到 provider 本身，`resolveWallet()` 可以把两步合成一步。它接受同样的 `network` 与 `dir` 选项，另外还支持可选的 `walletId`，用于指定某个钱包而不是当前激活的钱包。`walletId` 只在本地钱包配置模式下生效——静态注入模式下它会被忽略，返回的仍是环境变量对应的钱包。
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+最短的路径是 `resolveWallet()`。它接受 `network`、`dir`，以及可选的 `walletId`，用于指定某个已配置的钱包而不是激活钱包（在环境变量回退模式下会被忽略）：
 
 ```typescript
 import { resolveWallet } from "@bankofai/agent-wallet";
 
-const wallet = await resolveWallet({ network: "tron:nile" });
-
-// 也可以指定某个钱包，而不用当前激活的
-const other = await resolveWallet({ network: "tron:nile", walletId: "trading" });
-```
-
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-from agent_wallet import resolve_wallet
-
-async def main():
-    wallet = await resolve_wallet(network="tron:nile")
+const wallet = await resolveWallet({ network: "tron:3448148188" });
+console.log("Address:", await wallet.getAddress());
 
-    # 也可以指定某个钱包，而不用当前激活的
-    other = await resolve_wallet(network="tron:nile", wallet_id="trading")
-
-asyncio.run(main())
+// 或者指定某个钱包，而不是激活钱包
+const other = await resolveWallet({ network: "eip155:56", walletId: "trading" });
 ```
 
-</TabItem>
-</Tabs>
-
-两个函数都还接受 `dir`，用于指向 `~/.agent-wallet` 之外的钱包目录，等价于在代码里设置 `AGENT_WALLET_DIR` 环境变量。
-
-:::note Privy 授权密钥
-每个签名方法都有一个可选的第二参数 `SignOptions`。它只有一个字段，会作为 `privy-authorization-signature` 请求头转发——当 Privy 钱包启用了授权密钥策略时必须提供。本地钱包会忽略该字段。该字段在 TypeScript 里叫 `authorizationSignature`，在 Python 里叫 `authorization_signature`：
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+需要 provider 本身时，使用 `resolveWalletProvider()`：
 
 ```typescript
-await wallet.signMessage(message, { authorizationSignature });
-```
-
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from agent_wallet import SignOptions
+import { resolveWalletProvider } from "@bankofai/agent-wallet";
 
-await wallet.sign_message(message, SignOptions(authorization_signature=signature))
+const provider = resolveWalletProvider({ network: "tron:3448148188" });
+const wallet = await provider.getActiveWallet();     // 或 getActiveWallet("eip155:56")
 ```
 
-</TabItem>
-</Tabs>
-:::
-
-### 签名消息
+两个函数都接受 `dir`，它相当于在代码里设置 `AGENT_WALLET_DIR`。
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+### `Wallet` 接口
 
 ```typescript
-const sig = await wallet.signMessage(new TextEncoder().encode("Hello"));
-console.log("Signature:", sig);
-```
+interface Wallet {
+  getAddress(): Promise<string>;
+  signTransaction(payload: TransactionPayload, options?: SignOptions): Promise<SignedTransactionArtifact>;
+}
 
-</TabItem>
-<TabItem value="python" label="Python">
+interface Eip712Capable {
+  signTypedData(data: Record<string, unknown>, options?: SignOptions): Promise<string>;
+}
 
-```python
-sig = await wallet.sign_message(b"Hello")
-print("Signature:", sig)
+type SignOptions = {
+  authorizationSignature?: string; // 作为 privy-authorization-signature 转发给 Privy
+  signal?: AbortSignal;            // 取消 wallet-cli 签名子进程
+};
 ```
 
-</TabItem>
-</Tabs>
+- `signTransaction` 返回带类型的结果：`{ family: "evm", rawTransaction }`（hex，**不带** `0x`）或 `{ family: "tron", transaction }`（附带 `txID` 和 `signature` 的交易对象）。请根据 `family` 分支处理，不要去解析字符串。
+- `signTypedData` 返回**不带** `0x` 前缀的 hex 签名。它定义在单独的 `Eip712Capable` 接口上；调用前先检查（三种内置钱包类型都实现了它）。
+- 3.x 中没有 `signMessage` 或 `signRaw`。
 
 ### 签名交易
 
-Agent-wallet 只负责签名，不构建也不广播。你需要先通过 RPC（比如 TronGrid、Infura）构建未签名的交易，再传给 SDK 签名。
+Agent-wallet 只负责签名，不负责构建和广播交易。你需要先通过 RPC（如 TronGrid、EVM 节点）构建未签名交易，再交给 SDK 签名。
 
 #### TRON 交易
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+payload 必须包含 `raw_data_hex`（TronGrid 会返回）。对 `raw_secret`、`privy` 和环境变量钱包，缺少 `txID` 时会根据 `raw_data_hex` 计算。`wallet_cli` 钱包则需要完整交易——`raw_data`、`raw_data_hex`，以及等于 `raw_data_hex` 的 SHA-256 的 `txID`——否则 wallet-cli 会拒绝签名。
 
 ```typescript
 // 1. 调用方通过 TronGrid 构建未签名交易
@@ -338,41 +168,18 @@ const unsignedTx = {
   raw_data: { /* TronGrid 返回的原始数据 */ },
 };
 
-// 2. SDK 本地签名（无网络调用）
-const signedTxJson = await wallet.signTransaction(unsignedTx);
-console.log("Signed transaction:", signedTxJson);
+// 2. SDK 签名（raw_secret 在进程内签名；wallet_cli 委托给 wallet-cli）
+const signed = await wallet.signTransaction(unsignedTx);
+if (signed.family !== "tron") throw new Error("expected a TRON wallet");
+console.log("Signed transaction:", signed.transaction);
 
-// 3. 调用方负责广播
+// 3. 调用方广播 signed.transaction
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-# 1. 调用方通过 TronGrid 构建未签名交易
-unsigned_tx = {
-    "txID": "abc123...",
-    "raw_data_hex": "0a02...",
-    "raw_data": {},  # TronGrid 返回的原始数据
-}
-
-# 2. SDK 本地签名（无网络调用）
-signed_tx_json = await wallet.sign_transaction(unsigned_tx)
-print("Signed transaction:", signed_tx_json)
-
-# 3. 调用方负责广播
-```
-
-</TabItem>
-</Tabs>
-
 #### EVM 交易（BSC、Ethereum 等）
 
-<Tabs>
-<TabItem value="ts" label="TypeScript">
-
 ```typescript
-const signedTxHex = await wallet.signTransaction({
+const signed = await wallet.signTransaction({
   type: "eip1559",
   to: "0xRecipient...",
   value: 0n,
@@ -382,45 +189,26 @@ const signedTxHex = await wallet.signTransaction({
   nonce: 0,
   chainId: 56,
 });
-console.log("Signed tx:", signedTxHex);
-```
-
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from eth_utils import to_checksum_address
-
-signed_tx_hex = await wallet.sign_transaction({
-    "type": 2,  # 可省略——eth-account 真正要求的是两个 fee 字段齐全，或改用 legacy 的 gasPrice
-    "to": to_checksum_address("0xRecipient..."),
-    "value": 0,
-    "gas": 21000,
-    "maxFeePerGas": 20000000000,
-    "maxPriorityFeePerGas": 1000000000,
-    "nonce": 0,
-    "chainId": 56,
-})
-print("Signed tx:", signed_tx_hex)
+if (signed.family !== "evm") throw new Error("expected an EVM wallet");
+console.log("Signed tx:", "0x" + signed.rawTransaction);
 ```
 
-</TabItem>
-</Tabs>
+`wallet_cli` 钱包还会拒绝与钱包网络不一致的 `chainId`、已签名的 payload，以及 EIP-4844 / EIP-7702 交易。
 
 ### 签名 EIP-712 结构化数据
 
-用于 x402 协议 PaymentPermit 签名、Permit2 等场景：
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+用于 x402 支付授权、Permit2 等场景：
 
 ```typescript
-import type { Eip712Capable } from "@bankofai/agent-wallet";
+import type { Eip712Capable, Wallet } from "@bankofai/agent-wallet";
+
+function supportsTypedData(wallet: Wallet): wallet is Wallet & Eip712Capable {
+  return "signTypedData" in wallet && typeof wallet.signTypedData === "function";
+}
 
-// signTypedData 定义在 Eip712Capable 上，而不在基础的 Wallet 接口上
-const signer = wallet as unknown as Eip712Capable;
+if (!supportsTypedData(wallet)) throw new Error("wallet cannot sign typed data");
 
-const sig = await signer.signTypedData({
+const sig = await wallet.signTypedData({
   types: {
     EIP712Domain: [
       { name: "name", type: "string" },
@@ -438,119 +226,60 @@ const sig = await signer.signTypedData({
 console.log("Signature:", sig);
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-sig = await wallet.sign_typed_data({
-    "types": {
-        "EIP712Domain": [
-            {"name": "name", "type": "string"},
-            {"name": "chainId", "type": "uint256"},
-        ],
-        "Transfer": [
-            {"name": "to", "type": "address"},
-            {"name": "amount", "type": "uint256"},
-        ],
-    },
-    "primaryType": "Transfer",
-    "domain": {"name": "MyDApp", "chainId": 1},
-    "message": {"to": "0x...", "amount": 1000000},
-})
-print("Signature:", sig)
-```
-
-</TabItem>
-</Tabs>
-
 ---
 
 ### 管理多个钱包
 
-需要在代码中管理多个钱包时，使用本地模式的 `resolveWalletProvider()`，Provider 会读取钱包配置并支持切换活跃钱包：
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+`ConfigWalletProvider` 用于读取和修改钱包配置。你可以从 `resolveWalletProvider()` 获得它（已配置钱包时），也可以直接用 `new ConfigWalletProvider(dir, { network })` 构造：
 
 ```typescript
 import { resolveWalletProvider, ConfigWalletProvider } from "@bankofai/agent-wallet";
 
-// 本地模式：需要设置 AGENT_WALLET_PASSWORD
-const provider = resolveWalletProvider({ network: "tron:nile" });
+const provider = resolveWalletProvider({ network: "tron:3448148188" });
 
 if (provider instanceof ConfigWalletProvider) {
-  // 列出所有钱包 — 返回 [walletId, config, isActive] 元组数组
-  const wallets = provider.listWallets();
-  for (const [id, config, isActive] of wallets) {
-    console.log(`${id} (${config.type})${isActive ? " ← 活跃" : ""}`);
+  // 列出所有钱包——返回 [walletId, config, isActive] 元组
+  for (const [id, config, isActive] of provider.listWallets()) {
+    console.log(`${id} (${config.type})${isActive ? " ← active" : ""}`);
   }
 
-  // 切换活跃钱包
+  // 切换激活钱包（写入 wallets_config.json）
   provider.setActive("my-evm-wallet");
+
+  // 或者不切换，直接在指定网络上使用某个钱包
+  const bsc = await provider.getWallet("my-evm-wallet", "eip155:56");
 }
 
-// 获取并使用
+// 未设置激活钱包时，会回退到第一个已配置的钱包
 const wallet = await provider.getActiveWallet();
-const sig = await wallet.signMessage(new TextEncoder().encode("Hello"));
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-import asyncio
-from agent_wallet import resolve_wallet_provider, ConfigWalletProvider
-
-# 需要设置 AGENT_WALLET_PASSWORD
-provider = resolve_wallet_provider(network="tron:nile")
-
-async def main():
-    if isinstance(provider, ConfigWalletProvider):
-        # 列出所有钱包 — 返回 [(wallet_id, config, is_active)] 元组列表
-        wallets = provider.list_wallets()
-        for wallet_id, config, is_active in wallets:
-            print(f"{wallet_id} ({config.type}){'  ← 活跃' if is_active else ''}")
-
-        # 切换活跃钱包
-        provider.set_active("my-evm-wallet")
-
-    # 获取并使用
-    wallet = await provider.get_active_wallet()
-    sig = await wallet.sign_message(b"Hello")
-    print("Signature:", sig)
-
-asyncio.run(main())
-```
-
-</TabItem>
-</Tabs>
-
 ---
 
 ### 错误处理
 
-签名操作失败时，SDK 会抛出特定的错误类型，建议在代码中显式捕获，避免运行时崩溃。
-
-<Tabs>
-<TabItem value="ts" label="TypeScript">
+SDK 的类型化错误继承自 `WalletError`。少数配置和输入错误会直接抛出普通 `Error`：找不到钱包来源（既没有已配置的钱包，也没有 `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`）、这两个环境变量同时设置、私钥格式错误，或 `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` 无效。捕获你能处理的具体类型：
 
 ```typescript
 import {
   WalletNotFoundError,
+  NetworkError,
   SigningError,
-  DecryptionError,
+  WalletCliNotFoundError,
+  WalletCliExecutionError,
 } from "@bankofai/agent-wallet";
 
 try {
   const wallet = await provider.getActiveWallet();
-  const sig = await wallet.signMessage(new TextEncoder().encode("Hello"));
-  console.log("Signature:", sig);
+  const signed = await wallet.signTransaction(unsignedTx);
 } catch (e) {
   if (e instanceof WalletNotFoundError) {
-    console.error("钱包不存在——检查是否设置了活跃钱包");
-  } else if (e instanceof DecryptionError) {
-    console.error("解密失败——检查主密码是否正确");
-  } else if (e instanceof SigningError) {
+    console.error("找不到钱包——请检查钱包 ID");
+  } else if (e instanceof NetworkError) {
+    console.error("网络无效或不匹配——请使用规范 CAIP-2，例如 tron:3448148188");
+  } else if (e instanceof WalletCliNotFoundError) {
+    console.error("未安装 wallet-cli，或不在 PATH 中");
+  } else if (e instanceof WalletCliExecutionError || e instanceof SigningError) {
     console.error("签名失败：", e.message);
   } else {
     throw e;
@@ -558,66 +287,52 @@ try {
 }
 ```
 
-</TabItem>
-<TabItem value="python" label="Python">
-
-```python
-from agent_wallet import WalletNotFoundError, SigningError, DecryptionError
-
-try:
-    wallet = await provider.get_active_wallet()
-    sig = await wallet.sign_message(b"Hello")
-    print("Signature:", sig)
-except WalletNotFoundError:
-    print("钱包不存在——检查是否设置了活跃钱包")
-except DecryptionError:
-    print("解密失败——检查主密码是否正确")
-except SigningError as e:
-    print(f"签名失败：{e}")
-```
-
-</TabItem>
-</Tabs>
-
-错误类型层级：
+错误类型层级（均从包根导出）：
 
 ```
 WalletError
-├── WalletNotFoundError        # 指定钱包不存在
-├── DecryptionError            # 密码错误或密钥文件损坏
-├── SigningError               # 签名操作失败
-├── NetworkError               # 网络标识符不匹配
-├── InsufficientBalanceError   # 余额不足
-├── UnsupportedOperationError  # 该钱包类型不支持此操作
-├── PrivyConfigError           # Privy 钱包配置错误
-├── PrivyRequestError          # Privy API 请求失败
-├── PrivyRateLimitError        # Privy API 速率限制
-└── PrivyAuthError             # Privy 认证失败
-```
-
-:::note Python 导入方式
-TypeScript 会从包根导出以上全部错误类型。而 Python 的顶层 `agent_wallet` 只导出 `WalletError`、`WalletNotFoundError`、`DecryptionError`、`SigningError`、`NetworkError` 和 `UnsupportedOperationError`。其余五个需要从 `agent_wallet.core.errors` 导入：
-
-```python
-from agent_wallet.core.errors import (
-    InsufficientBalanceError,
-    PrivyConfigError,
-    PrivyRequestError,
-    PrivyRateLimitError,
-    PrivyAuthError,
-)
-```
+├── WalletNotFoundError              # 找不到指定的钱包 ID（或没有任何已配置钱包）
+├── DecryptionError                  # 为兼容保留；3.x 钱包类型不会抛出
+├── InsufficientBalanceError         # SDK 不会抛出；供你自己的代码使用
+├── SigningError                     # 签名失败或 payload 被拒绝
+├── NetworkError                     # 网络标识不规范或不匹配
+├── UnsupportedOperationError        # 该钱包不支持此操作
+└── ExternalSignerError
+    ├── ExternalSignerConfigError
+    │   ├── PrivyConfigError
+    │   └── WalletCliConfigError
+    ├── ExternalSignerExecutionError
+    │   ├── PrivyRequestError
+    │   ├── PrivyRateLimitError
+    │   ├── PrivyAuthError
+    │   └── WalletCliExecutionError
+    │       └── WalletCliSubmittedTransactionError
+    ├── ExternalSignerUsageError
+    │   └── WalletCliUsageError
+    └── ExternalSignerNotFoundError
+        └── WalletCliNotFoundError
+```
+
+`WalletCliExecutionError` 与 `WalletCliUsageError` 都带有 `code`。agent-wallet 自身产生的 code 有：`capability_missing`（该 wallet-cli 可执行文件不能签这一类交易；账户没有该链族地址时报的是 `contract_mismatch`）、`network_mismatch`（wallet-cli 不认识该网络；在能力检查之后才检查）、`contract_mismatch`、`unsupported_version`、`unsupported_runtime`、`migration_required` / `migration_completed` / `migration_cancelled`、`timeout`、`aborted`、`spawn_error`、`stdin_write`、`output_limit`、`status_query_failed`，以及 wallet-cli 失败信封里 `code` 为空字符串时补上的 `internal_error`（信封里完全没有 `code` 时报 `contract_mismatch`）。wallet-cli 返回失败信封时，它自己的 code 会原样透传（例如 `account_not_found`、`auth_failed`）：退出码 `2` 对应 `WalletCliUsageError`，退出码 `1` 对应 `WalletCliExecutionError`。`wallet_cli` 交易的 `chainId` 与 `-n` 不一致时抛出的是 `SigningError`，不是 `NetworkError`。
+
+:::tip 不要自动重试 wallet-cli 超时
+`@bankofai/agent-wallet/integrations/wallet-cli` 的 `signAndBroadcast()` 超时后，不要自动重发——先核实结果。有两种超时不是异常：广播超时但已知 `txId`，或 `wait: true` 的轮询期限到了，调用都会返回 `{ txId, stage: 'timeout' }`。构建或签名阶段超时，或广播在拿到 `txId` 之前就超时，会抛 code 为 `timeout` 的 `WalletCliExecutionError`。`WalletCliSubmittedTransactionError` 只在 `wait: true` 且交易已广播、之后查询状态失败时抛出（包括状态查询本身超时，此时其 `code` 为 `timeout`），并带上该 `txId`。普通的 `signTransaction()` 不广播，也不会抛这个错误。
 :::
 
-:::tip 关于 InsufficientBalanceError
-`InsufficientBalanceError` **不会**由 SDK 自动抛出——Agent-wallet 是纯签名工具，不会检查余额。这个错误类型是为你的应用代码准备的便捷类型，当你在发起交易前检测到余额不足时，可以抛出此异常。
-:::
+### 进阶入口
+
+| 导入路径 | 内容 |
+| :--- | :--- |
+| `@bankofai/agent-wallet` | `resolveWallet`、`resolveWalletProvider`、`ConfigWalletProvider`、`EnvWalletProvider`、`Network`、`WalletType`、`loadConfig` / `saveConfig`、类型与错误 |
+| `@bankofai/agent-wallet/advanced` | 底层适配器和客户端（`EvmSigner`、`TronSigner`、`RawSecretSigner`、`PrivyAdapter`、`WalletCliAdapter`、`PrivyClient`、`WalletCliClient`）、凭据提供器（`ExecSecretProvider`、`StaticSecretProvider`） |
+| `@bankofai/agent-wallet/advanced`（续） | 另有 `LocalSigner`、配置解析器（`ExternalSignerConfigResolver`、`PrivyConfigResolver`、`WalletCliConfigResolver`）、`resolveSecret` / `isSecretRef` / `DEFAULT_EXEC_TIMEOUT_MS` / `DEFAULT_SECRET_STDOUT_LIMIT` / `DEFAULT_SECRET_STDERR_LIMIT`、`defaultSecretProviderFactory`，以及 `parseWalletCliNetwork` / `assertTronWalletCliNetwork` |
+| `@bankofai/agent-wallet/integrations/wallet-cli` | 借助 wallet-cli 完成构建 / 广播 / 查询的 TRON 专用工具：`signAndBroadcast`、`buildTransfer`、`broadcast`、`getTxStatus`、`getBalance`、`getTxInfo` |
 
 ---
 
 ## 下一步
 
-- 喜欢敲命令？ → [CLI 命令行手册](./CLI-Reference.md)
-- 找现成代码？ → [完整代码示例](./SDK-Cookbook.md)
-- 了解 Agent-wallet 的设计思路 → [简介](../Intro.md)
-- 查看常见问题 → [FAQ](../FAQ.md)
+- 更喜欢命令行？ → [CLI 命令行手册](./CLI-Reference.md)
+- 想找现成代码？ → [完整代码示例](./SDK-Cookbook.md)
+- 了解 Agent-wallet 的设计 → [简介](../Intro.md)
+- 常见问题 → [常见问题](../FAQ.md)
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md
index 3d997e91..48d5f9de 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md
@@ -1,45 +1,54 @@
 # 常见问题
 
-先回答你最关心的三件事，然后是日常使用中会碰到的细节。
+先回答你最担心的几件事，再聊日常使用的细节。
 
 ---
 
-## 💰 AI 代理会不会把我的钱全转走？
+## 💰 AI 会不会把我的钱包掏空？
 
-这是最常被问到的问题，答案是：**就算 AI 代理被入侵了，你的核心资产也是安全的。**
-
-我们强烈建议你给 AI 代理单独创建一个钱包，只充入它实际需要的小额资金（比如当 Gas 费的额度）。你的主钱包、大额资产永远不碰。这样就算最坏情况发生，损失也只是那个小额钱包里的余额。
+最好的保护是限制风险敞口：**专门给 AI 代理建一个钱包**，只充进它实际需要的少量资金（比如够付 Gas 就行）。你的主钱包和大额资产完全不碰。最坏情况下，损失也仅限于这个小额代理钱包里的钱。
 
 ```bash
-# 给 AI 代理单独建一个小额钱包
-agent-wallet add
+# 为代理创建专用的 wallet-cli 账户，然后连结它
+wallet-cli create --label agent-small -o json
+agent-wallet add wallet_cli --wallet-id agent_small --account agent-small \
+  --cli-password-exec /absolute/path/to/fetch-password.sh
 ```
 
-而且你的钱包文件是高强度加密的。就算黑客拿到了文件，没有主密码就是一堆乱码——暴力破解在经济上毫无意义。
+使用 `wallet_cli` 钱包时，私钥本身保存在 wallet-cli 的加密 keystore 中——Agent-wallet 的配置里只有 wallet-cli 账户 ID 和密码来源。
 
 ---
 
-## 🔌 断网了，AI 代理还能签名吗？
-
-对 `local_secure` 和 `raw_secret` 钱包——能：**签名 100% 在你本地机器上完成**，不调 RPC、不连云服务、不请求任何远端 API，私钥从始至终不碰网络。
+## 🔌 断网了，AI 还能签名吗？
 
-唯一的例外是 `privy` 类型：密钥托管在 Privy，签名请求会发往 Privy 的 API——它天然依赖网络。
+`raw_secret` 钱包在进程内签名，不发起任何网络请求；`wallet_cli` 钱包在本机的 wallet-cli 子进程中签名。`privy` 钱包类型不同：私钥由 Privy 托管，签名请求发往 Privy API，因此天然需要联网。
 
-断网只会影响交易的构建和广播（那是 MCP Server 的事），签名本身完全离线。
+断网主要影响的是交易的构建和广播（这是 MCP Server 或你自己代码的工作）。
 
 ---
 
-## 🔑 密码忘了怎么办？
+## 🔑 还有主密码吗？忘了怎么办？
+
+### 我在 2.x 用的是 `local_secure` 和 `AGENT_WALLET_PASSWORD`，现在怎么办？ {#upgrade-from-2x}
 
-**找不回来。**
+Agent-wallet 3.0 移除了 `local_secure` 钱包类型、agent-wallet 主密码、`AGENT_WALLET_PASSWORD`、`runtime_secrets.json`，以及 `init`、`change-password` 和 `sign msg` 命令。3.x 不会读取或转换 `local_secure` 钱包。
 
-主密码是解密所有私钥的唯一凭证。没有"忘记密码"功能，没有后门。
+升级前：
 
-如果你忘了密码：
-- 有私钥或助记词的其他备份？运行 `agent-wallet reset`，重新初始化，重新导入
-- 什么备份都没有？那个钱包的访问权限就丢失了
+1. 备份 `~/.agent-wallet`。
+2. 在仍安装着 2.x 时，确认你能拿到原始私钥或助记词。
+3. 把 2.x 的目录挪开，例如 `mv ~/.agent-wallet ~/.agent-wallet-2x`。`wallets_config.json` 里只要还有 `local_secure` 钱包，3.x 就会拒绝它（`Invalid wallet config`），包括 `start` 在内、所有需要读取配置的命令都会失败，直到旧文件被移走（`reset` 仍可运行）。也可以用 `--dir` 或 `AGENT_WALLET_DIR` 让 3.x 使用一个新目录。
+4. 升级后，用 3.x 的某种类型重建钱包：
+   - **本机生产签名：** 把私钥导入 wallet-cli（`wallet-cli import private-key` 或 `wallet-cli import mnemonic`），然后执行 `agent-wallet start wallet_cli`。
+   - **托管签名：** `agent-wallet start privy`。
+   - **仅限开发：** `agent-wallet start raw_secret`。
+5. 确认新钱包解析出预期的地址（`agent-wallet resolve-address`）并能正常签名后，再自行删除旧的 2.x 目录。
 
-**所以请现在就做这件事**：打开密码管理器，把主密码存进去。认真的。
+同时更新环境变量：`TRON_PRIVATE_KEY`、`TRON_MNEMONIC` 和 `TRON_ACCOUNT_INDEX` 已不再读取——请改用 `AGENT_WALLET_PRIVATE_KEY`、`AGENT_WALLET_MNEMONIC` 和 `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX`。网络值必须是规范格式（`tron:728126428`、`tron:3448148188`、`eip155:1` 等）。
+
+### 忘了 wallet-cli 密码怎么办？
+
+保护 `wallet_cli` 钱包的密码属于 wallet-cli 的 keystore，而不是 Agent-wallet。Agent-wallet 无法找回它。请用你备份的助记词或私钥在 wallet-cli 中恢复账户（`wallet-cli import mnemonic` / `wallet-cli import private-key`），然后重新把它连结到 Agent-wallet。
 
 ---
 
@@ -47,95 +56,86 @@ agent-wallet add
 
 ### Agent-wallet 到底是什么？
 
-一个纯本地的加密签名工具。它做两件事：1）把你的私钥加密存储；2）在本地完成签名。不联网、不用云，本身没有独立界面——而是作为隐形的安全中枢，完美接入 OpenClaw 等 AI 前端工具中。
+一个面向 AI 代理的签名层。它为你的代码提供统一的接口——`getAddress`、`signTransaction`、`signTypedData`——并把每个请求交给你配置的密钥后端（`wallet_cli`、`privy` 或 `raw_secret`）。它不构建、不广播交易，也没有自己的界面。
+
+### Agent-wallet 和 wallet-cli，我该用哪个？
 
-### CLI 和 SDK 什么区别？用哪个？
+- **wallet-cli** 负责保管私钥（加密 keystore），是新用户和 BANK OF AI 工具的官方配置入口。参见 [wallet-cli](../wallet-cli/quickstart.md)。
+- **Agent-wallet** 面向基于 `@bankofai/agent-wallet` SDK 构建的代码。使用 `wallet_cli` 类型时，它通过你的 wallet-cli 账户签名，两者可以共用同一把私钥。
 
-- **CLI** — 命令行工具，用来建钱包、管密钥、手动测试签名
-- **SDK** — TypeScript / Python 库，用来在自己的代码里调用签名
+### CLI 和 SDK，我该用哪个？
 
-大多数人不需要 SDK。如果你是用 OpenClaw 和 MCP Server 的普通用户，CLI 建完钱包、配好环境变量就够了。SDK 是给自己写代理的开发者用的。
+- **CLI** — 命令行工具，用于配置钱包和手动测试签名
+- **SDK** — TypeScript 库，用于在你自己的代码里直接调用签名
 
-### Agent-wallet 和 MetaMask 有什么区别？
+SDK 读取的就是 CLI 创建的配置。
 
-MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要你手动点"确认"。Agent-wallet 是给 AI 代理用的命令行钱包，专门设计为非交互式——AI 代理可以在后台静默调用签名，不需要人盯着屏幕点按钮。两者的加密原理类似（都是 Keystore V3），但使用场景完全不同。
+### 能签名一段普通消息吗？
 
-### 一台电脑上可以创建多少个钱包？
+不能。3.x 只签名交易和 EIP-712 / TIP-712 结构化数据；`sign msg`、`signMessage()` 和 `signRaw()` 都已移除。
 
-没有限制。你可以为不同的 AI 代理、不同的链、不同的用途分别创建独立钱包。用 `agent-wallet add` 添加，用 `agent-wallet use` 切换。
+### 一台电脑能建几个钱包？
+
+不限。你可以为不同的 AI 代理、不同的链、不同的用途分别配置钱包。用 `agent-wallet add` 添加，用 `agent-wallet use` 切换。
 
 ---
 
 ## 钱包类型
 
-### `local_secure`、`raw_secret` 和 `privy` 有什么区别？
+### `wallet_cli`、`privy` 和 `raw_secret` 有什么区别？
 
-| | `local_secure` | `raw_secret` | `privy` |
+| | `wallet_cli` | `privy` | `raw_secret` |
 | :--- | :---: | :---: | :---: |
-| **密钥存储** | ✅ 本地加密 | ❌ 本地明文 | ☁️ Privy 云端托管 |
-| **代理读了文件** | ✅ 拿不到密钥 | ❌ 直接被盗 | ✅ 本地无密钥文件 |
-| **需要主密码** | ✅ 需要 | ❌ 不需要 | ❌ 不需要（使用 API 凭证） |
-| **适合场景** | ✅ 所有场景 | ⚠️ 完全隔离的开发环境 | ✅ 使用 Privy 的服务端代理 |
+| **私钥存储** | ✅ wallet-cli 加密 keystore | ☁️ Privy 云端托管 | ❌ 明文保存在 `wallets_config.json` |
+| **代理读到 Agent-wallet 的配置** | ✅ 里面没有私钥（只有 wallet-cli 账户 ID 和密码来源） | ✅ 里面没有私钥（API 凭据，其中 app secret 可用 exec 脚本） | ❌ 私钥瞬间被盗 |
+| **签名是否需要联网** | 否 | 是（Privy API） | 否 |
+| **适用场景** | ✅ 本机生产签名 | ✅ 使用 Privy 的服务端代理 | ⚠️ 仅限完全隔离的开发环境 |
 
-:::danger `raw_secret` 会以明文存储你的私钥
-`raw_secret` 不加密私钥——这恰恰是 `local_secure` 模式旨在防范的风险。如果你的机器上有任何其他进程能读取文件，你的私钥就会被直接盗走。**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理，且处于完全隔离的离线测试环境中。
+:::danger `raw_secret` 会以明文暴露你的私钥
+任何能读取你主目录文件的进程都能读到私钥。只在完全隔离的测试环境中配合一次性私钥使用 `raw_secret`。
 :::
 
-:::tip Privy 钱包
-`privy` 类型将密钥托管交给 [Privy](https://privy.io) 的服务器端钱包基础设施。本地磁盘上不存储任何私钥——签名请求会发送到 Privy 的 API。这非常适合已经使用 Privy 进行钱包管理的服务端 AI 代理。配置时需要 Privy App ID、App Secret 和 Wallet ID。
+:::tip 用 exec 脚本保存 wallet-cli 和 Privy 的凭据
+使用 `--cli-password-exec` / `--app-secret-exec`，让凭据在需要时（例如从 1Password）读取，而不是写进 `wallets_config.json`。在 `direct` 提示中输入的密码会以明文保存在那里（文件权限 `0600`）。
 :::
 
-### `network` 参数怎么填？
+### `network` 参数可以填哪些值？
+
+只接受精确的规范 CAIP-2 标识：
 
 | 值 | 说明 |
 | :--- | :--- |
-| `tron:mainnet` | TRON 主网 |
-| `tron:nile` | TRON Nile 测试网 |
-| `tron:shasta` | TRON Shasta 测试网 |
+| `tron:728126428` | TRON 主网 |
+| `tron:3448148188` | TRON Nile 测试网 |
+| `tron:2494104990` | TRON Shasta 测试网 |
 | `eip155:1` | Ethereum 主网 |
 | `eip155:56` | BSC 主网 |
+| `eip155:97` | BSC 测试网 |
 | `eip155:137` | Polygon 主网 |
 | `eip155:8453` | Base 主网 |
 | `eip155:42161` | Arbitrum 主网 |
 
-> 以上是常见示例，并非穷举白名单：agent-wallet 只校验前缀，任何 `eip155:<chainId>` 或 `tron:<network>` 取值都会被接受（包括 x402 系列工具要求的规范 CAIP-2 TRON ID，如 `tron:0x2b6653dc`）。
+> 以上是常用示例，并非白名单：任何 `eip155:<正整数 chainId>` 或 `tron:<正整数 chainId>` 都可以。别名（`tron:nile`、`tron:mainnet`、`evm:1`）、裸 `tron` / `eip155`、`tron:0x2b6653dc` 这类十六进制 TRON id，以及大小写或空白变体都会被拒绝。
+>
+> `wallet_cli` 钱包还要求该网络是 wallet-cli 自身认识的网络——即它的内置网络（`eip155:1`、`eip155:11155111`、`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`（Base 自 wallet-cli 4.14.0 起才内置）及表中三个 TRON 网络），或在 wallet-cli 自己的配置中添加的网络——否则签名会以 `network_mismatch` 失败。`raw_secret` 和 `privy` 钱包没有这一限制。
 
 ---
 
-## 安全性
-
-### 既然密码也要配在环境变量里，那和直接放明文私钥有什么区别？
-
-区别极大！这是"把现金摆在桌上"和"把钱锁进双重保险箱"的区别。
-
-你平时用 Web3 钱包（比如 MetaMask）时，肯定不会每次都复制粘贴明文私钥，而是用一个短密码去解锁它。Agent-wallet 就是专为 AI 打造的命令行版 MetaMask。
-
-* 传统方式（明文私钥）： 就像把现金直接放在桌子上。任何一个恶意的浏览器插件、一次不小心的代码提交、或者后台日志扫描，只要看一眼你的环境变量文件，钱瞬间就被转走了。这是典型的单点白给。
-* Agent-wallet 模式： 它把风险拆分成了两把锁。
-   1. 物理保险箱： 你的私钥被行业顶级的算法加密，锁死在你电脑深处的隐藏文件夹里（`~/.agent-wallet`）。
-   2. 开箱密码： 你放在环境变量里的，仅仅是解锁这个保险箱的密码。
+## 安全
 
-这就意味着，如果发生了泄露：
+### 私钥会离开我的电脑吗？
 
-* 黑客如果只偷到了你的密码（比如通过扫描环境变量），他没有你的加密钱包文件，密码就只是一串没用的字符。
-* 黑客如果只偷走了你的加密钱包文件，他没有你的主密码，文件就是一堆几万年都破解不开的乱码。
+`raw_secret` 和 `wallet_cli` 钱包都在本机签名——Agent-wallet 签名时不发起网络请求。`privy` 钱包是例外：私钥由 Privy 托管（从不出现在你的磁盘上），签名请求发往 Privy API。
 
-黑客必须同时黑进你的电脑、精准定位并偷走隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。这种攻击难度比仅仅扫描一下环境变量要高出无数倍！
+### `wallet_cli` 钱包是如何处理密码的？
 
-### 密钥会通过网络发出去吗？
+Agent-wallet 从不读取或解密 wallet-cli 的 keystore。每次签名时，它会固定所配置的账户和网络，获取密码（每次都重新执行 exec 脚本，默认 10 秒超时），只把密码写入这一次 wallet-cli 子进程的 stdin，并核对返回的签名者与账户一致。密码从不出现在命令行参数中。
 
-对 `local_secure` 和 `raw_secret` 钱包——永远不会：零网络请求、零 RPC 调用、零云服务，私钥不离开你的机器。`privy` 类型是例外：密钥托管在 Privy（从不落在你的磁盘上），签名请求会发往 Privy 的 API。
+### 怎样安全地保存凭据？
 
-### 主密码怎么保管才安全？
-
-- ✅ 用密码管理器（1Password、Bitwarden）
-- ✅ 通过环境变量 `AGENT_WALLET_PASSWORD` 传入
-- ❌ 不要写在代码里
-- ❌ 不要提交含密码的环境变量文件到 git
-
-### 加密算法安全吗？会不会被暴力破解？
-
-Agent-wallet 使用 Keystore V3 标准加密（scrypt + AES-128-CTR），这和 Ethereum 官方钱包使用的加密方案完全一致。scrypt 算法的设计目标就是让暴力破解在计算和内存上都极其昂贵——即使使用专用硬件，破解一个强密码也需要数万年。
+- ✅ 使用密码管理器（1Password、Bitwarden），并通过 exec 脚本引用
+- ❌ 不要把凭据硬编码在源码里，也不要作为命令行参数传入
+- ❌ 不要把 `~/.agent-wallet/wallets_config.json` 或 `.env` 文件提交到 git
 
 ---
 
@@ -143,15 +143,15 @@ Agent-wallet 使用 Keystore V3 标准加密（scrypt + AES-128-CTR），这和
 
 ### 支持哪些操作系统？
 
-macOS、Linux 和 Windows。只要能跑 Node.js >= 18 或 Python >= 3.11，就能用。Windows 支持在 v2.3.x 中添加——文件权限功能（如 `chmod 600`）在 Windows 上会被优雅地跳过，因为 Windows 不支持 Unix 风格的权限控制。
+macOS、Linux 和 Windows，需要 Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+（使用 wallet-cli 时也是同一范围）。在不支持 Unix 权限的平台上，会跳过文件权限加固（`wallets_config.json` 设为 `chmod 600`、目录设为 `700`）。在 Windows 上，请把 `AGENT_WALLET_WALLET_CLI_PATH` 指向 wallet-cli 的 JavaScript 入口，而不是 `.cmd` / `.bat` 包装脚本。
 
-### `npm install -g` 报权限错误怎么办？
+### `npm install -g` 报权限错误？
 
-常见于 macOS / Linux。两种解法：
+在 macOS / Linux 上很常见。两种解决方法：
 
-**方法 1（推荐）：用 nvm 管理 Node.js**，它会把全局包装在用户目录下，不需要 `sudo`。
+**方法一（推荐）：用 nvm 管理 Node.js**——它把全局包装在你的用户目录下，不需要 `sudo`。
 
-**方法 2：修复 npm 全局目录权限**：
+**方法二：修改 npm 全局目录权限：**
 ```bash
 mkdir -p ~/.npm-global
 npm config set prefix '~/.npm-global'
@@ -159,23 +159,27 @@ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
 source ~/.zshrc
 ```
 
-### 配了密码但 AI 代理说"找不到钱包"或"密码错误"？
+### 代理提示"wallet not found"或"network is required"？
 
-最常见的三个原因：
+最常见的原因：
 
-1. **密码没生效**：你在终端 A 配了 `export`，但 AI 代理在终端 B 运行。解决：重启 AI 代理后台服务（参考 [快速开始](./QuickStart.md) 第二步）。
-2. **密码被 shell 吃了**：双引号包裹的密码里有 `$` 或 `!`，被 shell 展开了。解决：改用单引号。
-3. **存储目录不对**：你之前用 `--dir` 指定了自定义路径，但 AI 代理在默认路径找。解决：`export AGENT_WALLET_DIR="/你的自定义路径"`。
+1. **存储目录不对**：创建钱包时用了 `--dir`，但代理查找的是默认路径。在代理的运行环境中设置 `AGENT_WALLET_DIR="/your/custom/path"` 并重启代理。
+2. **没有激活钱包（CLI）**：未设置激活钱包时，不带 `-w` 的 `agent-wallet sign` 会失败。运行 `agent-wallet list`；如果没有任何钱包标着 `*`，执行 `agent-wallet use <id>`。（SDK 的 `resolveWallet()` / `getActiveWallet()` 不会因此报错——它们会回退到第一个已配置的钱包。）
+3. **缺少网络或网络不规范**：`raw_secret` 和 `wallet_cli` 钱包需要 `tron:3448148188`、`eip155:56` 这样的网络。
 
-### `agent-wallet` 命令找不到（command not found）？
+### 添加 `wallet_cli` 钱包时提示 `wallet-cli not found`？
 
-说明全局安装没有生效。检查：
+安装兼容版本（`npm install -g '@tron-walletcli/wallet-cli@^4.13.0'`），并确认在同一个 shell 中 `wallet-cli --version` 能正常运行；或者设置 `AGENT_WALLET_WALLET_CLI_PATH`。Agent-wallet 3.x 不支持 wallet-cli 4.12.x 和 5.x。
+
+### 找不到 `agent-wallet` 命令？
+
+全局安装没有生效。检查一下：
 ```bash
-# 确认 npm 全局 bin 目录在 PATH 里
+# 确认 npm 全局 bin 目录在 PATH 中
 npm prefix -g
 # 全局 bin 目录为：$(npm prefix -g)/bin
 ```
-如果输出的路径不在你的 `$PATH` 中，手动添加：
+如果输出的路径不在你的 `$PATH` 里，手动加上：
 ```bash
 echo "export PATH=$(npm prefix -g)/bin:$PATH" >> ~/.zshrc
 source ~/.zshrc
@@ -183,36 +187,24 @@ source ~/.zshrc
 
 ---
 
-## 跨语言
-
-### Python 和 TypeScript 的密钥文件通用吗？
-
-通用。两个实现使用完全相同的加密格式。CLI 建的钱包，Python SDK 直接能用，反过来也一样。
-
-### 两种语言的签名结果一样吗？
-
-完全一样。同一个私钥 + 同一份数据 = 同一个签名。
-
----
-
-## 与 OpenClaw 集成
+## OpenClaw 集成
 
-### OpenClaw 是必须的吗？
+### 必须用 OpenClaw 吗？
 
-不是。Agent-wallet 是一个独立的签名工具，可以通过 CLI 或 SDK 独立使用。OpenClaw 只是最方便的前端——它让你用自然语言就能调用签名，不用写代码。
+不是。Agent-wallet 是独立的签名工具，可以单独通过 CLI 或 SDK 使用。
 
-### OpenClaw 里说"签名失败"或"钱包未连接"？
+### OpenClaw 提示"签名失败"或"钱包未连接"？
 
 按以下顺序排查：
 
-1. 确认 `AGENT_WALLET_PASSWORD` 环境变量已设置（在运行 OpenClaw 的那个终端里执行 `[[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "已设置" || echo "未设置"` 验证，不会泄露密码明文）
-2. 确认 MCP Server 是在设置了环境变量**之后**启动的
-3. 确认钱包已初始化：`agent-wallet list` 应该能看到至少一个钱包
-4. 如果以上都正确，尝试用 CLI 手动签名测试：`agent-wallet sign msg "test" -n tron`
+1. 确认你使用的工具确实是通过 Agent-wallet 3.x 签名的——新的 BANK OF AI 配置直接使用 [wallet-cli](../wallet-cli/quickstart.md)。
+2. 确认已配置钱包：`agent-wallet list` 应至少显示一个钱包，并用 `*` 标出激活钱包。
+3. 确认代理的运行环境使用同一个钱包目录（`AGENT_WALLET_DIR`），修改后重启代理。
+4. 手动签名试试：`agent-wallet sign typed-data '<json>' -n eip155:56`。
 
-### 在 OpenClaw 里签名需要花 Gas 费吗？
+### 签名需要付 Gas 吗？
 
-签名本身不花 Gas。签名只是用你的私钥对一段数据做密码学运算，完全在本地完成。只有当签名后的交易被广播到链上时，才需要 Gas 费。查地址、签名消息这类操作永远免费。
+签名本身不花 Gas。只有把签好的交易广播到区块链时才会产生 Gas 费。
 
 ---
 
@@ -220,6 +212,6 @@ source ~/.zshrc
 
 - 没写过代码？ → [快速开始](./QuickStart.md)
 - 喜欢敲命令？ → [CLI 命令行手册](./Developer/CLI-Reference.md)
-- 要开发应用？ → [SDK 接入指南](./Developer/SDK-Guide.md)
+- 要自己写代理？ → [SDK 接入指南](./Developer/SDK-Guide.md)
 - 找现成代码？ → [完整代码示例](./Developer/SDK-Cookbook.md)
 - 了解 OpenClaw Extension → [OpenClaw Extension 简介](../Openclaw-extension/Intro.md)
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md
index f67ae12d..67a8b5d0 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Intro.md
@@ -1,8 +1,9 @@
 # 简介
 
 :::note
-Agent Wallet 文档保留给现有 SDK、服务端和社区集成。官方新用户的钱包配置入口是 [wallet-cli](/zh-Hans/wallet-cli/quickstart/)，两套配置不会自动互通。
+Agent Wallet 文档介绍现有 SDK、服务端和社区集成所使用的 `@bankofai/agent-wallet` 3.x SDK 与 CLI。官方新用户的钱包配置入口是 [wallet-cli](../wallet-cli/quickstart.md)。从 3.0 起，Agent-wallet 可以通过 `wallet_cli` 钱包类型**连结**已有的 wallet-cli 账户，但绝不会导入、复制或解密 wallet-cli 的密钥。
 :::
+
 ## 享受 AI Agent 便利，告别私钥泄露焦虑
 
 ### 你的私钥，距离被盗可能只差一次文件读取
@@ -29,130 +30,115 @@ Agent Wallet 文档保留给现有 SDK、服务端和社区集成。官方新用
 
 ---
 
-## 破局之道：Agent-wallet —— 专为 AI 代理打造的 Web3 钱包
-
-你平时用 Web3 钱包（比如 TronLink/MetaMask）时，会每次把明文私钥贴进去吗？当然不会。你会用一个密码解锁它，然后让它替你签名。
-
-**Agent-wallet 就是专为 AI 代理打造的本地 TronLink/MetaMask。**
-
-它通过**"物理与密码分离"**的双重机制，把你的风险降到了最低：
+## 思路：统一的签名接口，密钥放在别处
 
-1. **第一重锁（物理文件）：** 你的私钥会被行业顶级的算法加密，锁死在电脑深处的隐藏文件夹里（`~/.agent-wallet`）。
-2. **第二重锁（授权密码）：** AI 代理只需要知道"开箱密码"（你可以配在环境变量里）就能干活。
+你平时用 Web3 钱包（比如 TronLink/MetaMask）时，会把明文私钥贴进每个应用吗？当然不会。钱包保管私钥，替你签名。
 
-**你可能会问："如果 AI 代理把我的开箱密码也泄露了怎么办？"**
+**Agent-wallet 给 AI 代理提供同样的东西：一个统一的签名接口（`getAddress`、`signTransaction`、`signTypedData`），背后接你选定的密钥后端。** 你的代理代码——或者它所使用的 MCP Server / Skill——只需请 Agent-wallet 签名，自己从不接触私钥。
 
-这就是 Agent-wallet 最精妙的地方：**密码泄露 ≠ 资产被盗。**
+Agent-wallet 3.x 支持三种钱包类型：
 
-如果黑客通过恶意插件只偷到了你的密码，他什么也干不了，因为他没有你的加密钱包文件。如果他只偷到了钱包文件，没有密码，那就是一堆无法破解的乱码。
+| 钱包类型 | 私钥在哪里 | 适用场景 |
+| :--- | :--- | :--- |
+| `wallet_cli` | 在 [wallet-cli](../wallet-cli/quickstart.md) 的加密 keystore 里。Agent-wallet 从不读取或解密该 keystore；每次签名都在受限的 wallet-cli 子进程中完成，keystore 密码只交给这一次签名的子进程。 | 本机生产签名 |
+| `privy` | 由 [Privy](https://privy.io) 托管——你的磁盘上没有私钥。签名请求发往 Privy API。 | 已在使用 Privy 的服务端代理 |
+| `raw_secret` | **以明文**保存在 `~/.agent-wallet/wallets_config.json` 中。 | 仅限开发和一次性测试密钥 |
 
-**黑客必须同时黑进你的电脑系统，精准翻出隐藏的钱包文件，并且同时窃取到环境变量里的密码，才能动你的钱。** 这种攻击难度和成本，比仅仅扫描一下环境变量文件里的明文私钥要高出无数倍！
+在 CI 等一次性环境中，SDK 也可以直接从环境变量（`AGENT_WALLET_PRIVATE_KEY` 或 `AGENT_WALLET_MNEMONIC`）读取私钥。这同样是明文——参见 [SDK 接入指南](./Developer/SDK-Guide.md)。
 
-一句话：**文件随便偷，没密码打不开；密码被泄露，没文件依然安全。**
+:::caution 从 2.x 升级
+3.0 移除了 `local_secure` 加密钱包类型、agent-wallet 主密码、`AGENT_WALLET_PASSWORD` 和 `runtime_secrets.json`。已有的 2.x `local_secure` 钱包**不会**被自动转换。请先备份 `~/.agent-wallet`，在 2.x 下确认你仍能拿到原始私钥或助记词，再把钱包重建为 `wallet_cli`（推荐）、`privy` 或 `raw_secret`。参见 [常见问题](./FAQ.md#upgrade-from-2x)。
+:::
 
 ---
 
-## 和"老办法"对比一下
+## 方案对比
 
-| | :x: 传统方式（明文私钥放在配置文件里） | :white_check_mark: Agent-wallet  |
+| | :x: 传统方案（私钥明文写在配置文件里） | :white_check_mark: Agent-wallet + `wallet_cli` |
 | :--- | :--- | :--- |
-| **工作原理** | :x: 把银行卡和密码直接交给 AI 代理 | :white_check_mark: **给 AI 代理密码，文件锁在本地** |
-| **遭遇日志/环境变量泄露** | :rotating_light: **直接倾家荡产** | :shield: **只丢了密码，没有文件，黑客偷不走钱** |
-| **遭遇加密文件被窃取** | :x: 明文私钥，直接被盗 | :shield: **没有密码，黑客打不开文件** |
-| **断网能签名吗** | :warning: 看情况 | :white_check_mark: **100% 离线签名**（`local_secure` / `raw_secret`；`privy` 类型经 Privy API 签名，需联网） |
+| **代理的配置里存的是什么** | :x: 私钥本身 | :white_check_mark: wallet-cli 账户 ID 和密码来源（最好是 `exec` 脚本） |
+| **密钥文件被其他程序读到** | :rotating_light: **全军覆没** | :shield: keystore 由 wallet-cli 加密 |
+| **TRON 与 EVM 用同一套签名 API** | :warning: 看你的代码 | :white_check_mark: 所有后端都是同一个 `Wallet` 接口 |
+| **能离线运行吗？** | :warning: 看情况 | :white_check_mark: `wallet_cli` 和 `raw_secret` 在本机签名；`privy` 通过 Privy API 签名，需要联网 |
 
 ---
 
-## 三条命令，一分钟上手
+## 三步完成第一次签名
 
-不需要先搞懂所有东西，先跑通再说：
+不需要先搞懂所有概念，先跑起来再说。这条路径使用最快的 `raw_secret` 类型，配合一把**一次性测试私钥**（绝不要用于真实资金）：
 
-**第一步 — 安装 Agent-wallet：**
+**第一步——安装 Agent-wallet：**
 ```bash
 npm install -g @bankofai/agent-wallet
 ```
 
-**第二步 — 创建你的 Agent-wallet 钱包：**
+**第二步——导入测试私钥：**
 ```bash
-agent-wallet start
+agent-wallet start raw_secret
 ```
-运行后，向导会让你设置一个**主密码**——直接回车则自动生成一个强密码，且只显示一次。这个密码是你唯一的"开箱钥匙"：每次 AI 代理需要签名时，都要用它来解锁钱包。**请立刻用密码管理器（如 1Password、Bitwarden）保存这个密码**——丢了就无法找回，资产也将无法操作。
+按提示选择 `private_key` 并粘贴测试私钥。CLI 会警告原始密钥将以明文保存在 `wallets_config.json` 中。
 
-**第三步 — 第一次签名：**
+**第三步——完成第一次签名：**
 ```bash
-agent-wallet sign msg "Hello from my AI agent" -n tron
+agent-wallet sign typed-data '{"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}],"Message":[{"name":"contents","type":"string"}]},"primaryType":"Message","domain":{"name":"AgentWallet","chainId":1},"message":{"contents":"Hello from my AI agent"}}' -n eip155:1
 ```
 
-CLI 会先要求输入主密码——直接跑 `agent-wallet start` 不会持久化密码，签名时必须解锁密钥库。（在第 2 步加上 `--save-runtime-secrets` 即可跳过这一步，BANK OF AI 的引导技能就是这么做的。）当屏幕上吐出一串哈希字符时——恭喜，你的 Agent-wallet 配置成功了。
+看到以 `Signature:` 开头的一行输出——恭喜，你的 Agent-wallet 已经上线了。
 
-> 想看每一步的详细说明？去 **[快速开始](./QuickStart.md)**。
+> 涉及真实资金时，请改为连结 wallet-cli 账户。完整步骤见 **[快速开始](./QuickStart.md)**。
 
 ---
 
-## 接下来，让 AI 代理真正跑起来
+## 下一步：接入你的 AI 代理
 
-Agent-wallet 建好了。现在的问题是：**怎么让我的 AI 代理用上这个钱包？**
+Agent-wallet 配好了，签名也通了。接下来的问题是：**怎么让我的 AI 代理用上这个钱包？**
 
 根据你的角色，走不同的路：
 
 ### 🎮 我是普通玩家——用现成的工具
 
-你完全不需要懂代码！你可以直接使用我们配套好的"全家桶"：**[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。
+你完全不需要懂代码！可以直接使用配套的工具：**[OpenClaw Extension](../Openclaw-extension/Intro.md) + [MCP Server](../McpServer-Skills/MCP/Intro.md) + [Skills](../McpServer-Skills/SKILLS/Intro.md)**。请以各工具自己的配置页为准确认它使用哪种钱包——新的配置直接使用 [wallet-cli](../wallet-cli/quickstart.md)。
 
 #### 🤝 它们是怎么配合干活的？
 
 为了让你用得绝对放心，我们把你的 AI 助理设计成了一家分工明确的"小公司"：
 
 - 🧠 **业务团队（OpenClaw + Skills + MCP）：** 负责在外头跑腿。它们脑子转得快、工具多，知道怎么查行情、算滑点、找最优报价。但最重要的是：它们没有任何动用你资金的权限。
-- 🏦 **财务总监（Agent Wallet）：** 负责死守钱袋子。你的私钥（银行卡密码）被死死锁在它的本地保险柜里，外面的业务团队根本看不见。
+- 🏦 **财务总监（Agent Wallet）：** 守在金库门口。使用 `wallet_cli` 类型时，金库就是 wallet-cli 的加密 keystore；使用 `privy` 时，金库是 Privy 的基础设施。
 
-一条完美的安全流水线是这样的：
+一条安全的流水线是这样的：
 
 1. 你坐在老板椅上发话："帮我买 100 U 的 TRX"。
 2. 业务团队马上跑去查价格、算手续费，并老老实实写好一张"交易申请单"。
-3. 它们把单子递给坐在保险柜旁的 **财务总监（Agent Wallet）**。
-4. 财务总监核对无误后，绝不把私钥拿出保险柜，而是直接在申请单上盖个"同意印章"（技术上叫签名），然后再把盖好章的单子递出去。
+3. 它们把单子递给 **财务总监（Agent Wallet）**。
+4. 财务总监让金库在申请单上盖个"同意印章"（技术上叫签名），私钥始终不离开金库，然后只把盖好章的单子递出去。
 5. 业务团队拿着盖好章的单子，去区块链上把事办妥。
 
-✨ **核心亮点：** 在整个过程中，跑腿的 AI 工具自始至终只拿到了"盖好章的纸"，连私钥的影子都没见着！既保证了 AI 代理能帮你干极其复杂的活儿，又保证了你的资产绝对安全。
-
-#### ⚙️ 听起来很棒，我该怎么把它们连起来？
-
-极其简单！你不需要写复杂的程序，只需要做一件事：给业务团队一把唤醒财务总监的内部口令。
-
-把你创建 Agent Wallet 时生成的"主密码"像下面这样告诉工具即可：
-
-```bash
-export AGENT_WALLET_PASSWORD='你的主密码'
-```
-
-就这一行配置！设置好口令后，整个系统就能全自动无缝配合了。你的 AI 代理将彻底蜕变为一个既聪明能干，又绝对安全的 Web3 顶级私人管家！
+✨ **核心亮点：** 跑腿的 AI 工具自始至终只拿到"盖好章的纸"——签好名的交易或签名。
 
 > 迫不及待想试试？去 👉 **[快速开始](./QuickStart.md)** 跟着做一遍。
 
 ### ⌨️ 我是进阶用户——想用 CLI 管理钱包
 
-需要免密签名、管理多个钱包、自定义存储目录？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。
+需要管理多个钱包、使用 exec 脚本凭据、自定义存储目录？去 **[CLI 命令行手册](./Developer/CLI-Reference.md)**。
 
 ### 👨‍💻 我是开发者——自己写代理
 
 <details>
-<summary>展开开发者路径 — TypeScript / Python SDK</summary>
+<summary>展开开发者路线 — TypeScript SDK</summary>
 
-Agent-wallet 提供了完整的 SDK，TypeScript 和 Python 双语言支持，共享同一套接口：
+Agent-wallet 3.x 提供 TypeScript SDK；SDK 读取的就是 CLI 写入的同一份配置：
 
 ```typescript
-import { resolveWalletProvider } from "@bankofai/agent-wallet";
+import { resolveWallet } from "@bankofai/agent-wallet";
 
-const provider = resolveWalletProvider({ network: "tron:nile" });
-const wallet   = await provider.getActiveWallet();
-const sig      = await wallet.signMessage(new TextEncoder().encode("Hello!"));
+const wallet = await resolveWallet({ network: "tron:3448148188" }); // TRON Nile
+const address = await wallet.getAddress();
+const signed = await wallet.signTransaction(unsignedTx); // { family: "tron", transaction }
 ```
 
-同一个密钥文件、同一份数据、同一个签名结果。
-
-> **[SDK 接入指南](./Developer/SDK-Guide.md)** 手把手教你接入。
-> **[完整代码示例](./Developer/SDK-Cookbook.md)** 展示端到端的真实交易：TRON 转账、BSC 转账、x402 支付签名。
+> **[SDK 接入指南](./Developer/SDK-Guide.md)** — 手把手集成教程。
+> **[完整代码示例](./Developer/SDK-Cookbook.md)** — 端到端真实交易：TRON 转账、BSC 转账、x402 支付签名。
 
 </details>
 
@@ -160,21 +146,25 @@ const sig      = await wallet.signMessage(new TextEncoder().encode("Hello!"));
 
 ## 支持的链
 
+所有网络都使用规范的 CAIP-2 标识：
+
 | 链类型 | 网络 |
 | :--- | :--- |
-| **EVM** | Ethereum、BSC、Polygon、Base、Arbitrum，以及任何 EVM 兼容链（主网和测试网均支持） |
-| **TRON** | TRON 主网、Nile 测试网、Shasta 测试网 |
+| **EVM** | `eip155:<chainId>` — Ethereum（`eip155:1`）、BSC（`eip155:56`）、Base（`eip155:8453`）及任何 EVM 兼容链，主网和测试网均支持 |
+| **TRON** | `tron:<chainId>` — 主网（`tron:728126428`）、Nile 测试网（`tron:3448148188`）、Shasta 测试网（`tron:2494104990`） |
+
+`wallet_cli` 钱包还要求该网络是 wallet-cli 自身认识的网络——即它的内置网络（`eip155:1`、`eip155:11155111`、`eip155:56`、`eip155:97`、`eip155:8453`、`eip155:84532`（Base 自 wallet-cli 4.14.0 起才内置）及上面三个 TRON 网络），或在 wallet-cli 自己的配置中添加的网络——否则签名会以 `network_mismatch` 失败。`raw_secret` 和 `privy` 钱包没有这一限制。
 
-两类链共用同一套接口——学一次，到处用。
+两种链类型共享同一套接口——学一次，到处用。
 
 ---
 
 ## 还有疑问？
 
-| 我在想… | 去这里 |
+| 我想知道… | 去这里 |
 | :--- | :--- |
-| AI 代理会不会把我的钱全转走？ | [FAQ](./FAQ.md) — 我们有专门的风险隔离方案 |
-| 没写过代码？ | [快速开始](./QuickStart.md) |
-| 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) |
-| 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) |
-| 找现成代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) |
+| AI 会不会把我钱包掏空？ | [常见问题](./FAQ.md) — 给代理单独开一个小额钱包 |
+| 从来没写过代码？ | [快速开始](./QuickStart.md) |
+| 更喜欢命令行？ | [CLI 命令行手册](./Developer/CLI-Reference.md) |
+| 要自己写代理？ | [SDK 接入指南](./Developer/SDK-Guide.md) |
+| 想找现成的代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md
index f55e30cf..c3ad1261 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md
@@ -4,67 +4,32 @@ import TabItem from '@theme/TabItem';
 # 快速开始
 
 :::note
-Agent Wallet 文档保留给现有 SDK、服务端和社区集成。官方新用户的钱包配置入口是 [wallet-cli](/zh-Hans/wallet-cli/quickstart/)，两套配置不会自动互通。
+Agent Wallet 文档介绍现有 SDK、服务端和社区集成所使用的 `@bankofai/agent-wallet` 3.x SDK 与 CLI。官方新用户的钱包配置入口是 [wallet-cli](../wallet-cli/quickstart.md)。Agent-wallet 可以连结 wallet-cli 账户（下文路径 A），但绝不会导入或解密 wallet-cli 的密钥。
 :::
 
-从零到在 AI 代理对话框里唤醒你的 Agent-wallet。创建钱包有两种方式：**命令行创建**适用于所有环境；**对话式创建**只适用于仍装有旧版 agent-wallet 和 bankofai-guide Skill 的环境。
+从零开始，配好一个能让 AI 代理或你自己的代码签名的 Agent-wallet。二选一：
 
-:::tip 前置依赖 & CLI 命令细节
-- 你的 AI Agent 支持 shell 命令执行（OpenClaw、Telegram Bot、Web 聊天页面、Claude Code、Cursor 等）
-- 本页只带你跑通最短路径。免密配置、管理多个钱包、签名类型等进阶内容，请看 [CLI 命令行手册](./Developer/CLI-Reference.md)。
-:::
-
----
-
-## 方式一：对话式创建（旧版 Skill）
-
-:::note 历史配置流程
-以下对话式流程仅适用于已安装旧版 agent-wallet 和 bankofai-guide Skill 的环境，这两个 Skill 已在 Skills 3.0.0 中删除。
-:::
-
-如果你之前安装过包含 `agent-wallet` 和 `bankofai-guide` 的旧版 [BANK OF AI 技能](../McpServer-Skills/SKILLS/QuickStart.md)，那么创建钱包只需要在 AI 对话框里发一句话就行——AI 会自动帮你生成密码、创建钱包、保存配置，全程无需手动改文件。
+- **路径 A —— 连结 wallet-cli 账户（真实资金推荐）。** 私钥留在 wallet-cli 的加密 keystore 中。
+- **路径 B —— 导入原始私钥（仅限开发）。** 私钥或助记词会**以明文**保存在 `~/.agent-wallet/wallets_config.json` 中。
 
-**操作步骤：**
+Privy 用户：参见 [CLI 命令行手册 → Privy](./Developer/CLI-Reference.md#privy-wallets)。
 
-1. 打开你的 AI Agent 对话框
-2. 复制下面这段 prompt 发送给 AI：
-
-   ```
-   创建 AgentWallet 钱包
-   ```
-
-3. AI 会自动完成以下流程：
-   - **检查当前钱包状态**——告诉你是否已有配置
-   - **询问创建方式**——给出两个选项：
-     - **A. 快速设置（强烈推荐）**：全自动，约 10 秒完成；自动生成安全密码；钱包加密存储在本地
-     - **B. 详细设置**：手动选择钱包类型；自定义密码；更多配置选项
-4. 回复 `A` 即可，AI 会自动跑完三个步骤：
-   - **步骤 1**：生成安全密码
-   - **步骤 2**：创建钱包
-   - **步骤 3**：获取钱包地址
-
-
-:::caution 主密码非常重要，请立即备份
-主密码仅展示一次。引导安装执行的是带 `--save-runtime-secrets` 的 `agent-wallet start`，会把它保存到本地的 `~/.agent-wallet/runtime_secrets.json`，但强烈建议你同时手动保存到密码管理器（1Password / Bitwarden 等）——一旦本地文件丢失或损坏，且没有外部备份，你的钱包将永久无法解锁（没有备份找回机制，没有客服，没有后门）。
-
-⚠️ 切勿把这个密码发到聊天工具、邮件、截图或公开仓库中。
+:::tip 前置条件 & CLI 命令详解
+- 你的 AI 代理支持执行 Shell 命令（OpenClaw、Telegram 机器人、网页聊天、Claude Code、Cursor 等），或者你要在自己的代码里集成 SDK。
+- 本页只带你走最短路径。所有命令与参数请查阅 [CLI 命令行手册](./Developer/CLI-Reference.md)。
 :::
 
-:::tip 完成即可用，无需配置环境变量
-对话式创建会传入 `--save-runtime-secrets`，把密码保存到 `~/.agent-wallet/runtime_secrets.json`，AI Agent 后续调用钱包时会自动读取，**无需手动配置 `AGENT_WALLET_PASSWORD` 环境变量**。如果你想了解环境变量配置方式，请看下面的"方式二"。
+:::caution 从 2.x 升级？
+3.0 移除了 `local_secure`、主密码、`AGENT_WALLET_PASSWORD` 和 `runtime_secrets.json`；配套的 `agent-wallet` / `bankofai-guide` 对话式 Skill 也已在 Skills 3.0.0 中移除。已有的 `local_secure` 钱包不会被转换。升级前请先阅读 [常见问题](./FAQ.md#upgrade-from-2x)。
 :::
 
 ---
 
-## 方式二：命令行手动创建（最精细控制）
-
-如果你想自己掌控每个步骤，或者你的环境不支持对话式安装，可以按下面的命令行流程手动完成。
-
-### 第一步：安装并初始化钱包
+## 第一步：安装
 
-#### 1.1 准备环境：安装 Node.js
+### 1.1 准备环境：安装 Node.js
 
-Agent-wallet 需要你的电脑里有 Node.js（这是一个运行环境，版本需 >= 18；建议安装当前的 LTS 版本）。
+Agent-wallet 和 wallet-cli（路径 A）都要求 **Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+**，即 2026 年 10 月的安全更新版本（已发布的 agent-wallet `3.0.0` 仍声明 `>=18`；wallet-cli `4.15.1` 及下一版 agent-wallet 声明了此范围）。安装最新的 LTS 即可满足。
 
 打开终端（Mac 用户按 `Command + 空格` 搜索"终端"），输入：
 
@@ -72,18 +37,18 @@ Agent-wallet 需要你的电脑里有 Node.js（这是一个运行环境，版
 node -v
 ```
 
-- **如果输出 `v18.x.x` 或更高数字：** 太棒了，直接跳到 1.2！
-- **如果没有输出或报错：** 别慌，去 **[Node.js 官方网站](https://nodejs.org)** 下载最新的 **LTS** 安装包，像装普通软件一样双击安装，一路"下一步"即可。装完后关掉终端重新打开，再输入 `node -v` 确认。
+- **如果显示 `v22.23.4`+（22.x）、`v24.22.1`+（24.x）或 `v26.12.1`+：** 很好，直接跳到 1.2！
+- **如果没有输出、报错或版本较旧：** 前往 **[Node.js 官网](https://nodejs.org)** 下载最新的 **LTS** 安装包。装完后关闭并重新打开终端，再执行一次 `node -v` 确认。
 
 <details>
-<summary>开发者首选：使用 nvm 安装（小白请跳过）</summary>
+<summary>开发者推荐：通过 nvm 安装（新手可跳过）</summary>
 
 ```bash
 # 1. 安装 nvm（已有可跳过）
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
 # 2. 重新加载终端配置
-source ~/.bashrc   # zsh 用户改成 source ~/.zshrc
+source ~/.bashrc   # zsh 用户：source ~/.zshrc
 
 # 3. 安装并切换到当前的 Node.js LTS
 nvm install --lts && nvm use --lts
@@ -91,141 +56,141 @@ nvm install --lts && nvm use --lts
 
 </details>
 
-#### 1.2 安装 Agent-wallet
+### 1.2 安装 Agent-wallet
 
 ```bash
 npm install -g @bankofai/agent-wallet
 ```
 
-验证安装成功：
+验证安装：
 ```bash
 agent-wallet --help
 ```
 
-看到帮助信息就说明安装好了。
+看到 `Usage: agent-wallet <command> [options]` 以及后面的命令列表，就说明装好了。
 
-#### 1.3 创建你的 Agent-wallet 钱包
-
-运行：
-```bash
-agent-wallet start
-```
-
-系统会引导你初始化 **Agent-wallet 钱包**。整个过程是交互式的——跟着提示走就行：
-
-```
-? Quick start type: local_secure  — Encrypted key stored locally (recommended)
-Password requirements: at least 8 characters, with uppercase, lowercase, digit, and special character. e.g. Abc12345!@
-New Master Password (press Enter to auto-generate a strong password):
+---
 
-Wallet initialized!
-Wallet ID (e.g. my_wallet_1) (default_secure):
-? Import source: generate  — Generate a new random private key
+## 第二步：创建钱包
 
-Wallets:
-┌────────────────┬──────────────┐
-│ Wallet ID      │ Type         │
-├────────────────┼──────────────┤
-│ default_secure │ local_secure │
-└────────────────┴──────────────┘
+<Tabs>
+<TabItem value="wallet-cli" label="路径 A：wallet-cli（推荐）" default>
 
-🔑 Your master password: <此处会显示你的专属密码>
-⚠️ Keep this password safe. You'll need it for signing and other operations.
-   （只有在你直接回车、由向导自动生成密码时才会出现这一行。）
+**2.1 安装兼容版本的 wallet-cli**（Agent-wallet 3.x 支持 `>=4.13.0 <5.0.0`）：
 
-Active wallet: default_secure
+```bash
+npm install -g '@tron-walletcli/wallet-cli@^4.13.0'
+wallet-cli --version
 ```
 
-:::caution 主密码 = 你所有资产的唯一钥匙
-这个密码是解开所有私钥的唯一凭证。**忘了就找不回来——我们也没有备份，没有后门，神仙难救。**
-
-请现在就做这件事：
-1. 打开你的密码管理器（1Password、Bitwarden 等）
-2. 新建一条记录，把主密码存进去
-3. 不要截图，不要记在桌面便签上，不要发给自己的微信
-:::
+**2.2 创建（或导入）wallet-cli 账户。** 首次使用时 wallet-cli 会初始化 `~/.wallet-cli`，并在终端中让你设置它的主密码：
 
----
+```bash
+wallet-cli create --label main-1 -o json
+```
 
-### 第二步：把密码"喂"给 AI 代理（极其重要！）
+如果要恢复已有钱包，改为执行 `wallet-cli import mnemonic --label main-1 -o json` 或 `wallet-cli import private-key --label main-1 -o json`。助记词、私钥和密码都通过隐藏提示输入——绝不要放进命令参数、环境变量、日志或聊天里。备份方法见 [wallet-cli 快速开始](../wallet-cli/quickstart.md)。
 
-为了让你的 AI 代理能自动使用你的钱包，你必须把密码配置到它的运行环境中。请根据你的电脑系统，选择对应的标签页，**无脑复制执行**即可。
+**2.3 写一个密码脚本**，这样 wallet-cli 密码不会落到 Agent-wallet 的配置里。脚本只负责把密码打印到 stdout——例如使用 1Password CLI：
 
-#### 2.1 保存并使密码生效
+```bash
+#!/bin/sh
+op read 'op://Private/wallet-cli-password/password'
+```
 
-<Tabs>
-<TabItem value="mac" label="Mac 用户 (Zsh)" default>
+保存（例如保存为 `~/bin/fetch-wallet-cli-password.sh`），并用 `chmod +x` 赋予可执行权限。
 
-**第 1 步：** 用编辑器打开 `~/.zshrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）：
+**2.4 把账户连结到 Agent-wallet：**
 
 ```bash
-open -e ~/.zshrc
+agent-wallet start wallet_cli \
+  --wallet-id my_cli_wallet \
+  --account main-1 \
+  --cli-password-exec /absolute/path/to/fetch-wallet-cli-password.sh
 ```
 
-在文件末尾添加这一行，保存并关闭：
+Agent-wallet 会先确认 wallet-cli 版本兼容、账户存在（这一步不索要密码），然后保存规范的账户 ID。输出结尾应为：
 
-```bash
-export AGENT_WALLET_PASSWORD='你的主密码'
 ```
+Wallet 'my_cli_wallet' created:
+...
+Active wallet: my_cli_wallet
 
-**第 2 步：** 回到终端，复制这条命令，粘贴回车，让配置立即生效：
-
-```bash
-source ~/.zshrc
+Quick guide:
+...
 ```
 
-:::tip 为什么不用 echo 命令？
-`echo "export ..." >> ~/.zshrc` 虽然更快捷，但你的真实密码会被逐字记录在 Shell 的历史文件（`.zsh_history` / `.bash_history`）中。这些历史文件常常会被安全扫描器、备份工具、AI 编程助手抓取——恰恰是 Agent-wallet 要防范的风险。用编辑器直接编辑配置文件，密码不会出现在任何命令历史中。
+:::tip 不用脚本、直接输入密码
+运行 `agent-wallet start wallet_cli` 时不带 `--cli-password-exec`，在密码来源提示中选择 `direct`。密码会以明文字符串保存在 `wallets_config.json`（文件权限 `0600`）中。`inspect` 始终显示为 `[redacted]`，但任何能读取该文件的程序都能读到密码。在命令行中传 `--cli-password <密码>` 会被拒绝。
 :::
 
 </TabItem>
-<TabItem value="linux" label="Linux 用户 ">
-
-**第 1 步：** 用编辑器打开 `~/.bashrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）：
+<TabItem value="raw-secret" label="路径 B：raw_secret（仅限开发）">
 
-```bash
-nano ~/.bashrc
-```
+:::danger 明文存储
+`raw_secret` 会把你的私钥或助记词**不加密**地写入 `~/.agent-wallet/wallets_config.json`。任何能读取你主目录文件的程序都能读到它。只能使用一次性测试私钥。
+:::
 
-在文件末尾添加这一行，保存并关闭（nano 中按 `Ctrl + O` 保存，`Ctrl + X` 退出）：
+Agent-wallet 3.x 不生成私钥——请导入一把已有的测试私钥：
 
 ```bash
-export AGENT_WALLET_PASSWORD='你的主密码'
+agent-wallet start raw_secret --wallet-id dev_wallet
 ```
 
-**第 2 步：** 回到终端，复制这条命令，粘贴回车，让配置立即生效：
+按提示选择 `private_key`（或 `mnemonic`）并粘贴。预期输出：
 
-```bash
-source ~/.bashrc
 ```
-
+Warning: Raw secret material will be stored in plaintext in wallets_config.json.
+...
+Wallet 'dev_wallet' created:
+...
+Active wallet: dev_wallet
+
+Quick guide:
+...
+```
 
 </TabItem>
 </Tabs>
 
+---
 
+## 第三步：检查钱包
 
+**查看地址**（不签名，也不需要密码）：
 
+```bash
+agent-wallet resolve-address
+```
 
-:::caution 密码有特殊字符？千万不要动单引号！
-自动生成的密码经常含有 `$`、`!` 等特殊字符。上面的命令已经用了单引号包裹密码，**直接替换引号内的文字就好，千万不要改成双引号**，否则 shell 会把密码"消化"掉：
+从列表中选择你的钱包。`raw_secret` 钱包，或同时拥有两条链地址的 wallet-cli 账户，会打印 EVM 和 TRON 两个地址：
 
-```bash
-# ✅ 正确 — 单引号，密码原样保存
-export AGENT_WALLET_PASSWORD='P@ss$w0rd!'
+```
+Wallet  my_cli_wallet
+Type    wallet_cli
 
-# ❌ 错误 — 双引号，$w0rd 被 shell 展开为空字符串，密码静默出错
-export AGENT_WALLET_PASSWORD="P@ss$w0rd!"  # 实际值变为 "P@ss!"
+Addresses
+EVM   0x...
+TRON  T...
 ```
-:::
 
-#### 2.2 重启你的 AI 代理后台服务
+**在测试网上签一次名。** 每条签名命令都需要用 `-n` 指定规范网络：
 
-:::danger 这一步很多人忘了，结果 AI 代理死活读不到密码！
-因为你刚才新存了密码，而正在后台运行的 AI 助手还没刷新——它还是个"瞎子"！只有关掉它重新启动，它才能"看"到你的新密码。
-:::
+```bash
+agent-wallet sign typed-data '{"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"chainId","type":"uint256"}],"Message":[{"name":"contents","type":"string"}]},"primaryType":"Message","domain":{"name":"AgentWallet","chainId":97},"message":{"contents":"hello"}}' -n eip155:97
+```
+
+成功时会打印 `Signature: <hex>`。
+
+---
+
+## 第四步：让代理用上这个钱包
+
+3.x **没有需要设置的密码环境变量**。任何使用 Agent-wallet SDK 的工具或代码，都会自动从 `~/.agent-wallet/wallets_config.json` 解析当前激活的钱包。
 
-不管你现在是否正开着 AI 代理的后台服务，请务必将它**关闭**，然后在刚才执行过命令的终端窗口里，**重新启动**它。
+- 如果你用 `--dir` 把钱包放在了别处，请在代理运行的环境中把 `AGENT_WALLET_DIR` 设为该目录。
+- 如果你使用了 `--cli-password-exec`，请确保脚本在那个环境里同样能运行（例如代理运行所用的用户也已登录 1Password CLI）。
+- 修改环境变量后，重启你的 AI 代理后台服务使其生效。
 
 ---
 
@@ -233,8 +198,8 @@ export AGENT_WALLET_PASSWORD="P@ss$w0rd!"  # 实际值变为 "P@ss!"
 
 | 我想… | 去这里 |
 | :--- | :--- |
-| 喜欢敲命令？ | [CLI 命令行手册](./Developer/CLI-Reference.md) |
-| 要开发应用？ | [SDK 接入指南](./Developer/SDK-Guide.md) |
-| 找现成代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) |
-| 了解安全设计原理 | [简介](./Intro.md) |
-| 查看常见问题 | [FAQ](./FAQ.md) |
+| 更喜欢命令行？ | [CLI 命令行手册](./Developer/CLI-Reference.md) |
+| 要自己写代理？ | [SDK 接入指南](./Developer/SDK-Guide.md) |
+| 想找现成的代码？ | [完整代码示例](./Developer/SDK-Cookbook.md) |
+| 了解安全设计 | [简介](./Intro.md) |
+| 查看常见问题 | [常见问题](./FAQ.md) |
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md
index eb324041..30a308ae 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md
@@ -17,11 +17,11 @@ BANK OF AI SKILLS 可以操作**真实的链上资产**。区块链交易一旦
 | 技能 | 能干什么 | 需要什么钥匙/密码？ |
 | :--- | :--- | :--- |
 | **wallet-cli** | 通过锁定版 `@tron-walletcli/wallet-cli@4.14.0` 直接完成 TRON 钱包操作——转账、质押、投票、合约、签名、链上查询（机器可读 JSON） | wallet-cli 本地管理的钱包；Agent 执行时密码仅经 stdin 传入 |
-| **sunswap**<br/>安装后目录名 `sunswap-dex-trading` | 查价、报价、换币，管理 V2/V3/V4 流动性池 | 查询不需要；交易需要钱包凭证 |
-| **sunpump-agent-skill**<br/>安装后目录名 `sunpump-meme-token-toolkit` | SunPump meme 币：一句话发币（服务端创建，无需钱包），查行情/排行/持有人/钱包持仓，买卖 meme 币（根据代币是否已发射自动选择兑换路线，仅 TRON 主网） | 只读查询与发币免配置；链上买卖需钱包凭证 |
-| **sunperp-skill**<br/>安装后目录名 `sunperp-perpetual-futures-trading` | 看行情、开仓、平仓、提现 | 看行情不需要；交易需要 SunPerp 密钥；提现还需要 `TRON_PRIVATE_KEY` 用于签署确认 |
-| **tronscan-skill**<br/>安装后目录名 `tronscan-data-lookup` | 查账户、交易、代币、区块、全网数据 | 可选 TronScan API 密钥——不配时请求走无密钥的 BofAI 代理，可能被限流 |
-| **usdd-skill**<br/>安装后目录名 `usdd-just-protocol` | USDD 稳定币——PSM 1:1 USDT ↔ USDD 兑换、金库查询、余额查看 | 查询不需要；PSM 兑换需要钱包凭证 |
+| **sunswap**<br/>安装后目录名 `sunswap-dex-trading` | 查价、报价、换币，管理 V2/V3/V4 流动性池 | 查询不需要；交易需要 `TRON_PRIVATE_KEY`（或 `TRON_MNEMONIC` / `AGENT_WALLET_PASSWORD`）；可选 `TRON_NETWORK`、`TRONGRID_API_KEY` |
+| **sunpump-agent-skill**<br/>安装后目录名 `sunpump-meme-token-toolkit` | SunPump meme 币：一句话发币（服务端创建，无需钱包），查行情/排行/持有人/钱包持仓，买卖 meme 币（根据代币是否已发射自动选择兑换路线，仅 TRON 主网） | 只读查询与发币免配置；链上买卖需 `TRON_PRIVATE_KEY`（或 `TRON_MNEMONIC` / `AGENT_WALLET_PASSWORD`）；可选 `TRONGRID_API_KEY`、`SUNPUMP_API_BASE_URL`，以及 `TRON_NETWORK`（如设置必须为 `mainnet`） |
+| **sunperp-skill**<br/>安装后目录名 `sunperp-perpetual-futures-trading` | 看行情、开仓、平仓、提现 | 看行情不需要；交易需要 `SUNPERP_ACCESS_KEY` 和 `SUNPERP_SECRET_KEY`；提现还需要 `TRON_PRIVATE_KEY` 用于签署确认（设置 `TRONGRID_API_KEY` 只会切换 RPC 节点） |
+| **tronscan-skill**<br/>安装后目录名 `tronscan-data-lookup` | 查账户、交易、代币、区块、全网数据 | 可选 `TRONSCAN_API_KEY`——不配时请求走无密钥的 BofAI 代理，可能被限流 |
+| **usdd-skill**<br/>安装后目录名 `usdd-just-protocol` | USDD 稳定币——PSM 1:1 USDT ↔ USDD 兑换、金库查询、余额查看 | PSM / 金库信息不需要；余额查看（未传 `--address` 时）和 PSM 兑换（含 `--dry-run`）需要 `TRON_PRIVATE_KEY`；可选 `TRON_NETWORK`、`TRONGRID_API_KEY` |
 
 其中 5 个技能安装后的目录名与仓库目录名不同——**安装后的那个名字**才是你在 `~/.agents/skills` 里看到的名字，也是让助手读取技能文件时要引用的名字。
 
@@ -60,7 +60,7 @@ wallet-cli 是官方钱包与 CLI 接入入口；其他 Skill 和服务端可能
 :::
 
 :::caution 密码与钱包管理的硬性边界
-Agent 执行时，钱包密码只能通过 `--password-stdin` 从受信来源传入——AI 不会把密码放进命令行参数、环境变量或对话里，也永远不会让你在聊天中粘贴密码、助记词或私钥。`import` / `backup` / `delete` / `change-password` 这几类根钱包管理命令**按技能策略仅限你本人执行**：即使你给出确认，AI 也不会代跑。这是技能层面的拒绝，而非 CLI 的强制锁——CLI 自身只对 `import` 与 `change-password` 强制要求 TTY，`backup` 甚至公开提供了 `--password-stdin` 的用法。主网上任何动钱的操作都会先预览、再等你明确确认。
+Agent 执行时，钱包密码只能通过 `--password-stdin` 从受信来源传入——AI 不会把密码放进命令行参数、环境变量或对话里，也永远不会让你在聊天中粘贴密码、助记词或私钥。`import` / `backup` / `delete` / `change-password` 这几类根钱包管理命令**按技能策略仅限你本人执行**：即使你给出确认，AI 也不会代跑。这是技能层面的拒绝，而非 CLI 的强制锁——CLI 自身只对 `import mnemonic` / `import private-key` / `import keystore`（`import watch` 和 `import ledger` 不需要）、`change-password`，以及不带 `--yes` 的 `delete` 强制要求 TTY，`backup` 甚至公开提供了 `--password-stdin` 的用法。主网上任何动钱的操作都会先预览、再等你明确确认。
 :::
 
 注意：wallet-cli 的规范网络标识是十进制 CAIP-2 ID——`tron:728126428`（主网）、`tron:3448148188`（Nile）、`tron:2494104990`（Shasta）；`tron:mainnet` / `tron:nile` / `tron:shasta` 仅作为输入别名被接受。这与 x402 协议元数据中的十六进制标识符（`tron:0x…`）不同；`wallet-cli x402` 仍使用 wallet-cli 的网络标识。
@@ -71,7 +71,7 @@ Agent 执行时，钱包密码只能通过 `--password-stdin` 从受信来源传
 
 ## sunswap {#sunswap}
 
-想在 SunSwap 上换币、查行情、管理流动性？对 AI 说下面的话就行。本技能基于 `@sun-protocol/sun-cli`（固定 1.2.2 版），同时支持换币、V2 AMM、V3 集中流动性以及带 hooks 的 V4 池子。
+想在 SunSwap 上换币、查行情、管理流动性？对 AI 说下面的话就行。本技能基于 `@sun-protocol/sun-cli`（固定 1.2.2 版，需自行安装：`npm install -g @sun-protocol/sun-cli@1.2.2`），同时支持换币、V2 AMM、V3 集中流动性以及带 hooks 的 V4 池子。
 
 **绝对安全，只看不花钱：**
 
@@ -111,7 +111,7 @@ V3 仅支持 `100`、`500`、`3000`、`10000` 四档费率（对应 0.01% / 0.05
 
 ## sunpump-agent-skill {#sunpump-agent-skill}
 
-想玩 SunPump 上的 meme 币？这个技能基于 `@sun-protocol/sun-cli`（固定 1.2.2 版），帮你发币、查行情、做研究、买卖 meme 币。发币（`sun sunpump launch`）在**服务端完成、无需钱包**：给出名称、符号、描述和 logo，由平台签名并广播创建交易。交易时它会**自动判断交易路径**：还没在 SunSwap V2 上创建交易对的「发射前」代币走 `sun sunpump buy/sell`，已在 SunSwap V2 建好交易对的「发射后」代币走普通 `sun swap`——下单前 AI 会先用 `sunpump state` 帮你确认走哪条路。**sunpump-agent-skill 的所有功能（查询和交易）都只支持 TRON 主网，不支持测试网。**
+想玩 SunPump 上的 meme 币？这个技能基于 `@sun-protocol/sun-cli`（固定 1.2.2 版，需自行安装：`npm install -g @sun-protocol/sun-cli@1.2.2`），帮你发币、查行情、做研究、买卖 meme 币。发币（`sun sunpump launch`）在**服务端完成、无需钱包**：给出名称、符号、描述和 logo，由平台签名并广播创建交易。交易时它会**自动判断交易路径**：还没在 SunSwap V2 上创建交易对的「发射前」代币走 `sun sunpump buy/sell`，已在 SunSwap V2 建好交易对的「发射后」代币走普通 `sun swap`——下单前 AI 会先用 `sunpump state` 帮你确认走哪条路。**sunpump-agent-skill 的所有功能（查询和交易）都只支持 TRON 主网，不支持测试网。**
 
 **绝对安全，只看不花钱：**
 
@@ -150,7 +150,7 @@ meme 币波动剧烈、容易被庄家控盘。AI 在给你看代币信息时会
 :::
 
 :::tip 关于发币（launch）
-发币走 SunPump agent 端点，由平台签名并广播创建交易，**无需钱包**。名称、符号、描述必填；强烈建议提供 logo（不带 logo 的发币请求可能被 API 拒绝）。成功后 AI 会报告新代币的合约地址和创建交易哈希。与其它 SunPump 操作一样，发币**仅支持主网**——传入任何非主网 `--network` 都会在执行前被直接拒绝，连 `--dry-run` 也不例外。
+发币走 SunPump agent 端点，由平台签名并广播创建交易，**无需钱包**。名称、符号、描述必填；Skill 会在发币前要求提供 logo 图片，因为不带 logo 的发币请求经常以服务端错误 `Invoke third part error` 失败。成功后 AI 会报告新代币的合约地址和创建交易哈希。与其它 SunPump 操作一样，发币**仅支持主网**——传入任何非主网 `--network` 都会在执行前被直接拒绝，连 `--dry-run` 也不例外。
 :::
 
 ---
@@ -179,7 +179,7 @@ meme 币波动剧烈、容易被庄家控盘。AI 在给你看代币信息时会
 
 > 被套牢了？ "帮我看看 BTC 现在的资金费率，建议做多还是做空？"
 
-> 想控制风险？ "帮我把 BTC-USDT 的杠杆降到 5 倍，止损调到 3%。"
+> 想控制风险？ "帮我把 BTC-USDT 的杠杆降到 5 倍，然后小仓开一个 BTC-USDT 多单，止损 3%。"（止损在开仓时设置；Skill 没有修改已有仓位止损的命令）
 
 > 想了解全局？ "帮我列出所有可交易的永续合约，按 24h 成交量排序。"
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md
index a748b526..eedddcc5 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md
@@ -33,7 +33,7 @@
 **最简单的解决办法：** 去 [Node.js 官网](https://nodejs.org/) 下载最新的 LTS 版本（就像安装普通软件一样，一路点"下一步"），装完后重新试一次。
 
 :::tip 已经装了 Node.js 但还是报错？
-在终端运行 `node --version` 查看版本号。技能需要 **v20 或更高版本**。如果版本太低，去官网重新下载最新版覆盖安装即可。
+在终端运行 `node --version` 查看版本号。技能需要 **22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+**。如果版本太低，去官网重新下载最新版覆盖安装即可。
 :::
 
 ### 怎么确认技能安装成功了？
@@ -116,7 +116,7 @@ AI 的应对策略是：先给你看报价，你确认后在实际提交前会
 
 ### 哪些 AI 工具能用这些技能？
 
-安装器覆盖了相当广的一批编程助手与 AI 客户端——Claude Code、Cursor、Codex、Cline、Gemini CLI、Amp、Zed 等等——对有独立技能目录的工具建立软链接，没有的则直接复制文件。其中 **OpenClaw** 依然最省心。任何能读取本地技能文件的 AI 助手也都能用：让它读 `~/.agents/skills/<技能名>/SKILL.md` 即可。
+安装器覆盖了相当广的一批编程助手与 AI 客户端——Claude Code、Cursor、Codex、Cline、Gemini CLI、Amp、Zed 等等——对有独立技能目录的工具建立软链接，没有的则直接复制文件。OpenClaw 一键安装器处于暂停维护状态，不作为新用户推荐入口。任何能读取本地技能文件的 AI 助手也都能用：让它读 `~/.agents/skills/<技能名>/SKILL.md` 即可。
 
 ---
 
@@ -136,12 +136,14 @@ AI 的应对策略是：先给你看报价，你确认后在实际提交前会
 rm -rf ~/.agents/skills/sunswap-dex-trading
 ```
 
-**更新：** 重新运行安装命令（保留 `-g`，更新的才是全局那份），会自动更新所有技能到最新版本。
+**更新：** 重新运行安装命令（保留 `-g`，更新的才是全局那份），并在弹出的列表里选中要更新的技能，它们会按 `main` 分支上的最新稳定版重新安装。重装会替换所选技能的整个目录，之后请在 SunPerp、TronScan、USDD 的目录里重新运行 `npm install`。
 
 ```bash
-npx skills add https://github.com/BofAI/skills -y -g
+npx skills add https://github.com/BofAI/skills/tree/main -g
 ```
 
+不要加 `-y`：它会连"安装到哪些 Agent"这一步也跳过，skills CLI 会把 Skill 装进本机检测到的所有 Agent（加上通用目录）并覆盖已有副本；一个 Agent 都没检测到时则装进它认识的全部 79 个 Agent（skills 1.7.4）。只装到某个 Agent、跳过选择 Agent 这一步，用 `-a <agent>`，例如 `-a claude-code`；选择技能和 `Proceed with installation?` 仍会询问。输出里的 `✗ … does not support global skill installation` 指的是没有全局 Skill 目录的 Agent，其余 Agent 均正常安装。
+
 ---
 
 ## 概念解释（给好奇的你）
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md
index b8fa17f9..b6de457a 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md
@@ -45,7 +45,7 @@
 2. **前置排雷：** "您给 Permit2 的 USDT 授权额度不够这次兑换——兑换会在成交前自动补发这笔授权。"
 3. **精准报价：** "按最新价格，50 USDT 约可兑换 350 TRX，我已经帮您设置好 1% 的防夹滑点。是否现在买入？"
 
-在这个场景里，你只说了一句话，而 Skill 默默在后台帮你兜底了"确认余额够付 → 校验交易对与滑点 → 拉取最新报价 → 把账单摊给你看并等你确认"这一整套步骤，其中一次性的 TRC-20 授权由底层 CLI 自动完成。这就是**"普通聊天 AI"和"专业 Web3 管家"**之间最直观的降维打击。
+在这个场景里，你只说了一句话，而 Skill 默默在后台帮你兜底了"确认余额够付 → 校验交易对与滑点 → 拉取最新报价 → 把账单摊给你看并等你确认"这一整套步骤，其中给 Permit2 的 TRC-20 授权（当前额度不够时，按本次兑换金额授权）由底层 CLI 自动完成。这就是**"普通聊天 AI"和"专业 Web3 管家"**之间最直观的降维打击。
 
 ---
 
@@ -78,7 +78,7 @@
 
 - **👶 我是链上小白：** 太好了！你再也不用去学怎么看复杂的 K 线图、怎么算滑点和 Gas 费了。直接用大白话提要求，AI 把处理好的结果直接喂给你。
 - **🕴️ 我是交易老手：** 盯盘太累？让 AI 帮你批量监控数据、计算收益率，省下大把精力。你只需专注策略，把枯燥的执行全扔给 AI。
-- **🍉 我只是想吃瓜玩玩：** 完全没问题！"链上数据侦探"等纯读取技能 100% 免费，不用连钱包也能畅通无阻，零风险体验 Web3 魔法。
+- **🍉 我只是想吃瓜玩玩：** 完全没问题！[tronscan-skill](./BANKOFAISkill.md#tronscan-skill) 等纯读取技能 100% 免费，不用连钱包也能畅通无阻，零风险体验 Web3 魔法。
 
 ---
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md
index 675853e7..0bbab8b0 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/QuickStart.md
@@ -6,7 +6,7 @@ description: "按需安装 Skills，并使用 wallet-cli 配置官方钱包入
 
 # Skills 快速入门
 
-需要 Node.js 20 或更新版本。选择所需 Skill，不再默认安装所有旧钱包和入门助手。
+需要 Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+。选择所需 Skill，不再默认安装所有旧钱包和入门助手。
 
 ## 安装 wallet-cli
 
@@ -22,26 +22,31 @@ wallet-cli --version
 ## 选择 Skill
 
 ```bash
-npx skills add https://github.com/BofAI/skills --skill wallet-cli -g
+npx skills add https://github.com/BofAI/skills/tree/main --skill wallet-cli -g
 ```
 
-`npx skills add` 只安装 Skill 定义，不安装外部 CLI。自 Skills 3.0.0 起，`wallet-cli` Skill 固定依赖 `@tron-walletcli/wallet-cli@4.14.0`，与上面安装的版本一致。
+`npx skills add` 只安装 Skill 定义，不安装外部 CLI。自 Skills 3.0.0 起，`wallet-cli` Skill 固定依赖 `@tron-walletcli/wallet-cli@4.14.0`，与上面安装的版本一致。请保留 `/tree/main` 后缀：仓库默认分支是 `develop`，其中可能包含尚未发布、且固定到其他 CLI 版本的 Skill。
 
 需要 DeFi 与数据业务（SunSwap、SunPump、SunPerp、TronScan、USDD）时，使用交互式选择安装：
 
 ```bash
-npx skills add https://github.com/BofAI/skills -g
+npx skills add https://github.com/BofAI/skills/tree/main -g
 ```
 
 只选择所需 Skills，并查看各自的依赖和凭据要求。SunSwap、SunPump、SunPerp、USDD 的现有实现不应被假定已经全部迁移到 wallet-cli。
 
+`npx skills add` 不会做的两步，需要自己完成：
+
+- **sun-cli**：SunSwap 和 SunPump Skill 要求版本恰好为 1.2.2（用 `sun --version` 检查）：`npm install -g @sun-protocol/sun-cli@1.2.2`。
+- **Node 依赖**：SunPerp、TronScan、USDD Skill 需要在各自安装目录里执行 `npm install`，例如 `cd ~/.agents/skills/tronscan-data-lookup && npm install`。
+
 ## 配置及调用
 
 按 [Wallet CLI 快速入门](/zh-Hans/wallet-cli/quickstart/)在本地配置和选择账户。不要把密码、助记词、私钥粘贴到聊天中。
 
-- 基础钱包与 TRON 操作：使用 `wallet-cli` Skill。
+- 基础钱包与 TRON 操作：使用 `wallet-cli` Skill。该 Skill 本身只覆盖 TRON 钱包流程；`x402`、`bai`、`8004` 是 wallet-cli 的命令组，不在 Skill 范围内，请按下面各自的参考文档使用。
 - x402 支付：使用 [wallet-cli x402](/zh-Hans/wallet-cli/command-reference/)。
-- B.AI 充值与记录：查看 `wallet-cli bai --json-schema -o json`，并配置 B.AI API Key。
+- B.AI 充值与记录：用 `wallet-cli bai --help` 查看 `bai` 下的命令（单个命令的输入 schema 用 `wallet-cli bai recharge --json-schema`；`wallet-cli bai --json-schema` 返回的是完整命令目录，而不只是 `bai`），并配置 B.AI API Key。
 - DeFi 与数据业务：按对应 Skill 的说明配置。
 
 Skills 3.0.0 已删除 `bankofai-guide`、`agent-wallet`、`x402-payment` 和 `recharge-skill`，当前技能列表见[技能大全](/zh-Hans/McpServer-Skills/SKILLS/BANKOFAISkill/)。OpenClaw 一键安装器处于暂停维护状态，不作为新用户推荐入口。
diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg
index 6c8b41de..1cb223eb 100644
--- a/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg
+++ b/static/img/diagrams/agent-wallet-x402-permit-flow.light.svg
@@ -26,8 +26,8 @@
   <rect width="880" height="635" rx="14" fill="url(#grid)"/>
   <rect x="0.5" y="0.5" width="879" height="634" rx="14" fill="none" stroke="#e2e8f0"/>
   <circle cx="28" cy="33" r="6" fill="#7c3aed"/>
-  <text x="46" y="39" fill="#0f172a" font-size="17" font-weight="700">x402 PaymentPermit signing</text>
-  <text x="46" y="60" fill="#64748b" font-size="11">Sign first, verify to proceed — the agent never waits for on-chain confirmation.</text>
+  <text x="46" y="39" fill="#0f172a" font-size="17" font-weight="700">x402 authorization signing</text>
+  <text x="46" y="60" fill="#64748b" font-size="11">Sign first; content is returned after verification and settlement.</text>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="440.0" y="113" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Server returns 402</text>
@@ -38,7 +38,7 @@
   <line x1="440.0" y1="143" x2="440.0" y2="179" stroke="#7c3aed" stroke-width="1.5" marker-end="url(#ah-violet)"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="440.0" y="208" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Agent builds PaymentPermit</text>
+  <text x="440.0" y="208" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Agent builds the authorization</text>
   <text x="440.0" y="227" fill="#64748b" font-size="10" text-anchor="middle">TransferWithAuthorization struct, EIP-712 format</text>
   <circle cx="150" cy="203" r="13" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="150" y="207" fill="#0f172a" font-size="11" font-weight="700" text-anchor="middle">2</text>
@@ -62,8 +62,8 @@
   <line x1="440.0" y1="428" x2="440.0" y2="464" stroke="#059669" stroke-width="1.5" marker-end="url(#ah-emerald)"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="440.0" y="493" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Server verifies and responds</text>
-  <text x="440.0" y="512" fill="#64748b" font-size="10" text-anchor="middle">Content returned only if the signature checks out</text>
+  <text x="440.0" y="493" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Server verifies, settles, responds</text>
+  <text x="440.0" y="512" fill="#64748b" font-size="10" text-anchor="middle">Content returned only after verification and settlement succeed</text>
   <circle cx="150" cy="488" r="13" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="150" y="492" fill="#0f172a" font-size="11" font-weight="700" text-anchor="middle">5</text>
   <text x="724" y="492" fill="#7c3aed" font-size="10" font-weight="600">SERVER</text>
diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.svg
index 956ed10c..d9f72a7e 100644
--- a/static/img/diagrams/agent-wallet-x402-permit-flow.svg
+++ b/static/img/diagrams/agent-wallet-x402-permit-flow.svg
@@ -26,8 +26,8 @@
   <rect width="880" height="635" rx="14" fill="url(#grid)"/>
   <rect x="0.5" y="0.5" width="879" height="634" rx="14" fill="none" stroke="#1e293b"/>
   <circle cx="28" cy="33" r="6" fill="#a78bfa"/>
-  <text x="46" y="39" fill="#f8fafc" font-size="17" font-weight="700">x402 PaymentPermit signing</text>
-  <text x="46" y="60" fill="#94a3b8" font-size="11">Sign first, verify to proceed — the agent never waits for on-chain confirmation.</text>
+  <text x="46" y="39" fill="#f8fafc" font-size="17" font-weight="700">x402 authorization signing</text>
+  <text x="46" y="60" fill="#94a3b8" font-size="11">Sign first; content is returned after verification and settlement.</text>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
   <text x="440.0" y="113" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Server returns 402</text>
@@ -38,7 +38,7 @@
   <line x1="440.0" y1="143" x2="440.0" y2="179" stroke="#a78bfa" stroke-width="1.5" marker-end="url(#ah-violet)"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
-  <text x="440.0" y="208" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Agent builds PaymentPermit</text>
+  <text x="440.0" y="208" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Agent builds the authorization</text>
   <text x="440.0" y="227" fill="#94a3b8" font-size="10" text-anchor="middle">TransferWithAuthorization struct, EIP-712 format</text>
   <circle cx="150" cy="203" r="13" fill="#1e293b" stroke="#a78bfa" stroke-width="1.5"/>
   <text x="150" y="207" fill="#f8fafc" font-size="11" font-weight="700" text-anchor="middle">2</text>
@@ -62,8 +62,8 @@
   <line x1="440.0" y1="428" x2="440.0" y2="464" stroke="#34d399" stroke-width="1.5" marker-end="url(#ah-emerald)"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
-  <text x="440.0" y="493" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Server verifies and responds</text>
-  <text x="440.0" y="512" fill="#94a3b8" font-size="10" text-anchor="middle">Content returned only if the signature checks out</text>
+  <text x="440.0" y="493" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Server verifies, settles, responds</text>
+  <text x="440.0" y="512" fill="#94a3b8" font-size="10" text-anchor="middle">Content returned only after verification and settlement succeed</text>
   <circle cx="150" cy="488" r="13" fill="#1e293b" stroke="#a78bfa" stroke-width="1.5"/>
   <text x="150" y="492" fill="#f8fafc" font-size="11" font-weight="700" text-anchor="middle">5</text>
   <text x="724" y="492" fill="#a78bfa" font-size="10" font-weight="600">SERVER</text>
diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg
index 583ae1d0..5271fa5d 100644
--- a/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg
+++ b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.light.svg
@@ -26,8 +26,8 @@
   <rect width="880" height="635" rx="14" fill="url(#grid)"/>
   <rect x="0.5" y="0.5" width="879" height="634" rx="14" fill="none" stroke="#e2e8f0"/>
   <circle cx="28" cy="33" r="6" fill="#7c3aed"/>
-  <text x="46" y="39" fill="#0f172a" font-size="17" font-weight="700">x402 PaymentPermit 签名</text>
-  <text x="46" y="60" fill="#64748b" font-size="11">先签名、验证通过再放行 —— Agent 无需等待链上确认。</text>
+  <text x="46" y="39" fill="#0f172a" font-size="17" font-weight="700">x402 授权签名</text>
+  <text x="46" y="60" fill="#64748b" font-size="11">先签名，验证并结算成功后才返回内容。</text>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="440.0" y="113" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">服务端返回 402</text>
@@ -38,7 +38,7 @@
   <line x1="440.0" y1="143" x2="440.0" y2="179" stroke="#7c3aed" stroke-width="1.5" marker-end="url(#ah-violet)"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="440.0" y="208" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Agent 构造 PaymentPermit</text>
+  <text x="440.0" y="208" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">Agent 构造授权</text>
   <text x="440.0" y="227" fill="#64748b" font-size="10" text-anchor="middle">TransferWithAuthorization 结构，EIP-712 格式</text>
   <circle cx="150" cy="203" r="13" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="150" y="207" fill="#0f172a" font-size="11" font-weight="700" text-anchor="middle">2</text>
@@ -58,12 +58,12 @@
   <text x="440.0" y="417" fill="#64748b" font-size="10" text-anchor="middle">签名作为支付凭证随请求发送</text>
   <circle cx="150" cy="393" r="13" fill="#ffffff" stroke="#059669" stroke-width="1.5"/>
   <text x="150" y="397" fill="#0f172a" font-size="11" font-weight="700" text-anchor="middle">4</text>
-  <text x="724" y="397" fill="#059669" font-size="10" font-weight="600">AGENT</text>
+  <text x="724" y="397" fill="#059669" font-size="10" font-weight="600">Agent</text>
   <line x1="440.0" y1="428" x2="440.0" y2="464" stroke="#059669" stroke-width="1.5" marker-end="url(#ah-emerald)"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="#ffffff"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.5"/>
-  <text x="440.0" y="493" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">服务端验证并响应</text>
-  <text x="440.0" y="512" fill="#64748b" font-size="10" text-anchor="middle">签名有效才返回内容</text>
+  <text x="440.0" y="493" fill="#0f172a" font-size="13" font-weight="600" text-anchor="middle">服务端验证、结算并响应</text>
+  <text x="440.0" y="512" fill="#64748b" font-size="10" text-anchor="middle">验证通过且结算成功才返回内容</text>
   <circle cx="150" cy="488" r="13" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5"/>
   <text x="150" y="492" fill="#0f172a" font-size="11" font-weight="700" text-anchor="middle">5</text>
   <text x="724" y="492" fill="#7c3aed" font-size="10" font-weight="600">服务端</text>
diff --git a/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg
index 8963c1f8..83b4b14e 100644
--- a/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg
+++ b/static/img/diagrams/agent-wallet-x402-permit-flow.zh.svg
@@ -26,8 +26,8 @@
   <rect width="880" height="635" rx="14" fill="url(#grid)"/>
   <rect x="0.5" y="0.5" width="879" height="634" rx="14" fill="none" stroke="#1e293b"/>
   <circle cx="28" cy="33" r="6" fill="#a78bfa"/>
-  <text x="46" y="39" fill="#f8fafc" font-size="17" font-weight="700">x402 PaymentPermit 签名</text>
-  <text x="46" y="60" fill="#94a3b8" font-size="11">先签名、验证通过再放行 —— Agent 无需等待链上确认。</text>
+  <text x="46" y="39" fill="#f8fafc" font-size="17" font-weight="700">x402 授权签名</text>
+  <text x="46" y="60" fill="#94a3b8" font-size="11">先签名，验证并结算成功后才返回内容。</text>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="88" width="540" height="55" rx="8" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
   <text x="440.0" y="113" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">服务端返回 402</text>
@@ -38,7 +38,7 @@
   <line x1="440.0" y1="143" x2="440.0" y2="179" stroke="#a78bfa" stroke-width="1.5" marker-end="url(#ah-violet)"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="183" width="540" height="55" rx="8" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
-  <text x="440.0" y="208" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Agent 构造 PaymentPermit</text>
+  <text x="440.0" y="208" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">Agent 构造授权</text>
   <text x="440.0" y="227" fill="#94a3b8" font-size="10" text-anchor="middle">TransferWithAuthorization 结构，EIP-712 格式</text>
   <circle cx="150" cy="203" r="13" fill="#1e293b" stroke="#a78bfa" stroke-width="1.5"/>
   <text x="150" y="207" fill="#f8fafc" font-size="11" font-weight="700" text-anchor="middle">2</text>
@@ -58,12 +58,12 @@
   <text x="440.0" y="417" fill="#94a3b8" font-size="10" text-anchor="middle">签名作为支付凭证随请求发送</text>
   <circle cx="150" cy="393" r="13" fill="#1e293b" stroke="#34d399" stroke-width="1.5"/>
   <text x="150" y="397" fill="#f8fafc" font-size="11" font-weight="700" text-anchor="middle">4</text>
-  <text x="724" y="397" fill="#34d399" font-size="10" font-weight="600">AGENT</text>
+  <text x="724" y="397" fill="#34d399" font-size="10" font-weight="600">Agent</text>
   <line x1="440.0" y1="428" x2="440.0" y2="464" stroke="#34d399" stroke-width="1.5" marker-end="url(#ah-emerald)"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="#0f172a"/>
   <rect x="170" y="468" width="540" height="55" rx="8" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
-  <text x="440.0" y="493" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">服务端验证并响应</text>
-  <text x="440.0" y="512" fill="#94a3b8" font-size="10" text-anchor="middle">签名有效才返回内容</text>
+  <text x="440.0" y="493" fill="#f8fafc" font-size="13" font-weight="600" text-anchor="middle">服务端验证、结算并响应</text>
+  <text x="440.0" y="512" fill="#94a3b8" font-size="10" text-anchor="middle">验证通过且结算成功才返回内容</text>
   <circle cx="150" cy="488" r="13" fill="#1e293b" stroke="#a78bfa" stroke-width="1.5"/>
   <text x="150" y="492" fill="#f8fafc" font-size="11" font-weight="700" text-anchor="middle">5</text>
   <text x="724" y="492" fill="#a78bfa" font-size="10" font-weight="600">服务端</text>

From a2d699ff3cb8c24a87d20079f540febeaa278697 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:02 +0800
Subject: [PATCH 06/13] docs(changelog): add Oct 21-27 entries to the changelog
 index

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 changelog/index.md                            | 119 +++++++++++++++++-
 .../current/index.md                          | 119 +++++++++++++++++-
 2 files changed, 236 insertions(+), 2 deletions(-)

diff --git a/changelog/index.md b/changelog/index.md
index 4fbd41fe..1db664c8 100644
--- a/changelog/index.md
+++ b/changelog/index.md
@@ -7,6 +7,110 @@ description: 'Product updates and announcements for BANK OF AI — all products,
 
 Product updates and announcements for BANK OF AI.
 
+<div className="changelog-entry">
+<div className="changelog-date">Oct 27, 2026</div>
+<div className="changelog-body">
+
+### Reverse audit: code features the docs had not covered
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- Facilitator error codes, 8004 subgraph defaults and contract revert reasons, Agent Wallet error codes and config schema, wallet-cli error codes and recharge rules, per-Skill setup steps and credentials, OpenClaw installer details, TRON MCP package and HTTP details. [x402](./x402/) · [8004](./8004/) · [Agent Wallet](./agent-wallet/) · [SKILLS](./skills/) · [OpenClaw](./openclaw-extension/) · [MCP](./mcp-server/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 25, 2026</div>
+<div className="changelog-body">
+
+### x402 docs aligned with SDK 2.1.0 and facilitator v2.2.2
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">x402</span><span className="changelog-tag">Fix</span></div>
+
+- The 2.1.0 package set on official `@x402/core` 2.28.0 (with `@bankofai/x402-tron-extensions` for TRON resource sponsoring), decimal TRON IDs, the official facilitator's 10-per-minute anonymous limit on both `/verify` and `/settle`, Nile resource sponsoring, and the remaining API Catalog CI rules. [Details](./x402/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 23, 2026</div>
+<div className="changelog-body">
+
+### Node.js requirements updated across products
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- Install pages now state the October 2026 security releases required by each project's source (published packages that still declare an older floor — agent-wallet `3.0.0` with `>=18`, TRON MCP Server `1.1.7` with `>=20` — are noted on their pages): Agent Wallet, wallet-cli, SKILLS, and OpenClaw Extension need Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+; the 8004 TypeScript SDK the same but only up to 26.x; TRON MCP Server needs 22.23.4+ or 24.22.1+ (source, `v1.1.8`; Node.js 26 is not supported; npm `1.1.7` declares `>=20`); the x402 SDK needs 24.22.1+. Both OpenClaw installers now check the full version before installing anything.
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 23, 2026</div>
+<div className="changelog-body">
+
+### 8004 docs aligned with SDK 1.2.1
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">8004</span><span className="changelog-tag">Fix</span></div>
+
+- Base Mainnet and Base Sepolia, canonical registration-v1 keys from `registerIPFS()`, the new TypeScript registry read APIs, and the 1.2.1 Node.js requirement. [Details](./8004/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 23, 2026</div>
+<div className="changelog-body">
+
+### OpenClaw Extension and TRON MCP Server docs matched to the code
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span></div>
+
+- OpenClaw: the installer still pins Skills `v1.5.15`, agent-wallet 2.3.1 and `chat.ainft.com` — the Sep 9 installer changes never shipped, and the docs now describe the real installer. [Details](./openclaw-extension/) TRON MCP Server: mainnet RPC fallback without an API key, tool and prompt details, and real wallet error texts. [Details](./mcp-server/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 22, 2026</div>
+<div className="changelog-body">
+
+### SKILLS 3.0.1 — Node.js security baseline
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">SKILLS</span></div>
+
+- The bundled Node.js Skills and the wallet-cli installer require Node.js `^22.23.4 || ^24.22.1 || >=26.12.1`. The `wallet-cli` Skill still pins `@tron-walletcli/wallet-cli@4.14.0`. [Details](./skills/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 21, 2026</div>
+<div className="changelog-body">
+
+### Agent Wallet docs rewritten for 3.0
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Agent Wallet</span><span className="changelog-tag">Breaking</span></div>
+
+- The Agent Wallet pages now follow 3.0.0: `wallet_cli`, `privy` and `raw_secret` wallets, exec-script credentials and exact CAIP-2 network IDs. `local_secure`, `AGENT_WALLET_PASSWORD` and the Python SDK are no longer covered. [Details](./agent-wallet/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">Oct 21, 2026</div>
+<div className="changelog-body">
+
+### SKILLS install command pinned to main
+
+<div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">SKILLS</span><span className="changelog-tag">Fix</span></div>
+
+- Install with `npx skills add https://github.com/BofAI/skills/tree/main -g` so the Skills match the documented wallet-cli version. [Details](./skills/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 28, 2026</div>
 <div className="changelog-body">
@@ -33,6 +137,19 @@ Product updates and announcements for BANK OF AI.
 </div>
 </div>
 
+<div className="changelog-entry">
+<div className="changelog-date">Sep 10, 2026</div>
+<div className="changelog-body">
+
+### Agent Wallet v3.0.0
+
+<div className="changelog-tags"><span className="changelog-tag">New Release</span><span className="changelog-tag">Agent Wallet</span><span className="changelog-tag">Breaking</span></div>
+
+- New `wallet_cli` wallet type; `local_secure`, the master password and `AGENT_WALLET_PASSWORD` removed; `signTransaction()` returns a typed artifact; `signRaw` / `signMessage` removed; low-level APIs move to `/advanced`. [Details](./agent-wallet/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">Sep 9, 2026</div>
 <div className="changelog-body">
@@ -41,7 +158,7 @@ Product updates and announcements for BANK OF AI.
 
 <div className="changelog-tags"><span className="changelog-tag">Docs</span><span className="changelog-tag">Fix</span><span className="changelog-tag">8004</span><span className="changelog-tag">Openclaw</span></div>
 
-- The 8004 guides are now internally consistent: one consistent `setWallet` call shape per SDK instead of four different ones, with the rules for how the new wallet's signature is supplied, no legacy TRON `chainId`, the network names the SDK actually accepts, and private keys read from environment variables. The Openclaw installer no longer pins a superseded skills tag and writes the correct BANK OF AI host. [8004 details](./8004/) · [Openclaw details](./openclaw-extension/)
+- The 8004 guides are now internally consistent: one consistent `setWallet` call shape per SDK instead of four different ones, with the rules for how the new wallet's signature is supplied, no legacy TRON `chainId`, the network names the SDK actually accepts, and private keys read from environment variables. The Openclaw installer no longer pins a superseded skills tag and writes the correct BANK OF AI host. *(Corrected on Oct 23: these installer changes never shipped.)* [8004 details](./8004/) · [Openclaw details](./openclaw-extension/)
 
 </div>
 </div>
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md
index 470342c1..a6b9acad 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs-changelog/current/index.md
@@ -7,6 +7,110 @@ description: 'BANK OF AI 各产品的更新与公告——全部产品，按时
 
 BANK OF AI 各产品的更新与公告。
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-27</div>
+<div className="changelog-body">
+
+### 反向审计：代码中有、文档未覆盖的内容
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- Facilitator 错误码、8004 的 subgraph 默认值与合约回退原因、Agent Wallet 错误码与配置结构、wallet-cli 错误码与充值规则、各 Skill 的安装步骤与凭据、OpenClaw 安装器细节、TRON MCP 的包内容与 HTTP 细节。[x402](./x402/) · [8004](./8004/) · [Agent Wallet](./agent-wallet/) · [SKILLS](./skills/) · [OpenClaw](./openclaw-extension/) · [MCP](./mcp-server/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-25</div>
+<div className="changelog-body">
+
+### x402 文档对齐 SDK 2.1.0 与 Facilitator v2.2.2
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">x402</span><span className="changelog-tag">修复</span></div>
+
+- 基于官方 `@x402/core` 2.28.0 的 2.1.0 版本组合（TRON 资源赞助使用 `@bankofai/x402-tron-extensions`）、十进制 TRON ID、官方 Facilitator 匿名调用 `/verify` 与 `/settle` 各每分钟 10 次的限流、Nile 资源赞助，以及 API Catalog 其余的 CI 规则。[详情](./x402/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-23</div>
+<div className="changelog-body">
+
+### 各产品的 Node.js 版本要求更新
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- 安装相关页面改为各项目源码要求的 2026 年 10 月安全更新版本（仍声明旧下限的已发布包——agent-wallet `3.0.0` 为 `>=18`、TRON MCP Server `1.1.7` 为 `>=20`——已在对应页面注明）：Agent Wallet、wallet-cli、SKILLS 和 OpenClaw Extension 需要 Node.js 22.23.4+（22.x）、24.22.1+（24.x）或 26.12.1+；8004 TypeScript SDK 相同，但最高只到 26.x；TRON MCP Server 需要 22.23.4+ 或 24.22.1+（源码 `v1.1.8`；不支持 Node.js 26；npm `1.1.7` 声明的是 `>=20`）；x402 SDK 需要 24.22.1+。OpenClaw 的两个安装器现在会在安装任何内容之前检查完整版本号。
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-23</div>
+<div className="changelog-body">
+
+### 8004 文档对齐 SDK 1.2.1
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">8004</span><span className="changelog-tag">修复</span></div>
+
+- Base 主网与 Base Sepolia、`registerIPFS()` 输出的规范 registration-v1 键名、新的 TypeScript 注册表读取 API，以及 1.2.1 的 Node.js 要求。[详情](./8004/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-23</div>
+<div className="changelog-body">
+
+### OpenClaw Extension 与 TRON MCP Server 文档按代码更正
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span></div>
+
+- OpenClaw：安装器仍锁定 Skills `v1.5.15`、agent-wallet 2.3.1 与 `chat.ainft.com`——9 月 9 日所述的安装器改动并未发布，文档现按实际安装器描述。[详情](./openclaw-extension/) TRON MCP Server：未配置 API Key 时的主网 RPC 回落、工具与提示词细节，以及真实的钱包报错文本。[详情](./mcp-server/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-22</div>
+<div className="changelog-body">
+
+### SKILLS 3.0.1——Node.js 安全基线
+
+<div className="changelog-tags"><span className="changelog-tag">新版本</span><span className="changelog-tag">SKILLS</span></div>
+
+- 内置的 Node.js Skills 与 wallet-cli 安装器要求 Node.js `^22.23.4 || ^24.22.1 || >=26.12.1`。`wallet-cli` Skill 仍锁定 `@tron-walletcli/wallet-cli@4.14.0`。[详情](./skills/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-21</div>
+<div className="changelog-body">
+
+### Agent Wallet 文档按 3.0 重写
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">Agent Wallet</span><span className="changelog-tag">破坏性变更</span></div>
+
+- Agent Wallet 各页改为对应 3.0.0：`wallet_cli`、`privy`、`raw_secret` 三种钱包，exec 脚本提供凭据，网络标识须为精确的 CAIP-2。`local_secure`、`AGENT_WALLET_PASSWORD` 和 Python SDK 不再介绍。[详情](./agent-wallet/)
+
+</div>
+</div>
+
+<div className="changelog-entry">
+<div className="changelog-date">2026-10-21</div>
+<div className="changelog-body">
+
+### SKILLS 安装命令固定到 main 分支
+
+<div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">SKILLS</span><span className="changelog-tag">修复</span></div>
+
+- 使用 `npx skills add https://github.com/BofAI/skills/tree/main -g` 安装，使 Skills 与文档中的 wallet-cli 版本一致。[详情](./skills/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-28</div>
 <div className="changelog-body">
@@ -33,6 +137,19 @@ BANK OF AI 各产品的更新与公告。
 </div>
 </div>
 
+<div className="changelog-entry">
+<div className="changelog-date">2026-09-10</div>
+<div className="changelog-body">
+
+### Agent Wallet v3.0.0
+
+<div className="changelog-tags"><span className="changelog-tag">新版本</span><span className="changelog-tag">Agent Wallet</span><span className="changelog-tag">破坏性变更</span></div>
+
+- 新增 `wallet_cli` 钱包类型；移除 `local_secure`、主密码与 `AGENT_WALLET_PASSWORD`；`signTransaction()` 返回带类型的结果；移除 `signRaw` / `signMessage`；低阶 API 移到 `/advanced`。[详情](./agent-wallet/)
+
+</div>
+</div>
+
 <div className="changelog-entry">
 <div className="changelog-date">2026-09-09</div>
 <div className="changelog-body">
@@ -41,7 +158,7 @@ BANK OF AI 各产品的更新与公告。
 
 <div className="changelog-tags"><span className="changelog-tag">文档</span><span className="changelog-tag">修复</span><span className="changelog-tag">8004</span><span className="changelog-tag">Openclaw</span></div>
 
-- 8004 文档内部已一致：`setWallet` 由四种互不一致的调用形态统一为每种 SDK 一种，并说明新钱包签名的三种提供方式、移除旧版 TRON `chainId`、改用 SDK 实际接受的网络标识、私钥改从环境变量读取。Openclaw 安装器不再固定在已被取代的技能标签上，并写入正确的 BANK OF AI 域名。[8004 详情](./8004/) · [Openclaw 详情](./openclaw-extension/)
+- 8004 文档内部已一致：`setWallet` 由四种互不一致的调用形态统一为每种 SDK 一种，并说明新钱包签名的三种提供方式、移除旧版 TRON `chainId`、改用 SDK 实际接受的网络标识、私钥改从环境变量读取。Openclaw 安装器不再固定在已被取代的技能标签上，并写入正确的 BANK OF AI 域名。*（10 月 23 日更正：这些安装器改动并未发布。）*[8004 详情](./8004/) · [Openclaw 详情](./openclaw-extension/)
 
 </div>
 </div>

From 3fd57cf8beb41c6733d6ec13819558ff60c65ec8 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Wed, 28 Oct 2026 17:02:02 +0800
Subject: [PATCH 07/13] chore: bump version to 1.4.26

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index b2a8f0d4..bf3608d9 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@x402-tron/docs",
-  "version": "1.4.20",
+  "version": "1.5.0",
   "description": "x402-tron documentation",
   "license": "MIT",
   "resolutions": {

From 601ac7c62f6de9620ec98b0a58caf969bfe1a156 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Thu, 29 Oct 2026 18:11:58 +0800
Subject: [PATCH 08/13] docs(x402): add self-hosted Gateway deployment steps

- Gateway: run your own gateway with the v1.0.4 Docker image (npm still has 1.0.2 with hex TRON IDs): provider.yml, .env, check, start, health and 402 checks.
- List Your Service and wallet-cli overview link to the new section.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docs/wallet-cli/index.md                      |  2 +-
 docs/x402/api-catalog/list-your-service.md    |  2 +-
 docs/x402/core-concepts/gateway.md            | 85 ++++++++++++++++++-
 .../current/wallet-cli/index.md               |  2 +-
 .../x402/api-catalog/list-your-service.md     |  2 +-
 .../current/x402/core-concepts/gateway.md     | 85 ++++++++++++++++++-
 6 files changed, 172 insertions(+), 6 deletions(-)

diff --git a/docs/wallet-cli/index.md b/docs/wallet-cli/index.md
index 34dce2b5..553dae80 100644
--- a/docs/wallet-cli/index.md
+++ b/docs/wallet-cli/index.md
@@ -14,7 +14,7 @@ Use **`@tron-walletcli/wallet-cli@4.15.1`** for new command-line integrations.
 | Browse providers and endpoints | `wallet-cli x402 provider-list`, `provider-show`, `endpoint-list` |
 | Refresh the catalog cache | `wallet-cli x402 update-catalog` |
 | B.AI recharge and records | `wallet-cli bai recharge`, `recharge-orders` |
-| Gateway deployment, configuration and catalog builds | [Gateway guide](/x402/core-concepts/gateway/) and [Catalog guide](/x402/api-catalog/) |
+| Gateway deployment, configuration and catalog builds | [Gateway deployment guide](/x402/core-concepts/gateway/#run-your-own-gateway) and [Catalog guide](/x402/api-catalog/) |
 
 Configure and select accounts through wallet-cli. An agent-wallet configuration does not automatically become a wallet-cli account. Use decimal CAIP-2 network IDs for the CLI: Nile `tron:3448148188`, TRON mainnet `tron:728126428`, BSC `eip155:56`, and Base `eip155:8453`. Protocol documentation can use hexadecimal TRON IDs; do not substitute those into CLI examples.
 
diff --git a/docs/x402/api-catalog/list-your-service.md b/docs/x402/api-catalog/list-your-service.md
index 1c84c718..4b31c8ff 100644
--- a/docs/x402/api-catalog/list-your-service.md
+++ b/docs/x402/api-catalog/list-your-service.md
@@ -55,7 +55,7 @@ Skip the form and follow the steps below to prepare the files and open the PR.
 
 ## Step 1: Prepare the two public files
 
-**Self-hosted gateway**: run and validate your Gateway, then prepare `catalog.json` and `pay.md` using the formats below. Include public endpoints, prices, and payment details only.
+**Self-hosted gateway**: prepare `catalog.json` and `pay.md` using the formats below. Include public endpoints, prices, and payment details only. Before you do, [run and validate your Gateway](/x402/core-concepts/gateway/#run-your-own-gateway).
 
 **Official gateway**: once onboarding is confirmed, fill in the two files using the official addresses assigned to you, following the examples below. The gateway uses one provider ID per payment chain, which differs from your catalog `fqn` — for example `https://x402-gateway.bankofai.io/providers/sunpump-token-launch-tron`, `…-bsc`, and `…-base`.
 
diff --git a/docs/x402/core-concepts/gateway.md b/docs/x402/core-concepts/gateway.md
index 58105b61..4ab369c7 100644
--- a/docs/x402/core-concepts/gateway.md
+++ b/docs/x402/core-concepts/gateway.md
@@ -94,7 +94,7 @@ Full steps: [List Your Service](../api-catalog/list-your-service.md).
 ### Official gateway, or run your own?
 
 - **Official gateway (hosted)**: BANK OF AI runs the gateway, proxies your API, and handles payment — you deploy nothing; the call addresses in your listing files use the official domain (like `x402-gateway.bankofai.io/providers/<gateway-provider-id>`).
-- **Run your own**: deploy the gateway on your own machine; upstream credentials and payout config stay local; the call addresses in your listing files use your own domain. For providers who want full control over credentials and infrastructure.
+- **Run your own**: deploy the gateway on your own machine; upstream credentials and payout config stay local; the call addresses in your listing files use your own domain. For providers who want full control over credentials and infrastructure. Setup steps: [Run your own gateway](#run-your-own-gateway).
 
 Either way, the calling Agent's experience is identical: discovery, quoting, payment, and the call all follow the same x402 flow.
 
@@ -102,6 +102,89 @@ Either way, the calling Agent's experience is identical: discovery, quoting, pay
 The gateway and the catalog solve two different problems: **the gateway collects the money; the catalog gets you discovered.** The catalog is just a public list of services — it never touches calls or funds. What Agents call is always the gateway address registered in the catalog; with a self-hosted gateway that's your own domain, so traffic and funds go straight to you. The point of listing: every Agent, CLI user, and catalog visitor plugged into the BANK OF AI catalog can discover and call your service — not just the people who happen to know your domain.
 :::
 
+## Run your own gateway
+
+These steps use gateway release **v1.0.4**, published as the Docker image `bankofai/x402-gateway:v1.0.4`. The npm package `@bankofai/x402-gateway` is still at 1.0.2, which predates the decimal TRON network IDs used in these docs, so run the image rather than the npm package. Full reference: [x402-gateway v1.0.4 README](https://github.com/BofAI/x402-gateway/blob/v1.0.4/README.md).
+
+### 1. Write a provider file
+
+Each provider lives in its own directory as `provider.yml` (or `provider.yaml`), for example `providers/example/provider.yml`:
+
+```yaml
+name: example-provider
+forward_url: ${X402_PROVIDER_FORWARD_URL}
+
+operator:
+  network: tron:3448148188        # TRON Nile; mainnet is tron:728126428
+  currencies:
+    usd: ["USDT"]
+  recipient: ${X402_PROVIDER_RECIPIENT}
+  scheme: exact
+  protocol: exact
+  facilitator_url: ${X402_FACILITATOR_URL}
+  facilitator_api_key_env: X402_FACILITATOR_API_KEY
+  valid_for_seconds: 300
+
+endpoints:
+  - method: GET
+    path: /v1/ping
+    metering:
+      dimensions:
+        - tiers:
+            - price_usd: 0.002
+```
+
+- `network` must be a decimal CAIP-2 ID. Aliases such as `tron:nile` are rejected.
+- `recipient` is your payout **address**. The gateway never needs a private key.
+- Endpoints without `metering` are forwarded for free.
+- If your upstream needs an API key, add a `routing.auth` block that reads it from an environment variable. See the README's *Provider Config* section.
+
+### 2. Set the environment
+
+Put the values the YAML references in a `.env` file next to the `providers/` directory:
+
+```bash
+X402_PROVIDER_FORWARD_URL=https://api.example.com
+X402_PROVIDER_RECIPIENT=<your-payout-address>
+X402_FACILITATOR_URL=https://facilitator.bankofai.io
+X402_FACILITATOR_API_KEY=<facilitator-api-key>
+X402_GATEWAY_ADMIN_TOKEN=<admin-token>
+X402_GATEWAY_PUBLIC_BASE_URL=https://gateway.example.com
+```
+
+`X402_GATEWAY_PUBLIC_BASE_URL` is the public origin Agents call. It is also the base of the addresses you publish in the catalog. Because `facilitator_api_key_env` is set, the gateway refuses to start without `X402_FACILITATOR_API_KEY`. For the facilitator's API key, see [Official Facilitator](./OfficialFacilitator.md).
+
+### 3. Validate the configuration
+
+```bash
+docker run --rm --env-file .env \
+  -v "$PWD/providers:/app/providers:ro" \
+  bankofai/x402-gateway:v1.0.4 \
+  x402-gateway check --providers /app/providers
+```
+
+`check` validates YAML syntax, required fields, environment expansion, network IDs and endpoint shape. It does not call your upstream, the facilitator or the chain.
+
+### 4. Start the gateway
+
+```bash
+docker run -d --name x402-gateway --env-file .env \
+  -p 4020:8080 \
+  -v "$PWD/providers:/app/providers:ro" \
+  bankofai/x402-gateway:v1.0.4
+```
+
+The image listens on `0.0.0.0:8080` inside the container. For production, pin the image by digest instead of tag, as the README recommends.
+
+### 5. Check health and the payment challenge
+
+```bash
+curl http://127.0.0.1:4020/__402/health
+curl -i http://127.0.0.1:4020/providers/example-provider/v1/ping
+```
+
+The `curl -i` request to the metered endpoint should return `402 Payment Required` with a `PAYMENT-REQUIRED` header. The provider path segment is the `name` field from the YAML. Once both checks pass and the public URL is reachable, continue with [List Your Service](../api-catalog/list-your-service.md).
+
 ## Next steps
 
 - [List your API](../api-catalog/list-your-service.md) — submission flow, required info, and security red lines
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md
index 18056c2d..847047e6 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/wallet-cli/index.md
@@ -14,7 +14,7 @@ description: "使用 wallet-cli 进行支付和服务发现。"
 | 浏览服务和接口 | `wallet-cli x402 provider-list`、`provider-show`、`endpoint-list` |
 | 刷新目录缓存 | `wallet-cli x402 update-catalog` |
 | B.AI 充值及记录 | `wallet-cli bai recharge`、`recharge-orders` |
-| Gateway 部署、配置和目录构建 | [Gateway 文档](/zh-Hans/x402/core-concepts/gateway/)及 [Catalog 文档](/zh-Hans/x402/api-catalog/) |
+| Gateway 部署、配置和目录构建 | [Gateway 部署文档](/zh-Hans/x402/core-concepts/gateway/#run-your-own-gateway)及 [Catalog 文档](/zh-Hans/x402/api-catalog/) |
 
 钱包由 wallet-cli 配置和选择，原有 agent-wallet 配置不会自动变成 wallet-cli 账户。CLI 网络参数使用十进制 CAIP-2 标识，例如 Nile `tron:3448148188`、TRON 主网 `tron:728126428`、BSC `eip155:56`、Base `eip155:8453`。不要将协议文档中的十六进制 TRON 标识直接替换到 CLI 示例中。
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md
index 322b1c12..a94e12cf 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/api-catalog/list-your-service.md
@@ -55,7 +55,7 @@ description: 把你的 API 上架到 API 目录 —— 填表申请或直接提
 
 ## 第 1 步：准备两份公开文件
 
-**自建网关**：先运行并验证自己的 Gateway，再按下文格式编写 `catalog.json` 和 `pay.md`，只包含公开接口、价格和收款信息。
+**自建网关**：按下文格式编写 `catalog.json` 和 `pay.md`，只包含公开接口、价格和收款信息。编写前，先[运行并验证自己的 Gateway](/zh-Hans/x402/core-concepts/gateway/#run-your-own-gateway)。
 
 **官方网关**：接入沟通确认后，按分配给你的官方地址填写两份文件即可，格式参考下面的示例。网关按支付链各分配一个 provider ID，与目录里的 `fqn` 不同，例如 `https://x402-gateway.bankofai.io/providers/sunpump-token-launch-tron`、`…-bsc` 和 `…-base`。
 
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md
index c315ebee..c0eec1e2 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/gateway.md
@@ -94,7 +94,7 @@ import ThemedImage from '@theme/ThemedImage';
 ### 官方网关，还是自己运行？
 
 - **官方网关（托管）**：由 BANK OF AI 运行网关，代理你的 API 并处理收款，你无需部署任何东西；上架文件里的调用地址填官方域名（形如 `x402-gateway.bankofai.io/providers/<gateway-provider-id>`）。
-- **自己运行网关**：在自己的机器上部署网关，上游凭证与收款配置只留在本地；上架文件里的调用地址填你自己的域名。适合希望完全自主掌控凭证与基础设施的服务方。
+- **自己运行网关**：在自己的机器上部署网关，上游凭证与收款配置只留在本地；上架文件里的调用地址填你自己的域名。适合希望完全自主掌控凭证与基础设施的服务方。部署步骤见[自建网关](#run-your-own-gateway)。
 
 无论哪种方式，调用方 Agent 的体验完全一致：发现、报价、付款、调用走的都是同一套 x402 流程。
 
@@ -102,6 +102,89 @@ import ThemedImage from '@theme/ThemedImage';
 网关和目录解决的是两件事：**网关负责收钱，目录负责让你被发现**。目录只是一份公开的服务清单，不经手任何调用与资金——Agent 调用的永远是目录里登记的网关地址。自建网关时，登记的就是你自己的域名，流量与款项直接到你；上架的意义在于：所有接入 BANK OF AI 目录的 Agent、CLI 用户与目录站访客都能发现并调用你的服务，而不只是知道你域名的人。
 :::
 
+## 自建网关 {#run-your-own-gateway}
+
+以下步骤基于网关 **v1.0.4** 版本，该版本以 Docker 镜像 `bankofai/x402-gateway:v1.0.4` 发布。npm 包 `@bankofai/x402-gateway` 目前仍是 1.0.2，早于本文档使用的十进制 TRON 网络 ID，因此请使用镜像，不要安装 npm 包。完整说明见 [x402-gateway v1.0.4 README](https://github.com/BofAI/x402-gateway/blob/v1.0.4/README.md)。
+
+### 1. 编写 provider 文件
+
+每个 provider 单独一个目录，文件名为 `provider.yml`（或 `provider.yaml`），例如 `providers/example/provider.yml`：
+
+```yaml
+name: example-provider
+forward_url: ${X402_PROVIDER_FORWARD_URL}
+
+operator:
+  network: tron:3448148188        # TRON Nile；主网为 tron:728126428
+  currencies:
+    usd: ["USDT"]
+  recipient: ${X402_PROVIDER_RECIPIENT}
+  scheme: exact
+  protocol: exact
+  facilitator_url: ${X402_FACILITATOR_URL}
+  facilitator_api_key_env: X402_FACILITATOR_API_KEY
+  valid_for_seconds: 300
+
+endpoints:
+  - method: GET
+    path: /v1/ping
+    metering:
+      dimensions:
+        - tiers:
+            - price_usd: 0.002
+```
+
+- `network` 必须是十进制 CAIP-2 ID，`tron:nile` 之类的别名会被拒绝。
+- `recipient` 填收款**地址**，网关不需要任何私钥。
+- 没有 `metering` 的端点免费转发。
+- 上游需要 API Key 时，添加 `routing.auth` 配置，从环境变量读取。详见 README 的 *Provider Config* 一节。
+
+### 2. 配置环境变量
+
+在 `providers/` 目录旁创建 `.env`，写入 YAML 引用的变量：
+
+```bash
+X402_PROVIDER_FORWARD_URL=https://api.example.com
+X402_PROVIDER_RECIPIENT=<你的收款地址>
+X402_FACILITATOR_URL=https://facilitator.bankofai.io
+X402_FACILITATOR_API_KEY=<facilitator-api-key>
+X402_GATEWAY_ADMIN_TOKEN=<admin-token>
+X402_GATEWAY_PUBLIC_BASE_URL=https://gateway.example.com
+```
+
+`X402_GATEWAY_PUBLIC_BASE_URL` 是 Agent 调用的公网地址，也是你在目录中登记地址的前缀。由于配置了 `facilitator_api_key_env`，缺少 `X402_FACILITATOR_API_KEY` 时网关会拒绝启动。Facilitator API Key 的获取方式见[官方 Facilitator](./OfficialFacilitator.md)。
+
+### 3. 校验配置
+
+```bash
+docker run --rm --env-file .env \
+  -v "$PWD/providers:/app/providers:ro" \
+  bankofai/x402-gateway:v1.0.4 \
+  x402-gateway check --providers /app/providers
+```
+
+`check` 校验 YAML 语法、必填字段、环境变量展开、网络 ID 和端点格式，不会调用上游、Facilitator 或链。
+
+### 4. 启动网关
+
+```bash
+docker run -d --name x402-gateway --env-file .env \
+  -p 4020:8080 \
+  -v "$PWD/providers:/app/providers:ro" \
+  bankofai/x402-gateway:v1.0.4
+```
+
+镜像在容器内监听 `0.0.0.0:8080`。生产环境请按 README 建议，用镜像 digest 而不是 tag 固定版本。
+
+### 5. 检查健康状态和付款挑战
+
+```bash
+curl http://127.0.0.1:4020/__402/health
+curl -i http://127.0.0.1:4020/providers/example-provider/v1/ping
+```
+
+`curl -i` 请求的是计费端点，应返回 `402 Payment Required`，并带有 `PAYMENT-REQUIRED` 响应头。路径中的 provider 段即 YAML 里的 `name`。两项检查都通过、公网地址可访问后，继续阅读[上架你的服务](../api-catalog/list-your-service.md)。
+
 ## 下一步
 
 - [上架你的 API](../api-catalog/list-your-service.md) —— 提交流程、所需信息与安全红线

From c97cbdea917a369be23c9cc6818bc140427d3e1a Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Thu, 29 Oct 2026 18:11:59 +0800
Subject: [PATCH 09/13] fix(site): redirect old /x402/cli/ pages to wallet-cli

The four x402 CLI pages moved to /wallet-cli/ in b11a7a1 without redirects. Add client redirects for both locales.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 docusaurus.config.js | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docusaurus.config.js b/docusaurus.config.js
index 2649fd8f..9072d032 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -115,7 +115,7 @@ module.exports = {
   ],
   plugins: [
     require.resolve('./docusaurus-plugin-global-style'),
-    // 兼容旧链接：/McpServer-Skills/Intro/ 重定向到 Skills 简介（自动覆盖各 locale）
+    // 兼容旧链接：/McpServer-Skills/Intro/ 重定向到 Skills 简介、/x402/cli/ 重定向到 wallet-cli（自动覆盖各 locale）
     [
       '@docusaurus/plugin-client-redirects',
       {
@@ -123,6 +123,11 @@ module.exports = {
           if (existingPath.endsWith('/McpServer-Skills/SKILLS/Intro/') || existingPath.endsWith('/McpServer-Skills/SKILLS/Intro')) {
             return [existingPath.replace('/McpServer-Skills/SKILLS/Intro', '/McpServer-Skills/Intro')]
           }
+          // 旧 x402 CLI 页面（docs/x402/cli/）已迁到 wallet-cli，保留旧地址
+          const walletCli = existingPath.match(/^(\/zh-Hans)?\/wallet-cli\/((?:quickstart|command-reference|faq)\/)?$/)
+          if (walletCli) {
+            return [`${walletCli[1] || ''}/x402/cli/${walletCli[2] || ''}`]
+          }
           if (existingPath === '/llmservice/image-models/pricing/') {
             return ['/llmservice/image-models/grok-imagine-image-2-0/']
           }

From 462ac67882f31cd30a62d44fc1993a63e0791a9c Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Thu, 29 Oct 2026 18:11:59 +0800
Subject: [PATCH 10/13] fix(nginx): return a real 404 for unknown paths

Unknown paths fell back to the locale index with HTTP 200. Return 404 and serve the locale's Docusaurus 404 page.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 default.conf | 9 ++++++---
 nginx.conf   | 9 ++++++---
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/default.conf b/default.conf
index 72191769..4c5ad0c5 100644
--- a/default.conf
+++ b/default.conf
@@ -7,13 +7,16 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
-    # 中文等非默认语言：未命中时回退到该语言的 index
+    # 站点是全静态构建，每个页面都有对应的 index.html；未命中的路径返回真实 404，
+    # 并显示对应语言的 Docusaurus 404 页。已迁移的旧地址由 plugin-client-redirects 生成跳转页。
     location /zh-Hans/ {
-        try_files $uri $uri/ /zh-Hans/index.html;
+        try_files $uri $uri/ =404;
+        error_page 404 /zh-Hans/404.html;
     }
 
     location / {
-        try_files $uri $uri/ /index.html;
+        try_files $uri $uri/ =404;
+        error_page 404 /404.html;
     }
 
     # Disable caching for index.html
diff --git a/nginx.conf b/nginx.conf
index 4a0947f6..238f039f 100644
--- a/nginx.conf
+++ b/nginx.conf
@@ -51,13 +51,16 @@ http {
         root /usr/share/nginx/html;
         index index.html;
 
-        # 中文等非默认语言：未命中静态文件时回退到该语言的 index，避免落到根 index 导致客户端 404
+        # 站点是全静态构建，每个页面都有对应的 index.html；未命中的路径返回真实 404，
+        # 并显示对应语言的 Docusaurus 404 页。已迁移的旧地址由 plugin-client-redirects 生成跳转页。
         location /zh-Hans/ {
-            try_files $uri $uri/ /zh-Hans/index.html;
+            try_files $uri $uri/ =404;
+            error_page 404 /zh-Hans/404.html;
         }
 
         location / {
-            try_files $uri $uri/ /index.html;
+            try_files $uri $uri/ =404;
+            error_page 404 /404.html;
         }
 
         location /assets/ {

From 36d4ca4e40c30c96b028891dc932274014f67e48 Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Thu, 29 Oct 2026 18:11:59 +0800
Subject: [PATCH 11/13] fix(css): restore the mobile table of contents

custom.css hid the collapsible TOC button, leaving narrow screens with no in-page navigation.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 static/css/custom.css | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/static/css/custom.css b/static/css/custom.css
index 99492488..29d4518d 100644
--- a/static/css/custom.css
+++ b/static/css/custom.css
@@ -604,17 +604,6 @@ html[data-theme='light'] .table-of-contents__link {
   display: none;
 }
 
-/**
-* Hide On this page
-*/
-.tocCollapsibleButton_TO0P {
-  display: none !important;
-}
-
-button[class*='tocCollapsibleButton'] {
-  display: none !important;
-}
-
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *

From 470f68e970368357105a3b6757e116cee96ec82f Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Thu, 29 Oct 2026 18:11:59 +0800
Subject: [PATCH 12/13] chore(lint): make yarn lint runnable and run it in CI

- Add ESLint 9 with typescript-eslint and React plugins, plus eslint.config.mjs; yarn lint failed with "eslint not found".
- CI: lint job on Node 22.23.4 before the Docker build.
- llmservice.js: list hook dependencies.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/docker.yml |   22 +
 eslint.config.mjs            |   44 +
 package.json                 |    8 +-
 src/pages/llmservice.js      |    2 +-
 yarn.lock                    | 1588 +++++++++++++++++++++++++++++++++-
 5 files changed, 1643 insertions(+), 21 deletions(-)
 create mode 100644 eslint.config.mjs

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index e0253854..3077322a 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -27,7 +27,29 @@ env:
   IMAGE_NAME: bankofai/docs
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.23.4
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --non-interactive
+
+      - name: Lint
+        run: yarn lint
+
   build-and-push:
+    needs: lint
     runs-on: ubuntu-latest
     permissions:
       contents: read
diff --git a/eslint.config.mjs b/eslint.config.mjs
new file mode 100644
index 00000000..31573463
--- /dev/null
+++ b/eslint.config.mjs
@@ -0,0 +1,44 @@
+// ESLint 9 flat config for the site's React/TypeScript sources (`yarn lint`).
+import js from '@eslint/js'
+import { defineConfig } from 'eslint/config'
+import react from 'eslint-plugin-react'
+import reactHooks from 'eslint-plugin-react-hooks'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig(
+  {
+    ignores: ['build/**', '.docusaurus/**', 'node_modules/**'],
+  },
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    files: ['src/**/*.{js,jsx,ts,tsx}'],
+    plugins: {
+      react,
+      'react-hooks': reactHooks,
+    },
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
+      globals: {
+        ...globals.browser,
+      },
+    },
+    settings: {
+      react: { version: 'detect' },
+    },
+    rules: {
+      ...react.configs.recommended.rules,
+      ...react.configs['jsx-runtime'].rules,
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+      // Swizzled theme wrappers forward untyped props from @theme-original.
+      '@typescript-eslint/no-explicit-any': 'off',
+      'react/prop-types': 'off',
+    },
+  }
+)
diff --git a/package.json b/package.json
index bf3608d9..104f6107 100644
--- a/package.json
+++ b/package.json
@@ -50,10 +50,16 @@
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "2.4.3",
+    "@eslint/js": "^9.39.0",
     "@tsconfig/docusaurus": "^1.0.6",
     "dotenv": "^16.0.3",
+    "eslint": "^9.39.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
     "prettier": "2.7.1",
-    "typescript": "^4.8.4"
+    "typescript": "^4.8.4",
+    "typescript-eslint": "^8.72.1"
   },
   "engines": {
     "node": "^22.23.4 || ^24.22.1 || >=26.12.1",
diff --git a/src/pages/llmservice.js b/src/pages/llmservice.js
index a524ade6..706c9983 100644
--- a/src/pages/llmservice.js
+++ b/src/pages/llmservice.js
@@ -8,7 +8,7 @@ export default function LlmServiceRedirect() {
   useEffect(() => {
     const isZh = pathname.startsWith('/zh-Hans')
     history.replace(isZh ? '/zh-Hans/llmservice/introduction' : '/llmservice/introduction')
-  }, [])
+  }, [history, pathname])
 
   return null
 }
diff --git a/yarn.lock b/yarn.lock
index 43adf61e..20b4b837 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -290,11 +290,25 @@
     js-tokens "^4.0.0"
     picocolors "^1.1.1"
 
+"@babel/code-frame@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.29.7.tgz#f2fbbfea87c44a21590ec515b778b2c26d8866e7"
+  integrity sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==
+  dependencies:
+    "@babel/helper-validator-identifier" "^7.29.7"
+    js-tokens "^4.0.0"
+    picocolors "^1.1.1"
+
 "@babel/compat-data@^7.28.6", "@babel/compat-data@^7.29.0":
   version "7.29.0"
   resolved "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.0.tgz"
   integrity sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==
 
+"@babel/compat-data@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/compat-data/-/compat-data-7.29.7.tgz#6f0237f0f36d2e51c0570a636faed9d2d0efe629"
+  integrity sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==
+
 "@babel/core@7.12.9":
   version "7.12.9"
   resolved "https://registry.npmjs.org/@babel/core/-/core-7.12.9.tgz"
@@ -338,6 +352,27 @@
     json5 "^2.2.3"
     semver "^6.3.1"
 
+"@babel/core@^7.24.4":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.29.7.tgz#80c10b17248082968b57a857b91640971f2070f7"
+  integrity sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==
+  dependencies:
+    "@babel/code-frame" "^7.29.7"
+    "@babel/generator" "^7.29.7"
+    "@babel/helper-compilation-targets" "^7.29.7"
+    "@babel/helper-module-transforms" "^7.29.7"
+    "@babel/helpers" "^7.29.7"
+    "@babel/parser" "^7.29.7"
+    "@babel/template" "^7.29.7"
+    "@babel/traverse" "^7.29.7"
+    "@babel/types" "^7.29.7"
+    "@jridgewell/remapping" "^2.3.5"
+    convert-source-map "^2.0.0"
+    debug "^4.1.0"
+    gensync "^1.0.0-beta.2"
+    json5 "^2.2.3"
+    semver "^6.3.1"
+
 "@babel/generator@^7.12.5", "@babel/generator@^7.18.7", "@babel/generator@^7.29.0":
   version "7.29.0"
   resolved "https://registry.npmjs.org/@babel/generator/-/generator-7.29.0.tgz"
@@ -349,6 +384,17 @@
     "@jridgewell/trace-mapping" "^0.3.28"
     jsesc "^3.0.2"
 
+"@babel/generator@^7.29.7", "@babel/generator@^7.29.8":
+  version "7.29.8"
+  resolved "https://registry.yarnpkg.com/@babel/generator/-/generator-7.29.8.tgz#4b0b887885422643339e09022148a4c4ebaa4979"
+  integrity sha512-gZbepsdh3WDtgZKWL+vTPh71LSBrm/Y4/QDZBVCcYfmeTEEuoOYwlSy+G1StfJg+/Zy550u/3TATbm7qDbbMtg==
+  dependencies:
+    "@babel/parser" "^7.29.8"
+    "@babel/types" "^7.29.8"
+    "@jridgewell/gen-mapping" "^0.3.12"
+    "@jridgewell/trace-mapping" "^0.3.28"
+    jsesc "^3.0.2"
+
 "@babel/helper-annotate-as-pure@^7.27.1", "@babel/helper-annotate-as-pure@^7.27.3":
   version "7.27.3"
   resolved "https://registry.npmjs.org/@babel/helper-annotate-as-pure/-/helper-annotate-as-pure-7.27.3.tgz"
@@ -367,6 +413,17 @@
     lru-cache "^5.1.1"
     semver "^6.3.1"
 
+"@babel/helper-compilation-targets@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/helper-compilation-targets/-/helper-compilation-targets-7.29.7.tgz#7a1def704302401c47f64fa85589e974ae217042"
+  integrity sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==
+  dependencies:
+    "@babel/compat-data" "^7.29.7"
+    "@babel/helper-validator-option" "^7.29.7"
+    browserslist "^4.24.0"
+    lru-cache "^5.1.1"
+    semver "^6.3.1"
+
 "@babel/helper-create-class-features-plugin@^7.28.6":
   version "7.28.6"
   resolved "https://registry.npmjs.org/@babel/helper-create-class-features-plugin/-/helper-create-class-features-plugin-7.28.6.tgz"
@@ -405,6 +462,11 @@
   resolved "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz"
   integrity sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==
 
+"@babel/helper-globals@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/helper-globals/-/helper-globals-7.29.7.tgz#f04a96fbd8473241b1079243f5b3f03a3010ab7b"
+  integrity sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==
+
 "@babel/helper-member-expression-to-functions@^7.28.5":
   version "7.28.5"
   resolved "https://registry.npmjs.org/@babel/helper-member-expression-to-functions/-/helper-member-expression-to-functions-7.28.5.tgz"
@@ -421,6 +483,14 @@
     "@babel/traverse" "^7.28.6"
     "@babel/types" "^7.28.6"
 
+"@babel/helper-module-imports@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/helper-module-imports/-/helper-module-imports-7.29.7.tgz#ef25048a518e828d7393fac5882ddd73921d7396"
+  integrity sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==
+  dependencies:
+    "@babel/traverse" "^7.29.7"
+    "@babel/types" "^7.29.7"
+
 "@babel/helper-module-transforms@^7.12.1", "@babel/helper-module-transforms@^7.27.1", "@babel/helper-module-transforms@^7.28.6":
   version "7.28.6"
   resolved "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz"
@@ -430,6 +500,15 @@
     "@babel/helper-validator-identifier" "^7.28.5"
     "@babel/traverse" "^7.28.6"
 
+"@babel/helper-module-transforms@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/helper-module-transforms/-/helper-module-transforms-7.29.7.tgz#b062747a5997ba138637201328bbff77960574ae"
+  integrity sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==
+  dependencies:
+    "@babel/helper-module-imports" "^7.29.7"
+    "@babel/helper-validator-identifier" "^7.29.7"
+    "@babel/traverse" "^7.29.7"
+
 "@babel/helper-optimise-call-expression@^7.27.1":
   version "7.27.1"
   resolved "https://registry.npmjs.org/@babel/helper-optimise-call-expression/-/helper-optimise-call-expression-7.27.1.tgz"
@@ -478,16 +557,31 @@
   resolved "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz"
   integrity sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==
 
+"@babel/helper-string-parser@^7.29.11":
+  version "7.29.11"
+  resolved "https://registry.yarnpkg.com/@babel/helper-string-parser/-/helper-string-parser-7.29.11.tgz#59d76b6193f61e0303b40991cabbedfadcbd5b63"
+  integrity sha512-snZbO7MEDOof+hvNa97EjEY7qD7h2kwvQr5AJC3ZhQudKW5dnej6k3kP9NQV88hJwaS8vDqRLFo9rivLEhle2g==
+
 "@babel/helper-validator-identifier@^7.28.5":
   version "7.28.5"
   resolved "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz"
   integrity sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==
 
+"@babel/helper-validator-identifier@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz#bd87084ced0c796ec46bda492de6e83d29e89fc2"
+  integrity sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==
+
 "@babel/helper-validator-option@^7.27.1":
   version "7.27.1"
   resolved "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz"
   integrity sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==
 
+"@babel/helper-validator-option@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/helper-validator-option/-/helper-validator-option-7.29.7.tgz#cf315be940213b354eb4abcc0bd01ebe3f73bc2a"
+  integrity sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==
+
 "@babel/helper-wrap-function@^7.27.1":
   version "7.28.6"
   resolved "https://registry.npmjs.org/@babel/helper-wrap-function/-/helper-wrap-function-7.28.6.tgz"
@@ -505,6 +599,14 @@
     "@babel/template" "^7.28.6"
     "@babel/types" "^7.28.6"
 
+"@babel/helpers@^7.29.7":
+  version "7.29.10"
+  resolved "https://registry.yarnpkg.com/@babel/helpers/-/helpers-7.29.10.tgz#d662b4a2d66cc6cf02bc50e8aced023fbc8649e9"
+  integrity sha512-EMCx3AGZ3WfAl6ht7AyQoPm2Lh+BGYEMdc4Q6Hf7uSCDOZFuLq44qNwL+iaim8VlyYhRAo4X43+weadK8ZB4Yg==
+  dependencies:
+    "@babel/template" "^7.29.7"
+    "@babel/types" "^7.29.8"
+
 "@babel/parser@^7.12.7", "@babel/parser@^7.18.8", "@babel/parser@^7.28.6", "@babel/parser@^7.29.0":
   version "7.29.0"
   resolved "https://registry.npmjs.org/@babel/parser/-/parser-7.29.0.tgz"
@@ -512,6 +614,13 @@
   dependencies:
     "@babel/types" "^7.29.0"
 
+"@babel/parser@^7.24.4", "@babel/parser@^7.29.7", "@babel/parser@^7.29.8", "@babel/parser@^7.29.9":
+  version "7.29.11"
+  resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.29.11.tgz#afa959e9d16c40d4d95012553cab363fc86cbcb7"
+  integrity sha512-OZ6+oaK7GMyg3IfCpj8JOmn8n+w2rJbDT0LLfVDTLb1ZFeKDh3AiNELgCMUw175IJHSkLl74hG0M0VLsvx+gag==
+  dependencies:
+    "@babel/types" "^7.29.11"
+
 "@babel/plugin-bugfix-firefox-class-in-computed-class-key@^7.28.5":
   version "7.28.5"
   resolved "https://registry.npmjs.org/@babel/plugin-bugfix-firefox-class-in-computed-class-key/-/plugin-bugfix-firefox-class-in-computed-class-key-7.28.5.tgz"
@@ -1211,6 +1320,15 @@
     "@babel/parser" "^7.28.6"
     "@babel/types" "^7.28.6"
 
+"@babel/template@^7.29.7":
+  version "7.29.7"
+  resolved "https://registry.yarnpkg.com/@babel/template/-/template-7.29.7.tgz#4d9d4004f645cdd304de958c725162784ecac700"
+  integrity sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==
+  dependencies:
+    "@babel/code-frame" "^7.29.7"
+    "@babel/parser" "^7.29.7"
+    "@babel/types" "^7.29.7"
+
 "@babel/traverse@^7.12.9", "@babel/traverse@^7.18.8", "@babel/traverse@^7.27.1", "@babel/traverse@^7.28.5", "@babel/traverse@^7.28.6", "@babel/traverse@^7.29.0":
   version "7.29.0"
   resolved "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz"
@@ -1224,6 +1342,19 @@
     "@babel/types" "^7.29.0"
     debug "^4.3.1"
 
+"@babel/traverse@^7.29.7":
+  version "7.29.10"
+  resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.29.10.tgz#08ab387639b4a67304511259c7da6cf23a82e91c"
+  integrity sha512-B3lYAs2nkKskbgQ1nfy8Ma9ao9Q1rntTAQHrzzyDuj+TSO+X3le6PfWwqDvodsb+OumE10eMFfuMCTQSQ5iuIQ==
+  dependencies:
+    "@babel/code-frame" "^7.29.7"
+    "@babel/generator" "^7.29.8"
+    "@babel/helper-globals" "^7.29.7"
+    "@babel/parser" "^7.29.9"
+    "@babel/template" "^7.29.7"
+    "@babel/types" "^7.29.8"
+    debug "^4.3.1"
+
 "@babel/types@^7.12.7", "@babel/types@^7.20.0", "@babel/types@^7.27.1", "@babel/types@^7.27.3", "@babel/types@^7.28.5", "@babel/types@^7.28.6", "@babel/types@^7.29.0", "@babel/types@^7.4.4":
   version "7.29.0"
   resolved "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz"
@@ -1232,6 +1363,14 @@
     "@babel/helper-string-parser" "^7.27.1"
     "@babel/helper-validator-identifier" "^7.28.5"
 
+"@babel/types@^7.29.11", "@babel/types@^7.29.7", "@babel/types@^7.29.8":
+  version "7.29.11"
+  resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.29.11.tgz#774cffe8cac2ca494f1334e4052002c96bf628fc"
+  integrity sha512-WCsemW40Cpc6gouC1SrY6PBaZ+oLRlEVY9XBvZBI7il/HyUrb2nJ505wE1MHEFyDZNnrWDEuy4jL50WVHfTTSQ==
+  dependencies:
+    "@babel/helper-string-parser" "^7.29.11"
+    "@babel/helper-validator-identifier" "^7.29.7"
+
 "@colors/colors@1.5.0":
   version "1.5.0"
   resolved "https://registry.npmjs.org/@colors/colors/-/colors-1.5.0.tgz"
@@ -1744,6 +1883,74 @@
   dependencies:
     tslib "^2.4.0"
 
+"@eslint-community/eslint-utils@^4.8.0", "@eslint-community/eslint-utils@^4.9.1":
+  version "4.10.1"
+  resolved "https://registry.yarnpkg.com/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz#8911bd72b2c3640a543609e0400b8c4d2e7e7cb6"
+  integrity sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg==
+  dependencies:
+    eslint-visitor-keys "^3.4.3"
+
+"@eslint-community/regexpp@^4.12.1", "@eslint-community/regexpp@^4.12.2":
+  version "4.12.2"
+  resolved "https://registry.yarnpkg.com/@eslint-community/regexpp/-/regexpp-4.12.2.tgz#bccdf615bcf7b6e8db830ec0b8d21c9a25de597b"
+  integrity sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==
+
+"@eslint/config-array@^0.21.2":
+  version "0.21.2"
+  resolved "https://registry.yarnpkg.com/@eslint/config-array/-/config-array-0.21.2.tgz#f29e22057ad5316cf23836cee9a34c81fffcb7e6"
+  integrity sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==
+  dependencies:
+    "@eslint/object-schema" "^2.1.7"
+    debug "^4.3.1"
+    minimatch "^3.1.5"
+
+"@eslint/config-helpers@^0.4.2":
+  version "0.4.2"
+  resolved "https://registry.yarnpkg.com/@eslint/config-helpers/-/config-helpers-0.4.2.tgz#1bd006ceeb7e2e55b2b773ab318d300e1a66aeda"
+  integrity sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==
+  dependencies:
+    "@eslint/core" "^0.17.0"
+
+"@eslint/core@^0.17.0":
+  version "0.17.0"
+  resolved "https://registry.yarnpkg.com/@eslint/core/-/core-0.17.0.tgz#77225820413d9617509da9342190a2019e78761c"
+  integrity sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==
+  dependencies:
+    "@types/json-schema" "^7.0.15"
+
+"@eslint/eslintrc@^3.3.6":
+  version "3.3.7"
+  resolved "https://registry.yarnpkg.com/@eslint/eslintrc/-/eslintrc-3.3.7.tgz#76d3dedec4a30ea32df797bf8a0085c1311b7316"
+  integrity sha512-F42g89Qd5oAWtp0k0nnSrjziAKza7w8SVT4mStc18LZMaRb4J1HQAHLCalEtDCxrTuksx7NU9qsmeLwpOfPqWw==
+  dependencies:
+    ajv "^6.14.0"
+    debug "^4.3.2"
+    espree "^10.0.1"
+    globals "^14.0.0"
+    ignore "^5.2.0"
+    import-fresh "^3.2.1"
+    js-yaml "^4.3.2"
+    minimatch "^3.1.5"
+    strip-json-comments "^3.1.1"
+
+"@eslint/js@9.39.5", "@eslint/js@^9.39.0":
+  version "9.39.5"
+  resolved "https://registry.yarnpkg.com/@eslint/js/-/js-9.39.5.tgz#6f2fbcff75500d229d535e0a949ae13472c84787"
+  integrity sha512-QywQuszQh77pIXCsq998c8hbhSTI/azTty1Z6N53dmAudKHhy573j3yvRLsX2BSp8YpLtoCEG8E9DJe+8zUh4A==
+
+"@eslint/object-schema@^2.1.7":
+  version "2.1.7"
+  resolved "https://registry.yarnpkg.com/@eslint/object-schema/-/object-schema-2.1.7.tgz#6e2126a1347e86a4dedf8706ec67ff8e107ebbad"
+  integrity sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==
+
+"@eslint/plugin-kit@^0.4.1":
+  version "0.4.1"
+  resolved "https://registry.yarnpkg.com/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz#9779e3fd9b7ee33571a57435cf4335a1794a6cb2"
+  integrity sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==
+  dependencies:
+    "@eslint/core" "^0.17.0"
+    levn "^0.4.1"
+
 "@hapi/hoek@^9.0.0", "@hapi/hoek@^9.3.0":
   version "9.3.0"
   resolved "https://registry.npmjs.org/@hapi/hoek/-/hoek-9.3.0.tgz"
@@ -1756,6 +1963,37 @@
   dependencies:
     "@hapi/hoek" "^9.0.0"
 
+"@humanfs/core@^0.19.2":
+  version "0.19.2"
+  resolved "https://registry.yarnpkg.com/@humanfs/core/-/core-0.19.2.tgz#a8272ca03b2acf492670222b2320b6c421bfde60"
+  integrity sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==
+  dependencies:
+    "@humanfs/types" "^0.15.0"
+
+"@humanfs/node@^0.16.6":
+  version "0.16.8"
+  resolved "https://registry.yarnpkg.com/@humanfs/node/-/node-0.16.8.tgz#8f800cccc13f4f8cd3116e2d9c0a94939da3e3ed"
+  integrity sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==
+  dependencies:
+    "@humanfs/core" "^0.19.2"
+    "@humanfs/types" "^0.15.0"
+    "@humanwhocodes/retry" "^0.4.0"
+
+"@humanfs/types@^0.15.0":
+  version "0.15.0"
+  resolved "https://registry.yarnpkg.com/@humanfs/types/-/types-0.15.0.tgz#f2a09f62012390b2bff3fc6fb248ddec8c09a090"
+  integrity sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==
+
+"@humanwhocodes/module-importer@^1.0.1":
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz#af5b2691a22b44be847b0ca81641c5fb6ad0172c"
+  integrity sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==
+
+"@humanwhocodes/retry@^0.4.0", "@humanwhocodes/retry@^0.4.2":
+  version "0.4.3"
+  resolved "https://registry.yarnpkg.com/@humanwhocodes/retry/-/retry-0.4.3.tgz#c2b9d2e374ee62c586d3adbea87199b1d7a7a6ba"
+  integrity sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==
+
 "@jest/schemas@^29.6.3":
   version "29.6.3"
   resolved "https://registry.npmjs.org/@jest/schemas/-/schemas-29.6.3.tgz"
@@ -2201,6 +2439,11 @@
   resolved "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz"
   integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==
 
+"@types/estree@^1.0.6":
+  version "1.0.10"
+  resolved "https://registry.yarnpkg.com/@types/estree/-/estree-1.0.10.tgz#8a4a266065af8c2fcf5983153cd97c11b313d0c6"
+  integrity sha512-lTyOMnOcmRBzdCv6/4zUZCrEhV0xrqQiUZBZtVcbmLHBXKLnN8q89v/wKRF/Q0HbwVsqbIG3o5HDoFl9sduM+g==
+
 "@types/express-serve-static-core@*":
   version "5.1.1"
   resolved "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz"
@@ -2459,6 +2702,102 @@
   dependencies:
     "@types/yargs-parser" "*"
 
+"@typescript-eslint/eslint-plugin@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.72.1.tgz#95e29de63ce7ed793eb1c6efd9f8b802ce808262"
+  integrity sha512-5CokTWXpmbylfFabsbvHC0CAw3XLaGnoa+nFJX5FR592h/LoZsENUE6p/rg5xvkKrFEXz6pYmgI29AgXc2N3BQ==
+  dependencies:
+    "@eslint-community/regexpp" "^4.12.2"
+    "@typescript-eslint/scope-manager" "8.72.1"
+    "@typescript-eslint/type-utils" "8.72.1"
+    "@typescript-eslint/utils" "8.72.1"
+    "@typescript-eslint/visitor-keys" "8.72.1"
+    ignore "^7.0.5"
+    natural-compare "^1.4.0"
+    ts-api-utils "^2.5.0"
+
+"@typescript-eslint/parser@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/parser/-/parser-8.72.1.tgz#7370b68dadc3819b9aac68ea340bd8b43ee62379"
+  integrity sha512-ZGwZP4OCfyA0AQTpEAMWz+rtX01DRhQWW5hB0ucKDEIX5U7jdmPSaMx94rQfaPAQzIYz2BimOgKOJtjfpRFQ9g==
+  dependencies:
+    "@typescript-eslint/scope-manager" "8.72.1"
+    "@typescript-eslint/types" "8.72.1"
+    "@typescript-eslint/typescript-estree" "8.72.1"
+    "@typescript-eslint/visitor-keys" "8.72.1"
+    debug "^4.4.3"
+
+"@typescript-eslint/project-service@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/project-service/-/project-service-8.72.1.tgz#1d09902a9c23f6cfab779e5acc78a45abf540add"
+  integrity sha512-fAuVMkwdO/huI8nyo/WKnNKf6Gag93S56Rh3Ts5mGcavwSdaN8tRg1gCeIGX8PF+nzp1BjGfO4gHhGzW1J6jTg==
+  dependencies:
+    "@typescript-eslint/tsconfig-utils" "^8.72.1"
+    "@typescript-eslint/types" "^8.72.1"
+    debug "^4.4.3"
+
+"@typescript-eslint/scope-manager@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/scope-manager/-/scope-manager-8.72.1.tgz#a0fb4dfe5aa2b0149b7a2d1fd00d947992b13067"
+  integrity sha512-lC/t6eMCZZQAAKZEYGL6RDVSuFehpdmMT6h+nJIjIa6oylN/PwDgDVtEIbB7O9xFfZYtZAYLoLlDNWKJhtF+uQ==
+  dependencies:
+    "@typescript-eslint/types" "8.72.1"
+    "@typescript-eslint/visitor-keys" "8.72.1"
+
+"@typescript-eslint/tsconfig-utils@8.72.1", "@typescript-eslint/tsconfig-utils@^8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.72.1.tgz#07394c85095ee38455e76bc221ba23650af73e44"
+  integrity sha512-e4D5R5vpeAEPBxT2BAzsFQL3sbwyeeeo5+aczgNSRK1V734jE7pTqaGFU+fXapWEQwnZbpFaTn32+Z8DwS6OTg==
+
+"@typescript-eslint/type-utils@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/type-utils/-/type-utils-8.72.1.tgz#f1f592f63bd9726de21191aae3ccf64a813914b8"
+  integrity sha512-iY2wlmyrXJmx4yxUGP3aYCFF3cA/6ShddOKmLU2dx7LnEykbAM8WThlxZEfd1NddqceF6eJmZUayxx9oKIYNlg==
+  dependencies:
+    "@typescript-eslint/types" "8.72.1"
+    "@typescript-eslint/typescript-estree" "8.72.1"
+    "@typescript-eslint/utils" "8.72.1"
+    debug "^4.4.3"
+    ts-api-utils "^2.5.0"
+
+"@typescript-eslint/types@8.72.1", "@typescript-eslint/types@^8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/types/-/types-8.72.1.tgz#067d8f738c294611e33a1425ae43ac9b9c2f24e3"
+  integrity sha512-LmE5IhQet1BWOWEXqBrVtBPsMAOQ6Nzk35d+WLh3mk4EUF33sqlfxjio1MdYeSvKSG5skactKKuixBIKXhL4Rw==
+
+"@typescript-eslint/typescript-estree@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/typescript-estree/-/typescript-estree-8.72.1.tgz#e93b9cc3a56bf12f5fed857bb8f4963cce7924ee"
+  integrity sha512-DAlUoUV93hIvrtIQLwCbmZQYVZwOMhiHJrOVUUIWicFZaIYjTRqlY3I/NZevfkLmSqkNHRu2qYDcq9lrn16oOQ==
+  dependencies:
+    "@typescript-eslint/project-service" "8.72.1"
+    "@typescript-eslint/tsconfig-utils" "8.72.1"
+    "@typescript-eslint/types" "8.72.1"
+    "@typescript-eslint/visitor-keys" "8.72.1"
+    debug "^4.4.3"
+    minimatch "^10.2.2"
+    semver "^7.7.3"
+    tinyglobby "^0.2.15"
+    ts-api-utils "^2.5.0"
+
+"@typescript-eslint/utils@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/utils/-/utils-8.72.1.tgz#f210c1bf4a25aa1306df80c702ed30bbbc9b4d3d"
+  integrity sha512-5v5liypurJBFHCBNqh/RjsymAD+VWcE0djuGY/BUqp5fC3Qn+luWDEksjuTtWjPn6i5zQlUtkZCRG/CYG0yCkA==
+  dependencies:
+    "@eslint-community/eslint-utils" "^4.9.1"
+    "@typescript-eslint/scope-manager" "8.72.1"
+    "@typescript-eslint/types" "8.72.1"
+    "@typescript-eslint/typescript-estree" "8.72.1"
+
+"@typescript-eslint/visitor-keys@8.72.1":
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/@typescript-eslint/visitor-keys/-/visitor-keys-8.72.1.tgz#c7aec9883b44ef795f1b8200df81d9d44d355de7"
+  integrity sha512-SB8xqipSzZHUePCCLNeYxqnxq83X61/qzNhjQGbTfjxGZIeOEP7tBgWYX05Tcd6CgE02WdTJnh5b8kMZJ/+bnQ==
+  dependencies:
+    "@typescript-eslint/types" "8.72.1"
+    eslint-visitor-keys "^5.0.0"
+
 "@webassemblyjs/ast@1.14.1", "@webassemblyjs/ast@^1.14.1":
   version "1.14.1"
   resolved "https://registry.npmjs.org/@webassemblyjs/ast/-/ast-1.14.1.tgz"
@@ -2603,6 +2942,11 @@ acorn-import-phases@^1.0.3:
   resolved "https://registry.npmjs.org/acorn-import-phases/-/acorn-import-phases-1.0.4.tgz"
   integrity sha512-wKmbr/DDiIXzEOiWrTTUcDm24kQ2vGfZQvM2fwg2vXqR5uW6aapr7ObPtj1th32b9u90/Pf4AItvdTh42fBmVQ==
 
+acorn-jsx@^5.3.2:
+  version "5.3.2"
+  resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-5.3.2.tgz#7ed5bb55908b3b2f1bc55c6af1653bada7f07937"
+  integrity sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==
+
 acorn-walk@^8.0.0:
   version "8.3.4"
   resolved "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.4.tgz"
@@ -2657,6 +3001,16 @@ ajv@^6.12.2, ajv@^6.12.4, ajv@^6.12.5:
     json-schema-traverse "^0.4.1"
     uri-js "^4.2.2"
 
+ajv@^6.14.0:
+  version "6.15.0"
+  resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.15.0.tgz#07e982c74626167aa7a2495c53817892d7139492"
+  integrity sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==
+  dependencies:
+    fast-deep-equal "^3.1.1"
+    fast-json-stable-stringify "^2.0.0"
+    json-schema-traverse "^0.4.1"
+    uri-js "^4.2.2"
+
 ajv@^8.0.0, ajv@^8.9.0:
   version "8.17.1"
   resolved "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz"
@@ -2774,21 +3128,104 @@ argparse@^2.0.1:
   resolved "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz"
   integrity sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==
 
+array-buffer-byte-length@^1.0.1, array-buffer-byte-length@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/array-buffer-byte-length/-/array-buffer-byte-length-1.0.2.tgz#384d12a37295aec3769ab022ad323a18a51ccf8b"
+  integrity sha512-LHE+8BuR7RYGDKvnrmcuSq3tDcKv9OFEXQt/HpbZhY7V6h0zlUXutnAD82GiFx9rdieCMjkvtcsPqBwgUl1Iiw==
+  dependencies:
+    call-bound "^1.0.3"
+    is-array-buffer "^3.0.5"
+
 array-flatten@1.1.1:
   version "1.1.1"
   resolved "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz"
   integrity sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==
 
+array-includes@^3.1.6, array-includes@^3.1.8:
+  version "3.2.0"
+  resolved "https://registry.yarnpkg.com/array-includes/-/array-includes-3.2.0.tgz#18771e6837351aa139c3b58873371d0afa64964a"
+  integrity sha512-VXY5eFRarnXcYxwBjJzPmEhH55+rmP79/+ueDhi0F+TuqfHCItagIHqxeUZrmgrOPa31QTh9H85DjX3FfJ0FTg==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    define-properties "^1.2.1"
+    es-abstract "^1.24.2"
+    es-object-atoms "^1.1.2"
+    es-shim-unscopables "^1.1.0"
+    is-string "^1.1.1"
+    math-intrinsics "^1.1.0"
+
 array-union@^2.1.0:
   version "2.1.0"
   resolved "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz"
   integrity sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==
 
+array.prototype.findlast@^1.2.5:
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/array.prototype.findlast/-/array.prototype.findlast-1.2.5.tgz#3e4fbcb30a15a7f5bf64cf2faae22d139c2e4904"
+  integrity sha512-CVvd6FHg1Z3POpBLxO6E6zr+rSKEQ9L6rZHAaY7lLfhKsWYUBBOuMs0e9o24oopj6H+geRCX0YJ+TJLBK2eHyQ==
+  dependencies:
+    call-bind "^1.0.7"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.2"
+    es-errors "^1.3.0"
+    es-object-atoms "^1.0.0"
+    es-shim-unscopables "^1.0.2"
+
+array.prototype.flat@^1.3.1:
+  version "1.3.3"
+  resolved "https://registry.yarnpkg.com/array.prototype.flat/-/array.prototype.flat-1.3.3.tgz#534aaf9e6e8dd79fb6b9a9917f839ef1ec63afe5"
+  integrity sha512-rwG/ja1neyLqCuGZ5YYrznA62D4mZXg0i1cIskIUKSiqF3Cje9/wXAls9B9s1Wa2fomMsIv8czB8jZcPmxCXFg==
+  dependencies:
+    call-bind "^1.0.8"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.5"
+    es-shim-unscopables "^1.0.2"
+
+array.prototype.flatmap@^1.3.3:
+  version "1.3.3"
+  resolved "https://registry.yarnpkg.com/array.prototype.flatmap/-/array.prototype.flatmap-1.3.3.tgz#712cc792ae70370ae40586264629e33aab5dd38b"
+  integrity sha512-Y7Wt51eKJSyi80hFrJCePGGNo5ktJCslFuboqJsbf57CCPcm5zztluPlc4/aD8sWsKvlwatezpV4U1efk8kpjg==
+  dependencies:
+    call-bind "^1.0.8"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.5"
+    es-shim-unscopables "^1.0.2"
+
+array.prototype.tosorted@^1.1.4:
+  version "1.1.4"
+  resolved "https://registry.yarnpkg.com/array.prototype.tosorted/-/array.prototype.tosorted-1.1.4.tgz#fe954678ff53034e717ea3352a03f0b0b86f7ffc"
+  integrity sha512-p6Fx8B7b7ZhL/gmUsAy0D15WhvDccw3mnGNbZpi3pmeJdxtWsj2jEaI4Y6oo3XiHfzuSgPwKc04MYt6KgvC/wA==
+  dependencies:
+    call-bind "^1.0.7"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.3"
+    es-errors "^1.3.0"
+    es-shim-unscopables "^1.0.2"
+
+arraybuffer.prototype.slice@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/arraybuffer.prototype.slice/-/arraybuffer.prototype.slice-1.0.4.tgz#9d760d84dbdd06d0cbf92c8849615a1a7ab3183c"
+  integrity sha512-BNoCY6SXXPQ7gF2opIP4GBE+Xw7U+pHMYKuzjgCN3GwiaIR09UUeKfheyIry77QtrCBlC0KK0q5/TER/tYh3PQ==
+  dependencies:
+    array-buffer-byte-length "^1.0.1"
+    call-bind "^1.0.8"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.5"
+    es-errors "^1.3.0"
+    get-intrinsic "^1.2.6"
+    is-array-buffer "^3.0.4"
+
 asap@~2.0.3:
   version "2.0.6"
   resolved "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz"
   integrity sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==
 
+async-function@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/async-function/-/async-function-1.0.0.tgz#509c9fca60eaf85034c6829838188e4e4c8ffb2b"
+  integrity sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA==
+
 at-least-node@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz"
@@ -2805,6 +3242,13 @@ autoprefixer@^10.4.12, autoprefixer@^10.4.7:
     picocolors "^1.1.1"
     postcss-value-parser "^4.2.0"
 
+available-typed-arrays@^1.0.7:
+  version "1.0.7"
+  resolved "https://registry.yarnpkg.com/available-typed-arrays/-/available-typed-arrays-1.0.7.tgz#a5cc375d6a03c2efc87a553f3e0b1522def14846"
+  integrity sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==
+  dependencies:
+    possible-typed-array-names "^1.0.0"
+
 axios@^0.25.0:
   version "0.25.0"
   resolved "https://registry.npmjs.org/axios/-/axios-0.25.0.tgz"
@@ -2886,6 +3330,11 @@ balanced-match@^1.0.0:
   resolved "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz"
   integrity sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==
 
+balanced-match@^4.0.2:
+  version "4.0.4"
+  resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-4.0.4.tgz#bfb10662feed8196a2c62e7c68e17720c274179a"
+  integrity sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==
+
 base16@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/base16/-/base16-1.0.0.tgz"
@@ -2978,6 +3427,13 @@ brace-expansion@^1.1.7:
     balanced-match "^1.0.0"
     concat-map "0.0.1"
 
+brace-expansion@^5.0.8:
+  version "5.0.12"
+  resolved "https://registry.yarnpkg.com/brace-expansion/-/brace-expansion-5.0.12.tgz#995fbb4750a77c4d16a7dc942ff2ca6ef8e675ec"
+  integrity sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==
+  dependencies:
+    balanced-match "^4.0.2"
+
 braces@^3.0.3, braces@~3.0.2:
   version "3.0.3"
   resolved "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz"
@@ -3032,6 +3488,16 @@ call-bind-apply-helpers@^1.0.0, call-bind-apply-helpers@^1.0.1, call-bind-apply-
     es-errors "^1.3.0"
     function-bind "^1.1.2"
 
+call-bind@^1.0.7, call-bind@^1.0.9:
+  version "1.0.9"
+  resolved "https://registry.yarnpkg.com/call-bind/-/call-bind-1.0.9.tgz#39a644700c80bc7d0ca9102fc6d1d43b2fd7eee7"
+  integrity sha512-a/hy+pNsFUTR+Iz8TCJvXudKVLAnz/DyeSUo10I5yvFDQJBFU2s9uqQpoSrJlroHUKoKqzg+epxyP9lqFdzfBQ==
+  dependencies:
+    call-bind-apply-helpers "^1.0.2"
+    es-define-property "^1.0.1"
+    get-intrinsic "^1.3.0"
+    set-function-length "^1.2.2"
+
 call-bind@^1.0.8:
   version "1.0.8"
   resolved "https://registry.npmjs.org/call-bind/-/call-bind-1.0.8.tgz"
@@ -3042,7 +3508,7 @@ call-bind@^1.0.8:
     get-intrinsic "^1.2.4"
     set-function-length "^1.2.2"
 
-call-bound@^1.0.2, call-bound@^1.0.3:
+call-bound@^1.0.2, call-bound@^1.0.3, call-bound@^1.0.4:
   version "1.0.4"
   resolved "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz"
   integrity sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==
@@ -3447,7 +3913,7 @@ cross-fetch@^3.1.5:
   dependencies:
     node-fetch "^2.7.0"
 
-cross-spawn@^7.0.3:
+cross-spawn@^7.0.3, cross-spawn@^7.0.6:
   version "7.0.6"
   resolved "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz"
   integrity sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==
@@ -3605,6 +4071,33 @@ csstype@^3.2.2:
   resolved "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz"
   integrity sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==
 
+data-view-buffer@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/data-view-buffer/-/data-view-buffer-1.0.2.tgz#211a03ba95ecaf7798a8c7198d79536211f88570"
+  integrity sha512-EmKO5V3OLXh1rtK2wgXRansaK1/mtVdTUEiEI0W8RkvgT05kfxaH29PliLnpLP73yYO6142Q72QNa8Wx/A5CqQ==
+  dependencies:
+    call-bound "^1.0.3"
+    es-errors "^1.3.0"
+    is-data-view "^1.0.2"
+
+data-view-byte-length@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/data-view-byte-length/-/data-view-byte-length-1.0.2.tgz#9e80f7ca52453ce3e93d25a35318767ea7704735"
+  integrity sha512-tuhGbE6CfTM9+5ANGf+oQb72Ky/0+s3xKUpHvShfiz2RxMFgFPjsXuRLBVMtvMs15awe45SRb83D6wH4ew6wlQ==
+  dependencies:
+    call-bound "^1.0.3"
+    es-errors "^1.3.0"
+    is-data-view "^1.0.2"
+
+data-view-byte-offset@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/data-view-byte-offset/-/data-view-byte-offset-1.0.1.tgz#068307f9b71ab76dbbe10291389e020856606191"
+  integrity sha512-BS8PfmtDGnrgYdOonGZQdLZslWIeCGFP9tpan0hi1Co2Zr2NKADsvGYA8XxuG/4UWgJ6Cjtv+YJnB6MM69QGlQ==
+  dependencies:
+    call-bound "^1.0.2"
+    es-errors "^1.3.0"
+    is-data-view "^1.0.1"
+
 debounce@^1.2.1:
   version "1.2.1"
   resolved "https://registry.npmjs.org/debounce/-/debounce-1.2.1.tgz"
@@ -3617,7 +4110,7 @@ debug@2.6.9, debug@^2.6.0:
   dependencies:
     ms "2.0.0"
 
-debug@4, debug@^4.1.0, debug@^4.2.0, debug@^4.3.1, debug@^4.4.3:
+debug@4, debug@^4.1.0, debug@^4.2.0, debug@^4.3.1, debug@^4.3.2, debug@^4.4.3:
   version "4.4.3"
   resolved "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz"
   integrity sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==
@@ -3636,6 +4129,11 @@ deep-extend@^0.6.0:
   resolved "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz"
   integrity sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==
 
+deep-is@^0.1.3:
+  version "0.1.4"
+  resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.4.tgz#a6f2dce612fadd2ef1f519b73551f17e85199831"
+  integrity sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==
+
 deepmerge@^4.2.2:
   version "4.3.1"
   resolved "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz"
@@ -3667,7 +4165,7 @@ define-lazy-prop@^2.0.0:
   resolved "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-2.0.0.tgz"
   integrity sha512-Ds09qNh8yw3khSjiJjiUInaGX9xlqZDY7JVryGxdxV7NPeuqQfplOpQ66yJFZut3jLa5zOwkXw1g9EI2uKh4Og==
 
-define-properties@^1.2.1:
+define-properties@^1.1.3, define-properties@^1.2.1:
   version "1.2.1"
   resolved "https://registry.npmjs.org/define-properties/-/define-properties-1.2.1.tgz"
   integrity sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==
@@ -3747,6 +4245,13 @@ dns-packet@^5.2.2:
   dependencies:
     "@leichtgewicht/ip-codec" "^2.0.1"
 
+doctrine@^2.1.0:
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/doctrine/-/doctrine-2.1.0.tgz#5cd01fc101621b42c4cd7f5d1a66243716d3f39d"
+  integrity sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw==
+  dependencies:
+    esutils "^2.0.2"
+
 dom-converter@^0.2.0:
   version "0.2.0"
   resolved "https://registry.npmjs.org/dom-converter/-/dom-converter-0.2.0.tgz"
@@ -3829,7 +4334,7 @@ dotenv@^16.0.3:
   resolved "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz"
   integrity sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==
 
-dunder-proto@^1.0.1:
+dunder-proto@^1.0.0, dunder-proto@^1.0.1:
   version "1.0.1"
   resolved "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz"
   integrity sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==
@@ -3925,6 +4430,76 @@ error-ex@^1.3.1:
   dependencies:
     is-arrayish "^0.2.1"
 
+es-abstract-get@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/es-abstract-get/-/es-abstract-get-1.0.0.tgz#1eae87101f42bedeb6a740e8c5051271aef89088"
+  integrity sha512-6PMWXpdhshVvFp+FoWYs1EvG1Nj0tvk0dZM+XcK0xMEM1czRVcP6ohqPWHy6qPagSpC8j4+p89WXlT+xXJs/fg==
+  dependencies:
+    es-errors "^1.3.0"
+    es-object-atoms "^1.1.2"
+    is-callable "^1.2.7"
+    object-inspect "^1.13.4"
+
+es-abstract@^1.17.5, es-abstract@^1.23.2, es-abstract@^1.23.3, es-abstract@^1.23.5, es-abstract@^1.23.9, es-abstract@^1.24.2:
+  version "1.24.2"
+  resolved "https://registry.yarnpkg.com/es-abstract/-/es-abstract-1.24.2.tgz#2dbd38c180735ee983f77585140a2706a963ed9a"
+  integrity sha512-2FpH9Q5i2RRwyEP1AylXe6nYLR5OhaJTZwmlcP0dL/+JCbgg7yyEo/sEK6HeGZRf3dFpWwThaRHVApXSkW3xeg==
+  dependencies:
+    array-buffer-byte-length "^1.0.2"
+    arraybuffer.prototype.slice "^1.0.4"
+    available-typed-arrays "^1.0.7"
+    call-bind "^1.0.8"
+    call-bound "^1.0.4"
+    data-view-buffer "^1.0.2"
+    data-view-byte-length "^1.0.2"
+    data-view-byte-offset "^1.0.1"
+    es-define-property "^1.0.1"
+    es-errors "^1.3.0"
+    es-object-atoms "^1.1.1"
+    es-set-tostringtag "^2.1.0"
+    es-to-primitive "^1.3.0"
+    function.prototype.name "^1.1.8"
+    get-intrinsic "^1.3.0"
+    get-proto "^1.0.1"
+    get-symbol-description "^1.1.0"
+    globalthis "^1.0.4"
+    gopd "^1.2.0"
+    has-property-descriptors "^1.0.2"
+    has-proto "^1.2.0"
+    has-symbols "^1.1.0"
+    hasown "^2.0.2"
+    internal-slot "^1.1.0"
+    is-array-buffer "^3.0.5"
+    is-callable "^1.2.7"
+    is-data-view "^1.0.2"
+    is-negative-zero "^2.0.3"
+    is-regex "^1.2.1"
+    is-set "^2.0.3"
+    is-shared-array-buffer "^1.0.4"
+    is-string "^1.1.1"
+    is-typed-array "^1.1.15"
+    is-weakref "^1.1.1"
+    math-intrinsics "^1.1.0"
+    object-inspect "^1.13.4"
+    object-keys "^1.1.1"
+    object.assign "^4.1.7"
+    own-keys "^1.0.1"
+    regexp.prototype.flags "^1.5.4"
+    safe-array-concat "^1.1.3"
+    safe-push-apply "^1.0.0"
+    safe-regex-test "^1.1.0"
+    set-proto "^1.0.0"
+    stop-iteration-iterator "^1.1.0"
+    string.prototype.trim "^1.2.10"
+    string.prototype.trimend "^1.0.9"
+    string.prototype.trimstart "^1.0.8"
+    typed-array-buffer "^1.0.3"
+    typed-array-byte-length "^1.0.3"
+    typed-array-byte-offset "^1.0.4"
+    typed-array-length "^1.0.7"
+    unbox-primitive "^1.1.0"
+    which-typed-array "^1.1.19"
+
 es-define-property@^1.0.0, es-define-property@^1.0.1:
   version "1.0.1"
   resolved "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz"
@@ -3935,6 +4510,28 @@ es-errors@^1.3.0:
   resolved "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz"
   integrity sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==
 
+es-iterator-helpers@^1.2.1:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/es-iterator-helpers/-/es-iterator-helpers-1.4.0.tgz#2b4635ee3e8db2285378a47a1ea8f8dd34adb653"
+  integrity sha512-c/A0P0oxkACDc+cKWw8evLXK83oBKgn0qPOqCYT4x9uolpCIJAcYvJC9QYKNDRPsTeGyCrQ326jrvgZWdCdK5Q==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    define-properties "^1.2.1"
+    es-abstract "^1.24.2"
+    es-errors "^1.3.0"
+    es-set-tostringtag "^2.1.0"
+    function-bind "^1.1.2"
+    get-intrinsic "^1.3.0"
+    globalthis "^1.0.4"
+    gopd "^1.2.0"
+    has-property-descriptors "^1.0.2"
+    has-proto "^1.2.0"
+    has-symbols "^1.1.0"
+    internal-slot "^1.1.0"
+    iterator.prototype "^1.1.5"
+    math-intrinsics "^1.1.0"
+
 es-module-lexer@^2.0.0:
   version "2.0.0"
   resolved "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.0.0.tgz"
@@ -3947,6 +4544,42 @@ es-object-atoms@^1.0.0, es-object-atoms@^1.1.1:
   dependencies:
     es-errors "^1.3.0"
 
+es-object-atoms@^1.1.2:
+  version "1.1.2"
+  resolved "https://registry.yarnpkg.com/es-object-atoms/-/es-object-atoms-1.1.2.tgz#a2d0b373205724dfa525d23b0c3e1b1ca582c99b"
+  integrity sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==
+  dependencies:
+    es-errors "^1.3.0"
+
+es-set-tostringtag@^2.1.0:
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz#f31dbbe0c183b00a6d26eb6325c810c0fd18bd4d"
+  integrity sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==
+  dependencies:
+    es-errors "^1.3.0"
+    get-intrinsic "^1.2.6"
+    has-tostringtag "^1.0.2"
+    hasown "^2.0.2"
+
+es-shim-unscopables@^1.0.2, es-shim-unscopables@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/es-shim-unscopables/-/es-shim-unscopables-1.1.0.tgz#438df35520dac5d105f3943d927549ea3b00f4b5"
+  integrity sha512-d9T8ucsEhh8Bi1woXCf+TIKDIROLG5WCkxg8geBCbvk22kzwC5G2OnXVMO6FUsvQlgUUXQ2itephWDLqDzbeCw==
+  dependencies:
+    hasown "^2.0.2"
+
+es-to-primitive@^1.3.0:
+  version "1.3.4"
+  resolved "https://registry.yarnpkg.com/es-to-primitive/-/es-to-primitive-1.3.4.tgz#0c854291cf0d7b439d6b9e5771ea837ffaf1f991"
+  integrity sha512-yPDz7wqpg1/mmHLmS3tcfTfbw5f1eryXvyghYBffGdERwe+mV7ZcWzTR8LR17Kvqt3qfPurjlonmnq3MKXIOXw==
+  dependencies:
+    es-abstract-get "^1.0.0"
+    es-define-property "^1.0.1"
+    es-errors "^1.3.0"
+    is-callable "^1.2.7"
+    is-date-object "^1.1.0"
+    is-symbol "^1.1.1"
+
 escalade@^3.2.0:
   version "3.2.0"
   resolved "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz"
@@ -3967,6 +4600,41 @@ escape-string-regexp@^4.0.0:
   resolved "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz"
   integrity sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==
 
+eslint-plugin-react-hooks@^7.1.1:
+  version "7.1.1"
+  resolved "https://registry.yarnpkg.com/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz#e6742cad75d970c0a3f30d7d3fa80a4784f55927"
+  integrity sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==
+  dependencies:
+    "@babel/core" "^7.24.4"
+    "@babel/parser" "^7.24.4"
+    hermes-parser "^0.25.1"
+    zod "^3.25.0 || ^4.0.0"
+    zod-validation-error "^3.5.0 || ^4.0.0"
+
+eslint-plugin-react@^7.37.5:
+  version "7.37.5"
+  resolved "https://registry.yarnpkg.com/eslint-plugin-react/-/eslint-plugin-react-7.37.5.tgz#2975511472bdda1b272b34d779335c9b0e877065"
+  integrity sha512-Qteup0SqU15kdocexFNAJMvCJEfa2xUKNV4CC1xsVMrIIqEy3SQ/rqyxCWNzfrd3/ldy6HMlD2e0JDVpDg2qIA==
+  dependencies:
+    array-includes "^3.1.8"
+    array.prototype.findlast "^1.2.5"
+    array.prototype.flatmap "^1.3.3"
+    array.prototype.tosorted "^1.1.4"
+    doctrine "^2.1.0"
+    es-iterator-helpers "^1.2.1"
+    estraverse "^5.3.0"
+    hasown "^2.0.2"
+    jsx-ast-utils "^2.4.1 || ^3.0.0"
+    minimatch "^3.1.2"
+    object.entries "^1.1.9"
+    object.fromentries "^2.0.8"
+    object.values "^1.2.1"
+    prop-types "^15.8.1"
+    resolve "^2.0.0-next.5"
+    semver "^6.3.1"
+    string.prototype.matchall "^4.0.12"
+    string.prototype.repeat "^1.0.0"
+
 eslint-scope@5.1.1:
   version "5.1.1"
   resolved "https://registry.npmjs.org/eslint-scope/-/eslint-scope-5.1.1.tgz"
@@ -3975,11 +4643,90 @@ eslint-scope@5.1.1:
     esrecurse "^4.3.0"
     estraverse "^4.1.1"
 
+eslint-scope@^8.4.0:
+  version "8.4.0"
+  resolved "https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-8.4.0.tgz#88e646a207fad61436ffa39eb505147200655c82"
+  integrity sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==
+  dependencies:
+    esrecurse "^4.3.0"
+    estraverse "^5.2.0"
+
+eslint-visitor-keys@^3.4.3:
+  version "3.4.3"
+  resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz#0cd72fe8550e3c2eae156a96a4dddcd1c8ac5800"
+  integrity sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==
+
+eslint-visitor-keys@^4.2.1:
+  version "4.2.1"
+  resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz#4cfea60fe7dd0ad8e816e1ed026c1d5251b512c1"
+  integrity sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==
+
+eslint-visitor-keys@^5.0.0:
+  version "5.0.1"
+  resolved "https://registry.yarnpkg.com/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz#9e3c9489697824d2d4ce3a8ad12628f91e9f59be"
+  integrity sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==
+
+eslint@^9.39.0:
+  version "9.39.5"
+  resolved "https://registry.yarnpkg.com/eslint/-/eslint-9.39.5.tgz#2a4e3c8b0f753196efae943c8ffaa8730fc6a3fa"
+  integrity sha512-DgZS62aPLXKlnxILS/AYCoRvHaZeXceIzlXPkkGGzJWSow1aEk0lbTlxUSlyjC8jcaKxAdOnTDz+o1JFSBsyjw==
+  dependencies:
+    "@eslint-community/eslint-utils" "^4.8.0"
+    "@eslint-community/regexpp" "^4.12.1"
+    "@eslint/config-array" "^0.21.2"
+    "@eslint/config-helpers" "^0.4.2"
+    "@eslint/core" "^0.17.0"
+    "@eslint/eslintrc" "^3.3.6"
+    "@eslint/js" "9.39.5"
+    "@eslint/plugin-kit" "^0.4.1"
+    "@humanfs/node" "^0.16.6"
+    "@humanwhocodes/module-importer" "^1.0.1"
+    "@humanwhocodes/retry" "^0.4.2"
+    "@types/estree" "^1.0.6"
+    ajv "^6.14.0"
+    chalk "^4.0.0"
+    cross-spawn "^7.0.6"
+    debug "^4.3.2"
+    escape-string-regexp "^4.0.0"
+    eslint-scope "^8.4.0"
+    eslint-visitor-keys "^4.2.1"
+    espree "^10.4.0"
+    esquery "^1.5.0"
+    esutils "^2.0.2"
+    fast-deep-equal "^3.1.3"
+    file-entry-cache "^8.0.0"
+    find-up "^5.0.0"
+    glob-parent "^6.0.2"
+    ignore "^5.2.0"
+    imurmurhash "^0.1.4"
+    is-glob "^4.0.0"
+    json-stable-stringify-without-jsonify "^1.0.1"
+    lodash.merge "^4.6.2"
+    minimatch "^3.1.5"
+    natural-compare "^1.4.0"
+    optionator "^0.9.3"
+
+espree@^10.0.1, espree@^10.4.0:
+  version "10.4.0"
+  resolved "https://registry.yarnpkg.com/espree/-/espree-10.4.0.tgz#d54f4949d4629005a1fa168d937c3ff1f7e2a837"
+  integrity sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==
+  dependencies:
+    acorn "^8.15.0"
+    acorn-jsx "^5.3.2"
+    eslint-visitor-keys "^4.2.1"
+
 esprima@^4.0.0:
   version "4.0.1"
   resolved "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz"
   integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
 
+esquery@^1.5.0:
+  version "1.7.0"
+  resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.7.0.tgz#08d048f261f0ddedb5bae95f46809463d9c9496d"
+  integrity sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==
+  dependencies:
+    estraverse "^5.1.0"
+
 esrecurse@^4.3.0:
   version "4.3.0"
   resolved "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz"
@@ -3992,7 +4739,7 @@ estraverse@^4.1.1:
   resolved "https://registry.npmjs.org/estraverse/-/estraverse-4.3.0.tgz"
   integrity sha512-39nnKffWz8xN1BU/2c79n9nB9HDzo0niYUqx6xyqUnyoAnQyyWpOTdZEeiCch8BBu515t4wp9ZmgVfVhn9EBpw==
 
-estraverse@^5.2.0:
+estraverse@^5.1.0, estraverse@^5.2.0, estraverse@^5.3.0:
   version "5.3.0"
   resolved "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz"
   integrity sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==
@@ -4115,6 +4862,11 @@ fast-json-stable-stringify@^2.0.0:
   resolved "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz"
   integrity sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==
 
+fast-levenshtein@^2.0.6:
+  version "2.0.6"
+  resolved "https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz#3d8a5c66883a16a30ca8643e851f19baa7797917"
+  integrity sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==
+
 fast-uri@^3.0.1:
   version "3.1.0"
   resolved "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz"
@@ -4159,6 +4911,11 @@ fbjs@^3.0.0, fbjs@^3.0.1:
     setimmediate "^1.0.5"
     ua-parser-js "^1.0.35"
 
+fdir@^6.5.0:
+  version "6.5.0"
+  resolved "https://registry.yarnpkg.com/fdir/-/fdir-6.5.0.tgz#ed2ab967a331ade62f18d077dae192684d50d350"
+  integrity sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==
+
 feed@^4.2.2:
   version "4.2.2"
   resolved "https://registry.npmjs.org/feed/-/feed-4.2.2.tgz"
@@ -4166,6 +4923,13 @@ feed@^4.2.2:
   dependencies:
     xml-js "^1.6.11"
 
+file-entry-cache@^8.0.0:
+  version "8.0.0"
+  resolved "https://registry.yarnpkg.com/file-entry-cache/-/file-entry-cache-8.0.0.tgz#7787bddcf1131bffb92636c69457bbc0edd6d81f"
+  integrity sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==
+  dependencies:
+    flat-cache "^4.0.0"
+
 file-loader@^6.2.0:
   version "6.2.0"
   resolved "https://registry.npmjs.org/file-loader/-/file-loader-6.2.0.tgz"
@@ -4231,11 +4995,24 @@ find-up@^5.0.0:
     locate-path "^6.0.0"
     path-exists "^4.0.0"
 
+flat-cache@^4.0.0:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/flat-cache/-/flat-cache-4.0.1.tgz#0ece39fcb14ee012f4b0410bd33dd9c1f011127c"
+  integrity sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==
+  dependencies:
+    flatted "^3.2.9"
+    keyv "^4.5.4"
+
 flat@^5.0.2:
   version "5.0.2"
   resolved "https://registry.npmjs.org/flat/-/flat-5.0.2.tgz"
   integrity sha512-b6suED+5/3rTpUBdG1gupIl8MPFCAMA0QXwmljLhvCUKcUvdE4gWky9zpuGCcXHOsz4J9wPGNWq6OKpmIzz3hQ==
 
+flatted@^3.2.9:
+  version "3.4.4"
+  resolved "https://registry.yarnpkg.com/flatted/-/flatted-3.4.4.tgz#aeeca2a506303f0cee61c59e6c9f2a88d2f29fc6"
+  integrity sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q==
+
 flux@^4.0.1:
   version "4.0.4"
   resolved "https://registry.npmjs.org/flux/-/flux-4.0.4.tgz"
@@ -4249,6 +5026,13 @@ follow-redirects@^1.0.0, follow-redirects@^1.14.7:
   resolved "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz"
   integrity sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==
 
+for-each@^0.3.3, for-each@^0.3.5:
+  version "0.3.5"
+  resolved "https://registry.yarnpkg.com/for-each/-/for-each-0.3.5.tgz#d650688027826920feeb0af747ee7b9421a41d47"
+  integrity sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==
+  dependencies:
+    is-callable "^1.2.7"
+
 fork-ts-checker-webpack-plugin@^6.5.0:
   version "6.5.3"
   resolved "https://registry.npmjs.org/fork-ts-checker-webpack-plugin/-/fork-ts-checker-webpack-plugin-6.5.3.tgz"
@@ -4322,12 +5106,37 @@ function-bind@^1.1.2:
   resolved "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz"
   integrity sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==
 
-gensync@^1.0.0-beta.1, gensync@^1.0.0-beta.2:
-  version "1.0.0-beta.2"
-  resolved "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz"
-  integrity sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==
-
-get-intrinsic@^1.2.4, get-intrinsic@^1.2.5, get-intrinsic@^1.3.0:
+function.prototype.name@^1.1.6, function.prototype.name@^1.1.8:
+  version "1.2.0"
+  resolved "https://registry.yarnpkg.com/function.prototype.name/-/function.prototype.name-1.2.0.tgz#758f3e84fa542672454bd5e14cb081a5ce07f70c"
+  integrity sha512-jObKIik1P2QjPHP5nz5BaOtUlfgS0fWo8IUByNXkM+o+02sJOi94em77GwJKQSJ3gfPHdgzLNrHc1uokV4P/ew==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    es-define-property "^1.0.1"
+    es-errors "^1.3.0"
+    functions-have-names "^1.2.3"
+    has-property-descriptors "^1.0.2"
+    hasown "^2.0.4"
+    is-callable "^1.2.7"
+    is-document.all "^1.0.0"
+
+functions-have-names@^1.2.3:
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/functions-have-names/-/functions-have-names-1.2.3.tgz#0404fe4ee2ba2f607f0e0ec3c80bae994133b834"
+  integrity sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==
+
+generator-function@^2.0.0:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/generator-function/-/generator-function-2.0.1.tgz#0e75dd410d1243687a0ba2e951b94eedb8f737a2"
+  integrity sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==
+
+gensync@^1.0.0-beta.1, gensync@^1.0.0-beta.2:
+  version "1.0.0-beta.2"
+  resolved "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz"
+  integrity sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==
+
+get-intrinsic@^1.2.4, get-intrinsic@^1.2.5, get-intrinsic@^1.2.6, get-intrinsic@^1.2.7, get-intrinsic@^1.3.0:
   version "1.3.0"
   resolved "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz"
   integrity sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==
@@ -4348,7 +5157,7 @@ get-own-enumerable-property-symbols@^3.0.0:
   resolved "https://registry.npmjs.org/get-own-enumerable-property-symbols/-/get-own-enumerable-property-symbols-3.0.2.tgz"
   integrity sha512-I0UBV/XOz1XkIJHEUDMZAbzCThU/H8DxmSfmdGcKPnVhu2VfFqr34jr9777IyaTYvxjedWhqVIilEDsCdP5G6g==
 
-get-proto@^1.0.1:
+get-proto@^1.0.0, get-proto@^1.0.1:
   version "1.0.1"
   resolved "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz"
   integrity sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==
@@ -4375,6 +5184,15 @@ get-stream@^6.0.0:
   resolved "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz"
   integrity sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==
 
+get-symbol-description@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/get-symbol-description/-/get-symbol-description-1.1.0.tgz#7bdd54e0befe8ffc9f3b4e203220d9f1e881b6ee"
+  integrity sha512-w9UMqWwJxHNOvoNzSJ2oPF5wvYcvP7jUvYzhp67yEhTi17ZDBBC1z9pTdGuzjD+EFIqLSYRweZjqfiPzQ06Ebg==
+  dependencies:
+    call-bound "^1.0.3"
+    es-errors "^1.3.0"
+    get-intrinsic "^1.2.6"
+
 github-slugger@^1.4.0:
   version "1.5.0"
   resolved "https://registry.npmjs.org/github-slugger/-/github-slugger-1.5.0.tgz"
@@ -4387,7 +5205,7 @@ glob-parent@^5.1.2, glob-parent@~5.1.2:
   dependencies:
     is-glob "^4.0.1"
 
-glob-parent@^6.0.1:
+glob-parent@^6.0.1, glob-parent@^6.0.2:
   version "6.0.2"
   resolved "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz"
   integrity sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==
@@ -4434,6 +5252,24 @@ global-prefix@^3.0.0:
     kind-of "^6.0.2"
     which "^1.3.1"
 
+globals@^14.0.0:
+  version "14.0.0"
+  resolved "https://registry.yarnpkg.com/globals/-/globals-14.0.0.tgz#898d7413c29babcf6bafe56fcadded858ada724e"
+  integrity sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==
+
+globals@^17.13.0:
+  version "17.13.0"
+  resolved "https://registry.yarnpkg.com/globals/-/globals-17.13.0.tgz#ab2134b5ededbf2fbe2831dd0acc36f4f1ddeac5"
+  integrity sha512-RwMTC61u7hrG3ZJMkZQOK4JLJrKS8QtoTii63EmWvFXHqycY9FObBJQCbsLxSO8kjKhWE5kV1GC+Vb1g3RI0Zg==
+
+globalthis@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/globalthis/-/globalthis-1.0.4.tgz#7430ed3a975d97bfb59bcce41f5cabbafa651236"
+  integrity sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ==
+  dependencies:
+    define-properties "^1.2.1"
+    gopd "^1.0.1"
+
 globby@^11.0.1, globby@^11.0.4, globby@^11.1.0:
   version "11.1.0"
   resolved "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz"
@@ -4506,6 +5342,11 @@ handle-thing@^2.0.0:
   resolved "https://registry.npmjs.org/handle-thing/-/handle-thing-2.0.1.tgz"
   integrity sha512-9Qn4yBxelxoh2Ow62nP+Ka/kMnOXRi8BXnRaUwezLNhqelnN49xKz4F/dPP8OYLxLxq6JDtZb2i9XznUQbNPTg==
 
+has-bigints@^1.0.2:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/has-bigints/-/has-bigints-1.1.0.tgz#28607e965ac967e03cd2a2c70a2636a1edad49fe"
+  integrity sha512-R3pbpkcIqv2Pm3dUwgjclDRVmWpTJW2DcMzcIhEXEx1oh/CEMObMm3KLmRJOdvhM7o4uQBnwr8pzRK2sJWIqfg==
+
 has-flag@^4.0.0:
   version "4.0.0"
   resolved "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz"
@@ -4518,11 +5359,25 @@ has-property-descriptors@^1.0.0, has-property-descriptors@^1.0.2:
   dependencies:
     es-define-property "^1.0.0"
 
-has-symbols@^1.1.0:
+has-proto@^1.2.0:
+  version "1.2.0"
+  resolved "https://registry.yarnpkg.com/has-proto/-/has-proto-1.2.0.tgz#5de5a6eabd95fdffd9818b43055e8065e39fe9d5"
+  integrity sha512-KIL7eQPfHQRC8+XluaIw7BHUwwqL19bQn4hzNgdr+1wXoU0KKj6rufu47lhY7KbJR2C6T6+PfyN0Ea7wkSS+qQ==
+  dependencies:
+    dunder-proto "^1.0.0"
+
+has-symbols@^1.0.3, has-symbols@^1.1.0:
   version "1.1.0"
   resolved "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz"
   integrity sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==
 
+has-tostringtag@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/has-tostringtag/-/has-tostringtag-1.0.2.tgz#2cdc42d40bef2e5b4eeab7c01a73c54ce7ab5abc"
+  integrity sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==
+  dependencies:
+    has-symbols "^1.0.3"
+
 has-yarn@^2.1.0:
   version "2.1.0"
   resolved "https://registry.npmjs.org/has-yarn/-/has-yarn-2.1.0.tgz"
@@ -4535,6 +5390,13 @@ hasown@^2.0.2:
   dependencies:
     function-bind "^1.1.2"
 
+hasown@^2.0.4:
+  version "2.0.4"
+  resolved "https://registry.yarnpkg.com/hasown/-/hasown-2.0.4.tgz#8c62d8cb90beb2aad5d0a5b67581ad9854c3f003"
+  integrity sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==
+  dependencies:
+    function-bind "^1.1.2"
+
 hast-to-hyperscript@^9.0.0:
   version "9.0.1"
   resolved "https://registry.npmjs.org/hast-to-hyperscript/-/hast-to-hyperscript-9.0.1.tgz"
@@ -4622,6 +5484,18 @@ he@^1.2.0:
   resolved "https://registry.npmjs.org/he/-/he-1.2.0.tgz"
   integrity sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==
 
+hermes-estree@0.25.1:
+  version "0.25.1"
+  resolved "https://registry.yarnpkg.com/hermes-estree/-/hermes-estree-0.25.1.tgz#6aeec17d1983b4eabf69721f3aa3eb705b17f480"
+  integrity sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==
+
+hermes-parser@^0.25.1:
+  version "0.25.1"
+  resolved "https://registry.yarnpkg.com/hermes-parser/-/hermes-parser-0.25.1.tgz#5be0e487b2090886c62bd8a11724cd766d5f54d1"
+  integrity sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==
+  dependencies:
+    hermes-estree "0.25.1"
+
 history@^4.9.0:
   version "4.10.1"
   resolved "https://registry.npmjs.org/history/-/history-4.10.1.tgz"
@@ -4794,6 +5668,11 @@ ignore@^5.2.0, ignore@^5.2.4:
   resolved "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz"
   integrity sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==
 
+ignore@^7.0.5:
+  version "7.0.14"
+  resolved "https://registry.yarnpkg.com/ignore/-/ignore-7.0.14.tgz#a52b081dfb4d77e947e04d5f9e320b16f1873959"
+  integrity sha512-wCBiZ77u1tuWde6G/nfOtLaCTYcFDU5yCzARzK10y+rLhzYoL7a7yEemcopcc2Mzow7gZOIjnV2ym1NYmdiJOQ==
+
 image-size@^1.0.1:
   version "1.2.1"
   resolved "https://registry.npmjs.org/image-size/-/image-size-1.2.1.tgz"
@@ -4867,6 +5746,15 @@ inline-style-parser@0.1.1:
   resolved "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.1.1.tgz"
   integrity sha512-7NXolsK4CAS5+xvdj5OMMbI962hU/wvwoxk+LWR9Ek9bVtyuuYScDN6eS0rUm6TxApFpw7CX1o4uJzcd4AyD3Q==
 
+internal-slot@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/internal-slot/-/internal-slot-1.1.0.tgz#1eac91762947d2f7056bc838d93e13b2e9604961"
+  integrity sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==
+  dependencies:
+    es-errors "^1.3.0"
+    hasown "^2.0.2"
+    side-channel "^1.1.0"
+
 interpret@^1.0.0:
   version "1.4.0"
   resolved "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz"
@@ -4902,11 +5790,38 @@ is-alphanumerical@^1.0.0:
     is-alphabetical "^1.0.0"
     is-decimal "^1.0.0"
 
+is-array-buffer@^3.0.4, is-array-buffer@^3.0.5:
+  version "3.0.5"
+  resolved "https://registry.yarnpkg.com/is-array-buffer/-/is-array-buffer-3.0.5.tgz#65742e1e687bd2cc666253068fd8707fe4d44280"
+  integrity sha512-DDfANUiiG2wC1qawP66qlTugJeL5HyzMpfr8lLK+jMQirGzNod0B12cFB/9q838Ru27sBwfw78/rdoU7RERz6A==
+  dependencies:
+    call-bind "^1.0.8"
+    call-bound "^1.0.3"
+    get-intrinsic "^1.2.6"
+
 is-arrayish@^0.2.1:
   version "0.2.1"
   resolved "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz"
   integrity sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==
 
+is-async-function@^2.0.0:
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/is-async-function/-/is-async-function-2.1.1.tgz#3e69018c8e04e73b738793d020bfe884b9fd3523"
+  integrity sha512-9dgM/cZBnNvjzaMYHVoxxfPj2QXt22Ev7SuuPrs+xav0ukGB0S6d4ydZdEiM48kLx5kDV+QBPrpVnFyefL8kkQ==
+  dependencies:
+    async-function "^1.0.0"
+    call-bound "^1.0.3"
+    get-proto "^1.0.1"
+    has-tostringtag "^1.0.2"
+    safe-regex-test "^1.1.0"
+
+is-bigint@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/is-bigint/-/is-bigint-1.1.0.tgz#dda7a3445df57a42583db4228682eba7c4170672"
+  integrity sha512-n4ZT37wG78iz03xPRKJrHTdZbe3IicyucEtdRsV5yglwc3GyUfbAfpSeD0FJ41NbUNSt5wbhqfp1fS+BgnvDFQ==
+  dependencies:
+    has-bigints "^1.0.2"
+
 is-binary-path@~2.1.0:
   version "2.1.0"
   resolved "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz"
@@ -4914,11 +5829,24 @@ is-binary-path@~2.1.0:
   dependencies:
     binary-extensions "^2.0.0"
 
+is-boolean-object@^1.2.1:
+  version "1.2.2"
+  resolved "https://registry.yarnpkg.com/is-boolean-object/-/is-boolean-object-1.2.2.tgz#7067f47709809a393c71ff5bb3e135d8a9215d9e"
+  integrity sha512-wa56o2/ElJMYqjCjGkXri7it5FbebW5usLw/nPmCMs5DeZ7eziSYZhSmPRn0txqeW4LnAmQQU7FgqLpsEFKM4A==
+  dependencies:
+    call-bound "^1.0.3"
+    has-tostringtag "^1.0.2"
+
 is-buffer@^2.0.0:
   version "2.0.5"
   resolved "https://registry.npmjs.org/is-buffer/-/is-buffer-2.0.5.tgz"
   integrity sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==
 
+is-callable@^1.2.7:
+  version "1.2.7"
+  resolved "https://registry.yarnpkg.com/is-callable/-/is-callable-1.2.7.tgz#3bc2a85ea742d9e36205dcacdd72ca1fdc51b055"
+  integrity sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==
+
 is-ci@^2.0.0:
   version "2.0.0"
   resolved "https://registry.npmjs.org/is-ci/-/is-ci-2.0.0.tgz"
@@ -4933,6 +5861,30 @@ is-core-module@^2.16.1:
   dependencies:
     hasown "^2.0.2"
 
+is-core-module@^2.16.2:
+  version "2.17.0"
+  resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.17.0.tgz#75c1c76236c9f7e38ddbfff292e127dc13b21027"
+  integrity sha512-J/vG0zBCbIKOQFfufSwyXdMrsohyJIUNkrnmo6WZGzoM7tr/lsbfW5b2BvisL6zsyMzK9UxV9L6c7AoFbyXHOA==
+  dependencies:
+    hasown "^2.0.4"
+
+is-data-view@^1.0.1, is-data-view@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/is-data-view/-/is-data-view-1.0.2.tgz#bae0a41b9688986c2188dda6657e56b8f9e63b8e"
+  integrity sha512-RKtWF8pGmS87i2D6gqQu/l7EYRlVdfzemCJN/P3UOs//x1QE7mfhvzHIApBTRf7axvT6DMGwSwBXYCT0nfB9xw==
+  dependencies:
+    call-bound "^1.0.2"
+    get-intrinsic "^1.2.6"
+    is-typed-array "^1.1.13"
+
+is-date-object@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/is-date-object/-/is-date-object-1.1.0.tgz#ad85541996fc7aa8b2729701d27b7319f95d82f7"
+  integrity sha512-PwwhEakHVKTdRNVOw+/Gyh0+MzlCl4R6qKvkhuvLtPMggI1WAHt9sOwZxQLSGpUaDnrdyDsomoRgNnCfKNSXXg==
+  dependencies:
+    call-bound "^1.0.2"
+    has-tostringtag "^1.0.2"
+
 is-decimal@^1.0.0:
   version "1.0.4"
   resolved "https://registry.npmjs.org/is-decimal/-/is-decimal-1.0.4.tgz"
@@ -4943,6 +5895,13 @@ is-docker@^2.0.0, is-docker@^2.1.1:
   resolved "https://registry.npmjs.org/is-docker/-/is-docker-2.2.1.tgz"
   integrity sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==
 
+is-document.all@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/is-document.all/-/is-document.all-1.0.0.tgz#163a4bfb362c6ed7b118ce46cdecc4e37dee3195"
+  integrity sha512-+XSoyS05OdBbhFuELhgTCpFNHkpBOJqtsZfUFFpe5QTw+9Sjbh8zitxhQkYAo6wV7e1Vb8cAPvpCk9jGam/82g==
+  dependencies:
+    call-bound "^1.0.4"
+
 is-extendable@^0.1.0:
   version "0.1.1"
   resolved "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz"
@@ -4953,12 +5912,30 @@ is-extglob@^2.1.1:
   resolved "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz"
   integrity sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==
 
+is-finalizationregistry@^1.1.0:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/is-finalizationregistry/-/is-finalizationregistry-1.1.1.tgz#eefdcdc6c94ddd0674d9c85887bf93f944a97c90"
+  integrity sha512-1pC6N8qWJbWoPtEjgcL2xyhQOP491EQjeUo3qTKcmV8YSDDJrOepfG8pcC7h/QgnQHYSv0mJ3Z/ZWxmatVrysg==
+  dependencies:
+    call-bound "^1.0.3"
+
 is-fullwidth-code-point@^3.0.0:
   version "3.0.0"
   resolved "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz"
   integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==
 
-is-glob@^4.0.1, is-glob@^4.0.3, is-glob@~4.0.1:
+is-generator-function@^1.0.10:
+  version "1.1.2"
+  resolved "https://registry.yarnpkg.com/is-generator-function/-/is-generator-function-1.1.2.tgz#ae3b61e3d5ea4e4839b90bad22b02335051a17d5"
+  integrity sha512-upqt1SkGkODW9tsGNG5mtXTXtECizwtS2kA161M+gJPc1xdb/Ax629af6YrTwcOeQHbewrPNlE5Dx7kzvXTizA==
+  dependencies:
+    call-bound "^1.0.4"
+    generator-function "^2.0.0"
+    get-proto "^1.0.1"
+    has-tostringtag "^1.0.2"
+    safe-regex-test "^1.1.0"
+
+is-glob@^4.0.0, is-glob@^4.0.1, is-glob@^4.0.3, is-glob@~4.0.1:
   version "4.0.3"
   resolved "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz"
   integrity sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==
@@ -4978,11 +5955,29 @@ is-installed-globally@^0.4.0:
     global-dirs "^3.0.0"
     is-path-inside "^3.0.2"
 
+is-map@^2.0.3:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/is-map/-/is-map-2.0.3.tgz#ede96b7fe1e270b3c4465e3a465658764926d62e"
+  integrity sha512-1Qed0/Hr2m+YqxnM09CjA2d/i6YZNfF6R2oRAOj36eUdS6qIV/huPJNSEpKbupewFs+ZsJlxsjjPbc0/afW6Lw==
+
+is-negative-zero@^2.0.3:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/is-negative-zero/-/is-negative-zero-2.0.3.tgz#ced903a027aca6381b777a5743069d7376a49747"
+  integrity sha512-5KoIu2Ngpyek75jXodFvnafB6DJgr3u8uuK0LEZJjrU19DrMD3EVERaR8sjz8CCGgpZvxPl9SuE1GMVPFHx1mw==
+
 is-npm@^5.0.0:
   version "5.0.0"
   resolved "https://registry.npmjs.org/is-npm/-/is-npm-5.0.0.tgz"
   integrity sha512-WW/rQLOazUq+ST/bCAVBp/2oMERWLsR7OrKyt052dNDk4DHcDE0/7QSXITlmi+VBcV13DfIbysG3tZJm5RfdBA==
 
+is-number-object@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/is-number-object/-/is-number-object-1.1.1.tgz#144b21e95a1bc148205dcc2814a9134ec41b2541"
+  integrity sha512-lZhclumE1G6VYD8VHe35wFaIif+CTy5SJIi5+3y4psDgWu4wPDoBhF8NxUOinEc7pHgiTsT6MaBb92rKhhD+Xw==
+  dependencies:
+    call-bound "^1.0.3"
+    has-tostringtag "^1.0.2"
+
 is-number@^7.0.0:
   version "7.0.0"
   resolved "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz"
@@ -5025,6 +6020,16 @@ is-plain-object@^2.0.4:
   dependencies:
     isobject "^3.0.1"
 
+is-regex@^1.2.1:
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/is-regex/-/is-regex-1.2.1.tgz#76d70a3ed10ef9be48eb577887d74205bf0cad22"
+  integrity sha512-MjYsKHO5O7mCsmRGxWcLWheFqN9DJ/2TmngvjKXihe6efViPqc274+Fx/4fYj/r03+ESvBdTXK0V6tA3rgez1g==
+  dependencies:
+    call-bound "^1.0.2"
+    gopd "^1.2.0"
+    has-tostringtag "^1.0.2"
+    hasown "^2.0.2"
+
 is-regexp@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/is-regexp/-/is-regexp-1.0.0.tgz"
@@ -5035,16 +6040,72 @@ is-root@^2.1.0:
   resolved "https://registry.npmjs.org/is-root/-/is-root-2.1.0.tgz"
   integrity sha512-AGOriNp96vNBd3HtU+RzFEc75FfR5ymiYv8E553I71SCeXBiMsVDUtdio1OEFvrPyLIQ9tVR5RxXIFe5PUFjMg==
 
+is-set@^2.0.3:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/is-set/-/is-set-2.0.3.tgz#8ab209ea424608141372ded6e0cb200ef1d9d01d"
+  integrity sha512-iPAjerrse27/ygGLxw+EBR9agv9Y6uLeYVJMu+QNCoouJ1/1ri0mGrcWpfCqFZuzzx3WjtwxG098X+n4OuRkPg==
+
+is-shared-array-buffer@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/is-shared-array-buffer/-/is-shared-array-buffer-1.0.4.tgz#9b67844bd9b7f246ba0708c3a93e34269c774f6f"
+  integrity sha512-ISWac8drv4ZGfwKl5slpHG9OwPNty4jOWPRIhBpxOoD+hqITiwuipOQ2bNthAzwA3B4fIjO4Nln74N0S9byq8A==
+  dependencies:
+    call-bound "^1.0.3"
+
 is-stream@^2.0.0:
   version "2.0.1"
   resolved "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz"
   integrity sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==
 
+is-string@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/is-string/-/is-string-1.1.1.tgz#92ea3f3d5c5b6e039ca8677e5ac8d07ea773cbb9"
+  integrity sha512-BtEeSsoaQjlSPBemMQIrY1MY0uM6vnS1g5fmufYOtnxLGUZM2178PKbhsk7Ffv58IX+ZtcvoGwccYsh0PglkAA==
+  dependencies:
+    call-bound "^1.0.3"
+    has-tostringtag "^1.0.2"
+
+is-symbol@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/is-symbol/-/is-symbol-1.1.1.tgz#f47761279f532e2b05a7024a7506dbbedacd0634"
+  integrity sha512-9gGx6GTtCQM73BgmHQXfDmLtfjjTUDSyoxTCbp5WtoixAhfgsDirWIcVQ/IHpvI5Vgd5i/J5F7B9cN/WlVbC/w==
+  dependencies:
+    call-bound "^1.0.2"
+    has-symbols "^1.1.0"
+    safe-regex-test "^1.1.0"
+
+is-typed-array@^1.1.13, is-typed-array@^1.1.14, is-typed-array@^1.1.15:
+  version "1.1.15"
+  resolved "https://registry.yarnpkg.com/is-typed-array/-/is-typed-array-1.1.15.tgz#4bfb4a45b61cee83a5a46fba778e4e8d59c0ce0b"
+  integrity sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ==
+  dependencies:
+    which-typed-array "^1.1.16"
+
 is-typedarray@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/is-typedarray/-/is-typedarray-1.0.0.tgz"
   integrity sha512-cyA56iCMHAh5CdzjJIa4aohJyeO1YbwLi3Jc35MmRU6poroFjIGZzUzupGiRPOjgHg9TLu43xbpwXk523fMxKA==
 
+is-weakmap@^2.0.2:
+  version "2.0.2"
+  resolved "https://registry.yarnpkg.com/is-weakmap/-/is-weakmap-2.0.2.tgz#bf72615d649dfe5f699079c54b83e47d1ae19cfd"
+  integrity sha512-K5pXYOm9wqY1RgjpL3YTkF39tni1XajUIkawTLUo9EZEVUFga5gSQJF8nNS7ZwJQ02y+1YCNYcMh+HIf1ZqE+w==
+
+is-weakref@^1.0.2, is-weakref@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/is-weakref/-/is-weakref-1.1.1.tgz#eea430182be8d64174bd96bffbc46f21bf3f9293"
+  integrity sha512-6i9mGWSlqzNMEqpCp93KwRS1uUOodk2OJ6b+sq7ZPDSy2WuI5NFIxp/254TytR8ftefexkWn5xNiHUNpPOfSew==
+  dependencies:
+    call-bound "^1.0.3"
+
+is-weakset@^2.0.3:
+  version "2.0.4"
+  resolved "https://registry.yarnpkg.com/is-weakset/-/is-weakset-2.0.4.tgz#c9f5deb0bc1906c6d6f1027f284ddf459249daca"
+  integrity sha512-mfcwb6IzQyOKTs84CQMrOwW4gQcaTOAWJ0zzJCl2WSPDrWk/OzDaImWFH3djXhb24g4eudZfLRozAvPGw4d9hQ==
+  dependencies:
+    call-bound "^1.0.3"
+    get-intrinsic "^1.2.6"
+
 is-whitespace-character@^1.0.0:
   version "1.0.4"
   resolved "https://registry.npmjs.org/is-whitespace-character/-/is-whitespace-character-1.0.4.tgz"
@@ -5072,6 +6133,11 @@ isarray@0.0.1:
   resolved "https://registry.npmjs.org/isarray/-/isarray-0.0.1.tgz"
   integrity sha512-D2S+3GLxWH+uhrNEcoh/fnmYeP8E8/zHl644d/jdA0g2uyXvy3sb0qxotE+ne0LtccHknQzWwZEzhak7oJ0COQ==
 
+isarray@^2.0.5:
+  version "2.0.5"
+  resolved "https://registry.yarnpkg.com/isarray/-/isarray-2.0.5.tgz#8af1e4c1221244cc62459faf38940d4e644a5723"
+  integrity sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==
+
 isarray@~1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz"
@@ -5087,6 +6153,18 @@ isobject@^3.0.1:
   resolved "https://registry.npmjs.org/isobject/-/isobject-3.0.1.tgz"
   integrity sha512-WhB9zCku7EGTj/HQQRz5aUQEUeoQZH2bWcltRErOpymJ4boYE6wL9Tbr23krRPSZ+C5zqNSrSw+Cc7sZZ4b7vg==
 
+iterator.prototype@^1.1.5:
+  version "1.1.5"
+  resolved "https://registry.yarnpkg.com/iterator.prototype/-/iterator.prototype-1.1.5.tgz#12c959a29de32de0aa3bbbb801f4d777066dae39"
+  integrity sha512-H0dkQoCa3b2VEeKQBOxFph+JAbcrQdE7KC0UkqwpLmv2EC4P41QXP+rqo9wYodACiG5/WM5s9oDApTU8utwj9g==
+  dependencies:
+    define-data-property "^1.1.4"
+    es-object-atoms "^1.0.0"
+    get-intrinsic "^1.2.6"
+    get-proto "^1.0.0"
+    has-symbols "^1.1.0"
+    set-function-name "^2.0.2"
+
 jest-util@^29.7.0:
   version "29.7.0"
   resolved "https://registry.npmjs.org/jest-util/-/jest-util-29.7.0.tgz"
@@ -5154,6 +6232,13 @@ js-yaml@^4.1.0:
   dependencies:
     argparse "^2.0.1"
 
+js-yaml@^4.3.2:
+  version "4.3.2"
+  resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.3.2.tgz#8e44fb14a2643c59726bb15787b5f1512cb3d3fb"
+  integrity sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==
+  dependencies:
+    argparse "^2.0.1"
+
 jsesc@^3.0.2, jsesc@~3.1.0:
   version "3.1.0"
   resolved "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz"
@@ -5164,6 +6249,11 @@ json-buffer@3.0.0:
   resolved "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.0.tgz"
   integrity sha512-CuUqjv0FUZIdXkHPI8MezCnFCdaTAacej1TZYulLoAg1h/PhwkdXFN4V/gzY4g+fMBCOV2xF+rp7t2XD2ns/NQ==
 
+json-buffer@3.0.1:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13"
+  integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==
+
 json-parse-even-better-errors@^2.3.0, json-parse-even-better-errors@^2.3.1:
   version "2.3.1"
   resolved "https://registry.npmjs.org/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz"
@@ -5179,6 +6269,11 @@ json-schema-traverse@^1.0.0:
   resolved "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz"
   integrity sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==
 
+json-stable-stringify-without-jsonify@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz#9db7b59496ad3f3cfef30a75142d2d930ad72651"
+  integrity sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==
+
 json5@^2.1.2, json5@^2.2.3:
   version "2.2.3"
   resolved "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz"
@@ -5193,6 +6288,16 @@ jsonfile@^6.0.1:
   optionalDependencies:
     graceful-fs "^4.1.6"
 
+"jsx-ast-utils@^2.4.1 || ^3.0.0":
+  version "3.3.5"
+  resolved "https://registry.yarnpkg.com/jsx-ast-utils/-/jsx-ast-utils-3.3.5.tgz#4766bd05a8e2a11af222becd19e15575e52a853a"
+  integrity sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ==
+  dependencies:
+    array-includes "^3.1.6"
+    array.prototype.flat "^1.3.1"
+    object.assign "^4.1.4"
+    object.values "^1.1.6"
+
 katex@^0.13.0:
   version "0.13.24"
   resolved "https://registry.npmjs.org/katex/-/katex-0.13.24.tgz"
@@ -5207,6 +6312,13 @@ keyv@^3.0.0:
   dependencies:
     json-buffer "3.0.0"
 
+keyv@^4.5.4:
+  version "4.5.4"
+  resolved "https://registry.yarnpkg.com/keyv/-/keyv-4.5.4.tgz#a879a99e29452f942439f2a405e3af8b31d4de93"
+  integrity sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==
+  dependencies:
+    json-buffer "3.0.1"
+
 kind-of@^6.0.0, kind-of@^6.0.2:
   version "6.0.3"
   resolved "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz"
@@ -5244,6 +6356,14 @@ leven@^3.1.0:
   resolved "https://registry.npmjs.org/leven/-/leven-3.1.0.tgz"
   integrity sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A==
 
+levn@^0.4.1:
+  version "0.4.1"
+  resolved "https://registry.yarnpkg.com/levn/-/levn-0.4.1.tgz#ae4562c007473b932a6200d403268dd2fffc6ade"
+  integrity sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==
+  dependencies:
+    prelude-ls "^1.2.1"
+    type-check "~0.4.0"
+
 lilconfig@^2.0.3:
   version "2.1.0"
   resolved "https://registry.npmjs.org/lilconfig/-/lilconfig-2.1.0.tgz"
@@ -5315,6 +6435,11 @@ lodash.memoize@^4.1.2:
   resolved "https://registry.npmjs.org/lodash.memoize/-/lodash.memoize-4.1.2.tgz"
   integrity sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag==
 
+lodash.merge@^4.6.2:
+  version "4.6.2"
+  resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a"
+  integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==
+
 lodash.uniq@4.5.0, lodash.uniq@^4.5.0:
   version "4.5.0"
   resolved "https://registry.npmjs.org/lodash.uniq/-/lodash.uniq-4.5.0.tgz"
@@ -5535,6 +6660,20 @@ minimatch@3.1.2, minimatch@^3.0.4, minimatch@^3.0.5, minimatch@^3.1.1:
   dependencies:
     brace-expansion "^1.1.7"
 
+minimatch@^10.2.2:
+  version "10.2.6"
+  resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-10.2.6.tgz#fd956bbe0b77241e9f15ac5dccb1c638060968ef"
+  integrity sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==
+  dependencies:
+    brace-expansion "^5.0.8"
+
+minimatch@^3.1.2, minimatch@^3.1.5:
+  version "3.1.5"
+  resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.1.5.tgz#580c88f8d5445f2bd6aa8f3cadefa0de79fbd69e"
+  integrity sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==
+  dependencies:
+    brace-expansion "^1.1.7"
+
 minimist@^1.2.0, minimist@^1.2.5:
   version "1.2.8"
   resolved "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz"
@@ -5568,6 +6707,11 @@ nanoid@^3.3.11:
   resolved "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz"
   integrity sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==
 
+natural-compare@^1.4.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7"
+  integrity sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==
+
 negotiator@0.6.3:
   version "0.6.3"
   resolved "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz"
@@ -5598,6 +6742,16 @@ node-emoji@^1.10.0:
   dependencies:
     lodash "^4.17.21"
 
+node-exports-info@^1.6.0:
+  version "1.6.2"
+  resolved "https://registry.yarnpkg.com/node-exports-info/-/node-exports-info-1.6.2.tgz#243a3105677d6781cd26e6a72350fd928a5cb46f"
+  integrity sha512-kXs9Go0cah0qHVV2v389IXQLdLCeE1xfFtjOAF+iobu0OIoG1pje8At2vMHyaPMiPMnG/LWP50twML21eMcAag==
+  dependencies:
+    array.prototype.flatmap "^1.3.3"
+    es-errors "^1.3.0"
+    object.entries "^1.1.9"
+    semver "^6.3.1"
+
 node-fetch@^2.7.0:
   version "2.7.0"
   resolved "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz"
@@ -5659,7 +6813,7 @@ object-assign@^4.1.0, object-assign@^4.1.1:
   resolved "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz"
   integrity sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==
 
-object-inspect@^1.13.3:
+object-inspect@^1.13.3, object-inspect@^1.13.4:
   version "1.13.4"
   resolved "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz"
   integrity sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==
@@ -5669,7 +6823,7 @@ object-keys@^1.1.1:
   resolved "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz"
   integrity sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==
 
-object.assign@^4.1.0:
+object.assign@^4.1.0, object.assign@^4.1.4, object.assign@^4.1.7:
   version "4.1.7"
   resolved "https://registry.npmjs.org/object.assign/-/object.assign-4.1.7.tgz"
   integrity sha512-nK28WOo+QIjBkDduTINE4JkF/UJJKyf2EJxvJKfblDpyg0Q+pkOHNTL0Qwy6NP6FhE/EnzV73BxxqcJaXY9anw==
@@ -5681,6 +6835,36 @@ object.assign@^4.1.0:
     has-symbols "^1.1.0"
     object-keys "^1.1.1"
 
+object.entries@^1.1.9:
+  version "1.1.9"
+  resolved "https://registry.yarnpkg.com/object.entries/-/object.entries-1.1.9.tgz#e4770a6a1444afb61bd39f984018b5bede25f8b3"
+  integrity sha512-8u/hfXFRBD1O0hPUjioLhoWFHRmt6tKA4/vZPyckBr18l1KE9uHrFaFaUi8MDRTpi4uak2goyPTSNJLXX2k2Hw==
+  dependencies:
+    call-bind "^1.0.8"
+    call-bound "^1.0.4"
+    define-properties "^1.2.1"
+    es-object-atoms "^1.1.1"
+
+object.fromentries@^2.0.8:
+  version "2.0.8"
+  resolved "https://registry.yarnpkg.com/object.fromentries/-/object.fromentries-2.0.8.tgz#f7195d8a9b97bd95cbc1999ea939ecd1a2b00c65"
+  integrity sha512-k6E21FzySsSK5a21KRADBd/NGneRegFO5pLHfdQLpRDETUNJueLXs3WCzyQ3tFRDYgbq3KHGXfTbi2bs8WQ6rQ==
+  dependencies:
+    call-bind "^1.0.7"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.2"
+    es-object-atoms "^1.0.0"
+
+object.values@^1.1.6, object.values@^1.2.1:
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/object.values/-/object.values-1.2.1.tgz#deed520a50809ff7f75a7cfd4bc64c7a038c6216"
+  integrity sha512-gXah6aZrcUxjWg2zR2MwouP2eHlCBzdV4pygudehaKXSGW4v2AsRQUK+lwwXhii6KFZcunEnmSUoYp5CXibxtA==
+  dependencies:
+    call-bind "^1.0.8"
+    call-bound "^1.0.3"
+    define-properties "^1.2.1"
+    es-object-atoms "^1.0.0"
+
 obuf@^1.0.0, obuf@^1.1.2:
   version "1.1.2"
   resolved "https://registry.npmjs.org/obuf/-/obuf-1.1.2.tgz"
@@ -5726,6 +6910,28 @@ opener@^1.5.2:
   resolved "https://registry.npmjs.org/opener/-/opener-1.5.2.tgz"
   integrity sha512-ur5UIdyw5Y7yEj9wLzhqXiy6GZ3Mwx0yGI+5sMn2r0N0v3cKJvUmFH5yPP+WXh9e0xfyzyJX95D8l088DNFj7A==
 
+optionator@^0.9.3:
+  version "0.9.4"
+  resolved "https://registry.yarnpkg.com/optionator/-/optionator-0.9.4.tgz#7ea1c1a5d91d764fb282139c88fe11e182a3a734"
+  integrity sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==
+  dependencies:
+    deep-is "^0.1.3"
+    fast-levenshtein "^2.0.6"
+    levn "^0.4.1"
+    prelude-ls "^1.2.1"
+    type-check "^0.4.0"
+    word-wrap "^1.2.5"
+
+own-keys@^1.0.1:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/own-keys/-/own-keys-1.0.2.tgz#31448ec1f781ecb1447f6f6aa0d6534222af59de"
+  integrity sha512-19YVAg7T+WTrxggPukVq7DjTv6+PJ867TmhCvBsYwmbFCsZd344rq2Ld1p0wo8f8Qrrhgp82c6FJRqdXWtSEhg==
+  dependencies:
+    call-bound "^1.0.4"
+    get-intrinsic "^1.3.0"
+    object-keys "^1.1.1"
+    safe-push-apply "^1.0.0"
+
 p-cancelable@^1.0.0:
   version "1.1.0"
   resolved "https://registry.npmjs.org/p-cancelable/-/p-cancelable-1.1.0.tgz"
@@ -5933,6 +7139,11 @@ picomatch@^2.0.4, picomatch@^2.2.1, picomatch@^2.2.3, picomatch@^2.3.1:
   resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
+picomatch@^4.0.4:
+  version "4.0.7"
+  resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-4.0.7.tgz#6313360034ccb36b3dc61ecbdff78121f90fe21f"
+  integrity sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==
+
 pkg-dir@^4.1.0:
   version "4.2.0"
   resolved "https://registry.npmjs.org/pkg-dir/-/pkg-dir-4.2.0.tgz"
@@ -5947,6 +7158,11 @@ pkg-up@^3.1.0:
   dependencies:
     find-up "^3.0.0"
 
+possible-typed-array-names@^1.0.0, possible-typed-array-names@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/possible-typed-array-names/-/possible-typed-array-names-1.1.0.tgz#93e3582bc0e5426586d9d07b79ee40fc841de4ae"
+  integrity sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==
+
 postcss-calc@^8.2.3:
   version "8.2.4"
   resolved "https://registry.npmjs.org/postcss-calc/-/postcss-calc-8.2.4.tgz"
@@ -6245,6 +7461,11 @@ postcss@^8.3.11, postcss@^8.4.14, postcss@^8.4.17, postcss@^8.4.33:
     picocolors "^1.1.1"
     source-map-js "^1.2.1"
 
+prelude-ls@^1.2.1:
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.2.1.tgz#debc6489d7a6e6b0e7611888cec880337d316396"
+  integrity sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==
+
 prepend-http@^2.0.0:
   version "2.0.0"
   resolved "https://registry.npmjs.org/prepend-http/-/prepend-http-2.0.0.tgz"
@@ -6298,7 +7519,7 @@ prompts@^2.4.2:
     kleur "^3.0.3"
     sisteransi "^1.0.5"
 
-prop-types@^15.6.2, prop-types@^15.7.2:
+prop-types@^15.6.2, prop-types@^15.7.2, prop-types@^15.8.1:
   version "15.8.1"
   resolved "https://registry.npmjs.org/prop-types/-/prop-types-15.8.1.tgz"
   integrity sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==
@@ -6618,6 +7839,20 @@ recursive-readdir@^2.2.2:
   dependencies:
     minimatch "^3.0.5"
 
+reflect.getprototypeof@^1.0.10:
+  version "1.0.10"
+  resolved "https://registry.yarnpkg.com/reflect.getprototypeof/-/reflect.getprototypeof-1.0.10.tgz#c629219e78a3316d8b604c765ef68996964e7bf9"
+  integrity sha512-00o4I+DVrefhv+nX0ulyi3biSHCPDe+yLv5o/p6d/UVlirijB8E16FtfwSAi4g3tcqrQ4lRAqQSoFEZJehYEcw==
+  dependencies:
+    call-bind "^1.0.8"
+    define-properties "^1.2.1"
+    es-abstract "^1.23.9"
+    es-errors "^1.3.0"
+    es-object-atoms "^1.0.0"
+    get-intrinsic "^1.2.7"
+    get-proto "^1.0.1"
+    which-builtin-type "^1.2.1"
+
 regenerate-unicode-properties@^10.2.2:
   version "10.2.2"
   resolved "https://registry.npmjs.org/regenerate-unicode-properties/-/regenerate-unicode-properties-10.2.2.tgz"
@@ -6630,6 +7865,18 @@ regenerate@^1.4.2:
   resolved "https://registry.npmjs.org/regenerate/-/regenerate-1.4.2.tgz"
   integrity sha512-zrceR/XhGYU/d/opr2EKO7aRHUeiBI8qjtfHqADTwZd6Szfy16la6kqD0MIUs5z5hx6AaKa+PixpPrR289+I0A==
 
+regexp.prototype.flags@^1.5.4:
+  version "1.5.4"
+  resolved "https://registry.yarnpkg.com/regexp.prototype.flags/-/regexp.prototype.flags-1.5.4.tgz#1ad6c62d44a259007e55b3970e00f746efbcaa19"
+  integrity sha512-dYqgNSZbDwkaJ2ceRd9ojCGjBq+mOm9LmtXnAnEGyHhN/5R7iDW2TRw3h+o/jCFxus3P2LfWIIiwowAjANm7IA==
+  dependencies:
+    call-bind "^1.0.8"
+    define-properties "^1.2.1"
+    es-errors "^1.3.0"
+    get-proto "^1.0.1"
+    gopd "^1.2.0"
+    set-function-name "^2.0.2"
+
 regexpu-core@^6.3.1:
   version "6.4.0"
   resolved "https://registry.npmjs.org/regexpu-core/-/regexpu-core-6.4.0.tgz"
@@ -6805,6 +8052,18 @@ resolve@^1.1.6, resolve@^1.22.11, resolve@^1.3.2:
     path-parse "^1.0.7"
     supports-preserve-symlinks-flag "^1.0.0"
 
+resolve@^2.0.0-next.5:
+  version "2.0.0-next.7"
+  resolved "https://registry.yarnpkg.com/resolve/-/resolve-2.0.0-next.7.tgz#ba3b035d4b1ee7c522426eee73cabcb0fd5515dd"
+  integrity sha512-tqt+NBWwyaMgw3zDsnygx4CByWjQEJHOPMdslYhppaQSJUtL/D4JO9CcBBlhPoI8lz9oJIDXkwXfhF4aWqP8xQ==
+  dependencies:
+    es-errors "^1.3.0"
+    is-core-module "^2.16.2"
+    node-exports-info "^1.6.0"
+    object-keys "^1.1.1"
+    path-parse "^1.0.7"
+    supports-preserve-symlinks-flag "^1.0.0"
+
 responselike@^1.0.2:
   version "1.0.2"
   resolved "https://registry.npmjs.org/responselike/-/responselike-1.0.2.tgz"
@@ -6858,6 +8117,17 @@ rxjs@^7.5.4:
   dependencies:
     tslib "^2.1.0"
 
+safe-array-concat@^1.1.3:
+  version "1.1.4"
+  resolved "https://registry.yarnpkg.com/safe-array-concat/-/safe-array-concat-1.1.4.tgz#a54cc9b61a57f33b42abad3cbdda3a2b38cc5719"
+  integrity sha512-wtZlHyOje6OZTGqAoaDKxFkgRtkF9CnHAVnCHKfuj200wAgL+bSJhdsCD2l0Qx/2ekEXjPWcyKkfGb5CPboslg==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    get-intrinsic "^1.3.0"
+    has-symbols "^1.1.0"
+    isarray "^2.0.5"
+
 safe-buffer@5.2.1, safe-buffer@>=5.1.0, safe-buffer@^5.1.0, safe-buffer@~5.2.0:
   version "5.2.1"
   resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz"
@@ -6868,6 +8138,23 @@ safe-buffer@~5.1.0, safe-buffer@~5.1.1:
   resolved "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz"
   integrity sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==
 
+safe-push-apply@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/safe-push-apply/-/safe-push-apply-1.0.0.tgz#01850e981c1602d398c85081f360e4e6d03d27f5"
+  integrity sha512-iKE9w/Z7xCzUMIZqdBsp6pEQvwuEebH4vdpjcDWnyzaI6yl6O9FHvVpmGelvEHNsoY6wGblkxR6Zty/h00WiSA==
+  dependencies:
+    es-errors "^1.3.0"
+    isarray "^2.0.5"
+
+safe-regex-test@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/safe-regex-test/-/safe-regex-test-1.1.0.tgz#7f87dfb67a3150782eaaf18583ff5d1711ac10c1"
+  integrity sha512-x/+Cz4YrimQxQccJf5mKEbIa1NzeCRNI5Ecl/ekmlYaampdNLPalVyIcCZNNH3MvmqBugV5TMYZXv0ljslUlaw==
+  dependencies:
+    call-bound "^1.0.2"
+    es-errors "^1.3.0"
+    is-regex "^1.2.1"
+
 "safer-buffer@>= 2.1.2 < 3":
   version "2.1.2"
   resolved "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz"
@@ -6965,6 +8252,11 @@ semver@^7.3.2, semver@^7.3.4, semver@^7.3.7, semver@^7.5.4:
   resolved "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz"
   integrity sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==
 
+semver@^7.7.3:
+  version "7.8.5"
+  resolved "https://registry.yarnpkg.com/semver/-/semver-7.8.5.tgz#39b646037dd50c14fb451e7e4cac58ed8b863f69"
+  integrity sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==
+
 send@~0.19.0, send@~0.19.1:
   version "0.19.2"
   resolved "https://registry.npmjs.org/send/-/send-0.19.2.tgz"
@@ -7039,6 +8331,25 @@ set-function-length@^1.2.2:
     gopd "^1.0.1"
     has-property-descriptors "^1.0.2"
 
+set-function-name@^2.0.2:
+  version "2.0.2"
+  resolved "https://registry.yarnpkg.com/set-function-name/-/set-function-name-2.0.2.tgz#16a705c5a0dc2f5e638ca96d8a8cd4e1c2b90985"
+  integrity sha512-7PGFlmtwsEADb0WYyvCMa1t+yke6daIG4Wirafur5kcf+MhUnPms1UeR0CKQdTZD81yESwMHbtn+TR+dMviakQ==
+  dependencies:
+    define-data-property "^1.1.4"
+    es-errors "^1.3.0"
+    functions-have-names "^1.2.3"
+    has-property-descriptors "^1.0.2"
+
+set-proto@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/set-proto/-/set-proto-1.0.0.tgz#0760dbcff30b2d7e801fd6e19983e56da337565e"
+  integrity sha512-RJRdvCo6IAnPdsvP/7m6bsQqNnn1FCBX5ZNtFL98MmFF/4xAIJTIg1YbHW5DC2W5SKZanrC6i4HsJqlajw/dZw==
+  dependencies:
+    dunder-proto "^1.0.1"
+    es-errors "^1.3.0"
+    es-object-atoms "^1.0.0"
+
 setimmediate@^1.0.5:
   version "1.0.5"
   resolved "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz"
@@ -7095,6 +8406,14 @@ side-channel-list@^1.0.0:
     es-errors "^1.3.0"
     object-inspect "^1.13.3"
 
+side-channel-list@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/side-channel-list/-/side-channel-list-1.0.1.tgz#c2e0b5a14a540aebee3bbc6c3f8666cc9b509127"
+  integrity sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==
+  dependencies:
+    es-errors "^1.3.0"
+    object-inspect "^1.13.4"
+
 side-channel-map@^1.0.1:
   version "1.0.1"
   resolved "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz"
@@ -7127,6 +8446,17 @@ side-channel@^1.1.0:
     side-channel-map "^1.0.1"
     side-channel-weakmap "^1.0.2"
 
+side-channel@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/side-channel/-/side-channel-1.1.1.tgz#ea02c62e05dc4bea67d4442f0fb71ee192f8e0ab"
+  integrity sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==
+  dependencies:
+    es-errors "^1.3.0"
+    object-inspect "^1.13.4"
+    side-channel-list "^1.0.1"
+    side-channel-map "^1.0.1"
+    side-channel-weakmap "^1.0.2"
+
 signal-exit@^3.0.2, signal-exit@^3.0.3:
   version "3.0.7"
   resolved "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz"
@@ -7261,6 +8591,14 @@ std-env@^3.0.1:
   resolved "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz"
   integrity sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==
 
+stop-iteration-iterator@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/stop-iteration-iterator/-/stop-iteration-iterator-1.1.0.tgz#f481ff70a548f6124d0312c3aa14cbfa7aa542ad"
+  integrity sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==
+  dependencies:
+    es-errors "^1.3.0"
+    internal-slot "^1.1.0"
+
 string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.2:
   version "4.2.3"
   resolved "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz"
@@ -7279,6 +8617,66 @@ string-width@^5.0.1:
     emoji-regex "^9.2.2"
     strip-ansi "^7.0.1"
 
+string.prototype.matchall@^4.0.12:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/string.prototype.matchall/-/string.prototype.matchall-4.1.0.tgz#8d854b2318fc596fc0877cfc6c4bcc50d0455b8e"
+  integrity sha512-tHNHTxInrYLCga9O9YGxWA3G9/nnzQw8UGAyqGx3Ar1pSTTzIuM4woFSq4SowkXCjJIwq5sIiQvEfRI9tCH1qQ==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    define-properties "^1.2.1"
+    es-abstract "^1.24.2"
+    es-errors "^1.3.0"
+    es-object-atoms "^1.1.2"
+    get-intrinsic "^1.3.0"
+    gopd "^1.2.0"
+    has-symbols "^1.1.0"
+    internal-slot "^1.1.0"
+    regexp.prototype.flags "^1.5.4"
+    set-function-name "^2.0.2"
+    side-channel "^1.1.1"
+
+string.prototype.repeat@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/string.prototype.repeat/-/string.prototype.repeat-1.0.0.tgz#e90872ee0308b29435aa26275f6e1b762daee01a"
+  integrity sha512-0u/TldDbKD8bFCQ/4f5+mNRrXwZ8hg2w7ZR8wa16e8z9XpePWl3eGEcUD0OXpEH/VJH/2G3gjUtR3ZOiBe2S/w==
+  dependencies:
+    define-properties "^1.1.3"
+    es-abstract "^1.17.5"
+
+string.prototype.trim@^1.2.10:
+  version "1.2.11"
+  resolved "https://registry.yarnpkg.com/string.prototype.trim/-/string.prototype.trim-1.2.11.tgz#e6bd19cda3985d05a42dda31f3ddf4d35d3430e3"
+  integrity sha512-PwvK7BU+CMTJGYQCTZb5RWXIML92lftJLhQz1tBzgKiqGxJaMlBAa48POXaNAC2s4y8jr3EFqrkF9+44neS46w==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    define-data-property "^1.1.4"
+    define-properties "^1.2.1"
+    es-abstract "^1.24.2"
+    es-object-atoms "^1.1.2"
+    has-property-descriptors "^1.0.2"
+    safe-regex-test "^1.1.0"
+
+string.prototype.trimend@^1.0.9:
+  version "1.0.10"
+  resolved "https://registry.yarnpkg.com/string.prototype.trimend/-/string.prototype.trimend-1.0.10.tgz#be6bcf4f3fe0460bdeccdb2cf4f971b310f8346e"
+  integrity sha512-2+3aDAOmPTmuFwjDnmJG2ctEkQKVki7vOSqaxkv42Mowj1V6PnvuwFCRrR5lChUux1TBskPjfkeTOhqczDMxTw==
+  dependencies:
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    define-properties "^1.2.1"
+    es-object-atoms "^1.1.2"
+
+string.prototype.trimstart@^1.0.8:
+  version "1.0.8"
+  resolved "https://registry.yarnpkg.com/string.prototype.trimstart/-/string.prototype.trimstart-1.0.8.tgz#7ee834dda8c7c17eff3118472bb35bfedaa34dde"
+  integrity sha512-UXSH262CSZY1tfu3G3Secr6uGLCFVPMhIqHjlgCUtCCcgihYc/xKs9djMTMUOb2j1mVSeU8EU6NWc/iQKU6Gfg==
+  dependencies:
+    call-bind "^1.0.7"
+    define-properties "^1.2.1"
+    es-object-atoms "^1.0.0"
+
 string_decoder@^1.1.1:
   version "1.3.0"
   resolved "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz"
@@ -7439,6 +8837,14 @@ tiny-warning@^1.0.0:
   resolved "https://registry.npmjs.org/tiny-warning/-/tiny-warning-1.0.3.tgz"
   integrity sha512-lBN9zLN/oAf68o3zNXYrdCt1kP8WsiGW8Oo2ka41b2IM5JL/S1CTyX1rW0mb/zSuJun0ZUrDxx4sqvYS2FWzPA==
 
+tinyglobby@^0.2.15:
+  version "0.2.17"
+  resolved "https://registry.yarnpkg.com/tinyglobby/-/tinyglobby-0.2.17.tgz#562a9a6c9eb2b3b123d39719f9af5bb44fcd7631"
+  integrity sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==
+  dependencies:
+    fdir "^6.5.0"
+    picomatch "^4.0.4"
+
 to-readable-stream@^1.0.0:
   version "1.0.0"
   resolved "https://registry.npmjs.org/to-readable-stream/-/to-readable-stream-1.0.0.tgz"
@@ -7481,11 +8887,23 @@ trough@^1.0.0:
   resolved "https://registry.npmjs.org/trough/-/trough-1.0.5.tgz"
   integrity sha512-rvuRbTarPXmMb79SmzEp8aqXNKcK+y0XaB298IXueQ8I2PsrATcPBCSPyK/dDNa2iWOhKlfNnOjdAOTBU/nkFA==
 
+ts-api-utils@^2.5.0:
+  version "2.5.0"
+  resolved "https://registry.yarnpkg.com/ts-api-utils/-/ts-api-utils-2.5.0.tgz#4acd4a155e22734990a5ed1fe9e97f113bcb37c1"
+  integrity sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==
+
 tslib@^2.0.3, tslib@^2.1.0, tslib@^2.4.0, tslib@^2.4.1:
   version "2.8.1"
   resolved "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz"
   integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==
 
+type-check@^0.4.0, type-check@~0.4.0:
+  version "0.4.0"
+  resolved "https://registry.yarnpkg.com/type-check/-/type-check-0.4.0.tgz#07b8203bfa7056c0657050e3ccd2c37730bab8f1"
+  integrity sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==
+  dependencies:
+    prelude-ls "^1.2.1"
+
 type-fest@^0.20.2:
   version "0.20.2"
   resolved "https://registry.npmjs.org/type-fest/-/type-fest-0.20.2.tgz"
@@ -7504,6 +8922,50 @@ type-is@~1.6.18:
     media-typer "0.3.0"
     mime-types "~2.1.24"
 
+typed-array-buffer@^1.0.3:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/typed-array-buffer/-/typed-array-buffer-1.0.3.tgz#a72395450a4869ec033fd549371b47af3a2ee536"
+  integrity sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw==
+  dependencies:
+    call-bound "^1.0.3"
+    es-errors "^1.3.0"
+    is-typed-array "^1.1.14"
+
+typed-array-byte-length@^1.0.3:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/typed-array-byte-length/-/typed-array-byte-length-1.0.3.tgz#8407a04f7d78684f3d252aa1a143d2b77b4160ce"
+  integrity sha512-BaXgOuIxz8n8pIq3e7Atg/7s+DpiYrxn4vdot3w9KbnBhcRQq6o3xemQdIfynqSeXeDrF32x+WvfzmOjPiY9lg==
+  dependencies:
+    call-bind "^1.0.8"
+    for-each "^0.3.3"
+    gopd "^1.2.0"
+    has-proto "^1.2.0"
+    is-typed-array "^1.1.14"
+
+typed-array-byte-offset@^1.0.4:
+  version "1.0.5"
+  resolved "https://registry.yarnpkg.com/typed-array-byte-offset/-/typed-array-byte-offset-1.0.5.tgz#c076d6a0db563933154b3c442204b614bf0d7b15"
+  integrity sha512-0FHJvLPqZ7KJzp17O13jfsAjsqazgrxBu2zEK95PmUz8lv2+GjRuxUInCr2Rk9Dms3ihN21zJ929ZO43yJ95QQ==
+  dependencies:
+    available-typed-arrays "^1.0.7"
+    call-bind "^1.0.9"
+    for-each "^0.3.5"
+    gopd "^1.2.0"
+    is-typed-array "^1.1.15"
+    reflect.getprototypeof "^1.0.10"
+
+typed-array-length@^1.0.7:
+  version "1.0.8"
+  resolved "https://registry.yarnpkg.com/typed-array-length/-/typed-array-length-1.0.8.tgz#0b70e982c9e9dafe2def6d6458ff4b3f2d2b6d70"
+  integrity sha512-phPGCwqr2+Qo0fwniCE8e4pKnGu/yFb5nD5Y8bf0EEeiI5GklnACYA9GFy/DrAeRrKHXvHn+1SUsOWgJp6RO+g==
+  dependencies:
+    call-bind "^1.0.9"
+    for-each "^0.3.5"
+    gopd "^1.2.0"
+    is-typed-array "^1.1.15"
+    possible-typed-array-names "^1.1.0"
+    reflect.getprototypeof "^1.0.10"
+
 typedarray-to-buffer@^3.1.5:
   version "3.1.5"
   resolved "https://registry.npmjs.org/typedarray-to-buffer/-/typedarray-to-buffer-3.1.5.tgz"
@@ -7511,6 +8973,16 @@ typedarray-to-buffer@^3.1.5:
   dependencies:
     is-typedarray "^1.0.0"
 
+typescript-eslint@^8.72.1:
+  version "8.72.1"
+  resolved "https://registry.yarnpkg.com/typescript-eslint/-/typescript-eslint-8.72.1.tgz#46324b99d4809e986aeb01285cfce28f74b45d14"
+  integrity sha512-3Li9FfPmQp45nxEtFD1ZCrYFI3cYK5kpyNtmm1H7lMagm8u9sy6PTjy3ytwQZs7KNukOyKFHAZ6z6GjYFeaeXw==
+  dependencies:
+    "@typescript-eslint/eslint-plugin" "8.72.1"
+    "@typescript-eslint/parser" "8.72.1"
+    "@typescript-eslint/typescript-estree" "8.72.1"
+    "@typescript-eslint/utils" "8.72.1"
+
 typescript@^4.8.4:
   version "4.9.5"
   resolved "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz"
@@ -7521,6 +8993,16 @@ ua-parser-js@^1.0.35:
   resolved "https://registry.npmjs.org/ua-parser-js/-/ua-parser-js-1.0.41.tgz"
   integrity sha512-LbBDqdIC5s8iROCUjMbW1f5dJQTEFB1+KO9ogbvlb3nm9n4YHa5p4KTvFPWvh2Hs8gZMBuiB1/8+pdfe/tDPug==
 
+unbox-primitive@^1.1.0:
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/unbox-primitive/-/unbox-primitive-1.1.0.tgz#8d9d2c9edeea8460c7f35033a88867944934d1e2"
+  integrity sha512-nWJ91DjeOkej/TA8pXQ3myruKpKEYgqvpw9lz4OPHj/NWFNluYrjbz9j01CJ8yKQd2g4jFoOkINCTW2I5LEEyw==
+  dependencies:
+    call-bound "^1.0.3"
+    has-bigints "^1.0.2"
+    has-symbols "^1.1.0"
+    which-boxed-primitive "^1.1.1"
+
 undici-types@~7.16.0:
   version "7.16.0"
   resolved "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz"
@@ -7980,6 +9462,59 @@ whatwg-url@^5.0.0:
     tr46 "~0.0.3"
     webidl-conversions "^3.0.0"
 
+which-boxed-primitive@^1.1.0, which-boxed-primitive@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/which-boxed-primitive/-/which-boxed-primitive-1.1.1.tgz#d76ec27df7fa165f18d5808374a5fe23c29b176e"
+  integrity sha512-TbX3mj8n0odCBFVlY8AxkqcHASw3L60jIuF8jFP78az3C2YhmGvqbHBpAjTRH2/xqYunrJ9g1jSyjCjpoWzIAA==
+  dependencies:
+    is-bigint "^1.1.0"
+    is-boolean-object "^1.2.1"
+    is-number-object "^1.1.1"
+    is-string "^1.1.1"
+    is-symbol "^1.1.1"
+
+which-builtin-type@^1.2.1:
+  version "1.2.1"
+  resolved "https://registry.yarnpkg.com/which-builtin-type/-/which-builtin-type-1.2.1.tgz#89183da1b4907ab089a6b02029cc5d8d6574270e"
+  integrity sha512-6iBczoX+kDQ7a3+YJBnh3T+KZRxM/iYNPXicqk66/Qfm1b93iu+yOImkg0zHbj5LNOcNv1TEADiZ0xa34B4q6Q==
+  dependencies:
+    call-bound "^1.0.2"
+    function.prototype.name "^1.1.6"
+    has-tostringtag "^1.0.2"
+    is-async-function "^2.0.0"
+    is-date-object "^1.1.0"
+    is-finalizationregistry "^1.1.0"
+    is-generator-function "^1.0.10"
+    is-regex "^1.2.1"
+    is-weakref "^1.0.2"
+    isarray "^2.0.5"
+    which-boxed-primitive "^1.1.0"
+    which-collection "^1.0.2"
+    which-typed-array "^1.1.16"
+
+which-collection@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/which-collection/-/which-collection-1.0.2.tgz#627ef76243920a107e7ce8e96191debe4b16c2a0"
+  integrity sha512-K4jVyjnBdgvc86Y6BkaLZEN933SwYOuBFkdmBu9ZfkcAbdVbpITnDmjvZ/aQjRXQrv5EPkTnD1s39GiiqbngCw==
+  dependencies:
+    is-map "^2.0.3"
+    is-set "^2.0.3"
+    is-weakmap "^2.0.2"
+    is-weakset "^2.0.3"
+
+which-typed-array@^1.1.16, which-typed-array@^1.1.19:
+  version "1.1.24"
+  resolved "https://registry.yarnpkg.com/which-typed-array/-/which-typed-array-1.1.24.tgz#211f5877c29e6213d50e8f2dce4ac9ca2d0008cf"
+  integrity sha512-wk4Mf4pR5mRP7eYuuTBCIQ9d0ud2Fv2jRLQpfgnRjbOxAFHmjKFValgTpitVKzJJS8ajnYQV2Du1SZ8j6b/EUQ==
+  dependencies:
+    available-typed-arrays "^1.0.7"
+    call-bind "^1.0.9"
+    call-bound "^1.0.4"
+    for-each "^0.3.5"
+    get-proto "^1.0.1"
+    gopd "^1.2.0"
+    has-tostringtag "^1.0.2"
+
 which@^1.3.1:
   version "1.3.1"
   resolved "https://registry.npmjs.org/which/-/which-1.3.1.tgz"
@@ -8013,6 +9548,11 @@ wildcard@^2.0.0:
   resolved "https://registry.npmjs.org/wildcard/-/wildcard-2.0.1.tgz"
   integrity sha512-CC1bOL87PIWSBhDcTrdeLo6eGT7mCFtrg0uIJtqJUFyK+eJnzl8A1niH56uu7KMa5XFrtiV+AQuHO3n7DsHnLQ==
 
+word-wrap@^1.2.5:
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.5.tgz#d2c45c6dd4fbce621a66f136cbe328afd0410b34"
+  integrity sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==
+
 wrap-ansi@^7.0.0:
   version "7.0.0"
   resolved "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz"
@@ -8088,6 +9628,16 @@ yocto-queue@^0.1.0:
   resolved "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz"
   integrity sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==
 
+"zod-validation-error@^3.5.0 || ^4.0.0":
+  version "4.0.2"
+  resolved "https://registry.yarnpkg.com/zod-validation-error/-/zod-validation-error-4.0.2.tgz#bc605eba49ce0fcd598c127fee1c236be3f22918"
+  integrity sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==
+
+"zod@^3.25.0 || ^4.0.0":
+  version "4.6.7"
+  resolved "https://registry.yarnpkg.com/zod/-/zod-4.6.7.tgz#e806cf64a7f4e37635ce9f2f52c04c3766f75e5b"
+  integrity sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==
+
 zwitch@^1.0.0:
   version "1.0.5"
   resolved "https://registry.npmjs.org/zwitch/-/zwitch-1.0.5.tgz"

From 1c2657cbefddd4890f12e1ad2acd19cbdac6433e Mon Sep 17 00:00:00 2001
From: jizhen181-dot <jizhen181@gmail.com>
Date: Thu, 29 Oct 2026 18:11:59 +0800
Subject: [PATCH 13/13] docs(readme): recommend Skills and wallet-cli for new
 setups

Skills 3.0 has no x402-payment skill; point agents to Skills and wallet-cli, and keep OpenClaw and TRON MCP as existing integrations.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 README.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 30c3fd1f..300d5e10 100644
--- a/README.md
+++ b/README.md
@@ -30,12 +30,14 @@ Built on the Model Context Protocol (MCP) architecture, providing full on-chain
 - **Infrastructure Layer (MCP Server)**: The agent’s **“hands and eyes.”** Provides a unified interface to read blocks, manage wallets, execute transfers, and interact with any contract.
 - **Application Logic Layer (Skills)**: The agent’s **“brain.”** Uses structured instructions (`SKILL.md`) to guide AI in orchestrating underlying tools.
   - **sunswap**: Enables automated DEX swaps.
-  - **x402-payment**: Allows agents to detect payment requirements and execute payments automatically.
+  - **wallet-cli**: Guides agents through wallet-cli for TRON accounts, transfers, signing, and on-chain operations.
 
 ---
 
 ### 3. 🧩 OpenClaw Extension: Financial Assistant for AI Agents
 
+> For new setups, start with Skills and wallet-cli (see [Quick Start](#-quick-start)). OpenClaw remains documented for existing integrations.
+
 OpenClaw is a financial extension plugin developed by BANK OF AI for AI agents, aiming to become the “central bank” of the agent economy.
 
 - **Wallet Ownership**: Enables agents to truly control and manage on-chain assets.
@@ -68,9 +70,11 @@ OpenClaw is a financial extension plugin developed by BANK OF AI for AI agents,
 ### 🤖 For Agents/Buyers
 *Want your agent to have autonomous payment and on-chain interaction capabilities?*
 
-1. **Install OpenClaw**: Configure your environment and connect to the [mcp-server-tron](https://github.com/BofAI/mcp-server-tron).
-2. **Sync Skills**: Load `sunswap` or `x402-payment` from the [skills](https://github.com/BofAI/skills) repository.
-3. **Start Transacting**: Your agent can now automatically process payment requests from sellers and execute settlements.
+1. **Install Skills**: Add the Skills your agent needs, such as `wallet-cli` or `sunswap`, from the [skills](https://github.com/BofAI/skills) repository. See the [Skills quick start](https://docs.bankofai.io/McpServer-Skills/SKILLS/QuickStart/).
+2. **Set up wallet-cli**: Install wallet-cli and configure an account on your own machine. See the [wallet-cli quick start](https://docs.bankofai.io/wallet-cli/quickstart/). Never send a private key, mnemonic, or password to an AI.
+3. **Start Transacting**: Your agent can now pay x402 endpoints with `wallet-cli x402 pay` and run on-chain workflows through Skills.
+
+Already using OpenClaw or the TRON MCP Server? Their docs remain available: [OpenClaw](https://docs.bankofai.io/Openclaw-extension/Intro/) and [TRON MCP Server](https://docs.bankofai.io/McpServer-Skills/MCP/TRONMCPServer/Intro/).
 
 ---