run402 4.8.0 → 4.10.0

package/cli.mjs

@@ -79,15 +79,15 @@ Examples:
   run402 allowance fund
   run402 deploy apply --manifest app.json
   run402 apply --manifest app.json --rehearse --json
-  run402 snapshots list prj_...
-  run402 branches create prj_... --ttl-days 7 --json
-  run402 cloud archives create prj_... --wait --output ./project.r402ar --json
+  run402 snapshots list --project prj_...
+  run402 branches create --project prj_... --ttl-days 7 --json
+  run402 cloud archives create --project prj_... --wait --output ./project.r402ar --json
   run402 core projects import ./project.r402ar --name imported-project --env-file ./required.env --json
   run402 jobs submit --file job.json
   run402 projects list
-  run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
-  run402 functions deploy <project_id> my-fn --file handler.ts
-  run402 secrets set <project_id> API_KEY sk-1234
+  run402 projects sql "SELECT * FROM users LIMIT 5" --project <project_id>
+  run402 functions deploy my-fn --file handler.ts --project <project_id>
+  run402 secrets set API_KEY --value sk-1234 --project <project_id>
   run402 image generate "a startup mascot, pixel art" --output logo.png
 
 Getting started:
@@ -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 } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 admin — Platform-admin operations (v1.57+)
 
@@ -17,12 +17,12 @@ Subcommands:
                                          (\`reactivated: true\` in the response).
                                          Replaces the v1.56 per-project pin.
 
-  archive <project_id> [--reason "..."]  Moderate-archive a single project. Sets
+  archive [--project <id>] [--reason "..."]  Moderate-archive a single project. Sets
                                          projects.archived_at = NOW(). Independent
                                          of organization lifecycle; the rest of the
                                          organization's projects keep serving.
 
-  reactivate <project_id>                Un-archive a project (flips archived_at
+  reactivate [--project <id>]            Un-archive a project (flips archived_at
                                          back to NULL). In v1.57 this no longer
                                          touches organization-level lifecycle — to
                                          reactivate a grace-state account, use
@@ -65,6 +65,9 @@ Examples:
   archive: `run402 admin archive — Moderate-archive a single project
 
 Usage:
+  run402 admin archive [--project <id>] [--reason "..."]
+
+Legacy (still supported):
   run402 admin archive <project_id> [--reason "..."]
 
 Options:
@@ -84,6 +87,9 @@ Examples:
   reactivate: `run402 admin reactivate — Un-archive a project
 
 Usage:
+  run402 admin reactivate [--project <id>]
+
+Legacy (still supported):
   run402 admin reactivate <project_id>
 
 Notes:
@@ -100,8 +106,8 @@ Examples:
 
 const FLAGS_BY_SUB = {
   "lease-perpetual": { known: ["--enable", "--disable"], values: [] },
-  archive: { known: ["--reason"], values: ["--reason"] },
-  reactivate: { known: [], values: [] },
+  archive: { known: ["--project", "--reason"], values: ["--project", "--reason"] },
+  reactivate: { known: ["--project"], values: ["--project"] },
 };
 
 function validateFlags(sub, args) {
@@ -137,18 +143,12 @@ async function leasePerpetual(args) {
 }
 
 async function archive(args) {
-  const projectId = args.find((a) => typeof a === "string" && !a.startsWith("--"));
-  if (!projectId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <project_id>.",
-      hint: "run402 admin archive <project_id> [--reason \"...\"]",
-    });
-  }
+  // Canonical: --project <id>; legacy leading prj_... positional kept.
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAGS_BY_SUB.archive.values });
   let reason;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--reason" && args[i + 1] !== undefined) {
-      reason = args[++i];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--reason" && rest[i + 1] !== undefined) {
+      reason = rest[++i];
     }
   }
   try {
@@ -160,14 +160,7 @@ async function archive(args) {
 }
 
 async function reactivate(args) {
-  const projectId = args.find((a) => typeof a === "string" && !a.startsWith("--"));
-  if (!projectId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <project_id>.",
-      hint: "run402 admin reactivate <project_id>",
-    });
-  }
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAGS_BY_SUB.reactivate.values });
   try {
     const data = await getSdk().admin.reactivateProject(projectId);
     console.log(JSON.stringify(data, null, 2));
@@ -192,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 } from "./argparse.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -10,15 +10,20 @@ Usage:
 
 Subcommands:
   browse  [--tag <tag>]                   Browse public apps
-  fork    <version_id> <name> [--subdomain <name>]
+  fork    <version_id> --name <name> [--subdomain <name>]
                                            Fork a published app into your own project
-  publish <id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
+  publish [--project <id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
                                            Publish a project as an app
-  versions <id>                            List published versions of a project
+  versions [--project <id>]                List published versions of a project
   inspect <version_id>                     Inspect a published app version
-  update  <project_id> <version_id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
+  update  <version_id> [--project <id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
                                            Update a published version
-  delete  <project_id> <version_id>        Delete a published version
+  delete  <version_id> [--project <id>]    Delete a published version
+
+Legacy (still supported): the old positional forms keep working, e.g.
+  run402 apps fork <version_id> <name>
+  run402 apps publish <project_id> / versions <project_id>
+  run402 apps update <project_id> <version_id> / delete <project_id> <version_id>
 
 Examples:
   run402 apps browse
@@ -48,13 +53,16 @@ Examples:
   fork: `run402 apps fork — Fork a published app into your own project
 
 Usage:
+  run402 apps fork <version_id> --name <name> [options]
+
+Legacy (still supported):
   run402 apps fork <version_id> <name> [options]
 
 Arguments:
   <version_id>        Published version ID (e.g. ver_abc123)
-  <name>              Name for the forked project
 
 Options:
+  --name <name>       Name for the forked project (alternative to the legacy positional)
   --subdomain <name>  Claim a subdomain for the forked project
 
 Examples:
@@ -64,10 +72,13 @@ Examples:
   publish: `run402 apps publish — Publish a project as an app
 
 Usage:
-  run402 apps publish <id> [options]
+  run402 apps publish [--project <id>] [options]
 
-Arguments:
-  <id>                Project ID to publish
+Legacy (still supported):
+  run402 apps publish <project_id> [options]
+
+Options (project):
+  --project <id>      Project ID to publish (defaults to the active project)
 
 Options:
   --description <d>   Human-readable description of the app
@@ -82,10 +93,12 @@ Examples:
   update: `run402 apps update — Update a published version's metadata
 
 Usage:
+  run402 apps update <version_id> [--project <id>] [options]
+
+Legacy (still supported):
   run402 apps update <project_id> <version_id> [options]
 
 Arguments:
-  <project_id>        Project ID that owns the version
   <version_id>        Published version ID to update
 
 Options:
@@ -114,10 +127,10 @@ Examples:
   versions: `run402 apps versions — List published versions of a project
 
 Usage:
-  run402 apps versions <id>
+  run402 apps versions [--project <id>]
 
-Arguments:
-  <id>                Project ID (e.g. prj_abc123)
+Legacy (still supported):
+  run402 apps versions <project_id>
 
 Examples:
   run402 apps versions prj_abc123
@@ -125,10 +138,12 @@ Examples:
   delete: `run402 apps delete — Delete a published version
 
 Usage:
+  run402 apps delete <version_id> [--project <id>]
+
+Legacy (still supported):
   run402 apps delete <project_id> <version_id>
 
 Arguments:
-  <project_id>        Project ID that owns the version
   <version_id>        Published version ID to delete
 
 Examples:
@@ -158,14 +173,16 @@ async function browse(args) {
 
 async function fork(versionId, name, args) {
   const parsedArgs = normalizeArgv([versionId, name, ...args].filter((arg) => arg !== undefined));
-  const valueFlags = ["--subdomain"];
+  const valueFlags = ["--subdomain", "--name"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const nameFlag = flagValue(parsedArgs, "--name");
+  const expected = nameFlag ? 1 : 2;
   const positionals = positionalArgs(parsedArgs, valueFlags);
-  if (positionals.length < 2) {
-    fail({ code: "BAD_USAGE", message: "Missing <version_id> and/or <name>." });
+  if (positionals.length < expected) {
+    fail({ code: "BAD_USAGE", message: nameFlag ? "Missing <version_id>." : "Missing <version_id> and/or <name>." });
   }
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[2]}` });
+  if (positionals.length > expected) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[expected]}` });
   }
   const opts = { subdomain: flagValue(parsedArgs, "--subdomain") ?? undefined };
   // Preserve the aggressive early exit when no allowance is configured.
@@ -174,7 +191,7 @@ async function fork(versionId, name, args) {
   try {
     const data = await getSdk().apps.fork({
       versionId: positionals[0],
-      name: positionals[1],
+      name: nameFlag ?? positionals[1],
       subdomain: opts.subdomain,
     });
 
@@ -195,14 +212,12 @@ async function fork(versionId, name, args) {
 
 async function publish(projectId, args) {
   const parsedArgs = normalizeArgv([projectId, ...args].filter((arg) => arg !== undefined));
-  const valueFlags = ["--description", "--tags", "--visibility"];
+  const valueFlags = ["--project", "--description", "--tags", "--visibility"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--fork-allowed", "--help", "-h"], valueFlags);
-  const positionals = positionalArgs(parsedArgs, valueFlags);
-  if (positionals.length < 1) {
-    fail({ code: "BAD_USAGE", message: "Missing <id>." });
-  }
-  if (positionals.length > 1) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps publish: ${positionals[1]}` });
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags });
+  const positionals = positionalArgs(rest, valueFlags);
+  if (positionals.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps publish: ${positionals[0]}` });
   }
   const opts = { description: undefined, tags: undefined, visibility: undefined, forkAllowed: undefined };
   opts.description = flagValue(parsedArgs, "--description") ?? undefined;
@@ -211,7 +226,7 @@ async function publish(projectId, args) {
   if (opts.visibility) assertAllowedValue(opts.visibility, ["public", "unlisted", "private"], "--visibility");
   if (parsedArgs.includes("--fork-allowed")) opts.forkAllowed = true;
   try {
-    const data = await getSdk().apps.publish(positionals[0], {
+    const data = await getSdk().apps.publish(resolvedProject, {
       description: opts.description,
       tags: opts.tags,
       visibility: opts.visibility,
@@ -225,13 +240,14 @@ async function publish(projectId, args) {
 
 async function versions(projectId, args = []) {
   const parsedArgs = normalizeArgv([projectId, ...args].filter((arg) => arg !== undefined));
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
-  if (positionals.length !== 1) {
-    fail({ code: "BAD_USAGE", message: positionals.length === 0 ? "Missing <id>." : `Unexpected argument for apps versions: ${positionals[1]}` });
+  assertKnownFlags(parsedArgs, ["--project", "--help", "-h"], ["--project"]);
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags: ["--project"] });
+  const positionals = positionalArgs(rest, ["--project"]);
+  if (positionals.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps versions: ${positionals[0]}` });
   }
   try {
-    const data = await getSdk().apps.listVersions(positionals[0]);
+    const data = await getSdk().apps.listVersions(resolvedProject);
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -255,14 +271,15 @@ async function inspect(versionId, args = []) {
 
 async function update(projectId, versionId, args) {
   const parsedArgs = normalizeArgv([projectId, versionId, ...args].filter((arg) => arg !== undefined));
-  const valueFlags = ["--description", "--tags", "--visibility"];
+  const valueFlags = ["--project", "--description", "--tags", "--visibility"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--fork-allowed", "--no-fork", "--help", "-h"], valueFlags);
-  const positionals = positionalArgs(parsedArgs, valueFlags);
-  if (positionals.length < 2) {
-    fail({ code: "BAD_USAGE", message: "Missing <project_id> and/or <version_id>." });
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags });
+  const positionals = positionalArgs(rest, valueFlags);
+  if (positionals.length < 1) {
+    fail({ code: "BAD_USAGE", message: "Missing <version_id>." });
   }
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps update: ${positionals[2]}` });
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps update: ${positionals[1]}` });
   }
   if (parsedArgs.includes("--fork-allowed") && parsedArgs.includes("--no-fork")) {
     fail({ code: "BAD_USAGE", message: "Provide either --fork-allowed or --no-fork, not both." });
@@ -275,8 +292,8 @@ async function update(projectId, versionId, args) {
   if (parsedArgs.includes("--fork-allowed")) opts.fork_allowed = true;
   if (parsedArgs.includes("--no-fork")) opts.fork_allowed = false;
   try {
-    await getSdk().apps.updateVersion(positionals[0], positionals[1], opts);
-    console.log(JSON.stringify({ project_id: positionals[0], version_id: positionals[1], updated: true }));
+    await getSdk().apps.updateVersion(resolvedProject, positionals[0], opts);
+    console.log(JSON.stringify({ project_id: resolvedProject, version_id: positionals[0], updated: true }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -284,17 +301,18 @@ async function update(projectId, versionId, args) {
 
 async function deleteVersion(projectId, versionId, args = []) {
   const parsedArgs = normalizeArgv([projectId, versionId, ...args].filter((arg) => arg !== undefined));
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
-  if (positionals.length < 2) {
-    fail({ code: "BAD_USAGE", message: "Missing <project_id> and/or <version_id>." });
+  assertKnownFlags(parsedArgs, ["--project", "--help", "-h"], ["--project"]);
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags: ["--project"] });
+  const positionals = positionalArgs(rest, ["--project"]);
+  if (positionals.length < 1) {
+    fail({ code: "BAD_USAGE", message: "Missing <version_id>." });
   }
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps delete: ${positionals[2]}` });
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps delete: ${positionals[1]}` });
   }
   try {
-    await getSdk().apps.deleteVersion(positionals[0], positionals[1]);
-    console.log(JSON.stringify({ project_id: positionals[0], version_id: positionals[1], deleted: true }));
+    await getSdk().apps.deleteVersion(resolvedProject, positionals[0]);
+    console.log(JSON.stringify({ project_id: resolvedProject, version_id: positionals[0], deleted: true }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -312,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 = [];
@@ -19,8 +20,14 @@ export function hasHelp(args = []) {
   return args.includes("--help") || args.includes("-h");
 }
 
+// CLI-wide convention: every command accepts `--json`. Where stdout is already
+// JSON (the vast majority of commands) it is a no-op; commands with a human
+// default switch on it explicitly. Baking it into the baseline known set here
+// makes the convention self-maintaining for future commands.
+const ALWAYS_KNOWN_FLAGS = ["--json"];
+
 export function assertKnownFlags(args = [], knownFlags = [], flagsWithValues = []) {
-  const known = new Set(knownFlags);
+  const known = new Set([...knownFlags, ...ALWAYS_KNOWN_FLAGS]);
   const valueFlags = new Set(flagsWithValues);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -301,11 +308,78 @@ export function resolvePositionalProject(args, opts = {}) {
   return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
 }
 
-function closestFlag(flag, candidates) {
+// Resolve the project id for a project-scoped command from BOTH accepted
+// forms — the canonical `--project <id>` flag and the legacy leading
+// positional `prj_...` — with active-project fallback (CLI-wide convention).
+//
+// Precedence:
+//   1. explicit `--project <id>` (canonical)
+//   2. a leading positional starting with "prj_" (legacy compat, no warning)
+//   3. the active project (`resolveProjectId(null)`)
+//
+// If BOTH a `--project` flag and a leading `prj_` positional are present and
+// they DIFFER, fail with BAD_USAGE ("Conflicting project ids"). If they agree,
+// the duplicate positional is consumed silently.
+//
+// Returns { projectId, rest } where `rest` is args with the project selector
+// tokens (the flag+value pair and/or the leading positional) removed.
+//
+// Options (in addition to every `resolvePositionalProject` option, which this
+// helper delegates to for the no-flag path):
+//   requireRestPositional: only treat a leading `prj_` positional as the
+//     project selector when at least one more bare positional follows (counted
+//     with opts.valueFlags). Needed by commands whose OWN attribute is itself a
+//     project id (e.g. `branches renew <branch-project-id>`).
+export function resolveProjectSelector(args, opts = {}) {
+  const list = Array.isArray(args) ? [...args] : [];
+  let flagProject = null;
+  const flagIdx = list.indexOf("--project");
+  if (flagIdx !== -1) {
+    flagProject = flagValue(list, "--project");
+    list.splice(flagIdx, 2);
+  }
+
+  const first = list[0];
+  let leadingIsProject = typeof first === "string" && first.startsWith("prj_");
+  if (leadingIsProject && opts.requireRestPositional) {
+    const remainder = positionalArgs(list.slice(1), opts.valueFlags ?? []);
+    if (remainder.length === 0) leadingIsProject = false;
+  }
+
+  if (flagProject !== null) {
+    if (leadingIsProject) {
+      if (first !== flagProject) {
+        fail({
+          code: "BAD_USAGE",
+          message: `Conflicting project ids: --project ${flagProject} vs positional ${first}`,
+          hint: "Pass the project once — prefer --project <id>.",
+          details: { project_flag: flagProject, positional: first },
+        });
+      }
+      list.shift();
+    }
+    return { projectId: flagProject, rest: list };
+  }
+
+  if (!leadingIsProject && typeof first === "string" && first.startsWith("prj_")) {
+    // A lone prj_ positional deliberately NOT consumed as the selector
+    // (requireRestPositional): it is the command's own attribute.
+    return { projectId: resolveProjectId(null), rest: list };
+  }
+  return resolvePositionalProject(list, opts);
+}
+
+/**
+ * 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;
@@ -315,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);