@itpay/cli 2.0.13 → 2.0.15

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,23 +33,39 @@
   ],
   "agent_rules": [
     "Install with npm install -g @itpay/cli.",
+    "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL https://dev.itpay.ai; no other Backend is allowed.",
     "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.",
-    "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
     "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, while Device registrations and quota lineage remain separate for app.itpay.ai and dev.itpay.ai.",
+    "Within each official 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 any Backend except the default https://app.itpay.ai or the exact test override https://dev.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"
+      "one official Backend: production https://app.itpay.ai by default, or explicit test https://dev.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 the selected official 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"
     },
     {
@@ -52,6 +57,7 @@
     "Treat result as current facts, instruction as how to use those facts, next as the preferred executable action, and recovery as exceptional paths.",
     "Run one state-changing command at a time. Treat next.command as the preferred continuation: execute it unchanged after filling required user data only when the current result has not already satisfied the user's goal.",
     "Keep the same explicit Agent Type through next and recovery commands; same-type windows reuse one Backend Agent Instance.",
+    "When testing dev, execute every returned command unchanged so its ITPAY_BACKEND_URL=https://dev.itpay.ai prefix is preserved.",
     "Use --target only for a Host presentation destination. Put capability business values in --input key=value exactly as required by the schema.",
     "Start a separate Service Execution for each independent service intent; quota remains shared according to Backend identity policy.",
     "Ask the user for required email or contact values and explain their purpose; never invent them.",
@@ -65,13 +71,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；省略时使用当前官方 Backend 对应本地状态中最后保存的 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` 是重新登记入口。
+命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://dev.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
 
 缺少确认参数返回 `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": "查看官方 Backend 和首次使用说明"
     }
   ]
 }

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`；仅测试时可通过 `ITPAY_BACKEND_URL=https://dev.itpay.ai` 选择官方开发环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
-**上游：** CLI 安装和 Backend URL 配置。
-**下游：** 完整 `itpay-buyer` Skill，随后选择 Agent Type 或读取 Catalog。
+**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
+**下游：** 完整 `itpay` Skill，随后选择 Agent Type 或进入当前已支持的 Buyer Catalog。
 
 ## 语法与参数
 
@@ -22,16 +24,43 @@ itpay readyz [--json]
 ```json
 {
   "status": "ready",
-  "result": { "backend": "available" },
-  "instruction": "ItPay 可用；先完整读取内置 Buyer Skill，再开始服务流程。",
-  "next": { "command": "itpay skill show itpay-buyer --json", "reason": "加载完整操作与安全规则" },
+  "result": { "backend": "available", "backend_url": "https://app.itpay.ai", "environment": "production" },
+  "instruction": "ItPay 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
+  "next": { "command": "itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
+  "recovery": []
+}
+```
+
+开发环境返回同一 envelope，但明确标记环境并在每个后续命令中保留 dev Backend：
+
+```json
+{
+  "status": "ready",
+  "result": { "backend": "available", "backend_url": "https://dev.itpay.ai", "environment": "development" },
+  "instruction": "ItPay dev 可用；后续必须执行返回的完整命令，并继续使用同一个 dev Backend。先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。",
+  "next": { "command": "ITPAY_BACKEND_URL=https://dev.itpay.ai itpay skill show itpay --json", "reason": "加载完整操作与安全规则" },
   "recovery": []
 }
 ```
 
 ## 异常处理
 
-连接失败时返回 `backend_unavailable`，要求核对 `ITPAY_BACKEND_URL` 后重试同一命令，不得继续下单。
+连接失败时返回 `backend_unavailable`，要求等待当前官方 Backend 恢复后重试同一完整命令，不得在失败时切换环境或继续下单。
+
+非官方 URL 返回 `backend_override_forbidden`，且不提供自动 recovery：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "backend_override_forbidden",
+    "message": "ITPAY_BACKEND_URL only supports https://app.itpay.ai or https://dev.itpay.ai"
+  },
+  "instruction": "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。",
+  "next": null,
+  "recovery": []
+}
+```
 
 CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的恢复动作：
 
@@ -40,17 +69,17 @@ CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不
   "status": "error",
   "error": {
     "code": "backend_contract_incompatible",
-    "message": "CLI 2.0.13 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.14, maximum major 2)"
+    "message": "CLI 2.0.15 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.16, maximum major 2)"
   },
   "result": {
-    "current_cli_version": "2.0.13",
-    "required_cli_version": "2.0.14"
+    "current_cli_version": "2.0.15",
+    "required_cli_version": "2.0.16"
   },
   "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.14",
+      "command": "npm install -g @itpay/cli@2.0.16",
       "reason": "安装 Backend 指定的兼容 CLI 版本"
     }
   ]

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.
+
 ## 范围与意义
 
 列出指定订单的退款记录，按最新到最旧排序。