image-skill 0.1.13 → 0.1.14

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

@@ -15,7 +15,11 @@ Public contract URLs:
 ## Global Rules
 
 - Every command that agents use must support `--json`.
-- JSON output must use the standard envelope from `https://image-skill.com/llms.txt`.
+- 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://image-skill.com/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.
@@ -48,39 +52,61 @@ Checks thin CLI/client health, hosted service reachability, auth state, local ou
 image-skill doctor --json
 ```
 
+### `image-skill trust`
+
+Returns a no-auth, no-spend evidence packet for tool selection and package
+provenance checks.
+
+```bash
+image-skill 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 Image Skill 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 `image-skill create --guide`.
+
+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.
+
 ### `image-skill signup --agent`
 
 Bootstraps restricted agent access.
 
 ```bash
 image-skill signup --agent \
-  --agent-contact agent-ops@example.com \
+  --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
-  --save \
   --json
 ```
 
-`--save` stores the returned `isk_r_` token in the public CLI config with 0600
-permissions and redacts it from stdout. Use `--show-token` only when the agent
-runtime has a separate secret store and needs the raw token once. Do not paste
-tokens into prompts, logs, issue text, or feedback.
-
-In this preview contract, `--agent-contact` is the accountable contact,
-sponsor, operator, or agent inbox for the restricted agent identity. If no
-individual human is in the loop, use a durable operator/team/agent inbox that
-can receive future claim, billing, or abuse notices. Do not invent a person or
-use a throwaway inbox.
+By default, signup stores the returned `isk_r_` token in the public CLI config
+with 0600 permissions and redacts it from stdout. `--save` remains accepted as
+a compatibility no-op for older instructions. Use `--no-save` only when local
+persistence is intentionally disabled, and use `--show-token --no-save` only
+when the agent runtime has a separate secret store and needs the raw token once.
+Do not paste tokens into prompts, logs, issue text, or feedback.
+
+In this preview contract, `--agent-contact` is an email-shaped durable contact
+inbox for the restricted agent identity, not a requirement to find an
+individual human. Use an agent-owned inbox when available; otherwise use an
+operator, team, or sponsor inbox that can receive future claim, billing, or
+abuse notices. Do not block waiting for a person, invent a person, or use a
+throwaway inbox.
 `example.invalid` addresses are only appropriate inside documented harness or
 proof runs. `--human-email` remains accepted as a compatibility alias for
 `--agent-contact`.
 
-For shell-based agent runtimes, store the token outside prompts and then expose
-it as:
-
-```bash
-export IMAGE_SKILL_TOKEN="isk_r_..."
-```
+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.
 
 If the agent runtime can hand secrets to a command over stdin, avoid exporting
 the token and use `--token-stdin` instead:
@@ -92,6 +118,38 @@ printf '%s\n' "$IMAGE_SKILL_TOKEN" | image-skill usage quota --token-stdin --jso
 `--api-base-url` is an advanced preview/test override; production public agents
 should omit it.
 
+### First Run Sequence
+
+Use the no-spend guide first. It checks health, executable model availability,
+auth/quota when a token already exists, and payment rails, then returns one
+`data.next_command`. Guide mode does not create a signup, provider job,
+dry-run job, payment object, credit debit, or asset.
+
+```bash
+image-skill create --guide --prompt "a compact field camera on a stainless workbench"
+```
+
+Read `data.stage`. If it returns `auth_required`, run `data.next_command` and
+rerun the guide. If it returns `quota_required`, inspect the payment commands
+it provides. If it returns `ready_to_create`, run `data.next_command`.
+
+Manual inspection remains available when the guide asks for it or when a task
+needs deeper capability detail:
+
+```bash
+image-skill trust
+image-skill doctor
+image-skill models list
+image-skill models show openai.gpt-image-2
+image-skill whoami
+image-skill usage quota
+image-skill create --dry-run --prompt "a compact field camera on a stainless workbench"
+```
+
+Use `--show-token` only when the runtime has a separate secret store and needs
+the raw token once. Otherwise prefer saved auth; it keeps tokens out of prompts,
+logs, and shell history.
+
 ### Local Config And Install
 
 Prefer package execution in fresh agent sandboxes:
@@ -113,22 +171,20 @@ npx -y image-skill@latest doctor --json
 
 Saved auth state defaults to
 `${XDG_CONFIG_HOME:-~/.config}/image-skill/config.json`. If that location is
-read-only, set a writable config path before `signup --save`:
+read-only, set a writable config path before `signup`:
 
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
 npx -y image-skill@latest signup --agent \
-  --agent-contact agent-ops@example.com \
+  --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
-  --save \
   --json
 ```
 
 Config write failures return `PUBLIC_CLI_CONFIG_WRITE_FAILED` with a structured
 `error.recovery.suggested_command`. Agents should follow that recovery field,
-then continue with `whoami`, `usage quota`, `models list`, and the requested
-creative flow.
+then rerun `create --guide` for the requested creative flow.
 
 ### `image-skill whoami`
 
@@ -460,6 +516,9 @@ capability-preserving schema for one model.
 ```bash
 image-skill models --json
 image-skill models list --json
+image-skill models list --available --operation image.generate --json
+image-skill models list --available --operation image.edit --json
+image-skill models list --catalog-only --provider fal --json
 image-skill models show MODEL_ID --json
 ```
 
@@ -477,6 +536,17 @@ 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 `summary` with total,
+returned, available, executable, catalog-only, provider split, first actionable
+model ids, recommended filter commands, and full-catalog flags. Use
+`--available` for currently usable executable rows, `--operation
+image.generate` or `--operation image.edit` 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"`.
+
 Image Skill 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
@@ -550,14 +620,26 @@ image-skill capabilities show CAPABILITY_ID --json
 
 ### `image-skill create`
 
-Creates an image or plans a zero-cost dry run.
+Guides, creates, or plans a zero-cost dry run.
+
+Guide the first image path without mutation:
+
+```bash
+image-skill create --guide --prompt "A compact field camera on a stainless workbench" --json
+```
+
+`create --guide` returns `schema: image-skill.create-guide.v1`,
+`stage`, `next_command`, `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.
 
 ```bash
 image-skill create \
   --prompt "A compact field camera on a stainless workbench" \
   --intent explore \
   --aspect-ratio 1:1 \
-  --max-estimated-usd-per-image 0.05 \
+  --max-estimated-usd-per-image 0.07 \
   --json
 ```
 
@@ -571,6 +653,9 @@ 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 `0.05` only when intentionally budget-capping to a lower-cost or
+lower-resolution path; the current no-model quality default needs `0.07` to
+permit the 2k plan.
 
 Preview-compatible richer shape:
 
@@ -680,6 +765,10 @@ and never executes provider controls or consumes credits.
 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 create 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.
 
 Minimum success data:
 
@@ -687,7 +776,7 @@ Minimum success data:
 {
   "job_id": "job_...",
   "capability": {
-    "id": "is.image.generate.preview.v1"
+    "id": "is.image.generate.xai-grok-imagine-image-quality.v1"
   },
   "assets": [
     {
@@ -696,17 +785,17 @@ Minimum success data:
       "mime_type": "image/png",
       "url": "https://media.image-skill.com/a/image_abc123.png",
       "content_length": 333444,
-      "width": 1024,
-      "height": 1024
+      "width": 2048,
+      "height": 2048
     }
   ],
   "cost": {
-    "estimated_usd": 0.05,
+    "estimated_usd": 0.07,
     "credit_pricing": {
       "credit_unit_usd": 0.01,
-      "credits_required": 9,
-      "estimated_provider_cost_usd": 0.05,
-      "estimated_revenue_usd": 0.09,
+      "credits_required": 12,
+      "estimated_provider_cost_usd": 0.07,
+      "estimated_revenue_usd": 0.12,
       "pricing_confidence": "known"
     }
   },
@@ -721,14 +810,14 @@ Minimum success data:
       },
       "model_parameters": {
         "keys": ["resolution"],
-        "defaults_applied": ["resolution=1k"],
+        "defaults_applied": ["resolution=2k"],
         "source": "default_policy"
       },
       "output": {
-        "resolution_class": "1k",
+        "resolution_class": "2k",
         "expected_width": null,
         "expected_height": null,
-        "expected_min_short_edge": 1024
+        "expected_min_short_edge": 2048
       }
     }
   },
@@ -762,10 +851,7 @@ curl -sS https://api.image-skill.com/v1/create \
     "intent": "explore",
     "aspect_ratio": "1:1",
     "output_count": 1,
-    "max_estimated_usd_per_image": 0.05,
-    "model_parameters": {
-      "seed": 1234
-    }
+    "max_estimated_usd_per_image": 0.07
   }'
 ```
 
@@ -1117,27 +1203,32 @@ 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`                            |
-| `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`                    |
+| 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      | An authenticated create 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 create
+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 `image-skill feedback create --json` with the event ID

package/skills/image-skill/references/llms.txt

@@ -38,6 +38,9 @@ Primary public surfaces:
 - Hosted API: https://api.image-skill.com for generation, editing, jobs, activity, storage, telemetry, identity, quota, and feedback
 - Hosted artifacts: prefer Image Skill-owned asset URLs such as https://media.image-skill.com/... when returned in assets[].url
 
+Output rule:
+JSON is the default public CLI output. --json is accepted for compatibility and explicitness, but it is not required on every command.
+
 Actor types:
 - human: sponsor, admin, billing, or claim actor
 - agent: durable agent identity
@@ -51,30 +54,30 @@ Claim states:
 - revoked: token or agent disabled
 
 First-run flow:
-1. image-skill doctor --json
-2. image-skill models list --json and image-skill models show MODEL_ID --json to inspect available creative models, operations, media inputs/outputs, model parameters, fixed controls, cost/latency class, safety behavior, and migration hints before choosing a provider.
-3. image-skill signup --agent --agent-contact EMAIL --agent-name NAME --runtime RUNTIME --save --json. The preview hosted signup path uses --agent-contact as the accountable contact, sponsor, operator, or agent inbox for the restricted agent identity. If no individual human is in the loop, use a durable operator/team/agent inbox that can receive future claim, billing, or abuse notices; do not invent a person or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias. Use --show-token only when the runtime has a separate secret store and needs the raw token once.
-4. Reuse the saved CLI auth for later commands, or store the returned data.token from --show-token in the agent runtime secret store and expose it as IMAGE_SKILL_TOKEN.
-5. image-skill whoami --json
-6. image-skill usage quota --json
-6-credit-note. One Image Skill credit is $0.01. Credit quotes grant prepaid value units; create/edit operations debit model-priced credits reported as cost.credit_pricing. Starter preview currently gives bounded free-preview credits plus a two-job daily cap.
+1. image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint. It performs read-only hosted reachability, model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
+2. If data.stage is prompt_required, rerun data.next_command with the real prompt.
+3. If data.stage is auth_required, run data.next_command. The signup command uses --agent-contact as an email-shaped durable contact inbox for the restricted agent identity, not as a requirement to find an individual human. It saves CLI auth by default so later commands can authenticate without a token handoff. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. --save remains accepted as a compatibility no-op, but the guide must not teach it. Use --no-save only when local persistence is intentionally disabled, and use --show-token --no-save only when the runtime has a separate secret store and needs the raw token once.
+4. Reuse the saved CLI auth for later commands. If the runtime needs the raw token once, store the returned data.token from --show-token --no-save in the agent runtime secret store and expose it as IMAGE_SKILL_TOKEN or pass it with --token-stdin.
+5. Rerun image-skill create --guide --prompt PROMPT after signup or payment changes. The guide should advance to ready_to_create once auth, quota, executable model selection, and budget guard are sufficient.
+6. If data.stage is quota_required, inspect data.checks.payments.suggested_commands. One Image Skill credit is $0.01. Credit quotes grant prepaid value units; create/edit operations debit model-priced credits reported as cost.credit_pricing. Starter preview currently gives bounded free-preview credits plus a two-job daily cap.
 6a. image-skill credits methods --json to inspect payment rails, availability, buyer modes, browser requirements, and recovery commands before quoting or buying.
 6b. image-skill credits packs list --json to inspect recommended live-money packs.
 6c. image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json for the default Stripe Checkout top-up path. Use --credits CREDITS instead of --pack only when the required exact budget is already known.
 6d. image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json when the agent has a stripe_checkout quote and needs a payment handoff. Present or open checkout_handoff_url for humans; 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. Credits are granted only after verified Stripe webhook fulfillment succeeds.
 6e. image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy or checkout completion to read durable payment state, receipt, credit_event, limits, and retry guidance without inferring from quota text.
-7. image-skill create --dry-run --prompt PROMPT --json for zero-cost planning.
-8. image-skill create --prompt PROMPT --intent explore --max-estimated-usd-per-image 0.05 --json for the first bounded free-preview operation when quota allows. Add --output-count N only after models show confirms the selected create model supports more than one output; credit_pricing.credits_required is the total debit across outputs, while max_estimated_usd_per_image remains a per-image guard.
-9. image-skill jobs show JOB_ID --json to recover status, cost, safety, timestamps, and final assets.
-10. image-skill assets get ASSET_URL_OR_ID --output ./result.png --json to fetch the generated asset without repeating provider work.
-11. image-skill activity list --subject JOB_ID --json to find the ledger event, trace, usage, and asset links to cite.
-12. image-skill edit --input ASSET_URL_OR_ID --prompt PROMPT --accept-unknown-cost --json for the second bounded free-preview operation when the task needs an edit.
-13. Leave image-skill feedback create --json if the first-run flow is confusing, blocked, missing an affordance, or easier through a direct provider than through Image Skill.
-14. image-skill activity show FEEDBACK_ID --json to confirm the feedback entered the hosted ledger.
+7. If data.stage is ready_to_create, run data.next_command for the first bounded create. Use 0.05 only when intentionally budget-capping to a lower-cost/lower-resolution path; the quality-default first create generally needs the guide's returned max_estimated_usd_per_image. Add --output-count N only after models show confirms the selected create model supports more than one output; credit_pricing.credits_required is the total debit across outputs, while max_estimated_usd_per_image remains a per-image guard.
+8. Use image-skill create --dry-run --prompt PROMPT for explicit zero-cost planning when you need the dry-run receipt before live create.
+9. Use image-skill doctor, image-skill models list, image-skill models show MODEL_ID, image-skill whoami, and image-skill usage quota as manual escape hatches when the guide returns them or when capability details matter.
+10. image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets.
+11. image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work.
+12. image-skill activity list --subject JOB_ID to find the ledger event, trace, usage, and asset links to cite.
+13. image-skill edit --input ASSET_URL_OR_ID --prompt PROMPT --accept-unknown-cost for the second bounded free-preview operation when the task needs an edit.
+14. Leave image-skill feedback create if the first-run flow is confusing, blocked, missing an affordance, or easier through a direct provider than through Image Skill.
+15. image-skill activity show FEEDBACK_ID to confirm the feedback entered the hosted ledger.
 
 Core commands:
 - image-skill doctor --json
-- image-skill signup --agent --agent-contact EMAIL --agent-name NAME --runtime RUNTIME --save --json
+- image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json
 - image-skill whoami --json
 - image-skill usage quota --json
 - image-skill quota --json (compatibility alias)
@@ -89,7 +92,11 @@ Core commands:
 - image-skill capabilities show CAPABILITY_ID --json
 - image-skill models --json
 - image-skill models list --json
+- image-skill models list --available --operation image.generate --json
+- image-skill models list --available --operation image.edit --json
+- image-skill models list --catalog-only --provider fal --json
 - image-skill models show MODEL_ID --json
+- image-skill create --guide --prompt PROMPT --json
 - image-skill create --prompt PROMPT --json
 - image-skill create --prompt PROMPT --output-count N --json
 - image-skill create --model fal.kling-image-o3-text-to-image --prompt PROMPT --element-frontal IMAGE_OR_ASSET[@ELEMENT_INDEX] --element-reference IMAGE_OR_ASSET[@ELEMENT_INDEX[:REFERENCE_INDEX]] --json
@@ -106,7 +113,7 @@ Core commands:
 - image-skill feedback create --type TYPE --title TITLE --body BODY --command COMMAND --expected EXPECTED --actual ACTUAL --proof-needed PROOF --surface cli,docs --evidence trace:TRACE_ID --severity medium --confidence high --next-state watch --json
 
 Hosted API endpoints:
-- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. Raw API request human_email is the compatibility contact field; CLI agents should prefer --agent-contact. The contact is not a requirement that an autonomous agent stop until a specific human is present. The response returns the token once as data.token. Store it in the agent runtime secret store; never put it in prompts, logs, issue text, or feedback.
+- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. Raw API request human_email is the legacy compatibility contact field; CLI agents should prefer --agent-contact. The preview hosted API currently expects an email-shaped durable contact inbox, but the contact is not a requirement that an autonomous agent stop until a specific human is present. The response returns the token once as data.token. Store it in the agent runtime secret store; never put it in prompts, logs, issue text, or feedback.
 - GET https://api.image-skill.com/v1/whoami returns durable hosted identity for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/quota returns durable hosted quota for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/payment-methods returns the no-auth action-only payment rail catalog. It tells agents which currently usable rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, limits, endpoint paths, and recovery commands. Planned, watch-only, fake, and private harness rails are intentionally omitted.
@@ -114,16 +121,16 @@ Hosted API endpoints:
 - POST https://api.image-skill.com/v1/credit-quotes returns a stripe_checkout credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, and live_money. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
 - 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. 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 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. The response summary includes total, returned, available, executable, cataloged_not_wired, provider split, first_actionable_model_ids, recommended filter commands, and full_catalog flags. For runnable choices require both status: available and execution.model_execution_status: executable; provider-level availability alone is not enough. GET https://api.image-skill.com/v1/models/MODEL_ID returns one model's capability-preserving schema.
 - 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 remains a per-image budget 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. 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/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 remains a per-image budget 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.
 - POST https://api.image-skill.com/v1/edit edits an Image Skill-owned input asset when Authorization: Bearer TOKEN has quota and the relevant preview grant. Request JSON: input_asset_id, prompt, optional mask_asset_id for mask-capable models, optional references[] for reference-capable models, optional model, optional intent, optional aspect_ratio, optional output constraints, optional model_parameters, optional max_estimated_usd_per_image, optional max_usd, optional accept_unknown_cost. 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[]. 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, Fal DreamO create, and xAI Grok Imagine image edit/quality edit. Kling references allow max 40 entries, max 10 contiguous element indexes from 0, one frontal per referenced element, and up to 3 reference images per element. DreamO references allow up to two contiguous reference_image indexes from 0, each with optional reference_task ip, id, or style. xAI edit references allow up to two contiguous reference_image indexes from 0 and do not accept reference_task; the primary input asset is the first source image. Reference assets must be owned PNG/JPEG/WebP, 10MB max, minimum 300px width/height, and aspect ratio 0.40-2.50. The public CLI uploads local paths or external URLs first for --input, --mask, --element-frontal, --element-reference, and --reference-image; do not send source bytes, external URLs, image_url, image_urls, mask_url, raw provider elements, frontal_image_url, reference_image_urls, first_image_url, second_image_url, images, or *_reference_task to /v1/edit or /v1/create. For Kling elements, --element-frontal IMAGE[@ELEMENT_INDEX] sends role element_frontal and --element-reference IMAGE[@ELEMENT_INDEX[:REFERENCE_INDEX]] sends role element_reference under top-level references[]. For DreamO create, --reference-image IMAGE[@INDEX[:TASK]] sends role reference_image with optional reference_task. For xAI edit, --reference-image IMAGE[@INDEX] supplies the second or third ordered source image.
 - GET https://api.image-skill.com/v1/assets/ASSET_ID returns hosted asset metadata for Authorization: Bearer TOKEN when the asset belongs to the actor organization.
 - GET https://api.image-skill.com/v1/jobs/JOB_ID returns hosted job metadata for Authorization: Bearer TOKEN when the job belongs to the actor organization.
 - GET https://api.image-skill.com/v1/activity returns hosted activity ledger events for Authorization: Bearer TOKEN. Optional query: limit, subject. Activity is for ledger context, not job recovery.
 - GET https://api.image-skill.com/v1/activity/REFERENCE returns hosted activity events related to one event, job, asset, usage, feedback, or trace reference.
-- Public activity event types are: job.completed, asset.created, asset.uploaded, usage.credit_consumed, feedback.created, feedback.github_queue.processed, payment.checkout_session.created, credits.payment_backed_granted, credits.payment_backed_refunded, credits.payment_backed_disputed, credits.payment_backed_reinstated, credits.payment_backed_reversal_pending, credits.payment_backed_reversal_rejected. Treat any other activity type as a contract bug and leave feedback with event ID plus trace ID.
+- Public activity event types are: job.completed, job.planned, asset.created, asset.uploaded, usage.credit_consumed, feedback.created, feedback.github_queue.processed, payment.checkout_session.created, credits.payment_backed_granted, credits.payment_backed_refunded, credits.payment_backed_disputed, credits.payment_backed_reinstated, credits.payment_backed_reversal_pending, credits.payment_backed_reversal_rejected. job.planned includes details.plan_receipt for authenticated hosted create dry-runs and is a planning receipt, not completed media work. Treat any other activity type as a contract bug and leave feedback with event ID plus trace ID.
 - POST https://api.image-skill.com/v1/cli runs public CLI-compatible commands over JSON argv.
 - GET https://api.image-skill.com/healthz checks API readiness.
 
@@ -188,7 +195,7 @@ Unclaimed agents may not:
 - send card data, wallet secrets, wallet private keys, seed phrases, raw x402 payment headers, provider receipts, Stripe secrets, MPP tokens, SPTs, bearer tokens, or any payment credential to Image Skill; Stripe payment details must be entered only on Stripe-hosted checkout pages
 
 Credits:
-One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability and whether a browser/human action is required. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --payment-method stripe_checkout --json for exact bounded custom top-ups when the required budget is already known. Use image-skill credits buy --provider stripe --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_handoff_url, copy-safe checkout_compact_url, and full Stripe checkout_url fallback and does not grant credits. Present checkout_handoff_url or checkout_compact_url to humans, especially in mobile terminals, SSH, or chat. If checkout_handoff_url is absent, present the full checkout_url in a code block and preserve the Stripe # fragment. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Do not silently downgrade to the cheapest model to avoid payment when the user asked for quality or is willing to pay; quote the needed credits and use the payment handoff. Credits buy requires explicit --idempotency-key. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; use per-run/per-step quote keys and inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
+One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability and whether a browser/human action is required. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --idempotency-key KEY --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --payment-method stripe_checkout --idempotency-key KEY --json for exact bounded custom top-ups when the required budget is already known. Use image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_handoff_url, copy-safe checkout_compact_url, and full Stripe checkout_url fallback and does not grant credits. Present checkout_handoff_url or checkout_compact_url to humans, especially in mobile terminals, SSH, or chat. If checkout_handoff_url is absent, present the full checkout_url in a code block and preserve the Stripe # fragment. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Do not silently downgrade to the cheapest model to avoid payment when the user asked for quality or is willing to pay; quote the needed credits and use the payment handoff. Credits buy requires explicit --idempotency-key. Quote idempotency keys are scoped to the hosted agent identity and exact quote terms; use per-run/per-step quote keys and inspect error.recovery.suggested_command on CREDIT_QUOTE_CONFLICT. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
 
 Telemetry:
 - command or endpoint name
@@ -211,15 +218,23 @@ auditable event IDs, feedback confirmation, usage links, job/asset links, or
 trace references. Activity is broader than jobs and can include completed
 outputs, uploads, usage events, and feedback. Activity does not replace jobs
 show/wait for polling, recovery, retry judgment, or final job state.
-Current activity event registry: job.completed, asset.created, asset.uploaded,
-usage.credit_consumed, feedback.created, feedback.github_queue.processed,
-payment.checkout_session.created, credits.payment_backed_granted,
-credits.payment_backed_refunded, credits.payment_backed_disputed,
-credits.payment_backed_reinstated, credits.payment_backed_reversal_pending,
-credits.payment_backed_reversal_rejected.
+Current activity event registry: job.completed, job.planned, asset.created,
+asset.uploaded, usage.credit_consumed, feedback.created,
+feedback.github_queue.processed, payment.checkout_session.created,
+credits.payment_backed_granted, credits.payment_backed_refunded,
+credits.payment_backed_disputed, credits.payment_backed_reinstated,
+credits.payment_backed_reversal_pending, credits.payment_backed_reversal_rejected.
 Feedback GitHub queue lifecycle events expose `details.github_queue.state`,
 `reason`, and public issue references when available, so agents can tell what
 happened to submitted feedback without inspecting private Actions artifacts.
+`job.planned` exposes `details.plan_receipt` for authenticated hosted create
+dry-runs; it does not mean assets were generated, credits were consumed, or a
+provider was called.
+`models list --available --operation image.generate --json` is the fastest
+manual escape hatch for runnable create choices. Use
+`models list --available --operation image.edit --json` for runnable edit
+choices. Use `models list --catalog-only --json` only when you intentionally
+want inspectable rows that Image Skill does not execute yet.
 
 Feedback:
 Use image-skill feedback create --json when the workflow fails, succeeds with friction, reveals confusing behavior, or suggests a missing feature. Feedback should include command, expected behavior, actual behavior, proof needed, surface, evidence, severity, confidence, and next state.