luxin-cli 0.0.1 → 0.2.1

package/cli.md

@@ -0,0 +1,1985 @@
+# Luxin CLI Contract
+
+Status: preview hosted-product contract.
+
+The `luxin` thin CLI/client gives agents a stable way to call the hosted Luxin service, parse JSON responses, receive artifacts, and leave feedback.
+
+Public contract URLs:
+
+- `https://luxin.sh`
+- `https://luxin.sh/skill.md`
+- `https://luxin.sh/llms.txt`
+- `https://luxin.sh/cli.md`
+- `https://api.luxin.sh`
+
+## Global Rules
+
+- Every command that agents use must support `--json`.
+- JSON is the default public CLI output. `--json` is accepted for
+  compatibility and explicitness, but fresh agents do not need to add it to
+  every command.
+- JSON output must use the standard envelope from
+  `https://luxin.sh/llms.txt`.
+- Commands must have deterministic exit codes.
+- Commands must emit service telemetry unless running in a documented no-telemetry test mode.
+- Commands must not print secrets after initial creation.
+- File-writing commands must avoid overwriting inputs unless `--overwrite` is explicit.
+- Expensive commands must expose quota, claim, cost, and budget guard failures clearly.
+- Public feedback commands submit to hosted product memory by default.
+
+## Exit Codes
+
+| Code | Meaning                                |
+| ---- | -------------------------------------- |
+| 0    | Success                                |
+| 1    | Generic failure                        |
+| 2    | Invalid arguments                      |
+| 3    | Auth required or invalid token         |
+| 4    | Capability denied                      |
+| 5    | Quota exceeded                         |
+| 6    | Content policy denied                  |
+| 7    | Provider failure                       |
+| 8    | Timeout                                |
+| 9    | Filesystem or artifact storage failure |
+
+## Commands
+
+### `luxin doctor`
+
+Checks thin CLI/client health, hosted service reachability, auth state, local output permissions, and telemetry status.
+
+```bash
+luxin doctor --json
+```
+
+`doctor` also reports `data.in_flight`, the local live-spend recovery
+breadcrumbs under the public CLI config directory. Outstanding entries include
+the original operation, idempotency key, age/TTL state, sweep eligibility, and a
+copy-runnable `recover_command`. Re-run the recovery command first when the
+original create/edit result still matters. Treat those idempotency keys and
+recovery commands as agent-internal operational data during normal progress
+updates; surface them to a human only when recovery needs a decision, handoff,
+or requested diagnostic detail.
+
+Use `luxin doctor --sweep-in-flight --json` to remove only
+sweep-eligible stale breadcrumbs after the long grace window. Plain `doctor`
+never deletes recovery breadcrumbs.
+
+### `luxin trust`
+
+Returns a no-auth, no-spend evidence packet for tool selection and package
+provenance checks.
+
+```bash
+luxin trust --json
+```
+
+The packet uses `schema: "image-skill.trust-packet.v0"` and reports the public
+CLI version, npm metadata status, public repo mapping when inferable, hosted
+contract document hashes, hosted `/healthz`, `/v1/models` availability, safe
+copyable commands, proof URL placeholders, and redaction guarantees.
+
+Use `trust` when deciding whether Luxin is current and honest enough to
+select. It is not a required setup step before the first image; the canonical
+fresh-agent creative entrypoint remains `luxin create --guide`.
+Agents may also use modality-first aliases when that is the natural wording:
+`luxin image create --guide`, `luxin video create --guide`,
+`luxin audio create --guide`, and `luxin 3d create --guide` all
+route into the same `create --guide` flow, with video/audio/3D intent hints
+added only when the agent did not already provide `--intent`.
+
+If package metadata, hosted docs, API health, or model availability cannot be
+verified, the command still returns a packet with explicit `unreachable`,
+`not_available_yet`, `inspect_only`, or `stale_or_mismatched` states rather
+than omitting the field.
+
+### `luxin signup --agent`
+
+Bootstraps restricted agent access. Signup is anonymous by default: no contact
+inbox is required to get a restricted token.
+
+```bash
+luxin signup --agent \
+  --agent-name creative-agent \
+  --runtime codex \
+  --discovery-source cli-md \
+  --json
+```
+
+Hosted signup saves the restricted `isk_r_` token to the public CLI config by
+default with `0600` permissions, so later hosted commands can authenticate from
+config without repeating signup or carrying a raw token through prompts. Set
+`LUXIN_CONFIG_PATH` first when the default config home may be read-only.
+Successful default signup reports `data.auth_handoff.status` as
+`saved_config_ready`, keeps `data.token` null, and should not require any
+token-copy step.
+The raw token is returned only when `--show-token` is set, and only once. Use
+`--show-token --no-save` when the agent runtime has a separate secret store and
+does not want local config. Do not paste tokens into prompts, logs, issue text,
+or feedback.
+
+`--agent-contact` is an email-shaped durable contact inbox and it is optional
+at signup: provide it when a durable inbox already exists, or attach one later
+with `luxin claim request --contact INBOX --json` when funding or
+durability makes it worth having. Use an agent-owned inbox when available;
+otherwise use an operator, team, or sponsor inbox that can receive future
+claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated
+human email just to fill the flag — omit it instead.
+`example.invalid` addresses are only appropriate inside documented harness or
+proof runs. `--human-email` remains accepted as a compatibility alias for
+`--agent-contact`.
+
+Anonymous signups mint a fresh agent identity on every call, so re-running
+signup without a contact creates a new agent instead of returning the existing
+one; rely on the saved config to reuse the identity you already have.
+
+`--discovery-source SLUG` (or the `IMAGE_SKILL_DISCOVERY_SOURCE` environment
+variable; the flag wins) optionally records where you discovered Luxin —
+a short channel slug such as `clawhub`, `skills-sh`, or `npm` (lowercase
+letters/digits plus `.`/`_`/`-`, max 64 chars). Keep `cli-md` when this
+command reference brought you here. It is self-reported, first-touch (a later
+re-signup never relabels it), and never required: omit it when you do not know
+the channel rather than guessing.
+
+### `luxin claim request`
+
+Attaches an email-shaped durable contact inbox to the authenticated agent —
+the on-demand identity upgrade after an anonymous signup. Use it when funding
+or durability makes a reachable contact worth having (billing, abuse, and
+recovery notices).
+
+```bash
+luxin claim request \
+  --contact agent-inbox@example.com \
+  --json
+```
+
+Re-running with the same contact is idempotent (`data.state` is `unchanged`);
+a different contact replaces the previous one (`data.state` is `attached`).
+Attaching a contact is not inbox-ownership verification: `data.claim_state`
+stays `unclaimed` and `data.claim_request_state` reports `requested`. The
+response echoes only a redacted form of the contact.
+
+If the runtime has a separate secret store, it may provide the token to commands
+as `IMAGE_SKILL_TOKEN`. Keep that value outside prompts, logs, issue text, and
+feedback. Saved config, `IMAGE_SKILL_TOKEN`, and `--token-stdin` are all
+accepted by hosted commands; config is the default fresh-agent path.
+
+If the agent runtime can hand secrets to a command over stdin, avoid exporting
+the token and use `--token-stdin` instead:
+
+```bash
+printf '%s\n' "$IMAGE_SKILL_TOKEN" | luxin usage quota --token-stdin --json
+```
+
+`--api-base-url` is an advanced preview/test override; production public agents
+should omit it.
+
+### First Run Guide Loop
+
+Use the no-spend guide first. It is the only required first command for a fresh
+agent. It checks health, executable model availability, auth/quota when a token
+already exists, and payment rails, then returns one primary
+`data.next_command` plus machine-readable `data.next_command_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.
+
+```bash
+IMAGE_SKILL_DISCOVERY_SOURCE=cli-md luxin create --guide --prompt "a compact field camera on a stainless workbench"
+```
+
+Read `data.stage` and `data.guide_warning`, run `data.next_command` only when
+`data.next_command_copy_runnable` is `true` and
+`data.guide_warning.next_command_safety` is safe for the current spend policy.
+When `data.next_command_copy_runnable` is `false`, fill
+`data.next_command_missing_inputs` first. Rerun the guide only after auth or
+payment state changes. Do not run
+`doctor`, `models list`, `signup`, `whoami`, `usage quota`, `create --dry-run`,
+or payment commands as a setup checklist before the guide asks for them.
+For no-doc recovery loops, prefer `data.guide_recovery`: 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
+live command field that would spend if rerun (`live_create_command_field` or
+`live_payment_command_field`). When `data.guide_recovery.double_spend_guard.required`
+is `true`, do not rerun that live field after a partial or unknown failure
+until `error.recovery`, `jobs`, `activity`, or payment status proves the next
+step.
+
+- `prompt_required`: fill `data.next_command_missing_inputs` with the real
+  prompt, then rerun `data.next_command`.
+- `auth_required`: fill `data.next_command_missing_inputs` when present, run
+  `data.next_command`, then rerun guide once. Hosted signup saves auth to
+  config by default. If the runtime intentionally used
+  `--no-save --show-token`, store the returned token and use
+  `data.auth_handoff.rerun_guide.with_env` or
+  `data.auth_handoff.rerun_guide.with_stdin`. In this stage,
+  `data.auth_ready.ready` is `false`, and
+  `data.guide_warning.next_command_safety` is
+  `hosted_signup_no_spend_setup`.
+- `quota_required`: fill `data.next_command_missing_inputs` when present, then
+  run `data.self_fund_next_command` to start the top-up.
+  It aliases `data.next_command` and is the first payment command, usually an
+  x402 or Stripe quote. First inspect
+  `data.self_fund_handoff.urgency`, `urgency_score`, and `urgency_reasons`; run
+  `data.self_fund_handoff.first_safe_command` for no-spend payment-method
+  inspection when you need rail state before opening a quote. If the guide
+  authenticated from env or stdin, prefer
+  `data.self_fund_handoff.auth.next_command.with_env` or
+  `data.self_fund_handoff.auth.next_command.with_stdin` so auth follows the
+  payment command. Then follow `data.self_fund_handoff.payment_commands.buy`
+  and `status`, and rerun `data.self_fund_handoff.after_next` once credits are
+  granted. If `data.self_fund_handoff.wallet_settlement` is non-null, pay the
+  exact amount in the returned `payable_instructions` field from a delegated
+  wallet before polling status; the handoff names the response fields and the
+  credential boundary. `data.guide_warning.next_command_safety` is
+  `live_money_payment_action`, and
+  `data.guide_warning.payment_top_up_path` summarizes the same path as
+  `data.checks.payments.preferred_method_summary.top_up_path`. Read that path
+  before the quote: `browserless_agent_self_fund` means a wallet-equipped agent
+  can complete the preferred live-money rail without a browser;
+  `human_payment_handoff` means the agent can create the payment attempt but a
+  human/browser step must complete before credits are granted.
+- any stage: inspect `data.checks.quota.top_up`; when `recommended` is `true`,
+  it includes the recommendation reason, preferred browserless x402 method, and
+  `quote_command` plus copy-runnable quote/buy/status command templates from
+  `usage quota`. On quota/payment recovery errors, the same browserless
+  handoff is exposed at `error.recovery.top_up.quote_command`, and
+  `error.recovery.suggested_command` points at that direct quote when delegated
+  live-money quoting is allowed. Use `error.recovery.top_up.first_command` for
+  no-spend payment-method inspection when delegated spend authority is absent or
+  unclear.
+- `ready_to_create`: `data.next_command` is a live media create. Its
+  `data.self_fund_preparation` is the pre-wall top-up affordance; 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 without paying, settling a
+  wallet transfer, debiting credits, calling a provider, or writing media.
+  When that recommended quote is copy-runnable, `data.self_fund_next_command`
+  aliases it and `data.self_fund_next_command_label` uses a `pre_wall_...`
+  label such as `pre_wall_browserless_agent_payable_quote`, so agents can open
+  the top-up quote path before consuming their remaining free allowance. Only
+  follow later buy/status/wallet-settlement commands when delegated spend is
+  allowed. `data.next_command_effect.label` is
+  `live_media_create_credit_debit`, with
+  `provider_call`, `hosted_create`, `credit_debit`, and `media_write` all true.
+  `data.guide_warning.next_command_safety` is
+  `live_media_create_credit_debit`, `data.guide_warning.no_spend_safe` is
+  `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
+  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
+  `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
+  `data.auth_handoff.next_command.with_env` or
+  `data.auth_handoff.next_command.with_stdin` so auth follows the create.
+
+Manual escape hatches are not prerequisites. Use them only when
+`data.next_command` / `data.escape_hatches` asks, or when the task genuinely
+needs deeper capability, quota, payment, or planning detail:
+
+```bash
+luxin trust
+luxin doctor
+luxin models list
+luxin models show openai.gpt-image-2
+luxin whoami
+luxin usage quota
+luxin create --dry-run --prompt "a compact field camera on a stainless workbench"
+```
+
+Use `--show-token --no-save` for hosted signup only when the runtime can
+immediately store the raw token once outside local config. For later commands,
+saved config is the default; `IMAGE_SKILL_TOKEN` and `--token-stdin` remain
+available for runtimes with a separate secret store.
+`create --guide` also returns `data.auth_handoff` with copy-safe env/stdin
+templates when auth is required or when the returned create command needs the
+same auth context.
+
+### Local Config And Install
+
+Prefer package execution in fresh agent sandboxes:
+
+```bash
+npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
+```
+
+Global install is optional, not the primary path. If `npm install -g luxin-cli`
+or `npx luxin-cli@latest ...` hits prefix/cache `EACCES`, retry with writable
+package-manager paths instead of cloning private source:
+
+```bash
+export npm_config_cache="${npm_config_cache:-$PWD/.npm-cache}"
+export npm_config_prefix="${npm_config_prefix:-$PWD/.npm-global}"
+export PATH="$npm_config_prefix/bin:$PATH"
+npm_config_update_notifier=false npx -y luxin-cli@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
+```
+
+For `npx skills add ... -g -a codex` installs, the writable target is Codex
+agent home rather than the npm prefix. If the Codex/global skill target is
+read-only or cannot create its default directory, keep the tracked slug install
+and point agent skill state at a writable workspace home. 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 luxin -g -a codex -y
+```
+
+Hosted signup saves auth state to the public CLI config by default. If the
+runtime needs a writable compatibility config path, set
+`LUXIN_CONFIG_PATH` before `signup`:
+
+```bash
+export LUXIN_CONFIG_PATH="$PWD/.luxin/config.json"
+# legacy name IMAGE_SKILL_CONFIG_PATH remains honored
+npm_config_update_notifier=false npx -y luxin-cli@latest signup --agent \
+  --agent-name creative-agent \
+  --runtime codex \
+  --json
+```
+
+Config write failures return `PUBLIC_CLI_CONFIG_WRITE_FAILED` with a structured
+`error.recovery.suggested_command`. Agents should follow that recovery field,
+then rerun `create --guide` for the requested creative flow.
+When `create --guide` reaches `auth_required`, it probes the configured auth
+path first. If local config cannot be written, `data.next_command` prefixes the
+normal saved-config signup with
+`LUXIN_CONFIG_PATH="$PWD/.luxin/config.json"`, so the first recovery
+step still saves auth locally without exposing the one-time token.
+`--show-token --no-save` and `data.auth_handoff.rerun_guide.with_stdin` remain
+structured fallback paths for runtimes that intentionally use a separate secret
+store.
+
+### `luxin whoami`
+
+Shows current actor, organization, claim state, token class, and grants.
+The JSON includes `session_origin` so a fresh agent can tell whether it is
+unauthenticated, loaded a saved config, created the token in this process, or
+is using hosted-session auth. `token_created_at` is the active token creation
+timestamp when Luxin can prove it, otherwise `null`.
+
+```bash
+luxin whoami --json
+```
+
+Minimum success data:
+
+```json
+{
+  "authenticated": true,
+  "session_origin": "loaded_from_config",
+  "token_status": "active",
+  "token_created_at": "2026-05-08T12:00:00.000Z"
+}
+```
+
+### `luxin usage quota`
+
+Canonical pre-spend check. Shows remaining credits, job limits, model limits,
+and reset windows before create/edit.
+
+The starter preview has 50 lifetime credits and a 50-job UTC-day compatibility
+cap. Funded identities have no daily job cap: their available prepaid credits
+and atomic credit reservations are the spend boundary. For funded identities,
+the optional `daily_jobs` object is omitted from the quota response.
+
+```bash
+luxin usage quota --json
+```
+
+`luxin quota --json` remains a compatibility alias.
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/quota \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN"
+```
+
+### `luxin credits methods`
+
+Machine-readable payment rail discovery. Use this before quoting or buying so
+agents can tell which rails are available, whether live money can move, whether
+browser/human action is required, and which command to try next.
+
+```bash
+luxin credits methods --json
+```
+
+Minimum success data shape:
+
+```json
+{
+  "contract_version": "image-skill.payment-methods.v1",
+  "credit_unit_cents": 1,
+  "currency": "USD",
+  "quote_endpoint": "/v1/credit-quotes",
+  "packs_endpoint": "/v1/credit-packs",
+  "status_endpoint": "/v1/credit-purchases/status",
+  "next_actions": {
+    "recommended_quote": {
+      "purpose": "quote_credit_top_up",
+      "recommendation_reason": "browserless_agent_self_fund",
+      "method_id": "stripe_x402.exact.usdc",
+      "pack_id": "starter-500",
+      "command": "luxin credits quote --pack starter-500 --payment-method stripe_x402.exact.usdc --json",
+      "quote_command_copy_runnable": true,
+      "buy_command": "luxin credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+      "status_command": "luxin credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      "requires_auth": true,
+      "live_money": true,
+      "requires_browser": false,
+      "agent_settleable": true,
+      "command_effect": {
+        "label": "live_money_quote_no_charge",
+        "no_spend": true,
+        "payment_object": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
+  "methods": [
+    {
+      "method_id": "stripe_checkout",
+      "status": "available",
+      "available": true,
+      "quoteable": true,
+      "purchasable": true,
+      "live_money": true,
+      "buyer_modes": ["hybrid", "human_only"],
+      "requires_browser": true,
+      "agent_initiated": true,
+      "agent_settleable": false,
+      "settlement_blocker": "requires human browser checkout completion",
+      "default_pack_id": "starter-500",
+      "purchase_endpoint": "/v1/credit-purchases/stripe-checkout-sessions"
+    },
+    {
+      "method_id": "stripe_x402.exact.usdc",
+      "status": "available",
+      "available": true,
+      "quoteable": true,
+      "purchasable": true,
+      "live_money": true,
+      "buyer_modes": ["agent_only", "hybrid"],
+      "requires_browser": false,
+      "agent_initiated": true,
+      "agent_settleable": true,
+      "settlement_blocker": null,
+      "default_pack_id": "starter-500",
+      "purchase_endpoint": "/v1/credit-purchases/stripe-x402-deposits"
+    }
+  ]
+}
+```
+
+Public payment discovery is intentionally action-first. Limited-rollout rails
+may be returned with `available:false`, `quoteable:false`, `purchasable:false`,
+and a non-null `unavailable_reason` so headless agents can understand the path
+without trying it. Use a method only when it is returned with `available:true`,
+`quoteable:true`, and `purchasable:true`. When
+`next_actions.recommended_quote` is present, prefer its `command` as the next
+authenticated quote step; it creates a live-money payment object but does not
+move money, grant credits, debit credits, call a provider, or write media.
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/payment-methods
+```
+
+### `luxin credits packs list`
+
+Lists the recommended Luxin credit packs. Packs are the default
+live-money buying UX because agents get obvious starter choices and avoid tiny
+fee traps. Use the payment method catalog to choose the rail:
+`stripe_checkout` when a human sponsor can complete Checkout, or
+`stripe_x402.exact.usdc` when a wallet-equipped agent can settle a browserless
+live crypto deposit attempt from returned pay-to instructions.
+Exact custom quotes are still supported when an agent already knows the
+required credit budget.
+
+```bash
+luxin credits packs list --json
+```
+
+Minimum success data:
+
+```json
+{
+  "credit_unit_cents": 1,
+  "credit_unit_usd": 0.01,
+  "currency": "USD",
+  "default_pack_id": "starter-500",
+  "packs": [
+    {
+      "pack_id": "starter-500",
+      "name": "Starter",
+      "display_name": "Starter (500 credits)",
+      "credits": 500,
+      "amount_cents": 500,
+      "amount_usd": "5.00",
+      "price_usd": "5.00",
+      "currency": "USD"
+    }
+  ],
+  "custom_quotes": {
+    "supported": true,
+    "min_credits": 1,
+    "max_credits": 5000
+  }
+}
+```
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/credit-packs
+```
+
+### `luxin credits quote`
+
+Requests a bounded credit quote from the hosted service. Public top-ups use the
+payment method returned by `credits methods --json`: `stripe_checkout` for the
+human Checkout path, or `stripe_x402.exact.usdc` for a browserless
+action-required deposit attempt. A quote never grants credits.
+One Luxin credit is a stable user-facing value unit worth `$0.01`.
+Creative operations can consume more than one credit based on the selected
+model's provider cost and Luxin's margin policy; inspect
+`models show MODEL_ID --json` and operation `cost.credit_pricing` for the exact
+debit before spending.
+
+```bash
+luxin credits quote --credits 10 --payment-method stripe_x402.exact.usdc --json
+```
+
+Always pass the payment method from `credits methods --json`; the public CLI
+does not infer one. For retry-stable automation, provide an explicit non-secret
+idempotency key:
+
+```bash
+luxin credits quote \
+  --credits 10 \
+  --payment-method stripe_x402.exact.usdc \
+  --idempotency-key quote-run-001 \
+  --json
+```
+
+Idempotency keys are scoped to the current hosted agent identity and exact
+quote request. Reusing a key with different credits, pack, or payment method
+returns a structured `error.recovery.suggested_command` with a fresh
+idempotency key for the attempted quote terms.
+
+For Stripe Checkout terms, prefer a named pack:
+
+```bash
+luxin credits quote \
+  --pack starter-500 \
+  --payment-method stripe_checkout \
+  --idempotency-key stripe-pack-quote-run-001 \
+  --json
+```
+
+For the browserless agent x402 rail, quote the exact method id returned by
+`credits methods --json`:
+
+```bash
+luxin credits quote \
+  --pack starter-500 \
+  --payment-method stripe_x402.exact.usdc \
+  --idempotency-key agent-x402-quote-run-001 \
+  --json
+```
+
+For exact custom terms, keep the same rail choice. Use
+`stripe_x402.exact.usdc` for an agent-settleable browserless rail, or use
+`stripe_checkout` only for a human Checkout fallback:
+
+```bash
+luxin credits quote \
+  --credits 137 \
+  --payment-method stripe_checkout \
+  --idempotency-key exact-quote-run-001 \
+  --json
+```
+
+Minimum success data:
+
+```json
+{
+  "quote_id": "quote_...",
+  "state": "created",
+  "credits": 10,
+  "price_amount_cents": 10,
+  "currency": "USD",
+  "expires_at": "2026-05-08T20:00:00.000Z",
+  "accepted_payment_method": "stripe_checkout",
+  "idempotency_key": "quote-run-001",
+  "pack_id": null,
+  "pack": null,
+  "live_money": true,
+  "next_actions": {
+    "recommended_buy": {
+      "purpose": "complete_credit_top_up",
+      "recommendation_reason": "human_checkout_handoff",
+      "quote_id": "quote_...",
+      "method_id": "stripe_checkout",
+      "provider": "stripe",
+      "command": "luxin credits buy --provider stripe --quote-id quote_... --idempotency-key purchase:quote_... --json",
+      "buy_command_copy_runnable": true,
+      "purchase_idempotency_key": "purchase:quote_...",
+      "status_command": "luxin credits status --quote-id quote_... --json",
+      "status_command_copy_runnable": true,
+      "status_command_after_payment": "luxin credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      "status_command_after_payment_copy_runnable": false,
+      "requires_auth": true,
+      "live_money": true,
+      "requires_browser": true,
+      "agent_settleable": false,
+      "human_handoff_required": true,
+      "command_effect": {
+        "label": "live_money_payment_attempt_requires_completion",
+        "no_spend": false,
+        "payment_attempt": true,
+        "credit_debit": false,
+        "media_write": false,
+        "wallet_settlement": false
+      }
+    }
+  }
+}
+```
+
+For x402 quotes, `accepted_payment_method` is
+`"stripe_x402.exact.usdc"`. The quote does not grant credits or include pay-to
+instructions; `data.next_actions.recommended_buy.command` carries the returned
+`quote_id` and a stable non-secret purchase idempotency key for the
+action-required deposit attempt. Run it only when delegated spend is allowed.
+Use `data.next_actions.recommended_buy.status_command` to inspect the quote or
+payment state by `quote_id`; after buy returns a `payment_attempt_id`, prefer
+`status_command_after_payment`.
+
+When `credits status --quote-id quote_... --json` sees an open
+`stripe_x402.exact.usdc` or `stripe_checkout` quote, it repeats the exact
+`data.next_actions.recommended_buy` command with the real `quote_id` and
+`purchase:quote_...` idempotency key so agents do not need to reconstruct the
+buy step from placeholders.
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/credit-quotes \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"pack_id":"starter-500","payment_method":"stripe_x402.exact.usdc","idempotency_key":"agent-x402-quote-run-001"}'
+```
+
+### `luxin credits buy`
+
+Creates a payment action for a previously returned quote. Choose the provider
+that matches the quote's `accepted_payment_method`.
+
+For a `stripe_x402.exact.usdc` quote, `--provider stripe_x402` creates a
+browserless action-required USDC deposit attempt. When the response includes
+`stripe_x402.payable_instructions`, a wallet-equipped agent may pay the exact
+USDC amount to `deposit_address` on Base without using a browser. The response
+is live money when `live_money:true`. Credits are granted only after verified
+settlement and webhook fulfillment succeeds. Deposit challenge creation itself
+must not mutate credit balances. Stay within the delegated cap and never pass
+wallet private keys, seed phrases, x402 payment headers, deposit client
+secrets, card data, Stripe secrets, or provider receipts to Luxin.
+When `create --guide` enters `quota_required` for this rail, it returns
+`data.self_fund_handoff.wallet_settlement` with the buy/status response fields
+to inspect, plus `data.self_fund_handoff.first_safe_command` for no-spend rail
+inspection before quote/buy: `data.stripe_x402.payable_instructions` after
+`credits buy`, or
+`data.payment_attempt.stripe_x402.payable_instructions` after `credits status`.
+
+```bash
+luxin credits buy \
+  --provider stripe_x402 \
+  --quote-id quote_... \
+  --idempotency-key agent-x402-buy-run-001 \
+  --json
+```
+
+Minimum x402 action-required data:
+
+```json
+{
+  "state": "action_required",
+  "quote_id": "quote_...",
+  "payment_attempt_id": "payatt_...",
+  "provider": "stripe",
+  "accepted_payment_method": "stripe_x402.exact.usdc",
+  "credits": 500,
+  "amount_cents": 500,
+  "currency": "USD",
+  "live_money": true,
+  "stripe_x402": {
+    "method_id": "stripe_x402.exact.usdc",
+    "scheme": "exact",
+    "network": "base",
+    "token_currency": "usdc",
+    "deposit_address_present": true,
+    "payable_instructions": {
+      "kind": "stripe_crypto_deposit",
+      "network": "base",
+      "token_currency": "usdc",
+      "token_decimals": 6,
+      "token_amount": "5.00",
+      "token_amount_atomic": "5000000",
+      "amount_cents": 500,
+      "amount_usd": "5.00",
+      "deposit_address": "0x...",
+      "token_contract_address": "0x...",
+      "supported_token_currencies": ["usdc"],
+      "expires_at": "2026-05-08T20:00:00.000Z",
+      "exact_amount_required": true
+    },
+    "redacted": {
+      "payment_intent_id": "[redacted-stripe-payment-intent]",
+      "deposit_address": "[redacted-stripe-crypto-deposit-address]",
+      "client_secret": "[redacted-stripe-client-secret]"
+    }
+  },
+  "next_actions": {
+    "recommended_settlement": {
+      "purpose": "settle_stripe_x402_credit_top_up",
+      "quote_id": "quote_...",
+      "payment_attempt_id": "payatt_...",
+      "method_id": "stripe_x402.exact.usdc",
+      "payable_instructions_path": "data.stripe_x402.payable_instructions",
+      "status_command": "luxin credits status --payment-attempt-id payatt_... --json",
+      "quota_command": "luxin usage quota --json",
+      "command_effect": {
+        "wallet_settlement": true,
+        "credit_debit": false,
+        "media_write": false
+      }
+    }
+  },
+  "next": {
+    "agent_action": "pay_stripe_crypto_deposit",
+    "suggested_commands": [
+      "luxin credits status --payment-attempt-id payatt_... --json"
+    ]
+  }
+}
+```
+
+For a `stripe_checkout` quote, `--provider stripe` creates a hosted Stripe
+Checkout Session and returns an `action_required` response with
+`checkout_handoff_url`.
+
+Agents should present or open `checkout_handoff_url` for humans. It is a short
+Luxin URL that redirects to Stripe Checkout and is safe to copy from
+mobile terminals, SSH clients, and wrapped chat output. `checkout_compact_url`
+is also copy-safe and equals the Luxin handoff when the hosted API can
+provide one. `checkout_url` is the raw Stripe compatibility fallback only; do
+not present it unless no handoff URL is available. Do not trim Stripe Checkout
+URLs: the long `#...` fragment is required by Stripe Checkout in the browser.
+Present any fallback Stripe URL in a fenced code block so terminal wrapping does
+not corrupt it. Stripe-hosted Checkout may also show a promotion-code field for
+operator-provided codes; agents should let the human enter those codes on
+Stripe, never collect promo codes, card details, or wallet credentials in the
+Luxin CLI.
+
+```bash
+luxin credits buy \
+  --provider stripe \
+  --quote-id quote_... \
+  --idempotency-key stripe-buy-run-001 \
+  --json
+```
+
+Minimum success data:
+
+```json
+{
+  "state": "action_required",
+  "quote_id": "quote_...",
+  "payment_attempt_id": "payatt_...",
+  "provider": "stripe",
+  "accepted_payment_method": "stripe_checkout",
+  "checkout_session_id": "cs_...",
+  "checkout_handoff_url": "https://api.luxin.sh/pay/payatt_...",
+  "checkout_compact_url": "https://api.luxin.sh/pay/payatt_...",
+  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...#fid...",
+  "credits": 500,
+  "amount_cents": 500,
+  "currency": "USD",
+  "live_money": true,
+  "next": {
+    "human_action": "open_checkout_url",
+    "checkout_handoff_url": "https://api.luxin.sh/pay/payatt_...",
+    "checkout_compact_url": "https://api.luxin.sh/pay/payatt_...",
+    "fallback_checkout_url": "https://checkout.stripe.com/c/pay/cs_...#fid...",
+    "after_payment": "open checkout_handoff_url or checkout_compact_url; use the full checkout_url only if no Luxin handoff URL is available, and preserve its Stripe # fragment. Then poll luxin credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json or luxin usage quota --json; credits are granted only after verified webhook fulfillment"
+  }
+}
+```
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/credit-purchases/stripe-checkout-sessions \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"quote_id":"quote_...","idempotency_key":"stripe-buy-run-001"}'
+```
+
+x402 hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/credit-purchases/stripe-x402-deposits \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"quote_id":"quote_...","idempotency_key":"agent-x402-buy-run-001"}'
+```
+
+### `luxin credits status`
+
+Without a payment reference, shows the current credit balance using the same
+quota data as `luxin usage quota --json`. With a payment reference,
+shows the durable state of a quote, x402 deposit attempt, Stripe Checkout
+attempt, Checkout Session, or receipt. Use the referenced form after
+`credits buy` so agents do not have to infer payment state from quota deltas
+or activity text.
+
+```bash
+luxin credits status --json
+luxin credits status \
+  --payment-attempt-id payatt_... \
+  --json
+```
+
+At most one reference flag is allowed: `--quote-id`,
+`--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`. Passing no
+reference returns the balance/quota state.
+
+For Stripe x402 attempts that are still `action_required`, status responses
+include `data.next_actions.recommended_settlement` with the same exact Base/USDC
+payable instructions, a copy-runnable status command for the real
+`payment_attempt_id`, and explicit effect flags showing this is wallet
+settlement, not credit debit, media write, or provider generation work.
+
+Minimum action-required data:
+
+```json
+{
+  "state": "action_required",
+  "quote": {
+    "quote_id": "quote_...",
+    "credits": 500,
+    "price_amount_cents": 500,
+    "accepted_payment_method": "stripe_checkout",
+    "pack_id": "starter-500",
+    "x402": null
+  },
+  "payment_attempt": {
+    "payment_attempt_id": "payatt_...",
+    "checkout_session_id": "cs_...",
+    "checkout_handoff_url": "https://api.luxin.sh/pay/payatt_...",
+    "checkout_compact_url": "https://api.luxin.sh/pay/payatt_...",
+    "checkout_url": "https://checkout.stripe.com/c/pay/cs_...#fid...",
+    "attempt_status": "requires_action"
+  },
+  "receipt": null,
+  "credit_event": null,
+  "next": {
+    "retry_after_seconds": 10,
+    "human_action": "open_checkout_url",
+    "checkout_handoff_url": "https://api.luxin.sh/pay/payatt_...",
+    "checkout_compact_url": "https://api.luxin.sh/pay/payatt_..."
+  }
+}
+```
+
+Minimum success data includes `state: "succeeded"`, `receipt`,
+`credit_event`, and the updated hosted `limits`.
+
+Hosted API equivalent:
+
+```bash
+curl -sS "https://api.luxin.sh/v1/credit-purchases/status?payment_attempt_id=payatt_..." \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN"
+```
+
+Do not pass card data, wallet secrets, provider receipts, Stripe secrets, MPP
+tokens, SPTs, live x402 payment headers, deposit client secrets, wallet
+private keys, seed phrases, or any payment credential to credits commands.
+Stripe Checkout collects payment details only on Stripe-hosted pages; x402
+settlement is handled by the agent/wallet against the returned redacted deposit
+challenge, not by pasting credentials into Luxin. The public request
+fields are `credits`, `pack_id`, `payment_method`, `quote_id`, status reference
+IDs, and `idempotency_key`.
+
+### `luxin models`
+
+First-run creative discovery. Lists public models and shows the full
+capability-preserving schema for one model.
+
+```bash
+luxin models --json
+luxin models list --json
+luxin models list --details --json
+luxin models list --available --operation image.generate --json
+luxin models list --available --operation image.edit --json
+luxin models list --available --modality video --operation video.generate --json
+luxin models list --query nano-banana --json
+luxin models list --catalog-only --provider fal --json
+luxin models show MODEL_ID --json
+luxin models show nano-banana --json
+luxin models show default --json
+```
+
+Hosted API equivalents:
+
+```bash
+curl -sS https://api.luxin.sh/v1/models
+curl -sS 'https://api.luxin.sh/v1/models?available=true&modality=video&operation=video.generate'
+curl -sS 'https://api.luxin.sh/v1/models?query=nano-banana'
+curl -sS https://api.luxin.sh/v1/models/xai.grok-imagine-image
+```
+
+`models show` exposes operation support, media input/output types, parameter
+schemas, defaults and fixed controls, cost and latency class, safety behavior,
+and migration hints. Agents should inspect it before assuming a model supports
+seeds, masks, reference images, transparent backgrounds, arbitrary aspect
+ratios, image-size presets, output counts, resolution controls, safety
+controls, or provider-native options.
+
+`models list` is executable-first by default and returns one
+`default: true` row when the default executable create model is included.
+`models show default --json` resolves to that model so first-run agents can
+inspect the recommended create surface without knowing a provider-specific
+model id. `models show` also resolves common migration aliases such as
+`nano-banana` to `fal.nano-banana-2`, while `models list --query QUERY --json`
+returns fuzzy provider/model-family matches before an agent commits to one
+model id. The list response also returns `summary` with total, returned,
+available, executable, catalog-only, provider split,
+`execution_availability`, first actionable model ids, recommended filter
+commands, alias hints, provider/category discovery groups, and
+catalog-inclusion flags. Default list output is a compact, sortable model menu
+and excludes catalog-only rows so fresh agents see executable candidates first.
+Each row keeps the model id, flat
+`estimated_usd_per_image`, `credits_required`, lightweight `task_tags`, status,
+provider, max output count/resolution, storage, and `show_command`, while
+omitting full parameter schemas. Use `models show MODEL_ID --json` for one
+model's full capability schema, or `models list --details --json` only when you
+intentionally need the full list with capability schemas for compatibility or
+offline analysis. `--summary` is still accepted as a compatibility alias for the
+default compact list. Use `--available` for currently usable executable rows,
+`--modality image|video|audio|3d` for media type, `--operation
+image.generate`, `--operation image.edit`, `--operation video.generate`,
+`--operation audio.generate`, or `--operation 3d.generate` for the task,
+`--provider fal|xai|openai` to narrow by provider, `--query QUERY` to search
+ids, display names, provider namespaces, operations, tags, intents, upstream
+Fal endpoint ids, and known aliases, and `--catalog-only` when you intentionally
+want source-backed rows that are inspectable but not runnable yet.
+Provider-level availability is not the same thing as model executability; for
+runnable choices require both `status:"available"` and
+`execution.model_execution_status:"executable"`. If a reachable provider has no
+runnable model for the requested operation, `summary.execution_availability`
+says so directly and includes the fastest `--available --operation ...`
+recovery command.
+
+Luxin standardizes common controls so agents can work quickly, but it
+must not flatten rich model capabilities into coarse universal categories.
+Use `model_parameters` for rare or model-specific parameters advertised by the
+capability schema.
+
+Current executable provider-native controls include:
+
+- Fal FLUX.1 dev: `model_parameters.image_size` for presets such as
+  `square_hd`, plus `seed`.
+- Fal FLUX Pro 1.1 Ultra Create: `model_parameters.seed` and
+  `model_parameters.raw`; optional reference-image controls remain cataloged
+  for inspection but are not executable on the create-only path.
+- Fal Z-Image Turbo Create/Edit: `model_parameters.image_size` for
+  `square_hd`, `square`, portrait/landscape presets, and `auto` on edit; costs
+  are quoted from requested megapixels when the output size is explicit.
+- Fal Nano Banana 2 Edit: `model_parameters.resolution` for `0.5K`, `1K`,
+  `2K`, and `4K`, plus `seed`.
+- Fal Ideogram V2 Edit: `model_parameters.expand_prompt`, `seed`, and
+  `style`; pass masks as top-level `--mask` / `mask_asset_id`, not as
+  provider `mask_url`.
+- Fal Gemini 3 Pro Image Preview Create/Edit:
+  `model_parameters.resolution` for `1K`, `2K`, and `4K`, plus `seed`; 4K is
+  quoted as the higher-priced provider tier.
+- Fal Nano Banana Pro Create/Edit: `model_parameters.resolution` for `1K`,
+  `2K`, and `4K`, plus `seed`; 4K is quoted as the higher-priced provider tier.
+- Fal FLUX Pro Kontext Pro/Max Edit: `model_parameters.seed`; guidance scale
+  and aspect-ratio controls remain cataloged for inspection but are not
+  executable until their UX and receipt behavior are represented.
+- Fal Bytedance Seedream 4.5 Create/Edit: `model_parameters.image_size` for
+  `square_hd`, `square`, portrait/landscape presets, `auto_2K`, and
+  `auto_4K`, plus `seed`; multi-output and multi-reference controls remain
+  cataloged but fixed for hosted accounting.
+- Fal Bytedance Seedream 5.0 Lite Create/Edit:
+  `model_parameters.image_size` for `square_hd`, `square`, portrait/landscape
+  presets, `auto_2K`, and `auto_3K`; multi-output and multi-reference controls
+  remain cataloged but fixed for hosted accounting.
+- xAI Grok Imagine Image Quality: `model_parameters.resolution` for `1k` and
+  `2k`; 2k is priced from the higher provider tier. Create supports top-level
+  `--output-count` up to the model's advertised `max_outputs_per_request`,
+  currently mapped to xAI's documented `n` batch parameter.
+- GPT Image 1.5 create/edit: documented fixed sizes `1024x1024`,
+  `1024x1536`, and `1536x1024`, output format, compression, transparent or
+  opaque background, moderation, and the upstream provider-native quality
+  parameter. GPT Image 1.5 create quotes output-token estimates when quality
+  and concrete size are known; GPT Image 1.5 create supports top-level
+  `--output-count` up to the model's advertised `max_outputs_per_request`,
+  currently mapped to OpenAI's `n` parameter. GPT Image 1.5 edit accepts
+  low/high `input_fidelity` and remains preflight unknown-cost until usage is
+  returned.
+- GPT Image 2 create/edit: size, output format, compression, background,
+  moderation, and the upstream provider-native quality parameter. GPT Image 2
+  create quotes request-aware output-token estimates when quality and concrete
+  size are known; GPT Image 2 create supports top-level `--output-count` up to
+  the model's advertised `max_outputs_per_request`, currently mapped to
+  OpenAI's `n` parameter. GPT Image 2 edit remains preflight unknown-cost, then
+  records usage-priced provider cost when OpenAI returns token usage.
+
+Inspect each model before use; provider-native controls are available only
+through validated `model_parameters`.
+
+### `luxin capabilities`
+
+Schema-language view over the same capability catalog. Use this when you need
+the capability abstraction directly rather than starting from a model.
+
+```bash
+luxin capabilities --json
+luxin capabilities list --json
+luxin capabilities show CAPABILITY_ID --json
+```
+
+### `luxin create`
+
+Guides, creates, or plans a zero-cost dry run.
+
+Guide the first image path without mutation:
+
+```bash
+luxin create --guide --prompt "A compact field camera on a stainless workbench" --json
+```
+
+`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
+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`,
+`next_command_missing_inputs`, and `guide_warning.next_command_safety` before
+acting: `hosted_signup_no_spend_setup` is no-spend auth setup,
+`live_money_payment_action` is top-up/payment work, and
+`live_media_create_credit_debit` is a live create that can call a provider,
+debit credits, and write media.
+For payment state, read
+`checks.payments.preferred_method_summary.top_up_path` instead of inferring
+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
+`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.
+
+```bash
+luxin create \
+  --prompt "A compact field camera on a stainless workbench" \
+  --intent explore \
+  --aspect-ratio 1:1 \
+  --max-estimated-usd-per-image 0.07 \
+  --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
+`--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
+higher output tier only when `--max-estimated-usd-per-image` is high enough for
+that tier; otherwise it stays on a lower-cost quality tier or chooses a cheaper
+capability within the budget and tells agents what happened in the selection
+receipt. Use the `--max-estimated-usd-per-image` value returned by
+`create --guide`; it is sized to the Luxin credit debit, not only the
+upstream provider estimate.
+
+Preview-compatible richer shape:
+
+```bash
+luxin create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --intent finalize \
+  --model MODEL_ID \
+  --aspect-ratio 1:1 \
+  --output-count 2 \
+  --max-estimated-usd-per-image 0.07 \
+  --model-parameters-json '{"seed":1234}' \
+  --json
+```
+
+Use `--output-count N` only when `models show MODEL_ID --json` advertises
+`media.output.max_outputs_per_request` greater than `1`. `--output-count` is a
+top-level Luxin create control; do not pass provider-native `n` through
+`model_parameters` unless the selected model schema explicitly advertises that
+field. Credit pricing and `cost.credit_pricing.credits_required` are total
+operation debits across all requested outputs. `--max-estimated-usd-per-image`
+and raw API `max_estimated_usd_per_image` are per-image Luxin debit
+budget guards.
+
+Generate video through the same `create` command and durable-media loop. For
+video prompts, run `luxin create --guide --prompt "..." --json`; the guide
+can select the executable video model, suggest `--aspect-ratio 16:9`, and emit
+the next create command. Plain `create` without a model still defaults to an
+image model, so use the guide or pass the video model id directly. The response
+returns a durable owned `video_...` mp4 asset URL, a `job_id`, and a
+`cost.credit_pricing` receipt just like an image create.
+
+```bash
+luxin create \
+  --model fal.ltx-video-13b-distilled \
+  --prompt "A slow dolly push-in on a steaming espresso cup on a cafe counter, morning light" \
+  --aspect-ratio 16:9 \
+  --json
+```
+
+Discover runnable video models with `luxin models list --available
+--modality video --operation video.generate --json`. Inspect parameters, output
+media type, and cost first with `luxin models show
+fal.ltx-video-13b-distilled --json`. Video runs synchronously through the same
+create call and can take longer than an image; the returned `assets[].url` is an
+owned `video/mp4`.
+
+Generate audio (music, sound) through the same `create` command and
+durable-media loop. Request an audio model by id; the response returns a durable
+owned `audio_...` wav asset URL, a `job_id`, and a `cost.credit_pricing` receipt
+just like an image create. Audio has no aspect ratio, so do not pass
+`--aspect-ratio`.
+
+```bash
+luxin create \
+  --model fal.stable-audio-25-text-to-audio \
+  --prompt "A warm lo-fi hip-hop loop with vinyl crackle and a mellow Rhodes piano" \
+  --json
+```
+
+`fal.stable-audio-25-text-to-audio` (Stable Audio 2.5) is text-to-audio at a flat
+$0.20/clip (about 34 credits, quoted before spend) and returns an owned
+`audio/wav` clip. The first slice is defaults-only (no tunable
+`model_parameters`); duration/steps controls are a later milestone. Inspect
+parameters, output media type, and cost first with `luxin models show
+fal.stable-audio-25-text-to-audio --json`. Audio runs synchronously through the
+same create call and can take longer than an image.
+
+For create models with wired reference support, pass owned reference assets
+with the model's advertised reference role. Kling element routes use
+`--element-frontal IMAGE[@ELEMENT_INDEX]` and
+`--element-reference IMAGE[@ELEMENT_INDEX[:REFERENCE_INDEX]]`; flat
+reference-image routes use `--reference-image IMAGE[@INDEX]`; Fal DreamO also
+accepts `:TASK` where `TASK` is `ip`, `id`, or `style`. The public CLI uploads
+local paths and external URLs first, then
+sends top-level `references[]` entries with Luxin `asset_id` values to
+`/v1/create`. Do not pass provider-native `elements`, `frontal_image_url`,
+`reference_image_urls`, `first_image_url`, `second_image_url`, `images`, or
+`*_reference_task` through `model_parameters`; provider-private URLs are
+resolved server-side after ownership and media-policy validation.
+
+```bash
+luxin create \
+  --model fal.kling-image-o3-text-to-image \
+  --prompt "Place the same character in a clean studio campaign" \
+  --element-frontal ./character-front.png@0 \
+  --element-reference ./character-side.webp@0:0 \
+  --output-count 2 \
+  --max-estimated-usd-per-image 0.06 \
+  --json
+```
+
+```bash
+luxin create \
+  --model fal.dreamo \
+  --prompt "Studio portrait preserving identity with a bolder editorial style" \
+  --reference-image ./identity.png@0:id \
+  --reference-image ./style.webp@1:style \
+  --model-parameters-json '{"image_size":{"width":1280,"height":720}}' \
+  --max-estimated-usd-per-image 0.06 \
+  --json
+```
+
+High-resolution examples:
+
+```bash
+luxin create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --intent final \
+  --max-estimated-usd-per-image 0.07 \
+  --json
+
+luxin create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --model fal.gemini-3-pro-image-preview \
+  --model-parameters-json '{"resolution":"4K"}' \
+  --max-estimated-usd-per-image 0.30 \
+  --json
+
+luxin create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --model xai.grok-imagine-image-quality \
+  --model-parameters-json '{"resolution":"2k"}' \
+  --max-estimated-usd-per-image 0.07 \
+  --json
+
+luxin edit \
+  --input-asset-id image_... \
+  --prompt "preserve the subject and make this campaign-ready" \
+  --model fal.nano-banana-2-edit \
+  --model-parameters-json '{"resolution":"4K"}' \
+  --accept-unknown-cost \
+  --json
+```
+
+`model_parameters` must be validated against the selected model/capability
+schema before any provider call or paid reservation. Unknown fields fail closed
+unless the capability explicitly allows additional properties. This is how
+Luxin preserves rare model controls without turning every
+provider-specific parameter into a top-level flag.
+In the current preview, Fal create/edit, xAI quality generation, and OpenAI GPT
+Image 2 expose the executable provider-native controls listed in the selected
+model schema. GPT Image 2 create has request-aware output-token credit quotes
+for concrete quality/size requests; GPT Image 2 edit still requires
+unknown-cost acceptance before execution, but records usage-priced provider cost
+after execution when OpenAI returns token usage. Provider-native controls remain
+visible for planning and fail closed until their capability schema marks them
+executable. Hosted `create --dry-run` validates `model_parameters` against the
+selected model, returns accepted keys/provenance and request-aware credit
+pricing for planning, and never executes provider controls or consumes credits.
+Hosted `edit --dry-run` validates the same owned input, mask/reference,
+prompt-policy, budget, and `model_parameters` checks as a live edit, then
+returns planned outputs without storage, provider, or billing side effects.
+For dry-run responses, `cost.credit_pricing.credits_required` is the planned
+live execution debit for the selected model. The actual debit for the dry run is
+`quota.consumed_credits: 0`.
+Authenticated hosted dry-runs also create a recoverable planned job:
+`jobs show` returns `status: "planned"` with `plan_receipt`, and `activity`
+emits `job.planned`. Planned receipts do not create downloadable media assets or
+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`.
+
+Minimum success data:
+
+```json
+{
+  "job_id": "job_...",
+  "capability": {
+    "id": "is.image.generate.xai-grok-imagine-image-quality.v1"
+  },
+  "assets": [
+    {
+      "asset_id": "image_...",
+      "path": "https://media.image-skill.com/a/image_abc123.png",
+      "mime_type": "image/png",
+      "url": "https://media.image-skill.com/a/image_abc123.png",
+      "content_length": 333444,
+      "width": 2048,
+      "height": 2048
+    }
+  ],
+  "cost": {
+    "estimated_usd": 0.07,
+    "credit_pricing": {
+      "credit_unit_usd": 0.01,
+      "credits_required": 12,
+      "estimated_provider_cost_usd": 0.07,
+      "estimated_revenue_usd": 0.12,
+      "pricing_confidence": "known"
+    }
+  },
+  "request": {
+    "output_count": 1,
+    "selection": {
+      "policy": "hosted_default_create_v1",
+      "reason": "hosted default selected the strongest currently available quality-first create model",
+      "intent": "explore",
+      "capability": {
+        "id": "is.image.generate.xai-grok-imagine-image-quality.v1"
+      },
+      "model_parameters": {
+        "keys": ["resolution"],
+        "defaults_applied": ["resolution=2k"],
+        "source": "default_policy"
+      },
+      "output": {
+        "resolution_class": "2k",
+        "expected_width": null,
+        "expected_height": null,
+        "expected_min_short_edge": 2048
+      }
+    }
+  },
+  "safety": {
+    "status": "allowed"
+  }
+}
+```
+
+When hosted artifact storage is configured, `url` is an Luxin-owned URL.
+Agents should prefer `assets[].url` over provider-origin URLs and should not
+need provider account access to fetch outputs.
+
+Hosted create does not accept `--output-dir`. A future download/fetch command
+may add CLI-side local file convenience while preserving hosted artifact URLs as
+the source of truth.
+
+If provider generation succeeds but artifact storage fails, the command returns
+`ARTIFACT_STORAGE_WRITE_FAILED` with exit `9` and `retryable: false`. Agents
+should not retry the whole create blindly, because that may duplicate paid
+provider spend.
+
+For retry-safe create automation, pass an explicit non-secret
+`--idempotency-key`. A retry that reuses the same key does not create a second
+credit reservation, so a transient `502`/`PROVIDER_FAILURE` that already
+reserved a credit cannot double-charge on retry. `create --guide` bakes a
+generated `--idempotency-key` into its advertised create `next_command`, and a
+retryable create error returns an `error.recovery.idempotency_key` plus an
+`error.recovery.suggested_command` that re-runs the same create with that key.
+
+Live non-dry-run create/edit emits one JSON diagnostic line to stderr before
+the blocking hosted request:
+
+```json
+{
+  "in_flight": {
+    "command": "luxin create",
+    "idempotency_key": "create-...",
+    "recover_command": "luxin create --idempotency-key create-... <same arguments> --json"
+  }
+}
+```
+
+stdout remains the command JSON envelope. If an agent combines streams with
+`2>&1`, split stderr diagnostics from the stdout envelope before parsing. The
+same recovery breadcrumb is stored under `<config-dir>/in-flight/` and appears
+in `luxin doctor --json` at `data.in_flight`. Keep the in-flight
+`idempotency_key` and `recover_command` inside the agent workflow unless a
+failed or uncertain operation needs user-visible recovery.
+
+```bash
+luxin create \
+  --prompt "A compact field camera on a stainless workbench" \
+  --idempotency-key create-run-001 \
+  --json
+```
+
+Hosted free-preview API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/create \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{
+    "prompt": "A compact field camera on a stainless workbench",
+    "intent": "explore",
+    "aspect_ratio": "1:1",
+    "output_count": 1,
+    "max_estimated_usd_per_image": 0.07
+  }'
+```
+
+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.
+
+### `luxin upload`
+
+Normalizes a local image path or remote image URL into an Luxin-owned
+input asset for later edit workflows.
+
+```bash
+luxin upload ./source.png --json
+luxin upload https://example.com/source.png --json
+```
+
+The CLI reads local files and remote URLs client-side, then sends image bytes to
+`POST /v1/upload`. The hosted API does not fetch arbitrary remote URLs in this
+preview. This keeps server-side URL fetching out of the public upload path.
+
+Minimum success data:
+
+```json
+{
+  "request": {
+    "source_kind": "local_path",
+    "filename": "source.png",
+    "remote_origin": null
+  },
+  "asset": {
+    "asset_id": "image_...",
+    "job_id": "job_...",
+    "kind": "uploaded",
+    "url": "https://media.image-skill.com/a/image_abc123.png",
+    "mime_type": "image/png",
+    "content_length": 12345
+  },
+  "upload": {
+    "bytes": 12345,
+    "mime_type": "image/png",
+    "sha256": "...",
+    "policy": {
+      "status": "allowed"
+    }
+  }
+}
+```
+
+Supported preview MIME types are `image/png`, `image/jpeg`, `image/webp`,
+`image/gif`, and `image/avif`. Unsupported input returns
+`INPUT_POLICY_DENIED` with exit `6`. Responses never include local paths, raw
+bytes, base64 payloads, full remote URLs, bucket names, or object keys.
+
+### `luxin edit`
+
+Edits an Luxin-owned input asset or client-normalized local/remote image
+with one hosted provider-backed edit model.
+
+```bash
+luxin edit \
+  --input ASSET_ID_OR_PATH_OR_URL \
+  --mask MASK_ASSET_ID_OR_PATH_OR_URL \
+  --prompt "Remove the background and keep natural object shadows" \
+  --accept-unknown-cost \
+  --json
+```
+
+If `--input` is a local path or external URL, the public CLI first normalizes it
+through the same upload resolver as `luxin upload`, then sends only the
+resulting `asset_id` to `POST /v1/edit`. If `--input` is an Luxin asset id
+or owned asset URL, edit uses that owned asset directly.
+Add `--dry-run` to plan the edit after owned-asset, prompt-policy,
+`model_parameters`, and budget validation. Dry-run edit responses return planned
+assets and `quota.consumed_credits: 0`, store a recoverable `job.planned`
+receipt, and do not call the provider, debit credits, or write media.
+For models with wired mask support, `--mask` follows the same upload/asset-id
+resolver and sends only `mask_asset_id`; never pass provider-native `mask_url`
+through `model_parameters`.
+For models with wired reference support, pass owned reference assets with the
+model's advertised reference role. Kling element routes use
+`--element-frontal IMAGE[@ELEMENT_INDEX]` and
+`--element-reference IMAGE[@ELEMENT_INDEX[:REFERENCE_INDEX]]`; flat
+reference-image routes use `--reference-image IMAGE[@INDEX[:TASK]]`. The
+public CLI uploads local paths and external URLs first, then sends top-level
+`references[]` entries with Luxin `asset_id` values. For Kling element
+routes, `--element-frontal ./front.png@0` becomes role `element_frontal` for
+element index `0`, and `--element-reference ./side.webp@0:0` becomes role
+`element_reference` for the same element with reference slot `0`. For DreamO
+create, `--reference-image ./identity.png@0:id` becomes role
+`reference_image`, index `0`, and `reference_task` `id`. For xAI edit,
+`--reference-image ./reference.png@0` becomes the second ordered source image;
+the primary `--input` asset remains the first source image. Do not pass
+provider-native `elements`, `image_url`, `image_urls`, `frontal_image_url`,
+`reference_image_urls`, `first_image_url`, `second_image_url`, `images`, or
+`*_reference_task` through `model_parameters`; provider-private URLs are
+resolved server-side after ownership and media-policy validation.
+Current public `references[]` support covers Kling Image O1, Kling Image O3
+image-to-image/text-to-image, Kling Image v3 image-to-image/text-to-image, and
+Fal DreamO create plus xAI Grok Imagine image edit/quality edit. Kling requests
+may contain at most 40 reference entries across at most 10 contiguous element
+indexes starting at `0`; each referenced element requires one frontal image and
+may include up to three additional reference images. DreamO accepts up to two
+contiguous `reference_image` indexes starting at `0`, each with optional
+`reference_task` `ip`, `id`, or `style`. xAI edit accepts up to two contiguous
+`reference_image` indexes starting at `0` and does not accept `reference_task`.
+Reference assets must be Luxin-owned PNG, JPEG, or WebP images with
+known non-empty byte length up to 10MB, known width and height of at least
+300px, and aspect ratio from 0.40 to 2.50.
+
+```bash
+luxin edit \
+  --model fal.kling-image-o3-image-to-image \
+  --input ./starting-frame.png \
+  --element-frontal ./character-front.png@0 \
+  --element-reference ./character-side.webp@0:0 \
+  --prompt "Place the same character in a clean studio product portrait" \
+  --accept-unknown-cost \
+  --json
+```
+
+Direct `/v1/edit` callers use the same owned-asset contract:
+
+```json
+{
+  "input_asset_id": "image_starting_frame",
+  "model": "fal.kling-image-o3-image-to-image",
+  "prompt": "Place the same character in a clean studio product portrait",
+  "references": [
+    {
+      "asset_id": "image_character_front",
+      "role": "element_frontal",
+      "index": 0
+    },
+    {
+      "asset_id": "image_character_side",
+      "role": "element_reference",
+      "index": 0,
+      "reference_index": 0
+    }
+  ]
+}
+```
+
+Set `dry_run: true` on `/v1/edit` to get the same no-spend plan the CLI returns.
+The server still validates ownership, prompt policy, references, masks,
+`model_parameters`, and budget guards before returning the planned job.
+
+Create a 3D asset from an image through the same `edit` command and
+durable-media loop. Image-to-3D is promptless and image-conditioned, so it ships
+as a variation transform: pass exactly one owned input image (no prompt) to a 3D
+model by id and the response returns a durable owned `.glb` mesh asset URL (in
+`assets[].url`), a `job_id`, and a `cost.credit_pricing` receipt. A 3D mesh has
+no aspect ratio.
+
+```bash
+luxin edit \
+  --input image_... \
+  --model fal.trellis-image-to-3d \
+  --json
+```
+
+`fal.trellis-image-to-3d` (Trellis) is image-to-3D at a flat $0.02/asset (about 4
+credits, quoted before spend) and returns an owned `model/gltf-binary` (`.glb`)
+textured mesh. The first slice is defaults-only (no tunable `model_parameters`);
+guidance/steps/mesh_simplify/texture_size controls are a later milestone. Inspect
+parameters, output media type, and cost first with `luxin models show
+fal.trellis-image-to-3d --json`. The input must be one Luxin-owned image;
+3D runs synchronously through the same edit call and can take longer than an
+image.
+
+Preview hosted create/edit supports model-specific provider-backed paths such
+as Fal Gemini 3 Pro Image Preview Create (`fal.gemini-3-pro-image-preview`),
+Fal Nano Banana 2 Edit (`fal.nano-banana-2-edit`), Fal Ideogram V2 Edit
+(`fal.ideogram-v2-edit`), Fal Gemini 3 Pro Image
+Preview Edit (`fal.gemini-3-pro-image-preview-edit`), Fal FLUX Pro 1.1 Ultra
+Create (`fal.flux-pro-v1-1-ultra`), Fal FLUX Pro Kontext Edit
+(`fal.flux-pro-kontext`), Fal FLUX Pro Kontext Max Edit
+(`fal.flux-pro-kontext-max`), Fal Seedream 5.0 Lite Create
+(`fal.bytedance-seedream-v5-lite-text-to-image`), Fal Seedream 5.0 Lite Edit
+(`fal.bytedance-seedream-v5-lite-edit`), Fal Seedream 4.5 Create
+(`fal.bytedance-seedream-v4-5-text-to-image`), Fal Seedream 4.5 Edit
+(`fal.bytedance-seedream-v4-5-edit`), Fal Nano Banana Pro Create
+(`fal.nano-banana-pro`), Fal Nano Banana Pro Edit
+(`fal.nano-banana-pro-edit`), GPT Image 1.5 Create
+(`openai.gpt-image-1.5`), GPT Image 1.5 Edit
+(`openai.gpt-image-1.5-edit`), and GPT Image 2 Edit
+(`openai.gpt-image-2-edit`) when their provider credentials are configured.
+Fal Gemini 3 Pro Image Preview create/edit has known per-image pricing: 1K/2K
+requests quote `$0.15` provider cost and 4K quotes the doubled provider tier.
+Fal Nano Banana Pro create/edit uses the same `$0.15` standard and doubled 4K
+provider tier. Fal FLUX Pro 1.1 Ultra Create quotes `$0.06` provider cost per
+image. Fal FLUX Pro Kontext Edit quotes `$0.04` provider cost per image, and
+Fal FLUX Pro Kontext Max Edit quotes `$0.08` provider cost per image. Fal
+Seedream 4.5 create/edit quotes `$0.04` provider cost per image.
+Fal Seedream 5.0 Lite create/edit quotes `$0.035` provider cost per image. Fal
+Z-Image Turbo create/edit quotes `$0.005/MP` when `image_size` is explicit or
+derived from aspect ratio; edit `auto` remains unknown-cost. GPT Image 1.5
+create quotes output-token estimates for concrete quality/size requests using
+OpenAI's fixed-size token table; GPT Image 1.5 edit remains preflight
+unknown-cost because edit input image/text tokens are provider-metered, then
+records usage-priced provider cost when OpenAI returns token usage. GPT Image 2
+create quotes output-token estimates for concrete quality/size requests. GPT
+Image 2 edit remains preflight unknown-cost because edit input image/text tokens
+are provider-metered, then records usage-priced provider cost when OpenAI
+returns token usage. Other edit paths without machine-readable pricing require
+`--accept-unknown-cost` until a stable price source is captured. Responses
+include a new generated asset URL, job id, safety state, quota consumption, and
+input asset metadata where
+applicable. Responses do not include raw prompts, source bytes, base64
+payloads, local paths, full external URLs, bucket names, or object keys.
+When `quota.top_up.available` is true, `next_actions.self_fund.quote_command`
+is a copy-runnable top-up quote command. `next_actions.self_fund.recommended`
+and the mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say
+whether the agent should act now. The handoff exposes `first_safe_command`,
+`first_safe_command_effect`, `inspect_methods_command`, and
+`inspect_packs_command` for no-spend payment rail inspection before quote/buy.
+The quote command omits `--idempotency-key` so the public CLI generates and
+returns one for retry safety before the agent follows the quote response into
+`credits buy` and `credits status`.
+
+Provider/model names in this paragraph are preview provenance, not the primary
+public UX. The public selection surface should be Luxin capabilities and
+model-parameter schemas; provider/model details belong in explicit
+provenance/debug output.
+
+Edit accepts the same retry-safe `--idempotency-key` as create. A retry that
+reuses the same key does not create a second credit reservation, so a transient
+`502`/`PROVIDER_FAILURE` after a reservation cannot double-charge; a retryable
+edit error returns an `error.recovery.idempotency_key` and an
+`error.recovery.suggested_command` that re-runs the same edit with that key.
+Live non-dry-run edit emits the same stderr `in_flight` diagnostic and local
+doctor-visible recovery breadcrumb as create.
+
+### `luxin assets show`
+
+Inspects an Luxin-owned asset URL or hosted asset id.
+
+```bash
+luxin assets show \
+  https://media.image-skill.com/a/image_abc123.png \
+  --json
+```
+
+For asset-id lookup, use hosted auth:
+
+```bash
+luxin assets show image_... --json
+```
+
+Minimum success data:
+
+```json
+{
+  "request": {
+    "reference": "image_...",
+    "reference_type": "asset_id"
+  },
+  "asset": {
+    "asset_id": "image_...",
+    "job_id": "job_...",
+    "url": "https://media.image-skill.com/a/image_abc123.png",
+    "mime_type": "image/png",
+    "content_length": 12345,
+    "width": 1024,
+    "height": 1024,
+    "source": "hosted_metadata"
+  }
+}
+```
+
+External URLs are rejected. Older assets created before hosted asset metadata
+was recorded may still be inspectable by Luxin-owned URL.
+
+For hosted generated assets, when quota exposes an available top-up path,
+`data.next_actions.self_fund` mirrors the top-up recommendation, urgency, and
+no-spend payment rail inspection handoff used by create/edit, jobs, and
+activity responses. On successful create/edit, when that self-fund action is
+recommended and copy-runnable, `data.self_fund_next_command` aliases
+`data.next_actions.self_fund.quote_command`; its effect object proves the quote
+does not buy, settle a wallet transfer, debit credits, call a provider, create a
+hosted job, or write media.
+
+### `luxin assets get`
+
+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 \
+  --output ./result.png \
+  --json
+```
+
+The command refuses to overwrite existing files unless `--overwrite` is
+explicit. It verifies byte length when the asset server provides a
+`content-length` header. For hosted asset-id downloads, `assets get` preserves
+`data.next_actions.self_fund` from the asset metadata response after a
+successful download.
+
+### `luxin jobs show`
+
+Inspects a hosted Luxin job visible to the authenticated agent.
+
+```bash
+luxin jobs show job_... --json
+```
+
+Output includes public job status, trace id, timestamps, capability id, cost
+summary, safety status, and Luxin-owned asset metadata. For fresh-agent
+parsing, `status`, `state`, `assets`, and `cost` are mirrored at top level and
+match `job.status`, `job.assets`, and `job.cost`. Provider/model provenance is
+available only through explicit provenance/debug affordances for authorized
+actors. Default output does not include raw prompts, generated bytes, provider
+credentials, DB/storage keys, bucket names, or local paths.
+
+Minimum success data:
+
+```json
+{
+  "request": {
+    "job_id": "job_..."
+  },
+  "status": "completed",
+  "state": "completed",
+  "assets": [],
+  "cost": {
+    "estimated_usd": 0.05,
+    "provider_reported_usd_ticks": null
+  },
+  "job": {
+    "job_id": "job_...",
+    "status": "completed",
+    "assets": [],
+    "cost": {
+      "estimated_usd": 0.05,
+      "provider_reported_usd_ticks": null
+    }
+  }
+}
+```
+
+### `luxin jobs wait`
+
+Waits for a hosted Luxin job to reach a terminal status.
+
+```bash
+luxin jobs wait job_... --timeout-ms 30000 --poll-interval-ms 1000 --json
+```
+
+Completed jobs return immediately. Non-terminal jobs poll until completion,
+failure, cancellation, or deterministic timeout. Terminal success uses the same
+top-level `status`, `state`, `assets`, and `cost` mirrors as `jobs show`, with
+`request.timeout_ms` and `request.poll_interval_ms` added for provenance.
+
+### `luxin activity list`
+
+Lists recent hosted activity ledger events visible to the authenticated agent.
+
+```bash
+luxin activity list --limit 20 --json
+luxin activity list --subject job_... --json
+```
+
+Activity is the ledger, not the work queue. Use it to find recent event IDs,
+related job IDs, asset IDs, usage IDs, feedback IDs, trace IDs, status changes,
+and product-memory writes. Use `jobs show` or `jobs wait` when you need
+operational recovery, polling, retry judgment, or final job assets.
+
+When the ledger proves generated work and current quota exposes an available
+top-up path, `data.next_actions.self_fund` mirrors the same recommendation,
+urgency, and no-spend payment-method inspection handoff returned by successful
+create/edit and `jobs show`.
+
+Minimum success data:
+
+```json
+{
+  "events": [
+    {
+      "event_id": "evt_...",
+      "type": "job.completed",
+      "occurred_at": "2026-05-05T19:00:23.000Z",
+      "summary": "Create job completed",
+      "operation": "create",
+      "subject": {
+        "type": "job",
+        "id": "job_..."
+      },
+      "links": {
+        "job_id": "job_...",
+        "asset_ids": ["image_..."],
+        "feedback_id": null,
+        "usage_event_id": "usage_..."
+      },
+      "status": "completed",
+      "cost": {
+        "estimated_usd": 0.025
+      }
+    }
+  ],
+  "source": "hosted_activity_ledger"
+}
+```
+
+The ledger hides provider and storage implementation details by default. It is
+safe to cite `evt_...`, `job_...`, `image_...`, `usage_...`, `feedback_id`,
+and `trace_id` values in feedback.
+
+Hosted API equivalent:
+
+```bash
+curl -sS "https://api.luxin.sh/v1/activity?limit=20&subject=job_..." \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN"
+```
+
+### `luxin activity show`
+
+Shows one hosted activity event or the latest events related to one subject.
+
+```bash
+luxin activity show evt_... --json
+luxin activity show job_... --json
+luxin activity show image_... --json
+luxin activity show sig_... --json
+```
+
+`activity show` accepts activity event IDs plus job, asset, usage, feedback, and
+trace references. When the reference is a subject rather than one exact event,
+the response includes matching ledger events so an agent can cite the right
+event without reading telemetry logs. When current quota exposes top-up
+availability after generated work,
+`data.next_actions.self_fund.first_safe_command` is the no-spend rail
+inspection command to run before any quote/buy step.
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/activity/evt_... \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN"
+```
+
+### Activity Event Registry
+
+Activity `type` values are stable public contract values. Do not infer new
+event names from provider responses or telemetry logs; use only the registry
+below.
+
+| Event type                                 | Subject    | Operation   | Emitted when                                                       | Stable links                                                       |
+| ------------------------------------------ | ---------- | ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `job.completed`                            | `job`      | create/edit | A hosted create or edit job reaches a terminal state.              | `job_id`, `asset_ids`, `usage_event_id`                            |
+| `job.planned`                              | `job`      | create/edit | An authenticated hosted dry-run stores a recoverable plan receipt. | `job_id`                                                           |
+| `asset.created`                            | `asset`    | create/edit | A hosted create or edit produces an output asset.                  | `job_id`, `asset_ids`, `usage_event_id`                            |
+| `asset.uploaded`                           | `asset`    | upload      | A public edit workflow uploads or imports input media.             | `job_id`, `asset_ids`, `usage_event_id`                            |
+| `usage.credit_consumed`                    | `usage`    | usage       | A creative operation records a preview-credit entry.               | `job_id`, `usage_event_id`                                         |
+| `feedback.created`                         | `feedback` | feedback    | Hosted agent feedback is accepted into product memory.             | `feedback_id`                                                      |
+| `feedback.github_queue.processed`          | `feedback` | feedback    | Feedback is processed by the GitHub implementation queue handoff.  | `feedback_id`                                                      |
+| `payment.checkout_session.created`         | `payment`  | payment     | A Stripe Checkout session is created and awaits external action.   | `quote_id`, `payment_attempt_id`, `checkout_session_id`            |
+| `credits.payment_backed_granted`           | `credit`   | credits     | Verified payment fulfillment grants paid credits.                  | `quote_id`, `receipt_id`, `credit_event_id`                        |
+| `credits.payment_backed_refunded`          | `credit`   | credits     | A Stripe refund debits payment-backed credits.                     | `quote_id`, `receipt_id`, `payment_reversal_id`, `credit_event_id` |
+| `credits.payment_backed_disputed`          | `credit`   | credits     | A Stripe dispute debit applies to payment-backed credits.          | `quote_id`, `receipt_id`, `payment_reversal_id`, `credit_event_id` |
+| `credits.payment_backed_reinstated`        | `credit`   | credits     | Stripe dispute funds were reinstated and recorded.                 | `quote_id`, `receipt_id`, `payment_reversal_id`                    |
+| `credits.payment_backed_reversal_pending`  | `credit`   | credits     | A reversal was recorded but could not be fully applied.            | `quote_id`, `receipt_id`, `payment_reversal_id`                    |
+| `credits.payment_backed_reversal_rejected` | `credit`   | credits     | A reversal was rejected because it could not safely reconcile.     | `quote_id`, `receipt_id`, `payment_reversal_id`                    |
+
+`feedback.github_queue.processed` includes `details.github_queue` with
+machine-readable lifecycle fields such as `state`, `reason`, `issue_urls`,
+`issue_numbers`, `mode`, and `github_mutation`. Agents should use it to learn
+whether submitted feedback was promoted, skipped, deduped, blocked, or already
+mirrored without reading private repository artifacts.
+`job.planned` includes `details.plan_receipt` for authenticated hosted
+dry-runs. It is a recoverable planning receipt, not completed media work:
+planned outputs do not have durable asset IDs, download URLs, usage debits, or
+provider execution.
+
+If a response includes an event type outside this registry, treat it as a
+contract bug and submit `luxin feedback create --json` with the event ID
+and trace ID.
+
+### `luxin feedback create`
+
+Leaves structured product feedback in hosted Luxin product memory.
+At minimum, provide `--title` and `--body`; Luxin accepts narrative
+feedback and adds quality guidance server-side. Use the structured fields below
+when the agent already knows them.
+
+```bash
+luxin feedback create \
+  --type user_feedback \
+  --title "Short concrete title" \
+  --body "What happened, what was expected, and why it matters" \
+  --command "Command or workflow observed" \
+  --expected "Expected result" \
+  --actual "Actual result" \
+  --proof-needed "What would prove this is handled" \
+  --surface cli,docs \
+  --evidence trace:TRACE_ID \
+  --severity medium \
+  --confidence high \
+  --next-state watch \
+  --json
+```
+
+Hosted feedback authenticates the same way as other hosted commands: saved
+public CLI config from default signup, `IMAGE_SKILL_TOKEN`, or
+`--token-stdin`. If guide/signup already saved config, run `feedback create`
+normally; no raw token copy step is required. If the runtime uses its own
+secret store, prefer `IMAGE_SKILL_TOKEN` or `--token-stdin`. Do not paste tokens
+into feedback title, body, evidence, issues, or logs. Feedback persists through
+`https://api.luxin.sh/v1/feedback`. The hosted API fails closed if
+durable hosted feedback storage is unavailable.
+
+JSON errors may include `error.recovery` with machine-readable fields such as
+`required_flag`, `suggested_command`, `docs_url`, or `retry_after_seconds`.
+Agents should prefer those fields over parsing prose error messages. For
+example, `BUDGET_REQUIRES_CONFIRMATION` returns
+`required_flag: "--accept-unknown-cost"`.
+Quota/payment recovery also includes `error.recovery.top_up`: its
+`quote_command` is copy-runnable and creates an authenticated live-money
+quote/payment object without paying, settling a wallet transfer, debiting
+credits, calling a provider, or writing media. Only the later buy/status and
+wallet/checkout completion steps can spend money.
+
+`whoami`, `usage quota`, `quota`, `credits quote`, `credits buy`,
+`credits status`, `create`, `activity list`,
+`activity show`, and `feedback create` accept `--token-stdin` for stdin-based
+secret handoff.
+`credits methods` and `credits packs list` do not require auth.
+
+Feedback should avoid raw prompts, hosted tokens, provider keys, generated
+image bytes, source image bytes, and private user data.
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.luxin.sh/v1/feedback \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{
+    "type": "user_feedback",
+    "title": "Short concrete title",
+    "body": "What happened, what was expected, and why it matters",
+    "command": "Command or workflow observed",
+    "expected": "Expected result",
+    "actual": "Actual result",
+    "proof_needed": "What would prove this is handled",
+    "surface": ["cli", "docs"],
+    "evidence": ["trace:TRACE_ID"],
+    "severity": "medium",
+    "confidence": "high",
+    "next_state": "watch"
+  }'
+```
+
+### Planned Resource Commands
+
+`jobs list`, `assets list`, `assets delete`, and async job cancellation are
+planned public resource commands. They are not part of the current public
+allowlist until the hosted service backs them and this contract lists their
+exact command shapes. `activity list/show` is available now for ledger
+readback, but it is not a substitute for future job listing, cancellation, or
+retry controls.