luxin-cli 0.2.3 → 0.2.5

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.3";
+const VERSION = "0.2.5";
 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,
@@ -553,6 +710,7 @@ function commandHelpByKey(key) {
       optional_flags: [
         "--guide",
         "--no-spend",
+        "--explain",
         "--dry-run",
         "--model",
         "--aspect-ratio",
@@ -1753,16 +1911,71 @@ 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);
+  // The compact hosted list omits `media.input.aspect_ratios` entirely, so the
+  // ratio capability can only come from the detail endpoint. Probe when the
+  // brief named a ratio (selection itself has to be capability-aware) and also
+  // when the pick is a video model: `selection.suggested_aspect_ratio` is
+  // video-only, and without the probe it reported null on every real video
+  // brief that did not state a ratio -- the same
+  // published-payload-omits-the-field defect as #2265, one field over.
+  const needsAspectRatioCapabilities =
+    briefAspectRatio !== null || selection?.model?.modality === "video";
+  if (needsAspectRatioCapabilities && 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,
+        routing: briefAspectRatio !== null,
+      }),
+      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,
@@ -1780,41 +1993,30 @@ async function createGuide(args, options = {}) {
           modelParameters: modelParameters.value ?? {},
           maxEstimatedUsdPerImage,
         });
-  const shouldPriceModelParameters =
-    selected !== null &&
-    !createGuideSelectedModelRequiresInputImage(selected) &&
-    createGuideCanPriceModelParameters(selected) &&
-    (defaultedModelParameters.defaultsApplied.length > 0 ||
-      Object.keys(modelParameters.value ?? {}).length > 0);
+  // Price the request the guide is about to emit, at the ratio it will emit it
+  // with -- not the registry's default-shape quote, which describes a request
+  // `create` never makes (#2259). Models priced from input-image dimensions stay
+  // on the quote: the guide uploads nothing, so there are no dimensions to price
+  // from. `tests/hosted-create-estimate-parity.test.ts` pins this against the
+  // source dry-run so the two implementations cannot drift apart again.
   const pricing =
-    selected === null
-      ? null
-      : shouldPriceModelParameters
-        ? createGuidePricingForModel(
-            selected,
-            defaultedModelParameters.modelParameters,
-            pricingContext,
-          )
-        : createGuideModelCreditPricing(selected);
-  const providerCostEstimate =
-    selected === null || !shouldPriceModelParameters
-      ? null
-      : createGuideProviderCostEstimateForModel(
+    selected === null || createGuideSelectedModelRequiresInputImage(selected)
+      ? createGuideModelCreditPricing(selected)
+      : createGuidePricingForModel(
           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 ??
@@ -1863,10 +2065,19 @@ async function createGuide(args, options = {}) {
     guideCommandPrefix,
   );
   const blocker = createGuideBlocker(stage, {
+    operation: guideOperation,
     requestedModelId,
     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,
@@ -1925,11 +2136,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,
   );
@@ -1991,9 +2212,16 @@ async function createGuide(args, options = {}) {
   // 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");
-  const paymentSummaryOutput = noSpendOutputMode
-    ? { ...paymentSummary, suggested_commands: [] }
-    : paymentSummary;
+  // 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
@@ -2030,7 +2258,7 @@ async function createGuide(args, options = {}) {
             },
           ),
           inspect_methods_command: escapeHatches.payment_methods,
-          note: "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).",
+          note: noSpendDiscoveryNote(readyCompact),
         },
       }
     : {
@@ -2046,7 +2274,49 @@ async function createGuide(args, options = {}) {
     escapeHatches,
     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"
@@ -2086,7 +2356,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"
@@ -2109,20 +2379,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,
@@ -2152,6 +2430,7 @@ async function createGuide(args, options = {}) {
     auth_handoff: authHandoff,
     escape_hatches: escapeHatches,
     no_spend_output_mode: noSpendOutputModeData,
+    output_mode: outputModeData,
     mutation: {
       provider_call: false,
       hosted_create: false,
@@ -2160,7 +2439,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) {
@@ -2177,6 +2460,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) =>
@@ -2187,17 +2476,23 @@ function selectCreateGuideModel(
   const isExecutableInputImageEdit = (model) =>
     model?.status === "available" &&
     guideModelExecutionStatus(model) === "executable" &&
-    Array.isArray(model?.supports) &&
-    (model.supports.includes("edit") || model.supports.includes("variation")) &&
     createGuideSelectedModelRequiresInputImage(model);
   const isExecutableGuideModel = (model) =>
     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 =
@@ -2214,7 +2509,7 @@ function selectCreateGuideModel(
     });
     const threeDimensional = eligible3d[0];
     if (threeDimensional !== undefined) {
-      return threeDimensional;
+      return chosen(threeDimensional);
     }
   }
   const eligible = guideCandidatesWithinBudget({
@@ -2224,23 +2519,156 @@ 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,
+      });
+    }
+  }
+
+  // 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, routing }) {
+  const ids = [];
+  if (typeof selected?.id === "string") {
+    ids.push(selected.id);
+  }
+  // Only a stated ratio can make the guide hop between models. Without one the
+  // sole open question is what the current pick can express, so asking about
+  // the alternatives would be a round trip spent on an answer nothing reads.
+  if (routing) {
+    for (const modelId of preferredCreateGuideModelIds(
+      createGuideIntentClass(intent),
+    )) {
+      if (models.some((model) => model?.id === modelId)) {
+        ids.push(modelId);
+      }
     }
   }
-  return eligible[0] ?? null;
+  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 = [
@@ -2412,29 +2840,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) ??
@@ -2450,7 +2896,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,
@@ -2459,8 +2905,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";
@@ -2490,8 +2936,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");
@@ -2502,45 +2948,59 @@ 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,
-  });
-}
-
-function createGuideCanPriceModelParameters(model) {
-  return String(model?.id ?? "").startsWith("xai.grok-imagine-image");
+  return (
+    createGuideAspectRatioCreditPricing(model, context) ??
+    createGuideModelCreditPricing(model)
+  );
 }
 
-function createGuideProviderCostEstimateForModel(
-  model,
-  modelParameters = {},
-  context = {},
-) {
-  if (String(model?.id ?? "").startsWith("xai.grok-imagine-image")) {
-    return createGuideXaiImageCostEstimate(model, modelParameters, context);
+// The debit `create` will actually make at the ratio the guide is about to
+// emit, read from the model registry (#2259).
+//
+// `economics.credit_pricing` is the quote at the model's own default shape --
+// no aspect ratio, no policy model-parameter defaults. `create` never sends
+// that request: it always sends a concrete ratio (`1:1` unless the brief asked
+// otherwise) plus the hosted defaults. For any model priced from its output
+// shape or from a defaulted parameter the quote is therefore not the debit, and
+// this CLI has no pricing engine to recompute it -- so the registry publishes
+// the answer and this reads it. Absent field means the quote already is the
+// debit.
+function createGuideAspectRatioCreditPricing(model, context) {
+  // Both shapes: `GET /v1/models` serves the COMPACT summary, which flattens
+  // economics onto the row, and only `?details=true` (or a fixture built from
+  // the full catalog) nests it. Reading only the nested one is how a fix passes
+  // its own test against a payload production never sends.
+  const byAspectRatio = isRecord(
+    model?.economics?.create_credit_debit_by_aspect_ratio,
+  )
+    ? model.economics.create_credit_debit_by_aspect_ratio
+    : model?.create_credit_debit_by_aspect_ratio;
+  const aspectRatio = context?.aspectRatio;
+  if (!isRecord(byAspectRatio) || typeof aspectRatio !== "string") {
+    return null;
+  }
+  const credits = byAspectRatio[aspectRatio];
+  if (!Number.isFinite(credits)) {
+    return null;
   }
+  const quoted = createGuideModelCreditPricing(model);
   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",
+    ...(quoted ?? {}),
+    credits_required: credits,
+    credit_unit_usd: CREDIT_UNIT_USD,
+    estimated_charge_usd: roundUsd(credits * CREDIT_UNIT_USD),
+    pricing_confidence: quoted?.pricing_confidence ?? "known",
   };
 }
 
-function createGuideXaiImageCostEstimate(model, modelParameters, context) {
+function createGuideCanPriceModelParameters(model) {
+  return String(model?.id ?? "").startsWith("xai.grok-imagine-image");
+}
+
+function createGuideXaiImagePricing(model, modelParameters, context) {
   const modelId = String(model?.id ?? "");
   const quality = modelId.includes("-quality");
   const edit = modelId.endsWith("-edit");
@@ -2555,11 +3015,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 ||
@@ -2568,67 +3037,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",
   };
 }
 
@@ -2653,14 +3067,47 @@ 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;
 }
 
+// ---------------------------------------------------------------------------
+// How the guide reads a model field. Read this before adding an accessor.
+//
+// There is NO normalizer. `createGuide` hands the rows from `GET /v1/models`
+// to these accessors verbatim -- `withModelSummary` is the `models list`
+// command's compactor and never runs on this path. So an accessor here has to
+// cope with BOTH published shapes itself:
+//
+//   GET /v1/models      (compact list)   flat: model_execution_status,
+//                                        credits_required, estimated_usd_per_image,
+//                                        max_outputs_per_request, artifact_storage.
+//                                        NO `media`, `execution`, or `economics`.
+//   GET /v1/models/:id  (detail)         nested under execution/economics/media.
+//
+// The convention is therefore NESTED-OR-FLAT: try the detail shape, fall back
+// to the flat field the list actually publishes. That convention is the whole
+// safety property, and #2265 was one accessor quietly breaking it.
+// `createGuideSelectedModelRequiresInputImage` read
+// `media.input.images.required` with a "fallback" of `accepts_input_images` --
+// a field the API has never published -- so against a real list row it had no
+// fallback at all, and it failed closed.
+//
+//   guideModelExecutionStatus       execution.model_execution_status  -> flat
+//   createGuideModelCreditPricing   economics.credit_pricing          -> flat
+//   guideBudgetUsdForModel          economics.estimated_usd_per_image -> flat
+//   guideModelAspectRatioValues     media.input.aspect_ratios.values  -> none;
+//                                   fails open and is hydrated from the detail
+//                                   endpoint on demand (see the note there)
+//   ...SelectedModelRequiresInputImage  reads `supports`, published on the list
+//
+// `max_outputs_per_request` and `artifact_storage` are published flat as well,
+// but nothing on the guide path reads them. Their only nested reads live in
+// `modelSummaryRow`/`modelSummaryTaskTags`, which `withModelSummary` skips
+// outright for a payload already marked `compact_model_summary` -- which the
+// hosted list is. Those eight `media.*` reads therefore never see a list row.
+// ---------------------------------------------------------------------------
+
 function guideModelExecutionStatus(model) {
   if (
     isRecord(model?.execution) &&
@@ -2682,16 +3129,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
@@ -2726,23 +3165,174 @@ 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".
+//
+// #2265, worth stating because the next reader will assume otherwise: this is
+// ONE OF EXACTLY TWO `media.*` reads that run over the LIST payload, and the
+// two behave OPPOSITELY. `GET /v1/models/:id` does publish `media`; the compact
+// list does not. So a `media.*` read is only safe here if it either fails open
+// or arranges to be hydrated from the detail endpoint first.
+//
+//   - This one FAILS OPEN. Unknown never disqualifies a model, so an unhydrated
+//     read costs a hint, not a decision. That is why capability routing kept
+//     working in production while `edit --guide` was dead.
+//   - `createGuideSelectedModelRequiresInputImage` used to FAIL CLOSED: no
+//     `media` meant no model could prove it accepts an input image, so `edit
+//     --guide` selected nothing on every real call. It no longer reads `media`
+//     at all -- see the note there.
+//
+// Failing open is not the same as being correct. `guideModelSuggestedAspectRatio`
+// consumes this to REPORT a value rather than to gate one, so before the probe
+// was extended to video picks it published `suggested_aspect_ratio: null` on
+// every video brief that did not state a ratio -- silently, since no blocker
+// fires. Fail-open degrades quietly; that is its failure mode, not its absence.
+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);
 }
 
+// #2265: this must decide from what the hosted payload actually publishes.
+// `GET /v1/models` returns the compact summary, which omits the `media` block
+// entirely (and has never published `accepts_input_images`), so gating on
+// `media.input.images.required` disqualified every model on every real call and
+// `edit --guide` could not select one, ever.
+//
+// This read FAILED CLOSED, which is why it was catastrophic rather than merely
+// lossy: an absent field could not prove any model accepts an input image, so
+// the guide selected nothing and reported `no_executable_model`. The other
+// list-payload `media.*` read (`guideModelAspectRatioValues`) fails open and
+// only loses a hint. Do not assume the two are interchangeable -- see the note
+// there before adding a third.
+//
+// `supports` is published and carries the same fact: it is derived from the
+// capability's operations (`image.edit` -> "edit", `image.variation` ->
+// "variation"), and both are input-image operations by construction. On the
+// live 220-model catalog the old conjunction and this predicate select the
+// identical 79 models, so the dropped conjunct was doing no work -- while
+// costing the mirror the ability to decide at all.
+//
+// Keep this reading only summary fields. `src/` holds strictly more model data
+// than the mirror can ever see; every extra field the guide reads there is a
+// fresh chance for the two surfaces to decide differently.
 function createGuideSelectedModelRequiresInputImage(model) {
   return (
-    (model?.media?.input?.images?.required === true ||
-      model?.accepts_input_images === true) &&
     Array.isArray(model?.supports) &&
     (model.supports.includes("edit") || model.supports.includes("variation"))
   );
@@ -2787,9 +3377,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"
@@ -3428,12 +4023,16 @@ function createGuideBlocker(stage, input) {
     };
   }
   if (stage === "no_executable_model") {
+    // #2265: name the operation that actually failed. Saying "create" when the
+    // caller ran `edit --guide` made the one diagnostic an agent gets point at
+    // the wrong half of the product.
+    const operation = input.operation === "edit" ? "edit" : "create";
     return {
       code: "no_executable_model",
       message:
         input.requestedModelId === null
-          ? "No available executable create model was found in the public registry."
-          : `Requested model is not currently an available executable create model: ${input.requestedModelId}`,
+          ? `No available executable ${operation} model was found in the public registry.`
+          : `Requested model is not currently an available executable ${operation} model: ${input.requestedModelId}`,
     };
   }
   if (stage === "auth_required") {
@@ -4072,14 +4671,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}.`,
   };
 }
 
@@ -4169,6 +4776,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")}`,
@@ -4228,6 +4836,7 @@ function createGuideEscapeHatches(input) {
               prompt: input.prompt,
               inputReference: input.inputReference,
               budgetGuard: input.budgetGuard,
+              aspectRatio: input.aspectRatio,
               modelParametersJson: input.modelParametersJson,
               dryRun: true,
               apiBaseUrl: input.apiBaseUrl,
@@ -4257,7 +4866,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" &&
@@ -4363,6 +4972,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 ||
@@ -4517,6 +5129,12 @@ async function create(argv) {
       "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;
@@ -4670,6 +5288,12 @@ async function edit(argv) {
       "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",
@@ -4789,7 +5413,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);
@@ -7224,7 +7848,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;