fix(auth): prompt for recovery on startup

README.md

@@ -50,6 +50,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 ### Option A: Standard install
 
 ```bash
+npm i -g @openai/codex
 npm i -g codex-multi-auth
 ```
 
@@ -74,16 +75,18 @@ codex auth status
 
 ### Step-by-step
 
-1. Install global package:
+1. Install global packages:
+   - `npm i -g @openai/codex`
    - `npm i -g codex-multi-auth`
 2. Run first login flow with `codex auth login`
-3. Validate state with `codex auth status` and `codex auth check`
+3. Validate state with `codex auth list` and `codex auth check`
 4. Confirm routing with `codex auth forecast --live`
 
 ### Verification
 
 ```bash
 codex auth status
+codex auth list
 codex auth check
 ```
 
@@ -95,7 +98,7 @@ codex auth check
 
 ```bash
 codex auth login
-codex auth status
+codex auth list
 codex auth check
 codex auth forecast --live
 ```

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.
 
+If interactive `codex auth login` starts with zero saved accounts and recoverable named backups in your `backups/` directory, the login flow will prompt you to restore before opening OAuth. Confirm to launch the existing restore manager; skip to proceed with a fresh login. The prompt is suppressed in non-interactive/fallback flows and after same-session `fresh` or `reset` actions.
+
 Verify the new account:
 
 ```bash

docs/reference/commands.md

@@ -26,6 +26,7 @@ Compatibility aliases are supported:
 | `codex auth switch <index>` | Set active account by index |
 | `codex auth check` | Run quick account health check |
 | `codex auth features` | Print implemented feature summary |
+| `codex auth restore-backup` | Open the backup restore picker directly |
 
 ---
 
@@ -111,6 +112,7 @@ codex auth report --live --json
 Repair and recovery:
 
 ```bash
+codex auth restore-backup
 codex auth fix --dry-run
 codex auth fix --live --model gpt-5-codex
 codex auth doctor --fix

docs/reference/storage-paths.md

@@ -22,6 +22,7 @@ Override root:
 | --- | --- |
 | Unified settings | `~/.codex/multi-auth/settings.json` |
 | Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` |
+| Named backups | `~/.codex/multi-auth/backups/<name>.json` |
 | Accounts backup | `~/.codex/multi-auth/openai-codex-accounts.json.bak` |
 | Accounts WAL | `~/.codex/multi-auth/openai-codex-accounts.json.wal` |
 | Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` |
@@ -56,6 +57,7 @@ Backup metadata:
 When project-scoped behavior is enabled:
 
 - `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json`
+- `~/.codex/multi-auth/projects/<project-key>/backups/<name>.json`
 
 `<project-key>` is derived as:
 
@@ -100,6 +102,17 @@ Rules:
 - `.rotate.`, `.tmp`, and `.wal` names are rejected
 - existing files are not overwritten unless a lower-level force path is used explicitly
 
+Restore workflow:
+
+1. Run `codex auth login`.
+2. Open the `Recovery` section.
+3. Choose `Restore From Backup`.
+4. Pick a backup and confirm the merge summary before import.
+
+Direct entrypoint:
+
+- Run `codex auth restore-backup` to open the same picker without entering the full login dashboard first.
+
 ---
 
 ## oc-chatgpt Target Paths
@@ -115,6 +128,7 @@ Experimental sync targets the companion `oc-chatgpt-multi-auth` storage layout:
 ## Verification Commands
 
 ```bash
+codex auth login
 codex auth status
 codex auth list
 ```

docs/troubleshooting.md

@@ -18,6 +18,8 @@ If the account pool is still not usable:
 codex auth login
 ```
 
+If `codex auth login` starts with no saved accounts and recoverable named backups are present, you will be prompted to restore before OAuth. This prompt only appears in interactive terminals and is skipped after same-session fresh/reset flows.
+
 ---
 
 ## Verify Install And Routing
@@ -89,24 +91,52 @@ codex auth doctor --json
 
 ---
 
-## Soft Reset
+## Reset Options
+
+- Delete a single saved account: `codex auth login` → pick account → **Delete Account**
+- Delete saved accounts: `codex auth login` → Danger Zone → **Delete Saved Accounts**
+- Reset local state: `codex auth login` → Danger Zone → **Reset Local State**
+
+Exact effects:
+
+| Action | Saved accounts | Flagged/problem accounts | Settings | Codex CLI sync state | Quota cache |
+| --- | --- | --- | --- | --- | --- |
+| Delete Account | Delete the selected saved account | Delete the matching flagged/problem entry for that refresh token | Keep | Keep | Keep |
+| Delete Saved Accounts | Delete all saved accounts | Keep | Keep | Keep | Keep |
+| Reset Local State | Delete all saved accounts | Delete all flagged/problem accounts | Keep | Keep | Clear |
+
+To perform the same actions manually:
 
-PowerShell:
+Delete saved accounts only:
 
 ```powershell
 Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json" -Force -ErrorAction SilentlyContinue
-Remove-Item "$HOME\.codex\multi-auth\openai-codex-flagged-accounts.json" -Force -ErrorAction SilentlyContinue
-Remove-Item "$HOME\.codex\multi-auth\settings.json" -Force -ErrorAction SilentlyContinue
-codex auth login
+Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.wal" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.bak*" -Force -ErrorAction SilentlyContinue
 ```
 
-Bash:
+```bash
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json.wal
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json.bak*
+```
+
+Reset local state (also clears flagged/problem accounts and quota cache; preserves settings and Codex CLI sync state):
+
+```powershell
+Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.wal" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json.bak*" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\openai-codex-flagged-accounts.json" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.codex\multi-auth\quota-cache.json" -Force -ErrorAction SilentlyContinue
+```
 
 ```bash
 rm -f ~/.codex/multi-auth/openai-codex-accounts.json
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json.wal
+rm -f ~/.codex/multi-auth/openai-codex-accounts.json.bak*
 rm -f ~/.codex/multi-auth/openai-codex-flagged-accounts.json
-rm -f ~/.codex/multi-auth/settings.json
-codex auth login
+rm -f ~/.codex/multi-auth/quota-cache.json
 ```
 
 ---

docs/upgrade.md

@@ -62,6 +62,12 @@ After source selection, environment variables still override individual setting
 For day-to-day operator use, prefer stable overrides documented in [configuration.md](configuration.md).
 For maintainer/debug flows, see advanced/internal controls in [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md).
 
+### Startup Recovery Prompt
+
+Interactive `codex auth login` now offers named-backup recovery before OAuth only when the session starts with zero saved accounts and at least one recoverable named backup.
+
+The prompt is intentionally skipped in fallback/non-interactive login paths and after same-session `fresh` or `reset` actions so an intentional wipe does not immediately re-offer restore state.
+
 ---
 
 ## Legacy Compatibility

index.ts

@@ -101,6 +101,12 @@ import {
 } from "./lib/logger.js";
 import { checkAndNotify } from "./lib/auto-update-checker.js";
 import { handleContextOverflow } from "./lib/context-overflow.js";
+import {
+	DESTRUCTIVE_ACTION_COPY,
+	deleteAccountAtIndex,
+	deleteSavedAccounts,
+	resetLocalState,
+} from "./lib/destructive-actions.js";
 import {
 	AccountManager,
         getAccountIdCandidates,
@@ -122,13 +128,11 @@ import {
 	loadAccounts,
 	saveAccounts,
 	withAccountStorageTransaction,
-	clearAccounts,
 	setStoragePath,
 	exportAccounts,
 	importAccounts,
 	loadFlaggedAccounts,
 	saveFlaggedAccounts,
-	clearFlaggedAccounts,
 	findMatchingAccountIndex,
 	StorageError,
 	formatStorageErrorHint,
@@ -3101,19 +3105,18 @@ while (attempted.size < Math.max(1, accountCount)) {
 
 									if (menuResult.mode === "manage") {
 										if (typeof menuResult.deleteAccountIndex === "number") {
-											const target = workingStorage.accounts[menuResult.deleteAccountIndex];
-											if (target) {
-												workingStorage.accounts.splice(menuResult.deleteAccountIndex, 1);
-												clampActiveIndices(workingStorage);
-												await saveAccounts(workingStorage);
-												await saveFlaggedAccounts({
-													version: 1,
-													accounts: flaggedStorage.accounts.filter(
-														(flagged) => flagged.refreshToken !== target.refreshToken,
-													),
-												});
+											const deleted = await deleteAccountAtIndex({
+												storage: workingStorage,
+												index: menuResult.deleteAccountIndex,
+											});
+											if (deleted) {
 												invalidateAccountManagerCache();
-												console.log(`\nDeleted ${target.email ?? `Account ${menuResult.deleteAccountIndex + 1}`}.\n`);
+												const label = `Account ${menuResult.deleteAccountIndex + 1}`;
+												const flaggedNote =
+													deleted.removedFlaggedCount > 0
+														? ` Removed ${deleted.removedFlaggedCount} matching problem account${deleted.removedFlaggedCount === 1 ? "" : "s"}.`
+														: "";
+												console.log(`\nDeleted ${label}.${flaggedNote}\n`);
 											}
 											continue;
 										}
@@ -3143,16 +3146,35 @@ while (attempted.size < Math.max(1, accountCount)) {
 									if (menuResult.mode === "fresh") {
 										startFresh = true;
 										if (menuResult.deleteAll) {
-											await clearAccounts();
-											await clearFlaggedAccounts();
+											const result = await deleteSavedAccounts();
 											invalidateAccountManagerCache();
 											console.log(
-												"\nCleared saved accounts from active storage. Recovery snapshots remain available. Starting fresh.\n",
+												`\n${
+													result.accountsCleared
+														? DESTRUCTIVE_ACTION_COPY.deleteSavedAccounts.completed
+														: "Delete saved accounts completed with warnings. Some saved account artifacts could not be removed; see logs."
+												}\n`,
 											);
 										}
 										break;
 									}
 
+									if (menuResult.mode === "reset") {
+										startFresh = true;
+										const result = await resetLocalState();
+										invalidateAccountManagerCache();
+										console.log(
+											`\n${
+												result.accountsCleared &&
+												result.flaggedCleared &&
+												result.quotaCacheCleared
+													? DESTRUCTIVE_ACTION_COPY.resetLocalState.completed
+													: "Reset local state completed with warnings. Some local artifacts could not be removed; see logs."
+											}\n`,
+										);
+										break;
+									}
+
 									startFresh = false;
 									break;
 								}