image-skill 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.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
+  `image-skill@latest`. Fresh agents that run `create --guide` now receive
+  `data.auth_handoff` templates in `auth_required` and `ready_to_create`, so a
+  one-time hosted signup token can be carried through `IMAGE_SKILL_TOKEN` or
+  `--token-stdin` without leaking it or falling back to URL installs.
+- Test: keeps the public trust-packet fixture aligned with the new npm version
+  so the release guard verifies the package, provenance, and CLI version as one
+  contract.
+
 ## 0.1.20 - 2026-06-02
 
 - Fix (funnel): the advertised `signup` usage line omitted the now-required

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.20";
+const VERSION = "0.1.22";
 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
@@ -942,6 +1007,11 @@ async function createGuide(args) {
           PUBLIC_NPX_COMMAND_PREFIX,
         )
       : null;
+  const authHandoff = createGuideAuthHandoff(stage, {
+    tokenSource: token.source,
+    nextCommand,
+    afterNext,
+  });
   return success("image-skill create --guide", {
     schema: "image-skill.create-guide.v1",
     ready: stage === "ready_to_create",
@@ -998,12 +1068,16 @@ 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,
     next_command: nextCommand,
     after_next: afterNext,
+    auth_handoff: authHandoff,
     escape_hatches: {
       doctor: renderGuidePrefixedCommand(
         PUBLIC_NPX_COMMAND_PREFIX,
@@ -1055,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" &&
@@ -1067,7 +1145,26 @@ 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) {
@@ -1172,6 +1269,47 @@ function createGuideBlocker(stage, input) {
   };
 }
 
+function createGuideAuthHandoff(stage, input) {
+  if (stage === "auth_required") {
+    return {
+      required: true,
+      token_source: "none",
+      secret_value_included: false,
+      accepted_methods: ["IMAGE_SKILL_TOKEN", "--token-stdin", "config"],
+      signup: {
+        returns_token_once: true,
+        public_cli_saves_config: false,
+        store_token_in: "agent_runtime_secret_store",
+      },
+      rerun_guide:
+        input.afterNext === null
+          ? null
+          : {
+              with_env: `IMAGE_SKILL_TOKEN="$IMAGE_SKILL_TOKEN" ${input.afterNext}`,
+              with_stdin: renderTokenStdinCommand(input.afterNext),
+            },
+      next_command: null,
+    };
+  }
+  if (stage === "ready_to_create") {
+    return {
+      required: true,
+      token_source: input.tokenSource,
+      secret_value_included: false,
+      accepted_methods: ["IMAGE_SKILL_TOKEN", "--token-stdin", "config"],
+      signup: null,
+      rerun_guide: null,
+      next_command: {
+        requires_auth: true,
+        reuse_current_auth_context: input.tokenSource,
+        with_env: `IMAGE_SKILL_TOKEN="$IMAGE_SKILL_TOKEN" ${input.nextCommand}`,
+        with_stdin: renderTokenStdinCommand(input.nextCommand),
+      },
+    };
+  }
+  return null;
+}
+
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix);
@@ -1220,6 +1358,10 @@ function renderGuideCommand(prompt, apiBaseUrl, commandPrefix = "image-skill") {
   ].join(" ");
 }
 
+function renderTokenStdinCommand(command) {
+  return `printf '%s\\n' "$IMAGE_SKILL_TOKEN" | ${command} --token-stdin`;
+}
+
 function renderCreateCommand(input) {
   return [
     input.commandPrefix ?? "image-skill",

package/cli.md

@@ -139,10 +139,16 @@ auth or payment state changes. Do not run `doctor`, `models list`, `signup`,
 checklist before the guide asks for them.
 
 - `prompt_required`: rerun `data.next_command` with the real prompt.
-- `auth_required`: run `data.next_command`, then rerun guide once.
+- `auth_required`: run `data.next_command`, store the returned token, then
+  rerun guide once. If the runtime does not automatically inject that token,
+  use `data.auth_handoff.rerun_guide.with_env` or
+  `data.auth_handoff.rerun_guide.with_stdin`.
 - `quota_required`: follow the payment commands in
   `data.checks.payments.suggested_commands`, then rerun guide once.
-- `ready_to_create`: run `data.next_command` for the first bounded create.
+- `ready_to_create`: run `data.next_command` for the first bounded create. If
+  the guide authenticated from env or stdin, prefer
+  `data.auth_handoff.next_command.with_env` or
+  `data.auth_handoff.next_command.with_stdin` so auth follows the create.
 
 Manual escape hatches are not prerequisites. Use them only when
 `data.next_command` / `data.escape_hatches` asks, or when the task genuinely
@@ -161,6 +167,9 @@ image-skill create --dry-run --prompt "a compact field camera on a stainless wor
 Use `--show-token` for hosted signup only when the runtime can immediately store
 the raw token once. For later commands, prefer `IMAGE_SKILL_TOKEN` or
 `--token-stdin`; both keep tokens out of prompts and shell history.
+`create --guide` also returns `data.auth_handoff` with copy-safe env/stdin
+templates when auth is required or when the returned create command needs the
+same auth context.
 
 ### Local Config And Install
 
@@ -257,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:
 
@@ -275,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
@@ -317,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
@@ -354,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:
 
@@ -383,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
@@ -408,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.
@@ -458,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 \
@@ -516,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`
 
@@ -651,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 \
@@ -670,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:
 
@@ -695,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