@itpay/cli 2.1.19 → 2.1.22

package/docs/agent/buyer/catalog-list.json

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "catalog-list",
   "title": "Browse ItPay V3 Service Catalog",
   "purpose": "Explain available services, outcomes, conditions, and prices in human language without exposing catalog identifiers.",
@@ -20,7 +20,8 @@
     "item_format": "Explain the title, what the human receives, any auxiliary discovery step, and the published price.",
     "service_flow": "Explain discovery as an auxiliary identity-confirmation step, including free quota and paid continuation. Present primary_service as the actual paid outcome. Read all values from the manifest.",
     "variant_selection": "Internal IDs are for the Agent's next command only and are never shown or requested from the human.",
-    "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically."
+    "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically.",
+    "railway": "Railway entries point to itpay docs show rail-booking --json; use its query and booking contracts instead of a generic start→invoke→cart sequence."
   },
   "agent_rules": [
     "Use catalog list only when the human asks for a new service, not when they want an earlier purchase.",
@@ -28,15 +29,32 @@
     "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
     "State free quota, paid continuation price, email requirement, and claim purpose exactly as published; do not exaggerate or omit conditions.",
     "Ask the human to choose only when multiple services could satisfy the goal; never make them choose an internal variant or offer ID.",
-    "After services start, submit service keywords only through the returned capability command's --input key=value options; --target is never a search keyword."
+    "Use each service’s returned input contract; railway planning and booking follow rail-booking, not a universal Cart route."
   ],
   "human_language": {
-    "prefer": ["服务", "查询", "报告", "免费次数", "价格", "你会得到什么"],
-    "avoid": ["service_id", "variant_id", "offer_id", "capability", "manifest"]
+    "prefer": [
+      "服务",
+      "查询",
+      "报告",
+      "免费次数",
+      "价格",
+      "你会得到什么"
+    ],
+    "avoid": [
+      "service_id",
+      "variant_id",
+      "offer_id",
+      "capability",
+      "manifest"
+    ]
   },
   "next_docs": [
     {
-      "condition": "Buyer selected a service and wants to purchase",
+      "condition": "Railway service selected",
+      "topic": "rail-booking"
+    },
+    {
+      "condition": "Non-rail Buyer selected a service and wants to purchase",
       "topic": "cart-checkout",
       "file": "docs/agent/buyer/cart-checkout.json"
     }

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

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "identity-and-sessions",
   "title": "Device Identity And Session Recovery",
   "purpose": "Explain stable local identity, official Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
@@ -12,7 +12,7 @@
   ],
   "identity_model": {
     "local_key": "One owner-only Ed25519 private key for the local installation.",
-    "backend_registration": "One registration per official Backend: app.itpay.ai by default and sandbox.itpay.ai only with the exact test override.",
+    "backend_registration": "One registration per configured official Backend. Follow the current CLI backend allowlist; do not switch to evade failures.",
     "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."
   },
@@ -26,10 +26,10 @@
     "Re-enrolling a public key the Backend already holds re-attaches to the existing device and quota lineage after proof-of-possession; it never creates a duplicate device. If enrollment verification keeps failing with internal_error, or returns agent_device_key_rotated or agent_device_key_conflict, `itpay device reset-key --confirm-key-reset` is the supported way to start over with a fresh key."
   ],
   "local_state_recovery": [
-    "Device state updates use an atomic directory lock and owner-only atomic file replacement; no lock file is opened with fs.open or fs.openSync.",
+    "Device state uses an owner-only atomic file replacement and a lock that the CLI can inspect. On a stale lock, run the returned device repair-lock command; it only reclaims a proven stale owner.",
     "Operation idempotency uses one immutable owner-only record per operation key. Different commands and Agent processes do not share a global operation-journal lock; legacy operations.json is read only.",
     "On device_state_unwritable, use the reported operation and errno to diagnose the failing stage without exposing local paths; keep the same Agent Type and CLI/Node launcher, restore Host-approved persistent access to ~/.itpay-v3, then retry the original command.",
-    "Do not manually create or delete state locks, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+    "Do not delete a live lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
   ],
   "commands": [
     {
@@ -51,19 +51,24 @@
       "intent": "abandon the local device key after the Backend refuses to complete enrollment with it (persistent internal_error, agent_device_key_rotated, or agent_device_key_conflict)",
       "command": "itpay device reset-key --confirm-key-reset --json",
       "success_signal": "the local private key is discarded and the next command enrolls as a brand-new device"
+    },
+    {
+      "intent": "repair only a proven stale local device lock",
+      "command": "itpay device repair-lock --json",
+      "success_signal": "the CLI reports whether the lock was stale and reclaimed; an active owner stays protected"
     }
   ],
   "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 production traffic to use https://app.itpay.ai. Use https://sandbox.itpay.ai only for an explicit test and keep the complete returned Backend-prefixed command for that entire flow.",
+    "Production defaults to https://app.itpay.ai; explicit sandbox or dev testing uses https://sandbox.itpay.ai or https://dev.itpay.ai. Keep the complete returned Backend-prefixed command for that 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, local, an IP, or any custom Backend; only the exact official sandbox.itpay.ai test override is allowed.",
+    "Do not switch Backend to evade a failure. Allowed public URLs are app.itpay.ai, sandbox.itpay.ai and dev.itpay.ai; local loopback requires the explicit CLI development flag.",
     "Do not use --target as identity or service input."
   ],
   "next_docs": [
@@ -93,10 +98,10 @@
   ],
   "auth_session_states": {
     "stages": "The CLI now reports the auth session stage exactly as the server returns it: waiting_provider (show the handoff and wait), email_verification_required (the human must verify the emailed code on the auth page), merge_confirmation_required (an existing account matches — the human must confirm the merge on the auth page), provider_pending/pending (generic wait), completed (session done — bind it, do not restart).",
-    "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and start a NEW session only if the human still wants in — never keep polling a dead one.",
-    "transport_unknown": "auth_session_unknown means a network error while polling — the outcome is unknown. Keep waiting on the SAME session (it may still complete); do NOT restart auth, and do not assume denial.",
-    "missing": "auth_session_not_found means the cached session is gone server-side; start a new login.",
-    "completed_resume": "When login completes, itpay auth login resumes the remembered pending service execution automatically when one exists — you do not need to find it yourself.",
+    "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and respect denial or cancellation. Start a new session only on an explicit login request; never keep polling a dead one.",
+    "transport_unknown": "auth_status_unknown means a network error while polling — the outcome is unknown. Keep waiting on the SAME session (it may still complete); do NOT restart auth, and do not assume denial.",
+    "missing": "auth_session_missing means the cached session is gone. An explicit auth login opens one fresh official session in that call; auth status stays read-only.",
+    "completed_resume": "After login completes, execute the returned command to resume the same paused service execution. Login does not silently run that command.",
     "path_b": "A buyer who reaches checkout without a login completes identity inside the protected checkout page; never force a separate itpay auth login first."
   }
 }

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

@@ -35,20 +35,21 @@
     "For first setup or a runtime change, identify the real Agent Type once, run itpay install <agent_type> --json yourself, and follow its setup continuation until the packaged Skill is loaded. Ordinary service requests start from the Skill's service command, without repeating install or readyz.",
     "After setup, tell the human only that ItPay is ready; never ask them to run setup commands or explain technical setup steps.",
     "Use the CLI distribution already provided by the current npm package, Skill, or plugin; update only through that distribution's own instructions.",
-    "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL https://sandbox.itpay.ai; no other Backend is allowed.",
+    "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL the configured official test Backend only when explicitly requested; follow the CLI allowlist.",
     "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update 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 one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, doubao-work, kimi-code, or openclaw.",
     "For compatibility, a global --agent-type codex declaration is normalized immediately to codex-desktop; all registration, output, and returned commands use codex-desktop. Never generate the alias, and do not use codex as an install target.",
-    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai and sandbox.itpay.ai.",
+    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai, sandbox.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 and target only select a presentation destination; load render-hosts only when a handoff cannot be shown.",
     "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."
+    "Do not change Agent Type or rotate local identity to reset quota or recover a failed command.",
+    "Skillhub and local host bundles are separate installed artifacts; verify their version and packaged Skill/docs instead of assuming an npm update changed them."
   ],
   "forbidden": [
     "Do not use terminal, claude-code, or plain-chat as Agent Types. Do not generate codex as an Agent Type; it is accepted only as a legacy global declaration and becomes codex-desktop before any request.",
-    "Do not set or suggest any Backend except the default https://app.itpay.ai or the exact test override https://sandbox.itpay.ai.",
+    "Do not set or suggest a Backend outside the CLI allowlist: https://app.itpay.ai, https://sandbox.itpay.ai, https://dev.itpay.ai; local loopback requires the CLI development flag. Do not switch Backend to evade a failure.",
     "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/orders-refunds.json

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "orders-refunds",
   "title": "Order, Delivery, Customer Care And Refund Recovery",
   "purpose": "Explain paid-order and delivery problems to the human, then read or manage the same owned Order without guessing payment, consumption, or refund state.",
@@ -34,16 +34,16 @@
     {
       "intent": "cancel before provider submission",
       "command": "itpay --agent-type <agent_type> refund cancel <refund_request_id> --json",
-      "success_signal": "the Refund Owner cancels the request and requires a new delivery authorization"
+      "success_signal": "the Refund Owner returns the current cancellation and access state; old grants do not revive"
     }
   ],
   "agent_rules": [
     "Act as the human's ItPay service representative: explain payment, delivery, access, and refund facts in plain language before giving the next action.",
     "After verified payment, say the Order is recorded and the human must not pay again. Recover that same Order or Service Execution if delivery is delayed or fails.",
     "ItPay derives payment, amount, currency, account ownership, and refund policy from the owned order; explain only their user-facing meaning.",
-    "Unconsumed delivery normally follows the automatic policy; consumed delivery normally requires manual review. These are policy routes, not promises of a successful or instant refund.",
+    "Read this order’s current refund policy. Railway return depends on supplier ticket facts and may require manual review; platform refund status alone does not prove a train ticket was returned.",
     "A refund request freezes all delivery paths and revokes existing grants immediately.",
-    "Cancellation or rejection restores eligibility but never reactivates an old grant.",
+    "Cancellation or rejection follows the returned order policy and never reactivates an old grant automatically.",
     "Use get or watch after interruption; do not infer success from elapsed time.",
     "Never switch CLI/MCP lanes or identities to recover an order or refund error.",
     "A read-only MCP Agent may explain policy and order facts, but directs refund actions to the ItPay Dashboard or a full Local CLI Agent."

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

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "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.",
@@ -13,7 +13,7 @@
     {
       "intent": "present the Checkout handoff",
       "command": "<execute the exact command returned by buy or services checkout>",
-      "success_signal": "the human can see both the ItPay Checkout QR or image and the Checkout URL"
+      "success_signal": "the returned official URL and/or QR supported by the actual Host is visible to the human"
     },
     {
       "intent": "read authoritative Checkout state",
@@ -29,7 +29,7 @@
   "agent_rules": [
     "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
-    "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
+    "Obtain only missing required agreement or material price/term changes. Reuse a valid explicit confirmation for unchanged terms; never invent it.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
     "Use only the handoff fields returned for the current Host. Load render-hosts if the official handoff is not visible.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",

package/docs/agent/buyer/purchased-content.json

@@ -29,7 +29,7 @@
   "intent_routing": {
     "previous_content": "Use vault list, optionally with the subject as --query.",
     "purchase_history": "Use orders.",
-    "new_service": "Use catalog only when the human asks for a new query or purchase.",
+    "new_service": "For a new railway request, read rail-booking; for other new services, use catalog. No previous-content match does not block a separately requested new railway query.",
     "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay."
   },
   "authorization_flow": [
@@ -41,8 +41,22 @@
     "Never rerun vault access as a status check."
   ],
   "human_language": {
-    "prefer": ["previously purchased content", "past report", "purchase history", "已购内容", "以前购买的报告", "购买记录"],
-    "avoid": ["Vault", "artifact", "Device", "Buyer", "grant", "start token"]
+    "prefer": [
+      "previously purchased content",
+      "past report",
+      "purchase history",
+      "已购内容",
+      "以前购买的报告",
+      "购买记录"
+    ],
+    "avoid": [
+      "Vault",
+      "artifact",
+      "Device",
+      "Buyer",
+      "grant",
+      "start token"
+    ]
   },
   "partial_results": {
     "available": "Explain the returned section normally.",

package/docs/agent/buyer/quickstart.json

@@ -1,7 +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.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "quickstart",
   "title": "Route One Human Intent Through ItPay",
   "purpose": "Choose the correct first action from the human's words and continue through one authoritative CLI envelope at a time.",
@@ -12,7 +12,7 @@
   "required_state": {
     "needs": [
       "the real supported Agent Type",
-      "one official Backend: production https://app.itpay.ai by default, or explicit test https://sandbox.itpay.ai"
+      "one allowed Backend: production https://app.itpay.ai by default; explicit https://sandbox.itpay.ai or https://dev.itpay.ai for the corresponding test environment"
     ],
     "must_not_need": [
       "Admin access",
@@ -21,18 +21,21 @@
     ]
   },
   "intent_routing": {
-    "new_service": "Use catalog list only for a new service or query.",
+    "new_service": "For other new services, use itpay catalog list --json and the selected input contract.",
     "previous_content": "Use vault list, optionally with the subject as --query.",
     "purchase_history": "Use orders.",
     "refund_or_paid_problem": "Resume the known Order or Refund before creating anything new.",
     "service_feedback": "Finish the original order outcome first, then submit one safe Agent postmortem; include a rating or comment only when the human explicitly gives it.",
-    "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay."
+    "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay.",
+    "railway": "Known railway intent: itpay docs show rail-booking --json. Read once, then follow its Exact/Smart route."
   },
-  "commands": [{
-    "intent": "continue the selected flow",
-    "command": "<execute the exact next.command returned by the previous CLI envelope>",
-    "success_signal": "the next envelope reports one current state and at most one preferred action"
-  }],
+  "commands": [
+    {
+      "intent": "continue the selected flow",
+      "command": "<execute the exact next.command returned by the previous CLI envelope>",
+      "success_signal": "the next envelope reports one current state and at most one preferred action"
+    }
+  ],
   "agent_rules": [
     "Use the CLI as the control surface; infer the human's intent before the first command and never hardcode a service workflow.",
     "Treat result as current facts, instruction as how to use those facts, next as the preferred executable action, and recovery as exceptional paths.",
@@ -40,10 +43,10 @@
     "Keep the same explicit Agent Type through next and recovery commands; same-type windows reuse one Backend Agent Instance.",
     "When testing sandbox, execute every returned command unchanged so its ITPAY_BACKEND_URL=https://sandbox.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.",
     "Explain useful service facts in ordinary language; never ask the human to run commands or learn internal IDs.",
-    "Normal payment uses the returned ItPay Checkout handoff."
+    "Normal payment uses the returned ItPay Checkout handoff.",
+    "A railway query execution and its separate booking execution may serve one purchase intent; keep both references."
   ],
   "forbidden": [
     "Do not invent catalog, variant, offer, capability, result item, order or refund IDs.",
@@ -51,6 +54,10 @@
     "Do not bypass a grant, refund lock, ownership error or compatibility gate."
   ],
   "next_docs": [
+    {
+      "condition": "Known railway request",
+      "topic": "rail-booking"
+    },
     {
       "condition": "Need service catalog language",
       "topic": "catalog-list"