image-skill 0.1.37 → 0.1.39

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.39 - 2026-06-10
+
+- Feature (growth): **`signup --discovery-source SLUG`** (or the
+  `IMAGE_SKILL_DISCOVERY_SOURCE` environment variable; the flag wins)
+  optionally records the channel where the agent discovered Image Skill — a
+  short slug such as `clawhub`, `skills-sh`, or `npm` (lowercase
+  letters/digits plus `.`/`_`/`-`, max 64 chars). Self-reported and
+  first-touch: the first signup that names a channel wins, and a later
+  re-signup never relabels it. Never required — omit it rather than guessing.
+
+## 0.1.38 - 2026-06-09
+
+- Feature (auth): **signup is anonymous by default** — `signup --agent
+--agent-name NAME --runtime RUNTIME` succeeds with no contact inbox.
+  `--agent-contact` stays optional with unchanged semantics when provided
+  (`--human-email` remains a compatibility alias). The guide's auth handoff no
+  longer asks for an inbox placeholder. Anonymous signups mint a fresh agent
+  identity on every call; reuse the saved config instead of re-running signup.
+- Feature (auth): new **`claim request --contact INBOX --json`** attaches an
+  email-shaped durable contact inbox to the authenticated agent after signup —
+  the on-demand identity upgrade for billing, abuse, and recovery notices
+  (`POST /v1/agent-claims`). Re-sending the same contact is idempotent
+  (`data.state` is `unchanged`). Attaching a contact is not inbox-ownership
+  verification: `data.claim_state` stays `unclaimed` and whoami/quota report
+  `claim_request_state: "requested"`.
+- Fix (recovery): the in-flight spend breadcrumb now survives **retryable**
+  failures (network reset, proxy 5xx — the maybe-already-debited cases it
+  exists for) and is removed only on success or a non-retryable rejection. A
+  network-level failure on a live create/edit now echoes the request's
+  `idempotency_key` in `error.recovery` so the advertised retry dedupes to one
+  charge. The breadcrumb filename is sanitized so an unusual
+  `--idempotency-key` value can never escape the `in-flight/` directory.
+
 ## 0.1.37 - 2026-06-09
 
 - Fix (recovery): a live `create`/`edit` now leaves a recovery handle _before_

package/README.md

@@ -128,9 +128,14 @@ Fresh sandboxes should prefer:
 
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
-npm_config_update_notifier=false npx -y image-skill@latest signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name creative-agent --runtime openclaw --json
+npm_config_update_notifier=false npx -y image-skill@latest signup --agent --agent-name creative-agent --runtime openclaw --json
 ```
 
+Signup is anonymous by default. `--agent-contact` stays optional for attaching
+an email-shaped durable contact inbox at signup; otherwise attach one later
+with `image-skill claim request --contact INBOX --json` when funding or
+durability makes it worth having.
+
 If npm prefix/cache paths are read-only, keep the fresh `npx -y` path and set
 the package-manager cache, prefix, and PATH together before rerunning the guide:
 

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.37";
+const VERSION = "0.1.39";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -29,9 +29,11 @@ const DEFAULT_CONFIG_PATH = join(
 );
 const LOCAL_WRITABLE_CONFIG_PATH = "$PWD/.image-skill/config.json";
 const SIGNUP_SUGGESTED_COMMAND =
-  "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json";
+  "image-skill signup --agent --agent-name NAME --runtime RUNTIME --json";
 const SIGNUP_CONTACT_GUIDANCE =
-  "Preview signup currently requires an email-shaped durable contact inbox, not an individual human email. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. --human-email remains a compatibility alias.";
+  "Signup is anonymous by default: no contact inbox is required to get a restricted token. --agent-contact stays optional for attaching an email-shaped durable contact inbox at signup; otherwise attach one later with `image-skill claim request --contact INBOX --json` when funding or durability makes it worth having. Never invent an inbox or borrow an unrelated human email just to fill the flag. --human-email remains a compatibility alias.";
+const CLAIM_REQUEST_SUGGESTED_COMMAND =
+  "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json";
 const HOSTED_SIGNUP_TOKEN_RETURNED_WARNING =
   "hosted restricted token is returned once; store it in the agent runtime secret store and never paste it into prompts, logs, issues, or product feedback";
 const PUBLIC_NPX_COMMAND_PREFIX =
@@ -70,7 +72,7 @@ const GUIDE_NEXT_COMMAND_PLACEHOLDERS = [
     placeholder: "AGENT_OR_OPERATOR_INBOX",
     flag: "--agent-contact",
     value_description:
-      "Email-shaped durable contact inbox for the restricted agent identity; use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox.",
+      "Optional email-shaped durable contact inbox; signup is anonymous by default and `claim request --contact` attaches one later. Use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox.",
     effect_description: "email-shaped durable contact inbox",
     example: "agent-inbox@example.com",
   },
@@ -166,6 +168,8 @@ async function main(rawArgv) {
         return await trust(rest);
       case "signup":
         return await signup(rest);
+      case "claim":
+        return await claim(rest);
       case "auth":
         return await auth(rest);
       case "whoami":
@@ -278,12 +282,13 @@ function commandHelpByKey(key) {
     "": {
       command: "help",
       usage:
-        "image-skill <doctor|trust|signup|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "image-skill <doctor|trust|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
       docs_url: "https://image-skill.com/cli.md",
       commands: [
         "doctor",
         "trust",
-        "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
+        "signup --agent --agent-name NAME --runtime RUNTIME",
+        "claim request --contact INBOX",
         "whoami",
         "usage quota",
         "quota",
@@ -334,15 +339,30 @@ function commandHelpByKey(key) {
     signup: {
       command: "image-skill signup help",
       usage:
-        "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json",
+        "image-skill signup --agent --agent-name NAME --runtime RUNTIME --json",
       docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
-      required_flags: [
-        "--agent",
+      required_flags: ["--agent", "--agent-name", "--runtime"],
+      optional_flags: [
         "--agent-contact",
-        "--agent-name",
-        "--runtime",
+        "--show-token",
+        "--no-save",
+        "--token-stdin",
       ],
-      optional_flags: ["--show-token", "--no-save", "--token-stdin"],
+    },
+    claim: {
+      command: "image-skill claim help",
+      usage:
+        "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-claim-request",
+      subcommands: ["request"],
+    },
+    "claim request": {
+      command: "image-skill claim request help",
+      usage:
+        "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-claim-request",
+      required_flags: ["--contact"],
+      optional_flags: ["--token-stdin"],
     },
     auth: {
       command: "image-skill auth help",
@@ -739,21 +759,26 @@ async function signup(argv) {
       contact.message,
       false,
       {
-        required_flags: ["--agent-contact", "--agent-name", "--runtime"],
+        required_flags: ["--agent-name", "--runtime"],
+        optional_flags: ["--agent-contact", "--discovery-source"],
         suggested_command: SIGNUP_SUGGESTED_COMMAND,
         docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
       },
     );
   }
-  if (contact.value === null || agentName === null || runtime === null) {
+  // Anonymous signup is the default (decision 0030): only name + runtime are
+  // required. A contact stays optional here and attachable later via
+  // `claim request --contact INBOX`.
+  if (agentName === null || runtime === null) {
     return failure(
       "image-skill signup",
       2,
       "INVALID_ARGUMENTS",
-      `signup requires --agent-contact, --agent-name, and --runtime. ${SIGNUP_CONTACT_GUIDANCE}`,
+      `signup requires --agent-name and --runtime. ${SIGNUP_CONTACT_GUIDANCE}`,
       false,
       {
-        required_flags: ["--agent-contact", "--agent-name", "--runtime"],
+        required_flags: ["--agent-name", "--runtime"],
+        optional_flags: ["--agent-contact", "--discovery-source"],
         accepted_aliases: {
           "--human-email": "--agent-contact",
         },
@@ -778,16 +803,26 @@ async function signup(argv) {
       return configReady.result;
     }
   }
+  // Discovery-source attribution (#1814): self-reported channel slug from
+  // --discovery-source or IMAGE_SKILL_DISCOVERY_SOURCE (flag wins). Omitted
+  // entirely when absent — never guessed, never required.
+  const discoverySource =
+    flagString(args, "discovery-source")?.trim() ||
+    process.env.IMAGE_SKILL_DISCOVERY_SOURCE?.trim() ||
+    null;
   const result = await apiRequest({
     command: "image-skill signup",
     method: "POST",
     apiBaseUrl: apiBase(args),
     path: "/v1/agent-signups",
     body: {
-      agent_contact: contact.value,
+      ...(contact.value === null ? {} : { agent_contact: contact.value }),
       agent_name: agentName,
       runtime,
       return_token: shouldSave || showToken,
+      ...(discoverySource === null || discoverySource === ""
+        ? {}
+        : { discovery_source: discoverySource }),
     },
   });
   result.envelope.command = "image-skill signup";
@@ -870,6 +905,55 @@ async function signup(argv) {
   return result;
 }
 
+// Claim request (decision 0030): attach an email-shaped durable contact to the
+// authenticated agent after an (often anonymous) signup — the on-demand
+// identity upgrade for funding notices and durability. claim_state stays
+// unclaimed; attaching a contact is not inbox-ownership verification.
+async function claim(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "request") {
+    return failure(
+      "image-skill claim",
+      2,
+      "INVALID_ARGUMENTS",
+      "claim requires the request subcommand",
+      false,
+      {
+        suggested_command: CLAIM_REQUEST_SUGGESTED_COMMAND,
+        docs_url: "https://image-skill.com/cli.md#image-skill-claim-request",
+      },
+    );
+  }
+  const args = parseArgs(rest);
+  const contact = flagString(args, "contact");
+  if (contact === null || contact.trim().length === 0) {
+    return failure(
+      "image-skill claim request",
+      2,
+      "INVALID_ARGUMENTS",
+      "claim request requires --contact, an email-shaped durable contact inbox (agent-owned when available, otherwise an operator, team, or sponsor inbox)",
+      false,
+      {
+        required_flags: ["--contact"],
+        suggested_command: CLAIM_REQUEST_SUGGESTED_COMMAND,
+        docs_url: "https://image-skill.com/cli.md#image-skill-claim-request",
+      },
+    );
+  }
+  const token = await resolveToken(args);
+  if (!token.ok) {
+    return token.result;
+  }
+  return apiRequest({
+    command: "image-skill claim request",
+    method: "POST",
+    apiBaseUrl: apiBase(args),
+    path: "/v1/agent-claims",
+    token: token.token,
+    body: { contact: contact.trim().toLowerCase() },
+  });
+}
+
 function rewriteSignupContactFailure(result) {
   const error = result.envelope.error;
   if (
@@ -882,7 +966,7 @@ function rewriteSignupContactFailure(result) {
         "human_email is a legacy alias for agent_contact and must be an email-shaped durable contact inbox")
   ) {
     error.message =
-      "preview signup currently requires --agent-contact to be an email-shaped durable contact inbox; it does not need to belong to an individual human";
+      "--agent-contact, when provided, must be an email-shaped durable contact inbox; signup itself is anonymous by default, so omit the flag entirely if no durable inbox exists";
     error.recovery = {
       ...(error.recovery ?? {}),
       suggested_command: SIGNUP_SUGGESTED_COMMAND,
@@ -2912,8 +2996,11 @@ function renderGuideCommand(
 }
 
 function renderGuideSignupCommand(input) {
+  // Anonymous signup (decision 0030): no contact placeholder in the handoff —
+  // the agent still substitutes its own name/runtime, but no longer has to
+  // find (or invent) an inbox before it can authenticate.
   const signupCommand = [
-    "signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name AGENT_NAME --runtime RUNTIME_NAME",
+    "signup --agent --agent-name AGENT_NAME --runtime RUNTIME_NAME",
     ...(input.apiBaseUrl === null
       ? []
       : ["--api-base-url", shellQuote(input.apiBaseUrl)]),
@@ -3182,7 +3269,7 @@ async function create(argv) {
       accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
     },
   });
-  await clearInFlightSpend(inFlight);
+  await clearInFlightSpendForResult(inFlight, result);
   return result;
 }
 
@@ -3307,7 +3394,7 @@ async function edit(argv) {
       accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
     },
   });
-  await clearInFlightSpend(inFlight);
+  await clearInFlightSpendForResult(inFlight, result);
   return result;
 }
 
@@ -4415,6 +4502,16 @@ function recoverCommandFor(operation, idempotencyKey) {
   return `image-skill ${operation} --idempotency-key ${idempotencyKey} <same arguments> --json`;
 }
 
+// The breadcrumb filename derives from the (possibly agent-supplied)
+// idempotency key; keep it to a safe charset so a hostile or accidental key
+// like "../config" can never escape the in-flight directory or collide with
+// the CLI's own config file.
+function inFlightSpendFileName(idempotencyKey) {
+  const safe = String(idempotencyKey).replace(/[^A-Za-z0-9._-]/g, "_");
+  const trimmed = safe.replace(/^\.+/, "").slice(0, 120);
+  return `${trimmed.length === 0 ? "key" : trimmed}.json`;
+}
+
 async function recordInFlightSpend(input) {
   const { command, operation, idempotencyKey, argv } = input;
   const recoverCommand = recoverCommandFor(operation, idempotencyKey);
@@ -4425,7 +4522,7 @@ async function recordInFlightSpend(input) {
   // or a later session can find an orphaned spend even when the transcript is
   // gone).
   const dir = inFlightSpendDir();
-  const path = join(dir, `${idempotencyKey}.json`);
+  const path = join(dir, inFlightSpendFileName(idempotencyKey));
   let recordedPath = null;
   try {
     await mkdir(dir, { recursive: true });
@@ -4481,6 +4578,26 @@ async function clearInFlightSpend(path) {
   }
 }
 
+// Clear the breadcrumb only when the spend's fate is KNOWN: a success, or a
+// non-retryable failure (4xx — the server rejected it without charging). A
+// retryable failure (network reset, proxy 5xx) is exactly the
+// maybe-already-debited case the breadcrumb exists for, so it must survive
+// for a later session or operator to find.
+async function clearInFlightSpendForResult(path, result) {
+  if (path === null || path === undefined) {
+    return;
+  }
+  const envelope = result?.envelope;
+  const retryableFailure =
+    envelope !== undefined &&
+    envelope.ok !== true &&
+    envelope.error?.retryable === true;
+  if (retryableFailure) {
+    return;
+  }
+  await clearInFlightSpend(path);
+}
+
 async function apiRequest(input) {
   const url = new URL(input.path, ensureTrailingSlash(input.apiBaseUrl));
   try {
@@ -4512,17 +4629,32 @@ async function apiRequest(input) {
       envelope,
     };
   } catch (error) {
+    // Money integrity (#1789 review): a network failure can land AFTER the
+    // request was sent — a live create/edit may already have reserved a
+    // credit. Echo the request's idempotency key in-band so the recovery
+    // re-run dedupes to one charge instead of pointing at doctor alone.
+    const recovery =
+      isCreateOrEditCommand(input.command) &&
+      input.body !== undefined &&
+      typeof input.body.idempotency_key === "string"
+        ? {
+            suggested_command: `${input.command} --idempotency-key ${input.body.idempotency_key} --json`,
+            idempotency_key: input.body.idempotency_key,
+            docs_url: "https://image-skill.com/cli.md",
+            retry_after_seconds: 30,
+          }
+        : {
+            suggested_command: "image-skill doctor --json",
+            docs_url: "https://image-skill.com/cli.md",
+            retry_after_seconds: 30,
+          };
     return failure(
       input.command,
       7,
       "HOSTED_API_REQUEST_FAILED",
       error instanceof Error ? error.message : "hosted API request failed",
       true,
-      {
-        suggested_command: "image-skill doctor --json",
-        docs_url: "https://image-skill.com/cli.md",
-        retry_after_seconds: 30,
-      },
+      recovery,
     );
   }
 }

package/cli.md

@@ -82,11 +82,11 @@ than omitting the field.
 
 ### `image-skill signup --agent`
 
-Bootstraps restricted agent access.
+Bootstraps restricted agent access. Signup is anonymous by default: no contact
+inbox is required to get a restricted token.
 
 ```bash
 image-skill signup --agent \
-  --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
   --json
@@ -104,16 +104,47 @@ The raw token is returned only when `--show-token` is set, and only once. Use
 does not want local config. Do not paste tokens into prompts, logs, issue text,
 or feedback.
 
-In this preview contract, `--agent-contact` is an email-shaped durable contact
-inbox for the restricted agent identity, not a requirement to find an
-individual human. Use an agent-owned inbox when available; otherwise use an
-operator, team, or sponsor inbox that can receive future claim, billing, or
-abuse notices. Do not block waiting for a person, invent a person, or use a
-throwaway inbox.
+`--agent-contact` is an email-shaped durable contact inbox and it is optional
+at signup: provide it when a durable inbox already exists, or attach one later
+with `image-skill claim request --contact INBOX --json` when funding or
+durability makes it worth having. Use an agent-owned inbox when available;
+otherwise use an operator, team, or sponsor inbox that can receive future
+claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated
+human email just to fill the flag — omit it instead.
 `example.invalid` addresses are only appropriate inside documented harness or
 proof runs. `--human-email` remains accepted as a compatibility alias for
 `--agent-contact`.
 
+Anonymous signups mint a fresh agent identity on every call, so re-running
+signup without a contact creates a new agent instead of returning the existing
+one; rely on the saved config to reuse the identity you already have.
+
+`--discovery-source SLUG` (or the `IMAGE_SKILL_DISCOVERY_SOURCE` environment
+variable; the flag wins) optionally records where you discovered Image Skill —
+a short channel slug such as `clawhub`, `skills-sh`, or `npm` (lowercase
+letters/digits plus `.`/`_`/`-`, max 64 chars). It is self-reported,
+first-touch (a later re-signup never relabels it), and never required: omit it
+when you do not know the channel rather than guessing.
+
+### `image-skill claim request`
+
+Attaches an email-shaped durable contact inbox to the authenticated agent —
+the on-demand identity upgrade after an anonymous signup. Use it when funding
+or durability makes a reachable contact worth having (billing, abuse, and
+recovery notices).
+
+```bash
+image-skill claim request \
+  --contact agent-inbox@example.com \
+  --json
+```
+
+Re-running with the same contact is idempotent (`data.state` is `unchanged`);
+a different contact replaces the previous one (`data.state` is `attached`).
+Attaching a contact is not inbox-ownership verification: `data.claim_state`
+stays `unclaimed` and `data.claim_request_state` reports `requested`. The
+response echoes only a redacted form of the contact.
+
 If the runtime has a separate secret store, it may provide the token to commands
 as `IMAGE_SKILL_TOKEN`. Keep that value outside prompts, logs, issue text, and
 feedback. Saved config, `IMAGE_SKILL_TOKEN`, and `--token-stdin` are all
@@ -276,7 +307,6 @@ runtime needs a writable compatibility config path, set
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
 npm_config_update_notifier=false npx -y image-skill@latest signup --agent \
-  --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
   --json

package/commands.json

@@ -27,6 +27,14 @@
       "mutation": true,
       "spend": false
     },
+    {
+      "id": "claim",
+      "docs_anchor": "image-skill-claim-request",
+      "surface": "hosted_cli",
+      "mutation": true,
+      "spend": false,
+      "subcommands": ["request"]
+    },
     {
       "id": "whoami",
       "docs_anchor": "image-skill-whoami",
@@ -140,12 +148,13 @@
       "key": "",
       "help": {
         "command": "help",
-        "usage": "image-skill <doctor|trust|signup|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "usage": "image-skill <doctor|trust|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
         "docs_url": "https://image-skill.com/cli.md",
         "commands": [
           "doctor",
           "trust",
-          "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
+          "signup --agent --agent-name NAME --runtime RUNTIME",
+          "claim request --contact INBOX",
           "whoami",
           "usage quota",
           "quota",
@@ -202,15 +211,34 @@
       "key": "signup",
       "help": {
         "command": "image-skill signup help",
-        "usage": "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json",
+        "usage": "image-skill signup --agent --agent-name NAME --runtime RUNTIME --json",
         "docs_url": "https://image-skill.com/cli.md#image-skill-signup-agent",
-        "required_flags": [
-          "--agent",
+        "required_flags": ["--agent", "--agent-name", "--runtime"],
+        "optional_flags": [
           "--agent-contact",
-          "--agent-name",
-          "--runtime"
-        ],
-        "optional_flags": ["--show-token", "--no-save", "--token-stdin"]
+          "--show-token",
+          "--no-save",
+          "--token-stdin"
+        ]
+      }
+    },
+    {
+      "key": "claim",
+      "help": {
+        "command": "image-skill claim help",
+        "usage": "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-claim-request",
+        "subcommands": ["request"]
+      }
+    },
+    {
+      "key": "claim request",
+      "help": {
+        "command": "image-skill claim request help",
+        "usage": "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-claim-request",
+        "required_flags": ["--contact"],
+        "optional_flags": ["--token-stdin"]
       }
     },
     {

package/llms.txt

@@ -61,7 +61,7 @@ First-run guide loop:
 1. Run image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint and the only required first command. It performs read-only hosted reachability, executable model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.guide_warning, data.next_command_effect, data.auth_ready, data.no_spend_evaluation, data.no_spend_next_command, data.no_spend_next_command_effect, data.self_fund_next_command, data.self_fund_handoff, data.auth_handoff, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
 2. Read data.guide_warning, then follow data.next_command when its next_command_safety is safe for the current spend policy. Do not run doctor, models list, signup, whoami, quota, dry-run, or payment commands as a setup checklist before the guide asks for them.
 3. If data.stage is prompt_required, rerun data.next_command with the real prompt.
-4. If data.stage is auth_required, data.auth_ready.ready is false and data.guide_warning.next_command_safety is hosted_signup_no_spend_setup. Run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the configured config path is blocked, data.next_command sets IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" and still runs a saved-config signup; do not switch to raw-token handoff unless recovery explicitly requires it. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. The signup command uses --agent-contact as an email-shaped durable contact inbox for the restricted agent identity, not as a requirement to find an individual human. Hosted signup returns the raw restricted token only when --show-token is set, and only once. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
+4. If data.stage is auth_required, data.auth_ready.ready is false and data.guide_warning.next_command_safety is hosted_signup_no_spend_setup. Run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the configured config path is blocked, data.next_command sets IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" and still runs a saved-config signup; do not switch to raw-token handoff unless recovery explicitly requires it. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. Signup is anonymous by default: no contact inbox is required to get a restricted token. The optional --agent-contact flag takes an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find an individual human; attach one later with image-skill claim request --contact INBOX --json when funding or durability makes it worth having. Hosted signup returns the raw restricted token only when --show-token is set, and only once. When providing a contact, use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated human email just to fill the flag — omit it instead. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. Anonymous signups mint a fresh agent identity on every call; reuse the saved config instead of re-running signup. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
 5. 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. 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.
 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, 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.
@@ -71,7 +71,8 @@ Manual escape hatches are not prerequisites. Use image-skill doctor, image-skill
 
 Core commands:
 - image-skill doctor --json
-- image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json
+- image-skill signup --agent --agent-name NAME --runtime RUNTIME --json
+- image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json
 - image-skill whoami --json
 - image-skill usage quota --json
 - image-skill quota --json (compatibility alias)
@@ -110,7 +111,8 @@ Core commands:
 - image-skill feedback create --type user_feedback --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. Request JSON prefers agent_contact as the email-shaped durable contact inbox for the restricted agent identity; human_email remains accepted only as a legacy compatibility alias. The contact is not a requirement that an autonomous agent stop until a specific human is present. Direct API callers receive the raw token once as data.token only when request.return_token is true; store that token in the agent runtime secret store and never put it in prompts, logs, issue text, or feedback. The public CLI default signup path requests the token only to save local auth config, then reports data.token:null and data.auth_handoff.status:saved_config_ready so no raw token copy step is required.
+- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. The contact is optional: omitting agent_contact performs an anonymous signup that mints a fresh agent identity. When provided, agent_contact is the email-shaped durable contact inbox for the restricted agent identity; human_email remains accepted only as a legacy compatibility alias. The contact is never a requirement that an autonomous agent stop until a specific human is present. Direct API callers receive the raw token once as data.token only when request.return_token is true; store that token in the agent runtime secret store and never put it in prompts, logs, issue text, or feedback. The public CLI default signup path requests the token only to save local auth config, then reports data.token:null and data.auth_handoff.status:saved_config_ready so no raw token copy step is required.
+- POST https://api.image-skill.com/v1/agent-claims attaches an email-shaped durable contact inbox to the authenticated agent after an (often anonymous) signup. Request JSON is {"contact": INBOX}. Re-sending the same contact is idempotent (data.state unchanged); a different contact replaces the previous one (data.state attached). Attaching a contact is not inbox-ownership verification: data.claim_state stays unclaimed and data.claim_request_state reports requested. The response echoes only a redacted contact.
 - 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/payment-methods returns the no-auth action-only payment rail catalog. It tells agents which currently usable rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, agent_initiated, agent_settleable, settlement_blocker, limits, endpoint paths, and recovery commands. Planned, watch-only, fake, and private harness rails are intentionally omitted.

package/package.json

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

@@ -118,18 +118,17 @@ edit        many assets  x     video     -> image-skill create --model fal.ltx-v
 
 ## First real run
 
-Hosted signup saves a restricted token to the public CLI config by default. The token is created by Image Skill and is not a user-supplied provider credential. The raw token is only returned once and only with `--show-token`; pass `--no-save --show-token` when the runtime has its own secret store.
+Hosted signup saves a restricted token to the public CLI config by default. The token is created by Image Skill and is not a user-supplied provider credential. The raw token is only returned once and only with `--show-token`; pass `--no-save --show-token` when the runtime has its own secret store. Signup is anonymous by default: no contact inbox is required.
 
 ```bash
 image-skill signup --agent \
-  --agent-contact AGENT_OR_OPERATOR_INBOX \
   --agent-name AGENT_NAME \
   --runtime RUNTIME_NAME
 image-skill whoami
 image-skill usage quota
 ```
 
-`--agent-contact` means an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find a specific human. Use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. `example.invalid` is only appropriate in documented harness or proof runs. `--human-email` remains an accepted compatibility alias.
+`--agent-contact` is optional at signup. It means an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find a specific human. Attach one later with `image-skill claim request --contact INBOX --json` when funding or durability makes it worth having (billing, abuse, and recovery notices). Use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox. Never invent an inbox or borrow an unrelated human email just to fill the flag — omit it instead. `example.invalid` is only appropriate in documented harness or proof runs. `--human-email` remains an accepted compatibility alias. Anonymous signups mint a fresh agent identity on every call; rely on the saved config to reuse the identity you already have.
 
 If the runtime supports stdin secret handoff, prefer `--token-stdin` over `--token` for `whoami`, `usage quota`, `create`, and `feedback create`. The guide returns `data.auth_handoff` with copy-safe env and stdin command templates so the token never lands in prompts, logs, or feedback.
 

package/skills/image-skill/SKILL.md

@@ -118,18 +118,17 @@ edit        many assets  x     video     -> image-skill create --model fal.ltx-v
 
 ## First real run
 
-Hosted signup saves a restricted token to the public CLI config by default. The token is created by Image Skill and is not a user-supplied provider credential. The raw token is only returned once and only with `--show-token`; pass `--no-save --show-token` when the runtime has its own secret store.
+Hosted signup saves a restricted token to the public CLI config by default. The token is created by Image Skill and is not a user-supplied provider credential. The raw token is only returned once and only with `--show-token`; pass `--no-save --show-token` when the runtime has its own secret store. Signup is anonymous by default: no contact inbox is required.
 
 ```bash
 image-skill signup --agent \
-  --agent-contact AGENT_OR_OPERATOR_INBOX \
   --agent-name AGENT_NAME \
   --runtime RUNTIME_NAME
 image-skill whoami
 image-skill usage quota
 ```
 
-`--agent-contact` means an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find a specific human. Use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. `example.invalid` is only appropriate in documented harness or proof runs. `--human-email` remains an accepted compatibility alias.
+`--agent-contact` is optional at signup. It means an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find a specific human. Attach one later with `image-skill claim request --contact INBOX --json` when funding or durability makes it worth having (billing, abuse, and recovery notices). Use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox. Never invent an inbox or borrow an unrelated human email just to fill the flag — omit it instead. `example.invalid` is only appropriate in documented harness or proof runs. `--human-email` remains an accepted compatibility alias. Anonymous signups mint a fresh agent identity on every call; rely on the saved config to reuse the identity you already have.
 
 If the runtime supports stdin secret handoff, prefer `--token-stdin` over `--token` for `whoami`, `usage quota`, `create`, and `feedback create`. The guide returns `data.auth_handoff` with copy-safe env and stdin command templates so the token never lands in prompts, logs, or feedback.
 

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

@@ -82,11 +82,11 @@ than omitting the field.
 
 ### `image-skill signup --agent`
 
-Bootstraps restricted agent access.
+Bootstraps restricted agent access. Signup is anonymous by default: no contact
+inbox is required to get a restricted token.
 
 ```bash
 image-skill signup --agent \
-  --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
   --json
@@ -104,16 +104,47 @@ The raw token is returned only when `--show-token` is set, and only once. Use
 does not want local config. Do not paste tokens into prompts, logs, issue text,
 or feedback.
 
-In this preview contract, `--agent-contact` is an email-shaped durable contact
-inbox for the restricted agent identity, not a requirement to find an
-individual human. Use an agent-owned inbox when available; otherwise use an
-operator, team, or sponsor inbox that can receive future claim, billing, or
-abuse notices. Do not block waiting for a person, invent a person, or use a
-throwaway inbox.
+`--agent-contact` is an email-shaped durable contact inbox and it is optional
+at signup: provide it when a durable inbox already exists, or attach one later
+with `image-skill claim request --contact INBOX --json` when funding or
+durability makes it worth having. Use an agent-owned inbox when available;
+otherwise use an operator, team, or sponsor inbox that can receive future
+claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated
+human email just to fill the flag — omit it instead.
 `example.invalid` addresses are only appropriate inside documented harness or
 proof runs. `--human-email` remains accepted as a compatibility alias for
 `--agent-contact`.
 
+Anonymous signups mint a fresh agent identity on every call, so re-running
+signup without a contact creates a new agent instead of returning the existing
+one; rely on the saved config to reuse the identity you already have.
+
+`--discovery-source SLUG` (or the `IMAGE_SKILL_DISCOVERY_SOURCE` environment
+variable; the flag wins) optionally records where you discovered Image Skill —
+a short channel slug such as `clawhub`, `skills-sh`, or `npm` (lowercase
+letters/digits plus `.`/`_`/`-`, max 64 chars). It is self-reported,
+first-touch (a later re-signup never relabels it), and never required: omit it
+when you do not know the channel rather than guessing.
+
+### `image-skill claim request`
+
+Attaches an email-shaped durable contact inbox to the authenticated agent —
+the on-demand identity upgrade after an anonymous signup. Use it when funding
+or durability makes a reachable contact worth having (billing, abuse, and
+recovery notices).
+
+```bash
+image-skill claim request \
+  --contact agent-inbox@example.com \
+  --json
+```
+
+Re-running with the same contact is idempotent (`data.state` is `unchanged`);
+a different contact replaces the previous one (`data.state` is `attached`).
+Attaching a contact is not inbox-ownership verification: `data.claim_state`
+stays `unclaimed` and `data.claim_request_state` reports `requested`. The
+response echoes only a redacted form of the contact.
+
 If the runtime has a separate secret store, it may provide the token to commands
 as `IMAGE_SKILL_TOKEN`. Keep that value outside prompts, logs, issue text, and
 feedback. Saved config, `IMAGE_SKILL_TOKEN`, and `--token-stdin` are all
@@ -276,7 +307,6 @@ runtime needs a writable compatibility config path, set
 ```bash
 export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
 npm_config_update_notifier=false npx -y image-skill@latest signup --agent \
-  --agent-contact agent-inbox@example.com \
   --agent-name creative-agent \
   --runtime codex \
   --json

package/skills/image-skill/references/commands.json

@@ -27,6 +27,14 @@
       "mutation": true,
       "spend": false
     },
+    {
+      "id": "claim",
+      "docs_anchor": "image-skill-claim-request",
+      "surface": "hosted_cli",
+      "mutation": true,
+      "spend": false,
+      "subcommands": ["request"]
+    },
     {
       "id": "whoami",
       "docs_anchor": "image-skill-whoami",
@@ -140,12 +148,13 @@
       "key": "",
       "help": {
         "command": "help",
-        "usage": "image-skill <doctor|trust|signup|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "usage": "image-skill <doctor|trust|signup|claim|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
         "docs_url": "https://image-skill.com/cli.md",
         "commands": [
           "doctor",
           "trust",
-          "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
+          "signup --agent --agent-name NAME --runtime RUNTIME",
+          "claim request --contact INBOX",
           "whoami",
           "usage quota",
           "quota",
@@ -202,15 +211,34 @@
       "key": "signup",
       "help": {
         "command": "image-skill signup help",
-        "usage": "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json",
+        "usage": "image-skill signup --agent --agent-name NAME --runtime RUNTIME --json",
         "docs_url": "https://image-skill.com/cli.md#image-skill-signup-agent",
-        "required_flags": [
-          "--agent",
+        "required_flags": ["--agent", "--agent-name", "--runtime"],
+        "optional_flags": [
           "--agent-contact",
-          "--agent-name",
-          "--runtime"
-        ],
-        "optional_flags": ["--show-token", "--no-save", "--token-stdin"]
+          "--show-token",
+          "--no-save",
+          "--token-stdin"
+        ]
+      }
+    },
+    {
+      "key": "claim",
+      "help": {
+        "command": "image-skill claim help",
+        "usage": "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-claim-request",
+        "subcommands": ["request"]
+      }
+    },
+    {
+      "key": "claim request",
+      "help": {
+        "command": "image-skill claim request help",
+        "usage": "image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+        "docs_url": "https://image-skill.com/cli.md#image-skill-claim-request",
+        "required_flags": ["--contact"],
+        "optional_flags": ["--token-stdin"]
       }
     },
     {

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

@@ -61,7 +61,7 @@ First-run guide loop:
 1. Run image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint and the only required first command. It performs read-only hosted reachability, executable model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.guide_warning, data.next_command_effect, data.auth_ready, data.no_spend_evaluation, data.no_spend_next_command, data.no_spend_next_command_effect, data.self_fund_next_command, data.self_fund_handoff, data.auth_handoff, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
 2. Read data.guide_warning, then follow data.next_command when its next_command_safety is safe for the current spend policy. Do not run doctor, models list, signup, whoami, quota, dry-run, or payment commands as a setup checklist before the guide asks for them.
 3. If data.stage is prompt_required, rerun data.next_command with the real prompt.
-4. If data.stage is auth_required, data.auth_ready.ready is false and data.guide_warning.next_command_safety is hosted_signup_no_spend_setup. Run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the configured config path is blocked, data.next_command sets IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" and still runs a saved-config signup; do not switch to raw-token handoff unless recovery explicitly requires it. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. The signup command uses --agent-contact as an email-shaped durable contact inbox for the restricted agent identity, not as a requirement to find an individual human. Hosted signup returns the raw restricted token only when --show-token is set, and only once. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
+4. If data.stage is auth_required, data.auth_ready.ready is false and data.guide_warning.next_command_safety is hosted_signup_no_spend_setup. Run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the configured config path is blocked, data.next_command sets IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" and still runs a saved-config signup; do not switch to raw-token handoff unless recovery explicitly requires it. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. Signup is anonymous by default: no contact inbox is required to get a restricted token. The optional --agent-contact flag takes an email-shaped durable contact inbox for the restricted agent identity, not a requirement to find an individual human; attach one later with image-skill claim request --contact INBOX --json when funding or durability makes it worth having. Hosted signup returns the raw restricted token only when --show-token is set, and only once. When providing a contact, use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Never invent an inbox or borrow an unrelated human email just to fill the flag — omit it instead. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. Anonymous signups mint a fresh agent identity on every call; reuse the saved config instead of re-running signup. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
 5. 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. 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.
 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, 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.
@@ -71,7 +71,8 @@ Manual escape hatches are not prerequisites. Use image-skill doctor, image-skill
 
 Core commands:
 - image-skill doctor --json
-- image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json
+- image-skill signup --agent --agent-name NAME --runtime RUNTIME --json
+- image-skill claim request --contact AGENT_OR_OPERATOR_INBOX --json
 - image-skill whoami --json
 - image-skill usage quota --json
 - image-skill quota --json (compatibility alias)
@@ -110,7 +111,8 @@ Core commands:
 - image-skill feedback create --type user_feedback --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. Request JSON prefers agent_contact as the email-shaped durable contact inbox for the restricted agent identity; human_email remains accepted only as a legacy compatibility alias. The contact is not a requirement that an autonomous agent stop until a specific human is present. Direct API callers receive the raw token once as data.token only when request.return_token is true; store that token in the agent runtime secret store and never put it in prompts, logs, issue text, or feedback. The public CLI default signup path requests the token only to save local auth config, then reports data.token:null and data.auth_handoff.status:saved_config_ready so no raw token copy step is required.
+- POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. The contact is optional: omitting agent_contact performs an anonymous signup that mints a fresh agent identity. When provided, agent_contact is the email-shaped durable contact inbox for the restricted agent identity; human_email remains accepted only as a legacy compatibility alias. The contact is never a requirement that an autonomous agent stop until a specific human is present. Direct API callers receive the raw token once as data.token only when request.return_token is true; store that token in the agent runtime secret store and never put it in prompts, logs, issue text, or feedback. The public CLI default signup path requests the token only to save local auth config, then reports data.token:null and data.auth_handoff.status:saved_config_ready so no raw token copy step is required.
+- POST https://api.image-skill.com/v1/agent-claims attaches an email-shaped durable contact inbox to the authenticated agent after an (often anonymous) signup. Request JSON is {"contact": INBOX}. Re-sending the same contact is idempotent (data.state unchanged); a different contact replaces the previous one (data.state attached). Attaching a contact is not inbox-ownership verification: data.claim_state stays unclaimed and data.claim_request_state reports requested. The response echoes only a redacted contact.
 - 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/payment-methods returns the no-auth action-only payment rail catalog. It tells agents which currently usable rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, agent_initiated, agent_settleable, settlement_blocker, limits, endpoint paths, and recovery commands. Planned, watch-only, fake, and private harness rails are intentionally omitted.