@itpay/cli 2.1.34 → 2.1.40

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

@@ -10,6 +10,11 @@
     "The agent needs to confirm its stable runtime identity and default output Host."
   ],
   "commands": [
+    {
+      "intent": "read this installed package Skill before network checks",
+      "command": "itpay skill show itpay --json",
+      "success_signal": "complete packaged Skill is read; the same version need not be read twice"
+    },
     {
       "intent": "list supported Agent Types",
       "command": "itpay install --json",
@@ -32,12 +37,12 @@
     }
   ],
   "agent_rules": [
-    "For first setup or a runtime change, identify the real Agent Type once, run itpay install <agent_type> --json yourself, and follow its setup continuation until the packaged Skill is loaded. Ordinary service requests start from the Skill's service command, without repeating install or readyz.",
+    "For first setup, read the complete Skill from this installed package before network checks. Select the actual Agent Type once through install and retain the same launcher and Backend. Do not reread the same version Skill, repeat initialization for ordinary tasks, or start login or business to prove setup.",
     "After setup, tell the human only that ItPay is ready; never ask them to run setup commands or explain technical setup steps.",
     "Use the CLI distribution already provided by the current npm package, Skill, or plugin; update only through that distribution's own instructions.",
     "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL the configured official test Backend only when explicitly requested; follow the CLI allowlist.",
-    "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update recovery returned by the CLI; never replace its version with latest.",
-    "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
+    "If Backend compatibility cannot be verified, stop this round. minimum_cli_version is a protocol floor, not a verified matching artifact. Ask the maintainer for the matching distribution; do not guess a version or downgrade.",
+    "Only install a replacement when its exact artifact and Backend contract have been verified; then reread that package Skill. Never change Agent Type or Device identity to recover compatibility.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, doubao-work, kimi-code, or openclaw.",
     "For compatibility, a global --agent-type codex declaration is normalized immediately to codex-desktop; all registration, output, and returned commands use codex-desktop. Never generate the alias, and do not use codex as an install target.",
     "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai, sandbox.itpay.ai and dev.itpay.ai.",

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

@@ -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",
@@ -45,9 +50,12 @@
     "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 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.",
+    "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.",
@@ -56,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."
@@ -99,5 +107,6 @@
     "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

@@ -66,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/quickstart.json

@@ -25,7 +25,7 @@
     "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.",
+    "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."
   },
@@ -107,5 +107,6 @@
     "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."
+  "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

@@ -11,18 +11,20 @@
   "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."
+    "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-exact --input-json <query-file> --json",
+      "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-smart --input-json <query-file> --json",
+      "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"
     },
@@ -40,7 +42,7 @@
     },
     {
       "step": "book",
-      "command": "itpay services run itpay-rail-booking --input-json <booking-file> --json",
+      "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"
     },
@@ -48,7 +50,7 @@
       "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"
+      "next": "submit the returned actor-type agent template only after genuine consent; reuse an unchanged explicit consent for code-only correction"
     },
     {
       "step": "checkout",
@@ -81,39 +83,44 @@
   },
   "input_and_expected_result": {
     "exact": {
-      "command": "itpay services run itpay-rail-exact --input-json <query-file> --json",
+      "command": "itpay services run itpay-rail --operation query_exact --input-json <query-file> --json",
       "example": {
-        "origin": "<已核实出发站>",
-        "destination": "<已核实到达站>",
-        "travel_date": "<用户出行日期 YYYY-MM-DD>"
+        "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-smart --input-json <query-file> --json",
+      "command": "itpay services run itpay-rail --operation query_smart --input-json <query-file> --json",
       "example": {
-        "endpoints": {
-          "origin": {
-            "kind": "area",
-            "text": "<用户出发市县镇完整名称>"
+        "input": {
+          "endpoints": {
+            "origin": {
+              "kind": "area",
+              "text": "<用户出发市县镇完整名称>"
+            },
+            "destination": {
+              "kind": "station",
+              "text": "<已核实到达站名>"
+            }
           },
-          "destination": {
-            "kind": "station",
-            "text": "<已核实到达站名>"
-          }
-        },
-        "travel_date": "<用户出行日期 YYYY-MM-DD>"
+          "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."
+    "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-booking --input-json <booking-file> --json",
+    "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."
   },
@@ -125,7 +132,7 @@
   "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": "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."
+    "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.",
@@ -158,5 +165,12 @@
     "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."
+  "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/service-feedback.json

@@ -7,7 +7,7 @@
   "purpose": "Finish the original order outcome first, then persist safe process context and any explicit human rating or comment without exposing commands or internal identifiers.",
   "when_to_use": [
     "The human asks to rate a service, leave feedback, report a blocker, or says how many stars the experience deserves.",
-    "A paid result has actually been delivered and the CLI instruction requires a safe Agent postmortem.",
+    "A paid result has actually been delivered and the CLI instruction offers an optional safe Agent postmortem.",
     "A paid service failed and its order, delivery, and refund path have already been explained or recovered."
   ],
   "intent_routing": {
@@ -27,7 +27,7 @@
   "agent_rules": [
     "A rating is optional. Normalize an explicit 1-5 rating to an integer; sentiment never implies a score. Preserve an explicit human comment without inventing one.",
     "Run every command yourself. Speak to the human only about the service, their rating, whether feedback was recorded, and any original order rights.",
-    "Submit one baseline Agent postmortem after the outcome. Do not pressure the human for a score; an empty repeat is a no-op, while a later explicit rating or comment updates the same feedback.",
+    "Optionally submit one baseline Agent postmortem after presenting the outcome; it never blocks delivery. Do not pressure the human for a score; an empty repeat is a no-op, while a later explicit rating or comment updates the same feedback.",
     "Use only the human's own words plus safe order context. Never upload the conversation, prompt, diagnostics, contact details, tokens, internal identities, provider responses, or purchased payload.",
     "A successful feedback submission does not promise a reply, resolution, refund, or order change.",
     "If submission outcome is unknown, stop and explain that recording could not be confirmed; never retry automatically.",

package/docs/cli-reference/commands/aftercare.md

@@ -0,0 +1,15 @@
+# `itpay aftercare`
+
+Railway manual refund/change intake; ordinary service refunds retain `itpay refund`.
+
+```sh
+itpay aftercare list --order <order_id> --json
+itpay aftercare create --order <order_id> --input-json <file> --json
+itpay aftercare get <case_id> --json
+itpay aftercare respond <case_id> --input-json <file> --json
+itpay aftercare cancel <case_id> --input-json <file> --json
+```
+
+`list` returns the complete current JSON templates, original safe journey and available ticket targets. Indices start at zero. Use user-selected targets; do not guess supplier IDs or money. Only real scope consent sets `user_confirmed_scope=true`.
+
+`get` shows original immutable request, history, supplier facts and separate money state. Pending/manual intake does not authorize financial execution. A current change proposal must be explicitly accepted using its returned revision; the original purchase consent is insufficient. Fees are coordinated manually, with no automatic payment link. Cancellation cannot undo supplier or money operations already started. Platform content locks remain; safe remaining-ticket status is a separate authorized read.

package/docs/cli-reference/commands/cart/add.md

@@ -2,6 +2,10 @@
 
 > **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
+## 服务报价的批准边界
+
+服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
+
 ## 范围与意义
 
 把一个已发布 Catalog offer 或一个已准备的 Service Quote 加入 canonical server Cart。Catalog 服务行先进入 `services next`；Quote 行已经锁定输入和价格，可以与其他独立 Execution 的 Quote 一起结算。

package/docs/cli-reference/commands/cart/next.md

@@ -2,6 +2,10 @@
 
 > **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
+## 服务报价的批准边界
+
+服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
+
 ## 范围与意义
 
 读取当前 canonical cart 对应的唯一首选动作。它不修改 cart。

package/docs/cli-reference/commands/readyz.md

@@ -45,7 +45,7 @@ itpay readyz [--json]
 
 ## 异常处理
 
-已收到 Backend 不可用响应等非传输异常时返回 `backend_unavailable`。尚未收到完整 HTTP 响应的临时传输失败使用 conventions 中对应的稳定 `network_*` 错误码；`readyz` 是 GET，按全局安全传输合同最多自动重试两次。两类错误都要求等待当前官方 Backend 恢复后重试同一完整命令，不得在失败时切换环境或继续下单。
+已收到 Backend 不可用响应等非传输异常时返回 `backend_unavailable`。尚未收到完整 HTTP 响应的临时传输失败使用 conventions 中对应的稳定 `network_*` 错误码；`readyz` 是 GET，按全局安全传输合同最多自动重试两次。有限尝试结束后本轮检查未完成，next=null、recovery=[]；网络恢复后可以重新检查，不得在失败时切换环境或继续下单。
 
 非官方 URL 返回 `backend_override_forbidden`，且不提供自动 recovery：
 
@@ -62,55 +62,7 @@ itpay readyz [--json]
 }
 ```
 
-CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的分发专属恢复动作。npm CLI 示例：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "backend_contract_incompatible",
-    "message": "CLI 2.0.15 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.16, maximum major 2)"
-  },
-  "result": {
-    "current_cli_version": "2.0.15",
-    "required_cli_version": "2.0.16"
-  },
-  "instruction": "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "npm install -g @itpay/cli@2.0.16",
-      "reason": "安装 Backend 指定的兼容 CLI 版本"
-    }
-  ]
-}
-```
-
-OpenClaw bundle 的同一错误改为：
-
-```json
-{
-  "status": "error",
-  "error": {
-    "code": "backend_contract_incompatible",
-    "message": "<same compatibility fact>"
-  },
-  "result": {
-    "current_cli_version": "2.0.15",
-    "required_cli_version": "2.0.16"
-  },
-  "instruction": "当前 OpenClaw Skill bundle 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，更新 Skill 后启动新会话并确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要运行 npm、切换 Agent Type 或删除 Device 身份。",
-  "next": null,
-  "recovery": [
-    {
-      "command": "openclaw skills update itpay",
-      "reason": "更新包含 Backend 指定 CLI 版本的 ItPay Skill bundle"
-    }
-  ]
-}
-```
-
-Kimi bundle 使用其 plugin 更新入口，不返回 npm 命令。只允许使用 Backend 返回的 `minimum_cli_version` 生成精确版本要求；兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
+业务命令取得兼容性合同但不匹配时，返回 `backend_contract_incompatible`；readyz 本身只证明存活。输出保留 `current_cli_version`、`current_api_contract_revision`、`platform_api_contract_revision`、`minimum_cli_version`、`maximum_cli_major`。minimum 是协议门槛，不是推荐制品。所有分发渠道均停止本轮、next=null、recovery=[]，由维护方提供已核验的配套制品；不要猜版本、降级或改变身份。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/services/checkout.md

@@ -2,6 +2,10 @@
 
 > **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
+## 服务报价的批准边界
+
+服务支持的 Quote/Cart/Checkout 共用服务端范围校验。缺少有效价格批准时返回完整 `approve_purchase` 模板，默认 `user_approved:false`；Agent 只在真实会话已同意当前主体、内容、价格或预算和条款时提交 true。选择候选或完成席别 review 不代替价格批准。同条件有效批准复用，已有 Checkout/未知付款先恢复原单，不补事后批准或创建替代订单。
+
 ## 范围与意义
 
 为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。

package/docs/cli-reference/commands/services/next.md

@@ -242,44 +242,17 @@ itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapsh
 }
 ```
 
-用户明确选择某班次/席别并要求购买时，用该 token 开启购票执行：
+有购买委托时，读取所选完整行程详情，使用其返回的 `itpay-rail --operation prepare_purchase` 完整模板；保留 continuation 的原 execution/snapshot 与完整 selections。上面的 booking_offer 是历史兼容事实，不将它改造成新公共承接或手拼多腿。
 
-```bash
-itpay services run itpay-rail-booking --input-json booking.json --json
-# booking.json: {"passengers": 1, "selection": {"token": "<selection_token>", "seat_type": "O"}}
-```
-
-`booking_offer` 只是受条件约束的可选承接：查询完成本身已满足查询目标，不自动购买。过期 token 不会因重读保存结果而恢复；按当前 owner 错误与用户原请求取得新的实时选择证据，不手工拼装 `legs` 绕过失效凭据。
-
-## 订票确认（booking review）
-
-`itpay-rail-booking` 在报价前停在 `workflow:confirm_booking` 人工确认节点。`services next` 返回 `booking_review_required`，`human_action.context.review` 携带服务端投影：`draft_revision`、`legs`（含可编码的 `seat_options`）、`notice_version` 等。乘客身份信息永不在此投影，也不经 CLI 提交。
-
-```json
-{
-  "status": "booking_review_required",
-  "result": {
-    "service_execution_id": "<id>",
-    "service_id": "itpay-rail-booking",
-    "human_action": {
-      "action_type": "workflow:confirm_booking",
-      "context": { "review": { "draft_revision": 1, "legs": [], "seat_options": {} } }
-    },
-    "required_fields": ["draft_revision", "passengers", "seat_type", "seat_preferences", "party_preference", "fallback", "notice_version", "accept_non_guaranteed"]
-  },
-  "instruction": "向用户展示行程与可选席别/座位偏好词表，并明确告知：座位偏好仅为请求、不保证分配。收集后经 --input-json 提交完整 JSON；draft_revision 以服务端当前值为准。",
-  "next": null,
-  "interaction": { "input_template": { "command": "itpay services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json", "executable": false } },
-  "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取当前 draft_revision 后重试" }]
-}
-```
+## 整程订票确认与价格批准
 
-规则：
+当前 `booking_review_required` 返回完整整程 review、每段席别代码/名称、人数、偏好词表、notice_version 与 draft_revision。直接读写返回的完整 JSON，不需要解析脚本；模板的 accept_non_guaranteed 默认 false。只补用户尚未明确同意的实质内容；仅修席别代码而车次、实际席别、人数、价格、条款未变时沿用原真实确认。
 
-- `seat_preferences` 逐乘客一条，`passenger_index` 从 0 起、人数 1–5、取值限该席别 `seat_options`；`party_preference`、`fallback=automatic_assignment`、`notice_version`、`accept_non_guaranteed=true` 全部必填。
-- `draft_revision` 必须等于投影值；服务端返回 `booking_review_changed` 时重新 `services next` 读取后重试，不得自行递增或重放旧 revision。
-- 付款暂停且 review 仍开放时，`next` 指向 Checkout 恢复，`recovery` 附带修订命令（`services action … confirm_booking --input-json`）——修订回到同一执行重新报价，不产生第二笔订单或付款。
-- 支付已在途/完成后 review 关闭，修订被拒绝；按返回的同一订单状态继续，不得新建执行。
+- 每段保留相连行程、对应席别、每位乘客偏好；不要恢复固定单腿 scalar 模板。
+- `booking_review_changed` 重新读取当前服务端 revision，不自行递增、不重放旧 revision。
+- 候选/条款确认不等于价格批准；实时报价后使用完整有范围 approve_purchase 模板，仅真实匹配批准允许 true。
+- 未付且允许修改时修订同一 booking 重新报价；支付已在途/完成、结果未知或退款锁定时按原单读取，不新建替代购买。
+- 乘客身份、电话、邮箱修改只在保护页完成，不在聊天或 workflow 输入收集。
 
 ## 异常处理
 

package/docs/cli-reference/commands/services/quote.md

@@ -10,7 +10,7 @@
 
 **上游：** 用户明确要求合并多个独立 Execution，且每个 Execution 的 Arazzo workflow 当前都允许 `prepare_quote`。
 
-**下游：** `cart add --quote`。多个独立 Execution 的 Quote 可以加入同一 Cart。
+**下游：** 读取当前服务器返回的有范围 `approve_purchase` 完整 JSON，默认 false；仅已有真实匹配批准时置 true 并记录。批准成功后再 `cart add --quote`，多个已批准 Quote 可加入同一 Cart。候选选择不等于价格批准。
 
 ## 语法与参数
 

package/docs/cli-reference/commands/services/run.md

@@ -124,23 +124,19 @@ itpay services run <service_id> --execution <execution_id> --json
 
 限流不是收费、不是试用耗尽、不需要重新登录。等待中不得重复扣试用或发起新的供应商请求。
 
-## 已选车次的购票输入（selection）
+## 公开操作与完整购买承接
 
-对 `itpay-rail-booking`，输入支持两种等价方式。优先使用查询结果里服务端签发的购买承接：
+铁路是一项 `itpay-rail` 服务，`query_exact`、`query_smart`、`prepare_purchase` 是固定定义内的操作。查询输入按返回模板填写 `{ "input": { ... } }`；不要把内部实现当三项公开服务重新发现。
 
-```json
-{
-  "passengers": 1,
-  "selection": {
-    "token": "<查询结果项中的 booking_offer.selection_token>",
-    "seat_type": "O"
-  }
-}
+```sh
+itpay services run itpay-rail --operation query_exact --input-json query.json --json
 ```
 
-`selection.token` 绑定一次具体查询结果快照与其中的班次/方案；服务端校验归属、快照版本、时效后推导权威 `legs` 并实时核价。Agent 只提交用户选定的承接、`seat_type`（必要时）与乘客人数，**绝不手工拼装 `legs`、站码、时刻或供应商形状**。显式 `legs` 输入仍然有效，字段即购票服务发布的 `input_schema`（`passengers` 为 1–5 整数人数，不是乘客身份数组）。
+所选行程详情返回完整准备购买模板，含 `continuation.service_execution_id`、`continuation.snapshot_id` 和 `input.selections`。原样保留当前 owner、快照、完整段数、席别代码和人数，写入文件并执行其命令。不要手拼腿、站码、时刻、付款批准或缺失的 snapshot。一次整程对应一个 booking、一个官方付款入口，各段分别出票。
+
+旧 `itpay-rail-exact/smart/booking` ID 仅用于已有执行和历史模板的兼容恢复；新公共模板与旧凭据共用原购买去重。存在或未知购买先恢复，过期库存不等于能新建购买。
 
-相同 selection 重复提交恢复同一购票执行，不会重复核价或建单。
+候选选择和席别条款确认不等于价格批准。实时报价返回完整有范围的 `approve_purchase` JSON，默认 `user_approved:false`。仅已有真实、匹配价格/上限/条款/主体同意才改 true；内容未变可复用。付款与出票事实仍由后端及官方页确认。
 
 ## 终态和异常
 

package/docs/cli-reference/commands/services/start.md

@@ -4,7 +4,9 @@
 
 ## 范围与意义
 
-按 Catalog 中的 `service_id` 启动一次 Service Execution，并返回当前可执行的唯一首选动作。不会调用 Provider、创建 Checkout 或订单。
+公开 service_definition 入口只返回固定版本的服务总览与操作，未创建 execution、未调用 Provider。铁路总览指向 rail-booking：首次实际查询前理解端点并写短摘要。使用返回的操作模板执行 `services run --operation … --input-json <file>`。
+
+旧内部 service_id 仍兼容启动一次 Service Execution，并返回当前合法动作，不创建 Checkout 或订单。以下执行示例属于旧入口。
 
 **上游：** `catalog list` 或服务端明确要求新 execution。
 **下游：** `services invoke`、`action`、`checkout` 或 `next`。

package/docs/cli-reference/conventions.md

@@ -80,7 +80,7 @@ next: <one command>
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
 - WorkBuddy 需通过宿主的正常权限机制允许 CLI 持久化 `~/.itpay-v3`。若被拦截，报告受阻操作和宿主原因；不切换 Node、删除 identity 或猜测性处理活跃 lock。
 - `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
-- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供升级 recovery。npm 分发返回精确的 `npm install -g @itpay/cli@<version>`；平台 bundle 返回该平台的 Skill/plugin 更新动作。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
+- `backend_contract_incompatible` 返回当前 CLI/API、平台 API 与 minimum/major 事实；minimum 不是已验证的推荐包。无配套制品证据时 next=null、recovery=[]，停止本轮并请求维护方提供匹配制品，禁止猜版本、降级或变更身份。
 
 ## 网络传输失败与自动重试
 

package/docs/cli-reference/index.md

@@ -95,3 +95,5 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
 - [Sell: create, test and submit services](commands/sell.md)
 
 - [Run a published service](commands/services/run.md)
+
+- [`itpay aftercare`](commands/aftercare.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.34",
+  "version": "2.1.40",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "candidate-dev"
   },
   "keywords": [
     "itpay",
@@ -76,5 +76,6 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/itpay-ai/cli.git"
-  }
+  },
+  "gitHead": "c83c252d8799ae75f036c81738addd44026f191d"
 }