Merge branch 'pr-137-head' into release-integration-20260320

# Conflicts:
#	lib/codex-manager.ts
#	test/codex-manager-cli.test.ts

Author: ndycode

docs/features.md

@@ -9,6 +9,7 @@ User-facing capability map for `codex-multi-auth`.
 | Capability | What it gives you | Primary entry |
 | --- | --- | --- |
 | Multi-account dashboard login | Add and manage multiple OAuth identities from one terminal flow | `codex auth login` |
+| Onboarding backup restore | Restores the latest named backup or lets you choose a named backup manually when a fresh install or empty pool needs to recover saved accounts fast | `codex auth login` |
 | Account dedupe and identity normalization | Avoid duplicate saved account rows | login flow |
 | Explicit active-account switching | Pick the current account by index instead of relying on hidden state | `codex auth switch <index>` |
 | Fast and deep health checks | See whether the current pool is usable before a coding session | `codex auth check` |

docs/getting-started.md

@@ -43,11 +43,21 @@ codex auth login
 
 Expected flow:
 
-1. The dashboard opens in the terminal.
-2. Choose `Add New Account`.
-3. Complete the official OAuth flow in your browser.
-4. Return to the terminal when the browser step completes.
-5. Confirm the account appears in the saved account list.
+Backup restore appears as `Restore Saved Backup` under the `Recover saved accounts` heading in the onboarding menu. This flow does not add any new CLI flags or npm scripts.
+See upgrade note: [onboarding restore behavior](upgrade.md#onboarding-restore-note).
+
+1. If no accounts are saved yet, the terminal opens directly to the sign-in menu.
+2. Choose one of the sign-in options:
+   - `Open Browser (Easy)` for the normal OAuth flow
+   - `Manual / Incognito` when you need to paste the callback yourself
+   - `Restore Saved Backup` under the `Recover saved accounts` heading when the current pool is empty and at least one valid named backup exists under `~/.codex/multi-auth/backups` by default, or under `%CODEX_MULTI_AUTH_DIR%\backups` if you override the storage root with `CODEX_MULTI_AUTH_DIR`
+3. If you choose `Restore Saved Backup`, the next menu lets you either:
+   - load the newest valid backup automatically
+   - pick a specific backup from a newest-first list
+   Empty, unreadable, or non-JSON backup sidecar files are skipped, so the menu entry appears only when at least one backup parses successfully and contains at least one account.
+4. If you use browser or manual sign-in, complete the official OAuth flow and return to the terminal.
+5. If you load a backup, the selected backup is restored, its active account is synced back into Codex CLI auth, and the login flow continues with that restored pool.
+6. Confirm the restored or newly signed-in account appears in the saved account list.
 
 Verify the new account:
 

docs/upgrade.md

@@ -76,6 +76,16 @@ For maintainer/debug flows, see advanced/internal controls in [development/CONFI
 
 ---
 
+## Onboarding Restore Note
+
+`codex auth login` now opens directly into the sign-in menu when the active pool is empty, instead of opening the account dashboard first.
+
+- `Recover saved accounts` appears only when at least one valid named backup exists.
+- No new CLI flags or npm scripts were added for this flow.
+- The backup root remains `~/.codex/multi-auth/backups` by default, or `%CODEX_MULTI_AUTH_DIR%\backups` when `CODEX_MULTI_AUTH_DIR` is set.
+
+---
+
 ## Legacy Compatibility
 
 Legacy files may still be discovered during migration-only compatibility checks.

lib/accounts.ts

@@ -101,7 +101,12 @@ export interface ManagedAccount {
 	expires?: number;
 	addedAt: number;
 	lastUsed: number;
-	lastSwitchReason?: "rate-limit" | "initial" | "rotation" | "best";
+	lastSwitchReason?:
+		| "rate-limit"
+		| "initial"
+		| "rotation"
+		| "best"
+		| "restore";
 	lastRateLimitReason?: RateLimitReason;
 	rateLimitResetTimes: RateLimitStateV3;
 	coolingDownUntil?: number;