image-skill 0.1.59 → 0.1.61

package/CHANGELOG.md

@@ -4,6 +4,24 @@ This changelog tracks the public `image-skill` CLI package and public skill
 mirror. The npm package metadata remains the authority for tarball integrity and
 provenance; this file is the human- and agent-readable release map.
 
+## 0.1.61 - 2026-06-17
+
+- Release (activation/self-fund): add payment-attempt continuation actions.
+  `credits status --quote-id ...` now repeats the exact
+  `data.next_actions.recommended_buy` command for open x402/Checkout quotes,
+  and Stripe x402 buy/status responses expose
+  `data.next_actions.recommended_settlement` with exact payable-instruction
+  paths, status/quota commands, and wallet-settlement safety flags.
+
+## 0.1.60 - 2026-06-17
+
+- Release (activation/self-fund): add `credits quote --json`
+  `data.next_actions.recommended_buy`, carrying the returned `quote_id`, a
+  stable purchase idempotency key, copy-runnable buy/status commands, and
+  explicit live-money payment-attempt safety fields. Quote remains no-credit
+  and no-media; buy still requires delegated spend and verified
+  settlement/webhook fulfillment before credits are granted.
+
 ## 0.1.59 - 2026-06-17
 
 - Release (activation/self-fund): add

package/SKILL.md

@@ -178,6 +178,13 @@ that action's `command` as the next authenticated quote step. It is the ranked
 handoff to the best currently usable rail. The quote command creates a
 live-money payment object but does not move money, grant credits, debit
 credits, call a provider, or write media.
+After the quote succeeds, prefer
+`data.next_actions.recommended_buy.command`: it includes the returned
+`quote_id` and a stable non-secret purchase idempotency key. For x402 this
+creates the browserless deposit attempt whose response contains pay-to
+instructions; for Checkout this creates the human handoff URL. Use the quote
+response's `status_command` to inspect by `quote_id`, and after buy returns a
+`payment_attempt_id`, prefer `status_command_after_payment`.
 
 Credits are not granted until verified settlement or webhook fulfillment succeeds in either rail. Operator-provided promotion codes are entered on Stripe-hosted Checkout, not in the CLI. For exact bounded budgets, keep the same rail choice: use `credits quote --credits CREDITS --payment-method stripe_x402.exact.usdc` when the method is agent-settleable, and use `--payment-method stripe_checkout` only for a human Checkout fallback.
 

package/bin/image-skill.mjs

@@ -15,7 +15,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.59";
+const VERSION = "0.1.61";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -1241,7 +1241,10 @@ async function credits(argv) {
         `generated idempotency key ${idempotency.value}; pass --idempotency-key for stable retries`,
       );
     }
-    return result;
+    return withCopyRunnableCreditQuoteCommands(
+      result,
+      createGuideCommandPrefix(),
+    );
   }
   if (subcommand === "buy") {
     const args = parseArgs(rest);
@@ -1293,7 +1296,10 @@ async function credits(argv) {
         idempotency_key: idempotency.value,
       },
     });
-    return withStripeCheckoutCopyFallback(result);
+    return withCopyRunnablePaymentNextActionCommands(
+      withStripeCheckoutCopyFallback(result),
+      createGuideCommandPrefix(),
+    );
   }
   if (subcommand === "status") {
     const args = parseArgs(rest);
@@ -1313,7 +1319,10 @@ async function credits(argv) {
       path: `/v1/credit-purchases/status?${query.toString()}`,
       token: token.token,
     });
-    return withStripeCheckoutCopyFallback(result);
+    return withCopyRunnablePaymentNextActionCommands(
+      withStripeCheckoutCopyFallback(result),
+      createGuideCommandPrefix(),
+    );
   }
   return invalid(
     "image-skill credits",
@@ -2759,6 +2768,182 @@ function paymentMethodCatalogWithCopyRunnableCommands(catalog, commandPrefix) {
   };
 }
 
+function withCopyRunnableCreditQuoteCommands(result, commandPrefix) {
+  const data = result.envelope.data;
+  if (
+    data === null ||
+    typeof data !== "object" ||
+    data.next_actions === null ||
+    typeof data.next_actions !== "object"
+  ) {
+    return result;
+  }
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      data: creditQuoteWithCopyRunnableCommands(data, commandPrefix),
+    },
+  };
+}
+
+function withCopyRunnablePaymentNextActionCommands(result, commandPrefix) {
+  const data = result.envelope.data;
+  if (
+    !result.envelope.ok ||
+    data === null ||
+    typeof data !== "object" ||
+    Array.isArray(data)
+  ) {
+    return result;
+  }
+  const updated = paymentNextActionsWithCopyRunnableCommands(
+    data,
+    commandPrefix,
+  );
+  if (updated === data) {
+    return result;
+  }
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      data: updated,
+    },
+  };
+}
+
+function paymentNextActionsWithCopyRunnableCommands(data, commandPrefix) {
+  if (
+    data.next_actions === null ||
+    typeof data.next_actions !== "object" ||
+    Array.isArray(data.next_actions)
+  ) {
+    return data;
+  }
+  let changed = false;
+  const nextActions = { ...data.next_actions };
+
+  if (
+    nextActions.recommended_buy !== null &&
+    typeof nextActions.recommended_buy === "object" &&
+    !Array.isArray(nextActions.recommended_buy)
+  ) {
+    const recommendedBuy = { ...nextActions.recommended_buy };
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "buy_command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "status_command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedBuy,
+        "status_command_after_payment",
+        commandPrefix,
+      ) || changed;
+    nextActions.recommended_buy = recommendedBuy;
+  }
+
+  if (
+    nextActions.recommended_settlement !== null &&
+    typeof nextActions.recommended_settlement === "object" &&
+    !Array.isArray(nextActions.recommended_settlement)
+  ) {
+    const recommendedSettlement = { ...nextActions.recommended_settlement };
+    changed =
+      renderPaymentActionCommandField(
+        recommendedSettlement,
+        "status_command",
+        commandPrefix,
+      ) || changed;
+    changed =
+      renderPaymentActionCommandField(
+        recommendedSettlement,
+        "quota_command",
+        commandPrefix,
+      ) || changed;
+    nextActions.recommended_settlement = recommendedSettlement;
+  }
+
+  return changed ? { ...data, next_actions: nextActions } : data;
+}
+
+function renderPaymentActionCommandField(record, field, commandPrefix) {
+  if (typeof record[field] !== "string") {
+    return false;
+  }
+  const rendered = renderCopyRunnablePaymentCommand(
+    commandPrefix,
+    record[field],
+  );
+  if (rendered === record[field]) {
+    return false;
+  }
+  record[field] = rendered;
+  return true;
+}
+
+function creditQuoteWithCopyRunnableCommands(quote, commandPrefix) {
+  const recommendedBuy =
+    quote.next_actions?.recommended_buy !== null &&
+    typeof quote.next_actions?.recommended_buy === "object"
+      ? quote.next_actions.recommended_buy
+      : null;
+  if (recommendedBuy === null) {
+    return quote;
+  }
+  return {
+    ...quote,
+    next_actions: {
+      ...quote.next_actions,
+      recommended_buy: {
+        ...recommendedBuy,
+        command:
+          typeof recommendedBuy.command === "string"
+            ? renderCopyRunnablePaymentCommand(
+                commandPrefix,
+                recommendedBuy.command,
+              )
+            : recommendedBuy.command,
+        buy_command:
+          typeof recommendedBuy.buy_command === "string"
+            ? renderCopyRunnablePaymentCommand(
+                commandPrefix,
+                recommendedBuy.buy_command,
+              )
+            : recommendedBuy.buy_command,
+        status_command:
+          typeof recommendedBuy.status_command === "string"
+            ? renderCopyRunnablePaymentCommand(
+                commandPrefix,
+                recommendedBuy.status_command,
+              )
+            : recommendedBuy.status_command,
+        status_command_after_payment:
+          typeof recommendedBuy.status_command_after_payment === "string"
+            ? renderCopyRunnablePaymentCommand(
+                commandPrefix,
+                recommendedBuy.status_command_after_payment,
+              )
+            : recommendedBuy.status_command_after_payment,
+      },
+    },
+  };
+}
+
 function renderCopyRunnablePaymentCommand(commandPrefix, command) {
   if (/\bnpx\s+(?:-y|--yes)\s+image-skill@latest\b/.test(command)) {
     return command;

package/cli.md

@@ -623,14 +623,53 @@ Minimum success data:
   "idempotency_key": "quote-run-001",
   "pack_id": null,
   "pack": null,
-  "live_money": true
+  "live_money": true,
+  "next_actions": {
+    "recommended_buy": {
+      "purpose": "complete_credit_top_up",
+      "recommendation_reason": "human_checkout_handoff",
+      "quote_id": "quote_...",
+      "method_id": "stripe_checkout",
+      "provider": "stripe",
+      "command": "image-skill credits buy --provider stripe --quote-id quote_... --idempotency-key purchase:quote_... --json",
+      "buy_command_copy_runnable": true,
+      "purchase_idempotency_key": "purchase:quote_...",
+      "status_command": "image-skill credits status --quote-id quote_... --json",
+      "status_command_copy_runnable": true,
+      "status_command_after_payment": "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      "status_command_after_payment_copy_runnable": false,
+      "requires_auth": true,
+      "live_money": true,
+      "requires_browser": true,
+      "agent_settleable": false,
+      "human_handoff_required": true,
+      "command_effect": {
+        "label": "live_money_payment_attempt_requires_completion",
+        "no_spend": false,
+        "payment_attempt": true,
+        "credit_debit": false,
+        "media_write": false,
+        "wallet_settlement": false
+      }
+    }
+  }
 }
 ```
 
 For x402 quotes, `accepted_payment_method` is
 `"stripe_x402.exact.usdc"`. The quote does not grant credits or include pay-to
-instructions; `credits buy --provider stripe_x402` creates the action-required
-deposit challenge.
+instructions; `data.next_actions.recommended_buy.command` carries the returned
+`quote_id` and a stable non-secret purchase idempotency key for the
+action-required deposit attempt. Run it only when delegated spend is allowed.
+Use `data.next_actions.recommended_buy.status_command` to inspect the quote or
+payment state by `quote_id`; after buy returns a `payment_attempt_id`, prefer
+`status_command_after_payment`.
+
+When `credits status --quote-id quote_... --json` sees an open
+`stripe_x402.exact.usdc` or `stripe_checkout` quote, it repeats the exact
+`data.next_actions.recommended_buy` command with the real `quote_id` and
+`purchase:quote_...` idempotency key so agents do not need to reconstruct the
+buy step from placeholders.
 
 Hosted API equivalent:
 
@@ -710,6 +749,22 @@ Minimum x402 action-required data:
       "client_secret": "[redacted-stripe-client-secret]"
     }
   },
+  "next_actions": {
+    "recommended_settlement": {
+      "purpose": "settle_stripe_x402_credit_top_up",
+      "quote_id": "quote_...",
+      "payment_attempt_id": "payatt_...",
+      "method_id": "stripe_x402.exact.usdc",
+      "payable_instructions_path": "data.stripe_x402.payable_instructions",
+      "status_command": "image-skill credits status --payment-attempt-id payatt_... --json",
+      "quota_command": "image-skill usage quota --json",
+      "command_effect": {
+        "wallet_settlement": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
   "next": {
     "agent_action": "pay_stripe_crypto_deposit",
     "suggested_commands": [
@@ -809,6 +864,12 @@ At most one reference flag is allowed: `--quote-id`,
 `--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`. Passing no
 reference returns the balance/quota state.
 
+For Stripe x402 attempts that are still `action_required`, status responses
+include `data.next_actions.recommended_settlement` with the same exact Base/USDC
+payable instructions, a copy-runnable status command for the real
+`payment_attempt_id`, and explicit effect flags showing this is wallet
+settlement, not credit debit, media write, or provider generation work.
+
 Minimum action-required data:
 
 ```json

package/llms.txt

@@ -118,7 +118,7 @@ Hosted API endpoints:
 - GET https://api.image-skill.com/v1/quota returns durable hosted quota for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/payment-methods returns the no-auth action-only payment rail catalog. It tells agents which currently usable rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, agent_initiated, agent_settleable, settlement_blocker, limits, endpoint paths, recovery commands, and data.next_actions.recommended_quote when a currently usable live rail can be quoted next. Planned, watch-only, fake, and private harness rails are intentionally omitted.
 - GET https://api.image-skill.com/v1/credit-packs returns the public pack catalog. Recommended live-money packs include starter-500, builder-2000, and studio-5000. Packs are the default top-up UX; exact quotes remain supported for agents that already know the required credit budget.
-- POST https://api.image-skill.com/v1/credit-quotes returns a credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Use stripe_checkout for the human Checkout path. Use payment_method stripe_x402.exact.usdc only when credits methods returns it available/quoteable/purchasable/requires_browser:false; treat it as autonomous self-settlement only when agent_settleable:true is also returned. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, and live_money. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
+- POST https://api.image-skill.com/v1/credit-quotes returns a credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Use stripe_checkout for the human Checkout path. Use payment_method stripe_x402.exact.usdc only when credits methods returns it available/quoteable/purchasable/requires_browser:false; treat it as autonomous self-settlement only when agent_settleable:true is also returned. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, live_money, and data.next_actions.recommended_buy for live public rails. The recommended buy action includes the real quote_id, a stable non-secret purchase_idempotency_key, a copy-runnable buy command, a quote-id status command, and a payment-attempt status template. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-x402-deposits creates a browserless action-required USDC deposit attempt for a stripe_x402.exact.usdc quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, accepted_payment_method: stripe_x402.exact.usdc, live_money, amount_cents, stripe_x402 challenge metadata, stripe_x402.payable_instructions when Stripe returns a Base deposit address, and next.agent_action: pay_stripe_crypto_deposit. A wallet-equipped agent can pay the exact USDC token_amount_atomic to payable_instructions.deposit_address on Base. This does not grant credits; verified settlement/webhook fulfillment grants paid credits exactly once.
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-checkout-sessions creates a Stripe Checkout Session for a stripe_checkout quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, checkout_session_id, checkout_handoff_url, checkout_compact_url, checkout_url, accepted_payment_method: stripe_checkout, and next.human_action: open_checkout_url. Present checkout_handoff_url to humans because it is short and redirects to Stripe; checkout_compact_url is also copy-safe when present. If no handoff URL is available, present the full checkout_url in a code block. Do not remove the Stripe # fragment; Checkout needs it in the browser. Stripe-hosted Checkout may accept operator-provided promotion codes; humans enter them on Stripe, not in the Image Skill CLI. This does not grant credits; verified Stripe webhook fulfillment grants paid credits exactly once.
 - GET https://api.image-skill.com/v1/credit-purchases/status returns durable payment state for Authorization: Bearer TOKEN. Query with exactly one of quote_id, payment_attempt_id, checkout_session_id, or receipt_id. Response includes state, quote, payment_attempt, receipt, credit_event, provider_event, limits, and next.
@@ -196,7 +196,7 @@ Unclaimed agents may not:
 - send card data, wallet secrets, wallet private keys, seed phrases, raw x402 payment headers, provider receipts, Stripe secrets, MPP tokens, SPTs, bearer tokens, or any payment credential to Image Skill; Stripe payment details must be entered only on Stripe-hosted checkout pages
 
 Credits:
-One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability, browser/human requirements, agent_initiated, agent_settleable, and settlement_blocker. If data.next_actions.recommended_quote is present, prefer its command as the next authenticated quote step; it is a no-spend live-money quote object handoff and does not move money, grant credits, debit credits, call a provider, or write media. Always pass the returned payment method when quoting. When stripe_x402.exact.usdc is returned with available:true, quoteable:true, purchasable:true, requires_browser:false, and agent_settleable:true, image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json followed by image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json creates a browserless live deposit attempt with stripe_x402.payable_instructions. Treat live_money:true as real spend, stay inside the delegated cap, and pay exactly token_amount_atomic USDC units to payable_instructions.deposit_address on Base only from a wallet substrate you control. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json and image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json only for the Stripe Checkout human path; this returns checkout_handoff_url, copy-safe checkout_compact_url, and full Stripe checkout_url fallback and does not grant credits. Present checkout_handoff_url or checkout_compact_url to humans, especially in mobile terminals, SSH, or chat. If checkout_handoff_url is absent, present the full checkout_url in a code block and preserve the Stripe # fragment. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after settlement/checkout completion to read state, receipt, credit_event, limits, and retry guidance. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Do not silently downgrade to the cheapest model to avoid payment when the user asked for quality or is willing to pay; quote the needed credits and use an agent_settleable:true x402 rail or Stripe Checkout fallback. Credits buy requires explicit --idempotency-key. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; the public CLI generates one when omitted and returns it in the quote response, while explicit keys remain available for retry-stable automation. Inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill: no wallet private keys, seed phrases, x402 payment headers, deposit client secrets, provider receipts, card data, or Stripe secrets. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
+One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability, browser/human requirements, agent_initiated, agent_settleable, and settlement_blocker. If data.next_actions.recommended_quote is present, prefer its command as the next authenticated quote step; it is a no-spend live-money quote object handoff and does not move money, grant credits, debit credits, call a provider, or write media. Always pass the returned payment method when quoting. After a successful public live-rail quote, prefer data.next_actions.recommended_buy.command: it includes the returned quote_id and a stable non-secret purchase idempotency key, and creates or replays the matching payment attempt. When stripe_x402.exact.usdc is returned with available:true, quoteable:true, purchasable:true, requires_browser:false, and agent_settleable:true, image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json followed by the quote response's recommended_buy.command creates a browserless live deposit attempt with stripe_x402.payable_instructions. Treat live_money:true as real spend, stay inside the delegated cap, and pay exactly token_amount_atomic USDC units to payable_instructions.deposit_address on Base only from a wallet substrate you control. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json and the quote response's recommended_buy.command only for the Stripe Checkout human path; this returns checkout_handoff_url, copy-safe checkout_compact_url, and full Stripe checkout_url fallback and does not grant credits. Present checkout_handoff_url or checkout_compact_url to humans, especially in mobile terminals, SSH, or chat. If checkout_handoff_url is absent, present the full checkout_url in a code block and preserve the Stripe # fragment. Use image-skill credits status --quote-id QUOTE_ID --json before or after buy, and image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after settlement/checkout completion to read state, receipt, credit_event, limits, and retry guidance. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Do not silently downgrade to the cheapest model to avoid payment when the user asked for quality or is willing to pay; quote the needed credits and use an agent_settleable:true x402 rail or Stripe Checkout fallback. Credits buy requires explicit --idempotency-key; recommended_buy.command supplies one generated from the quote id. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; the public CLI generates one when omitted and returns it in the quote response, while explicit keys remain available for retry-stable automation. Inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill: no wallet private keys, seed phrases, x402 payment headers, deposit client secrets, provider receipts, card data, or Stripe secrets. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
 
 Telemetry:
 - command or endpoint name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "Zero-setup durable creative-media CLI for agents (image + video + audio + 3D): guide-first creation, model and cost inspection, owned URLs, JSON recovery, payments, reusable assets, and feedback.",
   "type": "module",
   "private": false,

package/skill.md

@@ -178,6 +178,13 @@ that action's `command` as the next authenticated quote step. It is the ranked
 handoff to the best currently usable rail. The quote command creates a
 live-money payment object but does not move money, grant credits, debit
 credits, call a provider, or write media.
+After the quote succeeds, prefer
+`data.next_actions.recommended_buy.command`: it includes the returned
+`quote_id` and a stable non-secret purchase idempotency key. For x402 this
+creates the browserless deposit attempt whose response contains pay-to
+instructions; for Checkout this creates the human handoff URL. Use the quote
+response's `status_command` to inspect by `quote_id`, and after buy returns a
+`payment_attempt_id`, prefer `status_command_after_payment`.
 
 Credits are not granted until verified settlement or webhook fulfillment succeeds in either rail. Operator-provided promotion codes are entered on Stripe-hosted Checkout, not in the CLI. For exact bounded budgets, keep the same rail choice: use `credits quote --credits CREDITS --payment-method stripe_x402.exact.usdc` when the method is agent-settleable, and use `--payment-method stripe_checkout` only for a human Checkout fallback.
 

package/skills/image-skill/SKILL.md

@@ -178,6 +178,13 @@ that action's `command` as the next authenticated quote step. It is the ranked
 handoff to the best currently usable rail. The quote command creates a
 live-money payment object but does not move money, grant credits, debit
 credits, call a provider, or write media.
+After the quote succeeds, prefer
+`data.next_actions.recommended_buy.command`: it includes the returned
+`quote_id` and a stable non-secret purchase idempotency key. For x402 this
+creates the browserless deposit attempt whose response contains pay-to
+instructions; for Checkout this creates the human handoff URL. Use the quote
+response's `status_command` to inspect by `quote_id`, and after buy returns a
+`payment_attempt_id`, prefer `status_command_after_payment`.
 
 Credits are not granted until verified settlement or webhook fulfillment succeeds in either rail. Operator-provided promotion codes are entered on Stripe-hosted Checkout, not in the CLI. For exact bounded budgets, keep the same rail choice: use `credits quote --credits CREDITS --payment-method stripe_x402.exact.usdc` when the method is agent-settleable, and use `--payment-method stripe_checkout` only for a human Checkout fallback.
 

package/skills/image-skill/references/cli.md

@@ -623,14 +623,53 @@ Minimum success data:
   "idempotency_key": "quote-run-001",
   "pack_id": null,
   "pack": null,
-  "live_money": true
+  "live_money": true,
+  "next_actions": {
+    "recommended_buy": {
+      "purpose": "complete_credit_top_up",
+      "recommendation_reason": "human_checkout_handoff",
+      "quote_id": "quote_...",
+      "method_id": "stripe_checkout",
+      "provider": "stripe",
+      "command": "image-skill credits buy --provider stripe --quote-id quote_... --idempotency-key purchase:quote_... --json",
+      "buy_command_copy_runnable": true,
+      "purchase_idempotency_key": "purchase:quote_...",
+      "status_command": "image-skill credits status --quote-id quote_... --json",
+      "status_command_copy_runnable": true,
+      "status_command_after_payment": "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      "status_command_after_payment_copy_runnable": false,
+      "requires_auth": true,
+      "live_money": true,
+      "requires_browser": true,
+      "agent_settleable": false,
+      "human_handoff_required": true,
+      "command_effect": {
+        "label": "live_money_payment_attempt_requires_completion",
+        "no_spend": false,
+        "payment_attempt": true,
+        "credit_debit": false,
+        "media_write": false,
+        "wallet_settlement": false
+      }
+    }
+  }
 }
 ```
 
 For x402 quotes, `accepted_payment_method` is
 `"stripe_x402.exact.usdc"`. The quote does not grant credits or include pay-to
-instructions; `credits buy --provider stripe_x402` creates the action-required
-deposit challenge.
+instructions; `data.next_actions.recommended_buy.command` carries the returned
+`quote_id` and a stable non-secret purchase idempotency key for the
+action-required deposit attempt. Run it only when delegated spend is allowed.
+Use `data.next_actions.recommended_buy.status_command` to inspect the quote or
+payment state by `quote_id`; after buy returns a `payment_attempt_id`, prefer
+`status_command_after_payment`.
+
+When `credits status --quote-id quote_... --json` sees an open
+`stripe_x402.exact.usdc` or `stripe_checkout` quote, it repeats the exact
+`data.next_actions.recommended_buy` command with the real `quote_id` and
+`purchase:quote_...` idempotency key so agents do not need to reconstruct the
+buy step from placeholders.
 
 Hosted API equivalent:
 
@@ -710,6 +749,22 @@ Minimum x402 action-required data:
       "client_secret": "[redacted-stripe-client-secret]"
     }
   },
+  "next_actions": {
+    "recommended_settlement": {
+      "purpose": "settle_stripe_x402_credit_top_up",
+      "quote_id": "quote_...",
+      "payment_attempt_id": "payatt_...",
+      "method_id": "stripe_x402.exact.usdc",
+      "payable_instructions_path": "data.stripe_x402.payable_instructions",
+      "status_command": "image-skill credits status --payment-attempt-id payatt_... --json",
+      "quota_command": "image-skill usage quota --json",
+      "command_effect": {
+        "wallet_settlement": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
   "next": {
     "agent_action": "pay_stripe_crypto_deposit",
     "suggested_commands": [
@@ -809,6 +864,12 @@ At most one reference flag is allowed: `--quote-id`,
 `--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`. Passing no
 reference returns the balance/quota state.
 
+For Stripe x402 attempts that are still `action_required`, status responses
+include `data.next_actions.recommended_settlement` with the same exact Base/USDC
+payable instructions, a copy-runnable status command for the real
+`payment_attempt_id`, and explicit effect flags showing this is wallet
+settlement, not credit debit, media write, or provider generation work.
+
 Minimum action-required data:
 
 ```json

package/skills/image-skill/references/llms.txt

@@ -118,7 +118,7 @@ Hosted API endpoints:
 - GET https://api.image-skill.com/v1/quota returns durable hosted quota for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/payment-methods returns the no-auth action-only payment rail catalog. It tells agents which currently usable rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, agent_initiated, agent_settleable, settlement_blocker, limits, endpoint paths, recovery commands, and data.next_actions.recommended_quote when a currently usable live rail can be quoted next. Planned, watch-only, fake, and private harness rails are intentionally omitted.
 - GET https://api.image-skill.com/v1/credit-packs returns the public pack catalog. Recommended live-money packs include starter-500, builder-2000, and studio-5000. Packs are the default top-up UX; exact quotes remain supported for agents that already know the required credit budget.
-- POST https://api.image-skill.com/v1/credit-quotes returns a credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Use stripe_checkout for the human Checkout path. Use payment_method stripe_x402.exact.usdc only when credits methods returns it available/quoteable/purchasable/requires_browser:false; treat it as autonomous self-settlement only when agent_settleable:true is also returned. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, and live_money. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
+- POST https://api.image-skill.com/v1/credit-quotes returns a credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Use stripe_checkout for the human Checkout path. Use payment_method stripe_x402.exact.usdc only when credits methods returns it available/quoteable/purchasable/requires_browser:false; treat it as autonomous self-settlement only when agent_settleable:true is also returned. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, live_money, and data.next_actions.recommended_buy for live public rails. The recommended buy action includes the real quote_id, a stable non-secret purchase_idempotency_key, a copy-runnable buy command, a quote-id status command, and a payment-attempt status template. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-x402-deposits creates a browserless action-required USDC deposit attempt for a stripe_x402.exact.usdc quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, accepted_payment_method: stripe_x402.exact.usdc, live_money, amount_cents, stripe_x402 challenge metadata, stripe_x402.payable_instructions when Stripe returns a Base deposit address, and next.agent_action: pay_stripe_crypto_deposit. A wallet-equipped agent can pay the exact USDC token_amount_atomic to payable_instructions.deposit_address on Base. This does not grant credits; verified settlement/webhook fulfillment grants paid credits exactly once.
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-checkout-sessions creates a Stripe Checkout Session for a stripe_checkout quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, checkout_session_id, checkout_handoff_url, checkout_compact_url, checkout_url, accepted_payment_method: stripe_checkout, and next.human_action: open_checkout_url. Present checkout_handoff_url to humans because it is short and redirects to Stripe; checkout_compact_url is also copy-safe when present. If no handoff URL is available, present the full checkout_url in a code block. Do not remove the Stripe # fragment; Checkout needs it in the browser. Stripe-hosted Checkout may accept operator-provided promotion codes; humans enter them on Stripe, not in the Image Skill CLI. This does not grant credits; verified Stripe webhook fulfillment grants paid credits exactly once.
 - GET https://api.image-skill.com/v1/credit-purchases/status returns durable payment state for Authorization: Bearer TOKEN. Query with exactly one of quote_id, payment_attempt_id, checkout_session_id, or receipt_id. Response includes state, quote, payment_attempt, receipt, credit_event, provider_event, limits, and next.
@@ -196,7 +196,7 @@ Unclaimed agents may not:
 - send card data, wallet secrets, wallet private keys, seed phrases, raw x402 payment headers, provider receipts, Stripe secrets, MPP tokens, SPTs, bearer tokens, or any payment credential to Image Skill; Stripe payment details must be entered only on Stripe-hosted checkout pages
 
 Credits:
-One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability, browser/human requirements, agent_initiated, agent_settleable, and settlement_blocker. If data.next_actions.recommended_quote is present, prefer its command as the next authenticated quote step; it is a no-spend live-money quote object handoff and does not move money, grant credits, debit credits, call a provider, or write media. Always pass the returned payment method when quoting. When stripe_x402.exact.usdc is returned with available:true, quoteable:true, purchasable:true, requires_browser:false, and agent_settleable:true, image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json followed by image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json creates a browserless live deposit attempt with stripe_x402.payable_instructions. Treat live_money:true as real spend, stay inside the delegated cap, and pay exactly token_amount_atomic USDC units to payable_instructions.deposit_address on Base only from a wallet substrate you control. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json and image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json only for the Stripe Checkout human path; this returns checkout_handoff_url, copy-safe checkout_compact_url, and full Stripe checkout_url fallback and does not grant credits. Present checkout_handoff_url or checkout_compact_url to humans, especially in mobile terminals, SSH, or chat. If checkout_handoff_url is absent, present the full checkout_url in a code block and preserve the Stripe # fragment. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after settlement/checkout completion to read state, receipt, credit_event, limits, and retry guidance. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Do not silently downgrade to the cheapest model to avoid payment when the user asked for quality or is willing to pay; quote the needed credits and use an agent_settleable:true x402 rail or Stripe Checkout fallback. Credits buy requires explicit --idempotency-key. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; the public CLI generates one when omitted and returns it in the quote response, while explicit keys remain available for retry-stable automation. Inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill: no wallet private keys, seed phrases, x402 payment headers, deposit client secrets, provider receipts, card data, or Stripe secrets. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
+One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability, browser/human requirements, agent_initiated, agent_settleable, and settlement_blocker. If data.next_actions.recommended_quote is present, prefer its command as the next authenticated quote step; it is a no-spend live-money quote object handoff and does not move money, grant credits, debit credits, call a provider, or write media. Always pass the returned payment method when quoting. After a successful public live-rail quote, prefer data.next_actions.recommended_buy.command: it includes the returned quote_id and a stable non-secret purchase idempotency key, and creates or replays the matching payment attempt. When stripe_x402.exact.usdc is returned with available:true, quoteable:true, purchasable:true, requires_browser:false, and agent_settleable:true, image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json followed by the quote response's recommended_buy.command creates a browserless live deposit attempt with stripe_x402.payable_instructions. Treat live_money:true as real spend, stay inside the delegated cap, and pay exactly token_amount_atomic USDC units to payable_instructions.deposit_address on Base only from a wallet substrate you control. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json and the quote response's recommended_buy.command only for the Stripe Checkout human path; this returns checkout_handoff_url, copy-safe checkout_compact_url, and full Stripe checkout_url fallback and does not grant credits. Present checkout_handoff_url or checkout_compact_url to humans, especially in mobile terminals, SSH, or chat. If checkout_handoff_url is absent, present the full checkout_url in a code block and preserve the Stripe # fragment. Use image-skill credits status --quote-id QUOTE_ID --json before or after buy, and image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after settlement/checkout completion to read state, receipt, credit_event, limits, and retry guidance. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Do not silently downgrade to the cheapest model to avoid payment when the user asked for quality or is willing to pay; quote the needed credits and use an agent_settleable:true x402 rail or Stripe Checkout fallback. Credits buy requires explicit --idempotency-key; recommended_buy.command supplies one generated from the quote id. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; the public CLI generates one when omitted and returns it in the quote response, while explicit keys remain available for retry-stable automation. Inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill: no wallet private keys, seed phrases, x402 payment headers, deposit client secrets, provider receipts, card data, or Stripe secrets. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
 
 Telemetry:
 - command or endpoint name