epismo 0.19.1 → 1.0.1

package/README.md

@@ -1,101 +1,111 @@
 # Epismo CLI
 
-GitHub made code reusable.
-Hugging Face made AI models reusable.
-Epismo makes agentic workflows reusable.
-
-Capture how you got your best results — not just the output — and share them as executable workflows that agents and humans can discover, adapt, and run across projects.
-
-## CLI Contract
-
-Epismo CLI is designed for agents first.
-
-- Success output is machine-readable JSON on `stdout`, in both interactive and non-interactive runs.
-- `stderr` carries prompts, browser-login guidance, warnings, and errors (all JSON-shaped).
-- Exit code `0` means success; any non-zero code means failure.
-- In non-interactive environments, commands that would need a prompt fail fast instead of waiting for input.
+Agent-friendly CLI for Playbooks, Cases, Tasks, Records, Suggestions, Stars, and Aliases. Successful commands print JSON to stdout; warnings and failures are JSON-shaped on stderr.
 
 ## Install
 
+Node.js 22.12 or newer is required.
+
 ```bash
-npm install -g epismo      # or run ad hoc with: npx epismo <command>
+npm install -g epismo
+# or
+npx epismo <command>
 ```
 
-## Authentication
+## Authentication and workspace selection
 
 ```bash
-epismo login                                 # prompts for email, then OTP
-epismo logout                                # clear local credentials
-EPISMO_TOKEN=<access-token> epismo whoami    # preferred for scripts
+epismo login
+epismo login --email you@example.com
+epismo whoami
+epismo logout
 ```
 
-If `EPISMO_TOKEN` is set, the CLI uses it instead of stored credentials and resolves the workspace from the token itself (the saved default workspace is ignored).
+Commands use the workspace embedded in `EPISMO_TOKEN`, then the saved default from
+`epismo workspace use`, then personal space. A workspace-scoped CI token can be issued
+with `epismo token create --workspace-id <workspace-id>`.
 
 ## Commands
 
-Each command group maps to an Epismo resource.
-Run `epismo <command> --help` for the full flag set; the highlights:
-
-| Command      | Purpose                                                                       |
-| ------------ | ----------------------------------------------------------------------------- |
-| `whoami`     | Show the current user, effective workspace, and accessible workspaces.        |
-| `workspace`  | List/create/update workspaces, manage members, and get billing checkout URLs. |
-| `project`    | Manage projects within a workspace and their members.                         |
-| `agent`      | Manage which AI teammates appear in the assignee roster.                      |
-| `track`      | Create, update, search, and bulk-apply task/goal project tracks.              |
-| `log`        | Append, list, and delete activity/comment logs on tracks.                     |
-| `pack`       | Create, update, fetch, search, like, rate, and delete packs.                  |
-| `suggestion` | Send and triage improvement suggestions against packs.                        |
-| `alias`      | Manage pack aliases as a top-level resource.                                  |
-| `credit`     | Check the credit balance and start credit checkout.                           |
-| `token`      | Issue workspace-scoped CLI tokens for CI/CD.                                  |
+```text
+epismo login | logout | whoami
 
-A few group-specific notes that aren't obvious from `--help`:
+epismo workspace list | current | use | clear | create | checkout | update
+epismo workspace member list | upsert | delete
+epismo project list | create | update
+epismo project member list | add | delete
+epismo credit balance | checkout
+epismo token create
 
-- **Bulk member ops** accept comma-separated IDs and use one backend transaction. Membership does not change Stripe billing quantity.
-- **`track apply`** creates, updates, and deletes multiple tracks in one request; use a non-UUID `id` to create, and cross-references between new entries are resolved server-side.
-- **`track review`** generates a read-only detailed review for one or more completed/postponed task or goal tracks. It returns JSON with `targets` and a `review` object; it does not create or update packs automatically.
-- **`log`** entries are immutable comments/activity notes attached to a track (`kind`: `comment`, `update`, `review`, or the reserved `system`). `log list <track-reference>` reads one track, newest first by default; pass a task/goal UUID or URL containing it. Omit `<track-reference>` for an ACL-scoped activity feed across every track you can access, optionally `--author-id`-filtered either way. `--order asc|desc` and `--cursor <logId>` (the previous response's `nextCursor`) control pagination. Appending a log is free; listing costs credits like other reads. Authors outside what the caller can see (e.g. someone who has since left) come back as `"unknown"`.
+epismo playbook search | create | get | acl | archive | star | unstar | starred
+epismo playbook version list | get | publish
+epismo playbook share create
+epismo alias set | list | delete
 
-### Pack references
+epismo case start | get | list | assign | acl | update | close | reopen
+epismo task create | list | assign | update | close | reopen
+epismo record append | list
 
-Any command that takes a pack accepts a bare UUID, an alias (`@alias` or `@handle/alias`), a share URL, or a hub URL interchangeably.
-
-### Track references
+epismo suggestion create | get | list | update | resolve
+```
 
-Any command that takes an existing track accepts a task/goal UUID or a URL containing that UUID. Tracks do not have aliases.
+The Playbook, Case, Task, Record, Suggestion, Star, and Alias operations are also
+available through MCP. MCP names mirror the CLI resource/verb hierarchy in snake_case;
+for example, `epismo_playbook_version_list` maps to `epismo playbook version list`.
 
-### Access scope
+Run `epismo <command> --help` for flags and positional arguments.
 
-`track` and `pack` writes share one access model: `scope` is `{ "type": "personal" }` or `{ "type": "projects", "ids": [...] }` (required on create; omit on update to preserve existing access), with an optional `sharedWith`.
-The matching CLI flags are `--personal`, `--projects <id...>`, and `--share-with <userIdOrEmail...>`.
-Search uses the same selectors additively; omit them to use the default scope for the current context.
+## Structured input
 
-## Workspace Selection
+Commands that accept payloads support:
 
-There is no per-command `--workspace-id` flag — every command resolves a workspace, in this order:
+```bash
+epismo playbook create --input @playbook.json
+epismo record append <case-id> --input @record.json
+epismo suggestion create --input - < suggestion.json
+```
 
-1. The workspace embedded in `EPISMO_TOKEN` (issued via `epismo token create --workspace-id`).
-2. The saved default from `epismo workspace use` (interactive sessions).
-3. Personal space, when nothing else is configured.
+`--input` accepts an inline JSON object, `@file`, or `-` for stdin. Explicit flags
+override fields from `--input`. Complex Playbook Definitions and close-time Record
+arrays are best supplied through files.
 
-For CI/CD, issue a scoped token once and export it:
+`--input` always carries the whole request payload, so `epismo case start` takes the
+Case's own input object through `--case-input` instead:
 
 ```bash
-epismo token create --workspace-id <workspace-id>
-export EPISMO_TOKEN=<accessToken>     # all commands now use that workspace
+epismo case start --version-id <version-id> --acl <account-id> \
+  --case-input '{"companyName":"Acme"}'
 ```
 
-## Input / Output
+Mutation commands accept `--idempotency-key <uuid>`. When omitted, the CLI generates
+a UUID automatically. Reuse an explicit key when retrying a command whose first result
+was uncertain; reusing one with different arguments is rejected.
+
+Every mutation of an existing Case or Task requires `--lock-version`, taken from the
+most recent object returned by the API: `case assign | acl | update | close | reopen`
+and `task assign | update | close | reopen`. After a conflict, re-read the object and
+decide again rather than resending with a bumped number. Updates are partial: Case
+currently supports `title`, while Task supports `title` and `instructions`.
+
+`epismo record list` is a cross-Case activity feed constrained by current Case ACLs.
+Use `--case-id`, `--task-id`, `--created-by`, `--kinds`, `--origins`, or `--acl` to
+narrow it; these filters never grant access. Results default to newest first, and
+`--order asc` walks a timeline forward.
 
-- `--input <json>`, `--input @file.json`, or `--input -` (stdin) supply structured input; explicit flags override fields from `--input`, and enum-like flags are validated locally.
-- Success is JSON on `stdout`; errors and warnings are JSON on `stderr`:
+## Playbook references
+
+The CLI's REST commands currently use UUIDs for Playbook path arguments. Aliases are
+managed with `epismo alias`; MCP exposes the same alias set/list/delete operations and
+also accepts `pb:alias` and `pb:handle/alias` in `epismo_playbook_get`.
+
+## Output contract
+
+- Success: JSON on stdout and exit code `0`.
+- Failure: JSON on stderr and a non-zero exit code.
+- Non-interactive commands fail instead of waiting for an unavailable prompt.
 
 ```json
-{ "error": { "code": "NOT_FOUND", "message": "...", "retryable": false, "hint": "..." } }
+{ "error": { "code": "NOT_FOUND", "message": "...", "retryable": false } }
 ```
 
-## Update Checks
-
-Update checks run once per day in interactive sessions.
-Set `EPISMO_UPDATE_CHECK=0` to disable the background npm version check.
+Set `EPISMO_UPDATE_CHECK=0` to disable the daily interactive npm update check.

package/dist/auth.js

@@ -1,8 +1,8 @@
 import { createServer } from "node:http";
 import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
 import { spawn } from "node:child_process";
-import { createInterface } from "node:readline/promises";
 import { once } from "node:events";
+import { createInterface } from "node:readline/promises";
 import { stdin as input, stderr as output } from "node:process";
 import { clearCredentials, readCliConfig, readCredentials, resolveApiUrl, resolveWebUrl, writeCliConfig, writeCredentials } from "./config.js";
 import { requestJson } from "./api.js";
@@ -14,13 +14,14 @@ const CLI_CLIENT_ID = "epismo-cli";
 const TOKEN_REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
 // #8: common hint strings — defined once so wording is consistent everywhere
 const HINT_RUN_LOGIN = "Set EPISMO_TOKEN or run `epismo login`.";
-const HINT_RUN_LOGIN_BROWSER = "Run `epismo login --browser` in a terminal, or use the default OTP login with `epismo login`.";
+const HINT_RUN_LOGIN_BROWSER = "Run `epismo login` in an interactive terminal, or use a pre-issued EPISMO_TOKEN.";
 const REFRESH_RACE_RETRY_DELAYS_MS = [100, 200, 400, 800];
 // #9: browser login progress warning codes — defined once so wording is consistent everywhere
 const WARNING_BROWSER_OPENING = "BROWSER_OPENING";
 const WARNING_BROWSER_FALLBACK_URL = "BROWSER_FALLBACK_URL";
 const WARNING_BROWSER_WAITING = "BROWSER_WAITING";
 const WARNING_BROWSER_AUTHORIZED = "BROWSER_AUTHORIZED";
+const WARNING_OTP_SENT = "OTP_SENT";
 export function hasEnvTokenAuthentication() {
     return Boolean(process.env.EPISMO_TOKEN?.trim());
 }
@@ -28,8 +29,8 @@ async function prompt(question) {
     if (input.isTTY !== true || output.isTTY !== true) {
         throw new CliError({
             code: "NON_INTERACTIVE_INPUT_REQUIRED",
-            message: "This command requires interactive input, but no TTY is available.",
-            hint: "Pass the required flags explicitly, use --input, or run the command in a terminal."
+            message: "This login requires interactive input, but no TTY is available.",
+            hint: "Run the command in a terminal, or use a pre-issued EPISMO_TOKEN."
         });
     }
     const readline = createInterface({ input, output });
@@ -186,6 +187,59 @@ async function postOAuthToken(apiUrl, body) {
         body
     });
 }
+async function resolveLoginMethod(apiUrl, email) {
+    const response = await requestJson(apiUrl, "/v1/login-options", {
+        method: "POST",
+        body: { email }
+    });
+    if (response.method !== "sso" && response.method !== "otp") {
+        throw new CliError({
+            code: "LOGIN_METHOD_INVALID",
+            message: "The server returned an unsupported login method.",
+            retryable: true
+        });
+    }
+    return response.method;
+}
+async function loginWithOtp(apiUrl, email) {
+    if (input.isTTY !== true || output.isTTY !== true) {
+        throw new CliError({
+            code: "NON_INTERACTIVE_INPUT_REQUIRED",
+            message: "Email-code login requires an interactive terminal.",
+            hint: "Run the command in a terminal, or use a pre-issued EPISMO_TOKEN."
+        });
+    }
+    const issued = await requestJson(apiUrl, "/v1/otp-tokens", {
+        method: "POST",
+        body: { email }
+    });
+    const otpId = issued.otpId?.trim();
+    if (!otpId) {
+        throw new CliError({
+            code: "OTP_ID_MISSING",
+            message: "Failed to obtain an OTP id from the server.",
+            retryable: true
+        });
+    }
+    printWarning({
+        warning: { code: WARNING_OTP_SENT, message: `A sign-in code was sent to ${email}.` }
+    });
+    const otp = await prompt("Code: ");
+    if (!otp) {
+        throw new CliError({
+            code: "OTP_CODE_REQUIRED",
+            message: "A sign-in code is required.",
+            hint: `Run \`epismo login --email ${email}\` to request a new code.`
+        });
+    }
+    const tokenResponse = await postOAuthToken(apiUrl, {
+        grant_type: "otp",
+        otp_id: otpId,
+        otp,
+        client_id: CLI_CLIENT_ID
+    });
+    return toVerifiedLogin(tokenResponse, await fetchUserInfo(apiUrl, tokenResponse.access_token));
+}
 async function fetchUserInfo(apiUrl, accessToken) {
     return requestJson(apiUrl, "/oauth/userinfo", {
         authToken: accessToken
@@ -214,7 +268,21 @@ function toSavedWorkspace(workspace) {
         role: workspace.role
     };
 }
-async function loginWithBrowser(apiUrl, webUrl) {
+export function buildCliAuthorizationUrl(input) {
+    const authorizeUrl = new URL(`${input.webUrl}/oauth/authorize`);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", CLI_CLIENT_ID);
+    authorizeUrl.searchParams.set("redirect_uri", input.redirectUri);
+    authorizeUrl.searchParams.set("scope", "read write offline_access");
+    authorizeUrl.searchParams.set("code_challenge", input.challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    authorizeUrl.searchParams.set("state", input.state);
+    const email = input.email?.trim();
+    if (email)
+        authorizeUrl.searchParams.set("login_hint", email);
+    return authorizeUrl;
+}
+async function loginWithBrowser(apiUrl, webUrl, email) {
     if (output.isTTY !== true) {
         throw new CliError({
             code: "NON_INTERACTIVE_BROWSER_LOGIN",
@@ -225,21 +293,40 @@ async function loginWithBrowser(apiUrl, webUrl) {
     const { verifier, challenge } = generatePkce();
     const state = generateState();
     const { redirectUri, waitForCallback } = await startOAuthCallbackServer(state);
-    const authorizeUrl = new URL(`${webUrl}/oauth/authorize`);
-    authorizeUrl.searchParams.set("response_type", "code");
-    authorizeUrl.searchParams.set("client_id", CLI_CLIENT_ID);
-    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
-    authorizeUrl.searchParams.set("scope", "read write offline_access");
-    authorizeUrl.searchParams.set("code_challenge", challenge);
-    authorizeUrl.searchParams.set("code_challenge_method", "S256");
-    authorizeUrl.searchParams.set("state", state);
+    const authorizeUrl = buildCliAuthorizationUrl({ webUrl, redirectUri, challenge, state, email });
     const authorizeUrlString = authorizeUrl.toString();
-    printWarning({ warning: { code: WARNING_BROWSER_OPENING, message: "Opening browser for authorization..." } });
-    printWarning({ warning: { code: WARNING_BROWSER_FALLBACK_URL, message: `If the browser does not open, visit: ${authorizeUrlString}` } });
-    await openBrowser(authorizeUrlString);
-    printWarning({ warning: { code: WARNING_BROWSER_WAITING, message: "Waiting for authorization in your browser (times out in 5 minutes)..." } });
+    printWarning({
+        warning: { code: WARNING_BROWSER_OPENING, message: "Opening browser for authorization..." }
+    });
+    printWarning({
+        warning: {
+            code: WARNING_BROWSER_FALLBACK_URL,
+            message: `If the browser does not open, visit: ${authorizeUrlString}`
+        }
+    });
+    try {
+        await openBrowser(authorizeUrlString);
+    }
+    catch (cause) {
+        if (!(cause instanceof CliError) || cause.code !== "BROWSER_OPEN_FAILED") {
+            throw cause;
+        }
+        // The callback server is already listening and the URL was printed above,
+        // so manual browser navigation can complete the same authorization flow.
+    }
+    printWarning({
+        warning: {
+            code: WARNING_BROWSER_WAITING,
+            message: "Waiting for authorization in your browser (times out in 5 minutes)..."
+        }
+    });
     const { code } = await waitForCallback();
-    printWarning({ warning: { code: WARNING_BROWSER_AUTHORIZED, message: "Authorization received. Completing sign-in..." } });
+    printWarning({
+        warning: {
+            code: WARNING_BROWSER_AUTHORIZED,
+            message: "Authorization received. Completing sign-in..."
+        }
+    });
     const tokenResponse = await postOAuthToken(apiUrl, {
         grant_type: "authorization_code",
         code,
@@ -249,9 +336,8 @@ async function loginWithBrowser(apiUrl, webUrl) {
     });
     return toVerifiedLogin(tokenResponse, await fetchUserInfo(apiUrl, tokenResponse.access_token));
 }
-// The server lowercases emails before binding an OTP to them, so compare and
-// store the canonical lowercased form — otherwise the same address typed in a
-// different case looks like a different account.
+// Compare and store canonical lowercased addresses so the same account typed
+// with different casing does not trigger an unnecessary browser login.
 export function normalizeEmail(email) {
     return email.trim().toLowerCase();
 }
@@ -268,86 +354,11 @@ function toVerifiedLogin(tokenResponse, userInfo) {
         email: userInfo.email ? normalizeEmail(userInfo.email) : undefined
     };
 }
-// Send a code (hits the rate-limited /v1/otp-tokens) and return the otpId that
-// pairs with it. There is no local expiry — the server alone decides whether the
-// otpId/code is still valid when it is later verified.
-async function sendOtp(apiUrl, email) {
-    const response = await requestJson(apiUrl, "/v1/otp-tokens", {
-        method: "POST",
-        body: { email }
-    });
-    const otpId = response.otpId?.trim();
-    if (!otpId) {
-        throw new CliError({
-            code: "OTP_ID_MISSING",
-            message: "Failed to obtain an OTP id from the server.",
-            retryable: true
-        });
-    }
-    return { otpId, email };
-}
-// Exchange an (otpId, otp) pair for tokens. Hits /oauth/token only — never the
-// rate-limited send endpoint — so verify retries are cheap and self-contained.
-async function verifyOtp(apiUrl, otpId, otp) {
-    const tokenResponse = await postOAuthToken(apiUrl, {
-        grant_type: "otp",
-        otp_id: otpId,
-        otp,
-        client_id: CLI_CLIENT_ID
-    });
-    return toVerifiedLogin(tokenResponse, await fetchUserInfo(apiUrl, tokenResponse.access_token));
-}
-// Resolve which otpId to verify against without sending a new code: an explicit
-// --otp-id wins (CI/stateless), otherwise the one saved by an earlier send. We
-// never reject on a local clock — verifyOtp surfaces the server's verdict on an
-// expired/consumed code.
-export function resolvePendingOtpId(pending, options) {
-    const explicit = options.otpId?.trim();
-    if (explicit) {
-        return explicit;
-    }
-    if (!pending) {
-        throw new CliError({
-            code: "PENDING_LOGIN_NOT_FOUND",
-            message: "No pending login to verify.",
-            hint: "Run `epismo login --email you@example.com` first to receive a code."
-        });
-    }
-    const requestedEmail = options.email?.trim();
-    if (requestedEmail && normalizeEmail(requestedEmail) !== normalizeEmail(pending.email)) {
-        throw new CliError({
-            code: "PENDING_LOGIN_EMAIL_MISMATCH",
-            message: `The pending login is for ${pending.email}, not ${requestedEmail}.`,
-            hint: "Omit --email, or run `epismo login --email ...` to start over."
-        });
-    }
-    return pending.otpId;
-}
-async function resolveEmailForSend(optionEmail, lastLoginEmail) {
-    const provided = optionEmail?.trim();
-    if (provided) {
-        return normalizeEmail(provided);
-    }
-    const defaultEmail = lastLoginEmail?.trim();
-    const entered = defaultEmail
-        ? (await prompt(`Email [${defaultEmail}]: `)) || defaultEmail
-        : await prompt("Email: ");
-    const email = entered.trim();
-    if (!email) {
-        throw new CliError({
-            code: "EMAIL_REQUIRED",
-            message: "Email is required.",
-            hint: "Pass --email or provide it interactively."
-        });
-    }
-    return normalizeEmail(email);
-}
-// Persist tokens, clear any pending login, remember the email, and identify.
+// Persist tokens, remember the verified email, and identify.
 async function persistLogin(credentials, config, lastLoginEmail) {
     await writeCredentials(credentials);
     await writeCliConfig({
         ...config,
-        pendingLogin: undefined,
         lastLoginEmail: lastLoginEmail ?? config.lastLoginEmail
     });
     // auth.signed_in is emitted server-side by the API at /oauth/token.
@@ -368,103 +379,30 @@ function toLoggedIn(credentials, lastLoginEmail, config, alreadyLoggedIn) {
         ...(hint ? { hint } : {})
     };
 }
-// Read the OTP code from the terminal, mapping the no-TTY/blank cases to
-// OTP_CODE_REQUIRED so a caller that supplied an otpId but no code gets a clear
-// error instead of silently re-sending.
-async function promptForOtp() {
-    const interactive = input.isTTY === true && output.isTTY === true;
-    const otp = interactive ? (await prompt("OTP: ")).trim() : "";
-    if (!otp) {
-        throw new CliError({
-            code: "OTP_CODE_REQUIRED",
-            message: "OTP code is required.",
-            hint: "Pass --otp <code> to verify."
-        });
-    }
-    return otp;
-}
-// The OTP flow is split by which inputs are present, so a send and its verify
-// can happen in separate processes (e.g. an agent sending, then a human pasting
-// the code back):
-//   --otp or --otp-id present  → VERIFY against the pending/explicit otpId
-//                                (prompts for the code on a TTY when --otp absent)
-//   --email present, no --otp  → SEND; on a TTY also prompt + verify in-process
-//   neither, on a TTY          → interactive: prompt email → send → prompt → verify
-//   neither, no TTY            → error (prompt() throws NON_INTERACTIVE)
-// The email persisted as lastLoginEmail always comes from the verified token, so
-// it reflects the account actually signed into — not whatever the user typed.
+// Without an email, Web browser OAuth owns login-method selection. With an
+// email, the API performs the same domain discovery: SSO continues in the
+// browser while OTP completes interactively here in the terminal.
 export async function login(options) {
     const apiUrl = resolveApiUrl();
     const webUrl = resolveWebUrl();
     const config = await readCliConfig();
-    if (options.browser) {
-        const { credentials, email } = await loginWithBrowser(apiUrl, webUrl);
-        const lastLoginEmail = email ?? config.lastLoginEmail;
-        await persistLogin(credentials, config, lastLoginEmail);
-        return toLoggedIn(credentials, lastLoginEmail, config, false);
-    }
-    const providedOtp = options.otp?.trim();
-    const explicitOtpId = options.otpId?.trim();
-    // VERIFY: a code (or an explicit --otp-id signalling verify intent) was given.
-    // Never call the send endpoint here — so retries can't trip its rate limit or
-    // invalidate the code already sitting in the user's inbox.
-    if (providedOtp || explicitOtpId) {
-        const otpId = resolvePendingOtpId(config.pendingLogin, {
-            otpId: explicitOtpId,
-            email: options.email
-        });
-        const otp = providedOtp || (await promptForOtp());
-        const { credentials, email: verifiedEmail } = await verifyOtp(apiUrl, otpId, otp);
-        const lastLoginEmail = verifiedEmail ??
-            config.pendingLogin?.email ??
-            (options.email ? normalizeEmail(options.email) : config.lastLoginEmail);
-        await persistLogin(credentials, config, lastLoginEmail);
-        return toLoggedIn(credentials, lastLoginEmail, config, false);
-    }
-    // Already authenticated? Don't waste an OTP email (or a slot against the send
-    // rate limit). Short-circuit only when the session is still fresh and the same
-    // account is implied — an expired/near-expiry session, or a different --email,
-    // falls through to a normal send so the user can (re-)authenticate.
+    const requestedEmail = options.email?.trim() ? normalizeEmail(options.email) : undefined;
+    // Reuse a fresh credential only when the requested account matches.
     const existing = await readCredentials();
     if (existing && !shouldRefreshCredentials(existing)) {
-        const requestedEmail = options.email?.trim();
         const sameAccount = !requestedEmail ||
-            (!!config.lastLoginEmail &&
-                normalizeEmail(requestedEmail) === normalizeEmail(config.lastLoginEmail));
+            (!!config.lastLoginEmail && requestedEmail === normalizeEmail(config.lastLoginEmail));
         if (sameAccount) {
             return toLoggedIn(existing, config.lastLoginEmail, config, true);
         }
     }
-    // SEND: no code yet. Resolve the email (prompting only when a TTY is present)
-    // and send the code.
-    const email = await resolveEmailForSend(options.email, config.lastLoginEmail);
-    const pendingLogin = await sendOtp(apiUrl, email);
-    const interactive = input.isTTY === true && output.isTTY === true;
-    // Interactive terminal: keep today's one-shot UX — prompt for the code now and
-    // verify in the same process, so the pending login never has to be persisted.
-    if (interactive) {
-        const otp = (await prompt("OTP: ")).trim();
-        if (otp) {
-            const { credentials, email: verifiedEmail } = await verifyOtp(apiUrl, pendingLogin.otpId, otp);
-            const lastLoginEmail = verifiedEmail ?? email;
-            await persistLogin(credentials, config, lastLoginEmail);
-            return toLoggedIn(credentials, lastLoginEmail, config, false);
-        }
-        // No code entered — fall through to persist the pending login so the user can
-        // resume with `epismo login --otp <code>` once it arrives.
-    }
-    // Remember the otpId so a later `--otp` (possibly another process) can verify it.
-    await writeCliConfig({ ...config, lastLoginEmail: email, pendingLogin });
-    if (interactive) {
-        throw new CliError({
-            code: "OTP_CODE_REQUIRED",
-            message: "OTP code is required.",
-            hint: "Run `epismo login --otp <code>` once the code arrives."
-        });
-    }
-    // Non-interactive (agent / CI): the code was emailed; the caller verifies with
-    // `epismo login --otp <code>`.
-    return { kind: "otp_sent", email };
+    const verified = requestedEmail && (await resolveLoginMethod(apiUrl, requestedEmail)) === "otp"
+        ? await loginWithOtp(apiUrl, requestedEmail)
+        : await loginWithBrowser(apiUrl, webUrl, requestedEmail);
+    const lastLoginEmail = verified.email ?? config.lastLoginEmail;
+    const { credentials } = verified;
+    await persistLogin(credentials, config, lastLoginEmail);
+    return toLoggedIn(credentials, lastLoginEmail, config, false);
 }
 export async function logout() {
     const credentials = await readCredentials();