@itpay/cli 2.0.13 → 2.0.14

package/README.md

@@ -1,17 +1,21 @@
 # ItPay CLI
 
-The official V3 CLI for Agent-driven ItPay service discovery, checkout, delivery, order recovery, and refunds.
+The official V3 CLI and the single ItPay entry point for Agent-driven commerce.
+
+## One Entry Point, Two Actions
+
+`itpay` is the only 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, while Seller workflows will use the same entry point and are not implemented yet. Do not create separate Buyer or Seller product entry points.
 
 ```bash
 npm install -g @itpay/cli
 itpay readyz --json
-itpay skill show itpay-buyer --json
+itpay skill show itpay --json
 itpay install --json
 itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional environment override.
+The production Backend is permanently pinned to `https://app.itpay.ai`. Runtime environment variables cannot redirect the CLI to another Backend.
 
 ## Output Contract
 
@@ -42,11 +46,11 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 
 `--agent-type` identifies the stable runtime and registered Agent instance. Every returned ItPay command preserves it. Different windows or chats of the same type reuse one Agent Instance; they are not separate identities. `--host` only selects the human presentation surface, and `--target` only routes output to a Host destination. Use `itpay install <agent_type> --json` for the exact responsibility.
 
-The local installation keeps one Ed25519 private key. Each normalized Backend API base URL (`dev`, `test`, `app`, or local) has an independent server device registration, quota lineage, Agent instances, and sessions. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
+The local installation keeps one Ed25519 private key and one production Device registration for `https://app.itpay.ai`, with one Agent Instance per Agent Type. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
 
 ## Command Families
 
-- `readyz`, `catalog list`: compatibility and discovery.
+- `readyz`: fixed production Backend liveness; `catalog list`: compatibility-gated discovery.
 - `services start/invoke/action/checkout/next`: generic Service Execution flow.
 - `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
 - `checkout`: authoritative payment and fulfillment recovery.
@@ -71,11 +75,10 @@ itpay --agent-type <agent_type> services checkout <service_execution_id> --resum
 itpay checkout --id <checkout_id> --token <display_token> --json
 ```
 
-The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
+The local `~/.itpay-v3` directory stores one owner-only signing key, the `https://app.itpay.ai` Device registration and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
 
 ## Environment
 
-- `ITPAY_BACKEND_URL`: deliberate API override.
 - `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
 - `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
 - `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
@@ -91,10 +94,14 @@ Provider credentials, Buyer identity, payment provider choice, amount, refund po
 ```bash
 npm run lint
 npm test
+npm run test:coverage
 npm run test:package
 npm run pack:dry-run
 ```
 
+`npm install` configures the repository's pre-commit hook. Every commit must pass
+`npm run lint` and `npm test`; do not bypass the hook for pull-request changes.
+
 Source boundaries:
 
 - `src/main.ts`: parser and error-envelope wiring.

package/dist/src/commands/docs.js

@@ -92,6 +92,7 @@ function findDocsDir() {
 function parseDoc(raw, file) {
     const value = JSON.parse(raw);
     if (typeof value.schema_version !== "string" ||
+        typeof value.product_scope !== "string" ||
         typeof value.topic !== "string" ||
         typeof value.title !== "string" ||
         typeof value.purpose !== "string") {

package/dist/src/commands/guidance.js

@@ -257,8 +257,8 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "read_agent_session_rules",
-                label: "Read identity and session recovery rules",
-                command: "itpay skill show itpay-buyer --json",
+                label: "Read ItPay identity and session recovery rules",
+                command: "itpay skill show itpay --json",
                 reason: "The CLI already attempted one automatic session renewal; do not rotate identity or loop retries.",
             },
         ];
@@ -304,14 +304,9 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "retry_after_backend_recovers",
-                label: "Retry after the ItPay backend is reachable",
+                label: "Retry after app.itpay.ai is reachable",
                 command: "itpay readyz",
             },
-            {
-                id: "check_backend_url",
-                label: "Check the configured backend URL",
-                command: "echo $ITPAY_BACKEND_URL",
-            },
         ];
     }
     return [];

package/dist/src/commands/install.js

@@ -48,9 +48,9 @@ export function runInstall(target, options = {}) {
         instruction: INSTRUCTIONS[normalized],
         next: {
             command: `itpay --agent-type ${normalized} readyz --json`,
-            reason: "验证 CLI 与默认 ItPay API 的兼容性",
+            reason: "验证固定生产 ItPay API 的可用性",
         },
-        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看环境覆盖和首次使用说明" }],
+        recovery: [{ command: "itpay docs show install-and-setup", reason: "查看固定生产后端和首次使用说明" }],
     }, options);
 }
 function isInstallAgentType(value) {

package/dist/src/commands/readyz.js

@@ -5,8 +5,8 @@ export async function runReadyz(backend, options = {}) {
     writeCommandEnvelope({
         status: response.status,
         result: { backend: "available", ...(options.agentType ? { agent_type: options.agentType } : {}) },
-        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: [],
     }, options);
 }

package/dist/src/commands/skill.js

@@ -4,24 +4,24 @@ import { fileURLToPath } from "node:url";
 import { declaredAgentType } from "../state/agent_type.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
 const commandDir = dirname(fileURLToPath(import.meta.url));
-const BUYER_SKILL = "itpay-buyer";
+const ITPAY_SKILL = "itpay";
 export function runSkillShow(name, options = {}) {
     const normalized = name.trim().toLowerCase();
-    if (normalized !== BUYER_SKILL) {
-        throw new CommandContractError("skill_not_found", `skill not found: ${name}`, `当前 CLI 只内置 ${BUYER_SKILL}；不要猜测 Skill 名称。`, [{ command: `itpay skill show ${BUYER_SKILL} --json`, reason: "读取完整 Buyer Skill" }]);
+    if (normalized !== ITPAY_SKILL) {
+        throw new CommandContractError("skill_not_found", `skill not found: ${name}`, `当前 CLI 只内置 ${ITPAY_SKILL}；不要猜测 Skill 名称。`, [{ command: `itpay skill show ${ITPAY_SKILL} --json`, reason: "读取完整 ItPay Skill" }]);
     }
     let content;
     try {
         content = readFileSync(findSkillPath(), "utf8");
     }
     catch {
-        throw new Error("packaged skill is unavailable: itpay-buyer");
+        throw new Error("packaged skill is unavailable: itpay");
     }
     validateSkill(content);
     const agentType = options.agentType ?? declaredAgentType();
     const envelope = {
         status: "shown",
-        result: { skill: BUYER_SKILL, content },
+        result: { skill: ITPAY_SKILL, content },
         instruction: agentType
             ? agentType === "workbuddy"
                 ? "完整读取并遵守 Skill；保持 workbuddy 和同一 Node/CLI launcher。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。"
@@ -40,16 +40,16 @@ export function runSkillShow(name, options = {}) {
 }
 function findSkillPath() {
     if (process.env.ITPAY_CLI_SKILLS_DIR) {
-        return resolve(process.env.ITPAY_CLI_SKILLS_DIR, BUYER_SKILL, "SKILL.md");
+        return resolve(process.env.ITPAY_CLI_SKILLS_DIR, ITPAY_SKILL, "SKILL.md");
     }
-    const packagePath = resolve(commandDir, "..", "..", "..", "skills", BUYER_SKILL, "SKILL.md");
+    const packagePath = resolve(commandDir, "..", "..", "..", "skills", ITPAY_SKILL, "SKILL.md");
     if (existsSync(packagePath))
         return packagePath;
-    return resolve(commandDir, "..", "..", "skills", BUYER_SKILL, "SKILL.md");
+    return resolve(commandDir, "..", "..", "skills", ITPAY_SKILL, "SKILL.md");
 }
 function validateSkill(content) {
     const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
-    if (!frontmatter || !/^name:\s*itpay-buyer\s*$/m.test(frontmatter) || !/^description:\s*(?:>|\S)/m.test(frontmatter)) {
-        throw new Error("invalid packaged skill: itpay-buyer");
+    if (!frontmatter || !/^name:\s*itpay\s*$/m.test(frontmatter) || !/^description:\s*(?:>|\S)/m.test(frontmatter)) {
+        throw new Error("invalid packaged skill: itpay");
     }
 }

package/dist/src/main.js

@@ -26,7 +26,7 @@ import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckou
 const program = new Command();
 program
     .name("itpay")
-    .description("V3 ItPay CLI — checkout, payment, order, and refund commands")
+    .description("V3 ItPay CLI — one entry point for buy workflows and future sell workflows")
     .option("--agent-type <type>", "agent runtime type used for device enrollment and client-specific guidance")
     .version(CLI_VERSION);
 function withHost(value) {
@@ -106,11 +106,11 @@ function reportCLIError(error, contract) {
     const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
     const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
     const deviceRecovery = deviceError ? [{
-            command: "itpay skill show itpay-buyer --json",
-            reason: "读取身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
+            command: "itpay skill show itpay --json",
+            reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
         }] : [];
     const stateRecovery = stateError ? [{
-            command: "itpay skill show itpay-buyer --json",
+            command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
         }] : [];
     const authorizationInstruction = stateError
@@ -209,17 +209,15 @@ program
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await requirePlatformCompatibility(backend);
         await runReadyz(backend, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
             code: "backend_unavailable",
-            instruction: "检查 ITPAY_BACKEND_URL 后重试；后端恢复前不要继续下单。",
+            instruction: "固定生产后端 https://app.itpay.ai 当前不可用；后端恢复前不要继续下单，也不要切换到其他地址。",
             recovery: [
-                { command: "echo $ITPAY_BACKEND_URL", reason: "确认当前 Backend URL" },
-                { command: "itpay readyz", reason: "重试可用性检查" },
+                { command: "itpay readyz", reason: "重试固定生产后端的可用性检查" },
             ],
         });
     }
@@ -228,14 +226,14 @@ program
 const deviceCmd = program.command("device").description("Recover local Device registration state after an operator-confirmed Backend reset");
 deviceCmd
     .command("recover")
-    .description("Forget only the selected Backend registration while preserving the local private key")
+    .description("Forget only the app.itpay.ai registration while preserving the local private key")
     .option("--confirm-backend-reset", "confirm that an operator reset the selected Backend registration database")
     .option("--json", "output JSON instead of terminal text")
     .action(async (options) => {
     const config = loadConfig();
     try {
         if (!config.agentType) {
-            throw new CommandContractError("agent_type_required", "agent type is required for Backend-scoped Device recovery", "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
+            throw new CommandContractError("agent_type_required", "agent type is required for app.itpay.ai Device recovery", "如实声明当前 Agent Type；恢复后必须用同一类型重新登记。", [{ command: "itpay install --json", reason: "选择当前真实 Agent Type" }]);
         }
         if (!options.confirmBackendReset) {
             throw new CommandContractError("backend_reset_confirmation_required", "--confirm-backend-reset is required", "仅在运营已确认当前 Backend 的 Device 登记数据库被重建或清空后执行；普通 session 失效或 revoked 不得使用。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);

package/dist/src/state/config.js

@@ -1,4 +1,5 @@
-// CLI configuration loader. Reads config from environment only. Checkout
+// CLI configuration loader. The production Backend is pinned to app.itpay.ai;
+// environment variables configure only non-Backend runtime details. Checkout
 // display-token persistence belongs to the cart session file, protected with
 // owner-only permissions. Provider secrets are explicitly out of scope here.
 import { homedir } from "node:os";
@@ -10,7 +11,7 @@ import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
-export const CLI_VERSION = "2.0.13";
+export const CLI_VERSION = "2.0.14";
 export const API_CONTRACT_REVISION = "sha256:7f4c40b082292bf823631bcd37d452f4a8537153e30636d5eb3a2b24a77ce602";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
@@ -24,7 +25,7 @@ export function cartSessionPath(env = process.env) {
     return resolve(dir, CART_SESSION_FILENAME);
 }
 export function loadConfig(env = process.env) {
-    const baseURL = env.ITPAY_BACKEND_URL || DEFAULT_BASE_URL;
+    const baseURL = DEFAULT_BASE_URL;
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
     const agentType = declaredAgentType(env);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";

package/docs/agent/buyer/cart-checkout.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": "cart-checkout",
   "title": "Canonical Cart And Checkout Routing",
   "purpose": "Use the canonical server Cart and route service-backed lines through Service Execution without hardcoded service logic.",
@@ -43,8 +44,20 @@
     "Do not treat QR display as payment verification."
   ],
   "next_docs": [
-    { "condition": "Checkout handoff is ready", "topic": "payment-flow" },
-    { "condition": "Host rendering needs clarification", "topic": "render-hosts" }
+    {
+      "condition": "Checkout handoff is ready",
+      "topic": "payment-flow"
+    },
+    {
+      "condition": "Host rendering needs clarification",
+      "topic": "render-hosts"
+    }
   ],
-  "search_terms": ["cart", "checkout", "service execution", "resume", "contact"]
+  "search_terms": [
+    "cart",
+    "checkout",
+    "service execution",
+    "resume",
+    "contact"
+  ]
 }

package/docs/agent/buyer/catalog-list.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": "catalog-list",
   "title": "Browse ItPay V3 Service Catalog",
   "purpose": "Teach the agent how to browse and display available catalog services to the buyer.",

package/docs/agent/buyer/identity-and-sessions.json

@@ -1,18 +1,19 @@
 {
   "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": "identity-and-sessions",
   "title": "Device Identity And Session Recovery",
-  "purpose": "Explain stable local identity, Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
+  "purpose": "Explain stable local identity, the fixed app.itpay.ai production registration, Agent Type instances, and bounded automatic session recovery.",
   "when_to_use": [
     "A different Agent window or runtime starts using an existing CLI installation.",
     "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, or agent_device_revoked.",
-    "The configured ITPAY_BACKEND_URL changes between dev, test, and app."
+    "An operator confirms that the app.itpay.ai Device registration database was reset."
   ],
   "identity_model": {
     "local_key": "One owner-only Ed25519 private key for the local installation.",
-    "backend_registration": "One independent server registration per normalized Backend API base URL.",
-    "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
+    "backend_registration": "One production Device registration for https://app.itpay.ai; runtime environment variables cannot redirect the CLI.",
+    "agent_instance": "One instance per agent_type under the production registration; same-type windows and chats reuse it.",
     "presentation": "Host and target route output only and never identify the Agent or provide business input."
   },
   "automatic_recovery": [
@@ -29,36 +30,56 @@
   "commands": [
     {
       "intent": "reload the complete rules",
-      "command": "itpay --agent-type <agent_type> skill show itpay-buyer --json",
+      "command": "itpay --agent-type <agent_type> skill show itpay --json",
       "success_signal": "the full Skill is returned and next keeps the same Agent Type"
     },
     {
-      "intent": "confirm the selected Backend is available",
+      "intent": "confirm app.itpay.ai is available",
       "command": "itpay --agent-type <agent_type> readyz --json",
       "success_signal": "Backend is available and onboarding returns to the Skill"
     },
     {
-      "intent": "recover after an operator-confirmed reset of the selected Backend registration database",
+      "intent": "recover after an operator-confirmed reset of the app.itpay.ai Device registration database",
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
-      "success_signal": "only the selected Backend registration is removed; the private key and other Backend registrations remain"
+      "success_signal": "only the app.itpay.ai registration is removed and the private key remains"
     }
   ],
   "agent_rules": [
     "Use the real runtime type and keep it stable across every command in the flow.",
     "Keep the same CLI/Node launcher and Host-approved permission context for the whole flow.",
     "Treat a new window, chat, task, or process of the same runtime as the same Agent Type, not a new identity.",
-    "Expect dev, test, and app to have separate device IDs, quota lineage, Agent instances, and sessions even on the same machine.",
-    "After automatic recovery fails, stop and report the exact code, Backend URL, Agent Type, and command family without exposing private keys or tokens."
+    "Expect all production CLI traffic to use https://app.itpay.ai; do not set or suggest a Backend URL override.",
+    "After automatic recovery fails, stop and report the exact code, app.itpay.ai, Agent Type, and command family without exposing private keys or tokens."
   ],
   "forbidden": [
     "Do not delete ~/.itpay-v3, rotate the key, switch Agent Type, or repeatedly retry to obtain fresh quota.",
     "Do not use device recover for session expiry, revocation, quota recovery, or an unconfirmed Backend failure.",
-    "Do not copy a server device ID from one Backend registration into another.",
+    "Do not redirect the CLI to dev, test, local, or any non-app.itpay.ai Backend.",
     "Do not use --target as identity or service input."
   ],
   "next_docs": [
-    { "condition": "Identity is healthy", "topic": "quickstart" },
-    { "condition": "Need setup details", "topic": "install-and-setup" }
+    {
+      "condition": "Identity is healthy",
+      "topic": "quickstart"
+    },
+    {
+      "condition": "Need setup details",
+      "topic": "install-and-setup"
+    }
   ],
-  "search_terms": ["identity", "device", "session", "login", "authentication", "agent type", "backend", "revoked", "recover", "unwritable", "lock", "window", "chat"]
+  "search_terms": [
+    "identity",
+    "device",
+    "session",
+    "login",
+    "authentication",
+    "agent type",
+    "backend",
+    "revoked",
+    "recover",
+    "unwritable",
+    "lock",
+    "window",
+    "chat"
+  ]
 }

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,40 @@
   ],
   "agent_rules": [
     "Install with npm install -g @itpay/cli.",
+    "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.",
-    "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.",
     "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"
+  ]
 }