image-skill 0.1.28 → 0.1.29

package/cli.md

@@ -128,34 +128,76 @@ should omit it.
 
 Use the no-spend guide first. It is the only required first command for a fresh
 agent. It checks health, executable model availability, auth/quota when a token
-already exists, and payment rails, then returns one primary `data.next_command` plus
-machine-readable `data.next_command_effect`. Guide mode does not create a
-signup, provider job, dry-run job, payment object, credit debit, or asset.
+already exists, and payment rails, then returns one primary
+`data.next_command` plus machine-readable `data.next_command_effect`,
+`data.guide_warning`, `data.auth_ready`, and `data.no_spend_evaluation`. Guide
+mode does not create a signup, provider job, dry-run job, payment object,
+credit debit, or asset.
 
 ```bash
 image-skill create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-Read `data.stage`, run `data.next_command`, and rerun the guide only after
-auth or payment state changes. Do not run `doctor`, `models list`, `signup`,
-`whoami`, `usage quota`, `create --dry-run`, or payment commands as a setup
-checklist before the guide asks for them.
+Read `data.stage` and `data.guide_warning`, run `data.next_command` when
+`data.guide_warning.next_command_safety` is safe for the current spend policy,
+and rerun the guide only after auth or payment state changes. Do not run
+`doctor`, `models list`, `signup`, `whoami`, `usage quota`, `create --dry-run`,
+or payment commands as a setup checklist before the guide asks for them.
 
 - `prompt_required`: rerun `data.next_command` with the real prompt.
 - `auth_required`: run `data.next_command`, then rerun guide once. Hosted
   signup saves auth to config by default. If the runtime intentionally used
   `--no-save --show-token`, store the returned token and use
   `data.auth_handoff.rerun_guide.with_env` or
-  `data.auth_handoff.rerun_guide.with_stdin`.
-- `quota_required`: follow the payment commands in
-  `data.checks.payments.suggested_commands`, then rerun guide once.
+  `data.auth_handoff.rerun_guide.with_stdin`. In this stage,
+  `data.auth_ready.ready` is `false`, and
+  `data.guide_warning.next_command_safety` is
+  `hosted_signup_no_spend_setup`.
+- `quota_required`: run `data.self_fund_next_command` to start the top-up.
+  It aliases `data.next_command` and is the first payment command, usually an
+  x402 or Stripe quote. If the guide authenticated from env or stdin, prefer
+  `data.self_fund_handoff.auth.next_command.with_env` or
+  `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.self_fund_handoff.wallet_settlement` is non-null, pay the
+  exact amount in the returned `payable_instructions` field from a delegated
+  wallet before polling status; the handoff names the response fields and the
+  credential boundary. `data.guide_warning.next_command_safety` is
+  `live_money_payment_action`, and
+  `data.guide_warning.payment_top_up_path` summarizes the same path as
+  `data.checks.payments.preferred_method_summary.top_up_path`. Read that path
+  before the quote: `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.
 - `ready_to_create`: `data.next_command` is a live media create. Its
   `data.next_command_effect.label` is `live_media_create_credit_debit`, with
   `provider_call`, `hosted_create`, `credit_debit`, and `media_write` all true.
-  Run it for the first bounded create when media spend is allowed. If you are
-  in a no-spend evaluation or only need proof that the path is ready, run
-  `data.no_spend_next_command` instead; it is the dry-run plan command with no
-  provider call, credit debit, or media write. If the guide authenticated from
+  `data.guide_warning.next_command_safety` is
+  `live_media_create_credit_debit`, `data.guide_warning.no_spend_safe` is
+  `false`, `data.guide_warning.spend_required` is `true`, and
+  `data.guide_warning.recommended_command_field` is
+  `recommended_no_spend_command`.
+  `data.auth_ready.ready` is `true`,
+  `data.auth_ready.next_command_requires_auth` is `true`, and
+  `data.auth_ready.next_command_auth_ready` is `true`; the returned
+  `data.next_command` can reuse the current saved config, env token, or stdin
+  token context without exposing a raw token.
+  `data.no_spend_evaluation.stop_here` is `true`,
+  `data.no_spend_evaluation.next_command_is_live_create` is `true`, and
+  `data.no_spend_evaluation.recommended_command_field` is
+  `recommended_no_spend_command`. Run `data.next_command` for the first bounded
+  create only when media spend is allowed. If you are in a no-spend evaluation
+  or only need proof that the path is ready, stop before `data.next_command` and
+  run `data.recommended_no_spend_command` instead; it aliases
+  `data.no_spend_next_command` and is the dry-run plan command. Its
+  `data.no_spend_next_command_effect.label` is
+  `dry_run_planned_job_no_provider_call_no_credit_debit_no_media_write`, with
+  `no_spend`, `hosted_create_dry_run`, `planned_job`, and `plan_receipt` true,
+  `activity_event: "job.planned"`, and provider call, credit debit, and media
+  write false. It 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 create.
@@ -187,7 +229,7 @@ same auth context.
 Prefer package execution in fresh agent sandboxes:
 
 ```bash
-npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
+npm_config_update_notifier=false npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
 ```
 
 Global install is optional, not the primary path. If `npm install -g image-skill`
@@ -198,7 +240,21 @@ package-manager paths instead of cloning private source:
 export npm_config_cache="${npm_config_cache:-$PWD/.npm-cache}"
 export npm_config_prefix="${npm_config_prefix:-$PWD/.npm-global}"
 export PATH="$npm_config_prefix/bin:$PATH"
-npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
+npm_config_update_notifier=false npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json
+```
+
+For `npx skills add ... -g -a codex` installs, the writable target is Codex
+agent home rather than the npm prefix. If the Codex/global skill target is
+read-only or cannot create its default directory, keep the tracked slug install
+and point agent skill state at a writable workspace home. The skills.sh Codex
+adapter writes to `$HOME/.agents`; `CODEX_HOME` keeps Codex profile state on the
+same writable path:
+
+```bash
+export HOME="$PWD/.agent-home"
+export CODEX_HOME="$HOME/.codex"
+mkdir -p "$HOME" "$CODEX_HOME"
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
 ```
 
 Hosted signup saves auth state to the public CLI config by default. If the
@@ -207,7 +263,7 @@ runtime needs a writable compatibility config path, set
 
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
-npx -y image-skill@latest signup --agent \
+npm_config_update_notifier=false npx -y image-skill@latest signup --agent \
   --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
@@ -218,19 +274,37 @@ Config write failures return `PUBLIC_CLI_CONFIG_WRITE_FAILED` with a structured
 `error.recovery.suggested_command`. Agents should follow that recovery field,
 then rerun `create --guide` for the requested creative flow.
 When `create --guide` reaches `auth_required`, it probes the configured auth
-path first. If local config cannot be written, `data.next_command` uses
-`--show-token --no-save` and `data.auth_handoff.rerun_guide.with_stdin` shows
-the token-stdin rerun path instead of asking the agent to try a doomed saved
-signup.
+path first. If local config cannot be written, `data.next_command` prefixes the
+normal saved-config signup with
+`IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"`, so the first recovery
+step still saves auth locally without exposing the one-time token.
+`--show-token --no-save` and `data.auth_handoff.rerun_guide.with_stdin` remain
+structured fallback paths for runtimes that intentionally use a separate secret
+store.
 
 ### `image-skill whoami`
 
 Shows current actor, organization, claim state, token class, and grants.
+The JSON includes `session_origin` so a fresh agent can tell whether it is
+unauthenticated, loaded a saved config, created the token in this process, or
+is using hosted-session auth. `token_created_at` is the active token creation
+timestamp when Image Skill can prove it, otherwise `null`.
 
 ```bash
 image-skill whoami --json
 ```
 
+Minimum success data:
+
+```json
+{
+  "authenticated": true,
+  "session_origin": "loaded_from_config",
+  "token_status": "active",
+  "token_created_at": "2026-05-08T12:00:00.000Z"
+}
+```
+
 ### `image-skill usage quota`
 
 Canonical pre-spend check. Shows remaining credits, job limits, model limits,
@@ -343,8 +417,11 @@ Minimum success data:
     {
       "pack_id": "starter-500",
       "name": "Starter",
+      "display_name": "Starter (500 credits)",
       "credits": 500,
       "amount_cents": 500,
+      "amount_usd": "5.00",
+      "price_usd": "5.00",
       "currency": "USD"
     }
   ],
@@ -375,14 +452,17 @@ model's provider cost and Image Skill's margin policy; inspect
 debit before spending.
 
 ```bash
-image-skill credits quote --credits 10 --payment-method stripe_checkout --json
+image-skill credits quote --credits 10 --payment-method stripe_x402.exact.usdc --json
 ```
 
-For retry-stable automation, provide an explicit non-secret idempotency key:
+Always pass the payment method from `credits methods --json`; the public CLI
+does not infer one. For retry-stable automation, provide an explicit non-secret
+idempotency key:
 
 ```bash
 image-skill credits quote \
   --credits 10 \
+  --payment-method stripe_x402.exact.usdc \
   --idempotency-key quote-run-001 \
   --json
 ```
@@ -413,8 +493,9 @@ image-skill credits quote \
   --json
 ```
 
-For exact custom Stripe Checkout terms, request the provider and bounded credit
-amount explicitly:
+For exact custom terms, keep the same rail choice. Use
+`stripe_x402.exact.usdc` for an agent-settleable browserless rail, or use
+`stripe_checkout` only for a human Checkout fallback:
 
 ```bash
 image-skill credits quote \
@@ -470,6 +551,10 @@ settlement and webhook fulfillment succeeds. Deposit challenge creation itself
 must not mutate credit balances. Stay within the delegated cap and never pass
 wallet private keys, seed phrases, x402 payment headers, deposit client
 secrets, card data, Stripe secrets, or provider receipts to Image Skill.
+When `create --guide` enters `quota_required` for this rail, it returns
+`data.self_fund_handoff.wallet_settlement` with the buy/status response fields
+to inspect: `data.stripe_x402.payable_instructions` after `credits buy`, or
+`data.payment_attempt.stripe_x402.payable_instructions` after `credits status`.
 
 ```bash
 image-skill credits buy \
@@ -600,18 +685,23 @@ curl -sS https://api.image-skill.com/v1/credit-purchases/stripe-x402-deposits \
 
 ### `image-skill credits status`
 
-Shows the durable state of a quote, x402 deposit attempt, Stripe Checkout
-attempt, Checkout Session, or receipt. Use this after `credits buy` so agents
-do not have to infer payment state from quota deltas or activity text.
+Without a payment reference, shows the current credit balance using the same
+quota data as `image-skill usage quota --json`. With a payment reference,
+shows the durable state of a quote, x402 deposit attempt, Stripe Checkout
+attempt, Checkout Session, or receipt. Use the referenced form after
+`credits buy` so agents do not have to infer payment state from quota deltas
+or activity text.
 
 ```bash
+image-skill credits status --json
 image-skill credits status \
   --payment-attempt-id payatt_... \
   --json
 ```
 
-Exactly one reference flag is required: `--quote-id`,
-`--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`.
+At most one reference flag is allowed: `--quote-id`,
+`--payment-attempt-id`, `--checkout-session-id`, or `--receipt-id`. Passing no
+reference returns the balance/quota state.
 
 Minimum action-required data:
 
@@ -672,16 +762,20 @@ capability-preserving schema for one model.
 ```bash
 image-skill models --json
 image-skill models list --json
+image-skill models list --summary --json
 image-skill models list --available --operation image.generate --json
 image-skill models list --available --operation image.edit --json
+image-skill models list --available --modality video --operation video.generate --json
 image-skill models list --catalog-only --provider fal --json
 image-skill models show MODEL_ID --json
+image-skill models show default --json
 ```
 
 Hosted API equivalents:
 
 ```bash
 curl -sS https://api.image-skill.com/v1/models
+curl -sS 'https://api.image-skill.com/v1/models?available=true&modality=video&operation=video.generate'
 curl -sS https://api.image-skill.com/v1/models/xai.grok-imagine-image
 ```
 
@@ -692,17 +786,27 @@ seeds, masks, reference images, transparent backgrounds, arbitrary aspect
 ratios, image-size presets, output counts, resolution controls, safety
 controls, or provider-native options.
 
-`models list` is executable-first by default and returns `summary` with total,
-returned, available, executable, catalog-only, provider split,
+`models list` is executable-first by default and returns one
+`default: true` row when the default executable create model is included.
+`models show default --json` resolves to that model so first-run agents can
+inspect the recommended create surface without knowing a provider-specific
+model id. The list response also returns `summary` with total, returned,
+available, executable, catalog-only, provider split,
 `execution_availability`, first actionable model ids, recommended filter
 commands, and catalog-inclusion flags. Default list output excludes
 catalog-only rows so fresh agents see executable candidates first. Use
-`--available` for currently usable executable rows, `--operation
-image.generate` or `--operation image.edit` for the task, `--provider fal|xai|openai`
-to narrow by provider, and `--catalog-only` when you intentionally want
-source-backed rows that are inspectable but not runnable yet. Provider-level
-availability is not the same thing as model executability; for runnable
-choices require both `status:"available"` and
+`--summary` when you need a compact, sortable model menu: each row keeps the
+model id, flat `estimated_usd_per_image`, `credits_required`, lightweight
+`task_tags`, status, provider, max output count/resolution, storage, and
+`show_command`, while omitting full parameter schemas. Use `--available` for
+currently usable executable rows, `--modality image|video|audio|3d` for media
+type, `--operation image.generate`, `--operation image.edit`,
+`--operation video.generate`, `--operation audio.generate`, or
+`--operation 3d.generate` for the task, `--provider fal|xai|openai` to narrow by
+provider, and `--catalog-only` when you intentionally want source-backed rows
+that are inspectable but not runnable yet. Provider-level availability is not
+the same thing as model executability; for runnable choices require both
+`status:"available"` and
 `execution.model_execution_status:"executable"`. If a reachable provider has no
 runnable model for the requested operation, `summary.execution_availability`
 says so directly and includes the fastest `--available --operation ...`
@@ -790,10 +894,23 @@ image-skill create --guide --prompt "A compact field camera on a stainless workb
 ```
 
 `create --guide` returns `schema: image-skill.create-guide.v1`,
-`stage`, `next_command`, `escape_hatches`, selected executable model and cost,
-auth/quota/payment blockers, and mutation flags. All mutation flags must be
-false in guide mode: no provider call, hosted create, signup, payment object,
-credit debit, or media write.
+`stage`, `next_command`, `guide_warning`, `auth_ready`, `no_spend_evaluation`,
+`recommended_no_spend_command`,
+`self_fund_next_command`, `self_fund_handoff`, `escape_hatches`, selected
+executable model and cost, auth/quota/payment blockers, and mutation flags. All
+mutation flags must be false in guide mode: no provider call, hosted create,
+signup, payment object, credit debit, or media write.
+For next-command safety, read `guide_warning.next_command_safety` before
+acting: `hosted_signup_no_spend_setup` is no-spend auth setup,
+`live_money_payment_action` is top-up/payment work, and
+`live_media_create_credit_debit` is a live create that can call a provider,
+debit credits, and write media.
+For payment state, read
+`checks.payments.preferred_method_summary.top_up_path` instead of inferring
+from several arrays. It is `browserless_agent_self_fund` when the preferred
+rail is live money, browserless, agent initiated, and agent settleable;
+`human_payment_handoff` when a human/browser completion step is required; and
+`payment_method_inspection` when the guide cannot classify a direct top-up path.
 In guide cost output, `cost.estimated_usd_per_image` is the estimated Image
 Skill debit in dollars for one output, matching
 `cost.estimated_debit_usd_per_image` and
@@ -846,9 +963,12 @@ operation debits across all requested outputs. `--max-estimated-usd-per-image`
 and raw API `max_estimated_usd_per_image` are per-image Image Skill debit
 budget guards.
 
-Generate video through the same `create` command and durable-media loop. Because
-the no-model default selects an image model, request a video model by id; the
-response returns a durable owned `video_...` mp4 asset URL, a `job_id`, and a
+Generate video through the same `create` command and durable-media loop. For
+video prompts, run `image-skill create --guide --prompt "..." --json`; the guide
+can select the executable video model, suggest `--aspect-ratio 16:9`, and emit
+the next create command. Plain `create` without a model still defaults to an
+image model, so use the guide or pass the video model id directly. The response
+returns a durable owned `video_...` mp4 asset URL, a `job_id`, and a
 `cost.credit_pricing` receipt just like an image create.
 
 ```bash
@@ -859,10 +979,12 @@ image-skill create \
   --json
 ```
 
-Inspect parameters, output media type, and cost first with `image-skill models
-show fal.ltx-video-13b-distilled --json`. Video runs synchronously through the
-same create call and can take longer than an image; the returned `assets[].url`
-is an owned `video/mp4`.
+Discover runnable video models with `image-skill models list --available
+--modality video --operation video.generate --json`. Inspect parameters, output
+media type, and cost first with `image-skill models show
+fal.ltx-video-13b-distilled --json`. Video runs synchronously through the same
+create call and can take longer than an image; the returned `assets[].url` is an
+owned `video/mp4`.
 
 Generate audio (music, sound) through the same `create` command and
 durable-media loop. Request an audio model by id; the response returns a durable
@@ -964,17 +1086,23 @@ for concrete quality/size requests; GPT Image 2 edit still requires
 unknown-cost acceptance before execution, but records usage-priced provider cost
 after execution when OpenAI returns token usage. Provider-native controls remain
 visible for planning and fail closed until their capability schema marks them
-executable. Hosted
-`create --dry-run` validates `model_parameters` against the selected model,
-returns accepted keys/provenance and request-aware credit pricing for planning,
-and never executes provider controls or consumes credits.
+executable. Hosted `create --dry-run` validates `model_parameters` against the
+selected model, returns accepted keys/provenance and request-aware credit
+pricing for planning, and never executes provider controls or consumes credits.
+Hosted `edit --dry-run` validates the same owned input, mask/reference,
+prompt-policy, budget, and `model_parameters` checks as a live edit, then
+returns planned outputs without storage, provider, or billing side effects.
 For dry-run responses, `cost.credit_pricing.credits_required` is the planned
 live execution debit for the selected model. The actual debit for the dry run is
 `quota.consumed_credits: 0`.
-Authenticated hosted create dry-runs also create a recoverable planned job:
+Authenticated hosted dry-runs also create a recoverable planned job:
 `jobs show` returns `status: "planned"` with `plan_receipt`, and `activity`
 emits `job.planned`. Planned receipts do not create downloadable media assets or
-usage debits.
+usage debits, media writes, or provider execution. In the first-run guide, this
+exact no-spend command behavior is exposed as
+`data.no_spend_next_command_effect` and
+`data.recommended_no_spend_command_effect`; the evaluator stop policy is exposed
+as `data.no_spend_evaluation`.
 
 Minimum success data:
 
@@ -1145,6 +1273,10 @@ If `--input` is a local path or external URL, the public CLI first normalizes it
 through the same upload resolver as `image-skill upload`, then sends only the
 resulting `asset_id` to `POST /v1/edit`. If `--input` is an Image Skill asset id
 or owned asset URL, edit uses that owned asset directly.
+Add `--dry-run` to plan the edit after owned-asset, prompt-policy,
+`model_parameters`, and budget validation. Dry-run edit responses return planned
+assets and `quota.consumed_credits: 0`, store a recoverable `job.planned`
+receipt, and do not call the provider, debit credits, or write media.
 For models with wired mask support, `--mask` follows the same upload/asset-id
 resolver and sends only `mask_asset_id`; never pass provider-native `mask_url`
 through `model_parameters`.
@@ -1213,6 +1345,10 @@ Direct `/v1/edit` callers use the same owned-asset contract:
 }
 ```
 
+Set `dry_run: true` on `/v1/edit` to get the same no-spend plan the CLI returns.
+The server still validates ownership, prompt policy, references, masks,
+`model_parameters`, and budget guards before returning the planned job.
+
 Create a 3D asset from an image through the same `edit` command and
 durable-media loop. Image-to-3D is promptless and image-conditioned, so it ships
 as a variation transform: pass exactly one owned input image (no prompt) to a 3D
@@ -1352,11 +1488,39 @@ image-skill jobs show job_... --json
 ```
 
 Output includes public job status, trace id, timestamps, capability id, cost
-summary, safety status, and Image Skill-owned asset metadata. Provider/model
-provenance is available only through explicit provenance/debug affordances for
-authorized actors. Default output does not include raw prompts, generated bytes, provider
+summary, safety status, and Image Skill-owned asset metadata. For fresh-agent
+parsing, `status`, `state`, `assets`, and `cost` are mirrored at top level and
+match `job.status`, `job.assets`, and `job.cost`. Provider/model provenance is
+available only through explicit provenance/debug affordances for authorized
+actors. Default output does not include raw prompts, generated bytes, provider
 credentials, DB/storage keys, bucket names, or local paths.
 
+Minimum success data:
+
+```json
+{
+  "request": {
+    "job_id": "job_..."
+  },
+  "status": "completed",
+  "state": "completed",
+  "assets": [],
+  "cost": {
+    "estimated_usd": 0.05,
+    "provider_reported_usd_ticks": null
+  },
+  "job": {
+    "job_id": "job_...",
+    "status": "completed",
+    "assets": [],
+    "cost": {
+      "estimated_usd": 0.05,
+      "provider_reported_usd_ticks": null
+    }
+  }
+}
+```
+
 ### `image-skill jobs wait`
 
 Waits for a hosted Image Skill job to reach a terminal status.
@@ -1366,7 +1530,9 @@ image-skill jobs wait job_... --timeout-ms 30000 --poll-interval-ms 1000 --json
 ```
 
 Completed jobs return immediately. Non-terminal jobs poll until completion,
-failure, cancellation, or deterministic timeout.
+failure, cancellation, or deterministic timeout. Terminal success uses the same
+top-level `status`, `state`, `assets`, and `cost` mirrors as `jobs show`, with
+`request.timeout_ms` and `request.poll_interval_ms` added for provenance.
 
 ### `image-skill activity list`
 
@@ -1456,7 +1622,7 @@ below.
 | Event type                                 | Subject    | Operation   | Emitted when                                                       | Stable links                                                       |
 | ------------------------------------------ | ---------- | ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
 | `job.completed`                            | `job`      | create/edit | A hosted create or edit job reaches a terminal state.              | `job_id`, `asset_ids`, `usage_event_id`                            |
-| `job.planned`                              | `job`      | create      | An authenticated create dry-run stores a recoverable plan receipt. | `job_id`                                                           |
+| `job.planned`                              | `job`      | create/edit | An authenticated hosted dry-run stores a recoverable plan receipt. | `job_id`                                                           |
 | `asset.created`                            | `asset`    | create/edit | A hosted create or edit produces an output asset.                  | `job_id`, `asset_ids`, `usage_event_id`                            |
 | `asset.uploaded`                           | `asset`    | upload      | A public edit workflow uploads or imports input media.             | `job_id`, `asset_ids`, `usage_event_id`                            |
 | `usage.credit_consumed`                    | `usage`    | usage       | A creative operation records a preview-credit entry.               | `job_id`, `usage_event_id`                                         |
@@ -1475,7 +1641,7 @@ machine-readable lifecycle fields such as `state`, `reason`, `issue_urls`,
 `issue_numbers`, `mode`, and `github_mutation`. Agents should use it to learn
 whether submitted feedback was promoted, skipped, deduped, blocked, or already
 mirrored without reading private repository artifacts.
-`job.planned` includes `details.plan_receipt` for authenticated hosted create
+`job.planned` includes `details.plan_receipt` for authenticated hosted
 dry-runs. It is a recoverable planning receipt, not completed media work:
 planned outputs do not have durable asset IDs, download URLs, usage debits, or
 provider execution.
@@ -1508,7 +1674,12 @@ image-skill feedback create \
   --json
 ```
 
-Hosted feedback requires `IMAGE_SKILL_TOKEN` and persists through
+Hosted feedback authenticates the same way as other hosted commands: saved
+public CLI config from default signup, `IMAGE_SKILL_TOKEN`, or
+`--token-stdin`. If guide/signup already saved config, run `feedback create`
+normally; no raw token copy step is required. If the runtime uses its own
+secret store, prefer `IMAGE_SKILL_TOKEN` or `--token-stdin`. Do not paste tokens
+into feedback title, body, evidence, issues, or logs. Feedback persists through
 `https://api.image-skill.com/v1/feedback`. The hosted API fails closed if
 durable hosted feedback storage is unavailable.
 
@@ -1524,8 +1695,8 @@ example, `BUDGET_REQUIRES_CONFIRMATION` returns
 secret handoff.
 `credits methods` and `credits packs list` do not require auth.
 
-Feedback should avoid raw prompts, provider keys, generated image bytes, source
-image bytes, and private user data.
+Feedback should avoid raw prompts, hosted tokens, provider keys, generated
+image bytes, source image bytes, and private user data.
 
 Hosted API equivalent: