@seasonkoh/webaz 0.1.25 → 0.1.27

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

@@ -43,6 +43,15 @@ const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() =
 // 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 ?? '';
+// F6 (dogfood R2): keyed MCP handlers resolve api_key as  explicit args.api_key  >  env WEBAZ_API_KEY  >
+// '' (→ the existing typed API_KEY_REQUIRED guards). Explicit ALWAYS wins; env never overrides an explicit
+// key. Keyless actions (list/discover/detail/suggest/browse/get_campaign…) gate their public branches
+// separately and never call this, so a configured env key does NOT change the public read boundary.
+// The key is never printed/returned/logged.
+export function resolveMcpApiKey(args, envKey = WEBAZ_API_KEY) {
+    const explicit = typeof args?.api_key === 'string' ? args.api_key.trim() : '';
+    return explicit || envKey;
+}
 const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
 // 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 key → network_readonly(装完即见真网络)。
 // network_readonly(L1 onboarding,2026-06-08):无 key 默认。公共读匿名打 webaz.xyz(真 catalog/协议),
@@ -403,11 +412,11 @@ Skipping is allowed but agent then carries price/stock-race risk itself.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Buyer's api_key" },
+                api_key: { type: 'string', description: "Buyer's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 product_id: { type: 'string', description: 'Product ID (from webaz_search)' },
                 quantity: { type: 'number', description: 'Quantity, default 1' },
             },
-            required: ['api_key', 'product_id'],
+            required: ['product_id'],
         },
     },
     {
@@ -423,7 +432,7 @@ Actions: create (title/description/price) | mine | update (product_id + changed
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Seller's api_key" },
+                api_key: { type: 'string', description: "Seller's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 action: {
                     type: 'string',
                     enum: ['create', 'mine', 'update', 'delist', 'relist', 'trash', 'delete'],
@@ -479,7 +488,7 @@ Actions: create (title/description/price) | mine | update (product_id + changed
                     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'],
+            required: [],
         },
     },
     {
@@ -501,7 +510,7 @@ Options:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Buyer's api_key" },
+                api_key: { type: 'string', description: "Buyer's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 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' },
@@ -512,7 +521,7 @@ Options:
                 },
                 promoter_api_key: {
                     type: 'string',
-                    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).",
+                    description: "Referrer api_key (optional). ⚠️ Only L1 recorded (direct referrer, 70% commission); L2/L3 can't be inferred via MCP, so the undelivered L2/L3 portions go to commission_reserve (protocol reserve, in-only). Full 7:2:1 three-tier chain requires buyer clicking ?ref= URL from webaz_share_link (creates product_share_attribution).",
                 },
                 // B2 隐私购物
                 anonymous_recipient: {
@@ -526,7 +535,7 @@ Options:
                     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'],
+            required: ['product_id', 'shipping_address'],
         },
     },
     {
@@ -534,15 +543,15 @@ Options:
         // 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.
 
-- **Seller**: accept (24h after payment) | ship (needs tracking, within handling time)
-- **Logistics**: pickup (48h after ship) | transit | deliver (needs proof description)
+- **Seller**: accept (24h after payment) | ship (needs tracking/notes, within handling time) | pickup/transit/deliver ONLY when order.logistics_id is empty (Phase-1 self-fulfill; seller carries logistics responsibility) | decline (actively refuse a PAID order instead of silent timeout; requires decline_reason_code — objective codes [stock_consumed_concurrent/stale_price_snapshot/force_majeure] go to a PROVISIONAL fault you must then contest within the window, NOT auto-cleared; subjective codes [price_regret/cherry_pick/other] settle immediately as seller-fault + buyer refund) | contest_decline (open human arbitration on an objective-claimed provisional fault, within the contest window, to be cleared to no-fault; pass evidence_description — window expiry finalizes as fault)
+- **Logistics**: pickup (48h after ship) | transit | deliver (needs proof description) when assigned or claiming an unassigned shipped order
 - **Buyer**: confirm (→ fund settlement) | dispute (needs reason; freezes funds → arbitration)
 
 Missing deadline → protocol auto-marks party in default.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Operator's api_key" },
+                api_key: { type: 'string', description: "Operator's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 order_id: { type: 'string', description: 'Order ID' },
                 action: {
                     type: 'string',
@@ -560,7 +569,7 @@ Missing deadline → protocol auto-marks party in default.`,
                     description: 'Evidence description (recommended for ship/pickup/deliver; required for dispute)',
                 },
             },
-            required: ['api_key', 'order_id', 'action'],
+            required: ['order_id', 'action'],
         },
     },
     {
@@ -570,10 +579,10 @@ Missing deadline → protocol auto-marks party in default.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Querier's api_key" },
+                api_key: { type: 'string', description: "Querier's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 order_id: { type: 'string', description: 'Order ID' },
             },
-            required: ['api_key', 'order_id'],
+            required: ['order_id'],
         },
     },
     {
@@ -591,14 +600,14 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['view', 'deposits', 'withdrawals', 'income'],
                     description: 'Action type (default: view)',
                 },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -610,11 +619,11 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 unread: { type: 'boolean', description: 'Return only unread (default false)' },
                 mark_read: { type: 'boolean', description: 'Auto-mark read after call (default false)' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -637,7 +646,7 @@ Protocol auto-judges (no human): respondent silent 48h → favor initiator; arbi
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Operator's api_key" },
+                api_key: { type: 'string', description: "Operator's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 action: {
                     type: 'string',
                     enum: ['view', 'list_open', 'respond', 'add_evidence', 'arbitrate'],
@@ -668,7 +677,7 @@ Protocol auto-judges (no human): respondent silent 48h → favor initiator; arbi
                 },
                 ruling_reason: { type: 'string', description: 'Ruling reason (required for arbitrate; permanently recorded on-chain)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -695,7 +704,7 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['create', 'view', 'mine', 'submit_seller_evidence', 'available', 'vote', 'eligibility', 'verifier_status', 'apply', 'withdraw_application', 'appeal'],
@@ -718,7 +727,7 @@ Actions:
                 // appeal
                 reason: { type: 'string', description: 'Appeal reason (required for appeal, ≤500 chars)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -743,7 +752,7 @@ Actions: list (no auth) | publish (seller) | subscribe / unsubscribe (buyer) | m
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for list)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for list) (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['list', 'publish', 'subscribe', 'unsubscribe', 'my_skills', 'my_subs'],
@@ -807,7 +816,7 @@ Public-profile actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (required for view/add_role/switch_role/view_user; optional for public feed)' },
+                api_key: { type: 'string', description: 'Your api_key (required for view/add_role/switch_role/view_user; optional for public feed) (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['view', 'add_role', 'switch_role', 'view_user', 'feed'],
@@ -841,10 +850,10 @@ Use revoke when: PERMANENT decommission of agent/device, OR want access death NO
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your current api_key (the one to revoke)' },
+                api_key: { type: 'string', description: 'Your current api_key (the one to revoke) (or set the WEBAZ_API_KEY env var)' },
                 reason: { type: 'string', description: 'Optional: leaked / lost_device / rotation / unspecified' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -856,10 +865,10 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your current api_key (will be invalidated after PWA confirm)' },
+                api_key: { type: 'string', description: 'Your current api_key (will be invalidated after PWA confirm) (or set the WEBAZ_API_KEY env var)' },
                 reason: { type: 'string', description: 'Optional: rotation / leaked / scheduled' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -872,9 +881,9 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -887,15 +896,15 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 product_id: { type: 'string', description: 'Product to promote (from webaz_search)' },
                 side: {
                     type: 'string',
-                    enum: ['left', 'right', 'auto'],
-                    description: 'Which side of your binary tree the new user lands. auto = weaker leg (default)',
+                    enum: ['auto'],
+                    description: 'Deprecated / no-op — placement is always automatic (system-decided). Left/right选择已下线。',
                 },
             },
-            required: ['api_key', 'product_id'],
+            required: ['product_id'],
         },
     },
     {
@@ -909,12 +918,12 @@ Actions: list | block | unblock.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['list', 'block', 'unblock'], description: 'list: my blocked users | block: add | unblock: remove' },
                 user_id: { type: 'string', description: 'Target user id (required for block/unblock)' },
                 reason: { type: 'string', description: 'Optional reason for block (e.g. "fake product", "abuse")' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -923,11 +932,11 @@ Actions: list | block | unblock.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['list', 'follow', 'unfollow', 'status'], description: 'list: my follows + followers | follow/unfollow: change relation | status: check if I follow a user' },
                 user_id: { type: 'string', description: 'Target user (required for follow/unfollow/status)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -941,12 +950,12 @@ USE THIS for "what's popular near me / 我附近 / 同城" — geo-aggregated, n
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['query', 'set_location', 'clear_location'], description: 'query: get aggregated nearby activity | set_location: set your geo cell | clear_location: remove' },
                 lat: { type: 'number', description: 'Latitude -90..90 (for set_location, auto-truncated to 0.1°)' },
                 lng: { type: 'number', description: 'Longitude -180..180 (for set_location, auto-truncated to 0.1°)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -958,12 +967,12 @@ USE THIS for "what's popular near me / 我附近 / 同城" — geo-aggregated, n
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['read', 'set'], description: 'read: get current default | set: update' },
                 text: { type: 'string', description: 'Full address as free-text string (e.g. "John Doe / 1 Test St / Singapore SG / +65 12345678"). Required for set. ≤ 200 chars.' },
                 region: { type: 'string', description: 'Region tag for shipping match (e.g. "global", "china", "SG"). Optional for set. ≤ 40 chars.' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -979,7 +988,7 @@ Actions: list_mine | add (external_url + product/anchor) | delete | by_product |
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['list_mine', 'add', 'delete', 'by_product', 'by_anchor'], description: 'list_mine | add (need external_url + product/anchor) | delete | by_product | by_anchor' },
                 external_url: { type: 'string', description: 'For action=add' },
                 title: { type: 'string', description: 'For action=add (optional)' },
@@ -988,7 +997,7 @@ Actions: list_mine | add (external_url + product/anchor) | delete | by_product |
                 related_anchor: { type: 'string', description: 'For action=add or by_anchor' },
                 shareable_id: { type: 'string', description: 'For action=delete' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     // ── P3 RFQ / bid / chat / auto_bid（MCP 通过 HTTP 调 PWA，复用所有校验+状态机）────
@@ -1017,7 +1026,7 @@ Shipping address falls back to webaz_default_address if omitted.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['create', 'mine', 'browse', 'detail', 'award', 'cancel'] },
                 // create
                 title: { type: 'string' },
@@ -1036,7 +1045,7 @@ Shipping address falls back to webaz_default_address if omitted.`,
                 rfq_id: { type: 'string' },
                 bid_id: { type: 'string', description: 'Optional for award — if omitted, auto-pick current lowest bid' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1050,7 +1059,7 @@ Actions: submit (rfq_id + price + qty_offered + fulfillment_type; optional eta/n
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Seller api_key' },
+                api_key: { type: 'string', description: 'Seller api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['submit', 'patch', 'cancel', 'list_mine'] },
                 rfq_id: { type: 'string' },
                 bid_id: { type: 'string' },
@@ -1061,7 +1070,7 @@ Actions: submit (rfq_id + price + qty_offered + fulfillment_type; optional eta/n
                 note: { type: 'string' },
                 offer_id: { type: 'string', description: 'Optional; reference existing offer' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1081,7 +1090,7 @@ webaz_blocklist hides from search but does NOT auto-silence existing convs (busi
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['start', 'list', 'read', 'send', 'mark_read', 'block'] },
                 kind: { type: 'string', enum: ['order', 'rfq', 'listing_qa'] },
                 context_id: { type: 'string' },
@@ -1089,7 +1098,7 @@ webaz_blocklist hides from search but does NOT auto-silence existing convs (busi
                 conversation_id: { type: 'string' },
                 body: { type: 'string', description: 'Message body for send action (≤2000 chars)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1129,7 +1138,7 @@ Actions (15):
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['list', 'detail', 'create', 'claim', 'proof', 'confirm', 'disclose', 'cancel', 'me', 'stories', 'leaderboard', 'repay', 'repay_respond', 'donate', 'fund'] },
                 wish_id: { type: 'string' },
                 fulfillment_id: { type: 'string' },
@@ -1165,7 +1174,7 @@ Actions: create (seller, needs title/price/stock + content_hash sha256 + content
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['create', 'list', 'detail', 'patch'] },
                 product_id: { type: 'string' },
                 title: { type: 'string' }, price: { type: 'number' }, stock: { type: 'number' },
@@ -1190,11 +1199,11 @@ Actions: toggle (same endpoint; 2nd call auto-unlikes) | status (my like status
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['toggle', 'status'] },
                 shareable_id: { type: 'string' },
             },
-            required: ['api_key', 'action', 'shareable_id'],
+            required: ['action', 'shareable_id'],
         },
     },
     {
@@ -1239,7 +1248,7 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['create', 'browse', 'mine', 'detail', 'bid', 'cancel'] },
                 title: { type: 'string' },
                 qty: { type: 'number' },
@@ -1253,7 +1262,7 @@ Actions:
                 auction_id: { type: 'string' },
                 price: { type: 'number' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1267,7 +1276,7 @@ Actions: get | set (categories[] / regions[] / max_eta_h / bid_strategy) | disab
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['get', 'set', 'disable'] },
                 categories: { type: 'array', items: { type: 'string' } },
                 regions: { type: 'array', items: { type: 'string' } },
@@ -1280,7 +1289,7 @@ Actions: get | set (categories[] / regions[] / max_eta_h / bid_strategy) | disab
                 cooldown_min: { type: 'number' },
                 enabled: { type: 'boolean' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1300,7 +1309,7 @@ Actions: list (no auth, filters: kind/billing/query) | detail (public, no conten
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for list/detail)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for list/detail) (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['list', 'detail', 'publish', 'update', 'delist', 'resubmit', 'purchase', 'read', 'my_skills', 'library'],
@@ -1337,7 +1346,7 @@ Enums: **category** phone/computer/appliance/furniture/clothing/book/toy/sports/
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for browse/detail)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for browse/detail) (or set the WEBAZ_API_KEY env var)' },
                 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
@@ -1386,7 +1395,7 @@ Seller actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for get_campaign)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for get_campaign) (or set the WEBAZ_API_KEY env var)' },
                 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)' },
@@ -1415,7 +1424,7 @@ Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyon
             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)" },
+                api_key: { type: 'string', description: "User's api_key (real person required; or set the WEBAZ_API_KEY env var)" },
                 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' },
@@ -1423,7 +1432,7 @@ Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyon
                 text: { type: 'string', description: 'submit: the feedback / idea (≥5 chars)' },
                 feedback_id: { type: 'string', description: 'get: the feedback id' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -1435,7 +1444,8 @@ Discovery + suggesting need NO api_key (anyone / any agent can browse and propos
 Actions:
 - list_open (default): open public tasks (opt. filters: area / risk_level / auto_claimable / required_capabilities / agent_capabilities / max_duration_minutes / estimated_context_size / estimated_agent_budget — estimated_agent_budget is a resource/effort estimate, NOT a payment). Each task carries its execution boundary + the trusted canonical contribution target. NO api_key needed.
 - detail: one task's full execution boundary (allowed/forbidden paths, prohibited actions, acceptance criteria, verification commands, deliverables, definition_of_done) + the canonical repo to PR to + a copy-ready agent_handoff. NO api_key needed.
-- suggest: propose a NEW task (title + summary/reason; opt. area/expected_outcome/source_ref/github_login). It enters the maintainer inbox — it is a suggestion, NOT a contribution fact / reward / participation, and never auto-becomes a task. NO api_key needed.
+- suggest: propose a NEW task (title + summary/reason; opt. area/expected_outcome/source_ref/github_login). It enters the maintainer inbox — it is a suggestion, NOT a contribution fact / reward / participation, and never auto-becomes a task. NO api_key needed (but pass your key to LINK it to your account so you can track it via my_suggestions).
+- my_suggestions: your OWN past proposals + their review status / public_reply / next_action (api_key). Agent-readable 回执 so a proposer-agent can act on the maintainer's decision (needs_info → resubmit; converted → see converted_ref).
 - claim: take an open task (api_key); provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a handoff — point a coding agent at it; the human needn't know git but stays accountable (Passkey).
 - submit: mark in_review with pr_ref + verification_summary (api_key). The PR's base repo MUST be the canonical WebAZ repo, and a verification_summary (what you ran/verified) is REQUIRED — both server-enforced. A human maintainer reviews next; done ≠ merge.
 - status: tasks you hold (api_key).
@@ -1445,12 +1455,12 @@ Coordinates + records only — NO merge/reward; acceptance (done) = human mainta
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | claim | submit | status | profile' },
-                api_key: { type: 'string', description: 'claim/submit/status/profile: your api_key (accountable identity). NOT needed for list_open/detail/suggest.' },
+                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'my_suggestions', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | my_suggestions | claim | submit | status | profile' },
+                api_key: { type: 'string', description: 'claim/submit/status/profile: your api_key (accountable identity). NOT needed for list_open/detail/suggest. (or set the WEBAZ_API_KEY env var)' },
                 task_id: { type: 'string', description: 'detail / claim / submit: the task id' },
                 area: { type: 'string', description: 'list_open: area filter / suggest: suggested area (e.g. search / docs / mcp)' },
                 risk_level: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], description: 'list_open: optional risk filter' },
-                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — only auto-claimable (true) or manual-claim (false) tasks' },
+                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — true returns tasks an agent can just do (auto-claimable AND with a real effort estimate; matches the derived claimability=auto_claimable), false returns manual-claim tasks. A task with a placeholder (unknown) estimate is treated as manual_review even if its raw auto_claimable flag is true, so it is excluded from true.' },
                 required_capabilities: { type: 'string', description: 'list_open: optional filter — comma-separated; matches tasks that REQUIRE ALL of the listed capabilities (superset/AND match on the task requirement). For "tasks my agent can do", use agent_capabilities instead.' },
                 agent_capabilities: { type: 'string', description: 'list_open: optional filter — capabilities your agent HAS (comma-separated); matches tasks whose required_capabilities are a SUBSET of these, i.e. tasks your agent can actually do' },
                 max_duration_minutes: { type: 'number', description: 'list_open: optional filter — only tasks whose estimated max duration fits within this many minutes (your idle time)' },
@@ -1473,7 +1483,7 @@ Coordinates + records only — NO merge/reward; acceptance (done) = human mainta
 // RFC-004: webaz_feedback — agent-native "use → build" 反馈(双模;仅 NETWORK 能送达)
 async function handleFeedback(args) {
     const action = args.action || 'submit';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     if (toolBackend('webaz_feedback') !== 'network') {
@@ -1509,18 +1519,22 @@ async function handleFeedback(args) {
 }
 // RFC-006 断点1(b)交接:从【可信】canonical 目标(API 响应里,绝不硬编码/不取自 task metadata)构造"怎么真正
 // 动手"。人的编码 agent 做 git/PR;Passkey 真人担责。sandbox 运行 / 本地草稿不算正式参与。
-function buildContributeHandoff(cct, taskId) {
+function buildContributeHandoff(cct, taskId, caseId) {
     const c = (cct ?? {});
-    const repoUrl = c.canonical_github_url || 'https://github.com/seasonsagents-art/webaz';
-    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'seasonsagents-art/webaz';
+    const repoUrl = c.canonical_github_url || 'https://github.com/webaz-protocol/webaz';
+    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'webaz-protocol/webaz';
     const baseBranch = c.base_branch || 'main';
+    // case_id threads proposal → task → PR. = the source proposal id when this task came from a proposal,
+    // else the task id itself. Quote it in the PR so the whole case stays traceable end to end.
+    const cid = caseId || taskId;
     return {
+        case_id: cid,
         canonical_repo: baseRepo,
         repo: repoUrl,
         base_branch: baseBranch,
         start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
         do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
-        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. If any target repo differs from this canonical repo, STOP and ask the human — never contribute to a non-canonical repository.`,
+        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. Reference case ${cid} in the PR title/body so the proposal → task → PR chain stays traceable. If any target repo differs from this canonical repo, STOP and ask the human — never contribute to a non-canonical repository.`,
         pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, mark the PR per the meta-rule. Humans merge — no auto-merge.',
         then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${taskId} pr_ref=#<N> verification_summary="<the verification_commands you ran + their results>". Both pr_ref and verification_summary are required.`,
         not_participation: 'A sandbox run or a local-only draft is NOT participation and is NOT a contribution; only a merged PR (or recognized issue/task/RFC) on the canonical repo enters the contribution record.',
@@ -1531,7 +1545,7 @@ function buildContributeHandoff(cct, taskId) {
 // 端口 #329/#331);claim/submit/status/profile 需 key(真实可问责身份,走受 #330 守卫的 member 端口)。
 export async function handleContribute(args) {
     const action = args.action || 'list_open';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (toolBackend('webaz_contribute') !== 'network') {
         return {
             _mode: 'sandbox',
@@ -1571,7 +1585,7 @@ export async function handleContribute(args) {
             return { error: 'task_id required for action=detail' };
         const r = await apiCall('/api/public/build-tasks/' + encodeURIComponent(tid));
         if (!r.error && r.task)
-            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid);
+            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid, r.task.case_id);
         return r;
     }
     if (action === 'suggest') {
@@ -1583,6 +1597,7 @@ export async function handleContribute(args) {
             return { error: 'summary (the reason) required for action=suggest' };
         const r = await apiCall('/api/public/task-proposals', {
             method: 'POST',
+            apiKey, // optional — when present, links the proposal to the submitter so it shows up in action=my_suggestions (still works anonymously)
             body: {
                 title, summary,
                 suggested_area: args.area ?? args.suggested_area,
@@ -1591,6 +1606,8 @@ export async function handleContribute(args) {
                 proposer_github_login: args.proposer_github_login,
             },
         });
+        if (!r.error && r.linked_to_account)
+            r._next = 'Track this proposal\'s review status + reply: webaz_contribute action=my_suggestions api_key=<key>.';
         // typed errors (RATE_LIMITED / DUPLICATE_PROPOSAL / validation) are already mapped by apiCall; the
         // success response already carries the route-level `proposal_notice` (suggestion ≠ contribution/reward).
         return r;
@@ -1603,6 +1620,13 @@ export async function handleContribute(args) {
         };
     if (action === 'status')
         return apiCall('/api/build-tasks?mine=1', { apiKey });
+    if (action === 'my_suggestions') {
+        // your OWN past proposals + review status/public_reply/next_action (agent-readable 回执). Own rows only (server-enforced).
+        const r = await apiCall('/api/me/task-proposals', { apiKey });
+        if (!r.error)
+            r._next = 'Each item carries status + public_reply + next_action. needs_info → resubmit via action=suggest referencing the id; converted → see converted_ref.';
+        return r;
+    }
     if (action === 'profile')
         return apiCall('/api/build-reputation/me', { apiKey });
     if (action === 'claim') {
@@ -1721,8 +1745,11 @@ async function handleInfo() {
         // 连接两个场景:用协议(本工具) ↔ 改协议(开发协作)。想改 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',
+            repo: 'https://github.com/webaz-protocol/webaz',
             start_here: 'AGENTS.md (project map + before-you-code + PR flow) → CONTRIBUTING.md (full guide)',
+            // 低门槛路径:无需 api_key、无需 clone 仓库,直接经协议发现任务 / 提建议(对外 well-known 入口也有,见 agent_quickstart)。
+            no_key_path: 'No api_key needed to START contributing: discover open tasks and submit a suggestion via webaz_contribute action=list_open / action=suggest (mirrors GET /api/public/build-tasks + POST /api/public/task-proposals). / 无需 key 即可起步:webaz_contribute action=list_open 发现开放任务、action=suggest 提建议。',
+            contribution_boundary: 'A suggestion is a proposal in the maintainer review inbox — NOT a contribution fact, NOT formal participation, and NOT any economic or redemption right; recorded contribution is facts / evidence / attribution only (RFC-017). / 建议只是进入维护者审阅箱的提议,不是贡献事实、不是正式参与、不构成任何经济或兑现权利;记录的贡献只是事实/证据/归属(RFC-017)。',
             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)触发并担责。',
         },
         // NETWORK 模式:真网络 live 状态(best-effort 拉自 webaz.xyz);SANDBOX 模式为 null。
@@ -1732,10 +1759,10 @@ async function handleInfo() {
         // 佣金机制 —— 纯功能性描述(怎么运作),不做"自证清白"式辩护。
         commission_model: {
             split: '7:2:1 — L1 70% / L2 20% / L3 10% of an order\'s commission_pool',
-            jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → community fund).',
+            jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → commission_reserve / protocol reserve).',
             attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, not derived from the buyer\'s sponsor chain.',
             how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link /i/<permanent_code> (?ref=<permanent_code>) URL clicked in a browser (builds product_share_attribution).',
-            redirect_rules: 'chain_gap (no L / invalid sponsor) → charity_fund; level beyond the region cap → global_fund.',
+            redirect_rules: 'all undelivered commission (chain_gap / no L / invalid sponsor / level beyond the region cap / max_levels=0 / opt-out / escrow expiry) → commission_reserve (protocol reserve, in-only; use decided by governance).',
             l1_gate: 'the promoter must be a verified buyer (≥1 completed order) to receive commission, otherwise that share redirects.',
             opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded. Commission destination is state-dependent: never_activated / auto_downgraded → held in pending_commission_escrow (30d grace), recoverable by (re-)activating within the window, else swept to commission_reserve; deactivated (active opt-out) → future commission goes directly to commission_reserve, NOT escrow and NOT recoverable. Never to charity_fund. See docs/rfcs/RFC-002-rewards-opt-in.md.',
         },
@@ -2138,11 +2165,11 @@ async function handleVerifyPrice(args) {
     if (toolBackend('webaz_verify_price') === 'network') {
         return apiCall('/api/verify-price', {
             method: 'POST',
-            apiKey: args.api_key,
+            apiKey: resolveMcpApiKey(args),
             body: { product_id: args.product_id, quantity: Number(args.quantity ?? 1) },
         });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2188,7 +2215,7 @@ async function handleVerifyPrice(args) {
 async function handleListProduct(args) {
     // Wave 3 audit P0: 加 action 分发 — agent 卖家能完整管理目录（不止 create）
     const action = args.action || 'create';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     // RFC-003 P2b: NETWORK 模式 — 卖家目录管理全部转发生产端点（单一真相源）
@@ -2366,9 +2393,9 @@ async function handlePlaceOrder(args) {
             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 });
+        return apiCall('/api/orders', { method: 'POST', apiKey: resolveMcpApiKey(args), body });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2535,7 +2562,7 @@ async function handleUpdateOrder(args) {
             return { error: 'order_id and action required' };
         return apiCall(`/api/orders/${encodeURIComponent(orderId)}/action`, {
             method: 'POST',
-            apiKey: args.api_key,
+            apiKey: resolveMcpApiKey(args),
             body: {
                 action,
                 notes: args.notes ?? '',
@@ -2545,7 +2572,7 @@ async function handleUpdateOrder(args) {
             },
         });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2559,7 +2586,7 @@ async function handleUpdateOrder(args) {
     // agent-native 协议要求"哪个接口进结果一致"。MCP confirm 不再自己结算，
     // 走 PWA /api/orders/:id/action 的 settleOrder + settleCommission（authoritative）。
     if (action === 'confirm') {
-        const apiKey = args.api_key;
+        const apiKey = resolveMcpApiKey(args);
         const result = await pwaApi('POST', `/orders/${encodeURIComponent(orderId)}/action`, apiKey, {
             action: 'confirm',
             notes,
@@ -2668,9 +2695,9 @@ async function handleGetStatus(args) {
         const orderId = args.order_id;
         if (!orderId)
             return { error: 'order_id required' };
-        return apiCall(`/api/orders/${encodeURIComponent(orderId)}`, { apiKey: args.api_key });
+        return apiCall(`/api/orders/${encodeURIComponent(orderId)}`, { apiKey: resolveMcpApiKey(args) });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const statusInfo = getOrderStatus(db, args.order_id);
@@ -2707,7 +2734,7 @@ async function handleGetStatus(args) {
 async function handleWallet(args) {
     // Wave 3 audit P0: 加 action 分发 — agent 能查充值/提现/收入历史（写操作仍 UI-only 走 2FA）
     const action = args.action || 'view';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     // RFC-003 Batch 4:NETWORK 模式 → webaz.xyz 真网络【只读】(Bearer api_key)。
@@ -2775,14 +2802,14 @@ async function handleWallet(args) {
 async function handleNotifications(args) {
     // RFC-003 Batch 1:NETWORK 模式 → 调 webaz.xyz 真网络通知端点(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_notifications') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (args.mark_read)
             await apiCall('/api/notifications/read', { method: 'POST', apiKey });
         return await apiCall('/api/notifications' + (args.unread === true ? '?unread=1' : ''), { apiKey });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2806,7 +2833,7 @@ async function handleNotifications(args) {
 }
 // ─── 争议处理 ─────────────────────────────────────────────────
 async function handleDispute(args) {
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     const action = args.action;
@@ -2969,7 +2996,7 @@ async function handleDispute(args) {
 }
 // ─── 索赔验证（claim-verification）处理 — Wave 6 新增 ────────────
 async function handleClaimVerify(args) {
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     const action = String(args.action || '');
@@ -3057,7 +3084,7 @@ async function handleSkill(args) {
     const action = args.action;
     // RFC-003 Batch 3:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地引擎。
     if (toolBackend('webaz_skill') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (action === 'list') {
             const qs = new URLSearchParams();
             if (args.skill_type)
@@ -3094,8 +3121,8 @@ async function handleSkill(args) {
     // ── 浏览 Skill 市场 ────────────────────────────────────────
     if (action === 'list') {
         let userId;
-        if (args.api_key) {
-            const a = requireAuth(db, args.api_key);
+        if (resolveMcpApiKey(args)) {
+            const a = requireAuth(db, resolveMcpApiKey(args));
             if (!('error' in a))
                 userId = a.user.id;
         }
@@ -3112,7 +3139,7 @@ async function handleSkill(args) {
         };
     }
     // 以下操作需要身份验证
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3253,7 +3280,7 @@ function handleMyKey(args) {
 }
 async function handleProfile(args) {
     const action = args.action;
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     // RFC-003 Batch 1:NETWORK 模式 → 全部 action 调 webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_profile') === 'network') {
         if (action === 'view_user') {
@@ -3350,7 +3377,7 @@ async function handleProfile(args) {
 function handleRevokeKey(args) {
     // RFC-003 Batch 5:NETWORK 模式 → 不本地校验 key(PWA 会鉴权),直接返回 Passkey 撤销指引。
     if (toolBackend('webaz_revoke_key') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         const reason = (args.reason || 'unspecified').trim().slice(0, 100);
         return {
             _mode: 'network',
@@ -3368,7 +3395,7 @@ function handleRevokeKey(args) {
             },
         };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3392,7 +3419,7 @@ function handleRevokeKey(args) {
 function handleRotateKey(args) {
     // RFC-003 Batch 5:NETWORK 模式 → 不本地校验 key(PWA 会鉴权),直接返回 Passkey 轮换指引。
     if (toolBackend('webaz_rotate_key') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         const reason = (args.reason || 'rotation').trim().slice(0, 100);
         return {
             _mode: 'network',
@@ -3409,7 +3436,7 @@ function handleRotateKey(args) {
             },
         };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3429,16 +3456,16 @@ function handleRotateKey(args) {
         },
     };
 }
-// ─── 推广 / 双轨 (Tokenomics) ───────────────────────────────────
+// ─── 推广 / 推荐网络 (Tokenomics) ───────────────────────────────────
 async function handleReferral(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络聚合(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_referral') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         return await apiCall('/api/referral/me', { apiKey });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3456,16 +3483,9 @@ async function handleReferral(args) {
     const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
     const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
     const canL1 = override === 1 || (override === 0 && completed > 0);
-    // 原子能双轨
+    // Neutral participation record only — placement position + per-leg PV. Matching-rewards engine excised (#401):
+    // no Score / tier / pair-volume / payout is read or exposed.
     const me = db.prepare("SELECT total_left_pv, total_right_pv, left_child_id, right_child_id, placement_id, placement_side FROM users WHERE id = ?").get(userId);
-    const score = db.prepare(`
-    SELECT COALESCE(SUM(CASE WHEN settled_at IS NULL THEN score ELSE 0 END),0) as pending,
-           COALESCE(SUM(CASE WHEN settled_at IS NOT NULL THEN waz_amount ELSE 0 END),0) as settled_waz
-    FROM binary_score_records WHERE user_id = ?
-  `).get(userId);
-    const tiers = db.prepare("SELECT tier, pv_threshold, score_per_hit FROM binary_tier_config WHERE active=1 ORDER BY tier ASC").all();
-    const pair = Math.min(Number(me?.total_left_pv ?? 0), Number(me?.total_right_pv ?? 0));
-    const nextTier = tiers.find(t => t.pv_threshold > pair);
     // invite / share links use permanent_code ONLY — never usr_xxx. (sandbox users have one from register.)
     const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
     return {
@@ -3487,17 +3507,12 @@ async function handleReferral(args) {
             l1: byLevel[1], l2: byLevel[2], l3: byLevel[3],
             grand_total: byLevel[1].total + byLevel[2].total + byLevel[3].total,
         },
-        binary: {
-            left_invite_link: permaCode ? `/i/${permaCode}-L` : null,
-            right_invite_link: permaCode ? `/i/${permaCode}-R` : null,
-            platform_left: permaCode ? `/?placement=${permaCode}&side=left` : null, // 仅 PV 条线
-            platform_right: permaCode ? `/?placement=${permaCode}&side=right` : null,
+        placement: {
+            // Neutral participation/attribution record: a single referral code + per-leg PV. No matching rewards.
+            referral_link: permaCode ? `/i/${permaCode}` : null,
             total_left_pv: Number(me?.total_left_pv ?? 0),
             total_right_pv: Number(me?.total_right_pv ?? 0),
-            pair_volume: pair,
-            next_tier: nextTier ? { tier: nextTier.tier, pv_threshold: nextTier.pv_threshold, score_per_hit: nextTier.score_per_hit, pv_needed: nextTier.pv_threshold - pair } : null,
-            score_pending: score.pending,
-            waz_total_earned: score.settled_waz,
+            note: 'total_left_pv / total_right_pv are a participation / attribution record only — not income, not redeemable, no entitlement.',
         },
         rewards_status: (() => {
             // RFC-002 §3.5 — 4 states + pending escrow visibility (PR-4)
@@ -3540,23 +3555,21 @@ async function handleReferral(args) {
 async function handleShareLink(args) {
     // RFC-003 #1122:NETWORK 模式 → 调 webaz.xyz 的 /api/share-link(服务端同款计算);SANDBOX 走本地。
     if (toolBackend('webaz_share_link') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (!args.product_id)
             return { error: 'product_id required' };
+        // pre-public 去左右码:不再向 /api/share-link 转发 side(放置永远自动)
         const qs = new URLSearchParams({ product_id: String(args.product_id) });
-        if (args.side)
-            qs.set('side', String(args.side));
         return await apiCall('/api/share-link?' + qs.toString(), { apiKey });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
     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) {
@@ -3589,32 +3602,7 @@ async function handleShareLink(args) {
     const product = db.prepare("SELECT id, title, price, commission_rate FROM products WHERE id = ? AND status='active'").get(productId);
     if (!product)
         return { error: '商品不存在或已下架' };
-    let side = 'right';
-    if (sideArg === 'left' || sideArg === 'right') {
-        side = sideArg;
-    }
-    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_count, right_count FROM users WHERE id = ?")
-            .get(userId);
-        const pref = u?.placement_pref || 'team_count';
-        if (pref === 'pv_count') {
-            const since = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString().slice(0, 19).replace('T', ' ');
-            const w = db.prepare(`SELECT COALESCE(SUM(consumed_left_pv),0) AS l, COALESCE(SUM(consumed_right_pv),0) AS r
-                            FROM binary_score_records WHERE user_id = ? AND created_at >= ?`)
-                .get(userId, since);
-            const leftPv = Number(u?.total_left_pv ?? 0) + Number(w.l);
-            const rightPv = Number(u?.total_right_pv ?? 0) + Number(w.r);
-            side = leftPv <= rightPv ? 'left' : 'right';
-        }
-        else {
-            // 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';
-        }
-    }
+    // pre-public 去左右码:分享链接不再携带 side(放置侧别由注册时系统自动决定)
     const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
     const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
     const canL1 = override === 1 || (override === 0 && completed > 0);
@@ -3623,13 +3611,12 @@ async function handleShareLink(args) {
     const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
     if (!permaCode)
         return { error: 'permanent_code_missing — cannot build a share link; re-register or contact support', error_code: 'PERMANENT_CODE_MISSING' };
-    const link = `/?ref=${permaCode}&side=${side}#order-product/${productId}`;
+    const link = `/?ref=${permaCode}#order-product/${productId}`;
     return {
         product: { id: product.id, title: product.title, price: product.price, commission_rate: rate },
         share_link: link,
         full_url_hint: 'Prepend webaz.xyz (production) or http://localhost:3000 (local) to get the absolute URL',
-        side,
-        binary_explanation: `New user via this link → placed in your ${side === 'left' ? '🔵 left' : '🟢 right'} subtree (tail anchor)`,
+        placement_note: 'New user via this link → placement is recorded automatically by the system (no left/right choice).',
         commission_eligibility: canL1
             ? `You will earn 3-tier commission: L1=${(rate * 0.70 * 100).toFixed(1)}% L2=${(rate * 0.20 * 100).toFixed(1)}% L3=${(rate * 0.10 * 100).toFixed(1)}% of sale price`
             : 'You are NOT verified yet (need 1 completed purchase). 3-tier commission will be skipped, but points-matching still builds.',
@@ -3640,7 +3627,7 @@ async function handleShareLink(args) {
 async function handleBlocklist(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_blocklist') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         const act = String(args.action || '');
@@ -3655,7 +3642,7 @@ async function handleBlocklist(args) {
             return await apiCall('/api/blocklist/' + uid, { method: 'DELETE', apiKey });
         return { error: `unknown action: ${act}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3694,7 +3681,7 @@ async function handleBlocklist(args) {
 async function handleFollows(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_follows') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         const act = String(args.action || '');
@@ -3711,7 +3698,7 @@ async function handleFollows(args) {
             return await apiCall('/api/follows/' + uid + '/status', { apiKey });
         return { error: `unknown action: ${act}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3760,7 +3747,7 @@ async function handleNearby(args) {
     const action = String(args.action || '');
     // RFC-003 Batch 1:NETWORK 模式 → 调 webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_nearby') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (action === 'set_location')
@@ -3778,7 +3765,7 @@ async function handleNearby(args) {
         }
         return { error: `unknown action: ${action}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3829,7 +3816,7 @@ async function handleNearby(args) {
 async function handleDefaultAddress(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_default_address') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         const act = String(args.action || '');
@@ -3848,7 +3835,7 @@ async function handleDefaultAddress(args) {
         }
         return { error: `unknown action: ${act}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3889,7 +3876,7 @@ async function handleShareables(args) {
     const action = String(args.action || '');
     // RFC-003 Batch 1:NETWORK 模式 → 调 webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_shareables') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (action === 'list_mine')
@@ -3917,7 +3904,7 @@ async function handleShareables(args) {
         }
         return { error: `unknown action: ${action}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -4073,7 +4060,7 @@ async function pwaApi(method, path, apiKey, body) {
     }
 }
 async function handleSecondhand(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const isPublic = action === 'browse' || action === 'detail';
     if (!isPublic) {
@@ -4144,7 +4131,7 @@ async function handleSecondhand(args) {
     }
 }
 async function handleTrial(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const isPublic = action === 'get_campaign';
     if (!isPublic) {
@@ -4197,7 +4184,7 @@ async function handleTrial(args) {
     }
 }
 async function handleSkillMarket(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const isPublic = action === 'list' || action === 'detail';
     if (!isPublic) {
@@ -4270,7 +4257,7 @@ async function handleSkillMarket(args) {
     }
 }
 async function handleRfq(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4319,7 +4306,7 @@ async function handleRfq(args) {
     }
 }
 async function handleBid(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4393,7 +4380,7 @@ async function handleBid(args) {
     }
 }
 async function handleChat(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4435,7 +4422,7 @@ async function handleChat(args) {
     }
 }
 async function handleAutoBidSkill(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4558,7 +4545,7 @@ async function handleCharity(args) {
         return readEndpoint('webaz_charity', '/charity/leaderboard');
     if (action === 'fund')
         return readEndpoint('webaz_charity', '/charity/fund');
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required for this action' };
     if (toolBackend('webaz_charity') !== 'network') {
@@ -4621,7 +4608,7 @@ async function handleP2pProduct(args) {
             return { error: String(e.message) };
         }
     }
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required for create/patch' };
     const auth = requireAuth(db, apiKey);
@@ -4648,7 +4635,7 @@ async function handleP2pProduct(args) {
     return { error: `unknown action: ${action}` };
 }
 async function handleLike(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const sid = String(args.shareable_id || '');
     if (!apiKey || !sid)
@@ -4674,7 +4661,7 @@ async function handleLeaderboard(args) {
     return readEndpoint('webaz_leaderboard', '/leaderboard?kind=' + kind + '&limit=' + limit);
 }
 async function handleAuction(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -5132,7 +5119,7 @@ function addHours(date, hours) {
 function recordToolCall(tool, args, result, latencyMs) {
     let userId = null;
     try {
-        const apiKey = args.api_key;
+        const apiKey = resolveMcpApiKey(args);
         if (apiKey) {
             const row = db.prepare('SELECT id FROM users WHERE api_key = ?').get(apiKey);
             if (row)