image-skill 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.
 
+## Unreleased
+
+## 0.1.25 - 2026-06-02
+
+- Fix (activation): `create --guide` now probes whether the public CLI auth
+  config path can actually be written before telling a fresh agent to run a
+  config-saving signup. If the default path is blocked, the guide returns the
+  browserless `signup --show-token --no-save --json` fallback plus
+  `--token-stdin` rerun/create templates, so read-only or workspace-scoped
+  runtimes can continue without losing the one-time hosted token.
+- Fix (recovery copy): hosted signup config-write recovery now points agents at
+  a fresh `signup --agent ... --show-token` command instead of the local-only
+  `auth save` command, keeping the suggested recovery path valid for the hosted
+  public CLI.
+
+## 0.1.24 - 2026-06-02
+
+- Fix (activation): hosted `signup --agent` now saves the restricted token to
+  the public CLI config by default with `0600` permissions, while keeping the
+  raw token hidden unless `--show-token` is explicitly requested. Fresh agents
+  can run the guide's signup command, then continue with `whoami`, feedback,
+  credits, create, or edit from saved config instead of juggling a one-time
+  token through shell scope. `--show-token --no-save` remains available for
+  runtimes with their own secret store.
+- Feature (x402 self-fund): `credits buy --provider stripe_x402` now returns
+  `stripe_x402.payable_instructions` when Stripe provides a Base crypto deposit
+  address. Wallet-equipped agents get the exact USDC amount, atomic units,
+  Base deposit address, optional token contract, expiry, and exact-amount flag
+  needed to settle without a browser; Stripe PaymentIntent ids and client
+  secrets remain redacted.
+- Fix (payment readiness): `credits methods --json`, `create --guide`, public
+  skill docs, and the scoreboard now distinguish `agent_initiated` from
+  `agent_settleable`. A redacted browserless x402 deposit attempt is no longer
+  treated as autonomous self-fund ready unless the hosted catalog explicitly
+  reports `agent_settleable:true`; until then the guide prefers the Stripe
+  Checkout path that can actually be completed.
+
 ## 0.1.23 - 2026-06-02
 
 - Fix (guide payments): `create --guide` now distinguishes browserless,

package/README.md

@@ -85,18 +85,20 @@ Release notes live in
 Detailed package verification steps live in
 [`PROVENANCE.md`](https://github.com/danielgwilson/image-skill-cli/blob/main/PROVENANCE.md).
 
-Hosted signup returns the raw `isk_r_` token only when `--show-token` is set,
-and only once. Store it immediately in the agent runtime secret store, then use
-`IMAGE_SKILL_TOKEN` or `--token-stdin` for later hosted commands. The hosted
-public CLI does not auto-save signup auth into the local config. Use
-`image-skill auth save --json` only when a runtime intentionally wants a local
-0600 compatibility config.
+Hosted signup saves the restricted `isk_r_` token to the local public CLI
+config by default with `0600` permissions, so later hosted commands can
+authenticate without repeating signup. The raw token is returned only when
+`--show-token` is set, and only once. Use `--show-token --no-save` when a
+runtime intentionally wants to store the token somewhere else.
+`create --guide` checks whether the configured auth path is writable before it
+suggests a signup command; if not, it returns the `--show-token --no-save`
+fallback plus `--token-stdin` rerun guidance.
 
 Fresh sandboxes should prefer:
 
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
-npx -y image-skill@latest signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name creative-agent --runtime openclaw --show-token --json
+npx -y image-skill@latest signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name creative-agent --runtime openclaw --json
 ```
 
 If npm prefix/cache paths are read-only, set `npm_config_cache` and

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.23";
+const VERSION = "0.1.25";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -28,7 +28,7 @@ const DEFAULT_CONFIG_PATH = join(
   "config.json",
 );
 const SIGNUP_SUGGESTED_COMMAND =
-  "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --show-token --json";
+  "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json";
 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";
@@ -75,7 +75,7 @@ async function main(rawArgv) {
       commands: [
         "doctor",
         "trust",
-        "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME --show-token",
+        "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
         "auth status",
         "auth save",
         "auth logout",
@@ -346,21 +346,22 @@ async function signup(argv) {
       },
     );
   }
-  const saveRequested = flagBool(args, "save");
   const showToken = flagBool(args, "show-token");
-  if (saveRequested) {
-    return failure(
+  const noSave = flagBool(args, "no-save");
+  const saveRequested = flagBool(args, "save");
+  if (saveRequested && noSave) {
+    return invalid(
       "image-skill signup",
-      2,
-      "INVALID_ARGUMENTS",
-      "signup --save is not available on the hosted public CLI; use --show-token once and store the token in the agent runtime secret store",
-      false,
-      {
-        suggested_command: SIGNUP_SUGGESTED_COMMAND,
-        docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
-      },
+      "use either --save or --no-save, not both",
     );
   }
+  const shouldSave = !noSave;
+  if (shouldSave) {
+    const configReady = await assertConfigWritable("image-skill signup");
+    if (!configReady.ok) {
+      return configReady.result;
+    }
+  }
   const result = await apiRequest({
     command: "image-skill signup",
     method: "POST",
@@ -370,7 +371,7 @@ async function signup(argv) {
       agent_contact: contact.value,
       agent_name: agentName,
       runtime,
-      return_token: showToken,
+      return_token: shouldSave || showToken,
     },
   });
   result.envelope.command = "image-skill signup";
@@ -378,9 +379,39 @@ async function signup(argv) {
 
   const token = result.envelope.data?.token;
   const warnings = [...result.envelope.warnings];
+  if (result.envelope.ok && shouldSave) {
+    if (typeof token !== "string" || token.trim().length === 0) {
+      return failure(
+        "image-skill signup",
+        3,
+        "AUTH_REQUIRED",
+        "hosted signup did not return the restricted token needed for local auth save",
+        false,
+        {
+          suggested_command: `${SIGNUP_SUGGESTED_COMMAND} --show-token --no-save`,
+          docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
+        },
+      );
+    }
+    try {
+      await saveConfig({
+        api_base_url: apiBase(args),
+        token: token.trim(),
+        saved_at: new Date().toISOString(),
+        actor: null,
+      });
+    } catch (error) {
+      return configWriteFailure("image-skill signup", error);
+    }
+    warnings.push(
+      "hosted restricted token was saved to the public CLI config with 0600 permissions; later commands can authenticate from config without repeating signup",
+    );
+  }
   if (result.envelope.ok && showToken) {
     warnings.push(
-      "hosted restricted token was returned once because --show-token was set; store it in the agent runtime secret store and use IMAGE_SKILL_TOKEN or --token-stdin for later commands",
+      shouldSave
+        ? "hosted restricted token was also returned once because --show-token was set; keep it out of prompts, logs, issue text, and feedback"
+        : "hosted restricted token was returned once because --show-token --no-save was set; store it in the agent runtime secret store and use IMAGE_SKILL_TOKEN or --token-stdin for later commands",
     );
   }
 
@@ -392,11 +423,21 @@ async function signup(argv) {
       token_presented: showToken,
       storage: {
         ...(publicData.storage ?? {}),
-        saved: false,
-        config_path: null,
-        reason: showToken
-          ? "hosted signup returned the token once for the agent runtime secret store"
-          : "hosted signup did not request a raw token; use --show-token only when the agent can immediately store it in a runtime secret store",
+        saved: shouldSave,
+        config_path: shouldSave ? configPath() : null,
+        reason: shouldSave
+          ? "hosted signup saved the restricted token to the public CLI config for later commands"
+          : showToken
+            ? "hosted signup returned the token once for the agent runtime secret store"
+            : "hosted signup did not request a raw token or save config because --no-save was set",
+      },
+      auth_handoff: {
+        accepted_methods: ["config", "IMAGE_SKILL_TOKEN", "--token-stdin"],
+        token_source_after_signup: shouldSave ? "config" : "not_saved",
+        secret_value_included: showToken,
+        next_step: shouldSave
+          ? "Run whoami, usage quota, feedback create, credits, create, or edit normally; the CLI will read the saved config."
+          : "Store data.token in the agent runtime secret store immediately, then pass it with IMAGE_SKILL_TOKEN or --token-stdin.",
       },
     };
   }
@@ -984,6 +1025,8 @@ async function createGuide(args) {
     quota,
     estimatedCredits,
   });
+  const authConfigWrite =
+    stage === "auth_required" ? await probeConfigWritable() : null;
   const blocker = createGuideBlocker(stage, {
     requestedModelId,
     quota,
@@ -998,6 +1041,7 @@ async function createGuide(args) {
     apiBaseUrl: explicitApiBaseUrl(args),
     paymentSummary,
     commandPrefix: PUBLIC_NPX_COMMAND_PREFIX,
+    authConfigWritable: authConfigWrite?.ok ?? true,
   });
   const afterNext =
     stage === "auth_required" || stage === "quota_required"
@@ -1011,6 +1055,7 @@ async function createGuide(args) {
     tokenSource: token.source,
     nextCommand,
     afterNext,
+    authConfigWrite,
   });
   return success("image-skill create --guide", {
     schema: "image-skill.create-guide.v1",
@@ -1029,6 +1074,13 @@ async function createGuide(args) {
         claim_state: quota?.envelope.data?.claim_state ?? null,
         token_status: quota?.envelope.data?.token_status ?? null,
         saved_config_path: configPath(),
+        config_write:
+          authConfigWrite === null
+            ? null
+            : publicConfigWriteStatus(
+                authConfigWrite,
+                "image-skill create --guide",
+              ),
       },
       models: {
         reachable: models.envelope.ok,
@@ -1175,10 +1227,15 @@ function createGuidePaymentSummary(data) {
   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 agentPayableMethods = browserlessMethods.filter(
+    (method) =>
+      method.agent_settleable === true &&
+      (method.buyer_modes ?? []).some(
+        (mode) => mode === "agent_only" || mode === "hybrid",
+      ),
+  );
+  const agentInitiatedMethods = availableMethods.filter(
+    (method) => method.agent_initiated === true,
   );
   const humanHandoffMethods = availableMethods.filter(
     (method) =>
@@ -1186,7 +1243,10 @@ function createGuidePaymentSummary(data) {
       (method.buyer_modes ?? []).some((mode) => mode === "human_only"),
   );
   const preferredMethod =
-    agentPayableMethods[0] ?? browserlessMethods[0] ?? availableMethods[0];
+    agentPayableMethods[0] ??
+    humanHandoffMethods[0] ??
+    browserlessMethods[0] ??
+    availableMethods[0];
   return {
     checked: data !== null && typeof data === "object",
     live_money_methods: availableMethods.map((method) => method.method_id),
@@ -1194,9 +1254,15 @@ function createGuidePaymentSummary(data) {
       availableMethods.length > 0 &&
       availableMethods.every((method) => method.requires_browser === true),
     browserless_methods: browserlessMethods.map((method) => method.method_id),
+    agent_initiated_methods: agentInitiatedMethods.map(
+      (method) => method.method_id,
+    ),
     agent_payable_methods: agentPayableMethods.map(
       (method) => method.method_id,
     ),
+    agent_settleable_methods: agentPayableMethods.map(
+      (method) => method.method_id,
+    ),
     human_handoff_methods: humanHandoffMethods.map(
       (method) => method.method_id,
     ),
@@ -1314,6 +1380,7 @@ function createGuideBlocker(stage, input) {
 
 function createGuideAuthHandoff(stage, input) {
   if (stage === "auth_required") {
+    const authConfigWritable = input.authConfigWrite?.ok ?? true;
     return {
       required: true,
       token_source: "none",
@@ -1321,8 +1388,16 @@ function createGuideAuthHandoff(stage, input) {
       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",
+        public_cli_saves_config: authConfigWritable,
+        store_token_in: authConfigWritable
+          ? "public_cli_config_by_default"
+          : "agent_runtime_secret_store",
+        config_path: configPath(),
+        config_writable: authConfigWritable,
+        recovery:
+          input.authConfigWrite?.ok === false
+            ? configWriteRecovery("image-skill create --guide")
+            : null,
       },
       rerun_guide:
         input.afterNext === null
@@ -1364,10 +1439,11 @@ function createGuideNextCommand(stage, input) {
     );
   }
   if (stage === "auth_required") {
-    return renderGuidePrefixedCommand(
-      input.commandPrefix,
-      "signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name AGENT_NAME --runtime RUNTIME_NAME --show-token --json",
-    );
+    const signupCommand =
+      input.authConfigWritable === false
+        ? "signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name AGENT_NAME --runtime RUNTIME_NAME --show-token --no-save --json"
+        : "signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name AGENT_NAME --runtime RUNTIME_NAME --json";
+    return renderGuidePrefixedCommand(input.commandPrefix, signupCommand);
   }
   if (stage === "quota_required") {
     return renderGuidePrefixedCommand(
@@ -3151,7 +3227,7 @@ async function saveConfig(value) {
   await chmod(path, 0o600);
 }
 
-async function assertConfigWritable(command) {
+async function probeConfigWritable() {
   const path = configPath();
   const probePath = `${path}.write-test-${process.pid}-${randomBytes(4).toString("hex")}`;
   try {
@@ -3159,32 +3235,87 @@ async function assertConfigWritable(command) {
     await writeFile(probePath, "", { mode: 0o600 });
     await chmod(probePath, 0o600);
     await rm(probePath, { force: true });
-    return { ok: true };
+    return { ok: true, path, parent_path: dirname(path) };
   } catch (error) {
     await rm(probePath, { force: true }).catch(() => {});
     return {
       ok: false,
-      result: configWriteFailure(command, error),
+      path,
+      parent_path: dirname(path),
+      error,
+      message: configWriteErrorMessage(error),
     };
   }
 }
 
+async function assertConfigWritable(command) {
+  const status = await probeConfigWritable();
+  if (status.ok) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    result: configWriteFailure(command, status.error),
+  };
+}
+
+function publicConfigWriteStatus(status, command) {
+  if (status.ok) {
+    return {
+      writable: true,
+      config_path: status.path,
+      parent_path: status.parent_path,
+      parent_directories_prepared: true,
+      error_message: null,
+      recovery: null,
+    };
+  }
+  return {
+    writable: false,
+    config_path: status.path,
+    parent_path: status.parent_path,
+    parent_directories_prepared: false,
+    error_message: status.message,
+    recovery: configWriteRecovery(command),
+  };
+}
+
+function configWriteErrorMessage(error) {
+  return error instanceof Error
+    ? error.message
+    : "public CLI could not write its local auth config";
+}
+
+function configWriteRecovery(command) {
+  const safeConfigPath = "$PWD/.image-skill/config.json";
+  const baseSignupCommand = `IMAGE_SKILL_CONFIG_PATH="${safeConfigPath}" ${SIGNUP_SUGGESTED_COMMAND}`;
+  if (command === "image-skill auth save") {
+    return {
+      config_path_env: "IMAGE_SKILL_CONFIG_PATH",
+      suggested_config_path: safeConfigPath,
+      suggested_command: `IMAGE_SKILL_CONFIG_PATH="${safeConfigPath}" image-skill auth save --json`,
+      docs_url: "https://image-skill.com/cli.md#local-config-and-install",
+    };
+  }
+  return {
+    config_path_env: "IMAGE_SKILL_CONFIG_PATH",
+    suggested_config_path: safeConfigPath,
+    suggested_command: baseSignupCommand,
+    fallback_command: `${SIGNUP_SUGGESTED_COMMAND} --show-token --no-save`,
+    fallback_auth_method: "--token-stdin",
+    docs_url: "https://image-skill.com/cli.md#local-config-and-install",
+  };
+}
+
 function configWriteFailure(command, error) {
-  const message =
-    error instanceof Error
-      ? error.message
-      : "public CLI could not write its local auth config";
+  const message = configWriteErrorMessage(error);
   return failure(
     command,
     9,
     "PUBLIC_CLI_CONFIG_WRITE_FAILED",
     `public CLI could not write auth config at ${configPath()}: ${message}`,
     true,
-    {
-      suggested_command:
-        'IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" image-skill auth save --json',
-      docs_url: "https://image-skill.com/cli.md#local-config-and-install",
-    },
+    configWriteRecovery(command),
   );
 }
 

package/cli.md

@@ -84,18 +84,17 @@ image-skill signup --agent \
   --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
-  --show-token \
   --json
 ```
 
-Hosted signup returns the raw `isk_r_` token only when `--show-token` is set,
-and only once. Store it immediately in the agent runtime secret store, then use
-`IMAGE_SKILL_TOKEN` or `--token-stdin` for later hosted commands. Public hosted
-signup does not auto-save auth into the CLI config. `--save` is local-only
-(`--local`) and rejected on the hosted path; `--no-save` remains accepted for
-older hosted instructions. Use `--show-token --no-save` when the agent runtime
-has a separate secret store and needs the raw token once. Do not paste tokens
-into prompts, logs, issue text, or feedback.
+Hosted signup saves the restricted `isk_r_` token to the public CLI config by
+default with `0600` permissions, so later hosted commands can authenticate from
+config without repeating signup or carrying a raw token through prompts. Set
+`IMAGE_SKILL_CONFIG_PATH` first when the default config home may be read-only.
+The raw token is returned only when `--show-token` is set, and only once. Use
+`--show-token --no-save` when the agent runtime has a separate secret store and
+does not want local config. Do not paste tokens into prompts, logs, issue text,
+or feedback.
 
 In this preview contract, `--agent-contact` is an email-shaped durable contact
 inbox for the restricted agent identity, not a requirement to find an
@@ -109,7 +108,8 @@ proof runs. `--human-email` remains accepted as a compatibility alias for
 
 If the runtime has a separate secret store, it may provide the token to commands
 as `IMAGE_SKILL_TOKEN`. Keep that value outside prompts, logs, issue text, and
-feedback.
+feedback. Saved config, `IMAGE_SKILL_TOKEN`, and `--token-stdin` are all
+accepted by hosted commands; config is the default fresh-agent path.
 
 If the agent runtime can hand secrets to a command over stdin, avoid exporting
 the token and use `--token-stdin` instead:
@@ -139,9 +139,10 @@ 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`, 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
+- `auth_required`: run `data.next_command`, then rerun guide once. Hosted
+  signup saves auth to config by default. If the runtime intentionally used
+  `--no-save --show-token`, store the returned token and 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.
@@ -164,9 +165,10 @@ image-skill usage quota
 image-skill create --dry-run --prompt "a compact field camera on a stainless workbench"
 ```
 
-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.
+Use `--show-token --no-save` for hosted signup only when the runtime can
+immediately store the raw token once outside local config. For later commands,
+saved config is the default; `IMAGE_SKILL_TOKEN` and `--token-stdin` remain
+available for runtimes with a separate secret store.
 `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.
@@ -190,9 +192,9 @@ export PATH="$npm_config_prefix/bin:$PATH"
 npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
 ```
 
-Hosted signup does not auto-save auth state; it returns the token once with
-`--show-token`. If the runtime also needs a writable compatibility config path,
-set `IMAGE_SKILL_CONFIG_PATH` before `signup`:
+Hosted signup saves auth state to the public CLI config by default. If the
+runtime needs a writable compatibility config path, set
+`IMAGE_SKILL_CONFIG_PATH` before `signup`:
 
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
@@ -200,13 +202,17 @@ npx -y image-skill@latest signup --agent \
   --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
-  --show-token \
   --json
 ```
 
 Config write failures return `PUBLIC_CLI_CONFIG_WRITE_FAILED` with a structured
 `error.recovery.suggested_command`. Agents should follow that recovery field,
 then rerun `create --guide` for the requested creative flow.
+When `create --guide` reaches `auth_required`, it probes the configured auth
+path first. If local config cannot be written, `data.next_command` uses
+`--show-token --no-save` and `data.auth_handoff.rerun_guide.with_stdin` shows
+the token-stdin rerun path instead of asking the agent to try a doomed saved
+signup.
 
 ### `image-skill whoami`
 
@@ -264,6 +270,9 @@ Minimum success data shape:
       "live_money": true,
       "buyer_modes": ["hybrid", "human_only"],
       "requires_browser": true,
+      "agent_initiated": true,
+      "agent_settleable": false,
+      "settlement_blocker": "requires human browser checkout completion",
       "default_pack_id": "starter-500",
       "purchase_endpoint": "/v1/credit-purchases/stripe-checkout-sessions"
     },
@@ -276,6 +285,9 @@ Minimum success data shape:
       "live_money": true,
       "buyer_modes": ["agent_only", "hybrid"],
       "requires_browser": false,
+      "agent_initiated": true,
+      "agent_settleable": true,
+      "settlement_blocker": null,
       "default_pack_id": "starter-500",
       "purchase_endpoint": "/v1/credit-purchases/stripe-x402-deposits"
     }
@@ -299,11 +311,12 @@ curl -sS https://api.image-skill.com/v1/payment-methods
 
 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.
+fee traps. Use the payment method catalog to choose the rail:
+`stripe_checkout` when a human sponsor can complete Checkout, or
+`stripe_x402.exact.usdc` when a wallet-equipped agent can settle a browserless
+live crypto deposit attempt from returned pay-to instructions.
+Exact custom quotes are still supported when an agent already knows the
+required credit budget.
 
 ```bash
 image-skill credits packs list --json
@@ -343,10 +356,9 @@ 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 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.
+payment method returned by `credits methods --json`: `stripe_checkout` for the
+human Checkout path, or `stripe_x402.exact.usdc` for a browserless
+action-required deposit attempt. 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
 model's provider cost and Image Skill's margin policy; inspect
@@ -422,8 +434,9 @@ 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.
+`"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.
 
 Hosted API equivalent:
 
@@ -440,12 +453,14 @@ 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.
+browserless action-required USDC deposit attempt. When the response includes
+`stripe_x402.payable_instructions`, a wallet-equipped agent may pay the exact
+USDC amount to `deposit_address` on Base without using a browser. 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, card data, Stripe secrets, or provider receipts to Image Skill.
 
 ```bash
 image-skill credits buy \
@@ -474,6 +489,21 @@ Minimum x402 action-required data:
     "network": "base",
     "token_currency": "usdc",
     "deposit_address_present": true,
+    "payable_instructions": {
+      "kind": "stripe_crypto_deposit",
+      "network": "base",
+      "token_currency": "usdc",
+      "token_decimals": 6,
+      "token_amount": "5.00",
+      "token_amount_atomic": "5000000",
+      "amount_cents": 500,
+      "amount_usd": "5.00",
+      "deposit_address": "0x...",
+      "token_contract_address": "0x...",
+      "supported_token_currencies": ["usdc"],
+      "expires_at": "2026-05-08T20:00:00.000Z",
+      "exact_amount_required": true
+    },
     "redacted": {
       "payment_intent_id": "[redacted-stripe-payment-intent]",
       "deposit_address": "[redacted-stripe-crypto-deposit-address]",