image-skill 0.1.34 → 0.1.36

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.36 - 2026-06-04
+
+- Fix (guide): `create --guide --json` now marks templated follow-up commands
+  explicitly with `data.next_command_copy_runnable`,
+  `data.next_command_missing_inputs`, and
+  `data.next_command_effect.requires_placeholder_substitution`. Auth signup,
+  prompt recovery, payment handoff, and input-asset templates remain visible to
+  agents, but placeholder values such as `AGENT_OR_OPERATOR_INBOX`,
+  `AGENT_NAME`, `RUNTIME_NAME`, `QUOTE_ID`, and `PAYMENT_ATTEMPT_ID` are no
+  longer presented as if the command can be copied blindly.
+
+## 0.1.35 - 2026-06-04
+
+- Fix (CLI aliases): natural modality-first commands now route into the
+  guide-first public runtime. `image-skill image create`,
+  `image-skill video create`, `image-skill audio create`,
+  `image-skill 3d create`, and `image-skill image edit` normalize to the
+  existing `create` / `edit` flows instead of failing with
+  `PUBLIC_CLI_COMMAND_NOT_AVAILABLE`. Video, audio, and 3D aliases add the
+  matching intent hint unless the agent already supplied `--intent`.
+
 ## 0.1.34 - 2026-06-04
 
 - Fix (guide): `create --guide --model openai.gpt-image-2-edit` now returns an

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.34";
+const VERSION = "0.1.36";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -37,6 +37,14 @@ const HOSTED_SIGNUP_TOKEN_RETURNED_WARNING =
 const PUBLIC_NPX_COMMAND_PREFIX =
   "npm_config_update_notifier=false npx -y image-skill@latest";
 const CREDIT_UNIT_USD = 0.01;
+const MODALITY_COMMAND_ALIASES = new Map([
+  ["image", { command: "create", intent: null }],
+  ["video", { command: "create", intent: "video" }],
+  ["audio", { command: "create", intent: "audio" }],
+  ["3d", { command: "create", intent: "image-to-3d" }],
+  ["image-to-3d", { command: "create", intent: "image-to-3d" }],
+  ["three-d", { command: "create", intent: "image-to-3d" }],
+]);
 const PAYMENT_CREDENTIAL_FLAGS = new Set([
   "payment-token",
   "payment-secret",
@@ -57,8 +65,72 @@ const PAYMENT_CREDENTIAL_FLAGS = new Set([
   "provider-key",
   "provider-receipt",
 ]);
-
-const argv = process.argv.slice(2);
+const GUIDE_NEXT_COMMAND_PLACEHOLDERS = [
+  {
+    placeholder: "AGENT_OR_OPERATOR_INBOX",
+    flag: "--agent-contact",
+    value_description:
+      "Email-shaped durable contact inbox for the restricted agent identity; use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox.",
+    effect_description: "email-shaped durable contact inbox",
+    example: "agent-inbox@example.com",
+  },
+  {
+    placeholder: "AGENT_NAME",
+    flag: "--agent-name",
+    value_description:
+      "Stable display name for this restricted agent identity.",
+    effect_description: "stable agent identity name",
+    example: "codex-image-worker",
+  },
+  {
+    placeholder: "RUNTIME_NAME",
+    flag: "--runtime",
+    value_description:
+      "Stable name for the agent runtime or substrate using Image Skill.",
+    effect_description: "agent/runtime substrate name",
+    example: "codex-cli",
+  },
+  {
+    placeholder: "PROMPT",
+    flag: "--prompt",
+    value_description: "The real creative prompt to plan or create.",
+    effect_description: "real creative prompt",
+    example: "a compact field camera on a stainless workbench",
+  },
+  {
+    placeholder: "KEY",
+    flag: "--idempotency-key",
+    value_description:
+      "Unique idempotency key for this payment or create attempt.",
+    effect_description: "unique idempotency key",
+    example: "agent-generated-idempotency-key",
+  },
+  {
+    placeholder: "QUOTE_ID",
+    flag: "--quote-id",
+    value_description: "Quote id returned by the preceding credits quote call.",
+    effect_description: "quote id from credits quote",
+    example: null,
+  },
+  {
+    placeholder: "PAYMENT_ATTEMPT_ID",
+    flag: "--payment-attempt-id",
+    value_description:
+      "Payment attempt id returned by the preceding credits buy call.",
+    effect_description: "payment attempt id from credits buy",
+    example: null,
+  },
+  {
+    placeholder: "image_...",
+    flag: "--input",
+    value_description:
+      "Image Skill input asset id, usually from upload, assets, jobs, or a previous create.",
+    effect_description: "Image Skill input asset id",
+    example: null,
+  },
+];
+
+const argv = normalizePublicArgv(process.argv.slice(2));
 const result = await main(argv);
 process.stdout.write(`${JSON.stringify(result.envelope, null, 2)}\n`);
 process.exitCode = result.exitCode;
@@ -71,7 +143,7 @@ async function main(rawArgv) {
   }
 
   if (command === "help") {
-    return publicCliHelp(helpTarget(rest));
+    return publicCliHelp(helpTarget(normalizePublicArgv(rest)));
   }
 
   if (hasHelpFlag(rest)) {
@@ -160,10 +232,37 @@ function hasHelpFlag(argv) {
   return argv.includes("--help") || argv.includes("-h");
 }
 
+function normalizePublicArgv(argv) {
+  const [maybeModality, maybeSubcommand, ...rest] = argv;
+  if (maybeModality === undefined || maybeSubcommand === undefined) {
+    return argv;
+  }
+
+  const alias = MODALITY_COMMAND_ALIASES.get(maybeModality);
+  if (alias === undefined) {
+    return argv;
+  }
+
+  if (maybeSubcommand === "create") {
+    if (
+      alias.intent !== null &&
+      !rest.some((arg) => arg === "--intent" || arg.startsWith("--intent="))
+    ) {
+      return [alias.command, "--intent", alias.intent, ...rest];
+    }
+    return [alias.command, ...rest];
+  }
+
+  if (maybeModality === "image" && maybeSubcommand === "edit") {
+    return ["edit", ...rest];
+  }
+
+  return argv;
+}
+
 function helpTarget(argv) {
-  return argv.filter(
-    (arg) => arg !== "--help" && arg !== "-h" && arg !== "--json",
-  );
+  return parseArgs(argv.filter((arg) => arg !== "--help" && arg !== "-h"))
+    .positionals;
 }
 
 function helpKey(path) {
@@ -177,30 +276,36 @@ function helpKey(path) {
 function commandHelpByKey(key) {
   return {
     "": {
-      command: "image-skill help",
+      command: "help",
       usage:
-        "image-skill <doctor|trust|signup|auth|whoami|usage|quota|credits|models|capabilities|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "image-skill <doctor|trust|signup|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
       docs_url: "https://image-skill.com/cli.md",
       commands: [
         "doctor",
         "trust",
         "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
-        "auth status",
-        "auth save",
-        "auth logout",
         "whoami",
         "usage quota",
+        "quota",
         "credits methods",
-        "credits packs list",
         "credits quote",
+        "credits packs list",
         "credits buy",
         "credits status",
+        "capabilities",
+        "capabilities list",
+        "capabilities show",
+        "models",
         "models list",
         "models show",
         "create --guide",
-        "capabilities list",
-        "capabilities show",
+        "image create --guide",
+        "video create --guide",
+        "audio create --guide",
+        "3d create --guide",
+        "create --dry-run",
         "create",
+        "image edit",
         "upload",
         "edit",
         "assets show",
@@ -289,7 +394,7 @@ function commandHelpByKey(key) {
     },
     "credits methods": {
       command: "image-skill credits methods help",
-      usage: "image-skill credits methods --json",
+      usage: "image-skill credits methods",
       docs_url: "https://image-skill.com/cli.md#image-skill-credits",
     },
     "credits packs": {
@@ -332,6 +437,16 @@ function commandHelpByKey(key) {
       usage:
         "image-skill models list --available --operation image.generate --json",
       docs_url: "https://image-skill.com/cli.md#image-skill-models",
+      optional_flags: [
+        "--available",
+        "--executable",
+        "--catalog-only",
+        "--operation",
+        "--modality",
+        "--provider",
+        "--summary",
+        "--details",
+      ],
     },
     "models show": {
       command: "image-skill models show help",
@@ -365,6 +480,9 @@ function commandHelpByKey(key) {
         "--model",
         "--aspect-ratio",
         "--output-count",
+        "--element-frontal",
+        "--element-reference",
+        "--reference-image",
         "--model-parameters-json",
         "--idempotency-key",
       ],
@@ -385,6 +503,8 @@ function commandHelpByKey(key) {
         "--model",
         "--mask",
         "--element-reference",
+        "--element-frontal",
+        "--reference-image",
         "--model-parameters-json",
         "--idempotency-key",
       ],
@@ -897,12 +1017,6 @@ async function credits(argv) {
       (flag) =>
         !["json", "api-base-url", "token", "token-stdin"].includes(flag),
     );
-    if (!flagBool(args, "json")) {
-      return invalid(
-        "image-skill credits methods",
-        "credits methods requires --json",
-      );
-    }
     if (args.positionals.length > 0 || unknownFlags.length > 0) {
       return invalid(
         "image-skill credits methods",
@@ -993,7 +1107,7 @@ async function credits(argv) {
     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",
+        "credits quote requires --payment-method from credits methods; 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)) {
@@ -1134,13 +1248,13 @@ async function models(argv) {
     subcommand === "list" || subcommand === "show" ? rest : argv,
   );
   if (subcommand === "show") {
-    const modelId = args.positionals[0];
-    if (modelId === undefined) {
+    if (args.positionals.length !== 1) {
       return invalid(
         "image-skill models show",
-        "models show requires MODEL_ID",
+        "models show requires exactly one MODEL_ID",
       );
     }
+    const modelId = args.positionals[0];
     return apiRequest({
       command: "image-skill models show",
       method: "GET",
@@ -1169,13 +1283,21 @@ async function models(argv) {
     apiBaseUrl: apiBase(args),
     path: query.path,
   });
-  return flagBool(args, "summary") ? withModelSummary(result) : result;
+  return flagBool(args, "details") ? result : withModelSummary(result);
 }
 
 function modelListQuery(args) {
   const available = flagBool(args, "available");
   const executable = flagBool(args, "executable");
   const catalogOnly = flagBool(args, "catalog-only");
+  const summary = flagBool(args, "summary");
+  const details = flagBool(args, "details");
+  if (summary && details) {
+    return {
+      ok: false,
+      message: "models list --summary cannot be combined with --details",
+    };
+  }
   if (catalogOnly && (available || executable)) {
     return {
       ok: false,
@@ -1193,6 +1315,9 @@ function modelListQuery(args) {
   if (catalogOnly) {
     params.set("catalog_only", "true");
   }
+  if (details) {
+    params.set("details", "true");
+  }
   addQueryValue(params, "operation", flagString(args, "operation"));
   addQueryValue(params, "modality", flagString(args, "modality"));
   addQueryValue(params, "provider", flagString(args, "provider"));
@@ -1208,6 +1333,9 @@ function withModelSummary(result) {
   if (!isRecord(data) || !Array.isArray(data.models)) {
     return result;
   }
+  if (data.summary?.result_shape === "compact_model_summary") {
+    return result;
+  }
   return {
     ...result,
     envelope: {
@@ -1217,7 +1345,7 @@ function withModelSummary(result) {
         summary: {
           ...(isRecord(data.summary) ? data.summary : {}),
           result_shape: "compact_model_summary",
-          full_list_command: "image-skill models list --json",
+          full_list_command: "image-skill models list --details --json",
         },
         models: data.models.map(modelSummaryRow),
       },
@@ -1228,11 +1356,13 @@ function withModelSummary(result) {
 function modelSummaryRow(model) {
   return {
     id: model.id,
+    default: model.default === true,
     display_name: model.display_name,
     provider_id: model.provider_id,
     mode: model.mode,
     status: model.status,
     availability_reason: model.availability_reason ?? null,
+    modality: model.modality ?? "image",
     supports: Array.isArray(model.supports) ? [...model.supports] : [],
     operations: Array.isArray(model.operations) ? [...model.operations] : [],
     task_tags: modelSummaryTaskTags(model),
@@ -1505,6 +1635,9 @@ async function createGuide(args) {
     commandPrefix: guideCommandPrefix,
     authConfigWritable: authConfigWrite?.ok ?? true,
   });
+  const nextCommandMissingInputs =
+    createGuideNextCommandMissingInputs(nextCommand);
+  const nextCommandCopyRunnable = nextCommandMissingInputs.length === 0;
   const escapeHatches = createGuideEscapeHatches({
     prompt: trimmedPrompt,
     selected,
@@ -1521,6 +1654,8 @@ async function createGuide(args) {
   const nextCommandEffect = createGuideNextCommandEffect(stage, {
     estimatedCredits,
     estimatedDebitUsdPerImage,
+    nextCommandCopyRunnable,
+    nextCommandMissingInputs,
   });
   const noSpendNextCommand =
     stage === "ready_to_create" ? escapeHatches.dry_run : null;
@@ -1540,6 +1675,7 @@ async function createGuide(args) {
   const guideWarning = createGuideWarning(stage, {
     nextCommandEffect,
     paymentSummary,
+    nextCommandCopyRunnable,
   });
   const selfFundNextCommand = stage === "quota_required" ? nextCommand : null;
   const selfFundNextCommandLabel = createGuideSelfFundNextCommandLabel(
@@ -1570,6 +1706,7 @@ async function createGuide(args) {
     authenticated,
     tokenSource: publicTokenSource,
     savedConfigPath: configPath(),
+    nextCommandCopyRunnable,
   });
   const selfFundHandoff = createGuideSelfFundHandoff(stage, {
     paymentSummary,
@@ -1663,6 +1800,8 @@ async function createGuide(args) {
     guide_warning: guideWarning,
     auth_ready: authReady,
     next_command: nextCommand,
+    next_command_copy_runnable: nextCommandCopyRunnable,
+    next_command_missing_inputs: nextCommandMissingInputs,
     next_command_effect: nextCommandEffect,
     no_spend_next_command: noSpendNextCommand,
     no_spend_next_command_label: noSpendNextCommandLabel,
@@ -2262,7 +2401,9 @@ function createGuideAuthReady(stage, input) {
     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."
+        ? input.nextCommandCopyRunnable
+          ? "Auth is not ready yet; run data.next_command to create a restricted agent identity, then rerun the guide."
+          : "Auth is not ready yet; fill data.next_command_missing_inputs before running the data.next_command signup template, then rerun the guide."
         : null,
   };
 }
@@ -2393,6 +2534,9 @@ function createGuideWalletSettlementHandoff({
 }
 
 function createGuideNextCommandEffect(stage, input) {
+  const placeholders = createGuideEffectPlaceholders(
+    input.nextCommandMissingInputs,
+  );
   const base = {
     label: "read_only_or_no_media_setup",
     no_spend: true,
@@ -2404,6 +2548,9 @@ function createGuideNextCommandEffect(stage, input) {
     media_write: false,
     estimated_credits: null,
     estimated_debit_usd_per_image: null,
+    copy_runnable: input.nextCommandCopyRunnable,
+    requires_placeholder_substitution: placeholders.length > 0,
+    placeholders,
     warning: null,
   };
   if (stage === "auth_required") {
@@ -2437,6 +2584,9 @@ function createGuideNextCommandEffect(stage, input) {
       media_write: true,
       estimated_credits: input.estimatedCredits,
       estimated_debit_usd_per_image: input.estimatedDebitUsdPerImage,
+      copy_runnable: input.nextCommandCopyRunnable,
+      requires_placeholder_substitution: placeholders.length > 0,
+      placeholders,
       warning:
         "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.",
     };
@@ -2532,8 +2682,9 @@ function createGuideWarning(stage, input) {
       ...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.",
+      warning: input.nextCommandCopyRunnable
+        ? "data.next_command reruns the free guide with a real prompt; it does not call a provider, open payment, debit credits, or create media."
+        : "data.next_command is a no-spend guide template; fill data.next_command_missing_inputs before running it. It does not call a provider, open payment, debit credits, or create media.",
     };
   }
   if (stage === "no_executable_model" || stage === "service_unreachable") {
@@ -2550,8 +2701,9 @@ function createGuideWarning(stage, input) {
       ...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.",
+      warning: input.nextCommandCopyRunnable
+        ? "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."
+        : "data.next_command is a no-spend hosted signup/setup template; fill data.next_command_missing_inputs before running it. It creates a restricted agent identity but does not call a provider, open payment, debit credits, or create media.",
     };
   }
   if (stage === "quota_required") {
@@ -2565,12 +2717,17 @@ function createGuideWarning(stage, input) {
       spend_required: true,
       recommended_command_field: "escape_hatches",
       payment_top_up_path: paymentTopUpPath,
-      warning:
-        paymentTopUpPath === "browserless_agent_self_fund"
+      warning: input.nextCommandCopyRunnable
+        ? 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.",
+            : "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."
+        : paymentTopUpPath === "browserless_agent_self_fund"
+          ? "data.next_command is a browserless live-money top-up template; fill data.next_command_missing_inputs before running it, stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only payment inspection."
+          : paymentTopUpPath === "human_payment_handoff"
+            ? "data.next_command is a live-money payment handoff template; fill data.next_command_missing_inputs before running it, stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only inspection."
+            : "data.next_command is a live-money payment template; fill data.next_command_missing_inputs before running it, stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only inspection.",
     };
   }
   return {
@@ -2584,6 +2741,40 @@ function createGuideWarning(stage, input) {
   };
 }
 
+function createGuideNextCommandMissingInputs(command) {
+  return GUIDE_NEXT_COMMAND_PLACEHOLDERS.filter((placeholder) =>
+    commandContainsTemplateToken(command, placeholder.placeholder),
+  ).map((placeholder) => ({
+    flag: placeholder.flag,
+    placeholder: placeholder.placeholder,
+    value_description: placeholder.value_description,
+    example: placeholder.example,
+  }));
+}
+
+function createGuideEffectPlaceholders(missingInputs) {
+  return missingInputs.map((input) => {
+    const placeholder = GUIDE_NEXT_COMMAND_PLACEHOLDERS.find(
+      (candidate) => candidate.placeholder === input.placeholder,
+    );
+    return {
+      token: input.placeholder,
+      description: placeholder?.effect_description ?? input.value_description,
+      required: true,
+    };
+  });
+}
+
+function commandContainsTemplateToken(command, token) {
+  return new RegExp(
+    `(^|[^A-Za-z0-9_])${escapeRegExp(token)}(?=$|[^A-Za-z0-9_])`,
+  ).test(command);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix, {

package/cli.md

@@ -69,6 +69,11 @@ copyable commands, proof URL placeholders, and redaction guarantees.
 Use `trust` when deciding whether Image Skill is current and honest enough to
 select. It is not a required setup step before the first image; the canonical
 fresh-agent creative entrypoint remains `image-skill create --guide`.
+Agents may also use modality-first aliases when that is the natural wording:
+`image-skill image create --guide`, `image-skill video create --guide`,
+`image-skill audio create --guide`, and `image-skill 3d create --guide` all
+route into the same `create --guide` flow, with video/audio/3D intent hints
+added only when the agent did not already provide `--intent`.
 
 If package metadata, hosted docs, API health, or model availability cannot be
 verified, the command still returns a packet with explicit `unreachable`,
@@ -129,7 +134,8 @@ should omit it.
 Use the no-spend guide first. It is the only required first command for a fresh
 agent. It checks health, executable model availability, auth/quota when a token
 already exists, and payment rails, then returns one primary
-`data.next_command` plus machine-readable `data.next_command_effect`,
+`data.next_command` plus machine-readable `data.next_command_copy_runnable`,
+`data.next_command_missing_inputs`, `data.next_command_effect`,
 `data.guide_warning`, `data.auth_ready`, and `data.no_spend_evaluation`. Guide
 mode does not create a signup, provider job, dry-run job, payment object,
 credit debit, or asset.
@@ -138,22 +144,28 @@ credit debit, or asset.
 image-skill create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-Read `data.stage` and `data.guide_warning`, run `data.next_command` when
-`data.guide_warning.next_command_safety` is safe for the current spend policy,
-and rerun the guide only after auth or payment state changes. Do not run
+Read `data.stage` and `data.guide_warning`, run `data.next_command` only when
+`data.next_command_copy_runnable` is `true` and
+`data.guide_warning.next_command_safety` is safe for the current spend policy.
+When `data.next_command_copy_runnable` is `false`, fill
+`data.next_command_missing_inputs` first. Rerun the guide only after auth or
+payment state changes. Do not run
 `doctor`, `models list`, `signup`, `whoami`, `usage quota`, `create --dry-run`,
 or payment commands as a setup 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. Hosted
-  signup saves auth to config by default. If the runtime intentionally used
+- `prompt_required`: fill `data.next_command_missing_inputs` with the real
+  prompt, then rerun `data.next_command`.
+- `auth_required`: fill `data.next_command_missing_inputs` when present, 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`. In this stage,
   `data.auth_ready.ready` is `false`, and
   `data.guide_warning.next_command_safety` is
   `hosted_signup_no_spend_setup`.
-- `quota_required`: run `data.self_fund_next_command` to start the top-up.
+- `quota_required`: fill `data.next_command_missing_inputs` when present, then
+  run `data.self_fund_next_command` to start the top-up.
   It aliases `data.next_command` and is the first payment command, usually an
   x402 or Stripe quote. If the guide authenticated from env or stdin, prefer
   `data.self_fund_handoff.auth.next_command.with_env` or
@@ -762,7 +774,7 @@ capability-preserving schema for one model.
 ```bash
 image-skill models --json
 image-skill models list --json
-image-skill models list --summary --json
+image-skill models list --details --json
 image-skill models list --available --operation image.generate --json
 image-skill models list --available --operation image.edit --json
 image-skill models list --available --modality video --operation video.generate --json
@@ -793,20 +805,23 @@ inspect the recommended create surface without knowing a provider-specific
 model id. The list response also returns `summary` with total, returned,
 available, executable, catalog-only, provider split,
 `execution_availability`, first actionable model ids, recommended filter
-commands, and catalog-inclusion flags. Default list output excludes
-catalog-only rows so fresh agents see executable candidates first. Use
-`--summary` when you need a compact, sortable model menu: each row keeps the
-model id, flat `estimated_usd_per_image`, `credits_required`, lightweight
-`task_tags`, status, provider, max output count/resolution, storage, and
-`show_command`, while omitting full parameter schemas. Use `--available` for
-currently usable executable rows, `--modality image|video|audio|3d` for media
-type, `--operation image.generate`, `--operation image.edit`,
-`--operation video.generate`, `--operation audio.generate`, or
-`--operation 3d.generate` for the task, `--provider fal|xai|openai` to narrow by
-provider, and `--catalog-only` when you intentionally want source-backed rows
-that are inspectable but not runnable yet. Provider-level availability is not
-the same thing as model executability; for runnable choices require both
-`status:"available"` and
+commands, and catalog-inclusion flags. Default list output is a compact,
+sortable model menu and excludes catalog-only rows so fresh agents see
+executable candidates first. Each row keeps the model id, flat
+`estimated_usd_per_image`, `credits_required`, lightweight `task_tags`, status,
+provider, max output count/resolution, storage, and `show_command`, while
+omitting full parameter schemas. Use `models show MODEL_ID --json` for one
+model's full capability schema, or `models list --details --json` only when you
+intentionally need the full list with capability schemas for compatibility or
+offline analysis. `--summary` is still accepted as a compatibility alias for the
+default compact list. Use `--available` for currently usable executable rows,
+`--modality image|video|audio|3d` for media type, `--operation
+image.generate`, `--operation image.edit`, `--operation video.generate`,
+`--operation audio.generate`, or `--operation 3d.generate` for the task,
+`--provider fal|xai|openai` to narrow by provider, and `--catalog-only` when you
+intentionally want source-backed rows that are inspectable but not runnable yet.
+Provider-level availability is not the same thing as model executability; for
+runnable choices require both `status:"available"` and
 `execution.model_execution_status:"executable"`. If a reachable provider has no
 runnable model for the requested operation, `summary.execution_availability`
 says so directly and includes the fastest `--available --operation ...`
@@ -894,13 +909,15 @@ image-skill create --guide --prompt "A compact field camera on a stainless workb
 ```
 
 `create --guide` returns `schema: image-skill.create-guide.v1`,
-`stage`, `next_command`, `guide_warning`, `auth_ready`, `no_spend_evaluation`,
-`recommended_no_spend_command`,
+`stage`, `next_command`, `next_command_copy_runnable`,
+`next_command_missing_inputs`, `guide_warning`, `auth_ready`,
+`no_spend_evaluation`, `recommended_no_spend_command`,
 `self_fund_next_command`, `self_fund_handoff`, `escape_hatches`, selected
 executable model and cost, 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.
-For next-command safety, read `guide_warning.next_command_safety` before
+For next-command safety, read `next_command_copy_runnable`,
+`next_command_missing_inputs`, and `guide_warning.next_command_safety` before
 acting: `hosted_signup_no_spend_setup` is no-spend auth setup,
 `live_money_payment_action` is top-up/payment work, and
 `live_media_create_credit_debit` is a live create that can call a provider,