@itpay/cli 2.0.13 → 2.0.15

package/skills/{itpay-buyer → itpay}/SKILL.md

@@ -1,29 +1,38 @@
 ---
-name: itpay-buyer
+name: itpay
 description: >
-  Use the ItPay CLI when a human asks an Agent to discover services, use a
-  capability, buy a result, show a Checkout, recover an interrupted flow,
-  read a human-granted result, or manage a refund.
+  Use the single ItPay entry point when a human asks an Agent to buy or sell
+  through ItPay. Buyer workflows cover service discovery, purchase, Checkout,
+  delivery, recovery, and refunds. Seller workflows are not yet implemented.
 ---
 
-# ItPay Buyer
+# ItPay
 
 Use the CLI as the only ItPay control surface. Never recreate API calls or hardcode a service-specific sequence.
 
-## Envelope Rule
+## One Entry Point, Two Action Domains
+
+- `itpay` is the only CLI entry point, and `$itpay` is the only user-facing Skill invocation. Never create or route users to a separate Buyer or Seller entry point.
+- `buy` and `sell` are the two top-level ItPay action domains.
+- Buyer workflows are available now. Seller workflows will use this same `itpay` entry point, but are not implemented in the current release.
+- Do not invent Seller commands, onboarding, listings, or successful Seller state before that workflow ships.
 
-- Keep one honest Agent Type, CLI/Node launcher, and Host permission context. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
-- WorkBuddy: before any ItPay Bash command that persists `~/.itpay-v3`, set the Shell tool parameter `dangerouslyDisableSandbox` to `true`. If the human denies that permission, the command did not run: stop and report it. Never switch Node, delete identity, edit locks, or change Agent Type.
+## Critical Rules
+
+- The CLI defaults to production `https://app.itpay.ai`. Only an explicit test may use the exact prefix `ITPAY_BACKEND_URL=https://dev.itpay.ai`; never use another Backend. While testing dev, execute every returned command unchanged so that prefix is preserved.
+- Keep one honest Agent Type, one CLI/Node launcher, and one Host-approved permission context for the whole flow. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
+- WorkBuddy: before any ItPay Bash command that persists `~/.itpay-v3`, set the Shell tool parameter `dangerouslyDisableSandbox` to `true`. If the human denies that permission, the command did not run: stop and report it.
 - Windows, tasks, chats, processes, and model sessions are not new Agents. Never rotate Agent Type or identity to reset quota.
-- Read `status` and `result` as facts, follow `instruction`, and execute at most the applicable `next.command`; use `recovery` only when it cannot continue.
-- `next.command` is not unconditional. If the result satisfies the user's goal, present useful facts and stop; never dump the whole envelope.
+- Treat `next.command` as the preferred continuation, not an unconditional command. If the current result already satisfies the user's stated goal, present it and stop.
+- Keep internal parsing, retries, sandbox diagnosis, and command translation out of the user response; report useful progress, results, and real human decisions only.
+- If Device state is not writable, stop. Do not switch Node, manually create lock files, delete identity, or rotate Agent Type.
 
 ## Bootstrap
 
 ```bash
 npm install -g @itpay/cli
 itpay readyz --json
-itpay skill show itpay-buyer --json
+itpay skill show itpay --json
 itpay install --json
 itpay install <agent_type> --json
 itpay --agent-type <agent_type> readyz --json
@@ -35,11 +44,24 @@ If `backend_contract_incompatible` returns `result.required_cli_version`, stop e
 
 ## Identity And Sessions
 
-- One local Ed25519 private key represents this installation. Never expose, copy, delete, or rotate it during normal recovery.
-- `dev`, `test`, and `app` have separate Device registrations under the same key. Each registration has one Agent Instance per `agent_type`; same-type windows reuse it.
-- Keep the returned `--agent-type` on every commerce command, or use one stable `ITPAY_AGENT_TYPE`. `--host` is presentation and `--target` is routing; neither is identity or business input.
-- The CLI may renew a rejected/expired session and retry once. If it still fails or Device state is not writable, stop; do not loop, switch Node, edit locks, inspect credentials, or change identity.
-- Use `device recover --confirm-backend-reset` only after an operator confirms that Backend was reset. It preserves the key and other Backend registrations.
+- One local Ed25519 private key represents this ItPay installation. Never expose, copy, or rotate it to recover quota.
+- The CLI uses one local signing key with separate official Backend registrations. Each registration has one Agent Instance per `agent_type`; different windows and chats of the same type reuse it.
+- Every commerce command must keep the explicit `--agent-type` returned in `next` and `recovery`, or use one stable `ITPAY_AGENT_TYPE`. Never fall back to another type previously used on the machine.
+- The CLI renews an expired or rejected device session and retries the same request exactly once. If that retry still fails, stop and report it; do not loop, create a new identity, or switch Agent Type.
+- A revoked v2 device is not replaced automatically. It requires an explicit operator recovery path.
+- If an operator confirms that the current official Backend registration database was reset, use the complete returned `device recover --confirm-backend-reset` command. This preserves the private key and other Backend registration; never use it for ordinary session expiry or revocation.
+- `--host` selects presentation. `--target` is only the destination chat/channel/open ID required by some Hosts. Neither is business input or identity.
+
+## Envelope Rule
+
+For every JSON response:
+
+1. Read `status` and `result` as current facts.
+2. Follow `instruction` when explaining or presenting those facts.
+3. Execute at most the one `next.command`, filling only explicit placeholders or required user data.
+4. Use `recovery` only when the normal next step cannot continue.
+
+Do not print the whole envelope to the user. Return the useful result, a short explanation, and the next human action when needed.
 
 ## Golden Flow
 
@@ -110,7 +132,7 @@ Reuse the same Execution and Checkout. Never start another Execution, create ano
 itpay docs list --json
 itpay docs search <term> --json
 itpay docs show <topic> --json
-itpay skill show itpay-buyer --json
+itpay skill show itpay --json
 ```
 
 Normative command contracts are packaged under `docs/cli-reference`.