@itpay/cli 2.0.13 → 2.0.15

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 CLI defaults to the production Backend `https://app.itpay.ai`. Explicit tests may set `ITPAY_BACKEND_URL=https://dev.itpay.ai`; every other Backend URL is rejected before network or local state access.
 
 ## 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 a separate registration for each official Backend, with one Agent Instance per Agent Type under each registration. 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`: selected official 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,12 +75,12 @@ 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, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Production uses `cart.json` / `operations.json`; dev uses `cart.dev.json` / `operations.dev.json`. 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_BACKEND_URL`: optional test override; only the exact official URL `https://dev.itpay.ai` is accepted. Unset it for production.
 - `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
 - `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
 - `ITPAY_CURRENCY`: ordinary Cart currency, default `CNY`.
@@ -91,10 +95,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

@@ -1,6 +1,7 @@
 import { HttpError } from "../client/http.js";
 import { resolveOutput } from "../render/sink.js";
 import { declaredAgentType, qualifyItPayCommand } from "../state/agent_type.js";
+import { qualifyBackendCommand } from "../state/config.js";
 export function isTerminalServiceExecutionStatus(status) {
     return status === "failed" || status === "refunded" || status === "cancelled";
 }
@@ -84,7 +85,7 @@ export function printAgentGuidance(guidance, output) {
         out("next actions:\n");
         for (const action of guidance.next_actions) {
             out(`  - ${action.label}\n`);
-            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
+            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
             if (action.requires_human)
                 out("    requires human confirmation\n");
             if (action.reason)
@@ -95,17 +96,17 @@ export function printAgentGuidance(guidance, output) {
         out("recovery:\n");
         for (const action of guidance.recovery) {
             out(`  - ${action.label}\n`);
-            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
+            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
         }
     }
 }
 function qualifyEnvelope(value, agentType) {
     return {
         ...value,
-        next: value.next ? { ...value.next, command: qualifyItPayCommand(value.next.command, agentType) } : null,
+        next: value.next ? { ...value.next, command: qualifyBackendCommand(qualifyItPayCommand(value.next.command, agentType)) } : null,
         recovery: value.recovery.map((action) => ({
             ...action,
-            command: qualifyItPayCommand(action.command, agentType),
+            command: qualifyBackendCommand(qualifyItPayCommand(action.command, agentType)),
         })),
     };
 }
@@ -257,8 +258,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 +305,9 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "retry_after_backend_recovers",
-                label: "Retry after the ItPay backend is reachable",
+                label: "Retry after the selected official Backend 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: "查看官方 Backend 和首次使用说明" }],
     }, options);
 }
 function isInstallAgentType(value) {

package/dist/src/commands/readyz.js

@@ -2,11 +2,15 @@
 import { writeCommandEnvelope } from "./guidance.js";
 export async function runReadyz(backend, options = {}) {
     const response = await backend.readyz();
+    const backendURL = options.backendURL ?? "https://app.itpay.ai";
+    const environment = options.environment ?? "production";
     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: "加载完整操作与安全规则" },
+        result: { backend: "available", backend_url: backendURL, environment, ...(options.agentType ? { agent_type: options.agentType } : {}) },
+        instruction: environment === "development"
+            ? "ItPay dev 可用；后续必须执行返回的完整命令，并继续使用同一个 dev Backend。先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。"
+            : "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

@@ -2,7 +2,7 @@
 // services/backend/internal/httpapi/handlers/*.go. Commands only
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
-import { CLI_VERSION, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
+import { BackendOverrideError, CLI_VERSION, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
 import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.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) {
@@ -83,6 +83,7 @@ function resolveCheckoutPresentationArgs(input) {
 }
 function reportCLIError(error, contract) {
     const commandError = error instanceof CommandContractError ? error : undefined;
+    const backendOverrideError = error instanceof BackendOverrideError ? error : undefined;
     const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
     const stateError = error instanceof DeviceStateError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
@@ -106,11 +107,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
@@ -122,11 +123,11 @@ function reportCLIError(error, contract) {
                 : deviceError
                     ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
                     : undefined;
-    if (contract || commandError) {
+    if (contract || commandError || backendOverrideError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
             ...(requiredCLIVersion ? {
@@ -164,7 +165,9 @@ function reportCLIError(error, contract) {
                                         ? "Provider 拒绝了本次请求，但未声明这是输入错误；向用户逐字报告 error.message 和 result.quota 并停止。不要修改输入、不要重试、不要创建新 Execution。"
                                         : capabilityInputInvalid
                                             ? "输入未通过本地校验，上游尚未被调用且用户额度未变化。向用户逐字报告 error.message 并停止，不要原样重试或运行其他恢复命令。用户提供修正后的输入后，继续使用当前未结束的 Execution。"
-                                            : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
+                                            : backendOverrideError
+                                                ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。"
+                                                : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
             recovery: incompatible
                 ? requiredCLIVersion
@@ -172,9 +175,9 @@ function reportCLIError(error, contract) {
                     : []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
-                    : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
-            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : {}),
+            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError ? { jsonOutput: process.argv.includes("--json") } : {}),
             output: (text) => { process.stderr.write(text); },
         });
         process.exitCode = 1;
@@ -209,33 +212,34 @@ program
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await requirePlatformCompatibility(backend);
-        await runReadyz(backend, { jsonOutput: Boolean(options.json), ...(config.agentType ? { agentType: config.agentType } : {}) });
+        await runReadyz(backend, {
+            jsonOutput: Boolean(options.json), backendURL: config.baseURL, environment: config.environment,
+            ...(config.agentType ? { agentType: config.agentType } : {}),
+        });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
             code: "backend_unavailable",
-            instruction: "检查 ITPAY_BACKEND_URL 后重试；后端恢复前不要继续下单。",
+            instruction: `当前官方 Backend ${config.baseURL} 不可用；恢复前不要继续下单，也不要切换环境。`,
             recovery: [
-                { command: "echo $ITPAY_BACKEND_URL", reason: "确认当前 Backend URL" },
-                { command: "itpay readyz", reason: "重试可用性检查" },
+                { command: "itpay readyz", reason: "重试当前官方 Backend 的可用性检查" },
             ],
         });
     }
 });
 // --- device ---------------------------------------------------------------
-const deviceCmd = program.command("device").description("Recover local Device registration state after an operator-confirmed Backend reset");
+const deviceCmd = program.command("device").description("Recover the current official Backend registration after an operator-confirmed reset");
 deviceCmd
     .command("recover")
-    .description("Forget only the selected Backend registration while preserving the local private key")
+    .description("Forget only the current official Backend 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 ${config.baseURL} 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. Production defaults to app.itpay.ai; the only
+// allowed override is the official dev Backend. 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,21 +11,54 @@ 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 DEV_BASE_URL = "https://dev.itpay.ai";
+export const CLI_VERSION = "2.0.15";
 export const API_CONTRACT_REVISION = "sha256:7f4c40b082292bf823631bcd37d452f4a8537153e30636d5eb3a2b24a77ce602";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
+export class BackendOverrideError extends Error {
+    code = "backend_override_forbidden";
+    constructor() {
+        super(`ITPAY_BACKEND_URL only supports ${DEFAULT_BASE_URL} or ${DEV_BASE_URL}`);
+        this.name = "BackendOverrideError";
+    }
+}
+export function resolveBackendURL(env = process.env) {
+    const requested = env.ITPAY_BACKEND_URL?.trim();
+    if (!requested || requested === DEFAULT_BASE_URL || requested === `${DEFAULT_BASE_URL}/`)
+        return DEFAULT_BASE_URL;
+    if (requested === DEV_BASE_URL || requested === `${DEV_BASE_URL}/`)
+        return DEV_BASE_URL;
+    throw new BackendOverrideError();
+}
+export function qualifyBackendCommand(command, env = process.env) {
+    const requested = env.ITPAY_BACKEND_URL?.trim();
+    if (requested !== DEV_BASE_URL && requested !== `${DEV_BASE_URL}/`)
+        return command;
+    if (!command.startsWith("itpay ") || command.startsWith(`ITPAY_BACKEND_URL=${DEV_BASE_URL} `))
+        return command;
+    return `ITPAY_BACKEND_URL=${DEV_BASE_URL} ${command}`;
+}
+function stateFilename(filename, baseURL) {
+    if (baseURL !== DEV_BASE_URL)
+        return filename;
+    const dot = filename.lastIndexOf(".");
+    return dot < 0 ? `${filename}.dev` : `${filename.slice(0, dot)}.dev${filename.slice(dot)}`;
+}
+function stateDir(env) {
+    return resolve(env.HOME || homedir(), CART_SESSION_DEFAULT_DIR);
+}
 export function cartSessionPath(env = process.env) {
     if (env.ITPAY_CART_SESSION_PATH) {
         return resolve(env.ITPAY_CART_SESSION_PATH);
     }
-    const dir = resolve(homedir(), CART_SESSION_DEFAULT_DIR);
+    const dir = stateDir(env);
     mkdirSync(dir, { recursive: true });
-    return resolve(dir, CART_SESSION_FILENAME);
+    return resolve(dir, stateFilename(CART_SESSION_FILENAME, resolveBackendURL(env)));
 }
 export function loadConfig(env = process.env) {
-    const baseURL = env.ITPAY_BACKEND_URL || DEFAULT_BASE_URL;
+    const baseURL = resolveBackendURL(env);
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
     const agentType = declaredAgentType(env);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";
@@ -33,10 +67,11 @@ export function loadConfig(env = process.env) {
     const ideImageDirOverride = env.ITPAY_IDE_IMAGE_DIR_OVERRIDE;
     return {
         baseURL,
+        environment: baseURL === DEV_BASE_URL ? "development" : "production",
         ...(agentType ? { agentType } : {}),
         checkoutCurrency,
         idempotencyKey,
-        ...(!env.ITPAY_IDEMPOTENCY_KEY ? { operationJournal: new OperationJournal(resolve(homedir(), CART_SESSION_DEFAULT_DIR, OPERATION_JOURNAL_FILENAME)) } : {}),
+        ...(!env.ITPAY_IDEMPOTENCY_KEY ? { operationJournal: new OperationJournal(resolve(stateDir(env), stateFilename(OPERATION_JOURNAL_FILENAME, baseURL))) } : {}),
         ideImageAttach,
         ...(ideImageDirOverride ? { ideImageDirOverride } : {}),
         ...(bearerToken ? { bearerToken } : {}),

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,17 +1,18 @@
 {
   "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, official Backend-scoped registrations, 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 currently selected official Backend 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.",
+    "backend_registration": "One registration per official Backend: app.itpay.ai by default and dev.itpay.ai only with the exact test override.",
     "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
     "presentation": "Host and target route output only and never identify the Agent or provide business input."
   },
@@ -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 the selected official Backend 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 selected official Backend 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 selected Backend registration is removed and the private key and other Backend registration remain"
     }
   ],
   "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 production traffic to use https://app.itpay.ai. Use https://dev.itpay.ai only for an explicit test and keep the complete returned Backend-prefixed command for that entire flow.",
+    "After automatic recovery fails, stop and report the exact code, selected official Backend, 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 test, local, an IP, or any custom Backend; only the exact official dev.itpay.ai test override is allowed.",
     "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"
+  ]
 }