feat(auth): add backup browser and rotating restore support

README.md

@@ -16,8 +16,8 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 - Canonical `codex auth ...` workflow for account login, switching, checks, and diagnostics
 - Multi-account OAuth pool with health-aware selection and automatic failover
 - Project-scoped account storage under `~/.codex/multi-auth/projects/<project-key>/...`
-- Interactive dashboard for account actions and settings
-- Experimental settings tab for staged sync, backup, and refresh-guard controls
+- Interactive dashboard for login, restore, switching, sync preview, and settings
+- Productized settings split across `Everyday Settings`, `Codex CLI Sync`, `Experimental`, and `Advanced & Operator`
 - Forecast, report, fix, and doctor commands for operational safety
 - Flagged account verification and restore flow
 - Session affinity and live account sync controls
@@ -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
 ```
@@ -109,6 +112,12 @@ codex auth fix --dry-run
 codex auth doctor --fix
 ```
 
+Interactive dashboard paths:
+
+- restore named backups: `codex auth login` -> `Restore From Backup`
+- preview Codex CLI sync: `codex auth login` -> `Settings` -> `Codex CLI Sync`
+- adjust stable dashboard preferences: `codex auth login` -> `Settings` -> `Everyday Settings`
+
 ---
 
 ## Command Toolkit
@@ -234,6 +243,7 @@ codex auth login
 - `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
 - Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
 - OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
+- Interactive login skipped restore and went straight to OAuth: place named backups in `~/.codex/multi-auth/backups/`, then rerun `codex auth login` in a normal TTY
 - `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
 
 </details>

docs/README.md

@@ -17,13 +17,13 @@ Public documentation for `codex-multi-auth`.
 
 | Document | Focus |
 | --- | --- |
-| [index.md](index.md) | Daily-use landing page for common `codex auth ...` workflows |
-| [getting-started.md](getting-started.md) | Install, first login, and first health check |
+| [index.md](index.md) | Daily-use landing page for login, restore, sync, and diagnostics workflows |
+| [getting-started.md](getting-started.md) | Install, first login, startup restore prompt, and first health check |
 | [faq.md](faq.md) | Short answers to common adoption questions |
 | [architecture.md](architecture.md) | Public system overview of the wrapper, storage, and optional plugin runtime |
-| [features.md](features.md) | User-facing capability map |
+| [features.md](features.md) | User-facing capability map, including backup restore, sync center, and settings split |
 | [configuration.md](configuration.md) | Stable defaults, precedence, and environment overrides |
-| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, switching, and stale state |
+| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, restore, sync, and stale state |
 | [privacy.md](privacy.md) | Data handling and local storage behavior |
 | [upgrade.md](upgrade.md) | Migration from legacy package and path history |
 | [releases/v0.1.9.md](releases/v0.1.9.md) | Stable release notes |
@@ -39,8 +39,8 @@ Public documentation for `codex-multi-auth`.
 
 | Document | Focus |
 | --- | --- |
-| [reference/commands.md](reference/commands.md) | Commands, flags, and hotkeys |
-| [reference/settings.md](reference/settings.md) | Dashboard and runtime settings |
+| [reference/commands.md](reference/commands.md) | Commands, flags, hotkeys, and interactive entry points |
+| [reference/settings.md](reference/settings.md) | Everyday settings, sync center, and advanced operator controls |
 | [reference/storage-paths.md](reference/storage-paths.md) | Canonical and compatibility storage paths |
 | [reference/public-api.md](reference/public-api.md) | Public API stability and semver contract |
 | [reference/error-contracts.md](reference/error-contracts.md) | CLI, JSON, and helper error semantics |

docs/features.md

@@ -9,6 +9,8 @@ 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` |
+| Startup recovery prompt | Offer restore before OAuth when recoverable named backups are found and no active accounts exist | `codex auth login` |
+| Backup restore manager | Review named backups, merge with dedupe, and skip invalid or over-limit restores | `codex auth login` -> `Restore From Backup` |
 | 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` |
@@ -32,6 +34,7 @@ User-facing capability map for `codex-multi-auth`.
 | --- | --- | --- |
 | Safe repair workflow | Detects and repairs known local storage inconsistencies | `codex auth fix` |
 | Diagnostics with optional repair | One command to inspect and optionally fix common failures | `codex auth doctor` |
+| JSON diagnostics pack | Machine-readable state for support, bug reports, and deeper inspection | `codex auth report --live --json` |
 | Backup and WAL recovery | Safer persistence when local writes are interrupted or partially applied | storage runtime |
 
 ---
@@ -53,6 +56,8 @@ User-facing capability map for `codex-multi-auth`.
 | --- | --- |
 | Quick switch and search hotkeys | Faster navigation in the dashboard |
 | Account action hotkeys | Per-account set, refresh, toggle, and delete shortcuts |
+| Productized settings split | Keeps `Everyday Settings` separate from `Advanced & Operator` controls |
+| Preview-first sync center | Shows one-way Codex CLI sync results and rollback context before apply |
 | In-dashboard settings hub | Runtime and display tuning without editing files directly |
 | Browser-first OAuth with manual fallback | Works in normal and constrained terminal environments |
 

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
@@ -70,6 +72,29 @@ codex auth forecast --live
 
 ---
 
+## Restore Or Start Fresh
+
+Use the restore path when you already have named backup files and want to recover account state before creating new OAuth sessions.
+
+- Automatic path: run `codex auth login`, then confirm the startup restore prompt when it appears
+- Manual path: run `codex auth login`, then choose `Restore From Backup`
+- Backup location: `~/.codex/multi-auth/backups/<name>.json`
+
+The restore manager shows each backup name, account count, freshness, and whether the restore would exceed the account limit before it lets you apply anything.
+
+---
+
+## Sync And Settings
+
+The settings flow is split into two productized sections:
+
+- `Everyday Settings` for list appearance, details line, results and refresh behavior, and colors
+- `Advanced & Operator` for `Codex CLI Sync`, `Experimental`, and backend tuning
+
+Use `Codex CLI Sync` when you want to preview one-way sync from official Codex CLI account files before applying it. The sync screen shows source and target paths, preview summary, destination-only preservation, and backup rollback paths before apply.
+
+---
+
 ## Day-1 Command Pack
 
 ```bash

docs/index.md

@@ -1,6 +1,6 @@
 # codex-multi-auth Docs
 
-Daily-use guide for the `codex auth ...` workflow.
+Daily-use guide for the `codex auth ...` workflow, including restore, sync, and diagnostics.
 
 ---
 
@@ -12,6 +12,8 @@ codex auth list
 codex auth check
 ```
 
+If login detects recoverable named backups before OAuth, confirm the prompt to open `Restore From Backup` first.
+
 If you are choosing an account for the next session:
 
 ```bash
@@ -39,6 +41,12 @@ codex auth report --live --json
 codex auth doctor --fix
 ```
 
+Interactive workflows that ship in the dashboard:
+
+- backup restore: `codex auth login` -> `Restore From Backup`
+- sync preview and apply: `codex auth login` -> `Settings` -> `Codex CLI Sync`
+- settings split: `codex auth login` -> `Settings` -> `Everyday Settings` or `Advanced & Operator`
+
 ---
 
 ## Canonical Policy

docs/reference/commands.md

@@ -20,12 +20,13 @@ Compatibility aliases are supported:
 
 | Command | Description |
 | --- | --- |
-| `codex auth login` | Open interactive auth dashboard |
+| `codex auth login` | Open interactive auth dashboard, including login, restore, settings, and diagnostics entry points |
 | `codex auth list` | List saved accounts and active account |
 | `codex auth status` | Print short runtime/account summary |
 | `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 |
 
 ---
 
@@ -90,16 +91,26 @@ Compatibility aliases are supported:
 
 Settings screen hotkeys are panel-specific:
 
-- Account List View: `Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)`
-- Summary Line: `Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Back (No Save)`
-- Menu Behavior: `Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Back (No Save)`
-- Color Theme: `Enter Select | 1-2 Base | S Save | Q Back (No Save)`
-- Backend Controls: `Enter Open | 1-4 Category | S Save | R Reset | Q Back (No Save)`
+- List Appearance: `Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)`
+- Details Line: `Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Back (No Save)`
+- Results & Refresh: `Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Back (No Save)`
+- Colors: `Enter Select | 1-2 Base | S Save | Q Back (No Save)`
+- Advanced Backend Controls: `Enter Open | 1-4 Category | S Save | R Reset | Q Back (No Save)`
 
 ---
 
 ## Workflow Packs
 
+Interactive dashboard workflows:
+
+- Backup restore: `codex auth login` -> `Restore From Backup`
+- Startup recovery prompt: interactive `codex auth login` TTY flow only, then confirm restore when recoverable named backups are found before OAuth
+- Sync preview and apply: `codex auth login` -> `Settings` -> `Codex CLI Sync`
+- Stable settings path: `codex auth login` -> `Settings` -> `Everyday Settings`
+- Advanced settings path: `codex auth login` -> `Settings` -> `Advanced & Operator`
+
+---
+
 Health and planning:
 
 ```bash
@@ -111,6 +122,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/settings.md

@@ -1,6 +1,6 @@
 # Settings Reference
 
-Reference for dashboard and backend settings available from `codex auth login` -> `Settings`.
+Reference for the settings surface available from `codex auth login` -> `Settings`.
 
 ---
 
@@ -19,7 +19,11 @@ When `CODEX_MULTI_AUTH_DIR` is set, this root moves accordingly.
 
 ---
 
-## Account List View
+## Everyday Settings
+
+The shipped settings menu starts with `Everyday Settings` and keeps the stable dashboard path separate from advanced operator controls. This is the default path for most users.
+
+### List Appearance
 
 Controls account-row display and sorting behavior:
 
@@ -37,7 +41,7 @@ Controls account-row display and sorting behavior:
 - `menuSortQuickSwitchVisibleRow`
 - `menuLayoutMode`
 
-## Summary Line
+### Details Line
 
 Controls detail-line fields and order:
 
@@ -46,7 +50,7 @@ Controls detail-line fields and order:
 - `limits`
 - `status`
 
-## Menu Behavior
+### Results & Refresh
 
 Controls result-screen and fetch behavior:
 
@@ -56,7 +60,7 @@ Controls result-screen and fetch behavior:
 - `menuShowFetchStatus`
 - `menuQuotaTtlMs`
 
-## Color Theme
+### Colors
 
 Controls display style:
 
@@ -66,7 +70,38 @@ Controls display style:
 
 ---
 
-## Experimental
+## Advanced and Operator Controls
+
+The second top-level section is `Advanced & Operator`. It holds the sync workflow and backend tuning that are useful when you need to inspect or change lower-level behavior.
+
+### Codex CLI Sync
+
+`Codex CLI Sync` is a preview-first sync center for Codex CLI account sync.
+See [upgrade notes](../upgrade.md) for sync workflow changes.
+
+Before applying sync, it shows:
+
+- target path
+- current source path when available
+- last sync result for this session
+- preview summary (adds, updates, destination-only preserved accounts)
+- destination-only preservation behavior
+- backup and rollback context (`.bak`, `.bak.1`, `.bak.2`, `.wal`)
+
+Workflow notes:
+
+- refresh recomputes the read-only preview from Codex CLI source files
+- apply writes the preview result into the target path
+- sync is one-way, it is not a bidirectional merge
+- target-only accounts are preserved rather than deleted
+
+Validation:
+
+- `npm run typecheck`
+- `npm run build`
+- `npm test`
+
+### Experimental
 
 Experimental currently hosts:
 
@@ -88,7 +123,11 @@ Named backup behavior:
 - rejects separators, traversal (`..`), `.rotate.`, `.tmp`, and `.wal` suffixes
 - fails safely on collisions instead of overwriting by default
 
-## Backend Controls
+### Advanced Backend Controls
+
+`Advanced Backend Controls` stay available without changing the saved settings schema. They are grouped into categories so the everyday path can stay simpler for day-to-day use.
+
+## Backend Categories
 
 ### Session & Sync
 
@@ -178,6 +217,7 @@ For most environments:
 
 - smart sort enabled
 - auto-fetch limits enabled
+- storage backups enabled when you want rollback context for sync and recovery flows
 - live sync enabled
 - session affinity enabled
 - preemptive quota deferral enabled

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
 ```