From e89907e5ff496a7e55d637762cc9f5683ee7646e Mon Sep 17 00:00:00 2001 From: ndycode Date: Thu, 19 Mar 2026 21:09:32 +0800 Subject: [PATCH] docs(auth): align front-door flows with shipped workflows --- README.md | 17 +++++++++-------- docs/getting-started.md | 2 +- docs/index.md | 2 +- docs/reference/commands.md | 4 ++-- docs/reference/settings.md | 12 ++---------- docs/troubleshooting.md | 12 ++++++------ test/documentation.test.ts | 22 +++++++++++++++++++++- 7 files changed, 42 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 54fec5cb..b9f5588a 100644 --- a/README.md +++ b/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//...` - 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=`. ## 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=` 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 `, 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\\.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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 8caf3fb4..6738dd79 100644 --- a/docs/getting-started.md +++ b/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/.json` +- Backup location: `~/.codex/multi-auth/backups/.json` (or `C:\Users\\.codex\multi-auth\backups\.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. diff --git a/docs/index.md b/docs/index.md index ec09eff4..938054fa 100644 --- a/docs/index.md +++ b/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` --- diff --git a/docs/reference/commands.md b/docs/reference/commands.md index ab142c2b..5d5f548b 100644 --- a/docs/reference/commands.md +++ b/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 ` | 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` diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 0c9c802f..04b6ee5e 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -70,15 +70,13 @@ 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 @@ -86,7 +84,7 @@ Before applying sync, it shows: - 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: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1595eea7..65ddccc8 100644 --- a/docs/troubleshooting.md +++ b/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\\.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 --- diff --git a/test/documentation.test.ts b/test/documentation.test.ts index eb06a930..d68bddb0 100644 --- a/test/documentation.test.ts +++ b/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\\\\.codex\\multi-auth\\backups\\.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");