image-skill 0.1.0

package/llms.txt

@@ -0,0 +1,221 @@
+# Image Skill LLM Contract
+
+Status: preview hosted-product contract
+Canonical homepage: https://image-skill.com
+Canonical skill URL: https://image-skill.com/skill.md
+Canonical LLM URL: https://image-skill.com/llms.txt
+Canonical CLI URL: https://image-skill.com/cli.md
+Canonical hosted API URL: https://api.image-skill.com
+
+Purpose:
+Image Skill is a CLI-first hosted creative runtime for agents. Agents use it to create, edit, inspect, iterate on, and reuse generated images through a thin CLI/client and hosted API.
+
+Product thesis:
+Created by agents, for agents to create.
+
+Capability-preserving pillar:
+Do not handicap agent capability by reducing rich model/provider controls into
+coarse universal categories. Image Skill standardizes common controls for
+legibility and exposes introspection for model-specific controls. Agents should
+use capabilities, model parameter schemas, explicit budget/latency/output
+constraints, and validated model_parameters rather than guessing or treating
+quality tiers as a universal model abstraction.
+
+Primary public surfaces:
+- Homepage: https://image-skill.com
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Thin CLI/client: image-skill
+- Hosted API: https://api.image-skill.com for generation, editing, jobs, activity, storage, telemetry, identity, quota, and feedback
+- Hosted artifacts: prefer Image Skill-owned asset URLs such as https://media.image-skill.com/... when returned in assets[].url
+
+Actor types:
+- human: sponsor, admin, billing, or claim actor
+- agent: durable agent identity
+- session: ephemeral agent run
+- system: service automation
+
+Claim states:
+- unclaimed: restricted agent identity, tiny quota, low-risk workflows only
+- payment_backed_unclaimed: future capped paid state with receipts but no org/admin authority
+- claimed: human sponsor attached, scoped grants available
+- revoked: token or agent disabled
+
+First-run flow:
+1. image-skill doctor --json
+2. image-skill signup --agent --human-email EMAIL --agent-name NAME --runtime RUNTIME --save --json. The preview hosted signup path currently requires human_email; future payment-backed and agent-contact-backed signup paths are planned. Use --show-token only when the runtime has a separate secret store and needs the raw token once.
+3. Reuse the saved CLI auth for later commands, or store the returned data.token from --show-token in the agent runtime secret store and expose it as IMAGE_SKILL_TOKEN.
+4. image-skill whoami --json
+5. image-skill usage quota --json
+5-credit-note. 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 two-job daily cap.
+5a. image-skill credits packs list --json to inspect recommended live-money packs.
+5b. image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json for the default Stripe Checkout top-up path. Use --credits CREDITS instead of --pack only when the required exact budget is already known.
+5c. image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json when the agent has a stripe_checkout quote and needs a Stripe-hosted checkout_url. Credits are granted only after verified Stripe webhook fulfillment succeeds.
+5d. image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy or checkout completion to read durable payment state, receipt, credit_event, limits, and retry guidance without inferring from quota text.
+5e. image-skill credits quote --credits 10 --json and image-skill credits fake-purchase --quote-id QUOTE_ID --idempotency-key KEY --json only for fake/test credit-ledger proof. This moves no live money, accepts no payment credential, and returns live_money:false.
+6. image-skill create --dry-run --prompt PROMPT --json for zero-cost planning.
+7. image-skill models list --json, then image-skill models show MODEL_ID --json to inspect available creative models, operations, media inputs/outputs, model parameters, fixed controls, cost/latency class, safety behavior, and migration hints.
+8. image-skill create --prompt PROMPT --intent explore --max-estimated-usd-per-image 0.05 --json for the first bounded free-preview operation when quota allows.
+9. image-skill jobs show JOB_ID --json to recover status, cost, safety, timestamps, and final assets.
+10. image-skill assets get ASSET_URL_OR_ID --output ./result.png --json to fetch the generated asset without repeating provider work.
+11. image-skill activity list --subject JOB_ID --json to find the ledger event, trace, usage, and asset links to cite.
+12. image-skill edit --input ASSET_URL_OR_ID --prompt PROMPT --accept-unknown-cost --json for the second bounded free-preview operation when the task needs an edit.
+13. Leave image-skill feedback create --json if the first-run flow is confusing, blocked, or missing an affordance.
+14. image-skill activity show FEEDBACK_ID --json to confirm the feedback entered the hosted ledger.
+
+Core commands:
+- image-skill doctor --json
+- image-skill signup --agent --human-email EMAIL --agent-name NAME --runtime RUNTIME --save --json
+- image-skill whoami --json
+- image-skill usage quota --json
+- image-skill quota --json (compatibility alias)
+- image-skill credits packs list --json
+- image-skill credits quote --pack PACK_ID --payment-method fake|stripe_checkout --idempotency-key KEY --json
+- image-skill credits quote --credits CREDITS --payment-method fake|stripe_checkout --idempotency-key KEY --json
+- image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json
+- image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json
+- image-skill credits fake-purchase --quote-id QUOTE_ID --idempotency-key KEY --json
+- image-skill capabilities --json
+- image-skill capabilities list --json
+- image-skill capabilities show CAPABILITY_ID --json
+- image-skill models --json
+- image-skill models list --json
+- image-skill models show MODEL_ID --json
+- image-skill create --prompt PROMPT --json
+- image-skill create --dry-run --prompt PROMPT --json
+- image-skill upload PATH_OR_URL --json
+- image-skill edit --input ASSET_ID_OR_PATH_OR_URL --prompt PROMPT --accept-unknown-cost --json
+- image-skill assets show ASSET_ID_OR_URL --json
+- image-skill assets get ASSET_ID_OR_URL --output PATH --json
+- image-skill jobs show JOB_ID --json
+- image-skill jobs wait JOB_ID --timeout-ms 30000 --poll-interval-ms 1000 --json
+- image-skill activity list --limit 20 --json
+- image-skill activity list --subject JOB_OR_ASSET_OR_FEEDBACK_OR_TRACE --json
+- image-skill activity show EVENT_OR_JOB_OR_ASSET_OR_FEEDBACK_OR_TRACE --json
+- image-skill feedback create --type TYPE --title TITLE --body BODY --command COMMAND --expected EXPECTED --actual ACTUAL --proof-needed PROOF --surface cli,docs --evidence trace:TRACE_ID --severity medium --confidence high --next-state watch --json
+
+Hosted API endpoints:
+- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. The response returns the token once as data.token. Store it in the agent runtime secret store; never put it in prompts, logs, issue text, or feedback.
+- GET https://api.image-skill.com/v1/whoami returns durable hosted identity for Authorization: Bearer TOKEN.
+- GET https://api.image-skill.com/v1/quota returns durable hosted quota for Authorization: Bearer TOKEN.
+- GET https://api.image-skill.com/v1/credit-packs returns the public pack catalog. Recommended live-money packs include starter-500, builder-2000, and studio-5000. Packs are the default Stripe Checkout UX; exact quotes remain supported for agents that already know the required credit budget.
+- POST https://api.image-skill.com/v1/credit-quotes returns a fake/test or stripe_checkout credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, and live_money. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
+- POST https://api.image-skill.com/v1/credit-purchases/stripe-checkout-sessions creates a Stripe Checkout Session for a stripe_checkout quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, checkout_session_id, checkout_url, accepted_payment_method: stripe_checkout, and next.human_action: open_checkout_url. This does not grant credits; verified Stripe webhook fulfillment grants paid credits exactly once.
+- GET https://api.image-skill.com/v1/credit-purchases/status returns durable payment state for Authorization: Bearer TOKEN. Query with exactly one of quote_id, payment_attempt_id, checkout_session_id, or receipt_id. Response includes state, quote, payment_attempt, receipt, credit_event, provider_event, limits, and next.
+- POST https://api.image-skill.com/v1/credit-purchases confirms a fake/test quote for Authorization: Bearer TOKEN. Request JSON: quote_id, idempotency_key. Response includes receipt_id, credit_event_id, credits_granted, accepted_payment_method: fake, balance_after, and live_money:false. This grants bounded payment-backed credits without moving live money.
+- GET https://api.image-skill.com/v1/models returns the public model registry. GET https://api.image-skill.com/v1/models/MODEL_ID returns one model's capability-preserving schema.
+- GET https://api.image-skill.com/v1/capabilities returns the hosted capability catalog, normalized controls, model-parameter schemas, auth requirements, and deprecation notices.
+- POST https://api.image-skill.com/v1/create creates or dry-runs one bounded free-preview image when Authorization: Bearer TOKEN has quota and the relevant preview grant. Request JSON: prompt, optional model, optional intent, optional aspect_ratio, optional output constraints, optional model_parameters, optional dry_run, optional max_estimated_usd_per_image, optional max_usd, optional accept_unknown_cost. Success responses include cost.credit_pricing; agents should read credits_required instead of assuming one credit per operation.
+- POST https://api.image-skill.com/v1/upload accepts client-normalized base64 raster image bytes when Authorization: Bearer TOKEN has asset.upload. Request JSON: source_kind, filename, remote_origin, mime_type, content_length, sha256, bytes_base64. Do not send local paths, full remote URLs, prompts, tokens, or provider credentials.
+- POST https://api.image-skill.com/v1/edit edits an Image Skill-owned input asset when Authorization: Bearer TOKEN has quota and the relevant preview grant. Request JSON: input_asset_id, prompt, optional model, optional intent, optional aspect_ratio, optional output constraints, optional model_parameters, optional max_estimated_usd_per_image, optional max_usd, optional accept_unknown_cost. The public CLI uploads local paths or external URLs first; do not send source bytes or external URLs to /v1/edit.
+- GET https://api.image-skill.com/v1/assets/ASSET_ID returns hosted asset metadata for Authorization: Bearer TOKEN when the asset belongs to the actor organization.
+- GET https://api.image-skill.com/v1/jobs/JOB_ID returns hosted job metadata for Authorization: Bearer TOKEN when the job belongs to the actor organization.
+- GET https://api.image-skill.com/v1/activity returns hosted activity ledger events for Authorization: Bearer TOKEN. Optional query: limit, subject. Activity is for ledger context, not job recovery.
+- GET https://api.image-skill.com/v1/activity/REFERENCE returns hosted activity events related to one event, job, asset, usage, feedback, or trace reference.
+- Public activity event types are: job.completed, asset.created, asset.uploaded, usage.credit_consumed, feedback.created, payment.checkout_session.created, credits.payment_backed_granted. Treat any other activity type as a contract bug and leave feedback with event ID plus trace ID.
+- POST https://api.image-skill.com/v1/cli runs public CLI-compatible commands over JSON argv.
+- GET https://api.image-skill.com/healthz checks API readiness.
+
+Expected JSON envelope:
+{
+  "ok": true,
+  "command": "string",
+  "trace_id": "trace_...",
+  "actor": {
+    "actor_type": "agent",
+    "actor_id": "agt_...",
+    "organization_id": "org_...",
+    "claim_state": "unclaimed"
+  },
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+
+Expected error envelope:
+{
+  "ok": false,
+  "command": "string",
+  "trace_id": "trace_...",
+  "actor": null,
+  "data": null,
+  "warnings": [],
+  "error": {
+    "code": "string",
+    "message": "redacted human-readable message",
+    "retryable": false
+  }
+}
+
+Standard exit codes:
+- 0 success
+- 1 generic failure
+- 2 invalid arguments
+- 3 auth required or invalid token
+- 4 capability denied
+- 5 quota exceeded
+- 6 content policy denied
+- 7 provider failure
+- 8 timeout
+- 9 filesystem failure
+
+Unclaimed agents may:
+- inspect docs, capabilities, models, identity, and quota
+- request human claim
+- create product feedback
+- inspect fake/test or Stripe Checkout credit quotes, create Stripe-hosted checkout sessions for stripe_checkout quotes, and, when explicitly asked to exercise the preview credit ledger, confirm fake/test quotes
+- run only bounded free-preview workflows when quota, artifact storage, budget guard, and policy allow
+
+Unclaimed agents may not:
+- run high-cost or bulk jobs
+- publish publicly
+- create arbitrary webhooks
+- import provider keys
+- change billing plans, saved payment methods, team settings, or organization settings
+- access assets outside their organization
+- disable telemetry or audit logging
+- send card data, wallet secrets, provider receipts, Stripe secrets, MPP tokens, SPTs, or any payment credential to Image Skill; Stripe payment details must be entered only on Stripe-hosted checkout pages
+
+Credits:
+One Image Skill credit is $0.01. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --json for exact bounded custom top-ups when the required budget is already known. The default payment_method is fake. Use image-skill credits buy --provider stripe --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_url and does not grant credits. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Use image-skill credits fake-purchase --json only to exercise the quote, receipt, credit-ledger, and activity-audit contract before live settlement rails are enabled. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Credits buy and fake-purchase require explicit --idempotency-key. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
+
+Telemetry:
+- command or endpoint name
+- CLI, skill, and API version
+- actor class
+- capability id and, when explicitly authorized, model/provider provenance
+- status
+- duration
+- cost estimate
+- output count
+- error class
+- retry state
+- job ID or trace ID
+
+Telemetry must not include raw prompts, source images, generated images, provider keys, tokens, or sensitive payloads by default.
+
+Activity:
+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.
+Current activity event registry: job.completed, asset.created, asset.uploaded,
+usage.credit_consumed, feedback.created, payment.checkout_session.created,
+credits.payment_backed_granted.
+
+Feedback:
+Use image-skill feedback create --json when the workflow fails, succeeds with friction, reveals confusing behavior, or suggests a missing feature. Feedback should include command, expected behavior, actual behavior, proof needed, surface, evidence, severity, confidence, and next state.
+
+Artifact retry rule:
+If create returns ARTIFACT_STORAGE_WRITE_FAILED, do not retry the whole create blindly. The provider may have already generated an image. Leave feedback or wait for storage/job repair.
+
+Asset fetch rule:
+Use image-skill assets get on Image Skill-owned URLs or asset ids. Do not use Image Skill as a generic external URL downloader.
+
+Reference:
+- https://image-skill.com
+- https://image-skill.com/skill.md
+- https://image-skill.com/cli.md
+- https://image-skill.com/llms.txt

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "image-skill",
+  "version": "0.1.0",
+  "description": "Thin hosted CLI for Image Skill, a creative runtime for agents.",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "image-skill": "bin/image-skill.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "skill.md",
+    "llms.txt",
+    "cli.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/skill.md

@@ -0,0 +1,318 @@
+---
+name: image-skill
+description: Use Image Skill when an agent needs to create, edit, inspect, iterate on, or manage generated images through the hosted image-skill service and thin CLI/client. Also use it when an agent needs to bootstrap restricted access, check quota, request human claim, or leave product feedback.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  {
+    "status": "preview-contract",
+    "cli": "image-skill",
+    "canonical_skill_url": "https://image-skill.com/skill.md",
+    "canonical_api_url": "https://api.image-skill.com",
+  }
+---
+
+# Image Skill
+
+Status: preview hosted-product contract.
+
+Image Skill is a CLI-first hosted creative runtime for agents. Use it to create, edit, inspect, iterate on, and reuse generated images.
+
+Public agents should depend on the hosted contract, a thin CLI/client, stable JSON outputs, trace IDs, job IDs, artifact references, quota/cost state, and feedback commands.
+
+Core rule: Image Skill should preserve model capability, not flatten it away.
+Use capability introspection and model parameter schemas before assuming what a
+model can do. Normalized controls are for common paths; model parameters are
+how rare or provider-native capabilities remain available without turning the
+whole CLI into a lowest-common-denominator interface.
+
+## First Run
+
+Install the agent-facing skill from the public mirror repo when the runtime
+supports skills.sh-compatible installation:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+Install the executable CLI from npm:
+
+```bash
+npm install -g image-skill
+```
+
+Check service and client health:
+
+```bash
+image-skill doctor --json
+```
+
+Bootstrap restricted agent access:
+
+```bash
+image-skill signup --agent \
+  --human-email HUMAN_EMAIL \
+  --agent-name AGENT_NAME \
+  --runtime RUNTIME_NAME \
+  --save \
+  --json
+```
+
+`--save` stores the returned hosted token in the public CLI config with 0600
+permissions and redacts it from stdout. Use `--show-token` only when the agent
+runtime has a separate secret store and needs the raw token once.
+
+If the runtime supports stdin secret handoff, prefer `--token-stdin` for
+`whoami`, `usage quota`, `quota`, `create`, and `feedback create` instead of
+placing the token in command args.
+
+Inspect identity and quota:
+
+```bash
+image-skill whoami --json
+image-skill usage quota --json
+```
+
+The preview hosted signup path currently uses a human sponsor email. Future
+payment-backed and agent-contact-backed signup paths are planned so capable
+agents can become bounded paying users without making human claim the only
+path to meaningful usage.
+
+Credit quote and buy flow:
+
+```bash
+image-skill credits packs list --json
+image-skill credits quote \
+  --pack starter-500 \
+  --payment-method stripe_checkout \
+  --idempotency-key stripe-pack-quote-run-001 \
+  --json
+image-skill credits quote --credits 137 --json
+image-skill credits buy \
+  --provider stripe \
+  --quote-id QUOTE_ID \
+  --idempotency-key stripe-buy-run-001 \
+  --json
+image-skill credits fake-purchase \
+  --quote-id QUOTE_ID \
+  --idempotency-key purchase-run-001 \
+  --json
+```
+
+This is the agent-facing precursor to future MPP, Stripe, wallet, or
+delegated-card adapters. Packs are the default Stripe Checkout UX; exact
+`--credits` quotes remain available when an agent already knows the required
+budget. `credits buy --provider stripe` returns a
+Stripe-hosted `checkout_url` for a `stripe_checkout` quote and does not grant
+credits until verified webhook fulfillment succeeds. `credits fake-purchase`
+returns `live_money:false`, moves no live money, accepts no payment credential,
+and exists so agents can exercise the quote, receipt, credit-ledger, and
+activity-audit contract safely.
+One Image Skill credit is `$0.01`. Creative operations debit model-priced
+credits, not a flat one-credit unit. Use `models show MODEL_ID --json` and the
+operation response `cost.credit_pricing` to see `credits_required`,
+`estimated_provider_cost_usd`, and pricing confidence.
+
+## Create An Image
+
+Inspect models first:
+
+```bash
+image-skill models --json
+image-skill models list --json
+image-skill models show openai.gpt-image-2 --json
+```
+
+`models show` is the first detailed discovery surface for agents. It exposes
+operations, media inputs/outputs, model-parameter schemas, fixed and wired
+controls, cost/latency class, safety behavior, and migration hints. Use
+`capabilities` when you need the schema language directly.
+
+Create with hosted artifact URLs and JSON:
+
+```bash
+image-skill create \
+  --prompt "A product mockup of a compact field camera on a stainless workbench" \
+  --intent explore \
+  --aspect-ratio 1:1 \
+  --max-estimated-usd-per-image 0.05 \
+  --json
+```
+
+For model-specific controls that are advertised by models/capabilities, use a
+validated JSON parameter payload instead of inventing coarse global categories:
+
+```bash
+image-skill create \
+  --prompt-file ./prompt.md \
+  --intent finalize \
+  --model MODEL_ID \
+  --model-parameters-json '{"seed":1234}' \
+  --max-usd 0.25 \
+  --json
+```
+
+In the current preview, Fal create/edit expose executable `seed`, while OpenAI
+GPT Image 2 exposes documented provider-native controls such as size, output
+format, compression, background, moderation, and its provider-native quality
+parameter through validated `model_parameters`. These are model-specific
+controls, not universal Image Skill tiers.
+
+Hosted free-preview API:
+
+```bash
+curl -sS https://api.image-skill.com/v1/create \
+  -H "authorization: Bearer $IMAGE_SKILL_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"prompt":"A product mockup of a compact field camera on a stainless workbench","intent":"explore","aspect_ratio":"1:1","max_estimated_usd_per_image":0.05,"model_parameters":{"seed":1234}}'
+```
+
+Expected behavior:
+
+- returns `job_id`, `trace_id`, `asset_ids`, artifact references, cost estimate, and safety status;
+- returns Image Skill-owned artifact references under `assets[].url`;
+- emits service telemetry;
+- refuses when quota, claim state, scopes, content policy, budget guard, provider availability, or safety rules do not allow the job.
+
+## Fetch Generated Assets
+
+Upload an existing image into an Image Skill-owned input asset:
+
+```bash
+image-skill upload PATH_OR_URL --json
+```
+
+Use upload before edit workflows. The CLI normalizes local paths and remote
+URLs client-side; public responses include `asset_id`, `job_id`, hosted URL,
+MIME type, byte length, and SHA-256 hash, but never local paths, full remote
+URLs, raw bytes, base64 payloads, buckets, or object keys.
+
+Edit an owned input asset, local path, or remote URL:
+
+```bash
+image-skill edit \
+  --input ASSET_ID_OR_PATH_OR_URL \
+  --prompt "Remove the background and keep natural object shadows" \
+  --accept-unknown-cost \
+  --json
+```
+
+For local paths and external URLs, the public CLI uploads the input first and
+then edits the resulting Image Skill-owned asset id. Preview hosted edit uses
+Fal Nano Banana 2 Edit and consumes model-priced restricted free-preview
+credits after provider success.
+
+Inspect an Image Skill-owned asset:
+
+```bash
+image-skill assets show ASSET_ID_OR_URL --json
+```
+
+Download it without repeating provider work:
+
+```bash
+image-skill assets get ASSET_ID_OR_URL --output ./result.png --json
+```
+
+`assets get` refuses to overwrite existing files unless `--overwrite` is
+explicit. Use only Image Skill-owned asset URLs or asset ids returned by
+Image Skill.
+
+## Inspect Generated Jobs
+
+Inspect a hosted job:
+
+```bash
+image-skill jobs show JOB_ID --json
+```
+
+Wait for a hosted job to complete:
+
+```bash
+image-skill jobs wait JOB_ID --json
+```
+
+Use `jobs show` or `jobs wait` instead of telemetry or history files when you
+need status, cost, safety, public capability id, timestamps, and reusable assets
+for a hosted create.
+
+## Inspect Activity
+
+List recent ledger events:
+
+```bash
+image-skill activity list --limit 20 --json
+```
+
+Show one event or subject:
+
+```bash
+image-skill activity show EVENT_OR_JOB_OR_ASSET_OR_FEEDBACK --json
+```
+
+Use `activity` when you need an audit trail: recent jobs, assets, usage events,
+feedback acceptance, trace IDs, and status changes that can be cited in product
+feedback. Do not use `activity` as a wait or recovery command. Use `jobs show`
+or `jobs wait` for operational job state, final assets, and retry judgment.
+
+## Feedback
+
+If a workflow fails, is confusing, succeeds with friction, or suggests a missing feature, leave product feedback:
+
+```bash
+image-skill feedback create \
+  --type user_feedback \
+  --title "Short concrete title" \
+  --body "What happened, what was expected, and why it matters" \
+  --command "Command or workflow observed" \
+  --expected "Expected result" \
+  --actual "Actual result" \
+  --proof-needed "What would prove this is handled" \
+  --surface cli,docs \
+  --evidence trace:TRACE_ID \
+  --severity medium \
+  --confidence high \
+  --next-state watch \
+  --json
+```
+
+Good feedback includes the command, trace ID, expected result, actual result, and whether the issue is CLI affordance, model output, auth/quota, docs, provider reliability, or product judgment.
+If the agent cannot fill every structured field, still submit `--title` and
+`--body`; narrative feedback is accepted, and quality warnings remain available
+when the signal lacks enough triage evidence.
+
+When a JSON command fails, inspect `error.recovery` before retrying. Recovery
+may include `required_flag`, `suggested_command`, `docs_url`, or
+`retry_after_seconds`; use these fields instead of scraping prose messages.
+
+Public feedback is hosted by default. With `IMAGE_SKILL_TOKEN` set, the CLI
+submits to `https://api.image-skill.com/v1/feedback` and the service fails
+closed if durable hosted feedback storage is unavailable.
+
+## Safety And Cost
+
+- Check `usage quota --json` before costly workflows. `quota --json` remains a
+  compatibility alias.
+- Use `credits packs list --json` to inspect recommended live-money packs.
+- Use `credits quote --pack PACK_ID --payment-method stripe_checkout --json`
+  for the default Stripe Checkout path.
+- Use `credits quote --credits CREDITS --json` for exact bounded custom
+  top-ups when the required budget is already known.
+- Use `credits buy --provider stripe --json` only to create a Stripe-hosted
+  checkout action. Session creation itself does not grant credits.
+- Use `credits fake-purchase --json` only for preview credit-ledger proof; it
+  is not live settlement and must not receive payment credentials.
+- Treat credits as prepaid cents of Image Skill value. Operation debits are
+  model-aware and appear in `cost.credit_pricing`.
+- Use dry-run modes and explicit budget caps for exploration.
+- Do not mistake quota limits or free-preview policy for creative quality
+  labels. Ask capabilities what a capability supports.
+- Do not bypass claim state, scopes, policy checks, or telemetry.
+- Do not create deceptive, harassing, infringing, or unsafe media.
+- Escalate to the human when a workflow needs spend, identity, legal judgment, or external publishing.
+
+## Reference
+
+- Full machine-readable contract: `https://image-skill.com/llms.txt`
+- CLI command contract: `https://image-skill.com/cli.md`
+- Product homepage: `https://image-skill.com`