@itpay/cli 2.1.19 → 2.1.29

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

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

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

@@ -1,7 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
-  "product_scope": "itpay is the single public CLI entry point, and $itpay is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are buy and sell: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.",
+  "product_scope": "itpay is the single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "payment-flow",
   "title": "Human Checkout Handoff And Payment Verification",
   "purpose": "Show the ItPay Checkout to the human and recover authoritative payment state without creating duplicate payment resources.",
@@ -13,7 +13,7 @@
     {
       "intent": "present the Checkout handoff",
       "command": "<execute the exact command returned by buy or services checkout>",
-      "success_signal": "the human can see both the ItPay Checkout QR or image and the Checkout URL"
+      "success_signal": "the returned official URL and/or QR supported by the actual Host is visible to the human"
     },
     {
       "intent": "read authoritative Checkout state",
@@ -29,7 +29,7 @@
   "agent_rules": [
     "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
-    "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
+    "Obtain only missing required agreement or material price/term changes. Reuse a valid explicit confirmation for unchanged terms; never invent it.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
     "Use only the handoff fields returned for the current Host. Load render-hosts if the official handoff is not visible.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",

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

@@ -29,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://sandbox.itpay.ai"
+      "one allowed Backend: production https://app.itpay.ai by default; explicit https://sandbox.itpay.ai or https://dev.itpay.ai for the corresponding test environment"
     ],
     "must_not_need": [
       "Admin access",
@@ -21,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."
+    "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 sandbox, execute every returned command unchanged so its ITPAY_BACKEND_URL=https://sandbox.itpay.ai prefix is preserved.",
-    "Use --target only for a Host presentation destination. Put capability business values in --input key=value exactly as required by the schema.",
-    "Start a separate Service Execution for each independent service intent; quota remains shared according to Backend identity policy.",
+    "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.",
     "Ask the user for required email or contact values and explain their purpose; never invent them.",
     "Explain useful service facts in ordinary language; never ask the human to run commands or learn internal IDs.",
-    "Normal payment uses the returned ItPay Checkout handoff."
+    "Normal payment uses the returned ItPay Checkout handoff.",
+    "A railway query execution and its separate booking execution may serve one purchase intent; keep both references."
   ],
   "forbidden": [
     "Do not invent catalog, variant, offer, capability, result item, order or refund IDs.",
@@ -51,6 +54,10 @@
     "Do not bypass a grant, refund lock, ownership error or compatibility gate."
   ],
   "next_docs": [
+    {
+      "condition": "Known railway request",
+      "topic": "rail-booking"
+    },
     {
       "condition": "Need service catalog language",
       "topic": "catalog-list"
@@ -99,5 +106,6 @@
     "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."
 }

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

@@ -4,160 +4,140 @@
   "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": "Choose the right railway service for the buyer's situation, submit the exact input contract each service expects, bridge a chosen train into booking via the server-issued selection, and follow the protected checkout flow without inventing field names.",
+  "purpose": "One railway route from understanding the request to saved results, booking, protected checkout, order status and refunds.",
   "when_to_use": [
-    "The buyer wants train schedules, routes, or tickets.",
-    "A railway service execution fails at the geo, search, catalog, or recommend step.",
-    "The buyer only knows a city or fuzzy location rather than a station name.",
-    "The buyer asks about seat preferences, refunds, or ticket issuance status.",
-    "A query returned login_required or rate_limited."
+    "Any railway schedule, planning or ticket request; read this topic once before the first railway action."
   ],
-  "service_selection": {
-    "itpay-rail-exact": "Use when both exact railway station names are known, or when a few credible station-pair hypotheses can be checked with exact (e.g. 古镇 → 广州南). It is one station-pair + one travel_date query: filter the returned list locally for remembered train numbers or time windows — do NOT re-query per train. Do not silently treat a city name as its station.",
-    "itpay-rail-smart": "Use when the buyer has a city name, an area, an address, or wants transfer planning and recommendations. The platform resolves locations to stations itself; never silently convert a city into its namesake station.",
-    "itpay-rail-booking": "Purchase service — use after the buyer chooses a train/seat or delegates selection under clear rules. Starts draft/review → live quote → protected checkout → asynchronous issuance on one execution. Never queried for schedules.",
-    "svc_qizhidao_company_lookup": "Not a railway service; do not mix intents."
+  "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 from the results and stop. A clear purchase delegation permits selection under their rules, subject to required human terms."
   },
-  "input_contract": {
-    "itpay-rail-exact": {
-      "required": {
-        "origin": "Departure railway station name only, e.g. 古镇. Not a city or an address.",
-        "destination": "Arrival railway station name only, e.g. 广州南.",
-        "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date; aliases like date are rejected."
-      },
-      "optional": "None. additionalProperties is false — extra fields are rejected by the provider.",
-      "example": {
-        "origin": "古镇",
-        "destination": "广州南",
-        "travel_date": "2026-09-19"
-      }
+  "flow_at_a_glance": [
+    {
+      "step": "search Exact",
+      "command": "itpay services run itpay-rail-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"
     },
-    "itpay-rail-smart": {
-      "required": {
-        "origin": "Fullest known departure location: city, district, area, or address is all acceptable.",
-        "destination": "Fullest known arrival location, same rule as origin.",
-        "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date."
-      },
-      "optional": {
-        "origin_city": "Departure city hint that helps location resolution.",
-        "destination_city": "Arrival city hint.",
-        "origin_location": "Known coordinate object (AMap GCJ-02).",
-        "destination_location": "Destination coordinate object.",
-        "depart_after": "Do not depart before this time.",
-        "arrive_before": "Do not arrive after this time.",
-        "priority": "One of balanced | fastest | cheapest | safest | flexible.",
-        "max_transfers": "Integer 0-2, allowed transfer count.",
-        "passengers": "Integer 1-5, default 1: adult passenger count reflected in per-leg inventory and amounts. NOT identity records.",
-        "preference_context": "Bounded object, max 4 string-valued keys (<=200 chars each) of soft ranking preferences, e.g. {\"no_taxi\":\"true\"}. Validated allowlist; never carry passenger identity."
-      },
-      "example": {
-        "origin": "中山古镇",
-        "destination": "广州南",
-        "travel_date": "2026-09-19",
-        "priority": "fastest"
-      }
+    {
+      "step": "search Smart",
+      "command": "itpay services run itpay-rail-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."
     },
-    "itpay-rail-booking": {
-      "preferred": {
-        "passengers": "Integer 1-5: number of passengers, NOT passenger identity records.",
-        "selection": {
-          "token": "The booking_offer.selection_token carried on the chosen result item.",
-          "seat_type": "Use the seat_type code shown with seat_name in the returned booking_template.seat_choices (e.g. O = 二等座); never submit the display name as the code. Omit this optional field when the returned offer has no code; never guess."
-        }
+    {
+      "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 per-leg templates within each ticket_plan_ref.",
+      "next": "If current eligible options and full connections satisfy the request, answer or continue under delegation. Separate leg purchases have no joint guarantee."
+    },
+    {
+      "step": "book",
+      "command": "itpay services run itpay-rail-booking --input-json <booking-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 human 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": "do not infer paid or issued from the handoff"
+    },
+    {
+      "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 the human only if a genuine ambiguity changes the destination or constraints.",
+    "Before the first railway query, leave a 2–4 line route brief in the conversation, or write route-brief.txt using an existing local task-note tool: endpoint understanding and constraints; 1–2 plausible station pairs or transfer directions; knowledge or actually read source; Exact/Smart choice and facts still unverified. Choose one location for the brief, do not ask for permission to plan, and never write it after querying.",
+    "With sufficient knowledge, propose a credible route directly and label remembered trains as unverified. With insufficient knowledge, first attempt a targeted lookup using the full places and date on the most relevant source below; use another source only if needed. Do not visit all three routinely or research every possible route before ItPay. Make one short lookup, usually 1–2 relevant pages; enter ItPay as soon as you can choose a station pair or transfer direction. Do not collect complete external timetables or all prices. Typically 30–60 seconds to the first useful query is an observation goal, not a hard network timeout or consent gate.",
+    "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 browsing is unavailable, blocked by login or captcha, stop that lookup without repeated troubleshooting or installing a browser. State which route facts remain unverified. Clear endpoints may go to Smart for combinations, or a credible double-station hypothesis to Exact; unresolved place meaning still needs human clarification. Do not guess a station from an inaccessible website.",
+    "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."
+  ],
+  "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": "Broad station comparison, transfers, uncertain places, or a concrete address with ground connections. Each endpoint independently means an administrative area, a specific place, or a verified railway station. 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-exact --input-json <query-file> --json",
+      "example": {
+        "origin": "<已核实出发站>",
+        "destination": "<已核实到达站>",
+        "travel_date": "<用户出行日期 YYYY-MM-DD>"
       },
-      "explicit_legs": {
-        "passengers": "Integer 1-5.",
-        "legs": "Array with exactly ONE leg: from_station_code, to_station_code, travel_date, train_code, departure_time (HH:MM), arrival_time (HH:MM), arrival_days (int 0-7), seat_type. The public review accepts a single leg; only use when no booking_offer is available, and never guess these values. For v2 separate_legs_only journeys, book one leg at a time via that leg's own booking_offer — never a multi-leg basket."
+      "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-smart --input-json <query-file> --json",
+      "example": {
+        "endpoints": {
+          "origin": {
+            "kind": "area",
+            "text": "<用户出发市县镇完整名称>"
+          },
+          "destination": {
+            "kind": "station",
+            "text": "<已核实到达站名>"
+          }
+        },
+        "travel_date": "<用户出行日期 YYYY-MM-DD>"
       },
-      "boundary": "Identity fields (names, ID numbers, phones) never belong in this input; they are collected on the protected checkout page."
-    }
+      "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; omit kind when unresolved. 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. 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."
   },
-  "selection_flow": [
-    "Exact results carry per-train candidates; smart results carry journeys. Bookable options carry booking_offer with a server-signed selection_token.",
-    "The token binds the stored result snapshot and the chosen option. Submit it with passengers (and the exact seat_type code from booking_template.seat_choices when the user picked a class); the server derives the authoritative legs and re-quotes live. Do NOT hand-build legs JSON from the visible result. If only the code spelling is corrected and the confirmed train, actual seat class, passenger count, price, and terms remain identical, reuse the buyer's explicit approval. Material draft changes or missing approval require confirmation.",
-    "A historical selection identifies the original choice; booking refreshes current fare and inventory. A foreign buyer is rejected. Never guess token contents or hand-build legs as recovery.",
-    "Repeating the same selection restores the same booking execution instead of creating a second one.",
-    "v2 single-leg cards carry an opaque rsel_ selection_token bound to the buyer and saved journey/offer. The original selection can enter booking after its search window expires; live quote determines whether that exact train and seat remain purchasable.",
-    "v2 separate_legs_only journeys never carry a whole-journey token: open the journey detail, pick one leg, and use that leg's owner-issued booking_offer; each leg is quoted and confirmed independently with no joint guarantee."
-  ],
-  "trial_and_login": {
-    "policy": "itpay-rail-exact and itpay-rail-smart each allow 2 anonymous queries per enrolled device lineage — independent counters, not a shared pool of 4.",
-    "login_required": "Trial for that service is exhausted. The query is paused BEFORE provider calls; the execution keeps its input. Offer itpay auth login; after binding, resume the SAME execution with services run --execution <id> (no input file). Do not start a new execution, do not make the user re-describe the trip, and do not burn the other service's quota to dodge the gate.",
-    "rate_limited": "Registered accounts have no cumulative search cap but normal per-minute limits apply; wait retry_after_ms and resume the same execution.",
-    "fourth_result": "The 4th result is delivered first; only the next new query requires authorization.",
-    "purchase_after_trial": "Selecting a saved option and buying it does not consume search quota and works even when trial is exhausted."
+  "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": "Use the returned booking_template selection token, passenger count and a seat_type code matched to seat_name (for example O may mean 二等座 in that returned offer). Never send the display name as the code or guess a code for another train. Once the desired authorized seat and valid credentials are present, continue; read further seat pages only to find another needed class.",
+    "command": "itpay services run itpay-rail-booking --input-json <booking-file> --json",
+    "single_leg": "Booking accepts one leg. Smart transfer options require separate leg purchases without a joint seat or connection guarantee; do not send a multi-leg basket.",
+    "identity": "Passenger name, ID and phone are entered on the official protected checkout page, not in query or booking JSON."
   },
-  "flow": [
-    "For a known railway service, submit input directly with services run <service> --input-json <file> --json; keep the returned execution for follow-ups.",
-    "itpay-rail-smart may stop at a location confirmation step; show the candidate places to the buyer, then continue the same execution after the human confirms.",
-    "After the buyer explicitly picks a train/seat, run itpay-rail-booking with the selection token (preferred) or explicit legs. The execution then pauses at the booking review (workflow:confirm_booking): services next returns booking_review_required with human_action.context.review carrying draft_revision, legs, seat_options and notice_version.",
-    "Whether or not the query was free, the answer is the same shape under compare: one preferred option, at most two meaningful alternatives, the key trade-offs — then stop and wait for the buyer. Do not stack more options or chain into purchase.",
-    "Collect the review input and submit it with services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json. Required fields: draft_revision (exact server value), passengers, seat_type, seat_preferences (one entry per passenger_index 0..n-1, values limited to that leg's seat_options), party_preference, fallback=automatic_assignment, notice_version, accept_non_guaranteed=true. Only after an accepted review does the server quote and offer checkout.",
-    "The booking execution reaches a protected checkout: passenger identity data is entered by the human on that page, never through the CLI. Account authentication may happen inside checkout — do not force a separate auth login first (Path B).",
-    "Payment success does not mean the ticket is issued. Issuance is asynchronous; keep reading the same execution with services next.",
-    "If seat details are still syncing after issuance, advise the buyer to verify the itinerary on 12306 instead of repeating the query."
-  ],
-  "failure_handling": {
-    "failed_step": "The CLI reports failed_step and failed_step_meaning in the result when a workflow fails.",
-    "geo": "Location resolution failed: check origin/destination are real place names, or attach origin_city/coordinate hints, then start a NEW execution (a failed execution is terminal).",
-    "search": "Supplier query failed: most commonly a wrong field name (must be travel_date) or a nonexistent station name; recheck input against this doc.",
-    "catalog_or_recommend": "Location resolved but no feasible trains: change the date or stations.",
-    "login_required_is_not_failure": "login_required / rate_limited pause the execution; they are NOT failures and never justify a replacement execution.",
-    "general_rule": "Never replay a failed execution and never guess different field names; correct the input and start a new execution of the same service.",
-    "booking_review_changed": "The submitted draft_revision is stale: re-read services next for the current review projection and resubmit the full input; do not bump the revision yourself.",
-    "plan_conflict": "409: the action_request_id/expected_query_revision/snapshot_id no longer matches owner state. Re-read services next and reuse the fresh action handle; an identical replay of an accepted action still returns its original acceptance.",
-    "stale_cursor": "The paging cursor was minted against an older snapshot; restart paging from the current snapshot_id.",
-    "snapshot_not_found": "Unknown or superseded snapshot id; read the current projection for the latest snapshot.",
-    "journey_not_in_snapshot": "The rj_ reference is not inside the saved snapshot; pick a journey from the current page/projection.",
-    "plan_expired": "The 15-minute plan lifecycle ended: expansion stopped and the snapshot is read-only evidence; start a new execution for a fresh search. In-flight checkout/payment is unaffected.",
-    "action_request_invalid": "The action payload failed validation (unknown patch fields, malformed handle); copy the command from available_actions instead of composing it.",
-    "selection_stale": "The rsel_ token no longer matches the current snapshot/policy; re-read the journey and take the fresh booking_offer."
+  "review_and_checkout": {
+    "review": "Read the returned draft facts, current required action fields and actual notice; compare with the conversation. Ask only missing choices or terms, reuse known party/seat and unchanged explicit consent. No seat-letter preference means automatic allocation; only show seat letters when requested. Submit current notice_version/draft_revision with actor-type human only after real consent; delegation is not terms consent.",
+    "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.",
+    "checkout": "Show the returned safe itinerary summary and official link/QR supported by the actual host. Do not repeat a price approval already valid for unchanged terms. The human completes identity and payment on that page. Handoff is not payment or ticket issuance."
   },
-  "seat_preferences": {
-    "meaning": "A buyer's seat-letter preference may be planned per leg before payment. The plan is submitted to the supplier when encodable; unsupported combinations fall back to automatic assignment.",
-    "letters": "Evidence-backed letters only: O=ABCDF (second class), M=ACDF (first class), 9=ACF (business class). Other layouts auto-assign.",
-    "boundary": "Never claim a preference was fulfilled before supplier confirmation; check the issued seat in the order/status output.",
-    "review_contract": "Submitted inside the confirm_booking action via --input-json (nested JSON; --input key=value cannot express it and must not be combined with it). One preference per passenger slot, passenger_index 0-based. draft_revision must equal the server projection; a stale revision returns booking_review_changed — re-read services next and resubmit, never increment locally.",
-    "revision": "While payment has not started, the same execution accepts a revised review: resubmit confirm_booking with the new draft_revision; the old unpaid quote/checkout is retired and re-quoted. After a payment attempt the review is closed — never create a replacement purchase."
+  "continue_and_aftercare": {
+    "same_execution": "Wait and read the same query or booking execution. Once an order exists, use itpay order <order_id> --json for its authoritative state. Paid can still be issuing; report issued only when confirmed.",
+    "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": "Read itpay docs show orders-refunds --json and the current order policy. Railway supplier cancellation/return and platform refund have separate facts; a refund request is not completed railway return."
   },
-  "agent_rules": [
-    "Pick the service by the buyer's input precision: known stations or a few credible station-pair hypotheses → itpay-rail-exact; broader fuzzy locations → itpay-rail-smart; explicit purchase intent after a selection → itpay-rail-booking.",
-    "Choose the goal first (see goals): compare presents one preferred option plus at most two meaningful alternatives then waits; prepare_checkout selects under the buyer's rules and continues to the official confirmation entry without re-asking.",
-    "Never invent input field names. If the guidance block or this doc does not list a field, do not send it.",
-    "Never ask the buyer for passenger names, ID numbers, or phone numbers in chat; those are collected only on the protected checkout page.",
-    "Never reconstruct provider-shaped legs JSON when a booking_offer.selection_token is available; submit the token plus passengers.",
-    "Seat preferences are requests, not guarantees: always repeat the notice that automatic assignment remains possible, and never claim a specific seat before the issued order shows it.",
-    "Take draft_revision only from the current services next review projection; on booking_review_changed re-read instead of retrying the stale value.",
-    "login_required and rate_limited are pauses, not failures: resume the same execution, never spawn a replacement.",
-    "Do not repeat or replay a failed execution; correct the input and start a new one.",
-    "Do not claim payment equals ticket issuance; issuance is asynchronous and confirmed only by the issued seat status.",
-    "For v2 plans, act only on available_actions[] from the current projection: run the exact command the backend returned, then re-read; never invent action types, request ids, revisions or fields.",
-    "expand_search is the only intent that may spend provider budget; refine_preferences re-ranks saved data first and does not by itself expand.",
-    "A paused/expired/complete plan is still readable and selectable from its saved snapshot; never start a replacement execution to keep polling.",
-    "stop_search pauses scheduling but keeps saved data and existing selections; booking stays reachable only through the allowed actions the owner reports.",
-    "When since_snapshot returns result_not_updated, keep the previous snapshot and still surface the latest expansion status/end reason to the user."
-  ],
-  "human_language": {
-    "prefer": [
-      "车次",
-      "出发站",
-      "到达站",
-      "出行日期",
-      "座位",
-      "余票",
-      "出票中",
-      "已出票",
-      "登录后继续免费查询"
-    ],
-    "avoid": [
-      "workflow",
-      "execution",
-      "provider",
-      "seat_source",
-      "candidate_id",
-      "token",
-      "quota"
-    ]
+  "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": "Use the CLI returned device repair-lock recovery only for a lock proven stale; preserve active owners and identity.",
+    "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.",
+    "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."
   },
   "search_terms": [
     "rail",
@@ -173,32 +153,6 @@
     "booking",
     "rail-booking"
   ],
-  "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": "The order read exposes masked per-leg notification entries (keys: issued, details_pending, seat_ready) with channel, status and masked recipient — never raw numbers.",
-    "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."
-  },
-  "progressive_v2": {
-    "capability": "New CLI declares client_context.features=[\"rail.progressive.v2\"] at service start. It is a response-format declaration only; quota, service version and provider credentials stay server-decided. Old clients keep the legacy projection; never create a second execution to probe.",
-    "read_model": "While the plan workflow is active, services next carries rail_planning: schema_version, plan_id (jp_), query_revision, snapshot_id (rps_), readiness, expansion {status, reason, poll_after_ms, new_results_guaranteed}, coverage, budgets, recommendation + up to 4 alternatives (journey cards rj_), available_actions with concrete commands, result_item_id.",
-    "expansion_states": "queued/running: automatic work remains; paused: batch sufficient or auto window ended, expand only on explicit intent; complete/cancelled: budget or frontier exhausted — snapshot stays read-only, expand action absent; failed: reason visible after a published snapshot, readiness stays ready; expired: 15-minute lifecycle end — evidence read-only, in-flight purchase unaffected.",
-    "reads": "services next --since-snapshot <rps_…> suppresses the journey payload but always returns the latest expansion status. read-result gains --snapshot, --journey <rj_…> and an opaque --cursor bound to snapshot+filter+sort (stale -> stale_cursor). Reads never call the provider, never extend lifecycle, never invoke the model.",
-    "actions": "Three allowlisted planning actions ride POST actions with action_type workflow:expand_search | workflow:refine_preferences | workflow:stop_search. input_snapshot carries server-issued action_request_id plus expected_query_revision and snapshot_id; refine adds a validated preference_patch. Always copy the concrete command from available_actions[]; never assemble fields. Same id + same payload returns the stored acceptance; same id + different payload -> plan_conflict.",
-    "journey_card": "Cards carry station names, train codes, dated times, transfer/same-run notes, observed_at price time and handles. representative_offer.ticket_offers[] lists one purchasable segment per entry (leg_index, offer_id, service_ref, station codes, travel_date, seat_type, passengers, integer-minor amounts); per-item amounts sum to the total. rides[] (ridden legs) and ticket_offers[] (purchasable segments) are different lists — never infer transfers or fees from array lengths.",
-    "selection": "booking_support=single_leg cards carry booking_offer {service_id: itpay-rail-booking, selection_token: rsel_…}; submit it to itpay-rail-booking with passengers as today. separate_legs_only cards expose no whole-journey token — each leg is quoted and confirmed separately via its protected detail; never assemble legs JSON yourself. booking_support=none has no selection action.",
-    "honesty": "Coverage is bounded: repeat searched_scope/notices verbatim, never claim national-exhaustive search, and surface missing prices as unknown — never 0."
-  },
-  "goals": {
-    "compare": "Buyer wants to see options and keeps the final choice. Present one preferred option plus at most two meaningful alternatives, then wait. A fully-specified query with no purchase delegation stays compare.",
-    "prepare_checkout": "Buyer named the product, or delegated selection under explicit rules and asked for the purchase entry. Select under those rules, explain the match, and continue to the official confirmation/payment entry without re-asking '要不要买'. Clear delegation missing only the date asks for the date alone.",
-    "boundaries": [
-      "Decide locally from the whole conversation (negations, conditions, references, latest withdrawal); no trigger-word lists, no regex, no field-completeness classifier, no mode flag, never ask the human to name a mode.",
-      "Explicit buyer rules outrank default recommendations; missing facts are unknown, never assumed satisfied.",
-      "compare must not continue into selection; prepare_checkout must not silently downgrade to waiting.",
-      "A pending/login/error state is never new intent; withdrawal updates the goal but never rewrites a completed payment.",
-      "Neither goal authorizes payment or skips confirmation: payment, terms and passenger identity stay behind their own gates."
-    ],
-    "recipe": "The Skill first screen describes query→booking→review→checkout. Load rail-fast-checkout only when the current response leaves a stage detail unclear."
-  }
+  "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."
 }