ChanTso · ChanTso · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026
diff --git a/.devin/wiki.json b/.devin/wiki.json
@@ -0,0 +1,41 @@
+{
+  "repo_notes": [
+    {
+      "content": "Document the current source tree and the active README, docs/RUNTIME.md, docs/BUYER.md, and platform READMEs. This is one retail brand's own store, not a multi-merchant marketplace. ShopMate owns the Python API and buyer/merchant/analysis agents; CityBuddy is a separate repository providing Java Auth/Commerce services. Do not conflate CityBuddy agent-service or its engineering Web console with this repository's current agent host and merchant workspace. Trace every architecture arrow to actual code. The host uses a SELECT-only MySQL reporting account; analysis_runner.py passes complete bounded tables and code to analysis_sandbox.py. The Python sandbox has no network, database connection, or credentials. SQLite/WAL holds single-instance host conversations, recovery intents, and memory; Java/MySQL owns identity and transactions. Native flash-sale reservation/status calls go directly to Commerce, while simulated-payment orchestration goes through the ShopMate host. Android uses native Jetpack Compose and iOS native SwiftUI; KMP shares business/protocol rules, not the UI. Historical demo, transport and evaluation records retain their original measured revisions: Next.js references there are historical, not the current React/Vite workspace. Distinguish raw quoted prompts from documentation instructions. Do not invent performance, production capacity, multi-instance support, or authorization effectiveness from unactivated trials."
+    }
+  ],
+  "pages": [
+    {
+      "title": "Overview and architecture",
+      "purpose": "Explain the product, one-store business scope, native clients, Python host, external CityBuddy Auth/Commerce, and exact data/analysis boundaries. Use README.md, docs/RUNTIME.md, and actual routes."
+    },
+    {
+      "title": "Local setup and repository guide",
+      "purpose": "Document current run/build/check commands from active runtime and platform READMEs; explain directory ownership, product site, and contribution workflow."
+    },
+    {
+      "title": "Native clients and shared Kotlin core",
+      "purpose": "Describe Android Compose and iOS SwiftUI, shared SSE decoding/reduction/recovery rules, native lifecycle/network/storage, streaming rendering and reading position. Cover android/, ios/, shared/ and relevant tests."
+    },
+    {
+      "title": "Buyer shopping and recovery",
+      "purpose": "Trace ordinary shopping, conversation ownership, user/OBO identities, request keys, quote confirmation, lost-response recovery, refunds and direct flash-sale calls using buyer routes, clients, sessions, and docs/BUYER.md."
+    },
+    {
+      "title": "Merchant workspace and controlled execution",
+      "purpose": "Describe current React/Vite web/ UI, proposal previews, operator approval, Java receipts and concurrent ordinary/agent operations. Trace actual direct-user and delegated paths without treating all confirmations as the same token type."
+    },
+    {
+      "title": "Agent analysis, sandbox, memory and budgets",
+      "purpose": "Cover buyer/merchant/analysis factories, bounded shared model/tool budgets, read-only host SQL, complete-table handoff to the no-network Python sandbox, skills, editable memory and model transport."
+    },
+    {
+      "title": "Tests and measured evaluations",
+      "purpose": "Explain native/host/integration checks and retail acceptance. Keep retail-v1, retail-v2 and historical assessments separate by full measured SHA and denominator; report failures, provider errors, timing boundaries and non-activated ownership trials accurately."
+    },
+    {
+      "title": "Product showcase and attribution",
+      "purpose": "Explain site/ as an independently built GitHub Pages showcase, local full-stack demonstration, source/asset provenance and vendored licensing. Do not present site interactions as a public live transaction backend."
+    }
+  ]
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,23 +11,23 @@ uv sync --frozen
 npm --prefix web ci
 ```
 
-The [runtime guide](docs/RUNTIME.md#本地运行) covers the sibling CityBuddy checkout, Java 21, Docker Compose, and local service configuration. Native prerequisites and build commands are in the [Android](android/README.md) and [iOS](ios/README.md) guides. The [product site](site/README.md) can be previewed independently.
+The [runtime guide](docs/RUNTIME.md#run-locally) covers the sibling CityBuddy checkout, Java 21, Docker Compose, and local service configuration. Native prerequisites and build commands are in the [Android](android/README.md) and [iOS](ios/README.md) guides. The [product site](site/README.md) can be previewed independently.
 
 ## Check your changes
 
 Run checks for the areas you change:
 
 | Area | Checks |
 |---|---|
-| Python host | `uv run ruff check src tests scripts integration_tests`, `uv run ruff format --check src tests scripts integration_tests`, and the application/runtime pytest suite in the [runtime guide](docs/RUNTIME.md#检查与历史记录) |
+| Python host | `uv run ruff check src tests scripts integration_tests`, `uv run ruff format --check src tests scripts integration_tests`, and the application/runtime pytest suite in the [runtime guide](docs/RUNTIME.md#checks-and-historical-records) |
 | Merchant Web | `npm --prefix web run typecheck`, `npm --prefix web test`, `npm --prefix web run build` |
 | Android / shared Kotlin | `cd android && ./gradlew --no-daemon :shared:jvmTest :app:assembleDebug :app:testDebugUnitTest :app:lintDebug` |
 | iOS | Follow the [build and Simulator test commands](ios/README.md) for the affected behavior; the CI build-for-testing step builds test bundles but does not run them |
 | Documentation / site | Check relative links and language switches; preview changed layouts at desktop and mobile widths |
 
 [GitHub Actions](.github/workflows/ci.yml) runs the Python, Web, Android, and Apple build checks on pull requests. Preserve existing tests; add regression coverage when a behavior change needs it.
 
-Real Java/database integration tests and real-model evaluations are separate from the checks above. `uv run pytest integration_tests -q` changes demo business data: use the [fixture reset and serial-run instructions](docs/RUNTIME.md#检查与历史记录). Read a recorded evaluation's setup before running it; model calls use the configured provider and may incur cost.
+Real Java/database integration tests and real-model evaluations are separate from the checks above. `uv run pytest integration_tests -q` changes demo business data: use the [fixture reset and serial-run instructions](docs/RUNTIME.md#checks-and-historical-records). Read a recorded evaluation's setup before running it; model calls use the configured provider and may incur cost.
 
 ## Submit a pull request
 

diff --git a/README.md b/README.md
@@ -1,14 +1,24 @@
-[![ShopMate · Native commerce and agents](docs/assets/cover.png)](https://chantso.github.io/shopmate/)
+<p align="center">
+  <a href="https://chantso.github.io/shopmate/">
+    <img src="docs/assets/logo.svg" alt="ShopMate" width="128" height="138">
+  </a>
+</p>
 
-# ShopMate
+<h1 align="center">ShopMate</h1>
 
-**English** · [简体中文](README.zh-CN.md)
+<p align="center">
+  <a href="https://chantso.github.io/shopmate/"><strong>Explore the product ↗</strong></a>
+</p>
+
+<p align="center">Native shopping apps and commerce agents. From choosing to confirming to acting.</p>
 
-[![CI](https://github.com/ChanTso/shopmate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ChanTso/shopmate/actions/workflows/ci.yml)
+<p align="center">
+  <a href="https://github.com/ChanTso/shopmate/actions/workflows/ci.yml"><img src="https://github.com/ChanTso/shopmate/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+</p>
 
-**Native shopping apps and commerce agents. A continuous path from choosing to confirming to acting.**
+**English** · [简体中文](README.zh-CN.md)
 
-**[Explore the product ↗](https://chantso.github.io/shopmate/)** · [Android](android/README.md) · [iOS](ios/README.md) · [Run locally](docs/RUNTIME.md#本地运行) · [Retail evaluation](evals/records/retail-v2-20260907/README.md) · [Contributing](CONTRIBUTING.md)
+[Android](android/README.md) · [iOS](ios/README.md) · [Run locally](docs/RUNTIME.md#run-locally) · [Retail evaluation](evals/records/retail-v2-20260907/README.md) · [Contributing](CONTRIBUTING.md)
 
 Android / iOS buyer apps and a React merchant workspace for one retail brand. Shoppers describe what they need, compare products, and confirm transactions. Operators turn business data into proposals, review changes, and approve execution. [CityBuddy](https://github.com/ChanTso/citybuddy) provides the transaction and identity backend.
 
@@ -33,19 +43,28 @@ The product site presents native application footage and interaction demonstrati
 ## System boundaries
 
 ```mermaid
-flowchart LR
-    App[Android / iOS] --> Host[ShopMate API]
+flowchart TB
+    App[Android / iOS] --> Host[ShopMate API and agents]
     Web[React merchant workspace] --> Host
-    Host --> Agents[Buyer / Merchant agents]
-    Agents --> Analysis[Read-only SQL / Python sandbox]
+    App -->|Flash-sale reservations and status| Commerce[CityBuddy Commerce]
+    Host -->|Login and scoped delegation| Auth[CityBuddy Auth]
+    Host -->|Scoped tools and user actions| Commerce
     Host --> State[(SQLite: conversations and recovery)]
-    Host -->|Scoped tools / user confirmation| Java[CityBuddy: Auth / Commerce]
-    App -->|Flash sales| Java
-    Java --> DB[(MySQL: business state)]
-    Analysis -->|Read-only business views| DB
+    Auth --> DB[(MySQL: identity and transactions)]
+    Commerce --> DB
+```
+
+Merchant analysis uses a separate data path. The host queries reporting views with a read-only account, then passes complete, bounded tables to the network-isolated Python container.
+
+```mermaid
+flowchart LR
+    SQL[Host SQL analysis] -->|SELECT-only| Views[(MySQL reporting views)]
+    SQL -->|Complete table and code| Python[Python container: no network]
 ```
 
-ShopMate currently runs as a single-instance host. SQLite with WAL stores conversations, intents, and preferences; MySQL stores identities, products, orders, and transaction receipts. See the [runtime guide](docs/RUNTIME.md#身份对话与持久状态) for ownership and deployment constraints.
+The Python container has no database connection or credentials. Identity, conversation ownership, and business authorization remain enforced by their owning services.
+
+ShopMate currently runs as a single-instance host. SQLite with WAL stores conversations, intents, and preferences; MySQL stores identities, products, orders, and transaction receipts. See the [runtime guide](docs/RUNTIME.md#identity-conversations-and-persistent-state) for ownership and deployment constraints.
 
 ## Validation and results
 
@@ -59,7 +78,7 @@ The [retail evaluation](evals/records/retail-v2-20260907/README.md) records **18
 
 ## Run locally
 
-Prerequisites: a sibling CityBuddy checkout, Java 21, Python 3.11+, Node.js 24, uv, and Docker Compose. Complete the [initial backend setup](docs/RUNTIME.md#本地运行), then run:
+Prerequisites: a sibling CityBuddy checkout, Java 21, Python 3.11+, Node.js 24, uv, and Docker Compose. Complete the [initial backend setup](docs/RUNTIME.md#run-locally), then run:
 
 ```sh
 uv sync --frozen
@@ -80,6 +99,6 @@ Open the merchant workspace at **http://127.0.0.1:8101/**. Build the buyer apps
 | [`integration_tests/`](integration_tests/) · [`evals/`](evals/) | Business-boundary tests and real-model evaluations |
 | [`site/`](site/) | Independently built GitHub Pages product site |
 
-ShopMate reuses the retail cores and Messages runtime from [commerce-agents](vendor/commerce-agents/README.md), adding native clients, business tools, identity, persistent state, and transaction integration. Upstream [Apache-2.0 licensing](vendor/commerce-agents/LICENSE) and [image credits](web/public/products/IMAGE-CREDITS.md) are preserved. The cover uses the [same native demo footage as the product site](site/README.md).
+ShopMate reuses the retail cores and Messages runtime from [commerce-agents](vendor/commerce-agents/README.md), adding native clients, business tools, identity, persistent state, and transaction integration. Upstream [Apache-2.0 licensing](vendor/commerce-agents/LICENSE) and [image credits](web/public/products/IMAGE-CREDITS.md) are preserved. The [product site notes](site/README.md) describe how its native footage and interaction demonstrations were made.
 
 [Contributing](CONTRIBUTING.md) · [Apache-2.0 license](LICENSE)
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -1,14 +1,24 @@
-[![ShopMate · 选购有灵感，经营有把握](docs/assets/cover.png)](https://chantso.github.io/shopmate/)
+<p align="center">
+  <a href="https://chantso.github.io/shopmate/">
+    <img src="docs/assets/logo.svg" alt="ShopMate" width="128" height="138">
+  </a>
+</p>
 
-# ShopMate
+<h1 align="center">ShopMate</h1>
 
-[English](README.md) · **简体中文**
+<p align="center">
+  <a href="https://chantso.github.io/shopmate/"><strong>Explore the product ↗</strong></a>
+</p>
+
+<p align="center">原生购物客户端与经营 Agent，让选择、确认与执行成为连续的体验。</p>
 
-[![CI](https://github.com/ChanTso/shopmate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ChanTso/shopmate/actions/workflows/ci.yml)
+<p align="center">
+  <a href="https://github.com/ChanTso/shopmate/actions/workflows/ci.yml"><img src="https://github.com/ChanTso/shopmate/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+</p>
 
-**原生购物客户端 × 经营 Agent，让选择、确认与执行成为连续的体验。**
+[English](README.md) · **简体中文**
 
-**[浏览产品官网 ↗](https://chantso.github.io/shopmate/)** · [Android](android/README.md) · [iOS](ios/README.md) · [本地运行](docs/RUNTIME.md#本地运行) · [业务验收](evals/records/retail-v2-20260907/README.md) · [贡献指南](CONTRIBUTING.md)
+[Android](android/README.md) · [iOS](ios/README.md) · [本地运行](docs/RUNTIME.md#run-locally) · [业务验收](evals/records/retail-v2-20260907/README.md) · [贡献指南](CONTRIBUTING.md)
 
 面向同一零售品牌的 Android / iOS 买家 App 与 React 商家工作台。买家说出需求、比较商品、确认交易；运营人员从经营数据出发，准备方案、核对变更并批准执行。[CityBuddy](https://github.com/ChanTso/citybuddy) 提供实际交易与身份后端。
 
@@ -33,19 +43,28 @@
 ## 系统边界
 
 ```mermaid
-flowchart LR
-    App[Android / iOS] --> Host[ShopMate API]
+flowchart TB
+    App[Android / iOS] --> Host[ShopMate API 与 Agent]
     Web[React 商家工作台] --> Host
-    Host --> Agents[买家 / 经营 Agent]
-    Agents --> Analysis[只读 SQL / Python 沙箱]
-    Host --> State[(SQLite · 对话与恢复)]
-    Host -->|受限工具 / 人工确认| Java[CityBuddy · Auth / Commerce]
-    App -->|秒杀| Java
-    Java --> DB[(MySQL · 业务状态)]
-    Analysis -->|只读经营视图| DB
+    App -->|秒杀预约与状态查询| Commerce[CityBuddy Commerce]
+    Host -->|登录与受限委托交换| Auth[CityBuddy Auth]
+    Host -->|受限工具与用户操作| Commerce
+    Host --> State[(SQLite: 对话与恢复)]
+    Auth --> DB[(MySQL: 身份与交易)]
+    Commerce --> DB
+```
+
+经营分析有单独的数据通路：宿主以只读账号查询视图，再把完整、有界的数据表交给无网络 Python 容器。
+
+```mermaid
+flowchart LR
+    SQL[宿主 SQL 分析] -->|SELECT-only| Views[(MySQL 经营视图)]
+    SQL -->|完整数据表与代码| Python[Python 容器: 无网络]
 ```
 
-ShopMate 当前为单实例宿主，SQLite 使用 WAL 保存对话、意图和偏好；MySQL 保存身份、商品、订单和交易回执。两者职责与运行约束见[工程指南](docs/RUNTIME.md#身份对话与持久状态)。
+Python 容器没有数据库连接或凭证；账户、对话归属与业务授权仍由各自服务校验。
+
+ShopMate 当前为单实例宿主，SQLite 使用 WAL 保存对话、意图和偏好；MySQL 保存身份、商品、订单和交易回执。两者职责与运行约束见[工程指南](docs/RUNTIME.md#identity-conversations-and-persistent-state)。
 
 ## 验证与结果
 
@@ -57,7 +76,7 @@ ShopMate 当前为单实例宿主，SQLite 使用 WAL 保存对话、意图和
 
 ## 本地运行
 
-需要同级 CityBuddy 仓库、Java 21、Python 3.11+、Node.js 24、uv 与 Docker Compose。完成[首次后端准备](docs/RUNTIME.md#本地运行)后：
+需要同级 CityBuddy 仓库、Java 21、Python 3.11+、Node.js 24、uv 与 Docker Compose。完成[首次后端准备](docs/RUNTIME.md#run-locally)后：
 
 ```sh
 uv sync --frozen
@@ -78,6 +97,6 @@ uv run uvicorn shopmate.app:create_app --factory --host 127.0.0.1 --port 8101
 | [`integration_tests/`](integration_tests/) · [`evals/`](evals/) | 业务边界测试与真实模型验收 |
 | [`site/`](site/) | 独立构建的 GitHub Pages 产品官网 |
 
-复用 [commerce-agents](vendor/commerce-agents/README.md) 的零售核心与 Messages 运行时，扩展原生客户端、业务工具、身份、持久状态与实际交易接入。保留上游 [Apache-2.0 许可](vendor/commerce-agents/LICENSE)及[图片来源](web/public/products/IMAGE-CREDITS.md)；封面使用[官网中相同的原生演示画面](site/README.md)。
+复用 [commerce-agents](vendor/commerce-agents/README.md) 的零售核心与 Messages 运行时，扩展原生客户端、业务工具、身份、持久状态与实际交易接入。保留上游 [Apache-2.0 许可](vendor/commerce-agents/LICENSE)及[图片来源](web/public/products/IMAGE-CREDITS.md)；[官网说明](site/README.md)记录了原生画面与交互演示的制作方式。
 
 [贡献指南](CONTRIBUTING.md) · [Apache-2.0 许可](LICENSE)