image-skill 0.1.12 → 0.1.14

package/skill.md

@@ -78,18 +78,42 @@ provider API because Image Skill was missing something, submit feedback with:
 
 ## First Run
 
-The whole happy path is two commands — sign up once, then create:
+JSON is the default output for the public CLI. `--json` remains accepted for
+compatibility, but fresh agents do not need to add it to every command.
+
+Start with the no-spend guide. It checks hosted reachability, executable model
+availability, auth/quota state when credentials already exist, payment rail
+availability, and returns exactly one next command. Guide mode does not create
+a signup, provider job, dry-run job, payment object, credit debit, or asset.
 
 ```bash
-npx -y image-skill signup --agent --agent-contact YOUR_INBOX --agent-name NAME --runtime codex --show-token
-export IMAGE_SKILL_TOKEN=isk_...   # the token printed above; every later command reads it automatically
-npx -y image-skill create "a compact field camera on a stainless workbench"
+npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-That returns a durable owned image URL. JSON is the default output and high-res
-is the default quality — `--json` is accepted as a no-op, not required.
-Everything below is optional depth: skill install, health checks, model
-inspection, and spend controls.
+Read `data.stage`, `data.next_command`, and `data.mutation`. If the guide
+returns `auth_required`, run the signup command it gives you, then rerun the
+same guide. If it returns `quota_required`, inspect the payment commands it
+gives you and hand the Stripe link to a human sponsor. If it returns
+`ready_to_create`, run `data.next_command` for the bounded create.
+
+Use the lower-level inspection commands when the guide asks for them or when
+you need capability details before spending:
+
+```bash
+npx -y image-skill@latest doctor
+npx -y image-skill@latest models list --available --operation image.generate
+npx -y image-skill@latest models show openai.gpt-image-2
+npx -y image-skill@latest signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime codex
+npx -y image-skill@latest whoami
+npx -y image-skill@latest usage quota
+npx -y image-skill@latest create --dry-run --prompt "a compact field camera on a stainless workbench"
+npx -y image-skill@latest create --prompt "a compact field camera on a stainless workbench" --intent explore --max-estimated-usd-per-image 0.07
+```
+
+That returns durable owned media URLs, a recoverable job, cost receipts, and
+capability-preserving model metadata. Everything below is optional depth:
+skill install, writable config recovery, payment handoff, advanced model
+parameters, asset recovery, jobs, activity, and feedback.
 
 Install the agent-facing skill from the hosted public contract when the runtime
 supports skills.sh-compatible installation:
@@ -108,7 +132,7 @@ Run the executable CLI from npm without relying on a writable global npm
 prefix:
 
 ```bash
-npx -y image-skill@latest doctor --json
+npx -y image-skill@latest doctor
 ```
 
 For repeated shell use, use global package linking only after confirming the
@@ -119,39 +143,40 @@ home is read-only.
 Check service and client health:
 
 ```bash
-image-skill doctor --json
+image-skill doctor
 ```
 
 Inspect models before committing to a provider or model-specific parameter:
 
 ```bash
-image-skill models list --json
-image-skill models show openai.gpt-image-2 --json
-image-skill models show openai.gpt-image-1.5 --json
+image-skill models list
+image-skill models show openai.gpt-image-2
+image-skill models show openai.gpt-image-1.5
 ```
 
-Bootstrap restricted agent access:
+Bootstrap restricted agent access; auth is saved by default for later commands:
 
 ```bash
 image-skill signup --agent \
-  --agent-contact CONTACT_OR_SPONSOR_INBOX \
+  --agent-contact AGENT_OR_OPERATOR_INBOX \
   --agent-name AGENT_NAME \
-  --runtime RUNTIME_NAME \
-  --show-token \
-  --json
+  --runtime RUNTIME_NAME
 ```
 
-Hosted signup returns your token once. Put it in `IMAGE_SKILL_TOKEN` (your
-runtime's secret store or environment) and every later command authenticates
-automatically — you sign up once and then just run commands, with no token to
-pass and no config file to manage. If you do pass the token explicitly, prefer
-`--token-stdin` over `--token` so it never lands in shell history.
-
-In the preview contract, `--agent-contact` means 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.
+Saved auth lets every later command authenticate automatically — you sign up
+once and then just run commands, with no token to pass in prompts or shell
+history. `--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 runtime has a separate
+secret store and needs the raw token once. If you do pass the token explicitly,
+prefer `--token-stdin` over `--token`.
+
+In the preview contract, `--agent-contact` means 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`.
@@ -162,29 +187,29 @@ placing the token in command args.
 
 ## Local Config And Install
 
-Your hosted token lives in `IMAGE_SKILL_TOKEN`, not on disk, so a read-only home
-or npm prefix never blocks you. Run the published package directly and keep the
-token in the environment:
+Run the published package directly; do not clone private source because a global
+install or default config directory is blocked. Saved auth state defaults to the
+user config directory. If that location is read-only, point
+`IMAGE_SKILL_CONFIG_PATH` at a writable persistent path before `signup`:
 
 ```bash
+export IMAGE_SKILL_CONFIG_PATH="$PWD/image-skill-config.json"
 npx -y image-skill@latest signup --agent \
-  --agent-contact CONTACT_OR_SPONSOR_INBOX \
+  --agent-contact AGENT_OR_OPERATOR_INBOX \
   --agent-name AGENT_NAME \
-  --runtime RUNTIME_NAME \
-  --show-token --json
-# copy the returned token, then:
-export IMAGE_SKILL_TOKEN=isk_...
-npx -y image-skill@latest whoami --json
+  --runtime RUNTIME_NAME
+npx -y image-skill@latest whoami
 ```
 
 Do not fall back to another tool because a global install or the default config
-directory is blocked — the hosted path above needs neither.
+directory is blocked. Follow the CLI's structured recovery command and continue
+with `whoami`, `usage quota`, `models list`, and the requested creative flow.
 
 Inspect identity and quota:
 
 ```bash
-image-skill whoami --json
-image-skill usage quota --json
+image-skill whoami
+image-skill usage quota
 ```
 
 The preview hosted signup path currently uses the agent-contact inbox above.
@@ -202,7 +227,11 @@ image-skill credits quote \
   --payment-method stripe_checkout \
   --idempotency-key stripe-pack-quote-run-001 \
   --json
-image-skill credits quote --credits 137 --json
+image-skill credits quote \
+  --credits 137 \
+  --payment-method stripe_checkout \
+  --idempotency-key exact-quote-run-001 \
+  --json
 image-skill credits buy \
   --provider stripe \
   --quote-id QUOTE_ID \
@@ -210,14 +239,16 @@ image-skill credits buy \
   --json
 ```
 
-This is the agent-facing precursor to future MPP, live x402, wallet, or
-delegated-card adapters. Packs are the default Stripe Checkout UX; exact
+The public top-up path is Stripe Checkout. Future MPP, live x402, wallet, and
+delegated-card adapters remain private/canary until they are explicitly listed
+by `credits methods --json`. Packs are the default Stripe Checkout UX; exact
 `--credits` quotes remain available when an agent already knows the required
 budget. `credits methods --json` tells agents which rails are currently
 available, which buyer modes they support, and whether browser/human action is
-required before an agent tries to quote or buy. `credits buy --provider stripe`
-returns `checkout_handoff_url` for humans, `checkout_compact_url` as the
-copy-safe handoff, and full Stripe `checkout_url` only as a fallback for a
+required before an agent tries to quote or buy. `credits buy --provider stripe
+--quote-id QUOTE_ID --idempotency-key KEY --json` returns
+`checkout_handoff_url` for humans, `checkout_compact_url` as the copy-safe
+handoff, and full Stripe `checkout_url` only as a fallback for a
 `stripe_checkout` quote. It does not grant credits until verified webhook
 fulfillment succeeds. Present or open `checkout_handoff_url` first. If it is
 absent, present the full `checkout_url` in a code block; do not remove the
@@ -235,12 +266,20 @@ Inspect models first, especially when choosing between OpenAI, Fal, xAI, and
 future providers:
 
 ```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 openai.gpt-image-2 --json
 image-skill models show openai.gpt-image-1.5 --json
 ```
 
+Use `--available --operation image.generate` when you need a runnable create
+choice and `--available --operation image.edit` when you need a runnable edit
+choice. `--available` means both `status:"available"` and
+`execution.model_execution_status:"executable"`. The full catalog remains
+inspectable; `--catalog-only` shows source-backed rows that are useful for
+research but not runnable yet.
+
 `models show` is the first detailed discovery surface for agents. It exposes
 operations, media inputs/outputs, model-parameter schemas, fixed and wired
 controls, cost/latency class, safety behavior, and migration hints. Use
@@ -258,7 +297,7 @@ image-skill create \
   --prompt "A product mockup of 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
 ```
 
@@ -322,7 +361,7 @@ Hosted free-preview API:
 curl -sS https://api.image-skill.com/v1/create \
   -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
   -H "content-type: application/json" \
-  -d '{"prompt":"A product mockup of a compact field camera on a stainless workbench","intent":"explore","aspect_ratio":"1:1","output_count":1,"max_estimated_usd_per_image":0.05,"model_parameters":{"seed":1234}}'
+  -d '{"prompt":"A product mockup of a compact field camera on a stainless workbench","intent":"explore","aspect_ratio":"1:1","output_count":1,"max_estimated_usd_per_image":0.07}'
 ```
 
 Expected behavior:
@@ -521,13 +560,15 @@ closed if durable hosted feedback storage is unavailable.
 - Use `credits packs list --json` to inspect recommended live-money packs.
 - Use `credits quote --pack PACK_ID --payment-method stripe_checkout --json`
   for the default Stripe Checkout path.
-- Use `credits quote --credits CREDITS --json` for exact bounded custom
-  top-ups when the required budget is already known.
-- Use `credits buy --provider stripe --json` only to create a Stripe-hosted
-  checkout action. Present `checkout_handoff_url` to humans; if it is absent,
-  present the full `checkout_url` in a code block. Do not remove the
-  Stripe `#...` fragment; Checkout needs it in the browser. Session creation
-  itself does not grant credits.
+- Use `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 `credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY
+--json` only to create a Stripe-hosted checkout action. Present
+  `checkout_handoff_url` to humans; if it is absent, present the full
+  `checkout_url` in a code block. Do not remove the Stripe `#...` fragment;
+  Checkout needs it in the browser. Session creation itself does not grant
+  credits.
 - Never pass live x402 payment headers, wallet private keys, seed phrases,
   bearer tokens, Stripe secrets, provider keys, card data, or provider receipts
   to Image Skill.

package/skills/image-skill/SKILL.md

@@ -78,18 +78,42 @@ provider API because Image Skill was missing something, submit feedback with:
 
 ## First Run
 
-The whole happy path is two commands — sign up once, then create:
+JSON is the default output for the public CLI. `--json` remains accepted for
+compatibility, but fresh agents do not need to add it to every command.
+
+Start with the no-spend guide. It checks hosted reachability, executable model
+availability, auth/quota state when credentials already exist, payment rail
+availability, and returns exactly one next command. Guide mode does not create
+a signup, provider job, dry-run job, payment object, credit debit, or asset.
 
 ```bash
-npx -y image-skill signup --agent --agent-contact YOUR_INBOX --agent-name NAME --runtime codex --show-token
-export IMAGE_SKILL_TOKEN=isk_...   # the token printed above; every later command reads it automatically
-npx -y image-skill create "a compact field camera on a stainless workbench"
+npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-That returns a durable owned image URL. JSON is the default output and high-res
-is the default quality — `--json` is accepted as a no-op, not required.
-Everything below is optional depth: skill install, health checks, model
-inspection, and spend controls.
+Read `data.stage`, `data.next_command`, and `data.mutation`. If the guide
+returns `auth_required`, run the signup command it gives you, then rerun the
+same guide. If it returns `quota_required`, inspect the payment commands it
+gives you and hand the Stripe link to a human sponsor. If it returns
+`ready_to_create`, run `data.next_command` for the bounded create.
+
+Use the lower-level inspection commands when the guide asks for them or when
+you need capability details before spending:
+
+```bash
+npx -y image-skill@latest doctor
+npx -y image-skill@latest models list --available --operation image.generate
+npx -y image-skill@latest models show openai.gpt-image-2
+npx -y image-skill@latest signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime codex
+npx -y image-skill@latest whoami
+npx -y image-skill@latest usage quota
+npx -y image-skill@latest create --dry-run --prompt "a compact field camera on a stainless workbench"
+npx -y image-skill@latest create --prompt "a compact field camera on a stainless workbench" --intent explore --max-estimated-usd-per-image 0.07
+```
+
+That returns durable owned media URLs, a recoverable job, cost receipts, and
+capability-preserving model metadata. Everything below is optional depth:
+skill install, writable config recovery, payment handoff, advanced model
+parameters, asset recovery, jobs, activity, and feedback.
 
 Install the agent-facing skill from the hosted public contract when the runtime
 supports skills.sh-compatible installation:
@@ -108,7 +132,7 @@ Run the executable CLI from npm without relying on a writable global npm
 prefix:
 
 ```bash
-npx -y image-skill@latest doctor --json
+npx -y image-skill@latest doctor
 ```
 
 For repeated shell use, use global package linking only after confirming the
@@ -119,39 +143,40 @@ home is read-only.
 Check service and client health:
 
 ```bash
-image-skill doctor --json
+image-skill doctor
 ```
 
 Inspect models before committing to a provider or model-specific parameter:
 
 ```bash
-image-skill models list --json
-image-skill models show openai.gpt-image-2 --json
-image-skill models show openai.gpt-image-1.5 --json
+image-skill models list
+image-skill models show openai.gpt-image-2
+image-skill models show openai.gpt-image-1.5
 ```
 
-Bootstrap restricted agent access:
+Bootstrap restricted agent access; auth is saved by default for later commands:
 
 ```bash
 image-skill signup --agent \
-  --agent-contact CONTACT_OR_SPONSOR_INBOX \
+  --agent-contact AGENT_OR_OPERATOR_INBOX \
   --agent-name AGENT_NAME \
-  --runtime RUNTIME_NAME \
-  --show-token \
-  --json
+  --runtime RUNTIME_NAME
 ```
 
-Hosted signup returns your token once. Put it in `IMAGE_SKILL_TOKEN` (your
-runtime's secret store or environment) and every later command authenticates
-automatically — you sign up once and then just run commands, with no token to
-pass and no config file to manage. If you do pass the token explicitly, prefer
-`--token-stdin` over `--token` so it never lands in shell history.
-
-In the preview contract, `--agent-contact` means 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.
+Saved auth lets every later command authenticate automatically — you sign up
+once and then just run commands, with no token to pass in prompts or shell
+history. `--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 runtime has a separate
+secret store and needs the raw token once. If you do pass the token explicitly,
+prefer `--token-stdin` over `--token`.
+
+In the preview contract, `--agent-contact` means 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`.
@@ -162,29 +187,29 @@ placing the token in command args.
 
 ## Local Config And Install
 
-Your hosted token lives in `IMAGE_SKILL_TOKEN`, not on disk, so a read-only home
-or npm prefix never blocks you. Run the published package directly and keep the
-token in the environment:
+Run the published package directly; do not clone private source because a global
+install or default config directory is blocked. Saved auth state defaults to the
+user config directory. If that location is read-only, point
+`IMAGE_SKILL_CONFIG_PATH` at a writable persistent path before `signup`:
 
 ```bash
+export IMAGE_SKILL_CONFIG_PATH="$PWD/image-skill-config.json"
 npx -y image-skill@latest signup --agent \
-  --agent-contact CONTACT_OR_SPONSOR_INBOX \
+  --agent-contact AGENT_OR_OPERATOR_INBOX \
   --agent-name AGENT_NAME \
-  --runtime RUNTIME_NAME \
-  --show-token --json
-# copy the returned token, then:
-export IMAGE_SKILL_TOKEN=isk_...
-npx -y image-skill@latest whoami --json
+  --runtime RUNTIME_NAME
+npx -y image-skill@latest whoami
 ```
 
 Do not fall back to another tool because a global install or the default config
-directory is blocked — the hosted path above needs neither.
+directory is blocked. Follow the CLI's structured recovery command and continue
+with `whoami`, `usage quota`, `models list`, and the requested creative flow.
 
 Inspect identity and quota:
 
 ```bash
-image-skill whoami --json
-image-skill usage quota --json
+image-skill whoami
+image-skill usage quota
 ```
 
 The preview hosted signup path currently uses the agent-contact inbox above.
@@ -202,7 +227,11 @@ image-skill credits quote \
   --payment-method stripe_checkout \
   --idempotency-key stripe-pack-quote-run-001 \
   --json
-image-skill credits quote --credits 137 --json
+image-skill credits quote \
+  --credits 137 \
+  --payment-method stripe_checkout \
+  --idempotency-key exact-quote-run-001 \
+  --json
 image-skill credits buy \
   --provider stripe \
   --quote-id QUOTE_ID \
@@ -210,14 +239,16 @@ image-skill credits buy \
   --json
 ```
 
-This is the agent-facing precursor to future MPP, live x402, wallet, or
-delegated-card adapters. Packs are the default Stripe Checkout UX; exact
+The public top-up path is Stripe Checkout. Future MPP, live x402, wallet, and
+delegated-card adapters remain private/canary until they are explicitly listed
+by `credits methods --json`. Packs are the default Stripe Checkout UX; exact
 `--credits` quotes remain available when an agent already knows the required
 budget. `credits methods --json` tells agents which rails are currently
 available, which buyer modes they support, and whether browser/human action is
-required before an agent tries to quote or buy. `credits buy --provider stripe`
-returns `checkout_handoff_url` for humans, `checkout_compact_url` as the
-copy-safe handoff, and full Stripe `checkout_url` only as a fallback for a
+required before an agent tries to quote or buy. `credits buy --provider stripe
+--quote-id QUOTE_ID --idempotency-key KEY --json` returns
+`checkout_handoff_url` for humans, `checkout_compact_url` as the copy-safe
+handoff, and full Stripe `checkout_url` only as a fallback for a
 `stripe_checkout` quote. It does not grant credits until verified webhook
 fulfillment succeeds. Present or open `checkout_handoff_url` first. If it is
 absent, present the full `checkout_url` in a code block; do not remove the
@@ -235,12 +266,20 @@ Inspect models first, especially when choosing between OpenAI, Fal, xAI, and
 future providers:
 
 ```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 openai.gpt-image-2 --json
 image-skill models show openai.gpt-image-1.5 --json
 ```
 
+Use `--available --operation image.generate` when you need a runnable create
+choice and `--available --operation image.edit` when you need a runnable edit
+choice. `--available` means both `status:"available"` and
+`execution.model_execution_status:"executable"`. The full catalog remains
+inspectable; `--catalog-only` shows source-backed rows that are useful for
+research but not runnable yet.
+
 `models show` is the first detailed discovery surface for agents. It exposes
 operations, media inputs/outputs, model-parameter schemas, fixed and wired
 controls, cost/latency class, safety behavior, and migration hints. Use
@@ -258,7 +297,7 @@ image-skill create \
   --prompt "A product mockup of 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
 ```
 
@@ -322,7 +361,7 @@ Hosted free-preview API:
 curl -sS https://api.image-skill.com/v1/create \
   -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
   -H "content-type: application/json" \
-  -d '{"prompt":"A product mockup of a compact field camera on a stainless workbench","intent":"explore","aspect_ratio":"1:1","output_count":1,"max_estimated_usd_per_image":0.05,"model_parameters":{"seed":1234}}'
+  -d '{"prompt":"A product mockup of a compact field camera on a stainless workbench","intent":"explore","aspect_ratio":"1:1","output_count":1,"max_estimated_usd_per_image":0.07}'
 ```
 
 Expected behavior:
@@ -521,13 +560,15 @@ closed if durable hosted feedback storage is unavailable.
 - Use `credits packs list --json` to inspect recommended live-money packs.
 - Use `credits quote --pack PACK_ID --payment-method stripe_checkout --json`
   for the default Stripe Checkout path.
-- Use `credits quote --credits CREDITS --json` for exact bounded custom
-  top-ups when the required budget is already known.
-- Use `credits buy --provider stripe --json` only to create a Stripe-hosted
-  checkout action. Present `checkout_handoff_url` to humans; if it is absent,
-  present the full `checkout_url` in a code block. Do not remove the
-  Stripe `#...` fragment; Checkout needs it in the browser. Session creation
-  itself does not grant credits.
+- Use `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 `credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY
+--json` only to create a Stripe-hosted checkout action. Present
+  `checkout_handoff_url` to humans; if it is absent, present the full
+  `checkout_url` in a code block. Do not remove the Stripe `#...` fragment;
+  Checkout needs it in the browser. Session creation itself does not grant
+  credits.
 - Never pass live x402 payment headers, wallet private keys, seed phrases,
   bearer tokens, Stripe secrets, provider keys, card data, or provider receipts
   to Image Skill.