@itpay/cli 0.1.0

package/docs/agent/buyer/quickstart.json

@@ -0,0 +1,86 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "quickstart",
+  "title": "ItPay Buyer Agent Quickstart",
+  "purpose": "Teach a new external agent the minimal safe flow for buying through ItPay.",
+  "when_to_use": [
+    "The agent has just installed the ItPay CLI or loaded the buyer skill.",
+    "The user wants the agent to search for a service, recommend an option, or buy through ItPay.",
+    "The agent is unsure which ItPay buyer command should come first."
+  ],
+  "required_state": {
+    "needs": ["itp CLI available", "buyer delivery email before checkout"],
+    "must_not_need": ["ops token", "claim token", "raw key", "provider raw payload"]
+  },
+  "commands": [
+    {
+      "intent": "list the available agent docs topics",
+      "command": "itp docs list --role buyer --json",
+      "success_signal": "response.topics contains catalog-search, cart-checkout, payment-wait, secure-delivery"
+    },
+    {
+      "intent": "search the public catalog for the current user request",
+      "command": "itp buyer catalog search --query \"<user request>\" --json",
+      "success_signal": "response.products contains public products and variants"
+    },
+    {
+      "intent": "search standardized API services with category/facet filters when intent is clear",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --json",
+      "success_signal": "response.products are narrowed by category/facet before recommendation"
+    },
+    {
+      "intent": "buy a selected variant with the high-level cart-first flow",
+      "command": "itp buy <variant_id> --sandbox --email <buyer_email> --phone <buyer_phone> --json",
+      "success_signal": "response.status becomes waiting_human_auth, waiting_user_payment, payment_verified, or delivery_claimable"
+    }
+  ],
+  "agent_rules": [
+    "Use --json for every ItPay command.",
+    "Search and explain options before buying unless the user already named a variant.",
+    "Add the selected UCP Variant.id to cart; do not bypass cart for CORE-028 flows.",
+    "Before checkout, make sure a buyer delivery email is available. If no email is known from the current buyer context, ask the human for it before creating checkout.",
+    "Do not invent, guess, or use a placeholder email. Secure delivery and account/order access depend on the buyer email.",
+    "For first purchase, show auth_qr as the ItPay first-purchase entry: the human first approves provider login/registration/profile sharing, then ItPay should continue the same checkout to payment.",
+    "After showing auth_qr, keep running/resuming the same checkout unless the human explicitly asks you to pause. Do not stop merely because a QR was displayed.",
+    "Use high-level itp buy when possible; it is designed to show the first-purchase entry, wait/resume, continue to payment, wait for verification, and poll delivery.",
+    "Show the returned payment QR exactly as provided.",
+    "Payment truth comes only from payment_intent.verified.",
+    "Secure delivery goes to the human first; report redacted delivery status only."
+  ],
+  "forbidden": [
+    "Do not call ops commands from the buyer path.",
+    "Do not call worker run-once, provider query recovery, or fixture evidence routes.",
+    "Do not ask the user to paste raw keys, claim links, claim tokens, provider payloads, or secrets.",
+    "Do not rewrite, shorten, re-encode, or invent QR URLs.",
+    "Do not treat user text like 'I paid' as payment proof."
+  ],
+  "next_docs": [
+    {
+      "condition": "Need to discover or compare services",
+      "topic": "catalog-search",
+      "command": "itp docs show catalog-search --role buyer --json"
+    },
+    {
+      "condition": "User asks which option to choose",
+      "topic": "product-recommendation",
+      "command": "itp docs show product-recommendation --role buyer --json"
+    },
+    {
+      "condition": "A variant is selected and the agent needs to create cart/checkout",
+      "topic": "cart-checkout",
+      "command": "itp docs show cart-checkout --role buyer --json"
+    },
+    {
+      "condition": "The agent is unsure what is forbidden",
+      "topic": "safety-policy",
+      "command": "itp docs show safety-policy --role buyer --json"
+    },
+    {
+      "condition": "The user asks to view their ItPay account or previous orders",
+      "topic": "account-portal",
+      "command": "itp docs show account-portal --role buyer --json"
+    }
+  ],
+  "search_terms": ["start", "quickstart", "first time", "buyer flow", "how to use itpay", "开始", "第一次", "怎么用"]
+}

package/docs/agent/buyer/recovery.json

@@ -0,0 +1,63 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "recovery",
+  "title": "Safe Recovery",
+  "purpose": "Teach the agent how to recover without duplicating orders or crossing into ops authority.",
+  "when_to_use": [
+    "A command timed out.",
+    "The agent lost local context.",
+    "The human reports QR scan trouble.",
+    "Checkout or delivery is pending."
+  ],
+  "required_state": {
+    "needs": ["last known checkout_id, payment_intent_id, or variant_id"],
+    "must_not_need": ["ops token", "provider raw payload", "claim token"]
+  },
+  "commands": [
+    {
+      "intent": "resume checkout state",
+      "command": "itp buyer checkout resume <checkout_id> --json",
+      "success_signal": "response.status and agent_next_actions describe the safe next action"
+    },
+    {
+      "intent": "wait again on the same payment intent",
+      "command": "itp buyer payment wait <payment_intent_id> --json",
+      "success_signal": "response.payment_event.event_type is payment_intent.verified or still waiting"
+    },
+    {
+      "intent": "refresh display QR only",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+      "success_signal": "response.payment_intent.qr_image_url is present"
+    }
+  ],
+  "agent_rules": [
+    "Prefer resume over creating a new checkout.",
+    "A timeout does not prove failure.",
+    "Use the same checkout_id/cart_id/payment_intent_id whenever possible.",
+    "Report safe error messages only."
+  ],
+  "forbidden": [
+    "Do not call ops sandbox worker or provider query from buyer flow.",
+    "Do not create duplicate checkout after transient wait timeout.",
+    "Do not ask the user to paste secrets, claim links, or raw provider data."
+  ],
+  "next_docs": [
+    {
+      "condition": "QR needs display refresh",
+      "topic": "qr-refresh",
+      "command": "itp docs show qr-refresh --role buyer --json"
+    },
+    {
+      "condition": "Payment still waiting",
+      "topic": "payment-wait",
+      "command": "itp docs show payment-wait --role buyer --json"
+    },
+    {
+      "condition": "Delivery is claimable",
+      "topic": "secure-delivery",
+      "command": "itp docs show secure-delivery --role buyer --json"
+    }
+  ],
+  "search_terms": ["recover", "resume", "timeout", "lost", "retry", "stuck", "恢复", "重试", "卡住", "没返回", "断了", "找不到"]
+}

package/docs/agent/buyer/safety-policy.json

@@ -0,0 +1,56 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "safety-policy",
+  "title": "Buyer Agent Safety Policy",
+  "purpose": "Define the non-negotiable safety rules for ItPay buyer agents.",
+  "when_to_use": [
+    "The agent is unsure whether a command or data access is allowed.",
+    "The user asks the agent to reveal, fetch, or paste protected content.",
+    "The agent is deciding between buyer and ops commands."
+  ],
+  "required_state": {
+    "needs": ["role=buyer"],
+    "must_not_need": ["ops token", "raw secret access"]
+  },
+  "commands": [
+    {
+      "intent": "read this safety policy",
+      "command": "itp docs show safety-policy --role buyer --json",
+      "success_signal": "forbidden list is present"
+    },
+    {
+      "intent": "return to quickstart after safety check",
+      "command": "itp docs show quickstart --role buyer --json",
+      "success_signal": "quickstart topic is returned"
+    }
+  ],
+  "agent_rules": [
+    "Buyer agent authority is public discovery, cart/checkout creation, QR presentation, payment wait, and redacted delivery status.",
+    "Payment success must be verified by ItPay, not by user text or local inference.",
+    "Secure delivery is human-first.",
+    "If a request requires raw secret access, explain that ItPay blocks agent access by design."
+  ],
+  "forbidden": [
+    "No ops token in buyer flow.",
+    "No worker run-once in buyer flow.",
+    "No provider query recovery in buyer flow.",
+    "No fixture evidence route.",
+    "No raw key, redeem code, claim token, claim URL, storage ref, provider raw payload, buyer profile value, or session token in chat.",
+    "No QR URL rewriting.",
+    "No fake/mock/offline payment unless the user explicitly asks for offline simulation."
+  ],
+  "next_docs": [
+    {
+      "condition": "Need the normal flow",
+      "topic": "quickstart",
+      "command": "itp docs show quickstart --role buyer --json"
+    },
+    {
+      "condition": "Need delivery boundary details",
+      "topic": "secure-delivery",
+      "command": "itp docs show secure-delivery --role buyer --json"
+    }
+  ],
+  "search_terms": ["policy", "forbidden", "security", "secret", "ops", "安全", "禁止", "权限"]
+}

package/docs/agent/buyer/secure-delivery.json

@@ -0,0 +1,70 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "secure-delivery",
+  "title": "Secure Delivery Status",
+  "purpose": "Teach the agent how to handle ItPay secure delivery without seeing protected content.",
+  "when_to_use": [
+    "Payment was verified.",
+    "Checkout status mentions delivery_claimable, check_email, or claim_link_sent.",
+    "The user asks where the purchased key/content is."
+  ],
+  "required_state": {
+    "needs": ["checkout_id"],
+    "must_not_need": ["claim token", "claim link", "raw key", "storage ref"]
+  },
+  "commands": [
+    {
+      "intent": "check redacted delivery status",
+      "command": "itp buyer checkout status <checkout_id> --json",
+      "success_signal": "delivery.sensitive_content_redacted == true"
+    },
+    {
+      "intent": "list agent-safe delivery state",
+      "command": "itp buyer deliveries list --checkout <checkout_id> --json",
+      "success_signal": "response.deliveries contains no raw content or claim token"
+    },
+    {
+      "intent": "after the human says they granted agent access, discover the current agent's grants",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "success_signal": "response.agent_readable_grants contains only grants for this exact agent device"
+    }
+  ],
+  "agent_rules": [
+    "Tell the human to check email or the ItPay human claim UI.",
+    "Agent-visible status may say delivery_claimable/check_email/claim_link_sent.",
+    "Raw protected content is human-first unless the human later shares it outside ItPay.",
+    "If the user wants analysis, comparison, installation help, or structured use of the delivered result, you may ask the human to use the ItPay page's 'Give to Agent / 一键给 Agent' Passkey flow.",
+    "If the human uses the portal's one-key agent authorization, discover the resulting grant with buyer vault commands; do not ask the human to paste content or grant IDs.",
+    "Do not ask the human to paste the key into chat."
+  ],
+  "forbidden": [
+    "Do not call the secure claim URL as an agent API.",
+    "Do not request or print claim token, claim URL, raw key, redeem code, or storage ref.",
+    "Do not scrape the human claim UI.",
+    "Do not claim installation is complete unless a later human-granted install flow says so."
+  ],
+  "next_docs": [
+    {
+      "condition": "Human asks what the claim page is",
+      "topic": "human-claim-ui",
+      "command": "itp docs show human-claim-ui --role buyer --json"
+    },
+    {
+      "condition": "Human asks to view account or order history",
+      "topic": "account-portal",
+      "command": "itp docs show account-portal --role buyer --json"
+    },
+    {
+      "condition": "Human says they approved agent access with Passkey",
+      "topic": "vault-agent-read",
+      "command": "itp docs show vault-agent-read --role buyer --json"
+    },
+    {
+      "condition": "Delivery is not ready yet",
+      "topic": "recovery",
+      "command": "itp docs show recovery --role buyer --json"
+    }
+  ],
+  "search_terms": ["delivery", "claim", "email", "key", "redeem", "secure delivery", "交付", "邮件", "领取", "密钥"]
+}

package/docs/agent/buyer/vault-agent-read.json

@@ -0,0 +1,69 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer",
+  "topic": "vault-agent-read",
+  "title": "Human-Approved Vault Agent Read",
+  "purpose": "Teach the agent how to read only the artifact fields that the human explicitly approved with Passkey.",
+  "when_to_use": [
+    "The human opened the ItPay account portal and selected one-key agent authorization.",
+    "The user asks whether the agent can now see a purchased report or selected fields.",
+    "A checkout/order has delivered a vault artifact and the human granted agent-readable access."
+  ],
+  "required_state": {
+    "needs": ["authenticated buyer account session", "current agent device binding", "order_id or checkout_id or vault_artifact_id"],
+    "must_not_need": ["human portal token", "claim token", "passkey credential", "raw protected payload", "grant id copied by the human"]
+  },
+  "commands": [
+    {
+      "intent": "check whether this agent has active human-approved grants for a checkout",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "success_signal": "response.agent_readable_grants is an array; count > 0 means the human has granted this exact agent access"
+    },
+    {
+      "intent": "check whether this agent has active human-approved grants for one order or artifact",
+      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --json",
+      "success_signal": "only grants scoped to this logged-in agent device are returned"
+    },
+    {
+      "intent": "read a discovered grant view",
+      "command": "itp buyer vault grants read <agent_read_grant_id> --json",
+      "success_signal": "response.grant contains selected_fields, structured_view, or summary according to the human-approved scope"
+    },
+    {
+      "intent": "convenience read by order/artifact without asking the human for grant id",
+      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
+      "success_signal": "the CLI discovers the active grant and reads its scoped view"
+    }
+  ],
+  "agent_rules": [
+    "Only read through `buyer vault` commands after the human has explicitly approved the agent grant in the ItPay portal.",
+    "Do not ask the human to copy or paste `agent_read_grant_id`; discover it with `buyer vault grants list`.",
+    "If no grant is returned, tell the human to open their ItPay account portal, reveal with Passkey, choose fields, and confirm one-key agent authorization.",
+    "Use only fields returned in the grant view. Do not infer that unreturned fields are accessible.",
+    "If the command returns 401 or buyer_session_invalid, run `itp buyer auth status --json` and ask the human to reauthorize through a normal checkout/account flow."
+  ],
+  "forbidden": [
+    "Do not open, scrape, or screenshot the human portal to obtain protected content.",
+    "Do not request passkey credentials, portal tokens, claim links, claim tokens, storage refs, provider AppCode, provider keys, or raw payloads.",
+    "Do not use another agent's grant id. Grants are scoped to the exact buyer account session and agent device.",
+    "Do not cache selected fields beyond the task context unless the user explicitly asks you to create a local artifact."
+  ],
+  "next_docs": [
+    {
+      "condition": "The human needs a portal link to grant access",
+      "topic": "account-portal",
+      "command": "itp docs show account-portal --role buyer --json"
+    },
+    {
+      "condition": "The order was delivered but no grant exists",
+      "topic": "secure-delivery",
+      "command": "itp docs show secure-delivery --role buyer --json"
+    },
+    {
+      "condition": "The agent is unsure what it may read",
+      "topic": "safety-policy",
+      "command": "itp docs show safety-policy --role buyer --json"
+    }
+  ],
+  "search_terms": ["vault", "agent read", "passkey grant", "one key agent", "授权给 agent", "可读授权", "字段授权", "查看报告"]
+}

package/e2e-local.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+API_BASE=${VOLTAGENT_API_BASE:-http://localhost:3000}
+NODE=${NODE:-$(command -v node)}
+
+TMP_HOME=$(mktemp -d "${TMPDIR:-/tmp}/voltagent-itp-e2e-home.XXXXXX")
+TMP_SETUP_HOME=$(mktemp -d "${TMPDIR:-/tmp}/voltagent-itp-setup-home.XXXXXX")
+TMP_SETUP_NOWAIT_HOME=$(mktemp -d "${TMPDIR:-/tmp}/voltagent-itp-setup-nowait-home.XXXXXX")
+
+cleanup() {
+  rm -rf "$TMP_HOME" "$TMP_SETUP_HOME" "$TMP_SETUP_NOWAIT_HOME"
+}
+trap cleanup EXIT INT TERM
+
+itp_home() {
+  itp_home_dir="$1"
+  shift
+  attempt=0
+  while :; do
+    err_file="$itp_home_dir/itp-error.log"
+    if out=$(HOME="$itp_home_dir" PATH=/nonexistent VOLTAGENT_API_BASE="$API_BASE" "$NODE" "$ROOT/bin/itp" "$@" 2>"$err_file"); then
+      printf '%s' "$out"
+      return 0
+    fi
+    status=$?
+    error_text=$(cat "$err_file" 2>/dev/null || true)
+    attempt=$((attempt + 1))
+    if [ "$attempt" -lt 6 ] && printf '%s' "$error_text" | grep -q 'request failed: 429'; then
+      sleep "$attempt"
+      continue
+    fi
+    printf '%s\n' "$error_text" >&2
+    return "$status"
+  done
+}
+
+itp() {
+  itp_home "$TMP_HOME" "$@"
+}
+
+json_get() {
+  "$NODE" -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const v=JSON.parse(d); const path=process.argv[1].split('.'); let cur=v; for (const p of path) cur=cur?.[p]; if (cur === undefined || cur === null) process.exit(2); process.stdout.write(String(cur));})" "$1"
+}
+
+json_assert() {
+  "$NODE" -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const v=JSON.parse(d); const fn = new Function('v', process.argv[1]); if (!fn(v)) process.exit(1);})" "$1"
+}
+
+printf 'checking server %s\n' "$API_BASE" >&2
+curl -fsS "$API_BASE/api/status" >/dev/null
+curl -fsS "$API_BASE/api/itp/plans" | json_assert "return v.success === true && v.data.plans.some(p => p.plan_id === 'credit-100') && v.data.unit_rule === '1 credit = 1 CNY'" >/dev/null
+
+printf 'running one-command setup flow\n' >&2
+SETUP=$(itp_home "$TMP_SETUP_HOME" setup --credits 100 --method fake --mock-approve --allow-fake --offline --json)
+printf '%s' "$SETUP" | json_assert "return v.status === 'grant_ready' && v.target === 'generic' && v.grant_id && v.base_url && v.openai_base_url && v.credential && v.credential.stored === true && v.auth && v.auth.session_stored === true && v.runtime_install.status === 'skipped'"
+test ! -f "$TMP_SETUP_HOME/.codex/config.toml"
+TOKEN_FROM_SETUP=$(HOME="$TMP_SETUP_HOME" PATH=/nonexistent VOLTAGENT_API_BASE="$API_BASE" "$NODE" "$ROOT/bin/itp" token issue --grant "$(printf '%s' "$SETUP" | json_get grant_id)" --stdout)
+case "$TOKEN_FROM_SETUP" in
+  sk-*) ;;
+  *) echo "setup token issue did not return sk-* token" >&2; exit 1 ;;
+esac
+
+printf 'checking setup no-wait auth handoff\n' >&2
+SETUP_NOWAIT=$(itp_home "$TMP_SETUP_NOWAIT_HOME" setup --credits 100 --method fake --allow-fake --no-wait --json)
+printf '%s' "$SETUP_NOWAIT" | json_assert "return v.status === 'waiting_human_auth' && v.action === 'scan_alipay_auth' && v.run_id && v.auth_id && v.user_code && v.verification_uri_complete && v.human_action && v.human_action.display.length > 0"
+SETUP_NOWAIT_STATUS=$(itp_home "$TMP_SETUP_NOWAIT_HOME" status --json)
+printf '%s' "$SETUP_NOWAIT_STATUS" | json_assert "return v.status === 'waiting_human_auth' && v.run_id && v.auth_id && v.next && v.next.command.includes('resume')"
+SETUP_RESUMED=$(itp_home "$TMP_SETUP_NOWAIT_HOME" resume --mock-approve --allow-fake --offline --json)
+printf '%s' "$SETUP_RESUMED" | json_assert "return v.status === 'grant_ready' && v.run_id && v.grant_id && v.credential && v.credential.stored === true"
+
+USERNAME="e2e-$(date +%Y%m%d%H%M%S)-$$"
+printf 'registering %s\n' "$USERNAME" >&2
+AUTH=$(itp auth register --runtime codex --mock-approve --allow-fake --alipay-user-id "2088$RANDOM$RANDOM" --json)
+printf '%s' "$AUTH" | json_assert "return v.account_id && v.device_id && v.session_stored === true"
+
+ACCOUNT=$(itp account show --json)
+printf '%s' "$ACCOUNT" | json_assert "return v.password_set === false && v.account && v.account.account_id"
+
+printf 'setting first password\n' >&2
+printf 'secret123\n' | itp account set-password --password-stdin --json | json_assert "return v.password_set === true"
+ACCOUNT=$(itp account show --json)
+printf '%s' "$ACCOUNT" | json_assert "return v.password_set === true"
+
+printf 'creating fake checkout\n' >&2
+CHECKOUT=$(itp checkout create --credits 100 --method fake --allow-fake --idempotency-key "e2e-$USERNAME" --json)
+CHECKOUT_ID=$(printf '%s' "$CHECKOUT" | json_get checkout_id)
+GRANT_ID=$(printf '%s' "$CHECKOUT" | json_get grant_id)
+printf '%s' "$CHECKOUT" | json_assert "return v.status === 'grant_issued' && v.grant_id && !v.payment.cashier_url"
+
+printf 'waiting payment %s\n' "$CHECKOUT_ID" >&2
+PAYMENT=$(itp payment wait "$CHECKOUT_ID" --timeout 10 --json)
+printf '%s' "$PAYMENT" | json_assert "return v.status === 'grant_issued' && v.grant_id"
+
+printf 'installing grant %s\n' "$GRANT_ID" >&2
+INSTALL=$(itp grants install "$GRANT_ID" --target codex --json)
+printf '%s' "$INSTALL" | json_assert "return v.grant_id && v.credential && v.credential.credential_store"
+
+printf 'installing codex profile in temp HOME\n' >&2
+itp install codex --grant "$GRANT_ID" --offline --no-test --json | json_assert "return v.target === 'codex' && v.grant_id"
+test -f "$TMP_HOME/.codex/config.toml"
+test -f "$TMP_HOME/.itp/voltagent.env"
+
+BALANCE=$(itp balance --json)
+printf '%s' "$BALANCE" | json_assert "return v.active_grants === 1 && v.credits_remaining === '100.000000'"
+
+ORDERS=$(itp checkout list --limit 5 --json)
+printf '%s' "$ORDERS" | json_assert "return Array.isArray(v.orders) && v.orders.some(o => o.checkout_id === '$CHECKOUT_ID')"
+
+USAGE=$(itp usage --grant "$GRANT_ID" --json)
+printf '%s' "$USAGE" | json_assert "return v.grant_id === '$GRANT_ID' && v.total && v.total.requests === 0"
+
+printf 'rotating grant key\n' >&2
+ROTATE=$(itp keys rotate --grant "$GRANT_ID" --json)
+printf '%s' "$ROTATE" | json_assert "return v.grant_id === '$GRANT_ID' && v.credential && v.credential.credential_store"
+TOKEN=$(itp token issue --grant "$GRANT_ID" --stdout)
+case "$TOKEN" in
+  sk-*) ;;
+  *) echo "token issue did not return sk-* token" >&2; exit 1 ;;
+esac
+
+printf 'revoking grant\n' >&2
+REVOKE=$(itp grants revoke "$GRANT_ID" --json)
+printf '%s' "$REVOKE" | json_assert "return v.status === 'revoked'"
+BALANCE=$(itp balance --json)
+printf '%s' "$BALANCE" | json_assert "return v.active_grants === 0"
+
+printf 'voltagent local e2e ok\n'
+printf 'server: %s\n' "$API_BASE"
+printf 'account: %s\n' "$(printf '%s' "$AUTH" | json_get account_id)"
+printf 'checkout: %s\n' "$CHECKOUT_ID"
+printf 'grant: %s\n' "$GRANT_ID"
+printf 'temp_home_cleaned_on_exit: %s\n' "$TMP_HOME"

package/install.ps1

@@ -0,0 +1,53 @@
+$ErrorActionPreference = "Stop"
+
+$SourceDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ItpBin = Join-Path $SourceDir "bin\itp"
+$SkillsDir = Join-Path $SourceDir "skills"
+$DocsDir = Join-Path $SourceDir "docs"
+$NodeModules = Join-Path $SourceDir "node_modules"
+$Prefix = if ($env:ITP_PREFIX) { $env:ITP_PREFIX } else { Join-Path $HOME ".local" }
+$TargetDir = Join-Path $Prefix "bin"
+$TargetScript = Join-Path $TargetDir "itp.js"
+$TargetCmd = Join-Path $TargetDir "itp.cmd"
+$ModuleTarget = Join-Path $TargetDir "node_modules"
+$ShareTargetDir = Join-Path $Prefix "share\itpay_cli"
+$SkillsTarget = Join-Path $ShareTargetDir "skills"
+$DocsTarget = Join-Path $ShareTargetDir "docs"
+
+if (!(Test-Path $ItpBin)) {
+  throw "itp binary not found at $ItpBin"
+}
+
+New-Item -ItemType Directory -Force -Path $TargetDir | Out-Null
+Copy-Item -Force $ItpBin $TargetScript
+if (Test-Path $NodeModules) {
+  if (Test-Path $ModuleTarget) {
+    Remove-Item -Recurse -Force $ModuleTarget
+  }
+  Copy-Item -Recurse -Force $NodeModules $ModuleTarget
+}
+if (Test-Path $SkillsDir) {
+  if (Test-Path $SkillsTarget) {
+    Remove-Item -Recurse -Force $SkillsTarget
+  }
+  New-Item -ItemType Directory -Force -Path $ShareTargetDir | Out-Null
+  Copy-Item -Recurse -Force $SkillsDir $SkillsTarget
+}
+if (Test-Path $DocsDir) {
+  if (Test-Path $DocsTarget) {
+    Remove-Item -Recurse -Force $DocsTarget
+  }
+  New-Item -ItemType Directory -Force -Path $ShareTargetDir | Out-Null
+  Copy-Item -Recurse -Force $DocsDir $DocsTarget
+}
+Set-Content -Path $TargetCmd -Encoding ASCII -Value @"
+@echo off
+node "%~dp0itp.js" %*
+"@
+
+Write-Output "Installed itp to $TargetCmd"
+if (($env:Path -split ';') -notcontains $TargetDir) {
+  Write-Output "Add $TargetDir to PATH before running itp."
+} else {
+  & $TargetCmd --version
+}

package/install.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env sh
+set -eu
+
+SOURCE_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+ITP_BIN="$SOURCE_DIR/bin/itp"
+SKILLS_DIR="$SOURCE_DIR/skills"
+DOCS_DIR="$SOURCE_DIR/docs"
+NODE_MODULES="$SOURCE_DIR/node_modules"
+PREFIX="${ITP_PREFIX:-$HOME/.local}"
+TARGET_DIR="$PREFIX/bin"
+TARGET="$TARGET_DIR/itp"
+SHARE_TARGET_DIR="$PREFIX/share/itpay_cli"
+MODULE_TARGET="$TARGET_DIR/node_modules"
+
+if [ ! -f "$ITP_BIN" ]; then
+  echo "itp binary not found at $ITP_BIN" >&2
+  exit 1
+fi
+
+mkdir -p "$TARGET_DIR"
+chmod +x "$ITP_BIN"
+cp "$ITP_BIN" "$TARGET"
+chmod +x "$TARGET"
+
+if [ -d "$NODE_MODULES" ]; then
+  rm -rf "$MODULE_TARGET"
+  cp -R "$NODE_MODULES" "$MODULE_TARGET"
+fi
+
+if [ -d "$SKILLS_DIR" ]; then
+  rm -rf "$SHARE_TARGET_DIR/skills"
+  mkdir -p "$SHARE_TARGET_DIR"
+  cp -R "$SKILLS_DIR" "$SHARE_TARGET_DIR/skills"
+  find "$SHARE_TARGET_DIR/skills" -type f -exec chmod 0644 {} \;
+fi
+
+if [ -d "$DOCS_DIR" ]; then
+  rm -rf "$SHARE_TARGET_DIR/docs"
+  mkdir -p "$SHARE_TARGET_DIR"
+  cp -R "$DOCS_DIR" "$SHARE_TARGET_DIR/docs"
+  find "$SHARE_TARGET_DIR/docs" -type f -exec chmod 0644 {} \;
+fi
+
+case ":$PATH:" in
+  *":$TARGET_DIR:"*) ;;
+  *)
+    echo "Installed itp to $TARGET"
+    echo "Add $TARGET_DIR to PATH before running itp."
+    exit 0
+    ;;
+esac
+
+"$TARGET" --version

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@itpay/cli",
+  "version": "0.1.0",
+  "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
+  "type": "module",
+  "bin": {
+    "itp": "bin/itp",
+    "itpay": "bin/itp",
+    "itpay_cli": "bin/itp"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "docs/",
+    "install.sh",
+    "install.ps1",
+    "smoke.sh",
+    "e2e-local.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "smoke": "sh ./smoke.sh",
+    "check": "node --check ./bin/itp && sh ./smoke.sh"
+  },
+  "keywords": [
+    "itpay",
+    "voltagent",
+    "agent",
+    "cli",
+    "claude-code",
+    "codex",
+    "openclaw"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  }
+}