@seasonkoh/webaz 0.1.12 → 0.1.13

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

@@ -279,10 +279,15 @@ Note: paste-link matching hits webaz.xyz production data, not your local webaz.d
     },
     {
         name: 'webaz_verify_price',
-        description: `Lock product price before placing order — returns session_token.
-Recommended flow for agents: call this first to verify & lock price, then call webaz_place_order with session_token.
-Benefits: (1) order price matches displayed; (2) caller is alerted if price changed; (3) platform only liable for T0 price.
-session_token: 10-minute TTL, single-use.
+        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)
+
+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.
 
 ──
 中文：下单前锁价 — 10 分钟一次性 session_token；agent 应先调此再调 place_order。`,
@@ -298,8 +303,14 @@ session_token: 10-minute TTL, single-use.
     },
     {
         name: 'webaz_list_product',
-        description: `Seller product catalog management (create / update / shelf / archive / query own listings).
-Requires seller-role api_key. On create, system auto-suggests stake (~15% of price) to secure buyer protection.
+        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)
+
+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.
 
 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.
@@ -429,7 +440,9 @@ Missing any deadline auto-judges fault against the responsible party and trigger
     },
     {
         name: 'webaz_update_order',
-        description: `Update order status (each role can only perform their own actions).
+        description: `STATUS TRANSITIONS on an order (accept / ship / pickup / deliver / confirm / dispute) — NOT for editing order content (price/quantity/address are immutable after creation).
+
+USE THIS to advance an order through its lifecycle. Each role can only perform their own actions (see action list).
 
 Seller actions:
 - accept:  accept order (within 24h of payment)
@@ -486,7 +499,9 @@ Returns: current status, status history (who did what when), next responsible ac
     },
     {
         name: 'webaz_wallet',
-        description: `Wallet query (balance + earnings stats + deposit/withdrawal/income history).
+        description: `Wallet READ-ONLY query (balance + earnings stats + 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.
 
 Actions:
 - view         available balance + staked + in-escrow + total earnings + reputation tier (default)
@@ -494,9 +509,6 @@ Actions:
 - withdrawals  last 10 withdrawal requests (with status / tx_hash)
 - income       income breakdown: referral L1/L2/L3 + binary PV matching + sales net
 
-NOTE: actual withdrawals / deposits / whitelist management require Passkey + email OTP via PWA Web only.
-This is a security boundary — agents CANNOT bypass it. Use this tool for read-only queries only.
-
 ──
 中文：钱包查询（余额/收益/充提历史）。仅查询用，实际充提需 PWA Web + Passkey + 邮件 OTP，agent 不可绕过。`,
         inputSchema: {
@@ -532,7 +544,12 @@ Every status change (new order / ship / dispute / etc.) notifies relevant partic
     },
     {
         name: 'webaz_dispute',
-        description: `Manage dispute lifecycle (L3 dispute system).
+        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.
@@ -601,7 +618,12 @@ view / list_open / respond / add_evidence can be agent-proxied; only arbitrate n
     },
     {
         name: 'webaz_claim_verify',
-        description: `Crowd-sourced claim verification — no central arbitrator, 3 eligible verifiers reach consensus by vote.
+        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.
 
 When to use:
 - Buyer:   suspects a seller's product claim (e.g. "brand new sealed", "ships within 24h") → wants decentralized verification
@@ -670,12 +692,14 @@ Other actions (create / view / mine / available / eligibility / apply / appeal e
     },
     {
         name: 'webaz_skill',
-        description: `L4-4 Skill marketplace — sellers publish reusable seller-side behaviour configs; buyer Agents subscribe with one click.
+        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.
-This is NOT a product search — for "find me X" use webaz_search.
+
+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).
 
 ⚠️ 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.)
 
@@ -731,7 +755,9 @@ Actions:
     },
     {
         name: 'webaz_mykey',
-        description: `Confirm account existence by handle + permanent_code. Returns redacted api_key hint only — full api_key disclosure requires PWA + Passkey verification (Iron-Rule).
+        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).
+
+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).
 
 Rate-limited: 5 attempts per handle per hour. Excessive failures lock the handle for 1 hour.
 
@@ -798,13 +824,15 @@ Public-profile actions:
     },
     {
         name: 'webaz_revoke_key',
-        description: `Initiate api_key revocation. Iron-Rule: actual revocation requires PWA + Passkey confirmation — MCP only registers the intent and returns the PWA URL where you finish the action.
+        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.
 
-Use when:
-- Your api_key was leaked or you suspect unauthorized access
-- You are decommissioning an agent / device
+Use revoke (not rotate) when:
+- You are PERMANENTLY decommissioning this agent / device, OR
+- You want all access to die NOW with no fallback
 
-After PWA confirmation, the old api_key returns 401 on all tools. Plan ahead: have a new key (via webaz_rotate_key) before revoking, or you lose access.
+After PWA confirmation, the old api_key returns 401 on all tools.
 
 ──
 中文：发起 api_key 吊销。Iron-Rule：真正吊销必须 PWA + Passkey 二次确认（agent 不能单方面执行不可逆操作）。MCP 仅登记意图，返回 PWA 确认 URL。`,
@@ -943,7 +971,16 @@ to my address" — use webaz_search ship_to filter.`,
     },
     {
         name: 'webaz_shareables',
-        description: 'Manage your external content "shareables" (YouTube / TikTok / 小红书 / B 站 / IG / Twitter links bound to a product or anchor). WebAZ indexes only the URL, never the content bytes. Or query by product_id / anchor.',
+        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.
+
+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"
+
+Differs from webaz_share_link (which generates a NEW short link for sharing) — shareables register your EXISTING content as the discovery surface.
+
+──
+中文：把你在 YouTube/TikTok/小红书/B站/IG/Twitter 已发的内容(测评/开箱/推荐)锚定到 WebAZ 商品 —— 让你的外部内容变成赚 referral 佣金的入口。WebAZ 只锚 URL,不取内容。区别于 webaz_share_link(那个是生成新短链)。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1016,7 +1053,10 @@ Shipping address: if omitted, falls back to webaz_default_address (set via that
     },
     {
         name: 'webaz_bid',
-        description: `Bid on RFQs (seller-side).
+        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)
@@ -1044,7 +1084,9 @@ Actions:
     },
     {
         name: 'webaz_chat',
-        description: `Context-bound DM (no open DM — only order / rfq / listing_qa contexts allowed).
+        description: `Relay buyer↔seller (or RFQ partner) MESSAGES — context-bound DM, no open DM. Only order / rfq / listing_qa contexts allowed.
+
+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
@@ -1108,7 +1150,14 @@ Returns insufficient_data:true when data sparse.
     },
     {
         name: 'webaz_charity',
-        description: `Charity wish pool + repayment + community fund — double-anonymous + dual-signed anchoring + isolated prestige.
+        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).
+
+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)
@@ -1273,6 +1322,8 @@ Actions:
     {
         name: 'webaz_auto_bid',
         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.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools.",
   "main": "dist/mcp.js",
   "bin": {