image-skill 0.1.21 → 0.1.23

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.23 - 2026-06-02
+
+- Fix (guide payments): `create --guide` now distinguishes browserless,
+  agent-payable, and human-handoff payment rails instead of collapsing the
+  payment summary into a single browser-required flag. When the hosted catalog
+  exposes `stripe_x402.exact.usdc` as available and browserless, the guide marks
+  it as the preferred method and puts the x402 quote/buy/status commands before
+  the Stripe Checkout fallback.
+- Fix (quota recovery): when an authenticated agent has no remaining credits,
+  guide mode now points `data.next_command` at the preferred credit quote command
+  instead of the generic `credits methods` inspection command.
+
+## 0.1.22 - 2026-06-02
+
+- Fix (guide): `create --guide` now reports `cost.estimated_usd_per_image` as
+  the actual Image Skill credit debit dollars, matching `estimated_credits`.
+  The guide still exposes the upstream provider estimate separately as
+  `estimated_provider_usd_per_image`, so agents no longer see a confusing
+  "17 credits but $0.10" first-run cost mismatch.
+- Fix (payment discovery): `credits methods --json` and
+  `credits packs list --json` now tolerate `--token` / `--token-stdin`.
+  Fresh agents that safely carry their signup token through stdin can inspect
+  payment rails without hitting an unsupported-flag dead end; the token is
+  drained and not forwarded to the no-auth discovery endpoint.
+
 ## 0.1.21 - 2026-06-02
 
 - Release: ships the guide auth handoff already present on main to

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.21";
+const VERSION = "0.1.23";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -32,6 +32,7 @@ const SIGNUP_SUGGESTED_COMMAND =
 const SIGNUP_CONTACT_GUIDANCE =
   "Preview signup currently requires an email-shaped durable contact inbox, not an individual human email. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. --human-email remains a compatibility alias.";
 const PUBLIC_NPX_COMMAND_PREFIX = "npx -y image-skill@latest";
+const CREDIT_UNIT_USD = 0.01;
 const PAYMENT_CREDENTIAL_FLAGS = new Set([
   "payment-token",
   "payment-secret",
@@ -547,7 +548,8 @@ async function credits(argv) {
   if (subcommand === "methods") {
     const args = parseArgs(rest);
     const unknownFlags = [...args.flags.keys()].filter(
-      (flag) => !["json", "api-base-url"].includes(flag),
+      (flag) =>
+        !["json", "api-base-url", "token", "token-stdin"].includes(flag),
     );
     if (!flagBool(args, "json")) {
       return invalid(
@@ -563,6 +565,13 @@ async function credits(argv) {
           : "credits methods does not accept positional arguments",
       );
     }
+    const tokenHandoff = await acceptNoAuthTokenHandoff(
+      args,
+      "image-skill credits methods",
+    );
+    if (tokenHandoff !== null) {
+      return tokenHandoff;
+    }
     return apiRequest({
       command: "image-skill credits methods",
       method: "GET",
@@ -579,6 +588,25 @@ async function credits(argv) {
       );
     }
     const args = parseArgs(packsRest);
+    const unknownFlags = [...args.flags.keys()].filter(
+      (flag) =>
+        !["json", "api-base-url", "token", "token-stdin"].includes(flag),
+    );
+    if (args.positionals.length > 0 || unknownFlags.length > 0) {
+      return invalid(
+        "image-skill credits packs list",
+        unknownFlags.length > 0
+          ? `unsupported flags for credits packs list: ${unknownFlags.map((flag) => `--${flag}`).join(", ")}`
+          : "credits packs list does not accept positional arguments",
+      );
+    }
+    const tokenHandoff = await acceptNoAuthTokenHandoff(
+      args,
+      "image-skill credits packs list",
+    );
+    if (tokenHandoff !== null) {
+      return tokenHandoff;
+    }
     return apiRequest({
       command: "image-skill credits packs list",
       method: "GET",
@@ -719,6 +747,33 @@ async function credits(argv) {
   );
 }
 
+async function acceptNoAuthTokenHandoff(args, command) {
+  const tokenValues = args.flags.get("token");
+  if (tokenValues !== undefined && typeof tokenValues.at(-1) !== "string") {
+    return invalid(command, "token requires a value");
+  }
+  if (flagBool(args, "token-stdin") && tokenValues !== undefined) {
+    return invalid(command, "use either --token or --token-stdin, not both");
+  }
+  if (!flagBool(args, "token-stdin")) {
+    return null;
+  }
+  if (process.stdin.isTTY) {
+    return invalid(command, "--token-stdin requires a token piped on stdin");
+  }
+  const token = (await readStdin()).trim();
+  if (token.length === 0) {
+    return failure(
+      command,
+      3,
+      "AUTH_REQUIRED",
+      "--token-stdin received empty stdin",
+      false,
+    );
+  }
+  return null;
+}
+
 async function models(argv) {
   const [subcommand, ...rest] = argv;
   const args = parseArgs(
@@ -863,6 +918,10 @@ async function createGuide(args) {
   const requestedModelId = flagString(args, "model");
   const requestedProviderId = flagString(args, "provider");
   const requestedIntent = flagString(args, "intent") ?? "explore";
+  const maxEstimatedUsdPerImage = flagNumber(
+    args,
+    "max-estimated-usd-per-image",
+  );
   const health = await apiRequest({
     command: "image-skill create --guide",
     method: "GET",
@@ -888,16 +947,22 @@ async function createGuide(args) {
 
   const selected =
     models.envelope.ok && models.envelope.data?.models
-      ? selectCreateGuideModel(models.envelope.data.models, requestedModelId)
+      ? selectCreateGuideModel(models.envelope.data.models, requestedModelId, {
+          maxEstimatedUsdPerImage,
+        })
       : null;
   const pricing = selected?.economics?.credit_pricing ?? null;
   const estimatedCredits = pricing?.credits_required ?? null;
-  const estimatedUsdPerImage =
+  const estimatedProviderUsdPerImage =
     selected?.economics?.estimated_usd_per_image ??
-    (pricing === null ? null : pricing.estimated_revenue_usd);
+    pricing?.estimated_provider_cost_usd ??
+    pricing?.fallback_provider_cost_usd ??
+    null;
+  const estimatedDebitUsdPerImage =
+    pricing?.estimated_revenue_usd ?? estimatedProviderUsdPerImage;
   const budgetGuard =
-    flagNumber(args, "max-estimated-usd-per-image") ??
-    estimatedUsdPerImage ??
+    maxEstimatedUsdPerImage ??
+    estimatedDebitUsdPerImage ??
     (estimatedCredits === null ? 0.07 : estimatedCredits / 100);
   const quota =
     token.token === null
@@ -1003,7 +1068,10 @@ async function createGuide(args) {
           },
     cost: {
       estimated_credits: estimatedCredits,
-      estimated_usd_per_image: estimatedUsdPerImage,
+      estimated_usd_per_image: estimatedDebitUsdPerImage,
+      estimated_debit_usd_per_image: estimatedDebitUsdPerImage,
+      estimated_provider_usd_per_image: estimatedProviderUsdPerImage,
+      credit_unit_usd: pricing?.credit_unit_usd ?? CREDIT_UNIT_USD,
       pricing_confidence: pricing?.pricing_confidence ?? null,
     },
     blocker,
@@ -1061,7 +1129,11 @@ async function createGuide(args) {
   });
 }
 
-function selectCreateGuideModel(models, requestedModelId) {
+function selectCreateGuideModel(
+  models,
+  requestedModelId,
+  { maxEstimatedUsdPerImage = null } = {},
+) {
   const isExecutableCreate = (model) =>
     model?.status === "available" &&
     model?.execution?.model_execution_status === "executable" &&
@@ -1073,35 +1145,97 @@ function selectCreateGuideModel(models, requestedModelId) {
       ? requested
       : null;
   }
-  return models.find(isExecutableCreate) ?? null;
+  const candidates = models.filter(isExecutableCreate);
+  if (maxEstimatedUsdPerImage === null) {
+    return candidates[0] ?? null;
+  }
+  const capped = candidates.filter((model) => {
+    const estimatedUsd = guideBudgetUsdForModel(model);
+    return estimatedUsd === null || estimatedUsd <= maxEstimatedUsdPerImage;
+  });
+  return (capped.length === 0 ? candidates : capped)[0] ?? null;
+}
+
+function guideBudgetUsdForModel(model) {
+  const pricing = model?.economics?.credit_pricing ?? null;
+  return (
+    pricing?.estimated_revenue_usd ??
+    model?.economics?.estimated_usd_per_image ??
+    pricing?.estimated_provider_cost_usd ??
+    pricing?.fallback_provider_cost_usd ??
+    null
+  );
 }
 
 function createGuidePaymentSummary(data) {
   const methods = Array.isArray(data?.methods)
     ? data.methods.filter((method) => method.live_money)
     : [];
+  const availableMethods = methods.filter((method) => method.available);
+  const browserlessMethods = availableMethods.filter(
+    (method) => method.requires_browser === false,
+  );
+  const agentPayableMethods = browserlessMethods.filter((method) =>
+    (method.buyer_modes ?? []).some(
+      (mode) => mode === "agent_only" || mode === "hybrid",
+    ),
+  );
+  const humanHandoffMethods = availableMethods.filter(
+    (method) =>
+      method.requires_browser === true ||
+      (method.buyer_modes ?? []).some((mode) => mode === "human_only"),
+  );
+  const preferredMethod =
+    agentPayableMethods[0] ?? browserlessMethods[0] ?? availableMethods[0];
   return {
     checked: data !== null && typeof data === "object",
-    live_money_methods: methods
-      .filter((method) => method.available)
-      .map((method) => method.method_id),
-    requires_browser: methods.some((method) => method.requires_browser),
+    live_money_methods: availableMethods.map((method) => method.method_id),
+    requires_browser:
+      availableMethods.length > 0 &&
+      availableMethods.every((method) => method.requires_browser === true),
+    browserless_methods: browserlessMethods.map((method) => method.method_id),
+    agent_payable_methods: agentPayableMethods.map(
+      (method) => method.method_id,
+    ),
+    human_handoff_methods: humanHandoffMethods.map(
+      (method) => method.method_id,
+    ),
+    preferred_method: preferredMethod?.method_id ?? null,
     buyer_modes: [
       ...new Set(methods.flatMap((method) => method.buyer_modes ?? [])),
     ],
-    suggested_commands: [
-      "image-skill credits methods --json",
-      "image-skill credits packs list --json",
-      methods[0]?.recovery?.quote_command ??
-        "image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json",
-      methods[0]?.recovery?.purchase_command ??
-        "image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json",
-      methods[0]?.recovery?.status_command ??
-        "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
-    ],
+    suggested_commands: createGuidePaymentCommands(
+      preferredMethod,
+      availableMethods.filter((method) => method !== preferredMethod),
+    ),
   };
 }
 
+function createGuidePaymentCommands(preferredMethod, fallbackMethods) {
+  const commands = [
+    "image-skill credits methods --json",
+    "image-skill credits packs list --json",
+    preferredMethod?.recovery?.quote_command ??
+      "image-skill credits quote --pack starter-500 --payment-method stripe_x402.exact.usdc --idempotency-key KEY --json",
+    preferredMethod?.recovery?.purchase_command ??
+      "image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+    preferredMethod?.recovery?.status_command ??
+      "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+  ];
+  for (const method of fallbackMethods) {
+    for (const command of [
+      method.recovery?.quote_command,
+      method.recovery?.purchase_command,
+      method.recovery?.status_command,
+    ]) {
+      if (typeof command === "string" && !commands.includes(command)) {
+        commands.push(command);
+      }
+    }
+  }
+  return commands;
+}
+
 function createGuideStage(input) {
   if (input.prompt.length === 0) {
     return "prompt_required";
@@ -1238,7 +1372,9 @@ function createGuideNextCommand(stage, input) {
   if (stage === "quota_required") {
     return renderGuidePrefixedCommand(
       input.commandPrefix,
-      stripImageSkillCommandPrefix(input.paymentSummary.suggested_commands[0]),
+      stripImageSkillCommandPrefix(
+        firstPaymentActionCommand(input.paymentSummary.suggested_commands),
+      ),
     );
   }
   return renderCreateCommand({
@@ -1271,6 +1407,16 @@ function renderTokenStdinCommand(command) {
   return `printf '%s\\n' "$IMAGE_SKILL_TOKEN" | ${command} --token-stdin`;
 }
 
+function firstPaymentActionCommand(commands) {
+  return (
+    commands.find((command) => /\bcredits\s+quote\b/.test(command)) ??
+    commands.find((command) => /\bcredits\s+buy\b/.test(command)) ??
+    commands.find((command) => /\bcredits\s+methods\b/.test(command)) ??
+    commands[0] ??
+    "image-skill credits methods --json"
+  );
+}
+
 function renderCreateCommand(input) {
   return [
     input.commandPrefix ?? "image-skill",

package/cli.md

@@ -266,15 +266,28 @@ Minimum success data shape:
       "requires_browser": true,
       "default_pack_id": "starter-500",
       "purchase_endpoint": "/v1/credit-purchases/stripe-checkout-sessions"
+    },
+    {
+      "method_id": "stripe_x402.exact.usdc",
+      "status": "available",
+      "available": true,
+      "quoteable": true,
+      "purchasable": true,
+      "live_money": true,
+      "buyer_modes": ["agent_only", "hybrid"],
+      "requires_browser": false,
+      "default_pack_id": "starter-500",
+      "purchase_endpoint": "/v1/credit-purchases/stripe-x402-deposits"
     }
   ]
 }
 ```
 
-Public payment discovery is intentionally action-only. Rails that are merely
-planned, watch-only, fake, or private harness-only are not returned here. Use a
-method only when it is returned with `available:true`, `quoteable:true`, and
-`purchasable:true`.
+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`.
 
 Hosted API equivalent:
 
@@ -284,10 +297,13 @@ curl -sS https://api.image-skill.com/v1/payment-methods
 
 ### `image-skill credits packs list`
 
-Lists the recommended Image Skill credit packs for Stripe Checkout. Packs are
-the default live-money buying UX because agents get obvious starter choices and
-Stripe Checkout avoids tiny card-fee traps. Exact custom quotes are still
-supported when an agent already knows the required credit budget.
+Lists the recommended Image Skill credit packs. Packs are the default
+live-money buying UX because agents get obvious starter choices and avoid tiny
+fee traps. Use the payment method catalog to choose the rail: browserless
+`stripe_x402.exact.usdc` when it is available for agent self-funding, or
+`stripe_checkout` when a human sponsor needs a Checkout handoff. Exact custom
+quotes are still supported when an agent already knows the required credit
+budget.
 
 ```bash
 image-skill credits packs list --json
@@ -326,8 +342,10 @@ curl -sS https://api.image-skill.com/v1/credit-packs
 
 ### `image-skill credits quote`
 
-Requests a bounded credit quote from the hosted service. Public top-ups use
-Stripe Checkout with `--payment-method stripe_checkout`. A quote never grants
+Requests a bounded credit quote from the hosted service. Public top-ups use the
+payment method returned by `credits methods --json`: `stripe_x402.exact.usdc`
+for browserless agent self-funding when it is available, or
+`stripe_checkout` for the human Checkout fallback. A quote never grants
 credits.
 One Image Skill credit is a stable user-facing value unit worth `$0.01`.
 Creative operations can consume more than one credit based on the selected
@@ -363,6 +381,17 @@ image-skill credits quote \
   --json
 ```
 
+For the browserless agent x402 rail, quote the exact method id returned by
+`credits methods --json`:
+
+```bash
+image-skill credits quote \
+  --pack starter-500 \
+  --payment-method stripe_x402.exact.usdc \
+  --idempotency-key agent-x402-quote-run-001 \
+  --json
+```
+
 For exact custom Stripe Checkout terms, request the provider and bounded credit
 amount explicitly:
 
@@ -392,22 +421,77 @@ Minimum success data:
 }
 ```
 
+For x402 quotes, `accepted_payment_method` is
+`"stripe_x402.exact.usdc"` and the response includes redacted
+`quote.x402` metadata for the agent-payable deposit flow.
+
 Hosted API equivalent:
 
 ```bash
 curl -sS https://api.image-skill.com/v1/credit-quotes \
   -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
   -H "content-type: application/json" \
-  -d '{"pack_id":"starter-500","payment_method":"stripe_checkout","idempotency_key":"stripe-pack-quote-run-001"}'
+  -d '{"pack_id":"starter-500","payment_method":"stripe_x402.exact.usdc","idempotency_key":"agent-x402-quote-run-001"}'
 ```
 
 ### `image-skill credits buy`
 
-Creates a payment action for a previously returned quote. Stripe Checkout is the
-first live-money provider. This creates a hosted Stripe Checkout Session and
-returns an `action_required` response with `checkout_handoff_url`; credits are
-granted only after verified Stripe webhook fulfillment succeeds. Session
-creation itself must not mutate credit balances.
+Creates a payment action for a previously returned quote. Choose the provider
+that matches the quote's `accepted_payment_method`.
+
+For a `stripe_x402.exact.usdc` quote, `--provider stripe_x402` creates a
+browserless agent-payable USDC deposit challenge. The response is live money
+when `live_money:true`; credits are granted only after verified settlement and
+webhook fulfillment succeeds. Deposit challenge creation itself must not mutate
+credit balances. Stay within the delegated cap and never pass wallet private
+keys, seed phrases, x402 payment headers, deposit client secrets, or provider
+receipts to Image Skill.
+
+```bash
+image-skill credits buy \
+  --provider stripe_x402 \
+  --quote-id quote_... \
+  --idempotency-key agent-x402-buy-run-001 \
+  --json
+```
+
+Minimum x402 action-required data:
+
+```json
+{
+  "state": "action_required",
+  "quote_id": "quote_...",
+  "payment_attempt_id": "payatt_...",
+  "provider": "stripe",
+  "accepted_payment_method": "stripe_x402.exact.usdc",
+  "credits": 500,
+  "amount_cents": 500,
+  "currency": "USD",
+  "live_money": true,
+  "stripe_x402": {
+    "method_id": "stripe_x402.exact.usdc",
+    "scheme": "exact",
+    "network": "base",
+    "token_currency": "usdc",
+    "deposit_address_present": true,
+    "redacted": {
+      "payment_intent_id": "[redacted-stripe-payment-intent]",
+      "deposit_address": "[redacted-stripe-crypto-deposit-address]",
+      "client_secret": "[redacted-stripe-client-secret]"
+    }
+  },
+  "next": {
+    "agent_action": "pay_stripe_crypto_deposit",
+    "suggested_commands": [
+      "image-skill credits status --payment-attempt-id payatt_... --json"
+    ]
+  }
+}
+```
+
+For a `stripe_checkout` quote, `--provider stripe` creates a hosted Stripe
+Checkout Session and returns an `action_required` response with
+`checkout_handoff_url`.
 
 Agents should present or open `checkout_handoff_url` for humans. It is a short
 Image Skill URL that redirects to Stripe Checkout and is safe to copy from
@@ -417,8 +501,7 @@ provide one. `checkout_url` is the raw Stripe compatibility fallback only; do
 not present it unless no handoff URL is available. Do not trim Stripe Checkout
 URLs: the long `#...` fragment is required by Stripe Checkout in the browser.
 Present any fallback Stripe URL in a fenced code block so terminal wrapping does
-not corrupt it.
-Stripe-hosted Checkout may also show a promotion-code field for
+not corrupt it. Stripe-hosted Checkout may also show a promotion-code field for
 operator-provided codes; agents should let the human enter those codes on
 Stripe, never collect promo codes, card details, or wallet credentials in the
 Image Skill CLI.
@@ -467,11 +550,20 @@ curl -sS https://api.image-skill.com/v1/credit-purchases/stripe-checkout-session
   -d '{"quote_id":"quote_...","idempotency_key":"stripe-buy-run-001"}'
 ```
 
+x402 hosted API equivalent:
+
+```bash
+curl -sS https://api.image-skill.com/v1/credit-purchases/stripe-x402-deposits \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"quote_id":"quote_...","idempotency_key":"agent-x402-buy-run-001"}'
+```
+
 ### `image-skill credits status`
 
-Shows the durable state of a quote, Stripe Checkout attempt, Checkout Session,
-or receipt. Use this after `credits buy` so agents do not have to infer payment
-state from quota deltas or activity text.
+Shows the durable state of a quote, x402 deposit attempt, Stripe Checkout
+attempt, Checkout Session, or receipt. Use this after `credits buy` so agents
+do not have to infer payment state from quota deltas or activity text.
 
 ```bash
 image-skill credits status \
@@ -525,10 +617,13 @@ curl -sS "https://api.image-skill.com/v1/credit-purchases/status?payment_attempt
 ```
 
 Do not pass card data, wallet secrets, provider receipts, Stripe secrets, MPP
-tokens, SPTs, live x402 payment headers, or any payment credential to credits
-commands. Stripe Checkout collects payment details only on Stripe-hosted pages.
-The public request fields are `credits`, `pack_id`, `payment_method`,
-`quote_id`, status reference IDs, and `idempotency_key`.
+tokens, SPTs, live x402 payment headers, deposit client secrets, wallet
+private keys, seed phrases, or any payment credential to credits commands.
+Stripe Checkout collects payment details only on Stripe-hosted pages; x402
+settlement is handled by the agent/wallet against the returned redacted deposit
+challenge, not by pasting credentials into Image Skill. The public request
+fields are `credits`, `pack_id`, `payment_method`, `quote_id`, status reference
+IDs, and `idempotency_key`.
 
 ### `image-skill models`
 
@@ -660,6 +755,12 @@ image-skill create --guide --prompt "A compact field camera on a stainless workb
 auth/quota/payment blockers, and mutation flags. All mutation flags must be
 false in guide mode: no provider call, hosted create, signup, payment object,
 credit debit, or media write.
+In guide cost output, `cost.estimated_usd_per_image` is the estimated Image
+Skill debit in dollars for one output, matching
+`cost.estimated_debit_usd_per_image` and
+`cost.estimated_credits * cost.credit_unit_usd` when credit pricing is known.
+`cost.estimated_provider_usd_per_image` is the upstream provider estimate for
+transparency; do not use it as the amount the agent needs to fund.
 
 ```bash
 image-skill create \
@@ -679,10 +780,9 @@ intents, Image Skill may default an eligible quality-capability request to a
 higher output tier only when `--max-estimated-usd-per-image` is high enough for
 that tier; otherwise it stays on a lower-cost quality tier or chooses a cheaper
 capability within the budget and tells agents what happened in the selection
-receipt.
-Use `0.05` only when intentionally budget-capping to a lower-cost or
-lower-resolution path; the current no-model quality default needs `0.07` to
-permit the 2k plan.
+receipt. Use the `--max-estimated-usd-per-image` value returned by
+`create --guide`; it is sized to the Image Skill credit debit, not only the
+upstream provider estimate.
 
 Preview-compatible richer shape:
 
@@ -704,7 +804,8 @@ top-level Image Skill create control; do not pass provider-native `n` through
 `model_parameters` unless the selected model schema explicitly advertises that
 field. Credit pricing and `cost.credit_pricing.credits_required` are total
 operation debits across all requested outputs. `--max-estimated-usd-per-image`
-and raw API `max_estimated_usd_per_image` remain per-image budget guards.
+and raw API `max_estimated_usd_per_image` are per-image Image Skill debit
+budget guards.
 
 Generate video through the same `create` command and durable-media loop. Because
 the no-model default selects an image model, request a video model by id; the