luxin-cli 0.2.3 → 0.2.5

package/skills/image-edit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: image-edit
 description: >-
-  Image editing for agents: image-to-image edits, variations, and image-conditioned transforms through Luxin's zero-setup hosted runtime. Use when an agent needs to edit an existing image without provider credentials, OAuth, local runtime, or per-provider billing. Inspect the edit model, upload or reuse an input image, then return durable hosted assets, jobs, cost receipts, stable JSON, and feedback.
+  Edit an existing image from a prompt: replace a background, restyle it, fix a detail, or produce variations. No API key to obtain, no provider account to open, no billing to set up. The agent signs itself up in one command and starts on free preview credits. Upload an image or reuse one it already made, then get the edit back as a hosted media URL with no signature or expiry, plus a receipt for what the call cost.
 homepage: https://luxin.sh
 docs: https://luxin.sh/llms.txt
 metadata:

package/skills/image-generation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: image-generation
 description: >-
-  Image generation for agents: text-to-image and prompt-to-image through Luxin's zero-setup hosted runtime. Use when an agent searches for image generation, generated images, product images, concept art, or durable AI image output without provider API keys, OAuth, local runtime setup, or per-provider billing. Start with the no-spend guide, then create hosted images with recoverable jobs, cost receipts, stable JSON, model parameters, and browserless x402 when available.
+  Generate images from a text prompt without wiring up a provider first. The agent signs itself up in one command and starts on free preview credits: no API key to obtain, no billing account to set up. A no-spend guide picks a model and returns the exact create command, so the agent can skip model selection. Each image comes back as a hosted media URL with no signature or expiry, plus a receipt for what the call cost.
 homepage: https://luxin.sh
 docs: https://luxin.sh/llms.txt
 metadata:
@@ -30,7 +30,7 @@ Do not bring provider API keys, create provider accounts, run a local model serv
 ## First Command
 
 ```bash
-npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --model openai.gpt-image-2 --prompt "a compact field camera on a stainless workbench"
+npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
 ## Main Runtime Command

package/skills/image-skill/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: image-skill
+description: >-
+  Image generation and image editing for agents under Luxin's original skill name, with no API key to obtain first. The agent signs itself up in one command, starts on free preview credits, and creates on the next: no provider account to open, no billing to set up. Every result returns a hosted media URL with no signature or expiry, a job id the agent can re-fetch, and a receipt for what the call cost.
+homepage: https://luxin.sh
+docs: https://luxin.sh/llms.txt
+metadata:
+  status: preview-contract
+  cli: luxin
+  canonical_skill_url: https://luxin.sh/skill.md
+  canonical_api_url: https://api.luxin.sh
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by luxin signup and saved by default; not a user-supplied provider credential.
+---
+
+# Image Skill
+
+This is an intent-named Luxin entry for agents searching for image generation and editing. It uses the same zero-setup hosted Luxin runtime as the canonical `luxin` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks for image generation or image editing, or when an agent or install command still refers to this project by its former name, image-skill. It resolves to the same Luxin runtime as the canonical luxin skill.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend guide command below; when the guide reaches `ready_to_create`, run `data.next_command` only if `data.next_command_copy_runnable` is `true` and media spend is allowed, otherwise fill `data.next_command_missing_inputs` or run `data.recommended_no_spend_command` to verify safely. Keep generated work in Luxin so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --prompt "a compact field camera on a stainless workbench"
+```
+
+## Main Runtime Command
+
+```bash
+npm_config_update_notifier=false npx -y luxin-cli@latest create --prompt "PROMPT" --intent explore --max-estimated-usd-per-image 0.07
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/luxin --full-depth --skill image-skill -g -a codex -y
+```
+
+The canonical Luxin entry remains available as:
+
+```bash
+npx skills add danielgwilson/luxin --full-depth --skill luxin -g -a codex -y
+```
+
+If the Codex/global skill target is read-only or missing, keep the tracked slug
+install and point agent skill state at a writable workspace home before
+rerunning this intent install. The skills.sh Codex adapter writes to
+`$HOME/.agents`; `CODEX_HOME` keeps Codex profile state on the same writable
+path:
+
+```bash
+export HOME="$PWD/.agent-home"
+export CODEX_HOME="$HOME/.codex"
+mkdir -p "$HOME" "$CODEX_HOME"
+npx skills add danielgwilson/luxin --full-depth --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://luxin.sh/skill.md
+- LLM contract: https://luxin.sh/llms.txt
+- CLI contract: https://luxin.sh/cli.md
+- Hosted API: https://api.luxin.sh
+
+If Luxin lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `luxin feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.

package/skills/image-to-3d/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: image-to-3d
 description: >-
-  Image-to-3D asset creation for agents through Luxin's zero-setup hosted runtime. Use when an input image should become a durable hosted 3D mesh asset, such as a glb, without provider credentials, OAuth, local runtime, or per-provider billing. Inspect the 3D model, pass one owned input image to edit, then keep jobs, asset URLs, receipts, JSON recovery, payments, and feedback in one loop.
+  Turn one image into a 3D mesh and get back a glb file. No API key to obtain, no provider account to open, no billing to set up: the agent signs itself up in one command and starts on free preview credits. Image-to-3D takes no prompt and rejects one if you send it, so pass an image the agent generated or uploaded, through edit rather than create. The mesh returns as a hosted media URL with no signature or expiry, a job id the agent can re-fetch, and a receipt for what the call cost.
 homepage: https://luxin.sh
 docs: https://luxin.sh/llms.txt
 metadata:
@@ -30,7 +30,7 @@ Do not bring provider API keys, create provider accounts, run a local model serv
 ## First Command
 
 ```bash
-npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --model fal.trellis-image-to-3d --prompt "turn one product photo into a textured 3d mesh"
+npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --prompt "turn one product photo into a textured 3d mesh"
 ```
 
 ## Main Runtime Command

package/skills/luxin/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: luxin
 description: >-
-  AI image generation and editing for agents across text-to-image and
-  image-to-image workflows, video generation, audio generation, and image-to-3D
-  asset creation through one zero-setup hosted runtime. Use Luxin when an
-  agent needs durable media URLs, recoverable jobs, model/cost inspection and
-  stable JSON envelopes with capability-preserving parameters. Optional
-  agent-funded credits work without a provider API key, OAuth app, local model
-  or per-provider billing account.
+  Image generation and image editing for agents, plus video, audio, and
+  image-to-3D, through one hosted runtime with no API key to obtain first. The
+  agent signs itself up in one command, starts on free preview credits, and
+  creates on the next: no provider account to open, no billing to set up. Every
+  result returns a hosted media URL with no signature or expiry, a job id the
+  agent can re-fetch with jobs show, and a receipt for what the call cost. When
+  the preview credits run out, the agent hands its human one dashboard link to
+  fund more.
 homepage: https://luxin.sh
 docs: https://luxin.sh/llms.txt
 metadata:
@@ -39,7 +40,7 @@ JSON is the default. Do not add `--json` to examples.
 npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-The guide is a free, zero-spend planning call. Given current auth, quota, and payment state, it returns `data.next_command`, `data.next_command_copy_runnable`, `data.next_command_missing_inputs`, `data.stage`, `data.guide_warning`, `data.next_command_effect`, `data.auth_ready`, `data.no_spend_evaluation`, `data.guide_recovery`, `data.recommended_no_spend_command` (alias of `data.no_spend_next_command`), `data.no_spend_next_command_effect`, `data.self_fund_next_command`, `data.self_fund_handoff`, `data.self_fund_preparation`, `data.auth_handoff`, and `data.mutation`. It also preserves `data.checks.quota.top_up`, the same quota top-up recommendation returned by `usage quota`, so wallet-capable agents can see whether a browserless x402 top-up is recommended before the hard wall. Read `data.guide_warning` before running `data.next_command`: `next_command_safety` names whether the command is no-spend setup, read-only inspection, live-money payment action, or live media create. Run that next command only when `data.next_command_copy_runnable` is `true` and the warning says it is safe for your spend policy; when it is `false`, fill `data.next_command_missing_inputs` first. Prefer `data.guide_recovery` for no-doc recovery loops: it names the safest no-spend command and field, the live create or payment field that would spend, and the double-spend guard to check before any live retry. Repeat until `data.stage` is `ready_to_create`. At `ready_to_create`, `data.auth_ready.ready` and `data.auth_ready.next_command_auth_ready` are `true`: the returned create can reuse saved config, env token, or stdin token context without exposing a raw token. Read `data.self_fund_preparation` in this stage before spending the remaining free allowance: when `available` is true, it mirrors top-up `urgency`, `urgency_score`, and `urgency_reasons`; when `recommended` is true, `quote_command` creates an authenticated live-money quote/payment object but does not pay, settle a wallet transfer, debit credits, call a provider, or write media. When that quote is copy-runnable, `data.self_fund_next_command` aliases it with a `pre_wall_...` label such as `pre_wall_browserless_agent_payable_quote`, so you can open the quote path before the quota wall. Only a later buy/payment step can spend money. When `data.guide_warning.next_command_safety` is `live_media_create_credit_debit` and `data.no_spend_evaluation.stop_here` is `true`, `data.next_command` is the live create: run it only if media spend is allowed, otherwise stop before it and run `data.recommended_no_spend_command` for no-spend proof. The no-spend command is an authenticated hosted dry-run: it may create a recoverable `job.planned` receipt, but it has no provider call, credit debit, downloadable asset, or media write.
+The guide is a free, zero-spend planning call. Given current auth, quota, and payment state, it returns `data.next_command`, `data.next_command_copy_runnable`, `data.next_command_missing_inputs`, `data.stage`, `data.guide_warning`, `data.next_command_effect`, `data.no_spend_next_command` and `data.no_spend_next_command_effect`, `data.output_mode`, and `data.mutation`. The guide shapes the rest on state. While it is blocked it also returns `data.recommended_no_spend_command` (a documented alias of `data.no_spend_next_command`) and its label/effect, `data.auth_ready`, `data.no_spend_evaluation`, `data.guide_recovery`, `data.self_fund_next_command`, `data.self_fund_handoff`, `data.self_fund_preparation`, `data.auth_handoff`, `data.escape_hatches`, and the full `data.checks.quota.top_up` recommendation returned by `usage quota` — everything a blocked agent needs to unblock itself. Once `data.stage` is `ready_to_create` and `data.blocker` is `null`, nothing is blocked on funding or auth, so those fields are omitted and the response is the decision plus the no-spend proof. `data.output_mode` always tells you which shape you got: `mode` is `ready_compact` or `full`, `omitted_fields` names every omitted key, `compacted_fields` names sub-objects that are present but emptied, and `full_output_command` is a copy-runnable rerun with `--explain` that returns everything in every stage. When a pre-wall top-up is actually recommended, the `data.self_fund_*` fields stay in the compact response. Read `data.guide_warning` before running `data.next_command`: `next_command_safety` names whether the command is no-spend setup, read-only inspection, live-money payment action, or live media create. Run that next command only when `data.next_command_copy_runnable` is `true` and the warning says it is safe for your spend policy; when it is `false`, fill `data.next_command_missing_inputs` first. Prefer `data.guide_recovery` for no-doc recovery loops: it names the safest no-spend command and field, the live create or payment field that would spend, and the double-spend guard to check before any live retry. Repeat until `data.stage` is `ready_to_create`. At `ready_to_create` auth is already usable: the returned create can reuse saved config, env token, or stdin token context without exposing a raw token, and `data.auth_ready.ready` and `data.auth_ready.next_command_auth_ready` are `true` when you rerun with `--explain`. When a pre-wall top-up is recommended, read `data.self_fund_preparation` in this stage before spending the remaining free allowance: when `available` is true, it mirrors top-up `urgency`, `urgency_score`, and `urgency_reasons`; when `recommended` is true, `quote_command` creates an authenticated live-money quote/payment object but does not pay, settle a wallet transfer, debit credits, call a provider, or write media. When that quote is copy-runnable, `data.self_fund_next_command` aliases it with a `pre_wall_...` label such as `pre_wall_browserless_agent_payable_quote`, so you can open the quote path before the quota wall. Only a later buy/payment step can spend money. When `data.guide_warning.next_command_safety` is `live_media_create_credit_debit` and `data.guide_warning.no_spend_safe` is `false` (`data.no_spend_evaluation.stop_here` says the same under `--explain`), `data.next_command` is the live create: run it only if media spend is allowed, otherwise stop before it and run the field `data.guide_warning.recommended_command_field` names — resolve it as `data[data.guide_warning.recommended_command_field]` rather than hardcoding, since the compact response names `no_spend_next_command` and the fuller ones name the alias. The no-spend command is an authenticated hosted dry-run: it may create a recoverable `job.planned` receipt, but it has no provider call, credit debit, downloadable asset, or media write.
 
 When `data.stage` is `quota_required`, `data.self_fund_handoff` mirrors top-up `urgency`, `urgency_score`, and `urgency_reasons`, and exposes `first_safe_command` with a no-spend inspection effect. Run that no-spend command first when you need to inspect rails or stay below delegated spend authority before opening the live-money quote path.
 
@@ -53,7 +54,7 @@ Minimum success envelope on a create or edit:
     "assets": [
       {
         "asset_id": "image_...",
-        "url": "https://media.image-skill.com/a/image_...png",
+        "url": "https://media.luxin.sh/a/image_...png",
         "mime_type": "image/png"
       }
     ],
@@ -238,7 +239,7 @@ luxin claim code --json
 
 Give them `data.dashboard_url` and nothing else. They get a read-only view of your jobs, assets, quota, and activity, plus the ability to open a credit checkout for you. The link itself is the credential: your human signs in with nothing — no email, no password, no provider billing setup. Never share your token, and never quote the raw `data.code` in prompts, logs, issues, or feedback: the code is the whole credential. It rides in the URL fragment (`#code=...`), which browsers never send to a server, so share the link intact rather than rebuilding it as a query string.
 
-The code is single-use and expires (`data.ttl_seconds`, currently 15 minutes); the human session it opens lasts days. So one code is normally enough — reuse an unexpired `dashboard_url` instead of re-minting, and expect `DASHBOARD_CODE_RATE_LIMITED` past 30 codes per agent per hour. Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. `claim code` needs the `dashboard.claim` grant that `luxin signup --agent` tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write.
+The code is single-use and expires (`data.ttl_seconds`, currently 60 minutes); the human session it opens lasts days. So one code is normally enough — reuse an unexpired `dashboard_url` instead of re-minting, and expect `DASHBOARD_CODE_RATE_LIMITED` past 30 codes per agent per hour. Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. `claim code` needs the `dashboard.claim` grant that `luxin signup --agent` tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write.
 
 Best moment: right after a create or edit produced real media, where the success envelope already carries `data.next_actions.share_with_human` with this command and `share_field: "data.dashboard_url"`. A human who can see finished work is a human who will fund the next run. Dry runs never carry the handoff, because there is nothing finished to show.
 
@@ -257,6 +258,8 @@ luxin models show openai.gpt-image-2
 
 `--available` filters to runnable rows (`status:"available"` and `execution.model_execution_status:"executable"`). Do not treat provider-level `status:"available"` as runnable. `--catalog-only` exposes research rows that are not runnable yet; inspect them, do not pass them to create or edit.
 
+Aspect ratio is a normalized top-level control, not a `model_parameters` field: pass `--aspect-ratio 16:9` (API: top-level `aspect_ratio` on `/v1/create` and `/v1/edit`). Supported values are per-model — `models show MODEL_ID` lists them under `media.input.aspect_ratios.values`, and passing one a model does not expose fails before any spend. If you do not state a ratio, the model default applies, so put the ratio you need in the brief or pass the flag. `create --guide` reads an explicit ratio from your prompt, reports it as `selection.suggested_aspect_ratio`, prefers a model that can express it, and includes it in `data.next_command`.
+
 Pass model-specific controls through validated JSON, not invented top-level flags:
 
 ```bash
@@ -264,6 +267,7 @@ luxin create \
   --prompt-file ./prompt.md \
   --intent finalize \
   --model openai.gpt-image-2 \
+  --aspect-ratio 16:9 \
   --output-count 2 \
   --model-parameters-json '{"quality":"high","background":"opaque","output_format":"png"}' \
   --max-usd 0.80

package/skills/luxin/references/cli.md

@@ -196,8 +196,8 @@ luxin claim code --json
     "agent_id": "agt_...",
     "code": "dc_...",
     "dashboard_url": "https://luxin.sh/dashboard#code=dc_...",
-    "expires_at": "2026-07-30T18:15:00.000Z",
-    "ttl_seconds": 900,
+    "expires_at": "2026-07-30T19:00:00.000Z",
+    "ttl_seconds": 3600,
     "single_use": true,
     "human_handoff": {
       "purpose": "hand_dashboard_link_to_human",
@@ -217,7 +217,7 @@ the code is the whole credential. The code travels in the URL fragment
 logs and analytics — keep it that way by sharing the link intact rather than
 rebuilding it as a query string.
 
-The code is single-use and expires (`data.ttl_seconds`, currently 15 minutes).
+The code is single-use and expires (`data.ttl_seconds`, currently 60 minutes).
 The dashboard is read-only over your work — jobs, assets, quota, activity — plus
 the ability to open a credit checkout for you. It cannot create, edit, upload,
 or spend as you. Once your human has opened the link their session lasts days,
@@ -244,9 +244,41 @@ agent. It checks health, executable model availability, auth/quota when a token
 already exists, and payment rails, then returns one primary
 `data.next_command` plus machine-readable `data.next_command_copy_runnable`,
 `data.next_command_missing_inputs`, `data.next_command_effect`,
-`data.guide_warning`, `data.auth_ready`, `data.no_spend_evaluation`, and
-`data.guide_recovery`. Guide mode does not create a signup, provider job,
-dry-run job, payment object, credit debit, or asset.
+`data.guide_warning`, and `data.output_mode`. Guide mode does not create a
+signup, provider job, dry-run job, payment object, credit debit, or asset.
+
+The guide shapes its response on state. When the guide is blocked
+(`prompt_required`, `service_unreachable`, `no_executable_model`,
+`auth_required`, `quota_required`) it returns every field, including the
+self-fund, payment-recovery, and auth-handoff detail a blocked agent needs. When
+`data.stage` is `ready_to_create` and `data.blocker` is `null`, nothing is
+blocked on funding or auth, so the response is compact: it carries the decision
+(`data.next_command`, `data.selection`, `data.cost`), the safety verdict
+(`data.guide_warning`, `data.next_command_effect`), and the no-spend proof
+(`data.no_spend_next_command` and its effect), and omits
+`data.auth_ready`, `data.auth_handoff`, `data.escape_hatches`,
+`data.guide_recovery`, `data.no_spend_evaluation`, the `data.self_fund_*`
+fields, and the `data.recommended_no_spend_command` alias trio. The alias is a
+documented duplicate of `data.no_spend_next_command`; dropping it is why
+`data.guide_warning.recommended_command_field` names the base field in a
+compact response. Resolve the no-spend command through that pointer and the
+difference is invisible.
+
+`data.output_mode` always says which shape you got and never leaves a missing
+field ambiguous: `mode` is `ready_compact` or `full`, `omitted_fields` lists
+every omitted key by name, `compacted_fields` lists sub-objects that are present
+but emptied (`checks.quota.top_up`,
+`checks.payments.preferred_method_summary`, `checks.payments.suggested_commands`),
+and `full_output_command` is a copy-runnable rerun with `--explain` that returns
+every field in every stage. Add `--explain` to `create --guide` / `edit --guide`
+whenever you want the complete payload — debugging, harnesses, and
+recovery loops should use it. `--explain` is a guide output mode; it requires
+`--guide`.
+
+One exception keeps the funding path intact: when a pre-wall top-up is actually
+recommended (`data.self_fund_preparation.recommended` is `true`), the
+`data.self_fund_*` fields stay in the compact response and are not listed in
+`data.output_mode.omitted_fields`.
 
 ```bash
 IMAGE_SKILL_DISCOVERY_SOURCE=cli-md luxin create --guide --prompt "a compact field camera on a stainless workbench"
@@ -260,7 +292,10 @@ When `data.next_command_copy_runnable` is `false`, fill
 payment state changes. Do not run
 `doctor`, `models list`, `signup`, `whoami`, `usage quota`, `create --dry-run`,
 or payment commands as a setup checklist before the guide asks for them.
-For no-doc recovery loops, prefer `data.guide_recovery`: it names the current
+For no-doc recovery loops, prefer `data.guide_recovery`. It is returned
+whenever the guide is blocked; at an unblocked `ready_to_create` rerun the guide
+with `--explain` (or run `data.output_mode.full_output_command`) to get it. It
+names the current
 precondition (`precondition_code` / `precondition_message`), the safest
 no-spend command and field to run (`no_spend_command_field` /
 `no_spend_command`), the command to run after the precondition changes, and the
@@ -332,26 +367,34 @@ step.
   `false`, `data.guide_warning.spend_required` is `true`, and
   `data.guide_warning.recommended_command_field` is
   `recommended_no_spend_command`.
-  `data.auth_ready.ready` is `true`,
-  `data.auth_ready.next_command_requires_auth` is `true`, and
-  `data.auth_ready.next_command_auth_ready` is `true`; the returned
-  `data.next_command` can reuse the current saved config, env token, or stdin
-  token context without exposing a raw token.
-  `data.no_spend_evaluation.stop_here` is `true`,
-  `data.no_spend_evaluation.next_command_is_live_create` is `true`, and
-  `data.no_spend_evaluation.recommended_command_field` is
-  `recommended_no_spend_command`. Run `data.next_command` for the first bounded
+  This stage returns the compact payload described above:
+  `data.output_mode.mode` is `ready_compact`. Auth is already usable, so the
+  returned `data.next_command` reuses the current saved config, env token, or
+  stdin token context without exposing a raw token; `data.auth_ready` and
+  `data.auth_handoff` are omitted here and returned under `--explain`.
+  Run `data.next_command` for the first bounded
   create only when media spend is allowed. If you are in a no-spend evaluation
   or only need proof that the path is ready, stop before `data.next_command` and
-  run `data.recommended_no_spend_command` instead; it aliases
-  `data.no_spend_next_command` and is the dry-run plan command. Its
+  run the dry-run plan command instead. Always resolve it as
+  `data[data.guide_warning.recommended_command_field]` rather than hardcoding a
+  field name: in this compact response that field is `no_spend_next_command`,
+  and in blocked or `--explain` responses it is the
+  `recommended_no_spend_command` alias. Its
   `data.no_spend_next_command_effect.label` is
   `dry_run_planned_job_no_provider_call_no_credit_debit_no_media_write`, with
   `no_spend`, `hosted_create_dry_run`, `planned_job`, and `plan_receipt` true,
   `activity_event: "job.planned"`, and provider call, credit debit, and media
   write false. It may create a recoverable planned job/activity receipt, but no
-  provider execution, debit, downloadable asset, or media write. If the guide authenticated from
-  env or stdin, prefer
+  provider execution, debit, downloadable asset, or media write.
+  Under `--explain` this stage also returns
+  `data.auth_ready.ready` `true`,
+  `data.auth_ready.next_command_requires_auth` `true`,
+  `data.auth_ready.next_command_auth_ready` `true`,
+  `data.no_spend_evaluation.stop_here` `true`,
+  `data.no_spend_evaluation.next_command_is_live_create` `true`,
+  `data.no_spend_evaluation.recommended_command_field`
+  `recommended_no_spend_command`, and `data.guide_recovery`. If the guide
+  authenticated from env or stdin, prefer
   `data.auth_handoff.next_command.with_env` or
   `data.auth_handoff.next_command.with_stdin` so auth follows the create.
 
@@ -370,13 +413,23 @@ stays discoverable without dominating via
 `data.no_spend_output_mode.self_fund_discovery`: its
 `rerun_with_funding_command` re-runs the guide without `--no-spend` to surface
 the funding templates, and `inspect_methods_command` is a read-only, no-spend
-payment-method inspection (the same command as
-`data.escape_hatches.payment_methods`). `--no-spend` is a guide output mode; it
+payment-method inspection (the same command as `data.escape_hatches.payment_methods`
+when that field is present). `--no-spend` is a guide output mode; it
 requires `--guide`, and for a no-spend planned job outside the guide use
 `create --dry-run`.
 
+`--no-spend` composes with the state-dependent shaping above: at an unblocked
+`ready_to_create` the response is already compact, so
+`data.output_mode.omitted_fields` and
+`data.no_spend_output_mode.suppressed_fields` together describe what is missing.
+At `ready_to_create` the plain guide (no flags) is now the smallest response;
+reach for `--no-spend` when you want the suppression declared explicitly, and
+for `--explain` when you want everything.
+
 Manual escape hatches are not prerequisites. Use them only when
-`data.next_command` / `data.escape_hatches` asks, or when the task genuinely
+`data.next_command` / `data.escape_hatches` asks (`data.escape_hatches` is
+returned when the guide is blocked and under `--explain`), or when the task
+genuinely
 needs deeper capability, quota, payment, or planning detail:
 
 ```bash
@@ -1174,11 +1227,15 @@ luxin create --guide --prompt "A compact field camera on a stainless workbench"
 
 `create --guide` returns `schema: image-skill.create-guide.v1`,
 `stage`, `next_command`, `next_command_copy_runnable`,
-`next_command_missing_inputs`, `guide_warning`, `auth_ready`,
-`no_spend_evaluation`, `recommended_no_spend_command`,
-`self_fund_next_command`, `self_fund_handoff`, `self_fund_preparation`,
-`escape_hatches`, selected executable model and cost, auth/quota/payment
-blockers, and mutation flags. All
+`next_command_missing_inputs`, `guide_warning`, `next_command_effect`,
+`recommended_no_spend_command` (aliased by `no_spend_next_command`) and its
+effect, `output_mode`, selected executable model and cost, auth/quota/payment
+blockers, and mutation flags. When the guide is blocked, and at any stage under
+`--explain`, it also returns `auth_ready`, `auth_handoff`,
+`no_spend_evaluation`, `guide_recovery`, `escape_hatches`,
+`self_fund_next_command`, `self_fund_handoff`, and `self_fund_preparation`;
+`output_mode.omitted_fields` names whichever of those the current response left
+out, and `output_mode.full_output_command` is the rerun that returns them. All
 mutation flags must be false in guide mode: no provider call, hosted create,
 signup, payment object, credit debit, or media write.
 For next-command safety, read `next_command_copy_runnable`,
@@ -1193,12 +1250,16 @@ from several arrays. It is `browserless_agent_self_fund` when the preferred
 rail is live money, browserless, agent initiated, and agent settleable;
 `human_payment_handoff` when a human/browser completion step is required; and
 `payment_method_inspection` when the guide cannot classify a direct top-up path.
-In guide cost output, `cost.estimated_usd_per_image` is the estimated Image
-Skill debit in dollars for one output, matching
+In guide cost output, `cost.estimated_usd_per_image` is the estimated Luxin
+debit in dollars for one output, matching
 `cost.estimated_debit_usd_per_image` and
 `cost.estimated_credits * cost.credit_unit_usd` when credit pricing is known.
-`cost.estimated_provider_usd_per_image` is the upstream provider estimate for
-transparency; do not use it as the amount the agent needs to fund.
+That is the amount the agent needs to fund.
+`cost.cheaper_alternative` names one available model that costs strictly fewer
+credits than the selection and still satisfies the brief, with its
+`model_id` and `estimated_credits`; it is null when the selection is already
+the cheapest model that satisfies the brief. Pass its `model_id` to `--model`
+to take it.
 
 ```bash
 luxin create \
@@ -1209,9 +1270,15 @@ luxin create \
   --json
 ```
 
-Hosted defaults are quality-first. If an agent does not choose a model, Image
-Skill selects the strongest available create capability for the requested
-intent and budget, then records the decision in `request.selection`. Explicit
+Hosted defaults are intent-first. If an agent does not choose a model, Image
+Skill selects a create capability for the requested intent and budget, then
+records the decision in `request.selection`. `--intent draft` (or `cheap`,
+`budget`, `test`) selects the lowest-credit available model; `--intent final`
+(or `hero`, `product`, `campaign`, `deliverable`) selects the quality-first
+model; no intent, or `--intent explore`, selects a cost-efficient
+general-purpose model for iteration. A brief that states a reproducibility or
+aspect-ratio requirement still gets a model that can express it, even when a
+cheaper model cannot: capability outranks price. Explicit
 `--provider`, `--model`, namespaced model ids, and validated
 `model_parameters` always take precedence. For final/product/hero-style
 intents, Luxin may default an eligible quality-capability request to a
@@ -1384,7 +1451,28 @@ usage debits, media writes, or provider execution. In the first-run guide, this
 exact no-spend command behavior is exposed as
 `data.no_spend_next_command_effect` and
 `data.recommended_no_spend_command_effect`; the evaluator stop policy is exposed
-as `data.no_spend_evaluation`.
+as `data.no_spend_evaluation` when the guide is blocked or run with `--explain`.
+
+While the agent can still create, hosted `create` / `edit` responses no longer
+repeat the browserless top-up step tree. `data.next_actions.self_fund` keeps its
+recommendation, urgency, and command fields, but its `workflow` is replaced by
+`workflow_field: "quota.top_up.workflow"`, which points at the copy still
+carried in the same response. Once credits are exhausted and the agent is at the
+wall, `data.next_actions.self_fund.workflow` is inlined again, because that is
+the block the agent has to act on.
+
+Every hosted `create` / `edit` response carries `data.mutation`, so a no-spend
+evaluator reads the proof instead of inferring it from `dry_run` plus a
+`planned` asset. On a dry run it reports `provider_call: false`,
+`credit_debit: false`, and `media_write: false` explicitly, alongside
+`hosted_create_dry_run: true` and, for an authenticated dry run,
+`planned_job: true`, `plan_receipt: true`, and `activity_event: "job.planned"`
+for the recoverable receipt the dry run does write. An anonymous dry run stores
+nothing and reports `planned_job: false` with `activity_event: null`. Each entry
+in `data.assets` is labelled: a dry-run placeholder is
+`label: "planned_placeholder_not_media"` with `placeholder: true` and
+`downloadable: false`, and real output is `label: "durable_media"` with
+`downloadable: true`.
 
 Minimum success data:
 
@@ -1397,22 +1485,24 @@ Minimum success data:
   "assets": [
     {
       "asset_id": "image_...",
-      "path": "https://media.image-skill.com/a/image_abc123.png",
+      "path": "https://media.luxin.sh/a/image_abc123.png",
       "mime_type": "image/png",
-      "url": "https://media.image-skill.com/a/image_abc123.png",
+      "url": "https://media.luxin.sh/a/image_abc123.png",
       "content_length": 333444,
       "width": 2048,
       "height": 2048
     }
   ],
   "cost": {
-    "estimated_usd": 0.07,
+    "estimated_usd": 0.12,
     "credit_pricing": {
       "credit_unit_usd": 0.01,
       "credits_required": 12,
-      "estimated_provider_cost_usd": 0.07,
-      "estimated_revenue_usd": 0.12,
-      "pricing_confidence": "known"
+      "estimated_charge_usd": 0.12,
+      "self_fundable": true,
+      "self_fund_block_reason": null,
+      "pricing_confidence": "known",
+      "pricing_source": "model_parameters"
     }
   },
   "request": {
@@ -1420,7 +1510,7 @@ Minimum success data:
     "selection": {
       "policy": "hosted_default_create_v1",
       "reason": "hosted default selected the strongest currently available quality-first create model",
-      "intent": "explore",
+      "intent": "final",
       "capability": {
         "id": "is.image.generate.xai-grok-imagine-image-quality.v1"
       },
@@ -1508,7 +1598,9 @@ curl -sS https://api.luxin.sh/v1/create \
 
 Hosted free-preview create currently requires owned artifact storage and returns
 one `assets[]` entry per output with `assets[].url` under
-`https://media.image-skill.com/...` on success.
+`https://media.luxin.sh/...` on success. Previously issued
+`https://media.image-skill.com/...` URLs remain valid and are still accepted
+wherever an asset URL is an input.
 
 ### `luxin upload`
 
@@ -1537,7 +1629,7 @@ Minimum success data:
     "asset_id": "image_...",
     "job_id": "job_...",
     "kind": "uploaded",
-    "url": "https://media.image-skill.com/a/image_abc123.png",
+    "url": "https://media.luxin.sh/a/image_abc123.png",
     "mime_type": "image/png",
     "content_length": 12345
   },
@@ -1750,7 +1842,7 @@ Inspects an Luxin-owned asset URL or hosted asset id.
 
 ```bash
 luxin assets show \
-  https://media.image-skill.com/a/image_abc123.png \
+  https://media.luxin.sh/a/image_abc123.png \
   --json
 ```
 
@@ -1771,7 +1863,7 @@ Minimum success data:
   "asset": {
     "asset_id": "image_...",
     "job_id": "job_...",
-    "url": "https://media.image-skill.com/a/image_abc123.png",
+    "url": "https://media.luxin.sh/a/image_abc123.png",
     "mime_type": "image/png",
     "content_length": 12345,
     "width": 1024,
@@ -1799,7 +1891,7 @@ Downloads an Luxin-owned asset URL or hosted asset id to a local file.
 
 ```bash
 luxin assets get \
-  https://media.image-skill.com/a/image_abc123.png \
+  https://media.luxin.sh/a/image_abc123.png \
   --output ./result.png \
   --json
 ```
@@ -1837,16 +1929,14 @@ Minimum success data:
   "state": "completed",
   "assets": [],
   "cost": {
-    "estimated_usd": 0.05,
-    "provider_reported_usd_ticks": null
+    "estimated_usd": 0.05
   },
   "job": {
     "job_id": "job_...",
     "status": "completed",
     "assets": [],
     "cost": {
-      "estimated_usd": 0.05,
-      "provider_reported_usd_ticks": null
+      "estimated_usd": 0.05
     }
   }
 }

package/skills/luxin/references/commands.json

@@ -422,6 +422,7 @@
         "optional_flags": [
           "--guide",
           "--no-spend",
+          "--explain",
           "--dry-run",
           "--model",
           "--aspect-ratio",