image-skill 0.1.25 → 0.1.27

package/CHANGELOG.md

@@ -6,6 +6,22 @@ provenance; this file is the human- and agent-readable release map.
 
 ## Unreleased
 
+## 0.1.27 - 2026-06-02
+
+- Fix (activation): default hosted signup now reports saved auth as a positive
+  `data.auth_handoff.status: "saved_config_ready"` state, keeps `data.token`
+  null, and suppresses the generic hosted token-returned warning when the
+  public CLI saved the token instead of showing it. Fresh agents can rerun the
+  guide or continue with `whoami`, feedback, credits, create, or edit without
+  hunting for a raw token or running a separate `auth save`.
+
+## 0.1.26 - 2026-06-02
+
+- Fix (activation): public CLI subcommand help flags now return command help
+  instead of `INVALID_ARGUMENTS`. Fresh agents can run `signup --help`,
+  `credits buy --help`, `models show --help`, or similar discovery commands
+  without triggering auth, network, payment, or config validation.
+
 ## 0.1.25 - 2026-06-02
 
 - Fix (activation): `create --guide` now probes whether the public CLI auth

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.25";
+const VERSION = "0.1.27";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -31,6 +31,8 @@ const SIGNUP_SUGGESTED_COMMAND =
   "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --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.";
+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 = "npx -y image-skill@latest";
 const CREDIT_UNIT_USD = 0.01;
 const PAYMENT_CREDENTIAL_FLAGS = new Set([
@@ -62,47 +64,16 @@ process.exitCode = result.exitCode;
 async function main(rawArgv) {
   const [command, ...rest] = rawArgv;
 
-  if (
-    command === undefined ||
-    command === "help" ||
-    command === "--help" ||
-    command === "-h"
-  ) {
-    return success("image-skill help", {
-      usage:
-        "image-skill <doctor|trust|signup|auth|whoami|usage|quota|credits|models|capabilities|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",
-        "auth status",
-        "auth save",
-        "auth logout",
-        "whoami",
-        "usage quota",
-        "credits methods",
-        "credits packs list",
-        "credits quote",
-        "credits buy",
-        "credits status",
-        "models list",
-        "models show",
-        "create --guide",
-        "capabilities list",
-        "capabilities show",
-        "create",
-        "upload",
-        "edit",
-        "assets show",
-        "assets get",
-        "jobs show",
-        "jobs wait",
-        "activity list",
-        "activity show",
-        "feedback create",
-      ],
-    });
+  if (command === undefined || command === "--help" || command === "-h") {
+    return publicCliHelp([]);
+  }
+
+  if (command === "help") {
+    return publicCliHelp(helpTarget(rest));
+  }
+
+  if (hasHelpFlag(rest)) {
+    return publicCliHelp(helpTarget([command, ...rest]));
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
@@ -173,6 +144,321 @@ async function main(rawArgv) {
   }
 }
 
+function publicCliHelp(path) {
+  const key = helpKey(path);
+  const help =
+    commandHelpByKey(key) ?? commandHelpByKey(helpKey(path.slice(0, 1)));
+  if (help === undefined) {
+    return publicCliHelp([]);
+  }
+  return success(help.command, help);
+}
+
+function hasHelpFlag(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+
+function helpTarget(argv) {
+  return argv.filter(
+    (arg) => arg !== "--help" && arg !== "-h" && arg !== "--json",
+  );
+}
+
+function helpKey(path) {
+  const clean = path.filter((arg) => !arg.startsWith("-"));
+  if (clean.length >= 2) {
+    return `${clean[0]} ${clean[1]}`;
+  }
+  return clean[0] ?? "";
+}
+
+function commandHelpByKey(key) {
+  return {
+    "": {
+      command: "image-skill help",
+      usage:
+        "image-skill <doctor|trust|signup|auth|whoami|usage|quota|credits|models|capabilities|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",
+        "auth status",
+        "auth save",
+        "auth logout",
+        "whoami",
+        "usage quota",
+        "credits methods",
+        "credits packs list",
+        "credits quote",
+        "credits buy",
+        "credits status",
+        "models list",
+        "models show",
+        "create --guide",
+        "capabilities list",
+        "capabilities show",
+        "create",
+        "upload",
+        "edit",
+        "assets show",
+        "assets get",
+        "jobs show",
+        "jobs wait",
+        "activity list",
+        "activity show",
+        "feedback create",
+      ],
+    },
+    doctor: {
+      command: "image-skill doctor help",
+      usage: "image-skill doctor --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-doctor",
+      description:
+        "Check hosted API reachability, CLI version, auth state, and health.",
+    },
+    trust: {
+      command: "image-skill trust help",
+      usage: "image-skill trust --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-trust",
+      description:
+        "Return npm provenance, hosted contract hashes, API health, and model availability evidence.",
+    },
+    signup: {
+      command: "image-skill signup help",
+      usage:
+        "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
+      required_flags: [
+        "--agent",
+        "--agent-contact",
+        "--agent-name",
+        "--runtime",
+      ],
+      optional_flags: ["--show-token", "--no-save", "--token-stdin"],
+    },
+    auth: {
+      command: "image-skill auth help",
+      usage: "image-skill auth <status|save|logout> --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-auth",
+      subcommands: ["status", "save", "logout"],
+    },
+    "auth status": {
+      command: "image-skill auth status help",
+      usage: "image-skill auth status --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-auth",
+    },
+    "auth save": {
+      command: "image-skill auth save help",
+      usage: "image-skill auth save --token-stdin --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-auth",
+    },
+    "auth logout": {
+      command: "image-skill auth logout help",
+      usage: "image-skill auth logout --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-auth",
+    },
+    whoami: {
+      command: "image-skill whoami help",
+      usage: "image-skill whoami --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-whoami",
+    },
+    usage: {
+      command: "image-skill usage help",
+      usage: "image-skill usage quota --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-usage",
+      subcommands: ["quota"],
+    },
+    "usage quota": {
+      command: "image-skill usage quota help",
+      usage: "image-skill usage quota --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-usage",
+    },
+    quota: {
+      command: "image-skill quota help",
+      usage: "image-skill quota --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-quota",
+    },
+    credits: {
+      command: "image-skill credits help",
+      usage: "image-skill credits <methods|packs list|quote|buy|status> --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-credits",
+      subcommands: ["methods", "packs list", "quote", "buy", "status"],
+    },
+    "credits methods": {
+      command: "image-skill credits methods help",
+      usage: "image-skill credits methods --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-credits",
+    },
+    "credits packs": {
+      command: "image-skill credits packs help",
+      usage: "image-skill credits packs list --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-credits",
+      subcommands: ["list"],
+    },
+    "credits quote": {
+      command: "image-skill credits quote help",
+      usage:
+        "image-skill credits quote --pack PACK_ID --payment-method stripe_x402.exact.usdc --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-credits",
+      required_flags: ["--pack or --credits"],
+      optional_flags: ["--payment-method", "--idempotency-key"],
+    },
+    "credits buy": {
+      command: "image-skill credits buy help",
+      usage:
+        "image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-credits",
+      required_flags: ["--provider", "--quote-id", "--idempotency-key"],
+      supported_providers: ["stripe", "stripe_x402"],
+    },
+    "credits status": {
+      command: "image-skill credits status help",
+      usage:
+        "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-credits",
+      required_flags: ["--payment-attempt-id"],
+    },
+    models: {
+      command: "image-skill models help",
+      usage: "image-skill models <list|show> --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-models",
+      subcommands: ["list", "show"],
+    },
+    "models list": {
+      command: "image-skill models list help",
+      usage:
+        "image-skill models list --available --operation image.generate --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-models",
+    },
+    "models show": {
+      command: "image-skill models show help",
+      usage: "image-skill models show MODEL_ID --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-models",
+    },
+    capabilities: {
+      command: "image-skill capabilities help",
+      usage: "image-skill capabilities <list|show> --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-capabilities",
+      subcommands: ["list", "show"],
+    },
+    "capabilities list": {
+      command: "image-skill capabilities list help",
+      usage: "image-skill capabilities list --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-capabilities",
+    },
+    "capabilities show": {
+      command: "image-skill capabilities show help",
+      usage: "image-skill capabilities show CAPABILITY_ID --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-capabilities",
+    },
+    create: {
+      command: "image-skill create help",
+      usage:
+        'image-skill create --prompt "..." --intent explore --max-estimated-usd-per-image 0.07 --json',
+      docs_url: "https://image-skill.com/cli.md#image-skill-create",
+      optional_flags: [
+        "--guide",
+        "--dry-run",
+        "--model",
+        "--aspect-ratio",
+        "--output-count",
+        "--model-parameters-json",
+        "--idempotency-key",
+      ],
+    },
+    upload: {
+      command: "image-skill upload help",
+      usage: "image-skill upload PATH_OR_URL --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-upload",
+    },
+    edit: {
+      command: "image-skill edit help",
+      usage: 'image-skill edit --input image_... --prompt "..." --json',
+      docs_url: "https://image-skill.com/cli.md#image-skill-edit",
+      required_flags: ["--input"],
+      optional_flags: [
+        "--prompt",
+        "--model",
+        "--mask",
+        "--element-reference",
+        "--model-parameters-json",
+        "--idempotency-key",
+      ],
+    },
+    assets: {
+      command: "image-skill assets help",
+      usage: "image-skill assets <show|get> ASSET_ID_OR_URL --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-assets",
+      subcommands: ["show", "get"],
+    },
+    "assets show": {
+      command: "image-skill assets show help",
+      usage: "image-skill assets show ASSET_ID_OR_URL --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-assets",
+    },
+    "assets get": {
+      command: "image-skill assets get help",
+      usage: "image-skill assets get ASSET_ID_OR_URL --output PATH --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-assets",
+    },
+    jobs: {
+      command: "image-skill jobs help",
+      usage: "image-skill jobs <show|wait> JOB_ID --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-jobs",
+      subcommands: ["show", "wait"],
+    },
+    "jobs show": {
+      command: "image-skill jobs show help",
+      usage: "image-skill jobs show JOB_ID --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-jobs",
+    },
+    "jobs wait": {
+      command: "image-skill jobs wait help",
+      usage: "image-skill jobs wait JOB_ID --timeout-ms 30000 --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-jobs",
+    },
+    activity: {
+      command: "image-skill activity help",
+      usage: "image-skill activity <list|show> --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-activity",
+      subcommands: ["list", "show"],
+    },
+    "activity list": {
+      command: "image-skill activity list help",
+      usage: "image-skill activity list --subject JOB_ID --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-activity",
+    },
+    "activity show": {
+      command: "image-skill activity show help",
+      usage: "image-skill activity show REFERENCE --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-activity",
+    },
+    feedback: {
+      command: "image-skill feedback help",
+      usage: "image-skill feedback create --title TITLE --body BODY --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-feedback",
+      subcommands: ["create"],
+    },
+    "feedback create": {
+      command: "image-skill feedback create help",
+      usage:
+        "image-skill feedback create --title TITLE --body BODY --type user_feedback --json",
+      docs_url: "https://image-skill.com/cli.md#image-skill-feedback",
+      optional_flags: [
+        "--title",
+        "--body",
+        "--type",
+        "--severity",
+        "--confidence",
+        "--expected",
+        "--actual",
+        "--command",
+      ],
+    },
+  }[key];
+}
+
 async function doctor(argv) {
   const args = parseArgs(argv);
   const apiBaseUrl = apiBase(args);
@@ -378,7 +664,9 @@ async function signup(argv) {
   rewriteSignupContactFailure(result);
 
   const token = result.envelope.data?.token;
-  const warnings = [...result.envelope.warnings];
+  const warnings = result.envelope.warnings.filter(
+    (warning) => warning !== HOSTED_SIGNUP_TOKEN_RETURNED_WARNING,
+  );
   if (result.envelope.ok && shouldSave) {
     if (typeof token !== "string" || token.trim().length === 0) {
       return failure(
@@ -403,9 +691,6 @@ async function signup(argv) {
     } catch (error) {
       return configWriteFailure("image-skill signup", error);
     }
-    warnings.push(
-      "hosted restricted token was saved to the public CLI config with 0600 permissions; later commands can authenticate from config without repeating signup",
-    );
   }
   if (result.envelope.ok && showToken) {
     warnings.push(
@@ -426,15 +711,25 @@ async function signup(argv) {
         saved: shouldSave,
         config_path: shouldSave ? configPath() : null,
         reason: shouldSave
-          ? "hosted signup saved the restricted token to the public CLI config for later commands"
+          ? "auth is ready in the public CLI config; no raw token copy step is required"
           : showToken
             ? "hosted signup returned the token once for the agent runtime secret store"
             : "hosted signup did not request a raw token or save config because --no-save was set",
       },
       auth_handoff: {
+        status: shouldSave
+          ? "saved_config_ready"
+          : showToken
+            ? "manual_token_handoff"
+            : "not_saved",
+        saved_auth_ready: shouldSave,
         accepted_methods: ["config", "IMAGE_SKILL_TOKEN", "--token-stdin"],
         token_source_after_signup: shouldSave ? "config" : "not_saved",
         secret_value_included: showToken,
+        raw_token_copy_required: !shouldSave,
+        rerun_guide_hint: shouldSave
+          ? "Rerun the guide command you just ran; the CLI will authenticate from saved config."
+          : "Rerun the guide with IMAGE_SKILL_TOKEN or --token-stdin after storing the returned token.",
         next_step: shouldSave
           ? "Run whoami, usage quota, feedback create, credits, create, or edit normally; the CLI will read the saved config."
           : "Store data.token in the agent runtime secret store immediately, then pass it with IMAGE_SKILL_TOKEN or --token-stdin.",

package/cli.md

@@ -91,6 +91,9 @@ Hosted signup saves the restricted `isk_r_` token to the public CLI config by
 default with `0600` permissions, so later hosted commands can authenticate from
 config without repeating signup or carrying a raw token through prompts. Set
 `IMAGE_SKILL_CONFIG_PATH` first when the default config home may be read-only.
+Successful default signup reports `data.auth_handoff.status` as
+`saved_config_ready`, keeps `data.token` null, and should not require any
+token-copy step.
 The raw token is returned only when `--show-token` is set, and only once. Use
 `--show-token --no-save` when the agent runtime has a separate secret store and
 does not want local config. Do not paste tokens into prompts, logs, issue text,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "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/skills/image-skill/references/cli.md

@@ -91,6 +91,9 @@ Hosted signup saves the restricted `isk_r_` token to the public CLI config by
 default with `0600` permissions, so later hosted commands can authenticate from
 config without repeating signup or carrying a raw token through prompts. Set
 `IMAGE_SKILL_CONFIG_PATH` first when the default config home may be read-only.
+Successful default signup reports `data.auth_handoff.status` as
+`saved_config_ready`, keeps `data.token` null, and should not require any
+token-copy step.
 The raw token is returned only when `--show-token` is set, and only once. Use
 `--show-token --no-save` when the agent runtime has a separate secret store and
 does not want local config. Do not paste tokens into prompts, logs, issue text,