@itpay/cli 2.1.41 → 2.1.44

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

@@ -0,0 +1,152 @@
+# `itpay services run`
+
+## 范围与意义
+
+运行 Catalog 中已发布的通用 Buyer workflow。CLI 只提交服务声明要求的输入，并复用现有 Service Execution、Checkout、交付和退款命令；它不解释或执行 Seller 提供的任意命令文本。
+
+没有提供输入且未指定现有 execution 时，本命令创建一次 Execution，返回已发布的 JSON input schema，并要求 Agent 继续同一 Execution。已有 Execution 必须通过 `--execution` 恢复，不能创建替代 Execution。
+
+## 语法与参数
+
+```bash
+itpay services run <service_id>
+  [--input-json <file>]
+  [--execution <service_execution_id>]
+  [--timeout <seconds>]
+  [--host <host>]
+  [--target <target>]
+  [--json]
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `service_id` | Catalog 返回的服务 ID。恢复时必须与 Execution 所属服务一致。 |
+| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema；文件不超过 256 KiB。文件不可读、非合法 JSON 或顶层非 object 时在本地报 `workflow_input_invalid`，不发生网络写。 |
+| `--execution` | 恢复同一 Execution。不得用它切换服务或绕过原状态。 |
+| `--timeout` | 本次等待 workflow 状态变化的秒数，默认 120，范围 0–600；超时只返回当前状态。 |
+| `--host` / `--target` | Host 展示上下文，不是业务输入或 Buyer 身份。 |
+| `--json` | 输出稳定 JSON 信封。 |
+
+## 缺少输入
+
+```json
+{
+  "status": "input_required",
+  "result": {
+    "service_execution_id": "<execution_id>",
+    "service_id": "<service_id>",
+    "input_schema": { "type": "object", "required": ["<field>"] }
+  },
+  "instruction": "根据服务声明填写输入，然后继续同一服务执行。",
+  "next": {
+    "command": "itpay services run <service_id> --execution <execution_id> --input-json <file> --json",
+    "reason": "提交买家输入"
+  },
+  "recovery": []
+}
+```
+
+Agent 必须展示 schema 所需信息并等待用户提供真实输入；不得猜值，也不得为补输入创建新 Execution。
+
+铁路 Smart 新版 schema 使用 `endpoints.origin` / `endpoints.destination`，每端独立填写区域 `area`、具体地点 `place` 或准确车站 `station` 与原文 `text`；类型未确定可省略 `kind`。区域、地点和车站的九种组合共用这一输入。以当前执行返回的 `input_schema` 为准：旧 v4 执行仍使用旧字段；新版不可混填旧 `origin` / `destination`、坐标或锁站布尔值。地点/日期实质变更发起关联新查询，沿已保存结果返回的 `new_query_template` 填写真实变化；偏好、人数和期限在相同端点/日期下使用已有 `refine_preferences` 动作。
+
+## 执行与付款
+
+提供输入后，CLI 使用稳定 idempotency key 向同一 Execution 提交一次。`queued` 或 `running` 只轮询该 Execution。进入付款步骤时，CLI 调用现有 `services checkout`，返回其标准 `human_checkout_required` 输出和 Host handoff；不会实现第二套付款逻辑。
+
+付款完成后即使 CLI 已退出，Backend 仍继续该 workflow。再次运行：
+
+```bash
+itpay services run <service_id> --execution <execution_id> --json
+```
+
+只恢复当前状态。交付、Vault 授权和退款继续使用 `services next`、`services read-result`、`vault` 与 `refund` 的既有合同。
+
+## 免费试用额度与 `login_required`
+
+铁路查询类服务对未登录设备提供按服务独立计数的免费试用（`itpay-rail-exact` 与 `itpay-rail-smart` 各 2 次，互不共享）。额度在查询产生供应商副作用前由服务端原子记账：地点确认、内部多阶段、轮询和已保存结果分页不重复扣次；参数校验失败且未执行查询时不扣次。
+
+试用耗尽时，查询在供应商调用**之前**被暂停，Execution 不失败，已提交的输入服务端保留：
+
+```json
+{
+  "status": "login_required",
+  "result": {
+    "service_execution_id": "<execution_id>",
+    "service_id": "itpay-rail-exact",
+    "admission": "login_required",
+    "query_quota": [
+      { "service_id": "itpay-rail-exact", "used": 2, "limit": 2, "remaining": 0 },
+      { "service_id": "itpay-rail-smart", "used": 0, "limit": 2, "remaining": 2 }
+    ]
+  },
+  "instruction": "该服务的免费查询次数已用完（exact 2/2，smart 仍剩 2/2）。请用户在官方页面完成登录后继续免费查询；本次查询输入已保留，登录后恢复同一执行即可，不要新建执行或让用户重述行程。smart 额度属于另一类服务，不能拿它顶替 exact 查询。",
+  "next": {
+    "command": "itpay auth login --json",
+    "reason": "完成官方登录绑定后继续免费查询"
+  },
+  "recovery": [
+    {
+      "command": "itpay services run itpay-rail-exact --execution <execution_id> --json",
+      "when": "auth_bound",
+      "reason": "登录绑定完成后恢复同一查询执行"
+    }
+  ]
+}
+```
+
+`query_quota` 如实报告各查询服务自己的 `used`、`limit`、`remaining`。是否暂停只以本次服务端 `admission` 为准；已有结果先正常交付，不把另一服务的额度当作本次授权。
+
+登录绑定完成后，再次运行同一条 `services run <service> --execution <id> --json`（不带输入文件）：服务端重新读取当前设备绑定身份，被暂停的 Execution 从额度节点继续，不重放已成功的供应商调用，不要求重新输入。`failed`、`recovery_required` 或已完成付款的 Execution 不能以这种方式恢复。
+
+## `rate_limited`
+
+已注册账号查询不设累计次数上限，但受正常每分钟限流：
+
+```json
+{
+  "status": "rate_limited",
+  "result": {
+    "service_execution_id": "<execution_id>",
+    "service_id": "<service_id>",
+    "admission": "rate_limited",
+    "retry_after_ms": 42000
+  },
+  "instruction": "触发正常限流；等待后恢复同一执行，不要新建查询。",
+  "next": {
+    "command": "itpay services run <service_id> --execution <execution_id> --json",
+    "after_ms": 42000,
+    "reason": "限流窗口过后继续同一查询"
+  },
+  "recovery": []
+}
+```
+
+限流不是收费、不是试用耗尽、不需要重新登录。等待中不得重复扣试用或发起新的供应商请求。
+
+## 公开操作与完整购买承接
+
+铁路是一项 `itpay-rail` 服务，`query_exact`、`query_smart`、`prepare_purchase` 是固定定义内的操作。查询输入按返回模板填写 `{ "input": { ... } }`；不要把内部实现当三项公开服务重新发现。
+
+```sh
+itpay services run itpay-rail --operation query_exact --input-json query.json --json
+```
+
+所选行程详情返回完整准备购买模板，含 `continuation.service_execution_id`、`continuation.snapshot_id` 和 `input.selections`。原样保留当前 owner、快照、完整段数、席别代码和人数，写入文件并执行其命令。不要手拼腿、站码、时刻、付款批准或缺失的 snapshot。一次整程对应一个 booking、一个官方付款入口，各段分别出票。
+
+旧 `itpay-rail-exact/smart/booking` ID 仅用于已有执行和历史模板的兼容恢复；新公共模板与旧凭据共用原购买去重。存在或未知购买先恢复，过期库存不等于能新建购买。
+
+候选选择和席别条款确认不等于价格批准。实时报价返回完整有范围的 `approve_purchase` JSON，默认 `user_approved:false`。仅已有真实、匹配价格/上限/条款/主体同意才改 true；内容未变可复用。付款与出票事实仍由后端及官方页确认。
+
+## 终态和异常
+
+- 成功、付款、交付、授权、退款锁等状态使用既有命令的标准信封，不额外包装 Seller 专用格式。
+- 既有 Checkout、身份、兼容性和网络错误保持原错误码、instruction 与 recovery；`services run` 不得覆盖可执行的邮箱、登录、升级或状态恢复指令。
+- 如果创建 Execution 后未收到完整响应，返回 `workflow_start_outcome_unknown`，只允许先执行 `itpay services list --json` 查找刚创建的 Execution；不得直接重跑 `services run` 创建替代 Execution。
+- `recovery_required` 或 `failed` 返回当前 workflow step，`next: null`，并明确禁止重建 Execution 或重放结果未知的 Provider 请求。
+- service 不匹配、输入文件不是 JSON object、timeout 越界或 Backend 错误返回 `workflow_run_failed`。
+- `--timeout` 到期不是失败，只返回同一 Execution 当前可恢复状态。
+
+## Agent Type / Host
+
+所有 Local Agent Type 共享同一状态机和 JSON 事实。Host 只改变付款链接、二维码或附件的展示方式，不改变身份、价格、workflow 或交付权限。

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

@@ -1,10 +1,12 @@
 # `itpay services start`
 
-> **Product boundary:** `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 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.
 
 ## 范围与意义
 
-按 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`。
@@ -44,7 +46,7 @@ itpay --agent-type <agent_type> services start <service_id>
 }
 ```
 
-Start API 只提供免费额度上限，不提供当前剩余额度，因此本命令不得虚构 `remaining`。不得输出全部 capability DTO、contract version、graph ID、buyer/device ID 或重复 guidance。若服务不存在，recovery 为 `catalog list`。设备 session 由 CLI 自动登记或刷新；401 `agent_device_session_required` 仅续期并重试一次，仍失败时返回错误，不循环。
+Start API 只提供免费额度上限，不提供当前剩余额度，因此本命令不得虚构 `remaining`。不得输出全部 capability DTO、contract version、Arazzo workflow、buyer/device ID 或重复 guidance。若服务不存在，recovery 为 `catalog list`。设备 session 由 CLI 自动登记或刷新；401 `agent_device_session_required` 仅续期并重试一次，仍失败时返回错误，不循环。
 
 ## Agent Type / Host
 

package/docs/cli-reference/commands/vault/access.md

@@ -27,7 +27,8 @@ itpay vault access [--artifact <artifact_ref>] [--host <host>] [--target <target
   "handoff": {
     "url": "https://app.itpay.ai/vault/access/...",
     "qr_local_path": "<desktop-optional-local-path>",
-    "markdown": "<desktop-optional-host-ready-markdown>"
+    "markdown": "<desktop-optional-host-ready-markdown>",
+    "qr_image_url": "<chat-host-optional-absolute-https-png>"
   },
   "instruction": "说明这是当前智能体的只读授权，实际展示 handoff，然后停止；用户完成后重新运行最初的读取命令。",
   "next": null,
@@ -53,6 +54,7 @@ Agent不得提取、单独输出、记录或重建其中的 credential；但不
 | `claude-code-cli / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `workbuddy / plain-chat` | `url, agent_action` |
 | `zcode / plain-chat` | `url`；立即用内置浏览器打开，浏览器不可用时才展示可点击链接 |
+| `doubao-work / plain-chat` | `url, qr_image_url`；展示“直接打开授权页”和“授权二维码图片（保存或用另一台设备扫码）”两个有标签的官方入口 |
 | `kimi-code / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `openclaw / telegram` | `url, qr_image_url, agent_action` |
 | `openclaw / other` | `url, qr_image_url` |
@@ -61,3 +63,5 @@ Agent不得提取、单独输出、记录或重建其中的 credential；但不
 未显示并发送同一个 URL；不得创建替代请求。
 
 ZCode 不接收图片路径或二维码 URL。instruction 必须要求 Agent立即用内置浏览器打开完整 `handoff.url`，然后停止等待；不得只粘贴文字链接或重建二维码。仅当内置浏览器明确不可用时才展示同一个可点击链接。
+
+Doubao Work 的两个字段都是必需项。若兼容 Backend 未直接返回二维码 URL，CLI 必须从同一官方授权入口派生 Backend 的对应二维码端点；无法安全派生时命令必须明确失败，不得返回缺字段的 handoff。instruction 必须要求 Agent 同时展示完整 `handoff.url` 与 `handoff.qr_image_url`，清楚区分直接打开与跨设备扫码用途，然后停止等待。不得解析 credential、下载或重建二维码，也不得重复执行 `vault access` 检查状态。

package/docs/cli-reference/conventions.md

@@ -1,6 +1,6 @@
 # Output And Error Contract
 
-> **Product boundary:** `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 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.
 
 ## 目标
 
@@ -37,7 +37,7 @@ CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默
 - `recovery`：成功时通常为空；失败或中断时最多两个动作。
 - 一旦命令声明 `--agent-type` 或 `ITPAY_AGENT_TYPE`，所有 ItPay `next.command` 和 `recovery.command` 都保留同一类型。
 - 相同事实不得同时出现在顶层、`agent_guidance`、`next_actions` 等多个位置。
-- 默认隐藏 buyer、device、contract version、compiled graph、quote lock、内部 event ID 等实现细节。
+- 默认隐藏 buyer、device、contract version、Arazzo workflow、quote lock、内部 event ID 等实现细节。
 - token、付款 URL 和本地二维码路径只在确实需要交给用户时返回，并不得写入日志型命令。
 
 ## 默认文本输出
@@ -78,11 +78,9 @@ next: <one command>
 - 用户口头说“已付款”不是支付事实；仅服务端 `verified` 状态有效。
 - `agent_device_session_required` 只触发一次 session 续期和同请求重试；第二次失败必须返回，不得循环或换身份。
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
-- WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
+- WorkBuddy 需通过宿主的正常权限机制允许 CLI 持久化 `~/.itpay-v3`。若被拦截，报告受阻操作和宿主原因；不切换 Node、删除 identity 或猜测性处理活跃 lock。
 - `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
-minimum_cli_version 仅为协议门槛，不是经过核验的推荐制品。兼容失败保留当前 CLI/API、平台API及版本窗口事实；next=null、recovery=[]，停止本轮并请求维护方提供配套包，不猜版本或换身份。
-
-
+- `backend_contract_incompatible` 返回当前 CLI/API、平台 API 与 minimum/major 事实；minimum 不是已验证的推荐包。无配套制品证据时 next=null、recovery=[]，停止本轮并请求维护方提供匹配制品，禁止猜版本、降级或变更身份。
 
 ## 网络传输失败与自动重试
 

package/docs/cli-reference/index.md

@@ -2,7 +2,7 @@
 
 本目录是 ItPay CLI 的规范性命令合同。它定义命令应向人和 Agent 返回什么、如何指导下一步，以及失败后如何恢复。当前实现与本文档不一致时，以本文档作为后续校准目标。
 
-> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。当前入口同时覆盖购买新服务、查询订单、查看经用户授权的已购内容和退款；Seller 流程未来仍使用同一入口，当前尚未实现。不得为这些意图拆分新的产品入口。
+> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。当前入口同时覆盖购买新服务、查询订单、查看经用户授权的已购内容和退款；Seller 流程使用同一入口的 `itpay sell` 命令。不得为这些意图拆分新的产品入口。
 
 企知道可以作为示例数据出现，但任何命令、字段、状态和 instruction 都不得依赖某个服务。服务差异只能来自 Catalog、Service Contract、Capability metadata 和服务端状态。
 
@@ -34,6 +34,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay catalog list`](commands/catalog/list.md)
 - [`itpay install`](commands/install.md) - 查看指定 Agent 的安装说明
 - [`itpay skill show`](commands/skill.md) - 一次读取完整内置 ItPay Skill
+- [`itpay auth login / status`](commands/auth.md) - 官方登录并绑定当前已登记 Agent，继续免费查询
 - [`itpay device recover`](commands/device.md) - 仅恢复运营已确认重建的 Backend registration
 - [`itpay docs`](commands/docs/index.md)
   - [`itpay docs list`](commands/docs/list.md)
@@ -78,6 +79,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
 ### 通用服务执行
 
 - [`itpay services`](commands/services/index.md)
+  - [`itpay services run`](commands/services/run.md)
   - [`itpay services start`](commands/services/start.md)
   - [`itpay services invoke`](commands/services/invoke.md)
   - [`itpay services action`](commands/services/action.md)
@@ -86,5 +88,12 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
   - [`itpay services list`](commands/services/list.md)
   - [`itpay services get`](commands/services/get.md)
   - [`itpay services next`](commands/services/next.md)
+  - [`itpay services page`](commands/services/page.md)
   - [`itpay services read-result`](commands/services/read-result.md)
   - [`itpay services events`](commands/services/events.md)
+
+- [Sell: create, test and submit services](commands/sell.md)
+
+- [Run a published service](commands/services/run.md)
+
+- [`itpay aftercare`](commands/aftercare.md)

package/docs/sell.md

@@ -0,0 +1,84 @@
+# Sell Agent guide
+
+The railway acceptance release `2.1.2` is published under npm's `next` tag,
+not `latest`. Install this explicit version for dev acceptance and set
+`ITPAY_BACKEND_URL=https://dev.itpay.ai` on every command. Its API contract requires
+the matching dev backend release; do not use it against the older production
+backend. Promote the npm latest tag only after production compatibility is verified.
+
+`itpay sell` is the Seller command namespace. Buyer `services` commands remain separate. Read `itpay sell guide --json` first, authenticate with `itpay sell auth login` and complete the standard ItPay browser login, then run `itpay sell auth status`, then use `sell status` to select the user's existing merchant. An unverified merchant must finish KYB and payout setup in the dashboard.
+
+## Local-first workflow
+
+1. `sell init --project <directory> --service-id <id> --name <name>` creates a local project. `sell config --file <json>` sets price, policy and explicit test fixtures. Never invent prices or required API inputs.
+2. `sell library search/get` reads platform sources. `sell sources add --file <OpenAPI> --provider-key <key>` compiles local contracts with the platform importer. `sell workflow import --file <workflow.yaml>` preserves the submitted workflow and reports unsupported semantics. Read `sell workflow catalog` for supported node configuration.
+3. Generate or modify `workflow.yaml` in the user's Agent using the exact source contracts. Bind `providerOperationVersionId`, credential profile and input/output mappings explicitly. The first workflow ID must equal the service ID. Missing mappings, incompatible schema, unsupported content types or unsupported workflow semantics block execution. Do not remove unknown fields to conceal a compatibility error.
+4. `sell credentials bind --profile <id> --file <bindings.json>` accepts field-to-environment-variable mappings, never secret values. `sell credentials upload` uploads those environment values directly to the authenticated merchant after approval; values must not appear in chat, workflow files or generated docs. Platform-managed secrets cannot be downloaded.
+5. `sell workflow validate`, then `sell workflow versions save --name <name>`. Runs never create saved versions. `sell test run --confirm` performs actual Provider calls on this machine, with simulated payment/refund/delivery gates. `sell test get --run <id>` reads results. `sell test resume` never blindly replays an unknown request.
+6. `sell workflow preview` serves the existing Builder on loopback only. Review its exact YAML, price and version; then use `sell workflow confirm --confirm` only after user agreement.
+7. `sell push --merchant-id <id> --bindings <profile-map.json> --confirm` uploads the confirmed package. Profile map values are platform profile IDs, not secrets. Optimistic revisions prevent overwriting another editor. An ambiguous write requires explicit pull/reconciliation, never guessed retries.
+8. Inspect platform-imported operations and perform any required `sell sources probe` with explicit test inputs. Follow the backend Guide and the upload's returned version/revision fields to run `sell verify`. Disclose and confirm API side effects, including the exact risk hash if the platform returns an additional confirmation barrier.
+9. `sell submission preview` returns the workflow, price, policy and current agreements. After user approval, `sell submission submit` sends the exact revision, terms version and required confirmations. This requests review; it does not publish or approve.
+10. Use `sell submission get` and `sell services list/get` to follow the actual outcome. Rejected/withdrawn/taken-down services can be edited and resubmitted through the same process. Once published, verify with buyer `catalog list`.
+
+All platform operations accept `--input-json <file>` for their declared fields and `--merchant-id`/`--draft-id` where appropriate. Run each command's `--help`; do not invent options. `sell guide --merchant-id <id> --input-json <file>` with `{"draft_id":"..."}` returns server-derived next actions.
+
+## MCP
+
+`itpay sell mcp --stdio --project <directory>` exposes local creation, import, versioning, testing, preview, sync and platform actions. It reuses the local CLI identity. Remote MCP exposes only platform actions and cannot read paths on the user's machine. Use the local server for real local tests and file access. New remote grants require the appropriate `itpay.seller.read/write/test/submit` scopes; old buyer grants do not gain Seller authority.
+
+## Invariants
+
+- The current runtime accepts bounded, acyclic, single-entry workflows with multiple API nodes. Free queries can use quota and explicit human confirmation; paid workflows use one payment node and either fixed per-call pricing or a trusted pre-payment dynamic quote. Prepaid balance billing remains unsupported.
+- Protected railway fulfillment resumes through the platform booking Owner only after verified payment and Web passenger confirmation. A standalone API probe cannot supply a payment identity or passenger records. Follow the server Guide for actual acceptance and publication blockers; local graph validation is not live ticket-issuance evidence.
+- Local reports are diagnostics, not platform approval evidence. Platform verification is required; existing valid evidence may be reused. Admin approval never repeats Provider calls.
+- Every visual view reads the same YAML. Layout is presentation only.
+- Disclosure/confirmation binds the version being acted on. Do not turn `--confirm` into blanket permission for later changes.
+- Never approve real submissions or perform real payments in automated development tests.
+
+## Local recovery and packaging
+
+The local `.itpay-sell` directory contains private fixtures, reports and the encrypted run journal's local key. Exclude it from Git and shared artifacts. A terminated process may leave `runner.lock`; inspect the journal and ensure no runner is active before manual recovery. A request with an unknown outcome is never automatically replayed.
+
+Local reports never substitute for the platform verification gate. Repeated upload of an unchanged saved version reuses its cloud version; a changed cloud revision or fixture revision requires explicit pull/review.
+
+For CLI repository builds, run `node scripts/fetch-sell-runtime.mjs` to obtain the exact checksummed native runtime in `seller-runtime.lock.json`, then `npm run test:package`. The committed `assets/sell-preview` directory supplies the local Builder. Packaging rejects missing native binaries or preview assets; do not substitute an arbitrary local binary for the locked release.
+
+Example local MCP configuration (use the existing authenticated CLI account):
+
+```json
+{
+  "mcpServers": {
+    "itpay-sell": {
+      "command": "itpay",
+      "args": ["sell", "mcp", "--stdio", "--project", "/absolute/path/to/service"],
+      "env": {"ITPAY_BACKEND_URL": "https://sandbox.itpay.ai"}
+    }
+  }
+}
+```
+
+## Seller login and dev
+
+Use `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth login` to receive the normal ItPay authorization link. After browser login and required email verification, run `ITPAY_BACKEND_URL=https://dev.itpay.ai itpay sell auth status`. The CLI claims its own account session through the standard API and stores it in an owner-only file; never copy tokens or browser cookies. `itpay sell auth logout` revokes this session. Keep the same backend prefix on subsequent commands; production, dev, and sandbox state are isolated. Agent device enrollment does not grant Seller organization access.
+
+## Private dev live checkout acceptance
+
+`itpay sell tests start-checkout --merchant-id <merchant> --draft-id <draft> --input-json <file> --confirm --json`
+
+Requires the dev server in live Provider mode, an account-scoped platform admin session,
+and an active enrolled Agent already bound to the same buyer. The JSON contains
+`expected_revision` and `agent_instance_id`. Save exactly one success fixture first.
+This queues a private canary execution; it does not publish a service or pay for a ticket.
+Disclose the live query side effects before using `--confirm`.
+
+Resume the returned `service_execution_id` using the normal workflow commands through
+that Agent. The user confirms the route and submits passenger details in the protected
+Checkout page. Only a verified payment callback permits supplier creation/payment.
+
+`itpay sell tests accept-checkout --merchant-id <merchant> --draft-id <draft> --execution-id <execution> --confirm --json`
+
+Records server-observed completed delivery and issued tickets for the exact frozen
+workflow, fixture and dependency hashes. Pending, partial, manual-recovery, unpaid or
+changed tests cannot pass. No payment or issuance assertions are accepted as input.
+Then use the normal submission and admin review flow; this test alone is not publication.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.41",
+  "version": "2.1.44",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
-    "itp": "bin/itp",
-    "itpay": "bin/itp",
-    "itpay_cli": "bin/itp"
+    "itp": "bin/itp.mjs",
+    "itpay": "bin/itp.mjs",
+    "itpay_cli": "bin/itp.mjs"
   },
   "main": "./dist/src/main.js",
   "exports": {
@@ -15,14 +15,17 @@
   "files": [
     "bin/",
     "dist/src/",
-    "docs/",
+    "docs/agent/buyer/",
+    "docs/cli-reference/",
+    "docs/sell.md",
     "skills/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "assets/"
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "candidate-prod"
+    "tag": "candidate-dev"
   },
   "keywords": [
     "itpay",
@@ -32,6 +35,8 @@
     "codex",
     "openclaw",
     "zcode",
+    "doubao-work",
+    "doubao",
     "trae"
   ],
   "license": "MIT",
@@ -39,8 +44,10 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
-    "qrcode": "^1.5.4"
+    "qrcode": "^1.5.4",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^22.7.5",
@@ -58,16 +65,17 @@
     "check": "npm run lint && npm run test:coverage && npm run test:package",
     "pack:dry-run": "npm run clean && npm run build && npm pack --dry-run --ignore-scripts",
     "prepare": "node scripts/install-git-hooks.mjs",
-    "test:package": "npm run clean && npm run build && node scripts/package-smoke.mjs",
-    "prepack": "npm run clean && npm run build",
+    "test:package": "node scripts/check-sell-package.mjs && npm run clean && npm run build && node scripts/package-smoke.mjs",
+    "prepack": "node scripts/check-sell-package.mjs && npm run clean && npm run build",
     "prepublishOnly": "npm run check",
     "test": "tsx --test tests/*.test.ts",
     "test:coverage": "c8 --all --src src --extension .ts --exclude=src/client/types.ts --exclude=tests/** --exclude=scripts/** --reporter=text --reporter=lcov --check-coverage --lines 85 --statements 85 --functions 90 --branches 70 npm test",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "precheck": "node scripts/fetch-sell-runtime.mjs"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/itpay-ai/cli.git"
   },
-  "gitHead": "3cc612a853f9cff49574f416dfc0bc12ffbeefae"
+  "gitHead": "e857df88cab7549f3ee011fc4e562ef2d40f8274"
 }