run402 4.9.0 → 4.10.0

package/cli.mjs

@@ -385,11 +385,23 @@ switch (cmd) {
   }
   default: {
     const { fail } = await import("./lib/sdk-errors.mjs");
+    // Did-you-mean candidates: manifest families ∪ the allowlisted skipped
+    // families — together these cover every case in this switch (the
+    // cli-conventions gate keeps them in lockstep), so no second list.
+    const { COMMAND_MANIFEST, SKIPPED_FAMILIES } = await import("./lib/command-manifest.mjs");
+    const { closestWord } = await import("./lib/argparse.mjs");
+    const families = new Set([
+      ...COMMAND_MANIFEST.map((entry) => entry.path[0]),
+      ...Object.keys(SKIPPED_FAMILIES),
+    ]);
+    const closest = typeof cmd === "string" ? closestWord(cmd, [...families]) : null;
     fail({
       code: "UNKNOWN_COMMAND",
-      message: `Unknown command: ${cmd}`,
+      message: closest
+        ? `Unknown command: ${cmd}. Did you mean ${closest}?`
+        : `Unknown command: ${cmd}`,
       hint: "Run `run402 --help` for the command list.",
-      details: { command: cmd },
+      details: { command: cmd, closest: closest ? [closest] : [] },
     });
   }
 }

package/lib/admin.mjs

@@ -1,6 +1,6 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv, resolveProjectSelector } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 admin — Platform-admin operations (v1.57+)
 
@@ -185,6 +185,6 @@ export async function run(sub, args) {
     case "archive":         await archive(args); break;
     case "reactivate":      await reactivate(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown admin subcommand: ${sub}`, hint: "Run `run402 admin --help` for usage.", details: { command: "admin", subcommand: sub } });
+      failUnknownSubcommand("admin", sub);
   }
 }

package/lib/agent.mjs

@@ -1,7 +1,7 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, validateWebhookUrl } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, validateWebhookUrl, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 agent — Manage agent identity
 
@@ -201,6 +201,6 @@ export async function run(sub, args) {
       await passkey(args);
       return;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown agent subcommand: ${sub}`, hint: "Run `run402 agent --help` for usage.", details: { command: "agent", subcommand: sub } });
+      failUnknownSubcommand("agent", sub);
   }
 }

package/lib/ai.mjs

@@ -1,7 +1,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, resolvePositionalProject } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, resolvePositionalProject, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 ai — AI translation and moderation tools
 
@@ -230,6 +230,6 @@ export async function run(sub, args) {
     case "moderate":  await moderate(args); break;
     case "usage":     await usage(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown ai subcommand: ${sub}`, hint: "Run `run402 ai --help` for usage.", details: { command: "ai", subcommand: sub } });
+      failUnknownSubcommand("ai", sub);
   }
 }

package/lib/allowance.mjs

@@ -1,7 +1,7 @@
 import { readAllowance, saveAllowance, allowanceFile } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 allowance — Manage your agent allowance
 
@@ -347,6 +347,6 @@ export async function run(sub, args) {
     case "checkout": await checkout(args); break;
     case "history":  await history(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown allowance subcommand: ${sub}`, hint: "Run `run402 allowance --help` for usage.", details: { command: "allowance", subcommand: sub } });
+      failUnknownSubcommand("allowance", sub);
   }
 }

package/lib/apps.mjs

@@ -1,7 +1,7 @@
 import { allowanceAuthHeaders, saveProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, resolveProjectSelector } from "./argparse.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -330,6 +330,6 @@ export async function run(sub, args) {
     case "update":   await update(args[0], args[1], args.slice(2)); break;
     case "delete":   await deleteVersion(args[0], args[1], args.slice(2)); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown apps subcommand: ${sub}`, hint: "Run `run402 apps --help` for usage.", details: { command: "apps", subcommand: sub } });
+      failUnknownSubcommand("apps", sub);
   }
 }

package/lib/archives.mjs

@@ -1,6 +1,6 @@
 import { inspectArchive, verifyArchive } from "#sdk/node";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 archives — Inspect and verify portable Run402 project archives
 
@@ -23,12 +23,7 @@ export async function run(sub, rawArgs = []) {
     case "inspect": return inspect(rawArgs);
     case "verify": return verify(rawArgs);
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown archives subcommand: ${sub}`,
-        hint: "Run `run402 archives --help` for usage.",
-        details: { command: "archives", subcommand: sub },
-      });
+      failUnknownSubcommand("archives", sub);
   }
 }
 

package/lib/argparse.mjs

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from "node:fs";
 import { fail } from "./sdk-errors.mjs";
 import { resolveProjectId } from "./config.mjs";
+import { COMMAND_MANIFEST } from "./command-manifest.mjs";
 
 export function normalizeArgv(argv = []) {
   const out = [];
@@ -368,11 +369,17 @@ export function resolveProjectSelector(args, opts = {}) {
   return resolvePositionalProject(list, opts);
 }
 
-function closestFlag(flag, candidates) {
+/**
+ * Reusable did-you-mean helper: the closest candidate within Levenshtein
+ * distance ≤ 3, or null when nothing is close enough. Used for flags
+ * (`closestFlag`), top-level commands (cli.mjs's dispatch default), and
+ * subcommands (`failUnknownSubcommand`).
+ */
+export function closestWord(word, candidates) {
   let best = null;
   let bestDistance = Number.POSITIVE_INFINITY;
   for (const candidate of candidates) {
-    const d = levenshtein(flag, candidate);
+    const d = levenshtein(word, candidate);
     if (d < bestDistance) {
       best = candidate;
       bestDistance = d;
@@ -382,6 +389,60 @@ function closestFlag(flag, candidates) {
   return bestDistance <= 3 ? best : null;
 }
 
+function closestFlag(flag, candidates) {
+  return closestWord(flag, candidates);
+}
+
+/**
+ * Known subcommands of a command family, derived from COMMAND_MANIFEST
+ * (never hand-maintained). `family` may be multi-word for nested groups
+ * (e.g. "cloud archives", "email webhooks").
+ */
+export function knownSubcommands(family) {
+  const familyWords = String(family).split(" ").filter(Boolean);
+  const subs = new Set();
+  for (const entry of COMMAND_MANIFEST) {
+    if (entry.path.length <= familyWords.length) continue;
+    if (!familyWords.every((word, i) => entry.path[i] === word)) continue;
+    subs.add(entry.path[familyWords.length]);
+  }
+  return [...subs].sort();
+}
+
+/**
+ * Shared unknown-subcommand failure: derives the family's known
+ * subcommands from COMMAND_MANIFEST and adds a `Did you mean <sub>?`
+ * suggestion plus `details.closest` / `details.known_subcommands`.
+ *
+ * Options:
+ *   hint               override the default `Run \`run402 <family> --help\`…` line
+ *   label              display label when it differs from the manifest family
+ *                      (e.g. the email-webhooks group is dispatched as
+ *                      `run402 webhooks …` but lives at ["email","webhooks",…])
+ *   extraSubcommands   candidates handled by the module but absent from the
+ *                      manifest (nested group heads, aliases)
+ *   next_actions       forwarded to the error envelope
+ */
+export function failUnknownSubcommand(family, sub, { hint, label, extraSubcommands = [], next_actions } = {}) {
+  const displayLabel = label ?? family;
+  const known = [...new Set([...knownSubcommands(family), ...extraSubcommands])].sort();
+  const closest = typeof sub === "string" ? closestWord(sub, known) : null;
+  fail({
+    code: "UNKNOWN_SUBCOMMAND",
+    message: closest
+      ? `Unknown ${displayLabel} subcommand: ${sub}. Did you mean ${closest}?`
+      : `Unknown ${displayLabel} subcommand: ${sub}`,
+    hint: hint ?? `Run \`run402 ${displayLabel} --help\` for usage.`,
+    details: {
+      command: displayLabel,
+      subcommand: sub,
+      closest: closest ? [closest] : [],
+      known_subcommands: known,
+    },
+    ...(next_actions ? { next_actions } : {}),
+  });
+}
+
 function levenshtein(a, b) {
   const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
   const curr = Array.from({ length: b.length + 1 }, () => 0);

package/lib/asset-wire.mjs

@@ -0,0 +1,59 @@
+/**
+ * toWireAssetRef — project an SDK AssetRef (which carries camelCase TS
+ * conveniences like `cdnUrl`, `immutableUrl`, `contentSha256`, `size`) onto
+ * the CANONICAL gateway wire shape: snake_case keys only, no duplicate
+ * values under two casings.
+ *
+ * Canonical key set (gateway asset envelope):
+ *   key, sha256, size_bytes, content_type, visibility, immutable,
+ *   url, immutable_url, cdn_url, cdn_immutable_url, sri, etag,
+ *   content_digest, + the v1.49/v1.50/v1.54 image fields
+ *   (width_px, height_px, blurhash, variant_spec_version, display_url,
+ *   display_immutable_url, variants, metadata, image_format, image_info,
+ *   image_exif, image_exif_policy, blurhash_data_url, asset_schema).
+ *
+ * Unknown snake_case keys from newer gateways are preserved as-is; every
+ * camelCase key (the documented SDK aliases and any future ones) is dropped,
+ * with the aliases mapped back to their canonical snake twin when the snake
+ * form is missing from the input.
+ *
+ * The SDK keeps its camelCase conveniences for typed consumers (e.g.
+ * @run402/astro reads `cdnUrl`); this projector is the CLI/MCP output
+ * boundary only.
+ */
+
+// SDK-only convenience keys that must never appear in wire output. `size`
+// and `cdn` are lowercase but still SDK-only: `size` duplicates
+// `size_bytes`, `cdn` is the SDK's invalidation envelope (camelCase inner
+// keys, locally synthesized).
+const SDK_ONLY_KEYS = new Set(["size", "cdn"]);
+
+export function toWireAssetRef(ref) {
+  if (!ref || typeof ref !== "object" || Array.isArray(ref)) return ref;
+  const out = {};
+  for (const [key, value] of Object.entries(ref)) {
+    if (typeof value === "function") continue; // tag emitters (scriptTag, …)
+    if (SDK_ONLY_KEYS.has(key)) continue;
+    if (/[A-Z]/.test(key)) continue; // camelCase SDK aliases/conveniences
+    out[key] = value;
+  }
+  // Canonical fields whose only SDK source is a camelCase convenience.
+  if (out.content_type === undefined && typeof ref.contentType === "string") {
+    out.content_type = ref.contentType;
+  }
+  // SDK naming vs wire naming: `cdnUrl` is the IMMUTABLE cdn url,
+  // `cdnMutableUrl` the mutable one.
+  if (out.cdn_url === undefined && ref.cdnMutableUrl !== undefined) {
+    out.cdn_url = ref.cdnMutableUrl;
+  }
+  if (out.cdn_immutable_url === undefined && ref.cdnUrl !== undefined) {
+    out.cdn_immutable_url = ref.cdnUrl;
+  }
+  if (out.content_digest === undefined && ref.contentDigest !== undefined) {
+    out.content_digest = ref.contentDigest;
+  }
+  if (out.immutable === undefined) {
+    out.immutable = ref.immutable_url !== null && ref.immutable_url !== undefined;
+  }
+  return out;
+}

package/lib/assets.mjs

@@ -31,7 +31,8 @@ import { pipeline } from "node:stream/promises";
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, failUnknownSubcommand } from "./argparse.mjs";
+import { toWireAssetRef } from "./asset-wire.mjs";
 
 const HELP = `run402 blob — Direct-to-S3 blob storage
 
@@ -458,8 +459,11 @@ async function putOne(projectId, filePath, opts) {
     ...(opts.metadata ? { metadata: opts.metadata } : {}),
     ...(opts.exifPolicy ? { exifPolicy: opts.exifPolicy } : {}),
   });
-  log(opts, { event: "done", ...result });
-  return result;
+  // Canonical wire shape only on stdout: snake_case keys, no camelCase
+  // duplicates (the SDK's AssetRef carries both; toWireAssetRef projects).
+  const wire = toWireAssetRef(result);
+  log(opts, { event: "done", ...wire });
+  return wire;
 }
 
 function computeDestKey(filePath, keyOpt) {
@@ -681,6 +685,6 @@ export async function run(sub, args) {
     case "sign":     await sign(defaultProject, args); break;
     case "diagnose": await diagnose(defaultProject, args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown assets subcommand: ${sub}`, hint: "Run `run402 assets --help` for usage.", details: { command: "assets", subcommand: sub } });
+      failUnknownSubcommand("assets", sub);
   }
 }

package/lib/auth.mjs

@@ -1,7 +1,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 auth — Manage project user authentication
 
@@ -757,6 +757,6 @@ export async function run(sub, args) {
     case "providers": await providers(args); break;
     case "scaffold-roles": scaffoldRoles(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown auth subcommand: ${sub}`, hint: "Run `run402 auth --help` for usage.", details: { command: "auth", subcommand: sub } });
+      failUnknownSubcommand("auth", sub);
   }
 }

package/lib/billing.mjs

@@ -1,6 +1,6 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 billing — Email organizations and org checkouts
 
@@ -359,6 +359,6 @@ export async function run(sub, args) {
     case "balance": await balance(args); break;
     case "history": await history(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown billing subcommand: ${sub}`, hint: "Run `run402 billing --help` for usage.", details: { command: "billing", subcommand: sub } });
+      failUnknownSubcommand("billing", sub);
   }
 }

package/lib/branches.mjs

@@ -9,6 +9,7 @@ import {
   parseIntegerFlag,
   positionalArgs,
   resolveProjectSelector,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
 
 const HELP = `run402 branches — Contained project data branches
@@ -41,12 +42,7 @@ export async function run(sub, args = []) {
     case "renew": return renew(rest);
     case "delete": return deleteBranch(rest);
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown branches subcommand: ${sub}`,
-        hint: "Run `run402 branches --help` for usage.",
-        details: { command: "branches", subcommand: sub },
-      });
+      failUnknownSubcommand("branches", sub);
   }
 }
 

package/lib/cache.mjs

@@ -18,7 +18,7 @@
 
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
 import { editRequestAction } from "./next-actions.mjs";
 
 // Locally-defined helpers — argparse.mjs's normalized form is a flat
@@ -99,11 +99,7 @@ export async function run(sub, args) {
       await invalidate(args);
       break;
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown cache subcommand: ${sub}`,
-        hint: "Run `run402 cache --help` for usage.",
-        details: { command: "cache", subcommand: sub },
+      failUnknownSubcommand("cache", sub, {
         next_actions: [editRequestAction("run402 cache --help", "Choose a supported cache subcommand.")],
       });
   }

package/lib/cdn.mjs

@@ -16,7 +16,7 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 cdn — CloudFront CDN diagnostics for public blob URLs
 
@@ -135,6 +135,6 @@ export async function run(sub, args) {
       await waitFresh(defaultProject, args);
       break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown cdn subcommand: ${sub}`, hint: "Run `run402 cdn --help` for usage.", details: { command: "cdn", subcommand: sub } });
+      failUnknownSubcommand("cdn", sub);
   }
 }

package/lib/ci.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { failUnknownSubcommand } from "./argparse.mjs";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -459,6 +460,6 @@ export async function run(sub, args) {
     case "revoke": await revoke(args); break;
     case "set-asset-scopes": await setAssetScopes(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown ci subcommand: ${sub}`, hint: "Run `run402 ci --help` for usage.", details: { command: "ci", subcommand: sub } });
+      failUnknownSubcommand("ci", sub);
   }
 }

package/lib/cloud.mjs

@@ -3,7 +3,7 @@ import { dirname, resolve } from "node:path";
 
 import { getSdk } from "./sdk.mjs";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
-import { assertAllowedValue, assertKnownFlags, flagValue, hasHelp, normalizeArgv, parseIntegerFlag, positionalArgs, resolveProjectSelector } from "./argparse.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, hasHelp, normalizeArgv, parseIntegerFlag, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 cloud — Run402 Cloud portability commands
 
@@ -60,11 +60,7 @@ export async function run(sub, args = []) {
     return;
   }
   if (sub !== "archives") {
-    fail({
-      code: "UNKNOWN_SUBCOMMAND",
-      message: `Unknown cloud subcommand: ${sub}`,
-      hint: "Run `run402 cloud --help` for usage.",
-      details: { command: "cloud", subcommand: sub },
+    failUnknownSubcommand("cloud", sub, {
       next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
     });
   }
@@ -73,11 +69,7 @@ export async function run(sub, args = []) {
   if (action === "create") return create(rest);
   if (action === "download") return download(rest);
   if (action === "status") return status(rest);
-  fail({
-    code: "UNKNOWN_SUBCOMMAND",
-    message: `Unknown cloud archives subcommand: ${action}`,
-    hint: "Run `run402 cloud archives --help` for usage.",
-    details: { command: "cloud archives", subcommand: action },
+  failUnknownSubcommand("cloud archives", action, {
     next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
   });
 }

package/lib/contracts.mjs

@@ -8,6 +8,7 @@ import {
   positionalArgs,
   resolveProjectSelector,
   validateEvmAddress,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
 
 const HELP = `run402 contracts — KMS-backed Ethereum signers for smart-contract calls
@@ -520,6 +521,6 @@ export async function run(sub, args) {
     case "drain":            { const { projectId, rest } = select(); await drain(projectId, rest[0], rest.slice(1)); break; }
     case "delete":           { const { projectId, rest } = select(); await deleteSigner(projectId, rest[0], rest.slice(1)); break; }
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown contracts subcommand: ${sub}`, hint: "Run `run402 contracts --help` for usage.", details: { command: "contracts", subcommand: sub } });
+      failUnknownSubcommand("contracts", sub);
   }
 }

package/lib/core.mjs

@@ -1,6 +1,6 @@
 import { importArchiveToCore } from "#sdk/node";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
-import { assertKnownFlags, flagValue, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, hasHelp, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 core — Local Run402 Core commands
 
@@ -29,21 +29,11 @@ export async function run(sub, args = []) {
     return;
   }
   if (sub !== "projects") {
-    fail({
-      code: "UNKNOWN_SUBCOMMAND",
-      message: `Unknown core subcommand: ${sub}`,
-      hint: "Run `run402 core --help` for usage.",
-      details: { command: "core", subcommand: sub },
-    });
+    failUnknownSubcommand("core", sub);
   }
   const action = args[0];
   if (action === "import" || action === "apply") return importProject(args.slice(1));
-  fail({
-    code: "UNKNOWN_SUBCOMMAND",
-    message: `Unknown core projects subcommand: ${action}`,
-    hint: "Run `run402 core projects --help` for usage.",
-    details: { command: "core projects", subcommand: action },
-  });
+  failUnknownSubcommand("core projects", action, { extraSubcommands: ["apply"] });
 }
 
 async function importProject(rawArgs) {

package/lib/credentials.mjs

@@ -8,7 +8,7 @@ import {
   removeProject,
   saveProject,
 } from "./config.mjs";
-import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 import { fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 credentials — Manage local credential material
@@ -245,12 +245,7 @@ async function runProjectKeys(sub, args) {
     case "export": await exportKey(args); break;
     case "remove": await remove(args); break;
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown credentials project-keys subcommand: ${sub}`,
-        hint: "Run `run402 credentials project-keys --help` for usage.",
-        details: { command: "credentials project-keys", subcommand: sub },
-      });
+      failUnknownSubcommand("credentials project-keys", sub);
   }
 }
 
@@ -264,10 +259,5 @@ export async function run(sub, args = []) {
     await runProjectKeys(projectKeySub, rest);
     return;
   }
-  fail({
-    code: "UNKNOWN_SUBCOMMAND",
-    message: `Unknown credentials subcommand: ${sub}`,
-    hint: "Run `run402 credentials --help` for usage.",
-    details: { command: "credentials", subcommand: sub },
-  });
+  failUnknownSubcommand("credentials", sub);
 }

package/lib/deploy.mjs

@@ -1,4 +1,4 @@
-import { fail } from "./sdk-errors.mjs";
+import { failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 deploy — Unified deploy operations
 
@@ -65,11 +65,8 @@ export async function run(args) {
       return;
     }
     default:
-      fail({
-        code: "BAD_USAGE",
-        message: `Unknown deploy subcommand: ${sub}`,
+      failUnknownSubcommand("deploy", sub, {
         hint: "Use `run402 deploy apply --manifest <file>` for deployments.",
-        details: { subcommand: sub },
       });
   }
 }

package/lib/doctor.mjs

@@ -63,6 +63,27 @@ function redactAllowanceForDiagnostics(allowance) {
   return safe;
 }
 
+/**
+ * Compose a check-failure message context-first.
+ *
+ * The SDK kernel composes thrown messages as `<envelope message> while
+ * <context>`, which reads as two jammed fragments when the envelope message
+ * ends with a period ("…header. while checking tier status"). Strip the
+ * SDK's trailing ` while <context>` segment (using the error's own
+ * `context` field) and lead with the check label instead.
+ */
+function describeCheckFailure(label, err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  const context = typeof err?.context === "string" && err.context.length > 0 ? err.context : null;
+  let reason = raw;
+  if (context) {
+    const marker = ` while ${context}`;
+    const idx = raw.indexOf(marker);
+    if (idx !== -1) reason = (raw.slice(0, idx) + raw.slice(idx + marker.length)).trim();
+  }
+  return `${label} failed: ${reason}`;
+}
+
 export async function run(sub, args = []) {
   const all = [sub, ...args].filter(Boolean);
   if (all.includes("--help") || all.includes("-h")) {
@@ -111,9 +132,11 @@ export async function run(sub, args = []) {
   }
 
   // 2. Allowance.
+  let allowanceConfigured = false;
   try {
     const allowance = readAllowance();
     if (allowance) {
+      allowanceConfigured = true;
       checks.push({
         name: "allowance",
         status: "ok",
@@ -152,8 +175,13 @@ export async function run(sub, args = []) {
       name: "projects",
       status: "ok",
       value: { project_count: projectCount },
+      // State-aware parenthetical: only claim the wallet is set up when the
+      // allowance check above actually passed; pre-init installs are pointed
+      // at `run402 init` first.
       ...(projectCount === 0 && {
-        hint: "No projects yet — run 'run402 projects provision' to create one (wallet is already set up).",
+        hint: allowanceConfigured
+          ? "No projects yet — run 'run402 projects provision' to create one (wallet is already set up)."
+          : "No projects yet — run 'run402 init' to set up the wallet first, then 'run402 projects provision'.",
       }),
     });
   } catch (err) {
@@ -224,7 +252,7 @@ export async function run(sub, args = []) {
     checks.push({
       name: "tier",
       status: "error",
-      message: err instanceof Error ? err.message : String(err),
+      message: describeCheckFailure("tier status check", err),
     });
   }
 
@@ -324,13 +352,13 @@ export async function run(sub, args = []) {
     checks.push({
       name: "operator_health",
       status: "skipped",
-      message: err instanceof Error ? err.message : String(err),
+      message: describeCheckFailure("operator status check", err),
       ...(verbose && { hint: "GET /agent/v1/operator/status not reachable; requires v1.55+ gateway." }),
     });
     checks.push({
       name: "runtime_staleness",
       status: "skipped",
-      message: err instanceof Error ? err.message : String(err),
+      message: describeCheckFailure("operator status check", err),
     });
   }