@itpay/cli 0.1.1 → 0.1.4

package/README.md

@@ -34,16 +34,18 @@ openclaw
 Default API endpoint:
 
 ```text
-http://localhost:3000
+https://dev.api.itpay.ai
 ```
 
-Override it for ItPay staging or production:
+Override it for local development, staging, or production:
 
 ```bash
-export ITPAY_API_BASE=https://your-itpay-core.example.com
-export ITPAY_CORE_BASE_URL=https://your-itpay-core.example.com
+export ITPAY_API_BASE=http://127.0.0.1:18080
+export ITPAY_CORE_API_BASE=http://127.0.0.1:18080
 ```
 
+Production release will switch the package default to `https://api.itpay.ai`.
+
 ## Repository Layout
 
 ```text
@@ -184,10 +186,11 @@ node ./bin/itp --version
 
 ## Basic User Flow
 
-Set API endpoint if not using local backend:
+The default endpoint is the AWS dev backend. Set API endpoint only when testing
+local or another environment:
 
 ```bash
-export ITPAY_API_BASE=https://your-itpay-core.example.com
+export ITPAY_API_BASE=http://127.0.0.1:18080
 ```
 
 For the current buyer commerce flow, search the catalog, create a cart/checkout,

package/bin/itp

@@ -8,8 +8,8 @@ import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import QRCode from "qrcode";
 
-const VERSION = "0.1.2";
-const DEFAULT_API_BASE = process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_BASE_URL || "http://localhost:3000";
+const VERSION = "0.1.4";
+const DEFAULT_API_BASE = process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_API_BASE || process.env.ITPAY_CORE_BASE_URL || "https://dev.api.itpay.ai";
 const CONFIG_DIR = path.join(os.homedir(), ".itp");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const STATE_PATH = path.join(CONFIG_DIR, "state.json");
@@ -198,9 +198,9 @@ async function main() {
           "buyer catalog search --query 企业工商 --category business_data_api --provider itpay_enterprise_data --json",
           "buyer catalog get --variant var_pubg_couple_skin_cny20 --json",
           "buyer cart create --variant var_pubg_couple_skin_cny20 --json",
-          "buyer cart create --variants var_itpay_enterprise_precise_lookup_cny05,var_itpay_enterprise_fuzzy_search_cny01 --quantities 1,1 --json",
+          "buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json",
           "buyer cart show <cart_id> --json",
-          "buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --quantity 1 --json",
+          "buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --quantity 1 --json",
           "buyer cart remove <cart_id> --line <cart_line_item_id> --json",
           "buyer shelf manifest --json",
           "buyer shelf snapshot --version <catalog_version> --json",
@@ -715,11 +715,12 @@ async function buyer(command, rest, flags) {
       const checkoutID = flags.checkout || flags.checkout_id || positional(rest, 1) || readState().last_core_checkout_id;
       if (!checkoutID) throw new Error("checkout_id is required");
       const checkout = await getBuyerCheckout(checkoutID, flags);
-      await maybeClaimBuyerSessionForCheckout(checkout, flags);
+      const claimedSession = await maybeClaimBuyerSessionForCheckout(checkout, flags);
       output(buyerRunOutput({
         status: checkout.delivery_status || checkout.status,
         checkout,
         delivery: checkout.delivery,
+        buyer_session: buyerSessionClaimStatus(claimedSession),
         agent_next_actions: deliveryAwareAgentNextActions(checkout),
         optional_agent_read_grant: optionalAgentReadGrantHint(checkout.checkout_id, checkout)
       }));
@@ -759,15 +760,21 @@ async function buyer(command, rest, flags) {
             }
           }));
           return;
+          }
+        }
+        const claimedSession = await maybeClaimBuyerSessionForCheckout(checkout, flags);
+        if (checkout.payment_intent_id) {
+          const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
+          await renderItPayPaymentAction(intent, flags);
+          output(buyerRunOutput({
+            status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment",
+            checkout,
+            payment_intent: intent,
+            buyer_session: buyerSessionClaimStatus(claimedSession),
+            agent_next_actions: intent.agent_next_actions || checkout.agent_next_actions || ["wait_payment"]
+          }));
+          return;
         }
-      }
-      await maybeClaimBuyerSessionForCheckout(checkout, flags);
-      if (checkout.payment_intent_id) {
-        const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
-        await renderItPayPaymentAction(intent, flags);
-        output(buyerRunOutput({ status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment", checkout, payment_intent: intent, agent_next_actions: intent.agent_next_actions || checkout.agent_next_actions || ["wait_payment"] }));
-        return;
-      }
       if (checkout.agent_next_actions?.includes("create_payment_intent") || checkout.next_required_action === "create_payment_intent") {
         const intent = await createBuyerPaymentIntent(checkout.checkout_id, flags);
         await renderItPayPaymentAction(intent, flags);
@@ -778,6 +785,7 @@ async function buyer(command, rest, flags) {
         status: checkout.delivery_status || checkout.status,
         checkout,
         delivery: checkout.delivery,
+        buyer_session: buyerSessionClaimStatus(claimedSession),
         agent_next_actions: deliveryAwareAgentNextActions(checkout),
         optional_agent_read_grant: optionalAgentReadGrantHint(checkout.checkout_id, checkout)
       }));
@@ -838,10 +846,12 @@ async function buyer(command, rest, flags) {
     if (subcommand === "grants") {
       const action = rest[1] && !String(rest[1]).startsWith("--") ? rest[1] : "list";
       if (action === "list") {
+        const claimedSession = await ensureBuyerSessionForVaultAccess(flags);
         const grants = await listBuyerAgentReadGrants(flags);
         output(buyerRunOutput({
           status: "agent_read_grants",
           ...grants,
+          buyer_session: buyerSessionClaimStatus(claimedSession),
           agent_next_actions: grants.agent_readable_grants?.length ? ["read_agent_grant_view"] : ["wait_for_human_agent_read_grant"]
         }));
         return;
@@ -849,6 +859,7 @@ async function buyer(command, rest, flags) {
       if (action === "read" || action === "show") {
         const grantID = flags.grant || flags.grant_id || flags.agent_read_grant_id || positional(rest, 2);
         if (!grantID) throw new Error("agent_read_grant_id is required");
+        await ensureBuyerSessionForVaultAccess(flags);
         const view = await readBuyerAgentReadGrant(grantID, flags);
         output(buyerRunOutput({
           status: "agent_read_grant_view",
@@ -859,6 +870,7 @@ async function buyer(command, rest, flags) {
       }
     }
     if (subcommand === "read") {
+      await ensureBuyerSessionForVaultAccess(flags);
       const view = await readBuyerVaultArtifactGrant(flags);
       output(buyerRunOutput({
         status: "agent_read_grant_view",
@@ -1317,6 +1329,20 @@ async function maybeClaimBuyerSessionFromAuthAction(action, flags = {}) {
   }
 }
 
+function buyerSessionClaimStatus(claimed = null) {
+  const config = readConfig();
+  const hasSession = Boolean(readSessionToken());
+  if (!claimed && !hasSession) return undefined;
+  return {
+    status: "buyer_session_saved",
+    session_stored: true,
+    buyer_account_id: claimed?.buyer_account_id || config.account_id || null,
+    agent_device_id: claimed?.agent_device_id || config.device_id || null,
+    token_included: false,
+    agent_next_actions: ["reuse_buyer_session", "list_agent_read_grants"]
+  };
+}
+
 async function maybeClaimBuyerSessionForCheckout(checkout, flags = {}) {
   if (!checkout?.checkout_id) return null;
   if (readSessionToken()) return null;
@@ -1325,19 +1351,76 @@ async function maybeClaimBuyerSessionForCheckout(checkout, flags = {}) {
   return await maybeClaimBuyerSessionFromAuthAction(action, flags);
 }
 
+async function ensureBuyerSessionForVaultAccess(flags = {}) {
+  if (readSessionToken()) return null;
+  const checkoutID =
+    flags.checkout ||
+    flags.checkout_id ||
+    readState().last_core_checkout_id ||
+    readState().last_core_auth_checkout_id;
+  if (checkoutID) {
+    try {
+      const checkout = await getBuyerCheckout(checkoutID, flags);
+      rememberCoreAuthAction(checkout.checkout_id || checkoutID, checkout.human_action);
+      const claimed = await maybeClaimBuyerSessionForCheckout(checkout, { ...flags, quiet: true });
+      if (claimed || readSessionToken()) return claimed;
+    } catch {
+      // Continue with the locally remembered auth action below.
+    }
+    const action = readCoreAuthAction(checkoutID);
+    const claimed = await maybeClaimBuyerSessionFromAuthAction(action, { ...flags, quiet: true });
+    if (claimed || readSessionToken()) return claimed;
+  }
+  const state = readState();
+  const entries = Object.entries(state.core_auth_actions || {});
+  for (const [, action] of entries.reverse()) {
+    const claimed = await maybeClaimBuyerSessionFromAuthAction(action, { ...flags, quiet: true });
+    if (claimed || readSessionToken()) return claimed;
+  }
+  return null;
+}
+
 function parseBuyerAuthActionURL(action) {
-  const rawURL = action?.url || action?.auth_url || "";
-  if (!rawURL) return {};
-  try {
-    const parsed = new URL(rawURL);
-    const match = parsed.pathname.match(/\/v1\/buyer\/auth-sessions\/([^/]+)$/);
-    return {
-      authSessionID: match ? decodeURIComponent(match[1]) : "",
-      displayToken: parsed.searchParams.get("display_token") || ""
-    };
-  } catch {
-    return {};
+  if (!action || typeof action !== "object") return {};
+  let authSessionID = String(action.auth_session_id || "").trim();
+  if (!authSessionID && String(action.id || "").startsWith("auth_")) {
+    authSessionID = String(action.id).trim();
+  }
+  let displayToken = "";
+  let sourceURL = "";
+  for (const rawURL of buyerAuthActionCandidateURLs(action)) {
+    try {
+      const parsed = new URL(rawURL);
+      const token = parsed.searchParams.get("display_token") || "";
+      if (token && !displayToken) displayToken = token;
+      const match = parsed.pathname.match(/(?:^|\/)(?:v1\/buyer\/auth-sessions|auth)\/([^/?#]+)(?:\/|$)/);
+      if (match && !authSessionID) authSessionID = decodeURIComponent(match[1]);
+      if (!sourceURL && (match || token)) sourceURL = rawURL;
+      if (authSessionID && displayToken) break;
+    } catch {
+      // Ignore non-URL display entries.
+    }
+  }
+  return { authSessionID, displayToken, sourceURL };
+}
+
+function buyerAuthActionCandidateURLs(action) {
+  const urls = [];
+  for (const key of ["url", "web_url", "auth_url", "oauth_start_url", "mobile_wallet_url"]) {
+    if (action?.[key]) urls.push(String(action[key]));
   }
+  const presentationDisplay = action?.presentation?.display;
+  if (Array.isArray(presentationDisplay)) {
+    for (const entry of presentationDisplay) {
+      if (entry?.url) urls.push(String(entry.url));
+    }
+  }
+  if (Array.isArray(action?.display)) {
+    for (const entry of action.display) {
+      if (entry?.url) urls.push(String(entry.url));
+    }
+  }
+  return urls;
 }
 
 function rememberCoreAuthAction(checkoutID, action) {
@@ -1351,9 +1434,9 @@ function rememberCoreAuthAction(checkoutID, action) {
   next[checkoutID] = {
     kind: "auth_qr",
     id: action.id || action.auth_session_id || parsed.authSessionID,
-    auth_session_id: action.auth_session_id || parsed.authSessionID,
-    url: action.url,
-    web_url: action.web_url || action.url,
+    auth_session_id: parsed.authSessionID,
+    url: action.url || parsed.sourceURL,
+    web_url: action.web_url || action.url || parsed.sourceURL,
     expires_at: action.expires_at || null,
     saved_at: new Date().toISOString()
   };
@@ -1487,7 +1570,7 @@ function isBuyerDeliveryComplete(result) {
 }
 
 function buyerRunOutput(value = {}) {
-  return stripInternalBuyerFields({
+  return normalizeBuyerMoneyFields(stripInternalBuyerFields({
     schema_version: "itp.buyer.v1",
     docs: value.docs || buyerDocsFor(value),
     ...value,
@@ -1496,7 +1579,29 @@ function buyerRunOutput(value = {}) {
       claim_token_included: false,
       provider_raw_payload_included: false
     }
-  });
+  }));
+}
+
+function normalizeBuyerMoneyFields(value) {
+  if (Array.isArray(value)) return value.map((item) => normalizeBuyerMoneyFields(item));
+  if (!value || typeof value !== "object") return value;
+  const next = {};
+  for (const [key, item] of Object.entries(value)) {
+    next[key] = normalizeBuyerMoneyFields(item);
+  }
+  if (
+    typeof next.amount === "number" &&
+    Number.isFinite(next.amount) &&
+    typeof next.currency === "string" &&
+    next.currency.trim()
+  ) {
+    const currency = next.currency.trim().toUpperCase();
+    next.amount_minor = Number.isInteger(next.amount) ? next.amount : Math.round(next.amount);
+    next.amount_major = Number((next.amount_minor / 100).toFixed(2));
+    next.display_amount = `${currency} ${(next.amount_minor / 100).toFixed(2)}`;
+    next.amount_unit = "minor";
+  }
+  return next;
 }
 
 function buyerDocsFor(value = {}) {
@@ -3602,7 +3707,7 @@ function coreURL(pathname, flags = {}) {
 }
 
 function coreApiBase(flags = {}) {
-  const base = flags.api_base || flags.core_api_base || process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_API_BASE || process.env.ITPAY_CORE_BASE_URL || "http://127.0.0.1:18080";
+  const base = flags.api_base || flags.core_api_base || process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_API_BASE || process.env.ITPAY_CORE_BASE_URL || "https://dev.api.itpay.ai";
   return String(base).replace(/\/$/, "");
 }
 

package/docs/agent/buyer/cart-checkout.json

@@ -53,8 +53,8 @@
     },
     {
       "intent": "add one more selected UCP Variant.id to an existing cart before checkout",
-      "command": "itp buyer cart add <cart_id> --variant <variant_id> --quantity 1 --json",
-      "success_signal": "response.cart.cart_id is unchanged and response.cart.line_items includes the new line"
+      "command": "itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --json",
+      "success_signal": "response.cart.cart_id is unchanged; response.cart.line_items either includes a new line for different input/settings or increments quantity for an identical line"
     },
     {
       "intent": "remove one line from an existing cart before checkout",
@@ -77,12 +77,15 @@
     "Before cart creation, inspect product metadata input_schema_json and collect every required input field. Do not wait until after payment to ask for required query inputs.",
     "Enterprise fuzzy search requires input.company_name. This can be a keyword, brand, short name, or partial company name supplied by the user, such as 京东.",
     "Enterprise precise lookup requires input.company_name_or_credit_no. This must be a complete China mainland registered company name or unified social credit code. If the user only provides a brand/short name, resolve the exact name first or use fuzzy search before precise lookup.",
-    "Use --input key=value for service-specific inputs. For multiple lines, prefer separate cart add commands when each line needs different input.",
+    "Use --input key=value for service-specific inputs. For multiple query lines, prefer separate cart add commands so each line locks its own input.",
+    "Cart line identity includes variant, offer, price, provider product, and normalized input. Only a completely identical line should merge by increasing quantity.",
+    "If the same variant has a different company_name, company_name_or_credit_no, page number, setting, or any other input value, it must remain a separate cart line.",
     "Before checkout create, confirm buyer email is available for secure delivery. If it is missing, ask the human for the email before checkout; do not guess or use a placeholder.",
     "Use cart_id as the checkout handoff.",
-    "Use buyer cart show whenever you need current cart contents. Do not rely on chat memory for cart state.",
+    "Use buyer cart show before changing an existing cart and whenever you need current cart contents. Do not rely on chat memory for cart state.",
     "Use buyer cart add/remove before checkout when the user changes their mind. After checkout is created, treat the cart as locked.",
     "Do not override cart line_items during checkout.",
+    "Cart, checkout, and catalog JSON money fields use minor units. For CNY, amount=10 or expected_amount=10 means CNY 0.10. Tell humans the display_amount or converted major-unit amount, never interpret amount as yuan.",
     "If the user asks for several compatible products, add them to one cart and create one checkout. Do not split into separate checkouts unless ItPay rejects the cart or says split checkout is required.",
     "If the same cart is retried, expect the same checkout unless contact/client reference changes.",
     "The backend revalidates catalog, price, and delivery requirements.",
@@ -91,7 +94,8 @@
     "Do not tell the user auth_qr is a completed payment or payment proof.",
     "For first purchase, show the ItPay auth entry as one human orchestration entry; after provider OAuth callback the same checkout exposes payment.",
     "After showing auth_qr, poll checkout or run buyer checkout resume until identity_status becomes identity_resolved and payment_intent_id appears.",
-    "When auth completes, CLI should claim and store the buyer session so a repeat purchase by the same agent/device can skip auth."
+    "When auth completes, CLI should claim and store the buyer session so a repeat purchase by the same agent/device can skip auth.",
+    "If checkout status/resume returns buyer_session.status=buyer_session_saved, the agent is now bound to that buyer account on this device. Continue with payment, delivery polling, or buyer vault commands; do not ask the human for a buyer session token."
   ],
   "forbidden": [
     "Use the UCP cart and buyer checkout commands for external-agent tests.",

package/docs/agent/buyer/catalog-search.json

@@ -47,6 +47,7 @@
     "Use stable categories: business_data_api, business_verification_api, identity_verification_api, phone_verification_api, risk_compliance_api, location_weather_api, finance_data_api.",
     "Use safe facets such as --use-case, --input-facet, --output-facet, --sensitivity-level, --delivery-mode, and --provider.",
     "Use product and variant metadata to explain options in user language.",
+    "Money values from catalog JSON use minor units. For CNY, amount=10 means CNY 0.10, not CNY 10. Prefer display_amount when present, or divide amount/amount_minor by 100 before telling the user.",
     "For products with requires_human_input=true, do not ask for identity numbers or phone numbers in chat; rely on ItPay human authorization/input.",
     "Do not create checkout until the user intent maps to one selected variant or the user confirms a cart."
   ],

package/docs/agent/buyer/human-claim-ui.json

@@ -30,12 +30,14 @@
     "The claim link is short-lived and single-use.",
     "The agent may explain that ItPay intentionally separates agent operations from raw secret access.",
     "If the human wants the agent to analyze or use the delivered result, ask them to click 'Give to Agent / 一键给 Agent' in the ItPay page and confirm with Passkey.",
-    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list ...`; do not ask the human to paste the grant id.",
+    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list --checkout <checkout_id> --json`; do not ask the human to paste the grant id. The CLI restores the buyer agent session from the checkout auth handoff when possible.",
+    "If `buyer vault grants list` returns buyer_session.status=buyer_session_saved, the agent should proceed with the returned grant list; the saved session is intentionally not printed.",
     "If the human later wants the agent to install or use something, wait for an explicit human-granted install/capability flow."
   ],
   "forbidden": [
     "Do not ask the human to paste the claim link or key into chat.",
     "Do not fetch the claim page with CLI, curl, browser automation, or an agent tool.",
+    "Do not ask the human for auth session IDs, display tokens, buyer session tokens, or portal tokens.",
     "Do not store raw content in local run files."
   ],
   "next_docs": [

package/docs/agent/buyer/product-recommendation.json

@@ -28,6 +28,7 @@
   ],
   "agent_rules": [
     "Map user intent to the variant description and price.",
+    "Catalog JSON money fields use minor units. For CNY, amount=10 means CNY 0.10 and amount=50 means CNY 0.50. Use display_amount when present, or divide by 100 before explaining price to the user.",
     "For API products, explain what the API checks or returns, quota unit, sensitivity level, required human input, and whether Passkey/WebAuthn reveal is required.",
     "If metadata says agent_may_view_raw_result=false, tell the user secure delivery/reveal is human-first and do not request the raw result.",
     "For enterprise fuzzy search, tell the user the required input is a company keyword/short name/brand. The user can say something broad like 京东; the service is designed to return candidates.",

package/docs/agent/buyer/quickstart.json

@@ -39,10 +39,12 @@
     "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.",
+    "When explaining prices, remember ItPay JSON money fields use minor units. For CNY, amount=10 means CNY 0.10. Prefer display_amount when present.",
     "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.",
+    "When a buyer command returns buyer_session.status=buyer_session_saved, the CLI has stored the buyer account session for this agent device. You may continue with checkout/payment or `buyer vault` commands without asking the human for a token.",
     "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.",

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

@@ -10,7 +10,7 @@
     "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"],
+    "needs": ["checkout_id or 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": [
@@ -37,14 +37,17 @@
   ],
   "agent_rules": [
     "Only read through `buyer vault` commands after the human has explicitly approved the agent grant in the ItPay portal.",
+    "Prefer `itp buyer vault grants list --checkout <checkout_id> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
+    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
     "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."
+    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
   ],
   "forbidden": [
+    "Do not open, click through, scrape, or automate the human web UI yourself.",
     "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 request passkey credentials, portal tokens, claim links, claim tokens, auth session IDs, display tokens, session 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."
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -67,7 +67,7 @@ itp buyer catalog get --variant <variant_id> --json
 itp buyer cart create --variant <variant_id> --json
 itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,1 --json
 itp buyer cart show <cart_id> --json
-itp buyer cart add <cart_id> --variant <variant_id> --quantity 1 --json
+itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --json
 itp buyer cart remove <cart_id> --line <cart_line_item_id> --json
 itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json
 itp buyer checkout resume <checkout_id> --json
@@ -82,10 +82,18 @@ Enterprise data products require query input at cart time:
 
 ```bash
 itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json
+itp buyer cart show <cart_id> --json
+itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --json
 itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --json
 itp buy var_itpay_enterprise_fuzzy_search_cny01 --sandbox --email <buyer_email> --input company_name=京东 --json
 ```
 
+For cart edits, always read the server cart first with `buyer cart show`.
+Cart line identity includes the variant, offer, price, provider product, and
+normalized input. A fully identical line increments quantity; a different
+company name, exact name, page number, setting, or other input must stay as a
+separate line.
+
 Use fuzzy search when the user gives a short name, brand, keyword, or uncertain
 entity. Use precise lookup only after you have the exact China mainland
 registered company name or unified social credit code. If the user says
@@ -97,9 +105,11 @@ registered name or run fuzzy search first.
 1. Use `--json` for every ItPay command.
 2. Do not invent service IDs, variant IDs, checkout IDs, payment URLs, QR URLs,
    payment intent IDs, delivery IDs, or claim links.
-3. When the user asks for several compatible services, create one cart with
-   `--variants` and one checkout. Split only when ItPay rejects the cart or
-   explicitly says split checkout is required.
+3. When the user asks for several compatible services, use one cart and one
+   checkout. Prefer `buyer cart create` for the first line, then `buyer cart
+   show` and `buyer cart add` for each additional query line so each service
+   input is locked to the correct cart line. Split only when ItPay rejects the
+   cart or explicitly says split checkout is required.
 4. Before checkout, make sure a buyer delivery email is available. If the CLI
    has no known buyer email, ask the human for the email; do not invent one,
    do not use placeholders, and do not proceed to checkout without it. The
@@ -126,8 +136,13 @@ registered name or run fuzzy search first.
    `delivery_claimable`, `check_email`, and `claim_link_sent`, but must not
    fetch or reveal protected content.
 11. If the human uses Passkey to authorize agent-readable vault access, do not
-    ask them to paste content, portal text, claim links, or grant IDs. Run
+    ask them to paste content, portal text, claim links, session tokens, auth
+    session IDs, display tokens, or grant IDs. Run
     `itp buyer vault grants list ...` and then `itp buyer vault read ...`.
+    The CLI automatically restores the buyer agent session from the checkout
+    auth handoff when possible. If the JSON includes
+    `buyer_session.status=buyer_session_saved`, continue with the returned
+    grants; the session token is intentionally stored locally and not printed.
     Use only the fields returned by that command.
 12. If the user asks you to analyze, compare, summarize, install, or otherwise
     use a delivered result, you may ask them to open the ItPay claim/account
@@ -140,6 +155,10 @@ registered name or run fuzzy search first.
     broad keyword. For enterprise precise lookup, `company_name_or_credit_no`
     must be exact; otherwise warn the user that the query may waste the paid
     lookup.
+15. Do not operate ItPay by opening the human web UI yourself. Use the CLI for
+    catalog, cart, checkout, payment wait, delivery status, grant discovery,
+    and vault reads. Browser/UI pages are for the human to scan, pay, claim,
+    reveal, and approve.
 
 ## Docs Directory