image-skill 0.1.12 → 0.1.14

package/bin/image-skill.mjs

@@ -7,8 +7,12 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.12";
+const VERSION = "0.1.14";
+const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
+const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
+const DEFAULT_NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+const PUBLIC_REPO_URL = "https://github.com/danielgwilson/image-skill-cli";
 const PROMPTLESS_EDIT_MODEL_IDS = new Set([
   "fal.flux-dev-redux",
   "fal.flux-krea-redux",
@@ -20,9 +24,9 @@ const DEFAULT_CONFIG_PATH = join(
   "config.json",
 );
 const SIGNUP_SUGGESTED_COMMAND =
-  "image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name NAME --runtime RUNTIME --save --json";
+  "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json";
 const SIGNUP_CONTACT_GUIDANCE =
-  "Use --agent-contact for the accountable contact, sponsor, operator, or agent inbox for this restricted agent identity. If no individual human is in the loop, use a durable operator/team/agent inbox that can receive future claim, billing, or abuse notices; do not invent a person or use a throwaway inbox. --human-email remains a compatibility alias.";
+  "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 PAYMENT_CREDENTIAL_FLAGS = new Set([
   "payment-token",
   "payment-secret",
@@ -60,11 +64,12 @@ async function main(rawArgv) {
   ) {
     return success("image-skill help", {
       usage:
-        "image-skill <doctor|signup|auth|whoami|usage|quota|credits|models|capabilities|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "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",
-        "signup --agent --agent-contact --save",
+        "trust",
+        "signup --agent --agent-contact",
         "auth status",
         "auth save",
         "auth logout",
@@ -77,6 +82,7 @@ async function main(rawArgv) {
         "credits status",
         "models list",
         "models show",
+        "create --guide",
         "capabilities list",
         "capabilities show",
         "create",
@@ -105,6 +111,8 @@ async function main(rawArgv) {
     switch (command) {
       case "doctor":
         return await doctor(rest);
+      case "trust":
+        return await trust(rest);
       case "signup":
         return await signup(rest);
       case "auth":
@@ -193,6 +201,106 @@ async function doctor(argv) {
   });
 }
 
+async function trust(argv) {
+  const args = parseArgs(argv);
+  const unsupportedFlags = [...args.flags.keys()].filter(
+    (flag) => !["json", "api-base-url"].includes(flag),
+  );
+  if (args.positionals.length > 0 || unsupportedFlags.length > 0) {
+    return invalid(
+      "image-skill trust",
+      unsupportedFlags.length > 0
+        ? `unsupported flags for trust: ${unsupportedFlags.map((flag) => `--${flag}`).join(", ")}`
+        : "trust does not accept positional arguments",
+    );
+  }
+
+  const checkedAt = new Date().toISOString();
+  const apiBaseUrl = apiBase(args);
+  const docsBaseUrl = docsBaseForApiBaseUrl(apiBaseUrl);
+  const npmRegistryBaseUrl = npmRegistryBaseForApiBaseUrl(apiBaseUrl);
+
+  const [npmPackage, hostedContracts, health, models] = await Promise.all([
+    inspectNpmPackage({
+      checkedAt,
+      registryBaseUrl: npmRegistryBaseUrl,
+    }),
+    inspectHostedContracts({
+      checkedAt,
+      docsBaseUrl,
+    }),
+    apiRequest({
+      command: "image-skill trust",
+      method: "GET",
+      apiBaseUrl,
+      path: "/healthz",
+    }),
+    apiRequest({
+      command: "image-skill trust",
+      method: "GET",
+      apiBaseUrl,
+      path: "/v1/models",
+    }),
+  ]);
+
+  const hostedApi = trustHostedApi(health, apiBaseUrl, checkedAt);
+  const modelRegistry = trustModelRegistry(models, apiBaseUrl, checkedAt);
+  const publicRepo = trustPublicRepo(npmPackage);
+  const proofUrls = trustProofUrls({
+    npmPackage,
+    hostedContracts,
+    publicRepo,
+  });
+  const warnings = trustWarnings({
+    npmPackage,
+    hostedContracts,
+    hostedApi,
+    modelRegistry,
+    proofUrls,
+  });
+  const summary = trustSummary({
+    warnings,
+    npmPackage,
+    hostedContracts,
+    hostedApi,
+    modelRegistry,
+  });
+
+  return success(
+    "image-skill trust",
+    {
+      schema: "image-skill.trust-packet.v0",
+      checked_at: checkedAt,
+      subject: {
+        package: PACKAGE_NAME,
+        cli_version: VERSION,
+        mode: "public_hosted_cli",
+        api_base_url: apiBaseUrl,
+        docs_base_url: docsBaseUrl,
+        npm_registry_url: npmRegistryBaseUrl,
+      },
+      summary,
+      npm_package: npmPackage,
+      public_repo: publicRepo,
+      hosted_contracts: hostedContracts,
+      hosted_api: hostedApi,
+      model_registry: modelRegistry,
+      safe_commands: trustSafeCommands(),
+      proof_urls: proofUrls,
+      redaction: {
+        secrets_included: false,
+        private_paths_included: false,
+        config_file_read: false,
+        token_sources_read: false,
+        credential_values_read: false,
+        forbidden_material:
+          "tokens, API keys, private repo paths, provider credentials, payment credentials, card data, wallet secrets, and private package metadata",
+      },
+    },
+    warnings,
+  );
+}
+
 async function signup(argv) {
   const args = parseArgs(argv);
   if (!flagBool(args, "agent")) {
@@ -232,7 +340,7 @@ async function signup(argv) {
       },
     );
   }
-  const save = flagBool(args, "save");
+  const save = shouldSaveSignupAuth(args);
   const showToken = flagBool(args, "show-token");
   if (save) {
     const configReady = await assertConfigWritable("image-skill signup");
@@ -252,6 +360,8 @@ async function signup(argv) {
       return_token: save || showToken,
     },
   });
+  result.envelope.command = "image-skill signup";
+  rewriteSignupContactFailure(result);
 
   const token = result.envelope.data?.token;
   const warnings = [...result.envelope.warnings];
@@ -261,7 +371,7 @@ async function signup(argv) {
         "image-skill signup",
         3,
         "SIGNUP_TOKEN_NOT_RETURNED",
-        "signup --save requires a returned hosted token",
+        "signup default auth persistence requires a returned hosted token",
         true,
         {
           suggested_command: SIGNUP_SUGGESTED_COMMAND,
@@ -282,22 +392,19 @@ async function signup(argv) {
     warnings.push(`saved hosted token to ${configPath()}`);
   }
 
-  if (
-    !showToken &&
-    result.envelope.data &&
-    typeof result.envelope.data === "object"
-  ) {
+  if (result.envelope.data && typeof result.envelope.data === "object") {
+    const publicData = publicSignupData(result.envelope.data);
     result.envelope.data = {
-      ...result.envelope.data,
-      token: null,
-      token_presented: false,
+      ...publicData,
+      token: showToken ? (token ?? publicData.token ?? null) : null,
+      token_presented: showToken,
       storage: {
-        ...(result.envelope.data.storage ?? {}),
+        ...(publicData.storage ?? {}),
         saved: save,
         config_path: save ? configPath() : null,
         reason: save
           ? "public CLI saved token locally with 0600 permissions"
-          : "token redacted; rerun with --show-token or --save at signup time",
+          : "token not saved; later hosted commands need saved auth, IMAGE_SKILL_TOKEN, or --token-stdin",
       },
     };
   }
@@ -305,6 +412,31 @@ async function signup(argv) {
   return result;
 }
 
+function rewriteSignupContactFailure(result) {
+  const error = result.envelope.error;
+  if (
+    error !== null &&
+    typeof error === "object" &&
+    error.message === "human_email must be a valid email address"
+  ) {
+    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";
+    error.recovery = {
+      ...(error.recovery ?? {}),
+      suggested_command: SIGNUP_SUGGESTED_COMMAND,
+      docs_url: "https://image-skill.com/cli.md#image-skill-signup-agent",
+    };
+  }
+}
+
+function publicSignupData(data) {
+  const { human_email: humanEmail, ...rest } = data;
+  return {
+    ...rest,
+    ...(typeof humanEmail === "string" ? { agent_contact: humanEmail } : {}),
+  };
+}
+
 async function auth(argv) {
   const [subcommand, ...rest] = argv;
   const args = parseArgs(rest);
@@ -384,25 +516,31 @@ async function whoami(argv) {
 
 async function usage(argv) {
   const [subcommand, ...rest] = argv;
+  if (subcommand === undefined || subcommand.startsWith("-")) {
+    return await quota(argv, "image-skill usage quota");
+  }
   if (subcommand !== "quota") {
     return invalid("image-skill usage", "usage requires the quota subcommand");
   }
-  return quota(rest);
+  return quota(rest, "image-skill usage quota");
 }
 
-async function quota(argv) {
+async function quota(argv, command = "image-skill quota") {
   const args = parseArgs(argv);
   const token = await resolveToken(args);
   if (!token.ok) {
-    return token.result;
+    return withCommand(token.result, command);
   }
-  return apiRequest({
-    command: "image-skill quota",
-    method: "GET",
-    apiBaseUrl: apiBase(args),
-    path: "/v1/quota",
-    token: token.token,
-  });
+  return withCommand(
+    await apiRequest({
+      command,
+      method: "GET",
+      apiBaseUrl: apiBase(args),
+      path: "/v1/quota",
+      token: token.token,
+    }),
+    command,
+  );
 }
 
 async function credits(argv) {
@@ -601,15 +739,58 @@ async function models(argv) {
   ) {
     return invalid("image-skill models", "models supports list or show");
   }
+  const query = modelListQuery(args);
+  if (!query.ok) {
+    return invalid(
+      subcommand === "list" ? "image-skill models list" : "image-skill models",
+      query.message,
+    );
+  }
   return apiRequest({
     command:
       subcommand === "list" ? "image-skill models list" : "image-skill models",
     method: "GET",
     apiBaseUrl: apiBase(args),
-    path: "/v1/models",
+    path: query.path,
   });
 }
 
+function modelListQuery(args) {
+  const available = flagBool(args, "available");
+  const executable = flagBool(args, "executable");
+  const catalogOnly = flagBool(args, "catalog-only");
+  if (catalogOnly && (available || executable)) {
+    return {
+      ok: false,
+      message:
+        "models list --catalog-only cannot be combined with --available or --executable",
+    };
+  }
+  const params = new URLSearchParams();
+  if (available) {
+    params.set("available", "true");
+  }
+  if (executable) {
+    params.set("executable", "true");
+  }
+  if (catalogOnly) {
+    params.set("catalog_only", "true");
+  }
+  addQueryValue(params, "operation", flagString(args, "operation"));
+  addQueryValue(params, "provider", flagString(args, "provider"));
+  const query = params.toString();
+  return {
+    ok: true,
+    path: query.length === 0 ? "/v1/models" : `/v1/models?${query}`,
+  };
+}
+
+function addQueryValue(params, name, value) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    params.set(name, value.trim());
+  }
+}
+
 async function capabilities(argv) {
   const [subcommand, ...rest] = argv;
   const args = parseArgs(
@@ -651,20 +832,424 @@ async function capabilities(argv) {
   });
 }
 
+async function createGuide(args) {
+  if (flagBool(args, "dry-run")) {
+    return invalid(
+      "image-skill create --guide",
+      "create --guide cannot be combined with --dry-run; the guide returns the dry-run escape hatch separately",
+    );
+  }
+  if (hasReferenceFlags(args)) {
+    return invalid(
+      "image-skill create --guide",
+      "create --guide does not upload or resolve reference images; inspect the model with models show, then run create --dry-run before live referenced creates",
+    );
+  }
+  const modelParameters = jsonObjectFlag(args, "model-parameters-json");
+  if (!modelParameters.ok) {
+    return modelParameters.result;
+  }
+
+  const apiBaseUrl = apiBase(args);
+  const prompt = flagString(args, "prompt") ?? args.positionals[0] ?? "";
+  const trimmedPrompt = prompt.trim();
+  const requestedModelId = flagString(args, "model");
+  const requestedProviderId = flagString(args, "provider");
+  const requestedIntent = flagString(args, "intent") ?? "explore";
+  const health = await apiRequest({
+    command: "image-skill create --guide",
+    method: "GET",
+    apiBaseUrl,
+    path: "/healthz",
+  });
+  const models = await apiRequest({
+    command: "image-skill create --guide",
+    method: "GET",
+    apiBaseUrl,
+    path: "/v1/models",
+  });
+  const payments = await apiRequest({
+    command: "image-skill create --guide",
+    method: "GET",
+    apiBaseUrl,
+    path: "/v1/payment-methods",
+  });
+  const token = await resolveToken(args, { allowMissing: true });
+  if (!token.ok) {
+    return token.result;
+  }
+
+  const selected =
+    models.envelope.ok && models.envelope.data?.models
+      ? selectCreateGuideModel(models.envelope.data.models, requestedModelId)
+      : null;
+  const pricing = selected?.economics?.credit_pricing ?? null;
+  const estimatedCredits = pricing?.credits_required ?? null;
+  const estimatedUsdPerImage =
+    selected?.economics?.estimated_usd_per_image ??
+    (pricing === null ? null : pricing.estimated_revenue_usd);
+  const budgetGuard =
+    flagNumber(args, "max-estimated-usd-per-image") ??
+    estimatedUsdPerImage ??
+    (estimatedCredits === null ? 0.07 : estimatedCredits / 100);
+  const quota =
+    token.token === null
+      ? null
+      : await apiRequest({
+          command: "image-skill create --guide",
+          method: "GET",
+          apiBaseUrl,
+          path: "/v1/quota",
+          token: token.token,
+        });
+  const paymentSummary = createGuidePaymentSummary(payments.envelope.data);
+  const stage = createGuideStage({
+    prompt: trimmedPrompt,
+    health,
+    models,
+    selected,
+    token,
+    quota,
+    estimatedCredits,
+  });
+  const blocker = createGuideBlocker(stage, {
+    requestedModelId,
+    quota,
+    estimatedCredits,
+  });
+  const nextCommand = createGuideNextCommand(stage, {
+    prompt: trimmedPrompt,
+    selected,
+    requestedProviderId,
+    requestedIntent,
+    budgetGuard,
+    apiBaseUrl: explicitApiBaseUrl(args),
+    paymentSummary,
+  });
+  const afterNext =
+    stage === "auth_required" || stage === "quota_required"
+      ? renderGuideCommand(trimmedPrompt, explicitApiBaseUrl(args))
+      : null;
+  return success("image-skill create --guide", {
+    schema: "image-skill.create-guide.v1",
+    ready: stage === "ready_to_create",
+    stage,
+    checks: {
+      hosted_api: {
+        reachable: health.envelope.ok,
+        status: health.envelope.data?.status ?? null,
+        api_base_url: apiBaseUrl,
+        error_code: health.envelope.error?.code ?? null,
+      },
+      auth: {
+        source: token.source === "anonymous" ? "none" : token.source,
+        authenticated: quota?.envelope.data?.authenticated === true,
+        claim_state: quota?.envelope.data?.claim_state ?? null,
+        token_status: quota?.envelope.data?.token_status ?? null,
+        saved_config_path: configPath(),
+      },
+      models: {
+        reachable: models.envelope.ok,
+        executable_count: models.envelope.data?.summary?.executable ?? 0,
+        cataloged_not_wired_count:
+          models.envelope.data?.summary?.cataloged_not_wired ?? 0,
+        error_code: models.envelope.error?.code ?? null,
+      },
+      quota: {
+        checked: quota !== null,
+        authenticated: quota?.envelope.data?.authenticated === true,
+        remaining_credits: quotaRemainingCredits(quota?.envelope.data ?? null),
+        required_credits: estimatedCredits,
+        daily_jobs_remaining:
+          quota?.envelope.data?.daily_jobs?.remaining ?? null,
+        reason:
+          quota === null
+            ? "auth_required"
+            : quota.envelope.ok
+              ? null
+              : (quota.envelope.error?.code ?? "quota_unavailable"),
+      },
+      payments: paymentSummary,
+    },
+    selection:
+      selected === null
+        ? null
+        : {
+            operation: "create",
+            model_id: selected.id,
+            model_status: selected.status,
+            model_execution_status: selected.execution.model_execution_status,
+            reason:
+              requestedModelId === null
+                ? "default executable create model for first image"
+                : "requested executable create model",
+          },
+    cost: {
+      estimated_credits: estimatedCredits,
+      estimated_usd_per_image: estimatedUsdPerImage,
+      pricing_confidence: pricing?.pricing_confidence ?? null,
+    },
+    blocker,
+    next_command: nextCommand,
+    after_next: afterNext,
+    escape_hatches: {
+      doctor: "image-skill doctor --json",
+      model_inspection:
+        selected === null
+          ? "image-skill models list --json"
+          : `image-skill models show ${shellQuote(selected.id)} --json`,
+      payment_methods: "image-skill credits methods --json",
+      quota: "image-skill usage quota --json",
+      dry_run:
+        selected === null || trimmedPrompt.length === 0
+          ? "image-skill create --dry-run --prompt PROMPT --json"
+          : renderCreateCommand({
+              prompt: trimmedPrompt,
+              modelId: selected.id,
+              providerId: requestedProviderId,
+              intent: requestedIntent,
+              budgetGuard,
+              dryRun: true,
+              apiBaseUrl: explicitApiBaseUrl(args),
+            }),
+    },
+    mutation: {
+      provider_call: false,
+      hosted_create: false,
+      hosted_signup: false,
+      payment_object: false,
+      credit_debit: false,
+      media_write: false,
+    },
+  });
+}
+
+function selectCreateGuideModel(models, requestedModelId) {
+  const isExecutableCreate = (model) =>
+    model?.status === "available" &&
+    model?.execution?.model_execution_status === "executable" &&
+    Array.isArray(model?.supports) &&
+    model.supports.includes("create");
+  if (requestedModelId !== null) {
+    const requested = models.find((model) => model.id === requestedModelId);
+    return requested !== undefined && isExecutableCreate(requested)
+      ? requested
+      : null;
+  }
+  return models.find(isExecutableCreate) ?? null;
+}
+
+function createGuidePaymentSummary(data) {
+  const methods = Array.isArray(data?.methods)
+    ? data.methods.filter((method) => method.live_money)
+    : [];
+  return {
+    checked: data !== null && typeof data === "object",
+    live_money_methods: methods
+      .filter((method) => method.available)
+      .map((method) => method.method_id),
+    requires_browser: methods.some((method) => method.requires_browser),
+    buyer_modes: [
+      ...new Set(methods.flatMap((method) => method.buyer_modes ?? [])),
+    ],
+    suggested_commands: [
+      "image-skill credits methods --json",
+      "image-skill credits packs list --json",
+      methods[0]?.recovery?.quote_command ??
+        "image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json",
+      methods[0]?.recovery?.purchase_command ??
+        "image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json",
+      methods[0]?.recovery?.status_command ??
+        "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+    ],
+  };
+}
+
+function createGuideStage(input) {
+  if (input.prompt.length === 0) {
+    return "prompt_required";
+  }
+  if (!input.health.envelope.ok || !input.models.envelope.ok) {
+    return "service_unreachable";
+  }
+  if (input.selected === null) {
+    return "no_executable_model";
+  }
+  if (input.token.token === null) {
+    return "auth_required";
+  }
+  if (input.quota === null || !input.quota.envelope.ok) {
+    return input.quota?.envelope.error?.code === "AUTH_REQUIRED"
+      ? "auth_required"
+      : "service_unreachable";
+  }
+  const remaining = quotaRemainingCredits(input.quota.envelope.data);
+  if (
+    input.estimatedCredits !== null &&
+    remaining !== null &&
+    remaining < input.estimatedCredits
+  ) {
+    return "quota_required";
+  }
+  if (
+    input.quota.envelope.data?.daily_jobs !== undefined &&
+    input.quota.envelope.data.daily_jobs.remaining <= 0
+  ) {
+    return "quota_required";
+  }
+  return "ready_to_create";
+}
+
+function createGuideBlocker(stage, input) {
+  if (stage === "ready_to_create") {
+    return null;
+  }
+  if (stage === "prompt_required") {
+    return {
+      code: "prompt_required",
+      message: "Add --prompt so the guide can return the exact create command.",
+    };
+  }
+  if (stage === "no_executable_model") {
+    return {
+      code: "no_executable_model",
+      message:
+        input.requestedModelId === null
+          ? "No available executable create model was found in the public registry."
+          : `Requested model is not currently an available executable create model: ${input.requestedModelId}`,
+    };
+  }
+  if (stage === "auth_required") {
+    return {
+      code: "auth_required",
+      message:
+        "Sign up once with a durable agent contact before creating hosted media.",
+    };
+  }
+  if (stage === "quota_required") {
+    const remaining = quotaRemainingCredits(input.quota?.envelope.data ?? null);
+    return {
+      code: "quota_required",
+      message: `Selected first image requires ${input.estimatedCredits ?? "unknown"} credits; current remaining credits are ${remaining ?? "unknown"}.`,
+    };
+  }
+  return {
+    code: "service_unreachable",
+    message:
+      input.quota?.envelope.error?.message ??
+      "Guide could not complete read-only hosted or registry checks.",
+  };
+}
+
+function createGuideNextCommand(stage, input) {
+  if (stage === "prompt_required") {
+    return renderGuideCommand("PROMPT", input.apiBaseUrl);
+  }
+  if (stage === "no_executable_model" || stage === "service_unreachable") {
+    return "image-skill models list --json";
+  }
+  if (stage === "auth_required") {
+    return "image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name AGENT_NAME --runtime RUNTIME_NAME --json";
+  }
+  if (stage === "quota_required") {
+    return input.paymentSummary.suggested_commands[0];
+  }
+  return renderCreateCommand({
+    prompt: input.prompt,
+    modelId: input.selected.id,
+    providerId: input.requestedProviderId,
+    intent: input.requestedIntent,
+    budgetGuard: input.budgetGuard,
+    dryRun: false,
+    apiBaseUrl: input.apiBaseUrl,
+  });
+}
+
+function renderGuideCommand(prompt, apiBaseUrl) {
+  return [
+    "image-skill create --guide --prompt",
+    shellQuote(prompt),
+    ...(apiBaseUrl === null ? [] : ["--api-base-url", shellQuote(apiBaseUrl)]),
+    "--json",
+  ].join(" ");
+}
+
+function renderCreateCommand(input) {
+  return [
+    "image-skill create",
+    ...(input.dryRun ? ["--dry-run"] : []),
+    ...(input.providerId === null
+      ? []
+      : ["--provider", shellQuote(input.providerId)]),
+    "--model",
+    shellQuote(input.modelId),
+    "--prompt",
+    shellQuote(input.prompt),
+    "--intent",
+    shellQuote(input.intent),
+    "--max-estimated-usd-per-image",
+    shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.apiBaseUrl === null
+      ? []
+      : ["--api-base-url", shellQuote(input.apiBaseUrl)]),
+    "--json",
+  ].join(" ");
+}
+
+function explicitApiBaseUrl(args) {
+  return flagString(args, "api-base-url");
+}
+
+function formatUsd(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(2);
+}
+
+function shellQuote(value) {
+  return JSON.stringify(value);
+}
+
+function quotaRemainingCredits(data) {
+  if (data === null || data === undefined) {
+    return null;
+  }
+  const limits = data.limits ?? {};
+  const freeCredits =
+    typeof limits.remaining_credits === "number" ? limits.remaining_credits : 0;
+  const paidCredits =
+    typeof limits.payment_backed_remaining_credits === "number"
+      ? limits.payment_backed_remaining_credits
+      : 0;
+  return freeCredits + paidCredits;
+}
+
 async function create(argv) {
   const args = parseArgs(argv);
+  if (flagBool(args, "guide")) {
+    return createGuide(args);
+  }
   const prompt = await promptValue(args);
   if (!prompt.ok) {
     return prompt.result;
   }
-  const token = await resolveToken(args);
-  if (!token.ok) {
-    return token.result;
+  let referenceToken = null;
+  if (flagBool(args, "dry-run") && hasReferenceFlags(args)) {
+    referenceToken = await resolveToken(args);
+    if (!referenceToken.ok) {
+      return referenceToken.result;
+    }
   }
   const referencePlan = parseReferencePlan(args, "image-skill create");
   if (!referencePlan.ok) {
     return referencePlan.result;
   }
+  const anonymousDryRun =
+    flagBool(args, "dry-run") && referencePlan.referencePlans.length === 0;
+  const token =
+    referenceToken ??
+    (await resolveToken(args, { allowMissing: anonymousDryRun }));
+  if (!token.ok) {
+    return token.result;
+  }
   const modelParameters = jsonObjectFlag(args, "model-parameters-json");
   if (!modelParameters.ok) {
     return modelParameters.result;
@@ -675,11 +1260,14 @@ async function create(argv) {
   if (!outputCount.ok) {
     return outputCount.result;
   }
-  const references = await resolveReferences(
-    referencePlan.referencePlans,
-    args,
-    token.token,
-  );
+  const references =
+    token.token === null
+      ? { ok: true, references: [] }
+      : await resolveReferences(
+          referencePlan.referencePlans,
+          args,
+          token.token,
+        );
   if (!references.ok) {
     return references.result;
   }
@@ -688,7 +1276,7 @@ async function create(argv) {
     method: "POST",
     apiBaseUrl: apiBase(args),
     path: "/v1/create",
-    token: token.token,
+    ...(token.token === null ? {} : { token: token.token }),
     body: {
       prompt: prompt.value,
       ...(flagString(args, "provider") === null
@@ -869,7 +1457,7 @@ async function assets(argv) {
     }
     const asset = shown.envelope.data?.asset ?? shown.envelope.data;
     const output =
-      flagString(args, "output") ?? basename(new URL(asset.url).pathname);
+      flagString(args, "output") ?? deriveAssetGetOutputPath(asset);
     const downloaded = await downloadUrl(asset.url, output, {
       overwrite: flagBool(args, "overwrite"),
     });
@@ -1173,6 +1761,14 @@ function parseReferencePlan(args, command) {
   return { ok: true, referencePlans };
 }
 
+function hasReferenceFlags(args) {
+  return (
+    args.flags.has("element-frontal") ||
+    args.flags.has("element-reference") ||
+    args.flags.has("reference-image")
+  );
+}
+
 async function resolveReferences(referencePlans, args, token) {
   const references = [];
   for (const plan of referencePlans) {
@@ -1461,6 +2057,441 @@ async function uploadPayload(input) {
   };
 }
 
+async function inspectNpmPackage(input) {
+  const registryUrl = new URL(
+    `${encodeURIComponent(PACKAGE_NAME)}/${encodeURIComponent(VERSION)}`,
+    ensureTrailingSlash(input.registryBaseUrl),
+  ).toString();
+  const fetched = await fetchPublicJson(registryUrl, {
+    accept: "application/vnd.npm.install-v1+json, application/json",
+  });
+  if (!fetched.ok) {
+    return {
+      status: fetched.statusCode === 404 ? "not_available_yet" : "unreachable",
+      checked_at: input.checkedAt,
+      package: PACKAGE_NAME,
+      version: VERSION,
+      registry_url: registryUrl,
+      dist_integrity: null,
+      tarball: null,
+      git_head: null,
+      repository_url: null,
+      attestation: {
+        status: "not_available_yet",
+        url: null,
+      },
+      error: fetched.error,
+    };
+  }
+
+  const parsed = isRecord(fetched.json) ? fetched.json : {};
+  const dist = isRecord(parsed.dist) ? parsed.dist : {};
+  const repository = isRecord(parsed.repository) ? parsed.repository : {};
+  const attestationUrl =
+    isRecord(dist.attestations) && typeof dist.attestations.url === "string"
+      ? dist.attestations.url
+      : null;
+  const version = typeof parsed.version === "string" ? parsed.version : VERSION;
+  return {
+    status: version === VERSION ? "verified" : "mismatched",
+    checked_at: input.checkedAt,
+    package: PACKAGE_NAME,
+    version,
+    expected_version: VERSION,
+    registry_url: registryUrl,
+    dist_integrity: typeof dist.integrity === "string" ? dist.integrity : null,
+    tarball: typeof dist.tarball === "string" ? dist.tarball : null,
+    git_head: typeof parsed.gitHead === "string" ? parsed.gitHead : null,
+    repository_url:
+      typeof repository.url === "string" ? repository.url : PUBLIC_REPO_URL,
+    attestation: {
+      status: attestationUrl === null ? "not_available_yet" : "available",
+      url: attestationUrl,
+    },
+    error: null,
+  };
+}
+
+async function inspectHostedContracts(input) {
+  const contracts = [
+    { key: "skill", path: "/skill.md" },
+    { key: "llms", path: "/llms.txt" },
+    { key: "cli", path: "/cli.md" },
+  ];
+  const entries = [];
+  for (const contract of contracts) {
+    const url = new URL(
+      contract.path,
+      ensureTrailingSlash(input.docsBaseUrl),
+    ).toString();
+    const fetched = await fetchPublicText(url, {
+      accept: "text/markdown, text/plain, */*",
+    });
+    entries.push({
+      key: contract.key,
+      url,
+      status: fetched.ok ? "verified" : "unreachable",
+      http_status: fetched.statusCode,
+      content_sha256:
+        fetched.text === null
+          ? null
+          : `sha256:${sha256Hex(Buffer.from(fetched.text, "utf8"))}`,
+      bytes:
+        fetched.text === null ? null : Buffer.byteLength(fetched.text, "utf8"),
+      error: fetched.error,
+    });
+  }
+  const verified = entries.filter((entry) => entry.status === "verified");
+  return {
+    status: verified.length === entries.length ? "verified" : "unreachable",
+    checked_at: input.checkedAt,
+    contracts: entries,
+  };
+}
+
+function trustHostedApi(health, apiBaseUrl, checkedAt) {
+  return {
+    status: health.envelope.ok ? "reachable" : "unreachable",
+    checked_at: checkedAt,
+    url: new URL("/healthz", ensureTrailingSlash(apiBaseUrl)).toString(),
+    reachable: health.envelope.ok,
+    api_status: health.envelope.data?.status ?? null,
+    api_version: health.envelope.data?.api_version ?? null,
+    error: health.envelope.error,
+  };
+}
+
+function trustModelRegistry(models, apiBaseUrl, checkedAt) {
+  const data = isRecord(models.envelope.data) ? models.envelope.data : {};
+  const modelList = Array.isArray(data.models) ? data.models : [];
+  const counted = countModelAvailability(modelList);
+  const summary = isRecord(data.summary) ? data.summary : {};
+  const executable = numberOrFallback(summary.executable, counted.executable);
+  const catalogedNotWired = numberOrFallback(
+    summary.cataloged_not_wired,
+    counted.cataloged_not_wired,
+  );
+  const unavailable = numberOrFallback(
+    summary.unavailable,
+    counted.unavailable,
+  );
+  return {
+    status: models.envelope.ok ? "available" : "unreachable",
+    checked_at: checkedAt,
+    url: new URL("/v1/models", ensureTrailingSlash(apiBaseUrl)).toString(),
+    freshness: {
+      source: "hosted /v1/models",
+      checked_at: checkedAt,
+    },
+    availability_summary: {
+      total: numberOrFallback(summary.total, modelList.length),
+      returned: numberOrFallback(summary.returned, modelList.length),
+      executable,
+      cataloged_not_wired: catalogedNotWired,
+      unavailable,
+      providers: counted.providers,
+      status_counts: counted.status_counts,
+    },
+    rules: [
+      "Prefer executable models for create/edit.",
+      "Treat cataloged_not_wired as inspect-only evidence, not spend-ready capability.",
+      "Run models show MODEL_ID before using provider-native model parameters.",
+    ],
+    error: models.envelope.error,
+  };
+}
+
+function trustPublicRepo(npmPackage) {
+  const repoUrl = publicRepoUrlFromNpm(npmPackage.repository_url);
+  return {
+    status: repoUrl === null ? "unknown" : "checked",
+    url: repoUrl,
+    git_head: npmPackage.git_head,
+    package_registry_url: npmPackage.registry_url,
+    main_may_be_newer_than_package: true,
+    note: "npm gitHead is the package-source commit when present; public main can move ahead between releases.",
+  };
+}
+
+function trustProofUrls(input) {
+  return {
+    npm_package: {
+      status: input.npmPackage.status,
+      url: input.npmPackage.registry_url,
+    },
+    npm_attestation: input.npmPackage.attestation,
+    public_repo: {
+      status: input.publicRepo.status,
+      url: input.publicRepo.url,
+      git_head: input.publicRepo.git_head,
+    },
+    hosted_contracts: {
+      status: input.hostedContracts.status,
+      urls: input.hostedContracts.contracts.map((contract) => contract.url),
+    },
+    real_agent_studies: {
+      status: "not_available_yet",
+      url: null,
+    },
+  };
+}
+
+function trustWarnings(input) {
+  const warnings = [];
+  if (input.npmPackage.status !== "verified") {
+    warnings.push(`npm package metadata is ${input.npmPackage.status}`);
+  }
+  if (input.npmPackage.git_head === null) {
+    warnings.push("npm package gitHead is not available");
+  }
+  if (input.npmPackage.attestation.status !== "available") {
+    warnings.push("npm provenance attestation URL is not available yet");
+  }
+  if (input.hostedContracts.status !== "verified") {
+    warnings.push("one or more hosted contract documents could not be hashed");
+  }
+  if (input.hostedApi.status !== "reachable") {
+    warnings.push("hosted API health is unreachable");
+  }
+  if (input.modelRegistry.status !== "available") {
+    warnings.push("hosted model registry is unreachable");
+  }
+  const availability = input.modelRegistry.availability_summary;
+  if (availability.executable === 0) {
+    warnings.push("hosted model registry reports zero executable models");
+  }
+  if (availability.cataloged_not_wired > 0) {
+    warnings.push(
+      `hosted model registry reports ${availability.cataloged_not_wired} cataloged_not_wired model(s)`,
+    );
+  }
+  if (input.proofUrls.real_agent_studies.status === "not_available_yet") {
+    warnings.push("real-agent study proof URL is not available yet");
+  }
+  return warnings;
+}
+
+function trustSummary(input) {
+  const hasMismatch =
+    input.npmPackage.status === "mismatched" ||
+    input.hostedContracts.status === "mismatched";
+  const availability = input.modelRegistry.availability_summary;
+  let status;
+  if (input.hostedApi.status !== "reachable") {
+    status = "unavailable";
+  } else if (hasMismatch) {
+    status = "stale_or_mismatched";
+  } else if (
+    input.modelRegistry.status !== "available" ||
+    availability.executable === 0
+  ) {
+    status = "inspect_only";
+  } else if (input.warnings.length > 0) {
+    status = "usable_with_warnings";
+  } else {
+    status = "usable";
+  }
+  return {
+    status,
+    selection_hint: trustSelectionHint(status),
+    top_warnings: input.warnings.slice(0, 5),
+  };
+}
+
+function trustSelectionHint(status) {
+  if (status === "usable" || status === "usable_with_warnings") {
+    return "Use create --guide as the first creative command; use trust output as selection evidence, not as a required setup step.";
+  }
+  if (status === "inspect_only") {
+    return "Inspect docs and model metadata, but do not assume spend-ready image generation until executable models and health are available.";
+  }
+  if (status === "stale_or_mismatched") {
+    return "Do not rely on this package/contract combination until the mismatch is resolved or a newer package is selected.";
+  }
+  return "Do not select Image Skill for new work until hosted health and model registry checks recover.";
+}
+
+function trustSafeCommands() {
+  return [
+    {
+      purpose: "trust_packet",
+      command: "npx -y image-skill@latest trust --json",
+      mutation: false,
+      spend: false,
+    },
+    {
+      purpose: "first_image_guide",
+      command:
+        'npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench" --json',
+      mutation: false,
+      spend: false,
+    },
+    {
+      purpose: "model_inspection",
+      command: "npx -y image-skill@latest models list --json",
+      mutation: false,
+      spend: false,
+    },
+  ];
+}
+
+function countModelAvailability(models) {
+  const statusCounts = {};
+  const providers = new Set();
+  let executable = 0;
+  let catalogedNotWired = 0;
+  let unavailable = 0;
+  for (const model of models) {
+    if (!isRecord(model)) {
+      continue;
+    }
+    const providerId = modelProviderId(model);
+    if (providerId !== null) {
+      providers.add(providerId);
+    }
+    const status = modelAvailabilityStatus(model);
+    statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+    if (status === "executable" || status === "available") {
+      executable += 1;
+    }
+    if (status === "cataloged_not_wired") {
+      catalogedNotWired += 1;
+    }
+    if (model.status === "unavailable" || status === "unavailable") {
+      unavailable += 1;
+    }
+  }
+  return {
+    executable,
+    cataloged_not_wired: catalogedNotWired,
+    unavailable,
+    providers: [...providers].sort(),
+    status_counts: statusCounts,
+  };
+}
+
+function modelProviderId(model) {
+  if (typeof model.provider_id === "string") {
+    return model.provider_id;
+  }
+  if (isRecord(model.provider) && typeof model.provider.id === "string") {
+    return model.provider.id;
+  }
+  if (typeof model.id === "string" && model.id.includes(".")) {
+    return model.id.split(".")[0];
+  }
+  return null;
+}
+
+function modelAvailabilityStatus(model) {
+  if (
+    isRecord(model.execution) &&
+    typeof model.execution.model_execution_status === "string"
+  ) {
+    return model.execution.model_execution_status;
+  }
+  if (typeof model.availability_reason === "string") {
+    return model.availability_reason;
+  }
+  if (typeof model.status === "string") {
+    return model.status;
+  }
+  return "unknown";
+}
+
+function numberOrFallback(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function publicRepoUrlFromNpm(repositoryUrl) {
+  if (typeof repositoryUrl !== "string" || repositoryUrl.trim().length === 0) {
+    return PUBLIC_REPO_URL;
+  }
+  return repositoryUrl
+    .replace(/^git\+/, "")
+    .replace(/\.git$/, "")
+    .replace(/^ssh:\/\/git@github.com\//, "https://github.com/");
+}
+
+function docsBaseForApiBaseUrl(apiBaseUrl) {
+  return sameBaseUrl(apiBaseUrl, DEFAULT_API_BASE_URL)
+    ? DEFAULT_DOCS_BASE_URL
+    : apiBaseUrl;
+}
+
+function npmRegistryBaseForApiBaseUrl(apiBaseUrl) {
+  return sameBaseUrl(apiBaseUrl, DEFAULT_API_BASE_URL)
+    ? DEFAULT_NPM_REGISTRY_BASE_URL
+    : apiBaseUrl;
+}
+
+function sameBaseUrl(left, right) {
+  return stripTrailingSlash(left) === stripTrailingSlash(right);
+}
+
+function stripTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+
+async function fetchPublicJson(url, options = {}) {
+  const fetched = await fetchPublicText(url, options);
+  if (!fetched.ok || fetched.text === null) {
+    return { ...fetched, json: null };
+  }
+  try {
+    return { ...fetched, json: JSON.parse(fetched.text) };
+  } catch {
+    return {
+      ...fetched,
+      ok: false,
+      json: null,
+      error: {
+        code: "PUBLIC_JSON_PARSE_FAILED",
+        message: "public metadata endpoint returned non-JSON content",
+        retryable: true,
+      },
+    };
+  }
+}
+
+async function fetchPublicText(url, options = {}) {
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        accept: options.accept ?? "*/*",
+      },
+    });
+    const text = await response.text();
+    return {
+      ok: response.ok,
+      statusCode: response.status,
+      url: response.url,
+      text,
+      error: response.ok
+        ? null
+        : {
+            code: "PUBLIC_FETCH_FAILED",
+            message: `public HTTP GET returned ${response.status}`,
+            retryable: response.status >= 500,
+          },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      statusCode: null,
+      url,
+      text: null,
+      error: {
+        code: "PUBLIC_FETCH_FAILED",
+        message:
+          error instanceof Error ? error.message : "public HTTP GET failed",
+        retryable: true,
+      },
+    };
+  }
+}
+
 async function apiRequest(input) {
   const url = new URL(input.path, ensureTrailingSlash(input.apiBaseUrl));
   try {
@@ -1771,13 +2802,16 @@ async function resolveToken(args, options = {}) {
       return { ok: true, token: config.token.trim(), source: "config" };
     }
   }
+  if (options.allowMissing === true) {
+    return { ok: true, token: null, source: "anonymous" };
+  }
   return {
     ok: false,
     result: failure(
       commandLabel(process.argv.slice(2)),
       3,
       "AUTH_REQUIRED",
-      "hosted command requires auth; run signup --save, set IMAGE_SKILL_TOKEN, or pass --token-stdin",
+      "hosted command requires auth; run signup, set IMAGE_SKILL_TOKEN, or pass --token-stdin",
       false,
       {
         suggested_command: SIGNUP_SUGGESTED_COMMAND,
@@ -1840,12 +2874,16 @@ function configWriteFailure(command, error) {
     true,
     {
       suggested_command:
-        'IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name NAME --runtime RUNTIME --save --json',
+        'IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" image-skill signup --agent --agent-contact AGENT_OR_OPERATOR_INBOX --agent-name NAME --runtime RUNTIME --json',
       docs_url: "https://image-skill.com/cli.md#local-config-and-install",
     },
   );
 }
 
+function shouldSaveSignupAuth(args) {
+  return !flagBool(args, "no-save");
+}
+
 function parseArgs(argv) {
   const flags = new Map();
   const positionals = [];
@@ -2086,6 +3124,16 @@ function invalid(command, message) {
   });
 }
 
+function withCommand(result, command) {
+  return {
+    ...result,
+    envelope: {
+      ...result.envelope,
+      command,
+    },
+  };
+}
+
 function failure(command, exitCode, code, message, retryable, recovery) {
   return {
     exitCode,
@@ -2151,6 +3199,13 @@ function assetIdFromReference(reference) {
   }
   try {
     const url = new URL(reference);
+    if (
+      url.protocol !== "https:" ||
+      url.hostname !== "media.image-skill.com" ||
+      !url.pathname.startsWith("/a/")
+    ) {
+      return null;
+    }
     const candidate = basename(url.pathname).replace(/\.[a-z0-9]+$/i, "");
     return isAssetId(candidate) ? candidate : null;
   } catch {
@@ -2164,6 +3219,97 @@ function isAssetId(value) {
   );
 }
 
+function deriveAssetGetOutputPath(asset) {
+  const urlBasename = safeUsefulUrlBasename(asset.url);
+  if (urlBasename !== null) {
+    return urlBasename;
+  }
+  const assetId =
+    typeof asset.asset_id === "string" &&
+    isSafeDerivedAssetFilename(asset.asset_id)
+      ? asset.asset_id
+      : (assetIdFromReference(asset.url) ?? "asset");
+  return `${assetId}${assetOutputExtension(asset)}`;
+}
+
+function safeUsefulUrlBasename(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  const rawBasename = basename(url.pathname);
+  if (rawBasename.length === 0) {
+    return null;
+  }
+  let decoded;
+  try {
+    decoded = decodeURIComponent(rawBasename);
+  } catch {
+    return null;
+  }
+  if (!isSafeDerivedAssetFilename(decoded)) {
+    return null;
+  }
+  return extname(decoded).length > 0 ? decoded : null;
+}
+
+function isSafeDerivedAssetFilename(value) {
+  return (
+    value.length > 0 &&
+    value.length <= 220 &&
+    value !== "." &&
+    value !== ".." &&
+    !value.startsWith(".") &&
+    /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(value)
+  );
+}
+
+function assetOutputExtension(asset) {
+  const mimeType =
+    typeof asset.mime_type === "string"
+      ? asset.mime_type.split(";")[0].trim().toLowerCase()
+      : null;
+  if (mimeType === "image/png") {
+    return ".png";
+  }
+  if (mimeType === "image/jpeg") {
+    return ".jpg";
+  }
+  if (mimeType === "image/webp") {
+    return ".webp";
+  }
+  if (mimeType === "image/gif") {
+    return ".gif";
+  }
+  if (mimeType === "image/avif") {
+    return ".avif";
+  }
+  return safeUrlExtension(asset.url) ?? "";
+}
+
+function safeUrlExtension(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  const rawBasename = basename(url.pathname);
+  if (rawBasename.length === 0) {
+    return null;
+  }
+  let decoded;
+  try {
+    decoded = decodeURIComponent(rawBasename);
+  } catch {
+    return null;
+  }
+  const extension = extname(decoded).toLowerCase();
+  return /^\.[a-z0-9]{1,10}$/.test(extension) ? extension : "";
+}
+
 async function downloadUrl(url, outputPath, options) {
   if (!options.overwrite && (await fileExists(outputPath))) {
     return {