image-skill 0.1.63 → 0.1.64

package/CHANGELOG.md

@@ -4,6 +4,17 @@ This changelog tracks the public `image-skill` CLI package and public skill
 mirror. The npm package metadata remains the authority for tarball integrity and
 provenance; this file is the human- and agent-readable release map.
 
+## 0.1.64 - 2026-06-17
+
+- Release (activation/self-fund): publish the hosted success-surface
+  `data.next_actions.self_fund` visibility payload under an unpublished package
+  version so `image-skill@latest` can expose the no-spend self-fund first
+  command whenever hosted quota reports top-up availability. `recommended` and
+  urgency remain priority signals; availability controls whether the action is
+  visible. No payment caps, auth semantics, provider routing, wallet action,
+  provider spend, media spend, hosted deploy, or production write changed in
+  this release bump.
+
 ## 0.1.63 - 2026-06-17
 
 - Release (activation/self-fund): make quota/payment error recovery top-up

package/SKILL.md

@@ -284,20 +284,20 @@ image-skill activity show EVENT_OR_JOB_OR_ASSET_OR_FEEDBACK
 After a successful hosted create/edit, prefer `data.next_actions` when present:
 `inspect_job` and `inspect_asset` are no-spend recovery commands,
 `iterate_edit` reuses the asset, and `self_fund` promotes a copy-runnable
-top-up quote command when `quota.top_up.recommended` is true. That handoff
-mirrors top-up `urgency`, `urgency_score`, and `urgency_reasons`, and exposes
-`first_safe_command` plus `first_safe_command_effect` for no-spend rail
-inspection before quote/buy. Its `quote_command` omits `--idempotency-key`; the
-public CLI generates and returns one for retry safety. Use `jobs show` or
-`jobs wait` for
+top-up quote command when `quota.top_up.available` is true. Its `recommended`
+flag and mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say
+whether the agent should act now, while `first_safe_command` plus
+`first_safe_command_effect` support no-spend rail inspection before quote/buy.
+Its `quote_command` omits `--idempotency-key`; the public CLI generates and
+returns one for retry safety. Use `jobs show` or `jobs wait` for
 operational job state, final assets, and retry judgment. Use `activity` for
 audit trail context (recent jobs, assets, usage events, feedback acceptance,
 trace IDs, status changes) you can cite in feedback. `activity list/show` may
-also return `data.next_actions.self_fund` with the same urgency and no-spend
-inspection handoff when the ledger proves generated work and quota says top-up
-setup is recommended. `assets show` and hosted asset-id `assets get` may return
-the same `data.next_actions.self_fund` after generated work, so downloading or
-inspecting the asset does not hide the funding setup path.
+also return `data.next_actions.self_fund` with the same recommendation, urgency,
+and no-spend inspection handoff when the ledger proves generated work and quota
+exposes an available top-up path. `assets show` and hosted asset-id `assets get`
+may return the same `data.next_actions.self_fund` after generated work, so
+downloading or inspecting the asset does not hide the funding setup path.
 **Do not use `activity` as a wait or recovery command.** Activity is the ledger,
 not the work queue.
 

package/bin/image-skill.mjs

@@ -15,7 +15,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.63";
+const VERSION = "0.1.64";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";

package/cli.md

@@ -1603,14 +1603,15 @@ include a new generated asset URL, job id, safety state, quota consumption, and
 input asset metadata where
 applicable. Responses do not include raw prompts, source bytes, base64
 payloads, local paths, full external URLs, bucket names, or object keys.
-When `quota.top_up.recommended` is true, `next_actions.self_fund.quote_command`
-is a copy-runnable top-up quote command. `next_actions.self_fund` also mirrors
-top-up `urgency`, `urgency_score`, and `urgency_reasons`, and exposes
-`first_safe_command`, `first_safe_command_effect`, `inspect_methods_command`,
-and `inspect_packs_command` for no-spend payment rail inspection before
-quote/buy. The quote command omits `--idempotency-key` so the public CLI
-generates and returns one for retry safety before the agent follows the quote
-response into `credits buy` and `credits status`.
+When `quota.top_up.available` is true, `next_actions.self_fund.quote_command`
+is a copy-runnable top-up quote command. `next_actions.self_fund.recommended`
+and the mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say
+whether the agent should act now. The handoff exposes `first_safe_command`,
+`first_safe_command_effect`, `inspect_methods_command`, and
+`inspect_packs_command` for no-spend payment rail inspection before quote/buy.
+The quote command omits `--idempotency-key` so the public CLI generates and
+returns one for retry safety before the agent follows the quote response into
+`credits buy` and `credits status`.
 
 Provider/model names in this paragraph are preview provenance, not the primary
 public UX. The public selection surface should be Image Skill capabilities and
@@ -1665,9 +1666,10 @@ Minimum success data:
 External URLs are rejected. Older assets created before hosted asset metadata
 was recorded may still be inspectable by Image Skill-owned URL.
 
-For hosted generated assets, when quota says top-up setup is recommended,
-`data.next_actions.self_fund` mirrors the top-up urgency and no-spend payment
-rail inspection handoff used by create/edit, jobs, and activity responses.
+For hosted generated assets, when quota exposes an available top-up path,
+`data.next_actions.self_fund` mirrors the top-up recommendation, urgency, and
+no-spend payment rail inspection handoff used by create/edit, jobs, and
+activity responses.
 
 ### `image-skill assets get`
 
@@ -1755,10 +1757,10 @@ related job IDs, asset IDs, usage IDs, feedback IDs, trace IDs, status changes,
 and product-memory writes. Use `jobs show` or `jobs wait` when you need
 operational recovery, polling, retry judgment, or final job assets.
 
-When the ledger proves generated work and current quota says top-up setup is
-recommended, `data.next_actions.self_fund` mirrors the same urgency and
-no-spend payment-method inspection handoff returned by successful create/edit
-and `jobs show`.
+When the ledger proves generated work and current quota exposes an available
+top-up path, `data.next_actions.self_fund` mirrors the same recommendation,
+urgency, and no-spend payment-method inspection handoff returned by successful
+create/edit and `jobs show`.
 
 Minimum success data:
 
@@ -1816,9 +1818,10 @@ image-skill activity show sig_... --json
 `activity show` accepts activity event IDs plus job, asset, usage, feedback, and
 trace references. When the reference is a subject rather than one exact event,
 the response includes matching ledger events so an agent can cite the right
-event without reading telemetry logs. When current quota recommends top-up
-setup after generated work, `data.next_actions.self_fund.first_safe_command`
-is the no-spend rail inspection command to run before any quote/buy step.
+event without reading telemetry logs. When current quota exposes top-up
+availability after generated work,
+`data.next_actions.self_fund.first_safe_command` is the no-spend rail
+inspection command to run before any quote/buy step.
 
 Hosted API equivalent:
 

package/llms.txt

@@ -62,10 +62,10 @@ First-run guide loop:
 2. Read data.guide_warning, then follow data.next_command when its next_command_safety is safe for the current spend policy. Prefer data.guide_recovery for no-doc recovery: data.guide_recovery.no_spend_command_field and data.guide_recovery.no_spend_command name the safest no-spend command, data.guide_recovery.live_create_command_field and data.guide_recovery.live_payment_command_field name fields that would spend, and data.guide_recovery.double_spend_guard tells you when to check error.recovery, jobs, activity, or payment status before any live retry. Do not run doctor, models list, signup, whoami, quota, dry-run, or payment commands as a setup checklist before the guide asks for them.
 3. If data.stage is prompt_required, rerun data.next_command with the real prompt.
 4. If data.stage is auth_required, data.auth_ready.ready is false and data.guide_warning.next_command_safety is hosted_signup_no_spend_setup. Run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the configured config path is blocked, data.next_command sets IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" and still runs a saved-config signup; do not switch to raw-token handoff unless recovery explicitly requires it. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. Signup is anonymous by default: no contact inbox is required to get a restricted token. The optional --agent-contact flag takes an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find an individual human; attach one later with image-skill claim request --contact INBOX --json when funding or durability makes it worth having. Hosted signup returns the raw restricted token only when --show-token is set, and only once. When providing a contact, use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated human email just to fill the flag — omit it instead. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. Anonymous signups mint a fresh agent identity on every call; reuse the saved config instead of re-running signup. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
-5. At any guide stage, read data.checks.quota.top_up. When recommended is true, it includes recommendation_reason, preferred_payment_method, quote_command, quote_command_copy_runnable, quote_command_effect, and quote/buy/status command templates for the browserless x402 top-up path. On quota/payment recovery errors, read error.recovery.top_up: when delegated live-money quoting is allowed, prefer error.recovery.top_up.quote_command to open the top-up path, and use error.recovery.suggested_command for no-spend payment-method inspection. If data.stage is quota_required, data.guide_warning.next_command_safety is live_money_payment_action and data.guide_warning.payment_top_up_path summarizes the live-money path. Run data.self_fund_next_command to start the top-up. It aliases data.next_command and is the first payment command, usually an x402 or Stripe quote. First read data.checks.payments.preferred_method_summary.top_up_path: browserless_agent_self_fund means a wallet-equipped agent can complete the preferred live-money rail without a browser; human_payment_handoff means the agent can create the payment attempt but a human/browser step must complete before credits are granted. If the guide authenticated from env or stdin, prefer data.self_fund_handoff.auth.next_command.with_env or data.self_fund_handoff.auth.next_command.with_stdin so auth follows the payment command. Then follow data.self_fund_handoff.payment_commands.buy and status, and rerun data.self_fund_handoff.after_next once credits are granted. If data.stage is ready_to_create, inspect data.self_fund_preparation before consuming the remaining free allowance. When available and recommended are true, data.self_fund_preparation.quote_command is the pre-wall browserless x402 quote: it creates an authenticated live-money quote/payment object, but data.self_fund_preparation.quote_command_effect must show no provider call, no hosted create, no credit debit, no media write, and no wallet settlement until a later buy/payment step. 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 four-job daily cap.
+5. At any guide stage, read data.checks.quota.top_up. When available is true, it includes recommended, recommendation_reason, preferred_payment_method, quote_command, quote_command_copy_runnable, quote_command_effect, and quote/buy/status command templates for the browserless x402 top-up path; recommended and urgency say whether to act now. On quota/payment recovery errors, read error.recovery.top_up: when delegated live-money quoting is allowed, prefer error.recovery.top_up.quote_command to open the top-up path, and use error.recovery.suggested_command for no-spend payment-method inspection. If data.stage is quota_required, data.guide_warning.next_command_safety is live_money_payment_action and data.guide_warning.payment_top_up_path summarizes the live-money path. Run data.self_fund_next_command to start the top-up. It aliases data.next_command and is the first payment command, usually an x402 or Stripe quote. First read data.checks.payments.preferred_method_summary.top_up_path: browserless_agent_self_fund means a wallet-equipped agent can complete the preferred live-money rail without a browser; human_payment_handoff means the agent can create the payment attempt but a human/browser step must complete before credits are granted. If the guide authenticated from env or stdin, prefer data.self_fund_handoff.auth.next_command.with_env or data.self_fund_handoff.auth.next_command.with_stdin so auth follows the payment command. Then follow data.self_fund_handoff.payment_commands.buy and status, and rerun data.self_fund_handoff.after_next once credits are granted. If data.stage is ready_to_create, inspect data.self_fund_preparation before consuming the remaining free allowance. When available and recommended are true, data.self_fund_preparation.quote_command is the pre-wall browserless x402 quote: it creates an authenticated live-money quote/payment object, but data.self_fund_preparation.quote_command_effect must show no provider call, no hosted create, no credit debit, no media write, and no wallet settlement until a later buy/payment step. 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 four-job daily cap.
 5a. When data.stage is quota_required, data.self_fund_handoff mirrors top-up urgency, urgency_score, and urgency_reasons, and exposes first_safe_command plus first_safe_command_effect. Run first_safe_command, usually image-skill credits methods --json, for no-spend rail inspection before quote/buy when delegated spend authority is absent or unclear.
 6. If data.stage is ready_to_create, data.next_command is the first bounded live create. data.guide_warning.next_command_safety must be live_media_create_credit_debit, data.guide_warning.no_spend_safe must be false, data.guide_warning.spend_required must be true, and data.guide_warning.recommended_command_field must be recommended_no_spend_command. data.auth_ready.ready and data.auth_ready.next_command_auth_ready must be true; data.auth_ready.next_command_requires_auth must be true, and the command can reuse saved config, IMAGE_SKILL_TOKEN, or --token-stdin context without exposing a raw token. data.next_command_effect.label must be live_media_create_credit_debit and its provider_call, hosted_create, credit_debit, and media_write flags are true. data.no_spend_evaluation.stop_here must be true, data.no_spend_evaluation.next_command_is_live_create must be true, and data.no_spend_evaluation.recommended_command_field must be recommended_no_spend_command. Run data.next_command only when media spend is allowed. In no-spend evaluations, or when you only need to prove readiness without media/provider work, stop before data.next_command and run data.recommended_no_spend_command instead. data.recommended_no_spend_command must equal data.no_spend_next_command. data.no_spend_next_command_effect.label must be dry_run_planned_job_no_provider_call_no_credit_debit_no_media_write: no_spend, hosted_create_dry_run, planned_job, and plan_receipt are true; activity_event is job.planned; provider_call, credit_debit, and media_write are false. This dry-run may create a recoverable planned job/activity receipt but no provider execution, debit, downloadable asset, or media write. If the guide authenticated from env or stdin, prefer data.auth_handoff.next_command.with_env or data.auth_handoff.next_command.with_stdin so auth follows the live create. In guide cost output, cost.estimated_usd_per_image and cost.estimated_debit_usd_per_image are the Image Skill debit dollars for one output; cost.estimated_provider_usd_per_image is only the upstream provider estimate. Use the guide's returned max_estimated_usd_per_image because it is sized to the credit debit the agent funds. 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 Image Skill debit guard.
-7. After create, prefer data.next_actions when present: inspect_job and inspect_asset are copy-runnable no-spend recovery commands, iterate_edit is the reusable-asset edit template, and self_fund is the promoted top-up quote handoff when quota.top_up.recommended is true. self_fund mirrors urgency, urgency_score, and urgency_reasons, and exposes first_safe_command plus first_safe_command_effect for no-spend rail inspection before quote/buy. self_fund.quote_command is copy-runnable and omits --idempotency-key so the public CLI generates and returns one for retry safety; follow the quote response into buy/status. Otherwise use image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and image-skill activity list --subject JOB_ID to find ledger events, trace, usage, asset links, and any data.next_actions.self_fund handoff to cite or follow. Hosted asset-id assets show/get may also return data.next_actions.self_fund after generated work, so inspect that field before ending the session.
+7. After create, prefer data.next_actions when present: inspect_job and inspect_asset are copy-runnable no-spend recovery commands, iterate_edit is the reusable-asset edit template, and self_fund is the promoted top-up quote handoff when quota.top_up.available is true. self_fund.recommended plus urgency, urgency_score, and urgency_reasons say whether to act now, and self_fund exposes first_safe_command plus first_safe_command_effect for no-spend rail inspection before quote/buy. self_fund.quote_command is copy-runnable and omits --idempotency-key so the public CLI generates and returns one for retry safety; follow the quote response into buy/status. Otherwise use image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and image-skill activity list --subject JOB_ID to find ledger events, trace, usage, asset links, and any data.next_actions.self_fund handoff to cite or follow. Hosted asset-id assets show/get may also return data.next_actions.self_fund after generated work, so inspect that field before ending the session.
 8. 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. Feedback auth uses saved config from default signup, IMAGE_SKILL_TOKEN, or --token-stdin; if signup or guide already saved config, run feedback create normally and do not copy a raw token. Never paste tokens into feedback title, body, evidence, issues, or logs. Use image-skill activity show FEEDBACK_ID only when you need to confirm the feedback entered the hosted ledger.
 
 Manual escape hatches are not prerequisites. Use image-skill doctor, image-skill models list, image-skill models show MODEL_ID, image-skill whoami, image-skill usage quota, image-skill credits methods, image-skill credits packs list, image-skill credits quote, image-skill credits buy, image-skill credits status, image-skill create --dry-run, and image-skill edit --dry-run only when data.next_command or data.escape_hatches asks for them, or when the task genuinely needs deeper capability, quota, payment, or planning detail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.63",
+  "version": "0.1.64",
   "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,

package/skill.md

@@ -284,20 +284,20 @@ image-skill activity show EVENT_OR_JOB_OR_ASSET_OR_FEEDBACK
 After a successful hosted create/edit, prefer `data.next_actions` when present:
 `inspect_job` and `inspect_asset` are no-spend recovery commands,
 `iterate_edit` reuses the asset, and `self_fund` promotes a copy-runnable
-top-up quote command when `quota.top_up.recommended` is true. That handoff
-mirrors top-up `urgency`, `urgency_score`, and `urgency_reasons`, and exposes
-`first_safe_command` plus `first_safe_command_effect` for no-spend rail
-inspection before quote/buy. Its `quote_command` omits `--idempotency-key`; the
-public CLI generates and returns one for retry safety. Use `jobs show` or
-`jobs wait` for
+top-up quote command when `quota.top_up.available` is true. Its `recommended`
+flag and mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say
+whether the agent should act now, while `first_safe_command` plus
+`first_safe_command_effect` support no-spend rail inspection before quote/buy.
+Its `quote_command` omits `--idempotency-key`; the public CLI generates and
+returns one for retry safety. Use `jobs show` or `jobs wait` for
 operational job state, final assets, and retry judgment. Use `activity` for
 audit trail context (recent jobs, assets, usage events, feedback acceptance,
 trace IDs, status changes) you can cite in feedback. `activity list/show` may
-also return `data.next_actions.self_fund` with the same urgency and no-spend
-inspection handoff when the ledger proves generated work and quota says top-up
-setup is recommended. `assets show` and hosted asset-id `assets get` may return
-the same `data.next_actions.self_fund` after generated work, so downloading or
-inspecting the asset does not hide the funding setup path.
+also return `data.next_actions.self_fund` with the same recommendation, urgency,
+and no-spend inspection handoff when the ledger proves generated work and quota
+exposes an available top-up path. `assets show` and hosted asset-id `assets get`
+may return the same `data.next_actions.self_fund` after generated work, so
+downloading or inspecting the asset does not hide the funding setup path.
 **Do not use `activity` as a wait or recovery command.** Activity is the ledger,
 not the work queue.
 

package/skills/image-skill/SKILL.md

@@ -284,20 +284,20 @@ image-skill activity show EVENT_OR_JOB_OR_ASSET_OR_FEEDBACK
 After a successful hosted create/edit, prefer `data.next_actions` when present:
 `inspect_job` and `inspect_asset` are no-spend recovery commands,
 `iterate_edit` reuses the asset, and `self_fund` promotes a copy-runnable
-top-up quote command when `quota.top_up.recommended` is true. That handoff
-mirrors top-up `urgency`, `urgency_score`, and `urgency_reasons`, and exposes
-`first_safe_command` plus `first_safe_command_effect` for no-spend rail
-inspection before quote/buy. Its `quote_command` omits `--idempotency-key`; the
-public CLI generates and returns one for retry safety. Use `jobs show` or
-`jobs wait` for
+top-up quote command when `quota.top_up.available` is true. Its `recommended`
+flag and mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say
+whether the agent should act now, while `first_safe_command` plus
+`first_safe_command_effect` support no-spend rail inspection before quote/buy.
+Its `quote_command` omits `--idempotency-key`; the public CLI generates and
+returns one for retry safety. Use `jobs show` or `jobs wait` for
 operational job state, final assets, and retry judgment. Use `activity` for
 audit trail context (recent jobs, assets, usage events, feedback acceptance,
 trace IDs, status changes) you can cite in feedback. `activity list/show` may
-also return `data.next_actions.self_fund` with the same urgency and no-spend
-inspection handoff when the ledger proves generated work and quota says top-up
-setup is recommended. `assets show` and hosted asset-id `assets get` may return
-the same `data.next_actions.self_fund` after generated work, so downloading or
-inspecting the asset does not hide the funding setup path.
+also return `data.next_actions.self_fund` with the same recommendation, urgency,
+and no-spend inspection handoff when the ledger proves generated work and quota
+exposes an available top-up path. `assets show` and hosted asset-id `assets get`
+may return the same `data.next_actions.self_fund` after generated work, so
+downloading or inspecting the asset does not hide the funding setup path.
 **Do not use `activity` as a wait or recovery command.** Activity is the ledger,
 not the work queue.
 

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

@@ -1603,14 +1603,15 @@ include a new generated asset URL, job id, safety state, quota consumption, and
 input asset metadata where
 applicable. Responses do not include raw prompts, source bytes, base64
 payloads, local paths, full external URLs, bucket names, or object keys.
-When `quota.top_up.recommended` is true, `next_actions.self_fund.quote_command`
-is a copy-runnable top-up quote command. `next_actions.self_fund` also mirrors
-top-up `urgency`, `urgency_score`, and `urgency_reasons`, and exposes
-`first_safe_command`, `first_safe_command_effect`, `inspect_methods_command`,
-and `inspect_packs_command` for no-spend payment rail inspection before
-quote/buy. The quote command omits `--idempotency-key` so the public CLI
-generates and returns one for retry safety before the agent follows the quote
-response into `credits buy` and `credits status`.
+When `quota.top_up.available` is true, `next_actions.self_fund.quote_command`
+is a copy-runnable top-up quote command. `next_actions.self_fund.recommended`
+and the mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say
+whether the agent should act now. The handoff exposes `first_safe_command`,
+`first_safe_command_effect`, `inspect_methods_command`, and
+`inspect_packs_command` for no-spend payment rail inspection before quote/buy.
+The quote command omits `--idempotency-key` so the public CLI generates and
+returns one for retry safety before the agent follows the quote response into
+`credits buy` and `credits status`.
 
 Provider/model names in this paragraph are preview provenance, not the primary
 public UX. The public selection surface should be Image Skill capabilities and
@@ -1665,9 +1666,10 @@ Minimum success data:
 External URLs are rejected. Older assets created before hosted asset metadata
 was recorded may still be inspectable by Image Skill-owned URL.
 
-For hosted generated assets, when quota says top-up setup is recommended,
-`data.next_actions.self_fund` mirrors the top-up urgency and no-spend payment
-rail inspection handoff used by create/edit, jobs, and activity responses.
+For hosted generated assets, when quota exposes an available top-up path,
+`data.next_actions.self_fund` mirrors the top-up recommendation, urgency, and
+no-spend payment rail inspection handoff used by create/edit, jobs, and
+activity responses.
 
 ### `image-skill assets get`
 
@@ -1755,10 +1757,10 @@ related job IDs, asset IDs, usage IDs, feedback IDs, trace IDs, status changes,
 and product-memory writes. Use `jobs show` or `jobs wait` when you need
 operational recovery, polling, retry judgment, or final job assets.
 
-When the ledger proves generated work and current quota says top-up setup is
-recommended, `data.next_actions.self_fund` mirrors the same urgency and
-no-spend payment-method inspection handoff returned by successful create/edit
-and `jobs show`.
+When the ledger proves generated work and current quota exposes an available
+top-up path, `data.next_actions.self_fund` mirrors the same recommendation,
+urgency, and no-spend payment-method inspection handoff returned by successful
+create/edit and `jobs show`.
 
 Minimum success data:
 
@@ -1816,9 +1818,10 @@ image-skill activity show sig_... --json
 `activity show` accepts activity event IDs plus job, asset, usage, feedback, and
 trace references. When the reference is a subject rather than one exact event,
 the response includes matching ledger events so an agent can cite the right
-event without reading telemetry logs. When current quota recommends top-up
-setup after generated work, `data.next_actions.self_fund.first_safe_command`
-is the no-spend rail inspection command to run before any quote/buy step.
+event without reading telemetry logs. When current quota exposes top-up
+availability after generated work,
+`data.next_actions.self_fund.first_safe_command` is the no-spend rail
+inspection command to run before any quote/buy step.
 
 Hosted API equivalent:
 

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

@@ -62,10 +62,10 @@ First-run guide loop:
 2. Read data.guide_warning, then follow data.next_command when its next_command_safety is safe for the current spend policy. Prefer data.guide_recovery for no-doc recovery: data.guide_recovery.no_spend_command_field and data.guide_recovery.no_spend_command name the safest no-spend command, data.guide_recovery.live_create_command_field and data.guide_recovery.live_payment_command_field name fields that would spend, and data.guide_recovery.double_spend_guard tells you when to check error.recovery, jobs, activity, or payment status before any live retry. Do not run doctor, models list, signup, whoami, quota, dry-run, or payment commands as a setup checklist before the guide asks for them.
 3. If data.stage is prompt_required, rerun data.next_command with the real prompt.
 4. If data.stage is auth_required, data.auth_ready.ready is false and data.guide_warning.next_command_safety is hosted_signup_no_spend_setup. Run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the configured config path is blocked, data.next_command sets IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" and still runs a saved-config signup; do not switch to raw-token handoff unless recovery explicitly requires it. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. Signup is anonymous by default: no contact inbox is required to get a restricted token. The optional --agent-contact flag takes an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find an individual human; attach one later with image-skill claim request --contact INBOX --json when funding or durability makes it worth having. Hosted signup returns the raw restricted token only when --show-token is set, and only once. When providing a contact, use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated human email just to fill the flag — omit it instead. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. Anonymous signups mint a fresh agent identity on every call; reuse the saved config instead of re-running signup. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
-5. At any guide stage, read data.checks.quota.top_up. When recommended is true, it includes recommendation_reason, preferred_payment_method, quote_command, quote_command_copy_runnable, quote_command_effect, and quote/buy/status command templates for the browserless x402 top-up path. On quota/payment recovery errors, read error.recovery.top_up: when delegated live-money quoting is allowed, prefer error.recovery.top_up.quote_command to open the top-up path, and use error.recovery.suggested_command for no-spend payment-method inspection. If data.stage is quota_required, data.guide_warning.next_command_safety is live_money_payment_action and data.guide_warning.payment_top_up_path summarizes the live-money path. Run data.self_fund_next_command to start the top-up. It aliases data.next_command and is the first payment command, usually an x402 or Stripe quote. First read data.checks.payments.preferred_method_summary.top_up_path: browserless_agent_self_fund means a wallet-equipped agent can complete the preferred live-money rail without a browser; human_payment_handoff means the agent can create the payment attempt but a human/browser step must complete before credits are granted. If the guide authenticated from env or stdin, prefer data.self_fund_handoff.auth.next_command.with_env or data.self_fund_handoff.auth.next_command.with_stdin so auth follows the payment command. Then follow data.self_fund_handoff.payment_commands.buy and status, and rerun data.self_fund_handoff.after_next once credits are granted. If data.stage is ready_to_create, inspect data.self_fund_preparation before consuming the remaining free allowance. When available and recommended are true, data.self_fund_preparation.quote_command is the pre-wall browserless x402 quote: it creates an authenticated live-money quote/payment object, but data.self_fund_preparation.quote_command_effect must show no provider call, no hosted create, no credit debit, no media write, and no wallet settlement until a later buy/payment step. 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 four-job daily cap.
+5. At any guide stage, read data.checks.quota.top_up. When available is true, it includes recommended, recommendation_reason, preferred_payment_method, quote_command, quote_command_copy_runnable, quote_command_effect, and quote/buy/status command templates for the browserless x402 top-up path; recommended and urgency say whether to act now. On quota/payment recovery errors, read error.recovery.top_up: when delegated live-money quoting is allowed, prefer error.recovery.top_up.quote_command to open the top-up path, and use error.recovery.suggested_command for no-spend payment-method inspection. If data.stage is quota_required, data.guide_warning.next_command_safety is live_money_payment_action and data.guide_warning.payment_top_up_path summarizes the live-money path. Run data.self_fund_next_command to start the top-up. It aliases data.next_command and is the first payment command, usually an x402 or Stripe quote. First read data.checks.payments.preferred_method_summary.top_up_path: browserless_agent_self_fund means a wallet-equipped agent can complete the preferred live-money rail without a browser; human_payment_handoff means the agent can create the payment attempt but a human/browser step must complete before credits are granted. If the guide authenticated from env or stdin, prefer data.self_fund_handoff.auth.next_command.with_env or data.self_fund_handoff.auth.next_command.with_stdin so auth follows the payment command. Then follow data.self_fund_handoff.payment_commands.buy and status, and rerun data.self_fund_handoff.after_next once credits are granted. If data.stage is ready_to_create, inspect data.self_fund_preparation before consuming the remaining free allowance. When available and recommended are true, data.self_fund_preparation.quote_command is the pre-wall browserless x402 quote: it creates an authenticated live-money quote/payment object, but data.self_fund_preparation.quote_command_effect must show no provider call, no hosted create, no credit debit, no media write, and no wallet settlement until a later buy/payment step. 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 four-job daily cap.
 5a. When data.stage is quota_required, data.self_fund_handoff mirrors top-up urgency, urgency_score, and urgency_reasons, and exposes first_safe_command plus first_safe_command_effect. Run first_safe_command, usually image-skill credits methods --json, for no-spend rail inspection before quote/buy when delegated spend authority is absent or unclear.
 6. If data.stage is ready_to_create, data.next_command is the first bounded live create. data.guide_warning.next_command_safety must be live_media_create_credit_debit, data.guide_warning.no_spend_safe must be false, data.guide_warning.spend_required must be true, and data.guide_warning.recommended_command_field must be recommended_no_spend_command. data.auth_ready.ready and data.auth_ready.next_command_auth_ready must be true; data.auth_ready.next_command_requires_auth must be true, and the command can reuse saved config, IMAGE_SKILL_TOKEN, or --token-stdin context without exposing a raw token. data.next_command_effect.label must be live_media_create_credit_debit and its provider_call, hosted_create, credit_debit, and media_write flags are true. data.no_spend_evaluation.stop_here must be true, data.no_spend_evaluation.next_command_is_live_create must be true, and data.no_spend_evaluation.recommended_command_field must be recommended_no_spend_command. Run data.next_command only when media spend is allowed. In no-spend evaluations, or when you only need to prove readiness without media/provider work, stop before data.next_command and run data.recommended_no_spend_command instead. data.recommended_no_spend_command must equal data.no_spend_next_command. data.no_spend_next_command_effect.label must be dry_run_planned_job_no_provider_call_no_credit_debit_no_media_write: no_spend, hosted_create_dry_run, planned_job, and plan_receipt are true; activity_event is job.planned; provider_call, credit_debit, and media_write are false. This dry-run may create a recoverable planned job/activity receipt but no provider execution, debit, downloadable asset, or media write. If the guide authenticated from env or stdin, prefer data.auth_handoff.next_command.with_env or data.auth_handoff.next_command.with_stdin so auth follows the live create. In guide cost output, cost.estimated_usd_per_image and cost.estimated_debit_usd_per_image are the Image Skill debit dollars for one output; cost.estimated_provider_usd_per_image is only the upstream provider estimate. Use the guide's returned max_estimated_usd_per_image because it is sized to the credit debit the agent funds. 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 Image Skill debit guard.
-7. After create, prefer data.next_actions when present: inspect_job and inspect_asset are copy-runnable no-spend recovery commands, iterate_edit is the reusable-asset edit template, and self_fund is the promoted top-up quote handoff when quota.top_up.recommended is true. self_fund mirrors urgency, urgency_score, and urgency_reasons, and exposes first_safe_command plus first_safe_command_effect for no-spend rail inspection before quote/buy. self_fund.quote_command is copy-runnable and omits --idempotency-key so the public CLI generates and returns one for retry safety; follow the quote response into buy/status. Otherwise use image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and image-skill activity list --subject JOB_ID to find ledger events, trace, usage, asset links, and any data.next_actions.self_fund handoff to cite or follow. Hosted asset-id assets show/get may also return data.next_actions.self_fund after generated work, so inspect that field before ending the session.
+7. After create, prefer data.next_actions when present: inspect_job and inspect_asset are copy-runnable no-spend recovery commands, iterate_edit is the reusable-asset edit template, and self_fund is the promoted top-up quote handoff when quota.top_up.available is true. self_fund.recommended plus urgency, urgency_score, and urgency_reasons say whether to act now, and self_fund exposes first_safe_command plus first_safe_command_effect for no-spend rail inspection before quote/buy. self_fund.quote_command is copy-runnable and omits --idempotency-key so the public CLI generates and returns one for retry safety; follow the quote response into buy/status. Otherwise use image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and image-skill activity list --subject JOB_ID to find ledger events, trace, usage, asset links, and any data.next_actions.self_fund handoff to cite or follow. Hosted asset-id assets show/get may also return data.next_actions.self_fund after generated work, so inspect that field before ending the session.
 8. 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. Feedback auth uses saved config from default signup, IMAGE_SKILL_TOKEN, or --token-stdin; if signup or guide already saved config, run feedback create normally and do not copy a raw token. Never paste tokens into feedback title, body, evidence, issues, or logs. Use image-skill activity show FEEDBACK_ID only when you need to confirm the feedback entered the hosted ledger.
 
 Manual escape hatches are not prerequisites. Use image-skill doctor, image-skill models list, image-skill models show MODEL_ID, image-skill whoami, image-skill usage quota, image-skill credits methods, image-skill credits packs list, image-skill credits quote, image-skill credits buy, image-skill credits status, image-skill create --dry-run, and image-skill edit --dry-run only when data.next_command or data.escape_hatches asks for them, or when the task genuinely needs deeper capability, quota, payment, or planning detail.