run402 2.41.1 → 2.42.0

package/lib/operator.mjs

@@ -23,7 +23,8 @@ import { createServer } from "node:http";
 import { randomBytes, createHash } from "node:crypto";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
 import { getSdk } from "./sdk.mjs";
-import { normalizeArgv, hasHelp, assertKnownFlags } from "./argparse.mjs";
+import { claimWalletOrg, isStepUpRequired } from "#sdk/node";
+import { normalizeArgv, hasHelp, assertKnownFlags, flagValue } from "./argparse.mjs";
 import {
   saveOperatorSession,
   clearOperatorSession,
@@ -55,19 +56,25 @@ Usage:
   run402 operator overview
   run402 operator whoami
   run402 operator logout
+  run402 operator claim-wallet-org [--org <id>] [--name <label>]
 
 Subcommands:
-  login      Sign in via the browser. Default = device-flow READ session (powers
-             'overview'). --loopback = write-capable control-plane session
-             (aws-sso-style, passkey-fresh). --step-up = re-mint a fresh write session.
-  overview   Account view across ALL wallets controlling your email (requires login)
-  whoami     Show the cached session(s) — local, no network
-  logout     Revoke the session server-side and clear the local cache(s)
+  login            Sign in via the browser. Default = device-flow READ session (powers
+                   'overview'). --loopback = write-capable control-plane session
+                   (aws-sso-style, passkey-fresh). --step-up = re-mint a fresh write session.
+  overview         Account view across ALL wallets controlling your email (requires login)
+  whoami           Show the cached session(s) — local, no network
+  logout           Revoke the session server-side and clear the local cache(s)
+  claim-wallet-org Claim an org owned by your wallet's agent into your human identity
+                   (ownership transfer). Dual proof: your write-capable session
+                   ('login --loopback' first) + a fresh signature from the active wallet.
 
 Options:
   --no-open  (login) Do not auto-open the browser; just print the URL.
   --loopback (login) Use the loopback-PKCE write login instead of the device flow.
   --step-up  (login) Re-mint a fresh write session (implies --loopback).
+  --org <id> (claim-wallet-org) Pick which org to claim (only when the wallet owns several).
+  --name <s> (claim-wallet-org) Optional label to set on the claimed org.
 
 Notes:
   - The session is cached at the base config dir, shared across named wallets.
@@ -445,6 +452,64 @@ async function whoami(args) {
   process.exitCode = 1;
 }
 
+/**
+ * Claim a wallet-owned org into your human (console) identity — an ownership
+ * transfer (v1.82). Dual proof: your write-capable control-plane session (run
+ * 'operator login --loopback' first) PLUS a fresh SIWX signature from the active
+ * wallet over a server nonce. The Node convenience runs the whole dance
+ * (read session → challenge → sign → submit). Step-up failures and the
+ * multi-org `select_org` round-trip are surfaced here, not thrown to the user.
+ */
+async function claimWalletOrgCmd(args) {
+  assertKnownFlags(args, ["--help", "-h", "--org", "--name"], ["--org", "--name"]);
+  const orgId = flagValue(args, "--org");
+  const name = flagValue(args, "--name");
+  try {
+    const result = await claimWalletOrg(getSdk(), {
+      orgId: orgId ?? undefined,
+      displayName: name ?? undefined,
+    });
+    // CLI output contract (cli-output-shape): no top-level `status` envelope.
+    // The gateway's discriminator becomes an explicit `claimed` boolean.
+    if (result && result.status === "select_org") {
+      console.log(
+        JSON.stringify(
+          {
+            claimed: false,
+            selectable_orgs: result.selectable_orgs,
+            hint: "Your wallet's agent owns more than one org. Re-run with --org <id> to claim one.",
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+    console.log(
+      JSON.stringify(
+        {
+          claimed: true,
+          org_id: result.org_id,
+          display_name: result.display_name,
+          role: result.role,
+          already_owned: result.already_owned ?? false,
+        },
+        null,
+        2,
+      ),
+    );
+  } catch (err) {
+    if (isStepUpRequired(err)) {
+      return fail({
+        code: "STEP_UP_REQUIRED",
+        message: "Claiming a wallet org needs a fresh passkey step-up.",
+        hint: "Run 'run402 operator login --step-up', then re-run 'run402 operator claim-wallet-org'.",
+      });
+    }
+    reportSdkError(err);
+  }
+}
+
 export async function run(sub, args = []) {
   args = normalizeArgv(args);
   if (!sub || sub === "--help" || sub === "-h" || hasHelp(args)) {
@@ -464,6 +529,9 @@ export async function run(sub, args = []) {
     case "whoami":
       await whoami(args);
       break;
+    case "claim-wallet-org":
+      await claimWalletOrgCmd(args);
+      break;
     default:
       fail({
         code: "BAD_USAGE",

package/lib/org.mjs

@@ -10,64 +10,99 @@ import {
 
 const ROLE_LIST = "owner | admin | developer | billing | viewer";
 
-const HELP = `run402 org — org-owned control plane: identity, membership, invites
+const HELP = `run402 org — organizations: create, label, membership, invites
 
 Usage:
-  run402 org whoami
+  run402 org create [--name <label>]
   run402 org list
-  run402 org audit <billing_account> [--limit N] [--before <cursor>]
-  run402 org member list <billing_account>
-  run402 org member add  <billing_account> <wallet> [--role <role>]
-  run402 org member role <billing_account> <principal_id> <role>
-  run402 org member rm   <billing_account> <principal_id>
-  run402 org invite list   <billing_account>
-  run402 org invite create <billing_account> <email> [--role <role>] [--ttl-hours N]
-  run402 org invite rm     <billing_account> <principal_id>
+  run402 org get    <org>
+  run402 org rename <org> <display_name>   (or: --clear to remove the label)
+  run402 org whoami
+  run402 org audit  <org> [--limit N] [--before <cursor>]
+  run402 org member list <org>
+  run402 org member add  <org> <wallet> [--role <role>]
+  run402 org member role <org> <principal_id> <role>
+  run402 org member rm   <org> <principal_id>
+  run402 org invite list   <org>
+  run402 org invite create <org> <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     <org> <principal_id>
 
 Subcommands:
-  whoami      Resolved principal + org memberships (GET /agent/v1/whoami)
+  create      Create an empty org on the prototype tier (you become owner)
   list        Orgs you are a member of
+  get         Read one org (label + tier + your role)
+  rename      Set or clear an org's display label (owner-only)
+  whoami      Resolved principal + org memberships (GET /agent/v1/whoami)
   member      Manage members (list, add, role, rm) — mutations require owner
   invite      Manage email invites (list, create, rm) — mutations require owner
   audit       Control-plane audit trail for an org (admin+)
 
 Notes:
-  - A wallet AUTHENTICATES; the org (billing account) owns projects. Membership/role authorizes.
+  - A wallet AUTHENTICATES; an org owns projects. Membership/role authorizes.
   - Roles: ${ROLE_LIST}. Member/invite changes need an active owner.
+  - create/rename/member/invite are step-up gated for control-plane sessions.
   - Removing/demoting the org's only active owner fails with 409 LAST_OWNER.
   - JSON in, JSON out.
 
 Examples:
-  run402 org whoami
-  run402 org member list ba_abc
-  run402 org member add ba_abc 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
-  run402 org member role ba_abc prn_xyz owner
-  run402 org invite create ba_abc dev@example.com --role developer
-  run402 org audit ba_abc --limit 50
+  run402 org create --name "Kychee"
+  run402 org list
+  run402 org get org_abc
+  run402 org rename org_abc "New Name"
+  run402 org rename org_abc --clear
+  run402 org member add org_abc 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --role admin
+  run402 org invite create org_abc dev@example.com --role developer
+  run402 org audit org_abc --limit 50
 `;
 
 const SUB_HELP = {
-  whoami: `run402 org whoami — resolved principal + org memberships
+  create: `run402 org create — create an empty org (prototype tier; you become owner)
 
 Usage:
-  run402 org whoami
+  run402 org create [--name <label>]
 
-Calls GET /agent/v1/whoami. Returns the control-plane principal (id/type/displayName/createdAt),
-authenticator_id, and every org membership with role + status. REMOTE identity; for local
-wallet/profile state use 'run402 status'.
+The label is an optional free-text name (non-unique, not an id). Omit for an
+unlabeled org. There is no tier at create — paid tiers are a separate flow.
+Step-up gated for control-plane sessions; the free-org cap may apply.
 `,
   list: `run402 org list — orgs you are a member of
 
 Usage:
   run402 org list
+`,
+  get: `run402 org get — read one org (label + tier + your role)
+
+Usage:
+  run402 org get <org>
+
+Any active member may read. A non-member (including a guessed id) gets the same
+non-revealing 403.
+`,
+  rename: `run402 org rename — set or clear an org's display label (owner-only)
+
+Usage:
+  run402 org rename <org> <display_name>
+  run402 org rename <org> --clear
+
+Owner-only + step-up gated. Pass --clear (or an empty display_name) to remove
+the label.
+`,
+  whoami: `run402 org whoami — resolved principal + org memberships
+
+Usage:
+  run402 org whoami
+
+Calls GET /agent/v1/whoami. Returns the control-plane principal (id/type/displayName/createdAt),
+authenticator_id, and every org membership (org_id, display_name, role, status). REMOTE identity;
+for local wallet/profile state use 'run402 status'.
 `,
   member: `run402 org member — manage org members
 
 Usage:
-  run402 org member list <billing_account>
-  run402 org member add  <billing_account> <wallet> [--role <role>]
-  run402 org member role <billing_account> <principal_id> <role>
-  run402 org member rm   <billing_account> <principal_id>
+  run402 org member list <org>
+  run402 org member add  <org> <wallet> [--role <role>]
+  run402 org member role <org> <principal_id> <role>
+  run402 org member rm   <org> <principal_id>
 
 Roles: ${ROLE_LIST} (add defaults to developer). Mutations require an active owner.
 Demoting/removing the org's only active owner fails with 409 LAST_OWNER.
@@ -75,9 +110,9 @@ Demoting/removing the org's only active owner fails with 409 LAST_OWNER.
   invite: `run402 org invite — manage email invites
 
 Usage:
-  run402 org invite list   <billing_account>
-  run402 org invite create <billing_account> <email> [--role <role>] [--ttl-hours N]
-  run402 org invite rm     <billing_account> <principal_id>
+  run402 org invite list   <org>
+  run402 org invite create <org> <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     <org> <principal_id>
 
 An invite is claimed at the recipient's first login. Mutations require an active owner
 (plus step-up when driven by a control-plane session).
@@ -85,31 +120,76 @@ An invite is claimed at the recipient's first login. Mutations require an active
   audit: `run402 org audit — control-plane audit trail
 
 Usage:
-  run402 org audit <billing_account> [--limit N] [--before <cursor>]
+  run402 org audit <org> [--limit N] [--before <cursor>]
 
 Requires an admin+ membership on the org. Newest-first; page with --before.
 `,
 };
 
-// ── Top-level: whoami / list / audit ───────────────────────────────────────────
+// ── Top-level: create / list / get / rename / whoami / audit ────────────────────
+
+async function create(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = ["--name"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, { min: 0, max: 0, command: "run402 org create [--name <label>]" });
+  const name = flagValue(a, "--name");
+  try {
+    console.log(JSON.stringify(await getSdk().orgs.create({ displayName: name ?? undefined }), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org list" });
+  try {
+    console.log(JSON.stringify({ orgs: await getSdk().orgs.list() }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
 
 async function whoami(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
   requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org whoami" });
   try {
-    console.log(JSON.stringify(await getSdk().org.whoami(), null, 2));
+    console.log(JSON.stringify(await getSdk().orgs.whoami(), null, 2));
   } catch (err) {
     reportSdkError(err);
   }
 }
 
-async function list(args) {
+async function get(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
-  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org list" });
+  const [org] = requirePositionalCount(a, [], {
+    min: 1, max: 1, command: "run402 org get <org>", missing: "Missing <org>.",
+  });
   try {
-    console.log(JSON.stringify({ orgs: await getSdk().org.list() }, null, 2));
+    console.log(JSON.stringify(await getSdk().org(org).get(), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function rename(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--clear", "--help", "-h"]);
+  const clear = a.includes("--clear");
+  const positionals = requirePositionalCount(a, [], {
+    min: clear ? 1 : 2,
+    max: clear ? 1 : 2,
+    command: "run402 org rename <org> <display_name>",
+    missing: clear ? "Missing <org>." : "Missing <org> and/or <display_name> (or pass --clear).",
+  });
+  const org = positionals[0];
+  const displayName = clear ? null : positionals[1];
+  try {
+    console.log(JSON.stringify(await getSdk().org(org).rename(displayName), null, 2));
   } catch (err) {
     reportSdkError(err);
   }
@@ -119,17 +199,17 @@ async function audit(args) {
   const a = normalizeArgv(args);
   const valueFlags = ["--limit", "--before"];
   assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
-  const [ba] = requirePositionalCount(a, valueFlags, {
+  const [org] = requirePositionalCount(a, valueFlags, {
     min: 1,
     max: 1,
-    command: "run402 org audit <billing_account>",
-    missing: "Missing <billing_account>.",
+    command: "run402 org audit <org>",
+    missing: "Missing <org>.",
   });
   const limitFlag = flagValue(a, "--limit");
   const before = flagValue(a, "--before");
   const limit = limitFlag === null ? undefined : parseIntegerFlag("--limit", limitFlag, { min: 1, max: 1000 });
   try {
-    const events = await getSdk().org.audit(ba, { limit, before: before ?? undefined });
+    const events = await getSdk().org(org).audit({ limit, before: before ?? undefined });
     console.log(JSON.stringify({ events }, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -153,11 +233,11 @@ async function runMember(args) {
   if (memberAction === "list") {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--help", "-h"]);
-    const [ba] = requirePositionalCount(a, [], {
-      min: 1, max: 1, command: "run402 org member list <billing_account>", missing: "Missing <billing_account>.",
+    const [org] = requirePositionalCount(a, [], {
+      min: 1, max: 1, command: "run402 org member list <org>", missing: "Missing <org>.",
     });
     try {
-      console.log(JSON.stringify({ members: await getSdk().org.members.list(ba) }, null, 2));
+      console.log(JSON.stringify({ members: await getSdk().org(org).members.list() }, null, 2));
     } catch (err) {
       reportSdkError(err);
     }
@@ -168,12 +248,12 @@ async function runMember(args) {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--role", "--help", "-h"], ["--role"]);
     const role = flagValue(a, "--role");
-    const [ba, wallet] = requirePositionalCount(a, ["--role"], {
-      min: 2, max: 2, command: "run402 org member add <billing_account> <wallet> [--role <role>]",
-      missing: "Missing <billing_account> and/or <wallet>.",
+    const [org, wallet] = requirePositionalCount(a, ["--role"], {
+      min: 2, max: 2, command: "run402 org member add <org> <wallet> [--role <role>]",
+      missing: "Missing <org> and/or <wallet>.",
     });
     try {
-      const res = await getSdk().org.members.add(ba, { wallet, role: role || undefined });
+      const res = await getSdk().org(org).members.add({ wallet, role: role || undefined });
       console.log(JSON.stringify(res, null, 2));
     } catch (err) {
       reportSdkError(err);
@@ -184,12 +264,12 @@ async function runMember(args) {
   if (memberAction === "role") {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--help", "-h"]);
-    const [ba, principalId, role] = requirePositionalCount(a, [], {
-      min: 3, max: 3, command: "run402 org member role <billing_account> <principal_id> <role>",
-      missing: "Missing <billing_account>, <principal_id>, and/or <role>.",
+    const [org, principalId, role] = requirePositionalCount(a, [], {
+      min: 3, max: 3, command: "run402 org member role <org> <principal_id> <role>",
+      missing: "Missing <org>, <principal_id>, and/or <role>.",
     });
     try {
-      console.log(JSON.stringify(await getSdk().org.members.setRole(ba, principalId, role), null, 2));
+      console.log(JSON.stringify(await getSdk().org(org).members.setRole(principalId, role), null, 2));
     } catch (err) {
       reportSdkError(err);
     }
@@ -199,12 +279,12 @@ async function runMember(args) {
   if (memberAction === "rm") {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--help", "-h"]);
-    const [ba, principalId] = requirePositionalCount(a, [], {
-      min: 2, max: 2, command: "run402 org member rm <billing_account> <principal_id>",
-      missing: "Missing <billing_account> and/or <principal_id>.",
+    const [org, principalId] = requirePositionalCount(a, [], {
+      min: 2, max: 2, command: "run402 org member rm <org> <principal_id>",
+      missing: "Missing <org> and/or <principal_id>.",
     });
     try {
-      console.log(JSON.stringify(await getSdk().org.members.revoke(ba, principalId), null, 2));
+      console.log(JSON.stringify(await getSdk().org(org).members.revoke(principalId), null, 2));
     } catch (err) {
       reportSdkError(err);
     }
@@ -231,11 +311,11 @@ async function runInvite(args) {
   if (inviteAction === "list") {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--help", "-h"]);
-    const [ba] = requirePositionalCount(a, [], {
-      min: 1, max: 1, command: "run402 org invite list <billing_account>", missing: "Missing <billing_account>.",
+    const [org] = requirePositionalCount(a, [], {
+      min: 1, max: 1, command: "run402 org invite list <org>", missing: "Missing <org>.",
     });
     try {
-      console.log(JSON.stringify({ invites: await getSdk().org.invites.list(ba) }, null, 2));
+      console.log(JSON.stringify({ invites: await getSdk().org(org).invites.list() }, null, 2));
     } catch (err) {
       reportSdkError(err);
     }
@@ -248,13 +328,13 @@ async function runInvite(args) {
     assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
     const role = flagValue(a, "--role");
     const ttlFlag = flagValue(a, "--ttl-hours");
-    const [ba, email] = requirePositionalCount(a, valueFlags, {
-      min: 2, max: 2, command: "run402 org invite create <billing_account> <email> [--role <role>]",
-      missing: "Missing <billing_account> and/or <email>.",
+    const [org, email] = requirePositionalCount(a, valueFlags, {
+      min: 2, max: 2, command: "run402 org invite create <org> <email> [--role <role>]",
+      missing: "Missing <org> and/or <email>.",
     });
     const inviteTtlHours = ttlFlag === null ? undefined : parseIntegerFlag("--ttl-hours", ttlFlag, { min: 1, max: 8760 });
     try {
-      const res = await getSdk().org.invites.create(ba, { email, role: role || "developer", inviteTtlHours });
+      const res = await getSdk().org(org).invites.create({ email, role: role || "developer", inviteTtlHours });
       console.log(JSON.stringify(res, null, 2));
     } catch (err) {
       reportSdkError(err);
@@ -265,12 +345,12 @@ async function runInvite(args) {
   if (inviteAction === "rm") {
     const a = normalizeArgv(rest);
     assertKnownFlags(a, ["--help", "-h"]);
-    const [ba, principalId] = requirePositionalCount(a, [], {
-      min: 2, max: 2, command: "run402 org invite rm <billing_account> <principal_id>",
-      missing: "Missing <billing_account> and/or <principal_id>.",
+    const [org, principalId] = requirePositionalCount(a, [], {
+      min: 2, max: 2, command: "run402 org invite rm <org> <principal_id>",
+      missing: "Missing <org> and/or <principal_id>.",
     });
     try {
-      console.log(JSON.stringify(await getSdk().org.invites.revoke(ba, principalId), null, 2));
+      console.log(JSON.stringify(await getSdk().org(org).invites.revoke(principalId), null, 2));
     } catch (err) {
       reportSdkError(err);
     }
@@ -300,8 +380,11 @@ export async function run(sub, args) {
     process.exit(0);
   }
   switch (sub) {
-    case "whoami": await whoami(args); break;
+    case "create": await create(args); break;
     case "list": await list(args); break;
+    case "get": await get(args); break;
+    case "rename": await rename(args); break;
+    case "whoami": await whoami(args); break;
     case "audit": await audit(args); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);

package/lib/projects.mjs

@@ -11,7 +11,7 @@ Usage:
 
 Subcommands:
   quote                                   Show pricing tiers
-  provision [--tier <tier>] [--name <n>]  Provision a new Postgres project (pays via x402)
+  provision [--tier <tier>] [--name <n>] [--org <id>]  Provision a new Postgres project (pays via x402)
   use   <id>                              Set the active project (used as default for other commands)
   list                                    List all your projects (IDs, URLs, active marker)
   info  [id]                              Show project details: REST URL, keys
@@ -79,11 +79,13 @@ const SUB_HELP = {
   provision: `run402 projects provision — Provision a new Postgres project
 
 Usage:
-  run402 projects provision [--tier <tier>] [--name <name>]
+  run402 projects provision [--tier <tier>] [--name <name>] [--org <id>]
 
 Options:
   --tier <tier>       Tier for the new project (default: prototype)
   --name <name>       Human-readable name for the project
+  --org <id>          Provision into an EXISTING org (needs developer+ on it).
+                      Omit for the cold-start path. Tier is org-governed.
 
 Notes:
   - Payment is automatic via x402; requires a funded allowance
@@ -93,6 +95,7 @@ Examples:
   run402 projects provision
   run402 projects provision --tier prototype
   run402 projects provision --tier hobby --name my-app
+  run402 projects provision --org org_abc123
 `,
   sql: `run402 projects sql — Run a SQL query against a project's database
 
@@ -184,12 +187,24 @@ async function quote() {
 }
 
 async function provision(args) {
-  const opts = { tier: "prototype", name: undefined };
+  const opts = { tier: "prototype", name: undefined, orgId: undefined };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
     // Use !== undefined so an empty-string value is captured (and rejected
     // below) rather than silently dropped by the falsy-check pattern (GH-176).
     if (args[i] === "--name" && args[i + 1] !== undefined) opts.name = args[++i];
+    // --org targets an EXISTING org (v1.82); caller needs developer+ on it.
+    // Omitted = cold-start. Tier is org-governed, so --tier is irrelevant here
+    // (the gateway ignores a client-supplied tier in all cases).
+    if (args[i] === "--org" && args[i + 1] !== undefined) opts.orgId = args[++i];
+  }
+  if (opts.orgId === "") {
+    fail({
+      code: "BAD_USAGE",
+      message: "--org must not be empty.",
+      details: { field: "--org" },
+      hint: "Pass an org id (run402 org list), or omit --org for the cold-start path.",
+    });
   }
   // Validate --name when provided. Omitted --name lets the server pick a
   // default. The same envelope should also be enforced server-side (GH-176).
@@ -225,7 +240,7 @@ async function provision(args) {
 
   const activeBefore = getActiveProjectId();
   try {
-    const data = await getSdk().projects.provision({ tier: opts.tier, name: opts.name });
+    const data = await getSdk().projects.provision({ tier: opts.tier, name: opts.name, orgId: opts.orgId });
     const activeAfter = getActiveProjectId();
     const out = { ...data };
     if (activeBefore && activeAfter && activeBefore !== activeAfter) {
@@ -555,7 +570,7 @@ async function deleteProject(projectId, args = []) {
 }
 
 const FLAGS_BY_SUB = {
-  provision: { known: ["--tier", "--name"], values: ["--tier", "--name"] },
+  provision: { known: ["--tier", "--name", "--org"], values: ["--tier", "--name", "--org"] },
   sql: { known: ["--file", "--params"], values: ["--file", "--params"] },
   costs: { known: ["--window"], values: ["--window"] },
   "apply-expose": { known: ["--file"], values: ["--file"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "2.41.1",
+  "version": "2.42.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/control-plane-credentials.d.ts

@@ -9,7 +9,7 @@
  * / `passkeyVerify` / the loopback-PKCE `exchangeCliToken`, then:
  *
  *   const r = run402({ credentials: controlPlaneSessionCredentials({ token }) });
- *   await r.org.whoami();            // resolves the principal + memberships
+ *   await r.orgs.whoami();           // resolves the principal + memberships
  *
  * High-stakes writes still require a fresh passkey — an `email`/`oauth` session
  * gets {@link StepUpRequiredError}; run the step-up ceremony

package/sdk/dist/control-plane-credentials.js

@@ -9,7 +9,7 @@
  * / `passkeyVerify` / the loopback-PKCE `exchangeCliToken`, then:
  *
  *   const r = run402({ credentials: controlPlaneSessionCredentials({ token }) });
- *   await r.org.whoami();            // resolves the principal + memberships
+ *   await r.orgs.whoami();           // resolves the principal + memberships
  *
  * High-stakes writes still require a fresh passkey — an `email`/`oauth` session
  * gets {@link StepUpRequiredError}; run the step-up ceremony

package/sdk/dist/index.d.ts

@@ -30,7 +30,7 @@ import { Deploy } from "./namespaces/deploy.js";
 import { Ci } from "./namespaces/ci.js";
 import { Jobs } from "./namespaces/jobs.js";
 import { Operator } from "./namespaces/operator.js";
-import { Org } from "./namespaces/org.js";
+import { Orgs, ScopedOrg } from "./namespaces/org.js";
 import { Grants } from "./namespaces/grants.js";
 import type { ContentSource, FileSet } from "./namespaces/deploy.types.js";
 import { ScopedRun402 } from "./scoped.js";
@@ -85,12 +85,13 @@ export declare class Run402 {
      */
     readonly operator: Operator;
     /**
-     * Org-owned control plane (gateway v1.77+): resolve the principal +
-     * memberships (`org.whoami()`) and manage org membership (`list`, `members`,
-     * `addMember`, `setRole`, `removeMember` — owner-gated). Distinct from the
-     * local, network-free {@link Run402.whoami}.
+     * Org collection + identity (gateway v1.77+, first-class in v1.82):
+     * `r.orgs.create()` / `list()` / `whoami()`. For operations on a single org by
+     * id use the scoped sub-client {@link Run402.org} (`r.org(id).get()` /
+     * `rename()` / `members.*` / `invites.*` / `audit()`). Distinct from the local,
+     * network-free {@link Run402.whoami}.
      */
-    readonly org: Org;
+    readonly orgs: Orgs;
     /**
      * Per-project capability grants for agent/CI principals. Also available
      * project-scoped as `r.project(id).grants`.
@@ -128,6 +129,14 @@ export declare class Run402 {
      * use {@link project} instead.
      */
     useProject(id: string): Promise<ScopedRun402>;
+    /**
+     * Return an org-scoped sub-client with `id` pre-bound — the org analog of
+     * {@link Run402.project}. Instance operations (`get`, `rename`, `members.*`,
+     * `invites.*`, `audit`) drop their org-id argument. Synchronous: an org id is
+     * always explicit (there is no "active org" fallback). Collection/identity
+     * operations (`create`, `list`, `whoami`) live on {@link Run402.orgs}.
+     */
+    org(id: string): ScopedOrg;
     /**
      * Identify the active wallet and project: `{ local_label, server_label,
      * address, activeProject }`. `local_label` is the local wallet/profile
@@ -208,7 +217,7 @@ export type * from "./namespaces/jobs.js";
 export type * from "./namespaces/operator.js";
 export { OperatorSession } from "./namespaces/operator-session.js";
 export type * from "./namespaces/operator-session.js";
-export { Org, OrgMembers, OrgInvites } from "./namespaces/org.js";
+export { Orgs, ScopedOrg, OrgMembers, OrgInvites } from "./namespaces/org.js";
 export type * from "./namespaces/org.types.js";
 export { Grants } from "./namespaces/grants.js";
 export type * from "./namespaces/grants.types.js";