luxin-cli 0.2.2 → 0.2.4

package/bin/luxin.mjs

@@ -15,7 +15,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.2.2";
+const VERSION = "0.2.4";
 const PACKAGE_NAME = "luxin";
 const DEFAULT_API_BASE_URL = "https://api.luxin.sh";
 const DEFAULT_DOCS_BASE_URL = "https://luxin.sh";
@@ -32,6 +32,39 @@ const PROMPTLESS_EDIT_MODEL_IDS = new Set([
   // provider rejects any prompt, so the public CLI must not require/send one.
   "fal.trellis-image-to-3d",
 ]);
+// #2204-#2216: the guide fields the `ready_compact` output mode drops. Kept as
+// one list so the delete and `data.output_mode.omitted_fields` cannot drift.
+const COMPACT_OMITTABLE_GUIDE_FIELDS = [
+  "auth_handoff",
+  "auth_ready",
+  "escape_hatches",
+  "guide_recovery",
+  "no_spend_evaluation",
+  "recommended_no_spend_command",
+  "recommended_no_spend_command_effect",
+  "recommended_no_spend_command_label",
+  "self_fund_handoff",
+  "self_fund_next_command",
+  "self_fund_next_command_label",
+  "self_fund_preparation",
+];
+// Kept whenever the pre-wall top-up is recommended: dropping the funding nudge
+// at ready_to_create would regress the self-fund wall work.
+const COMPACT_SELF_FUND_GUIDE_FIELDS = new Set([
+  "self_fund_handoff",
+  "self_fund_next_command",
+  "self_fund_next_command_label",
+  "self_fund_preparation",
+]);
+
+// #2194 + #2204-#2216: in `ready_compact` mode `escape_hatches` is omitted, so
+// the no-spend discovery note points at the literal command instead of a field
+// that is not in the response.
+function noSpendDiscoveryNote(readyCompact) {
+  return readyCompact
+    ? "No-spend output mode omits live self-fund and payment command templates. Re-run this guide without --no-spend to surface them; self_fund_discovery.inspect_methods_command stays available for read-only, no-spend payment-method inspection. provider_call, credit_debit, and media_write remain false (see data.mutation). data.output_mode lists the fields this ready_to_create response also omits."
+    : "No-spend output mode omits live self-fund and payment command templates. Re-run this guide without --no-spend to surface them; data.escape_hatches.payment_methods stays available for read-only, no-spend payment-method inspection. provider_call, credit_debit, and media_write remain false (see data.mutation).";
+}
 const DEFAULT_CONFIG_PATH = join(
   process.env.XDG_CONFIG_HOME ?? join(os.homedir(), ".config"),
   "luxin",
@@ -52,9 +85,28 @@ const AGENT_SKILL_URL = "https://luxin.sh/skill.md";
 const AGENT_LLMS_URL = "https://luxin.sh/llms.txt";
 const AGENT_CLI_DOCS_URL = "https://luxin.sh/cli.md";
 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 CANONICAL_PUBLIC_MEDIA_HOST = "media.luxin.sh";
+const LEGACY_PUBLIC_MEDIA_HOST = "media.image-skill.com";
+// media.luxin.sh is the canonical media host. media.image-skill.com is the
+// pre-rename host; it still serves the identical objects, so asset URLs handed
+// out under it stay valid inputs forever.
+const ACCEPTED_PUBLIC_MEDIA_HOSTS = [
+  CANONICAL_PUBLIC_MEDIA_HOST,
+  LEGACY_PUBLIC_MEDIA_HOST,
+];
+// Credit prices for the xAI Grok Imagine image variants, in credits
+// (1 credit = CREDIT_UNIT_USD). The guide prices model parameters locally so it
+// can pick a resolution without a second round trip; the hosted API remains the
+// authority. Exact fractions keep the local estimate identical to the hosted
+// price. These are prices, not costs: the CLI never computes or publishes
+// provider cost or margin.
+const XAI_IMAGE_CREDIT_PRICES = {
+  source_image: { standard: 1 / 3, quality: 5 / 3 },
+  output_image: {
+    standard: 10 / 3,
+    quality: { "1k": 25 / 3, "2k": 35 / 3 },
+  },
+};
 const MODALITY_COMMAND_ALIASES = new Map([
   ["image", { command: "create", intent: null }],
   ["video", { command: "create", intent: "video" }],
@@ -156,6 +208,111 @@ const GUIDE_NEXT_COMMAND_PLACEHOLDERS = [
   },
 ];
 
+// ---------------------------------------------------------------------------
+// Explicit aspect-ratio intent (#2213/#2203/#2209, hardened by #2243/#2252).
+//
+// An agent that briefs "a 16:9 cinematic widescreen poster" is stating a
+// REQUIRED output shape, not decorating the prompt. This CLI used to ignore it
+// entirely: `createGuideSuggestedAspectRatio` only ever suggested a ratio for
+// video models, so `selection.suggested_aspect_ratio` was null for every image
+// create and the emitted `next_command` carried no `--aspect-ratio`. The agent
+// then got the model default with no signal that the ratio it asked for had
+// been dropped.
+//
+// Aspect ratio is a TOP-LEVEL NORMALIZED control (`--aspect-ratio`, validated
+// against `media.input.aspect_ratios.values`), NOT a `model_parameters` field.
+//
+// Conservative on purpose: a false negative degrades to the old behavior (no
+// suggested ratio), while a false positive silently overrides the shape an
+// agent actually wanted. So this fires ONLY on an explicit ratio token from a
+// known allowlist, or on an orientation word BOUND to an orientation noun.
+// Bare "portrait" and bare "landscape" are deliberately excluded -- "a portrait
+// of a woman" and "a landscape at dusk" are subject/genre words.
+// ---------------------------------------------------------------------------
+
+// Ratio tokens accepted verbatim from a brief. Deliberately limited to the
+// unambiguous photographic/display ratios. `2:1` and `1:2` are NOT here: they
+// collide with odds and mixing ratios far more often than they express a shape.
+const EXPLICIT_ASPECT_RATIOS = [
+  "1:1",
+  "4:3",
+  "3:4",
+  "3:2",
+  "2:3",
+  "16:9",
+  "9:16",
+  "21:9",
+  "9:21",
+];
+
+// A `W:H` token that is not part of a longer numeric run (so "16:9:30" and
+// "1920:1080:2" do not match) and is not a clock time ("9:16 am").
+const ASPECT_RATIO_TOKEN_RE =
+  /(?<![\d.:])(\d{1,2}):(\d{1,2})(?![\d.:])(?!\s*[ap]\.?m\.?\b)/gi;
+
+// A `W:H` token can appear in a brief without being a shape request:
+//
+//   "the ratio of sugar to flour is 3:2 in this recipe"   -> must not fire
+//   "a train departing at 16:9"                           -> must not fire
+//
+// Deliberately narrow. These match the immediate context of the token only;
+// they are not an attempt at natural-language understanding, and #2252 had to
+// walk back a first cut that over-matched.
+const RATIO_SUPPRESSING_CONTEXT = [
+  // Quantity ratios and mixes: "ratio of sugar to flour is 3:2", "a 2:3 mix",
+  // "dilute 1:1", "3:2 by weight/volume".
+  //
+  // Requires the "ratio of X TO Y" quantities construction, and exempts the
+  // shape vocabulary. A first cut matched any "ratio of ... N:M" and silently
+  // killed "an image with an aspect ratio of 16:9" -- the single most standard
+  // way to state a ratio in English, and a far worse failure than the recipe
+  // case it was written for (#2252).
+  /\bratios?\s+of\b(?![^.!?]*?\b(?:width|height|aspect)\b)[^.!?]*?\bto\b[^.!?]*?\d{1,2}:\d{1,2}/i,
+  /\d{1,2}:\d{1,2}\s*(?:dilution|mix(?:ture)?|blend|ratio\s+by|by\s+(?:weight|volume)|odds)\b/i,
+  /\b(?:dilut\w*|mix(?:ed|ing)?|blend\w*|steep\w*)\s+(?:it\s+|them\s+)?(?:at\s+|to\s+)?\d{1,2}:\d{1,2}/i,
+  // Clock times written without a leading zero: "a train departing at 16:9".
+  // `ASPECT_RATIO_TOKEN_RE` already rejects the "9:16 am" form; this covers the
+  // bare 24-hour reading.
+  //
+  // Keyed on a SCHEDULE VERB, not on a bare preposition. "at" alone is
+  // ambiguous and suppressing it broke a real request -- "render at 4:3 for the
+  // retro TV bumper" is a shape request and must keep firing.
+  //
+  // `leav` and `board` are deliberately NOT in this list: they collide with
+  // ordinary image nouns (autumn leaves, boardwalk, surfboard, keyboard,
+  // billboard), so "a photo of autumn leaves at 16:9" would lose its ratio.
+  /\b(?:depart|arriv|due|scheduled|timetabled)\w*\s+(?:at|by|around)?\s*\d{1,2}:\d{1,2}\b/i,
+];
+
+// Orientation nouns that turn an ambiguous orientation adjective into an
+// unambiguous shape request. "portrait orientation" / "vertical video" /
+// "square canvas" are shape requests; "portrait of a woman" is not.
+const ORIENTATION_NOUN =
+  "orientation|format|mode|aspect(?:\\s+ratio)?|ratio|crop|canvas|image|photo|picture|poster|banner|video|frame|composition|layout|thumbnail|cover";
+
+function boundOrientationRe(adjective) {
+  // "<adj> <noun>" (e.g. "vertical video") or "in <adj>" / "<adj> orientation".
+  return new RegExp(
+    `\\b(?:in\\s+${adjective}\\b|${adjective}[\\s-]+(?:${ORIENTATION_NOUN})\\b)`,
+    "i",
+  );
+}
+
+const ORIENTATION_RULES = [
+  // "widescreen" and "ultrawide" are unambiguous on their own -- they have no
+  // competing subject/genre meaning.
+  { re: /\bultra[\s-]?wide(?:screen)?\b/i, ratio: "21:9" },
+  { re: /\bwide[\s-]?screen\b/i, ratio: "16:9" },
+  // These four need an orientation noun to bind to.
+  { re: boundOrientationRe("portrait"), ratio: "9:16" },
+  { re: boundOrientationRe("vertical"), ratio: "9:16" },
+  { re: boundOrientationRe("landscape"), ratio: "16:9" },
+  { re: boundOrientationRe("horizontal"), ratio: "16:9" },
+  { re: boundOrientationRe("square"), ratio: "1:1" },
+];
+
+const GUIDE_ASPECT_RATIO_PROBE_LIMIT = 8;
+
 function agentSkillHint(commandPrefix = "luxin") {
   return {
     url: AGENT_SKILL_URL,
@@ -552,6 +709,8 @@ function commandHelpByKey(key) {
       docs_url: "https://luxin.sh/cli.md#luxin-create",
       optional_flags: [
         "--guide",
+        "--no-spend",
+        "--explain",
         "--dry-run",
         "--model",
         "--aspect-ratio",
@@ -1752,16 +1911,61 @@ async function createGuide(args, options = {}) {
     return token.result;
   }
 
-  const selected =
-    models.envelope.ok && models.envelope.data?.models
-      ? selectCreateGuideModel(models.envelope.data.models, requestedModelId, {
+  // Explicit aspect ratio stated in the brief, treated as a required capability
+  // during model selection and propagated into the emitted commands
+  // (#2213/#2203/#2209, guards corrected by #2252).
+  const briefAspectRatio = requestedAspectRatioFromBrief({
+    prompt: trimmedPrompt,
+    intent: requestedIntentFlag,
+  });
+  const listedModels =
+    models.envelope.ok && Array.isArray(models.envelope.data?.models)
+      ? models.envelope.data.models
+      : null;
+  const selectModel = (candidateModels) =>
+    candidateModels === null
+      ? null
+      : selectCreateGuideModel(candidateModels, requestedModelId, {
           operation: guideOperation,
           prompt: trimmedPrompt,
           intent: requestedIntent,
           maxEstimatedUsdPerImage,
+          requestedAspectRatio: briefAspectRatio,
+        });
+  let selection = selectModel(listedModels);
+  if (briefAspectRatio !== null && listedModels !== null) {
+    // Two-pass: the first pass names the models worth asking about, then one
+    // bounded round of detail lookups makes the second pass actually
+    // capability-aware instead of guessing.
+    const capabilityModels = await guideModelsWithAspectRatioCapabilities({
+      models: listedModels,
+      modelIds: guideAspectRatioProbeModelIds({
+        models: listedModels,
+        selected: selection?.model ?? null,
+        intent: requestedIntent,
+      }),
+      apiBaseUrl,
+    });
+    if (capabilityModels !== listedModels) {
+      selection = selectModel(capabilityModels);
+    }
+  }
+  const selected = selection?.model ?? null;
+  const selectedAspectRatio = createGuideSuggestedAspectRatio({
+    model: selected,
+    requestedAspectRatio: briefAspectRatio,
+  });
+  // The brief asked for a ratio and the selected model cannot express it, so no
+  // model could. Say so instead of dropping it silently.
+  const unsupportedAspectRatioWarning =
+    briefAspectRatio !== null &&
+    selectedAspectRatio === null &&
+    selected !== null
+      ? aspectRatioUnsupportedWarning({
+          aspectRatio: briefAspectRatio,
+          modelId: selected.id,
         })
       : null;
-  const selectedAspectRatio = createGuideSuggestedAspectRatio(selected);
   const pricingContext = {
     aspectRatio: selectedAspectRatio ?? "1:1",
     outputCount: 1,
@@ -1795,25 +1999,16 @@ async function createGuide(args, options = {}) {
             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 ??
+  // The guide publishes what the caller will be charged, never our provider
+  // cost. `economics.estimated_usd_per_image` is the hosted charge per image.
+  const estimatedDebitUsdPerImage =
+    pricing?.estimated_charge_usd ??
     selected?.economics?.estimated_usd_per_image ??
-    pricing?.fallback_provider_cost_usd ??
     (typeof selected?.estimated_usd_per_image === "number"
       ? selected.estimated_usd_per_image
       : null) ??
     null;
-  const estimatedDebitUsdPerImage =
-    pricing?.estimated_revenue_usd ?? estimatedProviderUsdPerImage;
   const budgetGuard =
     maxEstimatedUsdPerImage ??
     estimatedDebitUsdPerImage ??
@@ -1866,6 +2061,14 @@ async function createGuide(args, options = {}) {
     quota,
     estimatedCredits,
   });
+  // #2204-#2216: `--explain` opts back into the complete payload in every
+  // stage; the compact default is for the agent that just wants the decision.
+  // The payment/self-fund/recovery apparatus is correct when the guide is
+  // blocked and noise when it is not, so shape on that state rather than on a
+  // flag the caller has to know about.
+  const explainOutputMode = flagBool(args, "explain");
+  const readyCompact =
+    stage === "ready_to_create" && blocker === null && !explainOutputMode;
   const nextCommand = createGuideNextCommand(stage, {
     prompt: trimmedPrompt,
     selected,
@@ -1924,11 +2127,21 @@ async function createGuide(args, options = {}) {
     noSpendNextCommandLabel,
     noSpendNextCommandEffect,
   });
-  const guideWarning = createGuideWarning(stage, {
+  const baseGuideWarning = createGuideWarning(stage, {
     nextCommandEffect,
     paymentSummary,
     nextCommandCopyRunnable,
+    readyCompact,
   });
+  // Append, never replace: the stage warning carries the spend-safety contract
+  // agents rely on, and the ratio note is additive context.
+  const guideWarning =
+    unsupportedAspectRatioWarning === null
+      ? baseGuideWarning
+      : {
+          ...baseGuideWarning,
+          warning: `${baseGuideWarning.warning} ${unsupportedAspectRatioWarning}`,
+        };
   const quotaTopUp = createGuideQuotaTopUp(
     quota?.envelope.data?.top_up ?? null,
   );
@@ -1984,15 +2197,117 @@ async function createGuide(args, options = {}) {
     paymentSummary,
     selfFundPreparation,
   );
+  // #2194: no-spend output mode. Omit the live self-fund and payment command
+  // templates when the agent opts into a no-spend/dry-run study so the safe
+  // dry-run is not buried under quote/buy/payment workflow commands. Retain the
+  // dry-run command and the mutation proof, and keep the self-fund path
+  // discoverable via self_fund_discovery instead of dominating the response.
+  const noSpendOutputMode = flagBool(args, "no-spend");
+  // Keep the pre-wall self-fund nudge whenever it is actually recommended.
+  const selfFundRecommended = selfFundPreparation?.recommended === true;
+  const paymentSummaryOutput =
+    noSpendOutputMode || readyCompact
+      ? {
+          ...paymentSummary,
+          suggested_commands: [],
+          ...(readyCompact ? { preferred_method_summary: null } : {}),
+        }
+      : paymentSummary;
+  const selfFundHandoffOutput = noSpendOutputMode ? null : selfFundHandoff;
+  const selfFundPreparationOutput = noSpendOutputMode
+    ? null
+    : selfFundPreparation;
+  const selfFundNextCommandOutput = noSpendOutputMode
+    ? null
+    : selfFundNextCommand;
+  const selfFundNextCommandLabelOutput = noSpendOutputMode
+    ? null
+    : selfFundNextCommandLabel;
+  const noSpendOutputModeData = noSpendOutputMode
+    ? {
+        enabled: true,
+        suppressed_fields: [
+          "self_fund_next_command",
+          "self_fund_next_command_label",
+          "self_fund_handoff",
+          "self_fund_preparation",
+          "checks.payments.suggested_commands",
+        ],
+        self_fund_discovery: {
+          rerun_with_funding_command: renderGuideCommand(
+            trimmedPrompt.length > 0 ? trimmedPrompt : "PROMPT",
+            explicitApiBaseUrl(args),
+            guideCommandPrefix,
+            {
+              operation: guideOperation,
+              inputReference: options.inputReference,
+              modelId: requestedModelId,
+              providerId: requestedProviderId,
+              intent: requestedIntentFlag,
+              maxEstimatedUsdPerImage,
+              modelParametersJson: requestedModelParametersJson,
+            },
+          ),
+          inspect_methods_command: escapeHatches.payment_methods,
+          note: noSpendDiscoveryNote(readyCompact),
+        },
+      }
+    : {
+        enabled: false,
+        suppressed_fields: [],
+        self_fund_discovery: null,
+      };
   const guideRecovery = createGuideRecovery(stage, {
     blocker,
     nextCommand,
     noSpendNextCommand,
     afterNext,
     escapeHatches,
-    selfFundNextCommand,
+    selfFundNextCommand: selfFundNextCommandOutput,
   });
-  return createGuideSuccess(command, quota?.envelope.actor ?? null, {
+  // #2204-#2216: fields the compact ready payload drops. `self_fund_*` only
+  // joins the list when the pre-wall top-up is not recommended.
+  const compactOmittedFields = readyCompact
+    ? COMPACT_OMITTABLE_GUIDE_FIELDS.filter(
+        (field) =>
+          selfFundRecommended === false ||
+          !COMPACT_SELF_FUND_GUIDE_FIELDS.has(field),
+      )
+    : [];
+  const compactCompactedFields = readyCompact
+    ? [
+        "checks.payments.preferred_method_summary",
+        "checks.payments.suggested_commands",
+        "checks.quota.top_up",
+      ]
+    : [];
+  const outputModeData = {
+    schema: "image-skill.guide-output-mode.v1",
+    mode: readyCompact ? "ready_compact" : "full",
+    reason: readyCompact
+      ? "stage is ready_to_create with no blocker, so the guide returns the decision, the cost, and the no-spend proof. Payment, self-fund, auth-handoff, and recovery detail belong to blocked stages and are omitted here."
+      : explainOutputMode
+        ? "--explain returns every guide field in every stage."
+        : "the guide is not at an unblocked ready_to_create stage, so every field is returned.",
+    omitted_fields: compactOmittedFields,
+    compacted_fields: compactCompactedFields,
+    full_output_command: renderGuideCommand(
+      trimmedPrompt.length > 0 ? trimmedPrompt : "PROMPT",
+      explicitApiBaseUrl(args),
+      guideCommandPrefix,
+      {
+        operation: guideOperation,
+        inputReference: options.inputReference,
+        modelId: requestedModelId,
+        providerId: requestedProviderId,
+        intent: requestedIntentFlag,
+        maxEstimatedUsdPerImage,
+        modelParametersJson: requestedModelParametersJson,
+        explain: true,
+      },
+    ),
+  };
+  const guideData = {
     schema:
       guideOperation === "edit"
         ? "image-skill.edit-guide.v1"
@@ -2032,7 +2347,7 @@ async function createGuide(args, options = {}) {
         required_credits: estimatedCredits,
         daily_jobs_remaining:
           quota?.envelope.data?.daily_jobs?.remaining ?? null,
-        top_up: quotaTopUp,
+        top_up: readyCompact ? null : quotaTopUp,
         reason:
           quota === null
             ? "auth_required"
@@ -2040,7 +2355,7 @@ async function createGuide(args, options = {}) {
               ? null
               : (quota.envelope.error?.code ?? "quota_unavailable"),
       },
-      payments: paymentSummary,
+      payments: paymentSummaryOutput,
     },
     selection:
       selected === null
@@ -2055,20 +2370,28 @@ async function createGuide(args, options = {}) {
             modality: selected.modality ?? null,
             suggested_aspect_ratio: selectedAspectRatio,
             reason:
-              requestedModelId === null
-                ? createGuideSelectionReason(
-                    selected,
-                    trimmedPrompt,
-                    requestedIntent,
-                    guideOperation,
-                  )
-                : createGuideRequestedSelectionReason(selected),
+              requestedModelId !== null
+                ? createGuideRequestedSelectionReason(selected)
+                : selection?.aspectRatioRoutedFrom != null &&
+                    briefAspectRatio !== null
+                  ? aspectRatioRoutedCreateSelectionReason({
+                      aspectRatio: briefAspectRatio,
+                      skippedModelId: selection.aspectRatioRoutedFrom,
+                    })
+                  : selection?.aspectRatioCapableFallback === true &&
+                      briefAspectRatio !== null
+                    ? `guide selected an available model that supports the requested ${briefAspectRatio} aspect ratio`
+                    : createGuideSelectionReason(
+                        selected,
+                        trimmedPrompt,
+                        requestedIntent,
+                        guideOperation,
+                      ),
           },
     cost: {
       estimated_credits: estimatedCredits,
       estimated_usd_per_image: estimatedDebitUsdPerImage,
       estimated_debit_usd_per_image: estimatedDebitUsdPerImage,
-      estimated_provider_usd_per_image: estimatedProviderUsdPerImage,
       credit_unit_usd: pricing?.credit_unit_usd ?? CREDIT_UNIT_USD,
       pricing_confidence: pricing?.pricing_confidence ?? null,
       pricing_source: pricing?.pricing_source ?? null,
@@ -2090,13 +2413,15 @@ async function createGuide(args, options = {}) {
     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,
-    self_fund_preparation: selfFundPreparation,
+    self_fund_next_command: selfFundNextCommandOutput,
+    self_fund_next_command_label: selfFundNextCommandLabelOutput,
+    self_fund_handoff: selfFundHandoffOutput,
+    self_fund_preparation: selfFundPreparationOutput,
     after_next: afterNext,
     auth_handoff: authHandoff,
     escape_hatches: escapeHatches,
+    no_spend_output_mode: noSpendOutputModeData,
+    output_mode: outputModeData,
     mutation: {
       provider_call: false,
       hosted_create: false,
@@ -2105,7 +2430,11 @@ async function createGuide(args, options = {}) {
       credit_debit: false,
       media_write: false,
     },
-  });
+  };
+  for (const field of compactOmittedFields) {
+    delete guideData[field];
+  }
+  return createGuideSuccess(command, quota?.envelope.actor ?? null, guideData);
 }
 
 function createGuideSuccess(command, actor, data) {
@@ -2122,6 +2451,12 @@ function selectCreateGuideModel(
     prompt = "",
     intent = undefined,
     maxEstimatedUsdPerImage = null,
+    /**
+     * Aspect ratio explicitly requested by the brief, treated as a REQUIRED
+     * capability during selection (#2213/#2203/#2209) the same way a
+     * reproducibility need is. Null when the brief states no ratio.
+     */
+    requestedAspectRatio = null,
   } = {},
 ) {
   const isExecutableCreate = (model) =>
@@ -2139,10 +2474,18 @@ function selectCreateGuideModel(
     operation === "edit"
       ? isExecutableInputImageEdit(model)
       : isExecutableCreate(model) || isExecutableInputImageEdit(model);
+  const requestedRatio = requestedAspectRatio ?? null;
+  const chosen = (
+    model,
+    { aspectRatioRoutedFrom = null, aspectRatioCapableFallback = false } = {},
+  ) =>
+    model === undefined || model === null
+      ? null
+      : { model, aspectRatioRoutedFrom, aspectRatioCapableFallback };
   if (requestedModelId !== null) {
     const requested = resolveModelLookup(requestedModelId, models);
     return requested !== undefined && isExecutableGuideModel(requested)
-      ? requested
+      ? chosen(requested)
       : null;
   }
   const candidates =
@@ -2159,7 +2502,7 @@ function selectCreateGuideModel(
     });
     const threeDimensional = eligible3d[0];
     if (threeDimensional !== undefined) {
-      return threeDimensional;
+      return chosen(threeDimensional);
     }
   }
   const eligible = guideCandidatesWithinBudget({
@@ -2169,23 +2512,151 @@ function selectCreateGuideModel(
   if (createGuideImpliesAudio({ prompt, intent })) {
     const audio = eligible.find((model) => model?.modality === "audio");
     if (audio !== undefined) {
-      return audio;
+      return chosen(audio);
     }
   }
   if (createGuideImpliesVideo({ prompt, intent })) {
-    const video = eligible.find((model) => model?.modality === "video");
+    const videoCandidates = eligible.filter(
+      (model) => model?.modality === "video",
+    );
+    const video =
+      videoCandidates.find(
+        (model) => !modelCannotExpressAspectRatio(model, requestedRatio),
+      ) ?? videoCandidates[0];
     if (video !== undefined) {
-      return video;
+      return chosen(video);
     }
   }
   const intentClass = createGuideIntentClass(intent);
-  for (const modelId of preferredCreateGuideModelIds(intentClass)) {
-    const preferred = eligible.find((model) => model?.id === modelId);
-    if (preferred !== undefined) {
-      return preferred;
+  const preferredCandidates = preferredCreateGuideModelIds(intentClass)
+    .map((modelId) => eligible.find((model) => model?.id === modelId))
+    .filter((model) => model !== undefined);
+  const [topPreferred] = preferredCandidates;
+
+  // An explicitly requested aspect ratio is a REQUIRED capability, so walk the
+  // curated preference list in strength order but skip models that are KNOWN
+  // not to express the ratio through the normalized `--aspect-ratio` control
+  // (#2213/#2203/#2209). Unknown capability is not a denial: see
+  // `modelAspectRatioSupport`.
+  const preferredSupportingRatio = preferredCandidates.find(
+    (model) => !modelCannotExpressAspectRatio(model, requestedRatio),
+  );
+  if (preferredSupportingRatio !== undefined) {
+    const routedForAspectRatio =
+      requestedRatio !== null &&
+      topPreferred !== undefined &&
+      topPreferred.id !== preferredSupportingRatio.id;
+    return chosen(preferredSupportingRatio, {
+      aspectRatioRoutedFrom: routedForAspectRatio ? topPreferred.id : null,
+    });
+  }
+
+  // No curated model can express the ratio: fall out to the strongest
+  // remaining executable candidate that provably can, before degrading to the
+  // ratio-blind fallback.
+  if (requestedRatio !== null) {
+    const capable = eligible.find(
+      (model) => modelAspectRatioSupport(model, requestedRatio) === true,
+    );
+    if (capable !== undefined) {
+      return chosen(capable, {
+        aspectRatioRoutedFrom: topPreferred?.id ?? null,
+        aspectRatioCapableFallback: topPreferred === undefined,
+      });
     }
   }
-  return eligible[0] ?? null;
+
+  // Nothing can express the requested ratio (or none was requested): keep the
+  // ordinary selection exactly. The caller emits an honest guide_warning rather
+  // than letting the ratio disappear silently.
+  if (topPreferred !== undefined) {
+    return chosen(topPreferred);
+  }
+  return chosen(eligible[0]);
+}
+
+// The hosted `/v1/models` list is a compact summary and does not publish
+// `media.input.aspect_ratios.values`, so a stated ratio cannot be checked
+// against it. Probe the detail endpoint for the handful of models the guide
+// would actually route between -- never the whole catalog, whose
+// `?details=true` payload is multiple megabytes.
+//
+// Fail-open: an unreachable, errored, or malformed detail response leaves the
+// capability UNKNOWN, which never disqualifies a model and never triggers the
+// unsupported-ratio warning.
+
+function guideAspectRatioProbeModelIds({ models, selected, intent }) {
+  const ids = [];
+  if (typeof selected?.id === "string") {
+    ids.push(selected.id);
+  }
+  for (const modelId of preferredCreateGuideModelIds(
+    createGuideIntentClass(intent),
+  )) {
+    if (models.some((model) => model?.id === modelId)) {
+      ids.push(modelId);
+    }
+  }
+  return [...new Set(ids)].slice(0, GUIDE_ASPECT_RATIO_PROBE_LIMIT);
+}
+
+async function guideModelsWithAspectRatioCapabilities({
+  models,
+  modelIds,
+  apiBaseUrl,
+}) {
+  const missing = modelIds.filter((modelId) => {
+    const model = models.find((candidate) => candidate?.id === modelId);
+    return model !== undefined && guideModelAspectRatioValues(model) === null;
+  });
+  if (missing.length === 0) {
+    return models;
+  }
+  const probes = await Promise.all(
+    missing.map(async (modelId) => {
+      try {
+        const detail = await apiRequest({
+          command: "luxin create --guide",
+          method: "GET",
+          apiBaseUrl,
+          path: `/v1/models/${encodeURIComponent(modelId)}`,
+        });
+        const values = guideModelAspectRatioValues(
+          detail?.envelope?.data?.model ?? null,
+        );
+        return values === null ? null : { modelId, values };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  const resolved = new Map(
+    probes
+      .filter((probe) => probe !== null)
+      .map((probe) => [probe.modelId, probe.values]),
+  );
+  if (resolved.size === 0) {
+    return models;
+  }
+  return models.map((model) => {
+    const values = resolved.get(model?.id);
+    if (values === undefined) {
+      return model;
+    }
+    return {
+      ...model,
+      media: {
+        ...model?.media,
+        input: {
+          ...model?.media?.input,
+          aspect_ratios: {
+            ...model?.media?.input?.aspect_ratios,
+            values,
+          },
+        },
+      },
+    };
+  });
 }
 
 const MODEL_ALIAS_RULES = [
@@ -2357,29 +2828,47 @@ function createGuideIntentClass(intent) {
   return "general";
 }
 
+// Mirrors src/hosted-create-policy.ts (#2231). budget_draft is a superset of
+// general and both are ordered ascending by charged credits, so a
+// cost-minimizing intent can never select a model priced above the general
+// default. final keeps the quality-premium lead.
 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",
-      ];
+  if (intentClass === "budget_draft") {
+    return [
+      "fal.flux-1-schnell",
+      "fal.flux-1-dev",
+      "xai.grok-imagine-image",
+      "fal.bria-text-to-image-fast",
+      "xai.grok-imagine-image-quality",
+      "openai.gpt-image-2",
+    ];
+  }
+  if (intentClass === "final") {
+    return [
+      "xai.grok-imagine-image-quality",
+      "openai.gpt-image-2",
+      "fal.flux-1-dev",
+      "xai.grok-imagine-image",
+      "fal.flux-1-schnell",
+      "fal.bria-text-to-image-fast",
+    ];
+  }
+  return [
+    "fal.flux-1-dev",
+    "xai.grok-imagine-image",
+    "xai.grok-imagine-image-quality",
+    "openai.gpt-image-2",
+    "fal.flux-1-schnell",
+    "fal.bria-text-to-image-fast",
+  ];
 }
 
 function guideBudgetUsdForModel(model) {
+  // Budget caps compare the credit debit -- what the caller pays.
   const pricing = createGuideModelCreditPricing(model);
   return (
-    pricing?.estimated_revenue_usd ??
+    pricing?.estimated_charge_usd ??
     model?.economics?.estimated_usd_per_image ??
-    pricing?.estimated_provider_cost_usd ??
-    pricing?.fallback_provider_cost_usd ??
     (typeof model?.estimated_usd_per_image === "number"
       ? model.estimated_usd_per_image
       : null) ??
@@ -2395,7 +2884,7 @@ function createGuideDefaultModelParameters(input) {
     input.model?.id === "xai.grok-imagine-image-quality" &&
     modelParameters.resolution === undefined
   ) {
-    // Budget defaults must compare the credit debit (estimated_revenue_usd),
+    // Budget defaults must compare the credit debit (estimated_charge_usd),
     // the same basis the hosted budget guard enforces, not the provider cost.
     const twoKPricing = createGuidePricingForModel(
       input.model,
@@ -2404,8 +2893,8 @@ function createGuideDefaultModelParameters(input) {
     );
     const twoKAllowedByBudget =
       input.maxEstimatedUsdPerImage === null ||
-      typeof twoKPricing?.estimated_revenue_usd !== "number" ||
-      twoKPricing.estimated_revenue_usd <= input.maxEstimatedUsdPerImage;
+      typeof twoKPricing?.estimated_charge_usd !== "number" ||
+      twoKPricing.estimated_charge_usd <= input.maxEstimatedUsdPerImage;
     const intentClass = createGuideIntentClass(input.intent);
     const resolution =
       intentClass !== "budget_draft" && twoKAllowedByBudget ? "2k" : "1k";
@@ -2435,8 +2924,8 @@ function createGuideDefaultModelParameters(input) {
     );
     const mediumAllowedByBudget =
       input.maxEstimatedUsdPerImage === null ||
-      typeof mediumPricing?.estimated_revenue_usd !== "number" ||
-      mediumPricing.estimated_revenue_usd <= input.maxEstimatedUsdPerImage;
+      typeof mediumPricing?.estimated_charge_usd !== "number" ||
+      mediumPricing.estimated_charge_usd <= input.maxEstimatedUsdPerImage;
     if (mediumAllowedByBudget) {
       modelParameters.quality = "medium";
       defaultsApplied.push("quality=medium");
@@ -2447,45 +2936,17 @@ function createGuideDefaultModelParameters(input) {
 }
 
 function createGuidePricingForModel(model, modelParameters, context = {}) {
-  const estimate = createGuideProviderCostEstimateForModel(
-    model,
-    modelParameters,
-    context,
-  );
-  if (estimate.estimated_provider_cost_usd === null) {
-    return createGuideModelCreditPricing(model);
+  if (createGuideCanPriceModelParameters(model)) {
+    return createGuideXaiImagePricing(model, modelParameters, context);
   }
-  return createGuideCreditPricingForProviderCost({
-    providerCostUsd: estimate.estimated_provider_cost_usd,
-    pricingConfidence: estimate.pricing_confidence,
-    pricingSource: estimate.pricing_source,
-  });
+  return createGuideModelCreditPricing(model);
 }
 
 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) {
+function createGuideXaiImagePricing(model, modelParameters, context) {
   const modelId = String(model?.id ?? "");
   const quality = modelId.includes("-quality");
   const edit = modelId.endsWith("-edit");
@@ -2500,11 +2961,20 @@ function createGuideXaiImageCostEstimate(model, modelParameters, context) {
       ? context.referenceAssetCount
       : 0;
   const sourceImageCount = edit ? 1 + referenceAssetCount : 0;
-  const inputUsdPerImage = quality ? 0.01 : 0.002;
-  let outputUsdPerImage = 0.02;
-  if (quality) {
-    outputUsdPerImage = resolution === "2k" ? 0.07 : 0.05;
-  }
+  const sourceCredits = quality
+    ? XAI_IMAGE_CREDIT_PRICES.source_image.quality
+    : XAI_IMAGE_CREDIT_PRICES.source_image.standard;
+  const outputCredits = quality
+    ? XAI_IMAGE_CREDIT_PRICES.output_image.quality[resolution]
+    : XAI_IMAGE_CREDIT_PRICES.output_image.standard;
+  const creditsRequired = Math.max(
+    1,
+    Math.ceil(
+      roundUsdMicro(
+        sourceCredits * sourceImageCount + outputCredits * outputImageCount,
+      ),
+    ),
+  );
   const defaultResolution =
     modelParameters?.resolution === undefined ||
     modelParameters?.resolution === null ||
@@ -2513,67 +2983,12 @@ function createGuideXaiImageCostEstimate(model, modelParameters, context) {
     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",
+    estimated_charge_usd: roundUsd(creditsRequired * CREDIT_UNIT_USD),
+    pricing_confidence: "known",
+    pricing_source: defaultShape ? "model_registry" : "model_parameters",
   };
 }
 
@@ -2598,10 +3013,6 @@ 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;
 }
@@ -2627,16 +3038,8 @@ function createGuideModelCreditPricing(model) {
   }
   return {
     credits_required: model.credits_required,
-    estimated_revenue_usd:
-      typeof model.credits_required === "number"
-        ? model.credits_required * CREDIT_UNIT_USD
-        : null,
-    estimated_provider_cost_usd:
-      typeof model?.estimated_usd_per_image === "number"
-        ? model.estimated_usd_per_image
-        : null,
-    fallback_provider_cost_usd: null,
     credit_unit_usd: CREDIT_UNIT_USD,
+    estimated_charge_usd: roundUsd(model.credits_required * CREDIT_UNIT_USD),
     pricing_confidence:
       typeof model?.pricing_confidence === "string"
         ? model.pricing_confidence
@@ -2671,14 +3074,124 @@ function createGuideImpliesVideo(input) {
   );
 }
 
-function createGuideSuggestedAspectRatio(model) {
-  if (model?.modality !== "video") {
-    return null;
+// Extract an explicitly requested aspect ratio from a create/edit brief.
+//
+// Precedence:
+// 1. An explicit `W:H` token from EXPLICIT_ASPECT_RATIOS wins over any
+//    orientation word -- it is the most specific statement of intent.
+// 2. Otherwise a bound orientation phrase is used.
+//
+// Conflicts resolve to null (no request) rather than to a guess: two different
+// explicit ratios, or two orientation phrases implying different shapes, mean
+// the brief is ambiguous and the guide should not pick a side.
+function classifyRequestedAspectRatio(input) {
+  const text = `${input?.intent ?? ""} ${input?.prompt ?? ""}`.trim();
+  if (text.length === 0) {
+    return { aspectRatio: null, signal: null };
   }
+
+  const ratioTokenIsSuppressed = RATIO_SUPPRESSING_CONTEXT.some((re) =>
+    re.test(text),
+  );
+
+  const explicit = new Set();
+  if (!ratioTokenIsSuppressed) {
+    for (const match of text.matchAll(ASPECT_RATIO_TOKEN_RE)) {
+      const token = `${match[1]}:${match[2]}`;
+      if (EXPLICIT_ASPECT_RATIOS.includes(token)) {
+        explicit.add(token);
+      }
+    }
+  }
+  if (explicit.size === 1) {
+    const [only] = [...explicit];
+    return { aspectRatio: only ?? null, signal: "explicit_ratio_token" };
+  }
+  if (explicit.size > 1) {
+    // Contradictory explicit ratios: refuse to guess.
+    return { aspectRatio: null, signal: null };
+  }
+
+  const implied = new Set();
+  for (const rule of ORIENTATION_RULES) {
+    if (rule.re.test(text)) {
+      implied.add(rule.ratio);
+    }
+  }
+  if (implied.size === 1) {
+    const [only] = [...implied];
+    return { aspectRatio: only ?? null, signal: "orientation_phrase" };
+  }
+  return { aspectRatio: null, signal: null };
+}
+
+function requestedAspectRatioFromBrief(input) {
+  return classifyRequestedAspectRatio(input).aspectRatio;
+}
+
+// The normalized ratios a model publishes, or null when the payload does not
+// say. The hosted `/v1/models` list is a compact summary and omits the `media`
+// block entirely, so "not published" is the common case here and must be kept
+// distinct from "published and does not include this ratio".
+function guideModelAspectRatioValues(model) {
   const values = Array.isArray(model?.media?.input?.aspect_ratios?.values)
     ? model.media.input.aspect_ratios.values
     : model?.aspect_ratios;
-  if (!Array.isArray(values)) {
+  return Array.isArray(values) ? values : null;
+}
+
+// Tri-state on purpose: true (published and supported), false (published and
+// NOT supported), null (capability unknown). Unknown must never be read as a
+// denial -- doing so would make every ratio request in production claim "no
+// available model supports this", which is worse than the bug being fixed.
+function modelAspectRatioSupport(model, aspectRatio) {
+  if (aspectRatio === null || aspectRatio === undefined) {
+    return true;
+  }
+  const values = guideModelAspectRatioValues(model);
+  return values === null ? null : values.includes(aspectRatio);
+}
+
+function modelCannotExpressAspectRatio(model, aspectRatio) {
+  return modelAspectRatioSupport(model, aspectRatio) === false;
+}
+
+// Honest capability note for the case where an explicitly requested aspect
+// ratio made the guide skip its normal top pick. Name the capability that
+// forced the hop so agents learn which model could not express the shape.
+function aspectRatioRoutedCreateSelectionReason(input) {
+  return `guide selected a create model that supports the requested ${input.aspectRatio} aspect ratio because ${input.skippedModelId} does not expose ${input.aspectRatio}`;
+}
+
+// Fail-honestly note for the case where NO available model can express the
+// requested ratio. The guide keeps its normal selection and says so rather than
+// silently dropping the ratio, which is the exact failure this fixes.
+function aspectRatioUnsupportedWarning(input) {
+  return `The requested ${input.aspectRatio} aspect ratio is not supported by any available model, so data.next_command omits --aspect-ratio and ${input.modelId} will use its own default shape. Run the model_inspection_command to see the ratios it does support.`;
+}
+
+function createGuideSuggestedAspectRatio(input) {
+  const model = input?.model ?? null;
+  const requestedAspectRatio = input?.requestedAspectRatio ?? null;
+  if (model === null) {
+    return null;
+  }
+  // An explicit request wins for every modality, but not when the selected
+  // model is KNOWN not to express it. In that case return null so
+  // `next_command` stays runnable (`--aspect-ratio` would fail model
+  // validation) and let the caller warn instead of silently pretending the
+  // ratio was honored.
+  if (requestedAspectRatio !== null) {
+    return modelCannotExpressAspectRatio(model, requestedAspectRatio)
+      ? null
+      : requestedAspectRatio;
+  }
+  // No explicit request: preserve the existing video-only default.
+  if (model?.modality !== "video") {
+    return null;
+  }
+  const values = guideModelAspectRatioValues(model);
+  if (values === null) {
     return null;
   }
   return values.includes("16:9") ? "16:9" : (values[0] ?? null);
@@ -2732,9 +3245,14 @@ function createGuideSelectionReason(
       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";
+    const intentClass = createGuideIntentClass(intent);
+    if (intentClass === "budget_draft") {
+      return "guide selected the lowest-credit available create model for a draft/budget intent";
+    }
+    if (intentClass === "general") {
+      return "guide selected a cost-efficient general-purpose create model for iteration; pass --intent final for the quality-first model";
+    }
+    return "guide selected the strongest currently available quality-first create model for this intent";
   }
   return operation === "edit"
     ? "guide selected the first available executable input-image edit model"
@@ -3389,7 +3907,24 @@ function createGuideBlocker(stage, input) {
     };
   }
   if (stage === "quota_required") {
-    const remaining = quotaRemainingCredits(input.quota?.envelope.data ?? null);
+    const quotaData = input.quota?.envelope.data ?? null;
+    const remaining = quotaRemainingCredits(quotaData);
+    // Mirror createGuideStage's credit-first ordering: credits only outrank the
+    // daily-job cap when they are genuinely short. Agents that hold spare
+    // credits but hit the daily allowance (issues #2103, #2148) must be told the
+    // honest trigger, not a credits-shortfall line that reads as wrong to them
+    // (same confusion class as #1193).
+    const creditsShort =
+      input.estimatedCredits !== null &&
+      remaining !== null &&
+      remaining < input.estimatedCredits;
+    const dailyJobs = quotaData?.daily_jobs;
+    if (!creditsShort && dailyJobs !== undefined && dailyJobs.remaining <= 0) {
+      return {
+        code: "quota_required",
+        message: `You've reached today's job allowance (${dailyJobs.cap}/day); a top-up raises your daily allowance so you can keep creating now.`,
+      };
+    }
     return {
       code: "quota_required",
       message: `Selected first image requires ${input.estimatedCredits ?? "unknown"} credits; current remaining credits are ${remaining ?? "unknown"}.`,
@@ -4000,14 +4535,22 @@ function createGuideWarning(stage, input) {
       warning,
     };
   }
+  // #2204-#2216: name the field this response actually carries. The compact
+  // ready payload drops the `recommended_no_spend_command` alias, so it points
+  // at the base field instead; blocked and `--explain` payloads keep the alias
+  // and keep naming it. Either way
+  // `data[data.guide_warning.recommended_command_field]` resolves.
+  const noSpendField =
+    input.readyCompact === true
+      ? "no_spend_next_command"
+      : "recommended_no_spend_command";
   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.",
+    recommended_command_field: noSpendField,
+    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.${noSpendField}.`,
   };
 }
 
@@ -4097,6 +4640,7 @@ function createGuideNextCommand(stage, input) {
       prompt: input.prompt,
       inputReference: input.inputReference,
       budgetGuard: input.budgetGuard,
+      aspectRatio: input.aspectRatio,
       modelParametersJson: input.modelParametersJson,
       dryRun: false,
       idempotencyKey: `edit-guide-${Date.now()}-${randomBytes(4).toString("hex")}`,
@@ -4156,6 +4700,7 @@ function createGuideEscapeHatches(input) {
               prompt: input.prompt,
               inputReference: input.inputReference,
               budgetGuard: input.budgetGuard,
+              aspectRatio: input.aspectRatio,
               modelParametersJson: input.modelParametersJson,
               dryRun: true,
               apiBaseUrl: input.apiBaseUrl,
@@ -4185,7 +4730,7 @@ function renderGuideCommand(
   const operation = options.operation ?? "create";
   return [
     commandPrefix,
-    `${operation} --guide --prompt`,
+    `${operation} --guide${options.explain === true ? " --explain" : ""} --prompt`,
     shellQuote(prompt),
     ...(operation === "edit" &&
     typeof options.inputReference === "string" &&
@@ -4291,6 +4836,9 @@ function renderInputImageGuideCommand(input) {
     "--model",
     shellQuote(input.modelId),
     ...(promptless ? [] : ["--prompt", shellQuote(input.prompt)]),
+    ...(input.aspectRatio === null || input.aspectRatio === undefined
+      ? []
+      : ["--aspect-ratio", shellQuote(input.aspectRatio)]),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
     ...(input.modelParametersJson === null ||
@@ -4439,6 +4987,18 @@ async function create(argv) {
   if (flagBool(args, "guide")) {
     return createGuide(args);
   }
+  if (flagBool(args, "no-spend")) {
+    return invalid(
+      "luxin create",
+      "create --no-spend is a guide output mode; combine it with --guide, or use create --dry-run for a no-spend planned job",
+    );
+  }
+  if (flagBool(args, "explain")) {
+    return invalid(
+      "luxin create",
+      "create --explain is a guide output mode; combine it with --guide to return every guide field",
+    );
+  }
   const prompt = await promptValue(args);
   if (!prompt.ok) {
     return prompt.result;
@@ -4586,6 +5146,18 @@ async function edit(argv) {
       inputReference: input,
     });
   }
+  if (flagBool(args, "no-spend")) {
+    return invalid(
+      "luxin edit",
+      "edit --no-spend is a guide output mode; combine it with --guide, or use edit --dry-run for a no-spend planned job",
+    );
+  }
+  if (flagBool(args, "explain")) {
+    return invalid(
+      "luxin edit",
+      "edit --explain is a guide output mode; combine it with --guide to return every guide field",
+    );
+  }
   if (input === undefined) {
     return invalid(
       "luxin edit",
@@ -4705,7 +5277,7 @@ async function assets(argv) {
   if (assetId === null) {
     return invalid(
       "luxin assets",
-      "assets currently supports Luxin asset ids and media.image-skill.com URLs",
+      `assets currently supports Luxin asset ids and ${ACCEPTED_PUBLIC_MEDIA_HOSTS.join(" or ")} URLs`,
     );
   }
   const token = await resolveToken(args);
@@ -6967,6 +7539,16 @@ function quotaRecoveryWithCopyRunnableCommands(recovery, commandPrefix) {
           ),
         }
       : {}),
+    ...(recovery.human_handoff &&
+    typeof recovery.human_handoff === "object" &&
+    typeof recovery.human_handoff.command === "string"
+      ? {
+          human_handoff: {
+            ...recovery.human_handoff,
+            command: render(recovery.human_handoff.command),
+          },
+        }
+      : {}),
     top_up: quotaTopUpWithCopyRunnableCommands(recovery.top_up, commandPrefix),
   };
 }
@@ -7130,7 +7712,7 @@ function assetIdFromReference(reference) {
     const url = new URL(reference);
     if (
       url.protocol !== "https:" ||
-      url.hostname !== "media.image-skill.com" ||
+      !ACCEPTED_PUBLIC_MEDIA_HOSTS.includes(url.hostname.toLowerCase()) ||
       !url.pathname.startsWith("/a/")
     ) {
       return null;