run402 4.94.0 → 4.96.0

package/lib/domains.mjs

@@ -9,24 +9,24 @@ Usage:
   run402 domains <subcommand> [args...]
 
 Subcommands:
-  connect      <domain> [--project <id>] [--web] [--authority hosted-zone] [--email-send] [...]
-  list         [--project <id>] [--include-managed]
-  status       <domain> [--project <id>]
-  dns          <domain> [--project <id>] [--format json|bind]
-  check        <domain> [--project <id>]
-  apply        <domain> [--project <id>] [--authority auto|provider-connect|delegated-subdomain|hosted-zone]
-  repair       <domain> [--project <id>]
-  test-receive <domain> --to <local-part|address> [--project <id>]
-  wait         <domain> [--project <id>] [--until active|safe|receive-active] [--timeout-ms <n>] [--interval-ms <n>]
-  activate     <domain> [--project <id>]
-  disconnect   <domain> --confirm [--project <id>]
+  connect      <domain> [--project <project_id>] [--web] [--authority hosted-zone] [--email-send] [...]
+  list         [--project <project_id>] [--include-managed]
+  status       <domain> [--project <project_id>]
+  dns          <domain> [--project <project_id>] [--format json|bind]
+  check        <domain> [--project <project_id>]
+  apply        <domain> [--project <project_id>] [--authority auto|provider-connect|delegated-subdomain|hosted-zone]
+  repair       <domain> [--project <project_id>]
+  test-receive <domain> --to <local-part|address> [--project <project_id>]
+  wait         <domain> [--project <project_id>] [--until active|safe|receive-active] [--timeout-ms <n>] [--interval-ms <n>]
+  activate     <domain> [--project <project_id>]
+  disconnect   <domain> --confirm [--project <project_id>]
 `;
 
 const SUB_HELP = {
   connect: `run402 domains connect — connect a ProjectDomain capability
 
 Usage:
-  run402 domains connect <domain> --project <id> [--web] [--email-send] [--email-receive] [options]
+  run402 domains connect <domain> --project <project_id> [--web] [--email-send] [--email-receive] [options]
 
 Examples:
   run402 domains connect kysigned.com --project prj_123 --email-send --email-receive --mailbox-addresses primary --addresses info
@@ -42,52 +42,52 @@ Examples:
   list: `run402 domains list — list project domains
 
 Usage:
-  run402 domains list --project <id>
+  run402 domains list --project <project_id>
 `,
   status: `run402 domains status — show one ProjectDomain aggregate
 
 Usage:
-  run402 domains status <domain> --project <id>
+  run402 domains status <domain> --project <project_id>
 `,
   dns: `run402 domains dns — print required DNS records
 
 Usage:
-  run402 domains dns <domain> --project <id> [--format json|bind]
+  run402 domains dns <domain> --project <project_id> [--format json|bind]
 `,
   check: `run402 domains check — refresh ProjectDomain observations and checks
 
 Usage:
-  run402 domains check <domain> --project <id>
+  run402 domains check <domain> --project <project_id>
 `,
   apply: `run402 domains apply — apply safe provider-managed changes
 
 Usage:
-  run402 domains apply <domain> --project <id> [--authority auto|provider-connect|delegated-subdomain|hosted-zone]
+  run402 domains apply <domain> --project <project_id> [--authority auto|provider-connect|delegated-subdomain|hosted-zone]
 `,
   repair: `run402 domains repair — repair Run402-owned domain infrastructure
 
 Usage:
-  run402 domains repair <domain> --project <id>
+  run402 domains repair <domain> --project <project_id>
 `,
   "test-receive": `run402 domains test-receive — create an inbound receive test token
 
 Usage:
-  run402 domains test-receive <domain> --project <id> --to <local-part|address>
+  run402 domains test-receive <domain> --project <project_id> --to <local-part|address>
 `,
   wait: `run402 domains wait — poll until a ProjectDomain is ready
 
 Usage:
-  run402 domains wait <domain> --project <id> [--until active|safe|receive-active] [--timeout-ms <n>] [--interval-ms <n>]
+  run402 domains wait <domain> --project <project_id> [--until active|safe|receive-active] [--timeout-ms <n>] [--interval-ms <n>]
 `,
   activate: `run402 domains activate — activate custom mailbox addresses
 
 Usage:
-  run402 domains activate <domain> --project <id>
+  run402 domains activate <domain> --project <project_id>
 `,
   disconnect: `run402 domains disconnect — disconnect a ProjectDomain
 
 Usage:
-  run402 domains disconnect <domain> --project <id> --confirm
+  run402 domains disconnect <domain> --project <project_id> --confirm
 `,
 };
 
@@ -300,14 +300,14 @@ async function connect(args) {
   ], CONNECT_VALUE_FLAGS);
   const rest = positionalArgs(parsed, CONNECT_VALUE_FLAGS);
   const domain = rest[0];
-  if (!domain) fail({ code: "BAD_USAGE", message: "Missing <domain>.", hint: "run402 domains connect <domain> --project <id> --web" });
+  if (!domain) fail({ code: "BAD_USAGE", message: "Missing <domain>.", hint: "run402 domains connect <domain> --project <project_id> --web" });
   if (rest.length > 1) fail({ code: "BAD_USAGE", message: `Unexpected argument for domains connect: ${rest[1]}` });
   if (parsed.includes("--create-mailboxes") && parsed.includes("--no-create-mailboxes")) {
     fail({ code: "BAD_FLAG", message: "Choose only one of --create-mailboxes or --no-create-mailboxes." });
   }
   const projectId = resolveProjectId(flagValue(parsed, "--project"));
   try {
-    const result = await getSdk().domains.ensure(projectId, domain, { desired: desiredFromConnectFlags(domain, parsed) });
+    const result = await getSdk().domains.connect(projectId, { domain, desired: desiredFromConnectFlags(domain, parsed) });
     print(result);
     printHandoff(result);
   } catch (err) {
@@ -328,7 +328,7 @@ async function list(args) {
 async function status(args) {
   const { projectId, rest } = parseCommon(args);
   const domain = rest[0];
-  if (!domain) fail({ code: "BAD_USAGE", message: "Missing <domain>.", hint: "run402 domains status <domain> [--project <id>]" });
+  if (!domain) fail({ code: "BAD_USAGE", message: "Missing <domain>.", hint: "run402 domains status <domain> [--project <project_id>]" });
   if (rest.length > 1) fail({ code: "BAD_USAGE", message: `Unexpected argument for domains status: ${rest[1]}` });
   try {
     print(await getSdk().domains.get(projectId, domain));
@@ -366,7 +366,7 @@ async function action(name, args) {
   assertKnownFlags(parsed, [...valueFlags, "--help", "-h"], valueFlags);
   const rest = positionalArgs(parsed, valueFlags);
   const domain = rest[0];
-  if (!domain) fail({ code: "BAD_USAGE", message: `Missing <domain>.`, hint: `run402 domains ${name} <domain> [--project <id>]` });
+  if (!domain) fail({ code: "BAD_USAGE", message: `Missing <domain>.`, hint: `run402 domains ${name} <domain> [--project <project_id>]` });
   if (rest.length > 1) fail({ code: "BAD_USAGE", message: `Unexpected argument for domains ${name}: ${rest[1]}` });
   const projectId = resolveProjectId(flagValue(parsed, "--project"));
   try {
@@ -398,7 +398,7 @@ async function disconnect(args) {
   assertKnownFlags(parsed, [...valueFlags, "--confirm", "--help", "-h"], valueFlags);
   const rest = positionalArgs(parsed, valueFlags);
   const domain = rest[0];
-  if (!domain) fail({ code: "BAD_USAGE", message: "Missing <domain>.", hint: "run402 domains disconnect <domain> --confirm [--project <id>]" });
+  if (!domain) fail({ code: "BAD_USAGE", message: "Missing <domain>.", hint: "run402 domains disconnect <domain> --confirm [--project <project_id>]" });
   if (!parsed.includes("--confirm")) {
     fail({
       code: "CONFIRMATION_REQUIRED",

package/lib/email.mjs

@@ -74,51 +74,51 @@ Usage:
   run402 email <subcommand> [args...]
 
 Subcommands:
-  create <slug> [--project <id>]     Create a project-scoped mailbox local part
-  mailboxes [--project <id>]         List mailboxes with default-role metadata
+  create <slug> [--project <project_id>]     Create a project-scoped mailbox local part
+  mailboxes [--project <project_id>]         List mailboxes with default-role metadata
                                       and gateway next_actions
-  defaults [--outbound <slug|id>] [--auth-sender <slug|id>] [--project <id>]
+  defaults [--outbound <slug|id>] [--auth-sender <slug|id>] [--project <project_id>]
                                       Show or set mailbox defaults. With no
                                       flags, prints current settings/candidates.
-  update [<slug|id>] --footer-policy <run402_transparency|none> [--project <id>]
+  update [<slug|id>] --footer-policy <run402_transparency|none> [--project <project_id>]
                                       Update per-mailbox settings
-  info   [--project <id>]            Show mailbox info, including footer policy
-  status [--project <id>]            Alias for 'info' (prefer 'info')
+  info   [--project <project_id>]            Show mailbox info, including footer policy
+  status [--project <project_id>]            Alias for 'info' (prefer 'info')
   send   --to <email> [mode flags]   Send an email (template or raw HTML)
-  list   [--limit <n>] [--after <cursor>] [--direction <inbound|outbound>] [--project <id>]
+  list   [--limit <n>] [--after <cursor>] [--direction <inbound|outbound>] [--project <project_id>]
                                       List messages (paginated). Returns BOTH
                                       sent + received by default; --direction
                                       inbound is the reconciliation backstop.
-  get    <message_id> [--project <id>]  Get a message with replies
-  get-raw <message_id> --output <file> [--project <id>]
+  get    <message_id> [--project <project_id>]  Get a message with replies
+  get-raw <message_id> --output <file> [--project <project_id>]
                                       Fetch raw RFC-822 bytes (inbound only).
                                       --output is required: bytes are written
                                       to the file; stdout receives a JSON
                                       envelope { message_id, bytes, output }.
-  reply  <message_id> --html "..." [--text "..."] [--subject "..."] [--from-name "..."] [--project <id>]
+  reply  <message_id> --html "..." [--text "..."] [--subject "..."] [--from-name "..."] [--project <project_id>]
                                       Reply to an inbound message (threads via In-Reply-To)
-  delete [<slug|mailbox_id>] --confirm [--project <id>]
+  delete [<slug|mailbox_id>] --confirm [--project <project_id>]
                                       Delete the project's mailbox (irreversible)
   webhooks <action> [args...]        Manage webhooks (see below)
 
 Webhook subcommands:
-  webhooks list   [--project <id>]                List webhooks
-  webhooks get    <webhook_id> [--project <id>]   Get a webhook
-  webhooks delete <webhook_id> [--project <id>]   Delete a webhook
-  webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--project <id>]
+  webhooks list   [--project <project_id>]                List webhooks
+  webhooks get    <webhook_id> [--project <project_id>]   Get a webhook
+  webhooks delete <webhook_id> [--project <project_id>]   Delete a webhook
+  webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--project <project_id>]
                                                   Update a webhook
-  webhooks register --url <url> --events <e1,e2> [--project <id>]
+  webhooks register --url <url> --events <e1,e2> [--project <project_id>]
                                                   Register a new webhook
-  webhooks deliveries [--status <s>] [--project <id>]
+  webhooks deliveries [--status <s>] [--project <project_id>]
                                                   List durable delivery rows (DLQ visibility)
-  webhooks redrive <delivery_id> [--project <id>]
+  webhooks redrive <delivery_id> [--project <project_id>]
                                                   Re-queue a dead-lettered delivery
 
 Send modes:
   Template:  --template <name> --var key=value [--var ...]  OR --vars '{"k":"v",...}'
   Raw HTML:  --subject "..." --html "..." [--text "..."]    (both --subject and --html required)
   Raw HTML also supports: --attach <path>[:content-type] (repeatable; max 5, 7 MB total)
-  Both modes support: --from-name "Display Name" --project <id>
+  Both modes support: --from-name "Display Name" --project <project_id>
 
 Choosing a mailbox:
   --mailbox <slug|id>  Target a specific mailbox. Accepted by send, list, get,
@@ -185,12 +185,12 @@ Options:
                       extension when the :content-type suffix is omitted.
   --from-name "..."   Display name for the From header
   --mailbox <slug|id> Target mailbox. Omit to use default_outbound_mailbox_id.
-  --project <id>      Project ID (defaults to the active project)
+  --project <project_id>      Project ID (defaults to the active project)
 `,
   list: `run402 email list — List messages in the mailbox
 
 Usage:
-  run402 email list [--mailbox <slug|id>] [--limit <n>] [--after <cursor>] [--project <id>]
+  run402 email list [--mailbox <slug|id>] [--limit <n>] [--after <cursor>] [--project <project_id>]
 `,
   reply: `run402 email reply — Reply to an inbound message (threaded via In-Reply-To)
 
@@ -200,17 +200,17 @@ Usage:
   delete: `run402 email delete — Delete the project's mailbox (irreversible)
 
 Usage:
-  run402 email delete [<slug|mailbox_id>] --confirm [--project <id>]
+  run402 email delete [<slug|mailbox_id>] --confirm [--project <project_id>]
 `,
   info: `run402 email info — Show mailbox info, including footer policy
 
 Usage:
-  run402 email info [--project <id>]
+  run402 email info [--project <project_id>]
 `,
   status: `run402 email status — Alias for 'run402 email info' (prefer 'info')
 
 Usage:
-  run402 email status [--project <id>]
+  run402 email status [--project <project_id>]
 
 See 'run402 email info --help' for details. 'status' is kept for backward
 compatibility; new code should use 'info'.
@@ -218,7 +218,7 @@ compatibility; new code should use 'info'.
   "get-raw": `run402 email get-raw — Fetch raw RFC-822 bytes for an inbound message
 
 Usage:
-  run402 email get-raw <message_id> --output <file> [--project <id>]
+  run402 email get-raw <message_id> --output <file> [--project <project_id>]
 
 Arguments:
   <message_id>        Inbound message ID
@@ -228,14 +228,14 @@ Options:
                       stdout receives a JSON envelope
                       { message_id, bytes, output } — the MIME body is never
                       written to stdout, so the CLI stays pipeable.
-  --project <id>      Project ID (defaults to the active project)
+  --project <project_id>      Project ID (defaults to the active project)
   --mailbox <slug|id> Target a specific mailbox (required when the project
                       has more than one)
 `,
   create: `run402 email create — Create a project mailbox
 
 Usage:
-  run402 email create <slug> [--project <id>]
+  run402 email create <slug> [--project <project_id>]
 
 Arguments:
   <slug>              Mailbox slug (3-63 chars, lowercase alphanumeric +
@@ -244,7 +244,7 @@ Arguments:
                       <slug>@<project-mail-host>.mail.run402.com.
 
 Options:
-  --project <id>      Project ID (defaults to the active project)
+  --project <project_id>      Project ID (defaults to the active project)
 
 Notes:
   - Up to 5 mailboxes per project; the same slug may be used by another project
@@ -256,7 +256,7 @@ Examples:
   mailboxes: `run402 email mailboxes — List project mailboxes
 
 Usage:
-  run402 email mailboxes [--project <id>]
+  run402 email mailboxes [--project <project_id>]
 
 Returns JSON: { mailboxes, mailbox_settings?, next_actions? }. Mailbox rows
 include default-role/readiness metadata when the gateway provides it.
@@ -264,41 +264,41 @@ include default-role/readiness metadata when the gateway provides it.
   defaults: `run402 email defaults — Show or set mailbox defaults
 
 Usage:
-  run402 email defaults [--project <id>]
-  run402 email defaults --outbound <slug|mbx_id> [--auth-sender <slug|mbx_id>] [--project <id>]
-  run402 email defaults --auth-sender <slug|mbx_id> [--project <id>]
+  run402 email defaults [--project <project_id>]
+  run402 email defaults --outbound <slug|mbx_id> [--auth-sender <slug|mbx_id>] [--project <project_id>]
+  run402 email defaults --auth-sender <slug|mbx_id> [--project <project_id>]
 
 Options:
   --outbound <slug|mbx_id>     Set default_outbound_mailbox_id
   --auth-sender <slug|mbx_id>  Set auth_sender_mailbox_id
   --clear-outbound             Clear default_outbound_mailbox_id
   --clear-auth-sender          Clear auth_sender_mailbox_id
-  --project <id>               Project ID (defaults to the active project)
+  --project <project_id>               Project ID (defaults to the active project)
 `,
   update: `run402 email update — Update per-mailbox settings
 
 Usage:
-  run402 email update [<slug|mbx_id>] --footer-policy <run402_transparency|none> [--project <id>]
-  run402 email update --mailbox <slug|mbx_id> --footer-policy <run402_transparency|none> [--project <id>]
+  run402 email update [<slug|mbx_id>] --footer-policy <run402_transparency|none> [--project <project_id>]
+  run402 email update --mailbox <slug|mbx_id> --footer-policy <run402_transparency|none> [--project <project_id>]
 
 Options:
   --footer-policy <policy>  Outbound footer policy. Use run402_transparency or none.
                             Prototype projects are locked to run402_transparency;
                             attempts to set none return FOOTER_POLICY_TIER_REQUIRED.
   --mailbox <slug|id>       Target mailbox; omit only when the project has one mailbox.
-  --project <id>            Project ID (defaults to the active project)
+  --project <project_id>            Project ID (defaults to the active project)
 `,
   get: `run402 email get — Get a message with replies
 
 Usage:
-  run402 email get <message_id> [--mailbox <slug|id>] [--project <id>]
+  run402 email get <message_id> [--mailbox <slug|id>] [--project <project_id>]
 
 Arguments:
   <message_id>        Message ID to fetch
 
 Options:
   --mailbox <slug|id> Target mailbox. Omit to use default_outbound_mailbox_id.
-  --project <id>      Project ID (defaults to the active project)
+  --project <project_id>      Project ID (defaults to the active project)
 
 Examples:
   run402 email get msg_abc123 --mailbox support

package/lib/errors.mjs

@@ -30,6 +30,7 @@ import {
   normalizeArgv,
   parseIntegerFlag,
   positionalArgs,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
 
 /** Wire `kind` vocabulary (mirrors the gateway's KINDS set). */
@@ -43,10 +44,10 @@ export const DEFAULT_INTERVAL_MS = 15000;
 const HELP = `run402 errors — grouped error fingerprints + a promote/revert verdict
 
 Usage:
-  run402 errors [--project <id>] [filters] [--human]
-  run402 errors <fingerprint_id> [--project <id>] [--human]
-  run402 errors --new-in <release_id|active> --fail-on-new [--human]
-  run402 errors --new-in <release_id|active> --watch <dur> [--fail-on-new]
+  run402 errors list [--project <project_id>] [filters] [--human]
+  run402 errors get <fingerprint_id> [--project <project_id>] [--human]
+  run402 errors list --new-in <release_id|active> --fail-on-new [--human]
+  run402 errors list --new-in <release_id|active> --watch <dur> [--fail-on-new]
 
 What this is:
   A "fingerprint" is one error IDENTITY — errors with the same normalized
@@ -66,12 +67,12 @@ What this is:
   under that release; "active" resolves the project's live release.
 
 Filters (each maps 1:1 to a query param):
-  --project <id>        Project to read (defaults to the active project)
+  --project <project_id> Project to read (defaults to the active project)
   --since <iso>         Window start (ISO-8601). Default: 24h before --until
   --until <iso>         Window end (ISO-8601). Default: now
   --function <name>     Only this function's fingerprints
   --kind <kind>         One of: ${KINDS.join(", ")}
-  --fingerprint <id>    Only this fingerprint id (exact)
+  --fingerprint <fingerprint_id>    Only this fingerprint id (exact)
   --new-in <rel|active> Only identities first seen under this release
                         (a release id, or the literal "active" for live)
   --limit <n>           Page size (default 50, max 200)
@@ -115,30 +116,38 @@ Auth:
   leaks existence). Read-only; never lifecycle-gated.
 
 The golden path — gate a promote:
-  run402 deploy promote --project <id> --release <rel>
-  run402 errors --project <id> --new-in <rel> --watch 10m --fail-on-new
+  run402 deploy promote <release_id> --project <project_id>
+  run402 errors list --project <project_id> --new-in <release_id> --watch 10m --fail-on-new
   # exit 0 -> the new release is clean; exit 1 -> revert, drill in via logs.
   # (a promote response already hands you this exact command in next_actions
   #  as the "watch_errors" action — copy it verbatim.)
 
 Examples:
-  run402 errors                                   # last 24h, verdict + groups
-  run402 errors --function checkout --kind uncaught
-  run402 errors --since 2026-07-11T00:00:00Z --limit 200
-  run402 errors fp_9b21fa                          # one fingerprint, all samples
-  run402 errors --new-in active                    # what's new under the live release
-  run402 errors --new-in rel_01JX --fail-on-new    # one-shot gate (CI)
-  run402 errors --new-in rel_01JX --watch 10m --interval 30s --fail-on-new
+  run402 errors list                              # last 24h, verdict + groups
+  run402 errors list --function checkout --kind uncaught
+  run402 errors list --since 2026-07-11T00:00:00Z --limit 200
+  run402 errors get fp_9b21fa                     # one fingerprint, all samples
+  run402 errors list --new-in active              # what's new under the live release
+  run402 errors list --new-in rel_01JX --fail-on-new    # one-shot gate (CI)
+  run402 errors list --new-in rel_01JX --watch 10m --interval 30s --fail-on-new
 `;
 
 export async function run(sub, args = []) {
-  const argv = [sub, ...(Array.isArray(args) ? args : [])].filter((x) => x !== undefined && x !== null);
-  if (argv.includes("--help") || argv.includes("-h")) {
+  const rest = Array.isArray(args) ? args : [];
+  if (sub === undefined || sub === null || sub === "--help" || sub === "-h" || rest.includes("--help") || rest.includes("-h")) {
     console.log(HELP);
     process.exit(0);
   }
+  switch (sub) {
+    case "list": return runErrors("list", rest);
+    case "get": return runErrors("get", rest);
+    default:
+      failUnknownSubcommand("errors", sub);
+  }
+}
 
-  const a = normalizeArgv(argv);
+async function runErrors(mode, args) {
+  const a = normalizeArgv(args);
   const valueFlags = [
     "--project", "--since", "--until", "--function", "--kind",
     "--fingerprint", "--new-in", "--limit", "--cursor", "--watch", "--interval",
@@ -147,14 +156,21 @@ export async function run(sub, args = []) {
   assertKnownFlags(a, [...valueFlags, ...boolFlags], valueFlags);
 
   const positionals = positionalArgs(a, valueFlags);
-  if (positionals.length > 1) {
+  if (mode === "list" && positionals.length > 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for errors list: ${positionals[0]}`,
+      hint: "Read one fingerprint with `run402 errors get <fingerprint_id>`. Run `run402 errors --help`.",
+    });
+  }
+  if (mode === "get" && positionals.length !== 1) {
     fail({
       code: "BAD_USAGE",
-      message: `Unexpected extra argument: ${positionals[1]}`,
-      hint: "Pass at most one <fingerprint_id> for the detail view. Run `run402 errors --help`.",
+      message: positionals.length === 0 ? "Missing <fingerprint_id>." : `Unexpected extra argument: ${positionals[1]}`,
+      hint: "Usage: run402 errors get <fingerprint_id> [--project <project_id>] [--human]",
     });
   }
-  const fingerprintId = positionals[0] ?? null;
+  const fingerprintId = mode === "get" ? positionals[0] : null;
   // Output contract (cli-output-shape): JSON is ALWAYS the default. `--json`
   // is a universally-accepted no-op; human rendering is the `--human`
   // opt-out, matching `run402 up`. Never gate stdout shape on `--json`.
@@ -183,8 +199,8 @@ export async function run(sub, args = []) {
     if (offending) {
       fail({
         code: "BAD_USAGE",
-        message: `${offending} is not valid with a <fingerprint_id> (detail view).`,
-        hint: "Detail view accepts only --project and --human. Drop the fingerprint id to list + get a verdict.",
+        message: `${offending} is not valid with errors get <fingerprint_id>.`,
+        hint: "errors get accepts only --project and --human. Use `run402 errors list` to list + get a verdict.",
       });
     }
     const projectId = resolveProjectId(project);

package/lib/escalations.mjs

@@ -29,7 +29,7 @@ const ORG_FLAGS = ["--org", "--project"];
 const HELP = `run402 escalations — page a human when you judge you need one
 
 Usage:
-  run402 escalations raise <reason> [--severity high] [--wait] [--project <id>]
+  run402 escalations raise <reason> [--severity high] [--wait] [--project <project_id>]
   run402 escalations list [--status open] [--limit <n>] [--cursor <c>]
   run402 escalations get <escalation_id> [--delivery]
   run402 escalations ack <escalation_id>
@@ -48,12 +48,12 @@ WHEN TO RAISE — the judgement is yours, and that is the product:
 
 The flow: judge -> raise -> wait -> proceed-or-stand-down.
   \`--wait\` blocks until a human acknowledges (polls for you). Without it,
-  poll \`run402 escalations get <id>\` yourself. \`acknowledged\` means a NAMED
+  poll \`run402 escalations get <escalation_id>\` yourself. \`acknowledged\` means a NAMED
   human owns it — then do what they say, or stand down. Silence is not consent.
 
 Addressing:
   (default)         The active project's organization — a checkout needs no flags.
-  --project <id>    Resolve the org from another project.
+  --project <project_id>    Resolve the org from another project.
   --org <org_id>    Explicit organization.
 
 Delivery:
@@ -235,7 +235,7 @@ async function contacts(args) {
   fail({
     code: "COMMAND_REMOVED",
     message: "`run402 escalations contacts` moved to `run402 contacts`.",
-    hint: sub === "remove" ? "run402 contacts rm <id>" : `run402 contacts ${sub ?? "list"}`,
+    hint: sub === "remove" ? "run402 contacts rm <contact_id>" : `run402 contacts ${sub ?? "list"}`,
     details: {
       was: `escalations contacts${sub ? ` ${sub}` : ""}`,
       now: "contacts",

package/lib/events.mjs

@@ -4,7 +4,7 @@
  * since I last looked": deploy activations, mailbox suspensions, transfers,
  * lifecycle cliffs, verification outcomes — each with platform-synthesized
  * next_actions drill-downs. The feed also carries app-emitted business
- * facts (a deployed function's own `events.emit(...)` calls) alongside the
+ * events (a deployed function's own `events.emit(...)` calls) alongside the
  * platform's own events — filter with --source/--type.
  *
  * JSON envelope to stdout (pipe contract); flags map 1:1 to the HTTP query.
@@ -15,7 +15,7 @@
 import { resolveProjectId } 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, failUnknownSubcommand } from "./argparse.mjs";
 
 /** Wire `source` vocabulary (mirrors the gateway's app/platform dichotomy). */
 export const SOURCES = ["app", "platform"];
@@ -23,15 +23,15 @@ export const SOURCES = ["app", "platform"];
 const HELP = `run402 events — what happened to your project since you last looked
 
 Usage:
-  run402 events [--project <project_id>] [--cursor <cursor>] [--limit <n>]
-                [--source <app|platform>] [--type <name[,name]>]
-  run402 events --org <org_id> [--cursor <cursor>] [--limit <n>]
-                [--source <app|platform>] [--type <name[,name]>]
+  run402 events list [--project <project_id>] [--cursor <cursor>] [--limit <n>]
+                     [--source <app|platform>] [--type <name[,name]>]
+  run402 events list --org <org_id> [--cursor <cursor>] [--limit <n>]
+                     [--source <app|platform>] [--type <name[,name]>]
 
 Options:
-  --project <id>    Project to read (defaults to the active project)
-  --org <id>        Read the org-wide feed instead — a SUPERSET of the project
-                    feeds: it also carries org-level facts (project_id null)
+  --project <project_id>  Project to read (defaults to the active project)
+  --org <org_id>    Read the org-wide feed instead — a SUPERSET of the project
+                    feeds: it also carries org-level events (project_id null)
   --cursor <cursor> Opaque cursor from a previous response. Returns events strictly
                     after it. Omit on first contact to start from the earliest
                     retained event.
@@ -45,7 +45,7 @@ App events vs platform events:
   operational record (deploy activations, mailbox suspensions, transfers,
   lifecycle cliffs, verification outcomes, ...) — the platform's internal
   producers (gateway, email-lambda, ...) all collapse under this one value.
-  "app" is business facts a deployed function emitted itself via
+  "app" is business events a deployed function emitted itself via
   \`events.emit(type, payload?, {idempotencyKey?})\` from @run402/functions —
   e.g. "signature_completed" or "booking_created". Consumers should key on
   the PAIR (source, event_type) together: app event_type names are free-form
@@ -58,7 +58,7 @@ The cursor model — an id is not a cursor:
     your repo, a memory note — wherever you keep state) and pass it back as
     --cursor next time. One call then returns everything you missed.
   - Two opaque tokens, and they are different things. An event's "id" names a
-    FACT: the same event has the same id in the project feed and the org feed,
+    EVENT: the same event has the same id in the project feed and the org feed,
     which is how you dedup across both. The page "cursor" names a POSITION,
     and a position only means something inside the row set it came from.
   - So a cursor is NOT portable. Replaying a --project cursor against --org,
@@ -84,9 +84,9 @@ When your cursor is unusable (reset semantics):
 Event shape:
   { "id", "project_id", "event_type", "class", "occurred_at", "payload",
     "next_actions" }
-  project_id is what the fact is ABOUT. It is null for an org-level fact —
+  project_id is what the event is ABOUT. It is null for an org-level event —
   one that belongs to the org and to no project, visible only via --org. It
-  may also name a project that no longer exists: a fact outlives the project
+  may also name a project that no longer exists: an event outlives the project
   it describes, so deleting a project no longer erases its history.
   event_type is flat snake_case: deploy_activated, mailbox_suspended,
   project_transfer_completed, organization_past_due, verification_failed,
@@ -107,30 +107,37 @@ own deploy_activated event — poll once after deploying to establish your
 cursor, then catch up next session in one call.
 
 Examples:
-  run402 events                                # active project, from the earliest retained event
-  run402 events --cursor evc_1a2b              # everything since last time
-  run402 events --project prj_abc --limit 200
-  run402 events --org 00000000-0000-0000-0000-aaaaaaaaaaaa --cursor evc_9z
-  run402 events --source app                   # just this project's own emitted business facts
-  run402 events --source app --type signature_completed,booking_created
-  run402 events --source platform              # just the platform's operational record
+  run402 events list                                # active project, from the earliest retained event
+  run402 events list --cursor evc_1a2b              # everything since last time
+  run402 events list --project prj_abc --limit 200
+  run402 events list --org 00000000-0000-0000-0000-aaaaaaaaaaaa --cursor evc_9z
+  run402 events list --source app                   # just this project's own emitted business events
+  run402 events list --source app --type signature_completed,booking_created
+  run402 events list --source platform              # just the platform's operational record
 `;
 
 export async function run(sub, args) {
-  // Flat command: no subcommands. `sub` is the first arg (may be a flag).
-  const argv = [sub, ...(Array.isArray(args) ? args : [])].filter((a) => a !== undefined && a !== null);
-  if (argv.includes("--help") || argv.includes("-h")) {
+  const rest = Array.isArray(args) ? args : [];
+  if (sub === undefined || sub === null || sub === "--help" || sub === "-h" || rest.includes("--help") || rest.includes("-h")) {
     console.log(HELP);
     process.exit(0);
   }
-  const a = normalizeArgv(argv);
+  switch (sub) {
+    case "list": return list(rest);
+    default:
+      failUnknownSubcommand("events", sub);
+  }
+}
+
+async function list(args) {
+  const a = normalizeArgv(args);
   const valueFlags = ["--project", "--org", "--cursor", "--limit", "--source", "--type"];
   assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
   const extra = positionalArgs(a, valueFlags);
   if (extra.length > 0) {
     fail({
       code: "BAD_USAGE",
-      message: `Unexpected argument for events: ${extra[0]}`,
+      message: `Unexpected argument for events list: ${extra[0]}`,
       hint: "Run `run402 events --help` for usage.",
     });
   }

package/lib/feedback.mjs

@@ -56,7 +56,7 @@ Arguments:
                       joined with spaces if multiple are provided)
 
 Flags:
-  --project <id>      Project this feedback concerns. Required to relay a
+  --project <project_id>      Project this feedback concerns. Required to relay a
                       promotion consent (the hand_to_member next action
                       from a deploy response) — the server resolves the
                       project's site URL, org, and your presence name for
@@ -74,7 +74,7 @@ Notes:
     hand_to_member next action, show your human urls.site and
     urls.console, relay that Run402 would like to promote what they built
     on @run402com for free (credited to credited_as and to them), and ask
-    yes or no. On yes: run402 feedback send "promote: yes" --project <id>
+    yes or no. On yes: run402 feedback send "promote: yes" --project <project_id>
     [--handle <handle>]
 
 Examples: