@itpay/cli 2.0.12 → 2.0.14

package/docs/agent/buyer/install-and-setup.json

@@ -1,9 +1,10 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "install-and-setup",
   "title": "Install And Identify The ItPay Agent Runtime",
-  "purpose": "Install the CLI, load the complete Buyer Skill, and select one stable Agent Type without confusing identity, Backend, Host, target, or chat window.",
+  "purpose": "Install the CLI, load the complete ItPay Skill, and select one stable Agent Type without confusing identity, Backend, Host, target, or chat window.",
   "when_to_use": [
     "The CLI is being installed or upgraded.",
     "The agent needs to confirm its stable runtime identity and default output Host."
@@ -12,11 +13,11 @@
     {
       "intent": "verify the API and enter packaged onboarding",
       "command": "itpay readyz --json",
-      "success_signal": "status is ready and next points to skill show itpay-buyer"
+      "success_signal": "status is ready and next points to skill show itpay"
     },
     {
       "intent": "read the complete packaged operating contract",
-      "command": "itpay skill show itpay-buyer --json",
+      "command": "itpay skill show itpay --json",
       "success_signal": "status is shown, result.content contains the complete Skill, and next selects Agent Type or Catalog"
     },
     {
@@ -32,21 +33,40 @@
   ],
   "agent_rules": [
     "Install with npm install -g @itpay/cli.",
-    "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
+    "The production Backend is fixed to https://app.itpay.ai and cannot be redirected by runtime environment variables.",
+    "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and run only the exact npm install recovery returned by the CLI; never replace its version with latest.",
+    "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
+    "The production Backend is fixed to https://app.itpay.ai and cannot be redirected by runtime environment variables.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
-    "One local private key is reused, but each exact Backend API base URL has its own server registration and quota lineage.",
-    "Within one Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
+    "One local private key is reused with the https://app.itpay.ai production Device registration and quota lineage.",
+    "Within the production Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
     "Agent Type identifies the runtime. Host controls rendering and target only identifies a presentation destination.",
     "Keep the exact Agent Type in every next or recovery command; do not fall back to a type previously used by another runtime.",
     "Do not change Agent Type or rotate local identity to reset quota or recover a failed command."
   ],
   "forbidden": [
     "Do not use codex, terminal, claude-code, or plain-chat as Agent Types.",
+    "Do not set or suggest a Backend URL override; production CLI traffic always targets https://app.itpay.ai.",
     "Do not claim that install writes host configuration or registers a device; it only prints instructions.",
     "Do not create a new identity for a different window, task, chat, or process of the same Agent Type."
   ],
   "next_docs": [
-    { "condition": "Installation is verified", "topic": "quickstart" }
+    {
+      "condition": "Installation is verified",
+      "topic": "quickstart"
+    }
   ],
-  "search_terms": ["install", "agent type", "host", "target", "device", "session", "identity", "backend", "codex", "claude code", "workbuddy"]
+  "search_terms": [
+    "install",
+    "agent type",
+    "host",
+    "target",
+    "device",
+    "session",
+    "identity",
+    "backend",
+    "codex",
+    "claude code",
+    "workbuddy"
+  ]
 }

package/docs/agent/buyer/orders-refunds.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "orders-refunds",
   "title": "Order, Delivery And Refund Recovery",
   "purpose": "Read owned orders and manage refunds through signed Agent authority without guessing payment or refund state.",
@@ -48,7 +49,17 @@
     "Do not claim a refund succeeded before the Refund Owner says succeeded."
   ],
   "next_docs": [
-    { "condition": "Need the original purchase path", "topic": "quickstart" }
+    {
+      "condition": "Need the original purchase path",
+      "topic": "quickstart"
+    }
   ],
-  "search_terms": ["order", "refund", "cancel", "watch", "delivery lock", "grant"]
+  "search_terms": [
+    "order",
+    "refund",
+    "cancel",
+    "watch",
+    "delivery lock",
+    "grant"
+  ]
 }

package/docs/agent/buyer/payment-flow.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "payment-flow",
   "title": "Human Checkout Handoff And Payment Verification",
   "purpose": "Show the ItPay Checkout to the human and recover authoritative payment state without creating duplicate payment resources.",
@@ -42,8 +43,21 @@
     "Do not start another Service Execution to bypass quota, candidate, quote, checkout, or delivery state."
   ],
   "next_docs": [
-    { "condition": "Payment is verified", "topic": "orders-refunds" },
-    { "condition": "The current Host cannot display the handoff", "topic": "render-hosts" }
+    {
+      "condition": "Payment is verified",
+      "topic": "orders-refunds"
+    },
+    {
+      "condition": "The current Host cannot display the handoff",
+      "topic": "render-hosts"
+    }
   ],
-  "search_terms": ["payment", "checkout", "QR", "display token", "resume", "verified"]
+  "search_terms": [
+    "payment",
+    "checkout",
+    "QR",
+    "display token",
+    "resume",
+    "verified"
+  ]
 }

package/docs/agent/buyer/quickstart.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "quickstart",
   "title": "ItPay CLI Buyer Quickstart",
   "purpose": "Run the shortest safe discovery, Service Execution, Checkout, delivery, and refund flow using server-returned next commands.",
@@ -11,19 +12,23 @@
   "required_state": {
     "needs": [
       "the real supported Agent Type",
-      "the default API or an intentional ITPAY_BACKEND_URL override"
+      "the fixed production Backend https://app.itpay.ai"
     ],
-    "must_not_need": ["Admin access", "Provider secrets", "raw payload access"]
+    "must_not_need": [
+      "Admin access",
+      "Provider secrets",
+      "raw payload access"
+    ]
   },
   "commands": [
     {
-      "intent": "verify compatibility",
+      "intent": "verify fixed production Backend availability",
       "command": "itpay --agent-type <agent_type> readyz --json",
-      "success_signal": "status is ready and next points to the complete packaged Buyer Skill"
+      "success_signal": "status is ready and next points to the complete packaged ItPay Skill"
     },
     {
       "intent": "load the complete operating contract",
-      "command": "itpay --agent-type <agent_type> skill show itpay-buyer --json",
+      "command": "itpay --agent-type <agent_type> skill show itpay --json",
       "success_signal": "status is shown and next points to catalog list with the same Agent Type"
     },
     {
@@ -65,13 +70,43 @@
     "Do not bypass a grant, refund lock, ownership error or compatibility gate."
   ],
   "next_docs": [
-    { "condition": "Need service catalog language", "topic": "catalog-list" },
-    { "condition": "Need Cart and Checkout routing", "topic": "cart-checkout" },
-    { "condition": "Need payment recovery", "topic": "payment-flow" },
-    { "condition": "Need Host-specific presentation", "topic": "render-hosts" },
-    { "condition": "Need order or refund recovery", "topic": "orders-refunds" },
-    { "condition": "Need install or identity details", "topic": "install-and-setup" },
-    { "condition": "Need device session recovery rules", "topic": "identity-and-sessions" }
+    {
+      "condition": "Need service catalog language",
+      "topic": "catalog-list"
+    },
+    {
+      "condition": "Need Cart and Checkout routing",
+      "topic": "cart-checkout"
+    },
+    {
+      "condition": "Need payment recovery",
+      "topic": "payment-flow"
+    },
+    {
+      "condition": "Need Host-specific presentation",
+      "topic": "render-hosts"
+    },
+    {
+      "condition": "Need order or refund recovery",
+      "topic": "orders-refunds"
+    },
+    {
+      "condition": "Need install or identity details",
+      "topic": "install-and-setup"
+    },
+    {
+      "condition": "Need device session recovery rules",
+      "topic": "identity-and-sessions"
+    }
   ],
-  "search_terms": ["quickstart", "service", "next", "recovery", "delivery", "refund", "target", "input"]
+  "search_terms": [
+    "quickstart",
+    "service",
+    "next",
+    "recovery",
+    "delivery",
+    "refund",
+    "target",
+    "input"
+  ]
 }

package/docs/agent/buyer/render-hosts.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
+  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
   "topic": "render-hosts",
   "title": "Agent Type And Checkout Handoff Rendering",
   "purpose": "Use only the handoff fields returned for the current Agent Type and make the human Checkout visible on that surface.",
@@ -61,7 +62,18 @@
     "Do not inspect, download, or regenerate a local QR file for WorkBuddy."
   ],
   "next_docs": [
-    { "condition": "Need payment verification rules", "topic": "payment-flow" }
+    {
+      "condition": "Need payment verification rules",
+      "topic": "payment-flow"
+    }
   ],
-  "search_terms": ["host", "agent type", "QR", "markdown", "terminal", "desktop", "workbuddy"]
+  "search_terms": [
+    "host",
+    "agent type",
+    "QR",
+    "markdown",
+    "terminal",
+    "desktop",
+    "workbuddy"
+  ]
 }

package/docs/cli-reference/agent-types.md

@@ -1,5 +1,7 @@
 # Agent Type And Host Contract
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 `--agent-type` 表示哪类运行时在运行 CLI，用于 Agent 实例归属和定制 instruction。`--host` 表示输出展示在哪里；`--target` 只是在某些 Host 中指定 chat/channel/open ID。三者不可混用，窗口、任务和对话也不是身份。
 
 本地只保存一把 Ed25519 私钥。每个规范化 Backend API base URL 独立登记 Device，因此 dev/test/app 分别拥有自己的 device ID、quota lineage、Agent instances 和 sessions。同一 Backend 下每个 `agent_type` 只有一个 Agent Instance；同类型的不同窗口、任务或聊天复用它，不追踪窗口 ID。

package/docs/cli-reference/commands/buy.md

@@ -1,5 +1,7 @@
 # `itpay buy`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 为普通 Catalog 项目或已绑定 Service Quote 的 canonical Cart 创建一个 ItPay Checkout，并按当前 Agent Type 把付款入口交给用户。命令只创建或恢复 ItPay Checkout，不把“用户说已付款”当作付款成功。

package/docs/cli-reference/commands/cart/add.md

@@ -1,5 +1,7 @@
 # `itpay cart add`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 把一个已发布 Catalog offer 或一个已准备的 Service Quote 加入 canonical server Cart。Catalog 服务行先进入 `services next`；Quote 行已经锁定输入和价格，可以与其他独立 Execution 的 Quote 一起结算。

package/docs/cli-reference/commands/cart/clear.md

@@ -1,5 +1,7 @@
 # `itpay cart clear`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 放弃未锁定的 canonical cart。`--local` 只清理本地句柄和草稿，不声称服务端资源已取消。

package/docs/cli-reference/commands/cart/index.md

@@ -1,5 +1,7 @@
 # `itpay cart`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 命令范围
 
 管理 canonical server Cart。Catalog line 可以创建 Service Execution；已准备好的 Service Quote 则通过 `cart add --quote` 加入 Cart。Cart 聚合交易，但不合并 Execution、候选归属或交付。

package/docs/cli-reference/commands/cart/next.md

@@ -1,5 +1,7 @@
 # `itpay cart next`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取当前 canonical cart 对应的唯一首选动作。它不修改 cart。

package/docs/cli-reference/commands/cart/remove.md

@@ -1,5 +1,7 @@
 # `itpay cart remove`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 从未锁定的 canonical cart 删除一个 line。删除不会影响已创建的 Checkout 或订单；如果该 line 是某个未付款 Service Execution 在 Cart 中的最后一个引用，Backend 会在同一事务中取消该 execution。
@@ -16,7 +18,7 @@ itpay cart remove --local --variant <catalog_variant_id> --offer <offer_id> [--j
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `--line <cart_item_id>` | 否 | canonical Cart line；省略时使用当前 Backend URL 下最后保存的 line。 |
+| `--line <cart_item_id>` | 否 | canonical Cart line；省略时使用固定 `https://app.itpay.ai` 后端下最后保存的 line。 |
 | `--local` | 否 | 只修改显式本地草稿，不请求 Backend。 |
 | `--variant <catalog_variant_id>` | local 时是 | 与 `--offer` 一起标识本地草稿 line。 |
 | `--offer <offer_id>` | local 时是 | 与 `--variant` 一起标识本地草稿 line。 |

package/docs/cli-reference/commands/cart/show.md

@@ -1,5 +1,7 @@
 # `itpay cart show`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 显示 canonical server cart 的紧凑摘要和 line 句柄。默认不展开完整 Service Execution。

package/docs/cli-reference/commands/catalog/index.md

@@ -1,5 +1,7 @@
 # `itpay catalog`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 命令范围
 
 读取已发布的服务目录，帮助 Agent 发现可启动的通用服务。Catalog 只描述产品和入口，不执行服务、不创建购物车。

package/docs/cli-reference/commands/catalog/list.md

@@ -1,5 +1,7 @@
 # `itpay catalog list`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 列出当前 published Catalog。每个项目先说明用户真正购买的主服务，再说明免费或付费的辅助能力，避免把辅助消歧误称为最终服务。

package/docs/cli-reference/commands/checkout.md

@@ -1,5 +1,7 @@
 # `itpay checkout`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取并恢复一笔已存在 Checkout 的公开展示状态。它不创建新 Checkout，也不把“用户说已付款”当作付款成功。

package/docs/cli-reference/commands/device.md

@@ -1,5 +1,7 @@
 # `itpay device recover`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围
 
 仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
@@ -8,6 +10,6 @@
 itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
-命令使用 `ITPAY_BACKEND_URL` 选择唯一作用域，保留本地 Ed25519 私钥、其他 Backend registrations、Cart 和业务资源。它不访问 Backend，不自动创建新身份；返回的只读 `services list` 是重新登记入口。
+命令只作用于固定生产后端 `https://app.itpay.ai` 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。CLI 不接受 Backend URL 覆盖。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 是重新登记入口。
 
 缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。

package/docs/cli-reference/commands/docs/index.md

@@ -1,5 +1,7 @@
 # `itpay docs`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 命令范围
 
 浏览 npm 包内置的 Agent 操作文档。它是运行时自助说明，不读取服务端业务数据。

package/docs/cli-reference/commands/docs/list.md

@@ -1,5 +1,7 @@
 # `itpay docs list`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 按稳定 topic 名称列出 npm 包内置的 Agent 文档，只返回标题和一句用途，不加载完整内容，也不访问 Backend。

package/docs/cli-reference/commands/docs/search.md

@@ -1,5 +1,7 @@
 # `itpay docs search`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 在内置 topic 的名称、标题、用途和 `search_terms` 中进行不区分大小写的包含搜索。它不搜索完整正文或业务数据。

package/docs/cli-reference/commands/docs/show.md

@@ -1,5 +1,7 @@
 # `itpay docs show`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取一个指定 Agent 文档 topic。这是 docs 命令族中唯一返回完整文档内容的命令；不会级联读取其他 topic，也不访问 Backend。

package/docs/cli-reference/commands/install.md

@@ -1,5 +1,7 @@
 # `itpay install`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取当前 CLI 内置的 Agent Type 安装合同。它只说明 npm 安装、默认 API、默认 Host 和下一条验证命令；不修改宿主配置、不登记设备，也不调用 Backend。
@@ -35,12 +37,12 @@ itpay install [target] [--json]
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
   "next": {
     "command": "itpay --agent-type codex-desktop readyz --json",
-    "reason": "验证 CLI 与默认 ItPay API 的兼容性"
+    "reason": "验证固定生产 ItPay API 的可用性"
   },
   "recovery": [
     {
       "command": "itpay docs show install-and-setup",
-      "reason": "查看环境覆盖和首次使用说明"
+      "reason": "查看固定生产后端和首次使用说明"
     }
   ]
 }
@@ -83,7 +85,7 @@ itpay install [target] [--json]
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | Checkout 返回 `qr_image_url` 时，按当次 instruction 调用 `present_files` 在右侧打开二维码；不检查本地二维码文件。 |
+| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止，不切换 Node、不删除 identity、不处理 lock。Checkout 返回 `qr_image_url` 时按 instruction 调用 `present_files`。 |
 
 显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
 

package/docs/cli-reference/commands/next.md

@@ -1,5 +1,7 @@
 # `itpay next`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 从本机保存的 canonical Cart、Checkout 或 Service Execution 句柄恢复一个首选动作。它是中断后的总入口，不替代具体资源的 `next/get`，也不读取或复制 Backend DTO。

package/docs/cli-reference/commands/order.md

@@ -1,5 +1,7 @@
 # `itpay order`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取一笔当前 Buyer 或已绑定 Agent 可见的订单摘要、交付模式和退款访问锁。它不会返回受保护交付内容、Vault ID、内部 delivery artifact 或 Checkout token。

package/docs/cli-reference/commands/orders.md

@@ -1,5 +1,7 @@
 # `itpay orders`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 列出当前 account-scoped Buyer session 可见的订单摘要，用于恢复订单，不返回交付 payload。

package/docs/cli-reference/commands/pay.md

@@ -1,5 +1,7 @@
 # `itpay pay`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 为一个已存在的 Checkout 显式创建或刷新 Payment Intent。它只用于 Checkout 页面无法完成渠道动作时的受控集成恢复，不是普通 Buyer 流程。

package/docs/cli-reference/commands/readyz.md

@@ -1,11 +1,13 @@
 # `itpay readyz`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
-检查当前配置的 ItPay API 是否可用。它只做环境诊断，不登记设备、不创建业务资源。
+检查固定生产 Backend `https://app.itpay.ai` 是否可用。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
-**上游：** CLI 安装和 Backend URL 配置。
-**下游：** 完整 `itpay-buyer` Skill，随后选择 Agent Type 或读取 Catalog。
+**上游：** CLI 安装；Backend 固定为 `https://app.itpay.ai`，不可由运行时环境覆盖。
+**下游：** 完整 `itpay` Skill，随后选择 Agent Type 或进入当前已支持的 Buyer Catalog。
 
 ## 语法与参数
 
@@ -23,15 +25,41 @@ itpay readyz [--json]
 {
   "status": "ready",
   "result": { "backend": "available" },
-  "instruction": "ItPay 可用；先完整读取内置 Buyer Skill，再开始服务流程。",
-  "next": { "command": "itpay skill show itpay-buyer --json", "reason": "加载完整操作与安全规则" },
+  "instruction": "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
+  "next": { "command": "itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }
 ```
 
 ## 异常处理
 
-连接失败时返回 `backend_unavailable`，要求核对 `ITPAY_BACKEND_URL` 后重试同一命令，不得继续下单。
+连接失败时返回 `backend_unavailable`，要求等待 `https://app.itpay.ai` 恢复后重试同一命令，不得切换后端或继续下单。
+
+CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的恢复动作：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "backend_contract_incompatible",
+    "message": "CLI 2.0.14 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.15, maximum major 2)"
+  },
+  "result": {
+    "current_cli_version": "2.0.14",
+    "required_cli_version": "2.0.15"
+  },
+  "instruction": "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "npm install -g @itpay/cli@2.0.15",
+      "reason": "安装 Backend 指定的兼容 CLI 版本"
+    }
+  ]
+}
+```
+
+只允许使用 Backend 返回的 `minimum_cli_version` 生成精确 npm 版本。兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/refund/cancel.md

@@ -1,5 +1,7 @@
 # `itpay refund cancel`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 在 Refund Owner 允许时取消 active refund。取消成功后释放访问锁，但不复活旧 Agent grant。

package/docs/cli-reference/commands/refund/create.md

@@ -1,5 +1,7 @@
 # `itpay refund create`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 为一笔订单提交退款意图。Refund Owner 从订单推导 Buyer、支付、金额、币种、消费事实和审核策略；Agent 只提交订单和用户原因。

package/docs/cli-reference/commands/refund/get.md

@@ -1,5 +1,7 @@
 # `itpay refund get`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取一笔当前身份可见退款的权威快照、交付锁和可取消性。它只请求一次，不轮询、不改变退款状态。

package/docs/cli-reference/commands/refund/index.md

@@ -1,5 +1,7 @@
 # `itpay refund`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 命令范围
 
 创建、恢复、跟踪和取消退款申请。Refund Owner 决定政策和状态；CLI 只提交用户意图并展示服务端事实。

package/docs/cli-reference/commands/refund/list.md

@@ -1,5 +1,7 @@
 # `itpay refund list`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 列出指定订单的退款记录，按最新到最旧排序。

package/docs/cli-reference/commands/refund/watch.md

@@ -1,5 +1,7 @@
 # `itpay refund watch`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 轮询同一退款直到终态或 timeout。命令内部可以读取多次，但对外只输出一个最终信封，不把无变化轮询刷入 Agent 上下文。中断后可无副作用重跑。

package/docs/cli-reference/commands/services/action.md

@@ -1,5 +1,7 @@
 # `itpay services action`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 记录用户或 Agent 对 Service Execution 的结构化动作，例如选择候选、批准、拒绝或取消。它不直接调用付费 Provider。

package/docs/cli-reference/commands/services/checkout.md

@@ -1,5 +1,7 @@
 # `itpay services checkout`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。