@agenzo/merchant-cli 0.4.2 → 0.5.0

package/README.md

@@ -1,68 +1,77 @@
 # @agenzo/merchant-cli
 
-> **Merchant-fulfillment product-line CLI** — binary `agenzo-merchant-cli`, lives in the monorepo `agenzo-cli/apps/merchant-cli`.
-> Covers two noun groups: capability discovery (`services`) and the ride-hailing business loop (`ride-elife`), 7 commands in total.
+[![npm](https://img.shields.io/npm/v/@agenzo/merchant-cli.svg)](https://www.npmjs.com/package/@agenzo/merchant-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE) ![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)
+
+> **Merchant-fulfillment CLI** for the Agenzo platform — binary `agenzo-merchant-cli`.
+> Agents fulfill commerce services here. Each capability is a noun and the set grows over time — use `services` to discover what's available; today's capabilities are ride-hailing (`ride-elife`) and hotel booking (`hotel-redaug`).
+
+**[Overview](#overview)** · **[Features](#features)** · **[Quick Start](#quick-start)** · **[Global flags](#global-flags)** · **[Errors](#output-and-error-contract)** · **[Idempotency-Key](#idempotency-key)**
 
 ---
 
 ## Overview
 
-`agenzo-merchant-cli` is the command-line entry point for Agents to access Agenzo's merchant-fulfillment capabilities. This iteration ships two noun groups:
+`agenzo-merchant-cli` is the command-line entry point for Agents to fulfill commerce services on the Agenzo platform. Each fulfillment capability is exposed as a **noun**, and the set grows over time:
 
-- **`services`** (capability discovery): lets an Agent discover available merchant-fulfillment capabilities (which noun/verb to call, and the call flow). The data source this iteration is the **CLI-bundled registry** (the backend `/services` discovery endpoint is pending impl).
-- **`ride-elife`** (ride hailing, the only online provider): the full loop of quote → book → query/poll → cancel → list-orders.
+- **`services`** (capability discovery): list what's currently available and how to call it — run this first to learn the current capability set.
+- **`ride-elife`** (ride-hailing): the full loop of quote → book → query/poll → cancel → list-orders.
+- **`hotel-redaug`** (hotel booking): search, find-destination, hotel-filters, list-cities, hotel-detail, quote, create-order, pay-order, get (status/poll), cancel, checkout, get-checkout, list-orders. Supports both **monthly_settlement** (on-account deduction) and **pay_per_call** (user pays via EVO using the order_id as the merchantTransID).
 
-All shared infrastructure (HTTP client, output rendering, error system, exit codes, version negotiation, config) is reused from `@agenzo/cli-core`; the app only keeps command handling and merchant-domain-specific logic (ride body assembly, NDJSON watch, verb-schema help, services registry, idempotency-key policy).
-
-> This CLI keeps its structure, naming, and build configuration consistent with `agenzo-admin-cli` / `agenzo-token-cli` (4-CLI consistency).
+More fulfillment capabilities are added as new nouns over time; `services list` always reflects the current set.
 
 ## Features
 
 | Noun | Verb | Type | HTTP | Description |
 |---|---|---|---|---|
-| `services` | `list` | Read | — (bundled registry) | List available merchant-fulfillment capabilities |
-| `services` | `get <service-id>` | Read | — (bundled registry) | View the full metadata of a single capability (miss → `SERVICE_NOT_FOUND`) |
+| `services` | `list` | Read | — (local) | List available merchant-fulfillment capabilities |
+| `services` | `get <service-id>` | Read | — (local) | View the full metadata of a single capability (miss → `SERVICE_NOT_FOUND`) |
 | `ride-elife` | `quote` | Read | `POST /ride/quote` | Point-to-point quote (`vehicle_classes[]` + meet-and-greet) |
 | `ride-elife` | `book` | Write/Y | `POST /ride/book` | Book against a quote (monthly_settlement-aware, see below) |
 | `ride-elife` | `get` | Read | `GET /ride/<id>/status` | Query order status; `--watch` emits an NDJSON polling stream |
 | `ride-elife` | `cancel` | Write/Y | `POST /ride/<id>/cancel` | Cancel an order (no body, may incur a fee) |
 | `ride-elife` | `list-orders` | Read | `GET /ride/orders` | List booked trips (pagination + filtering) |
-
-> Write commands (`book` / `cancel`) are subject to the idempotency-key rules (see [Idempotency-Key](#idempotency-key)).
-> Not implemented: `ride-elife track` (pending impl, the backend has no location-stream interface) — `get --watch` already covers order-status polling.
-
-## Tech Stack
-
-- TypeScript (ESM) + [commander@14](https://github.com/tj/commander.js) + [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js)
-- Build: [tsup](https://tsup.egoist.dev/) (esm / node18 / dts, banner `#!/usr/bin/env node`)
-- Testing: [vitest](https://vitest.dev/) + [fast-check](https://fast-check.dev/) (PBT)
-- Shared base package: `@agenzo/cli-core` (the only horizontal dependency; importing other apps is **forbidden**)
+| `hotel-redaug` | `search` | Read | `POST /hotel/search` | Search hotels by coordinates or destination-id + stay dates + filters |
+| `hotel-redaug` | `find-destination` | Read | `POST /hotel/find-destination` | Resolve free-text to destinations (destination_id + coordinates) |
+| `hotel-redaug` | `hotel-filters` | Read | `POST /hotel/filters` | Get available filter options for a location (codes → search flags) |
+| `hotel-redaug` | `list-cities` | Read | `POST /hotel/cities` | List cities for a country (destination_id + coordinates) |
+| `hotel-redaug` | `hotel-detail` | Read | `POST /hotel/detail` | Hotel detail with facilities/images AND `rooms[]` (area/floor/beds/photos) — call before quote |
+| `hotel-redaug` | `quote` | Read | `POST /hotel/quote` | Real-time rooms/rates for one hotel (`product_token` + `price_items`) |
+| `hotel-redaug` | `create-order` | Write/Y | `POST /hotel/create-order` | Create a hotel order without charging (locks rate + returns `order_id` + payable amount) |
+| `hotel-redaug` | `pay-order` | Write/Y | `POST /hotel/{order_id}/pay` | Pay for a created order (takes only `--order-id`); billing path (`monthly_settlement` or `pay_per_call`) is chosen server-side |
+| `hotel-redaug` | `get` | Read | `GET /hotel/<id>/status` | Query order status; `--watch` emits an NDJSON polling stream |
+| `hotel-redaug` | `cancel` | Write/Y | `POST /hotel/<id>/cancel` | Cancel a whole order (acceptance ≠ proof; poll `get`) |
+| `hotel-redaug` | `checkout` | Write/Y | `POST /hotel/<id>/checkout` | Partial check-out / out-of-policy cancellation (async) |
+| `hotel-redaug` | `get-checkout` | Read | `GET /hotel/checkout/<task_order_code>` | Poll a check-out application; `--watch` emits an NDJSON stream |
+| `hotel-redaug` | `list-orders` | Read | `GET /hotel/orders` | List hotel orders (pagination + status filter) |
+
+> Write commands (`ride-elife book` / `cancel`; `hotel-redaug create-order` / `pay-order` / `cancel` / `checkout`) are subject to the idempotency-key rules (see [Idempotency-Key](#idempotency-key)).
+> Read status verbs `get` / `get-checkout` support `--watch` for NDJSON status polling.
+> `ride-elife track` is not available — use `get --watch` for order-status polling.
 
 ## Quick Start
 
 ### Requirements
 
-- Node.js 18+
-- `npm install` has been run in the monorepo
+- Node.js 22+
 
-### Build
+### Installation
 
 ```bash
-# in the monorepo root
-npm run build -w @agenzo/cli-core       # must build the shared base package first
-npm run build -w @agenzo/merchant-cli   # tsup produces dist/index.js (= bin agenzo-merchant-cli)
+npm install -g @agenzo/merchant-cli
 agenzo-merchant-cli --version
 ```
 
+Upgrade later with `npm install -g @agenzo/merchant-cli@latest`.
+
 ### Authentication
 
 A runtime-plane CLI that uses an **API Key** (`--api-key`, carried per command as the `X-Api-Key` header):
 
 - The API Key is issued by `agenzo-admin-cli keys create --scope merchant` and must include the `merchant` scope.
 - When `--api-key` is omitted, it is requested interactively (password input).
-- No Bearer Token / AuthService / keystore — consistent with `agenzo-token-cli`.
+- No Bearer Token or local keystore — every command carries the API Key.
 
-### End-to-end example
+### Ride-hailing end-to-end example
 
 ```bash
 # 1. Discover capabilities
@@ -92,13 +101,94 @@ agenzo-merchant-cli ride-elife cancel --api-key "$API_KEY" --yes \
   --order-id "$RIDE_ID" --idempotency-key "cancel-$(date +%s)"
 ```
 
+### Hotel booking end-to-end example
+
+The core Agent loop is `search → quote → create-order → pay-order → get`. Amounts are decimal currency
+units (e.g. `320.00` = 320.00 yuan). `pay-order` takes only `--order-id`; the billing path is chosen
+server-side by the developer's `billing_mode`:
+- **monthly_settlement**: deducted from the monthly-settlement account.
+- **pay_per_call**: the user pays via shared EVO parameters using the `order_id` as the EVO merchantTransID; the platform verifies that payment for the same `order_id` before confirming.
+
+```bash
+# 1. Search hotels by coordinates + stay dates (or use --destination-id from find-destination).
+#    Pick a hotels[].hotel_id from the result for the quote step.
+agenzo-merchant-cli hotel-redaug search --api-key "$API_KEY" \
+  --lat 31.2304 --lng 121.4737 --distance 20 \
+  --check-in 2026-02-10 --check-out 2026-02-12 \
+  --adults 2 --children 0 --room-num 1
+
+# 2. Quote one hotel (produces rates[].product_token, total_price, price_items)
+agenzo-merchant-cli hotel-redaug quote --api-key "$API_KEY" \
+  --hotel-id "$HOTEL_ID" \
+  --check-in 2026-02-10 --check-out 2026-02-12 \
+  --adults 2 --room-num 1 --nationality CN
+
+# 3. Create Order (write op: locks rate, no charge; returns order_id + payable amount).
+agenzo-merchant-cli hotel-redaug create-order --api-key "$API_KEY" --yes \
+  --product-token "$PRODUCT_TOKEN" \
+  --total-amount 640.00 --currency CNY \
+  --price-items '[{"sale_date":"2026-02-10","sale_price":320.00,"breakfast_num":2},{"sale_date":"2026-02-11","sale_price":320.00,"breakfast_num":2}]' \
+  --check-in 2026-02-10 --check-out 2026-02-12 \
+  --guest-name "Zhang San" --contact-name "Zhang San" \
+  --contact-phone "13800138000" --contact-country-code 86 \
+  --idempotency-key "hotel-create-$(date +%s)"
+
+# 4a. Pay Order — monthly_settlement path (on-account)
+agenzo-merchant-cli hotel-redaug pay-order --api-key "$API_KEY" --yes \
+  --order-id "$ORDER_ID" \
+  --idempotency-key "hotel-pay-$(date +%s)"
+
+# 4b. Pay Order — pay_per_call path (user already paid via EVO using order_id
+#     as the EVO merchantTransID). Same command, no other flag.
+agenzo-merchant-cli hotel-redaug pay-order --api-key "$API_KEY" --yes \
+  --order-id "$ORDER_ID" \
+  --idempotency-key "hotel-pay-$(date +%s)"
+
+# 4c. Pay Order — pay_per_call with --watch (polls until PAID or timeout)
+agenzo-merchant-cli hotel-redaug pay-order --api-key "$API_KEY" --yes \
+  --order-id "$ORDER_ID" \
+  --idempotency-key "hotel-pay-$(date +%s)" \
+  --watch --watch-interval 5 --watch-timeout 120
+
+# 5. Query / poll status. create-order returns order_status=AWAITING_PAYMENT;
+#    after pay-order succeeds, status becomes PAID; poll get until CONFIRMED.
+agenzo-merchant-cli hotel-redaug get --api-key "$API_KEY" --order-id "$ORDER_ID"
+agenzo-merchant-cli hotel-redaug get --api-key "$API_KEY" --order-id "$ORDER_ID" \
+  --watch --watch-interval 5 --watch-timeout 600
+
+# 6. List orders (pagination + optional status filter)
+agenzo-merchant-cli hotel-redaug list-orders --api-key "$API_KEY" \
+  --status CONFIRMED --page 1 --page-size 20
+
+# 7. Cancel a whole order (write op). Acceptance is NOT proof — poll get until CANCELLED.
+agenzo-merchant-cli hotel-redaug cancel --api-key "$API_KEY" --yes \
+  --order-id "$ORDER_ID" --fc-order-code "$FC_ORDER_CODE" \
+  --reason "Change of plans" \
+  --idempotency-key "hotel-cancel-$(date +%s)"
+
+# 8. Partial check-out / out-of-policy cancellation (write op, async).
+#    Returns task_order_code; poll get-checkout for the refund outcome.
+agenzo-merchant-cli hotel-redaug checkout --api-key "$API_KEY" --yes \
+  --order-id "$ORDER_ID" --fc-order-code "$FC_ORDER_CODE" \
+  --reason "Guest departing early" \
+  --checkout-rooms '[{"room_index":"1","guest_name":"Zhang San","cancel_check_in_date":"2026-02-11"}]' \
+  --refund-type 1 \
+  --idempotency-key "hotel-checkout-$(date +%s)"
+
+# 9. Poll the check-out application until a terminal refund status
+agenzo-merchant-cli hotel-redaug get-checkout --api-key "$API_KEY" \
+  --task-order-code "$TASK_ORDER_CODE"
+agenzo-merchant-cli hotel-redaug get-checkout --api-key "$API_KEY" \
+  --task-order-code "$TASK_ORDER_CODE" --watch --watch-interval 10 --watch-timeout 600
+```
+
 ## Global flags
 
 | Flag | Default | Description |
 |---|---|---|
-| `--format <json\|table>` | **`json`** | Output format. merchant-cli is an agent-first entry point, so it **defaults to `json`** (a deliberate deviation from cli-core's `table` default, D2); also reads the `AGENZO_FORMAT` environment variable |
+| `--format <json\|table>` | **`json`** | Output format. Defaults to `json`; pass `table` for tabular output. Also reads the `AGENZO_FORMAT` environment variable |
 | `--api-key <key>` | — (requested interactively) | API Key, carried per command as the `X-Api-Key` header |
-| `--yes` | `false` | Skip interactive confirmation (for CI / Agent); for write commands, `--yes` with a missing idempotency key is a hard error |
+| `--yes` | `false` | Skip interactive confirmation (non-interactive automation); for write commands, `--yes` with a missing idempotency key is a hard error |
 | `--verbose` | `false` | Verbose logging (written to stderr) |
 
 ## Output and error contract
@@ -106,24 +196,25 @@ agenzo-merchant-cli ride-elife cancel --api-key "$API_KEY" --yes \
 - **`--format json` (non-watch commands)**: stdout contains only a **single valid JSON** (business payload + `profile`/`endpoint` envelope, where endpoint is host-only without a path); all status/progress/spinner lines go to stderr and are silenced in json mode.
 - **`--format table`**: business output goes to stdout, status lines/spinner go to stderr.
 - **`get --watch`**: stdout is a line-by-line NDJSON stream, **not wrapped** in the profile/endpoint envelope; polling stops when it hits the terminal-status set (`At destination` / `Cancelled` / `Rejected` / `Customer no show` / `Driver no show`, case-sensitive) or times out; on timeout the final line is `{ "watch_status": "timeout", ... }`.
-- **Error envelope** (cli-core §8): `json` → `{ "error": { "code", "code_num", "message", "request_id"? } }`; `table` → `✗ [<code_num>] <message>`.
+- **`hotel-redaug get --watch` / `hotel-redaug get-checkout --watch`**: same NDJSON line-stream contract (no envelope). `get` stops when `order_status_code ∈ {3, 4, 5}` (equivalently `order_status ∈ {CONFIRMED, CANCELLED, COMPLETED}`); `get-checkout` stops when `refund_status ∈ {approved, rejected, refunded}`; on timeout the final line is `{ "watch_status": "timeout", ... }`.
+- **Error envelope**: `json` → `{ "error": { "code", "code_num", "message", "request_id"? } }`; `table` → `✗ [<code_num>] <message>`. When a request fails, retry with the same `--idempotency-key`; if it persists, contact support with the `request_id` from the error output.
 
-Exit codes (mapped by cli-core's `exitCodeFor`):
+Exit codes:
 
 | Exit code | Meaning | Representative error codes |
 |---|---|---|
 | `0` | Success | — |
-| `1` | Business / param | `PARAM_INVALID`(2101) · `PARAM_IDEMPOTENCY_KEY_REQUIRED`(2102) · `SERVICE_NOT_FOUND`(4101) · `VEHICLE_UNAVAILABLE`(4201) · `QUOTE_EXPIRED`(4202) · `BOOKING_FAILED`(4203) · `CANCELLATION_NOT_ALLOWED`(4204) · `BILLING_MODE_MISMATCH`(3001) · `ACCOUNT_*`(31xx) · `PAYMENT_ORDER_*`(32xx) |
+| `1` | Business / param | `PARAM_INVALID`(2101) · `PARAM_IDEMPOTENCY_KEY_REQUIRED`(2102) · `SERVICE_NOT_FOUND`(4101) · `VEHICLE_UNAVAILABLE`(4201) · `QUOTE_EXPIRED`(4202) · `BOOKING_FAILED`(4203) · `CANCELLATION_NOT_ALLOWED`(4204) · `NO_AVAILABILITY`(4301) · `PRICE_CHANGED`(4302) · `NAME_FORMAT_INVALID`(4303) · `HOTEL_ORDER_NOT_FOUND`(4304) · `ALREADY_CANCELLED`(4305) · `CHECKOUT_NOT_ALLOWED`(4306) · `CHECKOUT_TASK_NOT_FOUND`(4307) · `PAY_PER_CALL_NOT_AVAILABLE`(4308) · `BILLING_MODE_MISMATCH`(3001) · `ACCOUNT_*`(31xx) · `PAYMENT_ORDER_*`(32xx) |
 | `2` | Upgrade required | `UPGRADE_REQUIRED`(9008) |
 | `3` | Auth / invalid key | `KEY_INVALID`(1101) · `KEY_SCOPE_DENIED`(1102) |
 | `4` | Network / 5xx | `RATE_LIMITED`(5001) · `UPSTREAM_ERROR`(5101) · `INTERNAL_ERROR`(5201) |
 | `5` | User cancel | `CLIENT_ABORTED`(9007) · SIGINT |
 
-> api-key auth mapping: HTTP 401 → `KEY_INVALID`, 403 → `KEY_SCOPE_DENIED`. A known §8 string code returned by the backend (e.g. `QUOTE_EXPIRED`) takes priority and is preserved; otherwise it falls back to the HTTP-status mapping.
+> api-key auth mapping: HTTP 401 → `KEY_INVALID`, 403 → `KEY_SCOPE_DENIED`. A known string error code (e.g. `QUOTE_EXPIRED`) takes priority and is preserved; otherwise it falls back to the HTTP-status mapping.
 
 ## Idempotency-Key
 
-The write commands `ride-elife book` / `cancel` accept `--idempotency-key`:
+The write commands `ride-elife book` / `cancel` and `hotel-redaug create-order` / `pay-order` / `cancel` / `checkout` accept `--idempotency-key`:
 
 - Format: `[A-Za-z0-9_-]{1,128}`.
 - **The CLI never auto-generates one**: `--yes` with a missing key → hard error `PARAM_IDEMPOTENCY_KEY_REQUIRED` (exit 1), and no request is sent; a missing key without `--yes` → requested interactively.
@@ -132,66 +223,49 @@ The write commands `ride-elife book` / `cancel` accept `--idempotency-key`:
 
 ## Billing model for book (monthly_settlement-aware)
 
-`ride-elife book` **does not accept** `--payment-method-id` or any card information — the merchant domain holds no payment handle. Funding is decided by the backend according to the Developer's `billing_mode`:
+`ride-elife book` **does not accept** `--payment-method-id` or any card information — the merchant domain holds no payment handle. Funding is decided according to the Developer's `billing_mode`:
 
 - **monthly_settlement**: deducted from the monthly-settlement account, no payment handle; the response has `payment_status=ON_ACCOUNT` and includes `billing_entry_id`.
 - **pay_per_call**: optionally pass through `--payment-order-id` (a PAID order number charged separately, out-of-band); the response echoes `payment_order_id`.
 
 The request body contains at most an optional `payment_order_id`.
 
-## profile / host model
+### hotel-redaug billing (create-order + pay-order, two billing modes)
 
-merchant-cli **has no host / config commands** and does not govern environments. It reuses `@agenzo/cli-core`'s `ConfigManager` default configuration (i.e. the environment governed centrally by `agenzo-admin-cli`, persisted by default to `~/.agenzo-admin-cli/`):
+`hotel-redaug` uses a **two-step flow**: `create-order` (locks rate, no charge) then `pay-order` (settles).
 
-- Provides the `baseUrl` for `ApiClient` (host + `/api/merchant/v1`).
-- Provides the environment name + host for the `profile` / `endpoint` envelope in json output.
+`pay-order` takes only `--order-id`; there is no merchant-transaction-id flag. The billing path is
+chosen server-side by the developer's `billing_mode`:
 
-**Environment governance (setting the host / switching environments) belongs to `agenzo-admin-cli`** (`agenzo-admin-cli config set` / `set-host`) — consistent with `agenzo-token-cli`.
+- **monthly_settlement**: deducted from the monthly-settlement account. The response carries `payment_status=ON_ACCOUNT`.
+- **pay_per_call**: the user pays via shared EVO parameters out-of-band using the create-order `order_id` as the EVO merchantTransID; the platform queries EVO for that same `order_id` to confirm payment before calling upstream `payOrder` (response `settlement_path` is `pay_per_call`). If EVO reports "not yet paid", the CLI receives `PAYMENT_NOT_COMPLETED` (exit 1) — use `--watch` to poll until confirmed.
 
-## Machine-readable verb schema
+If the order's `billing_mode` is neither of the two values above, `pay-order` returns `BILLING_MODE_MISMATCH` (exit 1).
 
-Every `ride-elife` verb supports `--help --format json`, emitting that verb's machine-readable schema (`cli` / `noun` / `verb` / `description` / `flags` / `response` / `example`, some with `error_recovery` / `polling`):
+## Amount units (decimal currency)
 
-```bash
-agenzo-merchant-cli ride-elife quote --help --format json
-agenzo-merchant-cli ride-elife book --help --format json
-```
+Both `ride-elife` and `hotel-redaug` express **every monetary amount in DECIMAL currency units** paired with an ISO 4217 `currency` code — `320.00` means 320.00 yuan, never `32000` minor units (cents/fen). This applies to inputs (`hotel-redaug create-order --total-amount`, each `--price-items[].sale_price`) and to every rendered amount (`quote` totals and `price_items`, `get` / `list-orders` prices, cancellation fees, and refunds). Amounts are forwarded and rendered **verbatim**, with no minor-unit conversion in either direction. This differs from `agenzo-token-cli` and `agenzo-payment-cli`, which use minor units.
 
-## Development
+## profile / host model
 
-```bash
-npm run build -w @agenzo/merchant-cli   # tsup build
-npm run test  -w @agenzo/merchant-cli   # vitest (incl. fast-check PBT)
-```
+merchant-cli **has no host / config commands** and does not govern environments. It reuses the environment configured by `agenzo-admin-cli` (persisted under `~/.agenzo-admin-cli/`):
 
-Source structure:
-
-```text
-apps/merchant-cli/
-  src/
-    index.ts                 # commander assembly + top-level reportError + SIGINT
-    services/{list,get}.ts    # capability discovery (this iteration: CLI-bundled registry)
-    services/registry.ts      # bundled static registry (merchant domain)
-    ride-elife/{quote,book,get,cancel,list-orders}.ts
-    ride-elife/watch.ts       # NDJSON polling engine (merchant domain)
-    verb-schema.ts            # verb schema for --help --format json (merchant domain)
-    idempotency.ts            # idempotency key resolve / normalize (merchant domain)
-    types/api.ts              # ride/service response types (consumed by merchant only, not promoted to cli-core)
-  docs/                       # test design docs (see below)
-  tests/                      # vitest unit tests + PBT
-```
+- Determines the API host that requests are sent to.
+- Provides the environment name + host for the `profile` / `endpoint` envelope in json output.
 
-## Documentation index
+**Setting the host / switching environments belongs to `agenzo-admin-cli`** (`agenzo-admin-cli config set-host`).
 
-- [Test design doc (command matrix v1)](docs/test-design-command-matrix-v1.md) — a 7-command × requirement/Property coverage matrix, the L1–L4 layered testing strategy, L1 unit / L3 command-level case tables, and L4 manually executable smoke cases.
-- Architecture and standards: `architecture-upgrade/v1/` (cli-standard / cli-design §4+§8 / cli-guide).
-- monorepo overview: [`agenzo-cli/README.md`](../../README.md).
+## Machine-readable verb schema
 
-## Changelog
+Every `ride-elife` and `hotel-redaug` verb supports `--help --format json`, emitting that verb's machine-readable schema (`cli` / `noun` / `verb` / `description` / `flags` / `response` / `example`, some with `error_recovery` / `polling`):
 
-### 2026-06
+```bash
+agenzo-merchant-cli ride-elife quote --help --format json
+agenzo-merchant-cli ride-elife book --help --format json
+agenzo-merchant-cli hotel-redaug quote --help --format json
+agenzo-merchant-cli hotel-redaug create-order --help --format json   # write verb: error_recovery
+agenzo-merchant-cli hotel-redaug pay-order --help --format json      # write verb: error_recovery
+agenzo-merchant-cli hotel-redaug get --help --format json             # long-running: polling block
+```
 
-- Landed merchant-cli in the monorepo `agenzo-cli/apps/merchant-cli` (rewritten per cli-design §4, reusing `@agenzo/cli-core`).
-- Shipped `services` (list / get) + `ride-elife` (quote / book / get [+`--watch`] / cancel / list-orders), 7 commands in total.
-- Output defaults to `json` (agent-first); API Key auth (`X-Api-Key`); write commands require `--idempotency-key`.
-- Added the test design doc `docs/test-design-command-matrix-v1.md`.
+For `hotel-redaug`, `create-order` / `pay-order` / `cancel` / `checkout` are the write verbs that require `--idempotency-key`, and `get` / `get-checkout` are the long-running reads that support `--watch` NDJSON streaming (their schemas carry a `polling` block).