@seasonkoh/webaz 0.1.16 → 0.1.18

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -11,6 +11,11 @@
  *   webaz_update_order  L1-6 更新订单状态（发货/揽收/投递/确认/争议）
  *   webaz_get_status    L1-4 查询订单状态和历史
  *   webaz_wallet        查看钱包余额
+ *   …（39 工具,完整定义见下方 TOOLS 数组;数量以 TOOLS.length 为准）
+ *
+ * 双模(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ SANDBOX(本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
+ * 关联 / Related: AGENTS.md · RFC-003(双模) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
+ *   #6 不滥用(agent 责任制 + Iron-Rule 真人动作)· 生产端点在 src/pwa(NETWORK 共用)
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -30,6 +35,87 @@ const TELEMETRY_URL = process.env.WEBAZ_TELEMETRY_URL ?? 'https://webaz.xyz/api/
 // 2026-06-01: phase A pre-launch 默认 OFF(opt-in)— W8 public launch 时翻回 default ON + 加 README 披露段
 // Phase A pre-launch: telemetry default OFF (opt-in). Flip to default ON at W8 launch + add README disclosure section.
 const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() === 'on';
+// ─── RFC-003 P0: 双模(NETWORK / SANDBOX)骨架 ─────────────────────
+// NETWORK = 带 api_key 调 webaz.xyz/api(加入共享生产网络);SANDBOX = 本地 SQLite(离线试玩,与全网隔离)。
+// P0 不迁移任何工具(NETWORK_TOOLS 为空)→ 一切仍走本地 = 零行为变化;P1/P2 逐个把工具名加入集合切到网络。
+const WEBAZ_API_URL = (process.env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
+const WEBAZ_API_KEY = process.env.WEBAZ_API_KEY ?? '';
+const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
+// 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 → sandbox
+const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
+    : WEBAZ_MODE_ENV === 'sandbox' ? 'sandbox'
+        : (WEBAZ_API_KEY ? 'network' : 'sandbox');
+// 已迁移到 NETWORK 的工具名。P1/P2 逐个加入;未在集合里的工具仍走 sandbox(本地)。
+// P1(读工具): 纯公开读,无写无 Passkey,作"MCP 连得上生产网络"的首验证。
+const NETWORK_TOOLS = new Set([
+    'webaz_price_history',
+    'webaz_leaderboard',
+    'webaz_verify_price',
+    'webaz_place_order',
+    'webaz_list_product',
+    'webaz_update_order',
+    'webaz_search',
+    'webaz_get_status',
+    'webaz_feedback',
+    'webaz_contribute',
+]);
+const recentCalls = [];
+function pushRecentCall(c) {
+    recentCalls.push(c);
+    if (recentCalls.length > 8)
+        recentCalls.shift(); // 只留最近 8 条
+}
+// 单个工具实际后端:仅当全局 network 且该工具已迁移,才走网络;否则 sandbox。
+function toolBackend(tool) {
+    return (MODE === 'network' && NETWORK_TOOLS.has(tool)) ? 'network' : 'sandbox';
+}
+// 统一 API helper(P1/P2 迁移工具时使用)。Bearer api_key + 15s 超时 + 错误映射。
+async function apiCall(path, opts = {}) {
+    const { method = 'GET', body } = opts;
+    const key = opts.apiKey || WEBAZ_API_KEY; // 每次调用可覆盖(工具 args.api_key 优先);否则用全局配置 key
+    const url = WEBAZ_API_URL + (path.startsWith('/') ? path : '/' + path);
+    try {
+        const resp = await fetch(url, {
+            method,
+            headers: {
+                ...(key ? { authorization: `Bearer ${key}` } : {}),
+                ...(body != null ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(body != null ? { body: JSON.stringify(body) } : {}),
+            signal: AbortSignal.timeout(15_000),
+        });
+        let json = null;
+        try {
+            json = await resp.json();
+        }
+        catch {
+            json = null;
+        }
+        if (!resp.ok) {
+            const map = {
+                401: 'api_key 无效或未注册 — 请在 https://webaz.xyz 注册并把 api_key 填入 WEBAZ_API_KEY',
+                403: '权限不足 / 需邀请码 / 该动作需真人 Passkey(请到 webaz.xyz 用 Passkey 操作)',
+                429: '调用过于频繁,请稍后再试',
+                503: '服务暂不可用,请稍后重试',
+            };
+            return { error: json?.error ?? map[resp.status] ?? `HTTP ${resp.status}`, error_code: json?.error_code, http_status: resp.status };
+        }
+        return json ?? {};
+    }
+    catch (e) {
+        const msg = e.name === 'TimeoutError' ? '请求超时(15s)' : e.message;
+        return { error: `网络错误:${msg}`, network_error: true };
+    }
+}
+// 启动 banner(stderr)+ status 声明用 —— 让用户/agent 一眼知道现在是真网络还是沙盒
+function modeBanner() {
+    if (MODE === 'network') {
+        return `🟢 NETWORK mode — webaz.xyz (${WEBAZ_API_URL}). Migrated tools: ${NETWORK_TOOLS.size}/${TOOLS.length}`
+            + (NETWORK_TOOLS.size === 0 ? ' ⚠️ network client not active yet (P0 scaffold) — all tools still SANDBOX/local.' : '');
+    }
+    return `🟡 SANDBOX mode — local-only (~/.webaz/webaz.db), NOT the live network. Data is private to this machine.`
+        + (WEBAZ_API_KEY ? '' : ' Set WEBAZ_API_KEY (register at webaz.xyz) to join the network.');
+}
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
 initSystemUser(db);
@@ -156,10 +242,7 @@ const TOOLS = [
 Returns: protocol overview, available tools, role responsibilities, operation flows, **network_state (pre-launch disclaimer)**, **commission_model.compliance_notice (MLM-form disclosure)**.
 No auth required, no parameters needed.
 
-⚠️ Important: WebAZ is currently **pre-launch** with ~0 real users on the canonical endpoint. All stats / counts returned by this and other tools come from the **local MCP SQLite DB**, not protocol-wide prod state. Read network_state field BEFORE you treat any number as real-economy data.
-
-──
-中文：获取 WebAZ 说明 — 新 Agent 接入协议时应首先调用，返回协议简介、可用工具、角色职责、**网络状态(pre-launch 披露)** + **佣金结构合规提示(MLM 形态披露)**。⚠️ 协议尚未上线,统计来自本地库,不是真实运营数据。`,
+⚠️ Important: WebAZ is currently **pre-launch** with ~0 real users on the canonical endpoint. All stats / counts returned by this and other tools come from the **local MCP SQLite DB**, not protocol-wide prod state. Read network_state field BEFORE you treat any number as real-economy data.`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -167,46 +250,31 @@ No auth required, no parameters needed.
     },
     {
         name: 'webaz_register',
-        description: `Register a new WebAZ account. Returns:
-- api_key (credential, 36 chars, 128-bit crypto random — store securely)
-- permanent_code (6-char recovery code — use with handle via webaz_mykey to recover lost api_key)
-- handle (URL-safe unique ID derived from name; if requested handle is taken, system auto-appends numeric suffix — check handle_modified flag)
-- created_at (ISO timestamp)
-
-⚠️ Consent required: WebAZ is pre-launch and contains a 3-tier commission + binary PV pairing structure (see webaz_info.commission_model.compliance_notice — may overlap with MLM legal definitions). An agent acting for a human user MUST get the user's explicit, informed consent BEFORE creating an account on their behalf. Do NOT auto-register users just because they asked a generic shopping question.
+        // was ~1732 chars, now ~780 chars
+        description: `Register a new WebAZ account. Returns: api_key (36-char 128-bit credential, store securely) + permanent_code (6-char recovery code, pair with handle in webaz_mykey to recover lost api_key) + handle (URL-safe ID; if taken, system appends numeric suffix — check handle_modified flag) + created_at.
 
-Roles:
-- buyer:      browse, order, confirm receipt
-- seller:     list products, accept orders, ship
-- logistics:  pickup, transit updates, delivery confirm
-- reviewer:   structured product reviews
-- arbitrator: handle disputes, issue rulings
+⚠️ **Consent required (MLM disclosure)**: WebAZ is pre-launch with 3-tier commission + binary PV pairing structure (may overlap with MLM legal definitions; see webaz_info.commission_model.compliance_notice). Agent acting on behalf of human user **MUST get explicit informed consent BEFORE creating account**. Do NOT auto-register from generic shopping questions.
 
-⚠️ MCP register limitations (by-design anti-bot):
-- Does NOT set placement_id / sponsor_id (binary tree + referral chain not built) — MCP registration does NOT enroll the user into the multi-tier structure
-- To build a referral chain: user must arrive via webaz_share_link ?ref=<uid> URL clicked in browser (PWA flow) — explicit user action required
-- region defaults to 'global' if omitted; valid: singapore, china, usa, malaysia, indonesia, thailand, vietnam, taiwan, hk, global
+Roles: buyer (browse/order/confirm) | seller (list/accept/ship) | logistics (pickup/transit/deliver) | reviewer (reviews) | arbitrator (disputes/rulings).
 
-──
-中文：注册 WebAZ 账户。返回 api_key（128-bit 凭证）+ permanent_code（恢复码）+ handle（唯一标识，冲突自动加后缀，看 handle_modified）+ created_at。可选角色：买家/卖家/物流/测评员/仲裁员。
-注意：MCP register 不建立 placement/sponsor 链（防 bot），需要建链时用 webaz_share_link + PWA 浏览器注册。`,
+⚠️ **MCP register limitations (anti-bot, by design)**: does NOT set placement_id/sponsor_id — referral/PV chain NOT built via MCP. To build chain: user must arrive via webaz_share_link \`?ref=<uid>\` URL clicked in browser (PWA flow). region defaults 'global'; valid: singapore/china/usa/malaysia/indonesia/thailand/vietnam/taiwan/hk/global.`,
         inputSchema: {
             type: 'object',
             properties: {
-                name: { type: 'string', description: '你的名字或店铺名称' },
+                name: { type: 'string', description: 'Your name or shop name' },
                 role: {
                     type: 'string',
                     enum: ['buyer', 'seller', 'logistics', 'reviewer', 'arbitrator'],
-                    description: '你在协议中的角色',
+                    description: 'Your role in the protocol',
                 },
                 initial_balance: {
                     type: 'number',
-                    description: '初始模拟余额（测试用，默认 1000 WAZ）',
+                    description: 'Initial mock balance (for testing, default 1000 WAZ)',
                 },
                 region: {
                     type: 'string',
                     enum: ['global', 'singapore', 'china', 'usa', 'malaysia', 'indonesia', 'thailand', 'vietnam', 'taiwan', 'hk'],
-                    description: '账号所在地区（默认 global；影响 referral region cap 与佣金 redirect_region_cap 规则）',
+                    description: 'Account region (default global; affects referral region cap + commission redirect_region_cap rules)',
                 },
             },
             required: ['name', 'role'],
@@ -214,184 +282,133 @@ Roles:
     },
     {
         name: 'webaz_search',
+        // was ~2607 chars, now ~1050 chars
         description: `Search WebAZ marketplace + cross-platform anchor lookup. No auth required.
 
-⚠️ **STRICT MATCH ONLY** — query 永远是精准匹配(等于 title / 等于 external_title / 包含 ≥6 字符 alias)。
-不做 fuzzy LIKE 模糊降级。短查询(如 "钱包" "iphone")很大概率 0 命中,这是设计如此,不是 bug。
-0 命中时,**不要**自己拼短词 retry,也**不要**调别的工具假装搜索;应**引导用户访问 https://webaz.xyz/#discover**
-在搜索框输入关键词浏览(那里有 fuzzy LIKE)。模糊搜索是用户主动行为,不是 agent 代办。
+⚠️ **STRICT MATCH ONLY** (no fuzzy fallback). query matches = exact title OR exact external_title OR alias ≥6 chars contained in user text. Short queries (e.g. "iphone") likely return 0 — **this is by design, NOT a bug**. On 0 results: do NOT retry with shorter terms, do NOT call other tools to fake search. Direct user to https://webaz.xyz/#discover for fuzzy browse (user action, not agent's job).
 
 USE THIS when:
-- 用户给出 **完整商品标题 / SKU / 精准描述**(典型 strict match,如 "AirPods Pro 2 USB-C 港行"), OR
-- 用户给出 **筛选条件**(category / max_price / min_return_days / max_handling_hours / sort), OR
-- 用户粘贴 ANY external product URL/share-text from Taobao / Tmall / JD / PDD / 1688 / Douyin / Xiaohongshu
-  → WebAZ exact-matches against its anchor registry (canonical product fingerprints across
-    platforms). matched_by='none' means truly not indexed — do NOT silently fall back to keyword,
-    and do NOT guess similar products.
-
-⚠️ Do not skip this tool just because user gave you a URL — URL-paste is a first-class mode here,
-NOT a separate browser-fetch capability. Returns structured specs + logistics + after-sales +
-agent_summary (one-line decision hint).
+- User gives **full product title / SKU / precise description** (strict-match candidate), OR
+- User gives **filters** (category / max_price / min_return_days / max_handling_hours / sort), OR
+- User pastes **external URL / share-text** from Taobao / Tmall / JD / PDD / 1688 / Douyin / Xiaohongshu
+  → URL-paste is a first-class mode of THIS tool, NOT a separate browser-fetch. WebAZ exact-matches against its cross-platform anchor registry.
 
-【Keyword search — STRICT】Pass query / category / max_price / min_return_days / max_handling_hours.
-query 命中 = (1) 完全等于 product.title OR (2) 完全等于任一 external_title OR (3) 用户文本包含任一卖家声明 alias_value (≥6 字符)。模糊关键词请引导用户去 PWA #discover。
+【External-link paste】Prefer LLM-parse into \`external_link\` { platform, external_id?, external_title } (title = verbatim text inside 「」). If unparseable, drop raw into \`paste_text\` (server does light regex). Match: L1 external_id exact → L2 external_title exact → else \`matched_by:'none'\`. **No fuzzy fallback, no keyword degradation, no similar-product guessing.** matched_by='none' = tell user honestly "no exact match"; trust premise is precise not "looks similar".
 
-【External-link paste search】When user pastes share text from Taobao/Tmall/JD/Pinduoduo/1688/Douyin/Xiaohongshu
-(e.g. '【淘宝】「Product Name」 https://e.tb.cn/xxx ...'), do:
-1) Prefer your own LLM parsing → pass external_link object with:
-   - platform: 'taobao'|'tmall'|'jd'|'pdd'|'1688'|'douyin'|'xhs'
-   - external_id: canonical product ID (if resolvable from short URL; else omit)
-   - external_title: the title text inside 「」 brackets verbatim
-2) If you can't parse, drop the raw text into paste_text — WebAZ server does light regex parsing (no outbound calls)
-
-Match rules (STRICT, no guessing):
-- Level 1: external_id exact match
-- Level 2: external_title string exact match
-- Neither hit → matched_by: 'none', **NO fuzzy fallback, NO keyword degradation**
-
-IMPORTANT: matched_by='none' is an honest signal — tell the user "no exact match found".
-Do NOT silently fall back to keyword search (that's a separate tool's job).
-Do NOT guess similar products from title impressions.
-WebAZ's trust premise is that match results are TRULY precise, not "looks similar".
-
-Note: paste-link matching hits webaz.xyz production data, not your local webaz.db.
-
-──
-中文：商品搜索（无需登录）。两种模式：关键词搜索 + 粘贴外链精准匹配。外链匹配强制精准（仅 external_id 或 external_title 完全相等命中），不命中返回 matched_by:'none'，不做模糊降级。`,
+Returns: structured specs + logistics + after-sales + agent_summary (one-line decision hint). Paste-link hits webaz.xyz prod data, not local webaz.db.`,
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: '搜索关键词（商品名称或描述）' },
-                category: { type: 'string', description: '商品分类过滤（可选）' },
-                max_price: { type: 'number', description: '最高价格过滤（可选）' },
-                min_return_days: { type: 'number', description: '最少退货天数（可选，如 7 表示只看支持7天退货的商品）' },
-                max_handling_hours: { type: 'number', description: '最长发货时效小时数（可选，如 24 表示只看24h内发货的）' },
-                paste_text: { type: 'string', description: '用户粘贴的分享文本/外链原文（可选，服务端做轻量解析）' },
+                query: { type: 'string', description: 'Search keyword (product name or description)' },
+                category: { type: 'string', description: 'Category filter (optional)' },
+                max_price: { type: 'number', description: 'Max price filter (optional)' },
+                min_return_days: { type: 'number', description: 'Min return days (optional, e.g. 7 = only ≥7-day return)' },
+                max_handling_hours: { type: 'number', description: 'Max handling hours (optional, e.g. 24 = only ≤24h dispatch)' },
+                paste_text: { type: 'string', description: 'Raw paste text / external link (optional; server does light regex parse)' },
                 external_link: {
                     type: 'object',
-                    description: '外链结构化匹配（可选，由 agent 解析得到）',
+                    description: 'Structured external link match (optional, agent-parsed)',
                     properties: {
                         platform: { type: 'string', description: "'taobao'|'tmall'|'jd'|'pdd'|'1688'|'douyin'|'xhs'" },
-                        external_id: { type: 'string', description: '平台商品 canonical ID（可选）' },
-                        external_title: { type: 'string', description: '平台商品标题全文（可选）' },
-                        canonical_url: { type: 'string', description: '规范 URL（可选）' },
+                        external_id: { type: 'string', description: 'Platform product canonical ID (optional)' },
+                        external_title: { type: 'string', description: 'Platform product title verbatim (optional)' },
+                        canonical_url: { type: 'string', description: 'Canonical URL (optional)' },
                     },
                 },
-                limit: { type: 'number', description: '返回数量上限，默认 10，agent 模式可调到 200' },
-                sort: { type: 'string', enum: ['trending', 'newest', 'rating', 'price_asc', 'price_desc', 'random'], description: '排序：trending=综合分（默认），newest=最新，rating=信誉，price_asc/price_desc=价格，random=随机探索' },
-                has_sales: { type: 'string', enum: ['true', 'false'], description: 'true=只看已成交，false=只看新品' },
-                ship_to: { type: 'string', description: '配送目的地（省/市），自动过滤不可派送商品' },
-                seller_id: { type: 'string', description: '只看某卖家的商品' },
-                cursor: { type: 'string', description: '分页 cursor（上次返回的 next_cursor）' },
+                limit: { type: 'number', description: 'Result limit, default 10; agent mode up to 200' },
+                sort: { type: 'string', enum: ['trending', 'newest', 'rating', 'price_asc', 'price_desc', 'random'], description: 'Sort: trending=composite (default) / newest / rating / price_asc / price_desc / random' },
+                has_sales: { type: 'string', enum: ['true', 'false'], description: 'true=only sold; false=only new' },
+                ship_to: { type: 'string', description: 'Ship-to (province/city); auto-filters unshippable' },
+                seller_id: { type: 'string', description: 'Filter to one seller' },
+                cursor: { type: 'string', description: 'Pagination cursor (from previous next_cursor)' },
             },
         },
     },
     {
         name: 'webaz_verify_price',
-        description: `Lock product price + reserve stock window BEFORE webaz_place_order — returns session_token.
-
-USE THIS for EVERY purchase, not just price-sensitive ones. Reasons:
-(1) order price matches displayed (defeats flash-sale / hidden-fee races)
-(2) caller is alerted if price changed between view and order
-(3) protocol only liable for T0 price
-(4) reduces stock-depletion race on hot items (session_token is single-use within 10min)
+        // was ~647 chars, now ~370 chars
+        description: `Lock price + reserve stock BEFORE webaz_place_order — returns \`session_token\` (10-min TTL, single-use, pass to place_order).
 
-Skipping this is allowed but the agent then carries the price/stock-race risk itself. session_token: 10-minute TTL, single-use, pass it to webaz_place_order.
+USE THIS for **EVERY purchase**: (1) defeats flash-sale / hidden-fee race (2) alerts if price drifted (3) protocol only liable for T0 price (4) reduces stock-depletion race on hot items.
 
-──
-中文：下单前锁价 — 10 分钟一次性 session_token；agent 应先调此再调 place_order。`,
+Skipping is allowed but agent then carries price/stock-race risk itself.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '买家的 api_key' },
-                product_id: { type: 'string', description: '商品 ID（从 webaz_search 获得）' },
-                quantity: { type: 'number', description: '购买数量，默认 1' },
+                api_key: { type: 'string', description: "Buyer's api_key" },
+                product_id: { type: 'string', description: 'Product ID (from webaz_search)' },
+                quantity: { type: 'number', description: 'Quantity, default 1' },
             },
             required: ['api_key', 'product_id'],
         },
     },
     {
         name: 'webaz_list_product',
-        description: `⚠️ "list" = PUBLISH (verb), NOT "list out" (noun). Seller-only product catalog publishing & management.
-
-USE THIS when SELLER wants to:
-- publish a NEW product to their catalog, OR
-- update / delist / relist / trash / delete an existing product they own, OR
-- view their OWN listings (action=mine)
+        // was ~1336 chars, now ~650 chars
+        description: `⚠️ **"list" = PUBLISH** (verb), NOT "list out". Seller-only catalog publish + manage.
 
-NOT for browsing the marketplace — for that use webaz_search (anyone, no auth). Requires seller-role api_key. On create, system auto-suggests stake (~15% of price) to secure buyer protection.
+USE THIS when seller wants to publish / update / delist / relist / trash / delete own product, OR view own listings (action=mine). NOT for browsing marketplace — use webaz_search (anyone, no auth). Requires seller api_key. On create: system auto-suggests stake ~15% of price (buyer protection).
 
-Fill fields completely — better agent_summary helps buyer agents make comparison decisions (brand / return / handling / warranty).
-Note: for "exclusive price vs external link" listing, use PWA Web only — link claim needs crowd-verification.
+Fill agent_summary fields completely (brand/return/handling/warranty) — helps buyer agents compare. For "exclusive-price vs external-link" listing → PWA Web only (link claim needs crowd-verify).
 
-Actions:
-- create  list a new product (default; needs title/description/price)
-- mine    list all my products (no product_id needed)
-- update  modify fields (needs product_id; only changed fields)
-- delist  move to warehouse (status: warehouse; needs product_id)
-- relist  re-shelve from warehouse (status: active; needs product_id)
-- trash   move to trash (status: deleted; needs product_id)
-- delete  permanent delete (only trash items with no active orders; needs product_id)
-
-──
-中文：卖家商品目录管理（上架/更新/下架/回收/删除/查询）。Actions: create / mine / update / delist / relist / trash / delete。上架时系统自动建议 15% 价格的质押金。`,
+Actions: create (title/description/price) | mine | update (product_id + changed fields) | delist (→ warehouse) | relist (warehouse → active) | trash (→ deleted) | delete (only trash, no active orders).`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '卖家的 api_key' },
+                api_key: { type: 'string', description: "Seller's api_key" },
                 action: {
                     type: 'string',
                     enum: ['create', 'mine', 'update', 'delist', 'relist', 'trash', 'delete'],
-                    description: '要执行的操作（缺省 = create）',
+                    description: 'Action (default: create)',
                 },
-                product_id: { type: 'string', description: '商品 ID（update / delist / relist / trash / delete 时必填）' },
-                title: { type: 'string', description: '商品名称（create 必填；update 可选）' },
-                description: { type: 'string', description: '商品详细描述（create 必填；update 可选）' },
-                price: { type: 'number', description: '商品价格 WAZ（create 必填；update 可选）' },
-                stock: { type: 'number', description: '库存数量，默认 1' },
-                category: { type: 'string', description: '商品分类（可选）' },
+                product_id: { type: 'string', description: 'Product ID (required for update/delist/relist/trash/delete)' },
+                title: { type: 'string', description: 'Product name (required for create; optional for update)' },
+                description: { type: 'string', description: 'Product description (required for create; optional for update)' },
+                price: { type: 'number', description: 'Price in WAZ (required for create; optional for update)' },
+                stock: { type: 'number', description: 'Stock, default 1' },
+                category: { type: 'string', description: 'Category (optional)' },
                 specs: {
                     type: 'object',
-                    description: '结构化规格键值对，如 {"颜色":"黑色","内存":"16GB","存储":"512GB"}（可选）',
+                    description: 'Structured specs k/v, e.g. {"color":"black","ram":"16GB","storage":"512GB"} (optional)',
                 },
-                brand: { type: 'string', description: '品牌（可选）' },
-                model: { type: 'string', description: '型号（可选）' },
+                brand: { type: 'string', description: 'Brand (optional)' },
+                model: { type: 'string', description: 'Model (optional)' },
                 source_price: {
                     type: 'number',
-                    description: '同款商品的外部参考价（可选，仅作展示，不参与独家价认证——需通过 PWA 完成链接认领）',
+                    description: 'External reference price (optional, display only; exclusive-price auth needs PWA link-claim)',
                 },
-                ship_regions: { type: 'string', description: '发货地区，默认"全国"' },
-                handling_hours: { type: 'number', description: '发货时效（小时），默认 24' },
+                ship_regions: { type: 'string', description: 'Ship region, default "all"' },
+                handling_hours: { type: 'number', description: 'Handling time (hours), default 24' },
                 estimated_days: {
                     type: 'object',
-                    description: '预计送达天数：数字（如 4）或区域映射（如 {"江浙沪":2,"全国":4}）',
+                    description: 'Estimated delivery days: number (e.g. 4) OR region map (e.g. {"east":2,"all":4})',
                 },
-                fragile: { type: 'boolean', description: '是否易碎品，默认 false' },
-                return_days: { type: 'number', description: '支持退货天数，默认 7（填 0 表示不支持退货）' },
-                return_condition: { type: 'string', description: '退货条件说明（可选）' },
-                warranty_days: { type: 'number', description: '质保天数，默认 0' },
+                fragile: { type: 'boolean', description: 'Fragile flag, default false' },
+                return_days: { type: 'number', description: 'Return days, default 7 (0 = no returns)' },
+                return_condition: { type: 'string', description: 'Return conditions text (optional)' },
+                warranty_days: { type: 'number', description: 'Warranty days, default 0' },
                 // S2 库存预警
                 low_stock_threshold: {
                     type: 'number',
-                    description: '【S2】库存预警阈值（≤ 此数时通知卖家；填 0 = 关闭预警）',
+                    description: '[S2] Low-stock alert threshold (notify seller when ≤; 0 = disabled)',
                 },
                 auto_delist_on_zero: {
                     type: 'boolean',
-                    description: '【S2】库存归零时自动下架到仓库（防超卖）',
+                    description: '[S2] Auto-delist to warehouse when stock=0 (anti-oversell)',
                 },
                 // S3 跨境上架多语言
                 i18n_titles: {
                     type: 'object',
-                    description: '【S3】多语言标题，key 是语言码（en/ja/ko/fr/de/es/pt/ru/ar），value 是该语言标题（≤500 字）。zh 用 title 字段，无需填这里。例: {"en":"Wireless Earbuds","ja":"ワイヤレスイヤホン"}',
+                    description: '[S3] Multilingual titles, keys = en/ja/ko/fr/de/es/pt/ru/ar, values ≤500 chars. zh uses title field. E.g. {"en":"Wireless Earbuds","ja":"ワイヤレスイヤホン"}',
                 },
                 i18n_descs: {
                     type: 'object',
-                    description: '【S3】多语言描述，结构同 i18n_titles',
+                    description: '[S3] Multilingual descs, same structure as i18n_titles',
                 },
                 // S4 商品溯源（origin_claims）— 协议级可挑战
                 origin_claims: {
                     type: 'object',
-                    description: '【S4】商品溯源声明（可挑战）。例: {"made_in":"日本京都","material":"100% 棉 GOTS 认证","certs":[{"name":"GOTS","sha256":"<64 位 hex>"}]}。整体 JSON ≤ 4KB；任一证书 sha256 必须是 64 位 hex。任何买家可发起 claim 验证。',
+                    description: '[S4] Product-origin claims (challengeable). E.g. {"made_in":"Kyoto JP","material":"100% cotton GOTS-cert","certs":[{"name":"GOTS","sha256":"<64-hex>"}]}. Total JSON ≤4KB; any cert sha256 must be 64-hex. Any buyer can challenge.',
                 },
             },
             required: ['api_key'],
@@ -399,49 +416,46 @@ Actions:
     },
     {
         name: 'webaz_place_order',
-        description: `Buyer places an order. Requires buyer-role api_key.
+        // was ~1117 chars, now ~580 chars
+        description: `Buyer places order. Buyer api_key required. Funds auto-enter protocol escrow.
 
-On order, funds auto-enter protocol escrow. Order deadlines (all stored as absolute ISO timestamps in the response):
-- accept_deadline:   T+48h  (i.e., seller has 24h after the buyer's payment which is itself T+24h)
-- ship_deadline:     T+120h (72h after accept)
-- pickup_deadline:   T+168h (48h after ship)
-- delivery_deadline: T+336h (7d after pickup)
-- confirm_deadline:  T+408h (72h after delivery)
+Order deadlines (absolute ISO timestamps in response):
+- accept    T+48h  | ship  T+120h (72h after accept)
+- pickup    T+168h (48h after ship) | delivery T+336h (7d after pickup)
+- confirm   T+408h (72h after delivery)
 
-Missing any deadline auto-judges fault against the responsible party and triggers compensation per protocol economics.
+Missing any → auto-judge fault against responsible party + compensation per protocol.
 
-【B1 Cross-border tax】For cross-border orders, server auto-estimates import duty (seller's est_import_duty_pct × price) and returns it in the response.
-【B2 Privacy mode】Pass anonymous_recipient=true → system generates a PR-XXXXX alias instead of real name on shipping label.
-【B5 Donation】Optional donation_pct (0 / 0.5% / 1% / 2% / 5%) — sends that fraction of order amount to charity_fund.
-
-──
-中文：买家下单 — 资金进托管。订单 6 个 deadline 都是绝对时间戳，每个相对前一步的允许时长：accept 24h→ship 72h→pickup 48h→deliver 7d→confirm 72h。任何一个超时由对应责任方违约。可选：跨境关税估算 / 匿名收件 / 慈善捐赠。`,
+Options:
+- **B1 cross-border tax**: server auto-estimates duty (seller's est_import_duty_pct × price)
+- **B2 privacy**: \`anonymous_recipient=true\` → PR-XXXXX alias on shipping label
+- **B5 donation**: \`donation_pct\` 0 / 0.5 / 1 / 2 / 5% → charity_fund`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '买家的 api_key' },
-                product_id: { type: 'string', description: '要购买的商品 ID（从 webaz_search 获得）' },
-                quantity: { type: 'number', description: '购买数量，默认 1' },
-                shipping_address: { type: 'string', description: '收货地址' },
-                notes: { type: 'string', description: '给卖家的备注（可选）' },
+                api_key: { type: 'string', description: "Buyer's api_key" },
+                product_id: { type: 'string', description: 'Product ID to buy (from webaz_search)' },
+                quantity: { type: 'number', description: 'Quantity, default 1' },
+                shipping_address: { type: 'string', description: 'Shipping address' },
+                notes: { type: 'string', description: 'Note to seller (optional)' },
                 session_token: {
                     type: 'string',
-                    description: '价格锁定 token（推荐）：由 webaz_verify_price 返回，确保下单价格与展示价格一致',
+                    description: 'Price-lock session_token (recommended): from webaz_verify_price; guarantees order price = displayed price',
                 },
                 promoter_api_key: {
                     type: 'string',
-                    description: '推荐人的 api_key（可选）。⚠️ 仅记 L1（直接推荐人，70% commission）；L2/L3 无法经 MCP 推断，会按 region 规则 redirect（singapore 等高 max_levels → charity chain_gap；global max_levels=1 → global_fund region cap）。完整 7:2:1 三级链需买家经 webaz_share_link 生成的 ?ref= URL 浏览器点击（建 product_share_attribution）。',
+                    description: "Referrer api_key (optional). ⚠️ Only L1 recorded (direct referrer, 70% commission); L2/L3 can't be inferred via MCP, redirects per region rule (singapore-like high max_levels → charity chain_gap; global max_levels=1 → global_fund region cap). Full 7:2:1 three-tier chain requires buyer clicking ?ref= URL from webaz_share_link (creates product_share_attribution).",
                 },
                 // B2 隐私购物
                 anonymous_recipient: {
                     type: 'boolean',
-                    description: '【B2】匿名收件：系统生成 PR-XXXXX 代号代替真实姓名（卖家面单只见代号 + 地址）',
+                    description: '[B2] Anonymous recipient: system generates PR-XXXXX alias instead of real name (seller label shows alias + address only)',
                 },
                 // B5 公益捐赠（按订单总额百分比，定额选项防机器人滥用）
                 donation_pct: {
                     type: 'number',
                     enum: [0, 0.005, 0.01, 0.02, 0.05],
-                    description: '【B5】随单捐赠占订单金额的比例（0 / 0.5% / 1% / 2% / 5%）。捐赠金额另行计算并入 charity_fund，订单完成后落账。',
+                    description: '[B5] Per-order donation pct (0 / 0.5 / 1 / 2 / 5). Computed separately + into charity_fund, posted on order complete.',
                 },
             },
             required: ['api_key', 'product_id', 'shipping_address'],
@@ -449,41 +463,28 @@ Missing any deadline auto-judges fault against the responsible party and trigger
     },
     {
         name: 'webaz_update_order',
-        description: `STATUS TRANSITIONS on an order (accept / ship / pickup / deliver / confirm / dispute) — NOT for editing order content (price/quantity/address are immutable after creation).
+        // was ~927 chars, now ~430 chars
+        description: `STATUS TRANSITIONS on an order — NOT for editing order content (price/qty/address immutable after creation). Each role can only perform their own actions.
 
-USE THIS to advance an order through its lifecycle. Each role can only perform their own actions (see action list).
+- **Seller**: accept (24h after payment) | ship (needs tracking, within handling time)
+- **Logistics**: pickup (48h after ship) | transit | deliver (needs proof description)
+- **Buyer**: confirm (→ fund settlement) | dispute (needs reason; freezes funds → arbitration)
 
-Seller actions:
-- accept:  accept order (within 24h of payment)
-- ship:    confirm dispatch (needs tracking number, within promised handling time)
-
-Logistics actions:
-- pickup:  confirm parcel pickup (within 48h of ship)
-- transit: update to in-transit
-- deliver: confirm delivery (needs delivery proof description)
-
-Buyer actions:
-- confirm: confirm receipt → triggers fund settlement
-- dispute: raise dispute (needs reason; freezes funds pending arbitration)
-
-If a deadline is missed, protocol auto-marks that party as in default.
-
-──
-中文：更新订单状态 — 角色专属 action（卖家 accept/ship · 物流 pickup/transit/deliver · 买家 confirm/dispute）。截止超时自动判违约。`,
+Missing deadline → protocol auto-marks party in default.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '操作者的 api_key' },
-                order_id: { type: 'string', description: '订单 ID' },
+                api_key: { type: 'string', description: "Operator's api_key" },
+                order_id: { type: 'string', description: 'Order ID' },
                 action: {
                     type: 'string',
                     enum: ['accept', 'ship', 'pickup', 'transit', 'deliver', 'confirm', 'dispute'],
-                    description: '要执行的操作',
+                    description: 'Action to execute',
                 },
-                notes: { type: 'string', description: '操作说明（如物流单号、争议原因等）' },
+                notes: { type: 'string', description: 'Action note (e.g. tracking number, dispute reason)' },
                 evidence_description: {
                     type: 'string',
-                    description: '证据描述（发货/揽收/投递时建议提供，争议时必须提供）',
+                    description: 'Evidence description (recommended for ship/pickup/deliver; required for dispute)',
                 },
             },
             required: ['api_key', 'order_id', 'action'],
@@ -491,43 +492,37 @@ If a deadline is missed, protocol auto-marks that party as in default.
     },
     {
         name: 'webaz_get_status',
-        description: `Query order status, full history, and current responsible party.
-Requires api_key of an order participant (buyer / seller / logistics may all query).
-Returns: current status, status history (who did what when), next responsible actor, deadline.
-
-──
-中文：查订单状态 + 历史 + 当前责任方 + 截止时间。任一参与方可查。`,
+        // was ~286 chars, now ~200 chars
+        description: `Query order status + full history + current responsible party + deadline. Requires api_key of order participant (buyer/seller/logistics all OK). Returns: status / status_history (who did what when) / next_actor / deadline.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '查询者的 api_key' },
-                order_id: { type: 'string', description: '订单 ID' },
+                api_key: { type: 'string', description: "Querier's api_key" },
+                order_id: { type: 'string', description: 'Order ID' },
             },
             required: ['api_key', 'order_id'],
         },
     },
     {
         name: 'webaz_wallet',
-        description: `Wallet READ-ONLY query (balance + earnings stats + deposit/withdrawal/income history).
+        // was ~788 chars, now ~440 chars
+        description: `Wallet **READ-ONLY** query (balance / earnings / deposit/withdrawal/income history).
 
-⚠️ Iron-Rule (must read before use): actual withdrawals / deposits / whitelist management require Passkey + email OTP via PWA Web only. This tool CANNOT move money — only query state. If user asks "send/withdraw/deposit WAZ", do NOT promise it via MCP; instead direct them to PWA Web.
+⚠️ **Iron-Rule**: actual withdrawals / deposits / whitelist mgmt need **PWA Web + Passkey + email OTP**. This tool CANNOT move money — only query. User asks "send/withdraw/deposit WAZ"? Do NOT promise via MCP — direct to PWA Web.
 
 Actions:
-- view         available balance + staked + in-escrow + total earnings + reputation tier (default)
-- deposits     last 10 on-chain deposit records (tx_hash / amount / block_number)
-- withdrawals  last 10 withdrawal requests (with status / tx_hash)
-- income       income breakdown: referral L1/L2/L3 + binary PV matching + sales net
-
-──
-中文：钱包查询（余额/收益/充提历史）。仅查询用，实际充提需 PWA Web + Passkey + 邮件 OTP，agent 不可绕过。`,
+- view (default) — balance + staked + in-escrow + earnings + reputation tier
+- deposits — last 10 on-chain (tx_hash / amount / block)
+- withdrawals — last 10 (status / tx_hash)
+- income — breakdown: referral L1/L2/L3 + binary PV matching + sales net`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key' },
+                api_key: { type: 'string', description: 'Your api_key' },
                 action: {
                     type: 'string',
                     enum: ['view', 'deposits', 'withdrawals', 'income'],
-                    description: '操作类型（缺省 = view）',
+                    description: 'Action type (default: view)',
                 },
             },
             required: ['api_key'],
@@ -535,255 +530,185 @@ Actions:
     },
     {
         name: 'webaz_notifications',
-        description: `Query user notifications (L2-6 notification system).
-Agents should poll this periodically to check for pending order events.
-Every status change (new order / ship / dispute / etc.) notifies relevant participants.
-
-⚠️ Scope: 此工具只查 L2-6 system notifications。不含 / Does NOT include:
-  - chat unread(私信)→ 用 webaz_chat action=list
-  - announcements unread(管理员公告)→ 暂无 MCP 工具(PWA #me/announcements)
-  - feedback replies unread(用户反馈回复)→ 暂无 MCP 工具
-PWA 顶部红点是 4 项合计;此工具仅返回第 1 项 → 数字可能 < PWA 显示。
-PWA top badge aggregates all 4; this returns only 1 → may be < PWA shows.
+        // was ~608 chars, now ~330 chars
+        description: `Query user notifications (L2-6 system). Agents should poll periodically for pending order events (new order / ship / dispute → notifies relevant participants).
 
-──
-中文：查通知 — agent 定期调用检查待处理事件（新订单/发货/争议等会通知所有相关方）。`,
+⚠️ **Scope**: only L2-6 system notifications. Does NOT include: chat unread (use webaz_chat list) | announcements | feedback replies. PWA top badge aggregates 4; this returns 1 → may be **<** PWA shows.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key' },
-                unread: { type: 'boolean', description: '只返回未读通知（默认 false）' },
-                mark_read: { type: 'boolean', description: '调用后自动标为已读（默认 false）' },
+                api_key: { type: 'string', description: 'Your api_key' },
+                unread: { type: 'boolean', description: 'Return only unread (default false)' },
+                mark_read: { type: 'boolean', description: 'Auto-mark read after call (default false)' },
             },
             required: ['api_key'],
         },
     },
     {
         name: 'webaz_dispute',
-        description: `Manage ORDER-DELIVERY dispute lifecycle (L3 dispute system, central arbitrator).
-
-⚠️ Different from webaz_claim_verify:
-- webaz_dispute = order delivery problem (didn't arrive / wrong / damaged in transit / seller fraud) → central arbitrator + 120h ruling
-- webaz_claim_verify = challenge a product CLAIM (brand / spec / ship time) → 3 crowd verifiers vote
-Pick based on the actual problem: delivery/receiving = dispute; marketing-claim accuracy = claim_verify.
-
-When buyer claims item-not-as-described / damaged / seller fraud, first raise dispute via webaz_update_order action=dispute,
-then use this tool for follow-ups.
-
-Protocol guarantees (no human intervention):
-- Respondent has 48h to submit rebuttal evidence, else protocol auto-judges in initiator's favor
-- Arbitrator has 120h to issue ruling, else protocol defaults to refund-buyer
-- Once executed, ruling fund movement is instant and irreversible
+        // was ~2277 chars, now ~900 chars
+        description: `Manage ORDER-DELIVERY dispute lifecycle (L3, central arbitrator). For order delivery problems (not arrived / wrong / damaged / seller fraud). **NOT for challenging product marketing claims → use webaz_claim_verify.** Quick rule: did buyer receive item? Yes + item-itself issue → claim_verify. No / damaged-transit → dispute. Initial raise via webaz_update_order action=dispute, then this tool for follow-ups.
 
 Actions:
-- view:         view dispute details (any participant)
-- list_open:    list all pending disputes (arbitrators only)
-- respond:      respondent submits rebuttal evidence (before 48h deadline)
-- add_evidence: any participant (incl. logistics) submits supplementary evidence (Wave 3)
-- arbitrate:    arbitrator issues ruling + executes fund disposition (must be assigned arbitrator)
+- view          dispute details (any participant)
+- list_open     pending disputes (arbitrators only)
+- respond       respondent rebuttal (before 48h deadline)
+- add_evidence  any participant supplements
+- arbitrate     ruling + fund disposition (assigned arbitrator only)
 
-Ruling options (when arbitrate):
-- refund_buyer:    full refund to buyer + partial stake forfeit from seller
-- release_seller:  release funds to seller (seller wins)
-- partial_refund:  partial refund (needs refund_amount); if third-party fault, set liable_party (user_id) → seller settled full, compensation deducted from liable party
-- liability_split: distributed liability (Wave 3) — needs liability_parties: [{user_id, amount}] for proportional stake deductions
+Ruling options: refund_buyer | release_seller | partial_refund (needs refund_amount; optional liable_party → 3rd-party fault, seller settled full + deducted from liable) | liability_split (needs liability_parties[]={user_id,amount}).
 
-─────────────────────
-⚠️ Iron-Rule boundary (spec §4): arbitrate is a protocol iron-rule node requiring arbitrator to complete Passkey re-confirmation via PWA Web UI.
-Direct agent calls return 412 HUMAN_PRESENCE_REQUIRED — DO NOT retry; instead, guide the user to the browser.
-view / list_open / respond / add_evidence can be agent-proxied; only arbitrate needs human.
+Protocol auto-judges (no human): respondent silent 48h → favor initiator; arbitrator silent 120h → refund_buyer. Executed rulings are instant + irreversible.
 
-──
-中文：管理争议（L3）。Actions: view / list_open / respond / add_evidence (agent 可代) · arbitrate (需 PWA + Passkey 人工)。被诉方 48h 反驳，仲裁员 120h 裁定，超时自动判。`,
+⚠️ **Iron-Rule (spec §4)**: \`arbitrate\` needs PWA + Passkey real-human re-confirm. Direct agent call returns 412 HUMAN_PRESENCE_REQUIRED — **do NOT retry**, guide user to browser. view / list_open / respond / add_evidence are agent-proxyable.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '操作者的 api_key' },
+                api_key: { type: 'string', description: "Operator's api_key" },
                 action: {
                     type: 'string',
                     enum: ['view', 'list_open', 'respond', 'add_evidence', 'arbitrate'],
-                    description: '要执行的操作',
+                    description: 'Action to execute',
                 },
-                dispute_id: { type: 'string', description: '争议 ID（respond/add_evidence/arbitrate 时必填，view 时与 order_id 二选一）' },
-                order_id: { type: 'string', description: '订单 ID（view 时可替代 dispute_id）' },
-                notes: { type: 'string', description: '回应说明 / 反驳理由（respond 时填写）' },
-                evidence_description: { type: 'string', description: '证据描述（respond/add_evidence 时填写）' },
+                dispute_id: { type: 'string', description: 'Dispute ID (required for respond/add_evidence/arbitrate; for view, dispute_id OR order_id)' },
+                order_id: { type: 'string', description: 'Order ID (alternative to dispute_id for view)' },
+                notes: { type: 'string', description: 'Response / rebuttal note (for respond)' },
+                evidence_description: { type: 'string', description: 'Evidence description (for respond/add_evidence)' },
                 ruling: {
                     type: 'string',
                     enum: ['refund_buyer', 'release_seller', 'partial_refund', 'liability_split'],
-                    description: '裁定结果（arbitrate 时必填）',
+                    description: 'Ruling (required for arbitrate)',
                 },
-                refund_amount: { type: 'number', description: '部分退款金额，仅 ruling=partial_refund 时使用' },
-                liable_party: { type: 'string', description: '第三方责任方 user_id（partial_refund 时可选）：指定后赔偿金从该方扣除，卖家全额结算' },
+                refund_amount: { type: 'number', description: 'Partial refund amount (only when ruling=partial_refund)' },
+                liable_party: { type: 'string', description: '3rd-party liable user_id (optional for partial_refund): refund deducted from this party, seller settled in full' },
                 liability_parties: {
                     type: 'array',
-                    description: '责任分配数组（liability_split 时必填），每项 { user_id: string, amount: number }',
+                    description: 'Liability allocation array (required for liability_split); each item { user_id, amount }',
                     items: {
                         type: 'object',
                         properties: {
-                            user_id: { type: 'string', description: '责任方 user_id' },
-                            amount: { type: 'number', description: '该责任方需承担的金额（WAZ）' },
+                            user_id: { type: 'string', description: 'Liable user_id' },
+                            amount: { type: 'number', description: 'Amount this party owes (WAZ)' },
                         },
                         required: ['user_id', 'amount'],
                     },
                 },
-                ruling_reason: { type: 'string', description: '裁定理由（arbitrate 时必填，将永久记录在链上）' },
+                ruling_reason: { type: 'string', description: 'Ruling reason (required for arbitrate; permanently recorded on-chain)' },
             },
             required: ['api_key', 'action'],
         },
     },
     {
         name: 'webaz_claim_verify',
-        description: `Crowd-sourced PRODUCT-CLAIM verification — challenge seller's marketing claims (brand / spec / ship time / authenticity); 3 eligible verifiers reach consensus by vote.
-
-⚠️ Different from webaz_dispute:
-- webaz_claim_verify = challenge a CLAIM about the product itself ("seller said 24h ship but didn't" / "said brand new but used")
-- webaz_dispute = order-delivery problem (didn't arrive / arrived broken / wrong item) → central arbitrator
-If unsure: did the buyer GET the item? If yes + problem with item itself → claim_verify. If no/damaged in transit → dispute.
+        // was ~2917 chars, now ~1100 chars
+        description: `Crowd-sourced PRODUCT-CLAIM verification — challenge seller's marketing claims (brand / spec / ship time / authenticity). 3 eligible verifiers vote → consensus.
 
-When to use:
-- Buyer:   suspects a seller's product claim (e.g. "brand new sealed", "ships within 24h") → wants decentralized verification
-- Seller:  defends against an opened verification by submitting counter-evidence → extends task by 24h
-- Verifier: browses open tasks, votes on eligible ones (pass/fail/no_fault/abstain), settles on 3rd vote
+**vs webaz_dispute**: dispute = delivery problem (not arrived / damaged / wrong item, central arbitrator). claim_verify = item-itself / claim-accuracy ("said brand new but used", "said 24h ship but didn't"). Quick test: did buyer receive? Yes + item issue → claim_verify; No / transit damage → dispute.
 
 Actions:
 [Buyer]
-- create   open a verification on your own order's claim (locks 10 WAZ stake; order must be paid/delivered, NOT completed; settles when 3 votes collected)
-- view     task details (visible to participants + voters + eligible verifiers)
-- mine     all my tasks (buyer + seller + verifier perspectives)
-
+- create  open verification (locks 10 WAZ; order must be paid/delivered, NOT completed; settles on 3rd vote)
+- view    task details (visible to participants + voters + eligible verifiers)
+- mine    all my tasks (buyer/seller/verifier perspectives)
 [Seller]
-- submit_seller_evidence  submit rebuttal → +24h extension, task stays open
-
-[Verifier — gated by 7-condition eligibility, NOT just read-only]
-- available             list open tasks I can take (REQUIRES eligibility: age≥60d / email verified / ≥20 completed orders / 0 arbitration losses / never suspended / wallet ≥200 WAZ / reputation ≥110)
-- vote                  vote on a task (pass / fail / no_fault / abstain)
-                        pass     = seller's claim is true / product OK
-                        fail     = seller's claim is false / product mismatch
-                        no_fault = neither party clearly at fault (dispute has merit but inconclusive)
-                        abstain  = "not my expertise, skipping" — not counted in 3-vote consensus, doesn't affect accuracy (V3 right-to-decline)
-
+- submit_seller_evidence  rebuttal → +24h extension
+[Verifier]
+- available  list takeable tasks (eligibility: age≥60d / email verified / ≥20 completed orders / 0 arbitration losses / never suspended / wallet ≥200 WAZ / reputation ≥110)
+- vote       pass (claim true) | fail (claim false) | no_fault (inconclusive) | abstain (not my expertise — not counted, no accuracy impact)
 [Become Verifier]
-- eligibility           check my qualification status (reputation signals)
-- verifier_status       my quota / tier / stake
-- apply                 apply to verifier whitelist (needs reputation + stake lock)
-- withdraw_application  withdraw application, refund stake
-- appeal                appeal a suspension (only when suspended)
-
-─────────────────────
-⚠️ Iron-Rule boundary (spec §4): vote is a protocol iron-rule node requiring verifier to complete Passkey re-confirmation via PWA Web UI.
-Direct agent calls to vote return 412 HUMAN_PRESENCE_REQUIRED — DO NOT retry; instead, guide the user to the browser.
-Other actions (create / view / mine / available / eligibility / apply / appeal etc.) can be agent-proxied; only vote needs human.
+- eligibility / verifier_status / apply (needs stake) / withdraw_application / appeal (only when suspended)
 
-──
-中文：众包索赔验证 — 3 verifier 共识投票判定。买家创建、卖家反证、verifier 投票。仅 vote 需 PWA + Passkey 人工，其他 actions agent 可代。`,
+⚠️ **Iron-Rule (spec §4)**: \`vote\` needs PWA + Passkey real-human re-confirm. Direct agent call returns 412 HUMAN_PRESENCE_REQUIRED — **do NOT retry**, guide user to browser. All other actions agent-proxyable.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key' },
+                api_key: { type: 'string', description: 'Your api_key' },
                 action: {
                     type: 'string',
                     enum: ['create', 'view', 'mine', 'submit_seller_evidence', 'available', 'vote', 'eligibility', 'verifier_status', 'apply', 'withdraw_application', 'appeal'],
-                    description: '要执行的操作',
+                    description: 'Action to execute',
                 },
                 // create
-                order_id: { type: 'string', description: '订单 ID（create 时必填）。订单状态须在 paid/delivered（completed 终态不可发起）' },
+                order_id: { type: 'string', description: 'Order ID (required for create). Order status must be paid/delivered (cannot create on completed)' },
                 claim_target: {
                     type: 'string',
                     enum: ['price', 'commission', 'protection', 'return', 'warranty', 'handling', 'other'],
-                    description: '声明对象（create 时必填）。7 类: price（价格争议）/ commission（佣金）/ protection（买家保护）/ return（退货）/ warranty（保修）/ handling（履约时效）/ other',
+                    description: 'Claim target (required for create). 7 types: price / commission / protection / return / warranty / handling / other',
                 },
-                claim_text: { type: 'string', description: '声明文本 6-500 字（create 时必填）。create 会锁定 10 WAZ 防 spam（无责败诉退回）' },
-                evidence_uri: { type: 'string', description: '证据 URI（create/vote/submit_seller_evidence 可选；buyer 自带 / verifier 附证据 / seller 反驳证据）' },
+                claim_text: { type: 'string', description: 'Claim text 6-500 chars (required for create). Locks 10 WAZ anti-spam (refunded if no fault)' },
+                evidence_uri: { type: 'string', description: 'Evidence URI (optional for create/vote/submit_seller_evidence; buyer/verifier/seller respective evidence)' },
                 // view / vote / submit_seller_evidence
-                task_id: { type: 'string', description: '任务 ID（view / vote / submit_seller_evidence 时必填）' },
+                task_id: { type: 'string', description: 'Task ID (required for view/vote/submit_seller_evidence)' },
                 // vote
-                vote: { type: 'string', enum: ['pass', 'fail', 'no_fault', 'abstain'], description: 'vote 时必填；abstain = 不熟悉弃投（V3）' },
-                note: { type: 'string', description: '投票说明（vote 可选，≤500 字）' },
+                vote: { type: 'string', enum: ['pass', 'fail', 'no_fault', 'abstain'], description: 'Required for vote; abstain = not my expertise (V3 right-to-decline)' },
+                note: { type: 'string', description: 'Vote note (optional for vote, ≤500 chars)' },
                 // appeal
-                reason: { type: 'string', description: '申诉理由（appeal 时必填，≤500 字）' },
+                reason: { type: 'string', description: 'Appeal reason (required for appeal, ≤500 chars)' },
             },
             required: ['api_key', 'action'],
         },
     },
     {
         name: 'webaz_skill',
-        description: `L4-4 Skill marketplace — sellers publish reusable seller-side BEHAVIOUR configs; buyer Agents subscribe with one click.
-
-USE THIS when:
-- seller wants to install reusable selling behavior (auto-accept / catalog-sync / price-haggling / etc.), OR
-- buyer agent wants to subscribe to seller's behaviour to enable priority discovery / auto-deal flows.
+        // was ~2251 chars, now ~920 chars
+        description: `L4-4 Skill marketplace — sellers publish reusable seller-side BEHAVIOUR configs; buyer Agents subscribe one-click.
 
-NOT a product search — for "find me X" use webaz_search.
-NOT a KNOWLEDGE-content marketplace — for buying/selling templates / prompts / guides / checklists use webaz_skill_market (totally separate system, independent revenue flow).
+**NOT** a product search (use webaz_search). **NOT** a knowledge/content market (use webaz_skill_market — totally separate, independent revenue flow).
 
-⚠️ Important — Skill is NOT executable code distribution. There are exactly 5 typed Skill kinds (below), each accepts only **structured config parameters** (numbers / enums / amounts). There is NO path for an Agent to download and run arbitrary third-party code via this marketplace. Subscribing = setting a flag + data binding, not installing a plugin. (Common Web2 "plugin marketplace" risk model does NOT apply here.)
+⚠️ **Skill ≠ executable code distribution**. 5 typed kinds only, each accepts **structured config params** (numbers/enums/amounts). NO path for Agent to download/run arbitrary 3rd-party code. Subscribing = flag + data binding, NOT plugin install. Web2 "plugin marketplace" risk model does NOT apply.
 
-Skill is WebAZ's cold-start mechanism: existing Amazon/Shopify sellers integrate with zero cost,
-buyer agents subscribe and auto-discover those sellers' products with priority; on sale, the Skill publisher earns referral commission.
+Cold-start mechanism: Amazon/Shopify sellers integrate zero-cost; buyer agents auto-discover subscribed sellers with priority; publisher earns referral commission on sale.
 
-Skill types (typed, NOT free-form code):
-- catalog_sync      sync external store (Amazon/Shopify/custom) into WebAZ search → subscribers see priority
-- auto_accept       auto-accept incoming orders, no wait (config: min_amount, max_amount, max_daily_orders)
-- price_negotiation allow Agent-side haggling within limits (config: max_discount_pct, min_quantity)
-- quality_guarantee extra stake for issue compensation (config: guarantee_amount, coverage_days)
-- instant_ship      guarantee 24h dispatch (config: ship_within_hours)
+Skill types (typed, not free-form):
+- catalog_sync     sync external store → subscribers see priority
+- auto_accept      auto-accept orders (config: min/max_amount, max_daily_orders)
+- price_negotiation  agent-side haggling (config: max_discount_pct, min_quantity)
+- quality_guarantee  extra stake compensation (config: guarantee_amount, coverage_days)
+- instant_ship     guarantee 24h dispatch (config: ship_within_hours)
 
-Actions:
-- list        browse Skill marketplace (no auth)
-- publish     publish new Skill (sellers only)
-- subscribe   subscribe to a Skill (buyer perks)
-- unsubscribe cancel subscription
-- my_skills   my published Skills (seller view)
-- my_subs     my subscribed Skills (buyer view)
-
-──
-中文：Skill 市场 — 卖家发布 agent 能力插件（catalog_sync / auto_accept / price_negotiation / quality_guarantee / instant_ship），买家 agent 订阅。Actions: list / publish / subscribe / unsubscribe / my_skills / my_subs。`,
+Actions: list (no auth) | publish (seller) | subscribe / unsubscribe (buyer) | my_skills | my_subs.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key（list 时可省略）' },
+                api_key: { type: 'string', description: 'Your api_key (omit for list)' },
                 action: {
                     type: 'string',
                     enum: ['list', 'publish', 'subscribe', 'unsubscribe', 'my_skills', 'my_subs'],
-                    description: '要执行的操作',
+                    description: 'Action to execute',
                 },
                 // list 过滤参数
                 skill_type: {
                     type: 'string',
                     enum: ['catalog_sync', 'auto_accept', 'price_negotiation', 'quality_guarantee', 'instant_ship'],
-                    description: '过滤 Skill 类型（list 时可选）',
+                    description: 'Filter Skill type (optional for list)',
                 },
-                query: { type: 'string', description: '关键词搜索（list 时可选）' },
+                query: { type: 'string', description: 'Keyword search (optional for list)' },
                 // publish 参数
-                name: { type: 'string', description: 'Skill 名称（publish 时必填）' },
-                description: { type: 'string', description: 'Skill 详细描述（publish 时必填）' },
-                category: { type: 'string', description: '分类（publish 时可选）' },
+                name: { type: 'string', description: 'Skill name (required for publish)' },
+                description: { type: 'string', description: 'Skill description (required for publish)' },
+                category: { type: 'string', description: 'Category (optional for publish)' },
                 config: {
                     type: 'object',
-                    description: 'Skill 配置（publish 时可选，如 auto_accept 需填 max_daily_orders）',
+                    description: 'Skill config (optional for publish; e.g. auto_accept needs max_daily_orders)',
                 },
                 // subscribe 参数
-                skill_id: { type: 'string', description: 'Skill ID（subscribe/unsubscribe 时必填）' },
+                skill_id: { type: 'string', description: 'Skill ID (required for subscribe/unsubscribe)' },
             },
             required: ['action'],
         },
     },
     {
         name: 'webaz_mykey',
-        description: `Account RECOVERY check — confirm account existence by handle + permanent_code when user has lost their api_key but still remembers handle + 6-char recovery code from registration. Returns redacted api_key hint only — full api_key disclosure requires PWA + Passkey verification (Iron-Rule).
+        // was ~909 chars, now ~480 chars
+        description: `Account RECOVERY check — confirm account existence by handle + 6-char permanent_code (from registration). Returns redacted api_key_hint only.
 
-USE THIS ONLY when user has lost api_key and provides handle + permanent_code. NOT for "show me my api_key" (you already have it if you're authenticated). NOT for looking up other users (use webaz_profile).
+⚠️ **Iron-Rule**: full api_key disclosure requires **PWA + Passkey** verification — this MCP tool only returns hint + PWA URL, never full key.
 
-Rate-limited: 5 attempts per handle per hour. Excessive failures lock the handle for 1 hour.
+USE THIS ONLY when user lost api_key + has handle + permanent_code. NOT for "show my api_key" (use the one you have). NOT for looking up others (use webaz_profile).
 
-Returns:
-- found: boolean
-- api_key_hint (e.g. "key_7d3d***faa7b") — confirms which account, never the full key
-- full_api_key_recovery — instructions to use PWA for the real recovery
+Rate-limited: 5/handle/hour; excessive → 1h lock.
 
-──
-中文：handle + permanent_code 双因素确认账户存在，仅返回 redact 过的 api_key_hint。完整 api_key 必须经 PWA + Passkey 二次验证（Iron-Rule）。同 handle 每小时最多 5 次。`,
+Returns: found / api_key_hint (e.g. "key_7d3d***faa7b") / full_api_key_recovery URL.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -795,44 +720,36 @@ Returns:
     },
     {
         name: 'webaz_profile',
-        description: `View your own profile / manage roles, AND view any user's public profile + content streams (个人主页内容流).
+        // was ~1076 chars, now ~570 chars
+        description: `View own profile / manage roles, AND view any user's public profile + content streams.
 
-USE THIS when user wants info about a SPECIFIC PERSON (by usr_xxx / permanent code / @handle / name),
-OR wants to see someone's listings / notes / activity stream. NOT for product keyword search — use webaz_search.
+USE THIS for info about a SPECIFIC PERSON (by usr_xxx / permanent code / @handle / name), OR to see someone's listings / notes / activity stream. NOT for product keyword search — use webaz_search.
 
 Self actions (need api_key):
-- view        show your profile & wallet & api_key hint
-- add_role    add a new role
-- switch_role switch active role (one account can hold multiple roles)
+- view (profile + wallet + api_key hint) | add_role | switch_role
 
 Public-profile actions:
-- view_user   another user's public profile (user_id = usr_xxx / permanent_code / @handle; needs api_key)
-- feed        a user's content stream (user_id + feed). feed options:
-              secondhand | auctions | reviews | products | shares | reputation | pv | liked
-              (secondhand/auctions/reviews/products/shares/reputation are public;
-               pv needs api_key; liked is owner-only and needs your own api_key)
-
-──
-中文：看自己资料/管角色，也能看他人公开主页 + 内容流（二手/拍卖/测评/商品/笔记/信誉/PV/点赞）。Actions: view / add_role / switch_role / view_user / feed。`,
+- view_user (user_id = usr_xxx / permanent_code / @handle; needs api_key)
+- feed (user_id + feed): secondhand | auctions | reviews | products | shares | reputation (public) | pv (needs api_key) | liked (owner-only, needs your api_key)`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key（view/add_role/switch_role/view_user 必填；公开 feed 可省略）' },
+                api_key: { type: 'string', description: 'Your api_key (required for view/add_role/switch_role/view_user; optional for public feed)' },
                 action: {
                     type: 'string',
                     enum: ['view', 'add_role', 'switch_role', 'view_user', 'feed'],
-                    description: 'view/add_role/switch_role = 自己；view_user/feed = 看他人主页/内容流',
+                    description: 'view/add_role/switch_role = self; view_user/feed = other user profile/feed',
                 },
                 role: {
                     type: 'string',
                     enum: ['buyer', 'seller', 'logistics', 'arbitrator'],
                     description: 'Role to add or switch to (required for add_role / switch_role)',
                 },
-                user_id: { type: 'string', description: '目标用户：usr_xxx / 永久码 / @handle（view_user / feed 时必填）' },
+                user_id: { type: 'string', description: 'Target user: usr_xxx / permanent_code / @handle (required for view_user/feed)' },
                 feed: {
                     type: 'string',
                     enum: ['secondhand', 'auctions', 'reviews', 'products', 'shares', 'reputation', 'pv', 'liked'],
-                    description: '内容流类型（feed 时必填）',
+                    description: 'Feed type (required for feed)',
                 },
             },
             required: ['action'],
@@ -840,18 +757,14 @@ Public-profile actions:
     },
     {
         name: 'webaz_revoke_key',
-        description: `Initiate api_key revocation (NO REPLACEMENT — old key dies, no new one issued). Iron-Rule: actual revocation requires PWA + Passkey confirmation — MCP only registers the intent and returns the PWA URL where you finish the action.
-
-⚠️ STRONG RECOMMENDATION: use webaz_rotate_key instead unless you intentionally want zero replacement (e.g. fully decommissioning the agent / device). Rotate = atomic swap (no access gap). Revoke = death + you re-register from scratch.
+        // was ~778 chars, now ~430 chars
+        description: `Initiate api_key revocation (**NO REPLACEMENT** — old key dies, no new issued).
 
-Use revoke (not rotate) when:
-- You are PERMANENTLY decommissioning this agent / device, OR
-- You want all access to die NOW with no fallback
+⚠️ **Iron-Rule**: actual revocation needs **PWA + Passkey** confirm. MCP only registers intent + returns PWA URL.
 
-After PWA confirmation, the old api_key returns 401 on all tools.
+⚠️ **STRONG REC**: use \`webaz_rotate_key\` instead unless you want zero replacement. Rotate = atomic swap (no access gap). Revoke = death + re-register.
 
-──
-中文：发起 api_key 吊销。Iron-Rule：真正吊销必须 PWA + Passkey 二次确认（agent 不能单方面执行不可逆操作）。MCP 仅登记意图，返回 PWA 确认 URL。`,
+Use revoke when: PERMANENT decommission of agent/device, OR want access death NOW with no fallback. After PWA confirm: old key → 401 on all tools.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -863,12 +776,10 @@ After PWA confirmation, the old api_key returns 401 on all tools.
     },
     {
         name: 'webaz_rotate_key',
-        description: `Initiate api_key rotation (invalidate old key + issue new one). Iron-Rule: requires PWA + Passkey confirmation. After PWA confirms, old key returns 401 and new key is shown once — store immediately.
+        // was ~372 chars, now ~260 chars
+        description: `Initiate api_key rotation (invalidate old + issue new). ⚠️ **Iron-Rule**: needs **PWA + Passkey** confirm. After PWA: old → 401; new shown ONCE — store immediately.
 
-Safer than webaz_revoke_key because issuance is atomic with invalidation — no access gap.
-
-──
-中文：发起 api_key 轮换（旧 key 失效 + 新 key 同时签发）。比 revoke 安全，原子操作无访问中断。需 PWA + Passkey。`,
+Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -880,9 +791,11 @@ Safer than webaz_revoke_key because issuance is atomic with invalidation — no
     },
     {
         name: 'webaz_referral',
-        description: `View your full referral status: 3-tier commission (推土机) team + earnings + invite links + binary PV matching (原子能) tree + tier progress + L1 share permission gate. Use this to know how to promote and what you have earned.
+        description: `View your referral status: 3-tier commission (推土机) team + earnings + invite links + binary PV matching (原子能) tree + tier progress + L1 share permission gate + **rewards_status (RFC-002 §3.5 opt-in state + pending escrow)**.
+
+⚠️ **Opt-in required (RFC-002)**: rewards default = off. \`rewards_status\` field returns 4-state {opted_in | never_activated | auto_downgraded | deactivated} + pending_escrow tally. Opted-out users still see attribution + tree, but commission held in escrow until activation via PWA #me.
 
-⚠️ Commission structure involves multi-tier referral + binary pairing tree which may overlap with MLM legal definitions in many jurisdictions (see webaz_info.commission_model.compliance_notice). Agents acting on behalf of a human user MUST get the user's explicit consent before generating referral links or promoting on their behalf. Do NOT auto-recruit.`,
+⚠️ **MLM disclosure**: structure may overlap with MLM legal definitions (see webaz_info.commission_model.compliance_notice). Agent acting for human user **MUST get explicit consent** before generating referral links / promoting. Do NOT auto-recruit.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -893,9 +806,11 @@ Safer than webaz_revoke_key because issuance is atomic with invalidation — no
     },
     {
         name: 'webaz_share_link',
-        description: `Generate a product share link with your referral attached. Open this in any social platform (TikTok / WeChat / Telegram). Whoever clicks and registers/buys will count toward your 3-tier commission (if you are verified buyer) and PV tree.
+        description: `Generate product share link with your referral attached. Open in any social platform (TikTok/WeChat/Telegram). Clicker registers/buys → counts toward your 3-tier commission (if verified buyer) + PV tree.
+
+⚠️ **Opt-in required (RFC-002 §3.5)**: this is a valuation-layer action. Caller must have \`rewards_opted_in=1\` (builder-identity opt-in). Opted-out users get \`{error: 'rewards_opt_in_required', missing_requirements, next_steps}\` — direct user to PWA #me to apply.
 
-⚠️ This tool builds the referral chain. Generating a link is taking an active promotion step in a multi-tier commission + binary pairing structure (see webaz_info.commission_model.compliance_notice — may overlap with MLM legal definitions). Agents acting for a human user MUST get explicit consent before calling this on their behalf. Do NOT auto-generate.`,
+⚠️ **MLM disclosure**: builds referral chain (multi-tier commission + binary pairing). Agent acting for human user **MUST get explicit consent**. Do NOT auto-generate. See webaz_info.commission_model.compliance_notice.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -912,17 +827,12 @@ Safer than webaz_revoke_key because issuance is atomic with invalidation — no
     },
     {
         name: 'webaz_blocklist',
-        description: `Manage your blocklist of sellers/users. Blocked users' products are auto-hidden from your searches.
+        // was ~607 chars, now ~370 chars
+        description: `Manage blocklist of sellers/users. Blocked → auto-hidden from your search + can't follow them.
 
-Scope (元规则 #5 不偏袒 design):
-- ✓ Hides blocked user's products from YOUR search results
-- ✓ Prevents YOU from following them (webaz_follows respects this)
-- ✗ Does NOT prevent placing orders on their products (商品发布即承诺销售 — public listing = sales commitment)
-- ✗ Does NOT silence existing chat conversations (business context overrides)
-- ✗ Does NOT prevent NEW chat starts on shared order/rfq context
-- For active rejection: delist products, don't bid on RFQs, or cancel the order.
+⚠️ **Scope** (元规则 #5 不偏袒): ✓ hides from YOUR search ✓ prevents follow. ✗ Does NOT prevent placing orders on their products (商品发布即承诺销售) ✗ Does NOT silence existing chat (business context wins) ✗ Does NOT prevent new chat on shared order/rfq context. For active rejection: delist / don't bid / cancel order.
 
-Returns the action result.`,
+Actions: list | block | unblock.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -949,18 +859,12 @@ Returns the action result.`,
     },
     {
         name: 'webaz_nearby',
-        description: `Query anonymized nearby (~11km cell) purchase aggregation. k-anonymity ≥ 3 privacy guard. Or set/clear your coarse geo location (0.1° = 11km precision, never stores exact GPS).
+        // was ~831 chars, now ~430 chars
+        description: `Query anonymized nearby (~11km cell) purchase aggregation. **k-anonymity ≥3** privacy guard. Set/clear your coarse geo (0.1° precision, never exact GPS).
 
-USE THIS when user asks "what's popular/being bought near me / 我附近 / 同城" — geo-aggregated
-view, no specific keyword. NOT for "find product X" — use webaz_search. NOT for "items shippable
-to my address" — use webaz_search ship_to filter.
+USE THIS for "what's popular near me / 我附近 / 同城" — geo-aggregated, no keyword. NOT for "find product X" (use webaz_search). NOT for "shippable to me" (use webaz_search ship_to).
 
-⚠️ MCP query 需要先 set_location(否则返回 has_location: false 提示)。
-  PWA #nearby 有【全网 / 同城 / 周边 / 14 公里】 4 档 fallback,无 location 也能看全网视图 —
-  这是设计性差异(MCP agent 应明示要 location,PWA UI 友好降级)。
-⚠️ MCP query needs set_location first (else returns has_location: false).
-  PWA #nearby has 4-tier fallback (national/city/around/14km) showing global view without location —
-  by design (MCP demands location; PWA degrades gracefully).`,
+⚠️ MCP \`query\` needs \`set_location\` first (else \`has_location: false\`). PWA #nearby has 4-tier fallback (national / city / around / 14km) — designed difference: MCP demands location, PWA degrades.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -974,13 +878,10 @@ to my address" — use webaz_search ship_to filter.
     },
     {
         name: 'webaz_default_address',
-        description: `Read or set your default shipping address. Used to auto-filter unshippable products in search + fallback when webaz_rfq/place_order omits shipping_address.
+        // was ~370 chars, now ~230 chars
+        description: `Read or set default shipping address. Used by webaz_search unshippable filter + fallback for webaz_rfq/place_order if omitted.
 
-⚠️ set 仅接受 2 个字段：text（自由格式地址字符串）+ region（可选；用于 unshippable 过滤）。
-不接受 structured 字段（recipient/line1/city/country/phone 等）— 跟传统电商地址 API 不同，agent 必须自己拼接。
-
-──
-中文：读取/设置默认收货地址。set 需要 text 必填 + region 可选；不收 structured 字段。`,
+⚠️ \`set\` accepts only 2 fields: \`text\` (free-text address, ≤200 chars, required) + \`region\` (optional, for unshippable filter, ≤40 chars). NO structured fields (no recipient/line1/city/country/phone) — agent must concat itself.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -994,16 +895,14 @@ to my address" — use webaz_search ship_to filter.
     },
     {
         name: 'webaz_shareables',
-        description: `Bind your EXTERNAL content (YouTube / TikTok / 小红书 / B站 / IG / Twitter posts) to a WebAZ product — turns your content into a referral-earning channel. WebAZ indexes only the URL, never the content bytes.
+        // was ~843 chars, now ~480 chars
+        description: `Bind your **EXISTING external content** (YouTube / TikTok / 小红书 / B站 / IG / Twitter) to a WebAZ product/anchor — turns your content into referral-earning channel. WebAZ indexes only URL, never content bytes.
 
-USE THIS when:
-- creator/user wants to "anchor" their existing review/unboxing/recommendation video/post to a WebAZ product (or anchor) so future buyers clicking that content → registration / purchase counts toward THEIR referral commission, OR
-- agent wants to look up "what external content is associated with this product / this anchor"
+USE THIS when: creator anchors existing review/unboxing post → future buyers click → counts toward THEIR referral commission. OR agent looks up "what external content for this product/anchor".
 
-Differs from webaz_share_link (which generates a NEW short link for sharing) — shareables register your EXISTING content as the discovery surface.
+⚠️ Different from \`webaz_share_link\` (generates NEW short link) — shareables register EXISTING content as discovery surface.
 
-──
-中文：把你在 YouTube/TikTok/小红书/B站/IG/Twitter 已发的内容(测评/开箱/推荐)锚定到 WebAZ 商品 —— 让你的外部内容变成赚 referral 佣金的入口。WebAZ 只锚 URL,不取内容。区别于 webaz_share_link(那个是生成新短链)。`,
+Actions: list_mine | add (external_url + product/anchor) | delete | by_product | by_anchor.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1022,76 +921,63 @@ Differs from webaz_share_link (which generates a NEW short link for sharing) —
     // ── P3 RFQ / bid / chat / auto_bid（MCP 通过 HTTP 调 PWA，复用所有校验+状态机）────
     {
         name: 'webaz_rfq',
-        description: `RFQ (Request-for-Quotation) — buyer posts demand, sellers bid within a time window.
+        // was ~1822 chars, now ~880 chars
+        description: `RFQ (Request-for-Quotation) — buyer posts demand, sellers bid within time window.
 
-USE THIS when buyer wants to POST a need (and have sellers come to them) — typically because
-webaz_search returned no good match, OR the buyer wants competing quotes (bulk / custom / unusual
-spec / time-sensitive). NOT a search tool. For browsing existing listings use webaz_search.
+USE THIS when buyer POSTS a need (no good search match / bulk / custom / time-sensitive / wants competing quotes). NOT a search tool — for browsing use webaz_search. For AUCTION (English forward on a listed item) use webaz_auction.
 
 Actions:
-- create (buyer):  publish RFQ; needs title/qty/max_price/category/urgency/award_mode
-- mine (buyer):    my RFQ list
-- browse (seller): board view (filter by region/category/urgency/unbidded)
-- detail:          full detail (buyer sees all bids; seller sees only own)
-- award (buyer):   pick winner (pass bid_id for manual; omit for auto-lowest)
-- cancel (buyer):  cancel (only if no bid awarded; 30% deposit forfeited)
+- create (buyer)   publish RFQ (title/qty/max_price/category/urgency/award_mode)
+- mine (buyer)    my RFQ list
+- browse (seller) board view (filter by region/category/urgency/unbidded)
+- detail          full detail (buyer sees all bids; seller sees only own)
+- award (buyer)   pick winner (bid_id for manual; omit = auto-lowest)
+- cancel (buyer)  only pre-award; 30% deposit forfeit to charity_fund
 
 Economics:
-- Buyer deposit = clamp(0.1, 1) of (max_price × qty × 0.01)  — i.e. 1% capped at 1 WAZ (anti-spam, NOT anti-fraud; real anti-fraud is 30% cancel penalty)
-- No-max-price RFQ deposit = 0.1 WAZ flat
-- Seller bid stake = max(0.5, price × qty × 0.05)  — 5% with floor 0.5 WAZ
-- Cancel before award: 30% deposit forfeit to charity_fund
-- Award winner → standard order lifecycle, BUT with snapshot_commission_rate = 0 (RFQ orders 0% commission — direct deal between buyer/seller, no promoter chain to compensate). Seller gets price minus protocol_fee (2%) and fund_base (1%); no L1/L2/L3 dilution.
-- Seller bid stake (4.5+ WAZ) becomes bid_stake_held on the order; released to seller balance on successful complete; 50/50 split to buyer+sys_protocol on fault_seller (settleFault).
-- Window defaults: now=15min / today=60min / flex=1440min(24h)
-
-Shipping address: if omitted, falls back to webaz_default_address (set via that tool first).
+- Buyer deposit = clamp(0.1, 1) of max_price × qty × 1% (anti-spam). No-max-price = 0.1 WAZ flat.
+- Seller bid stake = max(0.5, price × qty × 5%). Becomes bid_stake_held on award; released on complete; 50/50 split (buyer + sys_protocol) on fault_seller.
+- Award → standard order lifecycle BUT **snapshot_commission_rate = 0** (RFQ 0% commission, no L1/L2/L3 promoter dilution); seller gets price − protocol_fee 2% − fund_base 1%.
+- Window defaults: now=15min / today=60min / flex=24h.
 
-──
-中文：求购单 RFQ。买家押金 1%（封顶 1 WAZ，仅防 spam）；卖家 bid stake 5%（最少 0.5 WAZ）；撤单扣 30% 入慈善池。`,
+Shipping address falls back to webaz_default_address if omitted.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key' },
+                api_key: { type: 'string', description: 'Your api_key' },
                 action: { type: 'string', enum: ['create', 'mine', 'browse', 'detail', 'award', 'cancel'] },
                 // create
                 title: { type: 'string' },
                 qty: { type: 'number' },
-                max_price: { type: 'number', description: 'WAZ 预算上限（可选；不填时 buyer 押金为 1 WAZ）' },
+                max_price: { type: 'number', description: 'Max budget in WAZ (optional; if omitted, buyer deposit = 1 WAZ)' },
                 category: { type: 'string', enum: ['standard', 'general', 'highvalue', 'restricted'] },
                 urgency: { type: 'string', enum: ['now', 'today', 'flex'] },
                 award_mode: { type: 'string', enum: ['manual', 'first_match', 'time_window'] },
                 award_window_min: { type: 'number' },
                 notes: { type: 'string' },
-                shipping_address: { type: 'string', description: '可选；缺省取 buyer 默认地址' },
+                shipping_address: { type: 'string', description: 'Optional; falls back to buyer default address' },
                 // browse filters
                 region: { type: 'string' },
                 unbidded: { type: 'boolean' },
                 // detail/award/cancel
                 rfq_id: { type: 'string' },
-                bid_id: { type: 'string', description: 'award 时可选 — 不传则自动选当前最低价' },
+                bid_id: { type: 'string', description: 'Optional for award — if omitted, auto-pick current lowest bid' },
             },
             required: ['api_key', 'action'],
         },
     },
     {
         name: 'webaz_bid',
+        // was ~733 chars, now ~400 chars
         description: `Bid on RFQs (seller-side, Request-for-Quotation).
 
-USE THIS ONLY for RFQ bidding (when a buyer posted demand via webaz_rfq and you want to quote). For AUCTION bidding (English forward auction on a listed item) use webaz_auction action=bid — they are separate systems with different economics (RFQ has bid stake; auction has min_increment + sniper extension).
-
-Actions:
-- submit:    new bid; needs rfq_id + price + qty_offered + fulfillment_type; optional eta_hours/note
-- patch:     edit price/ETA/fulfillment/note (only active; stake delta auto-settled)
-- cancel:    withdraw (only active; deposit released immediately)
-- list_mine: full bid history
+⚠️ **ONLY for RFQ bidding** (buyer posted demand via webaz_rfq). For AUCTION (English forward on listed item) use \`webaz_auction action=bid\` — separate systems with different economics (RFQ = bid stake; auction = min_increment + sniper extension).
 
-──
-中文：对 RFQ 报价（卖家）。Actions: submit / patch / cancel / list_mine。改价时 stake 自动结算差额。`,
+Actions: submit (rfq_id + price + qty_offered + fulfillment_type; optional eta/note) | patch (active only, stake delta auto-settled) | cancel (active only, deposit released immediately) | list_mine.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '卖家 api_key' },
+                api_key: { type: 'string', description: 'Seller api_key' },
                 action: { type: 'string', enum: ['submit', 'patch', 'cancel', 'list_mine'] },
                 rfq_id: { type: 'string' },
                 bid_id: { type: 'string' },
@@ -1100,42 +986,25 @@ Actions:
                 eta_hours: { type: 'number' },
                 fulfillment_type: { type: 'string', enum: ['instant_pickup', 'same_day', 'next_day', 'standard'] },
                 note: { type: 'string' },
-                offer_id: { type: 'string', description: '可选；引用已有 offer 商品' },
+                offer_id: { type: 'string', description: 'Optional; reference existing offer' },
             },
             required: ['api_key', 'action'],
         },
     },
     {
         name: 'webaz_chat',
-        description: `Relay buyer↔seller (or RFQ partner) MESSAGES — context-bound DM, no open DM. Only order / rfq / listing_qa contexts allowed.
+        // was ~1963 chars, now ~860 chars
+        description: `Relay buyer↔seller (or RFQ partner) MESSAGES — **context-bound DM**, NO open DM. Only \`order\` / \`rfq\` / \`listing_qa\` contexts.
 
-USE THIS when the user wants to communicate with the OTHER PARTY of a trade (e.g. "ask seller about return", "tell buyer about shipping delay", "answer Q&A on my listing"). NOT a general LLM chat — every message attaches to an order/rfq/listing_qa context. If the user just wants to chat with YOU (the agent), don't call this tool.
-Actions:
-- start:     open conversation — needs kind + context_id (for rfq, also recipient_id)
-- list:      my conversation list
-- read:      read messages (last 50; flag_reasons is array)
-- send:      send message (anti-scam regex; matches get flagged=true but still delivered; flag_reasons is array)
-- mark_read: mark as read
-- block:     block this specific conversation (sets conv.status=blocked; ≠ webaz_blocklist which hides from search)
+USE THIS for trade communication ("ask seller about return", "tell buyer about delay", "answer listing Q&A"). NOT general LLM chat — every message attaches to context. User chatting with agent? Don't call this.
 
-Anti-scam regex names (returned in flag_reasons array):
-phone_cn (CN mobile 11-digit), wechat (微信/vx/wechat/weixin), alipay (支付宝/alipay),
-qq (qq:digits), bank_card (16-19 consecutive digits), telegram (@handle/t.me/telegram),
-external_url (any http(s) URL except localhost/webaz.app/webaz.io).
+Actions: start (kind + context_id; rfq needs recipient_id) | list | read (last 50, flag_reasons array) | send (anti-scam regex; matches flagged=true but still delivered) | mark_read | block (this conv only; ≠ webaz_blocklist which hides from search).
 
-Rate limits (PWA-enforced):
-- Short-term: 60 messages / minute / user
-- AGENT_DAILY_CAP (reset at UTC midnight): new=30, trusted=100, quality=300, legend=1000
-  (returns 429 + error_code=AGENT_DAILY_CAP + cap + used + level fields)
-  3 overruns/day → auto agent warning strike.
+⚠️ **Anti-scam regex** (in flag_reasons[]): phone_cn (11-digit) / wechat (微信/vx/wechat) / alipay / qq / bank_card (16-19 digits) / telegram (@/t.me) / external_url (non-webaz HTTPS).
 
-Behavior note: webaz_blocklist hides target from your search; per-conversation block (this tool's "block")
-silences the specific conv. Existing conversations are NOT auto-silenced by webaz_blocklist
-(business context overrides — block prevents future ad-hoc contact but keeps active deal channels open).
+Rate limits: 60/min/user short-term + AGENT_DAILY_CAP (UTC reset): new=30 / trusted=100 / quality=300 / legend=1000 (over → 429 + error_code=AGENT_DAILY_CAP). 3 overruns/day → auto warning strike.
 
-──
-中文：上下文私聊 — 仅 order/rfq/listing_qa 三种场景可发起，无自由 DM。Actions: start / list / read / send / mark_read / block。
-反诈 regex 7 类 + 60/min rate limit。blocklist 不影响已建立 conversation（商业上下文优先）。`,
+webaz_blocklist hides from search but does NOT auto-silence existing convs (business context wins) — use this tool's \`block\` for per-conv silence.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1145,60 +1014,45 @@ silences the specific conv. Existing conversations are NOT auto-silenced by weba
                 context_id: { type: 'string' },
                 recipient_id: { type: 'string' },
                 conversation_id: { type: 'string' },
-                body: { type: 'string', description: 'send action 的消息正文 (≤ 2000 字)' },
+                body: { type: 'string', description: 'Message body for send action (≤2000 chars)' },
             },
             required: ['api_key', 'action'],
         },
     },
     {
         name: 'webaz_price_history',
-        description: `Product historical sale price + volume distribution — helps agents avoid bottom-price dumping bait.
-Returns:
-- windows: { d30, d90, lifetime } each {sales, volume, avg, median, p25, p75}
-- price_buckets: distribution array [{price, count, qty, pct}]
-- daily_avg: 30-day daily avg price trend [{date, sales, avg}]
-- category_avg_30d: same-category 30-day average
-- anomaly_flags: ('current_below_70pct_median' / 'far_below_category_avg' / 'far_above_category_avg')
-Returns insufficient_data:true when data sparse.
+        // was ~571 chars, now ~350 chars
+        description: `Product historical sale price + volume — helps agents avoid bottom-price dumping bait.
 
-──
-中文：商品历史成交价 + 量分布 — 防底价倾销。返回多时窗统计 + 价位分布 + 同类均价 + 异常预警。`,
+Returns: windows {d30, d90, lifetime} each {sales, volume, avg, median, p25, p75} | price_buckets [{price, count, qty, pct}] | daily_avg (30-day trend) | category_avg_30d | anomaly_flags (current_below_70pct_median / far_below_category_avg / far_above_category_avg). \`insufficient_data: true\` if sparse.`,
         inputSchema: {
             type: 'object',
             properties: {
-                product_id: { type: 'string', description: '商品 ID' },
+                product_id: { type: 'string', description: 'Product ID' },
             },
             required: ['product_id'],
         },
     },
     {
         name: 'webaz_charity',
-        description: `Charity WISH POOL + repayment + community FUND — double-anonymous + dual-signed anchoring + isolated prestige.
+        // was ~1856 chars, now ~850 chars
+        description: `Charity wish pool + repayment + community fund — double-anonymous + dual-signed anchoring + isolated prestige.
 
-USE THIS when:
-- user wants to publish a "wish" (need help with money/service) for community fulfillment, OR
-- user wants to claim/fulfill someone else's wish, OR
-- user wants to donate to / browse the community charity fund (separate from per-order donation).
+USE THIS for: publishing wish (need help) | claiming/fulfilling others' wishes | donating to / browsing community fund.
 
-NOT for per-order charity donation — that's handled by webaz_place_order's donation_pct param (0.5% / 1% / 2% / 5% sent to charity_fund at order time). This tool is for the standalone wish-fulfillment economy.
-Actions:
-- list:        browse public wishes (filter by category/target_kind; anonymous accessible)
-- detail:      single wish details (commit_hash + fulfillment + repayments)
-- create:      (auth) publish a wish
-- claim:       (auth) fulfiller claims (1:1 exclusive; 30-day self-claim lock; auto-release if no proof in 48h)
-- proof:       (auth) submit completion evidence
-- confirm:     (auth) wisher confirms → fulfiller +10 prestige
-- disclose:    (auth) apply for public disclosure (both parties must agree)
-- cancel:      (auth) wisher cancels (only open wishes)
-- me:          (auth) my charity profile (prestige breakdown + pending repayment queue)
-- stories / leaderboard: public
-- repay:       (auth) wisher initiates repayment (≥ 0.1 WAZ; auto-accepted if no response in 7d)
-- repay_respond:(auth) fulfiller responds (accept | decline_to_fund) — decline → funds go to community fund, wisher +8 / fulfiller +2 grace
-- donate:      (auth) donate to community fund (≥ 0.1 WAZ; daily 50 WAZ matched 1:1 → donation_honor)
-- fund:        fund balance + ledger + philanthropist leaderboard (public)
+**NOT** for per-order charity donation — that's webaz_place_order's \`donation_pct\` (0.5/1/2/5% to charity_fund at order time). This tool is the **standalone wish-fulfillment economy**.
 
-──
-中文：慈善许愿池 + 还愿 + 慈善基金。双匿名 + 双签锚定 + 隔离 prestige。Actions: list/detail/create/claim/proof/confirm/disclose/cancel/me/stories/leaderboard/repay/repay_respond/donate/fund。`,
+Actions (15):
+- list / detail / stories / leaderboard / fund — public
+- create  (auth) publish wish
+- claim   (auth) 1:1 exclusive, 30-day self-claim lock, auto-release if no proof 48h
+- proof / confirm  (auth) complete + wisher confirm → fulfiller +10 prestige
+- disclose (auth) both-agree public disclosure
+- cancel  (auth) only open wishes
+- me      (auth) prestige breakdown + pending repayment queue
+- repay   (auth) ≥0.1 WAZ; auto-accept if no response 7d
+- repay_respond  (auth) accept | decline_to_fund (decline → fund, wisher +8 / fulfiller +2 grace)
+- donate  (auth) ≥0.1 WAZ; daily 50 WAZ matched 1:1 → donation_honor`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1210,14 +1064,14 @@ Actions:
                 choice: { type: 'string', enum: ['accept', 'decline_to_fund'] },
                 category: { type: 'string', enum: ['medical', 'education', 'daily', 'elderly', 'disaster', 'tech', 'other'] },
                 target_kind: { type: 'string', enum: ['item', 'service', 'cash'] },
-                target_waz: { type: 'number', description: 'cash 模式必填，≤ 500' },
-                escrow_self: { type: 'number', description: '1=自我托管锁仓全额，0=纯协调' },
+                target_waz: { type: 'number', description: 'Required for cash mode, ≤500' },
+                escrow_self: { type: 'number', description: '1=self-escrow lock full amount; 0=pure coordination' },
                 title: { type: 'string' }, content: { type: 'string' },
-                window_hours: { type: 'number', description: '24-720 小时' },
+                window_hours: { type: 'number', description: '24-720 hours' },
                 allow_public: { type: 'number' },
                 proof_hash: { type: 'string', description: 'sha256 hex of proof_text' },
                 proof_note: { type: 'string' },
-                amount: { type: 'number', description: 'repay / donate 金额（WAZ）' },
+                amount: { type: 'number', description: 'repay / donate amount in WAZ' },
                 note: { type: 'string' },
                 limit: { type: 'number' },
             },
@@ -1226,20 +1080,15 @@ Actions:
     },
     {
         name: 'webaz_p2p_product',
+        // was ~880 chars, now ~480 chars
         description: `P2P native store — product detail lives on seller's node; WebAZ only anchors hash + key fields.
-Actions:
-- create (seller): publish anchor — needs title/price/stock + content_hash (sha256) + content_signature (HMAC-SHA256(api_key, hash|signed_at))
-- list:            browse public P2P products (incl. hash + peer_endpoint)
-- detail:          single product (incl. hash + endpoint; agent should self-fetch peer_endpoint and verify sha256)
-- patch (seller):  edit (price/stock/title direct; detail JSON change → must re-sign hash + signature)
 
-Verification flow (agent implements):
+Actions: create (seller, needs title/price/stock + content_hash sha256 + content_signature HMAC-SHA256(api_key, hash|signed_at)) | list | detail | patch (price/stock/title direct; detail JSON change → must re-sign).
+
+⚠️ **Agent verification flow** (must implement):
 1. GET peer_endpoint/<product_id> → raw JSON
 2. canonicalize (sort keys, drop nulls) → JSON.stringify
-3. sha256(canonical) === product.content_hash ? accept : reject trade
-
-──
-中文：P2P 原生商店 — 商品详情存卖家节点，WebAZ 只锚定 hash + 关键字段。Actions: create / list / detail / patch。Agent 须自行 GET peer_endpoint 校验 sha256。`,
+3. sha256(canonical) === product.content_hash ? accept : **reject trade**`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1259,14 +1108,12 @@ Verification flow (agent implements):
     },
     {
         name: 'webaz_like',
-        description: `Like a shareable (others' shared content) to boost product ranking.
-Actions:
-- toggle: like or unlike (same endpoint; second call auto-unlikes)
-- status: my like status on a shareable + total count
-Threshold: must have ≥1 completed order (anti-Sybil). One vote per person, can't like own.
+        // was ~369 chars, now ~230 chars
+        description: `Like a shareable to boost product ranking.
+
+Actions: toggle (same endpoint; 2nd call auto-unlikes) | status (my like status + total).
 
-──
-中文：对 shareable 点赞 — 提升商品 ranking。Actions: toggle / status。门槛：≥1 完成订单，不能给自己点。`,
+⚠️ **Anti-Sybil**: must have ≥1 completed order. One vote per person, can't like own.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1279,49 +1126,43 @@ Threshold: must have ≥1 completed order (anti-Sybil). One vote per person, can
     },
     {
         name: 'webaz_leaderboard',
-        description: `WebAZ leaderboards — no centralized traffic distribution, pure real-signal ranking. Privacy-first: GMV / revenue amounts are NEVER exposed.
-Kinds:
-- products       trending products (rank_score = sales×0.5 + referrals×2.0 + likes×1.0)
-- value_products value-certified (💎 cheapest 20% per category · daily batch)
-- creators       creator board (by total likes received)
-- sellers        seller board (by rating × log(reviews+1); GMV hidden)
-- buyers         buyer activity (by completed order count; GMV hidden)
-- verifiers      verifier board (correct count / accuracy)
-- arbitrators    arbitrator reputation (fairness_score)
-- agents         agent eval (trust_score + 30d call count)
+        // was ~817 chars, now ~480 chars
+        description: `WebAZ leaderboards — no centralized traffic distribution, pure real-signal ranking. **Privacy-first**: GMV / revenue amounts NEVER exposed.
 
-──
-中文：排行榜（无中心流量分发，纯真实信号）。8 类：products / value_products / creators / sellers / buyers / verifiers / arbitrators / agents。隐私第一不露 GMV。`,
+8 kinds:
+- products (sales×0.5 + referrals×2.0 + likes×1.0)
+- value_products (💎 cheapest 20% per category, daily batch)
+- creators (total likes received)
+- sellers (rating × log(reviews+1); GMV hidden)
+- buyers (completed order count; GMV hidden)
+- verifiers (correct count / accuracy)
+- arbitrators (fairness_score)
+- agents (trust_score + 30d call count)`,
         inputSchema: {
             type: 'object',
             properties: {
                 kind: {
                     type: 'string',
                     enum: ['products', 'value_products', 'creators', 'sellers', 'buyers', 'verifiers', 'arbitrators', 'agents'],
-                    description: '榜单类型',
+                    description: 'Leaderboard kind',
                 },
-                limit: { type: 'number', description: '默认 20，最多 50' },
+                limit: { type: 'number', description: 'Default 20, max 50' },
             },
             required: ['kind'],
         },
     },
     {
         name: 'webaz_auction',
-        description: `English forward auction — seller posts → buyers raise bids → anti-sniping extension → highest bid wins.
+        // was ~967 chars, now ~550 chars
+        description: `English forward auction — seller posts → buyers raise → **anti-sniping extension** → highest wins.
 
-USE THIS when user wants to BID on auction items OR a seller wants to START an auction (rare goods,
-collectibles, price-discovery). NOT a regular product search — auctions are time-windowed events.
-For fixed-price items use webaz_search.
-Actions:
-- create (seller): start auction; needs title/qty/category/starting_price, optional min_increment/reserve_price/window_min/sniper_extend_min
-- browse:          public board
-- mine:            my created (seller) + my participated (buyer)
-- detail:          full detail incl. bid history (buyer_id redacted for non-seller / non-bidder viewers)
-- bid (buyer):     place bid; needs auction_id + price (first ≥ starting; subsequent ≥ current + increment)
-- cancel (seller): cancel (only before any bid placed)
+USE THIS to BID on auction items OR seller starts auction (rare goods / collectibles / price-discovery). NOT regular product search — auctions are **time-windowed events**. For fixed-price use webaz_search.
 
-──
-中文：加价拍卖（English forward）— 反狙击延时 + 最高价中标。Actions: create / browse / mine / detail / bid / cancel。仅未出价时可取消。`,
+Actions:
+- create (seller): title/qty/category/starting_price + optional min_increment/reserve_price/window_min/sniper_extend_min
+- browse / mine (own + participated) / detail (bid history; buyer_id redacted to non-seller/non-bidder)
+- bid (buyer): auction_id + price (first ≥ starting; next ≥ current + increment)
+- cancel (seller, only pre-bid)`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1344,16 +1185,12 @@ Actions:
     },
     {
         name: 'webaz_auto_bid',
+        // was ~595 chars, now ~340 chars
         description: `Seller auto_bid Skill config — auto-quote on RFQ creation instantly.
 
-USE THIS as a shortcut equivalent to webaz_skill install kind=auto_bid + ongoing config edits. Dedicated tool because auto_bid is the most-used Skill and needs frequent param tuning (max_eta_h / undercut_pct / daily_cap). For other Skill kinds use webaz_skill directly.
-Actions:
-- get:     read current Skill config
-- set:     create/update Skill (needs categories[] / regions[] / max_eta_h / bid_strategy etc.)
-- disable: one-click disable (keeps config)
+Shortcut for \`webaz_skill install kind=auto_bid\` + ongoing config edits. Dedicated tool because auto_bid is most-used + needs frequent tuning (max_eta_h / undercut_pct / daily_cap). For other Skill kinds use webaz_skill.
 
-──
-中文：卖家 auto_bid Skill — RFQ 创建瞬间自动报价。Actions: get / set / disable。`,
+Actions: get | set (categories[] / regions[] / max_eta_h / bid_strategy) | disable (keeps config).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1364,7 +1201,7 @@ Actions:
                 max_eta_h: { type: 'number' },
                 fulfillment_type: { type: 'string', enum: ['instant_pickup', 'same_day', 'next_day', 'standard'] },
                 bid_strategy: { type: 'string', enum: ['cheapest_undercut', 'match_budget'] },
-                undercut_pct: { type: 'number', description: '0–0.5；折价幅度' },
+                undercut_pct: { type: 'number', description: '0–0.5; undercut margin' },
                 max_price_cap: { type: 'number' },
                 daily_cap: { type: 'number' },
                 cooldown_min: { type: 'number' },
@@ -1375,151 +1212,249 @@ Actions:
     },
     {
         name: 'webaz_skill_market',
-        description: `Knowledge-skill marketplace — anyone publishes reusable content skills (templates / prompts / guides / checklists); others pay to unlock. DISTINCT from webaz_skill (that one is seller behaviour-automation plugins).
+        // was ~1426 chars, now ~720 chars
+        description: `Knowledge-skill marketplace — anyone publishes content skills (templates / prompts / guides / checklists); others pay to unlock.
 
-Lifecycle: publish → WebAZ content review (human admin, not via MCP) → listed → buyers unlock.
-Billing modes: free / one_time (buy once, permanent) / per_use (charged each read).
-Revenue is an independent flow (author net → wallet, 5% protocol fee → sys_protocol); it does NOT enter PV / referral commission engines.
+⚠️ **DISTINCT from webaz_skill** (which is seller behaviour-automation plugins, totally separate revenue flow).
 
-Actions:
-- list       browse listed skills (filters: kind / billing / query; no auth needed)
-- detail     one skill's public detail (skill_id; content is NOT included)
-- publish    publish a new skill (title + content + billing_mode required) → enters review queue
-- update     edit own skill (editing an approved one re-enters review)
-- delist     take own skill offline
-- resubmit   resubmit a rejected/delisted skill for review
-- purchase   unlock free / one_time skill (cannot buy your own)
-- read       read the unlocked content; per_use charges price each call
-- my_skills  my published skills (all statuses)
-- library    my unlocked / used skills
+Lifecycle: publish → human admin content review (NOT via MCP) → listed → buyers unlock.
 
-──
-中文：知识技能市场 — 人人发布内容型技能（模板/提示词/指南/清单），他人付费解锁。与 webaz_skill（卖家自动化插件）是两套。计费 free/one_time/per_use；收入独立流转，不进 PV/佣金。审计是人工 admin 节点，不经 MCP。Actions: list / detail / publish / update / delist / resubmit / purchase / read / my_skills / library。`,
+Billing: \`free\` | \`one_time\` (buy once, permanent) | \`per_use\` (charged each read).
+
+⚠️ **Revenue is independent flow**: author net → wallet, 5% protocol fee → sys_protocol. Does **NOT** enter PV / referral commission engines.
+
+Actions: list (no auth, filters: kind/billing/query) | detail (public, no content) | publish (→ review queue) | update (re-enters review if approved) | delist | resubmit | purchase (free / one_time; cannot self-buy) | read (per_use charges each call) | my_skills | library.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key（list / detail 时可省略）' },
+                api_key: { type: 'string', description: 'Your api_key (omit for list/detail)' },
                 action: {
                     type: 'string',
                     enum: ['list', 'detail', 'publish', 'update', 'delist', 'resubmit', 'purchase', 'read', 'my_skills', 'library'],
-                    description: '要执行的操作',
+                    description: 'Action to execute',
                 },
-                skill_id: { type: 'string', description: '技能 ID（detail/update/delist/resubmit/purchase/read 时必填）' },
+                skill_id: { type: 'string', description: 'Skill ID (required for detail/update/delist/resubmit/purchase/read)' },
                 // publish / update
-                title: { type: 'string', description: '标题（publish 必填）' },
-                content: { type: 'string', description: '技能正文，购买后才可见（publish 必填）' },
-                summary: { type: 'string', description: '一句话简介（可选）' },
-                preview: { type: 'string', description: '公开试读，未购可见（可选）' },
-                skill_kind: { type: 'string', enum: ['template', 'prompt', 'guide', 'checklist'], description: '技能类型（默认 template）' },
-                billing_mode: { type: 'string', enum: ['free', 'one_time', 'per_use'], description: '计费模式（publish 必填）' },
-                price: { type: 'number', description: 'WAZ 价格；free 必须为 0，付费必须 >0，上限 100000' },
-                category: { type: 'string', description: '分类（可选）' },
+                title: { type: 'string', description: 'Title (required for publish)' },
+                content: { type: 'string', description: 'Skill content, visible only after purchase (required for publish)' },
+                summary: { type: 'string', description: 'One-line summary (optional)' },
+                preview: { type: 'string', description: 'Public preview, visible without purchase (optional)' },
+                skill_kind: { type: 'string', enum: ['template', 'prompt', 'guide', 'checklist'], description: 'Skill kind (default template)' },
+                billing_mode: { type: 'string', enum: ['free', 'one_time', 'per_use'], description: 'Billing mode (required for publish)' },
+                price: { type: 'number', description: 'Price in WAZ; free must = 0, paid must > 0, max 100000' },
+                category: { type: 'string', description: 'Category (optional)' },
                 // list filters
-                kind: { type: 'string', enum: ['template', 'prompt', 'guide', 'checklist'], description: '过滤类型（list 时可选）' },
-                billing: { type: 'string', enum: ['free', 'one_time', 'per_use'], description: '过滤计费模式（list 时可选）' },
-                query: { type: 'string', description: '关键词搜索（list 时可选）' },
+                kind: { type: 'string', enum: ['template', 'prompt', 'guide', 'checklist'], description: 'Filter type (optional for list)' },
+                billing: { type: 'string', enum: ['free', 'one_time', 'per_use'], description: 'Filter billing mode (optional for list)' },
+                query: { type: 'string', description: 'Keyword search (optional for list)' },
             },
             required: ['action'],
         },
     },
     {
         name: 'webaz_secondhand',
-        description: `Secondhand market (个人闲置二手) — peer-to-peer pre-owned goods, 1% protocol fee, escrow-protected. Supports shipping and in-person handoff.
+        // was ~1285 chars, now ~650 chars
+        description: `Secondhand market (个人闲置二手) — P2P pre-owned goods, 1% protocol fee, escrow-protected. Supports shipping + in-person handoff.
 
-USE THIS when user wants USED / pre-owned / 闲置 / 二手 items, OR wants to sell own used items.
-For NEW manufactured products use webaz_search. Note: secondhand and shop catalog are separate
-spaces — webaz_search does NOT return secondhand listings.
-
-Actions:
-- browse   list available items (filters: category / condition / region / min_price / max_price / query / sort; no auth needed; excludes your own when api_key given)
-- detail   one item's detail + seller's other listings (item_id; no auth needed)
-- publish  list an item (title + category + condition + price + images[] required; ≥1 image)
-- update   edit own item (item_id + fields; can set status available/reserved/closed)
-- mine     my listings + stats (available/sold/earned)
-- buy      place an order on an item (item_id + fulfillment_mode; shipping needs shipping_address)
+USE THIS for USED / pre-owned / 闲置 / 二手 items, OR selling own used. NOT for NEW manufactured (use webaz_search). **Separate space** — webaz_search does NOT return secondhand listings.
 
-category: phone / computer / appliance / furniture / clothing / book / toy / sports / other
-condition: brand_new / like_new / lightly_used / well_used / heavily_used
-fulfillment: shipping / in_person / both
+Actions: browse (filters: category/condition/region/price/query/sort; no auth, excludes own when api_key given) | detail (no auth) | publish (title + category + condition + price + images[≥1]) | update (item_id + fields; status available/reserved/closed) | mine | buy (item_id + fulfillment_mode; shipping needs shipping_address).
 
-──
-中文：二手集市 — 个人闲置 P2P，协议费 1%，escrow 保护，支持快递/面交。Actions: browse / detail / publish / update / mine / buy。`,
+Enums: **category** phone/computer/appliance/furniture/clothing/book/toy/sports/other · **condition** brand_new/like_new/lightly_used/well_used/heavily_used · **fulfillment** shipping/in_person/both.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key（browse / detail 时可省略）' },
-                action: { type: 'string', enum: ['browse', 'detail', 'publish', 'update', 'mine', 'buy'], description: '要执行的操作' },
-                item_id: { type: 'string', description: '物品 ID（detail/update/buy 时必填）' },
+                api_key: { type: 'string', description: 'Your api_key (omit for browse/detail)' },
+                action: { type: 'string', enum: ['browse', 'detail', 'publish', 'update', 'mine', 'buy'], description: 'Action to execute' },
+                item_id: { type: 'string', description: 'Item ID (required for detail/update/buy)' },
                 // publish / update
-                title: { type: 'string', description: '标题 2-60 字（publish 必填）' },
-                description: { type: 'string', description: '详细描述（≤1000 字，可选）' },
-                category: { type: 'string', enum: ['phone', 'computer', 'appliance', 'furniture', 'clothing', 'book', 'toy', 'sports', 'other'], description: '类目（publish 必填）' },
-                condition_grade: { type: 'string', enum: ['brand_new', 'like_new', 'lightly_used', 'well_used', 'heavily_used'], description: '成色（publish 必填）' },
-                price: { type: 'number', description: 'WAZ 价格 0-100000（publish 必填）' },
-                negotiable: { type: 'boolean', description: '是否可议价（可选）' },
-                images: { type: 'array', items: { type: 'string' }, description: '图片 dataURL/URL 数组，≥1 张，最多 9 张（publish 必填）' },
-                region: { type: 'string', description: '地点（≤40 字，可选）' },
-                fulfillment: { type: 'string', enum: ['shipping', 'in_person', 'both'], description: '履约方式（默认 both）' },
-                status: { type: 'string', enum: ['available', 'reserved', 'closed'], description: '改状态（update 时可选）' },
+                title: { type: 'string', description: 'Title 2-60 chars (required for publish)' },
+                description: { type: 'string', description: 'Description (≤1000 chars, optional)' },
+                category: { type: 'string', enum: ['phone', 'computer', 'appliance', 'furniture', 'clothing', 'book', 'toy', 'sports', 'other'], description: 'Category (required for publish)' },
+                condition_grade: { type: 'string', enum: ['brand_new', 'like_new', 'lightly_used', 'well_used', 'heavily_used'], description: 'Condition grade (required for publish)' },
+                price: { type: 'number', description: 'Price in WAZ 0-100000 (required for publish)' },
+                negotiable: { type: 'boolean', description: 'Negotiable flag (optional)' },
+                images: { type: 'array', items: { type: 'string' }, description: 'Images dataURL/URL array, ≥1 ≤9 (required for publish)' },
+                region: { type: 'string', description: 'Region (≤40 chars, optional)' },
+                fulfillment: { type: 'string', enum: ['shipping', 'in_person', 'both'], description: 'Fulfillment (default both)' },
+                status: { type: 'string', enum: ['available', 'reserved', 'closed'], description: 'Change status (optional for update)' },
                 // buy
-                fulfillment_mode: { type: 'string', enum: ['shipping', 'in_person'], description: '本单履约方式（buy 必填，默认 shipping）' },
-                shipping_address: { type: 'string', description: '收货地址（buy 且 shipping 时必填）' },
-                notes: { type: 'string', description: '订单备注（buy 可选，可写还价）' },
+                fulfillment_mode: { type: 'string', enum: ['shipping', 'in_person'], description: 'Per-order fulfillment (required for buy, default shipping)' },
+                shipping_address: { type: 'string', description: 'Shipping address (required for buy + shipping)' },
+                notes: { type: 'string', description: 'Order note (optional for buy; can include counter-offer)' },
                 // browse filters
-                condition: { type: 'string', description: '过滤成色，逗号分隔多选（browse 可选）' },
+                condition: { type: 'string', description: 'Filter condition, comma-separated multi (optional for browse)' },
                 min_price: { type: 'number' },
                 max_price: { type: 'number' },
-                query: { type: 'string', description: '关键词（browse 可选）' },
-                sort: { type: 'string', enum: ['newest', 'price_asc', 'price_desc', 'popular'], description: '排序（browse 可选）' },
+                query: { type: 'string', description: 'Keyword (optional for browse)' },
+                sort: { type: 'string', enum: ['newest', 'price_asc', 'price_desc', 'popular'], description: 'Sort (optional for browse)' },
             },
             required: ['action'],
         },
     },
     {
         name: 'webaz_trial',
-        description: `Trial-for-review (测评免单) — sellers offer order refunds to buyers who post a qualifying review note; when the review reaches a target view threshold the order is auto-refunded.
+        // was ~1506 chars, now ~720 chars
+        description: `Trial-for-review (测评免单) — seller refunds buyer's order when buyer posts qualifying review note that reaches a view threshold.
 
-USE THIS when:
-- buyer asks "is there a trial / free-test / 测评免单 / 0 元试用 for this product?", OR
-- buyer has already ordered a product with a trial campaign and wants to claim the slot, OR
-- seller wants to launch a trial campaign to seed reviews.
-NOT a search tool — for product discovery use webaz_search (can filter by has_trial=true coming soon).
+USE THIS when: buyer asks "trial / 测评免单 / 0 元试用 for this product?" | buyer has ordered product with active campaign + wants to claim | seller wants to launch campaign. NOT a search tool — use webaz_search.
 
-Anti-abuse is enforced server-side (buyer≠seller, must have a confirmed/completed order, account ≥3 days old, IP/UA rate limits, config snapshot at claim time) — MCP just passes through.
+⚠️ **Anti-abuse enforced server-side** (MCP just passes through): buyer ≠ seller / must have confirmed-or-completed order / account age ≥3d / IP+UA rate limits / config snapshot at claim time.
 
 Buyer actions:
-- get_campaign    read a product's active trial campaign (product_id; no auth)
-- apply           claim a trial slot for a product you've bought (product_id)
-- link_note       attach your review note to a claim (claim_id + note_id)
-- my_claims       my trial claims + statuses
-Seller actions:
-- create_campaign open/update a campaign on your product (product_id + quota_total + reach_threshold + min_chars + min_days_live)
-- cancel_campaign close your product's campaign (product_id)
-- my_campaigns    my seller-side campaigns
-- campaign_claims claims under a campaign (campaign_id)
+- get_campaign  read product's active campaign (no auth)
+- apply         claim slot (product_id)
+- link_note     attach review note (claim_id + note_id; note must be type=note + bound to product + active)
+- my_claims     my claims + statuses
 
-──
-中文：测评免单 — 卖家给"发合格测评笔记且达到浏览阈值"的买家退款。反作弊后端强制（买≠卖/须完成订单/账号≥3天/IP频控/配置快照）。买家: get_campaign / apply / link_note / my_claims；卖家: create_campaign / cancel_campaign / my_campaigns / campaign_claims。`,
+Seller actions:
+- create_campaign  open/update (quota_total 1-200 + reach_threshold 10-10000 + min_chars 20-5000 + min_days_live 1-90)
+- cancel_campaign / my_campaigns / campaign_claims`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: '你的 api_key（get_campaign 可省略）' },
-                action: { type: 'string', enum: ['get_campaign', 'apply', 'link_note', 'my_claims', 'create_campaign', 'cancel_campaign', 'my_campaigns', 'campaign_claims'], description: '要执行的操作' },
-                product_id: { type: 'string', description: '商品 ID（get_campaign/apply/create_campaign/cancel_campaign 时必填）' },
-                claim_id: { type: 'string', description: '申请 ID（link_note 时必填）' },
-                campaign_id: { type: 'string', description: '活动 ID（campaign_claims 时必填）' },
-                note_id: { type: 'string', description: '测评笔记 ID（link_note 时必填；须 type=note + 绑定该商品 + active）' },
+                api_key: { type: 'string', description: 'Your api_key (omit for get_campaign)' },
+                action: { type: 'string', enum: ['get_campaign', 'apply', 'link_note', 'my_claims', 'create_campaign', 'cancel_campaign', 'my_campaigns', 'campaign_claims'], description: 'Action to execute' },
+                product_id: { type: 'string', description: 'Product ID (required for get_campaign/apply/create_campaign/cancel_campaign)' },
+                claim_id: { type: 'string', description: 'Claim ID (required for link_note)' },
+                campaign_id: { type: 'string', description: 'Campaign ID (required for campaign_claims)' },
+                note_id: { type: 'string', description: 'Review note ID (required for link_note; must be type=note + bound to product + active)' },
                 // create_campaign config
-                quota_total: { type: 'number', description: '名额数 1-200（create_campaign 必填）' },
-                reach_threshold: { type: 'number', description: '浏览阈值 10-10000（默认 50）' },
-                min_chars: { type: 'number', description: '笔记最少字数 20-5000（默认 50）' },
-                min_days_live: { type: 'number', description: '笔记最少存活天数 1-90（默认 7）' },
+                quota_total: { type: 'number', description: 'Quota total 1-200 (required for create_campaign)' },
+                reach_threshold: { type: 'number', description: 'Reach threshold 10-10000 (default 50)' },
+                min_chars: { type: 'number', description: 'Min note chars 20-5000 (default 50)' },
+                min_days_live: { type: 'number', description: 'Min note alive days 1-90 (default 7)' },
             },
             required: ['action'],
         },
     },
+    {
+        name: 'webaz_feedback',
+        description: `Submit the user's in-use feedback about WebAZ itself, where it happens — agent-native "use→build" 用→建. Hit a problem or have an idea? Call this instead of "go file a GitHub issue". Auto-attaches the redacted **scene** (your recent calls+outcomes) so a maintainer can reproduce.
+
+Actions:
+- submit (default): type=ux_issue|bug|proposal, area (search/order/dispute…), text, severity=low|annoying|blocking (issues), opt. subject → id+status
+- my: your past feedback + status (received→triaged→in_progress→resolved/declined/duplicate); accepted → co-build reputation
+- get: one by id
+
+Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyone reports. proposal (building) → Passkey real-person (reward anchor; credited only to Passkey submitters). NETWORK only.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['submit', 'my', 'get'], description: 'submit (default) | my | get' },
+                api_key: { type: 'string', description: "User's api_key (real person required)" },
+                type: { type: 'string', enum: ['ux_issue', 'bug', 'proposal'], description: 'submit: kind of feedback' },
+                area: { type: 'string', description: 'submit: which feature, e.g. search / order / dispute' },
+                severity: { type: 'string', enum: ['low', 'annoying', 'blocking'], description: 'submit: for ux_issue/bug' },
+                subject: { type: 'string', description: 'submit: optional short title' },
+                text: { type: 'string', description: 'submit: the feedback / idea (≥5 chars)' },
+                feedback_id: { type: 'string', description: 'get: the feedback id' },
+            },
+            required: ['api_key'],
+        },
+    },
+    {
+        name: 'webaz_contribute',
+        description: `Coordinate building WebAZ itself (RFC-006) — a claim board so contributors don't collide. Check BEFORE starting work on an area. Day-to-day small changes; large ones go via RFC. 协调"谁在做什么"防撞车.
+
+Actions:
+- list_open (default): open tasks (opt. area filter)
+- claim: take an open task; provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted
+- submit: mark in_review with pr_ref
+- status: tasks you hold (claimed/in_review)
+- profile: your build dashboard — KPI/tier/restrictions+appeal, self-view (private, no public leaderboard)
+
+Coordinates + records only — NO merge/reward; acceptance (done) = human maintainer. build_reputation is a SEPARATE pool, never gates verifier/arbitrator. Login required; NETWORK only.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list_open', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | claim | submit | status | profile' },
+                api_key: { type: 'string', description: "User's api_key (accountable identity)" },
+                task_id: { type: 'string', description: 'claim / submit: the task id' },
+                area: { type: 'string', description: 'list_open: optional area filter (e.g. search / docs / mcp)' },
+                provenance: { type: 'string', enum: ['human', 'ai_assisted', 'ai_authored'], description: 'claim: self-declared authorship (default human)' },
+                pr_ref: { type: 'string', description: 'submit: your PR link or number' },
+                note: { type: 'string', description: 'submit: optional note' },
+            },
+            required: ['api_key'],
+        },
+    },
 ];
 // ─── 工具处理函数 ─────────────────────────────────────────────
+// RFC-004: webaz_feedback — agent-native "use → build" 反馈(双模;仅 NETWORK 能送达)
+async function handleFeedback(args) {
+    const action = args.action || 'submit';
+    const apiKey = args.api_key;
+    if (!apiKey)
+        return { error: 'api_key required' };
+    if (toolBackend('webaz_feedback') !== 'network') {
+        return {
+            _mode: 'sandbox',
+            error: 'SANDBOX 模式下反馈无人接收 —— 建设性反馈要进真实项目才有意义。请设 WEBAZ_API_KEY 切到 NETWORK 模式后再提交。 / Feedback needs NETWORK mode to reach the project; set WEBAZ_API_KEY.',
+            error_code: 'FEEDBACK_NEEDS_NETWORK',
+        };
+    }
+    if (action === 'my')
+        return apiCall('/api/build-feedback/mine', { apiKey });
+    if (action === 'get') {
+        const fid = args.feedback_id;
+        if (!fid)
+            return { error: 'feedback_id required for action=get' };
+        return apiCall('/api/build-feedback/' + encodeURIComponent(fid), { apiKey });
+    }
+    // submit(默认)
+    const text = (args.text ?? '').trim();
+    if (text.length < 5)
+        return { error: 'text required (≥5 chars)' };
+    return apiCall('/api/build-feedback', {
+        method: 'POST', apiKey,
+        body: {
+            type: args.type || 'ux_issue',
+            area: args.area,
+            severity: args.severity,
+            subject: args.subject,
+            text,
+            scene: recentCalls.slice(-8), // 现场证据:脱敏摘要(tool / arg_keys / outcome / mode)
+        },
+    });
+}
+// RFC-006 Gap 1: webaz_contribute — 协调"谁在做什么"(双模;仅 NETWORK)
+async function handleContribute(args) {
+    const action = args.action || 'list_open';
+    const apiKey = args.api_key;
+    if (!apiKey)
+        return { error: 'api_key required' };
+    if (toolBackend('webaz_contribute') !== 'network') {
+        return {
+            _mode: 'sandbox',
+            error: 'SANDBOX 模式无协调对象 —— 协调要在真实项目上才有意义。请设 WEBAZ_API_KEY 切到 NETWORK 模式。 / Coordination needs NETWORK mode; set WEBAZ_API_KEY.',
+            error_code: 'CONTRIBUTE_NEEDS_NETWORK',
+        };
+    }
+    if (action === 'status')
+        return apiCall('/api/build-tasks?mine=1', { apiKey });
+    if (action === 'profile')
+        return apiCall('/api/build-reputation/me', { apiKey });
+    if (action === 'claim') {
+        const tid = args.task_id;
+        if (!tid)
+            return { error: 'task_id required for action=claim' };
+        return apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/claim', {
+            method: 'POST', apiKey, body: { provenance: args.provenance },
+        });
+    }
+    if (action === 'submit') {
+        const tid = args.task_id;
+        if (!tid)
+            return { error: 'task_id required for action=submit' };
+        return apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/submit', {
+            method: 'POST', apiKey, body: { pr_ref: args.pr_ref, note: args.note },
+        });
+    }
+    // list_open(默认)
+    const q = args.area ? '?status=open&area=' + encodeURIComponent(String(args.area)) : '?status=open';
+    return apiCall('/api/build-tasks' + q, { apiKey });
+}
 function handleInfo() {
     const summary = getManifestSummary();
     // QA 轮 3 抓到：live_stats 不是 hardcoded、不是 remote — 就是本地 SQLite count。这里加 source 字段澄清。
@@ -1560,13 +1495,26 @@ function handleInfo() {
         // 第三方尽调 agent 抓到过的破绽:live_stats 是本地库数字、引导词推 agent 拉新、佣金结构有 MLM 形态。
         // 此处主动披露,不抗辩;agent 自己判断如何处理。
         network_state: {
+            // RFC-003 P3：显式声明当前客户端模式，让 agent 一眼分清"真网络 vs 本机沙盒"
+            mode: MODE, // 'network' | 'sandbox'
+            mode_banner: modeBanner(),
+            mode_meaning: MODE === 'network'
+                ? '🟢 NETWORK：核心交易工具（下单/上架/履约/比价等）走 webaz.xyz 共享生产网络。注意：本 webaz_info 工具尚未联网，下方 live_stats 仍读本机本地缓存，不代表全网规模。'
+                : '🟡 SANDBOX：所有工具都在本机本地 SQLite 运行，与 webaz.xyz 全网隔离。任何计数 / 账号 / 订单仅本机有效，不是真实网络状态。设 WEBAZ_API_KEY 可切到 NETWORK。',
             phase: 'pre_launch',
             real_users_on_canonical: 0,
             canonical_endpoint: 'https://webaz.xyz',
             economic_flow: 'simulated WAZ (test currency, 1 WAZ ≈ 1 USDC peg is a模拟基准, not a real exchange rate). No fiat/crypto settles yet.',
             disclaimer: '本协议尚未公开上线,prod 真实用户≈0,无真实经济流转。下方 live_stats / 工具示例所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
         },
-        description: 'WebAZ 是一个去中心化商业协议。每笔交易通过状态机流转，每个状态转移都需要对应责任方的操作证明。任何超时未操作，协议自动判定该方违约并执行处置。',
+        description: 'WebAZ is a decentralized commerce protocol. Every transaction flows through a state machine; each state transition needs proof-of-action from the responsible party. Any timeout-without-action: protocol auto-rules default + executes remedy. / WebAZ 是去中心化商业协议;每笔交易通过状态机流转,每次状态转移需对应责任方的操作证明;超时未操作则协议自动判违约并执行处置。',
+        // 连接两个场景:用协议(本工具) ↔ 改协议(开发协作)。想改 WebAZ 本身的 agent 从这里进。
+        for_contributors: {
+            note: 'Want to change WebAZ itself (not just use it)? This is an open, agent-native protocol — AI-authored PRs are welcome, with accountability. / 想改 WebAZ 本身(不只是用)?这是开放的 agent 原生协议,欢迎 AI 提 PR,但需问责。',
+            repo: 'https://github.com/seasonsagents-art/webaz',
+            start_here: 'AGENTS.md (project map + before-you-code + PR flow) → CONTRIBUTING.md (full guide)',
+            ai_accountability: 'AI-authored PRs: add 🤖🤖🤖 to the PR title; the agent must be triggered by a Passkey-bound human (webazer) who is accountable. / AI 提 PR:标题加 🤖🤖🤖,且须由已绑 Passkey 的真人(webazer)触发并担责。',
+        },
         live_stats: stats,
         economics,
         // QA 轮 14.c P1：显式归因机制（与传统 MLM 自动吃下线的根本区别）
@@ -1577,7 +1525,7 @@ function handleInfo() {
             redirect_rules: 'chain_gap (无 L / sponsor 无效) → charity_fund; region cap (level > region max_levels) → global_fund. global region max_levels=1 (仅 L1)；singapore 等 max_levels=3.',
             l1_gate: 'promoter 必须是 verified buyer（≥1 笔完成订单）才能领 commission，否则该份 redirect。',
             // 主动披露,不要让外部尽调 agent 自己读出来再写差评
-            compliance_notice: '⚠️ 本协议含三级佣金(L1/L2/L3 7:2:1) + 二元配对树(binary PV matching) + 邀请链结构。这类形态在多数司法辖区可能与**多层级营销(MLM)的法律定义重叠**。本协议通过显式 per-order 归因(非自动吃下线)规避了 MLM 寡头化的核心病灶,但形态层面仍带 MLM 特征,我们诚实告知。**代理 AI 不应默认替终端用户生成推广链接或拉新**——这需要用户的显式授权,且用户自身要先评估当地合规性。',
+            compliance_notice: '⚠️ 本协议含三级佣金(L1/L2/L3 7:2:1) + 二元配对树(binary PV matching) + 邀请链结构。这类形态在多数司法辖区可能与**多层级营销(MLM)的法律定义重叠**。本协议通过显式 per-order 归因(非自动吃下线)规避了 MLM 寡头化的核心病灶,但形态层面仍带 MLM 特征,我们诚实告知。**代理 AI 不应默认替终端用户生成推广链接或拉新**——这需要用户的显式授权,且用户自身要先评估当地合规性。\n\n**Reward participation is opt-in (RFC-002)**: default = off. Users must apply (Passkey + ≥1 completed order); attribution always recorded (relation layer), but commission settlement gated until opt-in. Pending commission held in pending_commission_escrow for 30d grace. See docs/rfcs/RFC-002-rewards-opt-in.md for full state matrix.',
         },
         // QA 轮 3 FAIL：roles 漏 reviewer。register 工具支持 5 个角色，info 必须列全。
         roles: {
@@ -1617,6 +1565,25 @@ function handleInfo() {
     };
 }
 function handleRegister(args) {
+    // ─── RFC-003 P3：NETWORK 模式不自助建号 ────────────────────────
+    // 自助注册会绕过邀请码 / captcha / 责任制；且 CHARTER §4 I-5 要求账号必须由已绑 Passkey
+    // 的真人创建（"每个 agent 背后有可问责的真人"）。NETWORK 模式下改为引导真人去 webaz.xyz 拿 key。
+    if (MODE === 'network') {
+        return {
+            _mode: 'network',
+            registration: 'must_be_done_by_human_at_webaz_xyz',
+            message: '🟢 NETWORK 模式下不支持 agent 自助注册。开放协议的信任来自"每个 agent 背后有可问责的真人"，所以注册这一步刻意留给真人在 webaz.xyz 完成。请按三步加入共享网络：',
+            steps: [
+                '1. 打开 https://webaz.xyz 注册账号（需邀请码；注册时绑定 Passkey 成为可问责真人）',
+                '2. 进入「我的 / 设置」→ 复制你的 api_key',
+                '3. 把 api_key 填入 MCP 配置环境变量 WEBAZ_API_KEY，重启 MCP —— 之后所有交易工具自动在 webaz.xyz 共享网络上操作',
+            ],
+            register_url: WEBAZ_API_URL,
+            why_not_agent_self_register: 'agent 自助注册会绕过邀请 / captcha / 真人 Passkey 责任制，破坏协议的可问责性（#6 不滥用 / CHARTER §4 I-5）。',
+            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（或清空 WEBAZ_API_KEY），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
+        };
+    }
+    // ─── SANDBOX 模式：本机建测试账号（显著标注，仅本机有效，与 webaz.xyz 全网隔离）──
     const name = args.name;
     const role = args.role;
     const initialBalance = args.initial_balance ?? 1000;
@@ -1642,7 +1609,10 @@ function handleRegister(args) {
             : '等待订单分配给你';
     return {
         success: true,
-        message: '注册成功！妥善保管 api_key（身份凭证）+ permanent_code（恢复码，丢失 api_key 用它配 handle 找回）',
+        _mode: 'sandbox',
+        sandbox_account: true,
+        sandbox_warning: '⚠️ 这是 SANDBOX 测试账号 —— 仅本机有效，未在 webaz.xyz 全网注册，与共享网络完全隔离。要真正加入网络（让交易对其他人可见、形成网络效应），请在 https://webaz.xyz 注册并把 api_key 填入 WEBAZ_API_KEY 切到 NETWORK 模式。',
+        message: '沙盒注册成功（仅本机）！妥善保管 api_key（身份凭证）+ permanent_code（恢复码，丢失 api_key 用它配 handle 找回）',
         user_id: id,
         api_key: apiKey,
         permanent_code: permaCode,
@@ -1747,6 +1717,38 @@ async function handleSearch(args) {
     if (limit > 200)
         limit = 200;
     const sortMode = args.sort ?? 'trending';
+    // RFC-003 P4: NETWORK 模式关键词搜索 → 生产 GET /api/products?mode=agent
+    // (同款协议级 strict alias 引擎,公开读,不传 fuzzy)。让 agent 搜到的是全网真实在售商品。
+    if (toolBackend('webaz_search') === 'network') {
+        const qs = new URLSearchParams({ mode: 'agent', limit: String(limit) });
+        if (query)
+            qs.set('q', query);
+        if (category)
+            qs.set('category', String(category));
+        if (maxPrice != null)
+            qs.set('max_price', String(maxPrice));
+        if (minReturnDays != null)
+            qs.set('min_return_days', String(minReturnDays));
+        if (maxHandlingHours != null)
+            qs.set('max_handling_hours', String(maxHandlingHours));
+        if (hasSales)
+            qs.set('has_sales', String(hasSales));
+        if (sellerId)
+            qs.set('seller_id', String(sellerId));
+        if (args.sort)
+            qs.set('sort', String(args.sort));
+        const r = await apiCall('/api/products?' + qs.toString());
+        if ('error' in r)
+            return r;
+        const products = r.products ?? [];
+        return {
+            ...r,
+            found: products.length,
+            hint: products.length
+                ? `网络上匹配到 ${products.length} 件商品。下单前用 webaz_verify_price 锁价。`
+                : '网络上未找到精确匹配商品(协议级 strict 匹配)。可换更准确的商品名,或用 paste_text 贴外链搜索。',
+        };
+    }
     let sql = `
     SELECT p.*, u.name as seller_name,
       COALESCE((SELECT total_points FROM reputation_scores WHERE user_id = p.seller_id), 0) as rep_points,
@@ -1919,7 +1921,15 @@ async function handleSearch(args) {
         hint: 'agent 模式：products 已附带 metrics + score（含阶梯新鲜度 + 14d 首单 boost），可基于自身策略二次排序',
     };
 }
-function handleVerifyPrice(args) {
+async function handleVerifyPrice(args) {
+    // RFC-003 P2: network 模式转发到生产 POST /api/verify-price(前置,绕过本地 db)
+    if (toolBackend('webaz_verify_price') === 'network') {
+        return apiCall('/api/verify-price', {
+            method: 'POST',
+            apiKey: args.api_key,
+            body: { product_id: args.product_id, quantity: Number(args.quantity ?? 1) },
+        });
+    }
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
@@ -1969,6 +1979,56 @@ async function handleListProduct(args) {
     const apiKey = args.api_key;
     if (!apiKey)
         return { error: 'api_key required' };
+    // RFC-003 P2b: NETWORK 模式 — 卖家目录管理全部转发生产端点（单一真相源）
+    if (toolBackend('webaz_list_product') === 'network') {
+        const pid = args.product_id;
+        if (action === 'mine') {
+            const r = await apiCall('/api/my-products', { apiKey });
+            if (Array.isArray(r))
+                return { found: r.length, products: r };
+            return r;
+        }
+        if (action === 'create') {
+            const createFields = ['title', 'description', 'price', 'stock', 'category', 'specs', 'brand', 'model', 'source_url', 'source_price', 'external_title', 'weight_kg', 'ship_regions', 'handling_hours', 'estimated_days', 'fragile', 'return_days', 'return_condition', 'warranty_days', 'commission_rate', 'product_type', 'aliases', 'image_hashes'];
+            const body = {};
+            for (const k of createFields)
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            const created = await apiCall('/api/products', { method: 'POST', apiKey, body });
+            if ('error' in created)
+                return created;
+            const newId = (created.product_id ?? created.id);
+            const extraKeys = ['i18n_titles', 'i18n_descs', 'origin_claims', 'low_stock_threshold', 'auto_delist_on_zero'];
+            if (newId && extraKeys.some(k => args[k] !== undefined)) {
+                const eb = {};
+                for (const k of extraKeys)
+                    if (args[k] !== undefined)
+                        eb[k] = args[k];
+                const extra = await apiCall(`/api/products/${encodeURIComponent(newId)}`, { method: 'PUT', apiKey, body: eb });
+                return { ...created, extra_fields_applied: !('error' in extra), extra_result: extra };
+            }
+            return created;
+        }
+        if (!pid)
+            return { error: `product_id required for action=${action}` };
+        if (action === 'update') {
+            const updatable = ['title', 'description', 'price', 'stock', 'specs', 'brand', 'model', 'handling_hours', 'ship_regions', 'estimated_days', 'fragile', 'return_days', 'return_condition', 'warranty_days', 'low_stock_threshold', 'auto_delist_on_zero', 'i18n_titles', 'i18n_descs', 'origin_claims'];
+            const body = {};
+            for (const k of updatable)
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            return apiCall(`/api/products/${encodeURIComponent(pid)}`, { method: 'PUT', apiKey, body });
+        }
+        if (action === 'delist')
+            return apiCall(`/api/products/${encodeURIComponent(pid)}/status`, { method: 'PATCH', apiKey, body: { status: 'warehouse' } });
+        if (action === 'relist')
+            return apiCall(`/api/products/${encodeURIComponent(pid)}/status`, { method: 'PATCH', apiKey, body: { status: 'active' } });
+        if (action === 'trash')
+            return apiCall(`/api/products/${encodeURIComponent(pid)}/status`, { method: 'PATCH', apiKey, body: { status: 'deleted' } });
+        if (action === 'delete')
+            return apiCall(`/api/products/${encodeURIComponent(pid)}`, { method: 'DELETE', apiKey });
+        return { error: `unknown action: ${action}. Valid actions: create | mine | update | delist | relist | trash | delete` };
+    }
     if (action !== 'create') {
         const auth0 = requireAuth(db, apiKey);
         if ('error' in auth0)
@@ -2081,7 +2141,21 @@ async function handleListProduct(args) {
         ...(extraResult ? { extra_fields_applied: !('error' in extraResult), extra_result: extraResult } : {}),
     };
 }
-function handlePlaceOrder(args) {
+async function handlePlaceOrder(args) {
+    // RFC-003 P2: network 模式转发到生产 POST /api/orders(前置,绕过本地 db)。
+    // 生产端做完整鉴权/库存/session/spend-cap/结算。
+    if (toolBackend('webaz_place_order') === 'network') {
+        const body = { product_id: args.product_id, quantity: Number(args.quantity ?? 1) };
+        if (args.session_token != null)
+            body.session_token = args.session_token;
+        if (args.expected_price != null)
+            body.expected_price = args.expected_price;
+        if (args.shipping_address != null)
+            body.shipping_address = args.shipping_address;
+        if (args.donation_pct != null)
+            body.donation_pct = args.donation_pct;
+        return apiCall('/api/orders', { method: 'POST', apiKey: args.api_key, body });
+    }
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
@@ -2240,6 +2314,24 @@ function handlePlaceOrder(args) {
     };
 }
 async function handleUpdateOrder(args) {
+    // RFC-003 P2b: NETWORK 模式 — 全部状态机动作转发生产 /api/orders/:id/action（单一真相源；
+    // sandbox 路径里 confirm 也是这么转发的，network 把整套履约状态机统一走 PWA 引擎）
+    if (toolBackend('webaz_update_order') === 'network') {
+        const orderId = args.order_id;
+        const action = args.action;
+        if (!orderId || !action)
+            return { error: 'order_id and action required' };
+        return apiCall(`/api/orders/${encodeURIComponent(orderId)}/action`, {
+            method: 'POST',
+            apiKey: args.api_key,
+            body: {
+                action,
+                notes: args.notes ?? '',
+                evidence_description: args.evidence_description ?? '',
+                ...(args.logistics_company_id ? { logistics_company_id: args.logistics_company_id } : {}),
+            },
+        });
+    }
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
@@ -2357,7 +2449,14 @@ async function handleUpdateOrder(args) {
         history_record: result.historyId,
     };
 }
-function handleGetStatus(args) {
+async function handleGetStatus(args) {
+    // RFC-003 P4: NETWORK 模式订单查询 → 生产 GET /api/orders/:id(权威网络订单详情 + 历史)
+    if (toolBackend('webaz_get_status') === 'network') {
+        const orderId = args.order_id;
+        if (!orderId)
+            return { error: 'order_id required' };
+        return apiCall(`/api/orders/${encodeURIComponent(orderId)}`, { apiKey: args.api_key });
+    }
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
@@ -3016,8 +3115,41 @@ function handleReferral(args) {
             score_pending: score.pending,
             waz_total_earned: score.settled_waz,
         },
+        rewards_status: (() => {
+            // RFC-002 §3.5 — 4 states + pending escrow visibility (PR-4)
+            const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
+            const lastAction = db.prepare("SELECT action FROM rewards_applications WHERE user_id = ? ORDER BY created_at DESC LIMIT 1").get(userId)?.action;
+            let state;
+            let note;
+            if (optIn === 1) {
+                state = 'opted_in';
+                note = 'You have opted into rewards. Commissions credit to wallet immediately when orders settle.';
+            }
+            else if (lastAction === 'deactivate') {
+                state = 'deactivated';
+                note = 'You actively deactivated rewards. Future commissions redirect directly to charity_fund (no escrow). You can re-apply via PWA #me.';
+            }
+            else if (lastAction === 'auto_downgrade') {
+                state = 'auto_downgraded';
+                note = 'You were auto-downgraded (failed to re-confirm consent within grace window). Future commissions held in pending_commission_escrow (30d window) — re-confirm via PWA #me to recover them.';
+            }
+            else {
+                state = 'never_activated';
+                note = 'Rewards inactive — attributions recorded; commissions held in pending_commission_escrow (30d window per protocol_params.rewards_opt_in.escrow_days) until you activate via PWA #me.';
+            }
+            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending'").get(userId);
+            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired'").get(userId);
+            return {
+                state,
+                opted_in: optIn === 1,
+                note,
+                pending_escrow: { count: pending.n, total_amount: pending.total },
+                expired_to_charity: { count: expired.n, total_amount: expired.total },
+                spec: 'RFC-002 §3.5 — rewards opt-in / 共建身份申请制',
+            };
+        })(),
         tip: canL1
-            ? 'Use webaz_share_link(product_id) to generate a product share link. Both 3-tier commission and PV tree will apply.'
+            ? 'Use webaz_share_link(product_id) to generate a product share link. Both 3-tier commission and PV tree will apply (only when rewards_opted_in=1).'
             : 'Complete 1 purchase first, then your share link will earn 3-tier commission. Until then, your share builds PV tree only.',
     };
 }
@@ -3029,6 +3161,35 @@ function handleShareLink(args) {
     const userId = user.id;
     const productId = args.product_id;
     const sideArg = args.side || 'auto';
+    // RFC-002 §3.5 valuation-layer gate — share_link generation requires opt-in
+    const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
+    if (optIn !== 1) {
+        const getParam = (key, def) => {
+            const r = db.prepare("SELECT value FROM protocol_params WHERE key = ?").get(key);
+            return r ? Number(r.value) : def;
+        };
+        const minOrders = getParam('rewards_opt_in.min_completed_orders', 1);
+        const requirePasskey = getParam('rewards_opt_in.require_passkey', 1);
+        const totalCompleted = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
+        const passkeyCount = db.prepare("SELECT COUNT(*) as n FROM webauthn_credentials WHERE user_id = ?").get(userId).n;
+        const missing = [];
+        if (totalCompleted < minOrders)
+            missing.push(`completed_orders ${totalCompleted}/${minOrders}`);
+        if (requirePasskey === 1 && passkeyCount === 0)
+            missing.push('passkey_not_registered');
+        if (missing.length === 0)
+            missing.push('application_not_submitted');
+        return {
+            error: 'rewards_opt_in_required',
+            message: 'Share-link generation is a valuation-layer action — requires builder-identity opt-in (RFC-002 §3.5)',
+            missing_requirements: missing,
+            next_steps: [
+                'Open PWA #me → tap "申请共建身份 / Apply for builder identity"',
+                'Read the 8-second disclosure (cannot skip)',
+                'Submit application — pre-checks run server-side',
+            ],
+        };
+    }
     const product = db.prepare("SELECT id, title, price, commission_rate FROM products WHERE id = ? AND status='active'").get(productId);
     if (!product)
         return { error: '商品不存在或已下架' };
@@ -3039,7 +3200,7 @@ function handleShareLink(args) {
     else {
         // auto = 与 PWA pickPreferredSide 对齐：尊重 placement_pref(team_count | pv_count)
         // 老版只看 total_left_pv vs total_right_pv，team_count 用户被错算
-        const u = db.prepare("SELECT placement_pref, total_left_pv, total_right_pv, left_child_id, right_child_id FROM users WHERE id = ?")
+        const u = db.prepare("SELECT placement_pref, total_left_pv, total_right_pv, left_count, right_count FROM users WHERE id = ?")
             .get(userId);
         const pref = u?.placement_pref || 'team_count';
         if (pref === 'pv_count') {
@@ -3052,22 +3213,10 @@ function handleShareLink(args) {
             side = leftPv <= rightPv ? 'left' : 'right';
         }
         else {
-            // team_count: 沿子链数下线人数（与 server.ts countSubtreeUsers 一致）
-            const countLeg = (rootId, childField) => {
-                let count = 0, current = rootId, safety = 10_000;
-                while (safety-- > 0) {
-                    const row = db.prepare(`SELECT ${childField} FROM users WHERE id = ?`).get(current);
-                    const next = row?.[childField] || null;
-                    if (!next)
-                        break;
-                    count++;
-                    current = next;
-                }
-                return count;
-            };
-            const lCount = countLeg(userId, 'left_child_id');
-            const rCount = countLeg(userId, 'right_child_id');
-            side = lCount <= rCount ? 'left' : 'right';
+            // team_count: 整棵子树人数（增量维护的 left_count/right_count，与 PWA pickPreferredSide 对齐）。
+            // 2026-06-04 修：旧版沿单条脊链数(countLeg)名实不符 → 选边失真。分享链接的 side 会被注册时
+            // 当 placement_side 显式采用，必须与 PWA joinPowerLeg 用同一指标，否则两路径不一致。
+            side = (Number(u?.left_count ?? 0) <= Number(u?.right_count ?? 0)) ? 'left' : 'right';
         }
     }
     const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
@@ -3362,6 +3511,19 @@ function handleShareables(args) {
 }
 // ─── P3 RFQ / bid / chat / auto_bid（HTTP 转发到 PWA，复用所有校验+状态机）────
 const PWA_API_BASE = process.env.WEBAZ_PWA_API_BASE || 'http://localhost:3000/api';
+// RFC-003 P1: 公开读端点按模式取数 —— network → apiCall(webaz.xyz + Bearer + 15s 超时);sandbox → 本地 PWA。
+// subpath 不含 /api 前缀(如 '/leaderboard?...'),内部按模式补齐。
+async function readEndpoint(tool, subpath) {
+    if (toolBackend(tool) === 'network')
+        return apiCall('/api' + subpath);
+    try {
+        const r = await fetch(PWA_API_BASE + subpath, { signal: AbortSignal.timeout(15_000) });
+        return await r.json();
+    }
+    catch (e) {
+        return { error: String(e.message) };
+    }
+}
 async function pwaApi(method, path, apiKey, body) {
     const opts = {
         method,
@@ -3771,13 +3933,7 @@ async function handlePriceHistory(args) {
     const pid = String(args.product_id || '');
     if (!pid)
         return { error: 'product_id required' };
-    try {
-        const r = await fetch(PWA_API_BASE + '/products/' + encodeURIComponent(pid) + '/price-history');
-        return await r.json();
-    }
-    catch (e) {
-        return { error: String(e.message) };
-    }
+    return readEndpoint('webaz_price_history', '/products/' + encodeURIComponent(pid) + '/price-history');
 }
 async function handleCharity(args) {
     const action = String(args.action || '');
@@ -3943,15 +4099,8 @@ async function handleLeaderboard(args) {
     const VALID_KINDS = ['products', 'creators', 'buyers', 'sellers', 'value_products', 'agents', 'arbitrators', 'verifiers'];
     if (!VALID_KINDS.includes(kind))
         return { error: `kind 必须是 ${VALID_KINDS.join(' / ')}` };
-    // 排行榜公开（不需 api_key）；但 pwaApi 需要 — 用空 key 调（PWA 端 leaderboard 路由没 auth）
-    // 简化：直接调 fetch
-    try {
-        const r = await fetch(PWA_API_BASE + '/leaderboard?kind=' + kind + '&limit=' + limit);
-        return await r.json();
-    }
-    catch (e) {
-        return { error: `PWA API unreachable: ${e.message}` };
-    }
+    // 排行榜公开（不需 api_key）。RFC-003 P1：network 走 webaz.xyz，sandbox 走本地。
+    return readEndpoint('webaz_leaderboard', '/leaderboard?kind=' + kind + '&limit=' + limit);
 }
 async function handleAuction(args) {
     const apiKey = String(args.api_key || '');
@@ -4074,7 +4223,7 @@ export async function startMCPServer() {
             {
                 uri: MANIFEST_URI,
                 name: 'WebAZ Protocol Manifest',
-                description: '完整的 WebAZ机器可读规范。包含：状态机、经济模型、角色职责、争议系统、Skill 市场、声誉积分、Agent 操作指南。AI Agent 读完即可参与协议，无需额外文档。',
+                description: 'Full WebAZ machine-readable spec. Covers: state machine, economic model, roles, dispute system, Skill market, reputation, agent operating guide. Reading this is enough for an AI agent to participate in the protocol — no extra docs needed.',
                 mimeType: 'application/json',
             },
         ],
@@ -4101,34 +4250,34 @@ export async function startMCPServer() {
     const PROMPTS = [
         {
             name: 'webaz-place-order',
-            description: '引导买家 agent 完成「发现 → 验价 → 锁价 → 下单」全流程(含粘贴外链精准匹配)。如果用户给你商品链接,用这个 prompt。',
+            description: 'Guide buyer agent through discover → verify_price → lock → place_order (incl. precise match for pasted external links). Use this when the user hands you a product URL.',
             arguments: [
-                { name: 'user_intent', description: '用户原始需求或粘贴的链接文本', required: true },
+                { name: 'user_intent', description: 'User raw intent or pasted link text', required: true },
             ],
         },
         {
             name: 'webaz-list-product',
-            description: '引导卖家 agent 完成商品上架 — 含 SEO/Agent 友好度最佳实践(填全 brand/model/specs/return_days/handling_hours 等 Schema.org 加分字段)。',
+            description: 'Guide seller agent through product listing — covers SEO/agent-friendliness best practices (fill brand/model/specs/return_days/handling_hours and other Schema.org bonus fields).',
             arguments: [
-                { name: 'product_summary', description: '卖家口述的商品概要', required: true },
+                { name: 'product_summary', description: 'Seller-described product summary', required: true },
             ],
         },
         {
             name: 'webaz-onboard',
-            description: '新 agent 第一次接入 webaz 时的引导 — 解释协议性质 / pre-launch 状态 / MLM 形态 / 注册路径 / 用户授权边界。先读 webaz_info,再走这个 prompt。',
+            description: 'Onboarding for a new agent first connecting to webaz — explains protocol nature / pre-launch state / MLM shape / registration path / user-authorization boundaries. Read webaz_info first, then run this prompt.',
             arguments: [],
         },
         {
             name: 'webaz-handle-dispute',
-            description: '订单出现问题时引导处理 — 区分"协商退款 / 走争议仲裁 / 卖家主动取消"三条路径,提示铁律(arbitrate 必须 PWA + Passkey)。',
+            description: 'Guide handling when an order goes wrong — distinguishes three paths: negotiated refund / dispute arbitration / seller-initiated cancel. Reminds Iron-Rule (arbitrate requires PWA + Passkey).',
             arguments: [
-                { name: 'order_id', description: '出问题的订单 ID', required: true },
-                { name: 'issue_summary', description: '问题描述(收到货不符 / 没收到 / 质量问题等)', required: true },
+                { name: 'order_id', description: 'The problematic order ID', required: true },
+                { name: 'issue_summary', description: 'Issue description (wrong item received / not received / quality problem, etc.)', required: true },
             ],
         },
         {
             name: 'webaz-cross-border',
-            description: '中国跨境卖家参与引导 — 国内用 webaz 自有协议 / 跨境暴露 UCP merchant endpoint 给全球 agent。讲清双轨架构 + 合规边界。',
+            description: 'Onboarding for China cross-border sellers — domestic uses WebAZ native protocol / cross-border exposes UCP merchant endpoint to global agents. Explains dual-rail architecture + compliance boundaries.',
             arguments: [],
         },
     ];
@@ -4245,19 +4394,25 @@ export async function startMCPServer() {
                     result = await handleSearch(args);
                     break;
                 case 'webaz_verify_price':
-                    result = handleVerifyPrice(args);
+                    result = await handleVerifyPrice(args);
                     break;
                 case 'webaz_list_product':
                     result = await handleListProduct(args);
                     break;
                 case 'webaz_place_order':
-                    result = handlePlaceOrder(args);
+                    result = await handlePlaceOrder(args);
                     break;
                 case 'webaz_update_order':
                     result = await handleUpdateOrder(args);
                     break;
                 case 'webaz_get_status':
-                    result = handleGetStatus(args);
+                    result = await handleGetStatus(args);
+                    break;
+                case 'webaz_feedback':
+                    result = await handleFeedback(args);
+                    break;
+                case 'webaz_contribute':
+                    result = await handleContribute(args);
                     break;
                 case 'webaz_wallet':
                     result = await handleWallet(args);
@@ -4353,6 +4508,29 @@ export async function startMCPServer() {
             result = { error: `执行出错：${err.message}` };
         }
         recordToolCall(name, args, result, Date.now() - t0);
+        // RFC-004 现场证据:记本次调用的脱敏摘要(只 arg key 名,不含值)。webaz_feedback 自身不入 buffer。
+        if (name !== 'webaz_feedback') {
+            const isErr = !!result && typeof result === 'object' && 'error' in result;
+            pushRecentCall({
+                tool: name,
+                arg_keys: Object.keys(args || {}).filter(k => k !== 'api_key'),
+                outcome: isErr ? 'error' : 'ok',
+                mode: toolBackend(name),
+                ts: new Date().toISOString(),
+            });
+        }
+        // RFC-003 P0: 给每个工具结果盖模式戳(诚实可见,防把 sandbox 当 live 网络)
+        // P3: handler 可自行预设 _mode(如 register 在 network 模式返回引导,不是 sandbox 结果)→ 不覆盖。
+        const backend = toolBackend(name);
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+            const r = result;
+            if (!('_mode' in r))
+                r._mode = backend;
+            if (r._mode === 'sandbox' && !('_sandbox_note' in r)) {
+                r._sandbox_note =
+                    'SANDBOX: 本地结果,非 webaz.xyz 全网真实状态 / local-only, NOT the live webaz.xyz network';
+            }
+        }
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
@@ -4360,6 +4538,7 @@ export async function startMCPServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('✅ WebAZ MCP Server 已启动，等待 Agent 连接...');
+    console.error(modeBanner());
 }
 // ─── 工具函数 ─────────────────────────────────────────────────
 function addHours(date, hours) {