image-skill 0.1.35 → 0.1.37

package/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,

package/commands.json

@@ -0,0 +1,515 @@
+{
+  "schema": "image-skill.public-command-manifest.v1",
+  "command_prefix": "image-skill",
+  "product_frame": "Image Skill is a hosted thin CLI and public contract for agent-native durable creative media.",
+  "skill_url": "https://image-skill.com/skill.md",
+  "docs_url": "https://image-skill.com/cli.md",
+  "llms_url": "https://image-skill.com/llms.txt",
+  "commands": [
+    {
+      "id": "doctor",
+      "docs_anchor": "image-skill-doctor",
+      "surface": "client",
+      "mutation": false,
+      "spend": false
+    },
+    {
+      "id": "trust",
+      "docs_anchor": "image-skill-trust",
+      "surface": "client",
+      "mutation": false,
+      "spend": false
+    },
+    {
+      "id": "signup",
+      "docs_anchor": "image-skill-signup-agent",
+      "surface": "hosted_cli",
+      "mutation": true,
+      "spend": false
+    },
+    {
+      "id": "whoami",
+      "docs_anchor": "image-skill-whoami",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false
+    },
+    {
+      "id": "usage",
+      "docs_anchor": "image-skill-usage",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false,
+      "subcommands": ["quota"]
+    },
+    {
+      "id": "quota",
+      "docs_anchor": "image-skill-quota",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false
+    },
+    {
+      "id": "credits",
+      "docs_anchor": "image-skill-credits",
+      "surface": "hosted_cli",
+      "mutation": true,
+      "spend": true,
+      "subcommands": ["methods", "packs list", "quote", "buy", "status"]
+    },
+    {
+      "id": "capabilities",
+      "docs_anchor": "image-skill-capabilities",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false,
+      "subcommands": ["list", "show"]
+    },
+    {
+      "id": "models",
+      "docs_anchor": "image-skill-models",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false,
+      "subcommands": ["list", "show"]
+    },
+    {
+      "id": "create",
+      "docs_anchor": "image-skill-create",
+      "surface": "hosted_cli",
+      "mutation": true,
+      "spend": true
+    },
+    {
+      "id": "upload",
+      "docs_anchor": "image-skill-upload",
+      "surface": "client",
+      "mutation": true,
+      "spend": false
+    },
+    {
+      "id": "edit",
+      "docs_anchor": "image-skill-edit",
+      "surface": "client",
+      "mutation": true,
+      "spend": true
+    },
+    {
+      "id": "assets",
+      "docs_anchor": "image-skill-assets",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false,
+      "subcommands": ["show", "get"]
+    },
+    {
+      "id": "jobs",
+      "docs_anchor": "image-skill-jobs",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false,
+      "subcommands": ["show", "wait"]
+    },
+    {
+      "id": "activity",
+      "docs_anchor": "image-skill-activity",
+      "surface": "hosted_cli",
+      "mutation": false,
+      "spend": false,
+      "subcommands": ["list", "show"]
+    },
+    {
+      "id": "feedback",
+      "docs_anchor": "image-skill-feedback",
+      "surface": "hosted_cli",
+      "mutation": true,
+      "spend": false,
+      "subcommands": ["create"]
+    }
+  ],
+  "modality_aliases": [
+    { "alias": "image", "command": "create", "intent": null },
+    { "alias": "video", "command": "create", "intent": "video" },
+    { "alias": "audio", "command": "create", "intent": "audio" },
+    { "alias": "3d", "command": "create", "intent": "image-to-3d" },
+    { "alias": "image-to-3d", "command": "create", "intent": "image-to-3d" },
+    { "alias": "three-d", "command": "create", "intent": "image-to-3d" }
+  ],
+  "help_entries": [
+    {
+      "key": "",
+      "help": {
+        "command": "help",
+        "usage": "image-skill <doctor|trust|signup|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "docs_url": "https://image-skill.com/cli.md",
+        "commands": [
+          "doctor",
+          "trust",
+          "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
+          "whoami",
+          "usage quota",
+          "quota",
+          "credits methods",
+          "credits quote",
+          "credits packs list",
+          "credits buy",
+          "credits status",
+          "capabilities",
+          "capabilities list",
+          "capabilities show",
+          "models",
+          "models list",
+          "models show",
+          "create --guide",
+          "image create --guide",
+          "video create --guide",
+          "audio create --guide",
+          "3d create --guide",
+          "create --dry-run",
+          "create",
+          "image edit",
+          "upload",
+          "edit",
+          "assets show",
+          "assets get",
+          "jobs show",
+          "jobs wait",
+          "activity list",
+          "activity show",
+          "feedback create"
+        ]
+      }
+    },
+    {
+      "key": "doctor",
+      "help": {
+        "command": "image-skill doctor help",
+        "usage": "image-skill doctor --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-doctor",
+        "description": "Check hosted API reachability, CLI version, auth state, and health."
+      }
+    },
+    {
+      "key": "trust",
+      "help": {
+        "command": "image-skill trust help",
+        "usage": "image-skill trust --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-trust",
+        "description": "Return npm provenance, hosted contract hashes, API health, and model availability evidence."
+      }
+    },
+    {
+      "key": "signup",
+      "help": {
+        "command": "image-skill signup help",
+        "usage": "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-signup-agent",
+        "required_flags": [
+          "--agent",
+          "--agent-contact",
+          "--agent-name",
+          "--runtime"
+        ],
+        "optional_flags": ["--show-token", "--no-save", "--token-stdin"]
+      }
+    },
+    {
+      "key": "whoami",
+      "help": {
+        "command": "image-skill whoami help",
+        "usage": "image-skill whoami --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-whoami"
+      }
+    },
+    {
+      "key": "usage",
+      "help": {
+        "command": "image-skill usage help",
+        "usage": "image-skill usage quota --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-usage",
+        "subcommands": ["quota"]
+      }
+    },
+    {
+      "key": "usage quota",
+      "help": {
+        "command": "image-skill usage quota help",
+        "usage": "image-skill usage quota --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-usage"
+      }
+    },
+    {
+      "key": "quota",
+      "help": {
+        "command": "image-skill quota help",
+        "usage": "image-skill quota --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-quota"
+      }
+    },
+    {
+      "key": "credits",
+      "help": {
+        "command": "image-skill credits help",
+        "usage": "image-skill credits <methods|packs list|quote|buy|status> --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-credits",
+        "subcommands": ["methods", "packs list", "quote", "buy", "status"]
+      }
+    },
+    {
+      "key": "credits methods",
+      "help": {
+        "command": "image-skill credits methods help",
+        "usage": "image-skill credits methods",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-credits"
+      }
+    },
+    {
+      "key": "credits packs",
+      "help": {
+        "command": "image-skill credits packs help",
+        "usage": "image-skill credits packs list --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-credits",
+        "subcommands": ["list"]
+      }
+    },
+    {
+      "key": "credits quote",
+      "help": {
+        "command": "image-skill credits quote help",
+        "usage": "image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-credits",
+        "required_flags": ["--pack or --credits", "--payment-method"],
+        "optional_flags": ["--idempotency-key"]
+      }
+    },
+    {
+      "key": "credits buy",
+      "help": {
+        "command": "image-skill credits buy help",
+        "usage": "image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-credits",
+        "required_flags": ["--provider", "--quote-id", "--idempotency-key"],
+        "supported_providers": ["stripe", "stripe_x402"]
+      }
+    },
+    {
+      "key": "credits status",
+      "help": {
+        "command": "image-skill credits status help",
+        "usage": "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-credits",
+        "required_flags": ["--payment-attempt-id"]
+      }
+    },
+    {
+      "key": "capabilities",
+      "help": {
+        "command": "image-skill capabilities help",
+        "usage": "image-skill capabilities <list|show> --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-capabilities",
+        "subcommands": ["list", "show"]
+      }
+    },
+    {
+      "key": "capabilities list",
+      "help": {
+        "command": "image-skill capabilities list help",
+        "usage": "image-skill capabilities list --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-capabilities"
+      }
+    },
+    {
+      "key": "capabilities show",
+      "help": {
+        "command": "image-skill capabilities show help",
+        "usage": "image-skill capabilities show CAPABILITY_ID --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-capabilities"
+      }
+    },
+    {
+      "key": "models",
+      "help": {
+        "command": "image-skill models help",
+        "usage": "image-skill models <list|show> --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-models",
+        "subcommands": ["list", "show"]
+      }
+    },
+    {
+      "key": "models list",
+      "help": {
+        "command": "image-skill models list help",
+        "usage": "image-skill models list --available --operation image.generate --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-models",
+        "optional_flags": [
+          "--available",
+          "--executable",
+          "--catalog-only",
+          "--operation",
+          "--modality",
+          "--provider",
+          "--summary",
+          "--details"
+        ]
+      }
+    },
+    {
+      "key": "models show",
+      "help": {
+        "command": "image-skill models show help",
+        "usage": "image-skill models show MODEL_ID --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-models"
+      }
+    },
+    {
+      "key": "create",
+      "help": {
+        "command": "image-skill create help",
+        "usage": "image-skill create --prompt \"...\" --intent explore --max-estimated-usd-per-image 0.07 --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-create",
+        "optional_flags": [
+          "--guide",
+          "--dry-run",
+          "--model",
+          "--aspect-ratio",
+          "--output-count",
+          "--element-frontal",
+          "--element-reference",
+          "--reference-image",
+          "--model-parameters-json",
+          "--idempotency-key"
+        ]
+      }
+    },
+    {
+      "key": "upload",
+      "help": {
+        "command": "image-skill upload help",
+        "usage": "image-skill upload PATH_OR_URL --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-upload"
+      }
+    },
+    {
+      "key": "edit",
+      "help": {
+        "command": "image-skill edit help",
+        "usage": "image-skill edit --input image_... --prompt \"...\" --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-edit",
+        "required_flags": ["--input"],
+        "optional_flags": [
+          "--dry-run",
+          "--prompt",
+          "--model",
+          "--mask",
+          "--element-reference",
+          "--element-frontal",
+          "--reference-image",
+          "--model-parameters-json",
+          "--idempotency-key"
+        ]
+      }
+    },
+    {
+      "key": "assets",
+      "help": {
+        "command": "image-skill assets help",
+        "usage": "image-skill assets <show|get> ASSET_ID_OR_URL --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-assets",
+        "subcommands": ["show", "get"]
+      }
+    },
+    {
+      "key": "assets show",
+      "help": {
+        "command": "image-skill assets show help",
+        "usage": "image-skill assets show ASSET_ID_OR_URL --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-assets"
+      }
+    },
+    {
+      "key": "assets get",
+      "help": {
+        "command": "image-skill assets get help",
+        "usage": "image-skill assets get ASSET_ID_OR_URL --output PATH --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-assets"
+      }
+    },
+    {
+      "key": "jobs",
+      "help": {
+        "command": "image-skill jobs help",
+        "usage": "image-skill jobs <show|wait> JOB_ID --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-jobs",
+        "subcommands": ["show", "wait"]
+      }
+    },
+    {
+      "key": "jobs show",
+      "help": {
+        "command": "image-skill jobs show help",
+        "usage": "image-skill jobs show JOB_ID --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-jobs"
+      }
+    },
+    {
+      "key": "jobs wait",
+      "help": {
+        "command": "image-skill jobs wait help",
+        "usage": "image-skill jobs wait JOB_ID --timeout-ms 30000 --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-jobs"
+      }
+    },
+    {
+      "key": "activity",
+      "help": {
+        "command": "image-skill activity help",
+        "usage": "image-skill activity <list|show> --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-activity",
+        "subcommands": ["list", "show"]
+      }
+    },
+    {
+      "key": "activity list",
+      "help": {
+        "command": "image-skill activity list help",
+        "usage": "image-skill activity list --subject JOB_ID --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-activity"
+      }
+    },
+    {
+      "key": "activity show",
+      "help": {
+        "command": "image-skill activity show help",
+        "usage": "image-skill activity show REFERENCE --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-activity"
+      }
+    },
+    {
+      "key": "feedback",
+      "help": {
+        "command": "image-skill feedback help",
+        "usage": "image-skill feedback create --title TITLE --body BODY --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-feedback",
+        "subcommands": ["create"]
+      }
+    },
+    {
+      "key": "feedback create",
+      "help": {
+        "command": "image-skill feedback create help",
+        "usage": "image-skill feedback create --title TITLE --body BODY --type user_feedback --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-feedback",
+        "optional_flags": [
+          "--title",
+          "--body",
+          "--type",
+          "--severity",
+          "--confidence",
+          "--expected",
+          "--actual",
+          "--command"
+        ]
+      }
+    }
+  ]
+}

package/llms.txt

@@ -119,7 +119,7 @@ Hosted API endpoints:
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-x402-deposits creates a browserless action-required USDC deposit attempt for a stripe_x402.exact.usdc quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, accepted_payment_method: stripe_x402.exact.usdc, live_money, amount_cents, stripe_x402 challenge metadata, stripe_x402.payable_instructions when Stripe returns a Base deposit address, and next.agent_action: pay_stripe_crypto_deposit. A wallet-equipped agent can pay the exact USDC token_amount_atomic to payable_instructions.deposit_address on Base. This does not grant credits; verified settlement/webhook fulfillment grants paid credits exactly once.
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-checkout-sessions creates a Stripe Checkout Session for a stripe_checkout quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, checkout_session_id, checkout_handoff_url, checkout_compact_url, checkout_url, accepted_payment_method: stripe_checkout, and next.human_action: open_checkout_url. Present checkout_handoff_url to humans because it is short and redirects to Stripe; checkout_compact_url is also copy-safe when present. If no handoff URL is available, present the full checkout_url in a code block. Do not remove the Stripe # fragment; Checkout needs it in the browser. Stripe-hosted Checkout may accept operator-provided promotion codes; humans enter them on Stripe, not in the Image Skill CLI. This does not grant credits; verified Stripe webhook fulfillment grants paid credits exactly once.
 - GET https://api.image-skill.com/v1/credit-purchases/status returns durable payment state for Authorization: Bearer TOKEN. Query with exactly one of quote_id, payment_attempt_id, checkout_session_id, or receipt_id. Response includes state, quote, payment_attempt, receipt, credit_event, provider_event, limits, and next.
-- GET https://api.image-skill.com/v1/models returns the public model registry. Query params: available=true returns currently usable executable rows, executable=true returns runtime-wired rows regardless current availability, catalog_only=true returns source-backed catalog-only rows, operation=image.generate|image.edit narrows by operation, and provider=fal|xai|openai narrows by provider. Default list output excludes catalog-only rows so fresh agents see executable candidates first. The response summary includes total, returned, available, executable, cataloged_not_wired, provider split, execution_availability, first_actionable_model_ids, recommended filter commands, and catalog-inclusion flags. For runnable choices require both status: available and execution.model_execution_status: executable; provider-level availability alone is not enough. 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. GET https://api.image-skill.com/v1/models/MODEL_ID returns one model's capability-preserving schema.
+- GET https://api.image-skill.com/v1/models returns the compact public model menu. Query params: available=true returns currently usable executable rows, executable=true returns runtime-wired rows regardless current availability, catalog_only=true returns source-backed catalog-only rows, operation=image.generate|image.edit narrows by operation, provider=fal|xai|openai narrows by provider, and details=true returns the full list with capability schemas. Default list output excludes catalog-only rows and omits parameter schemas so fresh agents see actionable choices first. Each compact row includes show_command; use GET https://api.image-skill.com/v1/models/MODEL_ID or image-skill models show MODEL_ID --json before spending or passing model_parameters. The response summary includes total, returned, available, executable, cataloged_not_wired, provider split, execution_availability, first_actionable_model_ids, recommended filter commands, and catalog-inclusion flags. For runnable choices require both status: available and execution.model_execution_status: executable; provider-level availability alone is not enough. 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.
 - GET https://api.image-skill.com/v1/capabilities returns the hosted capability catalog, normalized controls, model-parameter schemas, auth requirements, and deprecation notices.
 - POST https://api.image-skill.com/v1/create creates or dry-runs bounded free-preview images when Authorization: Bearer TOKEN has quota and the relevant preview grant. Request JSON: prompt, optional model, optional intent, optional aspect_ratio, optional output_count, optional references[] for reference-capable create models, optional model_parameters, optional dry_run, optional max_estimated_usd_per_image, optional accept_unknown_cost. output_count defaults to 1 and must not exceed the selected model's max_outputs_per_request. If model is omitted, hosted defaults are quality-first and the response includes request.selection with the selected capability, defaulted provider-native controls, expected output class, and pricing. Agents should read cost.credit_pricing.credits_required instead of assuming one credit per operation; for output_count greater than 1 this is the total debit across outputs. max_estimated_usd_per_image is a per-image Image Skill debit budget guard, not merely an upstream provider-cost guard. On dry_run responses, cost.credit_pricing.credits_required is the planned live execution debit, while quota.consumed_credits is the actual debit and remains 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, usage debits, or provider execution. references[] items use asset_id, role, index, optional reference_index for element_reference, and optional reference_task for reference_image; do not put URLs in references[].
 - POST https://api.image-skill.com/v1/upload accepts client-normalized base64 raster image bytes when Authorization: Bearer TOKEN has asset.upload. Request JSON: source_kind, filename, remote_origin, mime_type, content_length, sha256, bytes_base64. Do not send local paths, full remote URLs, prompts, tokens, or provider credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Zero-setup durable creative-media CLI for agents (image + video + audio + 3D): guide-first creation, model and cost inspection, owned URLs, JSON recovery, payments, reusable assets, and feedback.",
   "type": "module",
   "private": false,
@@ -23,6 +23,7 @@
     "skill.md",
     "llms.txt",
     "cli.md",
+    "commands.json",
     "skills"
   ],
   "engines": {