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

[ndycode]

Summary

• clean replacement for bloated #109
• keeps only the surviving docs/test alignment that is still valid on current dev

What Changed

• fixes front-door docs to point sync users through Settings -> Advanced & Operator -> Codex CLI Sync
• adds Windows backup-path guidance to docs/getting-started.md and expands README/troubleshooting backup-root wording to match the shipped restore flow
• aligns the settings reference heading/help wording with the current UI and locks the restore/sync path coverage in test/documentation.test.ts

Validation

• npm exec -- vitest run test/documentation.test.ts
• npm run lint
• npm run build

Notes

• Supersedes #109.
• This replay intentionally excludes stale release-note churn and old non-doc changes from the preserved branch.

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

docs-only pr that corrects front-door navigation paths across 6 doc files and adds one new vitest coverage block. the core fix is propagating the Settings -> Advanced & Operator -> Codex CLI Sync path (previously missing the intermediate step) into README, index, commands ref, settings ref, and troubleshooting. windows backup-root guidance is also added to getting-started and troubleshooting.

• all 7 Advanced & Operator nav-path occurrences are now consistent across the docs surface
• docs/reference/settings.md heading renamed to ## Advanced & Operator to match ui copy; stale validation cmds and upgrade.md cross-reference removed
• windows backup paths added (C:\Users\<User>\.codex\multi-auth\backups\) with CODEX_MULTI_AUTH_DIR override note
• new vitest test locks heading name and restore/sync path strings in getting-started + troubleshooting — but does not cover the same path strings in README.md, docs/index.md, or docs/reference/commands.md, leaving those free to drift
• env-var format %CODEX_MULTI_AUTH_DIR%\backups is cmd.exe syntax; the rest of the file uses powershell syntax ($HOME). windows users on powershell need $env:CODEX_MULTI_AUTH_DIR\backups — same issue appears in README.md and docs/getting-started.md
• no concurrency or token safety concerns introduced (docs-only)

Confidence Score: 4/5

• safe to merge; docs-only with no runtime impact — two minor polish issues worth addressing before or after landing
• all nav-path changes are internally consistent, the heading rename is backed by a test assertion, and the new test block adds real regression coverage. the two issues (cmd.exe vs powershell env syntax, and missing test coverage for README/index/commands nav paths) are both style-level — neither blocks correctness or causes a failing build
• docs/troubleshooting.md and test/documentation.test.ts warrant a second look — the former for the windows env-var syntax inconsistency, the latter for the coverage gap on README.md and docs/index.md nav-path assertions

Important Files Changed

Filename	Overview
test/documentation.test.ts	adds a new test locking restore and sync nav paths across getting-started and troubleshooting; heading rename assertion updated to "## Advanced & Operator" — but coverage doesn't extend to README.md, docs/index.md, or docs/reference/commands.md which carry the same path change
docs/troubleshooting.md	backup-root table rows updated to include windows path examples; sync nav path corrected to Advanced & Operator flow; windows env-var format uses cmd.exe %VAR% syntax which is inconsistent with powershell $HOME style used elsewhere in the same file
README.md	sync nav path updated, settings feature list wording aligned with shipped ui, windows backup path added to quick-start troubleshooting — same %VAR% env-var inconsistency as troubleshooting.md
docs/reference/settings.md	heading renamed from "Advanced and Operator Controls" to "## Advanced & Operator" to match ui copy; stale validation section and upgrade.md cross-reference removed; backup/rollback context clarified with "when storage backups are enabled"
docs/getting-started.md	windows backup path added alongside unix path; uses %CODEX_MULTI_AUTH_DIR% override hint which is cmd.exe syntax rather than powershell
docs/index.md	sync nav path corrected to include Advanced & Operator step; clean one-line change
docs/reference/commands.md	sync nav path updated and codex auth login description refined; clean alignment change

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[codex auth login] --> B[Restore From Backup]
    A --> C[Settings]
    C --> D[Everyday Settings]
    C --> E[Advanced & Operator]
    E --> F[Codex CLI Sync]
    E --> G[Experimental]
    E --> H[Advanced Backend Controls]
    D --> D1[List Appearance]
    D --> D2[Details Line]
    D --> D3[Results & Refresh]
    D --> D4[Colors]
    F --> F1[Preview sync]
    F --> F2[Apply sync]
    H --> H1[Session & Sync]
    H --> H2[Rotation & Quota]
    H --> H3[Refresh & Recovery]
    H --> H4[Performance & Timeouts]

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/troubleshooting.md
Line: 66-67

Comment:
**Windows env-var syntax is cmd.exe, not PowerShell**

the rest of `troubleshooting.md` uses PowerShell syntax throughout (e.g. `$HOME\.codex\...` in the Reset Options section). but the new backup-root guidance uses `%CODEX_MULTI_AUTH_DIR%\backups`, which is cmd.exe syntax. a PowerShell user will hit a dead end trying to expand that — they need `$env:CODEX_MULTI_AUTH_DIR\backups`. this same pattern is also introduced in `README.md` line 244 and `docs/getting-started.md` line 81.

consider aligning with PowerShell:

```suggestion
| 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` on Unix or `$env:CODEX_MULTI_AUTH_DIR\backups` in PowerShell; 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` on Unix or `$env:CODEX_MULTI_AUTH_DIR\backups` in PowerShell) and retry |
```

same fix needed in `README.md` line 244 and `docs/getting-started.md` line 81.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: test/documentation.test.ts
Line: 364-382

Comment:
**missing vitest coverage for README.md and index.md nav-path changes**

the new test locks the sync nav path in `troubleshooting.md` and the windows backup path in `getting-started.md`, but the same `Advanced & Operator -> Codex CLI Sync` path is now live in `README.md` (line 118), `docs/index.md`, and `docs/reference/commands.md` with no corresponding assertions. if one of those drifts back to the old path, the test suite won't catch it.

suggest adding assertions for the files that also carry the updated path:

```suggestion
	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");
		const readme = read("README.md");
		const index = read("docs/index.md");
		const commandRef = read("docs/reference/commands.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`",
		);
		const syncNavPath = "`Settings` -> `Advanced & Operator` -> `Codex CLI Sync`";
		expect(readme).toContain(syncNavPath);
		expect(index).toContain(syncNavPath);
		expect(commandRef).toContain(syncNavPath);
	});
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "docs(auth): align fr..."}

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 918b1c83-9aec-488d-9fb4-8de1aae6aec9

📥 Commits

Reviewing files that changed from the base of the PR and between 115f93f and e89907e.

📒 Files selected for processing (7)

• README.md
• docs/getting-started.md
• docs/index.md
• docs/reference/commands.md
• docs/reference/settings.md
• docs/troubleshooting.md
• test/documentation.test.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Greptile Review

🧰 Additional context used

📓 Path-based instructions (2)

docs/**

⚙️ CodeRabbit configuration file

keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.

Files:

• docs/index.md
• docs/reference/commands.md
• docs/reference/settings.md
• docs/troubleshooting.md
• docs/getting-started.md

test/**

⚙️ CodeRabbit configuration file

tests must stay deterministic and use vitest. demand regression cases that reproduce concurrency bugs, token refresh races, and windows filesystem behavior. reject changes that mock real secrets or skip assertions.

Files:

• test/documentation.test.ts

🔇 Additional comments (14)

docs/reference/settings.md (1)

73-87: section heading and conditional backup wording look good.

the rename from "Advanced and Operator Controls" to "## Advanced & Operator" matches the navigation breadcrumbs across docs/index.md:47, docs/reference/commands.md:108, and docs/troubleshooting.md:85,120-121. the backup rollback context wording at line 87 now correctly notes it appears only "when storage backups are enabled", which aligns with the storageBackupEnabled setting documented at line 154.

docs/index.md (1)

47-48: navigation path update is consistent.

sync preview path at line 47 now matches the shipped menu structure and aligns with assertions in test/documentation.test.ts:377. the adjacent settings split reference at line 48 correctly distinguishes Everyday Settings from Advanced & Operator.

docs/reference/commands.md (2)

23-23: login command description enhancement is accurate.

adding "dashboard paths and links to diagnostics commands" clarifies the full scope of the interactive dashboard. matches the actual shipped behavior.

---

108-110: workflow packs navigation paths are consistent.

the sync preview path at line 108 now matches docs/index.md:47 and docs/troubleshooting.md:85. stable/advanced paths at lines 109-110 correctly reference the split structure.

docs/getting-started.md (1)

81-81: windows backup path guidance is correct and tested.

the path C:\Users\<User>\.codex\multi-auth\backups\<name>.json matches the backup root derivation in lib/runtime-paths.ts:183-200 combined with lib/named-backup-export.ts:12-14. the CODEX_MULTI_AUTH_DIR override is accurate per the env var handling in the runtime paths module. this string is also asserted in test/documentation.test.ts:372.

test/documentation.test.ts (2)

347-347: heading assertion updated correctly.

the change from "## Advanced and Operator Controls" to "## Advanced & Operator" matches the actual heading at docs/reference/settings.md:73.

---

364-382: good coverage for restore/sync flow documentation alignment.

this test locks down:

• section headings (## Restore Or Start Fresh, ## Sync And Settings, ## Backup Restore Problems, ## Codex CLI Sync Problems)
• windows backup path template at line 372
• navigation breadcrumbs with the new Advanced & Operator intermediate menu

the windows path assertion is valuable for catching regressions when path handling changes.

one consideration: docs/index.md:47 and docs/reference/commands.md:108 also contain the same navigation path string but aren't asserted here. if those drift, this test won't catch it. not blocking, but worth considering for future coverage expansion.

docs/troubleshooting.md (3)

66-67: backup root guidance is consistent with other docs.

the env var references $CODEX_MULTI_AUTH_DIR/backups (unix) and %CODEX_MULTI_AUTH_DIR%\backups (windows) match the wording in docs/getting-started.md:81 and README.md:247. the default path examples are accurate per lib/runtime-paths.ts:183-200 and lib/named-backup-export.ts:176-180.

---

85-92: sync diagnostics section updated correctly.

navigation path at line 85 matches docs/index.md:47 and is asserted in test/documentation.test.ts:377. the symptom rewording at line 90 from "would be lost" to "want to confirm preserved" is clearer - describes user intent rather than hypothetical outcome.

---

120-121: diagnostics pack paths are consistent.

both navigation strings are asserted in test/documentation.test.ts:377,380, ensuring they stay aligned with the shipped menu structure.

README.md (4)

20-20: settings flow description is consistent.

the Everyday Settings plus Advanced & Operator structure matches the shipped menu and aligns with docs/reference/settings.md:22-23,73.

---

118-119: sync preview navigation path is consistent.

matches docs/index.md:47, docs/reference/commands.md:108, and docs/troubleshooting.md:85.

---

182-192: config file path clarification is accurate.

the distinction between config file and root is correct per lib/config.ts:68-76 - CODEX_MULTI_AUTH_CONFIG_PATH is treated as a complete file path that's returned directly if non-empty, not a directory. line 185 and line 192 descriptions accurately reflect this behavior.

---

247-247: windows backup path examples match other docs.

the path format $CODEX_MULTI_AUTH_DIR/backups / %CODEX_MULTI_AUTH_DIR%\backups and default examples are consistent with docs/troubleshooting.md:66 and docs/getting-started.md:81.

---

📝 Walkthrough

Summary

This is a low-severity, documentation-only PR that aligns front-door workflows and settings reference documentation with the current shipped product UI. The changes introduce no architectural decisions or code modifications and include test updates to validate the documentation changes, with no regression risks.

Changes

Documentation Updates:

• Navigation paths: Updated references throughout docs to route sync users through Settings → Advanced & Operator → Codex CLI Sync instead of direct Settings → Codex CLI Sync links, reflecting the new dashboard structure that separates Everyday Settings from Advanced & Operator controls
• Backup/restore paths: Added explicit Windows backup path example (C:\Users\<User>\.codex\multi-auth\backups\<name>.json) to getting-started.md and expanded troubleshooting guidance to reference the active backup root derived from CODEX_MULTI_AUTH_DIR environment variable, with Windows/macOS examples
• Configuration descriptions: Clarified "primary config file" vs "root" terminology in README and documented CODEX_MULTI_AUTH_CONFIG_PATH as the override mechanism for config file path lookup
• Settings reference: Renamed "Advanced and Operator Controls" heading to "Advanced & Operator" and updated sync UI description to note backup/rollback context is only shown when storage backups are enabled
• Removed outdated content: Deleted validation instructions subsection from settings reference and removed stale sync workflow upgrade note links

Test Coverage:

• Updated existing documentation assertions in test/documentation.test.ts for the settings heading change
• Added comprehensive new test case validating restore/sync section headings and command-path breadcrumbs across getting-started and troubleshooting docs, including assertions for Windows backup path template and troubleshooting navigation paths

Files Modified: 6 documentation files + 1 test file
Total Lines Changed: +42/-28

Impact

• Aligns documentation with current shipped UI without code changes
• Removes stale/bloated content from prior PR #109 while retaining valid doc and test updates
• Test coverage validates key documentation assertions around navigation paths and backup restore procedures
• No security, data-loss, or architectural risks

Walkthrough

documentation updates reflect ui navigation restructuring, moving settings submenus under "advanced & operator" and clarifying backup restore paths with explicit windows examples and environment variable references. test assertions updated to validate new documentation structure.

Changes

Cohort / File(s)	Summary
Navigation & Settings Documentation README.md, docs/index.md, docs/reference/commands.md, docs/reference/settings.md, docs/troubleshooting.md	updated dashboard navigation path from Settings -> Codex CLI Sync to Settings -> Advanced & Operator -> Codex CLI Sync. renamed section heading from "Advanced and Operator Controls" to "Advanced & Operator". clarified configuration terminology ("primary config file" vs "primary config root") and removed obsolete troubleshooting links.
Backup Path Documentation docs/getting-started.md, docs/troubleshooting.md	added explicit windows backup path example C:\Users\<User>\.codex\multi-auth\backups\<name>.json alongside linux/macos paths. emphasized CODEX_MULTI_AUTH_DIR environment variable as override for active backup root location.
Documentation Test Assertions test/documentation.test.ts	updated assertion for settings section heading match. added new test case validating presence of windows backup path template and navigation breadcrumbs (Settings -> Advanced & Operator -> Codex CLI Sync and Advanced Backend Controls).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

---

notes for review:

• test/documentation.test.ts:1-22 — new assertions only validate that documentation text exists, not that ui actually routes correctly. if ui navigation was refactored elsewhere, you need integration tests validating the actual dashboard flow, not just string matching in markdown.

• windows paths now explicit which is good, but %CODEX_MULTI_AUTH_DIR%\backups syntax in docs/troubleshooting.md should verify it matches actual windows env var handling in code (if codex respects %VAR% syntax). check lib/config.ts or equivalent.

• no regression tests added for the actual settings reorganization. if the ui module has tests, ensure they cover the new Advanced & Operator submenu structure and that no other navigation paths broke.

• all changes are consistent across documentation; no conflicting paths detected.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	title follows conventional commits format with type docs, scope auth, and a clear, lowercase imperative summary under 72 characters.
Description check	✅ Passed	description covers summary, what changed, and validation checks; all critical sections are present with concrete details about docs and test updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch clean/pr109-docs-frontdoor

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch clean/pr109-docs-frontdoor

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}