@itpay/cli 2.1.41 → 2.1.45

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.",
@@ -16,6 +16,11 @@
       "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": "read railway refund/change targets and complete current input templates",
+      "command": "itpay --agent-type <agent_type> aftercare list --order <order_id> --json",
+      "success_signal": "safe original itinerary, available leg/passenger targets, requests and full refund/change templates"
+    },
     {
       "intent": "request a refund",
       "command": "itpay --agent-type <agent_type> refund create --order <order_id> --reason buyer_requested --json",
@@ -34,19 +39,23 @@
     {
       "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.",
+    "A railway order can contain 1–3 legs paid together and issued separately. Report all-issued only when every leg is issued; retain issued tickets on a partial failure or unknown result. Railway return and platform refund follow per-leg supplier facts; do not promise a full refund or create replacement tickets.",
+    "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.",
-    "Use get or watch after interruption; do not infer success from elapsed time.",
+    "Cancellation or rejection follows the returned order policy and never reactivates an old grant automatically.",
+    "Use get after interruption; explicit watch defaults to a bounded 20-second window and returns on change or manual attention. Do not restart watch automatically or 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."
+    "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.",
+    "Railway refund or manual change: use aftercare list for structured ticket targets. Match the user’s explicit legs/passengers; only ask when that scope is missing. Explain the scope and manual handling before create using the returned complete JSON. No supplier reference or amount is needed from the user.",
+    "Aftercare acceptance, supplier completion and platform money status are separate. Only real scope consent may set user_confirmed_scope=true. A concrete change proposal requires fresh approval of the current proposal revision and fees; the original purchase consent cannot approve it. This release has no automatic change payment link.",
+    "Partial refunds do not mean every ticket was returned. The platform delivery lock remains; use the safe aftercare journey for remaining-ticket facts, never promise validity from historical issued state. Protected ticket numbers still require account authorization."
   ],
   "human_explanations": {
     "payment_verified": "Payment is confirmed and the Order is recorded. Do not ask the human to pay again; continue the same delivery.",
@@ -55,11 +64,11 @@
     "refund_automatic": "The request is on the automatic policy path because the delivery is reported unconsumed; only the final server status proves success.",
     "refund_manual": "The request requires human review, commonly because delivery was consumed. Manual review is not a rejection.",
     "refund_unknown": "The payment channel outcome is unknown. Delivery stays locked while ItPay reconciles; never submit or replay another refund.",
-    "refund_succeeded": "ItPay confirms the refund succeeded and delivery is permanently closed."
+    "refund_succeeded": "ItPay confirms this request’s money refund succeeded. Verify its scope and the remaining-ticket facts separately; only the order’s full refunded state establishes all platform money returned."
   },
   "forbidden": [
     "Do not fabricate Buyer sessions, Device IDs or payment references.",
-    "Do not read delivery while refund access_locked is true.",
+    "Do not consume locked platform delivery; authorized safe remaining-ticket status reads are separate.",
     "Do not claim a refund succeeded before the Refund Owner says succeeded.",
     "Do not promise an unconditional refund, instant arrival, or a channel result that ItPay has not confirmed.",
     "Do not blame the human for a Provider, delivery, platform, or payment-channel failure."
@@ -92,5 +101,12 @@
     "交付失败",
     "没有收到结果",
     "能不能退"
-  ]
+  ],
+  "rail_notifications": {
+    "channels": "Delivery notices reach the checkout-confirmed contact: email always works; a verified mainland SMS recipient is optional and checkout-scoped. The passenger phone, the login phone and the notification recipient are independent facts.",
+    "status_read": "Use the current returned reader for ticket state; order summaries do not expose per-leg notification delivery records. Do not infer a sent or delivered notification.",
+    "truthfulness": "Provider acceptance is not delivery; an uncertain send outcome is reconciled, not silently retried. A notification failure never changes ticket or refund state; report it as a delivery detail, not an order failure.",
+    "unavailable": "If SMS is not configured or a recipient is unverified, email still satisfies the contact policy — never present an unverified phone as enabled."
+  },
+  "consumption_and_access": "Platform content consumption is not train usage; access_locked freezes platform delivery and does not prove ticket validity. Read actual refund/ticket facts; a future departure does not guarantee eligibility."
 }

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,8 @@
   "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.",
+    "For a railway journey, show one official checkout for all legs: one total/payment, separate issuance. The page shares its authoritative payment_deadline_at/server_now/payment_remaining_seconds; reaching zero requires reading current status, not declaring cancellation.",
     "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.",
@@ -65,5 +66,6 @@
     "付款后",
     "不要重复付款",
     "支付确认"
-  ]
+  ],
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

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

@@ -29,20 +29,34 @@
   "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": [
     "Run the original list, orders, or read command.",
     "OpenClaw must pass its current trusted host and required target on the original command so the authorization continuation preserves the real presentation destination.",
-    "If it returns human_authorization_required, run only its next.command once.",
+    "If it returns human_authorization_required and context is complete, run its executable next.command once. If next is null or context/consent is missing, fill the returned interaction/input_template first; never invent host, target or consent.",
     "Make the returned handoff genuinely visible and stop.",
     "After the human says authorization is complete, rerun the original read command unchanged.",
     "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://dev.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,29 +21,32 @@
     ]
   },
   "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."
+    "service_feedback": "Finish the original order outcome first, then optionally 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.",
+    "railway": "Known railway intent: itpay docs show rail-booking. 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.",
-    "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.",
+    "Run one state-changing command at a time. Treat next.command as the preferred continuation: execute it unchanged only when its required values are already present; fill a non-executable input_template separately 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.",
+    "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. Use --input key=value only for simple scalars; nested objects use a small JSON file with the existing --input-json command.",
+    "For non-rail delivery that explicitly requires email, ask only that missing value and explain its purpose. Railway identity and notification contact are handled on the protected official checkout page; never guess 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"
@@ -99,5 +106,7 @@
     "rating",
     "target",
     "input"
-  ]
+  ],
+  "reading_results": "Read normal CLI text directly, or parse the complete --json envelope with the host file reader. If saving stdout to a file, first check the command exit code, then read the whole file with cat or the existing file tool. Keep stderr separate; do not use head, tail, regex or a custom script to recover truncated results. Write complex input as a small JSON file and use --input-json.",
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

package/docs/agent/buyer/rail-booking.json

@@ -0,0 +1,176 @@
+{
+  "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 use the same entry point via itpay sell.",
+  "topic": "rail-booking",
+  "title": "Railway Query, Planning, and Ticket Booking",
+  "purpose": "One railway route from understanding the request to saved results, booking, protected checkout, order status and refunds.",
+  "when_to_use": [
+    "Any railway schedule, planning or ticket request; read this topic once before the first railway action."
+  ],
+  "goal_and_overview": {
+    "route": "Understand endpoints and constraints → 2–4 line route brief → Exact or Smart → read enough saved results for the goal → select under delegation → missing real consent only → official payment entry; show and stop.",
+    "query_vs_booking": "Exact/Smart returns a query execution and saved evidence. Booking creates a separate execution from a server-issued selection; it is not a repeated search.",
+    "comparison": "If the human only asked to compare, answer within the searched scope and stop without a buy-or-not question. Reuse already-read unchanged Skill/docs in this context; do not repeat install/readyz/docs at each step. A clear purchase delegation permits selection under their rules, subject to required human terms.",
+    "public_entry": "One public service itpay-rail declares query_exact, query_smart and prepare_purchase. Query, booking, Checkout and order remain separate identities. Legacy IDs are only for recovering their pinned historical executions.",
+    "price_approval": "Choosing a candidate or confirming seat/whole-journey terms is not approving price. Read the current scoped approve_purchase template after quote; record true only for genuine matching exact-price or capped-budget approval, or an explicitly authorized official-page confirmation. Reuse matching approval; never fabricate it."
+  },
+  "flow_at_a_glance": [
+    {
+      "step": "search Exact",
+      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
+      "returns": "one station-pair query execution, resolved scope and either useful results or a same-execution wait action",
+      "next": "follow the current next command when still working; compare results and stop if the request is satisfied"
+    },
+    {
+      "step": "search Smart",
+      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
+      "returns": "one broader planning execution, observed coverage and either useful results or a same-execution wait action",
+      "next": "follow the current next command when still working; compare results and stop if the request is satisfied"
+    },
+    {
+      "step": "read Exact result",
+      "command": "itpay services read-result <query_execution_id> --json",
+      "returns": "saved station-pair rows with detail.command; detail returns booking_template",
+      "next": "Read enough candidates for the user objective. Only a purchase delegation permits using the chosen template."
+    },
+    {
+      "step": "read Smart result",
+      "command": "itpay services read-result <query_execution_id> --snapshot <snapshot_id> --json",
+      "returns": "same-snapshot journeys and detail.command. Single-leg detail returns a selection action: use human only for a real user pick, agent for delegated selection; its result supplies booking credentials. Transfer detail returns the complete ordered selections template for one ticket plan; do not turn it into separate purchases.",
+      "next": "If current eligible options and full connections satisfy the request, answer or continue under delegation. Selecting a journey does not lock inventory; preserve whole-journey purchase. No unsupported ground distance/time estimates."
+    },
+    {
+      "step": "book",
+      "command": "itpay services run itpay-rail --operation prepare_purchase --input-json <file> --json",
+      "returns": "a separate booking execution using the returned selection token, seat code and party size",
+      "next": "follow its review or waiting action on that same booking execution"
+    },
+    {
+      "step": "review",
+      "command": "itpay services next <booking_execution_id> --json",
+      "returns": "current review revision, material terms and a non-executable confirm_booking input_template",
+      "next": "submit the returned actor-type agent template only after genuine consent; reuse an unchanged explicit consent for code-only correction"
+    },
+    {
+      "step": "checkout",
+      "command": "use the returned next or handoff for the same booking execution",
+      "returns": "an official protected payment entry",
+      "next": "show the official entry using the current host immediately before optional memory/log writing, then stop; retain necessary safety/permissions, do not infer paid or issued"
+    },
+    {
+      "step": "aftercare",
+      "command": "itpay order <order_id> --json",
+      "returns": "authoritative payment and ticket state",
+      "next": "use orders-refunds for the same order when needed"
+    }
+  ],
+  "understand_before_search": [
+    "Preserve full administrative names, original endpoint meaning, date, party size, deadlines and station locks. Ask only for a missing date or genuine ambiguity changing the destination/constraints; no preference means do not pre-ask station, seat or departure time.",
+    "Before the first railway query, leave one 2–4 line conclusion brief in conversation or existing route-brief.txt (choose one, no Backend upload or private reasoning): Origin: full original meaning; station/area/place; evidence from user/context/reliable knowledge/actual lookup; unknown facts. Destination: the same. Journey: date, given party size/deadlines; credible station pair or transfer direction and evidence; Exact/Smart choice and one-sentence reason. Never replace this with “understood”, or write it after querying as pre-query evidence. Reuse it while waiting, reading, quoting or buying; update only changed endpoints/scope/date. With existing results, serve the facts rather than restart for a missing ceremony; missing prior evidence remains unobserved.",
+    "Only clear reliable route knowledge can directly support a candidate. A merely possible/probable transfer or “a long trip should transfer” is unknown: first make one targeted lookup on 12306 or 同程, with 携程 only if needed. Stop once a credible direct station pair or transfer direction is established; do not collect complete external timetables, prices or inventory. Remembered trains still require ItPay to verify the actual date and stock.",
+    "12306 https://kyfw.12306.cn/ is the official date/station/train reference; claim a date verified only after reading that date result. 同程 https://www.ly.com/mergeTrain/huochepiao helps identify station pairs and transfer directions. 携程 https://trains.ctrip.com/ is an optional supplement for transfer routes. Knowledge, search snippets and historical timetables do not prove current operation, inventory, price or purchase credentials.",
+    "If login, captcha or network blocks the short lookup, stop without repeated troubleshooting or browser installation and state the facts still unknown. Clear double-station endpoints can use Exact to verify direct trains; do not choose Smart merely because a transfer seems probable. A known transfer requirement or supported multi-station/place comparison can use Smart; genuinely unclear place meaning needs human clarification.",
+    "Date verification is required; the ItPay query for the actual date can perform it. A 12306 visit is not a mandatory extra call for every order. Valid Smart journeys and credentials do not require routine Exact rechecks of each leg.",
+    "Each side independently means area, place or station, giving all nine combinations. An area is not a same-name station; a specific station stays locked until the human consents to changing it. Smart also supports two locked stations when transfers are needed.",
+    "Distance alone does not establish a transfer requirement. One observed route through a station does not make it mandatory; a failed short lookup or incomplete search cannot establish that all direct trains are absent.",
+    "Unclear meaning that changes region/scope needs one key question, using known context first. Clear meaning with unknown coordinates can use the complete name and mark location verification pending. Use maps/browser for place identity; 12306/同程 for rail directions, 携程 as needed. Do not require a residential location to be researched on 12306. No fabricated coordinates or passenger/payment data in notes."
+  ],
+  "choose_search": {
+    "exact": "Known or credible resolved station pair, direct trains for one station pair and date only. A zero result does not mean the whole city has no train. An area delegation may permit checking another evidence-based pair within that original area; a human-specified station stays locked until they consent to changing that endpoint.",
+    "smart": "Use Smart for a reliably established transfer direction or explicit transfer need, broad station comparison, or a precise place needing nearby stations and ground evidence. Preserve each endpoint as area/place/station; a probable transfer alone is not a basis for Smart. Fastest does not automatically mean max_transfers=0.",
+    "scope": "Exact cannot claim a citywide or all-transfer optimum. Smart gives its observed scope and missing evidence; its first useful options may be shown before expansion finishes."
+  },
+  "input_and_expected_result": {
+    "exact": {
+      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
+      "example": {
+        "input": {
+          "origin": "<已核实出发站>",
+          "destination": "<已核实到达站>",
+          "travel_date": "<用户出行日期 YYYY-MM-DD>"
+        }
+      },
+      "contract": "Only origin, destination and travel_date are accepted. Use station names, not an undocumented station-code field. Filter time, seat and quantity against returned rows. Date is illustrative; use the actual requested queryable date."
+    },
+    "smart": {
+      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
+      "example": {
+        "input": {
+          "endpoints": {
+            "origin": {
+              "kind": "area",
+              "text": "<用户出发市县镇完整名称>"
+            },
+            "destination": {
+              "kind": "station",
+              "text": "<已核实到达站名>"
+            }
+          },
+          "travel_date": "<用户出行日期 YYYY-MM-DD>"
+        }
+      },
+      "contract": "The current published input_schema is authoritative: use endpoints only when it exposes endpoints. Each side independently accepts kind area/place/station and a full text; fill kind when supported by endpoint understanding; omit it only when the object meaning is clear but its category genuinely awaits verification, explicitly recorded in the brief. An unknown city is not resolved by omitting kind. A complete named place is legal; coordinates are optional. Area centers choose nearby stations without claiming door-to-door ground travel; place uses verified POI/coordinates when available; station locks exactly one verified railway station and does not mean the traveler is already there. All nine origin/destination combinations follow this same rule. Province-only areas need a narrower location. Never mix endpoints with legacy origin/destination or send a station lock/confirmed flag. Adult passengers is an integer 1–5. arrive_before maps to arrive_by; conflicting aliases are rejected. preference_context is unsupported."
+    },
+    "result": "Read the resolved station pair or area scope, observed coverage, complete compact train rows, fare/inventory evidence and stable references. The recommendation card is not the full catalog. Unknown cost and unverified address ground facts remain unknown. Eligible means usable, not equally preferable. Prefer existing default_layer, roles, dominance and tradeoffs; show at most three meaningful representatives. A same-arrival, earlier-departing and more expensive dominated option stays in the saved catalog rather than taking the first screen.",
+    "waiting": "Use the same execution and returned bounded wait command. next is a read; background work may still proceed. Do not resubmit, sleep/get/events repeatedly, or reread the whole guide.",
+    "followup": "Read the saved result for the original execution. Smart: itpay services read-result <execution_id> --snapshot <snapshot_id> --json. Exact: use its returned saved-result reader. Read the relevant same-snapshot pages first; unread does not mean nonexistent. Do not automatically enumerate every theoretical combination. For a new Smart query, restore the original area/place/station intent, passengers, deadlines and preferences; an Exact pair is verified evidence, not proof of user station locks. Only a user-locked station change or scope expansion needs new consent. After a changed endpoint or date, supply the original intent and a same-owner reuse_from reference to an unexpired snapshot; unchanged resolved endpoints and matching fresh station-pair facts may be reused. Date change never reuses old inventory. Preference, party-size or deadline changes within the same scope use refine_preferences on the existing plan. Planning deadline does not erase saved facts; an old selection token is not refreshed by rereading. For expiry, use only the server safe fresh-query template once within the original authorization, preserving all conditions and omitting reuse_from; it may consume query quota. Existing or unknown purchases resume the same booking/order, never new queries. Refresh does not guarantee inventory or original price; confirm materially changed terms. Change to a named station: kind station with matching text/code. Original-station vicinity: kind place with verified station text, remove station_code, resolve normally or use verified POI/coordinates (existing 30 km/5 candidates). Whole city only with explicit consent: kind area with full administrative name, remove POI/location/station_code. Preserve date, passengers, time limits and preferences; refuse cross-owner reuse. The public Smart input does not expose overnight layover. A home or specific address remains the destination; nearby railway stations are candidates, never implicit station locks. Report the rail arrival station separately from any unknown last-mile connection. Preserve the endpoint brief; update only affected facts. A terminal location failure follows its explicit complete new-query template only after new evidence.",
+    "public_envelope": "New public operation files contain input plus, for prepare_purchase, the exact continuation supplied by saved result detail. Do not invent source execution/snapshot IDs. Historical executions use their own pinned schema."
+  },
+  "select_and_book": {
+    "delegation": "Apply existing seat/price/delegation rules. Exact fastest requires enough coverage to compare the station-pair candidates; without ordering/coverage evidence the first page is not proof. Smart can present up to three eligible representatives once full connections meet the goal, or continue under delegation; no routine full-catalog or all-seat paging. If an unapproved seat choice changes the price, combine that decision and missing terms into one question. Do not default to second class or require a three-tier menu. No match does not permit loosening conditions.",
+    "input": "Copy the complete current booking_template.input_example; retain passenger count, every ordered token and the returned seat_type code matched to seat_name. Never use a seat display name as the code, mix selections/selection/legs or guess missing credentials. Technical JSON errors are repaired by the Agent using current input_schema/input_errors/template, preserving original user requirements; ask the human only for a genuinely missing business choice.",
+    "command": "itpay services run itpay-rail --operation prepare_purchase --input-json <file> --json",
+    "identity": "Passenger name, ID and phone are entered on the official protected checkout page, not in query or booking JSON.",
+    "whole_journey": "Use the returned complete ticket plan booking_template: ordered selections (2–3 legs) from one owner/snapshot/revision/plan, or selection for one leg. One booking, one refreshed whole quote, one checkout, one order and one payment; each leg issues separately without connection or joint-seat guarantees. Raw legs are single-leg compatibility only; never hand-compose multi-leg legs when complete selections are missing or expired. Do not combine different plans or choose per-leg payment by default. Historical details without a whole-journey template do not prove whole-journey support."
+  },
+  "review_and_checkout": {
+    "review": "Copy the returned complete interaction.input_template.input, current revision and notice. For a whole journey, each ordered leg has its own seat_type and an object preference per passenger; default auto, never null/string arrays. Use known choices and confirm only missing genuine terms consent or material changes. Set accept_non_guaranteed=true only after real consent; delegation or choosing a train alone is not terms consent. The false default is protection, not a broken template; if consent is missing, ask the returned review.consent_question once. Seat/berth placement requests differ from the whole-journey separate-issuance and partial-outcome terms; use the current notice.",
+    "equivalent_correction": "If only seat code spelling changes while train, actual seat class, party, price and terms are identical, reuse an existing explicit human approval. Material draft changes or missing approval require human confirmation. Reuse accepted original endpoints, no-seat, overnight and incomplete-coverage facts when unchanged; never silently substitute the destination.",
+    "checkout": "Present the complete itinerary, total and single official handoff: one payment, separate issuance. The human enters one passenger set on that page; verified account notification email is reused there and can be changed for this order. Do not ask or guess traveler identity/email in chat. Use the returned checkout payment deadline, not an estimated duration. Handoff is not payment, and payment is not all legs issued."
+  },
+  "continue_and_aftercare": {
+    "same_execution": "Read the same booking/checkout/order. Report issued only when every leg is confirmed issued; partial or unknown outcomes keep the same order and successful tickets, reconcile before retry, and explain the affected leg. No automatic rebuy or full-refund promise.",
+    "saved_vs_live": "A saved snapshot remains historical evidence after expiry. Real-time booking or quote credentials may expire and require the documented fresh validation path; rereading an old token does not renew it.",
+    "refund": "For railway refund/change use itpay aftercare list --order <order_id> --json. Select returned leg/passenger targets from the user’s request, explain scope and manual processing, submit the complete current template. Request acceptance is not supplier success or money returned. Read the same case; concrete change proposals need current-revision consent and actual fee facts. No automatic change payment or replacement purchase."
+  },
+  "exceptional_branches": {
+    "login_required": "Use itpay auth login --json, complete the official handoff, then execute the returned recovery command for the same paused query. Login returning a command does not execute it.",
+    "rate_limited": "Respect returned retry_after and continue the same execution.",
+    "booking_review_invalid": "Read the same booking review and use the returned seat code; reuse real consent only under the strict equivalent-correction rule.",
+    "booking_review_changed": "Read the current revision and compare material terms; confirm new terms only when changed.",
+    "selection_stale": "Saved result stays readable, but follow the current owner action for new live inventory and quote evidence; do not assume reread refreshes the token.",
+    "unknown_paid_outcome": "Read the same checkout/order before any mutation. Never repeat payment or create a new order on an unknown outcome.",
+    "lock": "Normal device authorization uses no legacy lock. Preserve identity and old lock files; follow the actual error stage, not a generic lock-repair command.",
+    "empty": "Report verified scope, failures and missing evidence separately. Do not guess a new date or station as a generic repair. Explain checked scope first, then propose at most two evidence-backed directions. Ask consent before changing a locked endpoint; after consent copy the complete original input and change only the accepted side in a new query.",
+    "ground_evidence_required": "If trains were found but a precise address deadline cannot be verified without ground or station-exit evidence, report the checked rail scope and missing fact. Ask for a precise location or verifiable connection fact; do not expand rail station pairs by default or call it no trains. Preserve the original place and compare its nearby candidates; only actual user consent may replace the destination with a station.",
+    "dependency_unavailable": "Map faults are external failures, not empty location candidates. Preserve resolved endpoints and original conditions. For a retryable wait, respect dependency.retry_at and execute the returned same-execution run command; never restart or sleep inside the CLI. Daily quota, permission or IP failures need service maintenance, not a different address.",
+    "partial": "Report saved usable routes together with checked scope and the precise gap. Unqueried hubs, geographic evidence gaps and budget limits are not proof of no trains. Use the returned action only; do not expand station pairs by default. A proposal to relax a condition is allowed, but requires real consent before a changed-scope query.",
+    "geographic_notice": "Geographic deviation is a ranking or explanation notice. Current eligibility and booking conditions come from verified dates, connections, inventory, prices, authorization and required ground evidence; do not reject a returned eligible train merely by geometric ratio.",
+    "selection_invalid": "Use only the current finite reason and executable recovery. An input constraint error requires the current complete template; stored_selection_inconsistent is a server problem that extra parameters cannot repair. With no recovery, stop: never append hidden fields, recreate a purchase or blame local simulation without evidence.",
+    "location_evidence_required": "A unique verified place continues directly; real multiple candidates use only the returned choice action and preserve the original place. Area-only or conflicting identity evidence is not proof the place does not exist: read affected_endpoint, original place, limited resolved_scope and finite reason; use maps/browser for missing evidence or ask only necessary human facts. A terminated query cannot resume: only after new evidence, fill the complete non-executable new_query_template and create once, preserving the other side/date/party/preferences/locks. Do not switch place to area, fabricate reuse_from or repeatedly get a terminal execution. Only a real dependency wait resumes the same execution. Correcting a proven classification within unchanged intent needs no repeated consent; changing destination or enlarging scope needs real consent."
+  },
+  "search_terms": [
+    "rail",
+    "railway",
+    "train",
+    "ticket",
+    "火车",
+    "火车票",
+    "高铁",
+    "车票",
+    "车次",
+    "seat",
+    "booking",
+    "rail-booking"
+  ],
+  "reading_and_writing": "Use the formal Skill Follow one envelope rules for direct text/file reading, truncation and small JSON input; no parsing scripts.",
+  "restore_old_execution": "Only when resuming an existing v4 execution, follow its own declared legacy schema; new queries use the current three-endpoint contract.",
+  "saved_followup": "Use returned refine_preferences with expected_query_revision for arrival/departure times, passengers, seat preference or priority; rerank uses existing facts. Only endpoints/date/new scope require a new query. Profiles compare within one journey, not the whole catalog. Fares and service fees are whole-journey totals for the stated people; observed available is not proof of ample inventory. Page limit is 1-20; follow next_offset exactly, never infer full-catalog optimality from the visible page. Byte-limited pages may contain fewer rows than limit. Area station candidates are not guaranteed nearest; transfer wait/minimum are facts, not a low-risk guarantee.",
+  "actor_conventions": {
+    "location_confirmation": "Use the returned human template only for the user's real place choice; no delegated human action.",
+    "journey_terms": "workflow:confirm_booking and booking_review_invalid recovery accept agent-reported genuine consent; default false, never infer from purchase delegation.",
+    "ordinary_human_action": "Use its published actor rule; do not generalize railway permission.",
+    "price_approval": "approve_purchase uses actor-type agent with the unchanged server-scoped approval template and genuine matching approval; candidate choice is not price approval."
+  }
+}

package/docs/agent/buyer/rail-fast-checkout.json

@@ -0,0 +1,48 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer_agent",
+  "product_scope": "itpay_rail",
+  "topic": "rail-fast-checkout",
+  "title": "Rail Fast Checkout — Delegated Purchase Supplement",
+  "purpose": "Short delegated-purchase supplement to rail-booking; host presentation differences only.",
+  "when_to_use": [
+    "The buyer delegated railway selection and a current bookable result is available. Read rail-booking first."
+  ],
+  "steps": [
+    {
+      "step": "read_full_flow",
+      "command": "Use the rail-booking guide already read for this request",
+      "notes": [
+        "Use the current query result and booking_template; this topic does not replace the railway guide.",
+        "Before first querying, follow the single endpoint-understanding brief in rail-booking (meaning/category/evidence/unknowns and Exact/Smart choice). Use reliable route knowledge or one short lookup if merely probable. With current results, continue from their facts; do not restart to backfill a brief."
+      ]
+    },
+    {
+      "step": "continue_delegated_booking",
+      "command": "Use the current result’s booking_template and returned next action",
+      "notes": [
+        "Select under the buyer’s unchanged rules. Required human terms still require real consent. Continue the same booking execution.",
+        "Copy the complete plan template into one booking; raw legs are single-leg compatibility only, multi-leg purchases require the complete selections template; one whole quote and official payment entry, separate issuance. Use the returned full review JSON; only missing real agreement requires asking."
+      ]
+    },
+    {
+      "step": "present_host_handoff",
+      "command": "Use the current Host handoff",
+      "notes": [
+        "Show only the supported official entry. Read itpay order <order_id> --json after payment for authoritative status; issuing is not issued."
+      ]
+    }
+  ],
+  "never": [
+    "Never invent consent, identity or a seat code.",
+    "Never duplicate a purchase or repeat an unknown-outcome payment.",
+    "Never show an internal command to the human.",
+    "When a failure has no applicable next, interaction, recovery or complete new-query template, stop; never guess undeclared fields, duplicate a booking, split a journey into separate payments or claim an unverified cause."
+  ],
+  "search_terms": [
+    "fast checkout",
+    "快速下单",
+    "一键购票",
+    "rail checkout recipe"
+  ]
+}

package/docs/agent/buyer/render-hosts.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": "render-hosts",
   "title": "Agent Type And Human Handoff Rendering",
   "purpose": "Use only the handoff fields returned for the current Agent Type and make Checkout or read authorization genuinely visible on that surface.",
@@ -33,12 +33,17 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files; show the amount and stop"
+      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files, then send handoff.mobile_url as a clickable link that jumps straight into Alipay or WeChat Pay on a phone; show the amount and stop"
     },
     {
       "agent_type": "zcode",
       "default_host": "plain-chat",
-      "responsibility": "open handoff.url immediately in the ZCode built-in browser and stop; only show the same clickable URL when the built-in browser is unavailable"
+      "responsibility": "open handoff.url immediately in the ZCode built-in browser, also send handoff.mobile_url as the phone-friendly entry, then stop; when the built-in browser is unavailable show both clickable links"
+    },
+    {
+      "agent_type": "doubao-work",
+      "default_host": "plain-chat",
+      "responsibility": "show handoff.mobile_url as the preferred same-phone checkout or authorization link and handoff.qr_image_url as the labeled save-or-scan fallback; state the amount for Checkout and stop"
     },
     {
       "agent_type": "kimi-code",
@@ -49,7 +54,9 @@
       "agent_type": "openclaw",
       "default_host": null,
       "host_required": true,
-      "native_hosts": ["telegram"],
+      "native_hosts": [
+        "telegram"
+      ],
       "responsibility": "pass the native OpenClaw entry target explicitly; for Telegram execute handoff.agent_action unchanged, then treat itp:grant_confirmed callbacks only as permission to query the same Checkout and follow Backend grant state; otherwise show the returned HTTPS QR image and Checkout URL"
     }
   ],
@@ -66,20 +73,23 @@
     }
   ],
   "agent_rules": [
-    "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
-    "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
-    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser.",
-    "For zcode with plain-chat, open handoff.url in the built-in browser. Do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; use the same clickable URL only as fallback.",
-    "If the WorkBuddy action fails, send the original handoff.url, report that it did not auto-open, and stop without creating another payment resource.",
-    "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
+    "Agent Type is stable identity; Host is presentation and may be explicitly overridden. Once the official handoff is available, show it on this host before optional memory/log work; retain necessary safety and permissions.",
+    "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy Checkout handoff uses its returned Card Link and mobile URL; auth login may separately return a local QR path.",
+    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser, then send handoff.mobile_url so phone users can tap straight into Alipay or WeChat Pay.",
+    "For zcode with plain-chat, open handoff.url in the built-in browser and also send handoff.mobile_url as the phone entry; do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; when the built-in browser is unavailable show both clickable links.",
+    "For doubao-work with plain-chat, show two labeled official links: handoff.mobile_url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
+    "If the WorkBuddy action fails, send the original handoff.url and handoff.mobile_url, report that it did not auto-open, and stop without creating another payment resource.",
+    "handoff.mobile_url is the phone-friendly Checkout URL; when the current client cannot open links in place (for example a mobile mini program), send it and tell the human to copy it into the phone browser where it can jump into Alipay or WeChat Pay. It is only returned when the handoff carries the complete token pair; when absent, handoff.url remains the entry.",
+    "Do not claim a handoff was shown until the official entry supported by this Host is genuinely visible. A link-only Host does not require a QR.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
-    "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant."
+    "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant.",
+    "Business flow is the same across hosts. Vault grants apply only to protected purchased-content access, not every railway step."
   ],
   "forbidden": [
     "Do not expose display tokens separately from the tokenized Checkout handoff.",
     "Do not print base64 images, mirror lists, renderer debug state, or provider QR URLs.",
     "Do not claim a desktop attachment exists when only a filesystem path was printed.",
-    "Do not use present_files for a local file, QR PNG, downloaded copy, or rebuilt URL in WorkBuddy."
+    "For Checkout Card Link, do not use present_files for a local file, QR PNG, downloaded copy or rebuilt URL. Auth login is separate: use its actual handoff capabilities and returned local QR when supported; never rebuild it."
   ],
   "next_docs": [
     {
@@ -99,6 +109,7 @@
     "desktop",
     "workbuddy",
     "zcode",
+    "doubao work",
     "kimi code",
     "openclaw",
     "telegram"