feat(auth): add first-run setup wizard

docs/getting-started.md

@@ -49,6 +49,8 @@ Expected flow:
 4. Return to the terminal when the browser step completes.
 5. Confirm the account appears in the saved account list.
 
+On a brand-new install (no `openai-codex-accounts.json` yet), `codex auth login` opens a first-run setup screen before OAuth. Use it to restore from backups, import an OpenCode pool, run doctor/check paths, open settings and Codex CLI sync, or skip straight to login. All actions reuse the existing backup browser, import, doctor, and settings flows.
+
 If you have named backups in `~/.codex/multi-auth/backups/` and no active accounts, the login flow can prompt you to restore before opening OAuth. Confirm to open `Restore From Backup`, review the recoverable backup list, and restore the entries you want. Skip the prompt to continue with a fresh login.
 
 Verify the new account:

lib/codex-manager.ts

@@ -101,6 +101,10 @@ import {
 } from "./storage.js";
 import type { AccountIdSource, TokenFailure, TokenResult } from "./types.js";
 import { ANSI } from "./ui/ansi.js";
+import {
+	type FirstRunWizardOptions,
+	showFirstRunWizard,
+} from "./ui/auth-menu.js";
 import { confirm } from "./ui/confirm.js";
 import { UI_COPY } from "./ui/copy.js";
 import { paintUiText, quotaToneFromLeftPercent } from "./ui/format.js";
@@ -4839,6 +4843,100 @@ async function runBackupBrowserManager(
 	}
 }
 
+async function buildFirstRunWizardOptions(): Promise<FirstRunWizardOptions> {
+	let namedBackupCount = 0;
+	let rotatingBackupCount = 0;
+	let hasOpencodeSource = false;
+
+	try {
+		const namedBackups = await listNamedBackups();
+		namedBackupCount = namedBackups.length;
+	} catch (error) {
+		console.warn("Failed to list named backups", error);
+	}
+	try {
+		const rotatingBackups = await listRotatingBackups();
+		rotatingBackupCount = rotatingBackups.length;
+	} catch (error) {
+		console.warn("Failed to list rotating backups", error);
+	}
+	try {
+		hasOpencodeSource = (await assessOpencodeAccountPool()) !== null;
+	} catch (error) {
+		console.warn("Failed to detect OpenCode import source", error);
+	}
+
+	return {
+		storagePath: getStoragePath(),
+		namedBackupCount,
+		rotatingBackupCount,
+		hasOpencodeSource,
+	};
+}
+
+async function runFirstRunWizard(
+	displaySettings: DashboardDisplaySettings,
+): Promise<"continue" | "cancelled"> {
+	while (true) {
+		const action = await showFirstRunWizard(await buildFirstRunWizardOptions());
+		switch (action.type) {
+			case "cancel":
+				console.log("Cancelled.");
+				return "cancelled";
+			case "login":
+			case "skip":
+				return "continue";
+			case "restore":
+				await runBackupBrowserManager(displaySettings);
+				break;
+			case "import-opencode": {
+				const assessment = await assessOpencodeAccountPool();
+				if (!assessment) {
+					console.log("No OpenCode account pool was detected.");
+					break;
+				}
+				if (!assessment.valid || assessment.wouldExceedLimit) {
+					console.log(
+						assessment.error ?? "OpenCode account pool is not importable.",
+					);
+					break;
+				}
+				const confirmed = await confirm(
+					`Import OpenCode accounts from ${assessment.backup.path}?`,
+				);
+				if (!confirmed) {
+					break;
+				}
+				await runActionPanel(
+					"Import OpenCode Accounts",
+					`Importing from ${assessment.backup.path}`,
+					async () => {
+						const imported = await importAccounts(assessment.backup.path);
+						console.log(
+							`Imported ${imported.imported} account${imported.imported === 1 ? "" : "s"}. Skipped ${imported.skipped}. Total accounts: ${imported.total}.`,
+						);
+					},
+					displaySettings,
+				);
+				break;
+			}
+			case "settings":
+				await configureUnifiedSettings(displaySettings);
+				break;
+			case "doctor":
+				await runActionPanel(
+					"Doctor",
+					"Checking storage and sync paths",
+					async () => {
+						await runDoctor(["--json"]);
+					},
+					displaySettings,
+				);
+				break;
+		}
+	}
+}
+
 async function runAuthLogin(): Promise<number> {
 	setStoragePath(null);
 	let suppressRecoveryPrompt = false;
@@ -5095,6 +5193,18 @@ async function runAuthLogin(): Promise<number> {
 				}
 			}
 		}
+		if (existingCount === 0 && isInteractiveLoginMenuAvailable()) {
+			const displaySettings = await loadDashboardDisplaySettings();
+			applyUiThemeFromDashboardSettings(displaySettings);
+			const firstRunResult = await runFirstRunWizard(displaySettings);
+			if (firstRunResult === "cancelled") {
+				return 0;
+			}
+			const refreshedAfterWizard = await loadAccounts();
+			if ((refreshedAfterWizard?.accounts.length ?? 0) > 0) {
+				continue;
+			}
+		}
 		let forceNewLogin = existingCount > 0;
 		while (true) {
 			const tokenResult = await runOAuthFlow(forceNewLogin);

lib/ui/auth-menu.ts

@@ -82,6 +82,22 @@ export type AuthMenuAction =
 	| { type: "delete-all" }
 	| { type: "cancel" };
 
+export interface FirstRunWizardOptions {
+	storagePath: string;
+	namedBackupCount: number;
+	rotatingBackupCount: number;
+	hasOpencodeSource: boolean;
+}
+
+export type FirstRunWizardAction =
+	| { type: "login" }
+	| { type: "restore" }
+	| { type: "import-opencode" }
+	| { type: "settings" }
+	| { type: "doctor" }
+	| { type: "skip" }
+	| { type: "cancel" };
+
 export type AccountAction =
 	| "back"
 	| "delete"
@@ -935,4 +951,47 @@ export async function showAccountDetails(
 	}
 }
 
+export async function showFirstRunWizard(
+	options: FirstRunWizardOptions,
+): Promise<FirstRunWizardAction> {
+	const ui = getUiRuntimeOptions();
+	const items: MenuItem<FirstRunWizardAction>[] = [
+		{
+			label: UI_COPY.firstRun.restore,
+			hint: UI_COPY.firstRun.backupSummary(
+				options.namedBackupCount,
+				options.rotatingBackupCount,
+			),
+			value: { type: "restore" },
+			color: "yellow",
+		},
+		...(options.hasOpencodeSource
+			? [
+					{
+						label: UI_COPY.firstRun.importOpencode,
+						value: { type: "import-opencode" as const },
+						color: "yellow" as const,
+					},
+				]
+			: []),
+		{ label: UI_COPY.firstRun.login, value: { type: "login" }, color: "green" },
+		{ label: UI_COPY.firstRun.settings, value: { type: "settings" } },
+		{ label: UI_COPY.firstRun.doctor, value: { type: "doctor" } },
+		{ label: UI_COPY.firstRun.skip, value: { type: "skip" } },
+		{ label: UI_COPY.firstRun.cancel, value: { type: "cancel" }, color: "red" },
+	];
+
+	const result = await select(items, {
+		message: UI_COPY.firstRun.title,
+		subtitle: UI_COPY.firstRun.subtitle(options.storagePath),
+		help: UI_COPY.firstRun.help,
+		clearScreen: true,
+		selectedEmphasis: "minimal",
+		focusStyle: ui.v2Enabled ? "chip" : "row-invert",
+		theme: ui.theme,
+	});
+
+	return result ?? { type: "cancel" };
+}
+
 export { isTTY };

lib/ui/copy.ts

@@ -146,6 +146,27 @@ export const UI_COPY = {
 			"(a) add, (c) check, (b) best, fi(x), (s) settings, (d) deep, (g) problem, (f) fresh, (r) reset, (q) back [a/c/b/x/s/d/g/f/r/q]: ",
 		invalidModePrompt: "Use one of: a, c, b, x, s, d, g, f, r, q.",
 	},
+	firstRun: {
+		title: "First-Run Setup",
+		subtitle: (storagePath: string) =>
+			`No saved accounts detected. Storage will be created at ${storagePath}.`,
+		backupSummary: (named: number, rotating: number) => {
+			const total = named + rotating;
+			if (total === 0) return "No backups detected yet";
+			if (named > 0 && rotating > 0)
+				return `Named backups: ${named}, rotating backups: ${rotating}`;
+			if (named > 0) return `Named backups: ${named}`;
+			return `Rotating backups: ${rotating}`;
+		},
+		restore: "Open Backup Browser",
+		importOpencode: "Import OpenCode Accounts",
+		login: "Add or Log In",
+		settings: "Open Settings & Sync",
+		doctor: "Run Doctor / Check Paths",
+		skip: "Skip setup and continue",
+		cancel: "Exit",
+		help: "↑↓ Move | Enter Select | Q Exit",
+	},
 } as const;
 
 /**