@itpay/cli 2.0.14 → 2.0.15

package/README.md

@@ -15,7 +15,7 @@ itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The production Backend is permanently pinned to `https://app.itpay.ai`. Runtime environment variables cannot redirect the CLI to another Backend.
+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
 
@@ -46,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 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.
+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`: fixed production Backend liveness; `catalog list`: compatibility-gated 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.
@@ -75,11 +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, 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.
+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_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`.

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)),
         })),
     };
 }
@@ -304,7 +305,7 @@ export function errorRecoveryActions(error) {
         return [
             {
                 id: "retry_after_backend_recovers",
-                label: "Retry after app.itpay.ai is reachable",
+                label: "Retry after the selected official Backend is reachable",
                 command: "itpay readyz",
             },
         ];

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: "验证固定生产 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,10 +2,14 @@
 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 可用；先完整读取内置 ItPay Skill，再进入当前已支持的 buy 流程。sell 将来也使用同一入口，但当前尚未实现。",
+        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/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";
@@ -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) => ({
@@ -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,31 +212,34 @@ program
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        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: "固定生产后端 https://app.itpay.ai 当前不可用；后端恢复前不要继续下单，也不要切换到其他地址。",
+            instruction: `当前官方 Backend ${config.baseURL} 不可用；恢复前不要继续下单，也不要切换环境。`,
             recovery: [
-                { 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 app.itpay.ai 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 app.itpay.ai 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,5 +1,5 @@
-// CLI configuration loader. The production Backend is pinned to app.itpay.ai;
-// environment variables configure only non-Backend runtime details. 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";
@@ -11,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.14";
+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 = DEFAULT_BASE_URL;
+    const baseURL = resolveBackendURL(env);
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
     const agentType = declaredAgentType(env);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";
@@ -34,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/identity-and-sessions.json

@@ -4,16 +4,16 @@
   "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, the fixed app.itpay.ai production registration, 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.",
-    "An operator confirms that the app.itpay.ai Device registration database was reset."
+    "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 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.",
+    "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."
   },
   "automatic_recovery": [
@@ -34,27 +34,27 @@
       "success_signal": "the full Skill is returned and next keeps the same Agent Type"
     },
     {
-      "intent": "confirm app.itpay.ai 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 app.itpay.ai Device 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 app.itpay.ai registration is removed and the private key remains"
+      "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 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."
+    "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 redirect the CLI to dev, test, local, or any non-app.itpay.ai Backend.",
+    "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": [

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

@@ -33,20 +33,19 @@
   ],
   "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.",
+    "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.",
-    "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 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.",
+    "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 a Backend URL override; production CLI traffic always targets https://app.itpay.ai.",
+    "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."
   ],

package/docs/agent/buyer/quickstart.json

@@ -12,7 +12,7 @@
   "required_state": {
     "needs": [
       "the real supported Agent Type",
-      "the fixed production Backend https://app.itpay.ai"
+      "one official Backend: production https://app.itpay.ai by default, or explicit test https://dev.itpay.ai"
     ],
     "must_not_need": [
       "Admin access",
@@ -22,7 +22,7 @@
   },
   "commands": [
     {
-      "intent": "verify fixed production Backend availability",
+      "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 ItPay Skill"
     },
@@ -57,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.",

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

@@ -18,7 +18,7 @@ itpay cart remove --local --variant <catalog_variant_id> --offer <offer_id> [--j
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `--line <cart_item_id>` | 否 | canonical Cart line；省略时使用固定 `https://app.itpay.ai` 后端下最后保存的 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/device.md

@@ -10,6 +10,6 @@
 itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
-命令只作用于固定生产后端 `https://app.itpay.ai` 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。CLI 不接受 Backend URL 覆盖。该命令不访问 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/install.md

@@ -37,12 +37,12 @@ itpay install [target] [--json]
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
   "next": {
     "command": "itpay --agent-type codex-desktop readyz --json",
-    "reason": "验证固定生产 ItPay API 的可用性"
+    "reason": "验证当前官方 ItPay API 的可用性"
   },
   "recovery": [
     {
       "command": "itpay docs show install-and-setup",
-      "reason": "查看固定生产后端和首次使用说明"
+      "reason": "查看官方 Backend 和首次使用说明"
     }
   ]
 }

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

@@ -4,9 +4,9 @@
 
 ## 范围与意义
 
-检查固定生产 Backend `https://app.itpay.ai` 是否可用。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
+检查当前官方 Backend 是否可用。默认使用生产环境 `https://app.itpay.ai`；仅测试时可通过 `ITPAY_BACKEND_URL=https://dev.itpay.ai` 选择官方开发环境。它只调用 `/v1/readyz` 做 liveness 诊断，不执行平台兼容性 gate、不登记设备、不创建业务资源；需要服务端合同的命令仍会在各自入口严格检查 compatibility。
 
-**上游：** CLI 安装；Backend 固定为 `https://app.itpay.ai`，不可由运行时环境覆盖。
+**上游：** CLI 安装；Backend 只能是官方 `https://app.itpay.ai` 或 `https://dev.itpay.ai`，其他 override 在网络或本地状态写入前被拒绝。
 **下游：** 完整 `itpay` Skill，随后选择 Agent Type 或进入当前已支持的 Buyer Catalog。
 
 ## 语法与参数
@@ -24,16 +24,43 @@ itpay readyz [--json]
 ```json
 {
   "status": "ready",
-  "result": { "backend": "available" },
+  "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`，要求等待 `https://app.itpay.ai` 恢复后重试同一命令，不得切换后端或继续下单。
+连接失败时返回 `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 不匹配时，返回一个可执行且版本固定的恢复动作：
 
@@ -42,17 +69,17 @@ CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不
   "status": "error",
   "error": {
     "code": "backend_contract_incompatible",
-    "message": "CLI 2.0.14 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.15, maximum major 2)"
+    "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.14",
-    "required_cli_version": "2.0.15"
+    "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.15",
+      "command": "npm install -g @itpay/cli@2.0.16",
       "reason": "安装 Backend 指定的兼容 CLI 版本"
     }
   ]