docs(auth): align front-door flows with shipped workflows

README.md

@@ -17,7 +17,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
 - 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 login, restore, switching, sync preview, and settings
-- Productized settings split across `Everyday Settings`, `Codex CLI Sync`, `Experimental`, and `Advanced & Operator`
+- Productized settings flow with `Everyday Settings` plus `Advanced & Operator` sections for `Codex CLI Sync`, `Experimental`, and `Advanced Backend Controls`
 - Forecast, report, fix, and doctor commands for operational safety
 - Flagged account verification and restore flow
 - Session affinity and live account sync controls
@@ -115,7 +115,7 @@ 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`
+- preview Codex CLI sync: `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`
 - adjust stable dashboard preferences: `codex auth login` -> `Settings` -> `Everyday Settings`
 
 ---
@@ -179,16 +179,17 @@ Override root with `CODEX_MULTI_AUTH_DIR=<path>`.
 
 ## Configuration
 
-Primary config root:
-- `~/.codex/multi-auth/settings.json`
-- or `CODEX_MULTI_AUTH_DIR/settings.json` when custom root is set
+Primary config file:
+- `~/.codex/multi-auth/settings.json` by default
+- `CODEX_MULTI_AUTH_DIR/settings.json` when a custom root is set
+- `CODEX_MULTI_AUTH_CONFIG_PATH=<path>` when you want to override the default config file lookup
 
 Selected runtime/environment overrides:
 
 | Variable | Effect |
 | --- | --- |
 | `CODEX_MULTI_AUTH_DIR` | Override settings/accounts root |
-| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file path |
+| `CODEX_MULTI_AUTH_CONFIG_PATH` | Override the default config file path lookup |
 | `CODEX_MODE=0/1` | Disable/enable Codex mode |
 | `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16` | TUI color profile |
@@ -210,7 +211,7 @@ codex auth forecast --live
 
 The Settings menu now includes an `Experimental` section for staged features:
 
-- preview-first sync into `oc-chatgpt-multi-auth`
+- preview-first sync into the companion `oc-chatgpt-multi-auth` account pool
 - named local pool backup export with filename prompt
 - refresh guard toggle and interval controls moved out of Backend Controls
 
@@ -243,7 +244,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
+- Interactive login skipped restore and went straight to OAuth: place named backups in your active backup root (`$CODEX_MULTI_AUTH_DIR/backups` or `%CODEX_MULTI_AUTH_DIR%\backups`; default examples: `~/.codex/multi-auth/backups/` and `C:\Users\<User>\.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/getting-started.md

@@ -78,7 +78,7 @@ Use the restore path when you already have named backup files and want to recove
 
 - 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`
+- Backup location: `~/.codex/multi-auth/backups/<name>.json` (or `C:\Users\<User>\.codex\multi-auth\backups\<name>.json` on Windows; override with `CODEX_MULTI_AUTH_DIR`)
 
 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.
 

docs/index.md

@@ -44,7 +44,7 @@ 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`
+- sync preview and apply: `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`
 - settings split: `codex auth login` -> `Settings` -> `Everyday Settings` or `Advanced & Operator`
 
 ---

docs/reference/commands.md

@@ -20,7 +20,7 @@ Compatibility aliases are supported:
 
 | Command | Description |
 | --- | --- |
-| `codex auth login` | Open interactive auth dashboard, including login, restore, settings, and diagnostics entry points |
+| `codex auth login` | Open interactive auth dashboard, including login, restore, settings, and dashboard paths and links to diagnostics commands |
 | `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 |
@@ -105,7 +105,7 @@ 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`
+- Sync preview and apply: `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`
 - Stable settings path: `codex auth login` -> `Settings` -> `Everyday Settings`
 - Advanced settings path: `codex auth login` -> `Settings` -> `Advanced & Operator`
 

docs/reference/settings.md

@@ -70,23 +70,21 @@ Controls display style:
 
 ---
 
-## Advanced and Operator Controls
+## Advanced & Operator
 
 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`)
+- backup and rollback context (`.bak`, `.bak.1`, `.bak.2`, `.wal`) when storage backups are enabled
 
 Workflow notes:
 
@@ -95,12 +93,6 @@ Workflow notes:
 - 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:

docs/troubleshooting.md

@@ -63,8 +63,8 @@ npm i -g codex-multi-auth
 
 | Symptom | Likely cause | Action |
 | --- | --- | --- |
-| You expected a restore prompt but went straight to OAuth | No recoverable named backups were found, the terminal is non-interactive, or the flow is skipping restore after an intentional reset | Put named backup files in `~/.codex/multi-auth/backups/`, then rerun `codex auth login` in an interactive terminal |
-| `Restore From Backup` says no backups were found | The named backup directory is empty or the files are elsewhere | Place backup files in `~/.codex/multi-auth/backups/` and retry |
+| You expected a restore prompt but went straight to OAuth | No recoverable named backups were found, the terminal is non-interactive, or the flow is skipping restore after an intentional reset | Verify the active backup root (`$CODEX_MULTI_AUTH_DIR/backups` or `%CODEX_MULTI_AUTH_DIR%\backups`; default examples: `~/.codex/multi-auth/backups/` and `C:\Users\<User>\.codex\multi-auth\backups\`), then rerun `codex auth login` in an interactive terminal |
+| `Restore From Backup` says no backups were found | The named backup directory is empty or the files are elsewhere under the active data root | Place backup files in the active backup root (`$CODEX_MULTI_AUTH_DIR/backups` or `%CODEX_MULTI_AUTH_DIR%\backups`) and retry |
 | A backup is listed but cannot be selected | The backup is invalid or would exceed the account limit | Trim current accounts first or choose a different backup |
 | Restore succeeded but some rows were skipped | Deduping kept the existing matching account state | Run `codex auth list` and `codex auth check` to review the merged result |
 
@@ -82,12 +82,12 @@ npm i -g codex-multi-auth
 
 ## Codex CLI Sync Problems
 
-Use `codex auth login` -> `Settings` -> `Codex CLI Sync` when you want to inspect sync state before applying it.
+Use `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync` when you want to inspect sync state before applying it.
 
 | Symptom | Likely cause | Action |
 | --- | --- | --- |
 | Sync preview looks one-way | This is the shipped behavior | Review the preview, then apply only if the target result is what you want |
-| A target-only account would be lost | The sync center preserves destination-only accounts instead of deleting them | Recheck the preview summary before apply |
+| You want to confirm target-only accounts are preserved | The sync center preserves destination-only accounts instead of deleting them | Recheck the preview summary before apply |
 | You want rollback context before syncing | Backup support is disabled in current settings | Enable storage backups in advanced settings, then refresh the sync preview |
 | Active selection does not match expectation | Preview kept the newer local choice or updated from Codex CLI based on selection precedence | Refresh preview and review the selection summary before apply |
 
@@ -117,8 +117,8 @@ codex auth doctor --json
 
 Interactive diagnostics path:
 
-- `codex auth login` -> `Settings` -> `Codex CLI Sync` for preview-based sync diagnostics
-- `codex auth login` -> `Settings` -> `Advanced Backend Controls` for sync, retry, quota, recovery, and timeout tuning
+- `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync` for preview-based sync diagnostics
+- `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Advanced Backend Controls` for sync, retry, quota, recovery, and timeout tuning
 
 ---
 

test/documentation.test.ts

@@ -344,7 +344,7 @@ describe("Documentation Integrity", () => {
 		expect(settingsRef).toContain(`### ${UI_COPY.settings.summaryFields}`);
 		expect(settingsRef).toContain(`### ${UI_COPY.settings.behavior}`);
 		expect(settingsRef).toContain(`### ${UI_COPY.settings.theme}`);
-		expect(settingsRef).toContain("## Advanced and Operator Controls");
+		expect(settingsRef).toContain("## Advanced & Operator");
 		expect(settingsRef).toContain(`### ${UI_COPY.settings.syncCenter}`);
 		expect(settingsRef).toContain(`### ${UI_COPY.settings.experimental}`);
 		expect(settingsRef).toContain(`### ${UI_COPY.settings.backend}`);
@@ -361,6 +361,26 @@ describe("Documentation Integrity", () => {
 		expect(settingsRef).toContain("- `menuStatuslineFields`");
 	});
 
+	it("keeps getting-started and troubleshooting docs aligned with current restore and sync flows", () => {
+		const gettingStarted = read("docs/getting-started.md");
+		const troubleshooting = read("docs/troubleshooting.md");
+
+		expect(gettingStarted).toContain("## Restore Or Start Fresh");
+		expect(gettingStarted).toContain("## Sync And Settings");
+		expect(gettingStarted).toContain("Restore From Backup");
+		expect(gettingStarted).toContain(
+			"C:\\Users\\<User>\\.codex\\multi-auth\\backups\\<name>.json",
+		);
+		expect(troubleshooting).toContain("## Backup Restore Problems");
+		expect(troubleshooting).toContain("## Codex CLI Sync Problems");
+		expect(troubleshooting).toContain(
+			"`codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`",
+		);
+		expect(troubleshooting).toContain(
+			"`codex auth login` -> `Settings` -> `Advanced & Operator` -> `Advanced Backend Controls`",
+		);
+	});
+
 	it("keeps changelog aligned with canonical 0.x release policy", () => {
 		const changelog = read("CHANGELOG.md");
 		expect(changelog).toContain("## [0.1.8] - 2026-03-11");