@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/pwa/public/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "WebAZ Protocol API",
     "version": "0.4.14",
-    "description": "Auto-generated endpoint inventory (673 endpoints, 17 with full schema). See docs/ for design context."
+    "description": "Auto-generated endpoint inventory (776 endpoints, 17 with full schema). See docs/ for design context."
   },
   "servers": [
     {
@@ -349,6 +349,71 @@
         ]
       }
     },
+    "/api/admin/arbitrators": {
+      "get": {
+        "summary": "名册(admin 只读,无需 Passkey)。含 active/suspended/revoked 全量 + 状态。",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/arbitrators/:user_id/reinstate": {
+      "post": {
+        "summary": "POST /api/admin/arbitrators/:user_id/reinstate",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/arbitrators/:user_id/revoke": {
+      "post": {
+        "summary": "POST /api/admin/arbitrators/:user_id/revoke",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/arbitrators/:user_id/suspend": {
+      "post": {
+        "summary": "POST /api/admin/arbitrators/:user_id/suspend",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/arbitrators/grant": {
+      "post": {
+        "summary": "POST /api/admin/arbitrators/grant",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/admin/atomic/process-ledger": {
       "post": {
         "summary": "POST /api/admin/atomic/process-ledger",
@@ -605,12 +670,11 @@
         ]
       }
     },
-    "/api/admin/disputes": {
-      "get": {
-        "summary": "GET /api/admin/disputes",
+    "/api/admin/direct-receive/aml-flags": {
+      "post": {
+        "summary": "POST /api/admin/direct-receive/aml-flags",
         "tags": [
-          "admin",
-          "dispute"
+          "admin"
         ],
         "security": [
           {
@@ -619,9 +683,9 @@
         ]
       }
     },
-    "/api/admin/economic-summary": {
-      "get": {
-        "summary": "隐私第一：运营财务，仅 protocol admin 可见。",
+    "/api/admin/direct-receive/aml-flags/:id/review": {
+      "post": {
+        "summary": "route 只做 auth + gate + 参数校验 + 调 reviewAmlFlag(唯一 review writer,原子改 flag + 写 audit)。",
         "tags": [
           "admin"
         ],
@@ -632,9 +696,9 @@
         ]
       }
     },
-    "/api/admin/editor-picks": {
+    "/api/admin/direct-receive/bond-slash": {
       "get": {
-        "summary": "GET /api/admin/editor-picks",
+        "summary": "── B3:保证金罚没(人工铁律:仲裁裁定卖家责的直付争议 → 提案 → 冷静期 → ROOT+Passkey 执行;绝不自动)──",
         "tags": [
           "admin"
         ],
@@ -643,9 +707,11 @@
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/admin/direct-receive/bond-slash/:id/cancel": {
       "post": {
-        "summary": "POST /api/admin/editor-picks",
+        "summary": "POST /api/admin/direct-receive/bond-slash/:id/cancel",
         "tags": [
           "admin"
         ],
@@ -656,9 +722,9 @@
         ]
       }
     },
-    "/api/admin/editor-picks/:id": {
-      "delete": {
-        "summary": "DELETE /api/admin/editor-picks/:id",
+    "/api/admin/direct-receive/bond-slash/:id/execute": {
+      "post": {
+        "summary": "执行(ROOT + 真人 Passkey,purpose direct_pay_bond_slash 绑 proposal_id;冷静期由域内绝对截止校验)。",
         "tags": [
           "admin"
         ],
@@ -669,9 +735,9 @@
         ]
       }
     },
-    "/api/admin/email-subscriptions": {
-      "get": {
-        "summary": "2026-05-25 admin 查邮箱订阅 — 独立端点，与建议分开",
+    "/api/admin/direct-receive/bond-slash/propose": {
+      "post": {
+        "summary": "提案(ROOT,审计留痕,不 Passkey —— 提案不动任何东西;执行才是终局动作)。通知卖家(冷静期=申诉窗)。",
         "tags": [
           "admin"
         ],
@@ -682,9 +748,9 @@
         ]
       }
     },
-    "/api/admin/email-subscriptions/:id/status": {
-      "patch": {
-        "summary": "2026-05-29: admin 标记申请处理状态（pending→contacted→invited→done）— 不动 POST 提交逻辑",
+    "/api/admin/direct-receive/deferrals": {
+      "get": {
+        "summary": "GET /api/admin/direct-receive/deferrals?status=pending — ROOT 审批队列(默认全部;可按 status 过滤)。纯读。",
         "tags": [
           "admin"
         ],
@@ -695,9 +761,9 @@
         ]
       }
     },
-    "/api/admin/errors": {
-      "get": {
-        "summary": "GET /api/admin/errors",
+    "/api/admin/direct-receive/deferrals/:id/approve": {
+      "post": {
+        "summary": "Passkey purpose_data 绑定【完整审批条款】(deferral_id + reduced_quota_factor + grace_days):签 A 批 B / 改条款一律拒。",
         "tags": [
           "admin"
         ],
@@ -708,9 +774,9 @@
         ]
       }
     },
-    "/api/admin/errors/aggregate": {
-      "get": {
-        "summary": "Tier 1 #5: 错误聚合 view（24h / 1h 趋势 + top by source + top messages + burst alert）",
+    "/api/admin/direct-receive/deferrals/:id/reject": {
+      "post": {
+        "summary": "POST /api/admin/direct-receive/deferrals/:id/reject — ROOT + 真人 Passkey 拒绝缓交。purpose_data 绑 deferral_id。",
         "tags": [
           "admin"
         ],
@@ -721,9 +787,9 @@
         ]
       }
     },
-    "/api/admin/events/recent": {
+    "/api/admin/direct-receive/deposits": {
       "get": {
-        "summary": "GET /api/admin/events/recent",
+        "summary": "GET /api/admin/direct-receive/deposits?status=pending — ROOT 只读:保证金申报队列(核对到账用)。B1。",
         "tags": [
           "admin"
         ],
@@ -734,16 +800,9 @@
         ]
       }
     },
-    "/api/admin/events/stream": {
-      "get": {
-        "summary": "GET /api/admin/events/stream",
-        "tags": [],
-        "security": []
-      }
-    },
-    "/api/admin/events/ticket": {
+    "/api/admin/direct-receive/deposits/:id/confirm-production": {
       "post": {
-        "summary": "POST /api/admin/events/ticket",
+        "summary": "当前恒 fail-closed(无 legal-cleared rail → assert 抛 → PRODUCTION_RAIL_NOT_CLEARED)。",
         "tags": [
           "admin"
         ],
@@ -754,9 +813,9 @@
         ]
       }
     },
-    "/api/admin/export/:kind": {
-      "get": {
-        "summary": "GET /api/admin/export/:kind",
+    "/api/admin/direct-receive/deposits/:id/execute-refund": {
+      "post": {
+        "summary": "unlock blockers(冷静期内可能新增退货/欠费等责任 —— 有任一即拒)。凭据必填;真实退款发生在协议外,此处只记录。",
         "tags": [
           "admin"
         ],
@@ -767,21 +826,12 @@
         ]
       }
     },
-    "/api/admin/feedback": {
-      "get": {
-        "summary": "admin 列出工单",
-        "tags": [],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ]
-      }
-    },
-    "/api/admin/feedback/:id/reply": {
+    "/api/admin/direct-receive/deposits/:id/reject": {
       "post": {
-        "summary": "admin 回复 + 切状态",
-        "tags": [],
+        "summary": "不 Passkey:驳回不授予/不移动任何东西(与缓交 reject 不同 —— 那是资格决定;这里只是\"到账核不上\"退回重报)。",
+        "tags": [
+          "admin"
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -789,9 +839,9 @@
         ]
       }
     },
-    "/api/admin/finance/monthly": {
+    "/api/admin/direct-receive/fee-account/:seller_id": {
       "get": {
-        "summary": "GET /api/admin/finance/monthly",
+        "summary": "只读诊断,不写、无 Passkey(读不授权能力);卖家私密财务,买家/卖家拿不到此 admin 视图。",
         "tags": [
           "admin"
         ],
@@ -802,9 +852,9 @@
         ]
       }
     },
-    "/api/admin/governance/activate": {
+    "/api/admin/direct-receive/fee-adjust": {
       "post": {
-        "summary": "body: { application_id, webauthn_token, note? }",
+        "summary": "≠ 退款(不动真钱,只调记账)。purpose_data 绑 seller_id+delta_units+reason。",
         "tags": [
           "admin"
         ],
@@ -815,9 +865,9 @@
         ]
       }
     },
-    "/api/admin/governance/appeals": {
-      "get": {
-        "summary": "GET /api/admin/governance/appeals — maintainer 看待裁决申诉",
+    "/api/admin/direct-receive/fee-prepay": {
+      "post": {
+        "summary": "不碰 buyer wallet/escrow/order/settlement/refund;非买家 escrow/保证金/penalty。本轮无\"余额退款\"(仅正向预付款登记)。",
         "tags": [
           "admin"
         ],
@@ -828,9 +878,9 @@
         ]
       }
     },
-    "/api/admin/governance/application/:id": {
+    "/api/admin/direct-receive/fee-prepay-requests": {
       "get": {
-        "summary": "GET /api/admin/governance/application/:id — 详情(含 expected_verdict 用于对比 — 仅 maintainer 看)",
+        "summary": "GET /api/admin/direct-receive/fee-prepay-requests?status=pending — ROOT 只读:预充值申请队列(核对到账用)。",
         "tags": [
           "admin"
         ],
@@ -841,9 +891,9 @@
         ]
       }
     },
-    "/api/admin/governance/applications": {
-      "get": {
-        "summary": "GET /api/admin/governance/applications — 列出 pending_onboarding(可筛 quiz_passed + has_case_review)",
+    "/api/admin/direct-receive/fee-prepay-requests/:id/approve": {
+      "post": {
+        "summary": "purpose_data 绑 request_id + seller_id + amount_units + method(把入账金额/对象钉进 Passkey)。原子:approved + recordFeePrepay + 关联 payment。",
         "tags": [
           "admin"
         ],
@@ -854,9 +904,9 @@
         ]
       }
     },
-    "/api/admin/governance/auto-deactivations": {
-      "get": {
-        "summary": "spec §6.2 公示触发原因(透明 — 元规则 #1)",
+    "/api/admin/direct-receive/fee-prepay-requests/:id/reject": {
+      "post": {
+        "summary": "POST /api/admin/direct-receive/fee-prepay-requests/:id/reject — ROOT + Passkey(不动钱)。purpose_data 绑 request_id。",
         "tags": [
           "admin"
         ],
@@ -867,9 +917,9 @@
         ]
       }
     },
-    "/api/admin/governance/resolve-appeal": {
+    "/api/admin/direct-receive/fee-refund": {
       "post": {
-        "summary": "accept → 恢复 active(spec §7.2) ;reject → 维持 inactive,公开理由",
+        "summary": "amount ≤ 当前 available(helper 同事务校验)。append-only + audit。purpose_data 绑 seller_id+amount_units+method+evidence_ref。",
         "tags": [
           "admin"
         ],
@@ -880,9 +930,9 @@
         ]
       }
     },
-    "/api/admin/governance/run-auto-deactivate": {
+    "/api/admin/direct-receive/kyb-reviews": {
       "post": {
-        "summary": "Useful for ops + testing. The scheduled cron also runs every N hours.",
+        "summary": "Passkey purpose_data 绑定【完整写入内容】(user_id+status+provider_ref+expires_at):签 A 写 B 一律拒。",
         "tags": [
           "admin"
         ],
@@ -893,9 +943,9 @@
         ]
       }
     },
-    "/api/admin/health": {
+    "/api/admin/direct-receive/product-verifications": {
       "get": {
-        "summary": "GET /api/admin/health",
+        "summary": "GET /api/admin/direct-receive/product-verifications?status=submitted — ROOT 审核队列(默认全部)。纯读。",
         "tags": [
           "admin"
         ],
@@ -906,16 +956,9 @@
         ]
       }
     },
-    "/api/admin/hot-wallet": {
-      "get": {
-        "summary": "Legacy x-admin-key 入口：仅余额",
-        "tags": [],
-        "security": []
-      }
-    },
-    "/api/admin/hot-wallet/status": {
-      "get": {
-        "summary": "P2-5: protocol 权限（区域 admin 看不到全局热钱包）",
+    "/api/admin/direct-receive/product-verifications/:id/review": {
+      "post": {
+        "summary": "Passkey purpose_data 绑 verification_id + decision:签 A 用 B / 改结论一律拒。verify = 放行该产品直付(逐品,绝不放行全部)。",
         "tags": [
           "admin"
         ],
@@ -926,9 +969,9 @@
         ]
       }
     },
-    "/api/admin/kyc/:user_id/approve": {
+    "/api/admin/direct-receive/readiness": {
       "post": {
-        "summary": "POST /api/admin/kyc/:user_id/approve",
+        "summary": "含 KYB/sanctions/AML/base-bond/rail clearance 全细节)。只读诊断(不写库、不 flip launch);ROOT 专用,买家/卖家拿不到。",
         "tags": [
           "admin"
         ],
@@ -939,9 +982,9 @@
         ]
       }
     },
-    "/api/admin/kyc/:user_id/reject": {
+    "/api/admin/direct-receive/sanctions-screenings": {
       "post": {
-        "summary": "POST /api/admin/kyc/:user_id/reject",
+        "summary": "purpose_data 绑定 user_id+status+provider_ref+expires_at。",
         "tags": [
           "admin"
         ],
@@ -952,9 +995,9 @@
         ]
       }
     },
-    "/api/admin/kyc/pending": {
+    "/api/admin/direct-receive/store-verifications": {
       "get": {
-        "summary": "─── KYC ──────────────────────────────────────────────────────",
+        "summary": "GET /api/admin/direct-receive/store-verifications?status=submitted — ROOT 审核队列(默认全部)。纯读。",
         "tags": [
           "admin"
         ],
@@ -965,20 +1008,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims": {
-      "get": {
-        "summary": "── ROOT: review queue (all claims, optional ?status=) ──",
-        "tags": [
-          "admin"
-        ],
-        "security": [
-          {
-            "bearerAuth": []
-          }
-        ]
-      },
+    "/api/admin/direct-receive/store-verifications/:id/review": {
       "post": {
-        "summary": "── admin proposes linking THEIR OWN seat to a contributor account ──",
+        "summary": "POST /api/admin/direct-receive/store-verifications/:id/review — ROOT + 真人 Passkey 核店铺 + 勾选逐品豁免。",
         "tags": [
           "admin"
         ],
@@ -989,11 +1021,12 @@
         ]
       }
     },
-    "/api/admin/operator-claims/:approvedEventId/revoke": {
-      "post": {
-        "summary": "── ROOT: revoke an APPROVED (active) claim ──",
+    "/api/admin/disputes": {
+      "get": {
+        "summary": "GET /api/admin/disputes",
         "tags": [
-          "admin"
+          "admin",
+          "dispute"
         ],
         "security": [
           {
@@ -1002,9 +1035,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims/:claimedEventId": {
+    "/api/admin/economic-summary": {
       "get": {
-        "summary": "── ROOT: claim detail ──",
+        "summary": "隐私第一：运营财务，仅 protocol admin 可见。",
         "tags": [
           "admin"
         ],
@@ -1015,9 +1048,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims/:claimedEventId/approve": {
-      "post": {
-        "summary": "── ROOT: approve a proposed-or-confirmed claim ──",
+    "/api/admin/editor-picks": {
+      "get": {
+        "summary": "GET /api/admin/editor-picks",
         "tags": [
           "admin"
         ],
@@ -1026,11 +1059,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/operator-claims/:claimedEventId/reject": {
+      },
       "post": {
-        "summary": "── ROOT: reject a still-proposed/confirmed claim ──",
+        "summary": "POST /api/admin/editor-picks",
         "tags": [
           "admin"
         ],
@@ -1041,9 +1072,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims/me": {
-      "get": {
-        "summary": "admin-seat owner can request/track unlink on their own active claims) ──",
+    "/api/admin/editor-picks/:id": {
+      "delete": {
+        "summary": "DELETE /api/admin/editor-picks/:id",
         "tags": [
           "admin"
         ],
@@ -1054,9 +1085,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims/unlink/:requestEventId/approve": {
-      "post": {
-        "summary": "relationship/request, approval_kind + conflict_disclosure are required (governance honesty). ──",
+    "/api/admin/email-subscriptions": {
+      "get": {
+        "summary": "2026-05-25 admin 查邮箱订阅 — 独立端点，与建议分开",
         "tags": [
           "admin"
         ],
@@ -1067,9 +1098,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims/unlink/:requestEventId/reject": {
-      "post": {
-        "summary": "── ROOT: reject an unlink request → claim stays active. Same self-or-related marking discipline. ──",
+    "/api/admin/email-subscriptions/:id/status": {
+      "patch": {
+        "summary": "2026-05-29: admin 标记申请处理状态（pending→contacted→invited→done）— 不动 POST 提交逻辑",
         "tags": [
           "admin"
         ],
@@ -1080,9 +1111,9 @@
         ]
       }
     },
-    "/api/admin/operator-claims/unlink/requests": {
+    "/api/admin/errors": {
       "get": {
-        "summary": "self_or_related flags each request the viewing root is a party to → the UI then REQUIRES honest marking. ──",
+        "summary": "GET /api/admin/errors",
         "tags": [
           "admin"
         ],
@@ -1093,12 +1124,11 @@
         ]
       }
     },
-    "/api/admin/orders": {
+    "/api/admin/errors/aggregate": {
       "get": {
-        "summary": "GET /api/admin/orders",
+        "summary": "Tier 1 #5: 错误聚合 view（24h / 1h 趋势 + top by source + top messages + burst alert）",
         "tags": [
-          "admin",
-          "order"
+          "admin"
         ],
         "security": [
           {
@@ -1107,9 +1137,9 @@
         ]
       }
     },
-    "/api/admin/payment-methods": {
+    "/api/admin/events/recent": {
       "get": {
-        "summary": "─── Admin payment_methods CRUD（root admin only · 基础设施变更需根权限）─",
+        "summary": "GET /api/admin/events/recent",
         "tags": [
           "admin"
         ],
@@ -1118,9 +1148,18 @@
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/admin/events/stream": {
+      "get": {
+        "summary": "GET /api/admin/events/stream",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/admin/events/ticket": {
       "post": {
-        "summary": "POST /api/admin/payment-methods",
+        "summary": "POST /api/admin/events/ticket",
         "tags": [
           "admin"
         ],
@@ -1131,9 +1170,9 @@
         ]
       }
     },
-    "/api/admin/payment-methods/:id": {
-      "delete": {
-        "summary": "DELETE /api/admin/payment-methods/:id",
+    "/api/admin/export/:kind": {
+      "get": {
+        "summary": "GET /api/admin/export/:kind",
         "tags": [
           "admin"
         ],
@@ -1142,12 +1181,12 @@
             "bearerAuth": []
           }
         ]
-      },
-      "put": {
-        "summary": "PUT /api/admin/payment-methods/:id",
-        "tags": [
-          "admin"
-        ],
+      }
+    },
+    "/api/admin/feedback": {
+      "get": {
+        "summary": "admin 列出工单",
+        "tags": [],
         "security": [
           {
             "bearerAuth": []
@@ -1155,9 +1194,20 @@
         ]
       }
     },
-    "/api/admin/products": {
+    "/api/admin/feedback/:id/reply": {
+      "post": {
+        "summary": "admin 回复 + 切状态",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/finance/monthly": {
       "get": {
-        "summary": "─── 商品 列表 + 强制下架 ───────────────────────────────",
+        "summary": "GET /api/admin/finance/monthly",
         "tags": [
           "admin"
         ],
@@ -1168,9 +1218,9 @@
         ]
       }
     },
-    "/api/admin/products/:id/force-delist": {
+    "/api/admin/governance/activate": {
       "post": {
-        "summary": "POST /api/admin/products/:id/force-delist",
+        "summary": "body: { application_id, webauthn_token, note? }",
         "tags": [
           "admin"
         ],
@@ -1181,9 +1231,9 @@
         ]
       }
     },
-    "/api/admin/protocol-kpi": {
+    "/api/admin/governance/appeals": {
       "get": {
-        "summary": "GET /api/admin/protocol-kpi",
+        "summary": "GET /api/admin/governance/appeals — maintainer 看待裁决申诉",
         "tags": [
           "admin"
         ],
@@ -1194,9 +1244,9 @@
         ]
       }
     },
-    "/api/admin/protocol-params": {
+    "/api/admin/governance/application/:id": {
       "get": {
-        "summary": "GET /api/admin/protocol-params",
+        "summary": "GET /api/admin/governance/application/:id — 详情(含 expected_verdict 用于对比 — 仅 maintainer 看)",
         "tags": [
           "admin"
         ],
@@ -1207,9 +1257,9 @@
         ]
       }
     },
-    "/api/admin/protocol-params/:key": {
-      "patch": {
-        "summary": "2026-06-03 #1095: + constitutional only-increase 守护",
+    "/api/admin/governance/applications": {
+      "get": {
+        "summary": "GET /api/admin/governance/applications — 列出 pending_onboarding(可筛 quiz_passed + has_case_review)",
         "tags": [
           "admin"
         ],
@@ -1220,9 +1270,9 @@
         ]
       }
     },
-    "/api/admin/protocol-params/:key/history": {
+    "/api/admin/governance/auto-deactivations": {
       "get": {
-        "summary": "A-3: 变更历史",
+        "summary": "spec §6.2 公示触发原因(透明 — 元规则 #1)",
         "tags": [
           "admin"
         ],
@@ -1233,9 +1283,9 @@
         ]
       }
     },
-    "/api/admin/protocol-params/:key/reset": {
+    "/api/admin/governance/resolve-appeal": {
       "post": {
-        "summary": "POST /api/admin/protocol-params/:key/reset",
+        "summary": "accept → 恢复 active(spec §7.2) ;reject → 维持 inactive,公开理由",
         "tags": [
           "admin"
         ],
@@ -1246,9 +1296,9 @@
         ]
       }
     },
-    "/api/admin/public-ideas": {
-      "get": {
-        "summary": "─── admin 端 ─────────────────────────────────────────────",
+    "/api/admin/governance/run-auto-deactivate": {
+      "post": {
+        "summary": "Useful for ops + testing. The scheduled cron also runs every N hours.",
         "tags": [
           "admin"
         ],
@@ -1259,9 +1309,9 @@
         ]
       }
     },
-    "/api/admin/public-ideas/:id": {
-      "patch": {
-        "summary": "PATCH /api/admin/public-ideas/:id",
+    "/api/admin/health": {
+      "get": {
+        "summary": "GET /api/admin/health",
         "tags": [
           "admin"
         ],
@@ -1272,9 +1322,16 @@
         ]
       }
     },
-    "/api/admin/quota-applications": {
+    "/api/admin/hot-wallet": {
       "get": {
-        "summary": "Admin",
+        "summary": "Legacy x-admin-key 入口：仅余额",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/admin/hot-wallet/status": {
+      "get": {
+        "summary": "P2-5: protocol 权限（区域 admin 看不到全局热钱包）",
         "tags": [
           "admin"
         ],
@@ -1285,9 +1342,9 @@
         ]
       }
     },
-    "/api/admin/quota-applications/:id/approve": {
+    "/api/admin/kyc/:user_id/approve": {
       "post": {
-        "summary": "POST /api/admin/quota-applications/:id/approve",
+        "summary": "POST /api/admin/kyc/:user_id/approve",
         "tags": [
           "admin"
         ],
@@ -1298,9 +1355,9 @@
         ]
       }
     },
-    "/api/admin/quota-applications/:id/reject": {
+    "/api/admin/kyc/:user_id/reject": {
       "post": {
-        "summary": "POST /api/admin/quota-applications/:id/reject",
+        "summary": "POST /api/admin/kyc/:user_id/reject",
         "tags": [
           "admin"
         ],
@@ -1311,9 +1368,9 @@
         ]
       }
     },
-    "/api/admin/quota-requests": {
+    "/api/admin/kyc/pending": {
       "get": {
-        "summary": "list quota requests (optional ?status=)",
+        "summary": "─── KYC ──────────────────────────────────────────────────────",
         "tags": [
           "admin"
         ],
@@ -1324,9 +1381,9 @@
         ]
       }
     },
-    "/api/admin/quota-requests/:id": {
+    "/api/admin/operator-claims": {
       "get": {
-        "summary": "detail of one request + the requester's live 24h create usage (reviewer context)",
+        "summary": "── ROOT: review queue (all claims, optional ?status=) ──",
         "tags": [
           "admin"
         ],
@@ -1335,11 +1392,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/quota-requests/:id/approve": {
+      },
       "post": {
-        "summary": "approve → time-boxed counted grant (self-approval rejected in the store)",
+        "summary": "── admin proposes linking THEIR OWN seat to a contributor account ──",
         "tags": [
           "admin"
         ],
@@ -1350,9 +1405,9 @@
         ]
       }
     },
-    "/api/admin/quota-requests/:id/reject": {
+    "/api/admin/operator-claims/:approvedEventId/revoke": {
       "post": {
-        "summary": "reject (self-rejection also blocked by the store's SELF_DECISION guard)",
+        "summary": "── ROOT: revoke an APPROVED (active) claim ──",
         "tags": [
           "admin"
         ],
@@ -1363,9 +1418,9 @@
         ]
       }
     },
-    "/api/admin/quota-requests/:id/revoke": {
-      "post": {
-        "summary": "revoke an already-approved grant (root)",
+    "/api/admin/operator-claims/:claimedEventId": {
+      "get": {
+        "summary": "── ROOT: claim detail ──",
         "tags": [
           "admin"
         ],
@@ -1376,9 +1431,9 @@
         ]
       }
     },
-    "/api/admin/region-payment-methods": {
-      "get": {
-        "summary": "─── region_payment_methods CRUD ──────────────────────────",
+    "/api/admin/operator-claims/:claimedEventId/approve": {
+      "post": {
+        "summary": "── ROOT: approve a proposed-or-confirmed claim ──",
         "tags": [
           "admin"
         ],
@@ -1387,9 +1442,11 @@
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/admin/operator-claims/:claimedEventId/reject": {
       "post": {
-        "summary": "POST /api/admin/region-payment-methods",
+        "summary": "── ROOT: reject a still-proposed/confirmed claim ──",
         "tags": [
           "admin"
         ],
@@ -1400,9 +1457,9 @@
         ]
       }
     },
-    "/api/admin/region-payment-methods/:id": {
-      "delete": {
-        "summary": "DELETE /api/admin/region-payment-methods/:id",
+    "/api/admin/operator-claims/me": {
+      "get": {
+        "summary": "admin-seat owner can request/track unlink on their own active claims) ──",
         "tags": [
           "admin"
         ],
@@ -1411,9 +1468,11 @@
             "bearerAuth": []
           }
         ]
-      },
-      "put": {
-        "summary": "PUT /api/admin/region-payment-methods/:id",
+      }
+    },
+    "/api/admin/operator-claims/unlink/:requestEventId/approve": {
+      "post": {
+        "summary": "relationship/request, approval_kind + conflict_disclosure are required (governance honesty). ──",
         "tags": [
           "admin"
         ],
@@ -1424,10 +1483,12 @@
         ]
       }
     },
-    "/api/admin/reputation/decay": {
+    "/api/admin/operator-claims/unlink/:requestEventId/reject": {
       "post": {
-        "summary": "POST /api/admin/reputation/decay",
-        "tags": [],
+        "summary": "── ROOT: reject an unlink request → claim stays active. Same self-or-related marking discipline. ──",
+        "tags": [
+          "admin"
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -1435,9 +1496,9 @@
         ]
       }
     },
-    "/api/admin/rewards-health": {
+    "/api/admin/operator-claims/unlink/requests": {
       "get": {
-        "summary": "以及\"在旧 major consent 上仍 opted-in\"= 下次 auto_downgrade cron 的降级候选。",
+        "summary": "self_or_related flags each request the viewing root is a party to → the UI then REQUIRES honest marking. ──",
         "tags": [
           "admin"
         ],
@@ -1448,11 +1509,12 @@
         ]
       }
     },
-    "/api/admin/risk/suspend/:user_id": {
-      "post": {
-        "summary": "POST /api/admin/risk/suspend/:user_id",
+    "/api/admin/orders": {
+      "get": {
+        "summary": "GET /api/admin/orders",
         "tags": [
-          "admin"
+          "admin",
+          "order"
         ],
         "security": [
           {
@@ -1461,9 +1523,9 @@
         ]
       }
     },
-    "/api/admin/risk/suspicious": {
+    "/api/admin/payment-methods": {
       "get": {
-        "summary": "─── D-1 风控告警 ────────────────────────────────────────────",
+        "summary": "─── Admin payment_methods CRUD（root admin only · 基础设施变更需根权限）─",
         "tags": [
           "admin"
         ],
@@ -1472,11 +1534,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/risk/unsuspend/:user_id": {
+      },
       "post": {
-        "summary": "POST /api/admin/risk/unsuspend/:user_id",
+        "summary": "POST /api/admin/payment-methods",
         "tags": [
           "admin"
         ],
@@ -1487,9 +1547,9 @@
         ]
       }
     },
-    "/api/admin/skill-market/:id/audit": {
-      "post": {
-        "summary": "─── Admin：审核 ────────────────────────────────────────────",
+    "/api/admin/payment-methods/:id": {
+      "delete": {
+        "summary": "DELETE /api/admin/payment-methods/:id",
         "tags": [
           "admin"
         ],
@@ -1498,11 +1558,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/skill-market/pending": {
-      "get": {
-        "summary": "─── Admin：待审列表 ────────────────────────────────────────",
+      },
+      "put": {
+        "summary": "PUT /api/admin/payment-methods/:id",
         "tags": [
           "admin"
         ],
@@ -1513,9 +1571,9 @@
         ]
       }
     },
-    "/api/admin/task-proposals": {
+    "/api/admin/platform-receive-accounts": {
       "get": {
-        "summary": "admin list (maintainer only)",
+        "summary": "── list(ROOT 读;含 inactive + qr_data_uri)──",
         "tags": [
           "admin"
         ],
@@ -1524,11 +1582,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/task-proposals/:id/ai-assist": {
+      },
       "post": {
-        "summary": "NEVER a decision: no auto-publish / auto-reject / hide / reward. A human admin must act explicitly.",
+        "summary": "── add(ROOT + Passkey)──",
         "tags": [
           "admin"
         ],
@@ -1539,9 +1595,9 @@
         ]
       }
     },
-    "/api/admin/task-proposals/:id/ai-suggestions": {
-      "get": {
-        "summary": "stored AI suggestions (evidence) for a proposal",
+    "/api/admin/platform-receive-accounts/:id": {
+      "delete": {
+        "summary": "── deactivate(ROOT + Passkey + 存在性)──",
         "tags": [
           "admin"
         ],
@@ -1550,11 +1606,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/task-proposals/:id/create-task-draft": {
-      "post": {
-        "summary": "No auto-publish (draft is internal/unclaimable until an explicit publish); no reward/credit side effect.",
+      },
+      "put": {
+        "summary": "── update(ROOT + Passkey + 存在性)──",
         "tags": [
           "admin"
         ],
@@ -1565,9 +1619,9 @@
         ]
       }
     },
-    "/api/admin/task-proposals/:id/review": {
-      "post": {
-        "summary": "admin review (maintainer only): needs_info | rejected | converted — no build_task is created here.",
+    "/api/admin/products": {
+      "get": {
+        "summary": "─── 商品 列表 + 强制下架 ───────────────────────────────",
         "tags": [
           "admin"
         ],
@@ -1578,9 +1632,9 @@
         ]
       }
     },
-    "/api/admin/tokenomics": {
-      "get": {
-        "summary": "Tokenomics 详细数据 + Tier 配置 + 高额榜",
+    "/api/admin/products/:id/force-delist": {
+      "post": {
+        "summary": "POST /api/admin/products/:id/force-delist",
         "tags": [
           "admin"
         ],
@@ -1591,9 +1645,9 @@
         ]
       }
     },
-    "/api/admin/tokenomics/require-ref/toggle": {
-      "post": {
-        "summary": "注册必须 ref 开关",
+    "/api/admin/protocol-kpi": {
+      "get": {
+        "summary": "GET /api/admin/protocol-kpi",
         "tags": [
           "admin"
         ],
@@ -1604,9 +1658,9 @@
         ]
       }
     },
-    "/api/admin/trial/run-eval": {
-      "post": {
-        "summary": "Admin 手动触发测评评估（测试 + 紧急 + 立即生效）",
+    "/api/admin/protocol-params": {
+      "get": {
+        "summary": "GET /api/admin/protocol-params",
         "tags": [
           "admin"
         ],
@@ -1617,16 +1671,9 @@
         ]
       }
     },
-    "/api/admin/usage": {
-      "get": {
-        "summary": "GET /api/admin/usage",
-        "tags": [],
-        "security": []
-      }
-    },
-    "/api/admin/users": {
-      "get": {
-        "summary": "GET /api/admin/users",
+    "/api/admin/protocol-params/:key": {
+      "patch": {
+        "summary": "2026-06-03 #1095: + constitutional only-increase 守护",
         "tags": [
           "admin"
         ],
@@ -1637,9 +1684,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/force-delist-all": {
-      "post": {
-        "summary": "POST /api/admin/users/:id/force-delist-all",
+    "/api/admin/protocol-params/:key/history": {
+      "get": {
+        "summary": "A-3: 变更历史",
         "tags": [
           "admin"
         ],
@@ -1650,9 +1697,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/grant-role": {
+    "/api/admin/protocol-params/:key/reset": {
       "post": {
-        "summary": "P0.1: admin 角色提权必须 root；其他角色需 users + scope",
+        "summary": "POST /api/admin/protocol-params/:key/reset",
         "tags": [
           "admin"
         ],
@@ -1663,9 +1710,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/l1-share-override": {
-      "post": {
-        "summary": "L1 分享权限 override：0 auto / 1 强允 / -1 强禁",
+    "/api/admin/public-ideas": {
+      "get": {
+        "summary": "─── admin 端 ─────────────────────────────────────────────",
         "tags": [
           "admin"
         ],
@@ -1676,9 +1723,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/pause-listing": {
-      "post": {
-        "summary": "POST /api/admin/users/:id/pause-listing",
+    "/api/admin/public-ideas/:id": {
+      "patch": {
+        "summary": "PATCH /api/admin/public-ideas/:id",
         "tags": [
           "admin"
         ],
@@ -1689,9 +1736,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/profile": {
+    "/api/admin/quota-applications": {
       "get": {
-        "summary": "完整档案聚合",
+        "summary": "Admin",
         "tags": [
           "admin"
         ],
@@ -1702,9 +1749,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/reset-failed-attempts": {
+    "/api/admin/quota-applications/:id/approve": {
       "post": {
-        "summary": "解除账号登录锁定：清零失败次数 + 解锁",
+        "summary": "POST /api/admin/quota-applications/:id/approve",
         "tags": [
           "admin"
         ],
@@ -1715,9 +1762,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/resume-listing": {
+    "/api/admin/quota-applications/:id/reject": {
       "post": {
-        "summary": "POST /api/admin/users/:id/resume-listing",
+        "summary": "POST /api/admin/quota-applications/:id/reject",
         "tags": [
           "admin"
         ],
@@ -1728,9 +1775,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/revoke-role": {
-      "post": {
-        "summary": "P0.3: revoke admin → root only",
+    "/api/admin/quota-requests": {
+      "get": {
+        "summary": "list quota requests (optional ?status=)",
         "tags": [
           "admin"
         ],
@@ -1741,9 +1788,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/set-product-quota": {
-      "post": {
-        "summary": "POST /api/admin/users/:id/set-product-quota",
+    "/api/admin/quota-requests/:id": {
+      "get": {
+        "summary": "detail of one request + the requester's live 24h create usage (reviewer context)",
         "tags": [
           "admin"
         ],
@@ -1754,16 +1801,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/set-roles": {
-      "post": {
-        "summary": "P0.2: preview diff，含 admin 变更 → root only",
-        "tags": [],
-        "security": []
-      }
-    },
-    "/api/admin/users/:id/suspend": {
+    "/api/admin/quota-requests/:id/approve": {
       "post": {
-        "summary": "P0.4: users + scope；suspend admin → root only",
+        "summary": "approve → time-boxed counted grant (self-approval rejected in the store)",
         "tags": [
           "admin"
         ],
@@ -1774,9 +1814,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/timeline": {
-      "get": {
-        "summary": "Wave F-3: 完整事件流",
+    "/api/admin/quota-requests/:id/reject": {
+      "post": {
+        "summary": "reject (self-rejection also blocked by the store's SELF_DECISION guard)",
         "tags": [
           "admin"
         ],
@@ -1787,9 +1827,9 @@
         ]
       }
     },
-    "/api/admin/users/:id/unsuspend": {
+    "/api/admin/quota-requests/:id/revoke": {
       "post": {
-        "summary": "POST /api/admin/users/:id/unsuspend",
+        "summary": "revoke an already-approved grant (root)",
         "tags": [
           "admin"
         ],
@@ -1800,9 +1840,20 @@
         ]
       }
     },
-    "/api/admin/users/batch-action": {
+    "/api/admin/region-payment-methods": {
+      "get": {
+        "summary": "─── region_payment_methods CRUD ──────────────────────────",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
       "post": {
-        "summary": "POST /api/admin/users/batch-action",
+        "summary": "POST /api/admin/region-payment-methods",
         "tags": [
           "admin"
         ],
@@ -1813,9 +1864,9 @@
         ]
       }
     },
-    "/api/admin/users/lookup": {
-      "get": {
-        "summary": "P1-1: 按 handle / id 任意角色查找",
+    "/api/admin/region-payment-methods/:id": {
+      "delete": {
+        "summary": "DELETE /api/admin/region-payment-methods/:id",
         "tags": [
           "admin"
         ],
@@ -1824,11 +1875,9 @@
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/admin/verifier-appeals": {
-      "get": {
-        "summary": "GET /api/admin/verifier-appeals",
+      },
+      "put": {
+        "summary": "PUT /api/admin/region-payment-methods/:id",
         "tags": [
           "admin"
         ],
@@ -1839,9 +1888,20 @@
         ]
       }
     },
-    "/api/admin/verifier-appeals/:id/decide": {
+    "/api/admin/reputation/decay": {
       "post": {
-        "summary": "POST /api/admin/verifier-appeals/:id/decide",
+        "summary": "POST /api/admin/reputation/decay",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/rewards-health": {
+      "get": {
+        "summary": "以及\"在旧 major consent 上仍 opted-in\"= 下次 auto_downgrade cron 的降级候选。",
         "tags": [
           "admin"
         ],
@@ -1852,9 +1912,9 @@
         ]
       }
     },
-    "/api/admin/verifier-applications": {
-      "get": {
-        "summary": "GET /api/admin/verifier-applications",
+    "/api/admin/risk/suspend/:user_id": {
+      "post": {
+        "summary": "POST /api/admin/risk/suspend/:user_id",
         "tags": [
           "admin"
         ],
@@ -1865,9 +1925,9 @@
         ]
       }
     },
-    "/api/admin/verifier-applications/:id/approve": {
-      "post": {
-        "summary": "POST /api/admin/verifier-applications/:id/approve",
+    "/api/admin/risk/suspicious": {
+      "get": {
+        "summary": "─── D-1 风控告警 ────────────────────────────────────────────",
         "tags": [
           "admin"
         ],
@@ -1878,9 +1938,9 @@
         ]
       }
     },
-    "/api/admin/verifier-applications/:id/reject": {
+    "/api/admin/risk/unsuspend/:user_id": {
       "post": {
-        "summary": "POST /api/admin/verifier-applications/:id/reject",
+        "summary": "POST /api/admin/risk/unsuspend/:user_id",
         "tags": [
           "admin"
         ],
@@ -1891,9 +1951,9 @@
         ]
       }
     },
-    "/api/admin/verifier-whitelist": {
-      "get": {
-        "summary": "GET /api/admin/verifier-whitelist",
+    "/api/admin/skill-market/:id/audit": {
+      "post": {
+        "summary": "─── Admin：审核 ────────────────────────────────────────────",
         "tags": [
           "admin"
         ],
@@ -1902,9 +1962,11 @@
             "bearerAuth": []
           }
         ]
-      },
-      "post": {
-        "summary": "POST /api/admin/verifier-whitelist",
+      }
+    },
+    "/api/admin/skill-market/pending": {
+      "get": {
+        "summary": "─── Admin：待审列表 ────────────────────────────────────────",
         "tags": [
           "admin"
         ],
@@ -1915,9 +1977,9 @@
         ]
       }
     },
-    "/api/admin/verifier-whitelist/:userId": {
-      "delete": {
-        "summary": "DELETE /api/admin/verifier-whitelist/:userId",
+    "/api/admin/task-proposals": {
+      "get": {
+        "summary": "admin list (maintainer only)",
         "tags": [
           "admin"
         ],
@@ -1928,9 +1990,9 @@
         ]
       }
     },
-    "/api/admin/verifier-whitelist/:userId/promote": {
+    "/api/admin/task-proposals/:id/ai-assist": {
       "post": {
-        "summary": "POST /api/admin/verifier-whitelist/:userId/promote",
+        "summary": "NEVER a decision: no auto-publish / auto-reject / hide / reward. A human admin must act explicitly.",
         "tags": [
           "admin"
         ],
@@ -1941,9 +2003,9 @@
         ]
       }
     },
-    "/api/admin/verifier-whitelist/:userId/revoke": {
-      "post": {
-        "summary": "POST /api/admin/verifier-whitelist/:userId/revoke",
+    "/api/admin/task-proposals/:id/ai-suggestions": {
+      "get": {
+        "summary": "stored AI suggestions (evidence) for a proposal",
         "tags": [
           "admin"
         ],
@@ -1954,9 +2016,9 @@
         ]
       }
     },
-    "/api/admin/verifier-whitelist/:userId/suspend": {
+    "/api/admin/task-proposals/:id/create-task-draft": {
       "post": {
-        "summary": "POST /api/admin/verifier-whitelist/:userId/suspend",
+        "summary": "No auto-publish (draft is internal/unclaimable until an explicit publish); no reward/credit side effect.",
         "tags": [
           "admin"
         ],
@@ -1967,9 +2029,9 @@
         ]
       }
     },
-    "/api/admin/verify-tasks": {
-      "get": {
-        "summary": "GET /api/admin/verify-tasks",
+    "/api/admin/task-proposals/:id/review": {
+      "post": {
+        "summary": "admin review (maintainer only): needs_info | rejected | converted — no build_task is created here.",
         "tags": [
           "admin"
         ],
@@ -1980,9 +2042,9 @@
         ]
       }
     },
-    "/api/admin/wish-reports": {
+    "/api/admin/tokenomics": {
       "get": {
-        "summary": "─── admin 慈善管理 ─────────────────────────────────────────",
+        "summary": "Tokenomics 详细数据 + Tier 配置 + 高额榜",
         "tags": [
           "admin"
         ],
@@ -1993,9 +2055,9 @@
         ]
       }
     },
-    "/api/admin/wish-reports/:id": {
-      "patch": {
-        "summary": "PATCH /api/admin/wish-reports/:id",
+    "/api/admin/tokenomics/require-ref/toggle": {
+      "post": {
+        "summary": "注册必须 ref 开关",
         "tags": [
           "admin"
         ],
@@ -2006,9 +2068,9 @@
         ]
       }
     },
-    "/api/admin/wishes/:id/takedown": {
+    "/api/admin/trial/run-eval": {
       "post": {
-        "summary": "POST /api/admin/wishes/:id/takedown",
+        "summary": "Admin 手动触发测评评估（测试 + 紧急 + 立即生效）",
         "tags": [
           "admin"
         ],
@@ -2019,91 +2081,45 @@
         ]
       }
     },
-    "/api/admin/withdrawals": {
+    "/api/admin/usage": {
       "get": {
-        "summary": "GET /api/admin/withdrawals",
-        "tags": [],
-        "security": []
-      }
-    },
-    "/api/admin/withdrawals/:id/approve": {
-      "post": {
-        "summary": "POST /api/admin/withdrawals/:id/approve",
+        "summary": "GET /api/admin/usage",
         "tags": [],
         "security": []
       }
     },
-    "/api/agent-buy": {
-      "post": {
-        "summary": "Agent 智能下单 — 外链/搜索词输入 → 自动比价 + 推荐 / 锁价",
+    "/api/admin/users": {
+      "get": {
+        "summary": "GET /api/admin/users",
         "tags": [
-          "agent"
+          "admin"
         ],
         "security": [
           {
             "bearerAuth": []
           }
-        ],
-        "requestBody": {
-          "type": "object",
-          "properties": {
-            "source_url": {
-              "type": "string",
-              "format": "uri",
-              "description": "外站链接（淘宝/京东/Amazon 等）"
-            },
-            "shipping_address": {
-              "type": "string"
-            },
-            "auto_buy": {
-              "type": "boolean",
-              "default": false,
-              "description": "true 时自动下单，false 时仅返回推荐"
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "type": "object",
-            "properties": {
-              "recommendation": {
-                "enum": [
-                  "buy_webaz",
-                  "buy_source",
-                  "no_match"
-                ]
-              },
-              "best_product": {
-                "type": "object"
-              },
-              "webaz_products": {
-                "type": "array"
-              },
-              "order_id": {
-                "type": "string",
-                "description": "仅 auto_bought=true 时"
-              },
-              "auto_bought": {
-                "type": "boolean"
-              }
-            }
-          }
-        }
+        ]
       }
     },
-    "/api/agent-grants": {
-      "get": {
-        "summary": "\"Connected agents\" UI shows so a human can spot stale/unused or busy agents before revoking.",
-        "tags": [],
+    "/api/admin/users/:id/force-delist-all": {
+      "post": {
+        "summary": "POST /api/admin/users/:id/force-delist-all",
+        "tags": [
+          "admin"
+        ],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/admin/users/:id/grant-role": {
       "post": {
-        "summary": "── Issue a grant (human-authenticated). Safe scopes only; risk/never-delegable rejected. ──",
-        "tags": [],
+        "summary": "P0.1: admin 角色提权必须 root；其他角色需 users + scope",
+        "tags": [
+          "admin"
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -2111,10 +2127,12 @@
         ]
       }
     },
-    "/api/agent-grants/:grant_id/revoke": {
+    "/api/admin/users/:id/l1-share-override": {
       "post": {
-        "summary": "── Revoke (online, one-click). ──",
-        "tags": [],
+        "summary": "L1 分享权限 override：0 auto / 1 强允 / -1 强禁",
+        "tags": [
+          "admin"
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -2122,11 +2140,464 @@
         ]
       }
     },
-    "/api/agent-grants/pair/:pairing_id/retrieve": {
+    "/api/admin/users/:id/pause-listing": {
       "post": {
-        "summary": "(pair 4) Agent retrieves the credential ONCE via PKCE verifier — UNAUTHENTICATED (PKCE-gated).",
-        "tags": [],
-        "security": []
+        "summary": "POST /api/admin/users/:id/pause-listing",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/profile": {
+      "get": {
+        "summary": "完整档案聚合",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/reset-failed-attempts": {
+      "post": {
+        "summary": "解除账号登录锁定：清零失败次数 + 解锁",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/resume-listing": {
+      "post": {
+        "summary": "POST /api/admin/users/:id/resume-listing",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/revoke-role": {
+      "post": {
+        "summary": "P0.3: revoke admin → root only",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/set-product-quota": {
+      "post": {
+        "summary": "POST /api/admin/users/:id/set-product-quota",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/set-roles": {
+      "post": {
+        "summary": "P0.2: preview diff，含 admin 变更 → root only",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/admin/users/:id/suspend": {
+      "post": {
+        "summary": "P0.4: users + scope；suspend admin → root only",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/timeline": {
+      "get": {
+        "summary": "Wave F-3: 完整事件流",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/:id/unsuspend": {
+      "post": {
+        "summary": "POST /api/admin/users/:id/unsuspend",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/batch-action": {
+      "post": {
+        "summary": "POST /api/admin/users/batch-action",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/users/lookup": {
+      "get": {
+        "summary": "P1-1: 按 handle / id 任意角色查找",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-appeals": {
+      "get": {
+        "summary": "GET /api/admin/verifier-appeals",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-appeals/:id/decide": {
+      "post": {
+        "summary": "POST /api/admin/verifier-appeals/:id/decide",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-applications": {
+      "get": {
+        "summary": "GET /api/admin/verifier-applications",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-applications/:id/approve": {
+      "post": {
+        "summary": "POST /api/admin/verifier-applications/:id/approve",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-applications/:id/reject": {
+      "post": {
+        "summary": "POST /api/admin/verifier-applications/:id/reject",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-whitelist": {
+      "get": {
+        "summary": "GET /api/admin/verifier-whitelist",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "POST /api/admin/verifier-whitelist",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-whitelist/:userId": {
+      "delete": {
+        "summary": "DELETE /api/admin/verifier-whitelist/:userId",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-whitelist/:userId/promote": {
+      "post": {
+        "summary": "POST /api/admin/verifier-whitelist/:userId/promote",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-whitelist/:userId/revoke": {
+      "post": {
+        "summary": "POST /api/admin/verifier-whitelist/:userId/revoke",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verifier-whitelist/:userId/suspend": {
+      "post": {
+        "summary": "POST /api/admin/verifier-whitelist/:userId/suspend",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/verify-tasks": {
+      "get": {
+        "summary": "GET /api/admin/verify-tasks",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/wish-reports": {
+      "get": {
+        "summary": "─── admin 慈善管理 ─────────────────────────────────────────",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/wish-reports/:id": {
+      "patch": {
+        "summary": "PATCH /api/admin/wish-reports/:id",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/wishes/:id/takedown": {
+      "post": {
+        "summary": "POST /api/admin/wishes/:id/takedown",
+        "tags": [
+          "admin"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/admin/withdrawals": {
+      "get": {
+        "summary": "GET /api/admin/withdrawals",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/admin/withdrawals/:id/approve": {
+      "post": {
+        "summary": "POST /api/admin/withdrawals/:id/approve",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/agent-buy": {
+      "post": {
+        "summary": "Agent 智能下单 — 外链/搜索词输入 → 自动比价 + 推荐 / 锁价",
+        "tags": [
+          "agent"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "type": "object",
+          "properties": {
+            "source_url": {
+              "type": "string",
+              "format": "uri",
+              "description": "外站链接（淘宝/京东/Amazon 等）"
+            },
+            "shipping_address": {
+              "type": "string"
+            },
+            "auto_buy": {
+              "type": "boolean",
+              "default": false,
+              "description": "true 时自动下单，false 时仅返回推荐"
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "type": "object",
+            "properties": {
+              "recommendation": {
+                "enum": [
+                  "buy_webaz",
+                  "buy_source",
+                  "no_match"
+                ]
+              },
+              "best_product": {
+                "type": "object"
+              },
+              "webaz_products": {
+                "type": "array"
+              },
+              "order_id": {
+                "type": "string",
+                "description": "仅 auto_bought=true 时"
+              },
+              "auto_bought": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/agent-grants": {
+      "get": {
+        "summary": "\"Connected agents\" UI shows so a human can spot stale/unused or busy agents before revoking.",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "agent delegation\"的安全叙事。零消费方(前端/MCP/测试均不用),故降级为不可用,统一走 pairing。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/agent-grants/:grant_id/revoke": {
+      "post": {
+        "summary": "── Revoke (online, one-click). ──",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/agent-grants/my-permission-requests": {
+      "get": {
+        "summary": "grant_id: an agent sees ONLY its own requests, never the human's other agents'. Audited (fail-closed).",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/agent-grants/pair/:pairing_id/retrieve": {
+      "post": {
+        "summary": "(pair 4) Agent retrieves the credential ONCE via PKCE verifier — UNAUTHENTICATED (PKCE-gated).",
+        "tags": [],
+        "security": []
       }
     },
     "/api/agent-grants/pair/:user_code": {
@@ -2151,6 +2622,17 @@
         ]
       }
     },
+    "/api/agent-grants/pair/:user_code/reject": {
+      "post": {
+        "summary": "拒绝是保护性动作,无需 Passkey(不签发任何凭证)。幂等:仅 pending 可拒。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/agent-grants/pair/start": {
       "post": {
         "summary": "(pair 1) Agent starts a pairing — UNAUTHENTICATED (agent has no credential yet). Safe scopes only.",
@@ -2158,6 +2640,51 @@
         "security": []
       }
     },
+    "/api/agent-grants/permission-requests": {
+      "get": {
+        "summary": "GET list this human's PENDING permission requests (for #agent-approvals). Human-authed.",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "NOT grantable (they need a per-action live Passkey, not a persistent grant) → structured reject.",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/agent-grants/permission-requests/:id/approve": {
+      "post": {
+        "summary": "POST approve — human-authed + live Passkey; expands the bound grant (union scopes + bundle + extend expiry). Audited.",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/agent-grants/permission-requests/:id/reject": {
+      "post": {
+        "summary": "POST reject — human-authed. Terminal 'rejected'; nothing is granted.",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/agent-grants/verify": {
+      "get": {
+        "summary": "Audited (acceptance #8: every grant use logs). Never returns the raw token/api_key.",
+        "tags": [],
+        "security": []
+      }
+    },
     "/api/agent-grants/whoami": {
       "get": {
         "summary": "end-to-end on a brand-new read-only endpoint that touches NO existing route and NO money path.",
@@ -2234,7 +2761,19 @@
       "get": {
         "summary": "GET /api/agent/negative-space",
         "tags": [],
-        "security": []
+        "security": []
+      }
+    },
+    "/api/agent/seller/products": {
+      "get": {
+        "summary": "The consumption (allow AND the permission_required deny) is audited by the middleware.",
+        "tags": [],
+        "security": [
+          {
+            "grantBearer": []
+          }
+        ],
+        "x-webaz-grant-scope": "seller_products_read"
       }
     },
     "/api/agent/verifiability": {
@@ -2407,15 +2946,274 @@
               }
             }
           }
-        }
+        }
+      }
+    },
+    "/api/anchor/me": {
+      "get": {
+        "summary": "GET /api/anchor/me",
+        "tags": [
+          "anchor"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/announcements/:id/read": {
+      "post": {
+        "summary": "POST /api/announcements/:id/read",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/announcements/active": {
+      "get": {
+        "summary": "列出对当前用户可见的活跃公告（按角色 + 区域过滤）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/arbitrator/apply": {
+      "post": {
+        "summary": "POST /api/arbitrator/apply",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/arbitrator/eligibility": {
+      "get": {
+        "summary": "GET /api/arbitrator/eligibility",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/arbitrator/me/kpi": {
+      "get": {
+        "summary": "Arbitrator KPI（仲裁累计 + 裁决分布 + pending）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/arbitrator/status": {
+      "get": {
+        "summary": "GET /api/arbitrator/status",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/arbitrator/withdraw-application": {
+      "post": {
+        "summary": "POST /api/arbitrator/withdraw-application",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auctions": {
+      "get": {
+        "summary": "看板：浏览公开拍卖（匿名可访问）",
+        "tags": [],
+        "security": []
+      },
+      "post": {
+        "summary": "卖家发起拍卖",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auctions/:id": {
+      "delete": {
+        "summary": "卖家：取消（仅未出价时）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "get": {
+        "summary": "详情：含 bid 历史（buyer 身份脱敏；卖家+出价人本人 可见全名）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auctions/:id/bids": {
+      "post": {
+        "summary": "买家：出价",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auctions/:id/remind": {
+      "delete": {
+        "summary": "DELETE /api/auctions/:id/remind",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "get": {
+        "summary": "GET /api/auctions/:id/remind",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "拍卖「⏰ 提醒我」(#959)",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auctions/mine": {
+      "get": {
+        "summary": "我的：买家=我出过价的，卖家=我发起的",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auth/logout-all": {
+      "post": {
+        "summary": "要求密码二次验证（防 api_key 被盗后攻击者锁死真用户）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auth/sessions": {
+      "get": {
+        "summary": "GET /api/auth/sessions",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/auth/sessions/:id/revoke": {
+      "post": {
+        "summary": "远程吊销某个会话（不影响当前 session）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/bids/:id": {
+      "delete": {
+        "summary": "卖家：撤回 bid（释放 stake）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "patch": {
+        "summary": "卖家：修改 bid（仅 active；stake 差额自动结算）",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/blocklist": {
+      "get": {
+        "summary": "D-2: 列表",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/blocklist/:user_id": {
+      "delete": {
+        "summary": "DELETE /api/blocklist/:user_id",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "POST /api/blocklist/:user_id",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
       }
     },
-    "/api/anchor/me": {
+    "/api/blocklist/:user_id/status": {
       "get": {
-        "summary": "GET /api/anchor/me",
-        "tags": [
-          "anchor"
-        ],
+        "summary": "GET /api/blocklist/:user_id/status",
+        "tags": [],
         "security": [
           {
             "bearerAuth": []
@@ -2423,9 +3221,20 @@
         ]
       }
     },
-    "/api/announcements/:id/read": {
+    "/api/blocklist/me": {
+      "get": {
+        "summary": "GET /api/blocklist/me",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/build-feedback": {
       "post": {
-        "summary": "POST /api/announcements/:id/read",
+        "summary": "── 提交 ──────────────────────────────────────────────",
         "tags": [],
         "security": [
           {
@@ -2434,9 +3243,9 @@
         ]
       }
     },
-    "/api/announcements/active": {
+    "/api/build-feedback/:id": {
       "get": {
-        "summary": "列出对当前用户可见的活跃公告（按角色 + 区域过滤）",
+        "summary": "GET /api/build-feedback/:id",
         "tags": [],
         "security": [
           {
@@ -2445,9 +3254,9 @@
         ]
       }
     },
-    "/api/arbitrator/apply": {
-      "post": {
-        "summary": "POST /api/arbitrator/apply",
+    "/api/build-feedback/mine": {
+      "get": {
+        "summary": "── 闭环:我的反馈进度 ──(必须在 /:id 之前声明)──────────",
         "tags": [],
         "security": [
           {
@@ -2456,9 +3265,9 @@
         ]
       }
     },
-    "/api/arbitrator/eligibility": {
+    "/api/build-reputation/me": {
       "get": {
-        "summary": "GET /api/arbitrator/eligibility",
+        "summary": "BUILD reputation (coordination layer) only and promise no economic value.",
         "tags": [],
         "security": [
           {
@@ -2467,9 +3276,18 @@
         ]
       }
     },
-    "/api/arbitrator/me/kpi": {
+    "/api/build-tasks": {
       "get": {
-        "summary": "Arbitrator KPI（仲裁累计 + 裁决分布 + pending）",
+        "summary": "uncommitted value_boundary; member scope hides restricted/internal. Bad filter → fail-closed 400.",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "POST /api/build-tasks",
         "tags": [],
         "security": [
           {
@@ -2478,9 +3296,9 @@
         ]
       }
     },
-    "/api/arbitrator/status": {
+    "/api/build-tasks/:id": {
       "get": {
-        "summary": "GET /api/arbitrator/status",
+        "summary": "GET /api/build-tasks/:id",
         "tags": [],
         "security": [
           {
@@ -2489,9 +3307,9 @@
         ]
       }
     },
-    "/api/arbitrator/withdraw-application": {
+    "/api/build-tasks/:id/claim": {
       "post": {
-        "summary": "POST /api/arbitrator/withdraw-application",
+        "summary": "task → claim respects auto_claimable. Success appends value_boundary + canonical_contribution_target only.",
         "tags": [],
         "security": [
           {
@@ -2500,14 +3318,40 @@
         ]
       }
     },
-    "/api/auctions": {
+    "/api/build-tasks/:id/release": {
+      "post": {
+        "summary": "POST /api/build-tasks/:id/release",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/build-tasks/:id/submit": {
+      "post": {
+        "summary": "POST /api/build-tasks/:id/submit",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/cart": {
       "get": {
-        "summary": "看板：浏览公开拍卖（匿名可访问）",
+        "summary": "GET /api/cart",
         "tags": [],
-        "security": []
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
       },
       "post": {
-        "summary": "卖家发起拍卖",
+        "summary": "POST /api/cart",
         "tags": [],
         "security": [
           {
@@ -2516,9 +3360,9 @@
         ]
       }
     },
-    "/api/auctions/:id": {
+    "/api/cart/:product_id": {
       "delete": {
-        "summary": "卖家：取消（仅未出价时）",
+        "summary": "DELETE /api/cart/:product_id",
         "tags": [],
         "security": [
           {
@@ -2526,8 +3370,8 @@
           }
         ]
       },
-      "get": {
-        "summary": "详情：含 bid 历史（buyer 身份脱敏；卖家+出价人本人 可见全名）",
+      "patch": {
+        "summary": "PATCH /api/cart/:product_id",
         "tags": [],
         "security": [
           {
@@ -2536,9 +3380,9 @@
         ]
       }
     },
-    "/api/auctions/:id/bids": {
+    "/api/cart/checkout": {
       "post": {
-        "summary": "买家：出价",
+        "summary": "C-1: 购物车批量下单（按 seller 自动分订单）",
         "tags": [],
         "security": [
           {
@@ -2547,27 +3391,73 @@
         ]
       }
     },
-    "/api/auctions/:id/remind": {
-      "delete": {
-        "summary": "DELETE /api/auctions/:id/remind",
-        "tags": [],
+    "/api/charity/fund": {
+      "get": {
+        "summary": "GET 基金概况 + 最近流水",
+        "tags": [
+          "charity"
+        ],
+        "security": []
+      }
+    },
+    "/api/charity/fund/donate": {
+      "post": {
+        "summary": "任何人捐款给慈善基金",
+        "tags": [
+          "charity"
+        ],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/charity/leaderboard": {
       "get": {
-        "summary": "GET /api/auctions/:id/remind",
+        "summary": "慈善排行",
+        "tags": [
+          "charity"
+        ],
+        "security": []
+      }
+    },
+    "/api/charity/me": {
+      "get": {
+        "summary": "GET /api/charity/me — 我的慈善档案",
+        "tags": [
+          "charity"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/charity/stories": {
+      "get": {
+        "summary": "GET /api/charity/stories — 公开披露的故事板",
+        "tags": [
+          "charity"
+        ],
+        "security": []
+      }
+    },
+    "/api/check-url": {
+      "get": {
+        "summary": "GET /api/check-url",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/checkin": {
       "post": {
-        "summary": "拍卖「⏰ 提醒我」(#959)",
+        "summary": "POST /api/checkin",
         "tags": [],
         "security": [
           {
@@ -2576,9 +3466,9 @@
         ]
       }
     },
-    "/api/auctions/mine": {
+    "/api/checkin/status": {
       "get": {
-        "summary": "我的：买家=我出过价的，卖家=我发起的",
+        "summary": "GET /api/checkin/status",
         "tags": [],
         "security": [
           {
@@ -2587,9 +3477,9 @@
         ]
       }
     },
-    "/api/auth/logout-all": {
-      "post": {
-        "summary": "要求密码二次验证（防 api_key 被盗后攻击者锁死真用户）",
+    "/api/checkout/tax-preview": {
+      "get": {
+        "summary": "GET /api/checkout/tax-preview",
         "tags": [],
         "security": [
           {
@@ -2598,9 +3488,9 @@
         ]
       }
     },
-    "/api/auth/sessions": {
+    "/api/claim-tasks/:id": {
       "get": {
-        "summary": "GET /api/auth/sessions",
+        "summary": "任务详情",
         "tags": [],
         "security": [
           {
@@ -2609,9 +3499,9 @@
         ]
       }
     },
-    "/api/auth/sessions/:id/revoke": {
+    "/api/claim-tasks/:id/seller-evidence": {
       "post": {
-        "summary": "远程吊销某个会话（不影响当前 session）",
+        "summary": "卖家提交证据 → 延期 24h；状态保持 open",
         "tags": [],
         "security": [
           {
@@ -2620,18 +3510,20 @@
         ]
       }
     },
-    "/api/bids/:id": {
-      "delete": {
-        "summary": "卖家：撤回 bid（释放 stake）",
+    "/api/claim-tasks/:id/vote": {
+      "post": {
+        "summary": "verifier 投票 — 铁律 §4",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
-      "patch": {
-        "summary": "卖家：修改 bid（仅 active；stake 差额自动结算）",
+      }
+    },
+    "/api/claim-tasks/available": {
+      "get": {
+        "summary": "列出可接的 open 任务",
         "tags": [],
         "security": [
           {
@@ -2640,9 +3532,9 @@
         ]
       }
     },
-    "/api/blocklist": {
+    "/api/claim-tasks/mine": {
       "get": {
-        "summary": "D-2: 列表",
+        "summary": "我相关的任务（必须在 /:id 之前注册，否则被 /:id 截获）",
         "tags": [],
         "security": [
           {
@@ -2651,18 +3543,27 @@
         ]
       }
     },
-    "/api/blocklist/:user_id": {
-      "delete": {
-        "summary": "DELETE /api/blocklist/:user_id",
+    "/api/claim-url": {
+      "post": {
+        "summary": "POST /api/claim-url",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
-      "post": {
-        "summary": "POST /api/blocklist/:user_id",
+      }
+    },
+    "/api/claims/public": {
+      "get": {
+        "summary": "公开 #claims 广场（无 auth — 透明性是验证声明信任的前提）",
+        "tags": [],
+        "security": []
+      }
+    },
+    "/api/contribution-facts/me": {
+      "get": {
+        "summary": "── READ-ONLY: the caller's OWN attributable contribution facts (GitHub + admin coordination) ──",
         "tags": [],
         "security": [
           {
@@ -2671,9 +3572,9 @@
         ]
       }
     },
-    "/api/blocklist/:user_id/status": {
-      "get": {
-        "summary": "GET /api/blocklist/:user_id/status",
+    "/api/contribution-identity/github/claim-challenge": {
+      "post": {
+        "summary": "── 1) issue a publication challenge ─────────────────────────────────────────────────────────",
         "tags": [],
         "security": [
           {
@@ -2682,9 +3583,9 @@
         ]
       }
     },
-    "/api/blocklist/me": {
-      "get": {
-        "summary": "GET /api/blocklist/me",
+    "/api/contribution-identity/github/claim-complete": {
+      "post": {
+        "summary": "── 2) complete the claim (human gate → re-fetch gist proof → atomic consume+bind) ────────────",
         "tags": [],
         "security": [
           {
@@ -2693,9 +3594,9 @@
         ]
       }
     },
-    "/api/build-feedback": {
-      "post": {
-        "summary": "── 提交 ──────────────────────────────────────────────",
+    "/api/contribution-identity/github/claimable": {
+      "get": {
+        "summary": "carries the uncommitted-value boundary, and errors never leak SQL/stack.",
         "tags": [],
         "security": [
           {
@@ -2704,9 +3605,9 @@
         ]
       }
     },
-    "/api/build-feedback/:id": {
+    "/api/contribution-identity/github/me": {
       "get": {
-        "summary": "GET /api/build-feedback/:id",
+        "summary": "metering/display surface can never read as a payout promise — facts + attribution only.",
         "tags": [],
         "security": [
           {
@@ -2715,9 +3616,9 @@
         ]
       }
     },
-    "/api/build-feedback/mine": {
+    "/api/contribution-score/evidence/me": {
       "get": {
-        "summary": "── 闭环:我的反馈进度 ──(必须在 /:id 之前声明)──────────",
+        "summary": "always the session user. Output is component evidence wrapped in the uncommitted-value boundary.",
         "tags": [],
         "security": [
           {
@@ -2726,9 +3627,9 @@
         ]
       }
     },
-    "/api/build-reputation/me": {
+    "/api/conversations": {
       "get": {
-        "summary": "BUILD reputation (coordination layer) only and promise no economic value.",
+        "summary": "我的会话列表",
         "tags": [],
         "security": [
           {
@@ -2737,18 +3638,20 @@
         ]
       }
     },
-    "/api/build-tasks": {
+    "/api/conversations/:id": {
       "get": {
-        "summary": "uncommitted value_boundary; member scope hides restricted/internal. Bad filter → fail-closed 400.",
+        "summary": "会话详情 + 消息分页",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/conversations/:id/archive": {
       "post": {
-        "summary": "POST /api/build-tasks",
+        "summary": "归档（仅自己侧）",
         "tags": [],
         "security": [
           {
@@ -2757,9 +3660,9 @@
         ]
       }
     },
-    "/api/build-tasks/:id": {
-      "get": {
-        "summary": "GET /api/build-tasks/:id",
+    "/api/conversations/:id/block": {
+      "post": {
+        "summary": "拉黑（双向屏蔽）",
         "tags": [],
         "security": [
           {
@@ -2768,9 +3671,9 @@
         ]
       }
     },
-    "/api/build-tasks/:id/claim": {
+    "/api/conversations/:id/messages": {
       "post": {
-        "summary": "task → claim respects auto_claimable. Success appends value_boundary + canonical_contribution_target only.",
+        "summary": "发消息",
         "tags": [],
         "security": [
           {
@@ -2779,9 +3682,9 @@
         ]
       }
     },
-    "/api/build-tasks/:id/release": {
+    "/api/conversations/:id/read": {
       "post": {
-        "summary": "POST /api/build-tasks/:id/release",
+        "summary": "标记已读",
         "tags": [],
         "security": [
           {
@@ -2790,9 +3693,9 @@
         ]
       }
     },
-    "/api/build-tasks/:id/submit": {
+    "/api/conversations/:id/report": {
       "post": {
-        "summary": "POST /api/build-tasks/:id/submit",
+        "summary": "举报（人工审核）",
         "tags": [],
         "security": [
           {
@@ -2801,18 +3704,20 @@
         ]
       }
     },
-    "/api/cart": {
-      "get": {
-        "summary": "GET /api/cart",
+    "/api/conversations/start": {
+      "post": {
+        "summary": "开会话（idempotent — 已存在则返回 id）",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
+      }
+    },
+    "/api/coupons": {
       "post": {
-        "summary": "POST /api/cart",
+        "summary": "POST /api/coupons",
         "tags": [],
         "security": [
           {
@@ -2821,18 +3726,20 @@
         ]
       }
     },
-    "/api/cart/:product_id": {
-      "delete": {
-        "summary": "DELETE /api/cart/:product_id",
+    "/api/coupons/:id": {
+      "patch": {
+        "summary": "PATCH /api/coupons/:id",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      },
-      "patch": {
-        "summary": "PATCH /api/cart/:product_id",
+      }
+    },
+    "/api/coupons/available": {
+      "get": {
+        "summary": "buyer 视角：全平台 + 已购卖家店铺/单品券 + 历史",
         "tags": [],
         "security": [
           {
@@ -2841,9 +3748,9 @@
         ]
       }
     },
-    "/api/cart/checkout": {
-      "post": {
-        "summary": "C-1: 购物车批量下单（按 seller 自动分订单）",
+    "/api/coupons/mine": {
+      "get": {
+        "summary": "GET /api/coupons/mine",
         "tags": [],
         "security": [
           {
@@ -2852,21 +3759,10 @@
         ]
       }
     },
-    "/api/charity/fund": {
+    "/api/coupons/preview": {
       "get": {
-        "summary": "GET 基金概况 + 最近流水",
-        "tags": [
-          "charity"
-        ],
-        "security": []
-      }
-    },
-    "/api/charity/fund/donate": {
-      "post": {
-        "summary": "任何人捐款给慈善基金",
-        "tags": [
-          "charity"
-        ],
+        "summary": "GET /api/coupons/preview",
+        "tags": [],
         "security": [
           {
             "bearerAuth": []
@@ -2874,21 +3770,10 @@
         ]
       }
     },
-    "/api/charity/leaderboard": {
-      "get": {
-        "summary": "慈善排行",
-        "tags": [
-          "charity"
-        ],
-        "security": []
-      }
-    },
-    "/api/charity/me": {
+    "/api/creator/stats": {
       "get": {
-        "summary": "GET /api/charity/me — 我的慈善档案",
-        "tags": [
-          "charity"
-        ],
+        "summary": "里程碑 L3：创作者贡献仪表盘",
+        "tags": [],
         "security": [
           {
             "bearerAuth": []
@@ -2896,18 +3781,9 @@
         ]
       }
     },
-    "/api/charity/stories": {
-      "get": {
-        "summary": "GET /api/charity/stories — 公开披露的故事板",
-        "tags": [
-          "charity"
-        ],
-        "security": []
-      }
-    },
-    "/api/check-url": {
+    "/api/direct-pay/availability": {
       "get": {
-        "summary": "GET /api/check-url",
+        "summary": "GET /api/direct-pay/availability?product_id=... — 该商品(以 qty=1 计)当前是否可直付 + 不可用原因(脱敏)。",
         "tags": [],
         "security": [
           {
@@ -2916,9 +3792,9 @@
         ]
       }
     },
-    "/api/checkin": {
+    "/api/direct-pay/disclosure-acks": {
       "post": {
-        "summary": "POST /api/checkin",
+        "summary": "stage:'both' —— 单 stage token 冒充不了 both,both token 也重放不了单 stage(一次性消费 + validate 精确匹配)。",
         "tags": [],
         "security": [
           {
@@ -2927,9 +3803,9 @@
         ]
       }
     },
-    "/api/checkin/status": {
+    "/api/direct-pay/disclosure-acks/:orderId": {
       "get": {
-        "summary": "GET /api/checkin/status",
+        "summary": "GET — 查询某单两次 ack 状态 + 买家视角披露文案(无卖家机制)。只读(本人),不需 gate token。",
         "tags": [],
         "security": [
           {
@@ -2938,20 +3814,18 @@
         ]
       }
     },
-    "/api/checkout/tax-preview": {
+    "/api/direct-receive/accounts": {
       "get": {
-        "summary": "GET /api/checkout/tax-preview",
+        "summary": "── list（本人;不返回 raw QR,只含 qr_image_ref)──",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/claim-tasks/:id": {
-      "get": {
-        "summary": "任务详情",
+      },
+      "post": {
+        "summary": "── add(Passkey)──",
         "tags": [],
         "security": [
           {
@@ -2960,20 +3834,18 @@
         ]
       }
     },
-    "/api/claim-tasks/:id/seller-evidence": {
-      "post": {
-        "summary": "卖家提交证据 → 延期 24h；状态保持 open",
+    "/api/direct-receive/accounts/:id": {
+      "delete": {
+        "summary": "── deactivate(Passkey + owner)──",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/claim-tasks/:id/vote": {
-      "post": {
-        "summary": "verifier 投票 — 铁律 §4",
+      },
+      "put": {
+        "summary": "── update(Passkey + owner)──",
         "tags": [],
         "security": [
           {
@@ -2982,20 +3854,18 @@
         ]
       }
     },
-    "/api/claim-tasks/available": {
+    "/api/direct-receive/accounts/:id/qr": {
       "get": {
-        "summary": "列出可接的 open 任务",
+        "summary": "── QR preview(owner-only read;硬化转发;不存在/非本人 → 404)──",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/claim-tasks/mine": {
-      "get": {
-        "summary": "我相关的任务（必须在 /:id 之前注册，否则被 /:id 截获）",
+      },
+      "put": {
+        "summary": "── upload / replace QR(Passkey + owner;immutable content-addressed store)──",
         "tags": [],
         "security": [
           {
@@ -3004,9 +3874,9 @@
         ]
       }
     },
-    "/api/claim-url": {
+    "/api/direct-receive/bond-deposit": {
       "post": {
-        "summary": "POST /api/claim-url",
+        "summary": "POST /api/direct-receive/bond-deposit",
         "tags": [],
         "security": [
           {
@@ -3015,16 +3885,9 @@
         ]
       }
     },
-    "/api/claims/public": {
-      "get": {
-        "summary": "公开 #claims 广场（无 auth — 透明性是验证声明信任的前提）",
-        "tags": [],
-        "security": []
-      }
-    },
-    "/api/contribution-facts/me": {
-      "get": {
-        "summary": "── READ-ONLY: the caller's OWN attributable contribution facts (GitHub + admin coordination) ──",
+    "/api/direct-receive/bond-deposit/:id/cancel": {
+      "post": {
+        "summary": "POST /api/direct-receive/bond-deposit/:id/cancel",
         "tags": [],
         "security": [
           {
@@ -3033,9 +3896,9 @@
         ]
       }
     },
-    "/api/contribution-identity/github/claim-challenge": {
+    "/api/direct-receive/bond-refund-request": {
       "post": {
-        "summary": "── 1) issue a publication challenge ─────────────────────────────────────────────────────────",
+        "summary": "── B2:退出退还 —— 申请(§5 blockers fail-closed)→ 冷静期 → admin 执行;申请期间直付资格暂停,可撤销 ──",
         "tags": [],
         "security": [
           {
@@ -3044,9 +3907,9 @@
         ]
       }
     },
-    "/api/contribution-identity/github/claim-complete": {
+    "/api/direct-receive/bond-refund-request/cancel": {
       "post": {
-        "summary": "── 2) complete the claim (human gate → re-fetch gist proof → atomic consume+bind) ────────────",
+        "summary": "POST /api/direct-receive/bond-refund-request/cancel",
         "tags": [],
         "security": [
           {
@@ -3055,9 +3918,9 @@
         ]
       }
     },
-    "/api/contribution-identity/github/claimable": {
+    "/api/direct-receive/bond-status": {
       "get": {
-        "summary": "carries the uncommitted-value boundary, and errors never leak SQL/stack.",
+        "summary": "GET /api/direct-receive/bond-status",
         "tags": [],
         "security": [
           {
@@ -3066,20 +3929,18 @@
         ]
       }
     },
-    "/api/contribution-identity/github/me": {
+    "/api/direct-receive/deferral": {
       "get": {
-        "summary": "metering/display surface can never read as a payout promise — facts + attribution only.",
+        "summary": "GET /api/direct-receive/deferral — 卖家本人缓交状态:最新一条申请(脱敏:不含 admin 身份)+ 是否当前生效(active)。",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/contribution-score/evidence/me": {
-      "get": {
-        "summary": "always the session user. Output is component evidence wrapped in the uncommitted-value boundary.",
+      },
+      "post": {
+        "summary": "POST /api/direct-receive/deferral — 卖家申请缓交。helper 强制:单一活跃、periodDays 正整数、id 唯一。",
         "tags": [],
         "security": [
           {
@@ -3088,9 +3949,9 @@
         ]
       }
     },
-    "/api/conversations": {
-      "get": {
-        "summary": "我的会话列表",
+    "/api/direct-receive/fee-prepay-request": {
+      "post": {
+        "summary": "── 提交预充值申请(不 Passkey;凭据必填)──",
         "tags": [],
         "security": [
           {
@@ -3099,9 +3960,9 @@
         ]
       }
     },
-    "/api/conversations/:id": {
-      "get": {
-        "summary": "会话详情 + 消息分页",
+    "/api/direct-receive/fee-prepay-request/:id/cancel": {
+      "post": {
+        "summary": "── 卖家撤销自己的 pending 申请 ──",
         "tags": [],
         "security": [
           {
@@ -3110,9 +3971,9 @@
         ]
       }
     },
-    "/api/conversations/:id/archive": {
-      "post": {
-        "summary": "归档（仅自己侧）",
+    "/api/direct-receive/fee-prepay-requests": {
+      "get": {
+        "summary": "── 卖家看自己的申请(全状态)──",
         "tags": [],
         "security": [
           {
@@ -3121,9 +3982,9 @@
         ]
       }
     },
-    "/api/conversations/:id/block": {
-      "post": {
-        "summary": "拉黑（双向屏蔽）",
+    "/api/direct-receive/my-fee-account": {
+      "get": {
+        "summary": "仅本人(requireSeller),买家拿不到;只读、不碰任何资金动作。供 seller fee center 展示。",
         "tags": [],
         "security": [
           {
@@ -3132,31 +3993,27 @@
         ]
       }
     },
-    "/api/conversations/:id/messages": {
-      "post": {
-        "summary": "发消息",
+    "/api/direct-receive/payment-instruction": {
+      "delete": {
+        "summary": "DELETE — 停用卖家当前 active 收款说明(软停用,留历史为 inactive)。停用后 create route fail-closed。",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/conversations/:id/read": {
-      "post": {
-        "summary": "标记已读",
+      },
+      "get": {
+        "summary": "GET — 卖家本人当前 active 收款说明;无则 instruction:null(200,显式空状态,便于 UI 渲染“尚未设置”)。",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/conversations/:id/report": {
-      "post": {
-        "summary": "举报（人工审核）",
+      },
+      "put": {
+        "summary": "PUT — 设置/替换卖家当前 active 收款说明。instruction 必填、trim、长度上限;label 可选、trim、长度上限。",
         "tags": [],
         "security": [
           {
@@ -3165,9 +4022,9 @@
         ]
       }
     },
-    "/api/conversations/start": {
-      "post": {
-        "summary": "开会话（idempotent — 已存在则返回 id）",
+    "/api/direct-receive/platform-receive-accounts": {
+      "get": {
+        "summary": "── 卖家看平台收款方式(active;含 instruction + qr_data_uri —— 平台公开收款明细,据此付款)──",
         "tags": [],
         "security": [
           {
@@ -3176,20 +4033,18 @@
         ]
       }
     },
-    "/api/coupons": {
+    "/api/direct-receive/product-verification": {
       "post": {
-        "summary": "POST /api/coupons",
+        "summary": "POST /api/direct-receive/product-verification — 卖家为某产品申领验证码(单一活跃 per product)。",
         "tags": [],
         "security": [
           {
             "bearerAuth": []
           }
         ]
-      }
-    },
-    "/api/coupons/:id": {
-      "patch": {
-        "summary": "PATCH /api/coupons/:id",
+      },
+      "put": {
+        "summary": "PUT /api/direct-receive/product-verification — 卖家为某产品提交外部商品链接(链接仅存储,WebAZ 不抓取)。",
         "tags": [],
         "security": [
           {
@@ -3198,9 +4053,9 @@
         ]
       }
     },
-    "/api/coupons/available": {
+    "/api/direct-receive/product-verifications": {
       "get": {
-        "summary": "buyer 视角：全平台 + 已购卖家店铺/单品券 + 历史",
+        "summary": "GET /api/direct-receive/product-verifications — 卖家本人所有产品的认证状态(逐产品)。",
         "tags": [],
         "security": [
           {
@@ -3209,9 +4064,9 @@
         ]
       }
     },
-    "/api/coupons/mine": {
+    "/api/direct-receive/readiness": {
       "get": {
-        "summary": "GET /api/coupons/mine",
+        "summary": "绝不下发 raw blocker / KYB·制裁·AML 分项(见 sellerDirectPayReadinessView)。只读 self(auth 用户自身 id)。",
         "tags": [],
         "security": [
           {
@@ -3220,9 +4075,9 @@
         ]
       }
     },
-    "/api/coupons/preview": {
+    "/api/direct-receive/selectable-accounts": {
       "get": {
-        "summary": "GET /api/coupons/preview",
+        "summary": "⚠️ 只下发元数据 method/currency/label —— instruction 原文与 QR 受披露门保护,D1/D2 ack 后才随订单快照给买家。",
         "tags": [],
         "security": [
           {
@@ -3231,9 +4086,27 @@
         ]
       }
     },
-    "/api/creator/stats": {
+    "/api/direct-receive/store-verification": {
       "get": {
-        "summary": "里程碑 L3：创作者贡献仪表盘",
+        "summary": "GET /api/direct-receive/store-verification — 卖家本人店铺认证状态(脱敏 DTO,含豁免位)。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "POST /api/direct-receive/store-verification — 卖家申领店铺验证码(单一活跃 per seller)。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      },
+      "put": {
+        "summary": "PUT /api/direct-receive/store-verification — 卖家提交店铺外链(仅存储,不抓取)。",
         "tags": [],
         "security": [
           {
@@ -3604,7 +4477,7 @@
     },
     "/api/external-anchors/:id/distribute-rewards": {
       "post": {
-        "summary": "手动 distribute（admin/arbitrator 补救：anchor 已 community 但 fee_paid_out=0）",
+        "summary": "白名单(isEligibleArbitrator),不认 legacy user.role(否则已 suspend/revoke 但 role 未同步的账号仍可触发放款)。",
         "tags": [],
         "security": [
           {
@@ -3815,6 +4688,13 @@
         ]
       }
     },
+    "/api/fx/rates": {
+      "get": {
+        "summary": "GET /api/fx/rates",
+        "tags": [],
+        "security": []
+      }
+    },
     "/api/governance/onboarding-stats": {
       "get": {
         "summary": "无 auth — agent / 用户 / 第三方都可读;不暴露 PII",
@@ -4271,6 +5151,13 @@
         ]
       }
     },
+    "/api/manifests/:hash/thumb": {
+      "get": {
+        "summary": "Only the low-res thumbnail is exposed (never full-res / metadata / other columns).",
+        "tags": [],
+        "security": []
+      }
+    },
     "/api/manifests/by-anchor/:anchor": {
       "get": {
         "summary": "GET /api/manifests/by-anchor/:anchor",
@@ -4810,9 +5697,87 @@
         ]
       }
     },
+    "/api/orders/:id/cancel-refund": {
+      "get": {
+        "summary": "GET /api/orders/:id/cancel-refund",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/cancel-refund/confirm": {
+      "post": {
+        "summary": "POST /api/orders/:id/cancel-refund/confirm",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/cancel-refund/decline": {
+      "post": {
+        "summary": "POST /api/orders/:id/cancel-refund/decline",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/cancel-refund/mark-refunded": {
+      "post": {
+        "summary": "POST /api/orders/:id/cancel-refund/mark-refunded",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/cancel-refund/request": {
+      "post": {
+        "summary": "POST /api/orders/:id/cancel-refund/request",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/cancel-refund/withdraw": {
+      "post": {
+        "summary": "POST /api/orders/:id/cancel-refund/withdraw",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/orders/:id/chain": {
       "get": {
-        "summary": "订单签名链 — 当事人 + arbitrator + admin 可查",
+        "summary": "订单签名链 — 当事人 + 白名单仲裁员(涉争议订单) + admin 可查",
         "tags": [
           "order"
         ],
@@ -4862,6 +5827,19 @@
         ]
       }
     },
+    "/api/orders/:id/direct-pay-qr": {
+      "get": {
+        "summary": "取【当时那一版】图字节。未 ack / 非买家 / 无 QR / 非 direct_p2p → 统一 404(不枚举,不泄露)。图字节不入 order JSON。",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/orders/:id/force-timeout-check": {
       "post": {
         "summary": "手动触发超时判责（当事人）",
@@ -4875,6 +5853,136 @@
         ]
       }
     },
+    "/api/orders/:id/mutual-cancel": {
+      "get": {
+        "summary": "GET /api/orders/:id/mutual-cancel",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/mutual-cancel/accept": {
+      "post": {
+        "summary": "POST /api/orders/:id/mutual-cancel/accept",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/mutual-cancel/decline": {
+      "post": {
+        "summary": "POST /api/orders/:id/mutual-cancel/decline",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/mutual-cancel/propose": {
+      "post": {
+        "summary": "POST /api/orders/:id/mutual-cancel/propose",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/mutual-cancel/withdraw": {
+      "post": {
+        "summary": "POST /api/orders/:id/mutual-cancel/withdraw",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/pending-accept/accept": {
+      "post": {
+        "summary": "卖家确认接单 → 开付款窗口(deadline 此刻起表;收款信息此刻起买家可见 —— orders-read 状态门放行)",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/pending-accept/cancel": {
+      "post": {
+        "summary": "买家撤单(接单前反悔)→ 无责取消 + 回补库存",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/pending-accept/confirm-quote": {
+      "post": {
+        "summary": "CAS:仅 pending_accept 且已报价;总额变更与状态转移同一 db.transaction(要么全生效要么全回滚)。",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/pending-accept/decline": {
+      "post": {
+        "summary": "卖家谢绝(无法发货/物流不可达等;理由可选,买家可见)→ 无责取消 + 回补库存",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/orders/:id/pending-accept/quote": {
+      "post": {
+        "summary": "可重复报价(买家确认前修正);每次报价重置响应窗(param direct_pay.quote_confirm_hours,默认 48h)。",
+        "tags": [
+          "order"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/orders/:order_id/buyer-rating": {
       "get": {
         "summary": "查 seller → buyer 评价（双盲遮蔽：buyer 看不到，除非自己也评过 OR 窗口到期）",
@@ -5364,6 +6472,17 @@
         "security": []
       }
     },
+    "/api/products/:id/external-links": {
+      "get": {
+        "summary": "array the seller workbench consumes; that stays untouched). Only public-safe columns are returned.",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/products/:id/get-or-create-share": {
       "post": {
         "summary": "获取或创建商品 shareable（被 sharePromoLink 用，走 /s/<id> 短链）",
@@ -5420,6 +6539,13 @@
         "security": []
       }
     },
+    "/api/products/:id/shipping-options": {
+      "get": {
+        "summary": "公开读:买家下单前查配送范围。生效 = 单品覆盖 ?? 店铺默认;template=null → 不按地区计费(下单不要求选地区)。",
+        "tags": [],
+        "security": []
+      }
+    },
     "/api/products/:id/status": {
       "patch": {
         "summary": "状态切换（active / warehouse / deleted）",
@@ -6105,6 +7231,17 @@
         ]
       }
     },
+    "/api/return-requests/:id/confirm-refund": {
+      "post": {
+        "summary": "POST /api/return-requests/:id/confirm-refund",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/return-requests/:id/decide": {
       "post": {
         "summary": "POST /api/return-requests/:id/decide",
@@ -6127,6 +7264,17 @@
         ]
       }
     },
+    "/api/return-requests/:id/mark-refunded": {
+      "post": {
+        "summary": "POST /api/return-requests/:id/mark-refunded",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/return-requests/:id/messages": {
       "post": {
         "summary": "POST /api/return-requests/:id/messages",
@@ -6361,6 +7509,17 @@
         ]
       }
     },
+    "/api/seller/accept-mode": {
+      "post": {
+        "summary": "POST /api/seller/accept-mode",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/seller/apply-quota-increase": {
       "post": {
         "summary": "POST /api/seller/apply-quota-increase",
@@ -6394,6 +7553,28 @@
         ]
       }
     },
+    "/api/seller/shipping-settings": {
+      "get": {
+        "summary": "卖家读自己的店铺级设置(设置 UI 回显):接单模式 + 运费模板 + 询价开关。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/api/seller/shipping-template": {
+      "post": {
+        "summary": "POST /api/seller/shipping-template",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/seller/withdraw-quota-application": {
       "post": {
         "summary": "POST /api/seller/withdraw-quota-application",
@@ -6423,6 +7604,17 @@
         ]
       }
     },
+    "/api/sellers/me/direct-pay-report": {
+      "get": {
+        "summary": "from/to 均可选(闭区间,按日期比较 substr(created_at,1,10));返回汇总 + 按月 + 逐单(含平台费明细)。",
+        "tags": [],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/api/sellers/me/flash-sales": {
       "get": {
         "summary": "seller 自己的 flash sales（全部状态）",