image-skill 0.1.43 → 0.1.45

package/bin/image-skill.mjs

@@ -15,7 +15,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.43";
+const VERSION = "0.1.45";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -49,6 +49,9 @@ 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 TARGET_GROSS_MARGIN = 0.4;
+const PAYMENT_BACKED_CREDIT_PAYMENT_FEE_RATE = 0.015;
+const PAYMENT_BACKED_CREDIT_PAYMENT_FEE_MODEL = "stripe_stablecoin_usd_percent";
 const MODALITY_COMMAND_ALIASES = new Map([
   ["image", { command: "create", intent: null }],
   ["video", { command: "create", intent: "video" }],
@@ -529,6 +532,7 @@ function commandHelpByKey(key) {
       docs_url: "https://image-skill.com/cli.md#image-skill-edit",
       required_flags: ["--input"],
       optional_flags: [
+        "--guide",
         "--dry-run",
         "--prompt",
         "--model",
@@ -1607,17 +1611,19 @@ async function capabilities(argv) {
   });
 }
 
-async function createGuide(args) {
+async function createGuide(args, options = {}) {
+  const guideOperation = options.guideOperation ?? "create";
+  const command = `image-skill ${guideOperation} --guide`;
   if (flagBool(args, "dry-run")) {
     return invalid(
-      "image-skill create --guide",
-      "create --guide cannot be combined with --dry-run; the guide returns the dry-run escape hatch separately",
+      command,
+      `${guideOperation} --guide cannot be combined with --dry-run; the guide returns the dry-run escape hatch separately`,
     );
   }
   if (hasReferenceFlags(args)) {
     return invalid(
-      "image-skill create --guide",
-      "create --guide does not upload or resolve reference images; inspect the model with models show, then run create --dry-run before live referenced creates",
+      command,
+      `${guideOperation} --guide does not upload or resolve reference images; inspect the model with models show, then run ${guideOperation} --dry-run before live referenced media calls`,
     );
   }
   const modelParameters = jsonObjectFlag(args, "model-parameters-json");
@@ -1632,6 +1638,10 @@ async function createGuide(args) {
   const requestedProviderId = flagString(args, "provider");
   const requestedIntentFlag = flagString(args, "intent");
   const requestedIntent = requestedIntentFlag ?? "explore";
+  const requestedModelParametersJson =
+    modelParameters.value === null
+      ? null
+      : JSON.stringify(modelParameters.value);
   const maxEstimatedUsdPerImage = flagNumber(
     args,
     "max-estimated-usd-per-image",
@@ -1662,17 +1672,58 @@ async function createGuide(args) {
   const selected =
     models.envelope.ok && models.envelope.data?.models
       ? selectCreateGuideModel(models.envelope.data.models, requestedModelId, {
+          operation: guideOperation,
           prompt: trimmedPrompt,
           intent: requestedIntent,
           maxEstimatedUsdPerImage,
         })
       : null;
   const selectedAspectRatio = createGuideSuggestedAspectRatio(selected);
-  const pricing = createGuideModelCreditPricing(selected);
+  const pricingContext = {
+    aspectRatio: selectedAspectRatio ?? "1:1",
+    outputCount: 1,
+  };
+  const defaultedModelParameters =
+    selected === null || createGuideSelectedModelRequiresInputImage(selected)
+      ? {
+          modelParameters: modelParameters.value ?? {},
+          defaultsApplied: [],
+        }
+      : createGuideDefaultModelParameters({
+          model: selected,
+          aspectRatio: pricingContext.aspectRatio,
+          intent: requestedIntent,
+          modelParameters: modelParameters.value ?? {},
+          maxEstimatedUsdPerImage,
+        });
+  const shouldPriceModelParameters =
+    selected !== null &&
+    !createGuideSelectedModelRequiresInputImage(selected) &&
+    createGuideCanPriceModelParameters(selected) &&
+    (defaultedModelParameters.defaultsApplied.length > 0 ||
+      Object.keys(modelParameters.value ?? {}).length > 0);
+  const pricing =
+    selected === null
+      ? null
+      : shouldPriceModelParameters
+        ? createGuidePricingForModel(
+            selected,
+            defaultedModelParameters.modelParameters,
+            pricingContext,
+          )
+        : createGuideModelCreditPricing(selected);
+  const providerCostEstimate =
+    selected === null || !shouldPriceModelParameters
+      ? null
+      : createGuideProviderCostEstimateForModel(
+          selected,
+          defaultedModelParameters.modelParameters,
+          pricingContext,
+        );
   const estimatedCredits = pricing?.credits_required ?? null;
   const estimatedProviderUsdPerImage =
+    providerCostEstimate?.estimated_provider_cost_usd ??
     selected?.economics?.estimated_usd_per_image ??
-    pricing?.estimated_provider_cost_usd ??
     pricing?.fallback_provider_cost_usd ??
     (typeof selected?.estimated_usd_per_image === "number"
       ? selected.estimated_usd_per_image
@@ -1699,6 +1750,9 @@ async function createGuide(args) {
     token.source === "anonymous" ? "none" : token.source;
   const stage = createGuideStage({
     prompt: trimmedPrompt,
+    promptRequired:
+      trimmedPrompt.length === 0 &&
+      (selected === null || !PROMPTLESS_EDIT_MODEL_IDS.has(selected.id)),
     health,
     models,
     selected,
@@ -1730,9 +1784,12 @@ async function createGuide(args) {
     requestedIntent,
     requestedIntentFlag,
     requestedModelId,
+    guideOperation,
+    inputReference: options.inputReference,
     maxEstimatedUsdPerImage,
     budgetGuard,
     aspectRatio: selectedAspectRatio,
+    modelParametersJson: requestedModelParametersJson,
     apiBaseUrl: explicitApiBaseUrl(args),
     paymentSummary,
     commandPrefix: guideCommandPrefix,
@@ -1748,9 +1805,12 @@ async function createGuide(args) {
     requestedIntent,
     requestedIntentFlag,
     requestedModelId,
+    guideOperation,
+    inputReference: options.inputReference,
     maxEstimatedUsdPerImage,
     budgetGuard,
     aspectRatio: selectedAspectRatio,
+    modelParametersJson: requestedModelParametersJson,
     apiBaseUrl: explicitApiBaseUrl(args),
     commandPrefix: guideCommandPrefix,
   });
@@ -1792,10 +1852,13 @@ async function createGuide(args) {
           explicitApiBaseUrl(args),
           guideCommandPrefix,
           {
+            operation: guideOperation,
+            inputReference: options.inputReference,
             modelId: requestedModelId,
             providerId: requestedProviderId,
             intent: requestedIntentFlag,
             maxEstimatedUsdPerImage,
+            modelParametersJson: requestedModelParametersJson,
           },
         )
       : null;
@@ -1818,8 +1881,19 @@ async function createGuide(args) {
     tokenSource: publicTokenSource,
     commandPrefix: guideCommandPrefix,
   });
-  return createGuideSuccess(quota?.envelope.actor ?? null, {
-    schema: "image-skill.create-guide.v1",
+  const guideRecovery = createGuideRecovery(stage, {
+    blocker,
+    nextCommand,
+    noSpendNextCommand,
+    afterNext,
+    escapeHatches,
+    selfFundNextCommand,
+  });
+  return createGuideSuccess(command, quota?.envelope.actor ?? null, {
+    schema:
+      guideOperation === "edit"
+        ? "image-skill.edit-guide.v1"
+        : "image-skill.create-guide.v1",
     ready: stage === "ready_to_create",
     stage,
     checks: {
@@ -1884,6 +1958,7 @@ async function createGuide(args) {
                     selected,
                     trimmedPrompt,
                     requestedIntent,
+                    guideOperation,
                   )
                 : createGuideSelectedModelRequiresInputImage(selected)
                   ? selected.modality === "3d"
@@ -1898,6 +1973,9 @@ async function createGuide(args) {
       estimated_provider_usd_per_image: estimatedProviderUsdPerImage,
       credit_unit_usd: pricing?.credit_unit_usd ?? CREDIT_UNIT_USD,
       pricing_confidence: pricing?.pricing_confidence ?? null,
+      pricing_source: pricing?.pricing_source ?? null,
+      model_parameter_defaults_applied:
+        defaultedModelParameters.defaultsApplied,
     },
     blocker,
     guide_warning: guideWarning,
@@ -1910,6 +1988,7 @@ async function createGuide(args) {
     no_spend_next_command_label: noSpendNextCommandLabel,
     no_spend_next_command_effect: noSpendNextCommandEffect,
     no_spend_evaluation: noSpendEvaluation,
+    guide_recovery: guideRecovery,
     recommended_no_spend_command: noSpendNextCommand,
     recommended_no_spend_command_label: noSpendNextCommandLabel,
     recommended_no_spend_command_effect: noSpendNextCommandEffect,
@@ -1930,8 +2009,8 @@ async function createGuide(args) {
   });
 }
 
-function createGuideSuccess(actor, data) {
-  const result = success("image-skill create --guide", data);
+function createGuideSuccess(command, actor, data) {
+  const result = success(command, data);
   result.envelope.actor = actor;
   return result;
 }
@@ -1939,7 +2018,12 @@ function createGuideSuccess(actor, data) {
 function selectCreateGuideModel(
   models,
   requestedModelId,
-  { prompt = "", intent = undefined, maxEstimatedUsdPerImage = null } = {},
+  {
+    operation = "create",
+    prompt = "",
+    intent = undefined,
+    maxEstimatedUsdPerImage = null,
+  } = {},
 ) {
   const isExecutableCreate = (model) =>
     model?.status === "available" &&
@@ -1953,14 +2037,19 @@ function selectCreateGuideModel(
     (model.supports.includes("edit") || model.supports.includes("variation")) &&
     createGuideSelectedModelRequiresInputImage(model);
   const isExecutableGuideModel = (model) =>
-    isExecutableCreate(model) || isExecutableInputImageEdit(model);
+    operation === "edit"
+      ? isExecutableInputImageEdit(model)
+      : isExecutableCreate(model) || isExecutableInputImageEdit(model);
   if (requestedModelId !== null) {
     const requested = models.find((model) => model.id === requestedModelId);
     return requested !== undefined && isExecutableGuideModel(requested)
       ? requested
       : null;
   }
-  const candidates = models.filter(isExecutableCreate);
+  const candidates =
+    operation === "edit"
+      ? models.filter(isExecutableInputImageEdit)
+      : models.filter(isExecutableCreate);
   if (createGuideImplies3d({ prompt, intent })) {
     const eligible3d = guideCandidatesWithinBudget({
       candidates: models.filter(
@@ -2068,6 +2157,221 @@ function guideBudgetUsdForModel(model) {
   );
 }
 
+function createGuideDefaultModelParameters(input) {
+  const modelParameters = { ...(input.modelParameters ?? {}) };
+  const defaultsApplied = [];
+
+  if (
+    input.model?.id === "xai.grok-imagine-image-quality" &&
+    modelParameters.resolution === undefined
+  ) {
+    const twoKEstimate = createGuideProviderCostEstimateForModel(
+      input.model,
+      { resolution: "2k" },
+      { aspectRatio: input.aspectRatio },
+    ).estimated_provider_cost_usd;
+    const twoKAllowedByBudget =
+      input.maxEstimatedUsdPerImage === null ||
+      twoKEstimate === null ||
+      twoKEstimate <= input.maxEstimatedUsdPerImage;
+    const intentClass = createGuideIntentClass(input.intent);
+    const resolution =
+      intentClass !== "budget_draft" && twoKAllowedByBudget ? "2k" : "1k";
+    modelParameters.resolution = resolution;
+    defaultsApplied.push(`resolution=${resolution}`);
+  }
+
+  if (
+    input.model?.id === "fal.flux-dev" &&
+    modelParameters.image_size === undefined
+  ) {
+    const imageSize = falDefaultImageSize(input.aspectRatio);
+    if (imageSize !== null) {
+      modelParameters.image_size = imageSize;
+      defaultsApplied.push(`image_size=${imageSize}`);
+    }
+  }
+
+  if (
+    input.model?.id === "openai.gpt-image-2" &&
+    modelParameters.quality === undefined
+  ) {
+    const mediumEstimate = createGuideProviderCostEstimateForModel(
+      input.model,
+      { ...modelParameters, quality: "medium" },
+      { aspectRatio: input.aspectRatio },
+    ).estimated_provider_cost_usd;
+    const mediumAllowedByBudget =
+      input.maxEstimatedUsdPerImage === null ||
+      mediumEstimate === null ||
+      mediumEstimate <= input.maxEstimatedUsdPerImage;
+    if (mediumAllowedByBudget) {
+      modelParameters.quality = "medium";
+      defaultsApplied.push("quality=medium");
+    }
+  }
+
+  return { modelParameters, defaultsApplied };
+}
+
+function createGuidePricingForModel(model, modelParameters, context = {}) {
+  const estimate = createGuideProviderCostEstimateForModel(
+    model,
+    modelParameters,
+    context,
+  );
+  if (estimate.estimated_provider_cost_usd === null) {
+    return createGuideModelCreditPricing(model);
+  }
+  return createGuideCreditPricingForProviderCost({
+    providerCostUsd: estimate.estimated_provider_cost_usd,
+    pricingConfidence: estimate.pricing_confidence,
+    pricingSource: estimate.pricing_source,
+  });
+}
+
+function createGuideCanPriceModelParameters(model) {
+  return String(model?.id ?? "").startsWith("xai.grok-imagine-image");
+}
+
+function createGuideProviderCostEstimateForModel(
+  model,
+  modelParameters = {},
+  context = {},
+) {
+  if (String(model?.id ?? "").startsWith("xai.grok-imagine-image")) {
+    return createGuideXaiImageCostEstimate(model, modelParameters, context);
+  }
+  return {
+    estimated_provider_cost_usd:
+      typeof model?.economics?.estimated_usd_per_image === "number"
+        ? model.economics.estimated_usd_per_image
+        : (createGuideModelCreditPricing(model)?.estimated_provider_cost_usd ??
+          null),
+    pricing_source: "model_registry",
+    pricing_confidence: "known",
+  };
+}
+
+function createGuideXaiImageCostEstimate(model, modelParameters, context) {
+  const modelId = String(model?.id ?? "");
+  const quality = modelId.includes("-quality");
+  const edit = modelId.endsWith("-edit");
+  const resolution = modelParameters?.resolution === "2k" ? "2k" : "1k";
+  const outputImageCount =
+    Number.isInteger(context?.outputCount) && context.outputCount > 0
+      ? context.outputCount
+      : 1;
+  const referenceAssetCount =
+    Number.isInteger(context?.referenceAssetCount) &&
+    context.referenceAssetCount > 0
+      ? context.referenceAssetCount
+      : 0;
+  const sourceImageCount = edit ? 1 + referenceAssetCount : 0;
+  const inputUsdPerImage = quality ? 0.01 : 0.002;
+  const outputUsdPerImage =
+    quality && resolution === "2k" ? 0.07 : quality ? 0.05 : 0.02;
+  const defaultResolution =
+    modelParameters?.resolution === undefined ||
+    modelParameters?.resolution === null ||
+    modelParameters?.resolution === "1k";
+  const defaultShape =
+    defaultResolution &&
+    outputImageCount === 1 &&
+    sourceImageCount === (edit ? 1 : 0);
+  return {
+    estimated_provider_cost_usd: roundUsdMicro(
+      inputUsdPerImage * sourceImageCount +
+        outputUsdPerImage * outputImageCount,
+    ),
+    pricing_source: defaultShape ? "model_registry" : "model_parameters",
+    pricing_confidence: "known",
+  };
+}
+
+function createGuideCreditPricingForProviderCost(input) {
+  const providerCostUsd = roundUsdMicro(input.providerCostUsd);
+  const creditsRequired = Math.max(
+    1,
+    Math.ceil(
+      roundUsdMicro(
+        providerCostUsd / (1 - TARGET_GROSS_MARGIN) / CREDIT_UNIT_USD,
+      ),
+    ),
+  );
+  const estimatedRevenueUsd = roundUsd(creditsRequired * CREDIT_UNIT_USD);
+  const estimatedPaymentFeeUsd = roundUsdMicro(
+    estimatedRevenueUsd * PAYMENT_BACKED_CREDIT_PAYMENT_FEE_RATE,
+  );
+  const estimatedNetRevenueUsd = roundUsdMicro(
+    estimatedRevenueUsd - estimatedPaymentFeeUsd,
+  );
+  const estimatedGrossMargin =
+    estimatedRevenueUsd > 0
+      ? roundRatio(
+          (estimatedRevenueUsd - providerCostUsd) / estimatedRevenueUsd,
+        )
+      : null;
+  const estimatedFeeAdjustedMargin =
+    estimatedRevenueUsd > 0
+      ? roundRatio(
+          (estimatedNetRevenueUsd - providerCostUsd) / estimatedRevenueUsd,
+        )
+      : null;
+  const selfFundBlockReason =
+    estimatedNetRevenueUsd + 1e-9 < providerCostUsd
+      ? "payment_fee_margin_negative"
+      : null;
+  return {
+    credits_required: creditsRequired,
+    credit_unit_usd: CREDIT_UNIT_USD,
+    estimated_provider_cost_usd: providerCostUsd,
+    fallback_provider_cost_usd: null,
+    estimated_revenue_usd: estimatedRevenueUsd,
+    estimated_gross_margin: estimatedGrossMargin,
+    payment_fee_rate: PAYMENT_BACKED_CREDIT_PAYMENT_FEE_RATE,
+    payment_fee_model: PAYMENT_BACKED_CREDIT_PAYMENT_FEE_MODEL,
+    estimated_payment_fee_usd: estimatedPaymentFeeUsd,
+    estimated_net_revenue_usd: estimatedNetRevenueUsd,
+    estimated_fee_adjusted_margin: estimatedFeeAdjustedMargin,
+    self_fundable: selfFundBlockReason === null,
+    self_fund_block_reason: selfFundBlockReason,
+    target_gross_margin: TARGET_GROSS_MARGIN,
+    pricing_confidence: input.pricingConfidence,
+    pricing_source: input.pricingSource,
+    margin_model: "provider_cost_plus_margin",
+  };
+}
+
+function falDefaultImageSize(aspectRatio) {
+  switch (aspectRatio) {
+    case "1:1":
+      return "square_hd";
+    case "4:3":
+      return "landscape_4_3";
+    case "3:4":
+      return "portrait_4_3";
+    case "16:9":
+      return "landscape_16_9";
+    case "9:16":
+      return "portrait_16_9";
+    default:
+      return null;
+  }
+}
+
+function roundUsd(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function roundRatio(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function roundUsdMicro(value) {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
 function guideModelExecutionStatus(model) {
   if (
     isRecord(model?.execution) &&
@@ -2155,7 +2459,12 @@ function createGuideSelectedModelRequiresInputImage(model) {
   );
 }
 
-function createGuideSelectionReason(model, prompt, intent) {
+function createGuideSelectionReason(
+  model,
+  prompt,
+  intent,
+  operation = "create",
+) {
   if (
     createGuideSelectedModelRequiresInputImage(model) &&
     createGuideImplies3d({ prompt, intent })
@@ -2183,7 +2492,9 @@ function createGuideSelectionReason(model, prompt, intent) {
       ? "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";
+  return operation === "edit"
+    ? "guide selected the first available executable input-image edit model"
+    : "guide selected the first available executable create model";
 }
 
 function createGuidePaymentSummary(data, commandPrefix) {
@@ -2398,7 +2709,7 @@ function renderCopyRunnablePaymentCommand(commandPrefix, command) {
 }
 
 function createGuideStage(input) {
-  if (input.prompt.length === 0) {
+  if (input.promptRequired) {
     return "prompt_required";
   }
   if (!input.health.envelope.ok || !input.models.envelope.ok) {
@@ -2805,6 +3116,64 @@ function createGuideNoSpendEvaluation(stage, input) {
   };
 }
 
+function createGuideRecovery(stage, input) {
+  let noSpendCommand = null;
+  let noSpendCommandField = null;
+  if (stage === "ready_to_create" && input.noSpendNextCommand !== null) {
+    noSpendCommand = input.noSpendNextCommand;
+    noSpendCommandField = "recommended_no_spend_command";
+  } else if (stage === "quota_required") {
+    noSpendCommand = input.escapeHatches.quota;
+    noSpendCommandField = "escape_hatches.quota";
+  } else if (
+    stage === "no_executable_model" ||
+    stage === "service_unreachable"
+  ) {
+    noSpendCommand = input.nextCommand;
+    noSpendCommandField = "next_command";
+  } else if (stage === "auth_required" || stage === "prompt_required") {
+    noSpendCommand = input.nextCommand;
+    noSpendCommandField = "next_command";
+  }
+  const noSpendMissingInputs =
+    noSpendCommand === null
+      ? []
+      : createGuideNextCommandMissingInputs(noSpendCommand);
+  const liveCreateCommandField =
+    stage === "ready_to_create" ? "next_command" : null;
+  const livePaymentCommandField =
+    stage === "quota_required" && input.selfFundNextCommand !== null
+      ? "self_fund_next_command"
+      : null;
+  const doubleSpendGuardRequired =
+    liveCreateCommandField !== null || livePaymentCommandField !== null;
+  return {
+    schema: "image-skill.guide-recovery.v1",
+    stage,
+    precondition_code: input.blocker?.code ?? null,
+    precondition_message: input.blocker?.message ?? null,
+    no_spend_command: noSpendCommand,
+    no_spend_command_field: noSpendCommandField,
+    no_spend_command_copy_runnable:
+      noSpendCommand === null ? null : noSpendMissingInputs.length === 0,
+    no_spend_command_missing_inputs: noSpendMissingInputs,
+    after_success_command: input.afterNext,
+    after_success_command_field: input.afterNext === null ? null : "after_next",
+    live_create_command_field: liveCreateCommandField,
+    live_payment_command_field: livePaymentCommandField,
+    double_spend_guard: {
+      required: doubleSpendGuardRequired,
+      safe_rerun_command_field: noSpendCommandField,
+      warning:
+        liveCreateCommandField !== null
+          ? "Do not blindly rerun data.next_command after a partial or unknown create/edit failure; use data.guide_recovery.no_spend_command, jobs/activity, or error.recovery before any live retry."
+          : livePaymentCommandField !== null
+            ? "Do not blindly rerun live payment commands with fresh identifiers after a partial or unknown payment failure; use data.guide_recovery.no_spend_command and payment status recovery before any new buy."
+            : "No live payment or live media command is exposed for this stage; follow the no-spend command and rerun the guide after the precondition is satisfied.",
+    },
+  };
+}
+
 function createGuideWarning(stage, input) {
   const effect = input.nextCommandEffect;
   const base = {
@@ -2925,10 +3294,13 @@ function escapeRegExp(value) {
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix, {
+      operation: input.guideOperation,
+      inputReference: input.inputReference,
       modelId: input.requestedModelId,
       providerId: input.requestedProviderId,
       intent: input.requestedIntentFlag,
       maxEstimatedUsdPerImage: input.maxEstimatedUsdPerImage,
+      modelParametersJson: input.modelParametersJson,
     });
   }
   if (stage === "no_executable_model" || stage === "service_unreachable") {
@@ -2950,7 +3322,9 @@ function createGuideNextCommand(stage, input) {
     return renderInputImageGuideCommand({
       modelId: input.selected.id,
       prompt: input.prompt,
+      inputReference: input.inputReference,
       budgetGuard: input.budgetGuard,
+      modelParametersJson: input.modelParametersJson,
       dryRun: false,
       idempotencyKey: `edit-guide-${Date.now()}-${randomBytes(4).toString("hex")}`,
       apiBaseUrl: input.apiBaseUrl,
@@ -2964,6 +3338,7 @@ function createGuideNextCommand(stage, input) {
     intent: input.requestedIntent,
     budgetGuard: input.budgetGuard,
     aspectRatio: input.aspectRatio,
+    modelParametersJson: input.modelParametersJson,
     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
@@ -2993,16 +3368,22 @@ function createGuideEscapeHatches(input) {
       "usage quota --json",
     ),
     dry_run:
-      input.selected === null || input.prompt.length === 0
+      input.selected === null ||
+      (input.prompt.length === 0 &&
+        !PROMPTLESS_EDIT_MODEL_IDS.has(input.selected.id))
         ? renderGuidePrefixedCommand(
             input.commandPrefix,
-            "create --dry-run --prompt PROMPT --json",
+            input.guideOperation === "edit"
+              ? "edit --dry-run --input image_... --prompt PROMPT --json"
+              : "create --dry-run --prompt PROMPT --json",
           )
         : createGuideSelectedModelRequiresInputImage(input.selected)
           ? renderInputImageGuideCommand({
               modelId: input.selected.id,
               prompt: input.prompt,
+              inputReference: input.inputReference,
               budgetGuard: input.budgetGuard,
+              modelParametersJson: input.modelParametersJson,
               dryRun: true,
               apiBaseUrl: input.apiBaseUrl,
               commandPrefix: input.commandPrefix,
@@ -3014,6 +3395,7 @@ function createGuideEscapeHatches(input) {
               intent: input.requestedIntent,
               budgetGuard: input.budgetGuard,
               aspectRatio: input.aspectRatio,
+              modelParametersJson: input.modelParametersJson,
               dryRun: true,
               apiBaseUrl: input.apiBaseUrl,
               commandPrefix: input.commandPrefix,
@@ -3027,10 +3409,16 @@ function renderGuideCommand(
   commandPrefix = "image-skill",
   options = {},
 ) {
+  const operation = options.operation ?? "create";
   return [
     commandPrefix,
-    "create --guide --prompt",
+    `${operation} --guide --prompt`,
     shellQuote(prompt),
+    ...(operation === "edit" &&
+    typeof options.inputReference === "string" &&
+    options.inputReference.trim().length > 0
+      ? ["--input", shellQuote(options.inputReference.trim())]
+      : []),
     ...(options.modelId === null ||
     options.modelId === undefined ||
     options.modelId === ""
@@ -3053,6 +3441,10 @@ function renderGuideCommand(
           "--max-estimated-usd-per-image",
           shellQuote(formatUsd(options.maxEstimatedUsdPerImage)),
         ]),
+    ...(options.modelParametersJson === null ||
+    options.modelParametersJson === undefined
+      ? []
+      : ["--model-parameters-json", shellQuote(options.modelParametersJson)]),
     ...(apiBaseUrl === null ? [] : ["--api-base-url", shellQuote(apiBaseUrl)]),
     "--json",
   ].join(" ");
@@ -3107,12 +3499,18 @@ function renderInputImageGuideCommand(input) {
     "edit",
     ...(input.dryRun ? ["--dry-run"] : []),
     "--input",
-    "image_...",
+    input.inputReference?.trim()
+      ? shellQuote(input.inputReference.trim())
+      : "image_...",
     "--model",
     shellQuote(input.modelId),
     ...(promptless ? [] : ["--prompt", shellQuote(input.prompt)]),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.modelParametersJson === null ||
+    input.modelParametersJson === undefined
+      ? []
+      : ["--model-parameters-json", shellQuote(input.modelParametersJson)]),
     ...(input.idempotencyKey === undefined || input.idempotencyKey === null
       ? []
       : ["--idempotency-key", shellQuote(input.idempotencyKey)]),
@@ -3142,6 +3540,10 @@ function renderCreateCommand(input) {
       : ["--aspect-ratio", shellQuote(input.aspectRatio)]),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.modelParametersJson === null ||
+    input.modelParametersJson === undefined
+      ? []
+      : ["--model-parameters-json", shellQuote(input.modelParametersJson)]),
     ...(input.idempotencyKey === undefined || input.idempotencyKey === null
       ? []
       : ["--idempotency-key", shellQuote(input.idempotencyKey)]),
@@ -3377,6 +3779,12 @@ async function edit(argv) {
   const args = parseArgs(argv);
   const input = flagString(args, "input") ?? args.positionals[0];
   const modelId = flagString(args, "model");
+  if (flagBool(args, "guide")) {
+    return createGuide(args, {
+      guideOperation: "edit",
+      inputReference: input,
+    });
+  }
   if (input === undefined) {
     return invalid(
       "image-skill edit",