image-skill 0.1.6 → 0.1.8

package/cli.md

@@ -92,6 +92,44 @@ printf '%s\n' "$IMAGE_SKILL_TOKEN" | image-skill usage quota --token-stdin --jso
 `--api-base-url` is an advanced preview/test override; production public agents
 should omit it.
 
+### Local Config And Install
+
+Prefer package execution in fresh agent sandboxes:
+
+```bash
+npm exec --yes --package image-skill@latest -- image-skill doctor --json
+```
+
+Global install is optional, not the primary path. If `npm install -g image-skill`
+or `npx image-skill@latest ...` hits prefix/cache `EACCES`, retry with writable
+package-manager paths instead of cloning private source:
+
+```bash
+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"
+npm exec --yes --package image-skill@latest -- image-skill doctor --json
+```
+
+Saved auth state defaults to
+`${XDG_CONFIG_HOME:-~/.config}/image-skill/config.json`. If that location is
+read-only, set a writable config path before `signup --save`:
+
+```bash
+export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
+npm exec --yes --package image-skill@latest -- image-skill signup --agent \
+  --agent-contact agent-ops@example.com \
+  --agent-name creative-agent \
+  --runtime codex \
+  --save \
+  --json
+```
+
+Config write failures return `PUBLIC_CLI_CONFIG_WRITE_FAILED` with a structured
+`error.recovery.suggested_command`. Agents should follow that recovery field,
+then continue with `whoami`, `usage quota`, `models list`, and the requested
+creative flow.
+
 ### `image-skill whoami`
 
 Shows current actor, organization, claim state, token class, and grants.
@@ -293,9 +331,21 @@ curl -sS https://api.image-skill.com/v1/credit-quotes \
 
 Creates a live-provider payment action for a previously returned quote. Stripe
 Checkout is the first supported provider. This creates a hosted Stripe Checkout
-Session and returns an `action_required` response with `checkout_url`; credits
-are granted only after verified Stripe webhook fulfillment succeeds. Session
-creation itself must not mutate credit balances.
+Session and returns an `action_required` response with
+`checkout_handoff_url`; credits are granted only after verified Stripe webhook
+fulfillment succeeds. Session creation itself must not mutate credit balances.
+
+Agents should present or open `checkout_handoff_url` for humans. It is a short
+Image Skill URL that redirects to Stripe Checkout and is safe to copy from
+mobile terminals, SSH clients, and wrapped chat output. `checkout_url` remains
+the Stripe compatibility fallback and is fragment-stripped by current API/CLI
+responses for human copy/paste; do not ask a person to copy it when
+`checkout_handoff_url` is present.
+
+If a stale server or older client exposes a raw Stripe URL with a long `#...`
+fragment, remove the fragment and use `checkout_compact_url` for human
+copy/paste. Present any fallback Stripe URL in a fenced code block so terminal
+wrapping does not corrupt it.
 
 ```bash
 image-skill credits buy \
@@ -315,14 +365,19 @@ Minimum success data:
   "provider": "stripe",
   "accepted_payment_method": "stripe_checkout",
   "checkout_session_id": "cs_...",
-  "checkout_url": "https://checkout.stripe.com/...",
+  "checkout_handoff_url": "https://api.image-skill.com/pay/payatt_...",
+  "checkout_compact_url": "https://checkout.stripe.com/c/pay/cs_...",
+  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
   "credits": 500,
   "amount_cents": 500,
   "currency": "USD",
   "live_money": true,
   "next": {
     "human_action": "open_checkout_url",
-    "after_payment": "poll image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json or image-skill usage quota --json; credits are granted only after verified webhook fulfillment"
+    "checkout_handoff_url": "https://api.image-skill.com/pay/payatt_...",
+    "checkout_compact_url": "https://checkout.stripe.com/c/pay/cs_...",
+    "fallback_checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
+    "after_payment": "open checkout_handoff_url, or checkout_compact_url if only a Stripe URL is available, then poll image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json or image-skill usage quota --json; credits are granted only after verified webhook fulfillment"
   }
 }
 ```
@@ -366,14 +421,18 @@ Minimum action-required data:
   "payment_attempt": {
     "payment_attempt_id": "payatt_...",
     "checkout_session_id": "cs_...",
-    "checkout_url": "https://checkout.stripe.com/...",
+    "checkout_handoff_url": "https://api.image-skill.com/pay/payatt_...",
+    "checkout_compact_url": "https://checkout.stripe.com/c/pay/cs_...",
+    "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
     "attempt_status": "requires_action"
   },
   "receipt": null,
   "credit_event": null,
   "next": {
     "retry_after_seconds": 10,
-    "human_action": "open_checkout_url"
+    "human_action": "open_checkout_url",
+    "checkout_handoff_url": "https://api.image-skill.com/pay/payatt_...",
+    "checkout_compact_url": "https://checkout.stripe.com/c/pay/cs_..."
   }
 }
 ```
@@ -468,12 +527,60 @@ must not flatten rich model capabilities into coarse universal categories.
 Use `model_parameters` for rare or model-specific parameters advertised by the
 capability schema.
 
-GPT Image 2 is exposed as `openai.gpt-image-2` for create and
-`openai.gpt-image-2-edit` for edit when OpenAI is configured. Inspect these
-models before use; OpenAI provider-native controls such as size, output
-format, compression, background, moderation, and the upstream
-provider-native quality parameter are available only through validated
-`model_parameters`.
+Current executable provider-native controls include:
+
+- Fal FLUX.1 dev: `model_parameters.image_size` for presets such as
+  `square_hd`, plus `seed`.
+- Fal FLUX Pro 1.1 Ultra Create: `model_parameters.seed` and
+  `model_parameters.raw`; optional reference-image controls remain cataloged
+  for inspection but are not executable on the create-only path.
+- Fal Z-Image Turbo Create/Edit: `model_parameters.image_size` for
+  `square_hd`, `square`, portrait/landscape presets, and `auto` on edit; costs
+  are quoted from requested megapixels when the output size is explicit.
+- Fal Nano Banana 2 Edit: `model_parameters.resolution` for `0.5K`, `1K`,
+  `2K`, and `4K`, plus `seed`.
+- Fal Ideogram V2 Edit: `model_parameters.expand_prompt`, `seed`, and
+  `style`; pass masks as top-level `--mask` / `mask_asset_id`, not as
+  provider `mask_url`.
+- Fal Gemini 3 Pro Image Preview Create/Edit:
+  `model_parameters.resolution` for `1K`, `2K`, and `4K`, plus `seed`; 4K is
+  quoted as the higher-priced provider tier.
+- Fal Nano Banana Pro Create/Edit: `model_parameters.resolution` for `1K`,
+  `2K`, and `4K`, plus `seed`; 4K is quoted as the higher-priced provider tier.
+- Fal FLUX Pro Kontext Pro/Max Edit: `model_parameters.seed`; guidance scale
+  and aspect-ratio controls remain cataloged for inspection but are not
+  executable until their UX and receipt behavior are represented.
+- Fal Bytedance Seedream 4.5 Create/Edit: `model_parameters.image_size` for
+  `square_hd`, `square`, portrait/landscape presets, `auto_2K`, and
+  `auto_4K`, plus `seed`; multi-output and multi-reference controls remain
+  cataloged but fixed for hosted accounting.
+- Fal Bytedance Seedream 5.0 Lite Create/Edit:
+  `model_parameters.image_size` for `square_hd`, `square`, portrait/landscape
+  presets, `auto_2K`, and `auto_3K`; multi-output and multi-reference controls
+  remain cataloged but fixed for hosted accounting.
+- xAI Grok Imagine Image Quality: `model_parameters.resolution` for `1k` and
+  `2k`; 2k is priced from the higher provider tier. Create supports top-level
+  `--output-count` up to the model's advertised `max_outputs_per_request`,
+  currently mapped to xAI's documented `n` batch parameter.
+- GPT Image 1.5 create/edit: documented fixed sizes `1024x1024`,
+  `1024x1536`, and `1536x1024`, output format, compression, transparent or
+  opaque background, moderation, and the upstream provider-native quality
+  parameter. GPT Image 1.5 create quotes output-token estimates when quality
+  and concrete size are known; GPT Image 1.5 create supports top-level
+  `--output-count` up to the model's advertised `max_outputs_per_request`,
+  currently mapped to OpenAI's `n` parameter. GPT Image 1.5 edit accepts
+  low/high `input_fidelity` and remains preflight unknown-cost until usage is
+  returned.
+- GPT Image 2 create/edit: size, output format, compression, background,
+  moderation, and the upstream provider-native quality parameter. GPT Image 2
+  create quotes request-aware output-token estimates when quality and concrete
+  size are known; GPT Image 2 create supports top-level `--output-count` up to
+  the model's advertised `max_outputs_per_request`, currently mapped to
+  OpenAI's `n` parameter. GPT Image 2 edit remains preflight unknown-cost, then
+  records usage-priced provider cost when OpenAI returns token usage.
+
+Inspect each model before use; provider-native controls are available only
+through validated `model_parameters`.
 
 ### `image-skill capabilities`
 
@@ -499,29 +606,125 @@ image-skill create \
   --json
 ```
 
+Hosted defaults are quality-first. If an agent does not choose a model, Image
+Skill selects the strongest available create capability for the requested
+intent and budget, then records the decision in `request.selection`. Explicit
+`--provider`, `--model`, namespaced model ids, and validated
+`model_parameters` always take precedence. For final/product/hero-style
+intents, Image Skill may default an eligible quality-capability request to a
+higher output tier only when `--max-estimated-usd-per-image` is high enough for
+that tier; otherwise it stays on a lower-cost quality tier or chooses a cheaper
+capability within the budget and tells agents what happened in the selection
+receipt.
+
 Preview-compatible richer shape:
 
 ```bash
 image-skill create \
-  --prompt-file ./prompt.md \
+  --prompt "Campaign-ready product image of a compact field camera" \
   --intent finalize \
   --model MODEL_ID \
   --aspect-ratio 1:1 \
-  --format png \
-  --max-usd 0.25 \
+  --output-count 2 \
+  --max-estimated-usd-per-image 0.07 \
   --model-parameters-json '{"seed":1234}' \
   --json
 ```
 
+Use `--output-count N` only when `models show MODEL_ID --json` advertises
+`media.output.max_outputs_per_request` greater than `1`. `--output-count` is a
+top-level Image Skill create control; do not pass provider-native `n` through
+`model_parameters` unless the selected model schema explicitly advertises that
+field. Credit pricing and `cost.credit_pricing.credits_required` are total
+operation debits across all requested outputs. `--max-estimated-usd-per-image`
+and raw API `max_estimated_usd_per_image` remain per-image budget guards.
+
+For create models with wired reference support, pass owned reference assets
+with the model's advertised reference role. Kling element routes use
+`--element-frontal IMAGE[@ELEMENT_INDEX]` and
+`--element-reference IMAGE[@ELEMENT_INDEX[:REFERENCE_INDEX]]`; flat
+reference-image routes use `--reference-image IMAGE[@INDEX]`; Fal DreamO also
+accepts `:TASK` where `TASK` is `ip`, `id`, or `style`. The public CLI uploads
+local paths and external URLs first, then
+sends top-level `references[]` entries with Image Skill `asset_id` values to
+`/v1/create`. Do not pass provider-native `elements`, `frontal_image_url`,
+`reference_image_urls`, `first_image_url`, `second_image_url`, `images`, or
+`*_reference_task` through `model_parameters`; provider-private URLs are
+resolved server-side after ownership and media-policy validation.
+
+```bash
+image-skill create \
+  --model fal.kling-image-o3-text-to-image \
+  --prompt "Place the same character in a clean studio campaign" \
+  --element-frontal ./character-front.png@0 \
+  --element-reference ./character-side.webp@0:0 \
+  --output-count 2 \
+  --max-estimated-usd-per-image 0.06 \
+  --json
+```
+
+```bash
+image-skill create \
+  --model fal.dreamo \
+  --prompt "Studio portrait preserving identity with a bolder editorial style" \
+  --reference-image ./identity.png@0:id \
+  --reference-image ./style.webp@1:style \
+  --model-parameters-json '{"image_size":{"width":1280,"height":720}}' \
+  --max-estimated-usd-per-image 0.06 \
+  --json
+```
+
+High-resolution examples:
+
+```bash
+image-skill create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --intent final \
+  --max-estimated-usd-per-image 0.07 \
+  --json
+
+image-skill create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --model fal.gemini-3-pro-image-preview \
+  --model-parameters-json '{"resolution":"4K"}' \
+  --max-estimated-usd-per-image 0.30 \
+  --json
+
+image-skill create \
+  --prompt "Campaign-ready product image of a compact field camera" \
+  --model xai.grok-imagine-image-quality \
+  --model-parameters-json '{"resolution":"2k"}' \
+  --max-estimated-usd-per-image 0.07 \
+  --json
+
+image-skill edit \
+  --input-asset-id image_... \
+  --prompt "preserve the subject and make this campaign-ready" \
+  --model fal.nano-banana-2-edit \
+  --model-parameters-json '{"resolution":"4K"}' \
+  --accept-unknown-cost \
+  --json
+```
+
 `model_parameters` must be validated against the selected model/capability
 schema before any provider call or paid reservation. Unknown fields fail closed
 unless the capability explicitly allows additional properties. This is how
 Image Skill preserves rare model controls without turning every
 provider-specific parameter into a top-level flag.
-In the current preview, Fal create/edit expose executable `seed`, and OpenAI
-GPT Image 2 exposes documented provider-native controls through
-`model_parameters`. Provider-native controls remain visible for planning and
-fail closed until their capability schema marks them executable.
+In the current preview, Fal create/edit, xAI quality generation, and OpenAI GPT
+Image 2 expose the executable provider-native controls listed in the selected
+model schema. GPT Image 2 create has request-aware output-token credit quotes
+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.
+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`.
 
 Minimum success data:
 
@@ -536,19 +739,44 @@ Minimum success data:
       "asset_id": "image_...",
       "path": "https://media.image-skill.com/a/image_abc123.png",
       "mime_type": "image/png",
-      "url": "https://media.image-skill.com/a/image_abc123.png"
+      "url": "https://media.image-skill.com/a/image_abc123.png",
+      "content_length": 333444,
+      "width": 1024,
+      "height": 1024
     }
   ],
   "cost": {
-    "estimated_usd": 0.025,
+    "estimated_usd": 0.05,
     "credit_pricing": {
       "credit_unit_usd": 0.01,
-      "credits_required": 5,
-      "estimated_provider_cost_usd": 0.025,
-      "estimated_revenue_usd": 0.05,
+      "credits_required": 9,
+      "estimated_provider_cost_usd": 0.05,
+      "estimated_revenue_usd": 0.09,
       "pricing_confidence": "known"
     }
   },
+  "request": {
+    "output_count": 1,
+    "selection": {
+      "policy": "hosted_default_create_v1",
+      "reason": "hosted default selected the strongest currently available quality-first create model",
+      "intent": "explore",
+      "capability": {
+        "id": "is.image.generate.xai-grok-imagine-image-quality.v1"
+      },
+      "model_parameters": {
+        "keys": ["resolution"],
+        "defaults_applied": ["resolution=1k"],
+        "source": "default_policy"
+      },
+      "output": {
+        "resolution_class": "1k",
+        "expected_width": null,
+        "expected_height": null,
+        "expected_min_short_edge": 1024
+      }
+    }
+  },
   "safety": {
     "status": "allowed"
   }
@@ -578,6 +806,7 @@ curl -sS https://api.image-skill.com/v1/create \
     "prompt": "A compact field camera on a stainless workbench",
     "intent": "explore",
     "aspect_ratio": "1:1",
+    "output_count": 1,
     "max_estimated_usd_per_image": 0.05,
     "model_parameters": {
       "seed": 1234
@@ -586,7 +815,8 @@ curl -sS https://api.image-skill.com/v1/create \
 ```
 
 Hosted free-preview create currently requires owned artifact storage and returns
-`assets[].url` under `https://media.image-skill.com/...` on success.
+one `assets[]` entry per output with `assets[].url` under
+`https://media.image-skill.com/...` on success.
 
 ### `image-skill upload`
 
@@ -643,6 +873,7 @@ with one hosted provider-backed edit model.
 ```bash
 image-skill edit \
   --input ASSET_ID_OR_PATH_OR_URL \
+  --mask MASK_ASSET_ID_OR_PATH_OR_URL \
   --prompt "Remove the background and keep natural object shadows" \
   --accept-unknown-cost \
   --json
@@ -652,16 +883,114 @@ 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.
+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`.
+For models with wired reference support, pass owned reference assets with the
+model's advertised reference role. Kling element routes use
+`--element-frontal IMAGE[@ELEMENT_INDEX]` and
+`--element-reference IMAGE[@ELEMENT_INDEX[:REFERENCE_INDEX]]`; flat
+reference-image routes use `--reference-image IMAGE[@INDEX[:TASK]]`. The
+public CLI uploads local paths and external URLs first, then sends top-level
+`references[]` entries with Image Skill `asset_id` values. For Kling element
+routes, `--element-frontal ./front.png@0` becomes role `element_frontal` for
+element index `0`, and `--element-reference ./side.webp@0:0` becomes role
+`element_reference` for the same element with reference slot `0`. For DreamO
+create, `--reference-image ./identity.png@0:id` becomes role
+`reference_image`, index `0`, and `reference_task` `id`. For xAI edit,
+`--reference-image ./reference.png@0` becomes the second ordered source image;
+the primary `--input` asset remains the first source image. Do not pass
+provider-native `elements`, `image_url`, `image_urls`, `frontal_image_url`,
+`reference_image_urls`, `first_image_url`, `second_image_url`, `images`, or
+`*_reference_task` through `model_parameters`; provider-private URLs are
+resolved server-side after ownership and media-policy validation.
+Current public `references[]` support covers Kling Image O1, Kling Image O3
+image-to-image/text-to-image, Kling Image v3 image-to-image/text-to-image, and
+Fal DreamO create plus xAI Grok Imagine image edit/quality edit. Kling requests
+may contain at most 40 reference entries across at most 10 contiguous element
+indexes starting at `0`; each referenced element requires one frontal image and
+may include up to three additional reference images. DreamO accepts up to two
+contiguous `reference_image` indexes starting at `0`, each with optional
+`reference_task` `ip`, `id`, or `style`. xAI edit accepts up to two contiguous
+`reference_image` indexes starting at `0` and does not accept `reference_task`.
+Reference assets must be Image Skill-owned PNG, JPEG, or WebP images with
+known non-empty byte length up to 10MB, known width and height of at least
+300px, and aspect ratio from 0.40 to 2.50.
+
+```bash
+image-skill edit \
+  --model fal.kling-image-o3-image-to-image \
+  --input ./starting-frame.png \
+  --element-frontal ./character-front.png@0 \
+  --element-reference ./character-side.webp@0:0 \
+  --prompt "Place the same character in a clean studio product portrait" \
+  --accept-unknown-cost \
+  --json
+```
+
+Direct `/v1/edit` callers use the same owned-asset contract:
+
+```json
+{
+  "input_asset_id": "image_starting_frame",
+  "model": "fal.kling-image-o3-image-to-image",
+  "prompt": "Place the same character in a clean studio product portrait",
+  "references": [
+    {
+      "asset_id": "image_character_front",
+      "role": "element_frontal",
+      "index": 0
+    },
+    {
+      "asset_id": "image_character_side",
+      "role": "element_reference",
+      "index": 0,
+      "reference_index": 0
+    }
+  ]
+}
+```
 
-Preview hosted edit supports model-specific provider-backed edit paths such as
-Fal Nano Banana 2 Edit (`fal.nano-banana-2-edit`) and GPT Image 2 Edit
+Preview hosted create/edit supports model-specific provider-backed paths such
+as Fal Gemini 3 Pro Image Preview Create (`fal.gemini-3-pro-image-preview`),
+Fal Nano Banana 2 Edit (`fal.nano-banana-2-edit`), Fal Ideogram V2 Edit
+(`fal.ideogram-v2-edit`), Fal Gemini 3 Pro Image
+Preview Edit (`fal.gemini-3-pro-image-preview-edit`), Fal FLUX Pro 1.1 Ultra
+Create (`fal.flux-pro-v1-1-ultra`), Fal FLUX Pro Kontext Edit
+(`fal.flux-pro-kontext`), Fal FLUX Pro Kontext Max Edit
+(`fal.flux-pro-kontext-max`), Fal Seedream 5.0 Lite Create
+(`fal.bytedance-seedream-v5-lite-text-to-image`), Fal Seedream 5.0 Lite Edit
+(`fal.bytedance-seedream-v5-lite-edit`), Fal Seedream 4.5 Create
+(`fal.bytedance-seedream-v4-5-text-to-image`), Fal Seedream 4.5 Edit
+(`fal.bytedance-seedream-v4-5-edit`), Fal Nano Banana Pro Create
+(`fal.nano-banana-pro`), Fal Nano Banana Pro Edit
+(`fal.nano-banana-pro-edit`), GPT Image 1.5 Create
+(`openai.gpt-image-1.5`), GPT Image 1.5 Edit
+(`openai.gpt-image-1.5-edit`), and GPT Image 2 Edit
 (`openai.gpt-image-2-edit`) when their provider credentials are configured.
-Current machine-readable prices are treated as unknown for these edit paths, so
-live edit requires `--accept-unknown-cost` until a stable price source is
-captured. Responses include a new generated asset URL, job id, safety state,
-quota consumption, and input asset metadata. Responses do not include raw
-prompts, source bytes, base64 payloads, local paths, full external URLs, bucket
-names, or object keys.
+Fal Gemini 3 Pro Image Preview create/edit has known per-image pricing: 1K/2K
+requests quote `$0.15` provider cost and 4K quotes the doubled provider tier.
+Fal Nano Banana Pro create/edit uses the same `$0.15` standard and doubled 4K
+provider tier. Fal FLUX Pro 1.1 Ultra Create quotes `$0.06` provider cost per
+image. Fal FLUX Pro Kontext Edit quotes `$0.04` provider cost per image, and
+Fal FLUX Pro Kontext Max Edit quotes `$0.08` provider cost per image. Fal
+Seedream 4.5 create/edit quotes `$0.04` provider cost per image.
+Fal Seedream 5.0 Lite create/edit quotes `$0.035` provider cost per image. Fal
+Z-Image Turbo create/edit quotes `$0.005/MP` when `image_size` is explicit or
+derived from aspect ratio; edit `auto` remains unknown-cost. GPT Image 1.5
+create quotes output-token estimates for concrete quality/size requests using
+OpenAI's fixed-size token table; GPT Image 1.5 edit remains preflight
+unknown-cost because edit input image/text tokens are provider-metered, then
+records usage-priced provider cost when OpenAI returns token usage. GPT Image 2
+create quotes output-token estimates for concrete quality/size requests. GPT
+Image 2 edit remains preflight unknown-cost because edit input image/text tokens
+are provider-metered, then records usage-priced provider cost when OpenAI
+returns token usage. Other edit paths without machine-readable pricing require
+`--accept-unknown-cost` until a stable price source is captured. Responses
+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.
 
 Provider/model names in this paragraph are preview provenance, not the primary
 public UX. The public selection surface should be Image Skill capabilities and
@@ -833,16 +1162,21 @@ Activity `type` values are stable public contract values. Do not infer new
 event names from provider responses or telemetry logs; use only the registry
 below.
 
-| Event type                         | Subject    | Operation   | Emitted when                                                      | Stable links                                            |
-| ---------------------------------- | ---------- | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
-| `job.completed`                    | `job`      | create/edit | A hosted create or edit job reaches a terminal state.             | `job_id`, `asset_ids`, `usage_event_id`                 |
-| `asset.created`                    | `asset`    | create/edit | A hosted create or edit produces an output asset.                 | `job_id`, `asset_ids`, `usage_event_id`                 |
-| `asset.uploaded`                   | `asset`    | upload      | A public edit workflow uploads or imports input media.            | `job_id`, `asset_ids`, `usage_event_id`                 |
-| `usage.credit_consumed`            | `usage`    | usage       | A creative operation records a preview-credit entry.              | `job_id`, `usage_event_id`                              |
-| `feedback.created`                 | `feedback` | feedback    | Hosted agent feedback is accepted into product memory.            | `feedback_id`                                           |
-| `feedback.github_queue.processed`  | `feedback` | feedback    | Feedback is processed by the GitHub implementation queue handoff. | `feedback_id`                                           |
-| `payment.checkout_session.created` | `payment`  | payment     | A Stripe Checkout session is created and awaits external action.  | `quote_id`, `payment_attempt_id`, `checkout_session_id` |
-| `credits.payment_backed_granted`   | `credit`   | credits     | Verified payment or fake-payment proof grants paid credits.       | `quote_id`, `receipt_id`, `credit_event_id`             |
+| Event type                                 | Subject    | Operation   | Emitted when                                                      | Stable links                                                       |
+| ------------------------------------------ | ---------- | ----------- | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `job.completed`                            | `job`      | create/edit | A hosted create or edit job reaches a terminal state.             | `job_id`, `asset_ids`, `usage_event_id`                            |
+| `asset.created`                            | `asset`    | create/edit | A hosted create or edit produces an output asset.                 | `job_id`, `asset_ids`, `usage_event_id`                            |
+| `asset.uploaded`                           | `asset`    | upload      | A public edit workflow uploads or imports input media.            | `job_id`, `asset_ids`, `usage_event_id`                            |
+| `usage.credit_consumed`                    | `usage`    | usage       | A creative operation records a preview-credit entry.              | `job_id`, `usage_event_id`                                         |
+| `feedback.created`                         | `feedback` | feedback    | Hosted agent feedback is accepted into product memory.            | `feedback_id`                                                      |
+| `feedback.github_queue.processed`          | `feedback` | feedback    | Feedback is processed by the GitHub implementation queue handoff. | `feedback_id`                                                      |
+| `payment.checkout_session.created`         | `payment`  | payment     | A Stripe Checkout session is created and awaits external action.  | `quote_id`, `payment_attempt_id`, `checkout_session_id`            |
+| `credits.payment_backed_granted`           | `credit`   | credits     | Verified payment or fake-payment proof grants paid credits.       | `quote_id`, `receipt_id`, `credit_event_id`                        |
+| `credits.payment_backed_refunded`          | `credit`   | credits     | A Stripe refund debits payment-backed credits.                    | `quote_id`, `receipt_id`, `payment_reversal_id`, `credit_event_id` |
+| `credits.payment_backed_disputed`          | `credit`   | credits     | A Stripe dispute debit applies to payment-backed credits.         | `quote_id`, `receipt_id`, `payment_reversal_id`, `credit_event_id` |
+| `credits.payment_backed_reinstated`        | `credit`   | credits     | Stripe dispute funds were reinstated and recorded.                | `quote_id`, `receipt_id`, `payment_reversal_id`                    |
+| `credits.payment_backed_reversal_pending`  | `credit`   | credits     | A reversal was recorded but could not be fully applied.           | `quote_id`, `receipt_id`, `payment_reversal_id`                    |
+| `credits.payment_backed_reversal_rejected` | `credit`   | credits     | A reversal was rejected because it could not safely reconcile.    | `quote_id`, `receipt_id`, `payment_reversal_id`                    |
 
 `feedback.github_queue.processed` includes `details.github_queue` with
 machine-readable lifecycle fields such as `state`, `reason`, `issue_urls`,