@itpay/cli 0.1.0

package/docs/agent/buyer/account-portal.json

@@ -0,0 +1,65 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "account-portal",
+  "title": "Human Account Portal",
+  "purpose": "Teach the agent how to help a human open the ItPay account/order portal without reading protected content.",
+  "when_to_use": [
+    "The human asks to see their ItPay account or previous orders.",
+    "The original claim email link expired or was already used.",
+    "The agent needs to explain that human UI and agent status share the same redacted order state."
+  ],
+  "required_state": {
+    "needs": ["authenticated buyer account session"],
+    "must_not_need": ["claim token", "raw content", "portal page contents"]
+  },
+  "commands": [
+    {
+      "intent": "create a one-time human account portal link",
+      "command": "itp account login-link --json",
+      "success_signal": "response.status == account_portal_login_link_created and response.portal_login_link.one_time == true"
+    },
+    {
+      "intent": "same command under buyer namespace",
+      "command": "itp buyer account login-link --json",
+      "success_signal": "response.login_url is present"
+    },
+    {
+      "intent": "agent-side state check without opening the human portal",
+      "command": "itp buyer checkout status <checkout_id> --json",
+      "success_signal": "response contains redacted order/delivery state only"
+    }
+  ],
+  "agent_rules": [
+    "Give the one-time account portal link to the human buyer.",
+    "Do not open the account portal link yourself.",
+    "The human portal and agent APIs read the same redacted order/vault state.",
+    "If the human chooses one-key agent authorization after Passkey reveal, use `itp buyer vault grants list ...` to discover the active grant; do not ask the human to copy the grant id.",
+    "If the human reports an order status, verify it through buyer status/order commands instead of scraping the portal.",
+    "Protected artifact reveal still requires a later Passkey/WebAuthn human reveal flow."
+  ],
+  "forbidden": [
+    "Do not fetch, screenshot, scrape, cache, or summarize the account portal page.",
+    "Do not ask the human to paste portal contents, claim links, keys, or raw results into chat.",
+    "Do not claim the portal link is a raw content reveal link.",
+    "Do not reuse a portal link after it has been opened."
+  ],
+  "next_docs": [
+    {
+      "condition": "The user asks where a delivered item is",
+      "topic": "secure-delivery",
+      "command": "itp docs show secure-delivery --role buyer --json"
+    },
+    {
+      "condition": "The human approved agent access to selected fields",
+      "topic": "vault-agent-read",
+      "command": "itp docs show vault-agent-read --role buyer --json"
+    },
+    {
+      "condition": "The user asks why the agent cannot open the portal",
+      "topic": "safety-policy",
+      "command": "itp docs show safety-policy --role buyer --json"
+    }
+  ],
+  "search_terms": ["account portal", "orders", "login link", "one time link", "portal", "账号", "订单", "登录链接", "一次性链接"]
+}

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

@@ -0,0 +1,130 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "cart-checkout",
+  "title": "Cart-First Checkout",
+  "purpose": "Teach the agent to use the UCP cart handoff, including CORE-033 multi-item carts, instead of bypassing cart.",
+  "when_to_use": [
+    "The user selected one or more public catalog variants.",
+    "The agent needs an estimate before checkout.",
+    "The agent needs to create a checkout from cart_id.",
+    "A first-time wild agent may receive auth_qr as a first-purchase auth-to-payment entry before payment is verified."
+  ],
+  "required_state": {
+    "needs": [
+      "catalog_variant_id or catalog_variant_ids",
+      "buyer email for secure delivery",
+      "product-specific required input fields before cart creation"
+    ],
+    "optional": [
+      "buyer phone"
+    ],
+    "must_not_need": [
+      "catalog version",
+      "expected amount",
+      "ops token"
+    ]
+  },
+  "commands": [
+    {
+      "intent": "create a cart estimate for the selected UCP Variant.id",
+      "command": "itp buyer cart create --variant <variant_id> --json",
+      "success_signal": "response.cart.cart_id is present and agent_next_actions includes create_checkout_from_cart"
+    },
+    {
+      "intent": "create a multi-item cart estimate for selected UCP Variant.id values",
+      "command": "itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,2 --json",
+      "success_signal": "response.cart.line_items contains every selected variant and response.cart.amount is the estimated total"
+    },
+    {
+      "intent": "create an enterprise fuzzy search cart with required query input",
+      "command": "itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json",
+      "success_signal": "response.cart.cart_id is present; the raw provider result is not visible to the agent"
+    },
+    {
+      "intent": "create an enterprise precise lookup cart with exact registered name or credit code",
+      "command": "itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --json",
+      "success_signal": "response.cart.cart_id is present; payment can proceed only after the exact query input is locked into the cart line"
+    },
+    {
+      "intent": "view the current cart state without relying on model memory",
+      "command": "itp buyer cart show <cart_id> --json",
+      "success_signal": "response.cart.line_items and response.cart.totals reflect the server-side cart"
+    },
+    {
+      "intent": "add one more selected UCP Variant.id to an existing cart before checkout",
+      "command": "itp buyer cart add <cart_id> --variant <variant_id> --quantity 1 --json",
+      "success_signal": "response.cart.cart_id is unchanged and response.cart.line_items includes the new line"
+    },
+    {
+      "intent": "remove one line from an existing cart before checkout",
+      "command": "itp buyer cart remove <cart_id> --line <cart_line_item_id> --json",
+      "success_signal": "response.cart.cart_id is unchanged and response.cart.line_items no longer contains that line id"
+    },
+    {
+      "intent": "create checkout from cart_id",
+      "command": "itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json",
+      "success_signal": "response.checkout.checkout_id is present; if response.checkout.next_required_action is auth_qr, show response.checkout.human_action and poll/resume until payment_intent_id appears"
+    },
+    {
+      "intent": "do both steps through the high-level command",
+      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --json",
+      "success_signal": "response.status is waiting_human_auth, waiting_user_payment, payment_verified, or delivery_claimable"
+    }
+  ],
+  "agent_rules": [
+    "CORE-033 supports multiple cart lines and bounded positive quantities when all items belong to the same supported settlement/provider group.",
+    "Before cart creation, inspect product metadata input_schema_json and collect every required input field. Do not wait until after payment to ask for required query inputs.",
+    "Enterprise fuzzy search requires input.company_name. This can be a keyword, brand, short name, or partial company name supplied by the user, such as 京东.",
+    "Enterprise precise lookup requires input.company_name_or_credit_no. This must be a complete China mainland registered company name or unified social credit code. If the user only provides a brand/short name, resolve the exact name first or use fuzzy search before precise lookup.",
+    "Use --input key=value for service-specific inputs. For multiple lines, prefer separate cart add commands when each line needs different input.",
+    "Before checkout create, confirm buyer email is available for secure delivery. If it is missing, ask the human for the email before checkout; do not guess or use a placeholder.",
+    "Use cart_id as the checkout handoff.",
+    "Use buyer cart show whenever you need current cart contents. Do not rely on chat memory for cart state.",
+    "Use buyer cart add/remove before checkout when the user changes their mind. After checkout is created, treat the cart as locked.",
+    "Do not override cart line_items during checkout.",
+    "If the user asks for several compatible products, add them to one cart and create one checkout. Do not split into separate checkouts unless ItPay rejects the cart or says split checkout is required.",
+    "If the same cart is retried, expect the same checkout unless contact/client reference changes.",
+    "The backend revalidates catalog, price, and delivery requirements.",
+    "For first purchase, auth_qr means the ItPay first-purchase entry: provider login/registration/profile consent first, then ItPay should continue the same checkout to payment.",
+    "After presenting auth_qr, run buyer checkout resume and keep it active/waiting. Do not stop at QR display unless the human explicitly asks you to pause.",
+    "Do not tell the user auth_qr is a completed payment or payment proof.",
+    "For first purchase, show the ItPay auth entry as one human orchestration entry; after provider OAuth callback the same checkout exposes payment.",
+    "After showing auth_qr, poll checkout or run buyer checkout resume until identity_status becomes identity_resolved and payment_intent_id appears.",
+    "When auth completes, CLI should claim and store the buyer session so a repeat purchase by the same agent/device can skip auth."
+  ],
+  "forbidden": [
+    "Do not call legacy checkout directly for CORE-028 external-agent tests.",
+    "Do not pass a different variant in checkout after cart is created.",
+    "Do not create a second cart/checkout after a retryable timeout unless the user asks to abandon the previous one.",
+    "Do not buy enterprise precise lookup with only a vague brand/short name unless you have resolved the exact registered company name.",
+    "Do not claim enterprise API raw results are visible to the agent; they are delivered to the human Vault/claim UI."
+  ],
+  "next_docs": [
+    {
+      "condition": "Checkout returns auth_qr",
+      "topic": "payment-qr",
+      "command": "itp docs show payment-qr --role buyer --json"
+    },
+    {
+      "condition": "Checkout has payment_intent_id and payment QR is needed",
+      "topic": "payment-qr",
+      "command": "itp docs show payment-qr --role buyer --json"
+    },
+    {
+      "condition": "Cart or checkout command fails",
+      "topic": "recovery",
+      "command": "itp docs show recovery --role buyer --json"
+    }
+  ],
+  "search_terms": [
+    "cart",
+    "checkout",
+    "cart_id",
+    "line_items",
+    "quantity",
+    "购物车",
+    "下单",
+    "结账"
+  ]
+}

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

@@ -0,0 +1,71 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "catalog-search",
+  "title": "Catalog Search For Buyer Agents",
+  "purpose": "Help the agent find public ItPay services without login and without expensive repeated full searches.",
+  "when_to_use": [
+    "The user describes a need but has not chosen a service.",
+    "The agent needs product and variant details before recommendation.",
+    "The agent needs to search standardized API products such as ItPay enterprise data APIs."
+  ],
+  "required_state": {
+    "needs": ["search query or service intent"],
+    "must_not_need": ["buyer login", "payment intent", "ops token"]
+  },
+  "commands": [
+    {
+      "intent": "search public catalog by natural language query",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --json",
+      "success_signal": "response.products contains variants with id, title, price, metadata"
+    },
+    {
+      "intent": "search API services by stable category and safe facets",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --delivery-mode managed_capability --use-case company_lookup --input-facet company_name --json",
+      "success_signal": "response.products only contains products matching the requested category/facets"
+    },
+    {
+      "intent": "search fuzzy company lookup when the user only provides a partial company name",
+      "command": "itp buyer catalog search --query \"企业 模糊 查询 公司简称\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --use-case company_disambiguation --input-facet company_name --json",
+      "success_signal": "response.products includes the fuzzy enterprise search product before precise lookup"
+    },
+    {
+      "intent": "get exact product details for a selected variant",
+      "command": "itp buyer catalog get --variant <variant_id> --json",
+      "success_signal": "response.selection.catalog_variant_id matches the selected variant"
+    },
+    {
+      "intent": "discover low-cost shelf sync endpoints for repeated reads",
+      "command": "itp buyer shelf manifest --json",
+      "success_signal": "response.snapshot_version and response.snapshot_url are present"
+    }
+  ],
+  "agent_rules": [
+    "Full search is allowed for explicit user search, not as a polling loop.",
+    "For repeated discovery, prefer shelf manifest/snapshot/delta.",
+    "For API services, map user intent to category/facet filters before relying on keyword ranking.",
+    "Use stable categories: business_data_api, business_verification_api, identity_verification_api, phone_verification_api, risk_compliance_api, location_weather_api, finance_data_api.",
+    "Use safe facets such as --use-case, --input-facet, --output-facet, --sensitivity-level, --delivery-mode, and --provider.",
+    "Use product and variant metadata to explain options in user language.",
+    "For products with requires_human_input=true, do not ask for identity numbers or phone numbers in chat; rely on ItPay human authorization/input.",
+    "Do not create checkout until the user intent maps to one selected variant or the user confirms a cart."
+  ],
+  "forbidden": [
+    "Do not require login for discovery.",
+    "Do not invent catalog items or variant IDs.",
+    "Do not assume search result order means the user has approved purchase."
+  ],
+  "next_docs": [
+    {
+      "condition": "Need to recommend among variants",
+      "topic": "product-recommendation",
+      "command": "itp docs show product-recommendation --role buyer --json"
+    },
+    {
+      "condition": "The user has chosen a variant",
+      "topic": "cart-checkout",
+      "command": "itp docs show cart-checkout --role buyer --json"
+    }
+  ],
+  "search_terms": ["catalog", "search", "shelf", "product", "variant", "api", "enterprise_data", "category", "facet", "business_data_api", "企业查询", "工商信息", "企业工商数据精准查询", "企业工商数据模糊查询", "搜索", "商品"]
+}

package/docs/agent/buyer/human-claim-ui.json

@@ -0,0 +1,59 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "human-claim-ui",
+  "title": "Human Claim UI",
+  "purpose": "Explain the human-only claim page boundary to an agent.",
+  "when_to_use": [
+    "The human received a secure delivery email.",
+    "The user asks why the agent cannot see the key.",
+    "The delivery status says claim_link_sent or check_email."
+  ],
+  "required_state": {
+    "needs": ["delivery status or human email"],
+    "must_not_need": ["claim token in agent context", "raw content in CLI output"]
+  },
+  "commands": [
+    {
+      "intent": "show agent-safe delivery status only",
+      "command": "itp buyer deliveries list --checkout <checkout_id> --json",
+      "success_signal": "response.secrets.raw_content_included == false"
+    },
+    {
+      "intent": "check whether the human has granted this agent a scoped view",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "success_signal": "count > 0 means the human approved agent-readable access for this exact agent device"
+    }
+  ],
+  "agent_rules": [
+    "The human claim page is for the human buyer, not the agent.",
+    "The claim link is short-lived and single-use.",
+    "The agent may explain that ItPay intentionally separates agent operations from raw secret access.",
+    "If the human wants the agent to analyze or use the delivered result, ask them to click 'Give to Agent / 一键给 Agent' in the ItPay page and confirm with Passkey.",
+    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list ...`; do not ask the human to paste the grant id.",
+    "If the human later wants the agent to install or use something, wait for an explicit human-granted install/capability flow."
+  ],
+  "forbidden": [
+    "Do not ask the human to paste the claim link or key into chat.",
+    "Do not fetch the claim page with CLI, curl, browser automation, or an agent tool.",
+    "Do not store raw content in local run files."
+  ],
+  "next_docs": [
+    {
+      "condition": "The human wants to view their account or other orders later",
+      "topic": "account-portal",
+      "command": "itp docs show account-portal --role buyer --json"
+    },
+    {
+      "condition": "The human approved agent-readable fields",
+      "topic": "vault-agent-read",
+      "command": "itp docs show vault-agent-read --role buyer --json"
+    },
+    {
+      "condition": "The user asks why this boundary exists",
+      "topic": "safety-policy",
+      "command": "itp docs show safety-policy --role buyer --json"
+    }
+  ],
+  "search_terms": ["claim ui", "claim page", "human", "single use", "reveal", "领取页", "人类", "查看密钥"]
+}

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

@@ -0,0 +1,66 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "payment-qr",
+  "title": "Payment QR Display",
+  "purpose": "Teach the agent how to present ItPay-hosted human QR images without corrupting or replacing them.",
+  "when_to_use": [
+    "Checkout returns human_action.kind=auth_qr for the first-purchase auth-to-payment entry.",
+    "PaymentIntent has been created.",
+    "The CLI returned human_action.kind=payment_qr, qr_png_url, preferred_qr_url, or qr_image_url.",
+    "The human needs to scan with Alipay sandbox."
+  ],
+  "required_state": {
+    "needs": ["payment_intent_id", "human_action", "qr_png_url/preferred_qr_url or local_qr_path"],
+    "must_not_need": ["raw provider QR", "provider sign", "ops token"]
+  },
+  "commands": [
+    {
+      "intent": "create payment intent through the high-level buy flow",
+      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --display agent --json",
+      "success_signal": "response.payment_intent.human_action.local_qr_path or response.payment_intent.human_action.qr_png_url is present"
+    },
+    {
+      "intent": "recover a scanner order-not-found display problem",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --display agent --json",
+      "success_signal": "response.payment_intent.human_action.local_qr_path or response.payment_intent.qr_png_url is present and status is still waiting_user_payment or verified"
+    }
+  ],
+  "agent_rules": [
+    "If human_action.kind is auth_qr, present the ItPay first-purchase entry URL/QR and explain it starts account login/registration/profile authorization and should continue to payment for the same checkout after approval.",
+    "For auth_qr, the ItPay auth entry is the primary handoff. oauth_start_url is fallback/debug and should not replace the ItPay orchestration page.",
+    "For auth_qr, do not call payment-intent creation directly or create a new checkout; poll checkout or run buyer checkout resume until payment_intent_id appears.",
+    "Do not stop after showing auth_qr unless the human explicitly asks you to pause. Keep waiting/resuming the same checkout so the post-auth payment handoff can continue.",
+    "Do not describe auth_qr as payment success or payment proof. Only payment_intent.verified proves payment.",
+    "MUST show local_qr_path first when present. Many agent clients do not reliably render remote QR images; local_qr_path is the most reliable desktop/chat display artifact.",
+    "If local_qr_path is not present, show qr_png_url or preferred_qr_url as the primary scannable QR. This is an ItPay-hosted human QR image; it may render the native provider payment code for scanner reliability, but the agent must not request or decode the raw provider payload.",
+    "Use qr_image_url/SVG only as a fallback when PNG/local rendering is unavailable.",
+    "For mobile users, present mobile_wallet_url as a clickable payment button when present.",
+    "payment_entry_url is the stable ItPay status/payment page. qr_png_url/local_qr_path is usually the better desktop scanner artifact.",
+    "In Alipay sandbox, the provider can briefly show order not found even after precreate succeeded. Tell the human to wait 30-60 seconds and retry the same QR/page. Do not create a new checkout, do not create a new payment intent, and do not repeatedly refresh unless the ItPay page or CLI explicitly asks for recovery.",
+    "Opening the payment page must not be treated as paid.",
+    "After showing QR, immediately wait for payment verification."
+  ],
+  "forbidden": [
+    "Do not encode payment_entry_url into a new QR yourself when qr_png_url/local_qr_path is available.",
+    "Do not encode mobile_wallet_url into a new QR yourself.",
+    "Do not request or display raw provider QR payloads.",
+    "Do not bypass the ItPay auth orchestration page by making oauth_start_url the primary user-facing link.",
+    "Do not rewrite, shorten, summarize, or translate QR URLs.",
+    "Do not expose raw provider QR payload in chat.",
+    "Do not treat QR display as payment success."
+  ],
+  "next_docs": [
+    {
+      "condition": "QR is visible to the human",
+      "topic": "payment-wait",
+      "command": "itp docs show payment-wait --role buyer --json"
+    },
+    {
+      "condition": "Alipay sandbox says order not found after waiting on the same QR/page",
+      "topic": "qr-refresh",
+      "command": "itp docs show qr-refresh --role buyer --json"
+    }
+  ],
+  "search_terms": ["qr", "payment qr", "alipay", "scan", "order not found", "二维码", "扫码", "付款码"]
+}

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

@@ -0,0 +1,54 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "payment-wait",
+  "title": "Payment Wait Contract",
+  "purpose": "Teach the agent to wait for human payment through the ItPay event wait contract instead of sleeping or guessing.",
+  "when_to_use": [
+    "The human is scanning or paying.",
+    "PaymentIntent status is waiting_user_payment.",
+    "The CLI returned agent_wait metadata."
+  ],
+  "required_state": {
+    "needs": ["payment_intent_id"],
+    "optional": ["cursor"],
+    "must_not_need": ["ops token", "provider query permission", "human text proof"]
+  },
+  "commands": [
+    {
+      "intent": "wait for payment verified event",
+      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "success_signal": "response.payment_event.event_type == payment_intent.verified"
+    },
+    {
+      "intent": "resume checkout after verified event",
+      "command": "itp buyer checkout status <checkout_id> --json",
+      "success_signal": "response.delivery.status or response.checkout.status is returned"
+    }
+  ],
+  "agent_rules": [
+    "wait.timeout is a heartbeat, not a payment failure.",
+    "Continue waiting with the same payment_intent_id unless the command reaches its overall timeout or the user cancels.",
+    "Payment success is payment_intent.verified only.",
+    "After verified, poll checkout or delivery status."
+  ],
+  "forbidden": [
+    "Do not accept 'I paid' as proof.",
+    "Do not run provider query recovery from buyer flow.",
+    "Do not create a duplicate checkout merely because one wait cycle timed out.",
+    "Do not call worker run-once."
+  ],
+  "next_docs": [
+    {
+      "condition": "payment_intent.verified received",
+      "topic": "secure-delivery",
+      "command": "itp docs show secure-delivery --role buyer --json"
+    },
+    {
+      "condition": "wait timeout or interrupted agent run",
+      "topic": "recovery",
+      "command": "itp docs show recovery --role buyer --json"
+    }
+  ],
+  "search_terms": ["wait", "long poll", "timeout", "still waiting", "paid", "payment", "等待", "付款", "付款成功", "没返回", "一直等", "超时"]
+}

package/docs/agent/buyer/product-recommendation.json

@@ -0,0 +1,79 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "product-recommendation",
+  "title": "Product Recommendation Rules",
+  "purpose": "Help the agent explain public product variants before checkout without overclaiming fulfillment or payment status.",
+  "when_to_use": [
+    "The user asks what to buy.",
+    "Catalog search returned multiple variants.",
+    "The user's request is fuzzy, such as company lookup, identity verification, phone verification, low budget, premium skin, or ten draw."
+  ],
+  "required_state": {
+    "needs": [
+      "catalog product or search result"
+    ],
+    "must_not_need": [
+      "buyer profile values",
+      "payment status",
+      "raw delivery content"
+    ]
+  },
+  "commands": [
+    {
+      "intent": "refresh exact product detail before recommendation",
+      "command": "itp buyer catalog get --variant <variant_id> --json",
+      "success_signal": "response.product.variants includes current price and availability"
+    }
+  ],
+  "agent_rules": [
+    "Map user intent to the variant description and price.",
+    "For API products, explain what the API checks or returns, quota unit, sensitivity level, required human input, and whether Passkey/WebAuthn reveal is required.",
+    "If metadata says agent_may_view_raw_result=false, tell the user secure delivery/reveal is human-first and do not request the raw result.",
+    "For enterprise fuzzy search, tell the user the required input is a company keyword/short name/brand. The user can say something broad like 京东; the service is designed to return candidates.",
+    "For enterprise precise lookup, warn that the input must be the exact registered company name or unified social credit code. If the user is vague, use fuzzy search or other knowledge/search to lock the correct entity before checkout.",
+    "For enterprise precise lookup, examples of acceptable input are 北京京东世纪贸易有限公司 or a unified social credit code; examples of insufficient input are 京东, 那个京东商城, 大众知道那个京东.",
+    "For regulated_identity or personal_sensitive products, do not collect identity numbers or phone numbers in chat; direct the flow through ItPay human authorization/input.",
+    "For the CORE-028 PUBG sandbox pack: 20 CNY is low-cost couple skin, 40 CNY is premium skin, 288 CNY is ten-draw supply pack.",
+    "Tell the user the service is a sandbox test service when applicable.",
+    "Ask for confirmation before buying if the user's intent is ambiguous."
+  ],
+  "forbidden": [
+    "Do not promise real game delivery for a sandbox service.",
+    "Do not hide the price.",
+    "Do not choose a more expensive variant without a clear user signal."
+  ],
+  "next_docs": [
+    {
+      "condition": "User confirmed the variant",
+      "topic": "cart-checkout",
+      "command": "itp docs show cart-checkout --role buyer --json"
+    },
+    {
+      "condition": "Need to search again",
+      "topic": "catalog-search",
+      "command": "itp docs show catalog-search --role buyer --json"
+    },
+    {
+      "condition": "Need to know how to pass required API product input into cart",
+      "topic": "cart-checkout",
+      "command": "itp docs show cart-checkout --role buyer --json"
+    }
+  ],
+  "search_terms": [
+    "recommend",
+    "compare",
+    "which one",
+    "variant",
+    "option",
+    "api",
+    "sensitivity",
+    "quota",
+    "passkey",
+    "推荐",
+    "怎么选",
+    "区别",
+    "敏感等级",
+    "查询次数"
+  ]
+}

package/docs/agent/buyer/qr-refresh.json

@@ -0,0 +1,52 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "qr-refresh",
+  "title": "QR Refresh Recovery",
+  "purpose": "Teach the agent how to recover scanner problems without changing payment truth or creating a second order.",
+  "when_to_use": [
+    "The human reports Alipay sandbox says order not found after waiting 30-60 seconds on the same QR/page.",
+    "The QR expired or the wallet cannot load it.",
+    "The payment intent is still not verified."
+  ],
+  "required_state": {
+    "needs": ["payment_intent_id"],
+    "must_not_need": ["ops token", "provider query", "new checkout"]
+  },
+  "commands": [
+    {
+      "intent": "ask ItPay for same-intent display recovery",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+      "success_signal": "response.payment_intent.qr_png_url or response.payment_intent.qr_image_url is present"
+    },
+    {
+      "intent": "continue waiting after refresh",
+      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "success_signal": "payment_event.event_type == payment_intent.verified"
+    }
+  ],
+  "agent_rules": [
+    "QR refresh is display recovery only. ItPay may return the same QR again when the current provider QR is still valid.",
+    "Use the same payment_intent_id.",
+    "For Alipay sandbox order-not-found, first ask the human to wait and scan/open the same QR/page again; use refresh only after that wait has failed.",
+    "After refresh, continue waiting through the normal wait contract."
+  ],
+  "forbidden": [
+    "Do not treat refresh as paid.",
+    "Do not query Alipay from buyer flow.",
+    "Do not create a new checkout unless the user explicitly abandons the old one."
+  ],
+  "next_docs": [
+    {
+      "condition": "refreshed QR is visible",
+      "topic": "payment-wait",
+      "command": "itp docs show payment-wait --role buyer --json"
+    },
+    {
+      "condition": "refresh fails",
+      "topic": "recovery",
+      "command": "itp docs show recovery --role buyer --json"
+    }
+  ],
+  "search_terms": ["refresh", "order not found", "expired qr", "qr unavailable", "刷新", "订单不存在"]
+}