run402 4.93.2 → 4.95.0

package/lib/deploy.mjs

@@ -1,72 +1,40 @@
 import { failUnknownSubcommand } from "./argparse.mjs";
 
-const HELP = `run402 deploy — Unified deploy operations
-
-Usage:
-  run402 deploy <subcommand> [options]
-
-Subcommands:
-  apply --manifest <file>       Apply a v2 ReleaseSpec manifest
-  rehearse <plan_id>            Rehearse a persisted plan on a contained branch
-  resume <operation_id>         Resume a stuck operation
-  list [--project <id>]         List recent deploy operations
-  events <operation_id>         Fetch event stream for an operation
-  verify <operation_id>         Verify gateway and edge coherence
-  diagnose <url>                Diagnose public URL routing
-  resolve --url <url>           Low-level resolve diagnostics
-  release ...                   Inspect release inventory and diffs
-
-Examples:
-  run402 deploy apply --manifest app.json
-  run402 deploy resume op_123
-  run402 deploy release active --project prj_123
-
-Manifest sketch:
-  {
-    "database": {
-      "migrations": [{ "id": "001_init", "sql_path": "schema.sql" }]
-    },
-    "site": {
-      "replace": { "index.html": { "path": "dist/index.html" } }
-    },
-    "functions": {
-      "replace": {
-        "api": {
-          "runtime": "node22",
-          "source": { "path": "api.mjs" }
-        }
-      }
-    },
-    "secrets": { "require": ["OPENAI_API_KEY"] },
-    "subdomains": { "set": ["my-app"] }
-  }
-`;
+/**
+ * `run402 deploy` is the one word that is both a verb and a family: bare
+ * `run402 deploy [--manifest <path>] [--project <project_id>] …` performs the
+ * deploy, and `run402 deploy <subcommand>` dispatches the family. Every
+ * subcommand and the deploy itself live in deploy-v2.mjs; this file only
+ * decides which one the argv names.
+ */
 
 export async function run(args) {
   const sub = args[0];
-  if (!sub || sub === "--help" || sub === "-h") {
-    console.log(HELP);
-    process.exit(0);
-  }
+  const { runDeployV2 } = await import("./deploy-v2.mjs");
 
   switch (sub) {
-  case "apply":
     case "rehearse":
     case "promote":
     case "resume":
+    case "status":
     case "list":
     case "events":
     case "verify":
-    case "diagnose":
     case "resolve":
-    case "release": {
-      const { runDeployV2 } = await import("./deploy-v2.mjs");
+    case "releases":
       await runDeployV2(sub, args.slice(1));
       return;
-    }
     default:
-      failUnknownSubcommand("deploy", sub, {
-        hint: "Use `run402 deploy apply --manifest <file>` for deployments.",
-      });
+      break;
+  }
+
+  // A bare word that is not a subcommand is a typo, never a manifest: the
+  // deploy takes no positionals. Everything else — no arguments at all, a
+  // flag, --help — is the deploy itself.
+  if (typeof sub === "string" && !sub.startsWith("-")) {
+    failUnknownSubcommand("deploy", sub, {
+      hint: "Use `run402 deploy --manifest <path>` to deploy, or one of the subcommands.",
+    });
   }
+  await runDeployV2("deploy", args);
 }

package/lib/dev.mjs

@@ -29,12 +29,12 @@ import { fail } from "./sdk-errors.mjs";
 const HELP = `run402 dev — Run Astro dev with Run402 context
 
 Usage:
-  run402 dev [--port <n>] [--host <h>] [--project <id>]
+  run402 dev [--port <n>] [--host <h>] [--project <project_id>]
 
 Options:
   --port <n>        Astro dev port (default 4321)
   --host <h>        Astro dev host (default localhost)
-  --project <id>    Project id (default: RUN402_PROJECT_ID env var)
+  --project <project_id>    Project id (default: RUN402_PROJECT_ID env var)
 
 The command:
   1. Loads .env.local from the current directory (if present)
@@ -85,7 +85,7 @@ export async function run(sub, args = []) {
     fail({
       code: "BAD_USAGE",
       message: "Missing RUN402_PROJECT_ID.",
-      hint: "Set it in .env.local (or pass --project <id>). Run 'run402 projects provision' first if you don't have one.",
+      hint: "Set it in .env.local (or pass --project <project_id>). Run 'run402 projects provision' first if you don't have one.",
     });
   }
   if (!process.env.RUN402_SERVICE_KEY) {

package/lib/doctor-source-scan.mjs

@@ -1,2 +1,2 @@
-// Shared with Node up, deploy apply, and scoped doctor.
+// Shared with Node up, deploy, and scoped doctor.
 export { scanFileContent, scanSourceTree, scanSourceFiles, resolveScanRoot, readDeclaredCapabilities, SCAN_SEVERITY, _testOnly_hallucinatedNames, _testOnly_authProperties } from "#sdk/node";

package/lib/doctor.mjs

@@ -2,7 +2,7 @@ import { resolveApplicationScope, loadApplicationScanInput, scanDeploymentSource
 /**
  * run402 doctor — Health and config diagnostics.
  *
- * Reports the state of the local Run402 setup: config dir, allowance,
+ * Reports the state of the local Run402 setup: config dir, wallet,
  * tier, project selection, API reachability. Agent-friendly: with
  * `--json`, emits a structured report the agent can branch on without
  * parsing English output.
@@ -14,7 +14,7 @@ import { resolveApplicationScope, loadApplicationScanInput, scanDeploymentSource
 
 import { existsSync, statSync } from "node:fs";
 import { GITVAULT_BYO_NO_PAYLOAD_COPY_STATEMENT } from "#sdk";
-import { configDir, readAllowance, loadKeyStore } from "./config.mjs";
+import { configDir, readWallet, loadKeyStore } from "./config.mjs";
 import { resolveGitvaultTarget } from "./gitvault-target.mjs";
 import { getSdk } from "./sdk.mjs";
 import {
@@ -47,11 +47,11 @@ const DOCTOR_VALUE_FLAGS = ["--scan-dir", "--dir", "--manifest", "--buzz-agent",
 const DOCTOR_CHECK_NAMES = [
   "config_dir",
   "cli_update",
-  "allowance",
+  "wallet",
   "projects",
   "api_reachable",
   "tier",
-  "operator_health",
+  "account_health",
   "runtime_staleness",
   "recovery_posture",
   "gitvault",
@@ -75,7 +75,7 @@ function collectRepeatableFlag(args, flag) {
 const HELP = `run402 doctor — Health and config diagnostics
 
 Usage:
-  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>] [--project <id>]
+  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>] [--project <project_id>]
                 [--only <check> ...]
   run402 --wallet <profile> doctor --buzz --buzz-agent <npub-or-hex>
 
@@ -87,10 +87,10 @@ Output:
       checks:   [{ name, status, severity, value?, hint?, message? }] }
   \`ok\` answers ONE question — can this agent ship from here — and is true
   exactly when \`blocking[]\` is empty. Every check carries a \`severity\`:
-    blocking  would stop a deploy: config_dir / allowance missing or error,
+    blocking  would stop a deploy: config_dir / wallet missing or error,
               api_reachable error, tier inactive / frozen / past_due /
               dormant / missing / error, error-severity source_scan findings
-    advisory  a warning that never stops a deploy: operator_health,
+    advisory  a warning that never stops a deploy: account_health,
               recovery_posture, gitvault, runtime_staleness, cli_update gaps
     info      ok / skipped / unknown
   Agents: branch on \`ok\`; read \`warnings[]\` (one entry per gap) for the
@@ -117,7 +117,7 @@ Options:
   --dir D        Select the application directory for deployment diagnostics.
   --manifest P   Explicitly select a manifest (executable configs are trusted code).
   --scan-dir D   Advanced arbitrary scan; does not claim deployment readiness
-  --project <id> Target THIS project's gitvault check instead of the repo-standing
+  --project <project_id> Target THIS project's gitvault check instead of the repo-standing
                  default (the 4.38.0 pin / run402 remote / RUN402_PROJECT_ID / active
                  project, in that order — see \`gitvault-target.mjs\`). Scoped to the
                  gitvault check only; every other check is wallet/machine-wide, not
@@ -127,7 +127,7 @@ Options:
                  source-tree scan, is suppressed rather than merely hidden: a
                  skipped check's network/filesystem work never runs at all, so
                  \`doctor --only gitvault\` costs one gitvault read, not a
-                 config/tier/operator/scan sweep. An unknown check name is
+                 config/tier/account/scan sweep. An unknown check name is
                  BAD_USAGE listing the valid names below. Not used with --buzz
                  (buzz mode is its own separate, always-complete check set).
   --buzz         Run only the zero-mutation Buzz setup preflight
@@ -148,7 +148,7 @@ Telemetry:
 Checks performed:
   - Config directory exists and is writable
   - Installed run402 CLI version and update guidance
-  - Allowance is configured and on a valid rail (x402 / mpp)
+  - Wallet is configured and on a valid rail (x402 / mpp)
   - Keystore has at least one wallet
   - API_BASE is reachable (network check via /health)
   - Active tier resolves and is not 'past_due' / 'frozen' / 'dormant'. A wallet
@@ -177,8 +177,8 @@ Checks performed:
 Buzz mode checks (in order):
   session_shell, node_runtime, run402_cli, buzz_cli, buzz_agent_target,
   run402_api, run402_console, buzz_relay, wallet_profile.
-  Buzz mode is read-only and skips the ordinary allowance, tier, project,
-  operator, runtime-staleness, and source-tree checks.
+  Buzz mode is read-only and skips the ordinary wallet, tier, project,
+  account, runtime-staleness, and source-tree checks.
 
 Exit codes:
   0  — ok: true (advisory warnings never change the exit code)
@@ -264,9 +264,9 @@ export function buildDoctorReport(rawChecks) {
   return { ok: blocking.length === 0, blocking, warnings, checks };
 }
 
-function redactAllowanceForDiagnostics(allowance) {
-  if (!allowance || typeof allowance !== "object") return allowance;
-  const safe = { ...allowance };
+function redactWalletForDiagnostics(localWallet) {
+  if (!localWallet || typeof localWallet !== "object") return localWallet;
+  const safe = { ...localWallet };
   delete safe.privateKey;
   if (typeof safe.funded === "boolean") safe.faucet_used = safe.funded;
   delete safe.funded;
@@ -390,39 +390,39 @@ export async function run(sub, args = []) {
     });
   }
 
-  // 2. Allowance.
-  let allowanceConfigured = false;
-  if (wanted("allowance")) try {
-    const allowance = readAllowance();
-    if (allowance) {
-      allowanceConfigured = true;
+  // 2. Wallet.
+  let walletConfigured = false;
+  if (wanted("wallet")) try {
+    const localWallet = readWallet();
+    if (localWallet) {
+      walletConfigured = true;
       checks.push({
-        name: "allowance",
+        name: "wallet",
         status: "ok",
         value: {
-          rail: allowance.rail,
+          rail: localWallet.rail,
           // Don't surface amounts or addresses unless --verbose; agents
           // checking for config presence don't need wallet details. Never
           // include keystore secrets in diagnostics, even in verbose mode.
-          ...(verbose && { details: redactAllowanceForDiagnostics(allowance) }),
+          ...(verbose && { details: redactWalletForDiagnostics(localWallet) }),
         },
       });
     } else {
       checks.push({
-        name: "allowance",
+        name: "wallet",
         status: "missing",
-        hint: "Run 'run402 init' to create an allowance.",
+        hint: "Run 'run402 init' to create a wallet.",
       });
     }
   } catch (err) {
     checks.push({
-      name: "allowance",
+      name: "wallet",
       status: "error",
       message: err instanceof Error ? err.message : String(err),
     });
   }
 
-  // 3. Project keystore. The wallet itself lives in allowance.json (verified
+  // 3. Project keystore. The wallet itself lives in wallet.json (verified
   // by check 2 above); this checks the per-project keys (anon_key /
   // service_key) that `run402 projects provision` writes. An empty store is
   // normal for fresh installs that haven't provisioned a project yet, so
@@ -435,10 +435,10 @@ export async function run(sub, args = []) {
       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
+      // wallet check above actually passed; pre-init installs are pointed
       // at `run402 init` first.
       ...(projectCount === 0 && {
-        hint: allowanceConfigured
+        hint: walletConfigured
           ? "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'.",
       }),
@@ -539,7 +539,7 @@ export async function run(sub, args = []) {
               : `organization lifecycle is '${lifecycle}' — the control plane is gated until the tier is reactivated`,
         hint: status === "unknown"
           ? "Tier resolved, but organization lifecycle could not be determined. Check `run402 tier status` before assuming the account is healthy."
-          : "Run 'run402 tier set prototype' to subscribe, renew, or reactivate the tier.",
+          : "Run 'run402 tier set prototype' to set, renew, or reactivate the tier.",
       });
     }
   } catch (err) {
@@ -550,41 +550,42 @@ export async function run(sub, args = []) {
     });
   }
 
-  // 6. Operator health snapshot (v1.55 + v1.56 verification attempt detail).
-  // The checks below all ride the SAME operator-status read (runtime_staleness
-  // and recovery_posture reuse the response operator_health already pulled),
+  // 6. Account health snapshot (v1.55 + v1.56 verification attempt detail).
+  // The checks below all ride the SAME `GET /agent/v1/me/status` read
+  // (runtime_staleness and recovery_posture reuse the response account_health
+  // already pulled),
   // so the whole block is gated on wanting ANY — --only runtime_staleness
   // alone still needs this read, but --only-ing none skips it entirely, same
   // "don't do the work of a check nobody asked for" discipline the rest of
   // --only follows.
-  if (wanted("operator_health") || wanted("runtime_staleness") || wanted("recovery_posture")) try {
+  if (wanted("account_health") || wanted("runtime_staleness") || wanted("recovery_posture")) try {
     const sdk = getSdk();
-    const status = await sdk.admin.getOperatorStatus();
+    const status = await sdk.me.status();
     const gaps = [];
-    if (status.operator_contact.email_status !== "verified") {
+    if (status.contact.email_status !== "verified") {
       // v1.56: prefer the structured email_verification.last_challenge.hint
       // over the generic "email not verified" message. The gateway computes
-      // a per-reason remediation hint that's actionable for the operator.
+      // a per-reason remediation hint that's actionable for the reader.
       const ev = status.email_verification;
       const ch = ev?.last_challenge;
       if (ch && ch.hint) {
         const attemptsLine = ch.attempt_count > 0
           ? ` (${ch.attempt_count}/${ch.attempt_count + ch.remaining_attempts} attempts used, ${ch.remaining_attempts} remaining)`
           : "";
-        gaps.push(`operator email not verified${attemptsLine}: ${ch.hint}`);
+        gaps.push(`contact email not verified${attemptsLine}: ${ch.hint}`);
       } else {
-        gaps.push(`operator email not verified (${status.operator_contact.email_status}) — run 'run402 agent contact --email ...' then reply to the challenge`);
+        gaps.push(`contact email not verified (${status.contact.email_status}) — run 'run402 agent contact --email ...' then reply to the challenge`);
       }
     }
-    if (status.operator_contact.passkey_status !== "verified") {
-      gaps.push("operator passkey not bound — run 'run402 agent passkey enroll' after email verification");
+    if (status.contact.passkey_status !== "verified") {
+      gaps.push("contact passkey not bound — run 'run402 login' (or 'run402 agent passkey enroll') after email verification");
     }
     // recovery-event-reachability: org-level reachability of mandatory
     // (recovery/security) notifications. Distinct from the per-wallet contact
     // check above — an org can be reachable via a member's verified email
     // even when this wallet has no contact, and vice versa. Omitted by older
     // gateways.
-    const reach = status.operator_reachability;
+    const reach = status.reachability;
     if (reach && reach.reachable === false) {
       const skipped = reach.skipped_last_90d > 0
         ? ` (${reach.skipped_last_90d} notification(s) already skipped in the last 90 days)`
@@ -599,16 +600,16 @@ export async function run(sub, args = []) {
         gaps.push(`${item.kind}: ${item.detail}`);
       }
     }
-    if (wanted("operator_health")) {
+    if (wanted("account_health")) {
       if (gaps.length > 0) {
         checks.push({
-          name: "operator_health",
+          name: "account_health",
           status: "warning",
           value: { gaps },
           hint: "Address the above gaps; they're what 'run402 notifications' is designed to surface.",
         });
       } else {
-        checks.push({ name: "operator_health", status: "ok" });
+        checks.push({ name: "account_health", status: "ok" });
       }
     }
 
@@ -618,7 +619,7 @@ export async function run(sub, args = []) {
     // gateway's current build — a plain redeploy with unchanged source does
     // NOT refresh it (apply's release diff keys on the source code_hash, not
     // the wrapper). Read-only signal; refreshing is strictly opt-in. Reuses
-    // the operator status fetched above to avoid a second round-trip.
+    // the account status fetched above to avoid a second round-trip.
     if (wanted("runtime_staleness")) {
       const runtime = status.runtime;
       if (runtime && typeof runtime.stale_function_count === "number") {
@@ -644,13 +645,13 @@ export async function run(sub, args = []) {
         checks.push({
           name: "runtime_staleness",
           status: "skipped",
-          ...(verbose && { hint: "operator status has no 'runtime' block; requires v1.69+ gateway." }),
+          ...(verbose && { hint: "account status has no 'runtime' block; requires v1.69+ gateway." }),
         });
       }
     }
 
     // 6c. Org recovery posture (gitvault-recovery-custody). One entry per
-    // vault-owning org the caller can see; rides the same operator-status
+    // vault-owning org the caller can see; rides the same account-status
     // read. Evidence levels, not guarantees: "configured" names what the
     // platform VERIFIED — it can never observe whether an off-platform
     // passkey or saved code still exists. The two headline facts mirror the
@@ -664,7 +665,7 @@ export async function run(sub, args = []) {
         checks.push({
           name: "recovery_posture",
           status: "skipped",
-          ...(verbose && { hint: "operator status has no 'recovery_posture' block; requires a gitvault-recovery-custody gateway." }),
+          ...(verbose && { hint: "account status has no 'recovery_posture' block; requires a gitvault-recovery-custody gateway." }),
         });
       } else if (posture.length === 0) {
         // No vault-owning org in the caller's view — nothing to lose, nothing to advise.
@@ -674,7 +675,7 @@ export async function run(sub, args = []) {
         for (const org of posture) {
           const label = `org ${org.org_id} (${org.vault_count} vault${org.vault_count === 1 ? "" : "s"})`;
           if (org.control_plane_configured === false) {
-            gaps.push(`${label}: no human owner with a working control-plane login — if this org's agent machine dies, nobody can sign in to recover it. Invite a backup human (run402 org invite create ${org.org_id} --email <their-email> --role owner) and have them complete login at console.run402.com.`);
+            gaps.push(`${label}: no human owner with a working control-plane login — if this org's agent machine dies, nobody can sign in to recover it. Invite a backup human (run402 orgs invite create ${org.org_id} --email <their-email> --role owner) and have them complete login at console.run402.com.`);
           }
           if (org.source_backup_configured === false) {
             gaps.push(`${label}: no human member holds a working source-access key — vault history has no member-side decryption backup. Have a member complete source enrollment at console.run402.com/account → Source access.`);
@@ -696,25 +697,24 @@ export async function run(sub, args = []) {
       }
     }
   } catch (err) {
-    // Operator status endpoint may not be reachable if the operator-binding
-    // substrate isn't deployed yet on the target API. Don't fail the whole
+    // The account status endpoint may not be reachable on the target API. Don't fail the whole
     // doctor over it — emit as a soft warning. The runtime-staleness check
     // rides on the same fetch, so skip it for the same reason.
-    if (wanted("operator_health")) checks.push({
-      name: "operator_health",
+    if (wanted("account_health")) checks.push({
+      name: "account_health",
       status: "skipped",
-      message: describeCheckFailure("operator status check", err),
-      ...(verbose && { hint: "GET /agent/v1/operator/status not reachable; requires v1.55+ gateway." }),
+      message: describeCheckFailure("account status check", err),
+      ...(verbose && { hint: "GET /agent/v1/me/status not reachable." }),
     });
     if (wanted("runtime_staleness")) checks.push({
       name: "runtime_staleness",
       status: "skipped",
-      message: describeCheckFailure("operator status check", err),
+      message: describeCheckFailure("account status check", err),
     });
     if (wanted("recovery_posture")) checks.push({
       name: "recovery_posture",
       status: "skipped",
-      message: describeCheckFailure("operator status check", err),
+      message: describeCheckFailure("account status check", err),
     });
   }
 
@@ -735,7 +735,7 @@ export async function run(sub, args = []) {
   // with its own pinned repo id or run402/origin remote, doctor checks THAT
   // vault, not the profile's active project — the same pin > remote >
   // RUN402_PROJECT_ID env > active-project order every other gitvault verb
-  // follows (`gitvault-target.mjs`). An explicit `--project <id>` outranks
+  // follows (`gitvault-target.mjs`). An explicit `--project <project_id>` outranks
   // all of that (the resolver's own top tier), same as every other gitvault
   // verb's `--project`.
   if (wanted("gitvault")) {
@@ -848,7 +848,7 @@ export async function run(sub, args = []) {
         if (gv.gitvault_policy === "required" && !gv.keystore.holds_repo_key) {
           gaps.push(
             "gitvault_policy is 'required' but this machine holds no key for the vault — a deploy from here is refused with GITVAULT_CLIENT_UPGRADE_REQUIRED. " +
-            "Run 'run402 repos create --project <id>' (idempotent; resolves to the existing repo), or 'run402 repos policy grandfathered --reason <why>' to un-gate the project.",
+            "Run 'run402 repos create --project <project_id>' (idempotent; resolves to the existing repo), or 'run402 repos policy grandfathered --reason <why>' to un-gate the project.",
           );
         } else if (gv.gitvault_policy === "required" && !gv.keystore.can_sign) {
           gaps.push("gitvault_policy is 'required' and this keystore is read-only (no signing key) — it can verify but cannot publish the capture a deploy needs");
@@ -921,7 +921,7 @@ export async function run(sub, args = []) {
           status: gaps.length > 0 ? "warning" : "ok",
           value: gaps.length > 0 ? { ...value, gaps } : value,
           hint: (gv.vault === null
-            ? `No vault for this project (that is a normal shape). Allocate one with 'run402 repos create --project <id>'. Keystore: ${gv.keystore.root}`
+            ? `No vault for this project (that is a normal shape). Allocate one with 'run402 repos create --project <project_id>'. Keystore: ${gv.keystore.root}`
             : gv.durability_statement
               ? `Back up ${gv.keystore.root} anyway — ${gv.durability_statement} (covering_recipients: ${gv.covering_recipients})`
               : `Back up ${gv.keystore.root} — whole-machine or whole-keystore loss is terminal for vault history.`) + byoDisclosure,
@@ -978,7 +978,7 @@ export async function run(sub, args = []) {
             details: findings,
           },
           hint: errorFindings.length > 0
-            ? scanDirOverride ? "Findings are from the explicit arbitrary scan directory; they do not establish that an application deploy will be refused." : "Fix the findings in this application. The same scoped source scan gates up and deploy apply."
+            ? scanDirOverride ? "Findings are from the explicit arbitrary scan directory; they do not establish that an application deploy will be refused." : "Fix the findings in this application. The same scoped source scan gates up and deploy."
             : "Source scan emitted warnings (non-blocking). Review and address when convenient.",
         });
       }

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",