image-skill 0.1.58 → 0.1.60

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.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
+  `credits methods --json` `data.next_actions.recommended_quote`, a ranked
+  copy-runnable quote handoff that prefers browserless agent-settleable x402
+  when available and falls back to Stripe Checkout when that is the only usable
+  live rail. The quote step is explicitly no-spend: it creates a live-money
+  payment object but does not move money, grant credits, debit credits, call a
+  provider, or write media.
+
 ## 0.1.58 - 2026-06-17
 
 - Release (activation/self-fund): mirror top-up urgency and the no-spend

package/SKILL.md

@@ -173,6 +173,19 @@ One Image Skill credit is `$0.01`. Operation debits are model-priced, not flat.
 | Same rail with `agent_settleable:false` but `purchasable:true`                                                                              | The rail is quoteable but settlement still needs a wallet substrate you do not have. Skip to Stripe Checkout.                                                                                                                                                  |
 | Only `stripe_checkout` available                                                                                                            | Quote with `--payment-method stripe_checkout`, then `credits buy --provider stripe` returns `checkout_handoff_url`. Hand that URL to a human sponsor. Do not strip the Stripe `#...` fragment if you fall back to the full `checkout_url`.                     |
 
+If `credits methods --json` returns `data.next_actions.recommended_quote`, use
+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.
 
 At any guide stage, read `data.checks.quota.top_up`: when `recommended` is

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.58";
+const VERSION = "0.1.60";
 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);
@@ -2675,8 +2678,55 @@ function withCopyRunnablePaymentMethodCommands(result, commandPrefix) {
 }
 
 function paymentMethodCatalogWithCopyRunnableCommands(catalog, commandPrefix) {
+  const nextActions =
+    catalog.next_actions !== null && typeof catalog.next_actions === "object"
+      ? catalog.next_actions
+      : null;
+  const recommendedQuote =
+    nextActions?.recommended_quote !== null &&
+    typeof nextActions?.recommended_quote === "object"
+      ? nextActions.recommended_quote
+      : null;
   return {
     ...catalog,
+    ...(recommendedQuote === null
+      ? {}
+      : {
+          next_actions: {
+            ...nextActions,
+            recommended_quote: {
+              ...recommendedQuote,
+              command:
+                typeof recommendedQuote.command === "string"
+                  ? renderCopyRunnablePaymentCommand(
+                      commandPrefix,
+                      recommendedQuote.command,
+                    )
+                  : recommendedQuote.command,
+              quote_command:
+                typeof recommendedQuote.quote_command === "string"
+                  ? renderCopyRunnablePaymentCommand(
+                      commandPrefix,
+                      recommendedQuote.quote_command,
+                    )
+                  : recommendedQuote.quote_command,
+              buy_command:
+                typeof recommendedQuote.buy_command === "string"
+                  ? renderCopyRunnablePaymentCommand(
+                      commandPrefix,
+                      recommendedQuote.buy_command,
+                    )
+                  : recommendedQuote.buy_command,
+              status_command:
+                typeof recommendedQuote.status_command === "string"
+                  ? renderCopyRunnablePaymentCommand(
+                      commandPrefix,
+                      recommendedQuote.status_command,
+                    )
+                  : recommendedQuote.status_command,
+            },
+          },
+        }),
     methods: Array.isArray(catalog.methods)
       ? catalog.methods.map((method) => ({
           ...method,
@@ -2712,6 +2762,73 @@ 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 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

@@ -421,6 +421,29 @@ Minimum success data shape:
   "quote_endpoint": "/v1/credit-quotes",
   "packs_endpoint": "/v1/credit-packs",
   "status_endpoint": "/v1/credit-purchases/status",
+  "next_actions": {
+    "recommended_quote": {
+      "purpose": "quote_credit_top_up",
+      "recommendation_reason": "browserless_agent_self_fund",
+      "method_id": "stripe_x402.exact.usdc",
+      "pack_id": "starter-500",
+      "command": "image-skill credits quote --pack starter-500 --payment-method stripe_x402.exact.usdc --json",
+      "quote_command_copy_runnable": true,
+      "buy_command": "image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+      "status_command": "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      "requires_auth": true,
+      "live_money": true,
+      "requires_browser": false,
+      "agent_settleable": true,
+      "command_effect": {
+        "label": "live_money_quote_no_charge",
+        "no_spend": true,
+        "payment_object": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
   "methods": [
     {
       "method_id": "stripe_checkout",
@@ -460,7 +483,10 @@ Public payment discovery is intentionally action-first. Limited-rollout rails
 may be returned with `available:false`, `quoteable:false`, `purchasable:false`,
 and a non-null `unavailable_reason` so headless agents can understand the path
 without trying it. Use a method only when it is returned with `available:true`,
-`quoteable:true`, and `purchasable:true`.
+`quoteable:true`, and `purchasable:true`. When
+`next_actions.recommended_quote` is present, prefer its `command` as the next
+authenticated quote step; it creates a live-money payment object but does not
+move money, grant credits, debit credits, call a provider, or write media.
 
 Hosted API equivalent:
 
@@ -597,14 +623,47 @@ 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`.
 
 Hosted API equivalent:
 

package/llms.txt

@@ -116,9 +116,9 @@ Hosted API endpoints:
 - POST https://api.image-skill.com/v1/agent-claims attaches an email-shaped durable contact inbox to the authenticated agent after an (often anonymous) signup. Request JSON is {"contact": INBOX}. Re-sending the same contact is idempotent (data.state unchanged); a different contact replaces the previous one (data.state attached). Attaching a contact is not inbox-ownership verification: data.claim_state stays unclaimed and data.claim_request_state reports requested. The response echoes only a redacted contact.
 - GET https://api.image-skill.com/v1/whoami returns durable hosted identity for Authorization: Bearer TOKEN.
 - 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, and recovery commands. Planned, watch-only, fake, and private harness rails are intentionally omitted.
+- 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. 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.58",
+  "version": "0.1.60",
   "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

@@ -173,6 +173,19 @@ One Image Skill credit is `$0.01`. Operation debits are model-priced, not flat.
 | Same rail with `agent_settleable:false` but `purchasable:true`                                                                              | The rail is quoteable but settlement still needs a wallet substrate you do not have. Skip to Stripe Checkout.                                                                                                                                                  |
 | Only `stripe_checkout` available                                                                                                            | Quote with `--payment-method stripe_checkout`, then `credits buy --provider stripe` returns `checkout_handoff_url`. Hand that URL to a human sponsor. Do not strip the Stripe `#...` fragment if you fall back to the full `checkout_url`.                     |
 
+If `credits methods --json` returns `data.next_actions.recommended_quote`, use
+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.
 
 At any guide stage, read `data.checks.quota.top_up`: when `recommended` is

package/skills/image-skill/SKILL.md

@@ -173,6 +173,19 @@ One Image Skill credit is `$0.01`. Operation debits are model-priced, not flat.
 | Same rail with `agent_settleable:false` but `purchasable:true`                                                                              | The rail is quoteable but settlement still needs a wallet substrate you do not have. Skip to Stripe Checkout.                                                                                                                                                  |
 | Only `stripe_checkout` available                                                                                                            | Quote with `--payment-method stripe_checkout`, then `credits buy --provider stripe` returns `checkout_handoff_url`. Hand that URL to a human sponsor. Do not strip the Stripe `#...` fragment if you fall back to the full `checkout_url`.                     |
 
+If `credits methods --json` returns `data.next_actions.recommended_quote`, use
+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.
 
 At any guide stage, read `data.checks.quota.top_up`: when `recommended` is

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

@@ -421,6 +421,29 @@ Minimum success data shape:
   "quote_endpoint": "/v1/credit-quotes",
   "packs_endpoint": "/v1/credit-packs",
   "status_endpoint": "/v1/credit-purchases/status",
+  "next_actions": {
+    "recommended_quote": {
+      "purpose": "quote_credit_top_up",
+      "recommendation_reason": "browserless_agent_self_fund",
+      "method_id": "stripe_x402.exact.usdc",
+      "pack_id": "starter-500",
+      "command": "image-skill credits quote --pack starter-500 --payment-method stripe_x402.exact.usdc --json",
+      "quote_command_copy_runnable": true,
+      "buy_command": "image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+      "status_command": "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      "requires_auth": true,
+      "live_money": true,
+      "requires_browser": false,
+      "agent_settleable": true,
+      "command_effect": {
+        "label": "live_money_quote_no_charge",
+        "no_spend": true,
+        "payment_object": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
   "methods": [
     {
       "method_id": "stripe_checkout",
@@ -460,7 +483,10 @@ Public payment discovery is intentionally action-first. Limited-rollout rails
 may be returned with `available:false`, `quoteable:false`, `purchasable:false`,
 and a non-null `unavailable_reason` so headless agents can understand the path
 without trying it. Use a method only when it is returned with `available:true`,
-`quoteable:true`, and `purchasable:true`.
+`quoteable:true`, and `purchasable:true`. When
+`next_actions.recommended_quote` is present, prefer its `command` as the next
+authenticated quote step; it creates a live-money payment object but does not
+move money, grant credits, debit credits, call a provider, or write media.
 
 Hosted API equivalent:
 
@@ -597,14 +623,47 @@ 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`.
 
 Hosted API equivalent:
 

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

@@ -116,9 +116,9 @@ Hosted API endpoints:
 - POST https://api.image-skill.com/v1/agent-claims attaches an email-shaped durable contact inbox to the authenticated agent after an (often anonymous) signup. Request JSON is {"contact": INBOX}. Re-sending the same contact is idempotent (data.state unchanged); a different contact replaces the previous one (data.state attached). Attaching a contact is not inbox-ownership verification: data.claim_state stays unclaimed and data.claim_request_state reports requested. The response echoes only a redacted contact.
 - GET https://api.image-skill.com/v1/whoami returns durable hosted identity for Authorization: Bearer TOKEN.
 - 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, and recovery commands. Planned, watch-only, fake, and private harness rails are intentionally omitted.
+- 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. 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