@dench.com/cli 0.4.9 → 2.0.1

package/dench.ts

@@ -73,7 +73,7 @@ type ConfigFile = {
    * Explicit user choice of which Dench backend to talk to by default,
    * set via `dench backend set <local|staging|prod|<url>>`. Takes
    * precedence over the legacy `currentHost` field (which used to be
-   * silently updated by every `dench login` and caused the CLI to
+   * silently updated by every `dench signin` and caused the CLI to
    * silently follow the last-logged-in environment).
    *
    * Resolution order in `resolveHost`:
@@ -164,8 +164,8 @@ const api = {
       agentUpdateTaskStatus: makeFunctionReference<"mutation">(
         "functions/agentWorkspace:agentUpdateTaskStatus",
       ),
-      createAgentLoginRequest: makeFunctionReference<"mutation">(
-        "functions/agentWorkspace:createAgentLoginRequest",
+      createSignInRequest: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:createSignInRequest",
       ),
       devAppendLog: makeFunctionReference<"mutation">(
         "functions/agentWorkspace:devAppendLog",
@@ -182,14 +182,11 @@ const api = {
       devListWorkspaceOverview: makeFunctionReference<"query">(
         "functions/agentWorkspace:devListWorkspaceOverview",
       ),
-      devRegisterAgent: makeFunctionReference<"mutation">(
-        "functions/agentWorkspace:devRegisterAgent",
-      ),
       devRequestApproval: makeFunctionReference<"mutation">(
         "functions/agentWorkspace:devRequestApproval",
       ),
-      pollAgentLoginRequest: makeFunctionReference<"mutation">(
-        "functions/agentWorkspace:pollAgentLoginRequest",
+      pollSignInRequest: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:pollSignInRequest",
       ),
       whatCanIDoHere: makeFunctionReference<"query">(
         "functions/agentWorkspace:whatCanIDoHere",
@@ -336,7 +333,7 @@ function normalizeCliError(error: unknown): CliError {
       nextActions: [
         "Check that DENCH_DEV_AGENT_KEY in your shell matches the Convex deployment env.",
         "Use --dev only for a local/dev Convex deployment configured with that key.",
-        "For normal terminal usage, run dench login or set DENCH_API_KEY + CONVEX_URL.",
+        "For normal terminal usage, run dench signin or set DENCH_API_KEY + CONVEX_URL.",
       ],
     });
   }
@@ -344,7 +341,7 @@ function normalizeCliError(error: unknown): CliError {
     return new CliError("Dev CRM access is disabled in production", {
       code: "dev_access_disabled",
       nextActions: [
-        "Remove --dev and run dench login for terminal access.",
+        "Remove --dev and run dench signin for terminal access.",
         "Or use DENCH_API_KEY + CONVEX_URL for sandbox/automation access.",
       ],
     });
@@ -354,8 +351,8 @@ function normalizeCliError(error: unknown): CliError {
       code: "invalid_api_key",
       nextActions: [
         "Check DENCH_API_KEY and CONVEX_URL point to the same organization/deployment.",
-        "Unset DENCH_API_KEY to use a saved dench login session instead.",
-        "Or run dench login to create a new terminal session.",
+        "Unset DENCH_API_KEY to use a saved dench signin session instead.",
+        "Or run dench signin to create a new terminal session.",
       ],
     });
   }
@@ -423,10 +420,11 @@ function help() {
   console.log(`Dench CLI
 
 Usage:
-  dench onboard [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
-  dench setup [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
-  dench what-can-i-do [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
-  dench login [--host ${DEFAULT_HOST}] [--name "Claude Code Agent"] [--kind <kind>] [--no-open]
+  dench signin [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench signin --new-workspace --org-name "Workspace" [--kind <kind>] [--name "AI Agent - Project"]
+  dench signin --email user@example.com [--new-workspace --org-name "Workspace"] [--kind <kind>] [--name "AI Agent - Project"]
+  dench signin --org <workspace-slug> [--kind <kind>] [--name "AI Agent - Project"]
+  dench upgrade [--tier pro|max] [--cycle monthly|yearly] [--no-open] [--json]
   dench sessions [--host <host>] [--json]
   dench use <session-key-or-workspace-slug> [--host <host>] [--json]
   dench logout [session-key-or-workspace-slug] [--session <key-or-scope>] [--host <host>] [--all] [--json]
@@ -570,14 +568,18 @@ Billing:
   dench billing topup --amount 5 creates a Stripe Checkout link for the human to pay.
 
 Agent setup:
-  dench onboard wraps login (when needed), workspace orientation, tasks, tools,
-  suggested work, memory, and next recommended actions.
+  dench signin is the only auth surface. Two transports (browser link
+  by default, OTP paste-back with --email <addr>) cover both intents:
+  signing in to an existing workspace or creating a new free CRM-only
+  workspace (--new-workspace --org-name "<name>"). New workspaces have
+  full CRM access; run \`dench upgrade\` to unlock chat, file sync,
+  enrichment, and image generation.
   --kind accepts any string. Suggested values: claude_code, codex, cursor,
   hermes, openclaw, or any custom kind (e.g. aider, goose, internal_orchestrator).
   Defaults to "other" when omitted. Values are normalized to lowercase
   snake_case before send (e.g. "Claude Code" -> claude_code).
-  After login approval, run dench status --mine --json and dench tasks --json.
-  Use dench memory and dench artifacts to continue from durable context.
+  After sign-in, run dench context --json and dench crm objects list --json
+  to verify the workspace + CRM are wired up.
   Do not create, claim, or log a setup task by default.
 
 Backends and hosts:
@@ -602,7 +604,7 @@ Dev fallback (run against a local Convex deployment with a dev key):
 
 Advanced:
   For long-lived agents or when the human asks:
-    DENCH_SESSION_KEY=stable-agent-id dench login
+    DENCH_SESSION_KEY=stable-agent-id dench signin
     DENCH_SESSION_KEY=stable-agent-id dench logout
     DENCH_SESSION_KEY=stable-agent-id dench status
 `);
@@ -621,7 +623,7 @@ Usage:
 
 Auth:
   All commands authenticate with DENCH_API_KEY (Bearer) directly to the
-  Dench Cloud Gateway. No \`dench login\` agent session is required —
+  Dench Cloud Gateway. No \`dench signin\` agent session is required —
   inside a Dench sandbox the key is baked into the env automatically;
   outside, export DENCH_API_KEY=<key> first.
 
@@ -669,39 +671,46 @@ be converted into a workspace task.
 `);
 }
 
-function onboardHelp() {
-  console.log(`Dench onboard
-
-Usage:
-  dench onboard [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
-  dench setup [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
-  dench what-can-i-do [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
-
-Logs in if needed, then shows what this agent can do here: workspace rules,
-open work, suggested work, connected-tool commands, memory, approvals, and
-next actions.
-`);
-}
-
-function loginHelp() {
-  console.log(`Dench login
+function signinHelp() {
+  console.log(`Dench signin
 
 Usage:
-  dench login [--name "AI Agent - Billing Repo"] [--kind <kind>] [--host <host>] [--no-open]
-
-Agent kind:
-  --kind accepts any string. Defaults to "other" when omitted.
-  Suggested values: claude_code, codex, cursor, hermes, openclaw, or any
-  custom kind such as aider, goose, or some_custom_agent. Values are
-  normalized to lowercase snake_case before send (e.g. "Claude Code"
-  becomes claude_code, "my agent" becomes my_agent).
-
-Agent setup:
-  Claude Code: dench login --kind claude_code --name "Claude Code Agent - Project"
-  Codex: dench login --kind codex --name "Codex Agent - Project"
-  Cursor: dench login --kind cursor --name "Cursor Agent - Project"
-  Custom: dench login --kind some_custom_agent --name "My Agent - Project"
-  After approval, run dench status --mine --json and dench tasks --json.
+  dench signin [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench signin --new-workspace --org-name "Workspace Name" [--kind <kind>] [--name "AI Agent - Project"]
+  dench signin --email user@example.com [--new-workspace --org-name "Workspace Name"] [--kind <kind>] [--name "AI Agent - Project"]
+  dench signin --org <workspace-slug> [--kind <kind>] [--name "AI Agent - Project"]
+
+Signs in a CLI agent to a Dench workspace. Two transport modes:
+
+  Browser (default): opens a one-click approval URL. The human picks
+    or creates a workspace in the browser, then the CLI saves the
+    session token. Use --no-open to print the link instead.
+
+  OTP (with --email): prompts for the 6-digit code the user receives
+    by email; never opens a browser. Useful for headless / remote
+    shells.
+
+Intents:
+
+  Sign in to existing workspace (default): the user picks one of
+    their admin workspaces in the browser. With OTP, the CLI prompts
+    when more than one admin workspace exists.
+
+  --new-workspace --org-name "<name>": creates a new FREE CRM-only
+    workspace with that name. Free workspaces have full CRM access;
+    chat, file sync, enrichment, and image-gen are paywalled — run
+    \`dench upgrade\` to unlock those.
+
+Agent identity:
+  --kind accepts any string. Suggested values: claude_code, codex,
+    cursor, hermes, openclaw, or any custom kind. Values are
+    normalized to lowercase snake_case (e.g. "Claude Code" \u2192
+    claude_code). Defaults to "other".
+  --name is a human-friendly label, e.g. "Cursor Agent - Billing Repo".
+
+After sign-in, run \`dench context --json\` to confirm the active
+workspace and agent, then \`dench crm objects list --json\` to verify
+CRM access.
 `);
 }
 
@@ -753,7 +762,7 @@ Usage:
 
 Lists all external apps connected to this organization (Slack, Gmail,
 GitHub, etc.). Authenticates with DENCH_API_KEY (Bearer) directly to the
-Dench Cloud Gateway — no \`dench login\` agent session required. Alias
+Dench Cloud Gateway — no \`dench signin\` agent session required. Alias
 for \`dench tool status\`.
 `);
 }
@@ -786,7 +795,7 @@ What this does:
   The default Dench backend is production (${PRODUCTION_HOST}). "dench backend set"
   stores an explicit override in ~/.dench/config.json so every future
   "dench" invocation talks to that backend by default. Use it instead of
-  relying on a stale currentHost from a past "dench login".
+  relying on a stale currentHost from a past "dench signin".
 
   Setting the backend to "local" also opts the CLI into auto-loading
   .env and .env.local from the dench.com workspace at startup, which is
@@ -810,7 +819,7 @@ function resolveHost(config: ConfigFile | undefined, _scope: SessionScope) {
   // represents an explicit user choice. Production wins on fresh
   // installs (no flags, no env, no config) — which is the safe default
   // for an agent CLI. The per-scope `currentHosts[scope.key]` map is
-  // intentionally NOT consulted here so that a past `dench login
+  // intentionally NOT consulted here so that a past `dench signin
   // --host http://localhost:3000` doesn't silently keep routing every
   // future command at local dev.
   return resolveHostFromArgs(filteredArgs, config?.defaultBackend);
@@ -854,19 +863,6 @@ function workspaceLabel(session: StoredSession) {
     : session.organization.name;
 }
 
-function loginNextCommandsMessage(
-  session: StoredSession,
-  stableSessionKey: string | undefined,
-) {
-  const workspaceName = session.organization?.name ?? "unknown workspace";
-  const workspaceSlug = session.organization?.slug ?? "unknown";
-  const agentName = session.agent?.name ?? "unknown agent";
-  const stableKeyText = stableSessionKey
-    ? ` Stable session key: ${stableSessionKey}.`
-    : "";
-  return `Next commands will use workspace ${workspaceName} (${workspaceSlug}) as ${agentName}.${stableKeyText}`;
-}
-
 function ambiguousSessionMessage(
   config: ConfigFile,
   scope: SessionScope,
@@ -970,11 +966,12 @@ function backendSnapshot(config: ConfigFile) {
     : null;
   const envHost = process.env.DENCH_HOST?.trim() || null;
   const argBackend =
-    option("--backend") ?? (hasFlag("--prod")
+    option("--backend") ??
+    (hasFlag("--prod")
       ? "production"
       : hasFlag("--staging")
         ? "staging"
-        : option("--host") ?? null);
+        : (option("--host") ?? null));
 
   let source: "flag" | "env" | "config" | "default";
   if (argBackend) source = "flag";
@@ -1082,7 +1079,9 @@ async function backendSet() {
       "Local backend selected. dench will now also load .env / .env.local from the workspace so GATEWAY_URL etc. are picked up.",
     );
   }
-  print("Future `dench` commands without --prod/--staging/--host will target this backend.");
+  print(
+    "Future `dench` commands without --prod/--staging/--host will target this backend.",
+  );
 }
 
 async function backendClear() {
@@ -1539,29 +1538,183 @@ async function discoverConvexUrl(host: string) {
   return payload.convexUrl;
 }
 
-async function login() {
+/**
+ * Read a single line from stdin. Used by `dench signin --email` for
+ * the OTP code and (when the user has multiple admin workspaces) the
+ * org-picker prompt. Returns the trimmed line or throws if stdin
+ * isn't a TTY — callers can pre-supply the value via flags to avoid
+ * the prompt in CI / non-interactive shells.
+ */
+async function promptLine(question: string): Promise<string> {
+  if (!process.stdin.isTTY) {
+    throw new CliError(
+      `Non-interactive shell: pass the answer to "${question}" via a CLI flag instead of prompting.`,
+      { code: "stdin_not_tty" },
+    );
+  }
+  process.stdout.write(question);
+  return await new Promise<string>((resolve, reject) => {
+    let data = "";
+    const onData = (chunk: Buffer | string) => {
+      data += chunk.toString();
+      if (data.includes("\n")) {
+        cleanup();
+        resolve(data.trim());
+      }
+    };
+    const onErr = (err: Error) => {
+      cleanup();
+      reject(err);
+    };
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.removeListener("error", onErr);
+      process.stdin.pause();
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+    process.stdin.on("error", onErr);
+  });
+}
+
+type SignInIntent = "join_existing" | "create_workspace";
+
+function signinNextCommandsMessage(
+  session: StoredSession,
+  stableSessionKey: string | undefined,
+) {
+  const workspaceName = session.organization?.name ?? "unknown workspace";
+  const workspaceSlug = session.organization?.slug ?? "unknown";
+  const agentName = session.agent?.name ?? "unknown agent";
+  const stableKeyText = stableSessionKey
+    ? ` Stable session key: ${stableSessionKey}.`
+    : "";
+  return `Signed in. Next commands will use workspace ${workspaceName} (${workspaceSlug}) as ${agentName}.${stableKeyText}`;
+}
+
+/**
+ * `dench signin` — the single unified CLI auth entry point.
+ *
+ * Two transports (browser link or OTP) × two intents (join existing
+ * workspace or create a new free CRM-only workspace). Replaces the
+ * deprecated `dench login`, `dench onboard`, `dench setup`,
+ * `dench what-can-i-do`, and `dench register` commands.
+ *
+ * Flag matrix:
+ *
+ *   (no flags)                       Browser link, join existing.
+ *   --new-workspace --org-name "X"   Browser link, create new free workspace.
+ *   --email <addr>                   OTP flow, join existing.
+ *   --email + --new-workspace ...    OTP flow, create new free workspace.
+ *   --org <slug-or-id>               Skip the org picker (existing workspaces).
+ *
+ * Both transports save the resulting `dch_agent_*` session to
+ * `~/.dench/config.json` via `saveSession()` — identical shape to the
+ * previous login flow, so `dench logout` / `dench use` keep working.
+ */
+async function signin() {
   const scope = resolveSessionScope({ args: filteredArgs });
   const explicitKey = explicitSessionKeyInput({ args: filteredArgs });
   const host = resolveHostFromArgs(filteredArgs, undefined);
   const convexUrl = await discoverConvexUrl(host);
   const client = new ConvexHttpClient(convexUrl);
-  const code = randomUrlSafe(18);
+
   const sessionToken = `dch_agent_${randomUrlSafe(32)}`;
-  const codeHash = await sha256Hex(code);
   const sessionTokenHash = await sha256Hex(sessionToken);
+
   const agentKind = normalizeAgentKind(option("--kind"));
   const agentName = resolveAgentName(agentKind);
-  const request = await client.mutation(
-    api.functions.agentWorkspace.createAgentLoginRequest,
-    {
-      codeHash,
+  const email = option("--email")?.trim().toLowerCase() || null;
+  const newWorkspace = hasFlag("--new-workspace");
+  const orgNameFlag = option("--org-name")?.trim() || null;
+  const orgFlag = option("--org")?.trim() || null;
+
+  if (newWorkspace && !orgNameFlag) {
+    throw new CliError(
+      "--new-workspace requires --org-name '<workspace name>'.",
+      { code: "missing_org_name" },
+    );
+  }
+  if (newWorkspace && orgFlag) {
+    throw new CliError(
+      "Pass either --new-workspace --org-name '<name>' OR --org <slug>, not both.",
+      { code: "conflicting_intent" },
+    );
+  }
+
+  const intent: SignInIntent = newWorkspace
+    ? "create_workspace"
+    : "join_existing";
+
+  if (email) {
+    await signinViaOtp({
+      host,
+      scope,
+      explicitKey,
+      sessionToken,
       sessionTokenHash,
       agentName,
       agentKind,
+      email,
+      intent,
+      proposedOrganizationName: orgNameFlag,
+      orgSelector: orgFlag,
+    });
+    return;
+  }
+
+  await signinViaBrowser({
+    client,
+    host,
+    convexUrl,
+    scope,
+    explicitKey,
+    sessionToken,
+    sessionTokenHash,
+    agentName,
+    agentKind,
+    intent,
+    proposedOrganizationName: orgNameFlag,
+    orgSelector: orgFlag,
+  });
+}
+
+/**
+ * Browser-link variant of `dench signin`. Creates a sign-in request
+ * row in Convex, opens the approval URL in the user's browser, then
+ * polls until the human approves the request (and picks/creates the
+ * target workspace on the approval page).
+ */
+async function signinViaBrowser(input: {
+  client: ConvexHttpClient;
+  host: string;
+  convexUrl: string;
+  scope: SessionScope;
+  explicitKey: ReturnType<typeof explicitSessionKeyInput>;
+  sessionToken: string;
+  sessionTokenHash: string;
+  agentName: string;
+  agentKind: string;
+  intent: SignInIntent;
+  proposedOrganizationName: string | null;
+  orgSelector: string | null;
+}) {
+  const code = randomUrlSafe(18);
+  const codeHash = await sha256Hex(code);
+  const request = await input.client.mutation(
+    api.functions.agentWorkspace.createSignInRequest,
+    {
+      codeHash,
+      sessionTokenHash: input.sessionTokenHash,
+      agentName: input.agentName,
+      agentKind: input.agentKind,
+      intent: input.intent,
+      proposedOrganizationName: input.proposedOrganizationName ?? undefined,
+      requestedOrganizationSelector: input.orgSelector ?? undefined,
       userAgent: "@dench.com/cli",
     },
   );
-  const approvalUrl = `${host}/agent-login/${encodeURIComponent(code)}`;
+  const approvalUrl = `${input.host}/agent-signin/${encodeURIComponent(code)}`;
 
   const openResult = await openUrl(approvalUrl, {
     noOpen: hasFlag("--no-open"),
@@ -1569,9 +1722,19 @@ async function login() {
     env: process.env,
   });
   logHuman(formatApprovalOpenMessage(approvalUrl, openResult));
-  logHuman(
-    "Before approving, switch Dench in your browser to the intended workspace.",
-  );
+  if (input.intent === "create_workspace") {
+    logHuman(
+      `On the approval page, confirm the workspace name and connect ${input.agentName}.`,
+    );
+  } else if (input.orgSelector) {
+    logHuman(
+      `On the approval page, confirm connecting ${input.agentName} to ${input.orgSelector}.`,
+    );
+  } else {
+    logHuman(
+      `On the approval page, pick which workspace to connect ${input.agentName} to (or create a new one).`,
+    );
+  }
   logHuman(
     `This request expires at ${new Date(request.expiresAt).toLocaleString()}.`,
   );
@@ -1579,33 +1742,33 @@ async function login() {
   const timeoutMs = Number(option("--timeout-ms") ?? 15 * 60 * 1000);
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    const poll = await client.mutation(
-      api.functions.agentWorkspace.pollAgentLoginRequest,
-      { codeHash, sessionTokenHash },
+    const poll = await input.client.mutation(
+      api.functions.agentWorkspace.pollSignInRequest,
+      { codeHash, sessionTokenHash: input.sessionTokenHash },
     );
 
     if (poll.status === "approved") {
       const storedSession: StoredSession = {
-        host,
-        convexUrl,
-        sessionToken,
+        host: input.host,
+        convexUrl: input.convexUrl,
+        sessionToken: input.sessionToken,
         organization: poll.organization,
         agent: poll.agent,
         sessionExpiresAt: poll.sessionExpiresAt,
         savedAt: Date.now(),
       };
-      await saveSession(storedSession, scope);
-      const message = loginNextCommandsMessage(
+      await saveSession(storedSession, input.scope);
+      const message = signinNextCommandsMessage(
         storedSession,
-        explicitKey?.source === "DENCH_SESSION_KEY"
-          ? explicitKey.value
+        input.explicitKey?.source === "DENCH_SESSION_KEY"
+          ? input.explicitKey.value
           : undefined,
       );
       print(
         json
           ? {
               ok: true,
-              host,
+              host: input.host,
               organization: poll.organization,
               agent: poll.agent,
               sessionExpiresAt: poll.sessionExpiresAt,
@@ -1616,13 +1779,275 @@ async function login() {
       return;
     }
     if (poll.status === "rejected" || poll.status === "expired") {
-      throw new Error(`Login ${poll.status}`);
+      throw new Error(`Sign-in ${poll.status}`);
     }
 
     await sleep(2000);
   }
 
-  throw new Error(`Login timed out. Open ${approvalUrl} and run login again.`);
+  throw new Error(
+    `Sign-in timed out. Open ${approvalUrl} and run \`dench signin\` again.`,
+  );
+}
+
+type OtpVerifyResult =
+  | {
+      kind: "completed";
+      organization?: { id: string; name: string; slug: string };
+      sessionExpiresAt?: number;
+    }
+  | {
+      kind: "requiresOrgChoice";
+      authToken: string;
+      organizations: Array<{ id: string; name: string; slug: string }>;
+      expiresAt: number;
+    };
+
+/**
+ * OTP variant of `dench signin`. Sends the OTP via the Next.js
+ * agent-signin routes, prompts the human for the 6-digit code, and
+ * mints a session against the org they pick (or create) in one or
+ * two HTTP round-trips.
+ */
+async function signinViaOtp(input: {
+  host: string;
+  scope: SessionScope;
+  explicitKey: ReturnType<typeof explicitSessionKeyInput>;
+  sessionToken: string;
+  sessionTokenHash: string;
+  agentName: string;
+  agentKind: string;
+  email: string;
+  intent: SignInIntent;
+  proposedOrganizationName: string | null;
+  orgSelector: string | null;
+}) {
+  const base = input.host.replace(/\/+$/, "");
+
+  // Step 1 — send the OTP.
+  const startResponse = await fetch(`${base}/api/agent-signin/otp-start`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({ email: input.email }),
+  });
+  if (!startResponse.ok) {
+    const body = await startResponse.text();
+    throw new CliError(
+      `OTP send failed (${startResponse.status}): ${body || "unknown error"}`,
+      { code: "otp_send_failed", status: startResponse.status },
+    );
+  }
+  logHuman(`We sent a 6-digit sign-in code to ${input.email}.`);
+
+  // Step 2 — verify the OTP. Either the user is unambiguously
+  // resolvable (single admin org or create_workspace intent) and the
+  // server hands us a session, OR we get an auth token + list and
+  // need a third call.
+  const code =
+    option("--otp-code")?.trim() || (await promptLine("Paste OTP: "));
+  if (!/^\d{6}$/.test(code)) {
+    throw new CliError("OTP code must be exactly 6 digits.", {
+      code: "invalid_otp_code",
+    });
+  }
+  const verifyResponse = await fetch(`${base}/api/agent-signin/otp-verify`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({
+      email: input.email,
+      code,
+      agentName: input.agentName,
+      agentKind: input.agentKind,
+      sessionTokenHash: input.sessionTokenHash,
+      intent: input.intent,
+      proposedOrganizationName: input.proposedOrganizationName ?? undefined,
+      organizationSelector: input.orgSelector ?? undefined,
+      userAgent: "@dench.com/cli",
+    }),
+  });
+  if (!verifyResponse.ok) {
+    const body = await verifyResponse.text();
+    throw new CliError(
+      `OTP verify failed (${verifyResponse.status}): ${body || "unknown error"}`,
+      { code: "otp_verify_failed", status: verifyResponse.status },
+    );
+  }
+  const verifyPayload = (await verifyResponse.json()) as {
+    ok: boolean;
+    result: OtpVerifyResult;
+  };
+  const result = verifyPayload.result;
+
+  // Branch A: server minted the session in one shot.
+  if (result.kind === "completed") {
+    assertOtpCompletedOrgMatchesSelector(
+      result.organization,
+      input.orgSelector,
+    );
+    await finalizeOtpSession(
+      input,
+      result.organization,
+      result.sessionExpiresAt,
+    );
+    return;
+  }
+
+  // Branch B: human has multiple admin orgs — pick one (or create new).
+  const finalizeChoice = await resolveOrgChoiceForOtp({
+    organizations: result.organizations,
+    orgSelector: input.orgSelector,
+  });
+
+  const finalizeResponse = await fetch(
+    `${base}/api/agent-signin/otp-finalize`,
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      body: JSON.stringify({
+        authToken: result.authToken,
+        organizationId: finalizeChoice.organizationId,
+        newOrganizationName: finalizeChoice.newOrganizationName,
+      }),
+    },
+  );
+  if (!finalizeResponse.ok) {
+    const body = await finalizeResponse.text();
+    throw new CliError(
+      `OTP finalize failed (${finalizeResponse.status}): ${body || "unknown error"}`,
+      { code: "otp_finalize_failed", status: finalizeResponse.status },
+    );
+  }
+  const finalizePayload = (await finalizeResponse.json()) as {
+    ok: boolean;
+    result: {
+      organization?: { id: string; name: string; slug: string };
+      sessionExpiresAt?: number;
+    };
+  };
+  await finalizeOtpSession(
+    input,
+    finalizePayload.result.organization,
+    finalizePayload.result.sessionExpiresAt,
+  );
+}
+
+function assertOtpCompletedOrgMatchesSelector(
+  organization: { id: string; name: string; slug: string } | undefined,
+  orgSelector: string | null,
+) {
+  if (!orgSelector) return;
+  const normalized = orgSelector.trim().toLowerCase();
+  if (!organization) {
+    throw new CliError(
+      `The OTP flow completed without an organization, but --org ${orgSelector} was requested.`,
+      { code: "org_not_found" },
+    );
+  }
+  const matches =
+    organization.id.toLowerCase() === normalized ||
+    organization.slug.toLowerCase() === normalized ||
+    organization.name.trim().toLowerCase() === normalized;
+  if (!matches) {
+    throw new CliError(
+      `The OTP flow resolved ${organization.name} (${organization.slug}), but --org ${orgSelector} was requested.`,
+      { code: "org_mismatch" },
+    );
+  }
+}
+
+async function finalizeOtpSession(
+  input: {
+    host: string;
+    scope: SessionScope;
+    explicitKey: ReturnType<typeof explicitSessionKeyInput>;
+    sessionToken: string;
+  },
+  organization: { id: string; name: string; slug: string } | undefined,
+  sessionExpiresAt: number | undefined,
+) {
+  const convexUrl = await discoverConvexUrl(input.host);
+  const storedSession: StoredSession = {
+    host: input.host,
+    convexUrl,
+    sessionToken: input.sessionToken,
+    organization,
+    sessionExpiresAt,
+    savedAt: Date.now(),
+  };
+  await saveSession(storedSession, input.scope);
+  const message = signinNextCommandsMessage(
+    storedSession,
+    input.explicitKey?.source === "DENCH_SESSION_KEY"
+      ? input.explicitKey.value
+      : undefined,
+  );
+  print(
+    json
+      ? {
+          ok: true,
+          host: input.host,
+          organization,
+          sessionExpiresAt,
+          message,
+        }
+      : message,
+  );
+}
+
+async function resolveOrgChoiceForOtp(input: {
+  organizations: Array<{ id: string; name: string; slug: string }>;
+  orgSelector: string | null;
+}): Promise<{ organizationId?: string; newOrganizationName?: string }> {
+  if (input.orgSelector) {
+    const match = input.organizations.find(
+      (org) =>
+        org.id === input.orgSelector ||
+        org.slug === input.orgSelector ||
+        org.name === input.orgSelector,
+    );
+    if (!match) {
+      throw new CliError(
+        `--org "${input.orgSelector}" did not match any of your admin workspaces.`,
+        { code: "org_not_found" },
+      );
+    }
+    return { organizationId: match.id };
+  }
+
+  // Interactive picker.
+  logHuman("");
+  logHuman("Which workspace should this agent connect to?");
+  for (let i = 0; i < input.organizations.length; i++) {
+    const org = input.organizations[i];
+    logHuman(`  ${i + 1}) ${org.name} (${org.slug})`);
+  }
+  logHuman(`  ${input.organizations.length + 1}) Create a new free workspace`);
+  logHuman("");
+
+  const answer = await promptLine("Pick a number: ");
+  const choice = Number(answer);
+  if (
+    !Number.isFinite(choice) ||
+    choice < 1 ||
+    choice > input.organizations.length + 1
+  ) {
+    throw new CliError(`Invalid choice: ${answer}`, {
+      code: "invalid_org_choice",
+    });
+  }
+  if (choice <= input.organizations.length) {
+    return { organizationId: input.organizations[choice - 1].id };
+  }
+  const newName = await promptLine("New workspace name: ");
+  if (!newName.trim()) {
+    throw new CliError("Workspace name cannot be empty.", {
+      code: "missing_org_name",
+    });
+  }
+  return { newOrganizationName: newName.trim() };
 }
 
 function normalizeApiBase(input: string) {
@@ -1745,6 +2170,114 @@ async function billingTopup(runtime: Runtime) {
   print(json ? output : output.message);
 }
 
+/**
+ * `dench upgrade` — turns a free CRM-only workspace into a paid Pro or
+ * Max plan by handing the human a Stripe Checkout link. Mirrors the
+ * `billing topup` flow (POST with the agent session as a Bearer
+ * token, surface the returned URL) but hits the existing
+ * `/api/stripe/create-checkout` endpoint that the marketing pricing
+ * page already uses.
+ *
+ * Two flag-driven paths:
+ *
+ *   --tier pro | max         Which paid tier to target. Defaults to
+ *                            "pro" (the most common upgrade from
+ *                            free).
+ *   --cycle monthly | yearly Billing cycle. Defaults to "monthly".
+ *
+ * The endpoint can also return `{ updated: true }` for in-place
+ * Pro \u2192 Max upgrades on an already-subscribed org (no Checkout URL
+ * needed in that case). We surface either outcome cleanly.
+ */
+async function denchUpgrade(runtime: Runtime) {
+  const sessionRuntime = requireSessionRuntime(runtime, "dench upgrade");
+  const tierFlag = option("--tier")?.trim().toLowerCase() || "pro";
+  const cycleFlag =
+    option("--cycle")?.trim().toLowerCase() ||
+    option("--billing-cycle")?.trim().toLowerCase() ||
+    "monthly";
+  if (tierFlag !== "pro" && tierFlag !== "max") {
+    throw new CliError("--tier must be 'pro' or 'max'.", {
+      code: "invalid_tier",
+    });
+  }
+  if (cycleFlag !== "monthly" && cycleFlag !== "yearly") {
+    throw new CliError("--cycle must be 'monthly' or 'yearly'.", {
+      code: "invalid_cycle",
+    });
+  }
+  // Internal tier strings still use the legacy "desktop" / "cloud"
+  // names from before the Daytona rewrite. Map the CLI's
+  // customer-facing flag onto them so the existing checkout endpoint
+  // doesn't need to learn a new vocabulary.
+  const internalTier = tierFlag === "pro" ? "desktop" : "cloud";
+
+  const response = await fetch(
+    `${sessionRuntime.host.replace(/\/+$/, "")}/api/stripe/create-checkout`,
+    {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json",
+        authorization: `Bearer ${sessionRuntime.sessionToken}`,
+      },
+      body: JSON.stringify({
+        tier: internalTier,
+        billingCycle: cycleFlag,
+        requestId: crypto.randomUUID(),
+      }),
+    },
+  );
+  const payload = await parseResponseBody(response);
+  if (!response.ok) {
+    const errorRecord = asRecord(payload);
+    throw new CliError(
+      stringField(errorRecord, "error", "message") ??
+        `Could not create upgrade checkout (${response.status})`,
+      {
+        code: stringField(errorRecord, "code") ?? "upgrade_failed",
+        status: response.status,
+      },
+    );
+  }
+  const record = asRecord(payload);
+  const url = stringField(record, "url");
+  const updatedInPlace = record?.updated === true;
+
+  if (updatedInPlace) {
+    const message = `Upgraded to Dench ${tierFlag === "pro" ? "Pro" : "Max"} in place — no Stripe Checkout needed.`;
+    print(
+      json ? { ok: true, updated: true, tier: tierFlag, message } : message,
+    );
+    return;
+  }
+
+  const openResult = url
+    ? await openUrl(url, {
+        noOpen: hasFlag("--no-open"),
+        json,
+        env: process.env,
+      })
+    : ({ status: "skipped", reason: "missing-url" } as const);
+  const openMessage =
+    url && openResult.status === "opened"
+      ? `Attempted to open Stripe Checkout in your browser. If it did not open, use this link: ${url}`
+      : url && openResult.status === "failed"
+        ? `Could not open browser automatically. Open this Stripe Checkout link: ${url}`
+        : url
+          ? `Open this Stripe Checkout link: ${url}`
+          : "Stripe Checkout link created.";
+  const output = {
+    ok: true,
+    tier: tierFlag,
+    billingCycle: cycleFlag,
+    url,
+    openResult,
+    message: openMessage,
+  };
+  print(json ? output : output.message);
+}
+
 function hasDevEnv() {
   return Boolean(
     process.env.NEXT_PUBLIC_CONVEX_URL &&
@@ -1794,11 +2327,11 @@ function resolveApiHost(fallbackHost: string): string {
 }
 
 function loginRequiredError(command = "this command") {
-  return new CliError(`${command} requires dench login`, {
+  return new CliError(`${command} requires dench signin`, {
     code: "login_required",
     nextActions: [
       "Set DENCH_API_KEY (and CONVEX_URL) in your env if running inside a sandbox or CI.",
-      'Or run dench onboard --kind <kind> --name "AI Agent - Project" to mint an agent session.',
+      'Or run dench signin --kind <kind> --name "AI Agent - Project" to mint an agent session.',
       "If already approved, run dench sessions --json, then dench use <session-key-or-workspace-slug>.",
     ],
   });
@@ -1815,7 +2348,7 @@ function missingDevEnvError() {
     missingEnv: required.filter((name) => !process.env[name]?.trim()),
     nextActions: [
       "Set NEXT_PUBLIC_CONVEX_URL, DENCH_WORKSPACE, and DENCH_DEV_AGENT_KEY.",
-      "Or remove --dev and run dench onboard to use a real agent session.",
+      "Or remove --dev and run dench signin to use a real agent session.",
     ],
   });
 }
@@ -1871,7 +2404,7 @@ async function getRuntime() {
     // src/lib/secrets/sandbox-tokens.ts) is enough to drive every
     // command that goes through `requireCrmAccess` server-side. We only
     // fall into this branch when no stored session is present, so
-    // explicit `dench login` setups keep their existing behavior.
+    // explicit `dench signin` setups keep their existing behavior.
     const apiKey = process.env.DENCH_API_KEY?.trim();
     const convexUrl = resolveApiKeyConvexUrl();
     if (apiKey && convexUrl) {
@@ -1965,6 +2498,103 @@ function requireAuthenticatedRuntime(
   throw loginRequiredError(command);
 }
 
+type GatewayCommandAuth = {
+  bearerToken: string;
+  gatewayBaseUrl?: string;
+};
+
+function gatewayBaseUrlForCli(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim().replace(/\/+$/, "");
+  if (!trimmed) return undefined;
+  // The desktop endpoint returns a `/v1` base; CLI gateway modules append
+  // `/v1/...` paths themselves, so normalize to the root origin here.
+  return trimmed.replace(/\/v1$/, "");
+}
+
+async function parseJsonResponseBody(response: Response): Promise<JsonRecord> {
+  const text = await response.text().catch(() => "");
+  if (!text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as JsonRecord)
+      : {};
+  } catch {
+    return { error: text };
+  }
+}
+
+function gatewayAuthError(
+  command: string,
+  response: Response,
+  body: JsonRecord,
+) {
+  const code =
+    typeof body.error === "string" && body.error.trim()
+      ? body.error.trim()
+      : `gateway_key_${response.status}`;
+  if (response.status === 403 && code === "no_active_subscription") {
+    return new CliError(`${command} requires a paid Dench workspace`, {
+      code: "paid_workspace_required",
+      nextActions: [
+        "Run dench upgrade --tier pro or dench upgrade --tier max, then retry.",
+      ],
+    });
+  }
+  if (response.status === 401) {
+    return loginRequiredError(command);
+  }
+  return new CliError(`${command} could not get a gateway key (${code})`, {
+    code,
+    status: response.status,
+    nextActions: [
+      "Confirm this agent is signed in to the intended workspace.",
+      "If the workspace is paid, retry after a minute in case gateway key provisioning is still finishing.",
+    ],
+  });
+}
+
+async function resolveGatewayCommandAuth(
+  runtime: Runtime,
+  command: string,
+): Promise<GatewayCommandAuth> {
+  if (runtime.mode === "apiKey") {
+    return { bearerToken: runtime.sessionToken };
+  }
+
+  if (runtime.mode === "session") {
+    const response = await fetch(
+      `${runtime.host.replace(/\/+$/, "")}/api/desktop/organizations/gateway-key`,
+      {
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${runtime.sessionToken}`,
+        },
+      },
+    );
+    const body = await parseJsonResponseBody(response);
+    if (!response.ok) {
+      throw gatewayAuthError(command, response, body);
+    }
+    const gatewayKey =
+      typeof body.gatewayKey === "string" ? body.gatewayKey.trim() : "";
+    if (!gatewayKey) {
+      throw new CliError(`${command} could not get a gateway key`, {
+        code: "missing_gateway_key",
+      });
+    }
+    return {
+      bearerToken: gatewayKey,
+      gatewayBaseUrl: gatewayBaseUrlForCli(body.gatewayBaseUrl),
+    };
+  }
+
+  const envApiKey = process.env.DENCH_API_KEY?.trim();
+  if (envApiKey) return { bearerToken: envApiKey };
+  throw loginRequiredError(command);
+}
+
 function encodeDevCrmSessionToken(args: {
   workspaceSlug: string;
   devKey: string;
@@ -1978,7 +2608,7 @@ function agentSessionRequiredError(command: string) {
     {
       code: "agent_session_required",
       nextActions: [
-        'Run dench onboard --kind <kind> --name "AI Agent - Project" to mint an agent session for this command.',
+        'Run dench signin --kind <kind> --name "AI Agent - Project" to mint an agent session for this command.',
         "Or run the equivalent action via the workspace UI / dench crm if it is org-level (e.g. CRM data, files).",
       ],
     },
@@ -2079,7 +2709,7 @@ function workspaceUrls(host: string, workspaceSlug: string | undefined) {
 
 function nextContextCommands() {
   return [
-    "dench onboard --json",
+    "dench context --json",
     "dench tasks --json",
     'dench log "Brief progress update"',
     'dench tool search "what you need" --toolkit <app>',
@@ -2087,12 +2717,24 @@ function nextContextCommands() {
   ];
 }
 
-async function connectedAppsContext(_runtime: Runtime) {
-  // Reach the Dench gateway directly with DENCH_API_KEY (mirrors the
-  // denchclaw pattern). This works for every Runtime mode — session,
-  // apiKey, dev — because the gateway only cares about the bearer key,
-  // not which Convex session is calling.
-  return fetchConnectedAppsSummary();
+async function connectedAppsContext(runtime: Runtime) {
+  try {
+    const gatewayAuth = await resolveGatewayCommandAuth(
+      runtime,
+      "dench context",
+    );
+    return fetchConnectedAppsSummary({
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
+  } catch (error) {
+    return {
+      available: false,
+      reason: errorMessage(error),
+      count: 0,
+      connections: [],
+    };
+  }
 }
 
 async function buildContext(runtime: Runtime) {
@@ -2135,36 +2777,6 @@ async function buildContext(runtime: Runtime) {
   };
 }
 
-async function runOnboarding() {
-  let runtime: Runtime;
-  try {
-    runtime = await getRuntime();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const isLoginRequired =
-      error instanceof CliError && error.payload.code === "login_required";
-    if (!isLoginRequired && !message.includes("Not logged in")) {
-      throw error;
-    }
-    logHuman("No Dench session found. Starting login first.");
-    await login();
-    runtime = await getRuntime();
-  }
-
-  const context = await buildContext(runtime);
-  print(
-    json
-      ? { ok: true, context }
-      : [
-          "Dench onboarding complete.",
-          "",
-          formatContext(context),
-          "",
-          "Setup is complete when the workspace and agent above are correct.",
-        ].join("\n"),
-  );
-}
-
 function formatCount(value: unknown) {
   return typeof value === "number" ? String(value) : "0";
 }
@@ -2441,7 +3053,7 @@ async function defaultDevAgentId(
   const agent = data.agents[0];
   if (!agent) {
     throw new Error(
-      'No agent registered yet. Run: dench register --name "AI Agent" --kind other --dev',
+      'No agent registered yet. Run: dench signin --kind <kind> --name "AI Agent - Project"',
     );
   }
   return agent._id;
@@ -2532,26 +3144,12 @@ function normalizeFilesPath(input: string): string {
   return cleaned;
 }
 
-function filesApiKey(runtime: Runtime): string | undefined {
-  if (runtime.mode === "apiKey") return runtime.sessionToken;
-  return process.env.DENCH_API_KEY?.trim() || undefined;
-}
-
-function requireFilesApiKey(runtime: Runtime, command: string): string {
-  const apiKey = filesApiKey(runtime);
-  if (!apiKey) {
-    throw new CliError(
-      `${command} needs DENCH_API_KEY (or a sandbox-baked api-key session). It bypasses the user-session auth path.`,
-      {
-        code: "files_api_key_required",
-        nextActions: [
-          "Run inside a Dench sandbox where DENCH_API_KEY is baked in.",
-          "Or export DENCH_API_KEY=<key> first (see dench login output).",
-        ],
-      },
-    );
-  }
-  return apiKey;
+async function requireFilesApiKey(
+  runtime: Runtime,
+  command: string,
+): Promise<string> {
+  const auth = await resolveGatewayCommandAuth(runtime, command);
+  return auth.bearerToken;
 }
 
 type FileTreeRow = {
@@ -2651,7 +3249,7 @@ async function uploadConvexFileBytes(
 
 async function runFilesLs() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench files ls");
+  const apiKey = await requireFilesApiKey(runtime, "dench files ls");
   const target = normalizeFilesPath(positional(2) ?? "/");
   const recursive = hasFlag("--recursive") || hasFlag("-r");
   const rows = recursive
@@ -2688,7 +3286,7 @@ async function runFilesLs() {
 
 async function runFilesMv() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench files mv");
+  const apiKey = await requireFilesApiKey(runtime, "dench files mv");
   const fromRaw = positional(2);
   const toRaw = positional(3);
   if (!fromRaw || !toRaw) {
@@ -2760,7 +3358,7 @@ async function runFilesMv() {
 
 async function runFilesRm() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench files rm");
+  const apiKey = await requireFilesApiKey(runtime, "dench files rm");
   const targetRaw = positional(2);
   if (!targetRaw) {
     throw new CliError("Usage: dench files rm <path> [--recursive]", {
@@ -2947,7 +3545,7 @@ async function* walkLocalFiles(
 
 async function runStage() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench stage");
+  const apiKey = await requireFilesApiKey(runtime, "dench stage");
   const localRaw = positional(1);
   const destRaw = positional(2);
   if (!localRaw) {
@@ -3182,21 +3780,40 @@ async function main() {
     return;
   }
 
-  if (command === "login" && hasFlag("--help")) {
-    loginHelp();
-    return;
-  }
+  const isDeprecatedAuthCommand =
+    command === "login" ||
+    command === "onboard" ||
+    command === "setup" ||
+    command === "what-can-i-do" ||
+    command === "register";
 
   if (
-    (command === "onboard" ||
-      command === "setup" ||
-      command === "what-can-i-do") &&
+    (command === "signin" || isDeprecatedAuthCommand) &&
     (subcommand === "help" || hasFlag("--help"))
   ) {
-    onboardHelp();
+    signinHelp();
     return;
   }
 
+  // `dench login`, `dench onboard`, `dench setup`, `dench what-can-i-do`,
+  // and `dench register` were removed in @dench.com/cli v2. Surface a
+  // clean redirect to the new unified surface so old `npx` caches and
+  // pre-existing agent prompts get a one-line nudge instead of an
+  // opaque "Unknown command" error.
+  if (isDeprecatedAuthCommand) {
+    throw new CliError(
+      `\`dench ${command}\` was removed in @dench.com/cli v2. Run \`dench signin\` instead.`,
+      {
+        code: "deprecated_command",
+        nextActions: [
+          "Run `dench signin` to connect this agent to an existing workspace.",
+          'Run `dench signin --new-workspace --org-name "<name>"` to create a free CRM-only workspace.',
+          "Upgrade the CLI globally with `npm install -g @dench.com/cli@latest`.",
+        ],
+      },
+    );
+  }
+
   if (command === "context" && hasFlag("--help")) {
     contextHelp();
     return;
@@ -3233,10 +3850,7 @@ async function main() {
     return;
   }
 
-  if (
-    command === "backend" &&
-    (subcommand === "help" || hasFlag("--help"))
-  ) {
+  if (command === "backend" && (subcommand === "help" || hasFlag("--help"))) {
     backendHelp();
     return;
   }
@@ -3258,23 +3872,43 @@ async function main() {
     const { runCrmCommand } = await import("./crm");
     const runtime = await getRuntime();
     // CRM is org-scoped — accept either an agent session token
-    // (`dch_agent_*` from `dench login`) or a unified Dench API key
+    // (`dch_agent_*` from `dench signin`) or a unified Dench API key
     // (`DENCH_API_KEY` baked into sandbox envVars). Server-side
     // `requireCrmAccess` (convex/lib/crm/access.ts) dispatches on the
     // bearer prefix and resolves the org for both.
     if (runtime.mode === "dev") {
+      const gatewayAuth =
+        subArgs[0] === "enrich"
+          ? await resolveGatewayCommandAuth(runtime, "dench crm enrich")
+          : undefined;
       await runCrmCommand({
         convex: runtime.client,
         args: subArgs,
         sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+        enrichmentGateway: gatewayAuth
+          ? {
+              apiKey: gatewayAuth.bearerToken,
+              baseUrl: gatewayAuth.gatewayBaseUrl,
+            }
+          : undefined,
       });
       return;
     }
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench crm");
+    const gatewayAuth =
+      subArgs[0] === "enrich"
+        ? await resolveGatewayCommandAuth(authedRuntime, "dench crm enrich")
+        : undefined;
     await runCrmCommand({
       convex: authedRuntime.client,
       args: subArgs,
       sessionToken: authedRuntime.sessionToken,
+      enrichmentGateway: gatewayAuth
+        ? {
+            apiKey: gatewayAuth.bearerToken,
+            baseUrl: gatewayAuth.gatewayBaseUrl,
+          }
+        : undefined,
     });
     return;
   }
@@ -3307,10 +3941,7 @@ async function main() {
       });
       return;
     }
-    const authedRuntime = requireAuthenticatedRuntime(
-      runtime,
-      "dench members",
-    );
+    const authedRuntime = requireAuthenticatedRuntime(runtime, "dench members");
     await runMembersCommand({
       convex: authedRuntime.client,
       args: subArgs,
@@ -3335,44 +3966,76 @@ async function main() {
   }
 
   if (command === "search") {
-    // `dench search` talks straight to the gateway over HTTP using
-    // DENCH_API_KEY; it deliberately bypasses requireSessionRuntime so
-    // it works in any sandbox / CI environment that has the key.
     const subArgs = args.slice(args.indexOf("search") + 1);
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runSearchCommand } = await import("./search");
-    await runSearchCommand({ args: filteredSubArgs, jsonOutput: json });
+    const sub = filteredSubArgs[0];
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+      await runSearchCommand({ args: filteredSubArgs, jsonOutput: json });
+      return;
+    }
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(
+      runtime,
+      "dench search",
+    );
+    await runSearchCommand({
+      args: filteredSubArgs,
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
   if (command === "image") {
-    // `dench image generate|edit` mirrors `dench search`: straight HTTP
-    // to the gateway with DENCH_API_KEY, no Convex session required.
-    // The gateway writes the bytes to Convex Storage on success; we
-    // also drop them on local disk so the next bash command sees them.
     const subArgs = args.slice(args.indexOf("image") + 1);
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runImageCommand } = await import("./image");
-    await runImageCommand({ args: filteredSubArgs, jsonOutput: json });
+    const sub = filteredSubArgs[0];
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+      await runImageCommand({ args: filteredSubArgs, jsonOutput: json });
+      return;
+    }
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench image");
+    await runImageCommand({
+      args: filteredSubArgs,
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
   if (command === "apps") {
-    // `dench apps` is an alias for `dench tool status`. Both speak
-    // straight HTTP to the Dench Cloud Gateway with DENCH_API_KEY —
-    // mirrors the denchclaw pattern. No Convex session involved.
-    await runToolCommand({ args: ["status"], jsonOutput: json });
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench apps");
+    await runToolCommand({
+      args: ["status"],
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
   if (command === "tool") {
-    // `dench tool {status,connect,search,run,disconnect}` is the model-facing
-    // composio surface and only needs DENCH_API_KEY (Bearer) on the
-    // gateway. Bypasses requireSessionRuntime entirely so it works in
-    // every sandbox / API-key context.
     const subArgs = stripRuntimeFlags(args.slice(args.indexOf("tool") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
-    await runToolCommand({ args: filteredSubArgs, jsonOutput: json });
+    const sub = filteredSubArgs[0];
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+      await runToolCommand({ args: filteredSubArgs, jsonOutput: json });
+      return;
+    }
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench tool");
+    await runToolCommand({
+      args: filteredSubArgs,
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
@@ -3485,7 +4148,7 @@ async function main() {
     const { runCronCommand } = await import("./cron");
     const runtime = await getRuntime();
     // Cron CRUD is org-scoped — accept either an agent session token
-    // (`dch_agent_*` from `dench login`) or a unified Dench API key
+    // (`dch_agent_*` from `dench signin`) or a unified Dench API key
     // (`DENCH_API_KEY` baked into sandbox envVars). Server-side
     // `requireCronAccess` (convex/lib/cronAccess.ts) dispatches on the
     // bearer prefix and resolves the org for both. The Bearer token
@@ -3508,7 +4171,7 @@ async function main() {
   // Dispatch all `dench identity / organisation / user / tools / mem /
   // heartbeat / bootstrap / model / daily` traffic through the shared
   // agent-config CLI module. Each command requires the same auth shape
-  // as `dench cron` (Bearer DENCH_API_KEY or `dench login` session
+  // as `dench cron` (Bearer DENCH_API_KEY or `dench signin` session
   // token) so server-side `requireCronAccess` accepts both.
   const AGENT_CONFIG_COMMANDS = new Set([
     "identity",
@@ -3582,17 +4245,8 @@ async function main() {
     }
   }
 
-  if (command === "login") {
-    await login();
-    return;
-  }
-
-  if (
-    command === "onboard" ||
-    command === "setup" ||
-    command === "what-can-i-do"
-  ) {
-    await runOnboarding();
+  if (command === "signin") {
+    await signin();
     return;
   }
 
@@ -3631,6 +4285,11 @@ async function main() {
     return;
   }
 
+  if (command === "upgrade") {
+    await denchUpgrade(runtime);
+    return;
+  }
+
   if (command === "context") {
     const context = await buildContext(runtime);
     print(json ? context : formatContext(context));
@@ -3828,24 +4487,6 @@ async function main() {
     return;
   }
 
-  if (command === "register") {
-    if (runtime.mode !== "dev") {
-      throw new Error(
-        "register is only needed in dev mode. Real sessions use dench login.",
-      );
-    }
-    const agentId = await runtime.client.mutation(
-      api.functions.agentWorkspace.devRegisterAgent,
-      {
-        ...runtime.workspaceArgs,
-        name: option("--name") ?? "AI Agent",
-        kind: normalizeAgentKind(option("--kind")),
-      },
-    );
-    print({ ok: true, agentId });
-    return;
-  }
-
   if (command === "project" && subcommand === "create") {
     if (runtime.mode !== "dev") {
       throw new Error(