@itpay/cli 2.0.3 → 2.0.7

package/docs/agent/buyer/cart-checkout.json

@@ -2,105 +2,49 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "cart-checkout",
-  "title": "V3 Cart-First Checkout",
-  "purpose": "Teach the agent to use the current V3 canonical server cart flow without treating local CLI state as business truth.",
+  "title": "Canonical Cart And Checkout Routing",
+  "purpose": "Use the canonical server Cart and route service-backed lines through Service Execution without hardcoded service logic.",
   "when_to_use": [
-    "The user already chose a catalog item, variant, and offer.",
-    "The agent needs to add a catalog item to a server cart before checkout.",
-    "The agent wants to understand how service-backed cart items create or resume Service Execution."
+    "A catalog item or variant is ready to add.",
+    "An interrupted Cart or Checkout needs recovery."
   ],
-  "required_state": {
-    "needs": [
-      "catalog_item_id",
-      "catalog_variant_id",
-      "offer_id"
-    ],
-    "optional": [
-      "quantity",
-      "contact email",
-      "contact phone",
-      "agent_device_id for service-backed items"
-    ],
-    "must_not_need": [
-      "catalog search support from this CLI"
-    ]
-  },
   "commands": [
     {
-      "intent": "add the first line to the canonical server cart",
-      "command": "itpay cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --quantity 1 --host <client> --json",
-      "success_signal": "JSON includes cart_id and cart_item_id; service-backed lines also include service_execution_id and top-level next_actions"
+      "intent": "add one published line",
+      "command": "itpay --agent-type <agent_type> cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --quantity 1 --json",
+      "success_signal": "result identifies the canonical cart line and next contains one executable recovery or service command"
     },
     {
-      "intent": "recover the next step for the current cart",
-      "command": "itpay cart next --json",
-      "success_signal": "JSON includes next_actions derived from the canonical server cart and Service Execution read model"
+      "intent": "read the canonical Cart route",
+      "command": "itpay --agent-type <agent_type> cart next --json",
+      "success_signal": "service-backed lines route to services next; ordinary lines route to buy"
     },
     {
-      "intent": "inspect the current canonical server cart before checkout",
-      "command": "itpay cart show",
-      "success_signal": "server cart lines, checkout readiness, and service refs are printed"
+      "intent": "create an ordinary Checkout",
+      "command": "itpay --agent-type <agent_type> buy --cart <cart_id> --json",
+      "success_signal": "status is human_checkout_required and handoff contains only fields usable by the current Host"
     },
     {
-      "intent": "soft-remove one active line from the canonical server cart",
-      "command": "itpay cart remove --line <cart_item_id>",
-      "success_signal": "the line is removed from the server cart; quote-locked or checkout-bound lines return a conflict"
-    },
-    {
-      "intent": "abandon the canonical server cart",
-      "command": "itpay cart clear",
-      "success_signal": "the server cart is abandoned, active lines are soft-removed, and local handles are cleared"
-    },
-    {
-      "intent": "create checkout from a server cart that is ready for checkout",
-      "command": "itpay buy --cart <cart_id> --host <client> [--contact-email <email>] [--contact-phone <phone>]",
-      "success_signal": "the CLI either renders checkout_qr or emits an interaction request for missing contact data"
-    },
-    {
-      "intent": "create quote lock and checkout for a service-backed cart item",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
-      "success_signal": "the quote lock is bound to the original server cart item when present; JSON includes checkout_id and display_token"
-    },
-    {
-      "intent": "read the next Service Execution action",
-      "command": "itpay services next <service_execution_id> --json",
-      "success_signal": "JSON includes next_actions such as invoke capability, select result item, or checkout"
+      "intent": "create or resume a service Checkout",
+      "command": "itpay --agent-type <agent_type> services checkout <service_execution_id> --capability <capability_id> [--input key=value] [--email <email>] --json",
+      "success_signal": "one Checkout handoff is returned; rerun with --resume after output or token loss"
     }
   ],
   "agent_rules": [
-    "The current V3 CLI uses server cart as the business source of truth. Local ~/.itpay-v3/cart.json only caches last ids and explicit local drafts.",
-    "Prefer top-level next_actions and itpay next/cart next/services next over hardcoded service-specific flows.",
-    "Use cart add/show/remove/clear before checkout. Remove and clear are server-side soft state changes, not hard deletes.",
-    "For service-backed items, use service_execution_id from cart add/show as the canonical handle for services invoke/action/checkout.",
-    "Do not call buy --cart on a service-backed cart item until the required service action and quote lock are complete.",
-    "Do not remove quote-locked or checkout-bound cart lines. Continue checkout/payment or use refund/cancel owner flow after payment.",
-    "If required contact data is missing, prefer --require-contact so the CLI can emit a structured interaction request.",
-    "Do not invent buyer email or phone values; let the human provide them when required.",
-    "Only request --email when the selected capability declares delivery_email_required. Tell the buyer it sends the protected result claim link.",
-    "The happy-path buy flow creates cart and checkout, then renders checkout_qr. It should not create a payment intent first."
+    "The Backend Cart is business truth; ~/.itpay-v3/cart.json only stores local recovery handles and explicit drafts.",
+    "Run the exact next.command returned by the CLI. Do not extract or invent a capability from a raw list.",
+    "One service intent uses one Service Execution. Start another execution for another independent intent.",
+    "Ask for email only when the selected capability requires protected delivery; never invent contact data.",
+    "A lost Checkout response is retried with the same Cart and persisted idempotency operation."
   ],
   "forbidden": [
-    "Do not treat local cart files as durable business truth.",
-    "Do not create duplicate checkout commands if the first handoff is still usable.",
-    "Do not treat QR display as proof of payment."
+    "Do not call ordinary buy for a service-backed Cart line.",
+    "Do not create a second Checkout when the existing one can be resumed.",
+    "Do not treat QR display as payment verification."
   ],
   "next_docs": [
-    {
-      "condition": "Need host rendering details after checkout is created",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    },
-    {
-      "condition": "Need order or refund follow-up after payment",
-      "topic": "orders-refunds",
-      "file": "docs/agent/buyer/orders-refunds.json"
-    }
+    { "condition": "Checkout handoff is ready", "topic": "payment-flow" },
+    { "condition": "Host rendering needs clarification", "topic": "render-hosts" }
   ],
-  "search_terms": [
-    "cart",
-    "checkout",
-    "buy",
-    "购物车",
-    "结账"
-  ]
+  "search_terms": ["cart", "checkout", "service execution", "resume", "contact"]
 }

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

@@ -27,7 +27,8 @@
     "Read the variant IDs and prices from the output; do not invent them.",
     "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.",
-    "If the buyer wants to search by keyword, filter the catalog output client-side (no backend search yet)."
+    "If the buyer wants to search by keyword, filter the catalog output client-side (no backend search yet).",
+    "After services start, submit service keywords only through the returned capability command's --input key=value options; --target is never a search keyword."
   ],
   "next_docs": [
     {

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

@@ -0,0 +1,64 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "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.",
+  "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."
+  ],
+  "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.",
+    "presentation": "Host and target route output only and never identify the Agent or provide business input."
+  },
+  "automatic_recovery": [
+    "The CLI reuses a valid cached device session.",
+    "On one HTTP 401 with code agent_device_session_required, it invalidates only the current Backend and Agent Type session, renews it, and retries the exact request once.",
+    "A second failure is returned to the Agent. The CLI does not loop, switch Agent Type, rotate the key, or create a replacement v2 device.",
+    "A revoked v2 registration requires explicit operator recovery; it is never silently replaced."
+  ],
+  "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.",
+    "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 a lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+  ],
+  "commands": [
+    {
+      "intent": "reload the complete rules",
+      "command": "itpay --agent-type <agent_type> skill show itpay-buyer --json",
+      "success_signal": "the full Skill is returned and next keeps the same Agent Type"
+    },
+    {
+      "intent": "confirm the selected 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",
+      "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"
+    }
+  ],
+  "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."
+  ],
+  "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 use --target as identity or service input."
+  ],
+  "next_docs": [
+    { "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"]
+}

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

@@ -2,81 +2,51 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "install-and-setup",
-  "title": "Install and Configure ItPay V3 CLI for Agent Hosts",
-  "purpose": "Guide the agent or runtime owner through installing and configuring the itpay CLI for different agent hosts.",
+  "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.",
   "when_to_use": [
-    "First-time setup of the itpay CLI.",
-    "The agent needs to be configured for a specific host (Codex, Claude Code, etc.).",
-    "The buyer wants to use itpay in a new environment."
+    "The CLI is being installed or upgraded.",
+    "The agent needs to confirm its stable runtime identity and default output Host."
   ],
   "commands": [
     {
-      "intent": "list all supported install targets",
-      "command": "itpay install",
-      "success_signal": "Table of targets (claude-code, codex, terminal, telegram, feishu) with config file paths."
+      "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"
     },
     {
-      "intent": "show install instructions for a specific target",
-      "command": "itpay install claude-code",
-      "success_signal": "Step-by-step instructions for Claude Code setup."
+      "intent": "read the complete packaged operating contract",
+      "command": "itpay skill show itpay-buyer --json",
+      "success_signal": "status is shown, result.content contains the complete Skill, and next selects Agent Type or Catalog"
     },
     {
-      "intent": "show install instructions for Codex / Trae",
-      "command": "itpay install codex",
-      "success_signal": "Step-by-step instructions for Codex/Trae setup."
-    }
-  ],
-  "env_vars": {
-    "ITPAY_BACKEND_URL": {
-      "required": false,
-      "description": "Optional V3 backend override. The CLI defaults to https://app.itpay.ai.",
-      "examples": ["http://localhost:18080", "https://test.itpay.ai"]
-    },
-    "ITPAY_BEARER_TOKEN": {
-      "required": false,
-      "description": "Bearer token for authenticated operations (orders list, vault, profile). Not needed for anonymous cart/checkout.",
-      "acquired_from": "Sign in via web at /signin, then copy the session token."
-    },
-    "ITPAY_CART_SESSION_PATH": {
-      "required": false,
-      "description": "Custom path for the cart session file. Default: ~/.itpay-v3/cart.json"
-    },
-    "ITPAY_AGENT_DEVICE_ID": {
-      "required": false,
-      "description": "Legacy compatibility input. V3 enrolls a signed device identity under ~/.itpay-v3/device; agents should not rotate or invent this value."
+      "intent": "list supported Agent Types",
+      "command": "itpay install --json",
+      "success_signal": "status is install_targets and exactly five agent_type/default_host pairs are returned"
     },
-    "ITPAY_AGENT_TYPE": {
-      "required": false,
-      "description": "Agent runtime type. Set this or pass --agent-type for commerce commands, for example codex-desktop or claude-code-cli."
-    },
-    "ITPAY_CURRENCY": {
-      "required": false,
-      "description": "Default currency for cart operations. Default: CNY"
+    {
+      "intent": "read setup for the real runtime",
+      "command": "itpay install <agent_type> --json",
+      "success_signal": "status is instructions_ready and next is a readyz command using that exact Agent Type"
     }
-  },
-  "host_requirements": {
-    "terminal": "No special config needed. QR renders as ASCII in terminal or saved as PNG file.",
-    "codex": "Use --host codex or --host trae. Markdown output with images and links.",
-    "claude-code": "Use --host claude-code. Markdown format with image references.",
-    "telegram": "Use --host telegram --target <chat_id>. Output includes openclaw_message payloads.",
-    "feishu": "Use --host feishu --target <open_id>. Output is Feishu Interactive Card JSON.",
-    "lark": "Use --host lark --target <open_id>. Same as feishu format."
-  },
+  ],
   "agent_rules": [
-    "Use the built-in https://app.itpay.ai production default; override ITPAY_BACKEND_URL only for another deliberate environment.",
-    "Install globally with npm install -g @itpay/cli for all hosts.",
-    "Identify the real runtime with --agent-type or ITPAY_AGENT_TYPE; do not invent a new type to obtain quota.",
-    "Run `itpay install` without arguments to see all supported targets.",
-    "Server cart facts persist in backend Postgres. ~/.itpay-v3/cart.json only caches last ids, checkout display token, and explicit local drafts."
+    "Install with npm install -g @itpay/cli.",
+    "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
+    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
+    "One local private key is reused, but each exact Backend API base URL has its own server registration and quota lineage.",
+    "Within one Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
+    "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 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" }
   ],
-  "search_terms": [
-    "install",
-    "setup",
-    "configure",
-    "first time",
-    "setup",
-    "安装",
-    "配置",
-    "environment"
-  ]
+  "search_terms": ["install", "agent type", "host", "target", "device", "session", "identity", "backend", "codex", "claude code", "workbuddy"]
 }

package/docs/agent/buyer/orders-refunds.json

@@ -2,75 +2,53 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "orders-refunds",
-  "title": "Orders, Payment Escape Hatch, And Refund Requests",
-  "purpose": "Teach the agent how to inspect orders and create refund requests with the current V3 CLI package.",
+  "title": "Order, Delivery And Refund Recovery",
+  "purpose": "Read owned orders and manage refunds through signed Agent authority without guessing payment or refund state.",
   "when_to_use": [
-    "The user wants to inspect one order.",
-    "The agent needs to list orders for an account-scoped bearer session.",
-    "The user wants to request a refund.",
-    "The checkout page is unavailable and the operator needs the payment-intent escape hatch."
+    "An order or Service Execution was interrupted after payment.",
+    "The buyer asks to request, track, or cancel a refund."
   ],
-  "required_state": {
-    "needs": [
-      "order_id for order or refund flows",
-      "ITPAY_BEARER_TOKEN for refund flows"
-    ],
-    "optional": [
-      "refund reason; defaults to buyer_requested"
-    ]
-  },
   "commands": [
     {
-      "intent": "read one canonical order by id",
-      "command": "itpay order <order_id>",
-      "success_signal": "order details and a status hint are printed"
+      "intent": "read one order",
+      "command": "itpay --agent-type <agent_type> order <order_id> --json",
+      "success_signal": "one compact owned-order summary and one current next step are returned"
     },
     {
-      "intent": "list account-visible orders",
-      "command": "ITPAY_BEARER_TOKEN=<account_scoped_token> itpay orders --limit 20",
-      "success_signal": "orders are listed, or the CLI prints that no orders were found"
+      "intent": "request a refund",
+      "command": "itpay --agent-type <agent_type> refund create --order <order_id> --reason buyer_requested --json",
+      "success_signal": "the Refund Owner returns its request id, policy status, consumption state, and access lock"
     },
     {
-      "intent": "create a payment intent only when the normal checkout page cannot do it",
-      "command": "itpay pay --checkout <checkout_id> --method alipay",
-      "success_signal": "payment_intent_id and current payment state are printed"
+      "intent": "recover one refund",
+      "command": "itpay --agent-type <agent_type> refund get <refund_request_id> --json",
+      "success_signal": "one authoritative refund snapshot is returned"
     },
     {
-      "intent": "request a refund for an order",
-      "command": "ITPAY_BEARER_TOKEN=<account_scoped_token> itpay refund --order <order_id> --reason buyer_requested",
-      "success_signal": "refund request id and refund status are printed"
+      "intent": "wait through provider processing",
+      "command": "itpay --agent-type <agent_type> refund watch <refund_request_id> --json",
+      "success_signal": "one terminal refund envelope or one resumable timeout envelope is returned"
+    },
+    {
+      "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"
     }
   ],
   "agent_rules": [
-    "Use itpay order when you already know the exact order id.",
-    "Use itpay orders only with an account-scoped bearer token. Missing or wrong scope should be surfaced as an error, not guessed away.",
-    "Treat itpay pay as an operator escape hatch. The checkout handoff remains the preferred path.",
-    "Never ask the user or client to supply refund payment ids, amount, currency, buyer id, or actor; the backend derives them from the owned order.",
-    "The refund response is the current source of truth; do not assume success locally."
+    "The Backend derives payment, amount, currency, Buyer and refund policy from the owned order.",
+    "A refund request freezes all delivery paths and revokes existing grants immediately.",
+    "Cancellation or rejection restores eligibility but never reactivates an old grant.",
+    "Use get or watch after interruption; do not infer success from elapsed time.",
+    "Account-wide orders requires an account-scoped Buyer bearer; exact order and refund routes support the bound signed Agent where documented."
   ],
   "forbidden": [
-    "Do not fabricate bearer tokens.",
-    "Do not create a payment intent first if normal checkout rendering is available.",
-    "Do not claim a refund succeeded before the backend response says so."
+    "Do not fabricate Buyer sessions, Device IDs or payment references.",
+    "Do not read delivery while refund access_locked is true.",
+    "Do not claim a refund succeeded before the Refund Owner says succeeded."
   ],
   "next_docs": [
-    {
-      "condition": "Need the initial buyer flow",
-      "topic": "quickstart",
-      "file": "docs/agent/buyer/quickstart.json"
-    },
-    {
-      "condition": "Need host-specific render behavior for checkout handoff",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    }
+    { "condition": "Need the original purchase path", "topic": "quickstart" }
   ],
-  "search_terms": [
-    "order",
-    "orders",
-    "refund",
-    "payment intent",
-    "退款",
-    "订单"
-  ]
+  "search_terms": ["order", "refund", "cancel", "watch", "delivery lock", "grant"]
 }

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

@@ -2,76 +2,47 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "payment-flow",
-  "title": "ItPay V3 Payment Flow — From Checkout to Verified Payment",
-  "purpose": "Teach the agent how to hand a checkout to the human, let the ItPay checkout page create provider payment, and verify payment state.",
+  "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.",
   "when_to_use": [
-    "The agent has created a checkout and needs to hand it to the human.",
-    "The buyer wants to pay via Alipay or WeChat Pay.",
-    "The agent needs to wait for payment verification before confirming success."
+    "buy or services checkout returned human_checkout_required.",
+    "The agent restarted or lost the Checkout output before payment was confirmed."
   ],
   "commands": [
     {
-      "intent": "create checkout from a canonical server cart and render ItPay checkout page handoff",
-      "command": "itpay buy --cart <cart_id> --host <client> --contact-email <email>",
-      "success_signal": "ItPay checkout QR/URL is rendered for the human; payment intent is not created by the agent."
+      "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"
     },
     {
-      "intent": "create service-execution quote lock and render ItPay checkout page handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>]",
-      "success_signal": "The quote lock is bound to the original server cart item when present; ItPay checkout QR/URL is rendered for the human; the checkout page handles authorization and provider payment."
+      "intent": "read authoritative Checkout state",
+      "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+      "success_signal": "pending returns one human handoff; completed returns no payment handoff and routes to delivery"
     },
     {
-      "intent": "create service-execution checkout with machine-readable handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
-      "success_signal": "JSON with kind='checkout_handoff_required', next_action='open_human_checkout', checkout_url, display_token, qr_png_url, and brand_qr_local_path."
-    },
-    {
-      "intent": "recover a service checkout after output loss, process restart, or token expiry",
+      "intent": "recover a service Checkout handoff",
       "command": "itpay services checkout <service_execution_id> --resume --json",
-      "success_signal": "The existing checkout is reused and a fresh handoff is persisted before rendering."
-    },
-    {
-      "intent": "inspect checkout state after payment",
-      "command": "itpay checkout --id <checkout_id> --token <display_token>",
-      "success_signal": "Current checkout status, any payment intents, and buyer session state."
+      "success_signal": "the same unpaid Checkout is reused with a fresh short-lived handoff"
     }
   ],
-  "payment_flow_states": {
-    "quote_bound": "Checkout created, no payment intent yet. Show the ItPay checkout QR/URL to the human.",
-    "payment_pending": "Payment intent created, waiting for buyer to complete payment.",
-    "payment_succeeded": "Payment verified via SSE event payment_intent.verified.",
-    "completed": "Order delivered."
-  },
   "agent_rules": [
-    "Do not call itpay pay or use --pay for the normal buyer flow; those are operator escape hatches.",
-    "The human opens the ItPay checkout page first; the page handles authorization and creates the Alipay/WeChat payment intent.",
-    "For JSON output, render brand_qr_local_path or qr_png_url to the human; do not render provider qr.alipay.com directly.",
-    "After timeout, re-run checkout --id ... --token ... to check current state before retrying.",
-    "Payment success is confirmed ONLY by backend events, not by QR display or buyer claim."
+    "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.",
+    "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.",
+    "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
+    "A terminal payment state must never display another payment handoff."
+  ],
+  "forbidden": [
+    "Do not render a provider QR in place of the ItPay Checkout handoff.",
+    "Do not mix a display token from another Checkout.",
+    "Do not create a replacement Checkout after an uncertain response; recover first.",
+    "Do not use services quote, cart, buy, or pay as a fallback when the single-Service checkout flow fails.",
+    "Do not start another Service Execution to bypass quota, candidate, quote, checkout, or delivery state."
   ],
   "next_docs": [
-    {
-      "condition": "Payment verified, need to check order state",
-      "topic": "orders-refunds",
-      "file": "docs/agent/buyer/orders-refunds.json"
-    },
-    {
-      "condition": "Need to understand render behavior per host",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    }
+    { "condition": "Payment is verified", "topic": "orders-refunds" },
+    { "condition": "The current Host cannot display the handoff", "topic": "render-hosts" }
   ],
-  "search_terms": [
-    "payment",
-    "pay",
-    "alipay",
-    "wechat",
-    "QR",
-    "payment intent",
-    "wait",
-    "SSE",
-    "verified",
-    "支付",
-    "扫码"
-  ]
+  "search_terms": ["payment", "checkout", "QR", "display token", "resume", "verified"]
 }