image-skill 0.1.28 → 0.1.29

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.28";
+const VERSION = "0.1.29";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -27,13 +27,15 @@ const DEFAULT_CONFIG_PATH = join(
   "image-skill",
   "config.json",
 );
+const LOCAL_WRITABLE_CONFIG_PATH = "$PWD/.image-skill/config.json";
 const SIGNUP_SUGGESTED_COMMAND =
   "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 HOSTED_SIGNUP_TOKEN_RETURNED_WARNING =
   "hosted restricted token is returned once; store it in the agent runtime secret store and never paste it into prompts, logs, issues, or product feedback";
-const PUBLIC_NPX_COMMAND_PREFIX = "npx -y image-skill@latest";
+const PUBLIC_NPX_COMMAND_PREFIX =
+  "npm_config_update_notifier=false npx -y image-skill@latest";
 const CREDIT_UNIT_USD = 0.01;
 const PAYMENT_CREDENTIAL_FLAGS = new Set([
   "payment-token",
@@ -301,8 +303,8 @@ function commandHelpByKey(key) {
       usage:
         "image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json",
       docs_url: "https://image-skill.com/cli.md#image-skill-credits",
-      required_flags: ["--pack or --credits"],
-      optional_flags: ["--payment-method", "--idempotency-key"],
+      required_flags: ["--pack or --credits", "--payment-method"],
+      optional_flags: ["--idempotency-key"],
     },
     "credits buy": {
       command: "image-skill credits buy help",
@@ -378,6 +380,7 @@ function commandHelpByKey(key) {
       docs_url: "https://image-skill.com/cli.md#image-skill-edit",
       required_flags: ["--input"],
       optional_flags: [
+        "--dry-run",
         "--prompt",
         "--model",
         "--mask",
@@ -496,7 +499,7 @@ async function doctor(argv) {
 async function trust(argv) {
   const args = parseArgs(argv);
   const unsupportedFlags = [...args.flags.keys()].filter(
-    (flag) => !["json", "api-base-url"].includes(flag),
+    (flag) => !["json", "api-base-url", "token", "token-stdin"].includes(flag),
   );
   if (args.positionals.length > 0 || unsupportedFlags.length > 0) {
     return invalid(
@@ -506,6 +509,13 @@ async function trust(argv) {
         : "trust does not accept positional arguments",
     );
   }
+  const tokenHandoff = await acceptNoAuthTokenHandoff(
+    args,
+    "image-skill trust",
+  );
+  if (tokenHandoff !== null) {
+    return tokenHandoff;
+  }
 
   const checkedAt = new Date().toISOString();
   const apiBaseUrl = apiBase(args);
@@ -972,12 +982,17 @@ async function credits(argv) {
       );
     }
     const idempotency = optionalIdempotencyKey(args, "quote");
-    const paymentMethod =
-      flagString(args, "payment-method") ?? "stripe_checkout";
+    const paymentMethod = flagString(args, "payment-method");
     const PUBLIC_QUOTE_PAYMENT_METHODS = [
       "stripe_checkout",
       "stripe_x402.exact.usdc",
     ];
+    if (paymentMethod === null) {
+      return invalid(
+        "image-skill credits quote",
+        "credits quote requires --payment-method from credits methods --json; use stripe_x402.exact.usdc for an agent-settleable browserless rail or stripe_checkout for a human Checkout handoff",
+      );
+    }
     if (!PUBLIC_QUOTE_PAYMENT_METHODS.includes(paymentMethod)) {
       return invalid(
         "image-skill credits quote",
@@ -1144,13 +1159,14 @@ async function models(argv) {
       query.message,
     );
   }
-  return apiRequest({
+  const result = await apiRequest({
     command:
       subcommand === "list" ? "image-skill models list" : "image-skill models",
     method: "GET",
     apiBaseUrl: apiBase(args),
     path: query.path,
   });
+  return flagBool(args, "summary") ? withModelSummary(result) : result;
 }
 
 function modelListQuery(args) {
@@ -1175,6 +1191,7 @@ function modelListQuery(args) {
     params.set("catalog_only", "true");
   }
   addQueryValue(params, "operation", flagString(args, "operation"));
+  addQueryValue(params, "modality", flagString(args, "modality"));
   addQueryValue(params, "provider", flagString(args, "provider"));
   const query = params.toString();
   return {
@@ -1183,6 +1200,133 @@ function modelListQuery(args) {
   };
 }
 
+function withModelSummary(result) {
+  const data = result.envelope.data;
+  if (!isRecord(data) || !Array.isArray(data.models)) {
+    return result;
+  }
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      data: {
+        ...data,
+        summary: {
+          ...(isRecord(data.summary) ? data.summary : {}),
+          result_shape: "compact_model_summary",
+          full_list_command: "image-skill models list --json",
+        },
+        models: data.models.map(modelSummaryRow),
+      },
+    },
+  };
+}
+
+function modelSummaryRow(model) {
+  return {
+    id: model.id,
+    display_name: model.display_name,
+    provider_id: model.provider_id,
+    mode: model.mode,
+    status: model.status,
+    availability_reason: model.availability_reason ?? null,
+    supports: Array.isArray(model.supports) ? [...model.supports] : [],
+    operations: Array.isArray(model.operations) ? [...model.operations] : [],
+    task_tags: modelSummaryTaskTags(model),
+    estimated_usd_per_image: model.economics?.estimated_usd_per_image ?? null,
+    credits_required: model.economics?.credit_pricing?.credits_required ?? null,
+    pricing_confidence:
+      model.economics?.credit_pricing?.pricing_confidence ?? null,
+    cost_known: model.economics?.cost_known ?? false,
+    budget_required_for_live:
+      model.economics?.budget_required_for_live ?? false,
+    max_outputs_per_request:
+      model.media?.output?.max_outputs_per_request ?? null,
+    max_resolution: model.media?.output?.max_resolution ?? null,
+    artifact_storage: model.execution?.artifact_storage ?? null,
+    model_execution_status: model.execution?.model_execution_status ?? null,
+    grants_required: Array.isArray(model.capability?.grants_required)
+      ? [...model.capability.grants_required]
+      : [],
+    show_command:
+      typeof model.id === "string"
+        ? `image-skill models show ${model.id} --json`
+        : "image-skill models show MODEL_ID --json",
+  };
+}
+
+function modelSummaryTaskTags(model) {
+  const tags = [];
+  const seen = new Set();
+  const add = (tag) => {
+    if (!seen.has(tag)) {
+      seen.add(tag);
+      tags.push(tag);
+    }
+  };
+  for (const support of Array.isArray(model.supports) ? model.supports : []) {
+    add(support);
+  }
+  for (const operation of Array.isArray(model.operations)
+    ? model.operations
+    : []) {
+    add(operationTag(operation));
+  }
+  for (const intent of Array.isArray(model.capability?.intents)
+    ? model.capability.intents
+    : []) {
+    add(intent);
+  }
+  if (
+    model.operations?.includes("image.generate") &&
+    model.media?.input?.images?.required !== true &&
+    model.media?.input?.references?.required !== true
+  ) {
+    add("text-to-image");
+  }
+  if (model.media?.input?.images?.required === true) {
+    add("input-image");
+    add("image-to-image");
+  }
+  if (model.media?.input?.mask?.supported === true) {
+    add(model.media?.input?.mask?.required === true ? "mask-required" : "mask");
+  }
+  if (model.media?.input?.references?.supported === true) {
+    add("reference-image");
+    if ((model.media?.input?.references?.max ?? 0) > 1) {
+      add("multi-reference");
+    }
+  }
+  if (model.media?.output?.transparent_background === true) {
+    add("transparent-background");
+  }
+  if ((model.media?.output?.max_outputs_per_request ?? 0) > 1) {
+    add("multi-output");
+  }
+  if (
+    String(model.id ?? "").includes("video") ||
+    String(model.display_name ?? "")
+      .toLowerCase()
+      .includes("video")
+  ) {
+    add("video");
+  }
+  if (model.execution?.artifact_storage === "image_skill_owned") {
+    add("downloadable");
+  }
+  return tags;
+}
+
+function operationTag(operation) {
+  if (operation === "image.generate") return "generate";
+  if (operation === "image.edit") return "edit";
+  if (operation === "image.variation") return "variation";
+  if (operation === "image.upscale") return "upscale";
+  if (operation === "image.utility") return "utility";
+  if (operation === "image.vision") return "vision";
+  return "inspect";
+}
+
 function addQueryValue(params, name, value) {
   if (typeof value === "string" && value.trim().length > 0) {
     params.set(name, value.trim());
@@ -1284,9 +1428,12 @@ async function createGuide(args) {
   const selected =
     models.envelope.ok && models.envelope.data?.models
       ? selectCreateGuideModel(models.envelope.data.models, requestedModelId, {
+          prompt: trimmedPrompt,
+          intent: requestedIntent,
           maxEstimatedUsdPerImage,
         })
       : null;
+  const selectedAspectRatio = createGuideSuggestedAspectRatio(selected);
   const pricing = selected?.economics?.credit_pricing ?? null;
   const estimatedCredits = pricing?.credits_required ?? null;
   const estimatedProviderUsdPerImage =
@@ -1310,6 +1457,9 @@ async function createGuide(args) {
           path: "/v1/quota",
           token: token.token,
         });
+  const authenticated = quota?.envelope.data?.authenticated === true;
+  const publicTokenSource =
+    token.source === "anonymous" ? "none" : token.source;
   const paymentSummary = createGuidePaymentSummary(payments.envelope.data);
   const stage = createGuideStage({
     prompt: trimmedPrompt,
@@ -1333,6 +1483,7 @@ async function createGuide(args) {
     requestedProviderId,
     requestedIntent,
     budgetGuard,
+    aspectRatio: selectedAspectRatio,
     apiBaseUrl: explicitApiBaseUrl(args),
     paymentSummary,
     commandPrefix: PUBLIC_NPX_COMMAND_PREFIX,
@@ -1344,6 +1495,7 @@ async function createGuide(args) {
     requestedProviderId,
     requestedIntent,
     budgetGuard,
+    aspectRatio: selectedAspectRatio,
     apiBaseUrl: explicitApiBaseUrl(args),
     commandPrefix: PUBLIC_NPX_COMMAND_PREFIX,
   });
@@ -1353,6 +1505,28 @@ async function createGuide(args) {
   });
   const noSpendNextCommand =
     stage === "ready_to_create" ? escapeHatches.dry_run : null;
+  const noSpendNextCommandLabel =
+    noSpendNextCommand === null
+      ? null
+      : "dry_run_plan_no_provider_call_no_credit_debit_no_media_write";
+  const noSpendNextCommandEffect = createGuideNoSpendNextCommandEffect(stage, {
+    estimatedCredits,
+    estimatedDebitUsdPerImage,
+  });
+  const noSpendEvaluation = createGuideNoSpendEvaluation(stage, {
+    noSpendNextCommand,
+    noSpendNextCommandLabel,
+    noSpendNextCommandEffect,
+  });
+  const guideWarning = createGuideWarning(stage, {
+    nextCommandEffect,
+    paymentSummary,
+  });
+  const selfFundNextCommand = stage === "quota_required" ? nextCommand : null;
+  const selfFundNextCommandLabel = createGuideSelfFundNextCommandLabel(
+    stage,
+    paymentSummary,
+  );
   const afterNext =
     stage === "auth_required" || stage === "quota_required"
       ? renderGuideCommand(
@@ -1367,7 +1541,18 @@ async function createGuide(args) {
     afterNext,
     authConfigWrite,
   });
-  return success("image-skill create --guide", {
+  const authReady = createGuideAuthReady(stage, {
+    authenticated,
+    tokenSource: publicTokenSource,
+    savedConfigPath: configPath(),
+  });
+  const selfFundHandoff = createGuideSelfFundHandoff(stage, {
+    paymentSummary,
+    nextCommand,
+    afterNext,
+    tokenSource: publicTokenSource,
+  });
+  return createGuideSuccess(quota?.envelope.actor ?? null, {
     schema: "image-skill.create-guide.v1",
     ready: stage === "ready_to_create",
     stage,
@@ -1379,8 +1564,8 @@ async function createGuide(args) {
         error_code: health.envelope.error?.code ?? null,
       },
       auth: {
-        source: token.source === "anonymous" ? "none" : token.source,
-        authenticated: quota?.envelope.data?.authenticated === true,
+        source: publicTokenSource,
+        authenticated,
         claim_state: quota?.envelope.data?.claim_state ?? null,
         token_status: quota?.envelope.data?.token_status ?? null,
         saved_config_path: configPath(),
@@ -1419,14 +1604,24 @@ async function createGuide(args) {
       selected === null
         ? null
         : {
-            operation: "create",
+            operation: createGuideSelectedModelRequiresInputImage(selected)
+              ? "edit"
+              : "create",
             model_id: selected.id,
             model_status: selected.status,
             model_execution_status: selected.execution.model_execution_status,
+            modality: selected.modality ?? null,
+            suggested_aspect_ratio: selectedAspectRatio,
             reason:
               requestedModelId === null
-                ? "default executable create model for first image"
-                : "requested executable create model",
+                ? createGuideSelectionReason(
+                    selected,
+                    trimmedPrompt,
+                    requestedIntent,
+                  )
+                : createGuideSelectedModelRequiresInputImage(selected)
+                  ? "requested executable image-to-3D model"
+                  : "requested executable create model",
           },
     cost: {
       estimated_credits: estimatedCredits,
@@ -1437,13 +1632,20 @@ async function createGuide(args) {
       pricing_confidence: pricing?.pricing_confidence ?? null,
     },
     blocker,
+    guide_warning: guideWarning,
+    auth_ready: authReady,
     next_command: nextCommand,
     next_command_effect: nextCommandEffect,
     no_spend_next_command: noSpendNextCommand,
-    no_spend_next_command_label:
-      noSpendNextCommand === null
-        ? null
-        : "dry_run_plan_no_provider_call_no_credit_debit_no_media_write",
+    no_spend_next_command_label: noSpendNextCommandLabel,
+    no_spend_next_command_effect: noSpendNextCommandEffect,
+    no_spend_evaluation: noSpendEvaluation,
+    recommended_no_spend_command: noSpendNextCommand,
+    recommended_no_spend_command_label: noSpendNextCommandLabel,
+    recommended_no_spend_command_effect: noSpendNextCommandEffect,
+    self_fund_next_command: selfFundNextCommand,
+    self_fund_next_command_label: selfFundNextCommandLabel,
+    self_fund_handoff: selfFundHandoff,
     after_next: afterNext,
     auth_handoff: authHandoff,
     escape_hatches: escapeHatches,
@@ -1458,31 +1660,126 @@ async function createGuide(args) {
   });
 }
 
+function createGuideSuccess(actor, data) {
+  const result = success("image-skill create --guide", data);
+  result.envelope.actor = actor;
+  return result;
+}
+
 function selectCreateGuideModel(
   models,
   requestedModelId,
-  { maxEstimatedUsdPerImage = null } = {},
+  { prompt = "", intent = undefined, maxEstimatedUsdPerImage = null } = {},
 ) {
   const isExecutableCreate = (model) =>
     model?.status === "available" &&
     model?.execution?.model_execution_status === "executable" &&
     Array.isArray(model?.supports) &&
     model.supports.includes("create");
+  const isExecutableImageTo3d = (model) =>
+    model?.status === "available" &&
+    model?.execution?.model_execution_status === "executable" &&
+    model?.modality === "3d" &&
+    Array.isArray(model?.supports) &&
+    model.supports.includes("variation") &&
+    createGuideSelectedModelRequiresInputImage(model);
+  const isExecutableGuideModel = (model) =>
+    isExecutableCreate(model) || isExecutableImageTo3d(model);
   if (requestedModelId !== null) {
     const requested = models.find((model) => model.id === requestedModelId);
-    return requested !== undefined && isExecutableCreate(requested)
+    return requested !== undefined && isExecutableGuideModel(requested)
       ? requested
       : null;
   }
   const candidates = models.filter(isExecutableCreate);
+  if (createGuideImplies3d({ prompt, intent })) {
+    const eligible3d = guideCandidatesWithinBudget({
+      candidates: models.filter(isExecutableImageTo3d),
+      maxEstimatedUsdPerImage,
+    });
+    const threeDimensional = eligible3d[0];
+    if (threeDimensional !== undefined) {
+      return threeDimensional;
+    }
+  }
+  const eligible = guideCandidatesWithinBudget({
+    candidates,
+    maxEstimatedUsdPerImage,
+  });
+  if (createGuideImpliesAudio({ prompt, intent })) {
+    const audio = eligible.find((model) => model?.modality === "audio");
+    if (audio !== undefined) {
+      return audio;
+    }
+  }
+  if (createGuideImpliesVideo({ prompt, intent })) {
+    const video = eligible.find((model) => model?.modality === "video");
+    if (video !== undefined) {
+      return video;
+    }
+  }
+  const intentClass = createGuideIntentClass(intent);
+  for (const modelId of preferredCreateGuideModelIds(intentClass)) {
+    const preferred = eligible.find((model) => model?.id === modelId);
+    if (preferred !== undefined) {
+      return preferred;
+    }
+  }
+  return eligible[0] ?? null;
+}
+
+function guideCandidatesWithinBudget({
+  candidates,
+  maxEstimatedUsdPerImage = null,
+}) {
   if (maxEstimatedUsdPerImage === null) {
-    return candidates[0] ?? null;
+    return candidates;
   }
   const capped = candidates.filter((model) => {
     const estimatedUsd = guideBudgetUsdForModel(model);
     return estimatedUsd === null || estimatedUsd <= maxEstimatedUsdPerImage;
   });
-  return (capped.length === 0 ? candidates : capped)[0] ?? null;
+  return capped.length === 0 ? candidates : capped;
+}
+
+function createGuideIntentClass(intent) {
+  const normalized = String(intent ?? "")
+    .trim()
+    .toLowerCase();
+  if (["cheap", "budget", "draft", "test"].includes(normalized)) {
+    return "budget_draft";
+  }
+  if (
+    [
+      "final",
+      "finalize",
+      "hero",
+      "product",
+      "product-shot",
+      "campaign",
+      "publication",
+      "deliverable",
+    ].includes(normalized)
+  ) {
+    return "final";
+  }
+  return "general";
+}
+
+function preferredCreateGuideModelIds(intentClass) {
+  return intentClass === "budget_draft"
+    ? [
+        "fal.flux-dev",
+        "xai.grok-imagine-image-quality",
+        "xai.grok-imagine-image",
+        "openai.gpt-image-2",
+      ]
+    : [
+        "xai.grok-imagine-image-quality",
+        "fal.flux-dev",
+        "xai.grok-imagine-image",
+        "openai.gpt-image-2",
+      ];
 }
 
 function guideBudgetUsdForModel(model) {
@@ -1496,6 +1793,81 @@ function guideBudgetUsdForModel(model) {
   );
 }
 
+function createGuideImplies3d(input) {
+  const searchable =
+    `${input?.intent ?? ""} ${input?.prompt ?? ""}`.toLowerCase();
+  return /\b(?:glb|gltf|mesh|model\s+asset|asset\s+model|textured\s+model|image-to-3d|(?:3d|three-d)\s+(?:\w+\s+){0,3}(?:model|asset|mesh|object)|(?:model|asset|mesh|object)\s+(?:in|as)\s+(?:3d|three-d))\b/.test(
+    searchable,
+  );
+}
+
+function createGuideImpliesAudio(input) {
+  const searchable =
+    `${input?.intent ?? ""} ${input?.prompt ?? ""}`.toLowerCase();
+  if (/\bmusic\s+video\b/.test(searchable)) {
+    return false;
+  }
+  return /\b(?:audio|sound|music|soundtrack|wav|text-to-audio)\b/.test(
+    searchable,
+  );
+}
+
+function createGuideImpliesVideo(input) {
+  const searchable =
+    `${input?.intent ?? ""} ${input?.prompt ?? ""}`.toLowerCase();
+  return /\b(?:video|clip|footage|animation|animated|mp4|b-roll|timelapse|time-lapse)\b/.test(
+    searchable,
+  );
+}
+
+function createGuideSuggestedAspectRatio(model) {
+  if (model?.modality !== "video") {
+    return null;
+  }
+  const values = model?.media?.input?.aspect_ratios?.values;
+  if (!Array.isArray(values)) {
+    return null;
+  }
+  return values.includes("16:9") ? "16:9" : (values[0] ?? null);
+}
+
+function createGuideSelectedModelRequiresInputImage(model) {
+  return (
+    model?.modality === "3d" && model?.media?.input?.images?.required === true
+  );
+}
+
+function createGuideSelectionReason(model, prompt, intent) {
+  if (
+    createGuideSelectedModelRequiresInputImage(model) &&
+    createGuideImplies3d({ prompt, intent })
+  ) {
+    return "3D intent matched executable image-to-3D model; provide one Image Skill-owned image_... input asset";
+  }
+  if (
+    model?.modality === "audio" &&
+    createGuideImpliesAudio({ prompt, intent })
+  ) {
+    return "audio intent matched executable audio create model";
+  }
+  if (
+    model?.modality === "video" &&
+    createGuideImpliesVideo({ prompt, intent })
+  ) {
+    return "video intent matched executable video create model";
+  }
+  if (
+    preferredCreateGuideModelIds(createGuideIntentClass(intent)).includes(
+      model?.id,
+    )
+  ) {
+    return createGuideIntentClass(intent) === "budget_draft"
+      ? "guide selected a draft/budget create model with high-definition defaults"
+      : "guide selected the strongest currently available quality-first create model for this intent";
+  }
+  return "guide selected the first available executable create model";
+}
+
 function createGuidePaymentSummary(data) {
   const methods = Array.isArray(data?.methods)
     ? data.methods.filter((method) => method.live_money)
@@ -1544,6 +1916,10 @@ function createGuidePaymentSummary(data) {
       (method) => method.method_id,
     ),
     preferred_method: preferredMethod?.method_id ?? null,
+    preferred_method_summary:
+      preferredMethod === undefined
+        ? null
+        : createGuidePreferredPaymentSummary(preferredMethod),
     buyer_modes: [
       ...new Set(methods.flatMap((method) => method.buyer_modes ?? [])),
     ],
@@ -1554,6 +1930,64 @@ function createGuidePaymentSummary(data) {
   };
 }
 
+function createGuidePreferredPaymentSummary(method) {
+  const buyerModes = Array.isArray(method.buyer_modes)
+    ? method.buyer_modes.filter((mode) => typeof mode === "string")
+    : [];
+  const liveMoney = method.live_money !== false;
+  const browserless = method.requires_browser === false;
+  const requiresBrowser = method.requires_browser === true;
+  const agentInitiated = method.agent_initiated === true;
+  const agentSettleable = method.agent_settleable === true;
+  const humanHandoffRequired =
+    requiresBrowser || buyerModes.includes("human_only");
+  const topUpPath =
+    agentSettleable && browserless
+      ? "browserless_agent_self_fund"
+      : humanHandoffRequired
+        ? "human_payment_handoff"
+        : "payment_method_inspection";
+  return {
+    method_id: method.method_id,
+    live_money: liveMoney,
+    requires_browser: requiresBrowser,
+    browserless,
+    agent_initiated: agentInitiated,
+    agent_settleable: agentSettleable,
+    human_handoff_required: humanHandoffRequired,
+    buyer_modes: buyerModes,
+    settlement_blocker:
+      typeof method.settlement_blocker === "string"
+        ? method.settlement_blocker
+        : null,
+    default_pack_id:
+      typeof method.default_pack_id === "string"
+        ? method.default_pack_id
+        : null,
+    min_amount_cents:
+      typeof method.limits?.min_amount_cents === "number"
+        ? method.limits.min_amount_cents
+        : null,
+    max_amount_cents:
+      typeof method.limits?.max_amount_cents === "number"
+        ? method.limits.max_amount_cents
+        : null,
+    top_up_path: topUpPath,
+    next_step:
+      topUpPath === "browserless_agent_self_fund"
+        ? "quote_buy_status_then_rerun_after_next"
+        : topUpPath === "human_payment_handoff"
+          ? "quote_buy_open_checkout_status_then_rerun_after_next"
+          : "inspect_credits_methods",
+    warning:
+      topUpPath === "browserless_agent_self_fund"
+        ? "Preferred rail is browserless live money that a wallet-equipped agent can initiate and settle inside delegated caps."
+        : topUpPath === "human_payment_handoff"
+          ? "Preferred rail starts a live-money payment handoff and requires human or browser completion before credits are granted."
+          : "Preferred payment rail needs inspection before an agent can choose the next top-up action.",
+  };
+}
+
 function createGuidePaymentCommands(preferredMethod, fallbackMethods) {
   const commands = [
     "image-skill credits methods --json",
@@ -1658,6 +2092,10 @@ function createGuideBlocker(stage, input) {
 function createGuideAuthHandoff(stage, input) {
   if (stage === "auth_required") {
     const authConfigWritable = input.authConfigWrite?.ok ?? true;
+    const recovery =
+      input.authConfigWrite?.ok === false
+        ? configWriteRecovery("image-skill create --guide")
+        : null;
     return {
       required: true,
       token_source: "none",
@@ -1665,16 +2103,21 @@ function createGuideAuthHandoff(stage, input) {
       accepted_methods: ["IMAGE_SKILL_TOKEN", "--token-stdin", "config"],
       signup: {
         returns_token_once: true,
-        public_cli_saves_config: authConfigWritable,
+        public_cli_saves_config: true,
         store_token_in: authConfigWritable
           ? "public_cli_config_by_default"
-          : "agent_runtime_secret_store",
+          : "public_cli_config_after_setting_IMAGE_SKILL_CONFIG_PATH",
         config_path: configPath(),
         config_writable: authConfigWritable,
-        recovery:
-          input.authConfigWrite?.ok === false
-            ? configWriteRecovery("image-skill create --guide")
-            : null,
+        preferred_save_config:
+          recovery === null
+            ? null
+            : {
+                config_path_env: recovery.config_path_env,
+                config_path: recovery.suggested_config_path,
+                command: input.nextCommand,
+              },
+        recovery,
       },
       rerun_guide:
         input.afterNext === null
@@ -1686,7 +2129,7 @@ function createGuideAuthHandoff(stage, input) {
       next_command: null,
     };
   }
-  if (stage === "ready_to_create") {
+  if (stage === "quota_required" || stage === "ready_to_create") {
     return {
       required: true,
       token_source: input.tokenSource,
@@ -1705,6 +2148,152 @@ function createGuideAuthHandoff(stage, input) {
   return null;
 }
 
+function createGuideAuthReady(stage, input) {
+  const nextCommandRequiresAuth =
+    stage === "quota_required" || stage === "ready_to_create";
+  const ready = input.authenticated;
+  return {
+    ready,
+    authenticated: input.authenticated,
+    source: input.tokenSource,
+    saved_config_path: input.savedConfigPath,
+    next_command_requires_auth: nextCommandRequiresAuth,
+    next_command_auth_ready: nextCommandRequiresAuth ? ready : null,
+    secret_value_included: false,
+    accepted_methods: ["config", "IMAGE_SKILL_TOKEN", "--token-stdin"],
+    warning: ready
+      ? "Current hosted auth is ready; data.next_command can reuse this auth context without exposing a raw token."
+      : stage === "auth_required"
+        ? "Auth is not ready yet; run data.next_command to create a restricted agent identity, then rerun the guide."
+        : null,
+  };
+}
+
+function createGuideSelfFundNextCommandLabel(stage, paymentSummary) {
+  if (stage !== "quota_required") {
+    return null;
+  }
+  const preferredMethod = paymentSummary.preferred_method;
+  if (
+    preferredMethod !== null &&
+    paymentSummary.browserless_methods.includes(preferredMethod) &&
+    paymentSummary.agent_settleable_methods.includes(preferredMethod)
+  ) {
+    return "browserless_agent_payable_quote";
+  }
+  if (
+    preferredMethod !== null &&
+    paymentSummary.human_handoff_methods.includes(preferredMethod)
+  ) {
+    return "human_handoff_payment_quote";
+  }
+  return "payment_or_quota_action";
+}
+
+function createGuideSelfFundHandoff(stage, input) {
+  if (stage !== "quota_required") {
+    return null;
+  }
+  const preferredMethod = input.paymentSummary.preferred_method;
+  const browserless =
+    preferredMethod !== null &&
+    input.paymentSummary.browserless_methods.includes(preferredMethod);
+  const agentInitiated =
+    preferredMethod !== null &&
+    input.paymentSummary.agent_initiated_methods.includes(preferredMethod);
+  const agentSettleable =
+    preferredMethod !== null &&
+    input.paymentSummary.agent_settleable_methods.includes(preferredMethod);
+  const humanHandoffRequired =
+    preferredMethod !== null &&
+    input.paymentSummary.human_handoff_methods.includes(preferredMethod);
+  const statusCommand = guidePaymentCommandByKind(
+    input.paymentSummary.suggested_commands,
+    "status",
+  );
+
+  return {
+    required: true,
+    preferred_method: preferredMethod,
+    live_money:
+      preferredMethod !== null &&
+      input.paymentSummary.live_money_methods.includes(preferredMethod),
+    browserless,
+    agent_initiated: agentInitiated,
+    agent_settleable: agentSettleable,
+    human_handoff_required: humanHandoffRequired,
+    payment_commands: {
+      quote: guidePaymentCommandByKind(
+        input.paymentSummary.suggested_commands,
+        "quote",
+      ),
+      buy: guidePaymentCommandByKind(
+        input.paymentSummary.suggested_commands,
+        "buy",
+      ),
+      status: statusCommand,
+    },
+    wallet_settlement: createGuideWalletSettlementHandoff({
+      preferredMethod,
+      browserless,
+      agentSettleable,
+      statusCommand,
+    }),
+    after_next: input.afterNext,
+    auth: {
+      token_source: input.tokenSource,
+      secret_value_included: false,
+      accepted_methods: ["IMAGE_SKILL_TOKEN", "--token-stdin", "config"],
+      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),
+      },
+    },
+    warning: agentSettleable
+      ? "data.self_fund_next_command starts a browserless live-money quote. Preserve auth with data.self_fund_handoff.auth.next_command, then follow payment_commands.buy, pay exactly what wallet_settlement points to, run payment_commands.status, and rerun after_next."
+      : "data.self_fund_next_command starts a live-money payment handoff. Preserve auth with data.self_fund_handoff.auth.next_command, complete the payment, then rerun after_next.",
+  };
+}
+
+function createGuideWalletSettlementHandoff({
+  preferredMethod,
+  browserless,
+  agentSettleable,
+  statusCommand,
+}) {
+  if (
+    preferredMethod !== "stripe_x402.exact.usdc" ||
+    !browserless ||
+    !agentSettleable
+  ) {
+    return null;
+  }
+  return {
+    method_id: "stripe_x402.exact.usdc",
+    wallet_required: true,
+    browser_required: false,
+    network: "base",
+    token_currency: "usdc",
+    exact_amount_required: true,
+    secret_value_included: false,
+    payable_instructions_fields: {
+      buy_response: "data.stripe_x402.payable_instructions",
+      status_response: "data.payment_attempt.stripe_x402.payable_instructions",
+    },
+    amount_atomic_field: "token_amount_atomic",
+    destination_field: "deposit_address",
+    status_command_after_payment: statusCommand,
+    next_step:
+      "Run payment_commands.buy, pay payable_instructions.token_amount_atomic USDC atomic units to payable_instructions.deposit_address on Base from a delegated wallet, then run status_command_after_payment until credits are granted before rerunning after_next.",
+    credential_boundary:
+      "Never send wallet private keys, seed phrases, x402 authorization payloads, Stripe secrets, client secrets, card data, provider receipts, or raw wallet credentials to Image Skill.",
+    warning:
+      "This is live money. Pay exactly the returned Base/USDC amount to the returned deposit address and stay within the delegated cap.",
+  };
+}
+
 function createGuideNextCommandEffect(stage, input) {
   const base = {
     label: "read_only_or_no_media_setup",
@@ -1751,7 +2340,7 @@ function createGuideNextCommandEffect(stage, input) {
       estimated_credits: input.estimatedCredits,
       estimated_debit_usd_per_image: input.estimatedDebitUsdPerImage,
       warning:
-        "data.next_command creates hosted media and can debit credits. For no-spend verification, run data.no_spend_next_command instead.",
+        "data.next_command creates hosted media and can debit credits. For no-spend verification, run data.recommended_no_spend_command (same value as data.no_spend_next_command) instead.",
     };
   }
   if (stage === "prompt_required") {
@@ -1763,6 +2352,140 @@ function createGuideNextCommandEffect(stage, input) {
   return base;
 }
 
+function createGuideNoSpendNextCommandEffect(stage, input) {
+  if (stage !== "ready_to_create") {
+    return null;
+  }
+  return {
+    label:
+      "dry_run_planned_job_no_provider_call_no_credit_debit_no_media_write",
+    no_spend: true,
+    provider_call: false,
+    hosted_create: false,
+    hosted_create_dry_run: true,
+    hosted_signup: false,
+    payment_object: false,
+    credit_debit: false,
+    media_write: false,
+    planned_job: true,
+    plan_receipt: true,
+    activity_event: "job.planned",
+    estimated_credits: input.estimatedCredits,
+    estimated_debit_usd_per_image: input.estimatedDebitUsdPerImage,
+    warning:
+      "data.no_spend_next_command may create a recoverable planned job/activity receipt (job.planned), but it does not call a provider, debit credits, or create downloadable media.",
+  };
+}
+
+function createGuideNoSpendEvaluation(stage, input) {
+  if (stage !== "ready_to_create") {
+    return {
+      stop_here: false,
+      stop_stage: "ready_to_create",
+      stop_reason: null,
+      next_command_is_live_create: false,
+      live_create_command_field: null,
+      live_create_allowed_when: null,
+      recommended_command_field: null,
+      recommended_command: null,
+      recommended_command_label: null,
+      recommended_command_effect: null,
+      warning: null,
+    };
+  }
+  return {
+    stop_here: true,
+    stop_stage: "ready_to_create",
+    stop_reason:
+      "ready_to_create means data.next_command is a live media create; no-spend evaluators should stop before it unless media spend is allowed.",
+    next_command_is_live_create: true,
+    live_create_command_field: "next_command",
+    live_create_allowed_when: "media_spend_allowed",
+    recommended_command_field: "recommended_no_spend_command",
+    recommended_command: input.noSpendNextCommand,
+    recommended_command_label: input.noSpendNextCommandLabel,
+    recommended_command_effect: input.noSpendNextCommandEffect,
+    warning:
+      "For no-spend verification at ready_to_create, run data.recommended_no_spend_command instead of data.next_command.",
+  };
+}
+
+function createGuideWarning(stage, input) {
+  const effect = input.nextCommandEffect;
+  const base = {
+    stage,
+    no_spend_safe:
+      effect.no_spend &&
+      !effect.provider_call &&
+      !effect.payment_object &&
+      !effect.credit_debit &&
+      !effect.media_write,
+    live_money_action: false,
+    spend_required: false,
+    provider_call: effect.provider_call,
+    payment_object: effect.payment_object,
+    credit_debit: effect.credit_debit,
+    media_write: effect.media_write,
+    payment_top_up_path: null,
+  };
+
+  if (stage === "prompt_required") {
+    return {
+      ...base,
+      next_command_safety: "rerun_guide_no_spend",
+      recommended_command_field: "next_command",
+      warning:
+        "data.next_command reruns the free guide with a real prompt; it does not call a provider, open payment, debit credits, or create media.",
+    };
+  }
+  if (stage === "no_executable_model" || stage === "service_unreachable") {
+    return {
+      ...base,
+      next_command_safety: "read_only_inspection_no_spend",
+      recommended_command_field: "next_command",
+      warning:
+        "data.next_command is read-only inspection/recovery; it does not call a provider, open payment, debit credits, or create media.",
+    };
+  }
+  if (stage === "auth_required") {
+    return {
+      ...base,
+      next_command_safety: "hosted_signup_no_spend_setup",
+      recommended_command_field: "next_command",
+      warning:
+        "data.next_command is no-spend hosted signup/setup; it creates a restricted agent identity but does not call a provider, open payment, debit credits, or create media.",
+    };
+  }
+  if (stage === "quota_required") {
+    const paymentTopUpPath =
+      input.paymentSummary.preferred_method_summary?.top_up_path ?? null;
+    return {
+      ...base,
+      next_command_safety: "live_money_payment_action",
+      no_spend_safe: false,
+      live_money_action: true,
+      spend_required: true,
+      recommended_command_field: "escape_hatches",
+      payment_top_up_path: paymentTopUpPath,
+      warning:
+        paymentTopUpPath === "browserless_agent_self_fund"
+          ? "data.next_command starts the browserless live-money top-up path; stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only payment inspection."
+          : paymentTopUpPath === "human_payment_handoff"
+            ? "data.next_command starts a live-money payment handoff that needs human or browser completion; stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only inspection."
+            : "data.next_command starts payment or quota recovery; inspect data.checks.payments before attempting live money, or use data.escape_hatches.payment_methods for read-only inspection.",
+    };
+  }
+  return {
+    ...base,
+    next_command_safety: "live_media_create_credit_debit",
+    no_spend_safe: false,
+    spend_required: true,
+    recommended_command_field: "recommended_no_spend_command",
+    warning:
+      "data.next_command is a live media create that can call a provider, debit credits, and create media. Run it only when media spend is allowed; otherwise run data.recommended_no_spend_command.",
+  };
+}
+
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix);
@@ -1774,11 +2497,7 @@ function createGuideNextCommand(stage, input) {
     );
   }
   if (stage === "auth_required") {
-    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);
+    return renderGuideSignupCommand(input);
   }
   if (stage === "quota_required") {
     return renderGuidePrefixedCommand(
@@ -1788,12 +2507,23 @@ function createGuideNextCommand(stage, input) {
       ),
     );
   }
+  if (createGuideSelectedModelRequiresInputImage(input.selected)) {
+    return renderImageTo3dGuideCommand({
+      modelId: input.selected.id,
+      budgetGuard: input.budgetGuard,
+      dryRun: false,
+      idempotencyKey: `edit-guide-${Date.now()}-${randomBytes(4).toString("hex")}`,
+      apiBaseUrl: input.apiBaseUrl,
+      commandPrefix: input.commandPrefix,
+    });
+  }
   return renderCreateCommand({
     prompt: input.prompt,
     modelId: input.selected.id,
     providerId: input.requestedProviderId,
     intent: input.requestedIntent,
     budgetGuard: input.budgetGuard,
+    aspectRatio: input.aspectRatio,
     dryRun: false,
     // Retry-safe by default (#1228): bake a stable idempotency key into the
     // advertised create command so an agent that copies it and retries after a
@@ -1828,16 +2558,25 @@ function createGuideEscapeHatches(input) {
             input.commandPrefix,
             "create --dry-run --prompt PROMPT --json",
           )
-        : renderCreateCommand({
-            prompt: input.prompt,
-            modelId: input.selected.id,
-            providerId: input.requestedProviderId,
-            intent: input.requestedIntent,
-            budgetGuard: input.budgetGuard,
-            dryRun: true,
-            apiBaseUrl: input.apiBaseUrl,
-            commandPrefix: input.commandPrefix,
-          }),
+        : createGuideSelectedModelRequiresInputImage(input.selected)
+          ? renderImageTo3dGuideCommand({
+              modelId: input.selected.id,
+              budgetGuard: input.budgetGuard,
+              dryRun: true,
+              apiBaseUrl: input.apiBaseUrl,
+              commandPrefix: input.commandPrefix,
+            })
+          : renderCreateCommand({
+              prompt: input.prompt,
+              modelId: input.selected.id,
+              providerId: input.requestedProviderId,
+              intent: input.requestedIntent,
+              budgetGuard: input.budgetGuard,
+              aspectRatio: input.aspectRatio,
+              dryRun: true,
+              apiBaseUrl: input.apiBaseUrl,
+              commandPrefix: input.commandPrefix,
+            }),
   };
 }
 
@@ -1851,6 +2590,23 @@ function renderGuideCommand(prompt, apiBaseUrl, commandPrefix = "image-skill") {
   ].join(" ");
 }
 
+function renderGuideSignupCommand(input) {
+  const signupCommand = [
+    "signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name AGENT_NAME --runtime RUNTIME_NAME",
+    ...(input.apiBaseUrl === null
+      ? []
+      : ["--api-base-url", shellQuote(input.apiBaseUrl)]),
+    "--json",
+  ].join(" ");
+  const command = renderGuidePrefixedCommand(
+    input.commandPrefix,
+    signupCommand,
+  );
+  return input.authConfigWritable === false
+    ? renderWritableConfigCommand(command)
+    : command;
+}
+
 function renderTokenStdinCommand(command) {
   return `printf '%s\\n' "$IMAGE_SKILL_TOKEN" | ${command} --token-stdin`;
 }
@@ -1865,6 +2621,37 @@ function firstPaymentActionCommand(commands) {
   );
 }
 
+function guidePaymentCommandByKind(commands, kind) {
+  const pattern =
+    kind === "quote"
+      ? /\bcredits\s+quote\b/
+      : kind === "buy"
+        ? /\bcredits\s+buy\b/
+        : /\bcredits\s+status\b/;
+  return commands.find((command) => pattern.test(command)) ?? null;
+}
+
+function renderImageTo3dGuideCommand(input) {
+  return [
+    input.commandPrefix ?? "image-skill",
+    "edit",
+    ...(input.dryRun ? ["--dry-run"] : []),
+    "--input",
+    "image_...",
+    "--model",
+    shellQuote(input.modelId),
+    "--max-estimated-usd-per-image",
+    shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.idempotencyKey === undefined || input.idempotencyKey === null
+      ? []
+      : ["--idempotency-key", shellQuote(input.idempotencyKey)]),
+    ...(input.apiBaseUrl === null
+      ? []
+      : ["--api-base-url", shellQuote(input.apiBaseUrl)]),
+    "--json",
+  ].join(" ");
+}
+
 function renderCreateCommand(input) {
   return [
     input.commandPrefix ?? "image-skill",
@@ -1879,6 +2666,9 @@ function renderCreateCommand(input) {
     shellQuote(input.prompt),
     "--intent",
     shellQuote(input.intent),
+    ...(input.aspectRatio === null || input.aspectRatio === undefined
+      ? []
+      : ["--aspect-ratio", shellQuote(input.aspectRatio)]),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
     ...(input.idempotencyKey === undefined || input.idempotencyKey === null
@@ -1895,6 +2685,10 @@ function renderGuidePrefixedCommand(commandPrefix, command) {
   return `${commandPrefix} ${stripImageSkillCommandPrefix(command)}`;
 }
 
+function renderWritableConfigCommand(command) {
+  return `IMAGE_SKILL_CONFIG_PATH="${LOCAL_WRITABLE_CONFIG_PATH}" ${command}`;
+}
+
 function stripImageSkillCommandPrefix(command) {
   return String(command ?? "").replace(/^image-skill\s+/, "");
 }
@@ -2120,6 +2914,7 @@ async function edit(argv) {
       ...(modelParameters.value === null
         ? {}
         : { model_parameters: modelParameters.value }),
+      ...(flagBool(args, "dry-run") ? { dry_run: true } : {}),
       // Retry-safe dedupe (#1228): see create — same key dedupes a retry that
       // follows a transient 502 which already debited a credit.
       ...(flagString(args, "idempotency-key") === null
@@ -3028,20 +3823,19 @@ function trustSafeCommands() {
   return [
     {
       purpose: "trust_packet",
-      command: "npx -y image-skill@latest trust --json",
+      command: `${PUBLIC_NPX_COMMAND_PREFIX} trust --json`,
       mutation: false,
       spend: false,
     },
     {
       purpose: "first_image_guide",
-      command:
-        'npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json',
+      command: `${PUBLIC_NPX_COMMAND_PREFIX} create --guide --prompt "a compact field camera on a stainless workbench" --json`,
       mutation: false,
       spend: false,
     },
     {
       purpose: "model_inspection",
-      command: "npx -y image-skill@latest models list --json",
+      command: `${PUBLIC_NPX_COMMAND_PREFIX} models list --json`,
       mutation: false,
       spend: false,
     },
@@ -3659,19 +4453,22 @@ function configWriteErrorMessage(error) {
 }
 
 function configWriteRecovery(command) {
-  const safeConfigPath = "$PWD/.image-skill/config.json";
-  const baseSignupCommand = `IMAGE_SKILL_CONFIG_PATH="${safeConfigPath}" ${SIGNUP_SUGGESTED_COMMAND}`;
+  const baseSignupCommand = renderWritableConfigCommand(
+    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`,
+      suggested_config_path: LOCAL_WRITABLE_CONFIG_PATH,
+      suggested_command: renderWritableConfigCommand(
+        "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_config_path: LOCAL_WRITABLE_CONFIG_PATH,
     suggested_command: baseSignupCommand,
     fallback_command: `${SIGNUP_SUGGESTED_COMMAND} --show-token --no-save`,
     fallback_auth_method: "--token-stdin",