image-skill 0.1.56 → 0.1.58

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.58 - 2026-06-17
+
+- Release (activation/self-fund): mirror top-up urgency and the no-spend
+  payment rail inspection command into hosted generated-asset
+  `assets show/get` `data.next_actions.self_fund`, so agents that inspect or
+  download created media can still discover the safe first self-fund step
+  before ending the session. 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.57 - 2026-06-16
+
+- Release (activation/self-fund): mirror top-up urgency and the no-spend
+  payment rail inspection command into hosted `activity list/show`
+  `data.next_actions.self_fund`, so agents inspecting their ledger after
+  generated work can discover the safe first self-fund step before hitting the
+  quota wall. 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.56 - 2026-06-16
 
 - Release (activation/self-fund): mirror top-up urgency and the no-spend

package/SKILL.md

@@ -279,7 +279,12 @@ 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.
+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.
 **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.56";
+const VERSION = "0.1.58";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -4026,6 +4026,7 @@ async function assets(argv) {
       return shown;
     }
     const asset = shown.envelope.data?.asset ?? shown.envelope.data;
+    const nextActions = shown.envelope.data?.next_actions;
     const output =
       flagString(args, "output") ?? deriveAssetGetOutputPath(asset);
     const downloaded = await downloadUrl(asset.url, output, {
@@ -4042,6 +4043,7 @@ async function assets(argv) {
       },
       asset,
       download: downloaded.data,
+      ...(nextActions === undefined ? {} : { next_actions: nextActions }),
     };
     return shown;
   }

package/cli.md

@@ -1578,6 +1578,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.
+
 ### `image-skill assets get`
 
 Downloads an Image Skill-owned asset URL or hosted asset id to a local file.
@@ -1591,7 +1595,9 @@ image-skill assets get \
 
 The command refuses to overwrite existing files unless `--overwrite` is
 explicit. It verifies byte length when the asset server provides a
-`content-length` header.
+`content-length` header. For hosted asset-id downloads, `assets get` preserves
+`data.next_actions.self_fund` from the asset metadata response after a
+successful download.
 
 ### `image-skill jobs show`
 
@@ -1662,6 +1668,11 @@ 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`.
+
 Minimum success data:
 
 ```json
@@ -1718,7 +1729,9 @@ 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.
+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.
 
 Hosted API equivalent:
 

package/llms.txt

@@ -65,7 +65,7 @@ First-run guide loop:
 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.
 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, and asset links to cite.
+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.
 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.
@@ -218,7 +218,9 @@ Use image-skill activity list/show when an agent needs recent ledger context,
 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.
+show/wait for polling, recovery, retry judgment, or final job state. When
+activity returns data.next_actions.self_fund, run its first_safe_command for
+no-spend rail inspection before any quote/buy step.
 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,

package/package.json

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

@@ -279,7 +279,12 @@ 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.
+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.
 **Do not use `activity` as a wait or recovery command.** Activity is the ledger,
 not the work queue.
 

package/skills/image-skill/SKILL.md

@@ -279,7 +279,12 @@ 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.
+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.
 **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

@@ -1578,6 +1578,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.
+
 ### `image-skill assets get`
 
 Downloads an Image Skill-owned asset URL or hosted asset id to a local file.
@@ -1591,7 +1595,9 @@ image-skill assets get \
 
 The command refuses to overwrite existing files unless `--overwrite` is
 explicit. It verifies byte length when the asset server provides a
-`content-length` header.
+`content-length` header. For hosted asset-id downloads, `assets get` preserves
+`data.next_actions.self_fund` from the asset metadata response after a
+successful download.
 
 ### `image-skill jobs show`
 
@@ -1662,6 +1668,11 @@ 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`.
+
 Minimum success data:
 
 ```json
@@ -1718,7 +1729,9 @@ 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.
+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.
 
 Hosted API equivalent:
 

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

@@ -65,7 +65,7 @@ First-run guide loop:
 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.
 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, and asset links to cite.
+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.
 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.
@@ -218,7 +218,9 @@ Use image-skill activity list/show when an agent needs recent ledger context,
 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.
+show/wait for polling, recovery, retry judgment, or final job state. When
+activity returns data.next_actions.self_fund, run its first_safe_command for
+no-spend rail inspection before any quote/buy step.
 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,