image-skill 0.1.35 → 0.1.37

package/skill.md

@@ -39,7 +39,7 @@ JSON is the default. Do not add `--json` to examples.
 npm_config_update_notifier=false npx -y image-skill@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 one concrete `data.next_command` to run, plus `data.stage`, `data.guide_warning`, `data.next_command_effect`, `data.auth_ready`, `data.no_spend_evaluation`, `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.auth_handoff`, and `data.mutation`. 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 when the warning says it is safe for your spend policy. 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. 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.auth_ready`, `data.no_spend_evaluation`, `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.auth_handoff`, and `data.mutation`. 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. 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. 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.
 
 Minimum success envelope on a create or edit:
 
@@ -133,7 +133,7 @@ image-skill usage quota
 
 If the runtime supports stdin secret handoff, prefer `--token-stdin` over `--token` for `whoami`, `usage quota`, `create`, and `feedback create`. The guide returns `data.auth_handoff` with copy-safe env and stdin command templates so the token never lands in prompts, logs, or feedback.
 
-If the default config home is read-only, set `IMAGE_SKILL_CONFIG_PATH` to a writable path before `signup`. Do not fall back to another tool because the install or default config directory is blocked. `create --guide` detects this and makes `data.next_command` a normal saved-config signup prefixed with `IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"`; the `--show-token --no-save` plus `--token-stdin` route stays available only as structured fallback recovery.
+If the default config home is read-only, set `IMAGE_SKILL_CONFIG_PATH` to a writable path before `signup`. Do not fall back to another tool because the install or default config directory is blocked. `create --guide` detects this and makes `data.next_command` a saved-config signup template prefixed with `IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"`; fill `data.next_command_missing_inputs` before running it. The `--show-token --no-save` plus `--token-stdin` route stays available only as structured fallback recovery.
 
 Install paths, in order of preference:
 
@@ -195,6 +195,8 @@ image-skill models list --available --modality video --operation video.generate
 image-skill models show openai.gpt-image-2
 ```
 
+`models list` is the compact, summary-first action menu. Use `models show MODEL_ID` for one model's full capability schema, or `models list --details` only when you intentionally need every model's full schema at once.
+
 `--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.
 
 Pass model-specific controls through validated JSON, not invented top-level flags:

package/skills/ai-audio-generation/SKILL.md

@@ -25,7 +25,7 @@ This is an intent-named Image Skill entry for agents searching for audio generat
 
 Use this skill when the task asks for AI audio generation, text-to-audio, music generation, sound design, ambience, effects, or durable hosted audio output.
 
-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 media spend is allowed, otherwise run `data.recommended_no_spend_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+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 Image Skill so future agents can recover and cite it.
 
 ## First Command
 

package/skills/ai-image-generation/SKILL.md

@@ -25,7 +25,7 @@ This is an intent-named Image Skill entry for agents searching for image generat
 
 Use this skill when the task asks for AI image generation, text-to-image, prompt-to-image, generated illustrations, concept art, product images, or any durable agent-created image.
 
-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 media spend is allowed, otherwise run `data.recommended_no_spend_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+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 Image Skill so future agents can recover and cite it.
 
 ## First Command
 

package/skills/ai-video-generation/SKILL.md

@@ -25,7 +25,7 @@ This is an intent-named Image Skill entry for agents searching for video generat
 
 Use this skill when the task asks for AI video generation, text-to-video, generated motion, animated concepts, or durable hosted video output.
 
-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 media spend is allowed, otherwise run `data.recommended_no_spend_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+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 Image Skill so future agents can recover and cite it.
 
 ## First Command
 

package/skills/creative-media/SKILL.md

@@ -25,7 +25,7 @@ This is an intent-named Image Skill entry for agents searching for creative medi
 
 Use this skill when the task asks for generative media, creative media, generated assets across modalities, or a single agent-facing runtime for image, edit, video, audio, and 3D work.
 
-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 media spend is allowed, otherwise run `data.recommended_no_spend_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+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 Image Skill so future agents can recover and cite it.
 
 ## First Command
 

package/skills/image-edit/SKILL.md

@@ -25,7 +25,7 @@ This is an intent-named Image Skill entry for agents searching for image editing
 
 Use this skill when the task asks to edit, vary, restyle, transform, or repair an existing image, including image-to-image work and model-specific edit parameters.
 
-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 media spend is allowed, otherwise run `data.recommended_no_spend_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+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 Image Skill so future agents can recover and cite it.
 
 ## First Command
 

package/skills/image-generation/SKILL.md

@@ -25,7 +25,7 @@ This is an intent-named Image Skill entry for agents searching for image generat
 
 Use this skill when the task asks for image generation, generated images, AI images, text-to-image, prompt-to-image, generated illustrations, concept art, product images, or any durable agent-created image.
 
-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 media spend is allowed, otherwise run `data.recommended_no_spend_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+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 Image Skill so future agents can recover and cite it.
 
 ## First Command
 

package/skills/image-skill/SKILL.md

@@ -39,7 +39,7 @@ JSON is the default. Do not add `--json` to examples.
 npm_config_update_notifier=false npx -y image-skill@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 one concrete `data.next_command` to run, plus `data.stage`, `data.guide_warning`, `data.next_command_effect`, `data.auth_ready`, `data.no_spend_evaluation`, `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.auth_handoff`, and `data.mutation`. 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 when the warning says it is safe for your spend policy. 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. 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.auth_ready`, `data.no_spend_evaluation`, `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.auth_handoff`, and `data.mutation`. 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. 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. 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.
 
 Minimum success envelope on a create or edit:
 
@@ -133,7 +133,7 @@ image-skill usage quota
 
 If the runtime supports stdin secret handoff, prefer `--token-stdin` over `--token` for `whoami`, `usage quota`, `create`, and `feedback create`. The guide returns `data.auth_handoff` with copy-safe env and stdin command templates so the token never lands in prompts, logs, or feedback.
 
-If the default config home is read-only, set `IMAGE_SKILL_CONFIG_PATH` to a writable path before `signup`. Do not fall back to another tool because the install or default config directory is blocked. `create --guide` detects this and makes `data.next_command` a normal saved-config signup prefixed with `IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"`; the `--show-token --no-save` plus `--token-stdin` route stays available only as structured fallback recovery.
+If the default config home is read-only, set `IMAGE_SKILL_CONFIG_PATH` to a writable path before `signup`. Do not fall back to another tool because the install or default config directory is blocked. `create --guide` detects this and makes `data.next_command` a saved-config signup template prefixed with `IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"`; fill `data.next_command_missing_inputs` before running it. The `--show-token --no-save` plus `--token-stdin` route stays available only as structured fallback recovery.
 
 Install paths, in order of preference:
 
@@ -195,6 +195,8 @@ image-skill models list --available --modality video --operation video.generate
 image-skill models show openai.gpt-image-2
 ```
 
+`models list` is the compact, summary-first action menu. Use `models show MODEL_ID` for one model's full capability schema, or `models list --details` only when you intentionally need every model's full schema at once.
+
 `--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.
 
 Pass model-specific controls through validated JSON, not invented top-level flags:

package/skills/image-skill/references/cli.md

@@ -134,7 +134,8 @@ should omit it.
 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_effect`,
+`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`, and `data.no_spend_evaluation`. Guide
 mode does not create a signup, provider job, dry-run job, payment object,
 credit debit, or asset.
@@ -143,22 +144,28 @@ credit debit, or asset.
 image-skill create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-Read `data.stage` and `data.guide_warning`, run `data.next_command` when
-`data.guide_warning.next_command_safety` is safe for the current spend policy,
-and rerun the guide only after auth or payment state changes. Do not run
+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.
 
-- `prompt_required`: rerun `data.next_command` with the real prompt.
-- `auth_required`: run `data.next_command`, then rerun guide once. Hosted
-  signup saves auth to config by default. If the runtime intentionally used
+- `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`: run `data.self_fund_next_command` to start the top-up.
+- `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. If the guide authenticated from env or stdin, prefer
   `data.self_fund_handoff.auth.next_command.with_env` or
@@ -767,7 +774,7 @@ capability-preserving schema for one model.
 ```bash
 image-skill models --json
 image-skill models list --json
-image-skill models list --summary --json
+image-skill models list --details --json
 image-skill models list --available --operation image.generate --json
 image-skill models list --available --operation image.edit --json
 image-skill models list --available --modality video --operation video.generate --json
@@ -798,20 +805,23 @@ inspect the recommended create surface without knowing a provider-specific
 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, and catalog-inclusion flags. Default list output excludes
-catalog-only rows so fresh agents see executable candidates first. Use
-`--summary` when you need a compact, sortable model menu: 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 `--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, 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
+commands, 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, 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 ...`
@@ -899,13 +909,15 @@ image-skill create --guide --prompt "A compact field camera on a stainless workb
 ```
 
 `create --guide` returns `schema: image-skill.create-guide.v1`,
-`stage`, `next_command`, `guide_warning`, `auth_ready`, `no_spend_evaluation`,
-`recommended_no_spend_command`,
+`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`, `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 `guide_warning.next_command_safety` before
+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,