fix(auth): preserve visible dashboard row numbers

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/v1.1.10.md](releases/v1.1.10.md) | Stable release notes |
@@ -40,8 +40,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,10 @@ 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 accounts from a companion app 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 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 +74,31 @@ 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.
+
+If you already have an OpenCode account pool on the same machine, use the recovery import option from the login dashboard to preview and import those saved accounts before creating new OAuth sessions. The detector checks the standard OpenCode account file and honors `CODEX_OPENCODE_POOL_PATH` when you need to point at a specific file.
+
+---
+
+## 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