freeman1128 · Sep 9, 2026 · Sep 9, 2026
diff --git a/README.en.md b/README.en.md
@@ -8,20 +8,29 @@ ACT (Agentic Commerce Trust Protocol) is an open protocol for agentic commerce.
 
 | Goal | Entry |
 |---|---|
+| Experience the ACT flow online | [ACT website demo](https://www.act-protocol.com/demo) |
 | Read ACT 2.1 | [Specification overview](docs/specification/overview.en.md) |
 | Understand end-to-end flows | [Scenarios and Business Flows](docs/specification/scenarios.en.md) |
-| Run the TSD-CRD credit-association reference flow | [TSD-CRD Reference Implementation](code/samples/tsd-crd-reference/README.md) |
 | Run the safe local A402 sample | [Local A402 Sample](code/samples/local-a402/README.md) |
-| Explore the interactive flow | [Web Showcase](code/web-client/alipay-ai-pay-showcase/README.md) |
+| Run the interactive demo locally | [Web Showcase](code/web-client/alipay-ai-pay-showcase/README.en.md) |
+| Run the TSD-CRD credit-association reference flow | [TSD-CRD Reference Implementation](code/samples/tsd-crd-reference/README.md) |
 | Integrate Alipay | [Alipay Reference Integration](integrations/alipay/README.md) |
 
-For a first visit: read the [English overview](docs/specification/overview.en.md), keep the [bilingual glossary](docs/glossary.md) open, run the local sample, and then choose the buyer or seller Alipay integration. The local sample intentionally demonstrates safe rejection rather than manufacturing payment success; a successful paid delivery requires verified proof from the official product workflow.
+For a first visit:
+
+1. Open the [ACT website demo](https://www.act-protocol.com/demo) to see the business steps, participants, and protocol components together.
+2. Read the [English overview](docs/specification/overview.en.md) to distinguish ADD, CID, PSD, TSD, and A402; keep the [bilingual glossary](docs/glossary.md) open for abbreviations.
+3. Read [Scenarios and Business Flows](docs/specification/scenarios.en.md) to map the demo onto complete protocol flows.
+4. Run the Local A402 Sample or TSD-CRD Reference Implementation depending on whether you are exploring the safe payment path or credit association.
+5. For a real successful payment flow, choose the [Alipay buyer](integrations/alipay/buyer-agent/README.md) or [Java seller](integrations/alipay/seller-java/README.md) integration and complete authorization and payment in the official sandbox.
+
+The Local A402 Sample intentionally rejects fake proof instead of manufacturing payment success. A successful paid delivery requires verified proof from the official product workflow. The TSD-CRD Reference Implementation uses only mock capabilities and test keys; it is not a production credit service.
 
 The five human-readable specification documents and the non-normative scenario guide live in `docs/specification/`. A402 and commerce-to-payment integration guides are grouped with the Alipay reference integration under `integrations/alipay/`. JSON Schemas, fixtures, and tests live in `code/schemas/`; they support implementation without adding requirements that are absent from the specification.
 
 ACT 2.1 is available in both [Chinese](docs/specification/overview.md) and [English](docs/specification/overview.en.md). The English documents are official informative translations of the final 2.1 publication; if a translation discrepancy is found, the Chinese publication remains controlling until the translation is corrected in a subsequent repository release.
 
-The overview and four domain specifications under `docs/specification/` are the sole versioned ACT 2.1 normative publication in this repository release; the scenario guide is explicitly non-normative. [act-protocol.com](https://www.act-protocol.com/) is a project-information entry point. Website content that is not explicitly labeled ACT 2.1 is informative and is not a normative source for this release. If a web page omits a component, uses a different structure, or conflicts with this release, it MUST NOT override or interpret the repository's ACT 2.1 requirements.
+The overview and four domain specifications under `docs/specification/` are the versioned ACT 2.1 normative publication; the scenario guide is non-normative. [act-protocol.com](https://www.act-protocol.com/) provides project information and the online demo; it does not replace the versioned specification in this repository.
 
 ## Repository layout
 
@@ -37,18 +46,27 @@ tools/                Repository quality and release tooling
 
 The dependency direction is specification → artifacts → product integration → sample/demo. Product code, demos, and repository tools do not define ACT semantics.
 
+## Online demo
+
+Open the [ACT website demo](https://www.act-protocol.com/demo) to experience the protocol flow without downloading or installing anything. The website demo is an interactive walkthrough, not a payment implementation or conformance certification.
+
 ## Run locally
 
-After downloading or cloning this repository, run from the repository root using Node.js 18 or later:
+The following Node.js programs have no third-party runtime dependencies, so `npm install` is not required. Download or clone the repository and run the commands from its root.
+
+### Local A402 Sample
+
+Requires Node.js 18 or later:
 
 ```bash
 npm --prefix code/samples/local-a402 run local
-npm --prefix code/web-client/alipay-ai-pay-showcase run demo
 ```
 
-The local A402 sample performs no payment. The Showcase explains the protocol flow and does not constitute a payment implementation or conformance claim.
+The sample returns `402 Payment Required`, decodes `Payment-Needed`, and verifies that a fake `Payment-Proof` does not deliver the paid resource. It never connects to a payment product or performs payment.
 
-The TSD-CRD reference suite requires Node.js 22.18 or later:
+### TSD-CRD Reference Implementation
+
+Requires Node.js 22.18 or later. Run its tests, baseline conformance checks, and local demo:
 
 ```bash
 npm --prefix code/samples/tsd-crd-reference run check
@@ -57,9 +75,29 @@ npm --prefix code/samples/tsd-crd-reference run demo
 
 It uses Mock providers, in-memory state, temporary test keys, and the optional non-normative `reference-v1` machine profile. Passing its tests is not a claim of full ACT 2.1 conformance or production readiness.
 
+### Web Showcase
+
+Requires Node.js 18 or later. To inspect or modify the interactive demo locally, run:
+
+```bash
+npm --prefix code/web-client/alipay-ai-pay-showcase run demo
+```
+
+Open `http://127.0.0.1:4173/`. The local Showcase explains the protocol flow and is not a payment implementation or conformance certification.
+
+## Alipay reference integration
+
+`integrations/alipay/` separates the two sides of the product integration:
+
+- `buyer-agent/` checks the environment and hands off to the buyer wallet and payment package `@alipay/agent-payment`.
+- `seller-java/` uses the Alipay Java SDK for Machine Pay proof verification and fulfillment confirmation. The official seller integration assistant `@alipay/alipay-aipay` is referenced as an external tool only.
+- `validation/` provides sandbox preflight and sanitized evidence guidance.
+
 For Alipay onboarding, credentials, sandbox operation, and current product behavior, use the [AIPay website](https://aipay.alipay.com/callpay) and its [official integration guide](https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html).
 
-Run all checks with Python 3, Node.js 22.18+, JDK 8+, and Maven 3.8+:
+## Quality checks
+
+Run all checks with Python 3, Node.js 22.18+, JDK 8+, and Maven 3.8+. The suite covers repository structure, internal links, key official external links, schemas, samples, integrations, and the demo:
 
 ```bash
 ./tools/verify.sh

diff --git a/README.md b/README.md
@@ -8,26 +8,27 @@ ACT（Agentic Commerce Trust Protocol）是面向智能体商业交互的开放
 
 | 目标 | 入口 |
 |---|---|
+| 在线体验 ACT 流程 | [ACT 官网 Demo](https://www.act-protocol.com/demo) |
 | 阅读 ACT 2.1 | [协议概览](docs/specification/overview.md) |
 | 理解完整业务流程 | [典型场景与业务流程](docs/specification/scenarios.md) |
-| 运行 TSD-CRD 信用关联参考链路 | [TSD-CRD Reference Implementation](code/samples/tsd-crd-reference/README.md) |
 | 本地运行安全的 A402 样例 | [Local A402 Sample](code/samples/local-a402/README.md) |
-| 查看交互演示 | [Web Showcase](code/web-client/alipay-ai-pay-showcase/README.md) |
+| 本地运行交互演示 | [Web Showcase](code/web-client/alipay-ai-pay-showcase/README.md) |
+| 运行 TSD-CRD 信用关联参考链路 | [TSD-CRD Reference Implementation](code/samples/tsd-crd-reference/README.md) |
 | 接入支付宝 | [Alipay Reference Integration](integrations/alipay/README.md) |
 
 第一次进入仓库，建议按以下顺序阅读：
 
-1. 用 2 分钟阅读[协议概览](docs/specification/overview.md)，先区分 ADD、CID、PSD、TSD 与 A402；
-2. 遇到缩写时查看[中英术语表](docs/glossary.md)；
-3. 需要理解信用关联时，运行 TSD-CRD Reference Implementation，观察关联、映射、生命周期、查询授权和验证；
-4. 运行 Local A402 Sample，观察 `402 → Payment-Needed → 伪 Proof 被拒绝` 的安全路径；
+1. 打开 [ACT 官网 Demo](https://www.act-protocol.com/demo)，先直观看到 Agent 商业流程中的业务步骤、参与方和协议组件；
+2. 用 2 分钟阅读[协议概览](docs/specification/overview.md)，区分 ADD、CID、PSD、TSD 与 A402；遇到缩写时查看[中英术语表](docs/glossary.md)；
+3. 阅读[典型场景与业务流程](docs/specification/scenarios.md)，把演示步骤对应到完整协议流程；
+4. 根据关注点运行 Local A402 Sample 或 TSD-CRD Reference Implementation，分别观察安全支付路径或信用关联路径；
 5. 需要真实支付成功链路时，选择[支付宝买方](integrations/alipay/buyer-agent/README.md)或[卖方 Java](integrations/alipay/seller-java/README.md)，并在官网沙箱完成授权和支付。
 
 Local A402 Sample 有意不伪造支付成功。真实资源交付必须来自已经验真的支付证明，因此“本地安全失败路径”和“官网沙箱成功路径”是两个不同的接入阶段。TSD-CRD Reference Implementation 同样只使用 Mock 能力和测试密钥，不是生产信用服务。
 
 ACT 2.1 的五份规范正文和非规范性场景指南位于 `docs/specification/`。A402 与 Commerce–Payment 接入指南随支付宝参考接入放在 `integrations/alipay/`。JSON Schema、fixtures 和测试位于 `code/schemas/`，用于帮助实现与验证，不增加协议正文未规定的要求。
 
-本仓库发布版本中，`docs/specification/` 下的协议概览和四份域规范共同构成 ACT 2.1 唯一的版本化规范正文；场景指南明确为非规范性材料。[act-protocol.com](https://www.act-protocol.com/) 是项目信息入口；未明确标注 ACT 2.1 版本的网页内容属于信息性材料，不是本 Release 的规范来源。网页如果遗漏本 Release 的组件、采用不同结构或与正文冲突，只能按网页自身标明的版本理解，不得用于覆盖或解释本仓库的 ACT 2.1 要求。
+`docs/specification/` 下的协议概览和四份域规范共同构成 ACT 2.1 的版本化规范正文，场景指南属于非规范性材料。[act-protocol.com](https://www.act-protocol.com/) 提供项目信息和在线演示，不替代本仓库中的版本化规范。
 
 ## 仓库结构
 
@@ -59,17 +60,27 @@ sample / demo
 
 产品实现、演示和 `tools/` 下的验证程序不得反向定义协议语义。
 
-## 运行本地样例
+## 在线体验 Demo
+
+无需下载或安装，即可打开 [ACT 官网 Demo](https://www.act-protocol.com/demo) 体验协议流程。官网 Demo 是交互演示，不是支付实现或一致性认证。
+
+## 本地运行
 
-下载或 clone 本仓库后，在仓库根目录执行以下命令，需要 Node.js 18 或更高版本：
+以下三个 Node.js 程序均无第三方运行时依赖，不需要先执行 `npm install`。下载或 clone 本仓库后，在仓库根目录运行。
+
+### Local A402 Sample
+
+需要 Node.js 18 或更高版本：
 
 ```bash
 npm --prefix code/samples/local-a402 run local
 ```
 
 这个样例返回 `402 Payment Required`、解码 `Payment-Needed`，并验证伪造的 `Payment-Proof` 不会导致资源交付。它不连接支付产品，也不会执行支付。
 
-运行 TSD-CRD 测试、基础一致性检查和本地 Demo 需要 Node.js 22.18 或更高版本：
+### TSD-CRD Reference Implementation
+
+需要 Node.js 22.18 或更高版本。运行测试、基础一致性检查和本地 Demo：
 
 ```bash
 npm --prefix code/samples/tsd-crd-reference run check
@@ -78,27 +89,29 @@ npm --prefix code/samples/tsd-crd-reference run demo
 
 该套件采用非规范性的 `reference-v1` 机器 Profile。测试通过只证明仓库内参考路径，不等于 ACT 2.1 全量 Conformance 或生产就绪。
 
-运行交互演示：
+### Web Showcase
+
+需要 Node.js 18 或更高版本。如需在本地查看或修改交互演示源码，运行：
 
 ```bash
 npm --prefix code/web-client/alipay-ai-pay-showcase run demo
 ```
 
-打开 `http://127.0.0.1:4173/`。Showcase 是协议流程演示，不是支付实现或一致性认证。
+打开 `http://127.0.0.1:4173/`。本地 Showcase 是协议流程演示，不是支付实现或一致性认证。
 
 ## 支付宝参考接入
 
 `integrations/alipay/` 展示两侧能力：
 
-- `buyer-agent/`：检查环境并引导安装支付宝官方 Agent Payment Skill/CLI；
-- `seller-java/`：使用支付宝 Java SDK 验证支付凭证并确认履约；
+- `buyer-agent/`：检查环境并引导安装买方钱包与支付工具 `@alipay/agent-payment`；
+- `seller-java/`：使用支付宝 Java SDK 接入 Machine Pay，验证支付凭证并确认履约；支付宝官方卖方接入助手 `@alipay/alipay-aipay` 仅作为外部工具引用；
 - `validation/`：沙箱前置检查和脱敏证据格式。
 
 支付宝开户、授权、密钥、沙箱和最新产品操作始终以 [AIPay 官网](https://aipay.alipay.com/callpay)及其[官方接入指南](https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html)为准。本仓库不复制或实现官网沙箱。
 
 ## 质量检查
 
-完整检查需要 Python 3、Node.js 22.18+、JDK 8+ 和 Maven 3.8+：
+完整检查需要 Python 3、Node.js 22.18+、JDK 8+ 和 Maven 3.8+。检查包含仓库结构、内部链接、关键官网外链、Schema、样例、集成和 Demo：
 
 ```bash
 ./tools/verify.sh

diff --git a/code/README.md b/code/README.md
@@ -6,6 +6,6 @@ This directory contains executable and machine-readable assets. It does not defi
 |---|---|
 | [`schemas/`](schemas/README.md) | JSON Schemas, fixtures, examples, test vectors, and implementation tests |
 | [`samples/`](samples/README.md) | Small runnable samples and the TSD-CRD reference implementation |
-| [`web-client/`](web-client/README.md) | Interactive protocol demonstrations |
+| [`web-client/`](web-client/README.en.md) | Interactive protocol demonstrations |
 
 The ACT 2.1 text is under [`docs/specification/`](../docs/specification/README.md). Reference implementation guidance and product-specific code belong under [`integrations/`](../integrations/README.md).
diff --git a/code/web-client/README.en.md b/code/web-client/README.en.md
@@ -0,0 +1,9 @@
+# Web client
+
+[简体中文](README.md) | English
+
+The demos in this directory explain protocol flows visually. They do not establish real payment, product compatibility, or production readiness.
+
+- [ACT 2.1 Machine Payment Showcase](alipay-ai-pay-showcase/README.en.md): presents business execution, participants, and protocol steps side by side using explanatory data only; it neither connects to nor replays an official product sandbox.
+
+To connect to the Alipay product or its sandbox, use the [Alipay Reference Integration](../../integrations/alipay/README.md).
diff --git a/code/web-client/README.md b/code/web-client/README.md
@@ -1,7 +1,9 @@
 # Web client
 
+[English](README.en.md) | 简体中文
+
 Demo 用于直观展示协议流程，但不能据此声明真实支付、产品兼容或生产就绪。
 
-- [ACT 2.1 Machine Payment Showcase](alipay-ai-pay-showcase/README.md)：对照业务与协议步骤，并可回放官方产品沙箱产生的脱敏证据。
+- [ACT 2.1 Machine Payment Showcase](alipay-ai-pay-showcase/README.md)：以左右对照方式展示业务执行、参与方和协议步骤；只使用说明性演示数据，不连接或回放官方产品沙箱。
 
 连接支付宝产品或沙箱请使用 [Alipay Reference Integration](../../integrations/alipay/README.md)。
diff --git a/code/web-client/alipay-ai-pay-showcase/README.en.md b/code/web-client/alipay-ai-pay-showcase/README.en.md
@@ -0,0 +1,78 @@
+# ACT × Alipay AI Pay Guided Showcase
+
+[简体中文](README.md) | English
+
+This demo explains how an agent purchases professional data during research. It presents business execution, participants, ACT 2.1 components, and Alipay product mappings side by side.
+
+> **Scope: Guided Demo / Non-normative / No real payment**
+> The demo does not connect to an Alipay sandbox, wallet, payment API, or proof-verification API. It receives no real events and performs no payment.
+
+## What the demo covers
+
+| Scenario | Core distinction | Alipay implementation boundary |
+|---|---|---|
+| L1 / `PSD-PAY-INS` | The user authenticates and confirms every payment | Shows an explanatory Alipay binding QR-code placeholder and payment confirmation card; the QR code cannot be scanned |
+| L2 / `PSD-PAY-DEL` | The user pre-authorizes a specific item, merchant, amount, and number of payments; matching payments proceed automatically | Demonstrates ACT 2.1 semantics only; this repository makes no claim about an Alipay L2 implementation |
+| L3 / `PSD-PAY-AUP` | The user sets task and budget boundaries; the agent selects and pays autonomously within them | Demonstrates ACT 2.1 semantics only; this repository makes no claim about an Alipay L3 implementation |
+
+Each scenario shows `CID-PCA-NEG`, commercial confirmation, the resource request, HTTP 402, `Payment-Needed`, payment handling, retrying the original request with `Payment-Proof`, proof verification, resource delivery, and fulfillment confirmation. Failure modes cover an unknown payment result, proof mismatch, unavailable proof verification, and idempotent retry.
+
+## Requirements
+
+- Node.js 18 or later.
+- No `npm install` is required.
+- Run the commands below from the repository root.
+
+## Start
+
+```bash
+npm --prefix code/web-client/alipay-ai-pay-showcase run demo
+```
+
+After startup, the terminal prints:
+
+```text
+ACT showcase: http://127.0.0.1:4173/
+```
+
+The server does not open a browser automatically. Visit `http://127.0.0.1:4173/`, then:
+
+1. Select L1, L2, or L3 to compare the three authorization levels.
+2. Use step-by-step playback to inspect the business action, participants, and protocol component at each stage.
+3. Use autoplay to watch the complete flow.
+4. Switch failure modes to inspect an unknown payment result, proof mismatch, unavailable verification, and idempotent retry.
+
+The server runs in the foreground. Press `Ctrl+C` to stop it.
+
+## Change the port
+
+The default port is `4173`. If it is already in use, set `PORT` to another value.
+
+macOS or Linux:
+
+```bash
+PORT=4174 npm --prefix code/web-client/alipay-ai-pay-showcase run demo
+```
+
+Windows PowerShell:
+
+```powershell
+$env:PORT=4174; npm --prefix code/web-client/alipay-ai-pay-showcase run demo
+```
+
+Open the new address printed by the terminal. If startup reports `EADDRINUSE`, the selected port is also occupied; choose another port and retry.
+
+## Boundaries
+
+- Orders, amounts, transaction references, QR codes, and results shown in the page are explanatory demo data.
+- The demo does not verify a real `Payment-Proof`, provide payment-success evidence, or constitute conformance certification.
+- ACT semantics come from the finalized specification under [`docs/specification/`](../../../docs/specification/README.md).
+- Use the [AIPay website](https://aipay.alipay.com/callpay) and its official integration documentation for Alipay product integration. This repository provides reference integration material only under [`integrations/alipay/`](../../../integrations/alipay/README.md).
+- The official sandbox is provided and operated by Alipay. This demo does not copy, proxy, or offer a “connect sandbox” feature.
+
+## Checks
+
+```bash
+npm --prefix code/web-client/alipay-ai-pay-showcase test
+npm --prefix code/web-client/alipay-ai-pay-showcase run build
+```